From 0d769773a1c439b6fd7c633d67f948012c004de7 Mon Sep 17 00:00:00 2001 From: default <216188+jdx@users.noreply.github.com> Date: Wed, 12 Aug 2026 22:52:09 +0000 Subject: [PATCH] fix(docs): link every command to the file that implements it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The four shell commands are all served by `shell.rs`, and `generate` lives in `generate/mod.rs`, but the link template spelled each command's file after the command itself, so those five links 404'd on GitHub. The command-to-file mapping is project-specific, so the two remaining rules join the hyphen-to-underscore step inside the template: a command with subcommands links at its directory's `mod.rs` — the idiom mise's spec already uses — and the four shells link at the one file they share. The link test no longer skips single-word commands, since those were exactly the broken ones. Every command in the spec is now checked against the file system, plus one named command per rule so that dropping a rule fails the test instead of a reader's browser. Co-Authored-By: Claude Opus 5 --- cli/assets/usage-extra.usage.kdl | 16 +++++++++++-- cli/tests/markdown.rs | 40 ++++++++++++++++++-------------- cli/usage.usage.kdl | 16 +++++++++++-- docs/cli/reference/bash.md | 2 +- docs/cli/reference/commands.json | 2 +- docs/cli/reference/fish.md | 2 +- docs/cli/reference/generate.md | 2 +- docs/cli/reference/powershell.md | 2 +- docs/cli/reference/zsh.md | 2 +- 9 files changed, 57 insertions(+), 27 deletions(-) diff --git a/cli/assets/usage-extra.usage.kdl b/cli/assets/usage-extra.usage.kdl index a12803e8c..8dd408b74 100644 --- a/cli/assets/usage-extra.usage.kdl +++ b/cli/assets/usage-extra.usage.kdl @@ -1,3 +1,15 @@ repository "https://github.com/jdx/usage" -// command names are hyphenated, the files that implement them are snake_case -source_code_link_template "https://github.com/jdx/usage/blob/main/cli/src/cli/{{ path | replace(from='-', to='_') }}.rs" +// The command path is not the file path: command names are hyphenated where the files +// that implement them are snake_case, a command with subcommands lives in its directory's +// `mod.rs`, and the four shell commands are all served by a single `shell.rs`. +source_code_link_template #""" +{%- set path = path | replace(from='-', to='_') -%} +{%- if cmd.subcommands | length > 0 -%} +{%- set path = path ~ "/mod.rs" -%} +{%- elif path in ["bash", "fish", "powershell", "zsh"] -%} +{%- set path = "shell.rs" -%} +{%- else -%} +{%- set path = path ~ ".rs" -%} +{%- endif -%} +https://github.com/jdx/usage/blob/main/cli/src/cli/{{path}} +"""# diff --git a/cli/tests/markdown.rs b/cli/tests/markdown.rs index c9cceb677..63d1f2c9e 100644 --- a/cli/tests/markdown.rs +++ b/cli/tests/markdown.rs @@ -251,9 +251,11 @@ fn test_markdown_out_file_dash_writes_no_file() { } #[test] -fn test_source_code_links_for_multi_word_commands_exist() { - // A hyphenated command like `complete-word` lives in `complete_word.rs`; linking it as - // `complete-word.rs` is a 404 on GitHub, and nothing but the file system can catch it. +fn test_source_code_links_exist() { + // A command's path is not its file's path: `complete-word` lives in `complete_word.rs`, + // `generate` in `generate/mod.rs`, and `bash` in `shell.rs`, which it shares with the + // three other shells. Each of those is a 404 on GitHub when the template gets it wrong, + // and nothing but the file system can catch it. let repo_root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")) .parent() .unwrap() @@ -290,27 +292,31 @@ fn test_source_code_links_for_multi_word_commands_exist() { continue; }; let path = rest.split_once("`]").expect("malformed source code link").0; - // Single-word commands are linked from the same template, but several of them - // legitimately live elsewhere (`usage bash` is served by `shell.rs`), so only the - // hyphen-to-underscore mapping is asserted here. - let is_multi_word = cur_cmd - .split_whitespace() - .next_back() - .unwrap_or("") - .contains('-'); - if !is_multi_word { - continue; - } assert!( repo_root.join(path).is_file(), "`{cur_cmd}` links to {path}, which does not exist" ); - checked.push(cur_cmd.clone()); + checked.push((cur_cmd.clone(), path.to_string())); } + // Every command carries a link, so a scrape that suddenly matches almost nothing means + // the document changed shape and the assertions above went blind. assert!( - checked.len() >= 2, - "expected to check several multi-word commands, checked {checked:?}" + checked.len() >= 10, + "expected a link for every command, checked {checked:?}" ); + // Existence alone can't tell a correct mapping from a coincidence, and each of the three + // rules in the template is currently carried by only part of the spec. Name one command + // per rule so that dropping a rule fails here rather than in a reader's browser. + for (cmd, file) in [ + ("usage complete-word", "cli/src/cli/complete_word.rs"), + ("usage generate", "cli/src/cli/generate/mod.rs"), + ("usage bash", "cli/src/cli/shell.rs"), + ] { + assert!( + checked.contains(&(cmd.to_string(), file.to_string())), + "expected `{cmd}` to link to {file}, checked {checked:?}" + ); + } fs::remove_file(&out_file).unwrap(); } diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl index 65783f972..749ffcb17 100644 --- a/cli/usage.usage.kdl +++ b/cli/usage.usage.kdl @@ -249,5 +249,17 @@ to properly escape and quote values with spaces in them. } repository "https://github.com/jdx/usage" -// command names are hyphenated, the files that implement them are snake_case -source_code_link_template "https://github.com/jdx/usage/blob/main/cli/src/cli/{{ path | replace(from='-', to='_') }}.rs" +// The command path is not the file path: command names are hyphenated where the files +// that implement them are snake_case, a command with subcommands lives in its directory's +// `mod.rs`, and the four shell commands are all served by a single `shell.rs`. +source_code_link_template #""" +{%- set path = path | replace(from='-', to='_') -%} +{%- if cmd.subcommands | length > 0 -%} +{%- set path = path ~ "/mod.rs" -%} +{%- elif path in ["bash", "fish", "powershell", "zsh"] -%} +{%- set path = "shell.rs" -%} +{%- else -%} +{%- set path = path ~ ".rs" -%} +{%- endif -%} +https://github.com/jdx/usage/blob/main/cli/src/cli/{{path}} +"""# diff --git a/docs/cli/reference/bash.md b/docs/cli/reference/bash.md index dee1d8f41..d6d0daa33 100644 --- a/docs/cli/reference/bash.md +++ b/docs/cli/reference/bash.md @@ -3,7 +3,7 @@ # `usage bash` - **Usage**: `usage bash [-h] [--help]