refactor(docs/output): unify options-rendering paths via shared (rows × columns) intermediate

[toiroakr]

Background

The option-rendering logic is currently spread across four+ similar functions that each iterate over ResolvedFieldMeta and emit a slightly different output format:

Location	Output	Input shape	Notes
src/docs/default-renderers.ts:renderOptionsTable	Markdown table	CommandInfo	env column conditional
src/docs/default-renderers.ts:renderOptionsTableFromArray	Markdown table	ResolvedFieldMeta[]	same body, different input wrapper
src/docs/default-renderers.ts:renderOptionsList	Markdown list	CommandInfo
src/docs/default-renderers.ts:renderOptionsListFromArray	Markdown list	ResolvedFieldMeta[]	same body, different input wrapper
src/docs/render-args.ts:renderFilteredTable	Markdown table	ResolvedFieldMeta[]	adds per-column filtering, branched separately because the table renderers above don't support it
src/output/help-generator.ts:formatFlags / renderOptions	Terminal (ANSI)	union/discriminated variants	shares the boolean inline-negation pattern

Adding a feature that touches the per-option visual representation today means editing roughly 4-5 places. The recent custom-negation work (#393) made this concrete: the same negation inline / separate-row / (↔ --positive) marker logic was duplicated across renderOptionsTable, renderOptionsList, renderOptionsTableFromArray, renderOptionsListFromArray, and renderFilteredTable, plus the analogous treatment in help-generator.

Proposal

Introduce a normalized intermediate representation that both the docs renderers and (optionally) the help generator consume:

```ts
type OptionRow = {
key: string; // "--cliName", "--cliName / --negation", etc.
cells: {
option: string;
alias: string;
description: string;
required: string;
default: string;
env: string;
};
extraRows?: OptionRow[]; // e.g. the separate negation row when negationDescription is set
};

function toOptionRows(options: ResolvedFieldMeta[], opts?: { columns?: ColumnId[] }): OptionRow[];
```

Then the actual emitters become trivial:

• `emitMarkdownTable(rows, columns)` — pure formatting
• `emitMarkdownList(rows)` — pure formatting
• `emitHelpLines(rows, ansiStyles)` — pure formatting

This way:

• The "decide what to display for this field" logic (negation handling, alias join order, placeholder resolution, boolean vs. value form, escape rules) lives once.
• Column filtering folds into the same path naturally — `renderFilteredTable` collapses into `emitMarkdownTable(toOptionRows(options, { columns }), columns)`.
• `From` / non-`From` variants reduce to thin adapters that just extract the array from `CommandInfo`.

Scope / non-goals

• Pure refactor — no change to rendered output. Golden tests in `playground/*/README.md` and snapshot tests in `src/docs/golden-test.test.ts` are the safety net.
• Help-generator integration is optional in a first pass; the docs renderers alone already remove most of the duplication.
• Out of scope: redesigning the field metadata itself.

Acceptance

• One canonical "render an option row" code path used by both Markdown table and list renderers.
• `render-args.ts:renderFilteredTable` removed / collapsed.
• All existing tests (including playground goldens) pass without regenerating output.

Context

Surfaced during review of #393 — the inline `/` negation join, the `(↔ --positive)` marker, and the separate-row `negationDescription` form each had to be added in 4-5 places. Future per-option features (e.g. value validators, deprecation markers) would hit the same fan-out.

[toiroakr]

Related: broaden the same idea to all sections (CLI help ↔ docs)

This issue scopes the unification to options rendering, but the same fan-out exists for the other sections too. Worth tracking as a follow-up (or expanding scope here) so we don't lock the abstraction prematurely.

Today's duplication, by section

Section	Docs path (src/docs/default-renderers.ts)	Help path (src/output/help-generator.ts)
Usage line	renderUsage(info)	buildUsageCommandName + inline usage assembly
Arguments	renderArgumentsTable / renderArgumentsList (+ *FromArray)	positional-args rendering in help-generator
Options	renderOptionsTable / renderOptionsList (+ *FromArray) and render-args.ts:renderFilteredTable	formatFlags / renderOptions
Subcommands	renderSubcommandsTable (+ *FromArray)	subcommands listing in help-generator
Examples	renderExamplesDefault (+ executed-output handling)	examples rendering in help-generator

Adding a new per-field concept (recent negation work in #393, or future ones like deprecated, experimental, since) means touching both columns. The CommandInfo shape from src/docs/types.ts is already the right intermediate for the docs side — extending it to drive help output too would close the loop.

Reference points

Two prior-art designs that handle this:

• kazupon/gunshi — there is no separate "doc generator." gunshi/generator.ts is 62 lines that just invoke the same cli([..., '-h'], …, { usageSilent: true }) and return the captured help string. The renderer plugin (@gunshi/plugin-renderer) is the single source of truth, and i18n / format variation lives in ctx.extensions[id].text(key) calls. CLI help and "doc generation" are literally the same code path.
• sapphi-red/ordana — keeps two emitters (terminal help via picocolors, Markdown via ordana-gen-docs) but both import the same stringifyArgument / stringifyArgumentType / stringifyPositionals from packages/ordana/src/utils.ts. The "decide what to show for this field" logic lives once; only the surrounding ANSI / Markdown wrapping differs.

The shape proposed in this issue (OptionRow { key, cells, extraRows } + thin emitters) generalizes cleanly to both approaches:

type SectionRow = { key: string; cells: Record<ColumnId, string>; extraRows?: SectionRow[] };

function toOptionRows(options: ResolvedFieldMeta[], opts?): SectionRow[];
function toArgumentRows(args: ResolvedFieldMeta[], opts?): SectionRow[];
function toSubcommandRows(subs: SubCommandInfo[], opts?): SectionRow[];

// emitters
emitMarkdownTable(rows, columns)
emitMarkdownList(rows)
emitHelpLines(rows, ansiStyles)   // consumed by src/output/help-generator.ts

Suggested split

1. Keep this issue's scope (options only) — ship the OptionRow intermediate + emitters first, with goldens as the safety net. Lowest risk.
2. Open a follow-up (or expand acceptance criteria here) to apply the same pattern to arguments, subcommands, and examples, and then route src/output/help-generator.ts through emitHelpLines(toOptionRows(...)) to retire the duplicated formatting.
3. Out of scope still: redesigning ResolvedFieldMeta itself, and i18n-style label substitution (separate concern, can layer on later).

Happy to take either route — keeping #399 narrow and opening a separate "unify CLI help + docs data model" issue is also fine. Flagging here so the abstraction chosen for options leaves room for the rest.