(74904dc) Let a ticket field be cleared back to unset, and bump to 0.18.0

`set --clear <field>` is the one way to take a value away, repeatable, with
the field as a `ValueEnum` value: an unknown one is a usage error listing the
six that are not, and the shells complete them for free. Not a per-field
`--clear-due`, which is a flag per field to keep in step with the one it
undoes, and not an empty value, which is already a paragraph break for a
section and would make an accidentally empty variable a silent delete.

What goes back is what `add` writes for a field it was never given, through
the new `NOT_SET` and `NONE` constants and each section's placeholder, so a
cleared ticket and one filed without the field read the same. Sections are in
scope and go back through `clear_section_body` rather than
`set_section_body`: the latter runs its items through `Section::render`, which
would have written `- [ ] _No acceptance criteria provided._`.

Owner is `chown --clear <ticket>`, so the field keeps its one writer. The flag
carries the ticket because the ticket is chown's second positional and a bare
flag would land it in the user's slot for the handler to read back out, which
is hand-parsing what clap can state. It writes `_Not set_` rather than the git
user: `add` falls back to the git user because it is filing something new, and
an owner taken away says nobody owns this.

The empty-value error split in two rather than being reworded. `non_empty`
says only that the value cannot be empty, for the arguments with no empty
form; `clearable` names `--clear`, for the arguments whose field has one. One
message for both would have lied about `ls --tag`.

Replacing and clearing one field in a single call is refused rather than
resolved by whichever was applied last, and cleared fields are reported as
`Cleared due on '...'` beside `Updated priority on '...'`, since one list
would say `Updated` of a field that was emptied.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-23 00:04:28 +02:00
co-authored by Claude Opus 5
parent 175c1d016d
commit cc5f9b8a46
15 changed files with 810 additions and 92 deletions
+18 -4
View File
@@ -59,7 +59,8 @@ and this file is for what someone changing worklane's own code needs.
- **`--due` is validated at parse time by `iso_date`, the way `--priority` is by `priority_level`.** A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars without `PROSE`. One parser serves `add` and `set`: the field has one definition of what it accepts, and validating only `add` would leave `set` open, which is the command a grooming sweep actually uses
- **The shape is checked before chrono is asked.** `%Y-%m-%d` accepts an unpadded `2026-8-9`, which would be stored exactly as typed and sort before `2026-10-01` in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting
- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
- An empty `--due` keeps `non_empty`'s message about clearing rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is that clearing is not supported yet
- An empty `--due` keeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser
- **A status is a `util::Status`, not a string.** `mv --status` and the `ls` positional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain `--due` and `--priority` take, and it is what lets the shells complete the four for free. `Status::ALL` is the flow order, which `status_dirs()` and `cmd_mv` both read rather than spelling the names again, and `DONE` is defined from it
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) 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 <ticket> -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
@@ -90,11 +91,24 @@ and this file is for what someone changing worklane's own code needs.
- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s), and neither `add`, `set`, `append` nor `chown` can reach the three status stamps, which `mv` writes as a side effect of the move. Do not add any of them
- `chown` takes the **user first and the ticket second**, after Unix `chown`, and is the only command that does not start with the ticket. Deliberate: the name borrows the Unix association, so the order borrows it too. A swap is left to `resolve_ticket`, which refuses a bare username as a ticket. No argument is inspected to see whether it *also* names a ticket, since such a check would only fire where resolution already fails and would stay silent on the one case it cannot catch, a ticket whose title is the username
- `cmd_chown` is `set_metadata_field` plus `save_ticket`, with the same whole-file no-op comparison `set` uses and the same `report()` output, so nothing about writing a field lives twice
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, and a `SectionKind`. Adding a section later is one entry, not edits in both commands
- `apply()` is the one place an edit is taken or dropped, shared by `set`'s replaced list and its cleared one. It was a closure over the single list until there were two, and two closures carrying one rule is how a later edit changes it for one and not the other
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, a `SectionKind` and the `--clear` value that empties it. Adding a section later is one entry, not edits in both commands
- Everything is targeted line surgery, never a regenerated file. That is what keeps a ticked criterion ticked and a handwritten `## Notes` section intact when an unrelated field changes. `section_body()` finds the lines to touch, `set_metadata_line()` does the metadata, and every other byte is copied through
- Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read `_No description provided._` above its description
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` in `command.rs`. Clearing a field is not supported yet, and the error says so rather than guessing
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` and `clearable` in `command.rs`. Neither spells clearing, and both errors name the flag that does
### Clearing a Field
- **`set --clear <field>` is the one way to take a value away, and it is a flag with the field as its value.** Not a per-field `--clear-due`, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likes
- **`Clearable` is a `ValueEnum` in `util.rs`**, so an unknown field is a usage error at the door listing the six that are not, and the shells complete them for free. It is also the whole table of what can be cleared: `Due`, `Tags` and `Priority` clear to a sentinel, `Description`, `Acceptance` and `Plan` to their section's placeholder. `Title` is absent because it addresses the ticket and names its file, so there is no state to go back to; `Owner`, `Status`, `Campaign` and the stamps because clearing them through `set` is exactly the second writer the missing `set --owner` exists to prevent
- **What is written is `NOT_SET` and `NONE`, the constants `add` writes.** A cleared ticket and one that was never given the field have to read the same, or clearing would be a third state that every parser then has to know about. `a_cleared_ticket_reads_like_one_filed_without_the_fields` compares the two files byte for byte, which is what keeps a new field honest
- **The placeholder goes into a section bare, via `clear_section_body`.** `set_section_body` runs its items through `Section::render`, which would write `- [ ] _No acceptance criteria provided._`. Both are `replace_section_body` underneath, so the line surgery and the trailing blank line live once
- **The pairing between a section and its `--clear` value is stored on both**, `Clearable::unset` one way and `Section::clear` the other, because the error for an empty value has to name the flag for *that* section and the section's label ("acceptance criteria") is not the flag's value ("acceptance"). `every_clearable_section_points_back_at_the_field_that_clears_it` keeps the two directions from drifting. `RELATIONS.clear` is `None`, the same rule that keeps it out of `section_args`
- **Cleared fields are reported apart from replaced ones**, as `Cleared due on '...'` beside `Updated priority on '...'`. One list would say `Updated` of a field that was emptied, which is the opposite of what a caller needs to read back. The labels are the ones `set` already prints when it *writes* the field, so the two lines name a field the same way
- **Replacing and clearing one field in a single call is refused**, by `SetArgs::contested`. clap cannot express it, because the field arrives as `--clear`'s value rather than in its name, and answering by whichever was applied last is a silent answer to a contradictory call
- **Clearing the owner is `chown --clear <ticket>`, and `--clear` carries the ticket.** Owner has one writer and clearing it cannot introduce a second, so it lives on `chown`; but the ticket is `chown`'s *second* positional, and a bare flag would land it in the user's slot for the handler to read back out, which is hand-parsing what clap can state. The typed call is identical either way. `ChownArgs::target` returns the one shape the constraints allow, and an error rather than a panic for the combination they already refuse
- **Clearing the owner writes `NOT_SET`, not the git user.** `add` falls back to the git user because it is filing something new; an owner taken away says nobody owns this, and putting the person running the command there instead hands them a ticket they were giving up
- Clearing a field that is already unset writes the sentinel that is already there, so the whole-file comparison below reports no change and nothing is written. That is not a special case, and must not become one
- No-op detection compares the whole file before and after each edit, so a field set to the value it already holds is reported unchanged and nothing is written
- `find_ticket_file()` matches on the uuid, never the title. Duplicate titles are allowed, so a title scan can land on a different ticket than the one resolved: `mv <uuid-of-second>` used to move the first ticket sharing its title
- `write_then_replace()` is the only way a ticket file is written. Content first, rename second, so a failure leaves a correct ticket under a stale name rather than a half-written one
@@ -322,7 +336,7 @@ and this file is for what someone changing worklane's own code needs.
- The UUID tier applies from `MIN_ID_SEARCH` (4) characters up. Not 8: `ls` prints `SHORT_ID_WIDTH` (7) characters, so a longer minimum would drop the printed id out of the UUID tier and let any title quoting it win instead. Below the minimum the search is text, so `show 641` is a title search
- The filename tier earns its place by reaching the middle of a UUID, which the prefix tier cannot. It is also why a short UUID search still resolves under a longer minimum, just at the wrong precedence, so a test for the minimum needs a decoy title to be meaningful
- Ambiguous matches (multiple results) print options and exit(1)
- Never return empty strings for required fields — use `_Not set_` or `_None_` as defaults
- Never return empty strings for required fields — use the `NOT_SET` and `NONE` constants in `util.rs`, which are what `add` writes and what `--clear` puts back. `is_unknown_value` reads both, plus the two hyphenated spellings an earlier version wrote
### Git Workflow
- Commit format: `([ticketID]) [short description]`
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.17.2"
version = "0.18.0"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.17.2"
version = "0.18.0"
edition = "2024"
[dependencies]
+3 -2
View File
@@ -11,10 +11,10 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring |
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID |
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused |
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last |
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning. `mv` refuses to move a ticket blocked by one that is not done, unless `-f` |
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown` |
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to |
| `worklane check <ticket> [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal |
| `worklane uncheck <ticket> [criteria...]` | Unticks acceptance criteria, addressed the same way |
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
@@ -37,6 +37,7 @@ asks worklane for the one thing only the board knows:
worklane show <TAB> every ticket, id and title, done included
worklane mv <TAB> the same, then --status <TAB> for the four
worklane chown alice <TAB> the ticket, which is the second argument here
worklane chown --clear <TAB> the ticket, which the flag carries here
worklane relate x --blocked-by <TAB>
```
+15 -11
View File
@@ -16,11 +16,12 @@ which command owns which field. Read it too. This document is the judgement.
**Propose the whole set of edits, wait, then apply exactly what was approved.**
Every job here writes to many tickets at once, and no field can be cleared back to unset
yet, so a date written onto the wrong ticket can only be overwritten, never taken off. A wrong
edit to one ticket is a mistake; a wrong sweep is thirty of them with no undo. So a
proposal is a list, one line per intended edit, each naming the ticket and the command
that would make it:
Every job here writes to many tickets at once, and nothing on the board records what a
field held before you wrote to it. `--clear` puts a field back to unset, which is **not
back to what it held**, so a date written over another date is gone. A wrong edit to one
ticket is a mistake; a wrong sweep is thirty of them with no undo. So a proposal is a
list, one line per intended edit, each naming the ticket and the command that would make
it:
```
(1b78a24) priority 3 -> 1 worklane set 1b78a24 --priority 1
@@ -37,10 +38,10 @@ other way is editing the file by hand:
| Field | Writer |
|-------|--------|
| Priority, Due, Tags | `worklane set <ticket> --priority` / `--due` / `--tags` |
| Priority, Due, Tags | `worklane set <ticket> --priority` / `--due` / `--tags`, and `--clear <field>` to empty one |
| Relations | `worklane relate <ticket> --blocked-by` / `--regression-of` / `--relates-to` |
| Campaign membership | `worklane assign <campaign> <ticket>` |
| Owner | `worklane chown <user> <ticket>` |
| Owner | `worklane chown <user> <ticket>`, and `worklane chown --clear <ticket>` to empty it |
| Status | `worklane mv <ticket> --status <target>` |
**Never edit a ticket file directly.** The filename, the `Status` field and the directory
@@ -101,8 +102,9 @@ What to look for:
A value that is not a real calendar date in that exact form is refused before anything
is written, so a typo costs nothing. `2026-8-9` is refused too: the padding is part of
the format. What is still true is that a date, once written, **cannot be cleared**, only
replaced by another date, so a plan applied to the wrong ticket has no undo.
the format. A date can be taken off again with `worklane set <ticket> --clear due`. What
that cannot do is recover the date that was there before it, so a plan applied over
existing dates still has no undo.
Ask the system what today is rather than assuming it. A plan built on a guessed date is
wrong by however much the guess was wrong.
@@ -119,13 +121,15 @@ The rules a dating plan has to keep:
whole backlog produces a board where every ticket is late, which is the same as no
dates at all.
- **Do not date `done`.** It is finished; a date on it is noise in every listing.
- Leave the rest unset. An unset due date is honest about what has not been planned.
- Leave the rest unset. An unset due date is honest about what has not been planned, and
a date that turned out to be wrong is better cleared than left to read as a plan.
## Tags
`worklane set <ticket> --tags bug,cli` is the writer, and it **replaces the whole
field**. Restate every tag the ticket should keep, or the ones you left out are gone.
This is the single most destructive thing in this document.
This is the single most destructive thing in this document. `--clear tags` empties the
field on purpose, which is a different thing from emptying it by forgetting a tag.
Derive the vocabulary from the board rather than inventing one. Read the tickets, count
what is actually used, and show the count before proposing anything. What to report:
+21 -7
View File
@@ -124,21 +124,34 @@ worklane add \
Editing afterwards, on a ticket in any status:
```
worklane set 1b78a24 --priority 1 # replace a field
worklane set 1b78a24 --priority 1 # replace a field
worklane set 1b78a24 --title "A better title" # renames the file, keeps the uuid
worklane set 1b78a24 --clear due # take a value away again
worklane set 1b78a24 --clear tags --clear plan # as many fields as you like
worklane append 1b78a24 --acceptance "One more criterion"
worklane append 1b78a24 --description "What was learned since."
worklane chown alice 1b78a24 # hand the ticket to someone
worklane chown --clear 1b78a24 # hand it back to nobody
```
`set` replaces, `append` adds. Neither has `--owner` or `--status`: owner is `chown`'s
and status is `mv`'s, so each field has exactly one writer. A field set to the value it
already holds is reported unchanged and nothing is written.
`set` replaces, `append` adds, `--clear` empties. Neither `set` nor `append` has
`--owner` or `--status`: owner is `chown`'s and status is `mv`'s, so each field has
exactly one writer. A field set to the value it already holds is reported unchanged and
nothing is written, and so is a field cleared that was already unset.
**`--clear` takes the field as its value**, one of `due`, `tags`, `priority`,
`description`, `acceptance` or `plan`, and repeats. It writes back exactly what `add`
writes for a field it was never given: `_Not set_`, `_None_` for tags, and the section
placeholder. There is no `--clear title`, because a title addresses the ticket and names
its file. There is no `--clear owner` either: that is `chown --clear <ticket>`, which
takes the ticket in the flag since there is no user to give, and returns the field to
unset rather than to the git user. Replacing and clearing the same field in one call is
refused rather than resolved.
`chown` takes the **user first and the ticket second**, after Unix `chown`, which is the
one command here that does not start with the ticket. The user is free text and is
checked against nothing. Swap the two and the call fails, because the username has to
resolve as a ticket.
resolve as a ticket. `--clear` replaces both arguments with the ticket alone.
`worklane init` creates `.worklane/` with the four status directories and the campaigns
directory beside them, for a repo that has no board yet.
@@ -261,6 +274,7 @@ the candidates and exits 1 rather than guessing.
`worklane mv --status committed -- -leading-title`.
- A comment body of exactly `--` needs its own separator:
`worklane comment 1b78a24 -- --`.
- An empty value for a scalar is a usage error. Clearing a field back to unset is not
supported yet.
- An empty value for a scalar is a usage error, not a way to clear the field: use
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
the section either, and an all-blank one is refused with the `--clear` for it named.
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
+105 -18
View File
@@ -4,7 +4,7 @@ use std::sync::LazyLock;
use chrono::NaiveDate;
use crate::util::{PRIORITY_RANGE, RelationKind, Status, priority_legend};
use crate::util::{Clearable, PRIORITY_RANGE, RelationKind, Status, priority_legend};
/// clap wants a `&str` with a long enough lifetime, and the legend is built from
/// the same ramp the listing uses rather than spelled out a second time.
@@ -43,13 +43,31 @@ pub struct Cli {
/// Reject an empty value at parse time, so it lands as a usage error rather than a
/// runtime one.
///
/// An empty value looks like a way to clear a field, and clearing is not supported
/// yet. Refusing it keeps the gap visible and stops an accidentally empty variable
/// from silently blanking a field. Only the scalars use this: for the multi-line
/// sections an empty value is a paragraph break.
/// Two messages rather than one, because the arguments that use this fall into two
/// kinds. A search term or a title has no empty form at all, and that is all this says.
/// A field that *can* be emptied says so and names `--clear`, which is [`clearable`]
/// below: an accidentally empty variable must not blank a field silently, and somebody
/// typing an empty value on purpose is reaching for exactly the flag that does it.
///
/// Only the scalars use either one. For the multi-line sections an empty value is a
/// paragraph break.
fn non_empty(raw: &str) -> Result<String, String> {
if raw.trim().is_empty() {
return Err("value cannot be empty, and clearing a field is not supported yet".to_string());
return Err("value cannot be empty".to_string());
}
Ok(raw.to_string())
}
/// Reject an empty value on an argument whose field can be cleared, and say how.
///
/// The message names no command, because the arguments that use this belong to three:
/// `set --tags`, `set --due`, `add --due` and the `chown` user. `set` and `chown` both
/// take a `--clear`; `add` does not, and there a field is left unset by omitting the
/// flag, which is what the caller was reaching for anyway.
fn clearable(raw: &str) -> Result<String, String> {
if raw.trim().is_empty() {
return Err("value cannot be empty, use --clear to return a field to unset".to_string());
}
Ok(raw.to_string())
@@ -73,7 +91,7 @@ fn non_empty(raw: &str) -> Result<String, String> {
fn iso_date(raw: &str) -> Result<String, String> {
// An empty value keeps the message that explains why it is refused, since somebody
// typing it is reaching for a way to clear the field rather than mistyping a date.
non_empty(raw)?;
clearable(raw)?;
let bytes = raw.as_bytes();
let shaped = raw.len() == 10 && bytes[4] == b'-' && bytes[7] == b'-';
@@ -143,7 +161,7 @@ pub enum Command {
/// Record a relation from one ticket to another
Relate(RelateArgs),
/// Change the owner of a ticket
/// Change the owner of a ticket, or return it to unset
///
/// User first, ticket second, after Unix `chown`. That reverses the ticket-first
/// order `mv`, `comment` and `show` use, deliberately: the name borrows the Unix
@@ -154,14 +172,7 @@ pub enum Command {
/// username usually will not, so the call fails on its own. It is silently wrong
/// only when both arguments resolve, which needs a ticket whose title matches the
/// username.
Chown {
/// New owner. Free text, like `add --owner`, checked against nothing
#[arg(value_parser = non_empty)]
user: String,
/// Ticket UUID or title
ticket: String,
},
Chown(ChownArgs),
/// Open the board view
Tui {
@@ -361,7 +372,7 @@ pub struct AddArgs {
clap::ArgGroup::new("set_fields")
.required(true)
.multiple(true)
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority"])
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority", "clear"])
))]
pub struct SetArgs {
/// Ticket UUID or title
@@ -384,7 +395,7 @@ pub struct SetArgs {
pub plan: Vec<String>,
/// Replace the tags
#[arg(short = 'g', long, value_parser = non_empty)]
#[arg(short = 'g', long, value_parser = clearable)]
pub tags: Vec<String>,
/// Replace the due date (YYYY-MM-DD)
@@ -398,6 +409,82 @@ pub struct SetArgs {
/// Replace the priority, 1 (most urgent) to 5 (least)
#[arg(long, value_parser = priority_level)]
pub priority: Option<u8>,
/// Return a field to unset. Repeat the flag for more than one
///
/// The counterpart to the flag it names, and the only way to take a value away: an
/// empty value is a paragraph break for a section and a usage error for a scalar, so
/// neither can spell this. What goes back is what `add` writes for a field it was
/// never given.
///
/// No `title`, which addresses the ticket and names its file, and no `owner`, which
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
#[arg(long, value_name = "FIELD")]
pub clear: Vec<Clearable>,
}
impl SetArgs {
/// A field this call both replaces and clears, if there is one.
///
/// clap cannot express the conflict, because `--clear` carries the field as a value
/// rather than in the flag's own name. So it is checked once here and refused, rather
/// than resolved by whichever of the two happens to be applied last, which is a
/// silent answer to a contradictory call.
pub fn contested(&self) -> Option<Clearable> {
self.clear.iter().copied().find(|field| match field {
Clearable::Due => self.due.is_some(),
Clearable::Tags => !self.tags.is_empty(),
Clearable::Priority => self.priority.is_some(),
Clearable::Description => !self.description.is_empty(),
Clearable::Acceptance => !self.acceptance.is_empty(),
Clearable::Plan => !self.plan.is_empty(),
})
}
}
/// `chown` is the only writer of Owner, so clearing the field has to live here too, and
/// that is what shapes the arguments.
///
/// **`--clear` carries the ticket rather than being a bare flag.** The ticket is the
/// *second* positional, so `chown --clear 1b78a24` with a plain flag would land the
/// ticket in the user's slot, and reading it back out of there is hand-parsing what clap
/// can state outright. The typed call is the same either way; only who checks it differs.
///
/// The two forms are mutually exclusive, and each argument says so, so a call carrying
/// both is a usage error from clap rather than a decision made here.
#[derive(clap::Args)]
pub struct ChownArgs {
/// New owner. Free text, like `add --owner`, checked against nothing
#[arg(value_parser = clearable, required_unless_present = "clear", conflicts_with = "clear")]
pub user: Option<String>,
/// Ticket UUID or title
#[arg(required_unless_present = "clear", conflicts_with = "clear")]
pub ticket: Option<String>,
/// Return the owner to unset on this ticket, which is named here since there is no
/// user to name
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
pub clear: Option<String>,
}
impl ChownArgs {
/// The ticket the call names, and the owner to write on it, `None` being unset.
///
/// `None` for the pair is unreachable while the constraints above hold, and is an
/// error at the call site rather than a panic, so loosening one of them costs a
/// message instead of a crash.
pub fn target(&self) -> Option<(&str, Option<&str>)> {
match (
self.clear.as_deref(),
self.user.as_deref(),
self.ticket.as_deref(),
) {
(Some(ticket), None, None) => Some((ticket, None)),
(None, Some(user), Some(ticket)) => Some((ticket, Some(user))),
_ => None,
}
}
}
/// `append` only offers the sections that hold multiple lines, since appending to a
+27
View File
@@ -118,6 +118,11 @@ complete -c worklane \
# than by position.
complete -c worklane {ticket_flags} -x -a '(worklane ls --ids)'
# `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`
# has a `--clear` of its own that takes a field name, and clap already offers those.
complete -c worklane -n '__fish_seen_subcommand_from chown' -l clear -x -a '(worklane ls --ids)'
# clap emits the four for `mv --status`, which is an option, but the fish generator
# emits nothing for the possible values of a positional. So the one place a status is
# positional needs them listed, and the same goes for the shell below.
@@ -198,6 +203,28 @@ mod tests {
}
}
/// `chown --clear` takes a ticket, so it is completed like one, and only under
/// `chown`: `set --clear` is the same flag name carrying a field.
#[test]
fn chowns_clear_is_completed_with_tickets_and_sets_is_not() {
let script = fish_dynamic();
let rule = script
.lines()
.find(|line| line.starts_with("complete") && line.contains("-l clear"))
.expect("chown --clear has a rule of its own");
assert!(rule.contains("__fish_seen_subcommand_from chown"), "{rule}");
assert!(rule.contains("worklane ls --ids"), "{rule}");
let chown = command().find_subcommand("chown").expect("chown exists").clone();
assert!(
chown.get_arguments().any(|arg| arg.get_long() == Some("clear")),
"`chown` has no --clear for the rule to complete"
);
assert!(
!TICKET_FLAGS.contains(&"clear"),
"--clear in TICKET_FLAGS would offer tickets to `set --clear`, which takes a field"
);
}
/// The flags completed as tickets have to be `relate`'s actual flags, or the rule
/// completes an option nothing accepts.
#[test]
+69 -24
View File
@@ -6,7 +6,7 @@ use std::path::Path;
use crate::campaign::*;
use crate::command::{
AddArgs, AppendArgs, CampaignAddArgs, CheckArgs, LsArgs, RelateArgs, SetArgs,
AddArgs, AppendArgs, CampaignAddArgs, CheckArgs, ChownArgs, LsArgs, RelateArgs, SetArgs,
};
use crate::install;
use crate::util::*;
@@ -805,6 +805,19 @@ fn save_ticket(
Ok(())
}
/// Take an edit, or record that it changed nothing.
///
/// Each edit is compared against the content going in, so a field set to the value it
/// already holds is reported as unchanged rather than claimed as an update. That is also
/// what makes clearing an already unset field free: the sentinel it writes is the one
/// already there, so the strings match and nothing is written.
fn apply(content: &mut String, changed: &mut Vec<&'static str>, field: &'static str, next: String) {
if *content != next {
content.clone_from(&next);
changed.push(field);
}
}
fn report(fields: &[&str], title: &str, verb: &str) {
if fields.is_empty() {
println!("No changes to '{}'", color_text(title, Color::Green));
@@ -820,25 +833,24 @@ fn report(fields: &[&str], title: &str, verb: &str) {
}
pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
if let Some(field) = args.contested() {
let name = field.name();
return Err(anyhow!(
"--{name} and --clear {name} contradict each other, so nothing was written"
));
}
let worklane_dir = find_worklane_dir(start)?;
let (status, title, original) = resolve_ticket(&args.ticket, &worklane_dir)?;
let uuid = parse_ticket_field(&original, "ID");
let mut content = original.clone();
let mut changed: Vec<&str> = Vec::new();
// Each edit is compared against the content going in, so a field set to the value
// it already holds is reported as unchanged rather than claimed as an update.
let mut apply = |content: &mut String, field: &'static str, next: String| {
if *content != next {
content.clone_from(&next);
changed.push(field);
}
};
let mut cleared: Vec<&str> = Vec::new();
if let Some(new_title) = &args.title {
let next = set_title(&content, new_title)?;
apply(&mut content, "title", next);
apply(&mut content, &mut changed, "title", next);
}
for (section, values) in section_args(&args.description, &args.acceptance, &args.plan) {
@@ -849,32 +861,46 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
let items = section.normalise(values);
if items.is_empty() {
return Err(anyhow!(
"An empty {} is not a way to clear the section, and clearing is not supported yet",
section.label
"An empty value is a paragraph break, not a way to empty the {}: use --clear {}",
section.label,
section.clear.map_or("", Clearable::name)
));
}
let next = set_section_body(&content, section, &items)?;
apply(&mut content, section.label, next);
apply(&mut content, &mut changed, section.label, next);
}
if !args.tags.is_empty() {
let next = set_metadata_field(&content, "Tags", &args.tags.join(", "), &title)?;
apply(&mut content, "tags", next);
apply(&mut content, &mut changed, "tags", next);
}
if let Some(due) = &args.due {
let next = set_metadata_field(&content, "Due", due, &title)?;
apply(&mut content, "due", next);
apply(&mut content, &mut changed, "due", next);
}
if let Some(priority) = args.priority {
let next = set_metadata_field(&content, "Priority", &priority.to_string(), &title)?;
apply(&mut content, "priority", next);
apply(&mut content, &mut changed, "priority", next);
}
if changed.is_empty() {
report(&changed, &title, "Updated");
// Last, and into a list of their own. No field can be in both, since `contested`
// refused that above, so the order is free and the report is what decides it: a
// caller is told what was replaced and what was emptied in those words.
for field in &args.clear {
let next = match field.unset() {
Unset::Field { field, sentinel } => {
set_metadata_field(&content, field, sentinel, &title)?
}
Unset::Section(section) => clear_section_body(&content, section)?,
};
apply(&mut content, &mut cleared, field.label(), next);
}
if changed.is_empty() && cleared.is_empty() {
report(&[], &title, "Updated");
return Ok(());
}
@@ -882,7 +908,12 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
save_ticket(&worklane_dir, &status, &uuid, &title, renamed, &content)?;
let shown = args.title.clone().unwrap_or(title);
report(&changed, &shown, "Updated");
if !changed.is_empty() {
report(&changed, &shown, "Updated");
}
if !cleared.is_empty() {
report(&cleared, &shown, "Cleared");
}
Ok(())
}
@@ -895,13 +926,23 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
/// stay silent on the one it cannot, a ticket whose title is the username.
///
/// No-op detection compares the whole file, the way `set` does, so an owner set to the
/// value it already holds is reported unchanged and nothing is written.
pub fn cmd_chown(user: &str, ticket_id: &str, start: &Path) -> Result<()> {
/// value it already holds is reported unchanged and nothing is written. The same
/// comparison is what makes clearing an already unset owner free.
///
/// **Clearing writes [`NOT_SET`], not the git user.** `add` falls back to the git user
/// for a ticket it is filing, which is a default for something new; an owner taken away
/// says nobody owns this, and putting the person running the command there instead would
/// hand them a ticket they were giving up.
pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
let (ticket_id, user) = args.target().ok_or_else(|| {
anyhow!("chown takes a user and a ticket, or --clear with the ticket alone")
})?;
let worklane_dir = find_worklane_dir(start)?;
let (status, title, original) = resolve_ticket(ticket_id, &worklane_dir)?;
let uuid = parse_ticket_field(&original, "ID");
let content = set_metadata_field(&original, "Owner", user, &title)?;
let content = set_metadata_field(&original, "Owner", user.unwrap_or(NOT_SET), &title)?;
if content == original {
report(&[], &title, "Updated");
@@ -910,7 +951,11 @@ pub fn cmd_chown(user: &str, ticket_id: &str, start: &Path) -> Result<()> {
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
report(&["owner"], &title, "Updated");
let verb = match user {
Some(_) => "Updated",
None => "Cleared",
};
report(&["owner"], &title, verb);
Ok(())
}
+1 -1
View File
@@ -387,7 +387,7 @@ mod tests {
for required in [
"Propose the whole set of edits",
"replaces the whole\nfield", // `set --tags` is the destructive one
"cannot be cleared", // and a due date cannot be taken back
"not\nback to what it held", // and --clear is not an undo
"blocked by", // ordering constrains any dating plan
"worklane campaign ls",
"does not touch",
+1 -1
View File
@@ -63,7 +63,7 @@ fn main() -> Result<()> {
Some(Command::Set(args)) => cmd_set(&args, &start),
Some(Command::Append(args)) => cmd_append(&args, &start),
Some(Command::Relate(args)) => cmd_relate(&args, &start),
Some(Command::Chown { user, ticket }) => cmd_chown(&user, &ticket, &start),
Some(Command::Chown(args)) => cmd_chown(&args, &start),
Some(Command::Check(args)) => cmd_check(&args, true, &start),
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start),
Some(Command::Comment {
+209 -3
View File
@@ -936,9 +936,22 @@ fn render_metadata_table(lines: &[&str], colored: bool, campaign: &str) -> Strin
result
}
/// What a scalar metadata field holds when it holds nothing.
///
/// A constant rather than a literal per site, because it is now written on purpose:
/// clearing a field puts it back, and the value it goes back to has to be the one `add`
/// wrote, or a cleared ticket and a never-set one would differ in the file.
pub const NOT_SET: &str = "_Not set_";
/// The same for Tags, which is a list.
///
/// A list that holds nothing reads as none rather than as not set, which is the
/// distinction `add` already makes and clearing has to keep.
pub const NONE: &str = "_None_";
pub fn is_unknown_value(value: &str) -> bool {
let trimmed = value.trim();
trimmed == "_None_" || trimmed == "_Not set_" || trimmed == "-None-" || trimmed == "-Not set-"
trimmed == NONE || trimmed == NOT_SET || trimmed == "-None-" || trimmed == "-Not set-"
}
/// Replace `**bold**` with colour, or leave the line exactly as it is.
@@ -1017,7 +1030,7 @@ pub fn parse_ticket_field(content: &str, field: &str) -> String {
metadata_lines(content)
.find_map(|line| metadata_field_body(line).strip_prefix(&prefix))
.map(|value| value.trim().to_string())
.unwrap_or_else(|| "_Not set_".to_string())
.unwrap_or_else(|| NOT_SET.to_string())
}
fn is_status_line(line: &str) -> bool {
@@ -1371,6 +1384,12 @@ pub struct Section {
/// appending to an empty section replaces the placeholder rather than following it.
pub placeholder: &'static str,
pub kind: SectionKind,
/// The `--clear` value that empties this section, where `set` can reach it at all.
///
/// `None` for Relations, for the same reason it is absent from `section_args`: its
/// only writer is `relate`, so `set` has no way to fill it and no business emptying
/// it either.
pub clear: Option<Clearable>,
}
pub const DESCRIPTION: Section = Section {
@@ -1378,6 +1397,7 @@ pub const DESCRIPTION: Section = Section {
label: "description",
placeholder: "_No description provided._",
kind: SectionKind::Prose,
clear: Some(Clearable::Description),
};
pub const ACCEPTANCE: Section = Section {
@@ -1385,6 +1405,7 @@ pub const ACCEPTANCE: Section = Section {
label: "acceptance criteria",
placeholder: "_No acceptance criteria provided._",
kind: SectionKind::Checklist,
clear: Some(Clearable::Acceptance),
};
pub const PLAN: Section = Section {
@@ -1392,6 +1413,7 @@ pub const PLAN: Section = Section {
label: "implementation plan",
placeholder: "_No implementation plan provided._",
kind: SectionKind::Numbered,
clear: Some(Clearable::Plan),
};
/// The edges to other tickets, one per line.
@@ -1405,6 +1427,7 @@ pub const RELATIONS: Section = Section {
label: "relations",
placeholder: "_No relations._",
kind: SectionKind::Bullets,
clear: None,
};
impl Section {
@@ -1438,6 +1461,108 @@ impl Section {
}
}
/// A field `set --clear` can return to the state a new ticket is born in.
///
/// The names are the flags they undo, so `--clear due` reads as the opposite of
/// `--due`. Three fields a ticket carries are deliberately absent:
///
/// - **Title** has no unset state. It addresses the ticket, it names the file through
/// its slug, and `add` requires it, so there is nothing to go back to.
/// - **Owner** is `chown`'s, and clearing it through `set` would give the field a
/// second writer, which is the rule the missing `set --owner` exists to keep.
/// - **Status**, **Campaign** and the three stamps belong to `mv` and `assign` for the
/// same reason.
#[derive(Copy, Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum Clearable {
Due,
Tags,
Priority,
Description,
Acceptance,
Plan,
}
/// What clearing a field writes back.
pub enum Unset {
/// A metadata line, back to the sentinel `add` writes when the flag is omitted.
Field {
field: &'static str,
sentinel: &'static str,
},
/// A section body, back to the placeholder `add` writes for an empty one.
Section(&'static Section),
}
impl Clearable {
/// Every field that can be cleared.
///
/// `#[cfg(test)]` because nothing in the binary walks the list: clap emits the
/// values for `--clear` from the `ValueEnum` itself, so the only caller is the suite
/// that checks each one against the ticket it empties.
#[cfg(test)]
pub const ALL: [Clearable; 6] = [
Clearable::Due,
Clearable::Tags,
Clearable::Priority,
Clearable::Description,
Clearable::Acceptance,
Clearable::Plan,
];
/// What clearing the field amounts to.
///
/// The sentinels are [`NOT_SET`] and [`NONE`] rather than strings written out here,
/// so a cleared field is byte-identical to one `add` left alone. That is the whole
/// promise of the command: a ticket that has been cleared and one that was never
/// given the field read the same.
pub fn unset(self) -> Unset {
match self {
Clearable::Due => Unset::Field {
field: "Due",
sentinel: NOT_SET,
},
Clearable::Tags => Unset::Field {
field: "Tags",
sentinel: NONE,
},
Clearable::Priority => Unset::Field {
field: "Priority",
sentinel: NOT_SET,
},
Clearable::Description => Unset::Section(&DESCRIPTION),
Clearable::Acceptance => Unset::Section(&ACCEPTANCE),
Clearable::Plan => Unset::Section(&PLAN),
}
}
/// The value the flag takes, as clap spells it.
///
/// Written out rather than read off `to_possible_value`, because it is used in error
/// messages that tell a caller what to type and a `&'static str` is what those want.
/// `the_clear_values_are_the_names_clap_accepts` keeps the two in step.
pub fn name(self) -> &'static str {
match self {
Clearable::Due => "due",
Clearable::Tags => "tags",
Clearable::Priority => "priority",
Clearable::Description => "description",
Clearable::Acceptance => "acceptance",
Clearable::Plan => "plan",
}
}
/// How the change is named in output.
///
/// The label `set` already prints when it *writes* the field, so a cleared field is
/// named the way a replaced one is rather than in the flag's own spelling.
pub fn label(self) -> &'static str {
match self.unset() {
Unset::Field { .. } => self.name(),
Unset::Section(section) => section.label,
}
}
}
/// Whether the line opens with `N. `, the shape a numbered step is stored in.
fn is_numbered_item(line: &str) -> bool {
let digits = line.chars().take_while(|c| c.is_ascii_digit()).count();
@@ -1481,12 +1606,32 @@ fn join_lines(lines: &[String]) -> String {
/// Replace a section's body with `items`, leaving every line outside it untouched.
pub fn set_section_body(content: &str, section: &Section, items: &[String]) -> Result<String> {
replace_section_body(content, section, section.render(items, 1))
}
/// Return a section to the placeholder `add` writes for an empty one.
///
/// Not [`set_section_body`] with the placeholder as its one item: the placeholder is a
/// line of the format rather than content, and `render` would dress it as `- [ ] _No
/// acceptance criteria provided._` in every section but the description. It is the same
/// line `append` already treats as no content, so a cleared section can be appended to
/// without the placeholder being left above what follows it.
pub fn clear_section_body(content: &str, section: &Section) -> Result<String> {
replace_section_body(content, section, vec![section.placeholder.to_string()])
}
/// The line surgery both of the above are, given a body that is already rendered.
fn replace_section_body(
content: &str,
section: &Section,
body_lines: Vec<String>,
) -> Result<String> {
let lines: Vec<&str> = content.lines().collect();
let body = section_body(&lines, section.heading)
.ok_or_else(|| anyhow!("Ticket has no {} section", section.label))?;
let mut out: Vec<String> = lines[..body.start].iter().map(|l| l.to_string()).collect();
out.extend(section.render(items, 1));
out.extend(body_lines);
// One blank line before whatever section follows, matching how `add` writes it.
if body.end < lines.len() {
out.push(String::new());
@@ -3791,6 +3936,67 @@ mod tests {
assert!(parse_relation("- blocked by").unwrap_err().to_string().contains("no target"));
}
/// The two directions of the pairing have to agree, or `--clear acceptance` would
/// empty one section while the error message about an empty value named another.
#[test]
fn every_clearable_section_points_back_at_the_field_that_clears_it() {
for field in Clearable::ALL {
if let Unset::Section(section) = field.unset() {
assert_eq!(
section.clear,
Some(field),
"{} does not point back at --clear {}",
section.heading,
field.name()
);
}
}
assert_eq!(RELATIONS.clear, None, "set must not be able to empty Relations");
}
/// The names are written out for the error messages, so this is what keeps them the
/// names clap actually accepts.
#[test]
fn the_clear_values_are_the_names_clap_accepts() {
for field in Clearable::ALL {
let possible = clap::ValueEnum::to_possible_value(&field).expect("not hidden");
assert_eq!(possible.get_name(), field.name());
}
}
/// The sentinel a cleared field goes back to is the one `add` writes for a field it
/// was never given, which is the whole promise of the flag.
#[test]
fn a_cleared_scalar_holds_the_sentinel_add_writes() {
for field in Clearable::ALL {
let Unset::Field { field: name, sentinel } = field.unset() else {
continue;
};
let expected = match name {
"Tags" => NONE,
_ => NOT_SET,
};
assert_eq!(sentinel, expected, "{name}");
assert!(is_unknown_value(sentinel), "{name} clears to something readable as set");
}
}
/// The placeholder goes in as a line of the format, not as an item: dressed by
/// `render` it would read `- [ ] _No acceptance criteria provided._`.
#[test]
fn clearing_a_section_writes_the_bare_placeholder() {
let content = "# T\n\n## Acceptance Criteria\n- [x] Done\n- [ ] Not\n\n## Metadata\n\n- **ID**: x\n";
let cleared = clear_section_body(content, &ACCEPTANCE).unwrap();
assert!(
cleared.contains(&format!("## Acceptance Criteria\n{}\n", ACCEPTANCE.placeholder)),
"{cleared}"
);
// Everything outside the section is where it was.
assert!(cleared.contains("- **ID**: x"), "{cleared}");
// And a second clear is the same string, which is what makes the no-op free.
assert_eq!(clear_section_body(&cleared, &ACCEPTANCE).unwrap(), cleared);
}
#[test]
fn the_placeholder_is_no_relations_rather_than_a_bad_line() {
let content = format!(
+5 -3
View File
@@ -530,9 +530,10 @@ fn add_refuses_an_unpadded_due_date_rather_than_padding_it() {
}
/// An empty value keeps the message about clearing, since that is what somebody typing
/// it is reaching for.
/// it is reaching for. On `add` the answer is to omit the flag, but the message names
/// `--clear` because the same parser guards `set --due`, where that is the answer.
#[test]
fn an_empty_due_date_says_clearing_is_not_supported() {
fn an_empty_due_date_points_at_clear() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
@@ -549,7 +550,8 @@ fn an_empty_due_date_says_clearing_is_not_supported() {
)
.to_string();
assert!(stderr.contains("clearing a field is not supported"), "{stderr}");
assert!(stderr.contains("use --clear"), "{stderr}");
assert!(!stderr.contains("not supported"), "{stderr}");
}
fn read_only_ticket(dir: &Path) -> String {
+88 -2
View File
@@ -213,7 +213,8 @@ fn chown_refuses_a_swapped_call() {
assert_eq!(ticket(&worklane), before);
}
/// An empty user looks like a way to clear the field, and clearing is not supported.
/// An empty user is still a usage error, and now points at the flag that does take the
/// owner away.
#[test]
fn chown_refuses_an_empty_user_as_a_usage_error() {
let temp = TempDir::new().unwrap();
@@ -223,11 +224,96 @@ fn chown_refuses_an_empty_user_as_a_usage_error() {
let out = run(&temp, &["chown", "", UUID]);
assert_eq!(out.status.code(), Some(2));
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("use --clear"), "{stderr:?}");
assert!(!stderr.contains("not supported"), "{stderr:?}");
assert_eq!(ticket(&worklane), before);
}
/// The owner goes back to the sentinel, not to the git user: an owner taken away says
/// nobody owns this.
#[test]
fn chown_clear_returns_the_owner_to_unset() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["chown", "--clear", UUID]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert!(
String::from_utf8_lossy(&out.stderr).contains("clearing a field is not supported"),
String::from_utf8_lossy(&out.stdout).contains("Cleared owner"),
"{:?}",
String::from_utf8_lossy(&out.stdout)
);
let content = ticket(&worklane);
assert!(content.contains("- **Owner**: _Not set_"), "{content}");
// Nothing else on the way past.
assert!(content.contains("- **Status**: backlog"), "{content}");
}
/// The ticket is still resolved the three usual ways when it arrives in the flag.
#[test]
fn chown_clear_resolves_the_ticket_it_is_given() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["chown", "--clear", "Original"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert!(ticket(&worklane).contains("- **Owner**: _Not set_"));
}
#[test]
fn chown_clear_on_an_unowned_ticket_is_no_change() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
run(&temp, &["chown", "--clear", UUID]);
let before = ticket(&worklane);
let out = run(&temp, &["chown", "--clear", UUID]);
assert!(out.status.success());
assert!(
String::from_utf8_lossy(&out.stdout).contains("No changes"),
"{:?}",
String::from_utf8_lossy(&out.stdout)
);
assert_eq!(ticket(&worklane), before, "the file was rewritten anyway");
}
/// Setting an owner and clearing it are the two forms of the command, and clap keeps
/// them apart rather than the handler picking one.
#[test]
fn chown_refuses_a_user_and_a_clear_together() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
for args in [
vec!["chown", "bob", "--clear", UUID],
vec!["chown", "bob", UUID, "--clear", UUID],
] {
let out = run(&temp, &args);
assert_eq!(out.status.code(), Some(2), "{args:?} was accepted");
assert!(
String::from_utf8_lossy(&out.stderr).contains("cannot be used with"),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
}
// And a bare --clear still needs the ticket it is meant to name.
let out = run(&temp, &["chown", "--clear"]);
assert_eq!(out.status.code(), Some(2));
assert!(
String::from_utf8_lossy(&out.stderr).contains("a value is required"),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
assert_eq!(ticket(&worklane), before);
}
+246 -14
View File
@@ -190,7 +190,11 @@ fn set_reports_only_the_fields_that_changed() {
assert!(!stdout.contains("due"), "{stdout:?}");
}
/// An empty scalar looks like a way to clear a field, and clearing is not supported.
/// An empty scalar is still a usage error, and the message now points at the flag that
/// does clear a field, so the two do not contradict each other.
///
/// `--title` is the exception, and says only that the value cannot be empty: a title has
/// no unset state to return to, so there is nothing to point at.
#[test]
fn set_refuses_an_empty_scalar_as_a_usage_error() {
let temp = TempDir::new().unwrap();
@@ -198,12 +202,227 @@ fn set_refuses_an_empty_scalar_as_a_usage_error() {
create_ticket(&worklane);
let before = ticket(&worklane);
for flag in ["--title", "--due", "--tags"] {
for (flag, expected) in [
("--title", "value cannot be empty"),
("--due", "use --clear"),
("--tags", "use --clear"),
] {
let out = run(&temp, &["set", UUID, flag, ""]);
assert_eq!(out.status.code(), Some(2), "{flag} was accepted");
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains(expected), "{flag}: {stderr:?}");
assert!(
String::from_utf8_lossy(&out.stderr).contains("clearing a field is not supported"),
"{flag}: {:?}",
!stderr.contains("not supported"),
"{flag} still says clearing is unsupported: {stderr:?}"
);
}
assert_eq!(ticket(&worklane), before);
}
/// An empty value is a paragraph break for a section, so it cannot also mean empty the
/// section. The error names the flag that does, per section.
#[test]
fn set_refuses_an_empty_section_and_names_the_clear_for_it() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
for (flag, expected) in [
("--description", "--clear description"),
("--acceptance", "--clear acceptance"),
("--plan", "--clear plan"),
] {
let out = run(&temp, &["set", UUID, flag, ""]);
assert_eq!(out.status.code(), Some(1), "{flag} was accepted");
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains(expected), "{flag}: {stderr:?}");
}
assert_eq!(ticket(&worklane), before);
}
/// Every field `--clear` reaches, in one call, back to what a ticket is born with.
#[test]
fn clear_returns_every_field_it_reaches_to_unset() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(
&temp,
&[
"set", UUID,
"--clear", "due",
"--clear", "tags",
"--clear", "priority",
"--clear", "description",
"--clear", "acceptance",
"--clear", "plan",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let content = ticket(&worklane);
assert!(content.contains("- **Due**: _Not set_"), "{content}");
assert!(content.contains("- **Tags**: _None_"), "{content}");
assert!(content.contains("- **Priority**: _Not set_"), "{content}");
assert!(
content.contains("## Description\n_No description provided._\n"),
"{content}"
);
assert!(
content.contains("## Acceptance Criteria\n_No acceptance criteria provided._\n"),
"{content}"
);
assert!(
content.contains("## Implementation Plan\n_No implementation plan provided._\n"),
"{content}"
);
// The placeholder goes in bare, not dressed as an item of the section it replaces.
assert!(!content.contains("- [ ] _No"), "{content}");
assert!(!content.contains("1. _No"), "{content}");
// What --clear cannot reach is untouched, the handwritten section included.
assert!(content.starts_with("# Original title\n"), "{content}");
assert!(content.contains("- **Owner**: alice"), "{content}");
assert!(content.contains("- **Status**: backlog"), "{content}");
assert!(
content.contains("## Notes\nA handwritten note the tool knows nothing about.\n"),
"{content}"
);
}
/// A cleared ticket and one that was never given the field have to read the same, or
/// clearing would be its own third state.
#[test]
fn a_cleared_ticket_reads_like_one_filed_without_the_fields() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
run(&temp, &["add", "--title", "Bare"]);
run(
&temp,
&[
"add",
"--title", "Full",
"--description", "A body.",
"--acceptance", "One criterion",
"--plan", "One step",
"--tags", "alpha,beta",
"--due", "2026-09-01",
"--priority", "2",
],
);
let full = added(&worklane, "full");
let out = run(
&temp,
&[
"set", &full.0,
"--clear", "due",
"--clear", "tags",
"--clear", "priority",
"--clear", "description",
"--clear", "acceptance",
"--clear", "plan",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let cleared = comparable(&fs::read_to_string(&full.1).unwrap());
let bare = comparable(&fs::read_to_string(&added(&worklane, "bare").1).unwrap());
assert_eq!(cleared, bare);
}
/// The uuid and the file of the one ticket whose slug matches, as `add` wrote it.
fn added(worklane: &Path, slug: &str) -> (String, PathBuf) {
let entry = fs::read_dir(worklane.join("backlog"))
.unwrap()
.filter_map(|e| e.ok())
.find(|e| {
e.file_name()
.to_string_lossy()
.ends_with(&format!("_{slug}.md"))
})
.unwrap_or_else(|| panic!("no ticket slugged {slug}"));
let name = entry.file_name().into_string().unwrap();
let uuid = name.split('_').next().unwrap().to_string();
(uuid, entry.path())
}
/// A ticket without the three lines that are different by definition: its title, its
/// uuid and the moment it was filed.
fn comparable(content: &str) -> String {
content
.lines()
.filter(|line| {
!line.starts_with("# ")
&& !line.contains("**ID**:")
&& !line.contains("**Created At**:")
})
.collect::<Vec<_>>()
.join("\n")
}
/// Nothing to take away is not a rewrite, per the same whole-file comparison a
/// replacement uses.
#[test]
fn clearing_a_field_that_is_already_unset_is_no_change() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
run(&temp, &["set", UUID, "--clear", "due", "--clear", "tags"]);
let before = ticket(&worklane);
let out = run(&temp, &["set", UUID, "--clear", "due", "--clear", "tags"]);
assert!(out.status.success());
assert!(
String::from_utf8_lossy(&out.stdout).contains("No changes"),
"{:?}",
String::from_utf8_lossy(&out.stdout)
);
assert_eq!(ticket(&worklane), before, "the file was rewritten anyway");
}
/// Replaced and emptied are reported in those words, since a caller doing both in one
/// call cannot tell which happened to which field otherwise.
#[test]
fn clear_is_reported_apart_from_a_replacement() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["set", UUID, "--priority", "1", "--clear", "due"]);
assert!(out.status.success());
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.contains("Updated priority on 'Original title'"), "{stdout:?}");
assert!(stdout.contains("Cleared due on 'Original title'"), "{stdout:?}");
}
/// Replacing and clearing one field in a single call is a contradiction, and answering
/// it by whichever was applied last would be a silent answer.
#[test]
fn clearing_and_replacing_the_same_field_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
for (flag, value, field) in [
("--due", "2026-12-31", "due"),
("--tags", "beta", "tags"),
("--priority", "1", "priority"),
("--acceptance", "A criterion", "acceptance"),
] {
let out = run(&temp, &["set", UUID, flag, value, "--clear", field]);
assert_eq!(out.status.code(), Some(1), "{flag} with --clear {field} was accepted");
assert!(
String::from_utf8_lossy(&out.stderr).contains("contradict each other"),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
}
@@ -211,25 +430,38 @@ fn set_refuses_an_empty_scalar_as_a_usage_error() {
assert_eq!(ticket(&worklane), before);
}
/// An empty value is a paragraph break for a section, so an all-blank one is a
/// clearing attempt rather than a break.
/// The fields no writer of `set` can reach are not reachable through `--clear` either,
/// and an unknown one is a usage error listing what is.
#[test]
fn set_refuses_to_clear_a_section() {
fn clear_refuses_a_field_it_does_not_own() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
let out = run(&temp, &["set", UUID, "--description", ""]);
assert_eq!(out.status.code(), Some(1));
assert!(
String::from_utf8_lossy(&out.stderr).contains("clearing is not supported"),
"{:?}",
String::from_utf8_lossy(&out.stderr)
);
for field in ["owner", "title", "status", "campaign", "relations", "nonsense"] {
let out = run(&temp, &["set", UUID, "--clear", field]);
assert_eq!(out.status.code(), Some(2), "--clear {field} was accepted");
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("possible values"), "{field}: {stderr:?}");
}
assert_eq!(ticket(&worklane), before);
}
/// `--clear` on its own satisfies the at-least-one-field rule, since it is a field
/// being written like any other.
#[test]
fn clear_alone_is_enough_of_a_field() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["set", UUID, "--clear", "due"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert!(ticket(&worklane).contains("- **Due**: _Not set_"));
}
/// A bare `set <ticket>` would otherwise be a silent no-op.
#[test]
fn set_requires_at_least_one_field() {