fix(docs): link multi-word commands to their real source files

[jdx]

What

Every hyphenated command in the generated CLI reference linked at a source file that does not exist, and 404'd on GitHub:

• docs/cli/reference/complete-word.md → cli/src/cli/complete-word.rs, but the file is complete_word.rs
• docs/cli/reference/generate/completion-init.md → generate/completion-init.rs, but the file is completion_init.rs

The command path was interpolated into source_code_link_template verbatim, so complete-word never became complete_word.

Why here

The link is not derived in lib/src/docs/. The source_code_link tera function in lib/src/docs/markdown/tera.rs only exposes path — the full command path joined by / — and the blob/main URL itself lives in the spec, cli/assets/usage-extra.usage.kdl. The fix goes in the template:

source_code_link_template "https://github.com/jdx/usage/blob/main/cli/src/cli/{{ path | replace(from='-', to='_') }}.rs"

Underscoring path inside the generator would have been wrong: command-name → file-name is project-specific. usage's files are Rust snake_case, but a Node CLI could legitimately ship complete-word.js, and the change would have silently altered output for every downstream consumer. mise's own spec already does this same replacement in its template (examples/mise.usage.kdl), so this follows the established idiom.

Test

test_source_code_links_for_multi_word_commands_exist in cli/tests/markdown.rs generates markdown from the checked-in spec, pairs each command heading with its source-code link, and asserts the file exists on disk for every hyphenated command. It asserts a floor of ≥2 commands checked, so a parsing regression can't make it pass vacuously.

Verified it catches the bug — reverting the template gives:

`usage complete-word` links to cli/src/cli/complete-word.rs, which does not exist

For the reviewer

Some source-code links still 404, for a different reason, and are deliberately out of scope here:

• bash.md / zsh.md / fish.md / powershell.md link at bash.rs etc., but all four commands are implemented in cli/src/cli/shell.rs
• generate.md links at generate.rs rather than generate/mod.rs (mise's template handles this parent-command case with {% if cmd.subcommands | length > 0 %})

That is why the new test is scoped to multi-word commands rather than asserting every link. It should be widened once those resolve.

Docs regenerated with mise run render. cargo test --workspace --all-features, cargo clippy --workspace --all-features --all-targets -- -D warnings, and cargo fmt --all all pass.

This PR description was generated by Claude Code.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and spec-template changes only; no runtime CLI or generator logic changes beyond regenerated markdown/JSON.

Overview
Generated CLI reference source code links for hyphenated commands (e.g. complete-word, generate completion-init) were built from the command path as-is, so they pointed at non-existent paths like complete-word.rs instead of complete_word.rs and 404’d on GitHub.

The fix updates source_code_link_template in the usage specs (cli/assets/usage-extra.usage.kdl, cli/usage.usage.kdl) to apply {{ path | replace(from='-', to='_') }} before appending .rs, keeping command-name → file-name mapping in the spec rather than hard-coding it in the markdown generator. Regenerated reference output (docs/cli/reference/*, commands.json) reflects the corrected links.

A new integration test in cli/tests/markdown.rs generates markdown from the checked-in spec and asserts that every multi-word command’s source link resolves to a real file on disk (with a minimum of two commands checked so the test can’t pass vacuously).

^{Reviewed by Cursor Bugbot for commit 3c53cc5. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes

  • Corrected generated CLI source-code links for hyphenated commands so they now point to the corresponding Rust source files.

• Documentation

  • Updated CLI reference links to use the correct underscored filenames.
  • Added guidance documenting the command-to-source filename convention.

• Tests

  • Added coverage verifying that generated Markdown source links resolve correctly for multi-word commands.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: d7c275ef-9a62-4f44-b2f3-c768c81dc397

📥 Commits

Reviewing files that changed from the base of the PR and between bc9d648 and 3c53cc5.

📒 Files selected for processing (6)

• cli/assets/usage-extra.usage.kdl
• cli/tests/markdown.rs
• cli/usage.usage.kdl
• docs/cli/reference/commands.json
• docs/cli/reference/complete-word.md
• docs/cli/reference/generate/completion-init.md

---

📝 Walkthrough

Walkthrough

Source-code link templates now convert hyphenated CLI command paths to underscored Rust filenames. Reference links were updated, and an integration test verifies that generated Markdown links resolve to existing files.

Changes

CLI source-link normalization

Layer / File(s)	Summary
Source-link template mapping cli/assets/usage-extra.usage.kdl, cli/usage.usage.kdl, docs/cli/reference/commands.json	Templates replace hyphens with underscores when generating Rust source paths. Comments document the naming convention.
Link validation and references cli/tests/markdown.rs, docs/cli/reference/complete-word.md, docs/cli/reference/generate/completion-init.md	The integration test checks generated links for hyphenated commands. Reference links use complete_word.rs and completion_init.rs.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to 3c53c

This localized change corrects generated links for multi-word CLI commands and adds regression coverage; no actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

• jdx/usage#746: Updates related CLI source-link templates and documentation.
• jdx/usage#762: References the complete_word.rs source file for the complete-word command.
• jdx/usage#803: Addresses hyphen-to-underscore normalization for CLI names.

Poem

A rabbit found a dashed command,
And mapped its path with careful hand.
Hyphens hopped to underscores bright,
Rust links now land exactly right.
Tests thump twice: “The files are there!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes fixing documentation links for multi-word commands.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR updates the repository-specific source-link template so hyphenated CLI command paths resolve to snake_case Rust source files and regenerates the affected reference documentation.

• Rewrites hyphens to underscores in the checked-in and source usage specifications.
• Adds a regression test that validates generated links for the current multi-word commands against the filesystem.
• Regenerates JSON and Markdown reference artifacts with corrected links.

Confidence Score: 5/5

The PR appears safe to merge, with the corrected links matching the current source tree and regression coverage validating both affected commands.

The template preserves nested path separators while mapping the two current hyphenated command names to existing snake_case Rust files, and no blocking or independently actionable issue remains.

Important Files Changed

Filename	Overview
cli/assets/usage-extra.usage.kdl	Updates the canonical hand-written source-link template to map hyphenated command names to existing snake_case Rust modules.
cli/tests/markdown.rs	Adds a non-vacuous regression test that renders the checked-in specification and verifies both current hyphenated command links resolve to files.
cli/usage.usage.kdl	Regenerates the CLI's checked-in self-description with the corrected source-link template.
docs/cli/reference/commands.json	Regenerates the serialized reference specification with the corrected template.
docs/cli/reference/complete-word.md	Corrects the complete-word source link from complete-word.rs to the existing complete_word.rs file.
docs/cli/reference/generate/completion-init.md	Corrects the completion-init source link from completion-init.rs to the existing completion_init.rs file.

_{Reviews (1): Last reviewed commit: "fix(docs): link multi-word commands to t..." | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▂▂▂▂▂▁▁▂▁█	148,191,912 → 148,983,794	+0.53%	14.56 → 14.51ms	-0.37%
startup	▁▁▁█████████	1,201,903 → 1,201,983	+0.01%	0.98 → 1.04ms	+5.81%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

	usage	clap	ratio
instructions, cold parse	39828	5962046	149x

usage: argv -> struct                            1683 ns      1.68 µs
clap: build tree + parse -> struct             506976 ns    506.98 µs
clap: parse -> struct, tree reused              23726 ns     23.73 µs
clap: build tree only                          312924 ns    312.92 µs

_{3c53cc5480d4 vs bc9d64801f56 · measured on the runner, not pushed to the history.}