diff --git a/AGENTS.md b/AGENTS.md index f1c90a9..c8475ab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,6 +31,13 @@ - Use `unwrap_or_else(|| expr)` for lazy defaults, `unwrap_or(val)` for eager defaults - Use `anyhow!()` with context strings that include identifying info (e.g. UUID, title) not bare values +### CLI Arguments +- The prose arguments carry `allow_hyphen_values`, via the `PROSE` constant in `command.rs`: `add --title`, `--description`, `--acceptance`, `--plan`, and the `comment` body. Ticket text quotes flag names constantly, and without it a criterion reading `--print is supported` is parsed as a flag and the whole ticket is refused with nothing written +- **The trade:** on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why `due`, `priority`, `tags`, `owner` and `status` are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add `PROSE` to a new argument unless it holds prose +- The ticket positionals (`show `, `mv `, `comment `) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title` +- A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop +- `add` has no positionals, so anything after a bare `--` is an unexpected argument and fails + ### Color and Output - Use `color_text()` helper for colored output — it respects `should_use_colors()` (terminal detection) - Color codes are defined in `get_color()`: red (31), cyan (36), orange (33), green (32), grey (38;5;8), magenta (1;35), brightred (38;5;9) diff --git a/Cargo.lock b/Cargo.lock index c155934..b1ea0d9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1029,7 +1029,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.3.1" +version = "0.3.2" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index eb80556..6688df9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.3.1" +version = "0.3.2" edition = "2024" [dependencies] diff --git a/src/command.rs b/src/command.rs index 3528a2e..f95e72e 100644 --- a/src/command.rs +++ b/src/command.rs @@ -37,6 +37,17 @@ pub struct Cli { pub command: Command, } +/// Arguments that carry prose, and therefore have to accept a value starting with +/// a hyphen. +/// +/// Ticket text quotes flag names constantly, and without this a criterion reading +/// "--print is supported" is parsed as a flag and the whole ticket is refused. The +/// trade, spelled out in AGENTS.md: on these arguments a genuinely mistyped flag +/// now lands as content instead of raising a usage error. That is the right way +/// round for prose, and it is why `due`, `priority`, `tags`, `owner` and `status` +/// are deliberately left without it. +const PROSE: bool = true; + #[derive(clap::Subcommand)] pub enum Command { /// Initialize worklane in the current project @@ -45,19 +56,19 @@ pub enum Command { /// Add a new ticket to the backlog Add { /// Ticket title - #[arg(short, long)] + #[arg(short, long, allow_hyphen_values = PROSE)] title: String, /// Ticket description. Use multiple flags to create multiline descriptions. - #[arg(short, long)] + #[arg(short, long, allow_hyphen_values = PROSE)] description: Vec, /// Acceptance criteria. Accepts multiple flags, each will be interpreted as a single criterium - #[arg(short, long)] + #[arg(short, long, allow_hyphen_values = PROSE)] acceptance: Vec, /// Implementation plan. Accepts multiple flags, each will be interpreted as a single step - #[arg(short, long)] + #[arg(short, long, allow_hyphen_values = PROSE)] plan: Vec, /// Tags (comma-separated) @@ -114,6 +125,7 @@ pub enum Command { ticket: String, /// Comment body (required) + #[arg(allow_hyphen_values = PROSE)] body: String, /// Owner diff --git a/tests/cmd_add.rs b/tests/cmd_add.rs index 51ce760..7ad9588 100644 --- a/tests/cmd_add.rs +++ b/tests/cmd_add.rs @@ -262,3 +262,121 @@ fn add_rejects_a_level_outside_the_range() { let count = fs::read_dir(worklane.join("backlog")).unwrap().count(); assert_eq!(count, 0, "a ticket was written despite a bad level"); } + +/// Ticket text quotes flag names constantly, and the space form is what both a +/// person and the opencode wrapper produce. Every one of these used to be refused +/// with "unexpected argument found", writing no ticket at all. +#[test] +fn add_accepts_prose_values_that_begin_with_a_hyphen() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()) + .args(["add", "--title", "-t is a flag name"]) + .args(["--description", "-x does nothing"]) + .args(["--acceptance", "--print should be supported"]) + .args(["--plan", "-f skips the check"]) + .assert() + .success(); + + let content = only_ticket(&worklane); + + // Stored verbatim, hyphens and all + assert!(content.contains("# -t is a flag name"), "was {content:?}"); + assert!(content.contains("-x does nothing"), "was {content:?}"); + assert!( + content.contains("- [ ] --print should be supported"), + "was {content:?}" + ); + assert!(content.contains("1. -f skips the check"), "was {content:?}"); +} + +/// The docs and the habit both use it, and it reaches the parser as one token, so +/// it has to keep working alongside the space form. +#[test] +fn add_still_accepts_the_equals_form() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()) + .args(["add", "--title=-x equals form"]) + .args(["--acceptance=--print via equals"]) + .assert() + .success(); + + let content = only_ticket(&worklane); + assert!(content.contains("# -x equals form"), "was {content:?}"); + assert!( + content.contains("- [ ] --print via equals"), + "was {content:?}" + ); +} + +/// Never silently dropped: a value that is nothing but hyphens is content. +#[test] +fn add_stores_a_title_that_is_only_hyphens() { + for bare in ["-", "--", "---"] { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()) + .args(["add", "--title", bare]) + .assert() + .success(); + + let content = only_ticket(&worklane); + assert!( + content.starts_with(&format!("# {}\n", bare)), + "for {bare:?}: {content:?}" + ); + } +} + +/// The other half of the trade. These arguments were deliberately left alone, so a +/// mistyped flag there is still a usage error rather than stored text. +#[test] +fn add_still_rejects_a_mistyped_flag_on_a_non_prose_argument() { + for flag in ["--due", "--priority", "--tags", "--owner"] { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()) + .args(["add", "--title", "Mistyped", flag, "--bogus"]) + .assert() + .failure(); + + let count = fs::read_dir(worklane.join("backlog")).unwrap().count(); + assert_eq!(count, 0, "{flag} wrote a ticket anyway"); + } +} + +/// `add` has no positionals, so a bare `--` ends the options and whatever follows +/// has nowhere to go. Recorded because clap's separator and a hyphen-leading value +/// are easy to confuse. +#[test] +fn add_rejects_arguments_after_a_bare_separator() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()) + .args(["add", "--title", "Sep", "--", "--title", "second"]) + .assert() + .failure(); + + let count = fs::read_dir(worklane.join("backlog")).unwrap().count(); + assert_eq!(count, 0); +} + +fn only_ticket(worklane: &PathBuf) -> String { + let files: Vec<_> = fs::read_dir(worklane.join("backlog")) + .unwrap() + .filter_map(|e| e.ok()) + .collect(); + assert_eq!(files.len(), 1, "expected exactly one ticket"); + fs::read_to_string(files[0].path()).unwrap() +} diff --git a/tests/cmd_comment.rs b/tests/cmd_comment.rs index cc61096..5e6e2b7 100644 --- a/tests/cmd_comment.rs +++ b/tests/cmd_comment.rs @@ -250,3 +250,92 @@ fn comments_added_back_to_back_are_both_kept() { let third = stdout.find("third comment").expect("third comment missing"); assert!(first < second && second < third, "comments out of order"); } + +/// The body is a positional, and the case that motivated this: a review comment +/// quoting a flag name used to be refused outright. +#[test] +fn comment_accepts_a_body_that_begins_with_a_hyphen() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let uuid = create_ticket(&worklane, "backlog", "Hyphen body"); + + for body in ["--print is the flag I mean", "-f skips the check", "-"] { + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()) + .args(["comment", &uuid, body]) + .assert() + .success(); + } + + let bodies: String = fs::read_dir(worklane.join("comments").join(&uuid)) + .unwrap() + .filter_map(|e| e.ok()) + .map(|e| fs::read_to_string(e.path()).unwrap()) + .collect(); + + for body in ["--print is the flag I mean", "-f skips the check"] { + assert!(bodies.contains(body), "{body:?} missing from {bodies:?}"); + } +} + +/// The ticket positional was deliberately left alone, so a hyphen-leading search +/// term is still a usage error. A bare separator is the way through, and it is the +/// only way through for `comment` since the body follows in the same position. +#[test] +fn comment_needs_a_separator_for_a_hyphen_leading_ticket() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog", "-leading"); + + let mut without = Command::cargo_bin(BIN_NAME).unwrap(); + without + .current_dir(&temp.path()) + .args(["comment", "-leading", "a body"]) + .assert() + .failure(); + + let mut with = Command::cargo_bin(BIN_NAME).unwrap(); + with.current_dir(&temp.path()) + .args(["comment", "--", "-leading", "a body"]) + .assert() + .success(); +} + +/// The one shape `allow_hyphen_values` does not reach: a lone `--` in a positional +/// is clap's end-of-options marker, consumed before any value is assigned. So a +/// comment body of exactly `--` needs its own separator in front of it. +/// +/// Not a silent drop either way, which is what matters: without the separator the +/// body is reported missing and nothing is written. +#[test] +fn a_bare_double_hyphen_body_needs_a_separator() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let uuid = create_ticket(&worklane, "backlog", "Bare separator"); + + let mut without = Command::cargo_bin(BIN_NAME).unwrap(); + let assert = without + .current_dir(&temp.path()) + .args(["comment", &uuid, "--"]) + .assert() + .failure(); + let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap(); + assert!(stderr.contains(""), "unclear error: {stderr}"); + assert!( + !worklane.join("comments").join(&uuid).exists(), + "a comment was written despite the error" + ); + + let mut with = Command::cargo_bin(BIN_NAME).unwrap(); + with.current_dir(&temp.path()) + .args(["comment", &uuid, "--", "--"]) + .assert() + .success(); + + let stored: String = fs::read_dir(worklane.join("comments").join(&uuid)) + .unwrap() + .filter_map(|e| e.ok()) + .map(|e| fs::read_to_string(e.path()).unwrap()) + .collect(); + assert!(stored.contains("**Comment**\n--\n"), "was {stored:?}"); +}