fix(docs): pin command-reference metavar format as a stable contract (#513)

[padak]

What

The release-asset command reference (scripts/gen_command_reference.py, consumed by help.keboola.com and the connection-docs freshness gate) rendered its option metavar column via Click's make_metavar(). That default is not stable across Click versions — it already drifted once: bare `TEXT` / `INTEGER` at v0.70.1 (Click 8.x), `<str>` / `<int>` at v0.72.0.

This PR pins the option metavar shape to a documented convention independent of the installed Click:

• Derive from ParamType.name (a version-stable token: text/integer/float/path/choice) instead of make_metavar(), via a new _stable_option_metavar().
• Value-taking options always render as a <...> span — <str>, <int>, <float>, <path>, and <a|b|c> for choices (literal case preserved, e.g. <admin|guest|readOnly|share>, since choice values are real CLI tokens). Flags carry no metavar span.
• Author-set metavars are wrapped and lowercased (ALIAS → <alias>).
• The column contract is documented in the module header.
• Positional arguments are unchanged — they render as `NAME` (positional) and are not part of the | `--flag` `<type>` | shape the downstream gate parses.

Why

The connection-docs freshness gate (keboola/connection-docs#1037, PRDCT-556) detects whether an option takes a value by matching /^<.*>$/ on the metavar span. That works today only because 0.72.0 happens to emit the <…> form. A future Typer/Click bump reverting to bare TEXT would silently make the checker misparse value-taking options, turning valid commands into false-positive "unknown command" errors and reddening the docs build on correct content. Pinning the format at the source makes the published asset a contract by intent, not by accident of the dependency version.

How it was tested

• New TestMetavarContract in tests/test_gen_command_reference.py: asserts scalar types map to the documented <...> forms, choices preserve literal case, explicit metavars are wrapped/lowercased, every value option satisfies the <...> span contract, flags carry no span, no bare uppercase TEXT/INTEGER/PATH/FLOAT leaks onto an option row, and the documented scalar/choice forms are present in the generated asset. A Click/Typer bump that changes make_metavar() now fails CI here instead of downstream.
• make check green (lint + format + changelog-check + typecheck + full suite: 4620 passed, 8 skipped).
• Verified the generated reference: all option metavars are <...>-wrapped; no bare uppercase metavars remain.

Note: no version bump / changelog entry — this only stabilizes the generated asset's shape (already <str> in the last release), it does not change the CLI surface. The immediate mitigation on the consumer side (accept <str> | TEXT | [a|b]) is still recommended in the linked issue; this is the durable source-side fix.

Fixes #513

[padak]

Second-opinion review (OpenAI Codex, gpt-5.6-sol, high reasoning) — verdict: NEEDS CHANGES.

Context check first: the reviewer inspected 922 value options and 226 flags in the current CLI — all existing types produce the intended spans, and no current command uses count or tuple options. So nothing breaks today; the findings are about valid Click parameter shapes the stable contract should survive, which is the whole point of this PR.

1. High — scripts/gen_command_reference.py:114 — count flags render as value-taking options. In Click, click.Option(..., count=True) has count=True but is_flag=False; the code would emit --verbose <int>, making the downstream gate think the option consumes a value. Suppress the metavar when is_flag or count is true, and add a _format_param() test with a count option.
2. Medium — scripts/gen_command_reference.py:102-104 — tuple/composite and unknown-type fallback can produce malformed spans. click.Tuple([STRING, INT]) has name "<text integer>" → rendered as <<text-integer>>. A nameless custom type silently becomes <str>. Add explicit composite handling via ptype.types (e.g. <str,int>) and a neutral <value> fallback for unknown types.
3. Medium — scripts/gen_command_reference.py:99-101 — str(choice) is not always the CLI token. With click.Choice(SomeEnum), Click accepts member names (RED|BLUE) while this emits Color.RED|Color.BLUE. Handle Enum members via .name (or Click's normalize_choice path) and add an Enum-backed choice test.
4. Low — tests/test_gen_command_reference.py:113-133 — tests overstate coverage. They exercise five synthetic external-Click options while the app uses Typer's vendored Click objects, and integration assertions check token presence, not every row. Add focused tests for count, tuple/nargs, multiple, Enum choice, custom/nameless types, plus a walk of the live Typer command tree validating every emitted option row.

Int ranges, float ranges, paths/files, scalar choices, regular boolean flags, and value-taking boolean options are handled consistently. The main remaining drift risk is composite/custom types and choices, not make_metavar() itself.

[padak]

All four findings addressed in 0de2827. Confirming the reviewer's context check first: none of these shapes exists in the CLI today, so the generated reference is byte-identical before and after (diffed scripts/gen_command_reference.py --output across the change — no diff). The point is that it stays that way when one of these shapes does appear.

1. High — count flags rendered as value-taking. Fixed. Metavar suppression moved out of the inline is_flag check into _takes_a_value(param) = not (is_flag or count). New _format_param()-level tests cover a count option (asserting is_flag is False and count is True explicitly, so the trap is documented in the test), a plain boolean flag, and — guarding the opposite mistake — a value option that must still get its span.

2. Medium — composite/unknown-type fallback. Fixed. _composite_types() detects is_composite and expands ptype.types, so click.Tuple([STRING, INT]) renders <str,int> instead of the nested <<text-integer>>. A scalar type with nargs > 1 repeats the same way (<int,int>); composites are excluded from that path since Click already sets nargs == len(types). A nameless custom ParamType now falls back to a neutral <value> rather than asserting <str>, and every token is folded through _sanitize_token() into the documented alphabet, so an unmapped named type degrades to e.g. <my-weird-type> and no span can be malformed.

3. Medium — Enum-backed click.Choice. Fixed. _choice_token() renders Enum members via .name, so click.Choice(Color) gives <RED|BLUE>. Click's own normalize_choice() is deliberately not used: it casefolds a case_sensitive=False choice, which would silently rewrite real CLI tokens like readOnly in the published asset. A test pins that too.

4. Low — tests overstate coverage. Added TestLiveCommandTreeGrammar, which walks the real Typer tree (Typer's vendored Click, not plain click) and validates every emitted option row — 1072 of them — against the option-cell grammar: names are backticked option tokens, the optional metavar matches ^<[A-Za-z0-9][A-Za-z0-9|,_-]*>$. It also cross-checks metavar presence against _takes_a_value() per live param, asserts no row nests angle brackets, and refuses to pass on a scan of fewer than 500 rows so a broken walker can't produce a silent green. Plus the requested focused cases: count, tuple, multi-value nargs, multiple=True, Enum choice, nameless and unmapped custom types.

Docstring contract in the module header updated to state the new rules (no span for is_flag or count, comma-joined composites, <value> fallback).

Verification: tests/test_gen_command_reference.py 27 passed; full suite 4633 passed / 140 skipped; ruff check, ruff format --check and ty check clean on both touched files; check_command_sync.py OK. Still no version bump / changelog entry — the published asset's bytes are unchanged.

[devin-ai-integration]

Devin Review found 1 potential issue.

[devin-ai-integration]

🔍 File-typed option renders as

_METAVAR_BY_TYPE_NAME maps "filename": "path", and Click's File type has name == "filename", so a click.File() option renders <path>, not <file>. The "file": "file" entry is unreachable for stock Click. Cosmetic, but worth confirming intent.

---

Was this helpful? React with 👍 or 👎 to provide feedback.