Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
a16169ce8c | ||
|
|
3d6a74bc53 | ||
|
|
7a0dd625ce | ||
|
|
8d8ae8abfe |
@@ -10,6 +10,7 @@
|
||||
- `src/install.rs` - the embedded agent assets and the compare-and-refuse install
|
||||
- `assets/SKILL.md` - the agent skill for the CLI itself, embedded with `include_str!`
|
||||
- `assets/REVIEW.md` - the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach; `SKILL.md` keeps its name because the role it teaches is the CLI
|
||||
- `assets/PLAN.md` - the agent skill for grooming the whole board: priorities, due dates, tags and campaigns
|
||||
- `tests/` - Integration tests using `assert_cmd` and `assert_fs`, one file per command
|
||||
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `handlers.rs` and `tui.rs`
|
||||
- Ticket files stored as `.md` in `.worklane/<status>/` directories
|
||||
@@ -52,6 +53,10 @@ and this file is for what someone changing worklane's own code needs.
|
||||
### CLI Arguments
|
||||
- The prose arguments carry `allow_hyphen_values`, via the `PROSE` constant in `command.rs`: `add --title`, `--description`, `--acceptance`, `--plan`, and the `comment` body. Ticket text quotes flag names constantly, and without it a criterion reading `--print is supported` is parsed as a flag and the whole ticket is refused with nothing written
|
||||
- **The trade:** on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why `due`, `priority`, `tags`, `owner` and `status` are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add `PROSE` to a new argument unless it holds prose
|
||||
- **`--due` is validated at parse time by `iso_date`, the way `--priority` is by `priority_level`.** A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars without `PROSE`. One parser serves `add` and `set`: the field has one definition of what it accepts, and validating only `add` would leave `set` open, which is the command a grooming sweep actually uses
|
||||
- **The shape is checked before chrono is asked.** `%Y-%m-%d` accepts an unpadded `2026-8-9`, which would be stored exactly as typed and sort before `2026-10-01` in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting
|
||||
- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
|
||||
- An empty `--due` keeps `non_empty`'s message about clearing rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is that clearing is not supported yet
|
||||
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title`
|
||||
- A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment <ticket> -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
|
||||
- `add` has no positionals, so anything after a bare `--` is an unexpected argument and fails
|
||||
@@ -93,7 +98,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `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
|
||||
- **The blocker check runs on every move**, after the already-in-that-status return and behind `force`. An open blocker is a reason not to start and a reason not to finish, and one rule is easier to hold than a table of which transitions care. A move to the status the ticket is already in is not a move, so it is not refused. `-f` now bypasses three rules, which is the right home for it: each one is a deliberate override of something the board would otherwise keep true
|
||||
- **A blocker that is not on the board warns and allows the move.** Refusing would wedge the ticket with no way out but `-f`, and a uuid nothing carries is a bookkeeping fault rather than a dependency. The refusal names **every** open blocker, since clearing the one that happened to be printed would leave the ticket blocked
|
||||
- Left out on purpose: removing a relation, which 4179958 assigns to 74904dc, and a blocked marker on the TUI card, which is its own ticket. Nothing on a card is worth a scan of the board per tick until the card is designed for it
|
||||
- Left out on purpose: removing a relation, which 4179958 assigns to 74904dc. The blocked marker on the card landed in b8ce18c, and it cost no scan of the board: the blockers ride along on the read that already builds the cards. See The Board View
|
||||
|
||||
### Campaigns
|
||||
|
||||
@@ -108,7 +113,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **`Resolved` carries what `content_trim` cannot render from the file.** The relations block and the campaign cell both come from elsewhere on the board. A struct rather than two more parameters, so the next such field is one entry here instead of an edit at every call site
|
||||
- `campaign show` lists **done** members, unlike `ls`, which leaves the done column out of its listing. What is finished against what is left is the whole question a campaign asks, so hiding half the answer is not an option. `ls --campaign` is the other way round: it is the ordinary board filtered, and keeps every rule `ls` already has
|
||||
- `campaign ls` scans the status directories **once per campaign** to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice
|
||||
- **The TUI gets neither a campaign tab nor a card marker**, for now. The detail view resolves the field because it renders the body, and that is all. A marker on a card would want a campaigns read per reload and the four corners are already spent; same reasoning as the blocked marker, which is also its own ticket
|
||||
- **The TUI gets neither a campaign tab nor a card marker**, for now. The detail view resolves the field because it renders the body, and that is all. A marker on a card would want a campaigns read per reload, which is more than the blocked mark cost: that one reads the ticket's own Relations section on the pass that already builds the card, and a campaign title is in another directory
|
||||
- `campaign_body()` builds the file from `DESCRIPTION` and `METADATA_HEADING` rather than its own string literals, so the two file formats cannot drift apart on the spelling of a heading. A campaign has no acceptance criteria (its definition of done is derived), no implementation plan and no Status
|
||||
- The campaigns directory is created by `init` and **on demand** by `campaign add`, since every board made before campaigns existed has none and a `worklane init` over a live board to get one would be a strange thing to have to do
|
||||
|
||||
@@ -141,6 +146,12 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- The criteria count is a field on `TicketItem`, filled in `collect_ticket_items` where the file is already being read, and counted through `criteria()` so a checkbox in a description is not counted here or numbered by `show`. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. `None` rather than `[0/0]` for a ticket with no criteria
|
||||
- **The tags go under the title, dimmed, each prefixed with `#`.** The field was invisible on the board: nothing said a ticket was tagged `bug` without opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one
|
||||
- `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 `×` after its id, in brightred.** 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
|
||||
- **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
|
||||
@@ -178,6 +189,8 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **A refused document does not stop the ones behind it.** The loop reports an outcome per document and the "pick it up on their next session" line is printed once, and only when something was actually written
|
||||
- **A role skill is its own document, not a section of `SKILL.md`.** The frontmatter description is the whole of what decides whether a skill loads, and one description cannot name both "anything touching a ticket" and "only when a review is asked for" without fitting neither. It is also why the review document does not restate the CLI: it says to read the `worklane` skill too
|
||||
- The review skill's own rules are guarded by `the_review_skill_keeps_the_decisions_that_define_it`, because each of them is a line an edit could drop without breaking anything: **the reviewer never ticks a criterion** (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), **never moves the ticket** (`mv` belongs to whoever does the work, the reviewer's half is the recommendation), and **never reviews the working tree when no commit names the ticket** (it says what it searched for and stops, since an untraceable ticket in `reviewing` is itself the finding)
|
||||
- **The plan skill is the one that can do damage, so its rules are the ones under test.** `set --tags` replaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable. `the_plan_skill_keeps_the_rules_that_bound_a_sweep` pins propose-then-apply and those two traps, because a document that loses them still reads like a plan
|
||||
- `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document
|
||||
- `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
|
||||
|
||||
### Color and Output
|
||||
@@ -198,6 +211,11 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Title → green (32)
|
||||
- Unknown values (`_None_`, `_Not set_`) → grey (38;5;8)
|
||||
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
|
||||
- **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
|
||||
- `tag_color()` is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, because `Bug` and `bug` are two different tags to the field and to every search
|
||||
- **The hash is FNV-1a written out here, not `DefaultHasher`.** std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for. `the_tag_mapping_is_pinned` fails on any change to it, so a repaint is a decision rather than a surprise
|
||||
- **The index is multiply-shift, not `% TAG_COLORS.len()`.** The length is a power of two, so a modulus keeps only the low three bits of the hash, and FNV-1a's low bits carry only the low bits of the input bytes: multiplication cannot move information downwards. Under a modulus every pair of tags differing above bit 2, `bug` and `BUG` among them, landed in one slot regardless of the rest of the string. It looked like a *good* palette on this board, two colliding cards out of sixty-four, because the vocabulary had been folded into a handful of slots. Taking the top bits of a 128-bit product uses the whole hash
|
||||
- Eight tag colours means roughly one card in five shows two tags alike. That is arithmetic and is accepted: the colour groups a tag across cards, it does not tell two tags apart within one, and the tag text is beside it either way. Do not widen the list to chase the number on one board
|
||||
- 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
|
||||
|
||||
Generated
+1
-1
@@ -1494,7 +1494,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "worklane"
|
||||
version = "0.13.0"
|
||||
version = "0.13.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "worklane"
|
||||
version = "0.13.0"
|
||||
version = "0.13.4"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
@@ -7,7 +7,7 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
|---------|-------------|
|
||||
| `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. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, `q` to quit. 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 directories |
|
||||
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags |
|
||||
| `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>` |
|
||||
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring |
|
||||
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
|
||||
@@ -18,7 +18,7 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
| `worklane check <ticket> [criterion]` | Ticks one acceptance criterion, by number as shown by `show` or by a substring. Prompts with the numbered list if omitted, or errors with it when there is no terminal |
|
||||
| `worklane uncheck <ticket> [criterion]` | Unticks one acceptance criterion, addressed the same way |
|
||||
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
|
||||
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Two ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
|
||||
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Three ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
|
||||
|
||||
## Exit codes
|
||||
| Code | Meaning |
|
||||
|
||||
+183
@@ -0,0 +1,183 @@
|
||||
---
|
||||
name: worklane-plan
|
||||
description: Groom a worklane board as a whole rather than one ticket at a time: review whether the priorities are right relative to each other, plan work by setting due dates, check the tags for consistency, and find the tickets that belong together in a campaign. Use for questions about the backlog as a body of work, what to do next week, what is mis-prioritised or mis-tagged, and what could become one goal. Not for filing or working a single ticket.
|
||||
---
|
||||
|
||||
# Planning a worklane board
|
||||
|
||||
For "are the backlog priorities right", "plan in tickets for next week", "check the
|
||||
tagging", "which of these could be one campaign". The subject is the board, not a
|
||||
ticket. Filing one, working one and reviewing one are other jobs.
|
||||
|
||||
The CLI itself is the `worklane` skill: the statuses, how a ticket is addressed and
|
||||
which command owns which field. Read it too. This document is the judgement.
|
||||
|
||||
## The one rule
|
||||
|
||||
**Propose the whole set of edits, wait, then apply exactly what was approved.**
|
||||
|
||||
Every job here writes to many tickets at once, and no field can be cleared back to unset
|
||||
yet, so a date written onto the wrong ticket can only be overwritten, never taken off. A wrong
|
||||
edit to one ticket is a mistake; a wrong sweep is thirty of them with no undo. So a
|
||||
proposal is a list, one line per intended edit, each naming the ticket and the command
|
||||
that would make it:
|
||||
|
||||
```
|
||||
(1b78a24) priority 3 -> 1 worklane set 1b78a24 --priority 1
|
||||
(4179958) due -> 2026-08-29 worklane set 4179958 --due 2026-08-29
|
||||
```
|
||||
|
||||
Then apply what was approved and nothing else. Not "and a few obvious ones while I was
|
||||
there": an approval is for the list that was shown.
|
||||
|
||||
## Who writes what
|
||||
|
||||
Every field has exactly one command that writes it, and a sweep that reaches for any
|
||||
other way is editing the file by hand:
|
||||
|
||||
| Field | Writer |
|
||||
|-------|--------|
|
||||
| Priority, Due, Tags | `worklane set <ticket> --priority` / `--due` / `--tags` |
|
||||
| Relations | `worklane relate <ticket> --blocked-by` / `--regression-of` / `--relates-to` |
|
||||
| Campaign membership | `worklane assign <campaign> <ticket>` |
|
||||
| Owner | `worklane chown <user> <ticket>` |
|
||||
| Status | `worklane mv <ticket> --status <target>` |
|
||||
|
||||
**Never edit a ticket file directly.** The filename, the `Status` field and the directory
|
||||
have to agree, and the commands are what keep them agreeing. A hand-written Relations
|
||||
line is worse still: it is the one section read back by machine, and a target that does
|
||||
not resolve to a uuid is an error on every later read of that ticket.
|
||||
|
||||
The last two rows are in the table to be recognised, not used. See the closing section.
|
||||
|
||||
## Read the board first
|
||||
|
||||
```
|
||||
worklane ls # every status, counts then tickets
|
||||
worklane ls backlog # one status
|
||||
worklane ls --priority 1 # the top of the pile
|
||||
worklane show 1b78a24 # one ticket, with its relations and comments
|
||||
worklane campaign ls # the goals that already exist
|
||||
```
|
||||
|
||||
`ls` prints the mark, the id, the title, the owner and the due date. It does **not**
|
||||
print tags, and there is no tag filter yet, so any judgement about tags means reading the
|
||||
tickets themselves. On a board of a few dozen that is a `show` per ticket and is worth
|
||||
doing rather than guessing from titles.
|
||||
|
||||
Read `done` too when the question is about what to do next. What was finished last is the
|
||||
best evidence of what this board actually moves at, and a plan that ignores it is a wish.
|
||||
|
||||
## Priorities
|
||||
|
||||
Priority runs **1 most urgent to 5 least**, and may be unset. `worklane set <ticket>
|
||||
--priority <n>` is the only writer.
|
||||
|
||||
Priority is relative. A ticket is never urgent by itself, it is urgent above something
|
||||
else, so every proposed change has to name what it now sits above and below. "This looks
|
||||
important" is not a reason; "this blocks three tickets that are all dated before it" is.
|
||||
|
||||
What to look for:
|
||||
|
||||
- **A blocker priced below what it blocks.** Read the Relations. A ticket that others are
|
||||
`blocked by` cannot be less urgent than the most urgent of them, or the board is asking
|
||||
for work in an order it will not allow.
|
||||
- **A flat board.** If almost everything is 3, the field is carrying no information and
|
||||
the answer is not to renumber everything at once. Propose the few that are genuinely 1
|
||||
and the few that are genuinely 5, and leave the middle alone.
|
||||
- **Too many 1s.** If everything is urgent, nothing is. Say how many there are before
|
||||
proposing another.
|
||||
- **A low priority already in `committed`.** Either the priority is wrong or starting it
|
||||
was, and which one it is decides whether the fix is a `set` or a conversation.
|
||||
- **A priority nobody has touched since the ticket was filed.** It is the filer's first
|
||||
guess, not a decision. That is the pile worth reading.
|
||||
|
||||
## Due dates
|
||||
|
||||
`worklane set <ticket> --due 2026-08-29`, format `YYYY-MM-DD`.
|
||||
|
||||
A value that is not a real calendar date in that exact form is refused before anything
|
||||
is written, so a typo costs nothing. `2026-8-9` is refused too: the padding is part of
|
||||
the format. What is still true is that a date, once written, **cannot be cleared**, only
|
||||
replaced by another date, so a plan applied to the wrong ticket has no undo.
|
||||
|
||||
Ask the system what today is rather than assuming it. A plan built on a guessed date is
|
||||
wrong by however much the guess was wrong.
|
||||
|
||||
The rules a dating plan has to keep:
|
||||
|
||||
- **Nothing is dated before the ticket it is blocked by.** Read the Relations first and
|
||||
date blockers ahead of their dependents. A dependent dated before its blocker is a date
|
||||
`mv` will refuse to honour anyway.
|
||||
- **A blocker left undated makes its dependent's date a fiction.** Either date both or
|
||||
neither.
|
||||
- **Date what fits, not what exists.** Ask how much capacity the week holds, or take the
|
||||
answer from what `done` shows the board finishing in a comparable stretch. Dating the
|
||||
whole backlog produces a board where every ticket is late, which is the same as no
|
||||
dates at all.
|
||||
- **Do not date `done`.** It is finished; a date on it is noise in every listing.
|
||||
- Leave the rest unset. An unset due date is honest about what has not been planned.
|
||||
|
||||
## Tags
|
||||
|
||||
`worklane set <ticket> --tags bug,cli` is the writer, and it **replaces the whole
|
||||
field**. Restate every tag the ticket should keep, or the ones you left out are gone.
|
||||
This is the single most destructive thing in this document.
|
||||
|
||||
Derive the vocabulary from the board rather than inventing one. Read the tickets, count
|
||||
what is actually used, and show the count before proposing anything. What to report:
|
||||
|
||||
- **Two spellings of one idea.** `bug` and `bugfix`, `tui` and `ui`. Pick the one already
|
||||
used more and say so.
|
||||
- **A tag used exactly once.** Either it is the start of a category and should be applied
|
||||
to its siblings, or it is a private note and should go. Do not leave it as it is without
|
||||
saying which.
|
||||
- **A tag that restates a field.** A `p1` tag beside a Priority field, an `open` tag
|
||||
beside a Status, an owner's name as a tag. The field is the writer; the tag is a copy
|
||||
that will disagree with it. This board already made that mistake once with priority and
|
||||
undid it deliberately.
|
||||
- **An untagged ticket** in a board where everything else is tagged. It is invisible to
|
||||
every question asked by tag.
|
||||
|
||||
Tags are for kind, not for state and not for goal. State is the status directory and the
|
||||
fields; a goal is a campaign.
|
||||
|
||||
## Campaigns
|
||||
|
||||
```
|
||||
worklane campaign ls
|
||||
worklane campaign show "v1 release"
|
||||
worklane campaign add --title "..." --description "..."
|
||||
worklane assign "v1 release" 1b78a24
|
||||
```
|
||||
|
||||
A campaign is the tickets that have to be finished **together** for one outcome. The test
|
||||
is whether you can name the outcome in a single line without listing the members. "The
|
||||
tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
|
||||
|
||||
- **Do not group by tag.** Ten tickets tagged `bug` share a kind, not a goal, and putting
|
||||
them in a container says nothing that the tag did not already say.
|
||||
- **Check what exists first.** `campaign ls` before proposing a new one, or you will
|
||||
propose a second container for a goal that already has one.
|
||||
- **A ticket is in at most one campaign**, and `assign` moves it rather than adding a
|
||||
second. So two proposed campaigns that overlap are really one proposal to take members
|
||||
out of the other, and it has to say so.
|
||||
- **A campaign's state is derived**, open until every member is done. There is nothing to
|
||||
close and nothing to move. A campaign whose members are all done is finished already.
|
||||
- `assign` takes the **campaign first and the ticket second**, like `chown`.
|
||||
|
||||
Proposing a campaign means naming the goal, the members, and what is deliberately left
|
||||
out of it. The last part is what makes it a goal rather than a pile.
|
||||
|
||||
## What a planner does not touch
|
||||
|
||||
- **Descriptions, acceptance criteria and implementation plans.** They are the ticket
|
||||
author's account of the work, and grooming is about how the work is ordered, not what
|
||||
it is. Something wrong in there is a comment on that ticket.
|
||||
- **Status.** `mv` belongs to whoever does the work. A plan that moves tickets between
|
||||
columns is reporting progress that did not happen.
|
||||
- **Owner.** `chown` records a commitment a person made. Propose it, do not write it,
|
||||
unless you were asked to assign the work.
|
||||
- **New tickets.** Grooming is about what is on the board. Something genuinely missing is
|
||||
worth filing, by the rules in the `worklane` skill, but say it is a new ticket rather
|
||||
than folding it into a grooming sweep.
|
||||
@@ -85,6 +85,9 @@ worklane add \
|
||||
checked off as true or false.
|
||||
- **`--plan`** takes one step per flag, numbered for you.
|
||||
- **`--priority`** runs 1 (most urgent) to 5 (least), and is left unset if omitted.
|
||||
- **`--due`** takes `YYYY-MM-DD` and nothing else. Anything that is not a real calendar
|
||||
date in that exact form, `2026-8-9` and `2026-02-30` included, is a usage error with
|
||||
nothing written. The same parser guards `set --due`.
|
||||
|
||||
Editing afterwards, on a ticket in any status:
|
||||
|
||||
|
||||
+44
-2
@@ -2,6 +2,8 @@ use clap::Parser;
|
||||
|
||||
use std::sync::LazyLock;
|
||||
|
||||
use chrono::NaiveDate;
|
||||
|
||||
use crate::util::{PRIORITY_RANGE, RelationKind, priority_legend};
|
||||
|
||||
/// clap wants a `&str` with a long enough lifetime, and the legend is built from
|
||||
@@ -53,6 +55,42 @@ fn non_empty(raw: &str) -> Result<String, String> {
|
||||
Ok(raw.to_string())
|
||||
}
|
||||
|
||||
/// Reject a due date that is not a real calendar date in the promised form.
|
||||
///
|
||||
/// At parse time, like `priority_level`, so a mistyped date is a usage error with
|
||||
/// nothing written rather than a value the board goes on showing. `--due` is one of the
|
||||
/// scalars deliberately left without `PROSE`, so this is the same bargain: nothing here
|
||||
/// holds prose, and a wrong value should stop the command.
|
||||
///
|
||||
/// **The shape is checked before chrono sees it.** `%Y-%m-%d` accepts an unpadded
|
||||
/// `2026-8-9`, which would then be stored exactly as typed and sort before `2026-10-01`
|
||||
/// in any comparison of the strings. Checking the length and the two dashes first is
|
||||
/// what lets a valid date be stored unchanged rather than normalised on the way in.
|
||||
///
|
||||
/// Strict on the way in, tolerant on the way out: `util::due_date` still cuts a
|
||||
/// datetime down to its date, because a file written before this existed, or by hand,
|
||||
/// can hold one and still has to render.
|
||||
fn iso_date(raw: &str) -> Result<String, String> {
|
||||
// An empty value keeps the message that explains why it is refused, since somebody
|
||||
// typing it is reaching for a way to clear the field rather than mistyping a date.
|
||||
non_empty(raw)?;
|
||||
|
||||
let bytes = raw.as_bytes();
|
||||
let shaped = raw.len() == 10 && bytes[4] == b'-' && bytes[7] == b'-';
|
||||
|
||||
if !shaped || NaiveDate::parse_from_str(raw, "%Y-%m-%d").is_err() {
|
||||
// Not echoing the value: clap has already printed `invalid value '...' for
|
||||
// '--due <DUE>'` above this line, and `priority_level` says its piece the same
|
||||
// way.
|
||||
return Err(
|
||||
"due date must be a real calendar date written as YYYY-MM-DD, for example 2026-08-29"
|
||||
.to_string(),
|
||||
);
|
||||
}
|
||||
|
||||
Ok(raw.to_string())
|
||||
}
|
||||
|
||||
/// Arguments that carry prose, and therefore have to accept a value starting with
|
||||
/// a hyphen.
|
||||
///
|
||||
@@ -275,7 +313,7 @@ pub struct AddArgs {
|
||||
pub tags: Vec<String>,
|
||||
|
||||
/// Due date (YYYY-MM-DD)
|
||||
#[arg(long)]
|
||||
#[arg(long, value_parser = iso_date)]
|
||||
pub due: Option<String>,
|
||||
|
||||
/// Owner
|
||||
@@ -324,7 +362,11 @@ pub struct SetArgs {
|
||||
pub tags: Vec<String>,
|
||||
|
||||
/// Replace the due date (YYYY-MM-DD)
|
||||
#[arg(long, value_parser = non_empty)]
|
||||
///
|
||||
/// The same parser as `add`: one field, one definition of what a due date is. The
|
||||
/// planning skill sets dates through `set` rather than `add`, so validating only
|
||||
/// the one that files a ticket would leave the path that is actually used open.
|
||||
#[arg(long, value_parser = iso_date)]
|
||||
pub due: Option<String>,
|
||||
|
||||
/// Replace the priority, 1 (most urgent) to 5 (least)
|
||||
|
||||
+37
-1
@@ -54,11 +54,24 @@ pub const REVIEW_SKILL: Asset = Asset {
|
||||
content: include_str!("../assets/REVIEW.md"),
|
||||
};
|
||||
|
||||
/// The skill that grooms the board as a whole rather than a ticket at a time.
|
||||
///
|
||||
/// Its own document for the reason `REVIEW_SKILL` is: it is wanted for questions about
|
||||
/// the backlog as a body of work, and loading it for every ticket touched would be a
|
||||
/// description that fits nothing. It is also the document where the destructive edits
|
||||
/// live, since every job in it writes to many tickets at once.
|
||||
pub const PLAN_SKILL: Asset = Asset {
|
||||
name: "worklane-plan",
|
||||
what: "skill",
|
||||
relative: "worklane-plan/SKILL.md",
|
||||
content: include_str!("../assets/PLAN.md"),
|
||||
};
|
||||
|
||||
/// Every skill this binary carries, in the order they install.
|
||||
///
|
||||
/// A `static` rather than a `const` so the slice borrowed from it outlives the
|
||||
/// statement that took it: a `const` is inlined at each use and the borrow dies there.
|
||||
pub static SKILLS: [Asset; 2] = [SKILL, REVIEW_SKILL];
|
||||
pub static SKILLS: [Asset; 3] = [SKILL, REVIEW_SKILL, PLAN_SKILL];
|
||||
|
||||
/// The skill a name on the command line asks for.
|
||||
pub fn skill_named(name: &str) -> Result<&'static Asset> {
|
||||
@@ -363,6 +376,29 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
/// The rules that keep a grooming sweep from being a silent rewrite of the board.
|
||||
///
|
||||
/// Every one of these is a line an edit could drop while leaving a document that
|
||||
/// still reads like a plan: `set --tags` replacing the whole field is how thirty
|
||||
/// tickets quietly lose their tags, and propose-then-apply is the only thing
|
||||
/// standing between a wrong judgement and thirty wrong tickets.
|
||||
#[test]
|
||||
fn the_plan_skill_keeps_the_rules_that_bound_a_sweep() {
|
||||
for required in [
|
||||
"Propose the whole set of edits",
|
||||
"replaces the whole\nfield", // `set --tags` is the destructive one
|
||||
"cannot be cleared", // and a due date cannot be taken back
|
||||
"blocked by", // ordering constrains any dating plan
|
||||
"worklane campaign ls",
|
||||
"does not touch",
|
||||
] {
|
||||
assert!(
|
||||
PLAN_SKILL.content.contains(required),
|
||||
"the plan skill no longer says {required:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// The decisions that make the review document a review rather than a rewrite.
|
||||
///
|
||||
/// Each of these is a rule an edit would drop without breaking anything else: a
|
||||
|
||||
+336
-29
@@ -7,6 +7,7 @@
|
||||
//! **Read only.** Moving a card by keypress is a follow-up. Everything here observes.
|
||||
|
||||
use std::collections::hash_map::DefaultHasher;
|
||||
use std::collections::HashMap;
|
||||
use std::hash::{Hash, Hasher};
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::time::{Duration, SystemTime};
|
||||
@@ -100,6 +101,14 @@ fn project_name(dir: &Path) -> String {
|
||||
pub struct Card {
|
||||
pub ticket: TicketItem,
|
||||
pub project: Option<String>,
|
||||
/// Whether a ticket this one is `blocked by` is on the board and not done.
|
||||
///
|
||||
/// Decided at reload like `project`, and for a stronger reason: the answer lives on
|
||||
/// two tickets at once, so no card can reach it alone and asking per draw would mean
|
||||
/// reading the tree per frame. Computed on the board the ticket came from and
|
||||
/// carried into the merge unchanged — `relate` resolves its target against one
|
||||
/// `.worklane`, so there is no such thing as a blocker in another project.
|
||||
pub blocked: bool,
|
||||
}
|
||||
|
||||
/// One status and the cards in it.
|
||||
@@ -534,7 +543,7 @@ fn detail_of(card: &Card) -> Detail {
|
||||
|
||||
/// The four columns of one board.
|
||||
fn columns_of(worklane_dir: &Path) -> Vec<Column> {
|
||||
status_dirs()
|
||||
let mut columns: Vec<Column> = status_dirs()
|
||||
.into_iter()
|
||||
.map(|status| {
|
||||
// An absent or unreadable directory is an empty column, not a missing one:
|
||||
@@ -545,11 +554,47 @@ fn columns_of(worklane_dir: &Path) -> Vec<Column> {
|
||||
.map(|ticket| Card {
|
||||
ticket,
|
||||
project: None,
|
||||
blocked: false,
|
||||
})
|
||||
.collect();
|
||||
Column { status, cards }
|
||||
})
|
||||
.collect()
|
||||
.collect();
|
||||
|
||||
mark_blocked(&mut columns);
|
||||
columns
|
||||
}
|
||||
|
||||
/// Set `blocked` on every card whose ticket waits on one that is not done.
|
||||
///
|
||||
/// Two walks of what `columns_of` has just read, not a lookup per relation: the status
|
||||
/// of a blocker is on another card, so the pass builds the uuid to status map once and
|
||||
/// then answers every card from it. Nothing is read from disk here, which is the point
|
||||
/// — the blockers came off the same read that built the cards.
|
||||
///
|
||||
/// A blocker the board does not hold marks nothing, the answer `mv` already gives it: a
|
||||
/// uuid nothing carries is a bookkeeping fault rather than a dependency. A ticket with
|
||||
/// no ID field is left out of the map entirely, or every ticket missing one would block
|
||||
/// every other ticket missing one, which is the guard `RelationIndex::inbound` makes.
|
||||
fn mark_blocked(columns: &mut [Column]) {
|
||||
let status_of: HashMap<String, &'static str> = columns
|
||||
.iter()
|
||||
.flat_map(|column| {
|
||||
column
|
||||
.cards
|
||||
.iter()
|
||||
.map(|card| (card.ticket.uuid.clone(), column.status))
|
||||
})
|
||||
.filter(|(uuid, _)| !uuid.trim().is_empty() && !is_unknown_value(uuid))
|
||||
.collect();
|
||||
|
||||
for column in columns.iter_mut() {
|
||||
for card in column.cards.iter_mut() {
|
||||
card.blocked = card.ticket.blockers.iter().any(|blocker| {
|
||||
matches!(status_of.get(blocker.as_str()), Some(status) if *status != DONE)
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Every board's columns as one set of four, each card labelled with the project it
|
||||
@@ -571,6 +616,10 @@ fn merge(per_project: &[Vec<Column>], projects: &[Project]) -> Vec<Column> {
|
||||
cards.extend(column.cards.iter().map(|card| Card {
|
||||
ticket: card.ticket.clone(),
|
||||
project: Some(project.name.clone()),
|
||||
// Already answered on the board the card came from. Recomputing it
|
||||
// over the merged columns would let one project's uuid resolve
|
||||
// against another's ticket, which is a relation nothing can record.
|
||||
blocked: card.blocked,
|
||||
}));
|
||||
}
|
||||
|
||||
@@ -824,6 +873,15 @@ fn aligned_offset(offset: u16, start: u16, end: u16, inner: u16, total: u16) ->
|
||||
offset.min(total.saturating_sub(inner))
|
||||
}
|
||||
|
||||
/// The mark a card carries while it waits on a ticket that is not done.
|
||||
///
|
||||
/// Not a fourth circle. The Geometric Shapes glyphs belong to the priority meter, and
|
||||
/// another one two cells away from it would read as part of that ramp rather than as a
|
||||
/// different fact. A multiplication sign is Latin-1, like the middle dot the unset
|
||||
/// priority draws, so it renders wherever the meter already does. That is the same
|
||||
/// safe-glyph rule that took the quadrant circles out of the ramp.
|
||||
const BLOCKED_MARK: &str = "\u{d7}";
|
||||
|
||||
/// One card as four corners with the title between them:
|
||||
///
|
||||
/// ```text
|
||||
@@ -845,6 +903,10 @@ fn aligned_offset(offset: u16, start: u16, end: u16, inner: u16, total: u16) ->
|
||||
///
|
||||
/// The tags sit between the title and the bottom corners, on a row a ticket without
|
||||
/// them does not spend. See [`tags_line`].
|
||||
///
|
||||
/// A held-up ticket carries [`BLOCKED_MARK`] after its id, ahead of the project and the
|
||||
/// due date, both of which 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.
|
||||
fn card_lines(card: &Card, selected: bool, width: u16) -> Vec<Line<'static>> {
|
||||
let ticket = &card.ticket;
|
||||
let (glyph, colour) = priority_mark(ticket.priority);
|
||||
@@ -865,10 +927,25 @@ fn card_lines(card: &Card, selected: bool, width: u16) -> Vec<Line<'static>> {
|
||||
Style::default().fg(Color::Red.into()).add_modifier(emphasis),
|
||||
),
|
||||
];
|
||||
// After the id, not before it: inserted ahead of the id the mark would push it out
|
||||
// of line, and a column of ids that do not start at the same cell is harder to read
|
||||
// than one card's worth of state is worth. Dropped whole when the row cannot hold
|
||||
// the identity and the mark together, the rule a corner follows, rather than
|
||||
// wrapping or cutting it.
|
||||
if card.blocked && spans_width(&left) + 1 + BLOCKED_MARK.chars().count() <= width as usize {
|
||||
left.push(Span::raw(" "));
|
||||
left.push(Span::styled(
|
||||
BLOCKED_MARK.to_string(),
|
||||
Style::default()
|
||||
.fg(Color::BrightRed.into())
|
||||
.add_modifier(emphasis),
|
||||
));
|
||||
}
|
||||
|
||||
let label = card
|
||||
.project
|
||||
.as_deref()
|
||||
.and_then(|name| project_label(name, width));
|
||||
.and_then(|name| project_label(name, width, spans_width(&left)));
|
||||
if let Some(label) = label {
|
||||
left.push(Span::raw(" "));
|
||||
// Grey like the owner and the criteria count: the shape carries which project
|
||||
@@ -921,6 +998,10 @@ fn card_lines(card: &Card, selected: bool, width: u16) -> Vec<Line<'static>> {
|
||||
/// corner: a cut list reads as a shorter one, and `bug` and `bugfix` truncated to the
|
||||
/// same width say the same thing. An untagged ticket spends no row at all, the way a
|
||||
/// short title spends no second one.
|
||||
///
|
||||
/// Each tag carries its own colour, from `tag_color`, so the same tag is the same
|
||||
/// colour on every card in every column. The row is spans rather than one string for
|
||||
/// that reason alone; it is still measured as one string.
|
||||
fn tags_line(tags: &[String], width: u16) -> Option<Line<'static>> {
|
||||
if tags.is_empty() {
|
||||
return None;
|
||||
@@ -932,31 +1013,45 @@ fn tags_line(tags: &[String], width: u16) -> Option<Line<'static>> {
|
||||
.collect::<Vec<_>>()
|
||||
.join(" ");
|
||||
|
||||
// Measured on the raw row, before anything is styled. What fits must not depend on
|
||||
// the colour decision, or a card would hold its tags in one render and drop them in
|
||||
// the other.
|
||||
if row.chars().count() > width as usize {
|
||||
return None;
|
||||
}
|
||||
|
||||
Some(Line::from(Span::styled(
|
||||
row,
|
||||
Style::default().fg(Color::Grey.into()),
|
||||
)))
|
||||
let mut spans = Vec::with_capacity(tags.len() * 2);
|
||||
for (index, tag) in tags.iter().enumerate() {
|
||||
if index > 0 {
|
||||
spans.push(Span::raw(" "));
|
||||
}
|
||||
spans.push(Span::styled(
|
||||
format!("#{tag}"),
|
||||
Style::default().fg(tag_color(tag).into()),
|
||||
));
|
||||
}
|
||||
|
||||
Some(Line::from(spans))
|
||||
}
|
||||
|
||||
/// The project name as it fits beside the mark and the id.
|
||||
/// The project name as it fits beside whatever the row already carries.
|
||||
///
|
||||
/// The mark and the id are the ticket's identity and never give way, so the label takes
|
||||
/// what the row has left and ends in an ellipsis where it was cut. It is measured before
|
||||
/// the due date, which is what gives the project the narrow column: on the All tab the
|
||||
/// project matters more than the date, and `corner_line` drops the date when what is
|
||||
/// left will not hold it.
|
||||
/// The mark, the id and the blocked mark are the ticket's identity and its state, and
|
||||
/// neither gives way, so the label takes what the row has left and ends in an ellipsis
|
||||
/// where it was cut. It is measured before the due date, which is what gives the project
|
||||
/// the narrow column: on the All tab the project matters more than the date, and
|
||||
/// `corner_line` drops the date when what is left will not hold it.
|
||||
///
|
||||
/// `used` is measured off the spans already built rather than added up from the widths
|
||||
/// they are supposed to have. The hand-written version left out the space after the
|
||||
/// priority mark, so the label was handed one cell more than the row had and a narrow
|
||||
/// column drew a card one character wider than its column.
|
||||
///
|
||||
/// Under three characters there is nothing left to say, and a single letter and a dot
|
||||
/// would only crowd the corner, so the label goes instead.
|
||||
fn project_label(name: &str, width: u16) -> Option<String> {
|
||||
// The mark and the space after it, the id in its brackets, and the space before the
|
||||
// label.
|
||||
let used = 2 + SHORT_ID_WIDTH + 2 + 1;
|
||||
let room = (width as usize).checked_sub(used)?;
|
||||
fn project_label(name: &str, width: u16, used: usize) -> Option<String> {
|
||||
// The space between the label and what precedes it.
|
||||
let room = (width as usize).checked_sub(used + 1)?;
|
||||
if room < 3 {
|
||||
return None;
|
||||
}
|
||||
@@ -995,7 +1090,7 @@ fn corner_line(
|
||||
width: u16,
|
||||
) -> Line<'static> {
|
||||
let mut spans = left;
|
||||
let used: usize = spans.iter().map(|span| span.content.chars().count()).sum();
|
||||
let used = spans_width(&spans);
|
||||
|
||||
let Some(right) = right else {
|
||||
return Line::from(spans);
|
||||
@@ -1012,6 +1107,11 @@ fn corner_line(
|
||||
Line::from(spans)
|
||||
}
|
||||
|
||||
/// The cells a run of spans takes, counted in characters rather than bytes.
|
||||
fn spans_width(spans: &[Span<'static>]) -> usize {
|
||||
spans.iter().map(|span| span.content.chars().count()).sum()
|
||||
}
|
||||
|
||||
/// The title over one row or two, wrapped on spaces, cut with an ellipsis if even two
|
||||
/// are not enough.
|
||||
///
|
||||
@@ -1645,14 +1745,23 @@ mod tests {
|
||||
assert!(rows[3].starts_with("alice"), "the owner moved: {rows:?}");
|
||||
}
|
||||
|
||||
/// Dimmed like the owner and the count beside it: the row is there to be scanned,
|
||||
/// not to compete with the title.
|
||||
/// Each tag carries its own colour, so the row can be scanned for one tag rather
|
||||
/// than read word by word. The row used to be a single grey span, which is what
|
||||
/// made a card of three tags one undifferentiated run.
|
||||
#[test]
|
||||
fn the_tag_row_is_dimmed() {
|
||||
fn each_tag_on_a_card_carries_its_own_colour() {
|
||||
let dir = board_dir();
|
||||
write_tagged_card(&dir, "Short", "2026-12-31", "- [ ] One", "cli, tui");
|
||||
write_tagged_card(&dir, "Short", "2026-12-31", "- [ ] One", "cli, docs");
|
||||
|
||||
assert_eq!(card_colour(&dir, 120, "#cli #tui"), Some(Color::Grey.into()));
|
||||
let cli = card_colour(&dir, 120, "#cli");
|
||||
let docs = card_colour(&dir, 120, "#docs");
|
||||
|
||||
// Through `tag_color`, not against a literal: the card has to use the mapping,
|
||||
// and the mapping is pinned by its own test in util.rs.
|
||||
assert_eq!(cli, Some(tag_color("cli").into()));
|
||||
assert_eq!(docs, Some(tag_color("docs").into()));
|
||||
assert_ne!(cli, docs, "two tags rendered in one colour");
|
||||
assert_ne!(cli, Some(Color::Grey.into()), "the row is still flat grey");
|
||||
}
|
||||
|
||||
/// And an untagged one spends no row on them, the way a short title spends no
|
||||
@@ -2652,13 +2761,211 @@ mod tests {
|
||||
|
||||
/// The label takes what the row has left, never the mark or the id, and says it was
|
||||
/// cut. A column too narrow for even that keeps the identity alone.
|
||||
///
|
||||
/// The mark, a space and the id in its brackets, which is what `card_lines` has
|
||||
/// built by the time it asks.
|
||||
#[test]
|
||||
fn the_project_label_gives_way_to_the_mark_and_the_id() {
|
||||
assert_eq!(project_label("alpha", 38).as_deref(), Some("alpha"));
|
||||
// Room for four characters of a longer name, the last of them the ellipsis.
|
||||
assert_eq!(project_label("factry-core", 16).as_deref(), Some("fac…"));
|
||||
assert_eq!(project_label("factry-core", 13), None);
|
||||
assert_eq!(project_label("alpha", 4), None);
|
||||
const IDENTITY: usize = 2 + 1 + SHORT_ID_WIDTH + 2;
|
||||
|
||||
assert_eq!(project_label("alpha", 38, IDENTITY).as_deref(), Some("alpha"));
|
||||
// Room for three characters of a longer name, the last of them the ellipsis.
|
||||
assert_eq!(
|
||||
project_label("factry-core", 16, IDENTITY).as_deref(),
|
||||
Some("fa…")
|
||||
);
|
||||
assert_eq!(project_label("factry-core", 13, IDENTITY), None);
|
||||
assert_eq!(project_label("alpha", 4, IDENTITY), None);
|
||||
}
|
||||
|
||||
/// The label plus everything before it has to fit the column it is drawn in. The
|
||||
/// arithmetic this replaced left out the space after the priority mark, so the row
|
||||
/// came out one cell wider than the column at every width the label was cut at.
|
||||
#[test]
|
||||
fn the_project_label_leaves_the_row_inside_the_column() {
|
||||
const IDENTITY: usize = 2 + 1 + SHORT_ID_WIDTH + 2;
|
||||
|
||||
for width in 13u16..40 {
|
||||
let Some(label) = project_label("factry-core", width, IDENTITY) else {
|
||||
continue;
|
||||
};
|
||||
let row = IDENTITY + 1 + label.chars().count();
|
||||
assert!(row <= width as usize, "row {row} over column {width}");
|
||||
}
|
||||
}
|
||||
|
||||
// ------------------------------------------------------- the blocked mark --
|
||||
|
||||
const BLOCKER: &str = "aaaaaaaa-0000-4000-8000-000000000000";
|
||||
const WAITER: &str = "bbbbbbbb-0000-4000-8000-000000000000";
|
||||
const ELSEWHERE: &str = "cccccccc-0000-4000-8000-000000000000";
|
||||
|
||||
/// A Relations section as `relate` writes it, for the `extra` a fixture appends.
|
||||
///
|
||||
/// It lands after the Metadata rather than in `SECTION_ORDER`'s place for it, which
|
||||
/// `section_body` reads all the same: these tests are about what the section says,
|
||||
/// not where the writer puts it.
|
||||
fn blocked_by(uuid: &str) -> String {
|
||||
format!("\n## Relations\n\n- blocked by {uuid}\n")
|
||||
}
|
||||
|
||||
/// Whether the board decided the named ticket is held up.
|
||||
///
|
||||
/// Over every column, done included: the flag is filled whether or not the column
|
||||
/// is drawn, the same way `reload` scans done while `d` hides it.
|
||||
fn marked_blocked(board: &Board, title: &str) -> bool {
|
||||
board
|
||||
.current()
|
||||
.columns
|
||||
.iter()
|
||||
.flat_map(|column| &column.cards)
|
||||
.find(|card| card.ticket.title == title)
|
||||
.unwrap_or_else(|| panic!("no card titled '{title}'"))
|
||||
.blocked
|
||||
}
|
||||
|
||||
/// The rows of the named ticket's card, laid out in a column of `inner` characters.
|
||||
fn card_rows(board: &Board, title: &str, inner: u16) -> Vec<String> {
|
||||
let card = board
|
||||
.current()
|
||||
.columns
|
||||
.iter()
|
||||
.flat_map(|column| &column.cards)
|
||||
.find(|card| card.ticket.title == title)
|
||||
.unwrap_or_else(|| panic!("no card titled '{title}'"));
|
||||
|
||||
card_lines(card, false, inner)
|
||||
.iter()
|
||||
.map(|line| line.spans.iter().map(|span| span.content.as_ref()).collect())
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// The one thing on a card that says do not start this. Without it a ticket whose
|
||||
/// blocker is still open reads exactly like one that is ready.
|
||||
#[test]
|
||||
fn a_card_waiting_on_an_open_ticket_carries_the_blocked_mark() {
|
||||
let dir = board_dir();
|
||||
write_ticket(&dir, "committed", BLOCKER, "The blocker", "");
|
||||
write_ticket(&dir, "backlog", WAITER, "The waiter", &blocked_by(BLOCKER));
|
||||
|
||||
let board = one_board(&dir);
|
||||
assert!(marked_blocked(&board, "The waiter"));
|
||||
// The far end of the relation is not held up by holding somebody else up.
|
||||
assert!(!marked_blocked(&board, "The blocker"));
|
||||
|
||||
let screen = render(&board, 120, 20).join("\n");
|
||||
assert!(
|
||||
screen.contains(&format!("({}) {}", short_id(WAITER), BLOCKED_MARK)),
|
||||
"no mark after the id:\n{screen}"
|
||||
);
|
||||
}
|
||||
|
||||
/// The mark is the state of the dependency, not a note that one was ever recorded.
|
||||
#[test]
|
||||
fn a_card_whose_blockers_are_all_done_carries_none() {
|
||||
let dir = board_dir();
|
||||
write_ticket(&dir, "done", BLOCKER, "The blocker", "");
|
||||
write_ticket(&dir, "backlog", WAITER, "The waiter", &blocked_by(BLOCKER));
|
||||
|
||||
let board = one_board(&dir);
|
||||
assert!(!marked_blocked(&board, "The waiter"));
|
||||
|
||||
let screen = render(&board, 120, 20).join("\n");
|
||||
assert!(
|
||||
!screen.contains(BLOCKED_MARK),
|
||||
"a cleared blocker still marked:\n{screen}"
|
||||
);
|
||||
}
|
||||
|
||||
/// One open blocker out of two is still a reason not to start, the rule `mv` applies
|
||||
/// when it names every open blocker rather than the first.
|
||||
#[test]
|
||||
fn a_card_is_marked_while_any_one_of_its_blockers_is_open() {
|
||||
let dir = board_dir();
|
||||
write_ticket(&dir, "done", BLOCKER, "The blocker", "");
|
||||
write_ticket(&dir, "reviewing", ELSEWHERE, "The other blocker", "");
|
||||
write_ticket(
|
||||
&dir,
|
||||
"backlog",
|
||||
WAITER,
|
||||
"The waiter",
|
||||
&format!("\n## Relations\n\n- blocked by {BLOCKER}\n- blocked by {ELSEWHERE}\n"),
|
||||
);
|
||||
|
||||
assert!(marked_blocked(&one_board(&dir), "The waiter"));
|
||||
}
|
||||
|
||||
/// The answer `mv` gives a dangling uuid: a bookkeeping fault, not a dependency.
|
||||
#[test]
|
||||
fn a_blocker_the_board_does_not_hold_marks_nothing() {
|
||||
let dir = board_dir();
|
||||
write_ticket(&dir, "backlog", WAITER, "The waiter", &blocked_by(ELSEWHERE));
|
||||
|
||||
assert!(!marked_blocked(&one_board(&dir), "The waiter"));
|
||||
}
|
||||
|
||||
/// Nothing but `relate` writes the section, so a line that is not a relation means a
|
||||
/// hand-edited file. `show` and `mv` are where that is reported; the board draws the
|
||||
/// ticket unmarked, the exception `detail_of` already makes for the same reason.
|
||||
#[test]
|
||||
fn a_relations_section_that_cannot_be_parsed_leaves_the_board_drawable() {
|
||||
let dir = board_dir();
|
||||
write_ticket(
|
||||
&dir,
|
||||
"backlog",
|
||||
WAITER,
|
||||
"The waiter",
|
||||
"\n## Relations\n\n- waits for the other one\n",
|
||||
);
|
||||
|
||||
let board = one_board(&dir);
|
||||
assert!(!marked_blocked(&board, "The waiter"));
|
||||
|
||||
let screen = render(&board, 120, 20).join("\n");
|
||||
assert!(screen.contains("The waiter"), "the board lost the ticket:\n{screen}");
|
||||
}
|
||||
|
||||
/// Dropped whole in a column that cannot hold the identity and the mark together,
|
||||
/// the rule a corner follows. The id keeps its place either way: a column of ids
|
||||
/// starting at different cells costs more than one card's state is worth.
|
||||
#[test]
|
||||
fn a_column_too_narrow_for_the_mark_drops_it() {
|
||||
let dir = board_dir();
|
||||
write_ticket(&dir, "committed", BLOCKER, "The blocker", "");
|
||||
write_ticket(&dir, "backlog", WAITER, "The waiter", &blocked_by(BLOCKER));
|
||||
|
||||
let board = one_board(&dir);
|
||||
// The mark, a space, the id in its brackets, and the space the mark needs.
|
||||
let identity = (2 + 1 + SHORT_ID_WIDTH + 2) as u16;
|
||||
let id = format!("({})", short_id(WAITER));
|
||||
|
||||
let wide = card_rows(&board, "The waiter", identity + 2);
|
||||
assert!(wide[0].contains(BLOCKED_MARK), "no mark with room for it: {:?}", wide[0]);
|
||||
|
||||
let narrow = card_rows(&board, "The waiter", identity);
|
||||
assert!(!narrow[0].contains(BLOCKED_MARK), "mark kept over the column: {:?}", narrow[0]);
|
||||
assert!(narrow[0].contains(&id), "the identity gave way instead: {:?}", narrow[0]);
|
||||
assert!(narrow[0].chars().count() <= identity as usize, "row over the column");
|
||||
}
|
||||
|
||||
/// The merge resolves nothing of its own. A relation names a uuid `relate` looked up
|
||||
/// in one `.worklane`, so a blocker in another project is not a thing that exists,
|
||||
/// and the flag each card arrives with is the one its own board worked out.
|
||||
#[test]
|
||||
fn the_blocked_mark_follows_a_card_onto_the_merge() {
|
||||
let (first, second) = (board_dir(), board_dir());
|
||||
write_ticket(&first, "committed", BLOCKER, "The blocker", "");
|
||||
write_ticket(&first, "backlog", WAITER, "The waiter", &blocked_by(BLOCKER));
|
||||
write_ticket(&second, "backlog", ELSEWHERE, "Elsewhere", &blocked_by(BLOCKER));
|
||||
|
||||
// The merge tab is where the view opens.
|
||||
let board = boards(&[("alpha", &first), ("beta", &second)]);
|
||||
assert_eq!(board.current().name, ALL);
|
||||
assert!(marked_blocked(&board, "The waiter"));
|
||||
assert!(
|
||||
!marked_blocked(&board, "Elsewhere"),
|
||||
"a uuid on another board was read as a blocker"
|
||||
);
|
||||
}
|
||||
|
||||
/// A change in any monitored board has to redraw, not only one in the first.
|
||||
|
||||
+331
-1
@@ -68,6 +68,17 @@ pub enum Color {
|
||||
Grey,
|
||||
Magenta,
|
||||
BrightRed,
|
||||
// The eight the tag palette draws from. Named as colours rather than as `TagBlue`,
|
||||
// because the enum is the palette and `TAG_COLORS` is what reserves them: a use
|
||||
// belongs to the list that claims it, not to the name of the colour it claims.
|
||||
Blue,
|
||||
Sky,
|
||||
Violet,
|
||||
Pink,
|
||||
Turquoise,
|
||||
Olive,
|
||||
Tan,
|
||||
Steel,
|
||||
}
|
||||
|
||||
impl Color {
|
||||
@@ -88,11 +99,23 @@ impl Color {
|
||||
Color::Magenta => "\x1b[1;35m",
|
||||
// Indexed, for the same reason grey is: this is the spelling that renders.
|
||||
Color::BrightRed => "\x1b[38;5;9m",
|
||||
// The tag palette, indexed throughout. The basic slots are themed by the
|
||||
// terminal and drift towards each other on a real palette, which is fine
|
||||
// for seven colours that each mean something and useless for six that have
|
||||
// to stay apart from those seven and from one another.
|
||||
Color::Blue => "\x1b[38;5;33m",
|
||||
Color::Sky => "\x1b[38;5;117m",
|
||||
Color::Violet => "\x1b[38;5;99m",
|
||||
Color::Pink => "\x1b[38;5;205m",
|
||||
Color::Turquoise => "\x1b[38;5;43m",
|
||||
Color::Olive => "\x1b[38;5;106m",
|
||||
Color::Tan => "\x1b[38;5;137m",
|
||||
Color::Steel => "\x1b[38;5;67m",
|
||||
}
|
||||
}
|
||||
|
||||
/// Every colour in the palette, so a test can walk them without listing them.
|
||||
pub const ALL: [Color; 7] = [
|
||||
pub const ALL: [Color; 15] = [
|
||||
Color::Red,
|
||||
Color::Cyan,
|
||||
Color::Orange,
|
||||
@@ -100,9 +123,95 @@ impl Color {
|
||||
Color::Grey,
|
||||
Color::Magenta,
|
||||
Color::BrightRed,
|
||||
Color::Blue,
|
||||
Color::Sky,
|
||||
Color::Violet,
|
||||
Color::Pink,
|
||||
Color::Turquoise,
|
||||
Color::Olive,
|
||||
Color::Tan,
|
||||
Color::Steel,
|
||||
];
|
||||
}
|
||||
|
||||
/// The colours a tag may be drawn in.
|
||||
///
|
||||
/// Deliberately disjoint from the seven that already carry a meaning, per the guideline
|
||||
/// in AGENTS.md: a tag in red reads as a uuid, in green as a title, in grey as an unset
|
||||
/// value. Reserving slots here rather than picking at the call site is what keeps the
|
||||
/// next colour someone assigns from landing on top of the tags.
|
||||
///
|
||||
/// Eight, and a real board carries more tags than that, so two tags will share a
|
||||
/// colour. That is accepted rather than designed around: the colour groups one tag
|
||||
/// across cards, it does not identify it, and the tag is written out beside it either
|
||||
/// way. Nothing pure can do better, since a function of the tag alone cannot know what
|
||||
/// else sits on the card.
|
||||
///
|
||||
/// Eight rather than six because two tags on one card collide at roughly `1 / n`, so
|
||||
/// the only lever is the size of the list. It stops here because these are the slots
|
||||
/// the assigned meanings leave: red, orange, green, cyan, magenta and grey are spoken
|
||||
/// for, and a ninth would have to be a shade of one of the eight. Two colours nobody
|
||||
/// can tell apart are a collision by another name.
|
||||
///
|
||||
/// At eight, about a fifth of the cards on this board show two tags in one colour. That
|
||||
/// is the arithmetic, not a fault to fix: the colour groups one tag *across* cards, so
|
||||
/// a repeat within a card costs nothing that the tag text beside it does not answer.
|
||||
///
|
||||
/// Do not tune this against the tags on one board. The count of collisions on any given
|
||||
/// board swings either side of the average on the luck of the hash, and picking the
|
||||
/// length that flatters today's vocabulary would be fitting to noise. An earlier draft
|
||||
/// scored two collisions in sixty-four here, which looked like a good palette and was
|
||||
/// really a broken index folding the whole vocabulary into a handful of slots.
|
||||
pub const TAG_COLORS: [Color; 8] = [
|
||||
Color::Blue,
|
||||
Color::Sky,
|
||||
Color::Violet,
|
||||
Color::Pink,
|
||||
Color::Turquoise,
|
||||
Color::Olive,
|
||||
Color::Tan,
|
||||
Color::Steel,
|
||||
];
|
||||
|
||||
/// FNV-1a, 64 bit, over the bytes of the tag.
|
||||
///
|
||||
/// Written out rather than taken from `std`: `DefaultHasher` is explicitly not promised
|
||||
/// to keep its output stable across releases, and a board that repaints itself on a
|
||||
/// toolchain upgrade has lost the one property this is for. Nine lines and no
|
||||
/// dependency buys a mapping that is the same on every machine and every version.
|
||||
fn fnv1a(bytes: &[u8]) -> u64 {
|
||||
const OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
|
||||
const PRIME: u64 = 0x0000_0100_0000_01b3;
|
||||
|
||||
let mut hash = OFFSET;
|
||||
for byte in bytes {
|
||||
hash ^= u64::from(*byte);
|
||||
hash = hash.wrapping_mul(PRIME);
|
||||
}
|
||||
hash
|
||||
}
|
||||
|
||||
/// The colour a tag is drawn in, derived from the tag itself.
|
||||
///
|
||||
/// A pure function of the string, so the same tag is the same colour on every card, in
|
||||
/// every view and on every board, with nothing stored and nothing to keep in step. Two
|
||||
/// boards that have never met agree about `bug`.
|
||||
///
|
||||
/// Case sensitive, because `Bug` and `bug` are two different tags everywhere else in
|
||||
/// worklane. Colouring them alike would be the display claiming a sameness the filter
|
||||
/// and the field do not have.
|
||||
pub fn tag_color(tag: &str) -> Color {
|
||||
// Multiply-shift, not `% len`. The palette length is a power of two, so a modulus
|
||||
// would keep the low three bits of the hash, and FNV-1a's low bits carry only the
|
||||
// low bits of the input bytes: the multiply cannot move information downwards and
|
||||
// the xor never does. `bug` and `BUG` differ in bit 5 of every letter, so under a
|
||||
// modulus they landed in the same slot no matter what else the strings held, as did
|
||||
// every other pair differing only above bit 2. Taking the top bits of the product
|
||||
// uses the whole hash, which is where the avalanche is.
|
||||
let index = (u128::from(fnv1a(tag.as_bytes())) * TAG_COLORS.len() as u128) >> 64;
|
||||
TAG_COLORS[index as usize]
|
||||
}
|
||||
|
||||
/// The same palette as ratatui sees it.
|
||||
///
|
||||
/// Chosen to match what crossterm emits for the escape above, so a card in the TUI and
|
||||
@@ -119,6 +228,16 @@ impl From<Color> for ratatui::style::Color {
|
||||
Color::Grey => Tui::DarkGray,
|
||||
Color::Magenta => Tui::Magenta,
|
||||
Color::BrightRed => Tui::LightRed,
|
||||
// Indexed on both sides, so the card and the listing are the same colour
|
||||
// by construction rather than by two guesses that happen to agree.
|
||||
Color::Blue => Tui::Indexed(33),
|
||||
Color::Sky => Tui::Indexed(117),
|
||||
Color::Violet => Tui::Indexed(99),
|
||||
Color::Pink => Tui::Indexed(205),
|
||||
Color::Turquoise => Tui::Indexed(43),
|
||||
Color::Olive => Tui::Indexed(106),
|
||||
Color::Tan => Tui::Indexed(137),
|
||||
Color::Steel => Tui::Indexed(67),
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -673,9 +792,40 @@ fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) -
|
||||
return paint(value, Color::Grey, colored);
|
||||
}
|
||||
|
||||
if name == "Tags" {
|
||||
return paint_tags(value, colored);
|
||||
}
|
||||
|
||||
value.to_string()
|
||||
}
|
||||
|
||||
/// The stored tag list with each tag in its own colour.
|
||||
///
|
||||
/// Painted in place rather than split and rejoined, so whatever separators the file
|
||||
/// 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();
|
||||
}
|
||||
|
||||
let lead = piece.len() - piece.trim_start().len();
|
||||
format!(
|
||||
"{}{}{}",
|
||||
&piece[..lead],
|
||||
paint(tag, tag_color(tag), colored),
|
||||
&piece[lead + tag.len()..]
|
||||
)
|
||||
})
|
||||
.collect::<Vec<_>>()
|
||||
.join(",")
|
||||
}
|
||||
|
||||
/// Render the Metadata section as two aligned columns.
|
||||
///
|
||||
/// Taken as a block rather than a line at a time because the field column cannot be
|
||||
@@ -1836,6 +1986,27 @@ pub struct TicketItem {
|
||||
/// asking per card would re-read every ticket body on every draw rather than on the
|
||||
/// tick that changed something.
|
||||
pub tags: Vec<String>,
|
||||
/// The full uuid from the ticket's own ID field, as a relation stores it.
|
||||
///
|
||||
/// `id` is the seven characters a listing prints; a relation names the whole uuid,
|
||||
/// so pairing a stored blocker with the ticket it points at needs the whole thing.
|
||||
/// Absent or unset reads as `_Not set_`, the way every other field does, and the
|
||||
/// board guards for it rather than matching on it.
|
||||
pub uuid: String,
|
||||
/// The uuids of the tickets this one records a `blocked by` against, empty when it
|
||||
/// records none.
|
||||
///
|
||||
/// Read here for the reason `criteria` is: the board marks every held-up card on
|
||||
/// every tick, and asking per card would re-read every ticket body on every draw.
|
||||
/// The uuids only, never the answer: whether a blocker is still open is a fact
|
||||
/// about another ticket, so it belongs to whoever holds the whole board.
|
||||
///
|
||||
/// A Relations section that cannot be parsed reads as no blockers rather than as a
|
||||
/// ticket that cannot be listed. `show` and `mv` still refuse it, which is where a
|
||||
/// hand-edited file has to be reported; a board or a listing that stops on one
|
||||
/// malformed ticket is the worse failure, and is the same exception `detail_of`
|
||||
/// already makes.
|
||||
pub blockers: Vec<String>,
|
||||
/// The file this came from. The listing ignores it; the TUI opens it for the
|
||||
/// detail view rather than resolving the ticket a second time.
|
||||
pub path: std::path::PathBuf,
|
||||
@@ -1971,6 +2142,13 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
|
||||
let filename = e.path().file_stem()?.to_string_lossy().to_string();
|
||||
let created_at = parse_ticket_field(&content, "Created At");
|
||||
|
||||
let blockers = parse_relations(&content, &title)
|
||||
.unwrap_or_default()
|
||||
.into_iter()
|
||||
.filter(|relation| relation.kind == RelationKind::BlockedBy)
|
||||
.map(|relation| relation.target)
|
||||
.collect();
|
||||
|
||||
// Through `criteria()`, so the card and the numbers `show` prints cannot
|
||||
// disagree: a checkbox written into a description is not a criterion there
|
||||
// and is not counted here.
|
||||
@@ -1993,6 +2171,8 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
|
||||
criteria: progress,
|
||||
campaign: parse_campaign(&content),
|
||||
tags: parse_tags(&content),
|
||||
uuid: parse_ticket_field(&content, "ID"),
|
||||
blockers,
|
||||
path: e.path(),
|
||||
})
|
||||
})
|
||||
@@ -2405,6 +2585,45 @@ mod tests {
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// The blockers come off the read that builds the item, so the board pays no second
|
||||
/// pass for them, and only the `blocked by` kind is one: the other two record no
|
||||
/// dependency and gate nothing.
|
||||
///
|
||||
/// A section that cannot be parsed reads as no blockers rather than as a ticket that
|
||||
/// cannot be listed. `show` and `mv` are where a hand-edited file is reported; a
|
||||
/// listing that stops on one malformed ticket is the worse failure.
|
||||
#[test]
|
||||
fn collect_ticket_items_reads_the_uuid_and_the_blockers_it_records() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-blocked-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
|
||||
let uuid = |tail: &str| format!("11111111-0000-4000-8000-00000000000{tail}");
|
||||
let write = |name: &str, relations: &str| {
|
||||
fs::write(
|
||||
dir.join(format!("{}.md", uuid(name))),
|
||||
format!(
|
||||
"# T{name}\n\n## Relations\n{relations}\n## Metadata\n\n- **ID**: {}\n",
|
||||
uuid(name)
|
||||
),
|
||||
)
|
||||
.unwrap();
|
||||
};
|
||||
|
||||
write("1", &format!("\n- blocked by {}\n- relates to {}\n", uuid("2"), uuid("3")));
|
||||
write("2", "\n- regression of 99999999-0000-4000-8000-000000000000\n");
|
||||
write("3", "\n- waits for the other one\n");
|
||||
|
||||
let items = collect_ticket_items(&dir).unwrap();
|
||||
let of = |title: &str| items.iter().find(|item| item.title == title).unwrap();
|
||||
|
||||
assert_eq!(of("T1").uuid, uuid("1"));
|
||||
assert_eq!(of("T1").blockers, vec![uuid("2")]);
|
||||
assert!(of("T2").blockers.is_empty(), "a regression was read as a blocker");
|
||||
assert!(of("T3").blockers.is_empty(), "an unreadable section was not survived");
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// Whole values, so a filter or a card cannot confuse two tags that share a prefix.
|
||||
#[test]
|
||||
fn parse_tags_splits_on_commas_and_keeps_whole_values() {
|
||||
@@ -2801,6 +3020,117 @@ mod tests {
|
||||
assert_eq!(seen.len(), Color::ALL.len());
|
||||
}
|
||||
|
||||
/// The text a cell holds once its colour is taken off, so a test can assert the
|
||||
/// separators survived without spelling out the escapes around them.
|
||||
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
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_tag_keeps_its_colour_and_different_tags_do_not_all_share_one() {
|
||||
assert_eq!(tag_color("bug"), tag_color("bug"));
|
||||
assert_eq!(tag_color("frontend"), tag_color("frontend"));
|
||||
|
||||
let spread: std::collections::HashSet<Color> =
|
||||
["bug", "feature", "cli", "tui", "docs", "chore", "output", "skills"]
|
||||
.iter()
|
||||
.map(|tag| tag_color(tag))
|
||||
.collect();
|
||||
assert!(spread.len() > 3, "the mapping collapses the vocabulary: {spread:?}");
|
||||
}
|
||||
|
||||
/// Case sensitive on purpose: `Bug` and `bug` are two different tags to the field
|
||||
/// and to every search, so one colour for both would be the display claiming a
|
||||
/// sameness nothing else has.
|
||||
///
|
||||
/// Over a set rather than one pair. Any single pair can land in the same slot by
|
||||
/// luck, one time in `TAG_COLORS.len()`, and a test that reads that accident as
|
||||
/// case folding would be asserting the hash rather than the rule.
|
||||
#[test]
|
||||
fn tag_colour_does_not_fold_case() {
|
||||
let folded = ["bug", "cli", "tui", "docs", "chore"]
|
||||
.iter()
|
||||
.all(|tag| tag_color(tag) == tag_color(&tag.to_uppercase()));
|
||||
assert!(!folded, "tag_color lowercases before hashing");
|
||||
}
|
||||
|
||||
/// Pinned so that a change to the hash is a failing test rather than a board that
|
||||
/// quietly repaints itself. If this fails, the mapping moved: decide whether that
|
||||
/// was intended before rewriting the expectations.
|
||||
#[test]
|
||||
fn the_tag_mapping_is_pinned() {
|
||||
assert_eq!(tag_color("bug"), Color::Blue);
|
||||
assert_eq!(tag_color("feature"), Color::Blue);
|
||||
assert_eq!(tag_color("cli"), Color::Steel);
|
||||
assert_eq!(tag_color("tui"), Color::Violet);
|
||||
assert_eq!(tag_color("docs"), Color::Tan);
|
||||
assert_eq!(tag_color("chore"), Color::Sky);
|
||||
assert_eq!(tag_color("skills"), Color::Tan);
|
||||
assert_eq!(tag_color("output"), Color::Blue);
|
||||
}
|
||||
|
||||
/// The whole reason the tag palette is a reserved list rather than a pick at the
|
||||
/// call site: a tag drawn in red reads as a uuid, in green as a title, in grey as
|
||||
/// an unset value.
|
||||
#[test]
|
||||
fn no_tag_colour_carries_another_meaning() {
|
||||
for assigned in [
|
||||
Color::Red,
|
||||
Color::Orange,
|
||||
Color::Cyan,
|
||||
Color::Green,
|
||||
Color::Grey,
|
||||
Color::Magenta,
|
||||
Color::BrightRed,
|
||||
] {
|
||||
assert!(
|
||||
!TAG_COLORS.contains(&assigned),
|
||||
"{assigned:?} means something else already"
|
||||
);
|
||||
}
|
||||
|
||||
// The priority ramp is the other list that claims colours, and it is built from
|
||||
// the assigned seven rather than named here, so ask it directly.
|
||||
for level in PRIORITY_RANGE {
|
||||
let ramp = priority_mark(Priority::Level(level)).1;
|
||||
assert!(!TAG_COLORS.contains(&ramp), "{ramp:?} is a priority colour");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_tags_cell_paints_each_tag_and_leaves_the_separators_alone() {
|
||||
let plain = metadata_value_cell("Tags", "bug, cli", false, "");
|
||||
assert_eq!(plain, "bug, cli", "colour off must be the stored value");
|
||||
|
||||
let painted = metadata_value_cell("Tags", "bug, cli", true, "");
|
||||
assert!(painted.contains(&paint("bug", tag_color("bug"), true)));
|
||||
assert!(painted.contains(&paint("cli", tag_color("cli"), true)));
|
||||
|
||||
// The separator the file holds comes back as it went in, spacing and all.
|
||||
assert_eq!(strip_escapes(&painted), "bug, cli");
|
||||
assert_eq!(strip_escapes(&metadata_value_cell("Tags", "bug,cli", true, "")), "bug,cli");
|
||||
assert_eq!(strip_escapes(&metadata_value_cell("Tags", " bug , cli ", true, "")), " bug , cli ");
|
||||
}
|
||||
|
||||
/// An unset value stays grey, since the Tags branch sits behind the unknown check.
|
||||
#[test]
|
||||
fn an_unset_tags_cell_is_still_grey() {
|
||||
assert_eq!(
|
||||
metadata_value_cell("Tags", "_None_", true, ""),
|
||||
paint("_None_", Color::Grey, true)
|
||||
);
|
||||
}
|
||||
|
||||
/// Pinned deliberately. Both SGR spellings of grey failed on a real palette,
|
||||
/// 90 reading nearly as light as the foreground and 37 sitting on top of it.
|
||||
/// This is the exact sequence crossterm emits for ratatui's Color::DarkGray,
|
||||
|
||||
@@ -457,3 +457,107 @@ fn add_treats_an_all_blank_description_as_none() {
|
||||
"was {content:?}"
|
||||
);
|
||||
}
|
||||
|
||||
/// The help, the README and the skill all promise `YYYY-MM-DD`, and until this the
|
||||
/// value was written to the ticket whatever it said.
|
||||
#[test]
|
||||
fn add_stores_a_valid_due_date_unchanged() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.arg("add")
|
||||
.args(["--title", "Dated"])
|
||||
.args(["--due", "2026-08-29"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let content = read_only_ticket(&worklane.join("backlog"));
|
||||
assert!(content.contains("- **Due**: 2026-08-29"), "{content}");
|
||||
}
|
||||
|
||||
/// Every one of these is refused at parse time, so the exit code is 2 and nothing is
|
||||
/// written. A date that cannot happen is as wrong as a word: `2026-02-30` has the shape
|
||||
/// and is not a day.
|
||||
#[test]
|
||||
fn add_refuses_a_due_date_that_is_not_a_real_iso_date() {
|
||||
for value in ["next friday", "29-08-2026", "2026-13-01", "2026-02-30", "2026/08/29", ""] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let out = cmd
|
||||
.current_dir(temp.path())
|
||||
.arg("add")
|
||||
.args(["--title", "Dated"])
|
||||
.args(["--due", value])
|
||||
.assert()
|
||||
.failure()
|
||||
.get_output()
|
||||
.clone();
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{value:?} was not a usage error");
|
||||
assert_eq!(
|
||||
fs::read_dir(worklane.join("backlog")).unwrap().count(),
|
||||
0,
|
||||
"{value:?} wrote a ticket anyway"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// An unpadded date parses as a date and would be stored as typed, which sorts before
|
||||
/// `2026-10-01` and is not the format anything promises.
|
||||
#[test]
|
||||
fn add_refuses_an_unpadded_due_date_rather_than_padding_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let stderr = String::from_utf8_lossy(
|
||||
&cmd.current_dir(temp.path())
|
||||
.arg("add")
|
||||
.args(["--title", "Dated"])
|
||||
.args(["--due", "2026-8-9"])
|
||||
.assert()
|
||||
.failure()
|
||||
.get_output()
|
||||
.stderr,
|
||||
)
|
||||
.to_string();
|
||||
|
||||
assert!(stderr.contains("YYYY-MM-DD"), "the error never names the format: {stderr}");
|
||||
}
|
||||
|
||||
/// An empty value keeps the message about clearing, since that is what somebody typing
|
||||
/// it is reaching for.
|
||||
#[test]
|
||||
fn an_empty_due_date_says_clearing_is_not_supported() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let stderr = String::from_utf8_lossy(
|
||||
&cmd.current_dir(temp.path())
|
||||
.arg("add")
|
||||
.args(["--title", "Dated"])
|
||||
.args(["--due", ""])
|
||||
.assert()
|
||||
.failure()
|
||||
.get_output()
|
||||
.stderr,
|
||||
)
|
||||
.to_string();
|
||||
|
||||
assert!(stderr.contains("clearing a field is not supported"), "{stderr}");
|
||||
}
|
||||
|
||||
fn read_only_ticket(dir: &Path) -> String {
|
||||
let file = fs::read_dir(dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.find(|e| e.path().extension().is_some_and(|ext| ext == "md"))
|
||||
.expect("no ticket written");
|
||||
|
||||
fs::read_to_string(file.path()).unwrap()
|
||||
}
|
||||
|
||||
@@ -7,6 +7,7 @@ const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
/// files in the repo rather than to a description of them.
|
||||
const SKILL: &str = include_str!("../assets/SKILL.md");
|
||||
const REVIEW: &str = include_str!("../assets/REVIEW.md");
|
||||
const PLAN: &str = include_str!("../assets/PLAN.md");
|
||||
|
||||
/// `HOME` is redirected, so the suite never writes into the home of whoever runs it.
|
||||
/// A temp directory rather than the real one is also what makes the already-installed
|
||||
@@ -25,6 +26,10 @@ fn installed_review(home: &TempDir) -> std::path::PathBuf {
|
||||
home.path().join(".claude/skills/worklane-review/SKILL.md")
|
||||
}
|
||||
|
||||
fn installed_plan(home: &TempDir) -> std::path::PathBuf {
|
||||
home.path().join(".claude/skills/worklane-plan/SKILL.md")
|
||||
}
|
||||
|
||||
/// Nothing about the skills needs a board, and they are wanted before there is one.
|
||||
///
|
||||
/// One invocation writes every document. A person who learned the command before the
|
||||
@@ -42,8 +47,11 @@ fn every_skill_installs_outside_a_worklane_directory() {
|
||||
assert!(stdout.contains(".claude/skills/worklane/SKILL.md"), "{stdout}");
|
||||
assert!(stdout.contains("Installed the worklane-review skill"), "{stdout}");
|
||||
assert!(stdout.contains(".claude/skills/worklane-review/SKILL.md"), "{stdout}");
|
||||
assert!(stdout.contains("Installed the worklane-plan skill"), "{stdout}");
|
||||
assert!(stdout.contains(".claude/skills/worklane-plan/SKILL.md"), "{stdout}");
|
||||
assert_eq!(std::fs::read_to_string(installed(&home)).unwrap(), SKILL);
|
||||
assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW);
|
||||
assert_eq!(std::fs::read_to_string(installed_plan(&home)).unwrap(), PLAN);
|
||||
|
||||
// Once, not per document: it is the one thing to do next, not part of an outcome.
|
||||
assert_eq!(
|
||||
@@ -64,6 +72,7 @@ fn a_named_skill_installs_only_that_one() {
|
||||
assert_eq!(out.status.code(), Some(0), "{stdout}");
|
||||
assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW);
|
||||
assert!(!installed(&home).exists(), "a named install wrote the other document too");
|
||||
assert!(!installed_plan(&home).exists(), "a named install wrote the other document too");
|
||||
}
|
||||
|
||||
/// A name nothing ships is a stop, with the choices in the message: guessing at the
|
||||
@@ -80,6 +89,7 @@ fn an_unknown_skill_name_is_refused_and_lists_what_there_is() {
|
||||
assert!(stderr.contains("worklane-review"), "{stderr}");
|
||||
assert!(!installed(&home).exists());
|
||||
assert!(!installed_review(&home).exists());
|
||||
assert!(!installed_plan(&home).exists());
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -138,6 +148,7 @@ fn a_modified_copy_does_not_stop_the_other_documents() {
|
||||
assert!(stdout.contains("install-skill worklane --print"), "{stdout}");
|
||||
assert_eq!(std::fs::read_to_string(installed(&home)).unwrap(), "hand written\n");
|
||||
assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW);
|
||||
assert_eq!(std::fs::read_to_string(installed_plan(&home)).unwrap(), PLAN);
|
||||
}
|
||||
|
||||
/// The print path is what makes a modified copy diffable, so it has to be the document
|
||||
@@ -154,8 +165,13 @@ fn print_writes_the_named_document_to_stdout_and_installs_nothing() {
|
||||
assert_eq!(out.status.code(), Some(0));
|
||||
assert_eq!(String::from_utf8_lossy(&out.stdout), REVIEW);
|
||||
|
||||
let out = run(&home, &["install-skill", "worklane-plan", "--print"]);
|
||||
assert_eq!(out.status.code(), Some(0));
|
||||
assert_eq!(String::from_utf8_lossy(&out.stdout), PLAN);
|
||||
|
||||
assert!(!installed(&home).exists(), "--print installed the skill anyway");
|
||||
assert!(!installed_review(&home).exists(), "--print installed the skill anyway");
|
||||
assert!(!installed_plan(&home).exists(), "--print installed the skill anyway");
|
||||
}
|
||||
|
||||
/// A diff is against one document. Printing them all run together would be neither of
|
||||
|
||||
@@ -415,3 +415,50 @@ fn neither_command_can_write_owner_or_status() {
|
||||
assert!(content.contains("- **Owner**: alice"));
|
||||
assert!(content.contains("- **Status**: backlog"));
|
||||
}
|
||||
|
||||
/// The same parser `add` uses, from one definition. Grooming a board sets dates through
|
||||
/// `set`, so validating only the command that files a ticket would leave the path that
|
||||
/// is actually used wide open.
|
||||
#[test]
|
||||
fn set_refuses_a_due_date_that_is_not_a_real_iso_date() {
|
||||
for value in ["next friday", "2026-02-30", "2026-8-9"] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = create_ticket(&worklane);
|
||||
let before = fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap();
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let out = cmd
|
||||
.current_dir(temp.path())
|
||||
.args(["set", UUID])
|
||||
.args(["--due", value])
|
||||
.assert()
|
||||
.failure()
|
||||
.get_output()
|
||||
.clone();
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{value:?} was not a usage error");
|
||||
assert_eq!(
|
||||
fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap(),
|
||||
before,
|
||||
"{value:?} changed the ticket anyway"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn set_stores_a_valid_due_date_unchanged() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = create_ticket(&worklane);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.args(["set", UUID])
|
||||
.args(["--due", "2026-12-31"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let content = fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap();
|
||||
assert!(content.contains("- **Due**: 2026-12-31"), "{content}");
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user