feat(cli): generate command reference from Clap - #712
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2898b9e8a4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| CLI_REFERENCE_INPUTS = ( | ||
| ("crates/registry-cli-docs/src/**", "crates/registry-cli-docs/src/lib.rs"), | ||
| ("crates/registry-evidence/src/cli.rs", "crates/registry-evidence/src/cli.rs"), |
There was a problem hiding this comment.
Include the root Cargo.toml and Cargo.lock in the CLI-reference inputs. When a change only upgrades Clap or alters its workspace features, the collector's implicit help options and render_usage() output can change, but this classifier leaves docs false, so CI never runs generate-cli-reference.mjs --check and stale generated pages can be merged.
AGENTS.md reference: AGENTS.md:L289-L291
Useful? React with 👍 / 👎.
| .map(ToString::to_string) | ||
| .map(|value| normalized(&value)) | ||
| .unwrap_or_default(), | ||
| required: argument.is_required_set(), |
There was a problem hiding this comment.
Deriving required only from Arg::is_required_set() discards requirements imposed by groups and relationships. For example, evidencectl audit show requires the singleton view group, so bare show is rejected, while its generated table labels --last-operation as not required; similarly, the requires relationships among relayctl inspect options are absent. This makes the published Required column inaccurate for valid command scenarios, so the catalog should represent effective group and conditional constraints rather than only the per-argument flag.
Useful? React with 👍 / 👎.
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
2898b9e to
6a4ad08
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6a4ad0810a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| | Option | Always required | Default | Values | Environment | Description | | ||
| | --- | --- | --- | --- | --- | --- | | ||
| | `--config <CONFIG>` | Yes | n/a | n/a | `MINT_CONFIG` | n/a | |
There was a problem hiding this comment.
When MINT_CONFIG is set, Clap accepts mint check without --config—an invocation with the variable set reaches configuration loading rather than producing a missing-argument error—yet this row says the option is always required. The same incorrect classification is generated for EVIDENCE_OID4VCI_CONFIG and RELAY_RUNTIME; derive requiredness from the effective CLI/environment alternatives rather than only Arg::is_required_set().
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
| | `--openapi <OPENAPI>` | No | n/a | n/a | n/a | OpenAPI 3.0 or 3.1 document: a local path or an HTTPS URL | | ||
| | `--transport <TRANSPORT>` | No | n/a | `sqlite-extract` | n/a | Source transport to author without an API description | | ||
| | `--profile <PROFILE>` | No | n/a | `local` | n/a | Explicit development profile for local authoring | |
There was a problem hiding this comment.
Every evidencectl new invocation is rejected by scaffold::run unless --profile local is present and exactly one of --openapi or --transport is supplied, but this new reference marks all three options as optional and emits no Constraints section. These checks remain outside the Clap metadata even after the new group/relationship extraction, so encode them in the command tree or otherwise include the runtime validation in the generated catalog.
AGENTS.md reference: docs/site/AGENTS.md:L25-L28
Useful? React with 👍 / 👎.
| "check:tutorial:evidence:dry-run": "bash scripts/check-evidence-tutorials.sh --dry-run", | ||
| "check:links": "npm run build && npm run check:links:built", | ||
| "check": "npm run generate && npm run check:evidence-links && npm run check:research-banners && npm run check:docset && npm run check:release-manifests && npm run check:archive-lock && npm run check:content && npm run check:cutover && npm run check:notary-surface && npm run check:markdown && npm run check:style && npm run check:style:fixtures && npm run check:openapi && npm run check:config-vocabulary && npm run check:tutorial:dry-run && npm run check:tutorial:evidence:dry-run && npm run check:svg && npm run build && npm run check:accessibility:built && npm run check:llms:built && npm run check:seo:current && npm run check:links:current", | ||
| "check": "npm run generate && npm run check:cli-reference && npm run check:evidence-links && npm run check:research-banners && npm run check:docset && npm run check:release-manifests && npm run check:archive-lock && npm run check:content && npm run check:cutover && npm run check:notary-surface && npm run check:markdown && npm run check:style && npm run check:style:fixtures && npm run check:openapi && npm run check:config-vocabulary && npm run check:tutorial:dry-run && npm run check:tutorial:evidence:dry-run && npm run check:svg && npm run build && npm run check:accessibility:built && npm run check:llms:built && npm run check:seo:current && npm run check:links:current", |
There was a problem hiding this comment.
In the inspected .github/workflows/ci.yml docs job, the only build check is npm run check, but this script runs npm run generate before check:cli-reference; generation overwrites the committed CLI pages and JSON, so the later comparison always sees freshly generated files. A PR containing stale or hand-edited CLI output can therefore pass the docs job; run the drift check before generation or assert that generation leaves the checkout clean.
AGENTS.md reference: AGENTS.md:L289-L291
Useful? React with 👍 / 👎.
1 participant
Pull Request
Summary
Add reusable Clap command-tree introspection for every released Evidence and Relay CLI:
relay,relayctl,evidence,evidencectl,mint, andevidence-oid4vci.A new docs-only
registry-cli-docscollector serializes those command trees to a deterministic, validated JSON contract. The docs generator uses that contract to produce the command-line reference overview and 66 command pages, with exact usage, arguments, options, defaults, values, environment variables, and nested-command links.The docs drift gate and CI change routing now keep the generated reference aligned with CLI changes. Hidden implementation seams and Clap's built-in help subcommands are excluded.
Checks
cargo fmt --all -- --checkcargo check --locked --workspace --all-targets-D warningsregistry-cli-docs, Relay V2, Relayctl, Evidence, Evidencectl, Mint, and Evidence OID4VCIcargo deny checkpython3 .github/scripts/test_ci_changes.pyproducts/identifiers/scripts/check.shproducts/relay-v2/scripts/check-contracts.shproducts/evidence/scripts/check-contracts.shproducts/evidence/scripts/check-source-neutrality.shnpm testandnpm run checkindocs/sitenode docs/site/scripts/generate-cli-reference.mjs --checkgit diff --checkFocused coverage verifies the exact released-binary set, complete usage/about metadata, hidden-command exclusion, deterministic regeneration, generated-file drift, MDX-safe provenance, and CLI/CI routing contracts.
Notes
This changes adopter tooling and generated documentation only. It does not change Relay or Evidence HTTP contracts, authorization, evaluation, signing, or release artifacts.
Existing non-blocking warnings remain in Redocly, Astro, Rhai syntax highlighting, Vale, and cargo-deny. No new warning or functional risk was found.
DCO
Signed-off-bytrailer.