{"version":3,"file":"formatter.mjs","names":[],"sources":["../../src/output/formatter.ts"],"sourcesContent":["import { camelToKebab } from '../util/shell-utils.ts';\nimport type { ColorConfig, ColorTheme } from './colorizer.ts';\nimport {\n createAnsiStyler,\n createConsoleStyler,\n createHtmlLayout,\n createHtmlStyler,\n createMarkdownLayout,\n createMarkdownStyler,\n createTextLayout,\n createTextStyler,\n DEFAULT_TERMINAL_WIDTH,\n type LayoutConfig,\n type Styler,\n shouldUseAnsi,\n wrapText,\n} from './styling.ts';\n\nexport type HelpFormat = 'text' | 'ansi' | 'console' | 'markdown' | 'html' | 'json';\nexport type HelpDetail = 'minimal' | 'standard' | 'full';\n\n// ============================================================================\n// Help Info Types (shared with help.ts)\n// ============================================================================\n\n/**\n * Information about a single positional argument.\n */\nexport type HelpPositionalInfo = {\n name: string;\n description?: string;\n optional: boolean;\n default?: unknown;\n type?: string;\n enum?: string[];\n};\n\n/**\n * Information about a single argument/flag.\n */\nexport type HelpArgumentInfo = {\n name: string;\n description?: string;\n optional: boolean;\n default?: unknown;\n type?: string;\n enum?: string[];\n /** Single-character short flags (shown as `-v`) */\n flags?: string[];\n /** Multi-character alternative long names (shown as `--dry-run`) */\n aliases?: string[];\n deprecated?: boolean | string;\n hidden?: boolean;\n examples?: unknown[];\n /** Environment variable(s) this arg can be set from */\n env?: string | string[];\n /** Whether this arg is an array type (shown as ) */\n variadic?: boolean;\n /** Whether this arg is a boolean (shown as --[no-]arg) */\n negatable?: boolean;\n /** Custom negative keyword(s) that set this arg to false (e.g. `['remote']` for `--remote`) */\n negative?: string[];\n /** Config file key that maps to this arg */\n configKey?: string;\n /** Group name for organizing this option under a labeled section in help output */\n group?: string;\n};\n\n/**\n * Information about a subcommand (minimal info for listing).\n */\nexport type HelpSubcommandInfo = {\n name: string;\n title?: string;\n description?: string;\n aliases?: string[];\n deprecated?: boolean | string;\n hidden?: boolean;\n hasSubcommands?: boolean;\n /** Group name for organizing this command under a labeled section in help output */\n group?: string;\n};\n\n/**\n * Information about a built-in command/flag entry.\n */\nexport type HelpBuiltinInfo = {\n name: string;\n description?: string;\n sub?: { name: string; description?: string }[];\n};\n\n/**\n * Comprehensive JSON structure for help information.\n * This is the single source of truth that all formatters use.\n */\nexport type HelpInfo = {\n /** The full command name (e.g., \"cli serve\" or \"\") */\n name: string;\n /** Short title for the command */\n title?: string;\n /** Command description */\n description?: string;\n /** Alternative names/aliases for this command */\n aliases?: string[];\n /** Whether the command is deprecated */\n deprecated?: boolean | string;\n /** Whether the command is hidden */\n hidden?: boolean;\n /** Usage string parts for flexible formatting */\n usage: {\n command: string;\n hasSubcommands: boolean;\n hasPositionals: boolean;\n hasArguments: boolean;\n /** The name of the field that reads from stdin, if any. Shown as `[stdin > field]` in usage. */\n stdinField?: string;\n };\n /** List of subcommands */\n subcommands?: HelpSubcommandInfo[];\n /** Positional arguments */\n positionals?: HelpPositionalInfo[];\n /** Arguments/flags (only visible ones, hidden filtered out) */\n arguments?: HelpArgumentInfo[];\n /** Built-in commands and flags (shown only for root command) */\n builtins?: HelpBuiltinInfo[];\n /** Command-level usage examples (shown in help output) */\n examples?: string[];\n /** Full help info for nested commands (used in 'full' detail mode) */\n nestedCommands?: HelpInfo[];\n};\n\n// ============================================================================\n// Formatter Interface\n// ============================================================================\n\n/**\n * A formatter that takes the entire HelpInfo structure and produces formatted output.\n */\nexport type Formatter = {\n /** Format the entire help info structure into a string */\n format: (info: HelpInfo) => string;\n};\n\n// ============================================================================\n// Generic Formatter Implementation\n// ============================================================================\n\n/**\n * Creates a formatter that uses the given styler and layout configuration.\n */\nfunction createGenericFormatter(styler: Styler, layout: LayoutConfig, showAllBuiltins?: boolean, terminalWidth?: number): Formatter {\n const { newline, indent, join, wrapDocument } = layout;\n\n function formatUsageSection(info: HelpInfo): string[] {\n const usageParts: string[] = [styler.command(info.usage.command), info.usage.hasSubcommands ? styler.meta('[command]') : ''];\n // Show actual positional argument names in usage line\n if (info.positionals && info.positionals.length > 0) {\n for (const arg of info.positionals) {\n const name = arg.name.startsWith('...') ? `${arg.name}` : arg.name;\n usageParts.push(styler.meta(arg.optional ? `[${name}]` : `<${name}>`));\n }\n }\n if (info.usage.hasArguments) usageParts.push(styler.meta('[options]'));\n return [`${styler.label('Usage:')} ${join(usageParts)}`];\n }\n\n function formatSubcommandsSection(info: HelpInfo): string[] {\n const lines: string[] = [];\n const subcommands = info.subcommands!;\n\n const subcommandSuffix = (c: HelpSubcommandInfo) => (c.hasSubcommands ? ' ' : '');\n const formatAliasParts = (c: HelpSubcommandInfo) => {\n if (!c.aliases?.length) return { plain: '', styled: '' };\n const realAliases = c.aliases.filter((a) => a !== '[default]');\n const hasDefault = c.aliases.some((a) => a === '[default]');\n const parts: string[] = [];\n const styledParts: string[] = [];\n if (realAliases.length) {\n parts.push(`(${realAliases.join(', ')})`);\n styledParts.push(`(${realAliases.join(', ')})`);\n }\n if (hasDefault) {\n parts.push('[default]');\n styledParts.push(styler.meta('[default]'));\n }\n return { plain: parts.length ? ` ${parts.join(' ')}` : '', styled: styledParts.length ? ` ${styledParts.join(' ')}` : '' };\n };\n // Column width is computed across all subcommands for consistent alignment\n const maxNameLength = Math.max(\n ...subcommands.map((c) => {\n return (c.name + subcommandSuffix(c) + formatAliasParts(c).plain).length;\n }),\n );\n\n const grouped = Object.groupBy(subcommands, (c) => c.group ?? '');\n\n const renderSubcommands = (cmds: HelpSubcommandInfo[]) => {\n for (const subCmd of cmds) {\n const aliasParts = formatAliasParts(subCmd);\n const suffix = subcommandSuffix(subCmd);\n const commandDisplay = subCmd.name + suffix + aliasParts.plain;\n const padding = ' '.repeat(Math.max(0, maxNameLength - commandDisplay.length + 2));\n const isDeprecated = !!subCmd.deprecated;\n const isDefaultEntry = subCmd.name === '[default]';\n const commandName = isDeprecated\n ? styler.deprecated(commandDisplay)\n : (isDefaultEntry ? styler.meta(subCmd.name) : styler.command(subCmd.name)) +\n (suffix ? styler.meta(suffix) : '') +\n aliasParts.styled;\n const lineParts: string[] = [commandName, padding];\n\n // Use title if available, otherwise use description\n const displayText = subCmd.title ?? subCmd.description;\n if (displayText) {\n lineParts.push(isDeprecated ? styler.deprecated(displayText) : styler.description(displayText));\n }\n if (isDeprecated) {\n const deprecatedMeta =\n typeof subCmd.deprecated === 'string' ? styler.meta(` (deprecated: ${subCmd.deprecated})`) : styler.meta(' (deprecated)');\n lineParts.push(deprecatedMeta);\n }\n lines.push(indent(1) + lineParts.join(''));\n }\n };\n\n for (const [key, items] of Object.entries(grouped)) {\n if (lines.length > 0) lines.push('');\n lines.push(styler.section(key ? `${key}:` : 'Commands:'));\n renderSubcommands(items!);\n }\n\n // Skip hint when builtins are present — the builtins section shows a combined hint\n if (!info.builtins?.length) {\n lines.push('');\n lines.push(styler.meta(`Run \"${info.name} [command] --help\" for more information on a command.`));\n }\n\n return lines;\n }\n\n function formatPositionalsSection(info: HelpInfo): string[] {\n const lines: string[] = [];\n const args = info.positionals!;\n\n lines.push(styler.section('Arguments:'));\n\n const maxNameLength = Math.min(32, Math.max(...args.map((a) => a.name.length)));\n const descCol = 2 + maxNameLength + 2;\n const posAvailWidth = terminalWidth ? terminalWidth - descCol : undefined;\n const descColPad = ' '.repeat(descCol);\n\n for (const arg of args) {\n const padding = ' '.repeat(Math.max(2, maxNameLength - arg.name.length + 2));\n const prefix = indent(1) + styler.arg(arg.name) + padding;\n\n const descPlain = arg.description ?? '';\n const styledDesc = descPlain ? styler.description(descPlain) : '';\n\n const metaParts: string[] = [];\n const styledMetaParts: string[] = [];\n if (info.usage.stdinField === arg.name) {\n metaParts.push('(stdin)');\n styledMetaParts.push(styler.meta('(stdin)'));\n }\n if (arg.enum) {\n const text = `(choices: ${arg.enum.join(', ')})`;\n metaParts.push(text);\n styledMetaParts.push(styler.meta(text));\n }\n if (arg.default !== undefined) {\n const text = `(default: ${String(arg.default)})`;\n metaParts.push(text);\n styledMetaParts.push(styler.meta(text));\n }\n\n const metaStyled = join(styledMetaParts);\n\n if (posAvailWidth && posAvailWidth > 0) {\n const metaPlain = metaParts.join(' ');\n const fullPlain = [descPlain, metaPlain].filter(Boolean).join(' ');\n if (fullPlain.length <= posAvailWidth) {\n lines.push(prefix + [styledDesc, metaStyled].filter(Boolean).join(' '));\n } else if (!descPlain || descPlain.length <= posAvailWidth) {\n lines.push(prefix + styledDesc);\n if (metaStyled) lines.push(descColPad + metaStyled);\n } else {\n const wrapped = wrapText(descPlain, posAvailWidth);\n lines.push(prefix + styler.description(wrapped[0]!));\n for (const wline of wrapped.slice(1)) lines.push(descColPad + styler.description(wline));\n if (metaStyled) lines.push(descColPad + metaStyled);\n }\n } else {\n lines.push(prefix + join([styledDesc, metaStyled]));\n }\n }\n\n return lines;\n }\n\n function formatArgumentsSection(info: HelpInfo): string[] {\n const lines: string[] = [];\n const argList = info.arguments || [];\n\n // Helper to check if a default value is meaningful (not empty string/array)\n const hasDefault = (value: unknown): boolean => {\n if (value === undefined) return false;\n if (value === '') return false;\n if (Array.isArray(value) && value.length === 0) return false;\n return true;\n };\n\n // Build columns: flags | names | type | description\n const argColumns = argList.map((arg) => {\n // Promote kebab-case alias to primary display name if it exists\n const kebab = camelToKebab(arg.name);\n const primaryName = kebab && arg.aliases?.includes(kebab) ? kebab : arg.name;\n const remainingAliases = arg.aliases?.filter((a) => a !== primaryName);\n\n const flagsPlain = arg.flags?.length ? arg.flags.map((f) => `-${f}`).join(', ') : '';\n const negPlain = arg.negative?.length ? arg.negative.map((n) => `--${n}`).join(', ') : '';\n const namesPlain = [`--${primaryName}`, ...(remainingAliases?.map((a) => `--${a}`) || []), ...(negPlain ? [negPlain] : [])].join(\n ', ',\n );\n const typePlain = arg.type && arg.type !== 'boolean' ? (arg.optional ? `[${arg.type}]` : `<${arg.type}>`) : '';\n\n const isDeprecated = !!arg.deprecated;\n\n return { flagsPlain, namesPlain, typePlain, isDeprecated, arg };\n });\n\n // Column widths are computed across all args (regardless of group) for consistent alignment\n const maxFlagsWidth = Math.min(12, Math.max(0, ...argColumns.map((c) => c.flagsPlain.length)));\n const maxNamesWidth = Math.min(32, Math.max(0, ...argColumns.map((c) => c.namesPlain.length)));\n const maxTypeWidth = Math.min(16, Math.max(0, ...argColumns.map((c) => c.typePlain.length)));\n const hasAnyFlags = maxFlagsWidth > 0;\n const descCol = 2 + (hasAnyFlags ? maxFlagsWidth + 2 : 0) + maxNamesWidth + 2 + (maxTypeWidth > 0 ? maxTypeWidth + 2 : 0);\n const argAvailWidth = terminalWidth ? terminalWidth - descCol : undefined;\n const descColPad = ' '.repeat(descCol);\n\n // Split into ordered groups: ungrouped first as \"Options:\", then each group in first-seen order\n const grouped = Object.groupBy(argColumns, (c) => c.arg.group ?? '');\n\n const renderArgColumns = (columns: typeof argColumns) => {\n for (const { flagsPlain, namesPlain, typePlain, isDeprecated, arg } of columns) {\n const parts: string[] = [];\n\n // Flags column\n if (hasAnyFlags) {\n const styledFlags = isDeprecated ? (flagsPlain ? styler.deprecated(flagsPlain) : '') : flagsPlain ? styler.arg(flagsPlain) : '';\n const flagsPadding = ' '.repeat(Math.max(0, maxFlagsWidth - flagsPlain.length));\n const separator = flagsPlain ? ', ' : ' ';\n parts.push(styledFlags + flagsPadding + separator);\n }\n\n // Names column\n const styledNames = isDeprecated ? styler.deprecated(namesPlain) : styler.arg(namesPlain);\n const namesPadding = ' '.repeat(Math.max(2, maxNamesWidth - namesPlain.length + 2));\n parts.push(styledNames + namesPadding);\n\n // Type column\n if (maxTypeWidth > 0) {\n const styledType = typePlain ? styler.type(typePlain) : '';\n const typePadding = ' '.repeat(Math.max(2, maxTypeWidth - typePlain.length + 2));\n parts.push(styledType + typePadding);\n }\n\n const prefix = indent(1) + parts.join('');\n const contPad = argAvailWidth ? descColPad : indent(3);\n\n // Build inline meta (deprecated no-reason, default, choices)\n const inlineMeta: string[] = [];\n const styledInlineMeta: string[] = [];\n if (isDeprecated && typeof arg.deprecated !== 'string') {\n inlineMeta.push('(deprecated)');\n styledInlineMeta.push(styler.meta('(deprecated)'));\n }\n if (hasDefault(arg.default)) {\n const text = `(default: ${String(arg.default)})`;\n inlineMeta.push(text);\n styledInlineMeta.push(styler.meta(text));\n }\n if (arg.enum) {\n const text = `(choices: ${arg.enum.join(', ')})`;\n inlineMeta.push(text);\n styledInlineMeta.push(styler.meta(text));\n }\n\n const descPlain = arg.description ?? '';\n const styledDesc = descPlain ? (isDeprecated ? styler.deprecated(descPlain) : styler.description(descPlain)) : '';\n const metaStyled = join(styledInlineMeta);\n\n if (argAvailWidth && argAvailWidth > 0) {\n // Terminal-width-aware: try to fit description + meta on one line\n const metaPlain = inlineMeta.join(' ');\n const fullPlain = [descPlain, metaPlain].filter(Boolean).join(' ');\n if (fullPlain.length <= argAvailWidth) {\n lines.push(prefix + [styledDesc, metaStyled].filter(Boolean).join(' '));\n } else if (!descPlain || descPlain.length <= argAvailWidth) {\n lines.push(prefix + styledDesc);\n if (metaStyled) lines.push(descColPad + metaStyled);\n } else {\n const wrapped = wrapText(descPlain, argAvailWidth);\n const styleFn = isDeprecated ? styler.deprecated : styler.description;\n lines.push(prefix + styleFn(wrapped[0]!));\n for (const wline of wrapped.slice(1)) lines.push(descColPad + styleFn(wline));\n if (metaStyled) lines.push(descColPad + metaStyled);\n }\n } else {\n // No terminal width (markdown/html): description on line 1, meta on line 2\n const descParts: string[] = [];\n if (styledDesc) descParts.push(styledDesc);\n lines.push(prefix + join(descParts));\n if (styledInlineMeta.length > 0) lines.push(indent(3) + metaStyled);\n }\n\n // Deprecated (with reason), examples — always on separate line\n const line3Parts: string[] = [];\n if (isDeprecated && typeof arg.deprecated === 'string') line3Parts.push(styler.meta(`(deprecated: ${arg.deprecated})`));\n if (arg.examples && arg.examples.length > 0) {\n const exampleValues = arg.examples.map((example) => (typeof example === 'string' ? example : JSON.stringify(example))).join(', ');\n line3Parts.push(styler.example('Example:'), styler.exampleValue(exampleValues));\n }\n if (line3Parts.length > 0) lines.push(contPad + join(line3Parts));\n\n // stdin, env, config — always on separate line\n const line4Parts: string[] = [];\n if (info.usage.stdinField === arg.name) line4Parts.push(styler.meta('(stdin)'));\n if (arg.env) {\n const envVars = typeof arg.env === 'string' ? [arg.env] : arg.env;\n line4Parts.push(styler.example('Env:'), styler.exampleValue(envVars.join(', ')));\n }\n if (arg.configKey) {\n line4Parts.push(styler.example('Config:'), styler.exampleValue(arg.configKey));\n }\n if (line4Parts.length > 0) lines.push(contPad + join(line4Parts));\n }\n };\n\n for (const [key, items] of Object.entries(grouped)) {\n if (lines.length > 0) lines.push('');\n lines.push(styler.section(key ? `${key}:` : 'Options:'));\n renderArgColumns(items!);\n }\n\n return lines;\n }\n\n function formatBuiltinsSection(info: HelpInfo): string[] {\n const lines: string[] = [];\n const builtins = info.builtins!;\n\n if (!showAllBuiltins) {\n // Collapsed summary: show selected builtins on a single line with a combined hint\n const highlights = ['help [command]', 'version', '[command] --repl'];\n lines.push(`${styler.label('Global:')} ${styler.meta(highlights.join(', '))}`);\n const hint = info.usage.hasSubcommands\n ? `Run \"${info.name} [command] --help\" for more information. Use \"--all\" for all global commands.`\n : `Use \"${info.name} help --all\" for more information on global commands.`;\n lines.push(styler.meta(hint));\n return lines;\n }\n\n lines.push(styler.section('Global:'));\n\n // Compute max effective name length for alignment across main and sub entries\n const allLengths: number[] = [];\n for (const entry of builtins) {\n allLengths.push(entry.name.length);\n if (entry.sub) {\n for (const sub of entry.sub) {\n // Sub entries get extra indent(2) - indent(1) = 2 chars\n allLengths.push(sub.name.length + 2);\n }\n }\n }\n const maxLen = Math.max(...allLengths);\n\n for (const entry of builtins) {\n const padding = ' '.repeat(Math.max(2, maxLen - entry.name.length + 2));\n const parts: string[] = [styler.command(entry.name)];\n if (entry.description) parts.push(padding + styler.description(entry.description));\n lines.push(indent(1) + parts.join(''));\n\n if (entry.sub) {\n for (const sub of entry.sub) {\n const subPadding = ' '.repeat(Math.max(2, maxLen - sub.name.length));\n const subParts: string[] = [styler.arg(sub.name)];\n if (sub.description) subParts.push(subPadding + styler.description(sub.description));\n lines.push(indent(2) + subParts.join(''));\n }\n }\n }\n\n return lines;\n }\n\n return {\n format(info: HelpInfo): string {\n const lines: string[] = [];\n\n // Show deprecation warning at the top if command is deprecated\n if (info.deprecated) {\n const deprecationMessage =\n typeof info.deprecated === 'string' ? `⚠️ This command is deprecated: ${info.deprecated}` : '⚠️ This command is deprecated';\n lines.push(styler.deprecated(deprecationMessage));\n lines.push('');\n }\n\n // Usage section\n lines.push(...formatUsageSection(info));\n lines.push('');\n\n // Title section (if present, shows a short summary line)\n if (info.title) {\n lines.push(styler.label(info.title));\n lines.push('');\n }\n\n // Aliases section (if present)\n if (info.aliases && info.aliases.length > 0) {\n lines.push(styler.meta(`Aliases: ${info.aliases.join(', ')}`));\n lines.push('');\n }\n\n // Description section (if present)\n if (info.description) {\n lines.push(styler.description(info.description));\n lines.push('');\n }\n\n // Examples section (if present)\n if (info.examples && info.examples.length > 0) {\n lines.push(styler.section('Examples:'));\n for (const ex of info.examples) {\n lines.push(indent(1) + styler.meta('$ ') + styler.exampleValue(ex));\n }\n lines.push('');\n }\n\n // Subcommands section\n if (info.subcommands && info.subcommands.length > 0) {\n lines.push(...formatSubcommandsSection(info));\n lines.push('');\n }\n\n if (info.positionals && info.positionals.length > 0) {\n lines.push(...formatPositionalsSection(info));\n lines.push('');\n }\n\n if (info.arguments && info.arguments.length > 0) {\n lines.push(...formatArgumentsSection(info));\n lines.push('');\n }\n\n if (info.builtins && info.builtins.length > 0) {\n lines.push(...formatBuiltinsSection(info));\n lines.push('');\n }\n\n // Show --no- hint when there are negatable boolean options defaulting to true\n if (info.arguments?.some((arg) => arg.negatable && arg.default === true)) {\n lines.push(styler.meta('Boolean options can be negated with --no-