Compare commits

...
7 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 00a64adca8 (03bdc76) Draw a symmetric relation once, and refuse the mirror, and bump to 0.32.1
`relate` refused a relation the ticket already held but never looked at what
the target held, so both ends of a `relates to` could store a line. `show` then
drew the same neighbour twice under the same label, since `RelatesTo` maps to
itself in `inverse_label`: one row from the stored line and one derived from the
far ticket's mirror of it, indistinguishable. Live on this board, where 8556048
and 8c8a520 each stored the other.

Both ends of the fix, because they do different jobs. `relation_rows` drops a
derived row that reads exactly like a stored one, which repairs the boards that
already hold both directions without an edit. `cmd_relate` refuses to store the
mirror in the first place, reporting no change since the edge is already
recorded at the far end, which stops it recurring. Neither alone closes it.

The dedupe keys on the **label** and the target, not the kind and the target.
Two tickets each blocking the other is two facts and the block has to say both,
`blocked by` from this end and `blocks` from the other; keying on the kind would
fold them into one row and lose half of what the ticket says. Only a symmetric
kind can collide with its own stored line, and `RelationKind::is_symmetric`
derives that from `label() == inverse_label()` rather than naming `RelatesTo`,
so a kind added later answers by construction. The same gate is what keeps the
refusal off a cycle: a target holding `blocked by <this>` is not a duplicate.

The stored row is the survivor, not the derived one, because it is the line
`relate --clear` can address. The consequence is worth knowing and is written
down: with both ends holding a line, clearing one leaves the other's, which then
draws as the derived row. Correct, since the far end still asserts the relation.

4179958 decided that `relates to` is symmetric and "written once, not onto both
files". Nothing enforced it until now.

The board's own data is left alone. 8556048 and 8c8a520 still both store the
line and the block now draws it once, which is what the criterion asked for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 12:41:49 +02:00
Ansho ReiandClaude Opus 5 0f0767ac00 (8556048) Take a relation off with relate --clear, and bump to 0.32.0
`relate` only added. A `--blocked-by` pointed at the wrong ticket was on that
ticket forever, refusing every move it made until the target was done or `-f`
was passed again, and a target that was deleted did not clean up either: the
board carried a dead edge that nothing could clear and every later read of the
ticket paid for.

`--clear <kind> <target>` takes one off. It is on `relate` rather than on `set`
for the reason `RELATIONS` is out of `section_args`: a relation names a target
that has to be resolved first, so one writer owns both directions, the way
`chown` owns setting an owner and clearing one. It names the target and not
just the kind, because a ticket can hold several relations of one kind and
emptying all of them is not what anybody is asking for. That is also why it is
not spelled the way `set --clear` is, which names a field and empties it whole.

Both spellings of the kind are taken, `blocked-by` from the flag and
`blocked by` from the label: both are in front of the reader, the flag being
what recorded the relation and the label what `show` prints and the file
stores, so refusing the printed form would trap anyone clearing a row they had
just read. `RelationKind::flag` is a match rather than a `replace` on the
label, so the flag, the `--clear` value and the completion list cannot drift.

`find_relation` searches the ticket's own edges by id prefix before it searches
the board, and that order is the feature rather than an optimisation: no search
of the board reaches a target whose ticket is gone, so the stored-target tier
is the only thing that can clear a dangling edge, which is the case most likely
to need clearing. Two stored targets under one prefix name the candidates
instead of guessing, as an ambiguous ticket search already does.

An edge the ticket does not hold reports no change, and a target naming nothing
at all is an error. The two are different facts: the first is the state the
caller asked for, and the second is a typo that a no-op would swallow. The
resolver's own reason is carried through, so an ambiguous search says it is
ambiguous rather than being reported as nothing found.

Recording and clearing the same relation in one call is refused, and the check
runs on what was *asked* for and not on what would be written. A relation
already in the file is not among the additions, so comparing against those
would have let `--blocked-by X --clear blocked-by X` quietly remove it.

Removals rewrite the section from what is left and additions are appended to
that, in that order and in two passes: a call with no `--clear` then takes
exactly the path it always took. The last edge leaves the placeholder, which is
the line `append` treats as no content, so the next `relate` replaces it rather
than writing underneath it.

The two values are one flag, so clap cannot type them apart. `num_args = 2` is
per occurrence, which makes an odd number a usage error and every chunk a full
pair, and `cleared` parses the kind before the ticket is resolved. Nothing is
logged, in either direction, since `relate` never has: a log recording only the
destructive half would read as though the additions had never happened.

`chowns_clear_is_completed_with_tickets_and_sets_is_not` found the first rule
carrying `-l clear` and there are now three, on three commands, each taking
something different. It is `each_clear_flag_is_completed_for_its_own_command`,
scoped per command, and `relate --clear` offers the kinds rather than a board
listing, since tickets where the kind goes would be candidates it refuses.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 12:13:37 +02:00
Ansho ReiandClaude Opus 5 7994d98913 (76d10d7) Strike through a relation to a discarded ticket, and bump to 0.31.5
The relations block marked a target `○ ◐ ●` or `?`, and none of those can say
the target was discarded: the status mark is one cell in a column of five
states, and `●` in grey against `●` in green is a colour a pipe does not get.
A row pointing at abandoned work therefore read as a live dependency, which is
exactly what it is not.

The row is struck through instead, the whole of it, gutter and padding
included, so the line runs unbroken from the label to the end of the title.
The relation stays recorded, for completeness and for the case the target is
moved back out of discarded, and reads at a glance as no longer standing for
anything. The mark column is untouched: 451fb83 already gave a discarded
target the full circle of done in the grey of the untouched pile, and the
strike is additive on top of that.

`Cell` learns a modifier, the first style on it that is not a colour. Same
trick as the palette, one step further: `Modifier::ansi()` is SGR 9 and
`From<Modifier> for ratatui::style::Modifier` is `CROSSED_OUT`, so a style
that exists for one renderer and not the other is a compile error. Bold stays
out of it, because bold rides inside `Color::Magenta.ansi()` and `span_from`
adds it back from the colour alone; a second modifier goes beside this one.

`paint_cell` opens the modifier ahead of the colour and closes both with one
reset, which is why the reset is now a constant the two writers share rather
than a literal in `paint`. `span_from` takes the modifier too and has no early
return for the uncoloured case any more: a struck plain run is a styled span
with no foreground. `Cell::struck` is a builder, because the strike is decided
a whole row at a time by the layout that already chose the colours.

`Body::push_cell` merges on the whole style rather than the colour alone.
Nothing outside the relations block carries a modifier today, and a merge
keyed on the colour would silently strike a plain run through the moment one
did.

The strike is under the same flag every other escape is, so a piped `show`
carries none of it. That is the bargain committed and reviewing already take
for being told apart by colour alone, and `assets/SKILL.md` says so outright
rather than leaving an agent to infer that a plain-looking row may point at
abandoned work.

Tests are paired both ways, and both halves are load bearing: a renderer that
struck nothing fails the presence, and one that struck every row fails the
absence. `the_status_marks_are_pinned` had never listed discarded, so it does.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 11:53:45 +02:00
Ansho ReiandClaude Opus 5 d1a0f0ee27 (2a83bd4) Frame the tag-filtered board with the tag's annotation, and bump to 0.31.4
A board filtered to a tag now says which tag, the way a board filtered to a
campaign says which campaign. The frame slot above the columns is shared, not
doubled: one filter is on at a time, per `Filter`, so the row and the geometry
`Chrome` computes stay as they are and only what is drawn into them changes.

`FrameContent` is what the two are told apart into, and `frame_content` is the
one place they are told apart at all. Everything below it is the campaign
frame's: the borders, the colour, `q board`, the page indicator, the scroll,
the focus and `enter`. A second match on the filter under there is how the two
frames would come to behave differently in a way nobody decided.

The tag goes on the top border as `#tag`, in the colour a card draws it in,
because `~v1` against `#bug` is what says at a glance which filter emptied the
columns. How many tickets carry it goes on the bottom right where the standing
goes, counted off every column, drawn or not. The annotation fills the prose
rows, wrapped and scrolled the way ebad2fa made the description.

An undeclared tag draws `NO_ANNOTATION` in grey rather than a blank row, which
is also the frame saying the word was never agreed on. The vocabulary file's
own placeholder and not the description section's, so the frame and `tags.md`
say the same thing about the same tag.

Nothing in the geometry is named after campaigns any more. `Chrome::campaign`
is `Chrome::frame`, `CAMPAIGN_ROW` is `FRAME_ROW`, and `Chrome::campaign_rows`
is `Chrome::frame_rows` — which collided with the free `frame_rows` that lays
out the whole screen, so that one is `screen_rows`.

`y` on a tag frame copies the tag, since a tag is its own id and the hash the
border draws is not part of what `--tag` matches. The footer's tag span and its
`q board` slot are gone: 0fd1ddc put them there for want of a frame to say it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 11:41:35 +02:00
Ansho ReiandClaude Opus 5 45b513bdce (2733b10) Colour the history block, and indent a comment's body deeper, and bump to 0.31.3
The block shipped with three painted things: the heading, the kind label
and the actor with its timestamp as one cyan span. Every value in it was
plain, so a status entry drew two status names in no colour while the
same names are orange in the metadata table three lines above, and a tags
entry drew its tags without the slots every other view gives them.

The kind label is now grey, as chrome that names a row. It was orange,
which means Status everywhere else, so an `owner` or `tags` label claimed
a meaning belonging to the value beside it. `From` on a comment's author
line goes grey for the same reason.

Each value takes the meaning its field carries in the metadata table:
status orange, tags through the same `tag_cells` the Tags field uses, a
campaign codename through `tag_color` bare the way `Codename` is, an
owner plain, and `_Not set_`, `_None_` and `_missing_` grey. The
separator is a constant beside `change`, with `split_change` next to it,
so the writer and the reader cannot disagree about what divides the two
halves.

The actor is drawn through `tag_color`, so one writer is one colour in
every entry it wrote, and cyan goes back to meaning the timestamp alone.

A comment's body moves to four spaces and the author line stays at column
0, so an indented line is somebody's own words and a line of values at
column 0 is the tool reporting itself.

The padding is still measured on the unpainted label, now pinned with the
alignment test running both ways.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-25 10:54:36 +02:00
Ansho Rei ab337ca7f8 (1f1b321) Record a move's reason in its history entry, and bump to 0.31.2 2026-08-25 10:38:04 +02:00
Ansho Rei 60b43a682e (a136d13) Draw the discarded column behind a three-state visibility rotation, and bump to 0.31.1 2026-08-25 03:33:38 +02:00
15 changed files with 2909 additions and 507 deletions
+47 -19
View File
@@ -28,7 +28,7 @@
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Discarded On`, `Campaign`, `Status`. The last five are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
- The four stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Not the history log either: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
- **`Discarded` is last in `Status::ALL`, and that placement is what makes the stamp rule fall out right.** Nothing sits after it, so a discard clears nothing: a ticket abandoned from reviewing keeps `Committed On` and `Submitted On`, and the file still says how far it got before it was dropped. It also makes every move out of discarded a backward move, so un-discarding needs `-f` without a rule of its own. `Discarded On` is its stamp, and `Completed On` stays untouched, because a discarded ticket was never done
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done and discarded by their stamp descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` (or `Status::FLOW`) rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done and discarded by their stamp descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
- Format: `**Field Name**: value`
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
- A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign
@@ -37,7 +37,7 @@
## Status Workflow
`backlog` → `committed` → `reviewing` → `done`, and `discarded` off to one side
- **`Status::ALL` and `Status::FLOW` are two different questions, and picking the wrong one is the mistake to watch for here.** `ALL` is every directory that can hold a ticket, which is what the tree walkers want: `status_dirs`, `RelationIndex::load`, `collect_ticket_items`' callers, `cmd_tags`, `list_ids`, the resolver and the digest all have to see a discarded ticket or it becomes unaddressable. `FLOW` is the four stages work moves through, which is what the *board* draws: a discarded column on screen is a136d13's ticket, not a side effect of the status existing, and keeping it out of `FLOW` is also what keeps done the last drawn column so hiding it stays a prefix
- **`Status::ALL` is every directory that can hold a ticket, and that is the only list left.** It is what the tree walkers want: `status_dirs`, `RelationIndex::load`, `collect_ticket_items`' callers, `cmd_tags`, `list_ids`, the resolver, the digest and the board's own columns all have to see a discarded ticket or it becomes unaddressable. There was a second list, `FLOW`, the four stages work moves through, which used to be what the board drew from; a136d13 drew the discarded column behind a visibility prefix instead, which took FLOW's last reader away, so it is gone. Hiding is decided by `Visibility`, never by leaving a status out of the walk: what is drawn changes, what is read does not. The prefix property survives on the order alone — done and discarded are deliberately the last two in `ALL` — and `the_terminal_columns_are_last_in_the_order_drawn` pins it
- **Discarding is not a stage, so the walk rules do not apply to entering it.** `mv --status discarded` is allowed from any status with no `-f`, because a backlog ticket that turns out to be a duplicate should not have to be walked through committed and reviewing to be abandoned. Leaving it needs `-f`, which comes free from the backward-move rule
- **The two dependency guards look opposite ways, and `mv` picks by direction.** `check_blockers` asks what this ticket waits on and gates work moves; `check_dependents` asks who waits on this ticket and gates the discard. A ticket being abandoned owes nothing to its own blockers, but the tickets blocked *by* it recorded a dependency on work that is about to be declared never-happening, so those plans get a look before the ground moves. `-f` is the caller saying they looked. Both name every offender rather than the first, and both skip targets that are themselves done or discarded
- **Discarded satisfies a block the way done does.** There is nothing left to wait for, and whether the dependent still makes sense was asked at discard time by the guard above, which is what makes it safe to pass here rather than a second place to re-ask
@@ -171,9 +171,21 @@ and this file is for what someone changing worklane's own code needs.
### Relating Tickets
- **The Relations section is `relate`'s alone.** `RELATIONS` is in the section table but deliberately out of `section_args`, so `set` and `append` cannot reach it: a relation names a target that has to be resolved to a uuid first, and a prose flag would let an unresolvable line into the one section that is read back by machine. Same rule as Owner and Status, one field one writer
- **`relate --clear <kind> <target>` is the removal, and it is on `relate` rather than on `set`** for the same reason the section is absent from `section_args`: one writer owns both directions, the way `chown` owns setting an owner and clearing one. It names the target and not just the kind, because a ticket can hold several relations of one kind and emptying all of them is not what anybody is asking for. That is also why it is not spelled like `set --clear`, which names a field and empties the whole of it
- **The two values are one flag, so clap cannot type them apart.** `num_args = 2` is per occurrence, which is what makes an odd number a usage error and every chunk a full pair; `RelateArgs::cleared` splits the pairs and parses the kind, so a bad kind is refused before the ticket is resolved. It exits 1 rather than clap's 2, which is the price of a two-value flag and the reason `RelationKind::parse_value` names the three in its message
- **Both spellings of the kind are accepted**, `blocked-by` from the flag and `blocked by` from the label. Both are in front of the reader: the flag is what recorded the relation and the label is what `show` prints and what the file stores, so refusing the printed form would be a trap for anyone clearing a row they just read. `RelationKind::flag` is a match rather than `label().replace(' ', "-")`, so the flag, the `--clear` value and the completion list cannot drift apart
- **`find_relation` searches the ticket's own edges before the board, and that order is the feature.** A dangling edge is the case most likely to need clearing, and no search of the board can reach a target whose ticket is gone, so the id-prefix tier over the stored targets is the only one that finds it. `MIN_ID_SEARCH` is the floor `resolve_in` puts under its own id tier and the comparison is case insensitive for the same reason. Two stored targets under one prefix name the candidates rather than guessing, which is what an ambiguous ticket search already does
- **An edge the ticket does not hold reports no change; a target naming nothing at all is an error.** The two are different facts: the first is the state the caller asked for, and the second is a typo that reporting no change would swallow. The resolver's own reason is carried through, so an ambiguous search says so instead of being reported as nothing found
- **Recording and clearing the same relation in one call is refused, and the check runs on what was *asked* for.** `items` drops the additions already in the file, so comparing against that would let `--blocked-by X --clear blocked-by X` quietly remove an existing X. `requested` is the full list for exactly that reason. The refusal is `set --clear`'s: nothing is written rather than one direction silently winning
- **Removals rewrite the section and additions are appended to the result, in that order.** Two passes rather than one rebuild, so a call with no `--clear` takes exactly the path it always took and `append_section_body` goes on deciding where a new line lands. Rewriting from the parsed relations is lossless because a line that is not a relation is already an error. The last edge leaves `clear_section_body`'s placeholder, which is the line `append` treats as no content, so the next `relate` replaces it instead of writing under it
- **A relation is not logged, either direction.** `relate` writes no history entry and neither does `--clear`, which keeps the two consistent; per the history rule, an edge that matters enough to explain gets a comment. Do not add an entry for the removal alone: a log that recorded only the destructive half would read as though the additions had never happened
- **`add` does not write the section.** The plan on 4179958 asked for it in the ticket writer; it is out on purpose. A `_No relations._` block in every new ticket is noise in every `show`, and the insertion path has to exist regardless for every ticket written before the section did, so leaving it out means one path that is always exercised rather than two
- **The full uuid is stored, not the seven characters `ls` prints.** It resolves without a scan and cannot turn ambiguous as the board grows. `show` renders the short id and the target's title instead: the file is the machine's copy, the output is the reader's
- **One direction is stored and the inverse is derived.** `blocked by` goes on the gated ticket rather than `blocks` on the blocker, because the gated ticket is the one whose move is refused and whose author knows about the dependency. `relates to` is symmetric and is written once, on whichever end the caller ran it from. `RelationIndex::inbound` finds the far end by scanning, which is what keeps `relate` a single-file write
- **A derived row that reads exactly like a stored one is dropped, and the stored one is kept.** Both ends of a symmetric relation could hold a line, since nothing stopped it until 03bdc76, and the block then drew the same neighbour twice under the same label. The stored row survives because it is the line `relate --clear` can address; the derived one is on a file this ticket does not own
- **The dedupe keys on the label and the target, not the kind and the target.** Two tickets each blocking the other is two facts and the block says both, `blocked by` from this end and `blocks` from the other; keying on the kind would fold them into one row and lose half of what the ticket says. Only a symmetric kind can collide with its own stored line, and `RelationKind::is_symmetric` derives that from `label() == inverse_label()` rather than naming `RelatesTo`, so a kind added later answers by construction
- **`relate` also refuses to store the mirror, which is the other half of the same fix.** The dedupe repairs a board that already holds both directions; the refusal stops it recurring. `mirrored` in `cmd_relate` reads the target's own relations and reports no change, gated on `is_symmetric` because a target holding `blocked by <this>` is a cycle rather than a duplicate. 4179958 decided `relates to` is written once and not onto both files; for six months nothing enforced it
- **A symmetric edge is cleared from the end that stores it.** With both ends holding a line, `--clear` on one leaves the other's, which then draws as the derived row: correct, since the far end still asserts the relation, and the reason the dedupe keeps the stored row rather than the derived one
- **A line in the section that is not a relation is an error naming the ticket**, not a line quietly dropped. Nothing but `relate` writes there, so a bad line means a hand-edited file. The TUI is the deliberate exception: `detail_of` falls back to no block, since one corrupt ticket must not take the whole board down
- **The block is built outside `content_trim` and passed in.** Half of it comes from other tickets and `content_trim` has only the body. It is spliced over the stored lines where the file has the section, and injected ahead of the metadata where it does not, because a ticket that is only pointed at has no section of its own and still has relations to show
- `ensure_section` inserts against `SECTION_ORDER`, before the first following section that is actually in the file, and adds no blank line that was not already there. A handwritten `## Notes` between the plan and the metadata therefore keeps its place, and Metadata is in that list as an anchor rather than as something anything appends to
@@ -254,16 +266,20 @@ and this file is for what someone changing worklane's own code needs.
- **A card names its campaign on the label row, before the tags, in bold.** `labels_line` draws both, `CAMPAIGN_MARK` (`~`) for the campaign and `#` for a tag, and the campaign takes the row's width first: two cards in one campaign is what a reader looking for a campaign is looking for, and the tags are the context around it. So a row too narrow for both drops the tags whole and keeps the campaign, the order `corner_line` and `project_label` already follow, and a campaign the row will not hold at all goes whole too. A ticket in neither spends no row, so **a ticket in no campaign renders exactly as it did before campaigns reached the card**
- **`Card::campaign` is a resolved `Cell`, not a uuid**, settled at reload the way `project` and `blocked` are. `TicketItem::campaign` already carries the uuid off the pass that builds the card; the name is in another directory, so `columns_of` reads `CampaignIndex` once per project and hands it to every card. Never per draw, the rule `criteria` and `tags` already hold. The merge carries the resolved cell rather than looking it up again, for the reason it carries `blocked`: a campaign is addressed inside one `.worklane`, so a merged lookup could answer one project's uuid with another project's campaign
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cells` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
- **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the four statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `done_count` and the copy key all keep working unchanged
- **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `column_count` and the copy key all keep working unchanged
- **`Tab::campaign` is a uuid on the tab, not on the `Board`.** A campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::campaign` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign, because both heights have to be measured the same way by everything that measures the board. `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::frame` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign or a tag, because both heights have to be measured the same way by everything that measures the board. `screen_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `FRAME_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to. **Nothing in the geometry is named after campaigns**, because the slot is the tag filter's too: `Chrome::frame` says how tall the frame is and never which filter filled it, so a measurement of the board never has to ask
- **The whole description is carried off the one read, and the cut is on the view.** `section_prose` replaced `section_opening`, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, and `CampaignRow::summary` takes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file
- **`CAMPAIGN_PROSE_ROWS` is the collapsed height, and it is a constant rather than a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::campaign_rows` takes the height because of this, and `frame_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `CAMPAIGN_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
- **`FRAME_PROSE_ROWS` is the collapsed height, and it is a constant rather than a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::frame_rows` takes the height because of this, and `screen_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `FRAME_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards
- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with a campaign selected the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back
- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no campaign is selected is the one state that must never exist — `select_campaign` and `reload` are what keep it from arising
- **The frame slot is shared between the two filters, not doubled.** One filter is on at a time, per `Filter`, so a tag frame is the campaign frame with its three slots filled differently: `#tag` in `tag_color` on the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows. `FrameContent` is what the two are told apart into, and **`frame_content` is the one place they are told apart at all** — the borders, the colour, `q board`, the page indicator, the scroll and the focus are all the campaign frame's, and a second `match` on the filter below that is how the two frames come to behave differently in a way nobody decided
- **A tag frame draws the annotation, which is the payoff for declaring a tag.** Whoever is browsing a tag is deciding whether the next ticket belongs in it, and the sentence saying when the tag is appropriate is then on the screen at that moment rather than in `tags.md`, which they would have to know to open. An undeclared tag draws `NO_ANNOTATION` in grey, which is also the frame saying the word was never agreed on — the vocabulary file's own placeholder rather than the description section's, so the frame and the file say the same thing about the same tag. A tag declared with nothing said about it draws the same, since here the two have the same nothing to show; the picker's sections are where the difference is actionable
- **A tag has no id, so `y` on its frame copies the word.** A tag *is* its name, matched whole by `ls --tag`, so there are no seven characters to shorten and the `#` the border draws is not part of it — `--tag "#bug"` matches nothing. The footer says `y copy tag` there for the same reason: naming it an id would send the reader looking for a short id on a border that prints a word
- **The count on a tag frame is every column's, drawn or not**, the rule the standing holds. With the filter on, those columns *are* the tickets carrying the tag, so it counts what is below it without counting it a second way. The noun is spelled out and pluralised, because a bare number on a border says nothing about what was counted, and there is no derived state beside it: a tag is a word and not a piece of work, so there is no `[open]` to be in
- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with either filter on the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back
- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no filter is on is the one state that must never exist — `select_filter` and `reload` are what keep it from arising, off `Filter::is_whole` rather than off which filter it is, since either draws a frame to hold it
- **`Tab::selected` hands back nothing while the frame holds the selection.** Every key that acts on a card has to answer for the frame. `←→` are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen. `y` is the exception that earns its place: it copies the campaign's short id, so `y copy id` means the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is about
- **`enter` routes on the focus through `Board::toggle_focused`: the frame's height on the frame, the overlay on a card.** It used to be inert on the frame for free, because `Tab::selected` hands back nothing and `toggle_detail` therefore had nothing to open. That is no longer an answer, and the routing is in `Board` rather than in the `main.rs` arm for the reason `dismiss` and `scroll_page` are
- **`q` does not gain a layer for the expanded frame, and up and down do not take it back.** The expanded frame is the frame at its other height, not a thing laid over the board, so `q` goes on taking the campaign filter off from either height and `enter` is the only key that undoes what `enter` did. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card. `Tab::expanded` sits beside the filter and resets where `select_campaign` and `reload` reset the focus and the offset — a different campaign opens collapsed and at the top of its own description
@@ -271,8 +287,8 @@ and this file is for what someone changing worklane's own code needs.
- **The frame is out of reach from under an open ticket.** With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting. `an_open_ticket_keeps_the_scroll_keys_from_the_frame` builds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it
- **The standing comes from the columns, not from a walk of the tree.** While a campaign is selected the columns *are* its members, done included, so `Tab::standing` counts what is already in hand rather than paying what `campaign ls` pays per campaign. Counted over every column, drawn or not: hiding done is a change to what is drawn and never to what is counted
- **The way out is on the frame's own border, not in the footer.** `q board` sits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows
- **`c` is named in the footer only on a closed board with nothing selected**, which is where a reader has to find it. Over an open ticket and on a filtered board it is left out: the frame's border then says how to put the campaign away, and the row has no cells to spare. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, `enter expand` or `enter collapse`, the two scroll keys and `y copy id`, and leaves out `←→` because they do nothing there. It has to say which way `enter` goes, since the key is a toggle and the frame is always at one of its two heights. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and `↑` reaches it
- **`c` and `t` are named in the footer only on a closed board with nothing filtered**, which is where a reader has to find them. Over an open ticket and on a filtered board they are left out: the frame's border then says how to put the filter away, and the row has no cells to spare. The tag used to be drawn on that row in its own colour, for want of a frame to draw it in, and 2a83bd4 took that away rather than saying it twice. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, `enter expand` or `enter collapse`, the two scroll keys and `y copy id` — `y copy tag` on a tag frame — and leaves out `←→` because they do nothing there. It has to say which way `enter` goes, since the key is a toggle and the frame is always at one of its two heights. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and `↑` reaches it
- **`picker: Option<Picker>` is the whole mode**, the shape `search` and `detail` use, and `Board::picker_key` runs beside `search_key` ahead of the action arms for the same reason: an open list owns the keyboard, so `d` must not toggle done and `q` must not quit while a campaign is being chosen. `ctrl-c` is the one key it declines and every other control combination is swallowed, or `ctrl-d` would reach the arm bound to `d`
- **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty
- **A picker row draws a real codename only.** The row opens with the short id, so the card's `~<id>` fallback would print it twice and say nothing the second time
@@ -296,15 +312,15 @@ and this file is for what someone changing worklane's own code needs.
- `tags` is a field on `TicketItem`, filled in `collect_ticket_items` through `parse_tags`, for the reason the criteria count is. `parse_tags` splits the comma-separated field into whole trimmed values, so a caller asking for `bug` is not answered by `bugfix`, and reads absent, `_None_` and empty as the same answer
- **A held-up card carries `BLOCKED_MARK`, `×`, after its id, in brightred.** The constant lives in `util.rs` and the relations block draws the same one, since both say the same word. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
- **The mark goes after the id, not before it.** Ahead of the id it would push every id in the column out of line whenever one card was blocked, which costs more than one card's state is worth. It is measured before the project label and the due date, so both give way to it: those are context for a ticket somebody can start, and this is the one thing on a card that says not to. Dropped whole when the row cannot hold the identity and the mark together, the rule a corner follows
- **`blocked` is on `Card`, not on `TicketItem`.** The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the way `project` is. What `collect_ticket_items` fills is the ticket's own `uuid` and its `blockers`, both read off the file it is already holding; `mark_blocked` then walks the four columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw
- **`blocked` is on `Card`, not on `TicketItem`.** The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the way `project` is. What `collect_ticket_items` fills is the ticket's own `uuid` and its `blockers`, both read off the file it is already holding; `mark_blocked` then walks the columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw
- **A blocker the board does not hold marks nothing**, the answer `mv` already gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exception `detail_of` makes for the same reason: `show` and `mv` are where a hand-edited file is reported, and a board that will not draw because one ticket is malformed is the worse failure
- **The merge carries the flag rather than recomputing it.** `relate` resolves its target inside one `.worklane`, so a blocker in another project is not a relation anything can record; resolving over the merged columns would let one project's uuid match another project's ticket. That is b8ce18c's fourth plan step and the answer is no
- `project_label` takes the width the row has already spent, measured off the spans, rather than adding up the widths those spans are supposed to have. The hand-written version left out the space after the priority mark, so a cut label was handed one cell more than the column had; `the_project_label_leaves_the_row_inside_the_column` pins it
- `due_date` cuts a due value back to its date only when it has one. The field is not validated (daa0e79), so it can hold a time or free text, and taking the first word regardless would turn "next friday" into "next"
- **Done is hidden until `d` asks for it.** Not a new opinion: `ls` already counts done in its summary and leaves it out of the listing. Done only grows, so a quarter of the width was going to the column least often read. The footer carries its count while it is hidden, which is the board's version of that summary line
- **Hiding is a change to what is drawn, never to what is read.** `reload` still scans the done directory and `digest` still watches it, so the footer count is right and revealing the column needs no rescan. Do not "optimise" that into a conditional scan
- `visible()` returns a prefix of `columns`, not a filter, which is what keeps `column` and `offsets` valid as indices into either. It is derived from where `DONE` actually sits rather than assuming the last slot, and `the_done_column_is_last` pins the assumption. A status inserted after done would otherwise hide two columns in silence
- Hiding the column under the selection moves the selection to the last drawn column and **closes an open detail view**. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing done again is a no-op for the selection, since a column is appended rather than inserted
- **The terminal columns are hidden until `d` asks for them, one step at a time.** Not a new opinion: `ls` already counts both in its summary and leaves them out of the listing. Done only grows, so a quarter of the width was going to the column least often read, and discarded arriving made it two. So `d` rotates three states — hide both, show done, show both, and back around — through the `Visibility` enum on `Board`, discarded last in the rotation because it is the least likely thing to be looking for. The footer names what the *next* press does and carries the count of the column still hidden, which is the board's version of that summary line. Hiding is a prefix of the columns: done and discarded are the last two in what the board draws, so revealing either appends it and the columns before keep their indices
- **Hiding is a change to what is drawn, never to what is read.** `reload` still scans the done and discarded directories and `digest` still watches them, so the footer counts are right and revealing either column needs no rescan. Do not "optimise" that into a conditional scan
- `visible()` returns a prefix of `columns`, not a filter, which is what keeps `column` and `offsets` valid as indices into either. It is derived from where `DONE` and `DISCARDED` actually sit rather than assuming positions, and `the_terminal_columns_are_last_in_the_order_drawn` pins the assumption. A status inserted after discarded would otherwise hide two columns in silence
- Hiding the column under the selection moves the selection to the last drawn column and **closes an open detail view**. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing another column is a no-op for the selection, since a column is appended rather than inserted
- The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket
- **Assert a column heading against the top border row, not the whole screen.** The footer names done too, so `screen.contains("done (0)")` passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden; `headings()` and `footer()` exist so the next one does not. `headings()` locates the row through `board_area()` rather than taking row zero, since the tab row sits above it when more than one board is monitored
@@ -338,7 +354,11 @@ and this file is for what someone changing worklane's own code needs.
### The Relations Block
- **One builder, two painters.** `relation_rows` decides which edges there are, what they are called and which direction comes first; `relation_cells` decides the layout, the mark and the colours; `paint_cells` turns cells into escapes for the CLI and `span_of` turns the same cells into ratatui spans for the board. Two builders producing one block in two shapes is a pair free to disagree about ordering or padding, which is what this shape exists to prevent
- **`Cell` is the unit both renderers take**: a run of text and the colour it is drawn in, `None` for the default foreground. The same trick as the palette itself, where `Color::ansi()` and `From<Color> for ratatui::style::Color` keep one colour from existing for one renderer and not the other
- **`Cell` is the unit both renderers take**: a run of text, the colour it is drawn in and the modifier it carries, `None` for the default foreground and for text drawn as it stands. The same trick as the palette itself, where `Color::ansi()` and `From<Color> for ratatui::style::Color` keep one colour from existing for one renderer and not the other, and `Modifier` is that trick a second time for the styles that are not colours
- **`Modifier` is the first style on a cell that is not a colour**, and it is an enum with one variant for the reason the palette is one: `Modifier::ansi()` is SGR 9 and `From<Modifier> for ratatui::style::Modifier` is `CROSSED_OUT`, so a style that exists for one renderer and not the other is a compile error. Bold is not in it, because bold rides inside `Color::Magenta.ansi()` and `span_from` adds it back from the colour alone; a second modifier goes here beside the strike. It is independent of the colour, so a struck run keeps whatever colour its column already gave it
- **`Cell::struck` is a builder, not a third constructor.** The strike is decided a whole row at a time and the cells of that row are built by the layout that already chose their colours, so `relation_cells` maps it over the row it has just finished rather than threading the decision through every cell it makes
- **`RESET` is a constant both writers share.** `paint` opens a colour and `paint_cell` may open a modifier ahead of one, and a reset that only knew about the colour would leave the strike running to the end of the line
- **`Body::push_cell` merges on the whole style, not the colour alone.** Nothing outside the relations block carries a modifier today, and a merge keyed on the colour would silently strike a plain run through the moment one did
- **`reference_cells` is the one spelling of a cross reference.** The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown. There was a `reference_cell` beside it that painted the cells for the CLI; once the whole body became cells the Campaign field stopped needing a string and it was the last caller, so it is gone
- **A row carries two marks, kind then status**: what sort of edge this is, then how far the ticket at the other end has got. `blocked by × ◐ (6ce2c47) Title`. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished
- The status went through one bad shape first. It was a rising bar, `▁▄▆█`, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer
@@ -372,14 +392,14 @@ and this file is for what someone changing worklane's own code needs.
- `worklane tui <path>...` takes any number of paths, each resolved through `find_worklane_dir` the way the working directory is: the first `.worklane` at or above it. No path is the working directory, so a bare `worklane` and `worklane tui` are unchanged
- The failure **names the path** that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare `worklane` has no path to name and keeps the message every other command gives, which is what its integration test asserts
- Two paths inside one project resolve to the same `.worklane` and are monitored once. `projects()` dedupes on the resolved directory, not on the argument
- **`Tab` owns the selection**, `column`, `card` and `offsets`, not `Board`. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. `Board::current()` is the tab in view, and `show_done` stays on the board because it is a preference about the flow rather than about a project
- **`Tab` owns the selection**, `column`, `card` and `offsets`, not `Board`. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. `Board::current()` is the tab in view, and `visibility` stays on the board because it is a preference about the flow rather than about a project
- The tabs are fixed for the run: a project cannot be added or dropped without restarting, so `Board::new` builds the tab list once and `reload` only refills each tab's columns. `reload` clamps **every** tab, and `select_tab` clamps again on arrival, because done may have been hidden while another tab was in view
- The merge tab goes **first** and is where the view opens: it is the reason to monitor several boards at once. It is materialised in `reload`, from the cards already read, rather than computed per draw — the same reason the criteria count is filled in `collect_ticket_items`
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes `by_status_order`: the merge spans statuses, so no single entry stamp governs it
- `Card` wraps a `TicketItem` with the project it came from, `Some` only on the merge tab. Decided at reload rather than passed down to `card_lines` as a "which tab is this" flag. `TicketItem` is therefore `Clone`: the merge holds a second copy rather than re-reading every tree
- **The project follows the id, on the card and on the overlay border.** Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live. `project_label` takes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is what `corner_line` drops
- `tab` and `shift+tab` cycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns took `hjkl` and the arrows
- **The tab row is drawn only when there is more than one board**, so a single board is the view it has always been. `frame_rows()` gives it `Length(0)` otherwise, which keeps the row indices the same for both cases and is shared with `card_width` and `column_text_height` for the reason `column_areas` is: geometry reproduced by hand drifts from the draw
- **The tab row is drawn only when there is more than one board**, so a single board is the view it has always been. `screen_rows()` gives it `Length(0)` otherwise, which keeps the row indices the same for both cases and is shared with `card_width` and `column_text_height` for the reason `column_areas` is: geometry reproduced by hand drifts from the draw
- `digest_of` hashes each board's `digest` into one value, so a change in any of them redraws. Do not watch only the first
### Who Wrote an Entry
@@ -457,8 +477,14 @@ and this file is for what someone changing worklane's own code needs.
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
- Relation kind mark → brightred `×` blocked by and blocks, cyan `→` relates to, orange `←` regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `●` discarded, grey `?` for a target the board does not hold. Discarded takes the full circle of done in the grey of the untouched pile: nothing is left to do, and it is not an achievement. The *pair* is what has to be unique, which is the same bargain the two half circles already take, and `every_status_has_a_mark` pins it against `status_dirs`. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
- **Relation row to a discarded target → struck through, the whole row.** The one thing in the palette that is not a colour, and it is here because the status mark cannot carry it: that mark is one cell in a column of five states, so a row pointing at abandoned work reads as a live dependency, which is exactly what it is not. The strike says the relation no longer stands for anything while the row stays on the ticket, for completeness and for the case the target is moved back out of discarded. Only discarded: a done target still stands for the fact that it was a blocker, and a `_missing_` one says something different again, that the row cannot be resolved at all. Gutter and padding included, so the line runs unbroken from the label to the end of the title, and every cell opens its own SGR 9 since each is closed by its own `RESET`
- **The strike is under the colour flag, like every other escape.** A piped `show` carries none of it, the same bargain committed and reviewing already take for being told apart by colour alone, and the board draws it as a style instead. Do not answer the pipe by changing the glyph in the mark column: the pair there has to stay unique, and `every_status_has_a_mark` is what says so
- Markdown link → cyan, markers and url kept. Not a new meaning for the colour: the plan numbers, the criterion numbers and the `relates to` mark are already cyan inside a rendered body, and a link is the same kind of thing, a pointer the reader may follow rather than a value. The url is not hidden behind the text the way a renderer would hide it, because `show` prints to a terminal worklane cannot assume will make it clickable, and a link whose target cannot be read is worse than a long line
- Chrome → grey. The footer's key names, a rendered `[ ]`, and the overlay's page indicator. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level
- Chrome → grey, in the history block too: the kind label at the head of a mechanical row, and the `From` on a comment's author line. Both name their row rather than holding a value, which is what grey already says. The label was orange, which means Status everywhere else, so an `owner` or `tags` label claimed a meaning belonging to the value beside it
- **A value in the history block takes the colour it has in the metadata table three lines above.** A status is orange, a tags entry goes through the same `tag_cells` the Tags field does, a campaign codename takes `tag_color` bare the way `Codename` does, and `_Not set_`, `_None_` and `_missing_` are grey. An owner stays plain: a person's name is the one value the palette has no meaning for, and spending a colour on the field that needs it least is how a colour stops meaning anything. The block's job is to be scanned, and it is not worth scanning if it has a palette of its own to learn first
- History actor → its name through `tag_color`, the way a campaign codename is. Not a new meaning for a reserved colour but the existing use of the tag slots, a name that groups rows: one writer is one colour in every entry it wrote, so a reader sees who has been working a ticket without reading the same name four times. `claude`, `opencode` and a person each get their own
- History timestamp → cyan, and its own span. It shared one with the actor while the two were formatted as `name (time)`, which spent the timestamp's colour on a name. The parentheses are plain: they are punctuation, not chrome with something to say
- Campaign label → its codename through `tag_color`, bold, marked `~`. The colour is what groups a campaign across the cards that carry it, which is exactly what a tag's colour is for, and one word is one colour in every view because `tag_color` is a pure function of it. The mark and the bold are what tell it from a tag on a row that holds both: the mark is not `#`, or the row would read as a list of tags with a stranger in it, and not `@`, which reads as a person on every board anyone has used. `Codename` in a metadata table takes the colour without the mark, since the field name has already said what it is
- Campaign label with no codename → grey. The label is then the short id, and grey keeps a reserved meaning off a `TAG_COLORS` slot in the one case where it would land on one: red is the uuid's everywhere else, and grey already means what a reader skips, which is what a campaign with no codename has to say for itself
- **The palette splits in two: seven colours that each mean one thing, and `TAG_COLORS`, the eight a tag may be drawn in.** A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour in `TAG_COLORS`, and do not draw a tag in one outside it
@@ -469,6 +495,8 @@ and this file is for what someone changing worklane's own code needs.
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground. `\x1b[38;5;8m` is byte for byte what crossterm emits for ratatui's `Color::DarkGray`, the grey frig and pantop use for dimmed rows
### Code Organization
- **`change` and `split_change` are a pair, and they live beside each other in `history.rs`.** The mechanical body is stored as one string, `before → after`, so painting the halves means splitting it, and the separator is a constant the writer and the reader share. A renderer with its own copy of the spacing would go on splitting on a separator the writer no longer emits, and would say so by drawing a whole body as one half. The split is `split_once`, so a value carrying the arrow itself keeps it
- **The history block indents by who is talking.** A comment's body sits at four spaces and the reason under a mechanical row at two; the author line stays at column 0 and is told from a mechanical row by its `From` and its colour instead. The rule a reader learns is that an indented line is somebody's own words and a line of values at column 0 is the tool reporting itself
- **`history.rs` owns the log end to end**: the path, the kinds, the parse, the write, the count and the render. It came out of `util.rs` and `handlers.rs`, where the reader, the writer, the counter and the renderer sat in three files and one of them was 5,500 lines. The test for the reason is the module doc: a reader asking what an entry is has one file to open, the way `campaign.rs` and `tag.rs` answer their own questions
- The body's painters return cells, not strings: `ordered_cells`, `inline_cells`, `metadata_cells`, `metadata_value_cells`, `tag_cells` and `push_heading`. `content_trim_colored` is the CLI entry point and `paint_cells` is the only thing that writes an escape. `colorize_line` is gone: it was a `pub` alias for the bold pass with one caller, and the only thing it added was asking the terminal
- **`inline_cells` walks the line once for both inline markers**, `**bold**` and `[text](url)`, rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and `\x1b[36m` carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was `colorize_bold` while links lived in a branch of their own in `content_parts`; that branch is gone, which is also what gives the criteria text and the metadata `Other` rows their links, since those already went through this function
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.31.0"
version = "0.32.1"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.31.0"
version = "0.32.1"
edition = "2024"
[dependencies]
+3 -2
View File
@@ -5,7 +5,7 @@ Worklane is a local Kanban flow for agentic software development.
## Commands
| Command | Description |
|---------|-------------|
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Discarded tickets are not drawn yet, `worklane ls discarded` is where they are read. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, `enter` gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
| `worklane` or `worklane tui [path...]` | Opens the board: one column per status, redrawn when the tree changes. Read only. Opens with done and discarded hidden, their counts in the footer; `d` rotates hide both, show done, show both, and back around. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, `enter` gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done, discarded directories |
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
| `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 |
@@ -13,7 +13,7 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions. `--status discarded` is exempt and reachable from anywhere, for a ticket that will not be done; leaving `discarded` is a backward move and needs `-f`. Discarding is refused while open tickets are blocked by the ticket, `-f` overrides. Records a `status` entry in the ticket's history, after the move: a refused or no-op move records nothing. `--actor` names the writer of that entry |
| `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. `--tags` records a `tags` entry in the ticket's history, with the tags before and after, and it is the only field of this command's that is logged; `--actor` names the writer of that entry |
| `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 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, and a derived row that reads exactly like a stored one is drawn once. `relates to` on a ticket whose target already stores it reports no change, since it is the same edge; `blocked by` and `regression of` read differently from the far end, so a mutual pair is two rows. `mv` refuses to move a ticket blocked by one that is not done, unless `-f`. `--clear <kind> <target>` takes an edge off instead, repeatable, the kind spelled either way, `blocked-by` or `blocked by`. The target resolves against the edges the ticket holds first, by id prefix, which is the only way to reach one whose ticket has been deleted, then as an ordinary ticket search. An edge the ticket does not hold reports no change; a target naming nothing at all is an error. Recording and clearing the same edge in one call is refused |
| `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. Records an `owner` entry in the ticket's history, with the owner before and after; `--actor` names who made the change, which is not the same as the user argument |
| `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 |
@@ -55,6 +55,7 @@ worklane mv <TAB> the same, then --status <TAB> for the five
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>
worklane relate x --clear <TAB> the three kinds, not a ticket: the kind comes first
worklane campaign show <TAB> the campaigns, from `campaign ls --ids`
worklane assign <TAB> the same, since a campaign comes first here
worklane ls --campaign <TAB> and again
+36 -2
View File
@@ -127,6 +127,11 @@ is never left half-marked. A criterion already in the state you asked for is rep
unchanged rather than refused, and a call that would change nothing writes nothing. Both
apply to `uncheck` exactly as they do to `check`.
**Say why on the unusual moves:** `worklane mv 1b78a24 --status backlog -f --reason "the
first plan was wrong"`. The reason is recorded inside the history entry beside the
transition it explains and rendered indented under its row, in `show` and on the board.
Optional on every move; a refused or no-op move records nothing even with one.
## Filing a ticket
```
@@ -196,13 +201,38 @@ directory beside them, for a repo that has no board yet.
worklane relate 1b78a24 --blocked-by 4179958 # this one waits on that one
worklane relate 1b78a24 --regression-of 6d327df # this one broke that one's fix
worklane relate 1b78a24 --relates-to 7bfb9fc # neighbours, no dependency
worklane relate 1b78a24 --clear blocked-by 4179958 # take that edge off again
```
One flag per kind, and each repeats. The ticket comes first and the flag says what it is
to the target, so read the call as a sentence: `relate A --blocked-by B` means A waits
on B. **Only one side is stored**, on the ticket you name, and `show` derives the other
on B.
**`--clear` is how an edge comes off, and it names the kind and the target**, because a
ticket can hold several relations of one kind and emptying all of them is rarely what is
wanted. Repeat the flag for more. The kind is spelled either way, `blocked-by` as the flag
records it or `blocked by` as `show` prints it. `set --clear` does not reach relations:
`relate` is the only writer of the section, so it owns both directions.
The target is resolved against the edges the ticket already holds first, by id prefix,
and only then as an ordinary ticket search. That order is what lets you clear an edge
whose target has been **deleted**, which is the case most likely to need it: `show` draws
it as `_missing_` with a `?` mark and `mv` warns about it on every move, and no search of
the board can reach a ticket that is gone.
An edge the ticket does not hold reports no change. A target that names nothing at all is
an error rather than a no-op, so a mistyped id does not read as success. Recording and
clearing the same edge in one call is refused outright, the way `set` refuses a field it
is also replacing, and nothing is written. **Only one side is stored**, on the ticket you name, and `show` derives the other
end for the ticket at the far side, so never record both directions.
`relates to` reads the same from both ends, so recording it on the second ticket is
refused as no change: the edge is already there, from the far side. `blocked by` and
`regression of` are different: the far end reads as `blocks` and `regressed by`, so two
tickets each blocking the other is two facts and the block shows both. A symmetric edge
comes off with `--clear` at the end that stores it, since that is the only end holding a
line to remove.
`--blocked-by` is enforced: `mv` refuses to move a ticket while a ticket it is blocked by
is not in `done` or `discarded`, whichever move it is, and names every open blocker. `-f`
moves it anyway, beside the backward and skipping moves it already allows. It is enforced
@@ -226,6 +256,10 @@ pair shares a glyph, and **your output is a pipe, so you do not get the colour**
`◐` as under way and `●` as nothing left to do, and if it matters which of the two,
`worklane show` on that target says so in its Status field. `○` is unambiguous without it.
A row pointing at a **discarded** target is struck through on a terminal, since a
relation to abandoned work otherwise reads as a live dependency. That is a style rather
than a character, so a pipe does not get it either: ask the target's Status field.
## Campaigns
A campaign groups the tickets that have to be finished together: a release, a migration,
@@ -314,7 +348,7 @@ HISTORY
status backlog → committed claude (2026-08-24 12:45:00)
From claude (2026-08-24 13:10:22)
The offset was never passed to the widget.
The offset was never passed to the widget.
owner _Not set_ → Ansho Rei claude (2026-08-24 13:11:04)
+35 -1
View File
@@ -230,6 +230,11 @@ pub enum Command {
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
/// Why the ticket moved, recorded in the history entry beside the transition
/// it explains. Prose, so it takes a leading hyphen
#[arg(long, allow_hyphen_values = PROSE)]
reason: Option<String>,
},
/// Replace fields on an existing ticket
@@ -847,12 +852,17 @@ pub struct AppendArgs {
/// Each flag repeats, so several relations of one kind land in a single call. The
/// targets are ticket searches, resolved by the same three tiers every other ticket
/// argument is, and stored as the target's uuid.
///
/// `--clear` is the other direction, and it is here rather than on `set` for the reason
/// Relations is absent from `section_args`: a relation names a target that has to be
/// resolved first, so its one writer owns both adding and removing, the way `chown` owns
/// both setting an owner and clearing one.
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("relation_kinds")
.required(true)
.multiple(true)
.args(["blocked_by", "regression_of", "relates_to"])
.args(["blocked_by", "regression_of", "relates_to", "clear"])
))]
pub struct RelateArgs {
/// Ticket UUID or title
@@ -869,6 +879,18 @@ pub struct RelateArgs {
/// Ticket this one is merely related to. Symmetric, so it is recorded once
#[arg(long, value_parser = non_empty)]
pub relates_to: Vec<String>,
/// Take a relation off: the kind, then the ticket it points at. Repeat the flag
///
/// Two values rather than one, because a ticket can hold several relations of one
/// kind and emptying every `blocked by` on it is not usually what is wanted. That is
/// also why this is not `set --clear`, which names a field and empties the whole of
/// it: the "value" here is one edge among several, so the target has to be named too.
///
/// A `Vec<String>` because clap cannot type the two values of one flag apart.
/// [`RelateArgs::cleared`] is where the pairs are split and the kind is parsed.
#[arg(long, num_args = 2, value_names = ["KIND", "TARGET"], value_parser = non_empty)]
pub clear: Vec<String>,
}
impl RelateArgs {
@@ -881,6 +903,18 @@ impl RelateArgs {
(RelationKind::RelatesTo, &self.relates_to),
]
}
/// The relations asked to be taken off, as a kind and the search naming the target.
///
/// `num_args = 2` is per occurrence, so clap has already refused an odd number of
/// values and every chunk is a full pair. A kind that is not one of the three is
/// refused here, before the ticket is resolved and long before anything is written.
pub fn cleared(&self) -> anyhow::Result<Vec<(RelationKind, &str)>> {
self.clear
.chunks(2)
.map(|pair| Ok((RelationKind::parse_value(&pair[0])?, pair[1].as_str())))
.collect()
}
}
/// `check` and `uncheck` are separate commands rather than one verb with a flag,
+55 -13
View File
@@ -22,7 +22,7 @@ use clap::{CommandFactory, ValueEnum};
use clap_complete::Shell;
use crate::install::SKILLS;
use crate::util::Status;
use crate::util::{RelationKind, Status};
/// Subcommands whose first positional is a ticket.
///
@@ -98,6 +98,11 @@ fn fish_dynamic() -> String {
let ticket_commands = TICKET_COMMANDS.join(" ");
let ticket_second_commands = TICKET_SECOND_COMMANDS.join(" ");
let ticket_flags = flag_list(&TICKET_FLAGS);
let relation_kinds = RelationKind::ALL
.iter()
.map(|kind| kind.flag())
.collect::<Vec<_>>()
.join(" ");
let campaign_commands = CAMPAIGN_COMMANDS.join(" ");
let campaign_nested = CAMPAIGN_NESTED_COMMANDS
.iter()
@@ -188,6 +193,14 @@ complete -c worklane \
complete -c worklane -n '__worklane_command_is relate' {ticket_flags} \
-x -a '(worklane ls --ids)'
# `--clear` is the one flag here whose first value is not a ticket, so it is not in
# `TICKET_FLAGS`: it takes the kind and then the target, and offering a board listing where
# the kind goes would be offering values it refuses. The kinds come from `RelationKind`
# rather than being spelled again. The target gets no rule at all, deliberately: fish
# completes the value after the flag, and the case this flag exists for is a target whose
# ticket is gone, which no listing of the board can offer.
complete -c worklane -n '__worklane_command_is relate' -l clear -x -a '{relation_kinds}'
# Campaigns, from `campaign ls --ids`, in the three places one is named: `assign`'s first
# argument, `campaign show`'s only one, and `ls --campaign`.
complete -c worklane \
@@ -464,22 +477,51 @@ 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.
/// Three commands carry a `--clear` and each one takes something different: `chown`
/// takes the ticket, `relate` takes the kind and then the target, and `set` takes a
/// field name clap already offers. So each rule is scoped to its own command, and a
/// bare search for `-l clear` cannot tell them apart, which is what this used to do.
#[test]
fn chowns_clear_is_completed_with_tickets_and_sets_is_not() {
fn each_clear_flag_is_completed_for_its_own_command() {
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("__worklane_command_is chown"), "{rule}");
assert!(rule.contains("worklane ls --ids"), "{rule}");
let chown = command().find_subcommand("chown").expect("chown exists").clone();
let cli = command();
let rule_for = |name: &str| {
let scope = format!("__worklane_command_is {name}");
script
.lines()
.find(|line| {
line.starts_with("complete")
&& line.contains("-l clear")
&& line.contains(&scope)
})
.unwrap_or_else(|| panic!("no --clear rule for {name}:\n{script}"))
};
let has_clear = |name: &str| {
cli.find_subcommand(name)
.unwrap_or_else(|| panic!("no such subcommand: {name}"))
.get_arguments()
.any(|arg| arg.get_long() == Some("clear"))
};
// `chown --clear` names the ticket in the flag, so the flag completes tickets.
assert!(has_clear("chown"), "`chown` has no --clear for the rule to complete");
assert!(rule_for("chown").contains("worklane ls --ids"), "{}", rule_for("chown"));
// `relate --clear` takes the kind first, so it offers the kinds and not a board
// listing: tickets there would be candidates the flag refuses. The target, the
// second value, is deliberately left uncompleted.
assert!(has_clear("relate"), "`relate` has no --clear for the rule to complete");
let relate = rule_for("relate");
for kind in RelationKind::ALL {
assert!(relate.contains(kind.flag()), "{kind:?} is not offered: {relate}");
}
assert!(
chown.get_arguments().any(|arg| arg.get_long() == Some("clear")),
"`chown` has no --clear for the rule to complete"
!relate.contains("worklane ls --ids"),
"tickets offered where the kind goes: {relate}"
);
assert!(
!TICKET_FLAGS.contains(&"clear"),
"--clear in TICKET_FLAGS would offer tickets to `set --clear`, which takes a field"
+176 -10
View File
@@ -607,10 +607,20 @@ pub fn cmd_mv(
target: Status,
force: bool,
actor: &Option<String>,
reason: &Option<String>,
start: &Path,
) -> Result<()> {
let target_status = target.as_str();
// A reason is one fact on one line, which is how the renderer draws it, so a
// newline smuggled in through the shell collapses with the whitespace around it.
// All blank means none, rather than an empty field in the log.
let reason = reason
.as_deref()
.map(str::split_whitespace)
.map(|words| words.collect::<Vec<_>>().join(" "))
.unwrap_or_default();
let worklane_dir = find_worklane_dir(start)?;
let (current_status, title, resolved) = resolve_ticket(ticket_id, &worklane_dir)?;
@@ -697,13 +707,14 @@ pub fn cmd_mv(
// After the move, never before: an entry for a move that was refused would be a log
// of things that did not happen. The no-op above returns without one for the same
// reason.
// reason, and without its --reason with it.
write_entry(
&worklane_dir,
&parse_ticket_field(&resolved, "ID"),
Kind::Status,
&change(&current_status, target_status),
&resolve_actor(actor.as_deref()),
&reason,
)?;
println!(
@@ -740,6 +751,7 @@ pub fn cmd_comment(
Kind::Comment,
body,
&resolve_actor(actor.as_deref()),
"",
)?;
println!("Comment added to '{}' ({})", title, filename);
@@ -988,6 +1000,7 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
&parse_ticket_field(&content, "Tags"),
),
&resolve_actor(args.actor.as_deref()),
"",
)?;
}
@@ -1046,6 +1059,7 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
&parse_ticket_field(&content, "Owner"),
),
&resolve_actor(args.actor.as_deref()),
"",
)?;
let verb = match user {
@@ -1091,16 +1105,97 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
/// The kinds are a flag each rather than a `--kind` value, so an unknown kind is a
/// usage error at the door instead of a line written into the file and refused on the
/// way back out.
/// The stored relation a `--clear` names, or `None` when the ticket does not hold it.
///
/// Two tiers, in this order. A uuid prefix against the targets this ticket already
/// stores, which is the only tier that can reach a dangling edge: the target's ticket is
/// gone, so no search of the board resolves it, and that is the case most likely to need
/// clearing. Then the ordinary ticket search, so a title or a prefix of a live ticket
/// works here the way it does in every other argument.
///
/// The prefix tier is the ticket's own relations and not the board, so it stays cheap and
/// cannot be made ambiguous by a ticket somewhere else. `MIN_ID_SEARCH` is the same floor
/// `resolve_in` puts under its id tier, and the comparison is case insensitive for the
/// same reason: an id typed back off a listing has to resolve in whatever case it was
/// read.
///
/// A search that reaches neither tier is an error, not a no-op. A relation the ticket does
/// not hold reports no change, which is what the caller asked for either way, but a search
/// naming nothing at all is a typo and reporting no change for it would swallow it.
fn find_relation(
existing: &[Relation],
kind: RelationKind,
search: &str,
title: &str,
worklane_dir: &Path,
) -> Result<Option<Relation>> {
let held: Vec<&Relation> = existing.iter().filter(|held| held.kind == kind).collect();
let wanted = search.to_lowercase();
let by_prefix: Vec<&Relation> = held
.iter()
.copied()
.filter(|held| {
search.chars().count() >= MIN_ID_SEARCH
&& held.target.to_lowercase().starts_with(&wanted)
})
.collect();
match by_prefix.as_slice() {
[only] => return Ok(Some((*only).clone())),
// Named rather than guessed at, the way an ambiguous ticket search is: the
// candidates are printed and nothing is written.
[_, _, ..] => {
return Err(anyhow!(
"'{}' matches {} '{}' relations on '{}': {}. Name more of the id",
search,
by_prefix.len(),
kind.label(),
title,
by_prefix
.iter()
.map(|held| short_id(&held.target))
.collect::<Vec<_>>()
.join(", ")
));
}
[] => {}
}
match resolve_ticket(search, worklane_dir) {
Ok((_status, _target_title, target)) => {
let target_uuid = parse_ticket_field(&target, "ID");
Ok(held.into_iter().find(|held| held.target == target_uuid).cloned())
}
// The resolver's own reason is carried through, so an ambiguous search says it is
// ambiguous rather than being reported as nothing at all.
Err(reason) => Err(anyhow!(
"No '{}' relation on '{}' matches '{}': {}",
kind.label(),
title,
search,
reason
)),
}
}
pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
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 existing = parse_relations(&original, &title)?;
// Every target resolved and every refusal raised before a byte is written, so a
// call naming one good ticket and one bad one records neither.
// Every target resolved, every kind parsed and every refusal raised before a byte is
// written, so a call naming one good ticket and one bad one records neither.
let asked = args.cleared()?;
let mut items: Vec<String> = Vec::new();
let mut changed: Vec<&str> = Vec::new();
// Every addition the call asked for, whether or not it is one to write. `items` drops
// the ones already held, and a contradiction has to be caught on what was *asked*: a
// relation already in the file is not in `items`, so comparing against that would let
// `--blocked-by X --clear blocked-by X` quietly remove it.
let mut requested: Vec<Relation> = Vec::new();
for (kind, targets) in args.requested() {
for search in targets {
@@ -1122,10 +1217,21 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
}
let relation = Relation { kind, target: target_uuid };
requested.push(relation.clone());
// Already held, either in the file or earlier in this call. Recording it
// twice would read as two dependencies on one ticket.
if existing.contains(&relation) || items.contains(&relation.item()) {
// A symmetric relation the target already stores is already recorded, from
// the other end: `show` derives it onto this ticket by scanning, so a line
// here would be the same edge stored twice. 4179958 decided `relates to` is
// written once and not onto both files, and nothing enforced it until
// 03bdc76. Only the symmetric kind, since the target holding
// `blocked by <this>` is a cycle rather than a duplicate.
let mirrored = kind.is_symmetric()
&& parse_relations(&target, &target_title)?
.contains(&Relation { kind, target: uuid.clone() });
// Already held, either in the file, at the far end, or earlier in this call.
// Recording it twice would read as two dependencies on one ticket.
if existing.contains(&relation) || items.contains(&relation.item()) || mirrored {
continue;
}
@@ -1136,15 +1242,74 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
}
}
if items.is_empty() {
let mut dropped: Vec<Relation> = Vec::new();
let mut cleared: Vec<&str> = Vec::new();
for (kind, search) in asked {
let Some(relation) = find_relation(&existing, kind, search, &title, &worklane_dir)? else {
continue;
};
// Both directions in one call, the way `set --clear` refuses a field it is also
// replacing: nothing is written rather than one of the two silently winning.
if requested.contains(&relation) {
return Err(anyhow!(
"--{} and --clear {} name the same relation to '{}', so nothing was written",
kind.flag(),
kind.flag(),
short_id(&relation.target)
));
}
if dropped.contains(&relation) {
continue;
}
dropped.push(relation);
if !cleared.contains(&kind.label()) {
cleared.push(kind.label());
}
}
if items.is_empty() && dropped.is_empty() {
report(&[], &title, "Recorded");
return Ok(());
}
let content = append_section_body(&ensure_section(&original, &RELATIONS), &RELATIONS, &items)?;
// Removals first, by rewriting the section from what is left, then additions appended
// to that. Two passes rather than one rebuild of the whole section: a call with no
// `--clear` then takes exactly the path it always took, and `append_section_body` goes
// on deciding where a new line lands.
let mut content = original.clone();
if !dropped.is_empty() {
let kept: Vec<String> = existing
.iter()
.filter(|held| !dropped.contains(held))
.map(|held| held.item())
.collect();
// The placeholder rather than an empty body when the last edge goes, which is the
// line `add` writes and the line `append` treats as no content, so the section can
// be written to again without it being left above what follows.
content = match kept.is_empty() {
true => clear_section_body(&content, &RELATIONS)?,
false => set_section_body(&content, &RELATIONS, &kept)?,
};
}
if !items.is_empty() {
content = append_section_body(&ensure_section(&content, &RELATIONS), &RELATIONS, &items)?;
}
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
report(&changed, &title, "Recorded");
if !changed.is_empty() {
report(&changed, &title, "Recorded");
}
if !cleared.is_empty() {
report(&cleared, &title, "Cleared");
}
Ok(())
}
@@ -1607,7 +1772,7 @@ pub fn cmd_assign(
Some(old) => CampaignIndex::load(&worklane_dir)?
.get(&old)
.map(|was| was.name().to_string())
.unwrap_or_else(|| "_missing_".to_string()),
.unwrap_or_else(|| MISSING.to_string()),
};
write_entry(
&worklane_dir,
@@ -1615,6 +1780,7 @@ pub fn cmd_assign(
Kind::Campaign,
&change(&before, campaign.name()),
&resolve_actor(actor.as_deref()),
"",
)?;
println!(
+385 -82
View File
@@ -23,7 +23,10 @@ use std::path::{Path, PathBuf};
use anyhow::{Result, anyhow};
use chrono::Local;
use crate::util::{Cell, Color, TIMESTAMP_FORMAT, paint_cells, should_use_colors};
use crate::util::{
Cell, Color, MISSING, TIMESTAMP_FORMAT, is_unknown_value, paint_cells, should_use_colors,
tag_cells, tag_color,
};
/// Where a ticket's history lives, under the board.
///
@@ -123,6 +126,10 @@ pub struct Entry {
pub time: String,
/// A comment's text, or the before and after of the field a mechanical entry names.
pub body: String,
/// Why a mechanical entry happened, as `mv --reason` gave it. Empty for every entry
/// that carries no such field, which is all of them but a reasoned move — including
/// every entry written before reasons existed.
pub reason: String,
}
/// Rename an old `comments` directory to `history`, before anything reads or writes it.
@@ -187,12 +194,23 @@ fn parse_entry(filename: &str, content: &str) -> Entry {
})
.unwrap_or("");
// A missing reason is legitimate rather than unreadable, which is why this does not
// share the `unknown` fallback the two fields above carry: every entry written
// before `mv --reason` existed has none.
let reason = content
.lines()
.find_map(|line| line.strip_prefix("**Reason**:"))
.map(str::trim)
.unwrap_or_default()
.to_string();
Entry {
filename: filename.to_string(),
kind,
author: field("Author"),
time: field("Time"),
body: body.to_string(),
reason,
}
}
@@ -267,19 +285,27 @@ pub fn count_comments(board: &Path, uuid: &str) -> usize {
///
/// A comment's file is byte for byte what `comment` wrote before the kinds existed, so
/// nothing has to be rewritten and a board can be read by either version.
fn entry_content(kind: Kind, body: &str, author: &str, time: &str) -> String {
format!(
///
/// The optional reason rides after **Time**, so the two fields every entry has always
/// carried keep their places and an older binary reading this file finds its body and
/// fields exactly where they were. Empty writes no line, which is what keeps a reasoned
/// entry and one without reading as the same shape minus the field.
fn entry_content(kind: Kind, body: &str, author: &str, time: &str, reason: &str) -> String {
let mut content = format!(
"{}\n\
{}\n\
\n\
**Author**: {}\n\
**Time**: {}\n\
",
{}\n\
\n\
**Author**: {}\n\
**Time**: {}\n",
kind.marker(),
body,
author,
time
)
);
if !reason.is_empty() {
content.push_str(&format!("**Reason**: {}\n", reason));
}
content
}
/// Write an entry under the first free name derived from the stamp.
@@ -318,12 +344,16 @@ fn write_new(dir: &Path, stem: &str, content: &str) -> Result<String> {
/// move that was refused would be a log of things that did not happen. The cost of that
/// order is that a failed write here leaves the edit in place and reports the failure,
/// which is the right way round — the ticket is the record and this is the story of it.
///
/// `reason` is the why [`Kind::Status`] can carry, from `mv --reason`; every other kind
/// passes the empty slice and gets no field written.
pub fn write_entry(
board: &Path,
uuid: &str,
kind: Kind,
body: &str,
author: &str,
reason: &str,
) -> Result<String> {
adopt_comments(board)?;
@@ -332,18 +362,38 @@ pub fn write_entry(
let now = Local::now();
let stem = format!("{}_{}", now.format(ENTRY_FILE_FORMAT), kind.slug());
let content = entry_content(kind, body, author, &now.format(TIMESTAMP_FORMAT).to_string());
let content =
entry_content(kind, body, author, &now.format(TIMESTAMP_FORMAT).to_string(), reason);
write_new(&dir, &stem, &content)
}
/// What joins the two halves of a mechanical body, and the only thing that tells them
/// apart.
///
/// Spelled once, beside the writer that puts it in and the reader that takes it out, so
/// the two cannot disagree about where one value ends and the next begins. A renderer
/// carrying its own copy of the spacing would go on splitting on a separator this one no
/// longer writes, and would say so by drawing a whole body as one half.
const CHANGE_SEPARATOR: &str = " → ";
/// What a mechanical entry records: the field before the edit and after it.
///
/// The values as the ticket holds them, sentinels included, so `_Not set_` reads the way
/// the field it came from does rather than being translated into a word this module
/// invented.
pub fn change(before: &str, after: &str) -> String {
format!("{} → {}", before, after)
format!("{}{}{}", before, CHANGE_SEPARATOR, after)
}
/// The before and after of a mechanical body, or `None` for a body not shaped as one.
///
/// Everything [`change`] writes splits, but an entry read off a board is whatever the
/// file holds, and a body that does not split is drawn whole rather than as a half of
/// something. `split_once`, so a value that carries the arrow itself keeps it: only the
/// first separator is the one this module wrote.
fn split_change(body: &str) -> Option<(&str, &str)> {
body.split_once(CHANGE_SEPARATOR)
}
pub fn format_history(entries: &[Entry]) -> String {
@@ -355,6 +405,67 @@ pub fn format_history_with(entries: &[Entry], colored: bool) -> String {
paint_cells(&history_cells(entries), colored)
}
/// How far the reason under a mechanical row sits from the margin.
///
/// One step, which is where a comment's body used to sit too. It stays here because the
/// reason belongs to the row above it: it is read as part of that transition, not as an
/// entry of its own.
const REASON_INDENT: &str = " ";
/// How far a comment's body sits from the margin.
///
/// One step deeper than a reason, so the column says who is talking: a line indented this
/// far is somebody's own words and a line of values at column 0 is the tool reporting
/// itself. The author line stays at column 0 and is told from a mechanical row by its
/// `From` and its colour instead, which is the trade this shape accepts.
const COMMENT_INDENT: &str = " ";
/// The cells one value in a mechanical body is drawn as, per the Color Guideline.
///
/// Keyed on the kind, because the kind is what says which field the value came from: the
/// same word is a status in one entry and a tag in another, and nothing in the value
/// itself could tell them apart. Every meaning here is the one the value already carries
/// in the metadata table three lines above, which is the whole point — the block is not
/// worth scanning if it has a palette of its own to learn first.
fn value_cells(kind: Kind, value: &str) -> Vec<Cell> {
// The sentinels first, whichever field they stand in. `_Not set_` in a tag colour
// would read as a campaign somebody named that, and grey is what an absent value is
// drawn in everywhere else. `_missing_` joins them here rather than in
// `is_unknown_value`: the field was set, and what it pointed at is gone.
if is_unknown_value(value) || value == MISSING {
return vec![Cell::colored(value, Color::Grey)];
}
match kind {
Kind::Status => vec![Cell::colored(value, Color::Orange)],
Kind::Tags => tag_cells(value),
// The codename in the colour that groups it everywhere else, and without the `~`
// a card's label carries: the kind at the head of the row has already said what
// this is, which is the same reason the `Codename` field takes the colour bare.
Kind::Campaign => vec![Cell::colored(value, tag_color(value))],
// A name is a value the palette has no meaning for, and spending one on the field
// that needs it least is how a colour stops meaning anything. `Comment` is here
// for the compiler: a comment's body is not a value and never reaches this.
Kind::Owner | Kind::Comment => vec![Cell::plain(value)],
}
}
/// Who wrote an entry and when, as two spans rather than one.
///
/// The actor through `tag_color`, the way a campaign codename is drawn. Not a new meaning
/// for a reserved colour but the existing use of the tag slots — a name that groups rows
/// — and it is what lets a reader see who has been working a ticket without reading the
/// same name four times. Cyan goes back to meaning the timestamp alone, which is what it
/// means everywhere else; it covered the name too while the two were one string.
fn stamp_cells(entry: &Entry) -> Vec<Cell> {
vec![
Cell::colored(entry.author.as_str(), tag_color(&entry.author)),
Cell::plain(" ("),
Cell::colored(entry.time.as_str(), Color::Cyan),
Cell::plain(")"),
]
}
/// The block laid out once, as [`Cell`]s: the CLI paints them and the board turns the
/// same ones into styled spans, so the two views cannot draw two different blocks.
pub fn history_cells(entries: &[Entry]) -> Vec<Cell> {
@@ -369,28 +480,54 @@ pub fn history_cells(entries: &[Entry]) -> Vec<Cell> {
for entry in entries {
cells.push(Cell::plain("\n"));
let stamp = format!("{} ({})", entry.author, entry.time);
match entry.kind {
// As it has always read: a header naming who said it, then the text.
Kind::Comment => {
cells.push(Cell::colored(format!("From {}", stamp), Color::Cyan));
// Grey on the word, for the reason the kind label is grey: `From` names
// the line, it is not a value in it.
cells.push(Cell::colored("From", Color::Grey));
cells.push(Cell::plain(" "));
cells.extend(stamp_cells(entry));
cells.push(Cell::plain("\n"));
if !entry.body.is_empty() {
cells.push(Cell::plain(format!(" {}", entry.body)));
cells.push(Cell::plain(format!("{}{}", COMMENT_INDENT, entry.body)));
}
cells.push(Cell::plain("\n"));
}
// One line: a field change is one fact and a paragraph for it would bury the
// comments it sits between.
// comments it sits between. A reason grows an indented line under the row,
// the way a comment's text sits under its From header, so it reads as
// attached to the transition it explains rather than as the next entry.
_ => {
let padding = Kind::LABEL_WIDTH.saturating_sub(entry.kind.slug().chars().count());
cells.push(Cell::colored(entry.kind.slug(), Color::Orange));
// Grey, as chrome. It was orange, which means Status everywhere else, so
// an `owner` or `tags` label claimed a meaning belonging to the value
// beside it. The label is not a value at all: it names the row, which is
// what grey already says.
cells.push(Cell::colored(entry.kind.slug(), Color::Grey));
// Measured on the unpainted label and carried in a cell of its own, the
// rule the metadata table follows: measuring a painted string counts its
// escapes towards its width, which tilts the column when colour is on and
// not when it is off.
cells.push(Cell::plain(format!("{} ", " ".repeat(padding))));
cells.push(Cell::plain(entry.body.clone()));
match split_change(&entry.body) {
Some((before, after)) => {
cells.extend(value_cells(entry.kind, before));
cells.push(Cell::plain(CHANGE_SEPARATOR));
cells.extend(value_cells(entry.kind, after));
}
None => cells.extend(value_cells(entry.kind, &entry.body)),
}
cells.push(Cell::plain(" "));
cells.push(Cell::colored(stamp, Color::Cyan));
cells.extend(stamp_cells(entry));
cells.push(Cell::plain("\n"));
if !entry.reason.is_empty() {
cells.push(Cell::plain(format!("{}{}", REASON_INDENT, entry.reason)));
cells.push(Cell::plain("\n"));
}
}
}
}
@@ -401,7 +538,32 @@ pub fn history_cells(entries: &[Entry]) -> Vec<Cell> {
#[cfg(test)]
mod tests {
use super::*;
use crate::util::{Fixture, paint};
use crate::util::{Fixture, NOT_SET, paint};
/// One entry, spelled the way a file on the board holds it.
fn entry(kind: &str, body: &str, author: &str, time: &str) -> Entry {
let marker = format!("**{}{}**", kind[..1].to_uppercase(), &kind[1..]);
parse_entry(
&format!("20260824_120000_000000_{kind}"),
&format!("{marker}\n{body}\n\n**Author**: {author}\n**Time**: {time}\n"),
)
}
/// What a painted block reads as once the escapes are taken off, so a test can
/// measure a column without counting sequences that occupy none.
fn strip_escapes(text: &str) -> String {
let mut out = String::with_capacity(text.len());
let mut rest = text;
while let Some(at) = rest.find('\x1b') {
out.push_str(&rest[..at]);
match rest[at..].find('m') {
Some(end) => rest = &rest[at + end + 1..],
None => return out,
}
}
out.push_str(rest);
out
}
fn board() -> Fixture {
Fixture::new("worklane-history")
@@ -411,7 +573,8 @@ mod tests {
fn an_entry_names_its_kind_in_the_file_and_in_the_filename() {
let board = board();
let filename =
write_entry(&board, "uuid", Kind::Status, "committed → reviewing", "claude").unwrap();
write_entry(&board, "uuid", Kind::Status, "committed → reviewing", "claude", "")
.unwrap();
assert!(filename.ends_with("_status.md"), "was {filename}");
@@ -420,6 +583,37 @@ mod tests {
assert_eq!(entries[0].kind, Kind::Status);
assert_eq!(entries[0].body, "committed → reviewing");
assert_eq!(entries[0].author, "claude");
assert_eq!(entries[0].reason, "");
}
/// One file, one event, its explanation: the reason rides in the entry that records
/// the transition it explains, as a field after **Time**, and round-trips.
#[test]
fn a_reason_is_recorded_in_the_file_and_read_back() {
let board = board();
let filename = write_entry(
&board,
"uuid",
Kind::Status,
"reviewing → backlog",
"claude",
"sent back: the first plan was wrong",
)
.unwrap();
let content = fs::read_to_string(history_dir(&board, "uuid").join(filename)).unwrap();
assert!(
content.ends_with("**Reason**: sent back: the first plan was wrong\n"),
"{content}"
);
// The fields every reader keys off keep their places above it
assert!(content.contains("**Time**:"), "{content}");
assert!(content.find("**Author**").unwrap() < content.find("**Reason**").unwrap());
let entries = read_history(&board, "uuid").unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].body, "reviewing → backlog");
assert_eq!(entries[0].reason, "sent back: the first plan was wrong");
}
/// The stamp leads the name and is fixed width, so the kind that follows it cannot
@@ -464,7 +658,7 @@ mod tests {
/// is what lets an old board be read without a migration.
#[test]
fn a_comment_file_is_shaped_as_it_always_was() {
let content = entry_content(Kind::Comment, "A body", "claude", "2026-08-24 12:00:00");
let content = entry_content(Kind::Comment, "A body", "claude", "2026-08-24 12:00:00", "");
assert_eq!(
content,
"**Comment**\nA body\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
@@ -535,10 +729,10 @@ mod tests {
#[test]
fn only_comments_are_counted() {
let board = board();
write_entry(&board, "uuid", Kind::Comment, "said", "claude").unwrap();
write_entry(&board, "uuid", Kind::Status, "backlog → committed", "claude").unwrap();
write_entry(&board, "uuid", Kind::Owner, "_Not set_ → alice", "claude").unwrap();
write_entry(&board, "uuid", Kind::Tags, "bug → bug, cli", "claude").unwrap();
write_entry(&board, "uuid", Kind::Comment, "said", "claude", "").unwrap();
write_entry(&board, "uuid", Kind::Status, "backlog → committed", "claude", "").unwrap();
write_entry(&board, "uuid", Kind::Owner, "_Not set_ → alice", "claude", "").unwrap();
write_entry(&board, "uuid", Kind::Tags, "bug → bug, cli", "claude", "").unwrap();
assert_eq!(read_history(&board, "uuid").unwrap().len(), 4);
assert_eq!(count_comments(&board, "uuid"), 1);
@@ -553,75 +747,185 @@ mod tests {
assert_eq!(kind_from_stem("20260820_143012_123456_status_01"), Kind::Status);
}
/// The other half of the pair below: with colour off the block is words and spaces,
/// and the flag is the only thing that decides. A renderer that painted regardless
/// would pass the pin and fail here.
#[test]
fn a_mechanical_entry_renders_as_one_line_and_a_comment_as_it_did() {
fn a_mechanical_entry_renders_as_one_line_and_a_comment_under_its_author() {
let entries = vec![
parse_entry(
"20260824_120000_000000_status",
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
),
parse_entry(
"20260824_120001_000000_comment",
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
entry("status", "committed → reviewing", "claude", "2026-08-24 12:00:00"),
entry("owner", "_Not set_ → alice", "claude", "2026-08-24 12:00:01"),
entry("tags", "bug → bug, cli", "claude", "2026-08-24 12:00:02"),
entry("campaign", "_Not set_ → v1", "claude", "2026-08-24 12:00:03"),
entry(
"comment",
"The offset was never passed",
"Ansho Rei",
"2026-08-24 12:00:04",
),
];
let rendered = format_history_with(&entries, false);
assert!(rendered.contains("HISTORY"), "{rendered}");
assert!(
rendered.contains("status committed → reviewing claude (2026-08-24 12:00:00)\n"),
"{rendered}"
);
for row in [
"status committed → reviewing claude (2026-08-24 12:00:00)\n",
"owner _Not set_ → alice claude (2026-08-24 12:00:01)\n",
"tags bug → bug, cli claude (2026-08-24 12:00:02)\n",
"campaign _Not set_ → v1 claude (2026-08-24 12:00:03)\n",
] {
assert!(rendered.contains(row), "missing {row:?} in {rendered}");
}
// The body sits a step deeper than a reason does, and the author line did not move
assert!(
rendered
.contains("From Ansho Rei (2026-08-24 12:00:01)\n The offset was never passed"),
.contains("From Ansho Rei (2026-08-24 12:00:04)\n The offset was never passed"),
"{rendered}"
);
assert!(!rendered.contains('\x1b'), "colour off still painted: {rendered:?}");
}
/// The pin for the cells conversion: `show` prints the block exactly as it printed
/// it before, every painted run spelled out, the way
/// `show_prints_the_same_body_it_printed_before_the_cells_conversion` pins the body.
/// The pin: `show` prints the block byte for byte, every painted run spelled out, the
/// way `show_prints_the_same_body_it_printed_before_the_cells_conversion` pins the
/// body.
///
/// Updated once since, deliberately: `campaign` widened the label column from 6 to
/// 8, and the campaign row itself joined the pin (f774a33).
/// Rewritten twice, deliberately. `campaign` widened the label column from 6 to 8 and
/// put its own row in the pin (f774a33). Then 2733b10 painted the values: the label
/// went grey as chrome, each value took the meaning it carries in the metadata table,
/// and the actor and the timestamp came apart into two spans.
///
/// Every kind is here rather than a representative one, since what each row proves is
/// different: status is the orange it is three lines above, tags go through the same
/// `tag_cells` the Tags field does, campaign takes its codename's colour, owner is the
/// one value the palette says nothing about, and the sentinel in the owner row is grey
/// on the same side of an arrow whose other side is not.
#[test]
fn show_prints_the_same_history_it_printed_before_the_cells_conversion() {
fn colour_on_paints_every_value_by_what_the_kind_says_it_is() {
let entries = vec![
parse_entry(
"20260824_120000_000000_status",
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
),
parse_entry(
"20260824_120001_000000_comment",
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
),
parse_entry(
"20260824_120002_000000_campaign",
"**Campaign**\n_Not set_ → v1\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:02\n",
entry("status", "committed → reviewing", "claude", "2026-08-24 12:00:00"),
entry(
"comment",
"The offset was never passed",
"Ansho Rei",
"2026-08-24 12:00:01",
),
entry("campaign", "_Not set_ → v1", "claude", "2026-08-24 12:00:02"),
entry("owner", "_Not set_ → alice", "claude", "2026-08-24 12:00:03"),
entry("tags", "bug → bug, cli", "claude", "2026-08-24 12:00:04"),
];
let stamp = |actor: &str, time: &str| {
format!(
"{} ({})",
paint(actor, tag_color(actor), true),
paint(time, Color::Cyan, true)
)
};
let expected = format!(
"\n{}\n{}\n\n{} committed → reviewing {}\n\n{}\n The offset was never passed\n\n{} _Not set_ → v1 {}\n",
"\n{}\n{}\n\n{} {} → {} {}\n\n{} {}\n The offset was never passed\n\n{} {} → {} {}\n\n{} {} → alice {}\n\n{} {} → {}, {} {}\n",
paint("HISTORY", Color::Orange, true),
"─".repeat(20),
paint("status", Color::Orange, true),
paint("claude (2026-08-24 12:00:00)", Color::Cyan, true),
paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true),
paint("campaign", Color::Orange, true),
paint("claude (2026-08-24 12:00:02)", Color::Cyan, true),
paint("status", Color::Grey, true),
paint("committed", Color::Orange, true),
paint("reviewing", Color::Orange, true),
stamp("claude", "2026-08-24 12:00:00"),
paint("From", Color::Grey, true),
stamp("Ansho Rei", "2026-08-24 12:00:01"),
paint("campaign", Color::Grey, true),
paint(NOT_SET, Color::Grey, true),
paint("v1", tag_color("v1"), true),
stamp("claude", "2026-08-24 12:00:02"),
paint("owner", Color::Grey, true),
paint(NOT_SET, Color::Grey, true),
stamp("claude", "2026-08-24 12:00:03"),
paint("tags", Color::Grey, true),
paint("bug", tag_color("bug"), true),
paint("bug", tag_color("bug"), true),
paint("cli", tag_color("cli"), true),
stamp("claude", "2026-08-24 12:00:04"),
);
assert_eq!(format_history_with(&entries, true), expected);
assert_eq!(format_history_with(&[], true), paint("No history yet.", Color::Grey, true));
}
/// The actor groups its rows: one writer is one colour wherever it wrote, and it is
/// not the timestamp's. Asserted through `tag_color` rather than against a literal,
/// so the row has to use the mapping and not a colour that happens to match it today.
#[test]
fn the_actor_is_one_colour_in_every_entry_and_the_timestamp_keeps_cyan() {
let entries = vec![
entry("status", "backlog → committed", "claude", "2026-08-24 12:00:00"),
entry("comment", "Said something", "claude", "2026-08-24 12:00:01"),
entry("owner", "_Not set_ → alice", "Ansho Rei", "2026-08-24 12:00:02"),
];
let rendered = format_history_with(&entries, true);
let painted = paint("claude", tag_color("claude"), true);
assert_eq!(rendered.matches(&painted).count(), 2, "{rendered}");
assert!(
rendered.contains(&paint("Ansho Rei", tag_color("Ansho Rei"), true)),
"{rendered}"
);
// Two writers, two colours, and neither of them cyan: that is the timestamp's
assert_ne!(tag_color("claude"), tag_color("Ansho Rei"));
for time in [
"2026-08-24 12:00:00",
"2026-08-24 12:00:01",
"2026-08-24 12:00:02",
] {
assert!(rendered.contains(&paint(time, Color::Cyan, true)), "{rendered}");
}
assert!(!rendered.contains(&paint("claude (", Color::Cyan, true)), "still one span");
}
/// The reason is the row's, so it renders indented under the row it explains and
/// before whatever entry follows, in both renderers — this is the one layout they
/// share. Paired with the pin above: an entry without a reason renders exactly as
/// it always did.
#[test]
fn a_reason_renders_indented_under_its_row() {
let entries = vec![
parse_entry(
"20260824_120000_000000_status",
"**Status**\nreviewing → backlog\n\n**Author**: claude\n**Time**: 2026-08-24 \
12:00:00\n**Reason**: sent back, the first plan was wrong\n",
),
entry("comment", "And why.", "Ansho Rei", "2026-08-24 12:00:01"),
];
let expected = format!(
"\n{}\n{}\n\n{} {} → {} {} ({})\n sent back, the first plan was wrong\n\n{} {} ({})\n And why.\n",
paint("HISTORY", Color::Orange, true),
"─".repeat(20),
paint("status", Color::Grey, true),
paint("reviewing", Color::Orange, true),
paint("backlog", Color::Orange, true),
paint("claude", tag_color("claude"), true),
paint("2026-08-24 12:00:00", Color::Cyan, true),
paint("From", Color::Grey, true),
paint("Ansho Rei", tag_color("Ansho Rei"), true),
paint("2026-08-24 12:00:01", Color::Cyan, true),
);
assert_eq!(format_history_with(&entries, true), expected);
assert!(
format_history_with(&entries, false)
.contains("claude (2026-08-24 12:00:00)\n sent back, the first plan was wrong"),
"colour off lost the reason: {}",
format_history_with(&entries, false)
);
}
/// Padded to the longest of the four, so every body starts in the same column
/// however short the label above it is.
///
/// Run both ways, which is the whole point of the pairing: the padding is measured on
/// the unpainted label and carried in a cell of its own, so the column a value lands
/// in cannot depend on the colour decision. Measuring a painted label would count its
/// escapes towards its width and tilt the table with colour on and not with it off,
/// which is exactly the bug the metadata table already learned.
#[test]
fn the_mechanical_labels_are_aligned() {
fn the_mechanical_labels_are_aligned_with_colour_on_and_off() {
let bodies = [
("status", "backlog → committed"),
("owner", "_Not set_ → alice"),
@@ -630,28 +934,27 @@ mod tests {
];
let entries: Vec<Entry> = bodies
.into_iter()
.map(|(kind, body)| {
let marker = format!("**{}{}**", kind[..1].to_uppercase(), &kind[1..]);
parse_entry(
&format!("20260824_120000_000000_{kind}"),
&format!(
"{marker}\n{body}\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
),
)
})
.map(|(kind, body)| entry(kind, body, "claude", "2026-08-24 12:00:00"))
.collect();
let rendered = format_history_with(&entries, false);
let columns: Vec<usize> = bodies
.into_iter()
.map(|(_, body)| rendered.find(body).expect("body missing"))
.map(|at| {
let line_start = rendered[..at].rfind('\n').map_or(0, |nl| nl + 1);
at - line_start
})
.collect();
assert_eq!(columns.len(), 4);
assert!(columns.windows(2).all(|pair| pair[0] == pair[1]), "{rendered}");
let columns = |colored: bool| -> Vec<usize> {
// Stripped before it is measured, so an escape counts for the nothing it
// occupies on screen and the two renderings are compared on what a reader sees
let rendered = strip_escapes(&format_history_with(&entries, colored));
bodies
.into_iter()
.map(|(_, body)| rendered.find(body).expect("body missing"))
.map(|at| {
let line_start = rendered[..at].rfind('\n').map_or(0, |nl| nl + 1);
at - line_start
})
.collect()
};
let plain = columns(false);
assert_eq!(plain.len(), 4);
assert!(plain.windows(2).all(|pair| pair[0] == pair[1]), "{plain:?}");
assert_eq!(columns(true), plain, "the colour decision moved the column");
}
#[test]
+10 -5
View File
@@ -57,9 +57,13 @@ fn main() -> Result<()> {
let worklane_dir = find_worklane_dir(&start)?;
cmd_show(&id, &worklane_dir)
}
Some(Command::Mv { ticket, status, force, actor }) => {
cmd_mv(&ticket, status, force, &actor, &start)
}
Some(Command::Mv {
ticket,
status,
force,
actor,
reason,
}) => cmd_mv(&ticket, status, force, &actor, &reason, &start),
Some(Command::Set(args)) => cmd_set(&args, &start),
Some(Command::Append(args)) => cmd_append(&args, &start),
Some(Command::Relate(args)) => cmd_relate(&args, &start),
@@ -238,8 +242,9 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
// columns took hjkl and the arrows.
KeyCode::Tab => board.select_tab(1, screen),
KeyCode::BackTab => board.select_tab(-1, screen),
// Free of the other bindings, and the footer names it in both states.
KeyCode::Char('d') => board.toggle_done(screen),
// Free of the other bindings, and the footer names what the next press
// does in every state of the rotation.
KeyCode::Char('d') => board.rotate_visibility(screen),
// An ordinary single-shot action like the rest: it opens the prompt, and
// from the next keypress on `search_key` above has the keyboard. A `/`
// typed into an open prompt is taken there as a character, and one pressed
+1138 -333
View File
File diff suppressed because it is too large Load Diff
+481 -38
View File
@@ -245,13 +245,55 @@ impl From<Color> for ratatui::style::Color {
}
}
/// The escape that closes a run, whatever was opened: a colour, a modifier or both.
///
/// One spelling for the two writers. `paint` opens a colour and `paint_cell` may open a
/// modifier ahead of it, and a reset that only knew about the colour would leave the
/// strikethrough running to the end of the line.
pub const RESET: &str = "\x1b[0m";
/// A style that is not a colour, which is the other half of what a [`Cell`] carries.
///
/// An enum with one variant rather than a `bool`, for the reason the palette is an enum:
/// the CLI needs an SGR sequence and the board needs a `ratatui` modifier, so a style
/// that exists for one renderer and not the other is a compile error. Bold is not here,
/// because bold rides inside `Color::Magenta.ansi()` and is added back on the board's
/// side from the colour alone; a second modifier would be added here beside this one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Modifier {
/// What a row about a discarded ticket is drawn with: the relation is still
/// recorded, and no longer stands for anything.
Strikethrough,
}
impl Modifier {
/// The SGR sequence the CLI writes. Closed by [`RESET`], like a colour.
pub fn ansi(self) -> &'static str {
match self {
Modifier::Strikethrough => "\x1b[9m",
}
}
}
/// The same modifier as ratatui sees it, the other half of [`Modifier::ansi`].
///
/// SGR 9 and `CROSSED_OUT` are the same request, so the two renderers cannot come to
/// draw one struck row and one plain one.
impl From<Modifier> for ratatui::style::Modifier {
fn from(modifier: Modifier) -> Self {
match modifier {
Modifier::Strikethrough => ratatui::style::Modifier::CROSSED_OUT,
}
}
}
/// `color_text` with the decision passed in rather than asked for.
///
/// The seam matters for anything that aligns columns: a caller has to be able to
/// render both ways in one process to prove the padding does not depend on it.
pub fn paint(text: &str, color: Color, enabled: bool) -> String {
if enabled {
format!("{}{}{}", color.ansi(), text, "\x1b[0m")
format!("{}{}{}", color.ansi(), text, RESET)
} else {
text.to_string()
}
@@ -722,11 +764,15 @@ impl Body {
self.push_cell(Cell::plain(c.to_string()));
}
/// One run, merged into the trailing cell when it is the same colour.
/// One run, merged into the trailing cell when it is drawn the same way.
///
/// Merging is not an optimisation. The board draws a span per cell, and the body is
/// pushed a character at a time in places, so without this a plain line arrives as
/// forty single-character spans for ratatui to wrap.
///
/// On the whole style and not the colour alone: nothing outside the relations block
/// carries a modifier today, and a merge keyed on the colour would silently strike a
/// plain run through the moment one did.
fn push_cell(&mut self, cell: Cell) {
if cell.text.is_empty() {
return;
@@ -734,7 +780,9 @@ impl Body {
match self.parts.last_mut() {
Some(BodyPart::Cells(cells)) => match cells.last_mut() {
Some(last) if last.color == cell.color => last.text.push_str(&cell.text),
Some(last) if last.color == cell.color && last.modifier == cell.modifier => {
last.text.push_str(&cell.text)
}
_ => cells.push(cell),
},
_ => self.parts.push(BodyPart::Cells(vec![cell])),
@@ -1006,7 +1054,11 @@ fn metadata_value_cells(name: &str, value: &str, campaign: &[Cell]) -> Vec<Cell>
/// holds come back unchanged. `bug, cli` and `bug,cli` are both written by hand at some
/// point, and a cell that normalised them would be the display quietly disagreeing with
/// the file it is showing.
fn tag_cells(value: &str) -> Vec<Cell> {
///
/// Shared with the history block, which draws the two halves of a tags entry through it:
/// a tag list is a tag list wherever it is printed, and the alternative was a second
/// splitter that would drift from this one the first time either changed.
pub(crate) fn tag_cells(value: &str) -> Vec<Cell> {
let mut cells = Vec::new();
for (index, piece) in value.split(',').enumerate() {
@@ -1091,6 +1143,15 @@ pub const NOT_SET: &str = "_Not set_";
/// distinction `add` already makes and clearing has to keep.
pub const NONE: &str = "_None_";
/// What stands in for something the board no longer holds.
///
/// Not an unset value, so [`is_unknown_value`] does not read it: a field pointing at a
/// campaign that has been removed is set, and what it is set to is gone. Drawn in the
/// same grey all the same, which is what it shares with an unset value and why the
/// spelling is a constant — the relations block writes it, `assign` records it in a
/// history entry, and the two have to be the same word for the third place to paint it.
pub const MISSING: &str = "_missing_";
/// Whether a field holds one of the two markers that mean it holds nothing.
///
/// The two constants and nothing else. `-None-` and `-Not set-` were accepted here from
@@ -2062,12 +2123,61 @@ impl RelationKind {
}
}
/// Whether the kind reads the same from both ends, which is `relates to` alone.
///
/// Derived from the two labels rather than listed, so a kind added later answers this
/// by construction. A symmetric kind is the only one whose derived row can collide
/// with its own stored line: `blocked by` from one end reads as `blocks` from the
/// other, and those are two different things to say about one pair of tickets.
pub fn is_symmetric(self) -> bool {
self.label() == self.inverse_label()
}
/// Every kind, so a caller can walk them without listing them a second time.
pub const ALL: [RelationKind; 3] = [
RelationKind::BlockedBy,
RelationKind::RegressionOf,
RelationKind::RelatesTo,
];
/// How the kind is spelled at the command line: the flag that records it, without
/// the leading hyphens.
///
/// A match rather than `label().replace(' ', "-")`, so the pairing is pinned and the
/// completion list, the `--clear` value and the flag cannot drift apart.
pub fn flag(self) -> &'static str {
match self {
RelationKind::BlockedBy => "blocked-by",
RelationKind::RegressionOf => "regression-of",
RelationKind::RelatesTo => "relates-to",
}
}
/// One kind from the value `relate --clear` names, or an error listing the three.
///
/// Both spellings are accepted, the flag's `blocked-by` and the label's `blocked by`,
/// because both are in front of the reader: the flag is what recorded the relation and
/// the label is what `show` prints in the block and what the file stores. Refusing the
/// form the tool itself prints would be a trap for anyone clearing a row they just
/// read. Case insensitive, the bargain the id and codename tiers already take.
pub fn parse_value(value: &str) -> Result<Self> {
let wanted = value.trim().to_lowercase().replace('-', " ");
RelationKind::ALL
.into_iter()
.find(|kind| kind.label() == wanted)
.ok_or_else(|| {
anyhow!(
"'{}' is not a relation kind. The kinds are {}",
value,
RelationKind::ALL
.iter()
.map(|kind| kind.flag())
.collect::<Vec<_>>()
.join(", ")
)
})
}
}
/// One stored edge: a kind, and the full uuid of the ticket it points at.
@@ -2247,7 +2357,7 @@ pub fn reference_cells(uuid: &str, name: Option<&str>) -> Vec<Cell> {
match name {
Some(name) => cells.push(Cell::plain(name)),
None => cells.push(Cell::colored("_missing_", Color::Grey)),
None => cells.push(Cell::colored(MISSING, Color::Grey)),
}
cells
@@ -2255,13 +2365,38 @@ pub fn reference_cells(uuid: &str, name: Option<&str>) -> Vec<Cell> {
/// Cells as the CLI prints them: each one painted, or carried through as it stands.
pub fn paint_cells(cells: &[Cell], colored: bool) -> String {
cells
.iter()
.map(|cell| match cell.color {
Some(color) => paint(&cell.text, color, colored),
None => cell.text.clone(),
})
.collect()
cells.iter().map(|cell| paint_cell(cell, colored)).collect()
}
/// One cell as an escape sequence, its modifier ahead of its colour and one [`RESET`]
/// closing both.
///
/// The modifier is under the same flag the colour is, so a piped `show` and the board's
/// own unpainted pass carry no escape at all, per the guideline: a function that takes
/// an `enabled` flag has to use it all the way down. The cost is that a pipe cannot see
/// a struck row, the same bargain committed and reviewing already take for being told
/// apart by colour alone.
fn paint_cell(cell: &Cell, colored: bool) -> String {
if !colored {
return cell.text.clone();
}
// Built rather than matched over the four combinations: either half may be absent,
// and a cell with neither has to come back byte for byte as it went in, since the
// CLI's output is pinned against what it printed before the cells conversion.
let mut opened = String::new();
if let Some(modifier) = cell.modifier {
opened.push_str(modifier.ansi());
}
if let Some(color) = cell.color {
opened.push_str(color.ansi());
}
if opened.is_empty() {
return cell.text.clone();
}
format!("{opened}{}{RESET}", cell.text)
}
/// The mark a blocking relation carries, and a card waiting on one.
@@ -2382,19 +2517,39 @@ pub struct RelationTarget {
pub struct Cell {
pub text: String,
pub color: Option<Color>,
/// The style that is not the colour, `None` for text drawn as it stands. Kept
/// beside the colour rather than folded into it: a struck run keeps whatever colour
/// its column already gave it, so the two are independent.
pub modifier: Option<Modifier>,
}
impl Cell {
pub fn plain(text: impl Into<String>) -> Self {
Cell { text: text.into(), color: None }
Cell {
text: text.into(),
color: None,
modifier: None,
}
}
pub(crate) fn colored(text: impl Into<String>, color: Color) -> Self {
Cell {
text: text.into(),
color: Some(color),
modifier: None,
}
}
/// The same cell, struck through.
///
/// A builder rather than a third constructor, because the strike is decided a whole
/// row at a time and the cells of that row are built by the layout that already
/// chose their colours. `relation_cells` maps this over the row it has just built,
/// so nothing has to thread the decision through every cell it makes.
pub(crate) fn struck(mut self) -> Self {
self.modifier = Some(Modifier::Strikethrough);
self
}
}
/// The relations of one ticket, both directions, in the order they are shown.
@@ -2424,10 +2579,30 @@ pub fn relation_rows(stored: &[Relation], index: &RelationIndex, uuid: &str) ->
})
.collect();
// How each stored row reads, which is what a derived row is checked against below.
// Collected first because the check cannot borrow `rows` while extending it.
let drawn: Vec<(&'static str, String)> =
rows.iter().map(|row| (row.label, row.uuid.clone())).collect();
rows.extend(
index
.inbound(uuid)
// A derived row that reads exactly like a stored one is not a second fact.
// Both ends of a symmetric relation can hold a line, since nothing stopped
// that until 03bdc76, and the block drew the same neighbour twice under the
// same label. The stored row is the one kept: it is the line `--clear` can
// address, where the derived one is on a file this ticket does not own.
//
// Keyed on the label and the target rather than the kind and the target,
// which is what keeps a mutual block as two rows: `blocked by` and `blocks`
// are different things to say about one pair, and only a symmetric kind,
// whose inverse label is its own, can collide with itself.
.into_iter()
.filter(|(kind, holder)| {
!drawn
.iter()
.any(|(label, target)| *label == kind.inverse_label() && *target == holder.uuid)
})
.map(|(kind, holder)| RelationRow {
kind,
label: kind.inverse_label(),
@@ -2455,8 +2630,8 @@ pub fn relation_cells(rows: &[RelationRow]) -> Vec<Vec<Cell>> {
rows.iter()
.map(|row| {
let (kind, kind_colour) = relation_mark(row.kind);
let (status, status_colour) =
status_mark(row.target.as_ref().map(|target| target.status.as_str()));
let status_of = row.target.as_ref().map(|target| target.status.as_str());
let (status, status_colour) = status_mark(status_of);
let padding = " ".repeat(width - row.label.chars().count());
// Kind, then state, then who: what sort of edge this is, how far the ticket
@@ -2476,7 +2651,16 @@ pub fn relation_cells(rows: &[RelationRow]) -> Vec<Vec<Cell>> {
row.target.as_ref().map(|target| target.title.as_str()),
));
cells
// The whole row, gutter and padding included, so the line runs unbroken from
// the label to the end of the title. The strike is what says the target was
// discarded, since the status mark cannot: it is one cell in a column of five
// states, and a row pointing at abandoned work otherwise reads as a live
// dependency, which is exactly what it is not. The relation stays recorded,
// for completeness and for the case the target is moved back out.
match status_of {
Some(DISCARDED) => cells.into_iter().map(Cell::struck).collect(),
_ => cells,
}
})
.collect()
}
@@ -2707,8 +2891,8 @@ pub enum Status {
impl Status {
/// Every status, in flow order with discarded last. The one list, which
/// [`status_dirs`], `mv` and every caller of [`by_status_order`] read rather than
/// spelling the five names again.
/// [`status_dirs`], `mv`, the board's columns and every caller of
/// [`by_status_order`] read rather than spelling the five names again.
pub const ALL: [Status; 5] = [
Status::Backlog,
Status::Committed,
@@ -2717,19 +2901,6 @@ impl Status {
Status::Discarded,
];
/// The stages work moves through: every status but discarded, which work never
/// moves through, it only ends up in.
///
/// What the board draws its columns from, so done stays the last drawn column and
/// hiding it stays a prefix of the list. Showing a discarded column is a136d13's,
/// not a side effect of the status existing.
pub const FLOW: [Status; 4] = [
Status::Backlog,
Status::Committed,
Status::Reviewing,
Status::Done,
];
/// The field `mv` stamps on entering this status, for the four that have one.
///
/// Derived from the status rather than spelled at the call site, so the mapping is
@@ -2762,17 +2933,20 @@ pub fn status_dirs() -> Vec<&'static str> {
Status::ALL.iter().map(|status| status.as_str()).collect()
}
/// The end of the flow, and the one status both views treat differently: `ls` counts it
/// in the summary and leaves it out of the listing, and the board hides its column until
/// asked. Named because that rule now has two readers.
/// The end of the flow, and one of the two statuses both views treat differently: `ls`
/// counts it in the summary and leaves it out of the listing, and the board hides its
/// column until `d` reveals it. Named because that rule now has two readers.
///
/// It is deliberately last in [`Status::FLOW`], which is what the board draws. The board
/// leans on that: hiding done drops the final column, so the other three keep their
/// indices and the selection only has to be handled when it is sitting on done itself.
/// Done and discarded are deliberately the last two in [`Status::ALL`], which is what
/// the board builds its columns from: hiding either is then a prefix of that list, so
/// the columns before them keep their indices and the selection only has to be handled
/// when it is sitting on a column that just went away. Discarded after done is also
/// what lets the stamp arrival rule keep a discard's journey.
pub const DONE: &str = Status::Done.as_str();
/// Where a ticket that will not be done ends up: the other terminal status, and the
/// other one `ls` leaves out of the listing.
/// other one `ls` leaves out of the listing and the board keeps off the screen until
/// asked, last in the rotation because it is the least likely thing to be looking for.
///
/// A discarded ticket counts as finished wherever progress is measured, since nothing is
/// left to do, and blocks nothing. What it is not is done: the two directories keep
@@ -5233,9 +5407,150 @@ Plain line with **bold** and a [link](http://x.test/a).
assert_eq!(status_mark(Some("committed")), ("\u{25d0}", Color::Orange));
assert_eq!(status_mark(Some("reviewing")), ("\u{25d0}", Color::Cyan));
assert_eq!(status_mark(Some("done")), ("\u{25cf}", Color::Green));
assert_eq!(status_mark(Some("discarded")), ("\u{25cf}", Color::Grey));
assert_eq!(status_mark(None), ("?", Color::Grey));
}
/// The strike is what says the target will never be done, because the status mark
/// cannot: it is one cell in a column of five states, and a row pointing at abandoned
/// work otherwise reads as a live dependency, which is exactly what it is not.
///
/// On every cell of the row, gutter and padding included, so the line runs unbroken
/// from the label to the end of the title. A cell left out would draw a gap.
#[test]
fn a_row_pointing_at_a_discarded_target_is_struck_through() {
let rows = vec![row(
RelationKind::BlockedBy,
"blocked by",
TARGET,
"Dropped",
DISCARDED,
)];
let cells = relation_cells(&rows);
assert_eq!(cells.len(), 1, "{cells:?}");
for cell in &cells[0] {
assert_eq!(
cell.modifier,
Some(Modifier::Strikethrough),
"{:?} is not struck, so the line breaks mid row",
cell.text
);
}
// Every run opened, since a cell is closed by its own reset: the CLI writes one
// `\x1b[9m` per cell or the strike stops at the first colour change.
let rendered = render_relations(&rows, true);
assert_eq!(
rendered.matches(Modifier::Strikethrough.ansi()).count(),
cells[0].len(),
"the CLI did not open the strike on every run:\n{rendered:?}"
);
}
/// Only discarded. A row to a live target is drawn as it always was, done included:
/// the strike says the relation no longer stands for anything, and a blocker that
/// landed still stands for the fact that it was one.
///
/// Over `status_dirs` rather than the four names, so a status added later is decided
/// here rather than inheriting the strike or the plain row by accident.
#[test]
fn a_row_to_a_live_target_is_not_struck() {
let live = status_dirs().into_iter().filter(|status| *status != DISCARDED);
for status in live {
let rows = vec![row(
RelationKind::BlockedBy,
"blocked by",
TARGET,
"Alive",
status,
)];
for cell in relation_cells(&rows).concat() {
assert_eq!(cell.modifier, None, "{status} is struck: {:?}", cell.text);
}
assert!(
!render_relations(&rows, true).contains(Modifier::Strikethrough.ansi()),
"{status} is struck through in show"
);
}
}
/// A target the board no longer holds is not struck either. `?` and `_missing_` say
/// the row cannot be resolved, which is a different fact from a target that was
/// resolved and abandoned, and striking both would fold the two together.
#[test]
fn a_row_to_a_missing_target_is_not_struck() {
let rows = vec![RelationRow {
kind: RelationKind::BlockedBy,
label: "blocked by",
uuid: TARGET.to_string(),
target: None,
}];
for cell in relation_cells(&rows).concat() {
assert_eq!(cell.modifier, None, "{:?}", cell.text);
}
}
/// Paired the way the guideline demands, and both halves are load bearing. The strike
/// is an escape sequence like a colour, so it is under the same flag: a piped `show`
/// carries none of it, the same bargain committed and reviewing already take for
/// being told apart by colour alone. A renderer that never struck anything would pass
/// the absence on its own.
#[test]
fn the_strike_is_under_the_colour_flag_like_every_other_escape() {
let rows = vec![row(
RelationKind::BlockedBy,
"blocked by",
TARGET,
"Dropped",
DISCARDED,
)];
assert!(
render_relations(&rows, true).contains(Modifier::Strikethrough.ansi()),
"nothing was struck at all, so the guard below is vacuous"
);
assert!(
!render_relations(&rows, false).contains('\x1b'),
"an escape survived the colour being off: {:?}",
render_relations(&rows, false)
);
}
/// Both halves of the modifier, the way the palette is pinned from both ends. SGR 9
/// and `CROSSED_OUT` are the same request, so one renderer cannot come to draw a
/// struck row plain while the other strikes it.
#[test]
fn the_strikethrough_is_the_same_request_in_both_renderers() {
assert_eq!(Modifier::Strikethrough.ansi(), "\x1b[9m");
assert_eq!(
ratatui::style::Modifier::from(Modifier::Strikethrough),
ratatui::style::Modifier::CROSSED_OUT
);
}
/// The modifier opens ahead of the colour and one reset closes both, which is why the
/// reset is a constant the two writers share. A cell carrying neither comes back byte
/// for byte as it went in, since the CLI's output is pinned against what it printed
/// before the cells conversion.
#[test]
fn a_cell_opens_its_modifier_ahead_of_its_colour_and_closes_once() {
let struck_and_coloured = Cell::colored("x", Color::Red).struck();
assert_eq!(
paint_cells(&[struck_and_coloured], true),
format!("\x1b[9m\x1b[31mx{RESET}")
);
let struck_only = Cell::plain("x").struck();
assert_eq!(paint_cells(&[struck_only], true), format!("\x1b[9mx{RESET}"));
assert_eq!(paint_cells(&[Cell::plain("x")], true), "x");
assert_eq!(paint_cells(&[Cell::plain("x").struck()], false), "x");
}
/// Every status the board holds is told apart from the other three. The shape does
/// not do it alone, since committed and reviewing are both half circles, so it is the
/// pair that has to be unique. Pinned against `status_dirs` rather than the four
@@ -5333,6 +5648,134 @@ Plain line with **bold** and a [link](http://x.test/a).
assert_eq!(seen.len(), 3, "{seen:?}");
}
/// Every kind is reachable by the flag that records it and by the label `show` prints,
/// in any case, and every kind has a flag of its own. Over `RelationKind::ALL` rather
/// than the three names, so a kind added later has to be spellable too.
#[test]
fn a_kind_parses_from_the_flag_spelling_and_the_label_spelling() {
let mut flags = std::collections::HashSet::new();
for kind in RelationKind::ALL {
assert!(flags.insert(kind.flag()), "{kind:?} shares its flag with another kind");
assert_eq!(kind.flag(), kind.label().replace(' ', "-"), "{kind:?}");
for spelling in [kind.flag().to_string(), kind.label().to_string()] {
for cased in [spelling.to_lowercase(), spelling.to_uppercase()] {
assert_eq!(
RelationKind::parse_value(&cased).unwrap(),
kind,
"{cased:?} does not parse as {kind:?}"
);
}
}
}
}
/// A value that is not a kind names the three, in the spelling the flags and the
/// completions use rather than the spelling the file stores: a reader who has just
/// been refused is about to retype the flag.
#[test]
fn a_value_that_is_not_a_kind_names_the_three() {
let refused = RelationKind::parse_value("depends-on").expect_err("accepted");
let message = refused.to_string();
assert!(message.contains("not a relation kind"), "{message}");
for kind in RelationKind::ALL {
assert!(message.contains(kind.flag()), "{kind:?} is not named: {message}");
}
}
/// `relates to` alone reads the same from both ends, and it is derived from the two
/// labels rather than listed, so a kind added later answers by construction.
#[test]
fn only_relates_to_is_symmetric() {
for kind in RelationKind::ALL {
assert_eq!(
kind.is_symmetric(),
kind == RelationKind::RelatesTo,
"{kind:?} claims symmetry it does not have, or has one it does not claim"
);
assert_eq!(kind.is_symmetric(), kind.label() == kind.inverse_label(), "{kind:?}");
}
}
/// Both ends of a symmetric relation can hold a line, since nothing stopped that
/// until 03bdc76, and the block drew the same neighbour twice under the same label.
/// The derived row goes and the stored one stays: it is the line `--clear` can
/// address, where the derived one lives on a file this ticket does not own.
#[test]
fn a_derived_row_that_reads_like_a_stored_one_is_drawn_once() {
let index = RelationIndex::new(vec![related(
TARGET,
"The neighbour",
"backlog",
vec![relation(RelationKind::RelatesTo, SELF)],
)]);
let stored = vec![relation(RelationKind::RelatesTo, TARGET)];
let rows = relation_rows(&stored, &index, SELF);
assert_eq!(rows.len(), 1, "the same edge is drawn twice: {rows:?}");
assert_eq!(rows[0].label, "relates to");
assert_eq!(rows[0].uuid, TARGET);
// The stored one, which is what `--clear` addresses. Both ends carry the same
// label here, so the label cannot say which survived: the count is what does.
assert_eq!(
render_relations(&rows, false),
format!("relates to {RELATES_MARK} {} (b1b2c3d) The neighbour\n", smark("backlog"))
);
}
/// Only where the row would read the same. A pair of tickets each blocking the other
/// is two facts, and the block says both: `blocked by` from this end and `blocks`
/// from the other. Deduping on the kind rather than on the label would have folded
/// them into one and lost half of what the ticket says.
#[test]
fn a_mutual_relation_of_an_asymmetric_kind_keeps_both_rows() {
for kind in RelationKind::ALL.into_iter().filter(|kind| !kind.is_symmetric()) {
let index = RelationIndex::new(vec![related(
TARGET,
"The other one",
"backlog",
vec![relation(kind, SELF)],
)]);
let stored = vec![relation(kind, TARGET)];
let rows = relation_rows(&stored, &index, SELF);
assert_eq!(rows.len(), 2, "{kind:?} lost a row: {rows:?}");
assert_eq!(rows[0].label, kind.label(), "{kind:?}");
assert_eq!(rows[1].label, kind.inverse_label(), "{kind:?}");
}
}
/// The dedupe is per target, not per kind: a second neighbour holding its own
/// `relates to` is a different edge and keeps its row.
#[test]
fn a_second_neighbours_derived_row_survives_the_dedupe() {
const OTHER: &str = "cccccccc-1111-4222-8333-444444444444";
let index = RelationIndex::new(vec![
related(
TARGET,
"The neighbour",
"backlog",
vec![relation(RelationKind::RelatesTo, SELF)],
),
related(
OTHER,
"Another one",
"backlog",
vec![relation(RelationKind::RelatesTo, SELF)],
),
]);
let stored = vec![relation(RelationKind::RelatesTo, TARGET)];
let rows = relation_rows(&stored, &index, SELF);
assert_eq!(rows.len(), 2, "{rows:?}");
assert_eq!(rows[0].uuid, TARGET, "the stored row is not first: {rows:?}");
assert_eq!(rows[1].uuid, OTHER, "the other neighbour was dropped: {rows:?}");
}
/// Both directions of one kind carry the same mark, since the kind is what the mark
/// says and the label is what says which way it points.
#[test]
+41
View File
@@ -1360,3 +1360,44 @@ fn un_discarding_drops_the_discard_stamp() {
assert!(field(&content, "Discarded On").is_none(), "{content}");
assert!(field(&content, "Committed On").is_some(), "{content}");
}
/// Prose takes a leading hyphen, so a reason that reads like a flag is stored as the
/// content it is rather than refused or swallowed. The cost of that bargain is that a
/// genuinely mistyped flag here lands in the log too.
#[test]
fn a_reason_takes_a_leading_hyphen_as_content() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(
&worklane,
"backlog",
"Hyphen Reason",
"Prose trap.",
"bbbb2222",
"alice",
"_Not set_",
"",
);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.args([
"mv",
"bbbb2222",
"--status",
"committed",
"--reason",
"-not-a-flag",
])
.assert()
.success();
let dir = worklane.join("history").join("bbbb2222");
let entry = fs::read_dir(&dir)
.unwrap()
.filter_map(|e| e.ok())
.map(|e| fs::read_to_string(e.path()).unwrap())
.collect::<Vec<_>>()
.join("\n");
assert!(entry.contains("**Reason**: -not-a-flag\n"), "{entry:?}");
}
+412
View File
@@ -388,3 +388,415 @@ fn a_line_that_is_not_a_relation_is_an_error() {
assert!(stderr.contains("is not a relation"), "{stderr}");
assert!(stderr.contains("The gated one"), "{stderr}");
}
// --------------------------------------------------------------- clearing --
/// Two blockers, one taken off by name. The other survives, which is the whole reason
/// `--clear` names the target and not just the kind: a ticket can hold several of one
/// kind, and emptying all of them is not usually what is wanted.
#[test]
fn a_relation_is_taken_off_by_its_kind_and_its_target() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--blocked-by",
FIXED,
],
);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(stdout(&out).contains("Cleared blocked by"), "{}", stdout(&out));
let content = ticket(&worklane, GATED);
assert!(
!content.contains(BLOCKER),
"the cleared relation is still there: {content}"
);
assert!(
content.contains(&format!("- blocked by {}", FIXED)),
"the other one went too: {content}"
);
}
/// Both spellings of the kind, because both are in front of the reader: `blocked-by` is
/// the flag that recorded it and `blocked by` is what `show` prints and what the file
/// stores. Refusing the form the tool itself prints would be a trap.
#[test]
fn the_kind_takes_the_flag_spelling_and_the_label_spelling() {
for kind in ["blocked-by", "blocked by", "Blocked-By"] {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(&temp, &["relate", GATED, "--clear", kind, BLOCKER]);
assert!(out.status.success(), "{kind}: {}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER), "{kind} did not clear it");
}
}
/// The target is a ticket argument like any other, so it resolves by title too.
#[test]
fn a_cleared_target_resolves_by_title() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "blocker"]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER));
}
/// A relation the ticket does not hold is the state the caller asked for, so it reports
/// no change rather than failing. The target resolves; the edge is simply not there.
#[test]
fn clearing_a_relation_the_ticket_does_not_hold_reports_no_change() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
// A kind it does not hold at all, and a target it holds under another kind.
for args in [["relates-to", BLOCKER], ["blocked-by", FIXED]] {
let out = run(&temp, &["relate", GATED, "--clear", args[0], args[1]]);
assert!(out.status.success(), "{args:?}: {}", String::from_utf8_lossy(&out.stderr));
assert!(stdout(&out).contains("No changes"), "{args:?}: {}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before, "{args:?} wrote something");
}
}
/// A search naming nothing at all is a typo, not a state to report. Reporting no change
/// for it would swallow it, which is the one thing the no-change rule must not do.
#[test]
fn clearing_a_target_that_names_nothing_is_an_error() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "9999zzzz"]);
assert!(!out.status.success(), "{}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before);
}
/// The inverse is derived by a scan rather than stored, so taking the stored line off is
/// what takes it off both ends. The other ticket's own file was never touched either way.
#[test]
fn the_derived_inverse_goes_with_the_stored_line() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let untouched = ticket(&worklane, BLOCKER);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let shown = stdout(&run(&temp, &["show", BLOCKER]));
assert!(shown.contains("blocks"), "the inverse was never derived: {shown}");
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let after = stdout(&run(&temp, &["show", BLOCKER]));
assert!(!after.contains("blocks"), "the inverse outlived the stored line: {after}");
assert_eq!(ticket(&worklane, BLOCKER), untouched, "the other ticket was written to");
}
/// The case most likely to need clearing, and the only one no search of the board can
/// reach: the target's ticket is gone, so the prefix tier over the stored targets is what
/// finds it. `show` renders it as `_missing_` until it is cleared, and `mv` warns about it
/// on every move.
#[test]
fn a_dangling_relation_can_be_cleared() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
fs::remove_file(find(&worklane, BLOCKER)).unwrap();
assert!(
stdout(&run(&temp, &["show", GATED])).contains("_missing_"),
"the fixture is not dangling"
);
// By the short id, which is all a reader has once the title is gone.
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", &BLOCKER[..7]]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER), "{}", ticket(&worklane, GATED));
assert!(!stdout(&run(&temp, &["show", GATED])).contains("_missing_"));
}
/// A prefix short enough to reach two stored targets names the candidates rather than
/// guessing, the way an ambiguous ticket search does, and writes nothing.
#[test]
fn an_ambiguous_prefix_over_the_stored_targets_names_the_candidates() {
const ONE: &str = "aaaa1111-0000-4000-8000-000000000000";
const TWO: &str = "aaaa2222-0000-4000-8000-000000000000";
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
create_ticket(&worklane, "backlog", "Twin one", ONE);
create_ticket(&worklane, "backlog", "Twin two", TWO);
run(&temp, &["relate", GATED, "--blocked-by", ONE, "--blocked-by", TWO]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "aaaa"]);
assert!(!out.status.success(), "{}", stdout(&out));
// The stored-target tier and not the board search, which would find the same two
// tickets by their own uuid prefix and report them the same way. The wording is what
// tells the two apart, so it is what this asserts.
let reason = String::from_utf8_lossy(&out.stderr);
assert!(
reason.contains("'blocked by' relations on"),
"the board answered instead: {reason}"
);
assert!(reason.contains(&ONE[..7]) && reason.contains(&TWO[..7]), "{reason}");
assert_eq!(ticket(&worklane, GATED), before);
}
/// The last edge leaves the placeholder `add` writes, not an empty body, so the section
/// can be written to again without the placeholder ending up above what follows it.
#[test]
fn clearing_the_last_relation_leaves_the_placeholder() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let content = ticket(&worklane, GATED);
assert!(
content.contains(
"## Relations
_No relations._
"
),
"{content}"
);
// And it is written to again without the placeholder being left behind.
run(&temp, &["relate", GATED, "--relates-to", FIXED]);
let again = ticket(&worklane, GATED);
assert!(again.contains(&format!("- relates to {}", FIXED)), "{again}");
assert!(
!again.contains("_No relations._"),
"the placeholder outlived the edge: {again}"
);
}
/// The same file surgery `relate` already does, so the tick, the handwritten section and
/// the prose survive a clear the way they survive a record.
#[test]
fn clearing_leaves_everything_it_was_not_asked_about_alone() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--relates-to",
FIXED,
],
);
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let content = ticket(&worklane, GATED);
assert!(content.contains("- [x] Crit one"), "the tick was lost: {content}");
assert!(
content.contains("## Notes\nA handwritten note the tool knows nothing about.\n"),
"the unknown section was lost: {content}"
);
assert!(content.contains("1. Step one"), "{content}");
assert!(content.contains("- **Owner**: alice"), "{content}");
assert!(content.contains("- **Status**: backlog"), "{content}");
}
/// One call does both, and each half reports itself in its own words.
#[test]
fn one_call_records_and_clears_different_relations() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(
&temp,
&[
"relate",
GATED,
"--clear",
"blocked-by",
BLOCKER,
"--relates-to",
FIXED,
],
);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let reported = stdout(&out);
assert!(reported.contains("Recorded relates to"), "{reported}");
assert!(reported.contains("Cleared blocked by"), "{reported}");
let content = ticket(&worklane, GATED);
assert!(!content.contains(BLOCKER), "{content}");
assert!(content.contains(&format!("- relates to {}", FIXED)), "{content}");
}
/// Recording and clearing the same relation in one call is refused outright, the way
/// `set` refuses a field it is also replacing: nothing is written rather than one of the
/// two silently winning.
///
/// It has to be caught on what the call *asked* for and not on what it would write. A
/// relation already in the file is not among the additions, so comparing against those
/// would let this call quietly remove one.
#[test]
fn recording_and_clearing_the_same_relation_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--clear",
"blocked-by",
BLOCKER,
],
);
assert!(!out.status.success(), "{}", stdout(&out));
assert!(
String::from_utf8_lossy(&out.stderr).contains("nothing was written"),
"{}",
String::from_utf8_lossy(&out.stderr)
);
assert_eq!(ticket(&worklane, GATED), before, "the relation was removed anyway");
}
/// A kind that is not one of the three is refused before the ticket is resolved, so
/// nothing is written. Exit 1 rather than clap's 2: the value is one of a pair clap
/// cannot type apart, so the kind is parsed by `RelateArgs::cleared`.
#[test]
fn an_unknown_kind_in_a_clear_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "depends-on", BLOCKER]);
assert!(!out.status.success(), "{}", stdout(&out));
let reason = String::from_utf8_lossy(&out.stderr);
assert!(reason.contains("not a relation kind"), "{reason}");
// The message names the three, in the spelling the flags and the completions use.
for kind in ["blocked-by", "regression-of", "relates-to"] {
assert!(reason.contains(kind), "{reason}");
}
assert_eq!(ticket(&worklane, GATED), before);
}
/// `--clear` takes exactly two values per occurrence, so clap refuses an odd number with
/// a usage error and nothing reaches the handler.
#[test]
fn a_clear_with_one_value_is_a_usage_error() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by"]);
assert_eq!(out.status.code(), Some(2), "{}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before);
}
/// The far end already stores it, so the edge is already recorded: `show` derives it onto
/// this ticket by scanning. A line here would be the same edge on two files, which
/// 4179958 decided against and nothing enforced until 03bdc76.
#[test]
fn a_relates_to_the_target_already_stores_is_not_stored_again() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", BLOCKER, "--relates-to", GATED]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--relates-to", BLOCKER]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before, "the mirror was stored anyway");
// Still shown, since it was recorded at the other end.
let shown = stdout(&run(&temp, &["show", GATED]));
assert_eq!(shown.matches("relates to").count(), 1, "{shown}");
}
/// A board that already holds both directions draws the edge once. The refusal above
/// stops it recurring; this is what repairs a ticket that already has it, without an edit.
#[test]
fn a_relates_to_stored_at_both_ends_is_drawn_once() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
// Both lines written directly, which is the state a board recorded before the refusal
// is in. The CLI will not produce it any more, so nothing else can set this up.
for (holder, target) in [(GATED, BLOCKER), (BLOCKER, GATED)] {
let path = find(&worklane, holder);
let content = fs::read_to_string(&path).unwrap().replace(
"## Metadata",
&format!("## Relations\n- relates to {target}\n\n## Metadata"),
);
fs::write(&path, content).unwrap();
}
let shown = stdout(&run(&temp, &["show", GATED]));
assert_eq!(shown.matches("relates to").count(), 1, "the edge is drawn twice:\n{shown}");
assert_eq!(shown.matches(&BLOCKER[..7]).count(), 1, "{shown}");
// And from the other end, which stores its own line and derives this one.
let far = stdout(&run(&temp, &["show", BLOCKER]));
assert_eq!(far.matches("relates to").count(), 1, "{far}");
}
/// Only where the row reads the same. Two tickets each blocking the other is two facts,
/// and the block says both: `blocked by` from this end, `blocks` from the other.
#[test]
fn a_mutual_block_is_still_drawn_from_both_ends() {
let temp = TempDir::new().unwrap();
board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(&temp, &["relate", BLOCKER, "--blocked-by", GATED]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(
!stdout(&out).contains("No changes"),
"the second was refused: {}",
stdout(&out)
);
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(shown.contains("blocked by"), "{shown}");
assert!(shown.contains("blocks"), "the derived direction was dropped:\n{shown}");
}
/// The same for the other asymmetric kind, whose inverse label also differs from its own.
#[test]
fn a_mutual_regression_is_still_drawn_from_both_ends() {
let temp = TempDir::new().unwrap();
board(&temp);
run(&temp, &["relate", GATED, "--regression-of", BLOCKER]);
run(&temp, &["relate", BLOCKER, "--regression-of", GATED]);
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(shown.contains("regression of"), "{shown}");
assert!(
shown.contains("regressed by"),
"the derived direction was dropped:\n{shown}"
);
}
+88
View File
@@ -114,6 +114,94 @@ fn mv_writes_a_status_entry() {
assert!(entry.contains("**Author**: claude"), "{entry:?}");
}
/// One file, one event, its explanation: `--reason` rides in the status entry that
/// records the transition it explains, as a field after **Time**, and `show` renders it
/// indented under the row rather than as a paragraph of its own.
#[test]
fn the_reason_travels_with_its_transition() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "reviewing");
run(
&temp,
&[
"mv",
UUID,
"--status",
"backlog",
"-f",
"--reason",
"sent back: the first plan was wrong",
],
);
let entry = only_entry(&worklane, "status");
assert!(entry.starts_with("**Status**\nreviewing → backlog\n"), "{entry:?}");
assert!(
entry.ends_with("**Reason**: sent back: the first plan was wrong\n"),
"{entry:?}"
);
let out = run(&temp, &["show", UUID]);
let stdout = String::from_utf8(out.stdout).unwrap();
let moved = stdout.find("reviewing → backlog").expect("the move is missing");
let reason = stdout
.find("\n sent back: the first plan was wrong")
.expect("the reason is missing");
// Attached means the very next line: nothing, not even a blank line, between.
assert!(
!stdout[moved..reason].contains('\n'),
"the reason is detached from its row:\n{stdout}"
);
}
/// The unusual moves are exactly the ones that need a why, so a refused one must not
/// log one either: the entry is written after the edit, and there was no edit.
#[test]
fn a_refused_move_writes_no_reason_either() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "reviewing");
let out = run(
&temp,
&[
"mv",
UUID,
"--status",
"backlog",
"--reason",
"this move never happened",
],
);
assert_eq!(out.status.code(), Some(1));
assert_eq!(entries(&worklane), vec![], "a refused move logged its reason");
}
/// Same for the move that changes nothing.
#[test]
fn a_no_op_move_writes_no_reason_either() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "committed");
let out = run(
&temp,
&[
"mv",
UUID,
"--status",
"committed",
"--reason",
"nothing moved",
],
);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert_eq!(entries(&worklane), vec![], "a no-op move logged its reason");
}
#[test]
fn chown_writes_an_owner_entry() {
let temp = TempDir::new().unwrap();