Compare commits

...
5 Commits
Author SHA1 Message Date
Ansho Rei c2ee165108 (e4d0bb7) Colour the whole detail overlay body, not just its relations, and bump to 0.27.3
The block was the only coloured part because it arrived as rows while
everything else arrived as a painted string, and the board had to ask for
the unpainted one: an escape in a ratatui paragraph is drawn as literal
bytes.

content_parts now paints nothing. BodyPart::Text becomes
BodyPart::Cells, so content_trim is the cells through paint_cells and the
board is the same cells through span_from. push_heading, ordered_cells,
inline_cells, metadata_cells, metadata_value_cells and tag_cells replace
the painters they were. Resolved.campaign is cells too, which made
reference_cell dead at its last caller.

The colored flag still reaches content_parts and no longer means paint.
It says whether this renderer can carry a colour at all, and one thing
turns on it: **bold** gives its markers up to the colour that replaces
them, so a renderer with none has to keep them.

Color::Magenta.ansi() is \x1b[1;35m, so span_from adds the bold modifier
on the board's side, since From<Color> carries only the colour and the
same cell must not be painted two ways.

show's output is pinned byte for byte against what it printed before,
both by a fixture holding one of every painted run and by diffing the
old binary against the new one over every ticket and campaign on this
board, coloured and piped.
2026-08-24 11:57:25 +02:00
Ansho Rei 407cb14fe6 (e6e3a1b) Guard the README command table against a missing row
The campaign and assign rows landed with 528566d. What was left was the
checking, done here against the built binary rather than against the
ticket that added them.

The campaign ls row was incomplete: the listing also prints the derived
state, [open] until every member is done and [done] after, and reads
"no members" with no state for a campaign nothing has been filed
against, which is neither. Corrected.

every_subcommand_has_a_row_in_the_readme_command_table walks clap's own
subcommands, one level of nesting included, against the table's rows.
Two commands hid behind an otherwise complete table for two minor
versions because the only thing walking it was somebody remembering to.
The tag subcommands are named in a PENDING list rather than skipped,
since f7dd1a1 rewrites that row.
2026-08-24 11:28:32 +02:00
Ansho Rei 108e21ad7f (25d3018) Fix the markdown link colorization branch, and bump to 0.27.2
The branch searched for a closing square bracket after the ]( sequence
instead of a closing parenthesis, so it fired only on text that was not
a link, and when it fired it pushed the matched span and dropped the
rest of the line.

Folded into colorize_bold, now colorize_inline: one walk over the source
line recognising both **bold** and [text](url). A second pass over the
first one's output 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. Unterminated markup of either kind
falls through to the ordinary character push, so the rest of the line
survives as literal text.

Criteria text and hand-written metadata rows get links too, since they
already went through this function. The whole span is painted, markers
and url kept: show prints to a terminal worklane cannot assume will make
a link clickable.
2026-08-24 11:15:15 +02:00
Ansho Rei 26b93f8f53 Add Makefile 2026-08-24 11:03:28 +02:00
Ansho ReiandClaude Opus 5 7126138d46 (0fd1ddc) Pick a tag in the tui, and bump to 0.27.1
The board could be cut by campaign and not by the axis `ls --tag` has answered
since 2f3796e. `t` opens a picker of every tag the board declares or carries,
and taking one filters every column to the cards carrying it, matched whole and
case sensitively the way the listing matches.

The picker is one piece of machinery over two lists rather than a second
picker. `PickerRow::key` is what made that cheap: a campaign is keyed by its
uuid and a tag by itself, both strings, so stepping over selectable rows,
keeping the highlight across a rebuild and taking a row with `enter` are
written once. Only the list and what the answer filters differ.

`Tab::campaign` became `Tab::filter`, an enum of whole, campaign or tag, with
`select_filter` its only writer. Picking either clears the other because they
are one field rather than because two setters remember to, which is also what
the shared frame slot needs: it holds one frame and can now only be asked to
name one thing.

The tag sections are declared above undeclared and neither is truncated, where
the completed campaigns are: a finished campaign is done with and that tail
only grows, while an undeclared tag is the row a reader most wants to see.
`campaign` and `campaigns` would have sat one under the other here the day the
second was invented.

The digest stamps `tags.md`, or a tag declared elsewhere would never reach an
open picker. The footer names the tag in its own colour beside `q board`,
because a tag draws no frame until 2a83bd4 and nothing else would say why the
cards are missing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 10:03:29 +02:00
12 changed files with 1738 additions and 347 deletions
+18 -11
View File
@@ -175,7 +175,7 @@ and this file is for what someone changing worklane's own code needs.
- **A campaign's state is derived, never stored.** Open until every member is done, computed by `Standing` from the members. A `Status` field on the campaign would be the same state in two places, and the two would disagree the moment a member moved. It is also why there is no `campaign mv` and no forward-only ruleset beside `mv`'s
- **A campaign with no members is neither open nor done.** `Standing::state()` returns `None` there, and both callers print `no members`. Calling it done would make a container nothing has been filed against the most complete thing on the board; calling it open would claim work that does not exist
- **Membership is one field on the member**, `Campaign` in the ticket Metadata, written only by `assign`. The member list is deliberately *not* on the campaign: that would put membership in two places, and would make one file that every assignment edits, which is contended the moment two agents share a board. So `add` has no `--campaign` and `set` has no `--campaign`, the same rule as Owner and Status
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cell` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cells` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
- **`add` does not write the field.** Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out of `add` means one path that is always exercised rather than two. Same reasoning as the Relations section
- `set_or_insert_metadata_field()` is the upsert, and `METADATA_ORDER` is its anchor list, the way `SECTION_ORDER` is `ensure_section`'s. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no `## Metadata` heading is an **error, not an insertion**: per 641e3d5 such a file has no fields at all, and writing one above the prose would invent a shape nothing reads
- **The four tiers are `resolve_in()`, shared by tickets and campaigns.** A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step. `Found.dir` is the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one
@@ -242,7 +242,7 @@ and this file is for what someone changing worklane's own code needs.
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the comments directory away after the board is built**, and is paired with `a_comment_added_after_the_board_was_built_reaches_the_card_on_reload`, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
- **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_cell` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
- **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
- **`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
@@ -328,7 +328,7 @@ 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
- **`reference_cells` is the one spelling of a cross reference**, and `reference_cell` is it painted. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown
- **`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
- **Both directions of a kind carry one mark.** `blocked by` and `blocks` are the same edge read from two ends, and the label is what says which end you are on. `both_directions_of_a_kind_carry_one_mark` pins it
@@ -340,11 +340,15 @@ and this file is for what someone changing worklane's own code needs.
- **Committed and reviewing are told apart by colour alone**, both being `◐`, so a pipe cannot tell them apart: `should_use_colors` is false and both read as under way. Accepted, because `●` and `○` are the two answers usually wanted and `show` on the target settles the rest, and `assets/SKILL.md` says so outright rather than leaving an agent to infer it. Do not fix this by giving one of them a colour that means something else
- `RelationTarget` carries the title and the status in one `Option`, because they come from the same lookup and are absent together. It was taken out when the mark keyed on the kind alone and put back one commit later, which is the cost of a field nothing reads: correct at the time, and churn either way
- **`show` and the board carry the same mark**, decided rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minor
- **`Resolved.relations` is rows, not a rendered block.** That is what lets the board style them: an escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so the block cannot arrive pre-painted. `content_parts` hands the text through already painted and the rows through untouched, which is the asymmetry the two renderers need
- **`BodyPart` splits the body rather than building it twice.** Everything outside the relations block is rendered once, by `content_parts`; `content_trim` is that with the rows painted, and the board is that with the rows styled. `Body` is the accumulator, so a caller pushes text and rows without tracking which it pushed last
- **`Resolved.relations` is rows, not a rendered block, and `Resolved.campaign` is cells for the same reason.** An escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so nothing in `Resolved` can arrive pre-painted. This was the asymmetry the two renderers needed while the rest of the body was a painted string; there is no asymmetry left, since `content_parts` paints nothing at all
- **`BodyPart` splits the body rather than building it twice.** It is `Cells` or `Relations`: everything outside the block is laid out once, by `content_parts`, and `content_trim` is that run through `paint_cells` while the board is the same cells run through `span_from`. `Body` is the accumulator, so a caller pushes cells and rows without tracking which it pushed last, and it merges a run into the trailing cell when the colour matches, because the board draws a span per cell and the body is pushed a character at a time in places
- **`Detail.body` is a `Text`, and it is the only thing measured.** `last_offset` and the `Paragraph` both take it, so the clamp cannot wrap the body differently from the draw. `Detail::plain()` flattens it for the suite and is `#[cfg(test)]`: a second representation carried alongside the spans is a second thing to disagree
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end
- **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end. It now splits **per cell** rather than per part, since a `Cells` part holds many runs and a newline can fall inside any of them
- **The whole overlay body is coloured now, and `content_parts` paints nothing.** The block used to be the only coloured part, because it arrived as rows while everything else arrived as a painted string; e4d0bb7 gave the rest the same `Cell` treatment. So the headings, the plan numbers, the criteria numbers and marks, the bold runs, the field names, the priority glyph, the tags and the grey unset values are one layout that `show` paints and the board styles. Do not reintroduce a `paint` call in `content_parts`: the flat overlay was exactly that, a renderer forced to ask for the unpainted string because the painted one held escapes
- **`colored` still reaches `content_parts`, and it no longer means paint.** It says whether *this* renderer can carry a colour at all, and one thing turns on it: `**bold**` gives its markers up to the colour that replaces them, so a renderer with none has to keep them or the emphasis is lost rather than moved. The board passes `true`, `content_trim` passes the CLI's decision, and a piped `show` still reads its markers. Nothing else in the body consults it
- **Magenta means bold, and `span_from` is where the board learns that.** `Color::Magenta.ansi()` is `\x1b[1;35m`, so the CLI draws every bold run bold as well as magenta, and `From<Color>` can carry only the colour. Without the modifier added on the board's side the same cell would be painted two ways, which is the one thing the shared layout exists to prevent
- **The conversion is pinned from both ends.** `show_prints_the_same_body_it_printed_before_the_cells_conversion` holds a body with one of every painted run and asserts the CLI's output byte for byte, written from what it printed before the change, so the risk in sharing a layout, the CLI's output drifting to suit the board, fails the suite. `the_whole_body_is_styled_in_the_overlay_and_no_escape_reached_it` is the other end and is paired the way the guideline demands: a renderer that dropped every colour passes the absence, and one that went back to painting strings passes the presence
- **The comments block is still flat, and it is the last piece that is.** `format_comments_with` is a string the board appends after the body rather than part of what `content_parts` lays out, so it was outside e4d0bb7. Its own ticket
### Finding the Board
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
@@ -394,11 +398,12 @@ and this file is for what someone changing worklane's own code needs.
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
- `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
- **The README command table has the same guard, `every_subcommand_has_a_row_in_the_readme_command_table` in `command.rs`.** The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: `campaign` and `assign` shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the `--campaign` flag on the `ls` row. It walks clap's own subcommands, one level of nesting included, against the `|` lines of `README.md`, so a new command fails the suite until the table lists it. `help` is excluded, being clap's. The tag subcommands are named in a `PENDING` list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it
### Color and Output
- Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in
- **`color_text()` is for the CLI's own printing only. Anything reachable from `content_trim` takes the decision as an argument and calls `paint()`**, because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes. `nothing_the_body_renders_asks_the_terminal_for_the_colour_decision` scans this file and fails on a new caller; the allowlist is `ambiguous`, which builds a failed-search message for stderr
- A function that takes an `enabled` flag must use it all the way down. `colorize_bold` honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function
- A function that takes an `enabled` flag must use it all the way down. The inline pass honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function. The better answer, where it fits, is to take no flag: `ordered_cells` and `metadata_value_cells` return the colour rather than a decision about it
- **A test that asserts an absence has to be paired with one that asserts the presence.** The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so `should_use_colors()` was false and the leaking branch was never taken. The pair is now `content_trim(.., false)` has no escape and `content_trim(.., true)` still colours, which pins the flag as the only thing that decides
- **The palette is the `Color` enum, not a string.** `Color::ansi()` gives the CLI its SGR sequence and `From<Color> for ratatui::style::Color` gives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is how `magenta` came to be undefined
- Reset color with `\x1b[0m` after colored text
@@ -415,6 +420,7 @@ 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 `?` for a target the board does not hold. 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
- 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
- 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
@@ -426,8 +432,9 @@ 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
- Colorization functions (`colorize_ordered`, `colorize_bold`, `content_trim_colored`) handle markdown formatting. `colorize_line` is gone: it was a `pub` alias for `colorize_bold` with one caller, and the only thing it added was asking the terminal
- `show` renders the Metadata section as a two column table via `render_metadata_table`, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
- 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
- `show` renders the Metadata section as a two column table via `metadata_cells`, not line by line. Column width is measured on the raw field names in characters and the padding goes into a cell of its own, so nothing is ever measured with a colour on it: measuring a painted string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
- The title is printed once, by `cmd_show`. `content_trim_colored` skips the `# ` heading in the file content
- Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
- `resolve_ticket()` scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filename
@@ -454,12 +461,12 @@ and this file is for what someone changing worklane's own code needs.
### Version Bumps
- Before every commit, decide whether the change warrants a version bump in `Cargo.toml`
- Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
- **`make patch`, `make minor` and `make major` do the mechanics**, run after the commit is in: each bumps `Cargo.toml` and the `worklane` entry in `Cargo.lock`, appends `, and bump to <version>` to the commit's subject, folds the bump into that commit, and tags it. Bumping by hand is how a version comes to be left untagged, which is what the one action is for. It refuses on a dirty tree, on an already-tagged `HEAD` and on a `HEAD` that is already pushed, since each of those makes the amend lose work, orphan a tag or need a force push
- Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
- **Changed output means the CLI's output.** That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View
- **Settling output that shipped one version ago is a patch**, not a second minor. 0.15.1 changed the relation mark 0.15.0 had just introduced, and 0.15.2 added the status mark beside it: the minor was the arrival of a marked relations block, and settling what it marks belongs to that. Three minors in an hour would tell anyone reading the tags that there were three features
- No bump for docs-only, tests-only or `--fixup` commits
- When one body of work spans several commits, bump once on the final commit rather than on each
- Bump `Cargo.toml` and the `worklane` entry in `Cargo.lock` together, in the commit that carries the bump
- Every bump gets a matching annotated tag, `v<version>`, on the bump commit — a bumped version is never left untagged
- Tag locally only; never push a tag unless asked
- `worklane --version` reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.27.0"
version = "0.27.3"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.27.0"
version = "0.27.3"
edition = "2024"
[dependencies]
+92
View File
@@ -0,0 +1,92 @@
# Release helpers.
#
# `make patch|minor|major` bumps the version in Cargo.toml and Cargo.lock, folds
# that bump into the last commit, and tags it. Everything is one action so a
# release cannot end up half-done: no version bump left untagged, no tag without
# a bump.
.PHONY: help patch minor major version release install
help:
@echo "make patch bump $(CURRENT) -> next patch, amend into HEAD, tag"
@echo "make minor bump $(CURRENT) -> next minor, amend into HEAD, tag"
@echo "make major bump $(CURRENT) -> next major, amend into HEAD, tag"
@echo "make version print the current version"
@echo "make install cargo install --path . && worklane install-skill"
# Read from the [package] table of Cargo.toml, which is the version the binary
# reports through `--version`, so it is the single source of truth. The name is
# what finds this crate's own entry in Cargo.lock.
PACKAGE = $(shell awk -F'"' '/^\[package\]/{p=1;next} /^\[/{p=0} p && /^name *= *"/{print $$2; exit}' Cargo.toml)
CURRENT = $(shell awk -F'"' '/^\[package\]/{p=1;next} /^\[/{p=0} p && /^version *= *"/{print $$2; exit}' Cargo.toml)
# 1 appends ", and bump to <version>" to the amended commit's subject; empty
# leaves the message alone.
AMEND_SUBJECT = 1
version:
@echo $(CURRENT)
patch: BUMP = patch
minor: BUMP = minor
major: BUMP = major
patch minor major: release
# A release rewrites the last commit, so refuse anything that would make that
# rewrite lose work or orphan a tag.
release:
@set -e; \
if ! git rev-parse -q --verify HEAD >/dev/null 2>&1; then \
echo "error: no commits yet, so there is no commit to fold a version bump into. Commit first." >&2; \
exit 1; \
fi; \
if [ -n "$$(git status --porcelain)" ]; then \
echo "error: working tree is dirty. Commit or stash first, and decide whether that work belongs in this version:" >&2; \
git status --short >&2; \
exit 1; \
fi; \
if [ -n "$$(git tag --points-at HEAD)" ]; then \
echo "error: HEAD is already tagged $$(git tag --points-at HEAD | paste -sd' '). Amending it would leave that tag on an orphaned commit. Commit something first." >&2; \
exit 1; \
fi; \
if upstream=$$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null) && \
git merge-base --is-ancestor HEAD "$$upstream" 2>/dev/null; then \
echo "error: HEAD is already pushed to $$upstream. Amending it would need a force push. Commit something first." >&2; \
exit 1; \
fi; \
current="$(CURRENT)"; \
if [ -z "$$current" ]; then echo "error: no version found in the [package] table of Cargo.toml" >&2; exit 1; fi; \
new=$$(echo "$$current" | awk -F. -v kind=$(BUMP) '{ \
if (NF != 3) exit 1; \
if (kind == "patch") printf "%d.%d.%d\n", $$1, $$2, $$3 + 1; \
else if (kind == "minor") printf "%d.%d.0\n", $$1, $$2 + 1; \
else printf "%d.0.0\n", $$1 + 1 }'); \
if [ -z "$$new" ]; then echo "error: cannot bump version '$$current': expected major.minor.patch" >&2; exit 1; fi; \
if git rev-parse -q --verify "refs/tags/v$$new" >/dev/null; then \
echo "error: tag v$$new already exists" >&2; exit 1; \
fi; \
awk -v v="$$new" '/^\[package\]/{p=1} /^\[/ && !/^\[package\]/{p=0} p && /^version *= *"/{sub(/"[^"]*"/, "\"" v "\"")} {print}' Cargo.toml > Cargo.toml.bump; \
mv Cargo.toml.bump Cargo.toml; \
git add Cargo.toml; \
if [ -f Cargo.lock ] && git ls-files --error-unmatch Cargo.lock >/dev/null 2>&1; then \
awk -v v="$$new" -v pkg="$(PACKAGE)" '$$0 == "name = \"" pkg "\""{f=1} f && /^version = "/{sub(/"[^"]*"/, "\"" v "\""); f=0} {print}' Cargo.lock > Cargo.lock.bump; \
mv Cargo.lock.bump Cargo.lock; \
git add Cargo.lock; \
fi; \
if [ -n "$(AMEND_SUBJECT)" ]; then \
subject=$$(git log -1 --format=%s | sed -E 's/, and bump to [0-9]+\.[0-9]+\.[0-9]+$$//'); \
body=$$(git log -1 --format=%b); \
if [ -n "$$body" ]; then \
git commit --quiet --amend -m "$$subject, and bump to $$new" -m "$$body"; \
else \
git commit --quiet --amend -m "$$subject, and bump to $$new"; \
fi; \
else \
git commit --quiet --amend --no-edit; \
fi; \
git tag -a "v$$new" -m "v$$new"; \
echo "$$current -> $$new, tagged v$$new on $$(git rev-parse --short HEAD) ($$(git log -1 --format=%s))"
install:
cargo install --path .
worklane install-skill
+18 -1
View File
@@ -21,7 +21,7 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane campaign add` | Files a campaign in `.worklane/campaigns/` with `--title`, `--description`, `--codename` and `--owner`. A campaign has no status: its state is derived, open until every member is done. `--codename` is one word to call it by, `v1` or `beaver`, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by |
| `worklane campaign set <campaign>` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` |
| `worklane campaign append <campaign>` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket |
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, for a script or a completion |
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title, how many members are done, and the state that count derives: `[open]` until every member is done and `[done]` after. A campaign nothing has been filed against reads `no members` and carries no state, being neither. `--ids` prints one per line as the id, a tab and the title, unstyled and without the counts, which read every ticket on the board, for a script or a completion |
| `worklane campaign show <campaign>` | Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks |
| `worklane assign <campaign> <ticket>` | Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after `chown`. A ticket is in at most one, so assigning one that already belongs somewhere moves it |
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
@@ -78,3 +78,20 @@ Whether a truncated pipe reports 141 or 0 depends on the size of the output, not
the command. A pipe holds 64 KiB, so a listing that fits lands in the buffer whole
and the writer never learns the reader left, giving 0. Only output past that gets far
enough to be cut off. Either way nothing is printed to stderr.
## Releasing
```sh
make patch # 0.27.1 -> next patch
make minor # 0.27.1 -> next minor
make major # 0.27.1 -> next major
```
Each bumps `Cargo.toml` and `Cargo.lock`, folds that bump into the last commit, and tags it
`v<version>`. One action, so no bump is left untagged and no tag lands without a bump. In this repo
it also appends `, and bump to <version>` to the commit's subject, the way the release commits
before it read.
It refuses to run when the working tree is dirty, when `HEAD` is already tagged, or when `HEAD` is
already pushed. The first asks you to decide whether that work belongs in the version; the other two
mean the amend would orphan a tag or need a force push.
+5 -5
View File
@@ -173,22 +173,22 @@ impl CampaignIndex {
/// target does, rather than as the bare value the file stores: the value is a full
/// uuid, so showing it raw is thirty-six characters that say nothing about what is
/// gone.
pub fn campaign_cell(content: &str, index: &CampaignIndex, colored: bool) -> String {
pub fn campaign_cells(content: &str, index: &CampaignIndex) -> Vec<Cell> {
let Some(uuid) = parse_campaign(content) else {
return String::new();
return Vec::new();
};
reference_cell(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()), colored)
reference_cells(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()))
}
/// The parts [`content_trim`] cannot render from the ticket file alone.
///
/// Both halves read the tree beside the ticket, so they are gathered in one place
/// rather than at each call site.
pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result<Resolved> {
pub fn resolved_for(content: &str, worklane_dir: &Path) -> Result<Resolved> {
Ok(Resolved {
relations: relations_for(content, worklane_dir)?,
campaign: campaign_cell(content, &CampaignIndex::load(worklane_dir)?, colored),
campaign: campaign_cells(content, &CampaignIndex::load(worklane_dir)?),
})
}
+65
View File
@@ -881,3 +881,68 @@ pub struct CheckArgs {
/// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted
pub criteria: Vec<String>,
}
#[cfg(test)]
mod tests {
use super::*;
use clap::CommandFactory;
/// The command names as the README table would have to spell them: `campaign add`
/// for a nested one, the bare name for a top level one. `help` is clap's own and
/// documents nothing.
fn documented_names() -> Vec<String> {
let cli = Cli::command();
let mut names = Vec::new();
for sub in cli.get_subcommands() {
if sub.get_name() == "help" {
continue;
}
names.push(sub.get_name().to_string());
for nested in sub.get_subcommands() {
if nested.get_name() == "help" {
continue;
}
names.push(format!("{} {}", sub.get_name(), nested.get_name()));
}
}
names
}
/// Every subcommand has a row in the README's command table.
///
/// `campaign` and `assign` went undocumented for two minor versions, e6e3a1b, and
/// the `--campaign` flag went with them, because the only thing walking the table
/// was somebody remembering to. This is what walks it. A command whose row is
/// missing is a command a reader of the README cannot discover at all, which is a
/// worse failure than a row that is merely out of date.
#[test]
fn every_subcommand_has_a_row_in_the_readme_command_table() {
// The tag subcommands are f7dd1a1's, which rewrites the `worklane tags` row
// once the vocabulary work above it has landed. Listed rather than skipped, so
// emptying this is part of closing that ticket rather than something to
// rediscover.
const PENDING: [&str; 3] = ["tags add", "tags set", "tags ls"];
let readme = include_str!("../README.md");
let table: String = readme.lines().filter(|line| line.starts_with('|')).collect();
let missing: Vec<String> = documented_names()
.into_iter()
.filter(|name| !PENDING.contains(&name.as_str()))
.filter(|name| !table.contains(&format!("`worklane {}", name)))
.collect();
assert!(
missing.is_empty(),
"no row in the README command table for {missing:?}. A new command is not \
shipped until the table lists it: that table is the only place a reader \
discovers one, and two commands hid behind an otherwise complete table \
for two minor versions."
);
}
}
+1 -1
View File
@@ -443,7 +443,7 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
let ticket_uuid = parse_ticket_field(&content, "ID");
// Read before anything is printed, so a board that cannot be read fails instead of
// half printing a ticket.
let resolved = resolved_for(&content, worklane_dir, should_use_colors())?;
let resolved = resolved_for(&content, worklane_dir)?;
// The only title in the output: content_trim_colored used to print it a second
// time from the file content. Green per the colour guideline, and the rule is
+5 -1
View File
@@ -248,7 +248,11 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
// The way in to the campaign picker, like `/` is to the search prompt: from
// the next keypress on `picker_key` above has the keyboard. Free of every
// other binding, and `ctrl-c` is matched above this so quitting still wins.
KeyCode::Char('c') => board.open_picker(),
KeyCode::Char('c') => board.open_picker(tui::PickerKind::Campaign, screen),
// The other axis the board is cut along, and the one `ls --tag` has
// answered since 2f3796e. Free of every other binding: `tab` is its own
// key code, not this letter.
KeyCode::Char('t') => board.open_picker(tui::PickerKind::Tag, screen),
_ => {}
}
}
+10
View File
@@ -163,6 +163,16 @@ impl TagIndex {
self.tags.keys().map(String::as_str)
}
/// What a tag means, whole, or `None` for a tag the file does not declare.
///
/// The raw section, paragraphs and all, where [`Self::summary`] is the one line a
/// listing has room for. `Some("")` is a tag declared with nothing said about it, which
/// the caller has to tell apart from `None`: the board draws the two in different
/// sections.
pub fn annotation(&self, tag: &str) -> Option<&str> {
self.tags.get(tag).map(String::as_str)
}
/// The opening line of what a tag means, or `None` for a tag the file does not declare.
///
/// The cut to one line lives here rather than on the parse, the way
+1113 -175
View File
File diff suppressed because it is too large Load Diff
+409 -151
View File
@@ -656,9 +656,11 @@ pub struct Resolved {
/// Rows rather than the rendered block: the CLI paints them into escapes and the
/// board styles the same rows itself, since a paragraph is no place for an escape.
pub relations: Vec<RelationRow>,
/// The Campaign value as it reads, from [`reference_cell`]. Empty leaves the stored
/// The Campaign value as it reads, from [`campaign_cells`]. Empty leaves the stored
/// value to render as it sits, which is what a ticket in no campaign wants.
pub campaign: String,
///
/// [`campaign_cells`]: crate::campaign::campaign_cells
pub campaign: Vec<Cell>,
}
pub fn content_trim_colored(content: &str, resolved: &Resolved) -> String {
@@ -670,35 +672,32 @@ pub fn content_trim_colored(content: &str, resolved: &Resolved) -> String {
/// The rule is measured on the name as displayed, in characters. It used to span the
/// raw line, so it ran three past the heading for the `## `, and byte length over-drew
/// anything non-ASCII.
fn push_heading(out: &mut Body, heading: &str, colored: bool) {
fn push_heading(out: &mut Body, heading: &str) {
let name = heading.strip_prefix("## ").unwrap_or(heading);
out.push_str(&paint(name, Color::Orange, colored));
out.push_cell(Cell::colored(name, Color::Orange));
out.push('\n');
out.push_str(&"─".repeat(name.chars().count()));
out.push('\n');
out.push('\n');
}
/// The ticket body rendered for display, with the colour decision passed in.
/// One piece of the rendered body: a run of cells, or relations still as rows.
///
/// The TUI needs the plain form: ratatui draws styled spans, and an escape sequence
/// embedded in a paragraph would be printed as literal bytes.
/// The body is one string to the CLI and a run of styled lines to the board. Neither
/// half is rendered here: a [`Cell`] carries the text and the colour it is drawn in, and
/// the renderer decides what a colour is, an escape sequence for the CLI and a ratatui
/// style for the board. That is what makes the two views one layout rather than two
/// that have to be kept in step.
///
/// [`Resolved`] carries the parts that come from elsewhere on the board, since the
/// body alone cannot render them.
/// One piece of the rendered body: text as it prints, or relations still as rows.
///
/// The body is one string to the CLI and a run of styled lines to the board, and the
/// only part that differs is the relations block. Splitting the body here rather than
/// building it twice is what keeps the two views from drifting: everything outside the
/// block is rendered once, by [`content_parts`], and the rows are handed on unpainted.
/// The relations stay rows rather than becoming cells here because their layout needs
/// the whole block at once: the label column is padded to the widest label.
pub enum BodyPart {
Text(String),
Cells(Vec<Cell>),
Relations(Vec<RelationRow>),
}
/// The body under construction. Text accumulates into the trailing run, and a relations
/// The body under construction. Cells accumulate into the trailing run, and a relations
/// block closes it, so a caller pushes text and rows without tracking which it pushed
/// last.
#[derive(Default)]
@@ -707,17 +706,37 @@ struct Body {
}
impl Body {
/// A run in the default foreground.
fn push_str(&mut self, text: &str) {
match self.parts.last_mut() {
Some(BodyPart::Text(run)) => run.push_str(text),
_ => self.parts.push(BodyPart::Text(text.to_string())),
}
self.push_cell(Cell::plain(text));
}
fn push(&mut self, c: char) {
self.push_cell(Cell::plain(c.to_string()));
}
/// One run, merged into the trailing cell when it is the same colour.
///
/// 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.
fn push_cell(&mut self, cell: Cell) {
if cell.text.is_empty() {
return;
}
match self.parts.last_mut() {
Some(BodyPart::Text(run)) => run.push(c),
_ => self.parts.push(BodyPart::Text(c.to_string())),
Some(BodyPart::Cells(cells)) => match cells.last_mut() {
Some(last) if last.color == cell.color => last.text.push_str(&cell.text),
_ => cells.push(cell),
},
_ => self.parts.push(BodyPart::Cells(vec![cell])),
}
}
fn push_cells(&mut self, cells: Vec<Cell>) {
for cell in cells {
self.push_cell(cell);
}
}
@@ -727,26 +746,42 @@ impl Body {
/// Whether the text written so far ends with `suffix`. A relations block never does,
/// since it is not text yet.
///
/// Over the whole trailing run rather than its last cell: a colour change starts a
/// new cell, and the question here is what the body reads like, not how it is split.
fn ends_with(&self, suffix: &str) -> bool {
match self.parts.last() {
Some(BodyPart::Text(run)) => run.ends_with(suffix),
Some(BodyPart::Cells(cells)) => {
let run: String = cells.iter().map(|cell| cell.text.as_str()).collect();
run.ends_with(suffix)
}
_ => false,
}
}
}
/// The ticket body as the CLI prints it.
///
/// [`Resolved`] carries the parts that come from elsewhere on the board, since the
/// body alone cannot render them.
pub fn content_trim(content: &str, colored: bool, resolved: &Resolved) -> String {
content_parts(content, colored, resolved)
.iter()
.map(|part| match part {
BodyPart::Text(text) => text.clone(),
BodyPart::Cells(cells) => paint_cells(cells, colored),
BodyPart::Relations(rows) => render_relations(rows, colored),
})
.collect()
}
/// The body rendered into its parts, with the colour decision already applied to the
/// text and deliberately not to the relations.
/// The body laid out as cells, for a renderer to colour as it colours anything.
///
/// `colored` no longer paints anything here, and it is not the CLI's flag: it says
/// whether *this* renderer can carry a colour at all, which is the one question the
/// layout still turns on. `**bold**` and `[text](url)` give their markers up to a
/// colour, so a renderer with no colour has to keep them, or the emphasis is lost
/// rather than moved. The board passes `true`, since it styles spans; `content_trim`
/// passes the CLI's decision, so a piped `show` still reads its markers.
pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<BodyPart> {
let relations = resolved.relations.as_slice();
let lines: Vec<&str> = content.trim().lines().collect();
@@ -772,24 +807,20 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
// file would have kept it, ahead of the metadata, rather than tacked on
// after everything.
if is_metadata_heading(line) && !stores_relations && !relations.is_empty() {
push_heading(&mut result, RELATIONS.heading, colored);
push_heading(&mut result, RELATIONS.heading);
result.push_relations(relations);
result.push('\n');
shown_relations = true;
}
push_heading(&mut result, section_name, colored);
push_heading(&mut result, section_name);
i += 1;
// Metadata is rendered as a block, so it is consumed here rather than
// falling through to the line-at-a-time cases below.
if is_metadata_heading(line) {
let end = section_end(&lines, i);
result.push_str(&render_metadata_table(
&lines[i..end],
colored,
&resolved.campaign,
));
result.push_cells(metadata_cells(&lines[i..end], colored, &resolved.campaign));
i = end;
}
@@ -825,7 +856,7 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
// Implementation Plan - color numbers in cyan
if current_section == "## Implementation Plan" {
result.push_str(&colorize_ordered(line, colored));
result.push_cells(ordered_cells(line));
result.push('\n');
continue;
}
@@ -837,35 +868,17 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
&& let Some((checked, text)) = checkbox(line)
{
criterion += 1;
result.push_str(&paint(&format!("{}.", criterion), Color::Cyan, colored));
result.push_cell(Cell::colored(format!("{}.", criterion), Color::Cyan));
result.push(' ');
result.push_str(&paint(if checked { "[x]" } else { "[ ]" }, Color::Grey, colored));
result.push_cell(Cell::colored(if checked { "[x]" } else { "[ ]" }, Color::Grey));
result.push(' ');
result.push_str(&colorize_bold(text, colored));
result.push_cells(inline_cells(text, colored));
result.push('\n');
continue;
}
// Standard markdown link colorization in cyan
if line.contains("[")
&& line.contains("(")
&& line.contains("]")
&& let Some(start) = line.find("[")
{
let bracket_text = &line[start..];
if let Some(end_bracket) = bracket_text.find("](") {
let link_start = start + end_bracket + 1;
if let Some(end) = line[link_start..].find(']') {
let absolute_end = link_start + end + 1;
result.push_str(&paint(&line[start..absolute_end], Color::Cyan, colored));
result.push('\n');
continue;
}
}
}
// Regular content - colorize **bold** in magenta
result.push_str(&colorize_bold(line, colored));
// Regular content, with its inline markup carried as cells of its own.
result.push_cells(inline_cells(line, colored));
result.push('\n');
}
@@ -875,42 +888,42 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
if !result.ends_with("\n\n") {
result.push('\n');
}
push_heading(&mut result, RELATIONS.heading, colored);
push_heading(&mut result, RELATIONS.heading);
result.push_relations(relations);
}
result.parts
}
/// Colour the `1.` at the head of a numbered line, leaving the rest alone.
/// The `1.` at the head of a numbered line as a cell of its own, the rest as it stands.
///
/// Takes the decision rather than asking for it. Asking is what put `\x1b[36m` and
/// `\x1b[0m` around every Implementation Plan number in the board's detail view,
/// which renders with colour off precisely because a paragraph is not a place an
/// escape sequence can go.
fn colorize_ordered(line: &str, colored: bool) -> String {
/// No colour flag. The cell says cyan and the renderer decides what cyan is, which is
/// what stopped this asking `should_use_colors()` and putting `\x1b[36m` around every
/// Implementation Plan number in the board's detail view.
fn ordered_cells(line: &str) -> Vec<Cell> {
if line.chars().next().is_none_or(|c| !c.is_ascii_digit()) {
return line.to_string();
return vec![Cell::plain(line)];
}
// Match "1. " pattern and color the number in cyan
let mut result = String::new();
// Match "1. " pattern and colour the number in cyan
let chars: Vec<char> = line.chars().collect();
for (i, c) in chars.iter().enumerate() {
if c.is_ascii_digit() {
// still scanning digits
} else if *c == '.' && i + 1 < chars.len() && chars[i + 1] == ' ' {
let number = &line[..i + 1];
result.push_str(&paint(number, Color::Cyan, colored));
result.push_str(&line[i + 1..]);
return result;
// Byte indexing on a char index, which holds because everything walked to
// get here is an ASCII digit or the dot itself.
return vec![
Cell::colored(&line[..i + 1], Color::Cyan),
Cell::plain(&line[i + 1..]),
];
} else {
break;
}
}
line.to_string()
vec![Cell::plain(line)]
}
/// Space between a label column and the value beside it, in the metadata table and in
@@ -948,33 +961,36 @@ fn metadata_row(line: &str) -> MetadataRow<'_> {
/// `campaign` is the resolved cell for the Campaign field, empty when there is none.
/// The file stores the full uuid, per the rule the Relations section already follows,
/// so a bare value here would be thirty-six characters saying nothing.
fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) -> String {
fn metadata_value_cells(name: &str, value: &str, campaign: &[Cell]) -> Vec<Cell> {
if name == CAMPAIGN_FIELD && !campaign.is_empty() {
return campaign.to_string();
return campaign.to_vec();
}
if name == "Priority" {
// Reads as a glyph, while the file keeps storing the number.
let (glyph, colour) = priority_mark(priority_from_value(value));
return format!("{} {}", paint(glyph, colour, colored), value);
return vec![
Cell::colored(glyph, colour),
Cell::plain(format!(" {}", value)),
];
}
if is_unknown_value(value) {
return paint(value, Color::Grey, colored);
return vec![Cell::colored(value, Color::Grey)];
}
// The same word in the same colour as the label a card draws, since `tag_color` is a
// pure function of it. No mark here: the field name has already said what this is,
// and the mark is what tells a campaign from a tag on a row that holds both.
if name == CODENAME_FIELD {
return paint(value, tag_color(value), colored);
return vec![Cell::colored(value, tag_color(value))];
}
if name == "Tags" {
return paint_tags(value, colored);
return tag_cells(value);
}
value.to_string()
vec![Cell::plain(value)]
}
/// The stored tag list with each tag in its own colour.
@@ -983,25 +999,28 @@ fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) -
/// 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 paint_tags(value: &str, colored: bool) -> String {
value
.split(',')
.map(|piece| {
let tag = piece.trim();
if tag.is_empty() {
return piece.to_string();
}
fn tag_cells(value: &str) -> Vec<Cell> {
let mut cells = Vec::new();
let lead = piece.len() - piece.trim_start().len();
format!(
"{}{}{}",
&piece[..lead],
paint(tag, tag_color(tag), colored),
&piece[lead + tag.len()..]
)
})
.collect::<Vec<_>>()
.join(",")
for (index, piece) in value.split(',').enumerate() {
if index > 0 {
cells.push(Cell::plain(","));
}
let tag = piece.trim();
if tag.is_empty() {
cells.push(Cell::plain(piece));
continue;
}
let lead = piece.len() - piece.trim_start().len();
cells.push(Cell::plain(&piece[..lead]));
cells.push(Cell::colored(tag, tag_color(tag)));
cells.push(Cell::plain(&piece[lead + tag.len()..]));
}
cells.retain(|cell| !cell.text.is_empty());
cells
}
/// Render the Metadata section as two aligned columns.
@@ -1009,7 +1028,7 @@ fn paint_tags(value: &str, colored: bool) -> String {
/// Taken as a block rather than a line at a time because the field column cannot be
/// sized until every name has been seen. The file is untouched by this: it goes on
/// storing the markdown list, and this is only how the list is shown.
fn render_metadata_table(lines: &[&str], colored: bool, campaign: &str) -> String {
fn metadata_cells(lines: &[&str], colored: bool, campaign: &[Cell]) -> Vec<Cell> {
// The heading already emits its own blank separator, so the one the template
// puts under it would otherwise open the section with a gap.
let start = lines
@@ -1030,21 +1049,23 @@ fn render_metadata_table(lines: &[&str], colored: bool, campaign: &str) -> Strin
.max()
.unwrap_or(0);
let mut result = String::new();
let mut result = Vec::new();
for row in &rows {
match row {
MetadataRow::Field { name, value } => {
result.push_str(&paint(name, Color::Red, colored));
result.push_str(&" ".repeat(field_width - name.chars().count()));
result.push_str(COLUMN_GUTTER);
result.push_str(&metadata_value_cell(name, value, colored, campaign));
result.push(Cell::colored(*name, Color::Red));
result.push(Cell::plain(format!(
"{}{}",
" ".repeat(field_width - name.chars().count()),
COLUMN_GUTTER
)));
result.extend(metadata_value_cells(name, value, campaign));
}
// The decision this row is rendered under, not the one the terminal
// would give: `colorize_line` asked `should_use_colors()` here, which is
// how escapes reached the board's detail view.
MetadataRow::Other(text) => result.push_str(&colorize_bold(text, colored)),
// `colored` reaches only this row, and only for the markers: a hand-written
// line is the one thing in the section that can carry inline markup.
MetadataRow::Other(text) => result.extend(inline_cells(text, colored)),
}
result.push('\n');
result.push(Cell::plain("\n"));
}
result
@@ -1077,52 +1098,93 @@ pub fn is_unknown_value(value: &str) -> bool {
trimmed == NONE || trimmed == NOT_SET
}
/// Replace `**bold**` with colour, or leave the line exactly as it is.
/// `**bold**` and `[text](url)` split into their own cells, or the line as one cell.
///
/// Taking `enabled` rather than asking makes both paths testable, and the
/// disabled path matters: stripping the markers when there is no colour to
/// replace them with loses the emphasis altogether, which is what happens to
/// every piped `show` and to everything the opencode tools read.
fn colorize_bold(line: &str, enabled: bool) -> String {
/// `enabled` is the only place in the body where the renderer's colour still changes
/// the layout, and it is why [`content_parts`] still takes the flag. The bold pair
/// gives its markers up to the colour that replaces them, so a renderer with none has
/// to keep them: stripping them there loses the emphasis rather than moving it, which
/// is what a piped `show` and everything the opencode tools read would get.
///
/// One walk for both markers rather than two passes. A pass over the output of
/// another would be scanning text that already holds escape sequences, and `\x1b[36m`
/// carries an opening bracket: a link scan run afterwards would take the escape for
/// markup. Walking the source once is the only place either marker can be recognised
/// for what it is.
fn inline_cells(line: &str, enabled: bool) -> Vec<Cell> {
if !enabled {
return line.to_string();
return vec![Cell::plain(line)];
}
let chars: Vec<char> = line.chars().collect();
let mut result = String::new();
let mut cells: Vec<Cell> = Vec::new();
let mut plain = String::new();
let mut i = 0;
while i < chars.len() {
if !is_delimiter(&chars, i) {
result.push(chars[i]);
i += 1;
// Unterminated markup falls through to the push below, one character at a
// time, so the rest of the line survives as the literal text it is. The old
// link branch pushed its match and dropped everything around it.
if is_delimiter(&chars, i)
&& let Some(close) = (i + 2..chars.len()).find(|&at| is_delimiter(&chars, at))
{
flush(&mut cells, &mut plain);
cells.push(Cell::colored(
chars[i + 2..close].iter().collect::<String>(),
Color::Magenta,
));
i = close + 2;
continue;
}
match (i + 2..chars.len()).find(|&at| is_delimiter(&chars, at)) {
Some(close) => {
let bold: String = chars[i + 2..close].iter().collect();
// `enabled`, not `should_use_colors()`. Asking again here made the
// flag a lie: the early return above respected it and this did not.
result.push_str(&paint(&bold, Color::Magenta, enabled));
i = close + 2;
}
// Unterminated: the rest is literal. The old scan walked off the end
// here and dropped the final character.
None => {
result.extend(&chars[i..]);
return result;
}
if chars[i] == '['
&& let Some(end) = link_end(&chars, i)
{
// Markers and url kept, unlike the bold pair. The url is content: a
// reader of `show` wants to see where the link goes, and the terminal
// that would make it clickable is not something worklane can count on.
flush(&mut cells, &mut plain);
cells.push(Cell::colored(chars[i..end].iter().collect::<String>(), Color::Cyan));
i = end;
continue;
}
plain.push(chars[i]);
i += 1;
}
result
flush(&mut cells, &mut plain);
cells
}
/// The plain run built so far, closed off ahead of a coloured one. An empty run pushes
/// nothing, so a line opening on a marker does not start with an empty cell.
fn flush(cells: &mut Vec<Cell>, plain: &mut String) {
if !plain.is_empty() {
cells.push(Cell::plain(std::mem::take(plain)));
}
}
fn is_delimiter(chars: &[char], at: usize) -> bool {
chars.get(at) == Some(&'*') && chars.get(at + 1) == Some(&'*')
}
/// The index one past the end of the `[text](url)` opening at `open`, or nothing when
/// the line does not close one.
///
/// The closing parenthesis is what ends a link. The old branch looked for a second
/// square bracket there, which a well-formed link does not have, so the whole branch
/// fired only on text that was not a link at all.
fn link_end(chars: &[char], open: usize) -> Option<usize> {
let close_text = (open + 1..chars.len()).find(|&at| chars[at] == ']')?;
if chars.get(close_text + 1) != Some(&'(') {
return None;
}
let close_url = (close_text + 2..chars.len()).find(|&at| chars[at] == ')')?;
Some(close_url + 1)
}
pub const METADATA_HEADING: &str = "## Metadata";
fn is_metadata_heading(line: &str) -> bool {
@@ -2151,21 +2213,16 @@ impl RelationIndex {
}
}
/// A cross reference as it reads: the short id, then the name it points at.
/// A cross reference in cells: the short id, then the name it points at.
///
/// `_missing_` rather than a bare uuid for something the board no longer holds. The id
/// is kept either way, since it is the only thing left to go looking for. Shared by the
/// relations block and the Campaign field, so a dangling reference is spelled one way
/// wherever it is shown.
pub fn reference_cell(uuid: &str, name: Option<&str>, colored: bool) -> String {
paint_cells(&reference_cells(uuid, name), colored)
}
/// The same cross reference in cells, for a renderer that is not writing escapes.
/// is kept either way, since it is the only thing left to go looking for.
///
/// The one spelling of a reference, so the relations block and the Campaign field cannot
/// come to say a dangling one differently, and the board draws the id in the colour the
/// guideline gives it rather than dropping every colour to stay safe.
/// come to say a dangling one differently, and every renderer draws the id in the colour
/// the guideline gives it rather than dropping every colour to stay safe. There was a
/// `reference_cell` beside this that painted the cells for the CLI; the Campaign field
/// was its last caller, and it now takes the cells like everything else.
pub fn reference_cells(uuid: &str, name: Option<&str>) -> Vec<Cell> {
let mut cells = vec![
Cell::plain("("),
@@ -2310,7 +2367,7 @@ pub struct Cell {
}
impl Cell {
fn plain(text: impl Into<String>) -> Self {
pub fn plain(text: impl Into<String>) -> Self {
Cell { text: text.into(), color: None }
}
@@ -3205,6 +3262,37 @@ impl Drop for Fixture {
#[cfg(test)]
mod tests {
/// One line's inline markup as a string, the shape these tests were written
/// against. `enabled` is both the marker decision and, here, the painting one,
/// which is what it was before the cells conversion split the two.
fn colorize_inline(line: &str, enabled: bool) -> String {
paint_cells(&inline_cells(line, enabled), enabled)
}
/// One metadata value as a string, the shape these tests were written against.
fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) -> String {
let campaign = match campaign.is_empty() {
true => Vec::new(),
false => vec![Cell::plain(campaign)],
};
paint_cells(&metadata_value_cells(name, value, &campaign), colored)
}
/// The metadata section as a string, the shape these tests were written against.
///
/// `metadata_cells` returns cells now, one layout for both renderers, so the CLI's
/// form is `paint_cells` over them. The campaign cell is a `&str` here because that
/// is all any of these needs: one run, already resolved.
fn render_metadata_table(lines: &[&str], colored: bool, campaign: &str) -> String {
let campaign = match campaign.is_empty() {
true => Vec::new(),
false => vec![Cell::plain(campaign)],
};
paint_cells(&metadata_cells(lines, colored, &campaign), colored)
}
use super::*;
/// The guard removes the directory when it goes out of scope, which is what makes the
@@ -4221,6 +4309,111 @@ mod tests {
assert_eq!(rendered, "Metadata\n────────\n\nID abc\nOwner alice\n");
}
/// A body holding one of everything the renderer paints, pinned byte for byte.
///
/// The guard for extending `Cell` to the whole body, e4d0bb7: the board and the CLI
/// now share one layout, and the risk in that is the CLI's output moving to suit the
/// board. Written from what `show` printed before the conversion, so a difference is
/// a regression rather than a rewrite. Every run the guideline gives a colour is in
/// here: heading, plan number, criterion number and mark, bold, link, field name,
/// priority glyph, tag, unset value, and a hand-written line the table carries
/// through.
const EVERY_PAINTED_RUN: &str = "\
# The Title
## Description
Plain line with **bold** and a [link](http://x.test/a).
## Acceptance Criteria
- [x] First, with **bold**
- [ ] Second
## Implementation Plan
1. Step one
2. Step two
## Metadata
- **ID**: 641e3d5a-0000-0000-0000-000000000000
- **Priority**: 2
- **Tags**: bug, cli
- **Due**: _Not set_
- **Owner**: alice
- A hand-written note with **bold**
- **Status**: backlog
";
#[test]
fn show_prints_the_same_body_it_printed_before_the_cells_conversion() {
let orange = |text: &str| paint(text, Color::Orange, true);
let cyan = |text: &str| paint(text, Color::Cyan, true);
let red = |text: &str| paint(text, Color::Red, true);
let bold = |text: &str| paint(text, Color::Magenta, true);
let grey = |text: &str| paint(text, Color::Grey, true);
let expected = format!(
"{}\n───────────\n\n\nPlain line with {} and a {}.\n\n\
{}\n───────────────────\n\n\n\
{} {} First, with {}\n{} {} Second\n\n\
{}\n───────────────────\n\n\n{} Step one\n{} Step two\n\n\
{}\n────────\n\n\
{} 641e3d5a-0000-0000-0000-000000000000\n\
{} {} 2\n\
{} {}, {}\n\
{} {}\n\
{} alice\n\
- A hand-written note with {}\n\
{} backlog\n",
orange("Description"),
bold("bold"),
cyan("[link](http://x.test/a)"),
orange("Acceptance Criteria"),
cyan("1."),
grey("[x]"),
bold("bold"),
cyan("2."),
grey("[ ]"),
orange("Implementation Plan"),
cyan("1."),
cyan("2."),
orange("Metadata"),
red("ID"),
red("Priority"),
paint("●◐", Color::Red, true),
red("Tags"),
paint("bug", tag_color("bug"), true),
paint("cli", tag_color("cli"), true),
red("Due"),
grey(NOT_SET),
red("Owner"),
bold("bold"),
red("Status"),
);
assert_eq!(content_trim(EVERY_PAINTED_RUN, true, &Resolved::default()), expected);
}
/// The other half of the pin: with colour off the same body carries no escape byte
/// at all. Asserted beside the coloured form so neither can pass vacuously, the rule
/// 6d327df's guard was written under.
#[test]
fn the_same_body_with_colour_off_carries_no_escape() {
let plain = content_trim(EVERY_PAINTED_RUN, false, &Resolved::default());
assert!(!plain.contains('\x1b'), "{plain:?}");
// The markers stay, since with no colour to carry the emphasis they are the
// emphasis. That is `colorize_inline`'s disabled path, not a gap in the pin.
assert!(
plain.contains("Plain line with **bold** and a [link](http://x.test/a)."),
"{plain:?}"
);
assert!(plain.contains("1. [x] First, with **bold**"), "{plain:?}");
assert!(plain.contains("Priority ●◐ 2"), "{plain:?}");
}
#[test]
fn a_section_after_metadata_still_renders() {
let content = "# T\n\n## Metadata\n\n- **ID**: abc\n\n## Notes\n\nafter\n";
@@ -4559,12 +4752,12 @@ mod tests {
#[test]
fn bold_markers_survive_when_colour_is_off() {
let line = "Some **bold** text";
assert_eq!(colorize_bold(line, false), line);
assert_eq!(colorize_inline(line, false), line);
}
#[test]
fn bold_markers_are_replaced_when_colour_is_on() {
let out = colorize_bold("Some **bold** text", true);
let out = colorize_inline("Some **bold** text", true);
assert!(out.contains("bold"), "was {out:?}");
assert!(!out.contains("**"), "markers left behind in {out:?}");
}
@@ -4573,17 +4766,82 @@ mod tests {
#[test]
fn an_unterminated_marker_keeps_the_whole_line() {
for line in ["a **bold", "**", "***", "trailing **"] {
assert_eq!(colorize_bold(line, true), line, "for {line:?}");
assert_eq!(colorize_inline(line, true), line, "for {line:?}");
}
}
#[test]
fn several_bold_runs_on_one_line_all_survive() {
let out = colorize_bold("**one** and **two** and rest", true);
let out = colorize_inline("**one** and **two** and rest", true);
assert!(out.contains("one") && out.contains("two") && out.ends_with("and rest"));
assert!(!out.contains("**"), "was {out:?}");
}
/// The old branch pushed the span it matched and dropped the rest of the line.
#[test]
fn a_link_keeps_the_text_on_either_side_of_it() {
let out = colorize_inline("see [the docs](https://x.test/y) for more", true);
assert!(out.starts_with("see "), "was {out:?}");
assert!(out.ends_with(" for more"), "was {out:?}");
assert!(out.contains("[the docs](https://x.test/y)"), "was {out:?}");
assert!(out.contains(Color::Cyan.ansi()), "not painted in {out:?}");
}
/// With no colour to carry it, the markup is the markup.
#[test]
fn a_link_survives_unchanged_when_colour_is_off() {
let line = "see [the docs](https://x.test/y) for more";
assert_eq!(colorize_inline(line, false), line);
}
/// The closing parenthesis ends a link. Looking for a second square bracket there,
/// as the old branch did, meant it fired on anything but a link.
#[test]
fn text_that_is_not_a_closed_link_is_left_alone() {
for line in [
"a [label] and (a note)",
"unterminated [text](http://x.test",
"[a][b] reference style",
"bare [",
] {
assert_eq!(colorize_inline(line, true), line, "for {line:?}");
}
}
#[test]
fn several_links_on_one_line_all_survive() {
let out = colorize_inline("[a](1) then [b](2) then end", true);
assert!(out.contains("[a](1)") && out.contains("[b](2)"), "was {out:?}");
assert!(out.ends_with(" then end"), "was {out:?}");
}
/// Both markers are recognised in the same walk, so a line does not have to pick
/// which of the two it gets.
#[test]
fn bold_and_a_link_on_one_line_are_both_coloured() {
let out = colorize_inline("**note**: read [this](http://x.test) first", true);
assert!(!out.contains("**"), "markers left behind in {out:?}");
assert!(out.contains("[this](http://x.test)"), "was {out:?}");
assert!(out.contains(Color::Magenta.ansi()), "no bold in {out:?}");
assert!(out.contains(Color::Cyan.ansi()), "no link in {out:?}");
assert!(out.ends_with(" first"), "was {out:?}");
}
/// End to end: the body a `show` prints keeps every word of a line with a link.
#[test]
fn a_body_line_with_a_link_keeps_all_of_its_text() {
let content = "# T\n\n## Description\n\nbefore [docs](http://x.test/a) after\n";
let rendered = content_trim(content, false, &Resolved::default());
assert!(
rendered.ends_with("before [docs](http://x.test/a) after\n"),
"{rendered:?}"
);
}
#[test]
fn short_id_shortens_a_full_uuid() {
assert_eq!(short_id("c230d2c6-d78a-44a5-8f5f-88fb28f84493"), "c230d2c");