fix(docs): pin command-reference metavar format as a stable contract (#513)#517
Draft
padak wants to merge 1 commit into
Draft
fix(docs): pin command-reference metavar format as a stable contract (#513)#517padak wants to merge 1 commit into
padak wants to merge 1 commit into
Conversation
…513) The release-asset reference (help.keboola.com, connection-docs freshness gate) is a published contract, but its option metavar column was rendered via Click's make_metavar(), whose default drifted between releases (bare `TEXT`/`INTEGER` at Click 8.x vs `<str>`/`<int>` later). The downstream connection-docs gate (keboola/connection-docs#1037) detects value-taking options by matching /^<.*>$/ on the metavar span, so a future dependency bump reverting to bare `TEXT` would silently break the docs build. Derive option metavars from Click's version-stable `ParamType.name` instead of `make_metavar()`: value-taking options always render as a `<...>` span (`<str>`, `<int>`, `<path>`, `<a|b|c>` for choices with literal case preserved), flags carry none. Document the column contract in the module header and add tests that fail CI on a Click/Typer bump that would change the shape, instead of letting the drift surface downstream.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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'smake_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:
ParamType.name(a version-stable token:text/integer/float/path/choice) instead ofmake_metavar(), via a new_stable_option_metavar().<...>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.ALIAS→<alias>).`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 bareTEXTwould 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
TestMetavarContractintests/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 uppercaseTEXT/INTEGER/PATH/FLOATleaks onto an option row, and the documented scalar/choice forms are present in the generated asset. A Click/Typer bump that changesmake_metavar()now fails CI here instead of downstream.make checkgreen (lint + format + changelog-check + typecheck + full suite: 4620 passed, 8 skipped).<...>-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