Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -957,6 +957,11 @@ looking at the clap surface, not only at the spec.
`--usage-spec` solely to expose the new canonical metadata; that new entry
point has no clap-era behavior to preserve and is excluded from tak's
compatibility baseline.
The six completed typed adopters now supply current `usage-rs` fixtures and
regenerated shadows for hk, fnox, pitchfork, aube, tak, and communique. Their
delimiter, optional-value, relationship, and command-policy metadata is therefore
visible to the gate. mise remains on its clap-era fixture until its router port can
emit the replacement metadata.
- [x] **Docs and manpages on a fleet spec.** communique's checked-in spec and
the KDL its shadow emits render the same markdown (index and every
command) and the same manpage. usage-cli's own
Expand Down Expand Up @@ -1042,9 +1047,10 @@ a prerequisite for trying a CLI.
parsers. Adoption is measured by what it lets mise delete, listed below.
Do not start this until the clap-only rows in **Trying the fleet** that
mise actually uses are either implemented or accepted as lost.
- [ ] **pitchfork** — not part of the five typed experiments, but already
generates its spec from clap. It is the next small adopter after those
experiment branches become mergeable.
- [x] **pitchfork** — jdx/Pitchfork#754 removes clap, parses its typed command tree
with `usage-rs`, uses the built-in completion protocol, and passes its Rust and
bats suites against the stacked usage revision. Its refreshed spec is part of the
fleet gate alongside the five original typed experiments.
- [~] **Other languages** — Go now parses, validates, renders help and answers
completions from generated static tables, verified against the shared corpus.
JavaScript and Python implementations remain open.
Expand Down
6 changes: 6 additions & 0 deletions argv/src/spec.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1182,6 +1182,12 @@ impl Spec<'_> {
if self.root.cmd.allow_missing_positional {
writeln!(out, "allow_missing_positional #true")?;
}
// Root metadata is written separately from `write_command`, so keep the required
// subcommand bit here as well. Without it a required typed enum still parsed correctly,
// but its emitted portable spec rendered `[COMMAND]` and accepted an empty invocation.
if self.root.subcommand_required && !self.root.cmd.subcommands.is_empty() {
writeln!(out, "subcommand_required #true")?;
}
if let Some(heading) = self.root.subcommand_help_heading {
prop(out, "subcommand_help_heading", heading)?;
}
Expand Down
13 changes: 7 additions & 6 deletions benches/fleet/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@

One spec per jdx CLI, checked in as a fixture.

Each is the output of that CLI's own `usage` subcommand — `clap_usage` over its clap
definition — copied verbatim. They are here for the same reason `benches/mise.usage.kdl` is:
the comparison needs a fixed input, and a reviewer needs to be able to read the diff when one
of them changes.
Each is the output of that CLI's own `usage` subcommand, copied verbatim. The fixtures now come
from the typed `usage-rs` fleet rewrites; they therefore exercise the metadata the replacement
actually emits instead of the subset an older `clap_usage` bridge could recover. They are here
for the same reason `benches/mise.usage.kdl` is: the comparison needs a fixed input, and a
reviewer needs to be able to read the diff when one of them changes.

## Why more than mise

Expand All @@ -26,5 +27,5 @@ None of the three is exotic. Each was simply outside one CLI's vocabulary.

These are snapshots, not links. A CLI that changes its own flags will not update the copy here,
and that is fine — the fixture's job is to hold a shape the renderers must agree on, not to
track a moving target. Refresh one by re-running its `usage` subcommand and committing the
diff, the same way `benches/mise.usage.kdl` is refreshed.
track a moving target. Refresh one from its usage-migration branch by re-running its `usage`
subcommand and committing the diff, the same way `benches/mise.usage.kdl` is refreshed.
4,966 changes: 1,480 additions & 3,486 deletions benches/fleet/aube.usage.kdl

Large diffs are not rendered by default.

51 changes: 27 additions & 24 deletions benches/fleet/communique.usage.kdl
Original file line number Diff line number Diff line change
@@ -1,45 +1,48 @@
// @generated by `communique usage`
min_usage_version "4.0"
name "communique"
bin "communique"
name communique
bin communique
version "1.3.1"
about "Editorialized release notes powered by AI"
usage "Usage: communique [OPTIONS] <COMMAND>"
unknown_flags error
subcommand_required #true
flag "-v --verbose" help="Enable verbose logging output" global=#true
flag "-q --quiet" help="Suppress progress output" global=#true
flag "-c --config" help="Path to config file (default: communique.toml in repo root)" global=#true {
arg "<CONFIG>"
arg <CONFIG>
}
cmd "generate" help="Generate release notes for a git tag" effect="read" {
flag "--github-release" help="Push editorialized notes to the GitHub release" effect="write"
flag "--changelog" help="Update CHANGELOG.md with the generated changelog entry" effect="write"
flag "--concise" help="Output concise changelog entry instead of detailed notes"
cmd generate help="Generate release notes for a git tag" effect=read {
flag --github-release help="Push editorialized notes to the GitHub release" effect=write
flag --changelog help="Update CHANGELOG.md with the generated changelog entry" effect=write
flag --concise help="Output concise changelog entry instead of detailed notes"
flag "-n --dry-run" help="Generate notes without updating GitHub or verifying links"
flag "--repo" help="GitHub repo in owner/repo format (auto-detected from git remote)" {
arg "<REPO>"
flag --repo help="GitHub repo in owner/repo format (auto-detected from git remote)" {
arg <REPO>
}
flag "--model" help="LLM model to use" {
arg "<MODEL>"
flag --model help="LLM model to use" {
arg <MODEL>
}
flag "--max-tokens" help="Max response tokens" {
arg "<MAX_TOKENS>"
flag --max-tokens help="Max response tokens" {
arg <MAX_TOKENS>
}
flag "--provider" help="LLM provider (anthropic or openai, auto-detected from model if omitted)" {
arg "<PROVIDER>"
flag --provider help="LLM provider (anthropic or openai, auto-detected from model if omitted)" {
arg <PROVIDER>
}
flag "--base-url" help="Base URL for the LLM API" {
arg "<BASE_URL>"
flag --base-url help="Base URL for the LLM API" {
arg <BASE_URL>
}
flag "-o --output" help="Write output to a file instead of stdout" effect="write" {
arg "<OUTPUT>"
flag "-o --output" help="Write output to a file instead of stdout" effect=write {
arg <OUTPUT>
}
arg "<TAG>" help="Git tag to generate release notes for"
arg <TAG> help="Git tag to generate release notes for"
arg "[PREV_TAG]" help="Previous tag (auto-detected if omitted)"
}
cmd "init" help="Generate a communique.toml config file in the repo root" effect="write" {
flag "--force" help="Overwrite existing config file" effect="destructive"
cmd init help="Generate a communique.toml config file in the repo root" effect=write {
flag --force help="Overwrite existing config file" effect=destructive
}
cmd "sponsors" help="Show the companies sponsoring communique and the jdx.dev open source tools" {
cmd sponsors help="Show the companies sponsoring communique and the jdx.dev open source tools" effect=read {
}
cmd "usage" help="Generates a usage spec for the CLI" hide=#true effect="read" {
cmd usage help="Generates a usage spec for the CLI" hide=#true effect=read {
long_help "Generates a usage spec for the CLI\n\nhttps://usage.jdx.dev"
}
Loading