diff --git a/AGENTS.md b/AGENTS.md index b098db4..b514dca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -394,6 +394,7 @@ and this file is for what someone changing worklane's own code needs. - **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake - **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance - `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist +- **The README command table has the same guard, `every_subcommand_has_a_row_in_the_readme_command_table` in `command.rs`.** The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: `campaign` and `assign` shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the `--campaign` flag on the `ls` row. It walks clap's own subcommands, one level of nesting included, against the `|` lines of `README.md`, so a new command fails the suite until the table lists it. `help` is excluded, being clap's. The tag subcommands are named in a `PENDING` list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it ### Color and Output - Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in diff --git a/README.md b/README.md index 1172852..9b5447d 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Worklane is a local Kanban flow for agentic software development. | `worklane campaign add` | Files a campaign in `.worklane/campaigns/` with `--title`, `--description`, `--codename` and `--owner`. A campaign has no status: its state is derived, open until every member is done. `--codename` is one word to call it by, `v1` or `beaver`, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by | | `worklane campaign set ` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` | | `worklane campaign append ` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket | -| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, for a script or a completion | +| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title, how many members are done, and the state that count derives: `[open]` until every member is done and `[done]` after. A campaign nothing has been filed against reads `no members` and carries no state, being neither. `--ids` prints one per line as the id, a tab and the title, unstyled and without the counts, which read every ticket on the board, for a script or a completion | | `worklane campaign show ` | Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks | | `worklane assign ` | Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after `chown`. A ticket is in at most one, so assigning one that already belongs somewhere moves it | | `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known | diff --git a/src/command.rs b/src/command.rs index cc991a0..16deda0 100644 --- a/src/command.rs +++ b/src/command.rs @@ -881,3 +881,68 @@ pub struct CheckArgs { /// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted pub criteria: Vec, } + +#[cfg(test)] +mod tests { + use super::*; + + use clap::CommandFactory; + + /// The command names as the README table would have to spell them: `campaign add` + /// for a nested one, the bare name for a top level one. `help` is clap's own and + /// documents nothing. + fn documented_names() -> Vec { + let cli = Cli::command(); + let mut names = Vec::new(); + + for sub in cli.get_subcommands() { + if sub.get_name() == "help" { + continue; + } + + names.push(sub.get_name().to_string()); + for nested in sub.get_subcommands() { + if nested.get_name() == "help" { + continue; + } + + names.push(format!("{} {}", sub.get_name(), nested.get_name())); + } + } + + names + } + + /// Every subcommand has a row in the README's command table. + /// + /// `campaign` and `assign` went undocumented for two minor versions, e6e3a1b, and + /// the `--campaign` flag went with them, because the only thing walking the table + /// was somebody remembering to. This is what walks it. A command whose row is + /// missing is a command a reader of the README cannot discover at all, which is a + /// worse failure than a row that is merely out of date. + #[test] + fn every_subcommand_has_a_row_in_the_readme_command_table() { + // The tag subcommands are f7dd1a1's, which rewrites the `worklane tags` row + // once the vocabulary work above it has landed. Listed rather than skipped, so + // emptying this is part of closing that ticket rather than something to + // rediscover. + const PENDING: [&str; 3] = ["tags add", "tags set", "tags ls"]; + + let readme = include_str!("../README.md"); + let table: String = readme.lines().filter(|line| line.starts_with('|')).collect(); + + let missing: Vec = documented_names() + .into_iter() + .filter(|name| !PENDING.contains(&name.as_str())) + .filter(|name| !table.contains(&format!("`worklane {}", name))) + .collect(); + + assert!( + missing.is_empty(), + "no row in the README command table for {missing:?}. A new command is not \ + shipped until the table lists it: that table is the only place a reader \ + discovers one, and two commands hid behind an otherwise complete table \ + for two minor versions." + ); + } +}