diff --git a/Cargo.lock b/Cargo.lock index 80a5fe7..9abc65a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.26.3" +version = "0.26.4" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index b356d70..be7d38c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.26.3" +version = "0.26.4" edition = "2024" [dependencies] diff --git a/assets/ADMIN.md b/assets/ADMIN.md index 4235cd4..691c88c 100644 --- a/assets/ADMIN.md +++ b/assets/ADMIN.md @@ -122,7 +122,7 @@ question asked by tag. ## Annotating a tag ``` -worklane tags # every tag carried, with counts +worklane tags # every tag, its count and what it means worklane tags add kitchen --annotation "..." # declare one, and say what it means worklane tags set kitchen --annotation "..." # change what it means ``` @@ -132,10 +132,15 @@ annotation under it. It is what a person opens to find out what the board means and it is what an agent reads before choosing one. **Declaring a tag tags nothing, and tagging a ticket declares nothing.** The two lists are -separate on purpose: `worklane tags` counts what the tickets carry, `tags.md` records what +separate on purpose: the counts come from what the tickets carry, `tags.md` records what the board agreed on, and the difference between them is the thing worth looking at. A tag carried by tickets but never declared is a word somebody invented in a hurry. +`worklane tags` reports both, as the tag, a tab, the count, and a tab and the annotation's +opening line for a tag that is declared. So the two cases worth finding read off the +listing: a tag at a count of zero is declared and nobody has reached for it, and a tag with +no annotation column at all is carried and was never declared. + ### What an annotation has to say The definition is the easy half and does the least work. What stops drift is the boundary @@ -177,9 +182,9 @@ ones two people quietly disagree about. not. Each names the other, so the refusal tells you which you wanted. - A tag cannot contain a comma, because a comma is what separates one tag from the next in the Tags field. Surrounding spaces are trimmed. -- `worklane tags` counts tickets, so a tag you have declared and never applied does not - appear in it. That is not a fault; it is the file and the board disagreeing, which is - the state that tells you the vocabulary has not landed yet. +- A tag you have declared and never applied lists at a count of zero. That is not a fault; + it is the file and the board disagreeing, which is the state that tells you the + vocabulary has not landed yet. - Nothing removes a declaration. There is no `tags rm`, so a tag declared in error stays in the file with whatever its annotation says. Say it is retired in the annotation. diff --git a/src/completions.rs b/src/completions.rs index 455ea72..843281a 100644 --- a/src/completions.rs +++ b/src/completions.rs @@ -192,14 +192,21 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \ -x -a '(worklane campaign ls --ids)' # Tags come from `worklane tags` rather than from a listing of objects, since a tag has no -# id. The count after the tab lands as fish's description, which is what makes the list -# worth reading: it says which spelling the board actually uses. -complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -a '(worklane tags)' +# id. Three fields now, the tag, its count and its annotation, and fish takes everything +# after the *first* tab as one description, so the count is dropped here rather than landing +# in the middle of the prose. `cut` and not `string replace` because the columns are what is +# being picked, and `cut -f1` is how a script reads this listing anyway. +# +# What is left is the annotation, and a tag the board carries but has never declared has +# none: it is offered with no description at all, which is the near-duplicate the file was +# added to catch. The count used to be the description and said the same thing more weakly. +complete -c worklane -n '__worklane_command_is ls' {tag_flags} \ + -x -a '(worklane tags | cut -f1,3)' # And `tags set` names one that is already declared, so it reads the same listing. `tags # add` has no rule on purpose: it takes a tag the board does not have, so the candidates # here are the values it refuses. -complete -c worklane -n '{tag_nested}' -a '(worklane tags)' +complete -c worklane -n '{tag_nested}' -a '(worklane tags | cut -f1,3)' # `chown --clear` names the ticket in the flag too, since with no user to give there is # no second positional to put it in. Scoped to `chown`, unlike the rule above: `set` @@ -514,6 +521,32 @@ mod tests { assert!(script.contains("__worklane_first_arg_of assign"), "{script}"); } + /// Every rule that reads the tag listing drops the count, because `worklane tags` prints + /// three fields and fish takes everything after the first tab as the description. Left + /// whole, a tag would be described as its count, a tab and its annotation. + /// + /// Pinned per rule rather than once over the script: a rule added later that reads + /// `worklane tags` raw is the bug this catches, and it would not show up in a single + /// `contains`. + #[test] + fn every_tag_rule_takes_the_annotation_as_its_description() { + let script = fish_dynamic(); + + let reading: Vec<&str> = script + .lines() + .filter(|line| line.contains("(worklane tags")) + .collect(); + + assert_eq!( + reading.len(), + 2, + "expected the ls --tag rule and the tags set one: {reading:?}" + ); + for line in reading { + assert!(line.contains("(worklane tags | cut -f1,3)"), "{line}"); + } + } + /// The one status positional and the one shell positional, which clap does not emit /// possible values for. Read off the enums, so a fifth status would appear here on /// its own. diff --git a/src/handlers.rs b/src/handlers.rs index 3e6d3f0..16c361a 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -1217,27 +1217,52 @@ pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> { Ok(()) } -/// Every tag on the board, with how many tickets carry it. +/// Every tag on the board: the ones the tickets carry, the ones the file declares, and +/// what each declared one means. /// /// The vocabulary itself, which nothing else could answer: `ls --tag` filters by a tag /// already known, and the decorated listing does not print tags at all. A grooming sweep /// starts by asking what the vocabulary *is*, and `assets/PLAN.md` used to have to say /// that the question could only be answered by reading the tickets. /// +/// **The union of the two vocabularies, not either one.** Since `tags.md` exists there are +/// two: the tags the file declares and the tags the tickets carry. A declared tag nothing +/// carries lists at zero rather than being dropped, and a carried tag nothing declares +/// still lists. Those two cases are the whole reason to declare tags at all, so this is +/// the command that has to show them apart. +/// /// **Alphabetical, and case sensitive.** `--tag` matches a whole value case sensitively, /// so `bug` and `Bug` are two tags and listing them as one would hide the reason a filter /// came back short. Sorting puts them next to each other, which is where a near-duplicate /// is spotted. /// -/// Machine-readable, the second output in the tree that is: the tag, a tab, the count. -/// Fish reads what follows the tab as a description, a script takes `cut -f1`, and neither -/// wants an escape sequence. Every status, done included, for the reason `ls --ids` -/// includes it: a tag retired months ago is still part of the answer to what the -/// vocabulary has been. +/// Machine-readable, the second output in the tree that is: the tag, a tab, the count, and +/// a tab and the annotation's opening line for a tag the file declares. Fish reads what +/// follows the first tab as a description, a script takes `cut -f1`, and neither wants an +/// escape sequence. +/// +/// **A carried but undeclared tag is marked by the absence of the third field**, which is +/// where the shape comes from. Anything appended to the tag itself would have a completion +/// offer a tag that does not exist, and anything added to the count would stop the second +/// field being a number. Absence costs neither, and it buys the one property a marker +/// could not: a board with no `tags.md` has every tag undeclared, so it prints two fields +/// a line, which is byte for byte what this printed before the file existed. The shipped +/// fish completion of an older version is still reading that. +/// +/// Every status, done included, for the reason `ls --ids` includes it: a tag retired months +/// ago is still part of the answer to what the vocabulary has been. pub fn cmd_tags(worklane_dir: &Path) -> Result<()> { + // Through the same `load` `tags add` uses, so a file that is there and cannot be read + // is an error here too. The listing is the one tag command that could go on without the + // file, and reporting a vocabulary while silently treating a broken file as no file is + // the wrong half of the answer. + let index = TagIndex::load(worklane_dir)?; + // BTreeMap rather than a sort afterwards: the order is the point, and the counting - // wants a map anyway. - let mut counts: BTreeMap = BTreeMap::new(); + // wants a map anyway. Seeded from the vocabulary rather than merged into afterwards, + // which is what puts a declared tag nothing carries in at zero. + let mut counts: BTreeMap = + index.names().map(|tag| (tag.to_string(), 0)).collect(); for status in status_dirs() { let status_path = worklane_dir.join(status); @@ -1253,7 +1278,10 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> { } for (tag, count) in counts { - println!("{}\t{}", tag, count); + match index.summary(&tag) { + Some(summary) => println!("{tag}\t{count}\t{summary}"), + None => println!("{tag}\t{count}"), + } } Ok(()) diff --git a/src/tag.rs b/src/tag.rs index 0c065dd..d07edc8 100644 --- a/src/tag.rs +++ b/src/tag.rs @@ -153,6 +153,45 @@ impl TagIndex { self.tags.contains_key(tag) } + /// Every tag the file declares, alphabetical, whatever the board carries. + /// + /// The half of the listing the status directories cannot answer. A tag declared and + /// never applied is carried by no ticket, so counting alone drops it, and that tag is + /// most of the reason the file exists: a word the board agreed on and nobody has + /// reached for yet is exactly what a grooming sweep wants to see. + pub fn names(&self) -> impl Iterator { + self.tags.keys().map(String::as_str) + } + + /// The opening line of what a tag means, or `None` for a tag the file does not declare. + /// + /// The cut to one line lives here rather than on the parse, the way + /// [`CampaignRow::summary`] takes one line off a description the read carries whole: + /// the annotation is prose with paragraphs in it, and which view wants how much of it + /// is the view's business. + /// + /// **`None` is what marks a carried but undeclared tag**, since `cmd_tags` prints no + /// third field for it. Nothing is appended to the tag itself and nothing is added to + /// the count, so `cut -f1` still yields the tag values and a board with no file at all + /// lists what it listed before the file existed. + /// + /// A declared tag with nothing said about it answers [`NO_ANNOTATION`] rather than an + /// empty string, because an empty third field is a trailing tab and nothing else: it + /// would be the only difference between declared and not, and it would be invisible in + /// a terminal and in a completion alike. The placeholder is also what the file itself + /// holds under that heading, so the field stays the section's opening line either way. + /// + /// [`CampaignRow::summary`]: crate::tui::CampaignRow::summary + /// [`NO_ANNOTATION`]: crate::tag::NO_ANNOTATION + pub fn summary(&self, tag: &str) -> Option<&str> { + let annotation = self.tags.get(tag)?; + + Some(match annotation.lines().next() { + Some(line) => line, + None => NO_ANNOTATION, + }) + } + /// Declare `tag`, or replace what it means. /// /// One writer for both, because the file holds one section per tag either way and the diff --git a/tests/cmd_tags.rs b/tests/cmd_tags.rs index 078a3f2..43e20c7 100644 --- a/tests/cmd_tags.rs +++ b/tests/cmd_tags.rs @@ -5,10 +5,11 @@ //! under test are the ones that question needs: every status counted, case kept apart, //! alphabetical order, and an output a shell can parse. //! -//! `tags add` is the other half of the same question. The listing reports the vocabulary -//! the tickets *carry*; the file reports the one the board *intends*, and the tests below -//! are mostly about the two being allowed to disagree without either one damaging the -//! other. +//! `tags add` is the other half of the same question. The file reports the vocabulary the +//! board *intends* and the tickets carry the one it *has*, and the tests below are mostly +//! about the two being allowed to disagree without either one damaging the other. The +//! listing reports both and marks which is which, so the tests for the output shape are +//! about the marking: which field it lands in, and what a board with no file still prints. use assert_cmd::Command; use assert_fs::TempDir; @@ -380,19 +381,113 @@ fn a_vocabulary_that_cannot_be_read_is_refused_rather_than_replaced() { assert!(stray.is_empty(), "a temp file was left in .worklane"); } -/// The vocabulary does not touch the listing, which counts tickets. The two disagreeing is -/// the normal state and the thing the file is for. +/// The listing is the union of the two vocabularies, and the two disagreeing is the normal +/// state rather than a fault: a declaration tags no ticket, and tagging a ticket declares +/// nothing. +/// +/// Both halves of the disagreement in one assertion, since neither is legible without the +/// other. `chore` is declared and carried by nothing, so it lists at zero with what it +/// means; `bug` is carried and declared by nothing, so it lists with a count and no third +/// field at all. #[test] -fn a_declared_tag_is_not_a_carried_one() { +fn the_listing_is_the_union_of_the_declared_and_the_carried() { let temp = TempDir::new().unwrap(); let worklane = setup_worklane(&temp); create_ticket(&worklane, "backlog", "11111111", "bug"); run(&temp, &["tags", "add", "chore", "-a", "Housekeeping."]); - // `chore` is declared and carried by nothing, `bug` is carried and declared by nothing, - // and the listing still answers only the second question. Reporting both is 9564ac9. - assert_eq!(tags(&temp), vec!["bug\t1"]); + assert_eq!(tags(&temp), vec!["bug\t1", "chore\t0\tHousekeeping."]); +} + +/// The third field is the annotation's *opening* line. An annotation is prose with +/// paragraphs in it, and a second line in this output would be read as a second tag. +#[test] +fn the_annotation_is_cut_to_its_opening_line() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + run( + &temp, + &[ + "tags", + "add", + "bug", + "-a", + "What it is.", + "-a", + "", + "-a", + "When to use it.", + ], + ); + + assert_eq!(tags(&temp), vec!["bug\t0\tWhat it is."]); +} + +/// A tag declared with nothing said about it still carries a third field, and it is the +/// placeholder the file itself holds under that heading. +/// +/// The subtle case, and the reason the field is not simply left empty: an empty third field +/// is a trailing tab, so the only difference between a declared tag and an undeclared one +/// would be invisible in a terminal and in a completion alike. +#[test] +fn a_tag_declared_without_an_annotation_is_still_marked_as_declared() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog", "11111111", "carried"); + + run(&temp, &["tags", "add", "declared"]); + + assert_eq!(tags(&temp), vec!["carried\t1", "declared\t0\t_No annotation provided._"]); +} + +/// `cut -f1` over the listing yields exactly the tag values, undeclared ones included. +/// +/// The constraint the whole output shape is built around: whatever marks a carried but +/// undeclared tag must stay out of the first field, or a completion offers a tag that does +/// not exist and `ls --tag` comes back empty for it. +#[test] +fn the_first_field_is_the_bare_tag_whether_it_is_declared_or_not() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog", "11111111", "carried,both"); + run(&temp, &["tags", "add", "both", "-a", "Carried and declared."]); + run(&temp, &["tags", "add", "declared", "-a", "Declared only."]); + + let first: Vec = tags(&temp) + .iter() + .map(|line| line.split('\t').next().unwrap().to_string()) + .collect(); + assert_eq!(first, vec!["both", "carried", "declared"]); + + // And each of them is a value `--tag` can match, which is what the first field is for. + for tag in ["both", "carried"] { + let out = run(&temp, &["ls", "--tag", tag, "--ids"]); + assert_eq!( + String::from_utf8_lossy(&out.stdout).lines().count(), + 1, + "--tag {tag} matched nothing" + ); + } +} + +/// A board with no vocabulary lists what it listed before the file existed, byte for byte. +/// +/// Every tag on such a board is carried and undeclared, so the absence of the third field +/// is what keeps the old output shape: a marker in it would have changed every line of +/// every board that predates the file, and the shipped fish completion of an older version +/// is still reading this. +#[test] +fn a_board_with_no_vocabulary_lists_what_it_listed_before_the_file_existed() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog", "11111111", "bug, cli"); + create_ticket(&worklane, "done", "22222222", "bug"); + assert!(!temp.path().join(".worklane").join("tags.md").exists()); + + let out = run(&temp, &["tags"]); + assert_eq!(String::from_utf8_lossy(&out.stdout), "bug\t2\ncli\t1\n"); } /// The bare form is the listing, byte for byte, because the shipped fish completion calls it @@ -409,7 +504,10 @@ fn the_bare_form_and_ls_are_the_same_listing() { assert!(bare.status.success()); assert_eq!(bare.stdout, group.stdout); - assert_eq!(String::from_utf8_lossy(&bare.stdout), "bug\t1\ncli\t1\n"); + assert_eq!( + String::from_utf8_lossy(&bare.stdout), + "bug\t1\nchore\t0\t_No annotation provided._\ncli\t1\n" + ); } // -------------------------------------------------- changing what a tag means --