Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ab337ca7f8 | ||
|
|
60b43a682e | ||
|
|
5bf0fd1bfe | ||
|
|
c03f47c52d | ||
|
|
9d17f55860 | ||
|
|
f454d212a4 | ||
|
|
a1bdb5df49 | ||
|
|
c2ee165108 | ||
|
|
407cb14fe6 | ||
|
|
108e21ad7f | ||
|
|
26b93f8f53 | ||
|
|
7126138d46 | ||
|
|
3592584747 | ||
|
|
5dc087d49e | ||
|
|
07c783410c | ||
|
|
dd2b457bff | ||
|
|
af1ef1f97f | ||
|
|
8e2ab6332c | ||
|
|
239d951b8c | ||
|
|
f515d69930 | ||
|
|
b1dbf3ed75 |
@@ -7,31 +7,43 @@
|
||||
- `src/handlers.rs` - one `cmd_*` per subcommand
|
||||
- `src/util.rs` - the ticket format, resolution, rendering and the palette
|
||||
- `src/campaign.rs` - the campaign file format, its resolution, its index and its members
|
||||
- `src/history.rs` - the history log: the path, the kinds, the reader, the writer, the card's counter and the block `show` and the board both render
|
||||
- `src/tui.rs` - board state, the change digest, and the ratatui draw
|
||||
- `src/clipboard.rs` - the OSC 52 write and the base64 it carries, the board's only way out to the clipboard
|
||||
- `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
|
||||
- `assets/ADMIN.md` - the agent skill for the board itself: designing and annotating the tag vocabulary, and repairing a board whose files and fields have come apart. The one asset written to hold for a board that tracks no software, so its examples span three subjects on purpose. It draws the line against `PLAN.md` in both directions: this one decides the vocabulary, that one applies it
|
||||
- `assets/TOOL.ts` - the opencode tool definitions wrapping the CLI, embedded the same way and installed by `install-tool`. The only asset that is not a document and the only one that reaches a single agent
|
||||
- `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`
|
||||
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `history.rs` and `tui.rs`
|
||||
- Ticket files stored as `.md` in `.worklane/<status>/` directories
|
||||
- History entries stored as `.md` in `.worklane/history/<ticket_uuid>/`, one file per entry, beside the status directories for the reason campaigns are
|
||||
- Campaign files stored as `.md` in `.worklane/campaigns/`, which is beside the status directories and deliberately not in `status_dirs()`
|
||||
|
||||
## Ticket File Format
|
||||
- Filenames: `<uuid_v4>_<slug>.md`
|
||||
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
|
||||
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
|
||||
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
|
||||
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done by `Completed On` descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
|
||||
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Discarded On`, `Campaign`, `Status`. The last five are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
|
||||
- The four stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Not the history log either: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
|
||||
- **`Discarded` is last in `Status::ALL`, and that placement is what makes the stamp rule fall out right.** Nothing sits after it, so a discard clears nothing: a ticket abandoned from reviewing keeps `Committed On` and `Submitted On`, and the file still says how far it got before it was dropped. It also makes every move out of discarded a backward move, so un-discarding needs `-f` without a rule of its own. `Discarded On` is its stamp, and `Completed On` stays untouched, because a discarded ticket was never done
|
||||
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done and discarded by their stamp descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
|
||||
- Format: `**Field Name**: value`
|
||||
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
|
||||
- A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign
|
||||
- Comments stored in `.worklane/comments/<ticket_uuid>/<timestamp>.md` with `**Comment**`, `**Author**`, `**Time**` fields
|
||||
- History entries stored in `.worklane/history/<ticket_uuid>/<stamp>_<kind>.md`, with the kind's marker (`**Comment**`, `**Status**`, `**Owner**`, `**Tags**`, `**Campaign**`), then the body, then `**Author**` and `**Time**`. See The History Log
|
||||
|
||||
## Status Workflow
|
||||
`backlog` → `committed` → `reviewing` → `done`
|
||||
`backlog` → `committed` → `reviewing` → `done`, and `discarded` off to one side
|
||||
|
||||
- **`Status::ALL` is every directory that can hold a ticket, and that is the only list left.** It is what the tree walkers want: `status_dirs`, `RelationIndex::load`, `collect_ticket_items`' callers, `cmd_tags`, `list_ids`, the resolver, the digest and the board's own columns all have to see a discarded ticket or it becomes unaddressable. There was a second list, `FLOW`, the four stages work moves through, which used to be what the board drew from; a136d13 drew the discarded column behind a visibility prefix instead, which took FLOW's last reader away, so it is gone. Hiding is decided by `Visibility`, never by leaving a status out of the walk: what is drawn changes, what is read does not. The prefix property survives on the order alone — done and discarded are deliberately the last two in `ALL` — and `the_terminal_columns_are_last_in_the_order_drawn` pins it
|
||||
- **Discarding is not a stage, so the walk rules do not apply to entering it.** `mv --status discarded` is allowed from any status with no `-f`, because a backlog ticket that turns out to be a duplicate should not have to be walked through committed and reviewing to be abandoned. Leaving it needs `-f`, which comes free from the backward-move rule
|
||||
- **The two dependency guards look opposite ways, and `mv` picks by direction.** `check_blockers` asks what this ticket waits on and gates work moves; `check_dependents` asks who waits on this ticket and gates the discard. A ticket being abandoned owes nothing to its own blockers, but the tickets blocked *by* it recorded a dependency on work that is about to be declared never-happening, so those plans get a look before the ground moves. `-f` is the caller saying they looked. Both name every offender rather than the first, and both skip targets that are themselves done or discarded
|
||||
- **Discarded satisfies a block the way done does.** There is nothing left to wait for, and whether the dependent still makes sense was asked at discard time by the guard above, which is what makes it safe to pass here rather than a second place to re-ask
|
||||
- **Both terminal statuses are hidden by default and counted anyway.** `ls` leaves done and discarded out of the decorated listing and keeps them in the summary counts, and `--ids` and the status positional still reach both: a ticket nobody will work still has to be nameable by a completion or a script
|
||||
- **A campaign counts a discarded member as finished.** The work was decided out of the campaign rather than left in it, and counting it outstanding would hold a campaign open forever over a ticket nobody will ever do
|
||||
- **`mv` creates the target directory before moving into it.** A board made before a status existed has no directory for it, and the first move into one is the wrong place to refuse. `init` gets all five from `status_dirs()`
|
||||
|
||||
**How to use worklane is in `assets/SKILL.md`, not here.** That document is what
|
||||
`worklane install-skill` ships, so it is the one place the flow, the move-as-you-work
|
||||
@@ -42,8 +54,12 @@ and this file is for what someone changing worklane's own code needs.
|
||||
## Testing
|
||||
- Run: `cargo test`
|
||||
- Tests use `assert_cmd` and `assert_fs` for CLI testing
|
||||
- `setup_worklane()` creates temp `.worklane/` with all four status folders pre-created, plus `campaigns/` in `cmd_campaign.rs`, which is also where the on-demand creation is tested from a board without it
|
||||
- `setup_worklane()` creates temp `.worklane/` with the four flow status folders pre-created, plus `campaigns/` in `cmd_campaign.rs`, which is also where the on-demand creation is tested from a board without it. **The fixtures deliberately do not create `discarded/`**, so every discard test runs against a board that predates the status and `mv_creates_the_discarded_directory_on_a_board_that_predates_it` is not the only thing exercising the on-demand creation
|
||||
- `create_ticket()` writes fully-formed markdown files directly (no `--` separator for positional args in test commands)
|
||||
- **Every unit-test fixture directory goes through `util::Fixture`, and nothing calls `remove_dir_all` at the end of a test.** `Fixture::new(prefix)` makes a uuid-named directory under the system temp dir and its `Drop` removes it, which is the only shape that also runs when an assertion fails — a trailing line does not, and a failing test is exactly when a fixture is most likely to be stranded. That was b74dc5a: `/tmp` reached 18363 of these and filled the disk, failing a link step and then a `git add` with "No space left on device", an error naming neither the tests nor what they left behind
|
||||
- **`Fixture` derefs to `Path` and also implements `AsRef<Path>`**, because the two reach different call sites: a parameter typed `&Path` is a coercion site and one bound by `impl AsRef<Path>` is not. `Fixture::child(name)` points the fixture at a directory inside itself while still removing the parent, which is the tree `project_tree` needs. The prefix earns its place on the one path that is ever left behind, which is why this is a small guard rather than `assert_fs::TempDir` — that names its directories `.tmpXXXXXX`, which says nothing about whose they are
|
||||
- **`WORKLANE_KEEP_FIXTURES=1 cargo test` keeps the fixtures and prints each path.** Opt-in rather than kept-automatically-on-failure, because the assertions here carry the state they are about: a failing board test prints the rendered rows. The flag is read once when a fixture is made rather than at drop time, so the answer cannot change mid-test, and `Fixture::swept()` turns it off for the three tests that are about the guard itself and must not be failed by a reader's environment
|
||||
- **Verify a claim about leaked fixtures against a clean temp dir, not against `/tmp`.** `TMPDIR=/tmp/scratch cargo test` then count what is left in it: `/tmp` still holds the historical leak, so counting there measures the past rather than the change
|
||||
- In `tui.rs`, `write_member_card` is `write_tagged_card` plus a Campaign field and `write_campaign` puts a campaign on disk, creating the campaigns directory as it goes — `board_dir()` deliberately does not, so every test that does not write one is also the test that a board with no campaigns draws. `picker_rows` cuts the picker's list out of the frame by its own geometry, for the reason `overlay_title_row` exists: a card carries the same campaign label, so a search over every row finds the board rather than the list
|
||||
- **`cargo clippy --all-targets` is clean. Keep it clean**, and do not silence a lint that is pointing at something real. The only two `allow`s in the tree sit on the `create_ticket` fixtures in `cmd_mv.rs` and `cmd_show.rs`, each carrying the reason and what would replace it
|
||||
- **`cargo fmt --check` is clean too, and `rustfmt.toml` is what makes that affordable.** rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:
|
||||
@@ -120,6 +136,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
|
||||
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read `_No description provided._` above its description
|
||||
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` and `clearable` in `command.rs`. Neither spells clearing, and both errors name the flag that does
|
||||
- **A call whose values are *every one* blank is refused, by `replaced_items` for `set` and `appended_items` for `append`.** The check is the section's rather than the object's, so `campaign set --description` shares it. What differs is the way out, which is why `replaced_items` takes it as an argument: a ticket's section is emptied with `--clear <field>` and a campaign's description cannot be emptied at all, so a single hard-coded tail would name a flag that does not exist on one of the two
|
||||
|
||||
### Clearing a Field
|
||||
- **`set --clear <field>` is the one way to take a value away, and it is a flag with the field as its value.** Not a per-field `--clear-due`, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likes
|
||||
@@ -169,7 +186,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
|
||||
@@ -180,9 +197,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `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 got a card label and a frame, not a campaign tab.** 61879a4 decided it. A tab would have had to answer what its columns are, and a campaign groups *across* the flow rather than within one status, so the honest answer is the four statuses filtered — which is a filter on the board it already has rather than a fifth tab. So: a label on the card, a frame above the columns while one is selected, and `c` for the picker. The cost the earlier decision balked at, a campaigns read per reload, is paid once per project in `columns_of` and is what names the label; see The Board View
|
||||
- **A campaign is named by its codename on the board, and by its short id when it has none.** The uuid does not fit on a card and the title is a sentence, which is the gap `Codename` fills. `campaign_label` builds it in one place, as a `Cell`, so the CLI paints it and the board makes a span of it; the mark is `CAMPAIGN_MARK`, `~`, beside `#` for a tag
|
||||
- **`campaign set` is the only writer of a filed campaign's fields, and it carries the two scalars.** d637288 decided it: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `--title`, which renames the file the way `set --title` does, and `--codename`. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist
|
||||
- **`campaign set` and `campaign append` are the only writers of a filed campaign's fields.** d637288 decided the command: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `set` carries `--title`, which renames the file the way `set --title` does, `--description` and `--codename`; `append` carries `--description` alone. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist
|
||||
- **Replacing a codename the campaign already has needs `--force`.** Once a campaign has one it is referred to by it: it is on every card in the campaign, it is what resolves the campaign at the command line, and it is in somebody's shell history. Changing it silently is the mistake `install-skill --force` exists to prevent, so it is refused and the refusal names both words and the flag rather than leaving it to be found. Checked before any edit is applied, like `SetArgs::contested`, so a call also carrying `--title` writes neither field. Setting the codename a campaign already carries stays a **no-op, not a refusal** — `--force` is about overwriting a *different* word, which is the same division `install::Outcome` draws between `Unchanged` and `Refused`. `--force` guards the codename alone: a campaign always has a title, so guarding that would mean the flag was always required
|
||||
- **No `campaign set --description`, and that is the line, not an oversight.** `set` and `append` are a pair for a prose section: a way to replace a description with no way to add a paragraph is half of it. The two scalars have no append form at all, which is the same line `append` already draws for a ticket. `campaign_set_offers_no_description_and_no_owner` pins it. No `--owner` either, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign; and no `--clear`, because a wrong codename is replaced rather than emptied and `Clearable` is `SetArgs`'s, its variants being a ticket's fields
|
||||
- **The description arrived as a pair, `set --description` and `campaign append`, 32e98ab.** Never one without the other: for a prose section `set` replaces and `append` adds, and a way to replace a description with no way to add a paragraph is the half that is easy to reach for and wrong, since replacing a description to add a sentence to it is how the rest of it gets lost. The two scalars have no append form at all, which is the same line `append` already draws for a ticket, and `campaign_append_offers_only_the_description` pins that. Neither flag takes `--force`: a description is prose written to be revised, the same reason `tags set --annotation` has none
|
||||
- **`append` is a campaign's own subcommand, not the top-level `append`.** That one resolves a ticket, and one positional naming either object is the ambiguity `resolve_in` makes real: its tiers are the same over both directories, so a search can resolve in each and nothing but a flag could say which was meant. It would also make a liar of `resolve_ticket`, which explains a ticket search that *names* a campaign. Under `campaign` the object is settled by the command, as it is for `set`, `show` and `ls`
|
||||
- **Still no `--owner` and still no `--clear`.** No `--owner`, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign. No `--clear`, which 32e98ab settled rather than deferred: a codename is replaced rather than emptied, and emptying the description of a container six tickets are filed against is not a thing anybody has asked for, so the only spellings left would be `Clearable` on a campaign, whose variants are a ticket's fields, or a second enum with one variant in it. `campaign_set_offers_no_owner_and_no_clear` pins both
|
||||
- **An empty `--description ""` is a paragraph break here too, and the refusal for an all-blank value names no flag.** Every prose argument in the tool reads a blank value that way, `add`, `set` and `tags --annotation` alike, so a campaign reading it as *empty the section* would be the one exception. With no `--clear` to point at, the refusal says a campaign's description has no cleared form instead of naming a flag that does not exist. `replaced_items` is where the check lives, shared with `set`, and the way out is the caller's argument for exactly that reason
|
||||
- **`SECTION_ORDER` needs no campaign variant, and that is what the one-section file proves.** A campaign holds Description and Metadata where a ticket holds four sections and Metadata. Every consumer of the list looks for the headings that follow, *filtered by what is actually in the file*, so a campaign's description anchors against `## Metadata` — which is where `campaign_body` writes it. `the_description_is_edited_in_place_in_a_file_with_one_section` pins that no section a campaign does not have gets inserted to anchor against
|
||||
- **A campaign whose Description heading is gone is refused, not given the section back.** No `ensure_section` on this path: every campaign the tool has ever filed carries the heading, so an insertion here would be reachable only from a hand-edited file, which is the opposite of the Relations case, where `add` writes nothing and the insertion is the only path there is. The refusal therefore names the section and **not** the object — "There is no description section to write to" — because both a ticket and a campaign reach `replace_section_body` now. `write_then_replace` still carries the noun, where the message is about a file
|
||||
- **The codename is written through `set_or_insert_metadata_field`, not `set_metadata_field`.** Every campaign filed before the field existed has no such line, and those are exactly the campaigns the command is for, which is the same reasoning that puts `assign` on the upsert. **`Codename` is therefore in `METADATA_ORDER`, directly after ID**, so an inserted one lands where `campaign_body` writes it and a campaign given a codename later is the same file as one filed with it. Nothing upserts it on a ticket, so its place in a ticket's order costs nothing
|
||||
- **One write path for tickets and campaigns.** `save_entry` is the body, `save_ticket` and `save_campaign` are the named wrappers, and `write_then_replace` and `find_entry_file` take the noun as a `&str` so a failure says "campaign" where it is one. A campaign file is a ticket file in every way that matters here, `<uuid>_<slug>.md` in a directory, and the rename happens only after the write has landed. Every message puts the noun mid-sentence so there is no capital to case
|
||||
- `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
|
||||
@@ -198,6 +220,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `notify` is deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387
|
||||
- Cards come from `collect_ticket_items`, the same source `ls` uses, so there is no second parser. `TicketItem::path` exists for the detail view
|
||||
- **The detail view scrolls on `pgup` and `pgdn`, not on up and down.** Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them
|
||||
- **The campaign frame scrolls on the same two keys, and `Board::scroll_page` is where the precedence lives.** An open ticket wins, whatever holds the selection behind it; the frame takes them only when there is no overlay to take them first. In `Board` rather than in the `main.rs` arm for the reason `dismiss` is: a layering rule written into that dispatch is a rule nothing can check
|
||||
- The scroll offset is clamped against the *wrapped* line count, from `Paragraph::line_count`, which is why `ratatui` carries the `unstable-rendered-line-info` feature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed
|
||||
- The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end
|
||||
- The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does *not* reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading
|
||||
@@ -217,7 +240,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **The footer's last slot always answers how to get out**, and with a ticket open the honest answer is `ctrl-c`, the only key left that quits in one press. Going on saying `q quit` there would be 1b78a24 in the other direction: a footer describing a key by what it used to do
|
||||
- **The overlay names its ticket on the border, not at the head of the paragraph.** `Board::detail` is a `Detail` carrying the title, the id and the text, because the name has to travel beside the body rather than inside it: `content_trim` drops the `# ` heading on purpose, since `cmd_show` prints it, and anything in the paragraph scrolls away
|
||||
- `detail_title` cuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket
|
||||
- The detail view renders with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_comments_with` take the colour decision for that reason
|
||||
- The detail view renders from cells, never from painted strings: ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_history_with` take the colour decision for the CLI's side of the same layouts
|
||||
- Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
|
||||
- **A card is four corners with the title between them:** mark and short id top left, due top right, owner bottom left, comment count then criteria count bottom right. The numbers are in corners because that is where the eye goes for one, and they were invisible at the end of a line of prose
|
||||
- The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
|
||||
@@ -225,37 +248,63 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **A corner that will not fit is dropped whole**, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
|
||||
- **`corner_line`'s right side is a group, single-spaced, and it gives up its items from the front.** The item nearest the edge is what the corner is *about*; anything to its left has been added beside it. So the bottom row loses its comment count before its criteria count, and the top row, with one item, behaves exactly as it did when the parameter was an `Option`. The spacing between the items lives in `corner_line` with the gap arithmetic rather than in a caller, for the reason `column_areas` is shared: geometry reproduced by hand drifts from the draw. `due_span` returns a `Span` and not an `Option<Span>` now, since the `Option` only ever existed to satisfy the old signature and the function cannot fail
|
||||
- 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 comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The comments live outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_comments` applies, and no body is read, because a count needs none of them. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the comments of another. `comments_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
|
||||
- **The comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The history lives outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_history` applies, and no body is read, because a count needs none of them. **It counts comments and not entries**, off the kind in the filename, so a card still says how many things somebody said: a ticket that has moved three times has not been talked about, and counting the moves would put a number on every card on the board. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the history of another. `history_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
|
||||
- **The count is cyan and the mark is `COMMENT_MARK`, U+275E, a Dingbat.** It is the only coloured thing on a row whose owner and criteria count are grey, because two counts side by side otherwise read as one number in brackets and another that lost its brackets. Not U+1F4AC SPEECH BALLOON: emoji presentation and East Asian Width Wide, so it draws two cells where `spans_width` counts one character and every corner on the card lands a cell out. Not U+1F5E8 LEFT SPEECH BUBBLE either: text presentation and Neutral, but in a pictograph block most terminal fonts leave as tofu. Check both properties before swapping the glyph
|
||||
- **`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
|
||||
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the history 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
|
||||
- **`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
|
||||
- **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 statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `column_count` and the copy key all keep working unchanged
|
||||
- **`Tab::campaign` is a uuid on the tab, not on the `Board`.** A campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing
|
||||
- **The frame above the columns is three rows, and `Chrome` is what every measurement takes.** `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
|
||||
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` on the bottom left. One text row, the opening line of the description. Every row spent here is a row of cards
|
||||
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::campaign` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign, because both heights have to be measured the same way by everything that measures the board. `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
|
||||
- **The whole description is carried off the one read, and the cut is on the view.** `section_prose` replaced `section_opening`, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, and `CampaignRow::summary` takes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file
|
||||
- **`CAMPAIGN_PROSE_ROWS` is the collapsed height, and it is a constant rather than a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
|
||||
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::campaign_rows` takes the height because of this, and `frame_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
|
||||
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `CAMPAIGN_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
|
||||
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards
|
||||
- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with a campaign selected the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back
|
||||
- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no campaign is selected is the one state that must never exist — `select_campaign` and `reload` are what keep it from arising
|
||||
- **`Tab::selected` hands back nothing while the frame holds the selection.** Every key that acts on a card has to answer for the frame. `←→` are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen. `y` is the exception that earns its place: it copies the campaign's short id, so `y copy id` means the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is about
|
||||
- **`enter` routes on the focus through `Board::toggle_focused`: the frame's height on the frame, the overlay on a card.** It used to be inert on the frame for free, because `Tab::selected` hands back nothing and `toggle_detail` therefore had nothing to open. That is no longer an answer, and the routing is in `Board` rather than in the `main.rs` arm for the reason `dismiss` and `scroll_page` are
|
||||
- **`q` does not gain a layer for the expanded frame, and up and down do not take it back.** The expanded frame is the frame at its other height, not a thing laid over the board, so `q` goes on taking the campaign filter off from either height and `enter` is the only key that undoes what `enter` did. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card. `Tab::expanded` sits beside the filter and resets where `select_campaign` and `reload` reset the focus and the offset — a different campaign opens collapsed and at the top of its own description
|
||||
- **The toggle re-clamps the frame offset, through `scroll_frame(0, screen)`.** A taller viewport has a smaller last offset than a shorter one, so where the reader was can end up past the end of the frame they just asked for. The draw clamps on its own geometry either way, but the stored value has to be clamped too or the next `pgup` counts down from a number the frame never showed. A scroll of no pages is that clamp and nothing else, which keeps it in the one place it lives
|
||||
- **The frame is out of reach from under an open ticket.** With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting. `an_open_ticket_keeps_the_scroll_keys_from_the_frame` builds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it
|
||||
- **The standing comes from the columns, not from a walk of the tree.** While a campaign is selected the columns *are* its members, done included, so `Tab::standing` counts what is already in hand rather than paying what `campaign ls` pays per campaign. Counted over every column, drawn or not: hiding done is a change to what is drawn and never to what is counted
|
||||
- **The way out is on the frame's own border, not in the footer.** `q board` sits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows
|
||||
- **`c` is named in the footer only on a closed board with nothing selected**, which is where a reader has to find it. Over an open ticket and on a filtered board it is left out: the frame's border then says how to put the campaign away, and the row has no cells to spare. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
|
||||
- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, `enter expand` or `enter collapse`, the two scroll keys and `y copy id`, and leaves out `←→` because they do nothing there. It has to say which way `enter` goes, since the key is a toggle and the frame is always at one of its two heights. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and `↑` reaches it
|
||||
- **`picker: Option<Picker>` is the whole mode**, the shape `search` and `detail` use, and `Board::picker_key` runs beside `search_key` ahead of the action arms for the same reason: an open list owns the keyboard, so `d` must not toggle done and `q` must not quit while a campaign is being chosen. `ctrl-c` is the one key it declines and every other control combination is swallowed, or `ctrl-d` would reach the arm bound to `d`
|
||||
- **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty
|
||||
- **A picker row draws a real codename only.** The row opens with the short id, so the card's `~<id>` fallback would print it twice and say nothing the second time
|
||||
- **The picker draws two sections, open campaigns above completed, and truncates the completed tail.** One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by `Created At` newest first, because what a reader recognises about a finished campaign is that it was finished recently. `COMPLETED_SHOWN` of them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the rule `by_status_order` holds for a column
|
||||
- **`picker_list` is the one place that decides what a picker row is**, and `Picker::row` counts *drawn* rows. The sections reorder the campaigns and add rows of their own, so `Tab::campaigns` and the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick
|
||||
- **A heading is drawn only over rows that exist**, the bargain an untagged card's label row already makes, and it says which kind its rows are for as long as they are there — which is what a query filtering down to completed campaigns alone has to go on saying
|
||||
- **`open` and `completed`, not `open` and `done`.** The split is taken from `Standing::state`, so the section a campaign lands in and the state the frame draws cannot come to disagree about what finished means, but the word is the section's own: a campaign sits in no status directory, so it is not *in* done the way a ticket under that heading is. A campaign with no members is neither, per that method, and lists as open — completed means every member is done, and it holds none to be done
|
||||
- **Headings and the truncation line take no number: the highlight moves over campaigns only.** `stepped_picker_row` walks past the chrome rather than stopping on it, since a highlight resting on a heading gives `enter` nothing to do, and a step that runs out of campaigns is no move at all, the way a card at the end of a column clamps rather than cycling
|
||||
- **`/` in the picker is the key it already is on the board**, and `picker_key` can take it because printable keys used to fall through `_ => {}`. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer `disk` with every campaign whose description mentions one. **An empty query matches everything**, the opposite of `first_match`'s answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing `/` must not empty the list
|
||||
- **A query turns the truncation off**, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
|
||||
- **The query is a layer, and `esc` takes it off before it takes the picker off**, the order `dismiss` closes the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement and `enter` stay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every *printable* key goes into the buffer, so `q` types and so does `j`
|
||||
- **The highlight follows its campaign, not its row number.** `place_picker` takes a uuid, the answer `Tab::campaign` already gives for the filter: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted uuid before the lists are rebuilt and puts it back after
|
||||
- **A miss is a row in the box, `no match` in brightred**, where the search prompt puts its own, and `enter` on it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty
|
||||
- **The picker's footer becomes its query**, the trade `draw_search` makes: with every printable key going into a buffer, a list of keys describes nothing that works. `/ search` is named only on the closed query, and the open one names what `esc` does to *it* rather than what it does to the picker
|
||||
- **The title says both counts while a query is open**, `campaigns (2 of 6)`. The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen
|
||||
- **Every campaign's standing is settled at reload, in one pass over the cards.** `standings_of` counts the cards naming each uuid off the columns the reload is already holding, which is what `Standing::of` builds for `campaign ls` without the walk of the status directories that one pays *per campaign*. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing
|
||||
- **`Tab::standing` is gone with it.** The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rule `wrapped_height` holds for the scroll. `the_standings_are_read_when_the_cards_are_and_not_per_draw` takes the status directories away after the board is built, paired with `a_member_finished_after_the_board_was_built_completes_its_campaign` for the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changing
|
||||
- **`q` takes off one layer at a time, in the order they were put on**: the overlay, then the campaign filter, then the board. `Board::dismiss` holds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticket
|
||||
- **`digest` watches the campaigns directory** as well as the statuses and the comments. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
|
||||
- **`digest` watches the campaigns directory** as well as the statuses and the history. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
|
||||
- **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 `BLOCKED_MARK`, `×`, after its id, in brightred.** The constant lives in `util.rs` and the relations block draws the same one, since both say the same word. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
|
||||
- **The mark goes after the id, not before it.** Ahead of the id it would push every id in the column out of line whenever one card was blocked, which costs more than one card's state is worth. It is measured before the project label and the due date, so both give way to it: those are context for a ticket somebody can start, and this is the one thing on a card that says not to. Dropped whole when the row cannot hold the identity and the mark together, the rule a corner follows
|
||||
- **`blocked` is on `Card`, not on `TicketItem`.** The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the way `project` is. What `collect_ticket_items` fills is the ticket's own `uuid` and its `blockers`, both read off the file it is already holding; `mark_blocked` then walks the four columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw
|
||||
- **`blocked` is on `Card`, not on `TicketItem`.** The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the way `project` is. What `collect_ticket_items` fills is the ticket's own `uuid` and its `blockers`, both read off the file it is already holding; `mark_blocked` then walks the columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw
|
||||
- **A blocker the board does not hold marks nothing**, the answer `mv` already gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exception `detail_of` makes for the same reason: `show` and `mv` are where a hand-edited file is reported, and a board that will not draw because one ticket is malformed is the worse failure
|
||||
- **The merge carries the flag rather than recomputing it.** `relate` resolves its target inside one `.worklane`, so a blocker in another project is not a relation anything can record; resolving over the merged columns would let one project's uuid match another project's ticket. That is b8ce18c's fourth plan step and the answer is no
|
||||
- `project_label` takes the width the row has already spent, measured off the spans, rather than adding up the widths those spans are supposed to have. The hand-written version left out the space after the priority mark, so a cut label was handed one cell more than the column had; `the_project_label_leaves_the_row_inside_the_column` pins it
|
||||
- `due_date` cuts a due value back to its date only when it has one. The field is not validated (daa0e79), so it can hold a time or free text, and taking the first word regardless would turn "next friday" into "next"
|
||||
- **Done is hidden until `d` asks for it.** Not a new opinion: `ls` already counts done in its summary and leaves it out of the listing. Done only grows, so a quarter of the width was going to the column least often read. The footer carries its count while it is hidden, which is the board's version of that summary line
|
||||
- **Hiding is a change to what is drawn, never to what is read.** `reload` still scans the done directory and `digest` still watches it, so the footer count is right and revealing the column needs no rescan. Do not "optimise" that into a conditional scan
|
||||
- `visible()` returns a prefix of `columns`, not a filter, which is what keeps `column` and `offsets` valid as indices into either. It is derived from where `DONE` actually sits rather than assuming the last slot, and `the_done_column_is_last` pins the assumption. A status inserted after done would otherwise hide two columns in silence
|
||||
- Hiding the column under the selection moves the selection to the last drawn column and **closes an open detail view**. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing done again is a no-op for the selection, since a column is appended rather than inserted
|
||||
- **The terminal columns are hidden until `d` asks for them, one step at a time.** Not a new opinion: `ls` already counts both in its summary and leaves them out of the listing. Done only grows, so a quarter of the width was going to the column least often read, and discarded arriving made it two. So `d` rotates three states — hide both, show done, show both, and back around — through the `Visibility` enum on `Board`, discarded last in the rotation because it is the least likely thing to be looking for. The footer names what the *next* press does and carries the count of the column still hidden, which is the board's version of that summary line. Hiding is a prefix of the columns: done and discarded are the last two in what the board draws, so revealing either appends it and the columns before keep their indices
|
||||
- **Hiding is a change to what is drawn, never to what is read.** `reload` still scans the done and discarded directories and `digest` still watches them, so the footer counts are right and revealing either column needs no rescan. Do not "optimise" that into a conditional scan
|
||||
- `visible()` returns a prefix of `columns`, not a filter, which is what keeps `column` and `offsets` valid as indices into either. It is derived from where `DONE` and `DISCARDED` actually sit rather than assuming positions, and `the_terminal_columns_are_last_in_the_order_drawn` pins the assumption. A status inserted after discarded would otherwise hide two columns in silence
|
||||
- Hiding the column under the selection moves the selection to the last drawn column and **closes an open detail view**. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing another column is a no-op for the selection, since a column is appended rather than inserted
|
||||
- The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket
|
||||
- **Assert a column heading against the top border row, not the whole screen.** The footer names done too, so `screen.contains("done (0)")` passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden; `headings()` and `footer()` exist so the next one does not. `headings()` locates the row through `board_area()` rather than taking row zero, since the tab row sits above it when more than one board is monitored
|
||||
|
||||
@@ -290,7 +339,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
|
||||
@@ -302,11 +351,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 history block arrives as cells too, so nothing in the overlay is flat.** `history_cells` lays the block out once; `format_history` is those cells through `paint_cells` and the board pushes the same ones as a `Cells` part after the body, since the log lives outside the ticket file and `content_parts` never sees it. Pinned from both ends the way the body is: `show_prints_the_same_history_it_printed_before_the_cells_conversion` holds the CLI's output byte for byte, and `the_history_block_is_styled_in_the_overlay_and_no_escape_reached_it` pairs the presence with the absence (f3e099e, closing the gap e4d0bb7 left)
|
||||
|
||||
### 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
|
||||
@@ -319,7 +372,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `worklane tui <path>...` takes any number of paths, each resolved through `find_worklane_dir` the way the working directory is: the first `.worklane` at or above it. No path is the working directory, so a bare `worklane` and `worklane tui` are unchanged
|
||||
- The failure **names the path** that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare `worklane` has no path to name and keeps the message every other command gives, which is what its integration test asserts
|
||||
- Two paths inside one project resolve to the same `.worklane` and are monitored once. `projects()` dedupes on the resolved directory, not on the argument
|
||||
- **`Tab` owns the selection**, `column`, `card` and `offsets`, not `Board`. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. `Board::current()` is the tab in view, and `show_done` stays on the board because it is a preference about the flow rather than about a project
|
||||
- **`Tab` owns the selection**, `column`, `card` and `offsets`, not `Board`. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. `Board::current()` is the tab in view, and `visibility` stays on the board because it is a preference about the flow rather than about a project
|
||||
- The tabs are fixed for the run: a project cannot be added or dropped without restarting, so `Board::new` builds the tab list once and `reload` only refills each tab's columns. `reload` clamps **every** tab, and `select_tab` clamps again on arrival, because done may have been hidden while another tab was in view
|
||||
- The merge tab goes **first** and is where the view opens: it is the reason to monitor several boards at once. It is materialised in `reload`, from the cards already read, rather than computed per draw — the same reason the criteria count is filled in `collect_ticket_items`
|
||||
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes `by_status_order`: the merge spans statuses, so no single entry stamp governs it
|
||||
@@ -329,6 +382,32 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **The tab row is drawn only when there is more than one board**, so a single board is the view it has always been. `frame_rows()` gives it `Length(0)` otherwise, which keeps the row indices the same for both cases and is shared with `card_width` and `column_text_height` for the reason `column_areas` is: geometry reproduced by hand drifts from the draw
|
||||
- `digest_of` hashes each board's `digest` into one value, so a change in any of them redraws. Do not watch only the first
|
||||
|
||||
### Who Wrote an Entry
|
||||
- **Identity is supplied, not detected.** Every option that needs no cooperation fails: a harness variable such as `CLAUDECODE` names the tool rather than the instance and breaks across versions, walking the parent process is platform specific and also only names the harness, and a terminal check separates interactive from not, which a human piping output is too. So the actor is `WORKLANE_ACTOR`, set once per session, with `--actor` as the per-call override
|
||||
- **Precedence: flag, then `WORKLANE_ACTOR`, then `get_git_user()`, then `unknown`.** `resolve_actor` is the only caller of `get_git_user` for an entry's author, and every entry the CLI writes goes through it. The two halves are separate pure functions, `session_actor` and `entry_actor`, tested without touching the process environment for the reason `colors_wanted` is split that way
|
||||
- **The session half is cached in a `OnceLock`, the way `should_use_colors` is:** neither the variable nor the git user can change mid-run, and the fallback costs a `git config` subprocess. `session_actor` takes the git user as a closure so that subprocess is not run when the variable already answered
|
||||
- An **empty `WORKLANE_ACTOR` counts as unset**, the convention `colors_wanted` follows for `NO_COLOR`, so a wrapper script can clear an inherited one. Whitespace counts the same, since a shell quoting a missing value writes one
|
||||
- **The actor is free text, checked against nothing**, like the `chown` user: there is no registry of actors, and the same reason `ls --tag` refuses to validate a tag
|
||||
- **It was `comment --owner`, renamed with no alias.** Owner is the ticket's assignee and has one writer, `chown`; this names the writer of the entry, which is a different field. Pre-1.0, and two names for one thing is what splitting `set` and `chown` avoided. `the_owner_flag_is_gone` pins the refusal, since an alias kept "for now" is what makes the wrong name permanent
|
||||
- **`add --owner` and `campaign add --owner` still default to the git user, deliberately.** Those write the assignee, and a ticket an agent files is work for the person whose board it is; attributing it to the agent would put its name in the Owner column of everything it reported
|
||||
- **An entry does not record whether the call had a terminal.** It is the one agent signal that needs no cooperation, so it was worth considering, and it was rejected: it cannot name an actor, a human piping output produces the same value, and once the actor is explicit the extra field answers no question anybody asks
|
||||
- **Set it in the agent's configuration, not per call.** `env` in `~/.claude/settings.json` reaches every command Claude Code runs. opencode has no equivalent: its config is JSON with no `env` block for the tools it spawns, so it inherits the environment it was started with, which means a wrapper or a shell function around `opencode`. Both are documented in `assets/SKILL.md` rather than assumed
|
||||
|
||||
### The History Log
|
||||
- **The log is the comments directory with the kind named in it.** It was already an append-only log with one event kind: one file per entry under `.worklane/history/<uuid>/`, stamped to the microsecond and written with `create_new`. Adding `status`, `owner` and `tags` beside `comment` needed no new mechanism, which is why there is no separate journal file and no database
|
||||
- **What is not logged, deliberately:** ticking or unticking a criterion, and edits to the title, description, plan, priority or due. Those change often and a log of them is noise. When one of them matters, whoever made it adds a comment saying why. Do not add a kind for a field on the grounds that it is cheap to record: the cost is that the log stops being worth reading
|
||||
- **`--clear` is logged, since it is the same field going somewhere.** `chown --clear` and `set --clear tags` write an entry whose after-value is the sentinel the ticket now holds, `_Not set_` or `_None_`. The values are recorded verbatim rather than translated into words this module invented, so an entry reads the way the field it came from does
|
||||
- **The kind is read from the file and only counted from the filename.** `parse_entry` matches the leading marker; `kind_from_stem` splits the stem for the card's counter, which must not read four hundred files to draw a board. A name says what a file is for a listing, and the file says what it is for a reader
|
||||
- **A file with no marker is a comment**, which is what every entry written before the kinds existed is. That is the whole of the compatibility, and it is why there is no migration command: `entry_content(Kind::Comment, ..)` is byte for byte what `cmd_comment` wrote before this module, so nothing is rewritten and either version can read the other's board
|
||||
- **The old directory is adopted, not migrated.** `adopt_comments` renames `comments` to `history` on the first access, and the reader, the writer and the counter all call it, so no caller has to remember it and no path reaches the log without it. **A board holding both is refused**, naming both paths: only worklane writes there, so it cannot reach that state on its own, and picking which of two entries with one name survives is not a decision to make silently. The counter swallows that error, because a count is drawn per card and a board that cannot be adopted must not take the TUI down; the next write reports it
|
||||
- **An entry is written after the edit it describes, never before.** A refused move, a refused chown and a failed save log nothing, which is what `a_refused_move_writes_nothing` and `a_failed_edit_writes_nothing` pin. The cost of that order is that a failed entry write leaves the edit in place and reports the failure, which is the right way round: the ticket is the record and the log is the story of it
|
||||
- **A no-op edit writes nothing either, and `apply` is what decides that** for `set`: a field it did not record as changed was already what the call asked for. `cmd_mv` and `cmd_chown` have their own early returns and sit behind them
|
||||
- **The stamp leads the filename and the kind follows it**, so the lexicographic sort in `read_history` stays chronological however many kinds there are. The collision suffix goes last, after the kind, and is a number, so it matches no slug and the counter skips it
|
||||
- **A mechanical entry renders as one line and a comment as it always did.** A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to `Kind::LABEL_WIDTH`, `campaign` being the longest of the four, so the bodies line up under each other
|
||||
- **A campaign entry records `Campaign::name`, the codename or failing that the title, never the uuid the field holds.** Settled when the entry is written, not left to the renderer: a log is a record, and resolving at read time would let an entry change meaning when a campaign is renamed. A `before` uuid the board no longer has reads `_missing_`, the way the Campaign field itself renders a dangling one, and a ticket never assigned starts from `_Not set_` (f774a33)
|
||||
- **`--actor` is on every command that writes an entry**, spelled from one `ACTOR_HELP` in `command.rs`: a flag documented differently on each command reads as four flags. On `chown` it sits beside `user`, which is the ticket's new assignee — the two are different questions and that command answers both
|
||||
- **`set --actor` reaches only the entry `--tags` writes**, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries
|
||||
|
||||
### Shipping the Agent Assets
|
||||
- The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
|
||||
- **`assets/SKILL.md` is the only worklane skill document in this repo, and nothing may reintroduce a second.** There was one: `.opencode/skill/worklane-kanban-skill/SKILL.md`, 223 lines of the same document that nothing shipped and no test checked, and it drifted exactly as far as a copy nobody reads does. Its frontmatter still called the skill `worklane_kanban`, its examples still used short flags the CLI had stopped accepting, and it knew nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow. It was **not** inert while it existed: `opencode debug skill` listed it, so an agent working in this repo saw two worklane skills and could load either. Deleted by b2c5531. A copy under `.opencode/`, in a second assets file, or in the README is the same mistake; the document has one home and `install-skill` is how it travels
|
||||
@@ -356,11 +435,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
|
||||
@@ -376,7 +456,8 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- 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
|
||||
- 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
|
||||
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `●` discarded, grey `?` for a target the board does not hold. Discarded takes the full circle of done in the grey of the untouched pile: nothing is left to do, and it is not an achievement. The *pair* is what has to be unique, which is the same bargain the two half circles already take, and `every_status_has_a_mark` pins it against `status_dirs`. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
|
||||
- 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
|
||||
@@ -388,8 +469,10 @@ 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
|
||||
- **`history.rs` owns the log end to end**: the path, the kinds, the parse, the write, the count and the render. It came out of `util.rs` and `handlers.rs`, where the reader, the writer, the counter and the renderer sat in three files and one of them was 5,500 lines. The test for the reason is the module doc: a reader asking what an entry is has one file to open, the way `campaign.rs` and `tag.rs` answer their own questions
|
||||
- The body's painters return cells, not strings: `ordered_cells`, `inline_cells`, `metadata_cells`, `metadata_value_cells`, `tag_cells` and `push_heading`. `content_trim_colored` is the CLI entry point and `paint_cells` is the only thing that writes an escape. `colorize_line` is gone: it was a `pub` alias for the bold pass with one caller, and the only thing it added was asking the terminal
|
||||
- **`inline_cells` walks the line once for both inline markers**, `**bold**` and `[text](url)`, rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and `\x1b[36m` carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was `colorize_bold` while links lived in a branch of their own in `content_parts`; that branch is gone, which is also what gives the criteria text and the metadata `Other` rows their links, since those already went through this function
|
||||
- `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
|
||||
@@ -416,12 +499,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
@@ -1503,7 +1503,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "worklane"
|
||||
version = "0.24.1"
|
||||
version = "0.31.2"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "worklane"
|
||||
version = "0.24.1"
|
||||
version = "0.31.2"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
@@ -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
|
||||
@@ -5,29 +5,38 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
## Commands
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, whose border carries a page indicator while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it and says how far it has got, and `q` on its border gives the whole board back. 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` or `worklane tui [path...]` | Opens the board: one column per status, redrawn when the tree changes. Read only. Opens with done and discarded hidden, their counts in the footer; `d` rotates hide both, show done, show both, and back around. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, `enter` gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
|
||||
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done, discarded directories |
|
||||
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
|
||||
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
|
||||
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three |
|
||||
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
|
||||
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused |
|
||||
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three. Ends with the ticket's history: every comment on it and every change to its status, owner or tags, oldest first, each naming who made it |
|
||||
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions. `--status discarded` is exempt and reachable from anywhere, for a ticket that will not be done; leaving `discarded` is a backward move and needs `-f`. Discarding is refused while open tickets are blocked by the ticket, `-f` overrides. Records a `status` entry in the ticket's history, after the move: a refused or no-op move records nothing. `--actor` names the writer of that entry |
|
||||
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused. `--tags` records a `tags` entry in the ticket's history, with the tags before and after, and it is the only field of this command's that is logged; `--actor` names the writer of that entry |
|
||||
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last |
|
||||
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning. `mv` refuses to move a ticket blocked by one that is not done, unless `-f` |
|
||||
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to |
|
||||
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to. Records an `owner` entry in the ticket's history, with the owner before and after; `--actor` names who made the change, which is not the same as the user argument |
|
||||
| `worklane check <ticket> [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal |
|
||||
| `worklane uncheck <ticket> [criteria...]` | Unticks acceptance criteria, addressed the same way |
|
||||
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
|
||||
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title. The author is `--actor`, or `WORKLANE_ACTOR`, or the git user, in that order |
|
||||
| `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, and `--codename`. At least one required. The only way to change a campaign after it is filed, and the way a campaign filed before codenames existed gets one. 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. No `--description`: replacing prose without an `append` to add a paragraph is half a pair |
|
||||
| `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 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, 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 |
|
||||
| `worklane completions <shell>` | Prints a completion script for `fish`, `bash`, `zsh`, `elvish` or `powershell`. See below |
|
||||
| `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 |
|
||||
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Four 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, and `worklane-admin` sets a board up and repairs one, its tag vocabulary and the faults a board can develop. 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-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
|
||||
|
||||
## Environment
|
||||
|
||||
| Variable | Effect |
|
||||
|----------|--------|
|
||||
| `WORKLANE_ACTOR` | Who every entry the CLI writes is attributed to: a comment, and the `status`, `owner` and `tags` entries `mv`, `chown` and `set --tags` record. Set it once, in the environment an agent runs in, and every call it makes is attributed to it instead of to the git user of whoever's machine it is on. `--actor` overrides it per call, an empty value counts as unset, and with neither supplied the author is the git user and then `unknown`. Free text, checked against nothing |
|
||||
| `NO_COLOR` | Set and non-empty turns colour off, whatever the value, per no-color.org. Colour is also off when output is not a terminal, and when `TERM` is `dumb` or empty |
|
||||
| `XDG_CONFIG_HOME` | Where `install-tool` looks for opencode's config root, `$XDG_CONFIG_HOME/opencode`, defaulting to `~/.config`. `install-skill` does not follow it: `~/.claude` is not an XDG path |
|
||||
|
||||
## Completions
|
||||
|
||||
```sh
|
||||
@@ -42,7 +51,7 @@ asks worklane for the one thing only the board knows:
|
||||
|
||||
```
|
||||
worklane show <TAB> every ticket, id and title, done included
|
||||
worklane mv <TAB> the same, then --status <TAB> for the four
|
||||
worklane mv <TAB> the same, then --status <TAB> for the five
|
||||
worklane chown alice <TAB> the ticket, which is the second argument here
|
||||
worklane chown --clear <TAB> the ticket, which the flag carries here
|
||||
worklane relate x --blocked-by <TAB>
|
||||
@@ -77,3 +86,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.
|
||||
|
||||
+323
@@ -0,0 +1,323 @@
|
||||
---
|
||||
name: worklane-admin
|
||||
description: Set up and repair a worklane board itself, whatever it tracks: design and annotate the tag vocabulary with `worklane tags`, retire or rename a tag, and fix a board whose files and fields disagree, such as a ticket missing from `ls`, a duplicated id, a stray temp file or a move that will not go through. Use when the subject is the board's own configuration or health. Not for filing, working or reviewing a ticket, and not for priorities, due dates or campaigns.
|
||||
---
|
||||
|
||||
# Administering a worklane board
|
||||
|
||||
For "set up a board for this", "what tags should this board have", "add a tag", "what
|
||||
does this tag mean", "the board is in a weird state", "this ticket has gone missing".
|
||||
The subject is the board itself: the vocabulary it files against, and the parts that can
|
||||
come apart.
|
||||
|
||||
The CLI is the `worklane` skill: the statuses, how a ticket is addressed, which command
|
||||
owns which field. Read it too.
|
||||
|
||||
**This is not `worklane-plan`.** That skill grooms the work: priorities, due dates,
|
||||
retagging tickets, campaigns. This one decides what the tags *are* and puts the board
|
||||
back together. The line between them is the tag section: designing and annotating the
|
||||
vocabulary is here, applying it across tickets is there.
|
||||
|
||||
## A board is not only for software
|
||||
|
||||
Everything below holds for a board tracking a product strategy, a house move or a term's
|
||||
teaching, and the worked examples say so. What changes between domains is the tags, never
|
||||
the shape. Nothing in worklane knows what your tickets are about.
|
||||
|
||||
Two things you do not get to configure, whatever the board is for:
|
||||
|
||||
- **The four statuses.** `backlog`, `committed`, `reviewing`, `done`, in that order, one
|
||||
step at a time. There is no way to rename them or add a fifth. If a board wants a
|
||||
waiting-on-someone-else state, that is a tag, and the ticket stays in `committed`.
|
||||
- **The fields.** Priority 1 to 5, Due, Owner, Tags, Campaign. A board that wants a
|
||||
concept these do not cover expresses it as a tag or a campaign, not as a new field.
|
||||
|
||||
So the tag vocabulary is where a board is fitted to its subject, and it is most of this
|
||||
document.
|
||||
|
||||
## Starting a board
|
||||
|
||||
```
|
||||
worklane init # in the directory the board belongs to
|
||||
```
|
||||
|
||||
Which directory decides which board. Commands walk up from the working directory to the
|
||||
nearest `.worklane`, so a board in `~/house` answers every `worklane` run from anywhere
|
||||
under `~/house` and nowhere else.
|
||||
|
||||
`init` makes the four status directories, the campaigns directory and an empty `tags.md`.
|
||||
Run on a board that already exists it prints a line and changes nothing, which is what
|
||||
makes it safe to run when you are not sure.
|
||||
|
||||
Then declare the vocabulary before the tickets pile up. Tags applied for months are far
|
||||
harder to change than tags agreed once, because changing one means rewriting every ticket
|
||||
carrying it.
|
||||
|
||||
## Designing a tag vocabulary
|
||||
|
||||
A tag is a word a ticket carries so the board can be cut by it later. `worklane ls --tag
|
||||
kitchen` is the whole payoff, so the test of a good vocabulary is whether the cuts it
|
||||
allows are cuts anyone wants.
|
||||
|
||||
### Work in axes
|
||||
|
||||
An axis is one question every ticket on this board can answer, with a small closed set of
|
||||
answers. Pick two or three axes and keep them apart. Nearly every vocabulary that goes
|
||||
bad is one where two axes were mixed into one pile of words.
|
||||
|
||||
A software tool:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `feature`, `bug`, `chore`, `docs` |
|
||||
| Area | `cli`, `tui`, `api`, `build` |
|
||||
|
||||
A product strategy:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `research`, `decision`, `experiment`, `writeup` |
|
||||
| Audience | `enterprise`, `self-serve`, `internal` |
|
||||
|
||||
A household:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `repair`, `errand`, `admin`, `cleaning` |
|
||||
| Room | `kitchen`, `garden`, `garage`, `car` |
|
||||
|
||||
Same shape, nothing in common. Derive the axes from the questions somebody will actually
|
||||
ask this board, not from a template: if nobody will ever ask "show me everything in the
|
||||
garage", `garage` is not earning its place.
|
||||
|
||||
### The rules
|
||||
|
||||
- **A tag is for kind, not for state.** State is the status directory. A `doing` tag
|
||||
beside `committed`, a `blocked` tag beside a `blocked by` relation, a `done` tag at all:
|
||||
each is a second copy of something the board already knows, and the copy is the one that
|
||||
goes stale.
|
||||
- **A tag is not a goal.** Everything for one outcome is a campaign, which has a title, a
|
||||
description and a state derived from its members. `worklane campaign` owns that;
|
||||
`worklane-plan` decides what belongs in one.
|
||||
- **A tag is not a field.** No `p1` beside Priority, no `alice` beside Owner, no `august`
|
||||
beside Due. The field is the writer and the tag will disagree with it.
|
||||
- **A tag is not a person.** Owner is a field, and `chown` writes it.
|
||||
- **Two axes, not two words for one thing.** Before adding a word, say which axis it is
|
||||
on. If it does not fit one, either it is a new axis, which is a decision, or it is a
|
||||
private note, which is not a tag.
|
||||
- **Around a dozen tags, up to twenty.** Past that nobody remembers the vocabulary, so
|
||||
they invent a near-duplicate instead of reusing what is there. Fewer, broader tags beat
|
||||
a long tail nobody can recall.
|
||||
- **Singular or plural, pick one and keep to it.** `bug`/`bugs` and `chore`/`chores` are
|
||||
the commonest way a board ends up with two words for one idea.
|
||||
- **Case matters.** `Bug` and `bug` are two tags to `--tag`, to `tags` and to the colour
|
||||
a card is drawn in. Lowercase everything unless there is a reason.
|
||||
|
||||
### How many tags per ticket
|
||||
|
||||
One per axis is the target: a ticket is one kind of thing in one area. A ticket that wants
|
||||
three areas is usually two tickets, and a ticket with no tag at all is invisible to every
|
||||
question asked by tag.
|
||||
|
||||
## Annotating a tag
|
||||
|
||||
```
|
||||
worklane tags # every tag, its count and what it means
|
||||
worklane tags add kitchen --annotation "..." # declare one, and say what it means
|
||||
worklane tags set kitchen --annotation "..." # change what it means
|
||||
```
|
||||
|
||||
`.worklane/tags.md` holds one section per declared tag, the tag as the heading and its
|
||||
annotation under it. It is what a person opens to find out what the board means by a word,
|
||||
and it is what an agent reads before choosing one.
|
||||
|
||||
**Declaring a tag tags nothing, and tagging a ticket declares nothing.** The two lists are
|
||||
separate on purpose: the counts come from what the tickets carry, `tags.md` records what
|
||||
the board agreed on, and the difference between them is the thing worth looking at. A tag
|
||||
carried by tickets but never declared is a word somebody invented in a hurry.
|
||||
|
||||
`worklane tags` reports both, as the tag, a tab, the count, and a tab and the annotation's
|
||||
opening line for a tag that is declared. So the two cases worth finding read off the
|
||||
listing: a tag at a count of zero is declared and nobody has reached for it, and a tag with
|
||||
no annotation column at all is carried and was never declared.
|
||||
|
||||
### What an annotation has to say
|
||||
|
||||
The definition is the easy half and does the least work. What stops drift is the boundary
|
||||
against the neighbouring tag, so write that.
|
||||
|
||||
Worthless, because nobody was ever unsure of this:
|
||||
|
||||
```
|
||||
worklane tags add bug --annotation "Bugs."
|
||||
```
|
||||
|
||||
Useful, because it answers the question somebody was actually about to get wrong:
|
||||
|
||||
```
|
||||
worklane tags add bug \
|
||||
--annotation "Behaviour that contradicts what the tool says it does, reproducible from a described state." \
|
||||
--annotation "" \
|
||||
--annotation "Not for something missing. A gap is a feature, however obvious the gap is."
|
||||
```
|
||||
|
||||
The same for a household board:
|
||||
|
||||
```
|
||||
worklane tags add repair \
|
||||
--annotation "Something that worked and now does not." \
|
||||
--annotation "" \
|
||||
--annotation "Not for an improvement to something that works, which is a project, and not for a thing that needs replacing rather than fixing."
|
||||
```
|
||||
|
||||
Repeat `--annotation` for more lines, and pass an empty one for a paragraph break. Three
|
||||
lines is plenty: a definition, then the boundary.
|
||||
|
||||
Write an annotation for every tag, including the obvious ones. The obvious tags are the
|
||||
ones two people quietly disagree about.
|
||||
|
||||
### Traps
|
||||
|
||||
- `tags add` refuses a tag that is already declared, and `tags set` refuses one that is
|
||||
not. Each names the other, so the refusal tells you which you wanted.
|
||||
- A tag cannot contain a comma, because a comma is what separates one tag from the next in
|
||||
the Tags field. Surrounding spaces are trimmed.
|
||||
- A tag you have declared and never applied lists at a count of zero. That is not a fault;
|
||||
it is the file and the board disagreeing, which is the state that tells you the
|
||||
vocabulary has not landed yet.
|
||||
- Nothing removes a declaration. There is no `tags rm`, so a tag declared in error stays
|
||||
in the file with whatever its annotation says. Say it is retired in the annotation.
|
||||
|
||||
## Changing the vocabulary later
|
||||
|
||||
### Renaming a tag
|
||||
|
||||
There is no rename. The tag is the key, so it means rewriting the Tags field of every
|
||||
ticket carrying it, one at a time:
|
||||
|
||||
```
|
||||
worklane ls --tag bugs --ids # every ticket carrying the old word
|
||||
worklane show 1b78a24 # read the whole Tags field of each
|
||||
worklane set 1b78a24 --tags bug,cli # restate all of them, with the new word
|
||||
worklane tags add bug --annotation "..."
|
||||
```
|
||||
|
||||
**`--tags` replaces the whole field.** Restate every tag the ticket should keep or the
|
||||
ones you leave out are gone, with no undo. This is the most destructive command on the
|
||||
board. Read the ticket's current tags before writing, never from memory, and run
|
||||
`worklane tags` before and after: a count that moved where nothing was meant to change is
|
||||
a tag lost to that rule.
|
||||
|
||||
Propose the whole list of edits and wait for approval before applying any of them, the way
|
||||
`worklane-plan` requires for a sweep. The reason is the same: nothing records what a field
|
||||
held before you wrote to it.
|
||||
|
||||
### Retiring a tag
|
||||
|
||||
Take it off the tickets the same way, then leave the declaration saying it is retired and
|
||||
what replaced it. A tag with a count of zero and an annotation pointing elsewhere is a
|
||||
better answer than a word that simply vanishes, because the next person will otherwise
|
||||
reinvent it.
|
||||
|
||||
## Repairing a board
|
||||
|
||||
Every repair here has been run against a real board. Work by symptom.
|
||||
|
||||
**The rule that does not bend: do not edit a ticket file.** The filename, the `Status`
|
||||
field and the directory have to agree, and the commands are what keep them agreeing. The
|
||||
two exceptions below are files no command owns, and they are marked as such.
|
||||
|
||||
### A ticket has vanished from `ls`
|
||||
|
||||
`worklane ls` leaves `done` out of its listing, though it still counts it at the top. So
|
||||
first check `worklane ls done`. If it is there and should not be, its file has been moved
|
||||
into the wrong directory by hand or by a restore.
|
||||
|
||||
The repair is two moves, not one:
|
||||
|
||||
```
|
||||
worklane mv 1b78a24 --status reviewing -f
|
||||
worklane mv 1b78a24 --status done -f
|
||||
```
|
||||
|
||||
`mv` reads the current status from the *directory*, so moving it to the status the
|
||||
directory already says it is in is refused as a no-op and the field stays wrong. Moving it
|
||||
away and back rewrites the field. Check with `worklane show 1b78a24`, whose `Status` line
|
||||
is read from the file rather than from where it sits.
|
||||
|
||||
### A command says the id matches several tickets
|
||||
|
||||
```
|
||||
Multiple tickets found matching 'bf2dc18':
|
||||
1. (bf2dc18) Alpha [backlog]
|
||||
2. (bf2dc18) Alpha [done]
|
||||
```
|
||||
|
||||
The same file exists in two status directories, usually from a copy or a half-finished
|
||||
restore. The ticket is now unaddressable: every command resolves before it acts, so `show`
|
||||
and `mv` fail the same way and cannot be used to fix it.
|
||||
|
||||
**File exception.** Read both with `cat`, keep the one whose `Status` field agrees with
|
||||
the directory it is in, and delete the other. If neither agrees, keep either and repair it
|
||||
as above. Then confirm with `worklane show`.
|
||||
|
||||
### A move is refused by a blocker
|
||||
|
||||
```
|
||||
Cannot move 'Beta' while it is blocked by:
|
||||
...
|
||||
Use --force (-f) to move it anyway.
|
||||
```
|
||||
|
||||
Working as intended: a ticket cannot advance while something it waits on is unfinished.
|
||||
Finish the blocker, or use `-f` if the dependency is no longer real. Note that the
|
||||
relation stays on the ticket and will refuse the next move too, and there is no way to
|
||||
take a relation off, so `-f` is the answer every time until the blocker is done.
|
||||
|
||||
If the message says `is blocked by X, which is not on the board`, the blocker has been
|
||||
deleted. That is a warning rather than a refusal and the move goes through.
|
||||
|
||||
### `show` renders `_missing_`
|
||||
|
||||
A relation or a Campaign field naming something the board no longer holds. Harmless to
|
||||
read and impossible to clear, since `relate` only adds and `assign` only moves a ticket
|
||||
between campaigns that exist. For a campaign, `worklane assign <a-real-campaign> <ticket>`
|
||||
overwrites it. For a relation, leave it.
|
||||
|
||||
### A status is missing from `worklane ls`
|
||||
|
||||
The count list at the top of `ls` names every status directory it found, so a status that
|
||||
is absent from it has had its directory deleted. Nothing errors until something tries to
|
||||
move a ticket there, which then fails with a raw file error.
|
||||
|
||||
**File exception.** `worklane init` will not repair it, since it refuses on a board that
|
||||
already exists. Recreate the directory:
|
||||
|
||||
```
|
||||
mkdir .worklane/reviewing
|
||||
```
|
||||
|
||||
### A `.wl-*.tmp` file in `.worklane/`
|
||||
|
||||
The staging file for a write that was killed part way. Every write stages here and renames
|
||||
into place, so a leftover means the write did not finish; nothing reads these and no
|
||||
listing shows them.
|
||||
|
||||
**File exception.** Delete it. Then check the ticket it names with `worklane show` and
|
||||
redo whatever the interrupted command was.
|
||||
|
||||
### Nothing works and the error names `.worklane`
|
||||
|
||||
Check where you are. Commands resolve the nearest `.worklane` at or above the working
|
||||
directory, so running from the wrong directory addresses another board or none. `worklane
|
||||
ls` from where you think the board is, is the fastest way to find out.
|
||||
|
||||
## What this skill does not touch
|
||||
|
||||
- **Priorities, due dates, campaign membership and retagging sweeps.** That is
|
||||
`worklane-plan`. Deciding the vocabulary is here; applying it across the board is there.
|
||||
- **Filing a ticket, working one, moving it through the statuses.** That is the `worklane`
|
||||
skill.
|
||||
- **Judging whether a finished ticket is really done.** That is `worklane-review`.
|
||||
- **The content of a ticket.** A description or an acceptance criterion that is wrong is
|
||||
the author's, and the answer is a comment on that ticket.
|
||||
+19
-1
@@ -136,6 +136,14 @@ field on purpose, which is a different thing from emptying it by forgetting a ta
|
||||
proposed: a count that dropped where nothing was meant to change is a tag lost to the
|
||||
replace-the-whole-field rule above.
|
||||
|
||||
**Designing the vocabulary is the `worklane-admin` skill, not this one.** What the tags
|
||||
should be, what each one means, how one is declared with `worklane tags add` and annotated
|
||||
so the next person picks the same word: read that document before proposing a vocabulary,
|
||||
and read `.worklane/tags.md` before proposing a tag. This section is the sweep over
|
||||
tickets already tagged, which is a different job. A board whose tags are declared has an
|
||||
annotation per tag, and a ticket that contradicts one is mis-tagged against a written
|
||||
standard rather than against your reading of the board.
|
||||
|
||||
Derive the vocabulary from the board rather than inventing one. Read `worklane tags`, count
|
||||
what is actually used, and show the count before proposing anything. What to report:
|
||||
|
||||
@@ -160,7 +168,8 @@ fields; a goal is a campaign.
|
||||
worklane campaign ls
|
||||
worklane campaign show v1
|
||||
worklane campaign add --title "..." --codename v1 --description "..."
|
||||
worklane campaign set v1 --title "..." # or --codename, on one already filed
|
||||
worklane campaign set v1 --title "..." # or --description or --codename, on one already filed
|
||||
worklane campaign append v1 -d "..." # add a paragraph to the description
|
||||
worklane assign v1 1b78a24
|
||||
```
|
||||
|
||||
@@ -186,6 +195,12 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
|
||||
- **Do not propose renaming a codename a campaign already has.** It is what the campaign is
|
||||
called on every card in it and at the command line, so changing it is churn dressed as
|
||||
grooming. `campaign set` refuses it without `--force` for that reason.
|
||||
- **A campaign's description is editable, so a wrong one is a fix rather than a refiling.**
|
||||
A container whose description no longer describes what its members are for is worth
|
||||
pointing out: it is the line every one of those tickets was filed against. `campaign set
|
||||
--description` replaces it and `campaign append --description` adds to it, so neither
|
||||
needs the campaign refiled and its members reassigned. Adding to it is the usual answer;
|
||||
replacing prose to add a sentence to it is how the rest of it gets lost.
|
||||
|
||||
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.
|
||||
@@ -199,6 +214,9 @@ out of it. The last part is what makes it a goal rather than a pile.
|
||||
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.
|
||||
- **The tag vocabulary itself, and the state of the board's own files.** Declaring a tag,
|
||||
writing what it means, retiring one, or repairing a ticket whose file and fields have
|
||||
come apart: all `worklane-admin`. A sweep applies the vocabulary, it does not decide it.
|
||||
- **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.
|
||||
|
||||
+130
-29
@@ -1,15 +1,15 @@
|
||||
---
|
||||
name: worklane
|
||||
description: Manage tickets on a local worklane kanban board with the `worklane` CLI, backed by markdown files in a `.worklane/` directory. Use whenever you need to file, find, read, update, comment on or move a ticket, when asked what is on the board or what to pick up next, and when reporting work you are not going to do in the change at hand. Covers the four statuses, how a ticket is addressed, what belongs in each section, and the argument traps that silently swallow a flag.
|
||||
description: Manage tickets on a local worklane kanban board with the `worklane` CLI, backed by markdown files in a `.worklane/` directory. Use whenever you need to file, find, read, update, comment on or move a ticket, when asked what is on the board or what to pick up next, and when reporting work you are not going to do in the change at hand. Covers the five statuses, how a ticket is addressed, what belongs in each section, and the argument traps that silently swallow a flag.
|
||||
---
|
||||
|
||||
# worklane
|
||||
|
||||
A kanban board as files. Every ticket is one markdown file in `.worklane/<status>/`,
|
||||
named `<uuid>_<slug>.md`, and comments live in `.worklane/comments/<uuid>/`. The CLI is
|
||||
the only thing that writes there: do not hand-edit or hand-place a file, because the
|
||||
filename, the `Status` field and the directory have to agree and the commands are what
|
||||
keep them agreeing.
|
||||
named `<uuid>_<slug>.md`, and its history lives in `.worklane/history/<uuid>/`, one file
|
||||
per entry. The CLI is the only thing that writes there: do not hand-edit or hand-place a
|
||||
file, because the filename, the `Status` field and the directory have to agree and the
|
||||
commands are what keep them agreeing.
|
||||
|
||||
Commands walk up from the working directory to find the nearest `.worklane`, so **run
|
||||
`worklane` inside the repo the ticket belongs to**. Which directory you run it in is
|
||||
@@ -20,7 +20,7 @@ a person, not for you: it takes over the screen and does not return until quit.
|
||||
|
||||
## The flow
|
||||
|
||||
`backlog` → `committed` → `reviewing` → `done`
|
||||
`backlog` → `committed` → `reviewing` → `done`, with `discarded` off to one side
|
||||
|
||||
**Move the ticket as you work it, not afterwards.** `worklane mv <id> --status committed`
|
||||
before writing any code, and `--status reviewing` once it is done and the tests pass. The
|
||||
@@ -35,11 +35,39 @@ skipping move, for correcting a mistake.
|
||||
A move is also refused while the ticket is blocked by one that is not done yet, see
|
||||
[Relating tickets](#relating-tickets).
|
||||
|
||||
`mv` stamps the time as it goes: `Committed On`, `Submitted On` and `Completed On`, one
|
||||
field for the status the ticket is in now, shown by `show` among the rest of the
|
||||
metadata. Only the current one is kept, so the stamp says how long the ticket has been
|
||||
where it is, not how long each earlier stage took. Nothing else writes them, and moving
|
||||
a ticket back removes the stamp of the status it left.
|
||||
`mv` stamps the time as it goes: `Committed On`, `Submitted On`, `Completed On` and
|
||||
`Discarded On`, shown by `show` among the rest of the metadata. They **accumulate**, so a
|
||||
ticket that walked the whole flow carries all of them side by side and the journey is
|
||||
legible; presence means it got that far and has not been sent back past it, not that it
|
||||
is there now, which is what `Status` says. Moving a ticket back drops the stamps of every
|
||||
stage after where it lands.
|
||||
|
||||
## Discarding a ticket
|
||||
|
||||
`worklane mv <id> --status discarded` is where a ticket goes that will not be done: a
|
||||
duplicate, something obsolete, something that turned out to be wrong. It keeps the record
|
||||
and the relations, which deleting the file by hand would destroy.
|
||||
|
||||
```
|
||||
worklane mv 1b78a24 --status discarded
|
||||
```
|
||||
|
||||
Reachable from any status and needs no `-f`, because discarding is not a stage of work: a
|
||||
backlog ticket does not have to be walked through `committed` to be abandoned. **Say why
|
||||
in a comment before you discard it.** The status records that it will not happen and
|
||||
nothing records what was decided, and that is the question somebody asks in six months.
|
||||
|
||||
What it means everywhere else:
|
||||
|
||||
- `ls` leaves it out of the listing and keeps it in the counts, the way it treats `done`.
|
||||
`ls discarded` and `--ids` still reach it
|
||||
- A campaign counts a discarded member as **finished**: the work left the campaign rather
|
||||
than sitting in it unfinished
|
||||
- A discarded ticket **blocks nothing**, so a ticket waiting on it can move
|
||||
- Discarding a ticket that open tickets are blocked by is **refused**, naming them: their
|
||||
plans depended on this work, so they need a look first. `-f` says you looked
|
||||
- Getting it back is a backward move, so it needs `-f`:
|
||||
`worklane mv 1b78a24 --status backlog -f`
|
||||
|
||||
## Reading the board
|
||||
|
||||
@@ -48,13 +76,13 @@ worklane ls # every status, counts then tickets
|
||||
worklane ls backlog # one status
|
||||
worklane ls --priority 1 # only the most urgent
|
||||
worklane ls --tag bug # only the tickets carrying that tag
|
||||
worklane show 1b78a24 # one ticket, body and comments
|
||||
worklane show 1b78a24 # one ticket, body and history
|
||||
```
|
||||
|
||||
`ls` prints a seven-character id per ticket. That is what you address it by.
|
||||
|
||||
`worklane ls --ids` prints the same tickets as an id, a tab and a title, one per line and
|
||||
unstyled, with done included and the filters still applying. That is the form to parse
|
||||
unstyled, with done and discarded included and the filters still applying. That is the form to parse
|
||||
when you want the ids themselves: `worklane ls --ids | cut -f1`. The decorated listing is
|
||||
for reading, not for cutting up.
|
||||
|
||||
@@ -99,6 +127,11 @@ is never left half-marked. A criterion already in the state you asked for is rep
|
||||
unchanged rather than refused, and a call that would change nothing writes nothing. Both
|
||||
apply to `uncheck` exactly as they do to `check`.
|
||||
|
||||
**Say why on the unusual moves:** `worklane mv 1b78a24 --status backlog -f --reason "the
|
||||
first plan was wrong"`. The reason is recorded inside the history entry beside the
|
||||
transition it explains and rendered indented under its row, in `show` and on the board.
|
||||
Optional on every move; a refused or no-op move records nothing even with one.
|
||||
|
||||
## Filing a ticket
|
||||
|
||||
```
|
||||
@@ -159,7 +192,7 @@ one command here that does not start with the ticket. The user is free text and
|
||||
checked against nothing. Swap the two and the call fails, because the username has to
|
||||
resolve as a ticket. `--clear` replaces both arguments with the ticket alone.
|
||||
|
||||
`worklane init` creates `.worklane/` with the four status directories and the campaigns
|
||||
`worklane init` creates `.worklane/` with the five status directories and the campaigns
|
||||
directory beside them, for a repo that has no board yet.
|
||||
|
||||
## Relating tickets
|
||||
@@ -176,9 +209,10 @@ on B. **Only one side is stored**, on the ticket you name, and `show` derives th
|
||||
end for the ticket at the far side, so never record both directions.
|
||||
|
||||
`--blocked-by` is enforced: `mv` refuses to move a ticket while a ticket it is blocked by
|
||||
is not in `done`, whichever move it is, and names every open blocker. `-f` moves it
|
||||
anyway, beside the backward and skipping moves it already allows. The other two kinds are
|
||||
reference data and never refuse anything.
|
||||
is not in `done` or `discarded`, whichever move it is, and names every open blocker. `-f`
|
||||
moves it anyway, beside the backward and skipping moves it already allows. It is enforced
|
||||
from the other end too: discarding a ticket that open tickets are blocked by is refused,
|
||||
naming them. The other two kinds are reference data and never refuse anything.
|
||||
|
||||
Recording a relation the ticket already holds reports no change. A ticket cannot relate
|
||||
to itself, and a target that later disappears shows as `_missing_` rather than silently
|
||||
@@ -187,15 +221,15 @@ going away.
|
||||
`show` marks each row twice, kind then status. The kind is `×` for `blocked by` and
|
||||
`blocks`, `→` for `relates to`, `←` for `regression of` and `regressed by`; both
|
||||
directions of one kind carry one mark, and the label is what says which end you are on.
|
||||
The status is the target's own: `○` backlog, `◐` committed or reviewing, `●` done, and
|
||||
`?` for a target the board no longer holds. So `blocked by × ● (1b78a24)` is a blocker
|
||||
The status is the target's own: `○` backlog, `◐` committed or reviewing, `●` done or
|
||||
discarded, and `?` for a target the board no longer holds. So `blocked by × ● (1b78a24)` is a blocker
|
||||
that is finished and `blocked by × ○ (1b78a24)` is one nobody has started. The board
|
||||
draws the same block.
|
||||
|
||||
Colour is what tells committed from reviewing, since both are `◐`, and **your output is a
|
||||
pipe, so you do not get the colour**. Read `◐` as under way, and if it matters which
|
||||
stage, `worklane show` on that target says so in its Status field. `●` and `○` are
|
||||
unambiguous without it, which are the two answers usually being asked for.
|
||||
Colour is what tells committed from reviewing apart, and done from discarded, since each
|
||||
pair shares a glyph, and **your output is a pipe, so you do not get the colour**. Read
|
||||
`◐` as under way and `●` as nothing left to do, and if it matters which of the two,
|
||||
`worklane show` on that target says so in its Status field. `○` is unambiguous without it.
|
||||
|
||||
## Campaigns
|
||||
|
||||
@@ -211,7 +245,8 @@ worklane campaign add --title "First public release" --codename v1 \
|
||||
worklane campaign ls # every campaign, its codename, how far it has got
|
||||
worklane campaign ls --ids # id and title, tab separated, like ls --ids
|
||||
worklane campaign show v1 # its body, then its members by status
|
||||
worklane campaign set v1 --title "..." # replace the title or the codename
|
||||
worklane campaign set v1 --title "..." # replace the title, description or codename
|
||||
worklane campaign append v1 -d "..." # add a paragraph to the description
|
||||
worklane assign v1 1b78a24 # put a ticket in it
|
||||
worklane ls --campaign v1 # only that campaign's tickets
|
||||
```
|
||||
@@ -226,9 +261,16 @@ existed needs. **Replacing a codename it already has needs `--force`**: that wor
|
||||
the campaign is referred to on the board and at the command line, so changing it is a
|
||||
decision rather than a correction. Setting the one it already has is a no-op either way.
|
||||
|
||||
`campaign set` is the only way to change a campaign after it is filed, and it reaches the
|
||||
title and the codename only. There is no way to edit a campaign's description or its owner
|
||||
yet.
|
||||
`campaign set` and `campaign append` are the only ways to change a campaign after it is
|
||||
filed. `set` replaces the title, the description or the codename; `append` adds a paragraph
|
||||
to the description, which is what to use when the description is right and only incomplete,
|
||||
since replacing prose to add a sentence to it is how the rest of it gets lost. An empty
|
||||
`--description ""` between two values is a paragraph break, exactly as it is for a ticket,
|
||||
and a call whose every value is blank is refused: a campaign's description cannot be
|
||||
emptied. There is still no way to change a campaign's owner.
|
||||
|
||||
`append` here is `campaign append` and not the top-level `append`, which takes a ticket. The
|
||||
two objects are addressed the same way, so the command is what says which one is meant.
|
||||
|
||||
`assign` takes the **campaign first and the ticket second**, like `chown`, and is the
|
||||
only writer of the field. `add` has no `--campaign` and neither has `set`, so membership
|
||||
@@ -262,6 +304,62 @@ existing ticket will have been written from a different angle.
|
||||
- Related but not the same: file it, and record it with `relate <new> --relates-to <old>`
|
||||
rather than only mentioning the id in prose.
|
||||
|
||||
## What the board records about your work
|
||||
|
||||
`show` ends with a HISTORY block: every comment on the ticket and every change to its
|
||||
status, owner, tags or campaign, oldest first, each naming who made it. You do not write
|
||||
these by hand. `mv`, `chown`, `set --tags` and `assign` record themselves, and a call
|
||||
that changes nothing records nothing. A campaign move is recorded by codename, or by
|
||||
title for a campaign that has none, not by the uuid the field holds.
|
||||
|
||||
```
|
||||
HISTORY
|
||||
────────────────────
|
||||
|
||||
status backlog → committed claude (2026-08-24 12:45:00)
|
||||
|
||||
From claude (2026-08-24 13:10:22)
|
||||
The offset was never passed to the widget.
|
||||
|
||||
owner _Not set_ → Ansho Rei claude (2026-08-24 13:11:04)
|
||||
|
||||
campaign _Not set_ → v1 claude (2026-08-24 13:12:30)
|
||||
```
|
||||
|
||||
Nothing else is logged: ticking a criterion, and editing the title, description, plan,
|
||||
priority or due date, leave no entry. **When one of those matters, say so in a comment.**
|
||||
An implementation plan rewritten because the first one was wrong is worth a sentence; the
|
||||
edit itself is not recorded and nobody can reconstruct why from the file.
|
||||
|
||||
Read the block before picking a ticket up: it says whether somebody has already had it in
|
||||
`committed` and sent it back, which the current status alone does not.
|
||||
|
||||
## Who your entries are attributed to
|
||||
|
||||
Every comment carries an author, and by default that is the git user of the machine you
|
||||
are running on, which is the human whose checkout it is and not you. Set
|
||||
`WORKLANE_ACTOR` in your own environment and it becomes the author of every entry you
|
||||
write, so a board several agents write to says which of them said what:
|
||||
|
||||
```
|
||||
WORKLANE_ACTOR=claude worklane comment 1b78a24 "The offset was never passed to the widget."
|
||||
```
|
||||
|
||||
Set it once where your session's environment is configured, not on each call: `env` in
|
||||
`~/.claude/settings.json` for Claude Code, and the environment opencode is started with
|
||||
for opencode, since it passes its own environment to the tools it runs. `--actor`
|
||||
overrides it for one call and is spelled the same on every command that writes an entry,
|
||||
`comment`, `mv`, `chown`, `set` and `assign`. An empty value counts as unset and falls
|
||||
back to the
|
||||
git user, and with nothing at all the author is `unknown`. It is free text, checked
|
||||
against nothing: name yourself something a person reading the board will recognise.
|
||||
|
||||
On `chown`, `--actor` is not the user argument: `worklane chown alice 1b78a24` makes alice
|
||||
the ticket's owner, and `--actor` says who made that change.
|
||||
|
||||
If the variable is not set and you cannot set it, pass `--actor` rather than letting the
|
||||
comment claim to be the user's.
|
||||
|
||||
## Shell completions
|
||||
|
||||
```
|
||||
@@ -292,8 +390,8 @@ the candidates and exits 1 rather than guessing.
|
||||
`--print is supported` is stored, not parsed as a flag. The cost is that a genuinely
|
||||
mistyped flag there lands as content instead of failing, so read back what you wrote
|
||||
with `worklane show`.
|
||||
- `--due`, `--priority`, `--tags`, `--owner` and `--status` do *not* accept one, so a
|
||||
mistyped flag on those is a usage error and nothing is written.
|
||||
- `--due`, `--priority`, `--tags`, `--owner`, `--actor` and `--status` do *not* accept one,
|
||||
so a mistyped flag on those is a usage error and nothing is written.
|
||||
- A ticket argument that starts with a hyphen needs the flags first and a separator:
|
||||
`worklane mv --status committed -- -leading-title`.
|
||||
- A comment body of exactly `--` needs its own separator:
|
||||
@@ -301,4 +399,7 @@ the candidates and exits 1 rather than guessing.
|
||||
- An empty value for a scalar is a usage error, not a way to clear the field: use
|
||||
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
|
||||
the section either, and an all-blank one is refused with the `--clear` for it named.
|
||||
- **`comment` has no `--owner`.** Owner is the ticket's assignee, which `chown` writes;
|
||||
the author of a comment is `--actor` or `WORKLANE_ACTOR`. The old spelling is a usage
|
||||
error, not an alias.
|
||||
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
|
||||
|
||||
+26
-6
@@ -187,7 +187,7 @@ export const ls = tool({
|
||||
|
||||
export const show = tool({
|
||||
description:
|
||||
"Show a complete ticket by UUID or title. Displays title, description, acceptance criteria, implementation plan, metadata, and comments.",
|
||||
"Show a complete ticket by UUID or title. Displays title, description, acceptance criteria, implementation plan, metadata, and the history: every comment on it and every change to its status, owner or tags.",
|
||||
args: {
|
||||
id: tool.schema
|
||||
.string()
|
||||
@@ -219,6 +219,10 @@ export const mv = tool({
|
||||
.boolean()
|
||||
.describe("Force move (allows non-sequential moves like done -> backlog). Use with caution.")
|
||||
.optional(),
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
if (!args.ticket) {
|
||||
@@ -229,6 +233,7 @@ export const mv = tool({
|
||||
}
|
||||
const cmd: string[] = ["mv", args.ticket, "--status", args.status];
|
||||
if (args.force) cmd.push("--force");
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
try {
|
||||
return await run(cmd, context);
|
||||
@@ -247,9 +252,9 @@ export const comment = tool({
|
||||
body: tool.schema
|
||||
.string()
|
||||
.describe("Comment body text (required). Supports markdown formatting and multiple paragraphs separated by newlines."),
|
||||
owner: tool.schema
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Comment author. If omitted, defaults to the git user.")
|
||||
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
@@ -261,7 +266,7 @@ export const comment = tool({
|
||||
}
|
||||
|
||||
const cmd: string[] = ["comment", args.ticket, args.body];
|
||||
if (args.owner) cmd.push("--owner", args.owner);
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
try {
|
||||
return await run(cmd, context);
|
||||
@@ -306,6 +311,10 @@ export const set = tool({
|
||||
.string()
|
||||
.describe("New priority level, 1 (most urgent) to 5 (least)")
|
||||
.optional(),
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Who the entry is attributed to. Only reaches the entry tags writes, since that is the one field of this command's that is logged. If omitted, WORKLANE_ACTOR is used, then the git user.")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
if (!args.ticket) {
|
||||
@@ -330,8 +339,12 @@ export const set = tool({
|
||||
if (args.tags) cmd.push("--tags", args.tags);
|
||||
if (args.due) cmd.push("--due", args.due);
|
||||
if (args.priority) cmd.push("--priority", String(args.priority));
|
||||
// Last, and not counted as a field: the length check below is what refuses a call
|
||||
// that names nothing to change, and an actor alone changes nothing.
|
||||
const fields = cmd.length;
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
if (cmd.length === 2) {
|
||||
if (fields === 2) {
|
||||
return "Error setting fields: give at least one field to change";
|
||||
}
|
||||
|
||||
@@ -405,6 +418,10 @@ export const chown = tool({
|
||||
ticket: tool.schema
|
||||
.string()
|
||||
.describe("Ticket UUID prefix (4+ chars) or title substring (required)"),
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Who the entry is attributed to, which on this command is not the same as user: user becomes the ticket's owner, actor is who made the change. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\".")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
if (!args.user) {
|
||||
@@ -414,8 +431,11 @@ export const chown = tool({
|
||||
return "Error changing owner: ticket is required";
|
||||
}
|
||||
|
||||
const cmd: string[] = ["chown", args.user, args.ticket];
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
try {
|
||||
return await run(["chown", args.user, args.ticket], context);
|
||||
return await run(cmd, context);
|
||||
} catch (err: any) {
|
||||
return `Error changing owner: ${err.message}`;
|
||||
}
|
||||
|
||||
+31
-8
@@ -50,6 +50,21 @@ pub struct Campaign {
|
||||
pub content: String,
|
||||
}
|
||||
|
||||
impl Campaign {
|
||||
/// The name a reader knows the campaign by: the codename, or the title for a
|
||||
/// campaign filed without one.
|
||||
///
|
||||
/// What the history log records for a campaign move. The field holds a uuid, which
|
||||
/// says nothing in a log line, and resolving at read time would let an entry change
|
||||
/// meaning when a campaign is renamed, so the name is settled when the entry is
|
||||
/// written. The codename over the title because it is the word the board and the
|
||||
/// command line already use for the campaign, and a log row holds two of these
|
||||
/// around an arrow.
|
||||
pub fn name(&self) -> &str {
|
||||
self.codename.as_deref().unwrap_or(&self.title)
|
||||
}
|
||||
}
|
||||
|
||||
/// The campaigns directory as [`resolve_in`] takes it.
|
||||
///
|
||||
/// The name is empty because a campaign has no status: it is what makes the ambiguity
|
||||
@@ -173,30 +188,30 @@ 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)?),
|
||||
})
|
||||
}
|
||||
|
||||
/// The members of a campaign, grouped by status in flow order.
|
||||
/// The members of a campaign, grouped by status in flow order, discarded last.
|
||||
///
|
||||
/// Read through `collect_ticket_items`, the source `ls` and the board already use, so
|
||||
/// there is no second parser and the rows print the way every other listing does.
|
||||
/// Empty groups are kept: a campaign's shape is the four statuses, and a caller that
|
||||
/// Empty groups are kept: a campaign's shape is the statuses, and a caller that
|
||||
/// wants only the filled ones can say so.
|
||||
pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec<TicketItem>)>> {
|
||||
let mut grouped = Vec::new();
|
||||
@@ -224,6 +239,10 @@ pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec
|
||||
}
|
||||
|
||||
/// How far a campaign has got: members done against members held.
|
||||
///
|
||||
/// `Copy` because the board carries one on every `CampaignRow`, settled at reload: two
|
||||
/// counters are cheaper to copy than to reach back through a reference for.
|
||||
#[derive(Clone, Copy, Debug, Default)]
|
||||
pub struct Standing {
|
||||
pub done: usize,
|
||||
pub total: usize,
|
||||
@@ -232,9 +251,13 @@ pub struct Standing {
|
||||
impl Standing {
|
||||
pub fn of(grouped: &[(&'static str, Vec<TicketItem>)]) -> Self {
|
||||
Self {
|
||||
// Discarded counts as finished: the work was decided out of the campaign,
|
||||
// not left in it, and one abandoned ticket must not hold a campaign open
|
||||
// forever. The same predicate `mv` gates on, so "nothing outstanding" means
|
||||
// one thing across the tool.
|
||||
done: grouped
|
||||
.iter()
|
||||
.filter(|(status, _)| *status == DONE)
|
||||
.filter(|(status, _)| !is_open(status))
|
||||
.map(|(_, items)| items.len())
|
||||
.sum(),
|
||||
total: grouped.iter().map(|(_, items)| items.len()).sum(),
|
||||
|
||||
+287
-22
@@ -130,6 +130,62 @@ fn codename(raw: &str) -> Result<String, String> {
|
||||
Ok(value)
|
||||
}
|
||||
|
||||
/// Reject a tag value that `ls --tag` could never match.
|
||||
///
|
||||
/// `--tag` matches a whole value of the comma-separated Tags field, so a value carrying a
|
||||
/// comma is two tags and would be declared under a name nothing can be filtered by. A line
|
||||
/// break is refused for the file's sake rather than the filter's: a tag is a heading in
|
||||
/// `tags.md`, and a heading is one line.
|
||||
///
|
||||
/// Trimmed rather than refused for surrounding space, because `parse_tags` trims every
|
||||
/// value it reads off a ticket and [`TagIndex::parse`] trims every heading it reads off the
|
||||
/// vocabulary. Refusing here would refuse a value that both of those accept.
|
||||
///
|
||||
/// [`TagIndex::parse`]: crate::tag::TagIndex::parse
|
||||
fn tag_value(raw: &str) -> Result<String, String> {
|
||||
let value = raw.trim();
|
||||
|
||||
if value.is_empty() {
|
||||
return Err("tag cannot be empty".to_string());
|
||||
}
|
||||
|
||||
if value.contains(',') {
|
||||
return Err(
|
||||
"tag cannot contain a comma, which is what separates one tag from the next".to_string()
|
||||
);
|
||||
}
|
||||
|
||||
if value.contains(['\n', '\r']) {
|
||||
return Err("tag must be a single line".to_string());
|
||||
}
|
||||
|
||||
Ok(value.to_string())
|
||||
}
|
||||
|
||||
/// Reject an annotation line that would be read back as a tag of its own.
|
||||
///
|
||||
/// The vocabulary is one heading per tag with its prose under it, so a line of prose
|
||||
/// starting with the section marker would split the annotation and declare whatever
|
||||
/// followed. Refused at parse time, where nothing has been written, rather than escaped on
|
||||
/// the way in: an annotation is prose, and quietly rewriting prose is worse than asking for
|
||||
/// a different line.
|
||||
fn annotation_line(raw: &str) -> Result<String, String> {
|
||||
match raw.lines().any(|line| line.starts_with(crate::tag::SECTION)) {
|
||||
true => Err(format!(
|
||||
"an annotation line cannot start with '{}', which is how the vocabulary file \
|
||||
starts a tag",
|
||||
crate::tag::SECTION
|
||||
)),
|
||||
false => Ok(raw.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
/// What `--actor` says on every command that writes a history entry.
|
||||
///
|
||||
/// One string, so the five spell it the same: a flag documented differently on each
|
||||
/// command reads as five flags.
|
||||
const ACTOR_HELP: &str = "Who the entry is attributed to, overriding WORKLANE_ACTOR and the git user. Free text, checked against nothing";
|
||||
|
||||
/// Arguments that carry prose, and therefore have to accept a value starting with
|
||||
/// a hyphen.
|
||||
///
|
||||
@@ -171,6 +227,14 @@ pub enum Command {
|
||||
/// Force move (allows backward or non-sequential moves)
|
||||
#[arg(short, long)]
|
||||
force: bool,
|
||||
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
actor: Option<String>,
|
||||
|
||||
/// Why the ticket moved, recorded in the history entry beside the transition
|
||||
/// it explains. Prose, so it takes a leading hyphen
|
||||
#[arg(long, allow_hyphen_values = PROSE)]
|
||||
reason: Option<String>,
|
||||
},
|
||||
|
||||
/// Replace fields on an existing ticket
|
||||
@@ -217,9 +281,10 @@ pub enum Command {
|
||||
#[arg(allow_hyphen_values = PROSE)]
|
||||
body: String,
|
||||
|
||||
/// Owner
|
||||
#[arg(short, long)]
|
||||
owner: Option<String>,
|
||||
/// Named after the writer of the entry, not after the ticket's assignee, which
|
||||
/// is `chown`'s. It was `--owner`, which said the wrong one of the two.
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
actor: Option<String>,
|
||||
},
|
||||
|
||||
/// Group tickets that have to be finished together
|
||||
@@ -242,17 +307,23 @@ pub enum Command {
|
||||
|
||||
/// Ticket UUID or title
|
||||
ticket: String,
|
||||
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
actor: Option<String>,
|
||||
},
|
||||
|
||||
/// List the tags the board carries, and how many tickets carry each
|
||||
/// The tag vocabulary: what the board carries, and what each tag means
|
||||
///
|
||||
/// A command rather than a mode on `ls`, for two reasons. `ls --tag <tag>` answers
|
||||
/// "what is tagged bug" and cannot answer "what tags exist", which is the question a
|
||||
/// grooming sweep starts from; and a `--tags` beside a `--tag` is one letter away from
|
||||
/// a filter that means something else.
|
||||
///
|
||||
/// The output is machine-readable, like `ls --ids`: the tag, a tab, the count.
|
||||
Tags,
|
||||
/// The listing is machine-readable, like `ls --ids`: the tag, a tab, the count.
|
||||
Tags {
|
||||
#[command(subcommand)]
|
||||
command: Option<TagCommand>,
|
||||
},
|
||||
|
||||
/// Print a shell completion script
|
||||
///
|
||||
@@ -305,10 +376,18 @@ pub enum Command {
|
||||
/// No `mv`: a campaign has no status to move it to, its state is derived from its
|
||||
/// members.
|
||||
///
|
||||
/// No `append`, and therefore no `set --description`: `set` and `append` are a pair for a
|
||||
/// prose section, and a way to replace a description with no way to add a paragraph to one
|
||||
/// is half of it. That pair is its own ticket. `set` here carries the two scalars, which
|
||||
/// have no append form at all, the same line `append` already draws for a ticket.
|
||||
/// `set` and `append` arrive together, 32e98ab, because for a prose section they are a
|
||||
/// pair: a way to replace a description with no way to add a paragraph to one is the half
|
||||
/// that is easy to reach for and wrong, since replacing a description to add a sentence is
|
||||
/// how the rest of it gets lost. The two scalars have no append form at all, which is the
|
||||
/// same line `append` already draws for a ticket.
|
||||
///
|
||||
/// **`append` is a campaign's own subcommand and not the top-level `append`.** That one
|
||||
/// resolves a ticket, and its positional would then name either object: `resolve_in`'s tiers
|
||||
/// are the same over both directories, so a search can resolve in each and nothing but a
|
||||
/// flag could say which was meant. It would also make a liar of `resolve_ticket`, which
|
||||
/// explains a ticket search that names a campaign. Under `campaign` the object is settled by
|
||||
/// the command, the way it is for `set`, `show` and `ls`.
|
||||
#[derive(clap::Subcommand)]
|
||||
pub enum CampaignCommand {
|
||||
/// File a new campaign
|
||||
@@ -316,11 +395,19 @@ pub enum CampaignCommand {
|
||||
|
||||
/// Replace fields on an existing campaign
|
||||
///
|
||||
/// The only way to change a campaign after it is filed. `campaign add --codename` writes
|
||||
/// the field at creation the way `add --title` does for a ticket; this is what replaces
|
||||
/// it, so every campaign filed before the field existed can still be given one.
|
||||
/// The only way to change a campaign's title or codename after it is filed.
|
||||
/// `campaign add --codename` writes the field at creation the way `add --title` does for
|
||||
/// a ticket; this is what replaces it, so every campaign filed before the field existed
|
||||
/// can still be given one.
|
||||
Set(CampaignSetArgs),
|
||||
|
||||
/// Add a paragraph to a campaign's description
|
||||
///
|
||||
/// The other half of `campaign set --description`, and the half that keeps what is
|
||||
/// already written: a description is the sentence a whole campaign's members are filed
|
||||
/// against, so adding a line to it must not mean retyping it.
|
||||
Append(CampaignAppendArgs),
|
||||
|
||||
/// List campaigns with their member counts
|
||||
Ls {
|
||||
/// Print one campaign per line as its id and title, tab separated, for a script
|
||||
@@ -341,25 +428,30 @@ pub enum CampaignCommand {
|
||||
},
|
||||
}
|
||||
|
||||
/// What can be replaced on a campaign that is already filed: its title and its codename.
|
||||
///
|
||||
/// The two scalars, and deliberately not the description. See [`CampaignCommand`].
|
||||
/// What can be replaced on a campaign that is already filed: everything it holds but its
|
||||
/// owner.
|
||||
///
|
||||
/// No `--owner`: nothing writes a campaign's Owner today, and giving `set` one would settle
|
||||
/// by accident whether `chown` grows a campaign or `set` keeps the field, which is the
|
||||
/// one-field-one-writer question and not this command's to answer.
|
||||
///
|
||||
/// No `--clear`: nothing has asked to empty a codename, a wrong one is replaced rather than
|
||||
/// emptied, and the vocabulary is a real question — `Clearable` is `SetArgs`'s and its
|
||||
/// variants are a ticket's fields, so reusing it here would put a ticket's enum on a
|
||||
/// campaign and inventing a second one is a decision worth making on purpose.
|
||||
/// No `--clear`, which is 32e98ab's decision and not a deferral. A codename is replaced
|
||||
/// rather than emptied, and a campaign's one prose section has no cleared form worth
|
||||
/// reaching: emptying the description of a container six tickets are filed against is not a
|
||||
/// thing anybody has asked for, and the only ways to spell it would be to put [`Clearable`]
|
||||
/// on a campaign, whose variants are a ticket's fields, or to invent a second enum with one
|
||||
/// variant in it. So an empty `--description ""` stays a paragraph break here exactly as it
|
||||
/// is everywhere else, and the refusal for an all-blank value says there is nowhere to go
|
||||
/// back to rather than naming a flag that does not exist.
|
||||
///
|
||||
/// `--force` guards the codename and nothing else. A campaign that already has one is
|
||||
/// referred to by it: it is on every card in the campaign, it is what resolves it at the
|
||||
/// command line, and it is very likely in somebody's shell history. Replacing that silently
|
||||
/// is the same mistake overwriting an edited skill document would be, which is what
|
||||
/// `install-skill --force` exists for. A title needs no guard, since a campaign always has
|
||||
/// one and replacing it is the whole point of the flag.
|
||||
/// one and replacing it is the whole point of the flag. Neither does a description: it is
|
||||
/// prose written to be revised, the same reason `tags set --annotation` has no guard, and a
|
||||
/// guard in front of the command's whole purpose is worse than no command.
|
||||
///
|
||||
/// The group makes at least one field mandatory, so a bare `worklane campaign set <c>` is a
|
||||
/// usage error rather than a silent no-op, exactly as it is for [`SetArgs`].
|
||||
@@ -368,7 +460,7 @@ pub enum CampaignCommand {
|
||||
clap::ArgGroup::new("campaign_set_fields")
|
||||
.required(true)
|
||||
.multiple(true)
|
||||
.args(["title", "codename"])
|
||||
.args(["title", "description", "codename"])
|
||||
))]
|
||||
pub struct CampaignSetArgs {
|
||||
/// Campaign UUID, title, filename or codename
|
||||
@@ -378,6 +470,13 @@ pub struct CampaignSetArgs {
|
||||
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)]
|
||||
pub title: Option<String>,
|
||||
|
||||
/// Replace the description. Repeat the flag for more lines, empty for a paragraph break
|
||||
///
|
||||
/// The whole section, so a paragraph added to it is `campaign append --description`
|
||||
/// rather than the description retyped
|
||||
#[arg(short, long, allow_hyphen_values = PROSE)]
|
||||
pub description: Vec<String>,
|
||||
|
||||
/// Replace the codename, a single word to call the campaign by
|
||||
///
|
||||
/// The same parser `campaign add --codename` takes, so a codename is one thing however
|
||||
@@ -396,6 +495,25 @@ pub struct CampaignSetArgs {
|
||||
pub force: bool,
|
||||
}
|
||||
|
||||
/// What can be added to a campaign that is already filed: a paragraph of its description.
|
||||
///
|
||||
/// One field, so it is `required` rather than a group of one, which is the longer way to say
|
||||
/// the same thing and the shape [`TagSetArgs`] already takes. A bare
|
||||
/// `worklane campaign append <c>` is therefore a usage error rather than a silent no-op.
|
||||
///
|
||||
/// No `--title` and no `--codename`, because appending to a scalar has no meaning. That is
|
||||
/// the line `append` already draws for a ticket, where the title is absent for the same
|
||||
/// reason.
|
||||
#[derive(clap::Args)]
|
||||
pub struct CampaignAppendArgs {
|
||||
/// Campaign UUID, title, filename or codename
|
||||
pub campaign: String,
|
||||
|
||||
/// Add a paragraph to the description. Repeat the flag for more lines within it
|
||||
#[arg(short, long, required = true, allow_hyphen_values = PROSE)]
|
||||
pub description: Vec<String>,
|
||||
}
|
||||
|
||||
/// What a campaign holds: a title, a description and an owner.
|
||||
///
|
||||
/// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a
|
||||
@@ -429,6 +547,78 @@ pub struct CampaignAddArgs {
|
||||
pub owner: Option<String>,
|
||||
}
|
||||
|
||||
/// What the tag vocabulary can be asked for.
|
||||
///
|
||||
/// Optional, unlike [`CampaignCommand`], and that is the whole shape of the compatibility
|
||||
/// here: `worklane tags` was the listing before it was a group, the shipped fish completion
|
||||
/// calls it that way to fill in `ls --tag`, and a bare call turning into a usage error would
|
||||
/// break a script for the sake of symmetry. So the bare form stays the listing, and `tags
|
||||
/// ls` is the same thing spelled the way `campaign ls` is.
|
||||
///
|
||||
#[derive(clap::Subcommand)]
|
||||
pub enum TagCommand {
|
||||
/// Declare a tag, and what it means
|
||||
Add(TagAddArgs),
|
||||
|
||||
/// Replace what a declared tag means
|
||||
Set(TagSetArgs),
|
||||
|
||||
/// List the tags the board carries, and how many tickets carry each
|
||||
Ls,
|
||||
}
|
||||
|
||||
/// What declaring a tag takes: the tag, and what it is for.
|
||||
///
|
||||
/// No owner and no timestamp, which every other file under `.worklane/` carries. A tag is
|
||||
/// not an object with a history, it is a word the board agrees on, and `git log` over
|
||||
/// `tags.md` answers who wrote which line better than a field would.
|
||||
#[derive(clap::Args)]
|
||||
pub struct TagAddArgs {
|
||||
/// The tag to declare, spelled the way `ls --tag` matches it
|
||||
#[arg(value_parser = tag_value)]
|
||||
pub tag: String,
|
||||
|
||||
/// What the tag means and when it is appropriate. Use multiple flags for multiline
|
||||
/// annotations
|
||||
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = annotation_line)]
|
||||
pub annotation: Vec<String>,
|
||||
}
|
||||
|
||||
/// What can be replaced on a tag that is already declared: what it means, and nothing else.
|
||||
///
|
||||
/// No `--force`, unlike [`CampaignSetArgs`]. A codename is guarded because once a campaign
|
||||
/// has one it is how the campaign is addressed, on every card and at every command line, so
|
||||
/// replacing it silently breaks the way it is referred to. An annotation is prose written to
|
||||
/// be revised and nothing addresses anything by it, so a guard would stand in front of the
|
||||
/// command's whole purpose.
|
||||
///
|
||||
/// No rename. The tag *is* the key, so changing it means rewriting the Tags field of every
|
||||
/// ticket carrying it. That is a migration, not a flag on `set`.
|
||||
///
|
||||
/// No `--clear`. An annotation is emptied with `--annotation ""`, which writes the same
|
||||
/// placeholder a tag declared without one gets, so a second spelling would add nothing.
|
||||
/// [`Clearable`] is a ticket's fields anyway, per [`SetArgs`].
|
||||
///
|
||||
/// `--annotation` is required, so a bare `worklane tags set <tag>` is a usage error rather
|
||||
/// than a silent no-op, exactly as the group on [`CampaignSetArgs`] makes it for a campaign.
|
||||
#[derive(clap::Args)]
|
||||
pub struct TagSetArgs {
|
||||
/// The tag to change, spelled the way it is declared
|
||||
#[arg(value_parser = tag_value)]
|
||||
pub tag: String,
|
||||
|
||||
/// What the tag means and when it is appropriate, replacing whatever it said before. Use
|
||||
/// multiple flags for multiline annotations
|
||||
#[arg(
|
||||
short,
|
||||
long,
|
||||
required = true,
|
||||
allow_hyphen_values = PROSE,
|
||||
value_parser = annotation_line
|
||||
)]
|
||||
pub annotation: Vec<String>,
|
||||
}
|
||||
|
||||
/// `ls` holds four filters, an output mode and nothing else, which is the boundary the
|
||||
/// Rust Style rule in AGENTS.md names: two of the filters are adjacent `Option<String>`
|
||||
/// values that a caller can swap silently, so the mode that joined them came as a
|
||||
@@ -556,6 +746,11 @@ pub struct SetArgs {
|
||||
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
|
||||
#[arg(long, value_name = "FIELD")]
|
||||
pub clear: Vec<Clearable>,
|
||||
|
||||
/// Only reaches the entry `--tags` writes, since that is the one field of this
|
||||
/// command's that is logged
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
pub actor: Option<String>,
|
||||
}
|
||||
|
||||
impl SetArgs {
|
||||
@@ -601,6 +796,11 @@ pub struct ChownArgs {
|
||||
/// user to name
|
||||
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
|
||||
pub clear: Option<String>,
|
||||
|
||||
/// Not the same as `user`, which is the ticket's new assignee: this is who made the
|
||||
/// change. Both are on this command because it writes both.
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
pub actor: Option<String>,
|
||||
}
|
||||
|
||||
impl ChownArgs {
|
||||
@@ -709,3 +909,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."
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
+101
-17
@@ -50,11 +50,16 @@ pub const CAMPAIGN_COMMANDS: [&str; 1] = ["assign"];
|
||||
|
||||
/// Nested subcommands whose first argument is a campaign, as `parent child`.
|
||||
///
|
||||
/// `campaign show` and `campaign set`, and they are why the fish half needs a third
|
||||
/// position helper: their argument is the *third* token, where `__worklane_first_arg_of`
|
||||
/// reads the second and `__worklane_second_arg_of` counts a top-level command's arguments.
|
||||
/// Neither can tell `campaign show <TAB>` from `chown alice <TAB>` by position.
|
||||
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 2] = [("campaign", "show"), ("campaign", "set")];
|
||||
/// `campaign show`, `campaign set` and `campaign append`, and they are why the fish half
|
||||
/// needs a third position helper: their argument is the *third* token, where
|
||||
/// `__worklane_first_arg_of` reads the second and `__worklane_second_arg_of` counts a
|
||||
/// top-level command's arguments. Neither can tell `campaign show <TAB>` from
|
||||
/// `chown alice <TAB>` by position.
|
||||
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 3] = [
|
||||
("campaign", "show"),
|
||||
("campaign", "set"),
|
||||
("campaign", "append"),
|
||||
];
|
||||
|
||||
/// Options whose value is a campaign.
|
||||
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
|
||||
@@ -66,6 +71,15 @@ pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
|
||||
/// one where `ls --ids` answers the tickets.
|
||||
pub const TAG_FLAGS: [&str; 1] = ["tag"];
|
||||
|
||||
/// Nested commands whose first argument is a tag the board already has.
|
||||
///
|
||||
/// `tags set` changes what a declared tag means, so the values it takes are exactly the
|
||||
/// ones `worklane tags` prints. `tags add` is deliberately absent: the tag it takes is one
|
||||
/// the board does not have yet, so offering the ones it does would offer exactly the values
|
||||
/// it refuses. Which of the two a new tag positional belongs to is what
|
||||
/// `no_tag_taking_option_is_missing` makes somebody decide.
|
||||
pub const TAG_NESTED_COMMANDS: [(&str, &str); 1] = [("tags", "set")];
|
||||
|
||||
pub fn generate(shell: Shell, out: &mut dyn io::Write) -> io::Result<()> {
|
||||
let mut command = crate::command::Cli::command();
|
||||
clap_complete::generate(shell, &mut command, "worklane", out);
|
||||
@@ -92,6 +106,11 @@ fn fish_dynamic() -> String {
|
||||
.join("; or ");
|
||||
let campaign_flags = flag_list(&CAMPAIGN_FLAGS);
|
||||
let tag_flags = flag_list(&TAG_FLAGS);
|
||||
let tag_nested = TAG_NESTED_COMMANDS
|
||||
.iter()
|
||||
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("; or ");
|
||||
let statuses = possible_values(Status::value_variants());
|
||||
let shells = possible_values(Shell::value_variants());
|
||||
let skills = SKILLS
|
||||
@@ -178,9 +197,21 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \
|
||||
-x -a '(worklane campaign ls --ids)'
|
||||
|
||||
# Tags come from `worklane tags` rather than from a listing of objects, since a tag has no
|
||||
# id. The count after the tab lands as fish's description, which is what makes the list
|
||||
# worth reading: it says which spelling the board actually uses.
|
||||
complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -a '(worklane tags)'
|
||||
# id. Three fields now, the tag, its count and its annotation, and fish takes everything
|
||||
# after the *first* tab as one description, so the count is dropped here rather than landing
|
||||
# in the middle of the prose. `cut` and not `string replace` because the columns are what is
|
||||
# being picked, and `cut -f1` is how a script reads this listing anyway.
|
||||
#
|
||||
# What is left is the annotation, and a tag the board carries but has never declared has
|
||||
# none: it is offered with no description at all, which is the near-duplicate the file was
|
||||
# added to catch. The count used to be the description and said the same thing more weakly.
|
||||
complete -c worklane -n '__worklane_command_is ls' {tag_flags} \
|
||||
-x -a '(worklane tags | cut -f1,3)'
|
||||
|
||||
# And `tags set` names one that is already declared, so it reads the same listing. `tags
|
||||
# add` has no rule on purpose: it takes a tag the board does not have, so the candidates
|
||||
# here are the values it refuses.
|
||||
complete -c worklane -n '{tag_nested}' -a '(worklane tags | cut -f1,3)'
|
||||
|
||||
# `chown --clear` names the ticket in the flag too, since with no user to give there is
|
||||
# no second positional to put it in. Scoped to `chown`, unlike the rule above: `set`
|
||||
@@ -348,9 +379,24 @@ mod tests {
|
||||
|
||||
// A guard on the walker itself: if it stopped finding arguments, every assertion
|
||||
// above would pass by never running.
|
||||
assert_eq!(seen, 4, "expected assign, campaign show, campaign set and ls --campaign");
|
||||
assert_eq!(
|
||||
seen, 5,
|
||||
"expected assign, campaign show, campaign set, campaign append and ls --campaign"
|
||||
);
|
||||
}
|
||||
|
||||
/// Commands whose tag positional names a tag that does not exist yet.
|
||||
///
|
||||
/// `tags add` declares a word the board has never carried, so completing it from
|
||||
/// `worklane tags` would offer exactly the values the command refuses. Recorded rather
|
||||
/// than skipped, so the *next* tag positional has to say which it is: `tags set` takes
|
||||
/// a tag that is already declared and wants a rule in the fish block, and the test
|
||||
/// below fails until it gets one or lands here.
|
||||
///
|
||||
/// In the test module because nothing outside it reads the list; the rule it encodes is
|
||||
/// about what the fish block is missing, which is a test's question.
|
||||
const TAG_NEW_COMMANDS: [(&str, &str); 1] = [("tags", "add")];
|
||||
|
||||
/// Tags have their own list because their values come from `worklane tags` rather than
|
||||
/// from a listing of objects, so a second tag-taking option would need that rule and
|
||||
/// not the campaign one.
|
||||
@@ -363,19 +409,31 @@ mod tests {
|
||||
}
|
||||
seen += 1;
|
||||
let name = path.join(" ");
|
||||
let long = arg.get_long().unwrap_or_else(|| {
|
||||
panic!(
|
||||
"`worklane {name}` takes a tag as a positional, \
|
||||
which the fish block has no rule for"
|
||||
)
|
||||
});
|
||||
|
||||
let Some(long) = arg.get_long() else {
|
||||
let known = match path.as_slice() {
|
||||
[parent, child] => {
|
||||
let pair = (parent.as_str(), child.as_str());
|
||||
TAG_NESTED_COMMANDS.contains(&pair) || TAG_NEW_COMMANDS.contains(&pair)
|
||||
}
|
||||
_ => false,
|
||||
};
|
||||
assert!(
|
||||
known,
|
||||
"`worklane {name}` takes a tag as a positional, so it belongs in \
|
||||
TAG_NESTED_COMMANDS if the tag already exists and TAG_NEW_COMMANDS if it \
|
||||
does not"
|
||||
);
|
||||
continue;
|
||||
};
|
||||
|
||||
assert!(
|
||||
TAG_FLAGS.contains(&long),
|
||||
"`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS"
|
||||
);
|
||||
}
|
||||
|
||||
assert_eq!(seen, 1, "expected ls --tag");
|
||||
assert_eq!(seen, 3, "expected ls --tag, tags add and tags set");
|
||||
}
|
||||
|
||||
/// **Every rule naming an option has to say which command it belongs to.** A bare
|
||||
@@ -471,6 +529,32 @@ mod tests {
|
||||
assert!(script.contains("__worklane_first_arg_of assign"), "{script}");
|
||||
}
|
||||
|
||||
/// Every rule that reads the tag listing drops the count, because `worklane tags` prints
|
||||
/// three fields and fish takes everything after the first tab as the description. Left
|
||||
/// whole, a tag would be described as its count, a tab and its annotation.
|
||||
///
|
||||
/// Pinned per rule rather than once over the script: a rule added later that reads
|
||||
/// `worklane tags` raw is the bug this catches, and it would not show up in a single
|
||||
/// `contains`.
|
||||
#[test]
|
||||
fn every_tag_rule_takes_the_annotation_as_its_description() {
|
||||
let script = fish_dynamic();
|
||||
|
||||
let reading: Vec<&str> = script
|
||||
.lines()
|
||||
.filter(|line| line.contains("(worklane tags"))
|
||||
.collect();
|
||||
|
||||
assert_eq!(
|
||||
reading.len(),
|
||||
2,
|
||||
"expected the ls --tag rule and the tags set one: {reading:?}"
|
||||
);
|
||||
for line in reading {
|
||||
assert!(line.contains("(worklane tags | cut -f1,3)"), "{line}");
|
||||
}
|
||||
}
|
||||
|
||||
/// The one status positional and the one shell positional, which clap does not emit
|
||||
/// possible values for. Read off the enums, so a fifth status would appear here on
|
||||
/// its own.
|
||||
@@ -484,7 +568,7 @@ mod tests {
|
||||
status.as_str()
|
||||
);
|
||||
}
|
||||
assert!(script.contains("-a 'backlog committed reviewing done' -d status"));
|
||||
assert!(script.contains("-a 'backlog committed reviewing done discarded' -d status"));
|
||||
for shell in ["fish", "bash", "zsh", "elvish", "powershell"] {
|
||||
assert!(script.contains(shell), "the shell positional is never offered {shell}");
|
||||
}
|
||||
|
||||
+416
-186
@@ -7,10 +7,12 @@ use std::path::Path;
|
||||
|
||||
use crate::campaign::*;
|
||||
use crate::command::{
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs,
|
||||
RelateArgs, SetArgs,
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CampaignAppendArgs, CampaignSetArgs, CheckArgs,
|
||||
ChownArgs, LsArgs, RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
|
||||
};
|
||||
use crate::history::{Kind, change, format_history, read_history, write_entry};
|
||||
use crate::install;
|
||||
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
|
||||
use crate::util::*;
|
||||
|
||||
pub fn cmd_init(start: &Path) -> Result<()> {
|
||||
@@ -33,6 +35,13 @@ pub fn cmd_init(start: &Path) -> Result<()> {
|
||||
// campaigns, which is why `status_dirs()` is untouched.
|
||||
fs::create_dir_all(campaigns_dir(&worklane_dir))?;
|
||||
|
||||
// The tag vocabulary, beside both for the same reason, and written empty rather than
|
||||
// left for the first `tags add` to make. An empty file explains itself when it is
|
||||
// opened, which is the point of the preamble, and a board that has one from the start
|
||||
// has one file shape rather than two. `fs::write` and not `write_then_replace`: the
|
||||
// directory was made three lines ago, so there is nothing here to truncate.
|
||||
fs::write(tags_path(&worklane_dir), TagIndex::default().render())?;
|
||||
|
||||
println!("Initialized worklane in: {}", worklane_dir.display());
|
||||
Ok(())
|
||||
}
|
||||
@@ -104,11 +113,12 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
|
||||
println!(" [{}] {} {}", status.to_uppercase(), count, label);
|
||||
}
|
||||
|
||||
// Show all tickets except done grouped by status. Over `Status::ALL` rather
|
||||
// than the names, because each column is ordered by its own entry stamp and the
|
||||
// comparator is keyed on the status, not on the directory it was read from.
|
||||
// Show all tickets except the two terminal statuses, grouped by status. Over
|
||||
// `Status::ALL` rather than the names, because each column is ordered by its own
|
||||
// entry stamp and the comparator is keyed on the status, not on the directory it
|
||||
// was read from.
|
||||
for status in Status::ALL {
|
||||
if status.as_str() == DONE {
|
||||
if !is_open(status.as_str()) {
|
||||
continue;
|
||||
}
|
||||
let status_path = worklane_dir.join(status.as_str());
|
||||
@@ -343,99 +353,12 @@ pub fn cmd_add(args: &AddArgs, start: &Path) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Public for the TUI's detail view, which shows the same comments `show` does.
|
||||
pub fn read_comments(comments_dir: &Path) -> Result<Vec<(String, String, String, String)>> {
|
||||
if !comments_dir.exists() {
|
||||
return Ok(vec![]);
|
||||
}
|
||||
|
||||
let mut comments: Vec<(String, String, String, String)> = Vec::new();
|
||||
|
||||
for entry in fs::read_dir(comments_dir)? {
|
||||
let entry = entry?;
|
||||
let path = entry.path();
|
||||
if path.extension().is_some_and(|e| e == "md") {
|
||||
let content = fs::read_to_string(&path)?;
|
||||
let filename = path
|
||||
.file_stem()
|
||||
.map(|s| s.to_string_lossy().to_string())
|
||||
.unwrap_or_default();
|
||||
|
||||
let author = content
|
||||
.lines()
|
||||
.find(|l| l.starts_with("**Author**"))
|
||||
.and_then(|l| l.split_once("**Author**:"))
|
||||
.map(|(_, value)| value)
|
||||
.map(|s| s.trim().to_string())
|
||||
.unwrap_or_else(|| "unknown".to_string());
|
||||
|
||||
let time = content
|
||||
.lines()
|
||||
.find(|l| l.starts_with("**Time**"))
|
||||
.and_then(|l| l.split_once("**Time**:"))
|
||||
.map(|(_, value)| value)
|
||||
.map(|s| s.trim().to_string())
|
||||
.unwrap_or_else(|| "unknown".to_string());
|
||||
|
||||
let body = if let Some(after_comment) = content.strip_prefix("**Comment**\n") {
|
||||
if let Some(end) = after_comment.find("\n\n**Author**") {
|
||||
after_comment[..end].trim()
|
||||
} else {
|
||||
after_comment.trim()
|
||||
}
|
||||
} else {
|
||||
""
|
||||
};
|
||||
|
||||
comments.push((filename, author, time, body.to_string()));
|
||||
}
|
||||
}
|
||||
|
||||
comments.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
|
||||
Ok(comments)
|
||||
}
|
||||
|
||||
/// Write a comment under the first free name derived from `stem`.
|
||||
///
|
||||
/// `create_new` rather than `fs::write`: a name that already exists means another
|
||||
/// comment landed in the same microsecond, and truncating it is exactly the data
|
||||
/// loss this guards against. The suffix is zero padded so the names keep sorting
|
||||
/// in the order they were written.
|
||||
fn write_new_comment(comments_dir: &Path, stem: &str, content: &str) -> Result<String> {
|
||||
for attempt in 0..100 {
|
||||
let filename = match attempt {
|
||||
0 => format!("{}.md", stem),
|
||||
n => format!("{}_{:02}.md", stem, n),
|
||||
};
|
||||
|
||||
match fs::OpenOptions::new()
|
||||
.write(true)
|
||||
.create_new(true)
|
||||
.open(comments_dir.join(&filename))
|
||||
{
|
||||
Ok(mut file) => {
|
||||
file.write_all(content.as_bytes())?;
|
||||
return Ok(filename);
|
||||
}
|
||||
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
|
||||
Err(e) => return Err(e.into()),
|
||||
}
|
||||
}
|
||||
|
||||
Err(anyhow!(
|
||||
"No free comment filename for '{}' in {}",
|
||||
stem,
|
||||
comments_dir.display()
|
||||
))
|
||||
}
|
||||
|
||||
pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
let (_status, title, content) = resolve_ticket(search, worklane_dir)?;
|
||||
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
|
||||
@@ -445,9 +368,8 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
println!("\n{}", content_trim_colored(&content, &resolved));
|
||||
|
||||
if ticket_uuid != "_Not set_" {
|
||||
let comments_dir = comments_dir(worklane_dir, &ticket_uuid);
|
||||
let comments = read_comments(&comments_dir)?;
|
||||
let formatted = format_comments(&comments);
|
||||
let entries = read_history(worklane_dir, &ticket_uuid)?;
|
||||
let formatted = format_history(&entries);
|
||||
println!("{}", formatted);
|
||||
}
|
||||
|
||||
@@ -462,6 +384,7 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
/// mid-sentence so there is no capital to case.
|
||||
const TICKET: &str = "ticket";
|
||||
const CAMPAIGN: &str = "campaign";
|
||||
const TAG: &str = "tag";
|
||||
|
||||
/// Write `content` over `path`, without ever leaving half a file behind.
|
||||
///
|
||||
@@ -602,7 +525,10 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str) -> Result<()>
|
||||
|
||||
for blocker in &blockers {
|
||||
match index.get(&blocker.target) {
|
||||
Some(target) if target.status == DONE => {}
|
||||
// Discarded satisfies a block the way done does: there is nothing left to
|
||||
// wait for. Whether the dependent still makes sense was asked when the
|
||||
// blocker was discarded, which is `check_dependents`' refusal.
|
||||
Some(target) if !is_open(&target.status) => {}
|
||||
Some(target) => open.push(format!(
|
||||
" ({}) {} [{}]",
|
||||
color_text(short_id(&target.uuid), Color::Red),
|
||||
@@ -630,12 +556,71 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str) -> Result<()>
|
||||
))
|
||||
}
|
||||
|
||||
/// Refuse discarding a ticket while open tickets are blocked by it.
|
||||
///
|
||||
/// The mirror of [`check_blockers`], asked at the other end of the edge: those tickets
|
||||
/// recorded a dependency on work that is about to be declared never-happening, so their
|
||||
/// plans need a look before the ground moves. `-f` is the caller saying they looked.
|
||||
///
|
||||
/// Tickets already done or discarded do not hold it up: a dependency that was satisfied
|
||||
/// or abandoned is nobody's plan anymore.
|
||||
fn check_dependents(worklane_dir: &Path, uuid: &str, title: &str) -> Result<()> {
|
||||
let index = RelationIndex::load(worklane_dir)?;
|
||||
|
||||
// Every open dependent, not the first, for the reason `check_blockers` names them
|
||||
// all.
|
||||
let waiting: Vec<String> = index
|
||||
.iter()
|
||||
.filter(|ticket| is_open(&ticket.status))
|
||||
.filter(|ticket| {
|
||||
ticket
|
||||
.relations
|
||||
.iter()
|
||||
.any(|relation| relation.kind == RelationKind::BlockedBy && relation.target == uuid)
|
||||
})
|
||||
.map(|ticket| {
|
||||
format!(
|
||||
" ({}) {} [{}]",
|
||||
color_text(short_id(&ticket.uuid), Color::Red),
|
||||
ticket.title,
|
||||
color_text(&ticket.status, Color::Orange),
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
|
||||
if waiting.is_empty() {
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
Err(anyhow!(
|
||||
"Cannot discard '{}' while open tickets are blocked by it:\n{}\nUse --force (-f) to discard it anyway.",
|
||||
color_text(title, Color::Green),
|
||||
waiting.join("\n"),
|
||||
))
|
||||
}
|
||||
|
||||
/// A status is a [`Status`] rather than a string, so an unknown one is clap's to refuse
|
||||
/// and nothing here has to check. What is left is the order of the flow, which is
|
||||
/// `Status::ALL`.
|
||||
pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Result<()> {
|
||||
pub fn cmd_mv(
|
||||
ticket_id: &str,
|
||||
target: Status,
|
||||
force: bool,
|
||||
actor: &Option<String>,
|
||||
reason: &Option<String>,
|
||||
start: &Path,
|
||||
) -> Result<()> {
|
||||
let target_status = target.as_str();
|
||||
|
||||
// A reason is one fact on one line, which is how the renderer draws it, so a
|
||||
// newline smuggled in through the shell collapses with the whitespace around it.
|
||||
// All blank means none, rather than an empty field in the log.
|
||||
let reason = reason
|
||||
.as_deref()
|
||||
.map(str::split_whitespace)
|
||||
.map(|words| words.collect::<Vec<_>>().join(" "))
|
||||
.unwrap_or_default();
|
||||
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let (current_status, title, resolved) = resolve_ticket(ticket_id, &worklane_dir)?;
|
||||
|
||||
@@ -645,7 +630,13 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
|
||||
.unwrap();
|
||||
let target_idx = Status::ALL.iter().position(|status| *status == target).unwrap();
|
||||
|
||||
if !force && target_idx < current_idx {
|
||||
// Discarding is not a stage of work, so the walk rules below do not apply to
|
||||
// entering it: a ticket is abandoned from wherever it stands. They do apply to
|
||||
// leaving it, which with discarded last in `Status::ALL` is always a backward move,
|
||||
// so un-discarding needs `-f` with no rule of its own.
|
||||
let discarding = target == Status::Discarded;
|
||||
|
||||
if !force && !discarding && target_idx < current_idx {
|
||||
return Err(anyhow!(
|
||||
"Cannot move backward from {} to {}. Use --force (-f) to allow.",
|
||||
color_text(¤t_status, Color::Orange),
|
||||
@@ -653,7 +644,7 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
|
||||
));
|
||||
}
|
||||
|
||||
if !force && target_idx != current_idx + 1 && target_idx != current_idx {
|
||||
if !force && !discarding && target_idx != current_idx + 1 && target_idx != current_idx {
|
||||
return Err(anyhow!(
|
||||
"Can only move one stage forward at a time. Use --force (-f) to skip stages."
|
||||
));
|
||||
@@ -669,14 +660,25 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
|
||||
|
||||
// After the no-op above, so a ticket is never refused for a move it is not making,
|
||||
// and behind `force`, which is where the other two overrides of a rule the board
|
||||
// keeps true already live.
|
||||
// keeps true already live. The two guards look opposite ways: a ticket being worked
|
||||
// must not run ahead of what it waits on, and a ticket being abandoned owes nothing
|
||||
// to its own blockers but must not be pulled out from under the tickets waiting on
|
||||
// it.
|
||||
if !force {
|
||||
check_blockers(&worklane_dir, &resolved, &title)?;
|
||||
match discarding {
|
||||
true => check_dependents(&worklane_dir, &parse_ticket_field(&resolved, "ID"), &title)?,
|
||||
false => check_blockers(&worklane_dir, &resolved, &title)?,
|
||||
}
|
||||
}
|
||||
|
||||
let current_path = worklane_dir.join(¤t_status);
|
||||
let target_path = worklane_dir.join(target_status);
|
||||
|
||||
// A board created before a status existed has no directory for it, and the first
|
||||
// move into one is the wrong place to refuse. Idempotent for every board that has
|
||||
// it.
|
||||
fs::create_dir_all(&target_path)?;
|
||||
|
||||
// Updated before the file is even located, so a ticket without a Status field is
|
||||
// refused for that reason rather than for whatever the lookup notices first.
|
||||
let content = set_status_field(&resolved, target_status, &title)?;
|
||||
@@ -703,6 +705,18 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
|
||||
&title,
|
||||
)?;
|
||||
|
||||
// After the move, never before: an entry for a move that was refused would be a log
|
||||
// of things that did not happen. The no-op above returns without one for the same
|
||||
// reason, and without its --reason with it.
|
||||
write_entry(
|
||||
&worklane_dir,
|
||||
&parse_ticket_field(&resolved, "ID"),
|
||||
Kind::Status,
|
||||
&change(¤t_status, target_status),
|
||||
&resolve_actor(actor.as_deref()),
|
||||
&reason,
|
||||
)?;
|
||||
|
||||
println!(
|
||||
"Moved ticket '{}' from {} to {}",
|
||||
color_text(&title, Color::Green),
|
||||
@@ -716,7 +730,7 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
|
||||
pub fn cmd_comment(
|
||||
ticket_id: &str,
|
||||
body: &str,
|
||||
owner: &Option<String>,
|
||||
actor: &Option<String>,
|
||||
start: &Path,
|
||||
) -> Result<()> {
|
||||
if body.is_empty() {
|
||||
@@ -731,29 +745,14 @@ pub fn cmd_comment(
|
||||
return Err(anyhow!("Could not determine ticket ID."));
|
||||
}
|
||||
|
||||
let comments_dir = comments_dir(&worklane_dir, &ticket_uuid);
|
||||
fs::create_dir_all(&comments_dir)?;
|
||||
|
||||
let stem = Local::now().format(COMMENT_FILE_FORMAT).to_string();
|
||||
|
||||
let author = match owner {
|
||||
Some(o) => o.clone(),
|
||||
None => get_git_user().unwrap_or_else(|| "unknown".to_string()),
|
||||
};
|
||||
|
||||
let comment_content = format!(
|
||||
"**Comment**\n\
|
||||
{}\n\
|
||||
\n\
|
||||
**Author**: {}\n\
|
||||
**Time**: {}\n\
|
||||
",
|
||||
let filename = write_entry(
|
||||
&worklane_dir,
|
||||
&ticket_uuid,
|
||||
Kind::Comment,
|
||||
body,
|
||||
author,
|
||||
Local::now().format(TIMESTAMP_FORMAT)
|
||||
);
|
||||
|
||||
let filename = write_new_comment(&comments_dir, &stem, &comment_content)?;
|
||||
&resolve_actor(actor.as_deref()),
|
||||
"",
|
||||
)?;
|
||||
|
||||
println!("Comment added to '{}' ({})", title, filename);
|
||||
Ok(())
|
||||
@@ -775,6 +774,42 @@ fn section_args<'a>(
|
||||
]
|
||||
}
|
||||
|
||||
/// The lines a caller's values amount to, or the refusal an all-blank call earns.
|
||||
///
|
||||
/// An empty value is a paragraph break, so a call whose values are *every one* blank asked
|
||||
/// for nothing, and writing an empty section is not what it meant. Shared by `set` and
|
||||
/// `campaign set` because the rule is the section's rather than the object's.
|
||||
///
|
||||
/// `instead` is the way out, and it is the caller's because the callers differ: a ticket's
|
||||
/// section is emptied with `--clear <field>`, and a campaign's description has no cleared
|
||||
/// form at all, per [`CampaignSetArgs`].
|
||||
fn replaced_items(section: &Section, values: &[String], instead: &str) -> Result<Vec<String>> {
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"An empty value is a paragraph break, not a way to empty the {}: {}",
|
||||
section.label,
|
||||
instead
|
||||
));
|
||||
}
|
||||
|
||||
Ok(items)
|
||||
}
|
||||
|
||||
/// The same for `append`, which has no way out to name: appending nothing was never a way
|
||||
/// to empty anything, so the message says only that there was nothing to add.
|
||||
fn appended_items(section: &Section, values: &[String]) -> Result<Vec<String>> {
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"Nothing to append to the {}: every value given was blank",
|
||||
section.label
|
||||
));
|
||||
}
|
||||
|
||||
Ok(items)
|
||||
}
|
||||
|
||||
/// Write the ticket back, renaming the file when a new title changes its slug.
|
||||
///
|
||||
/// The content goes down first and the rename second, the same order and for the same
|
||||
@@ -863,12 +898,23 @@ fn apply(content: &mut String, changed: &mut Vec<&'static str>, field: &'static
|
||||
}
|
||||
|
||||
fn report(fields: &[&str], title: &str, verb: &str) {
|
||||
report_in(fields, title, Color::Green, verb)
|
||||
}
|
||||
|
||||
/// The same, for a subject that is not a title.
|
||||
///
|
||||
/// Green means title, everywhere, so the one caller whose subject is a tag cannot use it:
|
||||
/// a tag is drawn in a `TAG_COLORS` slot or it is drawn wrong, and green is deliberately
|
||||
/// not one of them. The colour is passed in rather than decided here, which is the trade
|
||||
/// `paint` makes with `color_text`, and it keeps the wording in one place so a tag reports
|
||||
/// a no-op in the same words a ticket does.
|
||||
fn report_in(fields: &[&str], title: &str, color: Color, verb: &str) {
|
||||
if fields.is_empty() {
|
||||
println!("No changes to '{}'", color_text(title, Color::Green));
|
||||
println!("No changes to '{}'", color_text(title, color));
|
||||
return;
|
||||
}
|
||||
|
||||
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, Color::Green));
|
||||
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, color));
|
||||
}
|
||||
|
||||
pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
|
||||
@@ -897,14 +943,8 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
|
||||
continue;
|
||||
}
|
||||
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"An empty value is a paragraph break, not a way to empty the {}: use --clear {}",
|
||||
section.label,
|
||||
section.clear.map_or("", Clearable::name)
|
||||
));
|
||||
}
|
||||
let clear = format!("use --clear {}", section.clear.map_or("", Clearable::name));
|
||||
let items = replaced_items(section, values, &clear)?;
|
||||
|
||||
let next = set_section_body(&content, section, &items)?;
|
||||
apply(&mut content, &mut changed, section.label, next);
|
||||
@@ -946,6 +986,24 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
|
||||
let renamed = changed.contains(&"title").then_some(()).and(args.title.as_ref());
|
||||
save_ticket(&worklane_dir, &status, &uuid, &title, renamed, &content)?;
|
||||
|
||||
// Tags alone, of everything `set` writes. The other fields change often enough that a
|
||||
// log of them is noise, and `apply` is what decides this: a field it did not record as
|
||||
// changed was already what the call asked for. Emptying the field counts, since
|
||||
// `--clear tags` is the same field going somewhere.
|
||||
if changed.contains(&"tags") || cleared.contains(&"tags") {
|
||||
write_entry(
|
||||
&worklane_dir,
|
||||
&uuid,
|
||||
Kind::Tags,
|
||||
&change(
|
||||
&parse_ticket_field(&original, "Tags"),
|
||||
&parse_ticket_field(&content, "Tags"),
|
||||
),
|
||||
&resolve_actor(args.actor.as_deref()),
|
||||
"",
|
||||
)?;
|
||||
}
|
||||
|
||||
let shown = args.title.clone().unwrap_or(title);
|
||||
if !changed.is_empty() {
|
||||
report(&changed, &shown, "Updated");
|
||||
@@ -990,6 +1048,20 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
|
||||
|
||||
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
|
||||
|
||||
// Behind the no-change return above, so a chown to the owner a ticket already has
|
||||
// records nothing, and after the save, so a failed write logs nothing.
|
||||
write_entry(
|
||||
&worklane_dir,
|
||||
&uuid,
|
||||
Kind::Owner,
|
||||
&change(
|
||||
&parse_ticket_field(&original, "Owner"),
|
||||
&parse_ticket_field(&content, "Owner"),
|
||||
),
|
||||
&resolve_actor(args.actor.as_deref()),
|
||||
"",
|
||||
)?;
|
||||
|
||||
let verb = match user {
|
||||
Some(_) => "Updated",
|
||||
None => "Cleared",
|
||||
@@ -1011,13 +1083,7 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
|
||||
continue;
|
||||
}
|
||||
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"Nothing to append to the {}: every value given was blank",
|
||||
section.label
|
||||
));
|
||||
}
|
||||
let items = appended_items(section, values)?;
|
||||
|
||||
content = append_section_body(&content, section, &items)?;
|
||||
changed.push(section.label);
|
||||
@@ -1197,27 +1263,52 @@ pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Every tag on the board, with how many tickets carry it.
|
||||
/// Every tag on the board: the ones the tickets carry, the ones the file declares, and
|
||||
/// what each declared one means.
|
||||
///
|
||||
/// The vocabulary itself, which nothing else could answer: `ls --tag` filters by a tag
|
||||
/// already known, and the decorated listing does not print tags at all. A grooming sweep
|
||||
/// starts by asking what the vocabulary *is*, and `assets/PLAN.md` used to have to say
|
||||
/// that the question could only be answered by reading the tickets.
|
||||
///
|
||||
/// **The union of the two vocabularies, not either one.** Since `tags.md` exists there are
|
||||
/// two: the tags the file declares and the tags the tickets carry. A declared tag nothing
|
||||
/// carries lists at zero rather than being dropped, and a carried tag nothing declares
|
||||
/// still lists. Those two cases are the whole reason to declare tags at all, so this is
|
||||
/// the command that has to show them apart.
|
||||
///
|
||||
/// **Alphabetical, and case sensitive.** `--tag` matches a whole value case sensitively,
|
||||
/// so `bug` and `Bug` are two tags and listing them as one would hide the reason a filter
|
||||
/// came back short. Sorting puts them next to each other, which is where a near-duplicate
|
||||
/// is spotted.
|
||||
///
|
||||
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count.
|
||||
/// Fish reads what follows the tab as a description, a script takes `cut -f1`, and neither
|
||||
/// wants an escape sequence. Every status, done included, for the reason `ls --ids`
|
||||
/// includes it: a tag retired months ago is still part of the answer to what the
|
||||
/// vocabulary has been.
|
||||
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count, and
|
||||
/// a tab and the annotation's opening line for a tag the file declares. Fish reads what
|
||||
/// follows the first tab as a description, a script takes `cut -f1`, and neither wants an
|
||||
/// escape sequence.
|
||||
///
|
||||
/// **A carried but undeclared tag is marked by the absence of the third field**, which is
|
||||
/// where the shape comes from. Anything appended to the tag itself would have a completion
|
||||
/// offer a tag that does not exist, and anything added to the count would stop the second
|
||||
/// field being a number. Absence costs neither, and it buys the one property a marker
|
||||
/// could not: a board with no `tags.md` has every tag undeclared, so it prints two fields
|
||||
/// a line, which is byte for byte what this printed before the file existed. The shipped
|
||||
/// fish completion of an older version is still reading that.
|
||||
///
|
||||
/// Every status, done included, for the reason `ls --ids` includes it: a tag retired months
|
||||
/// ago is still part of the answer to what the vocabulary has been.
|
||||
pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
// Through the same `load` `tags add` uses, so a file that is there and cannot be read
|
||||
// is an error here too. The listing is the one tag command that could go on without the
|
||||
// file, and reporting a vocabulary while silently treating a broken file as no file is
|
||||
// the wrong half of the answer.
|
||||
let index = TagIndex::load(worklane_dir)?;
|
||||
|
||||
// BTreeMap rather than a sort afterwards: the order is the point, and the counting
|
||||
// wants a map anyway.
|
||||
let mut counts: BTreeMap<String, usize> = BTreeMap::new();
|
||||
// wants a map anyway. Seeded from the vocabulary rather than merged into afterwards,
|
||||
// which is what puts a declared tag nothing carries in at zero.
|
||||
let mut counts: BTreeMap<String, usize> =
|
||||
index.names().map(|tag| (tag.to_string(), 0)).collect();
|
||||
|
||||
for status in status_dirs() {
|
||||
let status_path = worklane_dir.join(status);
|
||||
@@ -1233,12 +1324,110 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
}
|
||||
|
||||
for (tag, count) in counts {
|
||||
println!("{}\t{}", tag, count);
|
||||
match index.summary(&tag) {
|
||||
Some(summary) => println!("{tag}\t{count}\t{summary}"),
|
||||
None => println!("{tag}\t{count}"),
|
||||
}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Declare a tag, and what it means.
|
||||
///
|
||||
/// The counterpart of `cmd_tags`, which reports the vocabulary the tickets *carry*. This
|
||||
/// writes the one the board *intends*, and the two are deliberately not kept in step: a
|
||||
/// declaration tags nothing, so the file cannot be used to work out what is in use, and
|
||||
/// `tags add` on a word no ticket carries is the normal case rather than a mistake.
|
||||
///
|
||||
/// **A tag already declared is refused rather than overwritten**, the way `add` refuses
|
||||
/// nothing and `campaign set --codename` refuses a replacement without `--force`. An
|
||||
/// annotation is the sentence a whole team files tickets against, so replacing one by
|
||||
/// typing `add` twice is not something to do by accident. The refusal names the command
|
||||
/// that does replace it, since that is the next thing the caller wants.
|
||||
///
|
||||
/// The whole file is re-rendered from the parsed vocabulary, so declaring a tag also
|
||||
/// re-sorts the file and rewrites its preamble. That is why an unreadable file is an error
|
||||
/// in `TagIndex::load` rather than an empty vocabulary: here, empty would mean erased.
|
||||
pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let mut index = TagIndex::load(&worklane_dir)?;
|
||||
|
||||
if index.declared(&args.tag) {
|
||||
return Err(anyhow!(
|
||||
"Tag '{}' is already declared, so nothing was written. \
|
||||
Use `worklane tags set` to change what it means",
|
||||
args.tag
|
||||
));
|
||||
}
|
||||
|
||||
// Joined with a single newline, so an empty value is a paragraph break, exactly as it
|
||||
// is for a description.
|
||||
let annotation = trim_blank_ends(&args.annotation).join("\n");
|
||||
index.declare(&args.tag, &annotation);
|
||||
|
||||
write_then_replace(
|
||||
&worklane_dir,
|
||||
&tags_path(&worklane_dir),
|
||||
TAGS_FILE,
|
||||
&index.render(),
|
||||
TAG,
|
||||
&args.tag,
|
||||
)?;
|
||||
|
||||
// The tag in its own colour, which is the colour it is drawn in on every card and in
|
||||
// every listing: `tag_color` is a pure function of the word.
|
||||
println!("Declared tag: {}", color_text(&args.tag, tag_color(&args.tag)));
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Replace what a declared tag means.
|
||||
///
|
||||
/// The other half of `tags add`, and the half `campaign` still lacks for its description,
|
||||
/// 32e98ab. An annotation is the sentence a whole team files tickets against, so getting it
|
||||
/// wrong once must not be permanent.
|
||||
///
|
||||
/// **A tag that is not declared is refused rather than declared here.** `add` and `set` are
|
||||
/// a pair, each refusing what the other is for, so which of the two wrote a line is never a
|
||||
/// question of which one happened to be typed. The refusal names the other command, the way
|
||||
/// `add`'s names this one.
|
||||
///
|
||||
/// The no-op compares the rendered file rather than the annotation, which is what `apply`
|
||||
/// does for a ticket: the file is the thing that would be written, so it is the thing worth
|
||||
/// asking whether the write would change.
|
||||
pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let mut index = TagIndex::load(&worklane_dir)?;
|
||||
|
||||
if !index.declared(&args.tag) {
|
||||
return Err(anyhow!(
|
||||
"No tag '{}' is declared, so nothing was written. \
|
||||
Use `worklane tags add` to declare it",
|
||||
args.tag
|
||||
));
|
||||
}
|
||||
|
||||
let original = index.render();
|
||||
index.declare(&args.tag, &trim_blank_ends(&args.annotation).join("\n"));
|
||||
let next = index.render();
|
||||
|
||||
let mut changed: Vec<&'static str> = Vec::new();
|
||||
if original != next {
|
||||
changed.push("annotation");
|
||||
write_then_replace(
|
||||
&worklane_dir,
|
||||
&tags_path(&worklane_dir),
|
||||
TAGS_FILE,
|
||||
&next,
|
||||
TAG,
|
||||
&args.tag,
|
||||
)?;
|
||||
}
|
||||
|
||||
report_in(&changed, &args.tag, tag_color(&args.tag), "Updated");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Replace fields on a campaign that is already filed.
|
||||
///
|
||||
/// `cmd_set` for a campaign, and built out of the same parts: `set_title` for the heading,
|
||||
@@ -1266,6 +1455,18 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
/// No-op detection compares the whole file, the way `set` and `chown` do, so setting a
|
||||
/// codename a campaign already carries writes nothing. That is a no-op and not a refusal:
|
||||
/// `--force` is about overwriting a *different* word, and there is nothing to overwrite.
|
||||
///
|
||||
/// **The description goes through `set_section_body` and the `DESCRIPTION` entry**, the
|
||||
/// section table `cmd_set` and `campaign_body` already read, so what a campaign's one prose
|
||||
/// section *is* stays decided in one place. A second definition scoped to campaigns would
|
||||
/// drift on the spelling of the heading, which is the drift `campaign_body` was written
|
||||
/// against.
|
||||
///
|
||||
/// A campaign whose Description heading is gone is refused by that call rather than given
|
||||
/// the section back through `ensure_section`. Every campaign the tool has ever filed carries
|
||||
/// the heading, so an insertion path here would be reachable only from a hand-edited file:
|
||||
/// that is the opposite of the Relations case, where `add` writes nothing and the insertion
|
||||
/// is the only path there is.
|
||||
pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
|
||||
@@ -1293,6 +1494,16 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
apply(&mut content, &mut changed, "title", next);
|
||||
}
|
||||
|
||||
if !args.description.is_empty() {
|
||||
let items = replaced_items(
|
||||
&DESCRIPTION,
|
||||
&args.description,
|
||||
"a campaign's description has no cleared form",
|
||||
)?;
|
||||
let next = set_section_body(&content, &DESCRIPTION, &items)?;
|
||||
apply(&mut content, &mut changed, DESCRIPTION.label, next);
|
||||
}
|
||||
|
||||
if let Some(codename) = &args.codename {
|
||||
let next = set_or_insert_metadata_field(&content, CODENAME_FIELD, codename, &title)?;
|
||||
apply(&mut content, &mut changed, "codename", next);
|
||||
@@ -1310,6 +1521,32 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Add a paragraph to a campaign's description.
|
||||
///
|
||||
/// The other half of `campaign set --description`, and `cmd_append` for a campaign: the same
|
||||
/// `append_section_body` and the same `DESCRIPTION` entry, so a paragraph lands under a
|
||||
/// campaign's description the way it lands under a ticket's, blank line and all. A campaign
|
||||
/// filed with no description holds the placeholder, and that is replaced rather than
|
||||
/// followed, which is `append_section_body`'s rule and not a case handled here.
|
||||
///
|
||||
/// No whole-file comparison, unlike `set`: every value blank is refused above, so there is
|
||||
/// nothing left that appends nothing. `cmd_append` says it the same way.
|
||||
///
|
||||
/// One section, so there is no loop and no list to report: what changed is the description
|
||||
/// or the call failed.
|
||||
pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
|
||||
|
||||
let items = appended_items(&DESCRIPTION, &args.description)?;
|
||||
let content = append_section_body(&campaign.content, &DESCRIPTION, &items)?;
|
||||
|
||||
save_campaign(&worklane_dir, &campaign.uuid, &campaign.title, None, &content)?;
|
||||
|
||||
report(&[DESCRIPTION.label], &campaign.title, "Appended to");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Show a campaign, then its members grouped by status.
|
||||
///
|
||||
/// Every status is shown, done included, unlike `ls`, which leaves done out of its
|
||||
@@ -1350,7 +1587,12 @@ pub fn cmd_campaign_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
///
|
||||
/// No-op detection compares the whole file, the way `set` and `chown` do, so assigning
|
||||
/// a ticket to the campaign it already names writes nothing.
|
||||
pub fn cmd_assign(campaign_search: &str, ticket_id: &str, start: &Path) -> Result<()> {
|
||||
pub fn cmd_assign(
|
||||
campaign_search: &str,
|
||||
ticket_id: &str,
|
||||
actor: &Option<String>,
|
||||
start: &Path,
|
||||
) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let campaign = resolve_campaign(campaign_search, &worklane_dir)?;
|
||||
let (status, title, original) = resolve_ticket(ticket_id, &worklane_dir)?;
|
||||
@@ -1369,6 +1611,27 @@ pub fn cmd_assign(campaign_search: &str, ticket_id: &str, start: &Path) -> Resul
|
||||
|
||||
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
|
||||
|
||||
// Behind the no-change return above and after the save, the rule every writer
|
||||
// follows. The entry records `Campaign::name`, not the uuid the field holds: what
|
||||
// the reader should see is settled here, when the entry is written. A campaign the
|
||||
// board no longer has reads `_missing_`, the way the Campaign field itself renders
|
||||
// a dangling uuid.
|
||||
let before = match parse_campaign(&original) {
|
||||
None => NOT_SET.to_string(),
|
||||
Some(old) => CampaignIndex::load(&worklane_dir)?
|
||||
.get(&old)
|
||||
.map(|was| was.name().to_string())
|
||||
.unwrap_or_else(|| "_missing_".to_string()),
|
||||
};
|
||||
write_entry(
|
||||
&worklane_dir,
|
||||
&uuid,
|
||||
Kind::Campaign,
|
||||
&change(&before, campaign.name()),
|
||||
&resolve_actor(actor.as_deref()),
|
||||
"",
|
||||
)?;
|
||||
|
||||
println!(
|
||||
"Assigned '{}' to campaign '{}'",
|
||||
color_text(&title, Color::Green),
|
||||
@@ -1642,36 +1905,3 @@ pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// The collision path cannot be provoked from the CLI, since two processes
|
||||
/// will not share a microsecond, but it is the whole point of the guard.
|
||||
#[test]
|
||||
fn a_colliding_stem_takes_the_next_name_and_keeps_the_first() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-test-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
|
||||
let first = write_new_comment(&dir, "20260820_143012_123456", "first").unwrap();
|
||||
let second = write_new_comment(&dir, "20260820_143012_123456", "second").unwrap();
|
||||
let third = write_new_comment(&dir, "20260820_143012_123456", "third").unwrap();
|
||||
|
||||
assert_eq!(first, "20260820_143012_123456.md");
|
||||
assert_eq!(second, "20260820_143012_123456_01.md");
|
||||
assert_eq!(third, "20260820_143012_123456_02.md");
|
||||
|
||||
// Nothing was truncated on the way through
|
||||
assert_eq!(fs::read_to_string(dir.join(&first)).unwrap(), "first");
|
||||
assert_eq!(fs::read_to_string(dir.join(&second)).unwrap(), "second");
|
||||
assert_eq!(fs::read_to_string(dir.join(&third)).unwrap(), "third");
|
||||
|
||||
// read_comments sorts on the stem, so the names must sort in write order
|
||||
let mut names = vec![second.clone(), third.clone(), first.clone()];
|
||||
names.sort();
|
||||
assert_eq!(names, vec![first, second, third]);
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
+763
@@ -0,0 +1,763 @@
|
||||
//! What happened to a ticket, one file per entry.
|
||||
//!
|
||||
//! The comments directory was already an append-only log with exactly one event kind:
|
||||
//! one file per entry under a directory named by the ticket's uuid, stamped to the
|
||||
//! microsecond and written with `create_new` so two writers cannot clobber each other.
|
||||
//! This is that log with the kind named in it, so a status change, an owner change, a
|
||||
//! tag change and a campaign move are recorded beside what somebody said about them.
|
||||
//!
|
||||
//! What is deliberately not logged: ticking or unticking a criterion, and edits to the
|
||||
//! title, description, plan, priority or due. Those change often and a log of them is
|
||||
//! noise. When one of them matters, whoever made it adds a comment saying why, which is
|
||||
//! the record actually worth keeping.
|
||||
//!
|
||||
//! Every entry names its author, from [`resolve_actor`], so a board several agents write
|
||||
//! to says which of them did what.
|
||||
//!
|
||||
//! [`resolve_actor`]: crate::util::resolve_actor
|
||||
|
||||
use std::fs;
|
||||
use std::io::Write;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use anyhow::{Result, anyhow};
|
||||
use chrono::Local;
|
||||
|
||||
use crate::util::{Cell, Color, TIMESTAMP_FORMAT, paint_cells, should_use_colors};
|
||||
|
||||
/// Where a ticket's history lives, under the board.
|
||||
///
|
||||
/// Beside the status directories rather than among them, the way `campaigns_dir` is: an
|
||||
/// entry has no status of its own. Spelled once here, so the writer, the reader and the
|
||||
/// card's counter cannot disagree about the path.
|
||||
pub const HISTORY_DIR: &str = "history";
|
||||
|
||||
/// The name the same directory had while a comment was the only entry it could hold.
|
||||
///
|
||||
/// Kept so a board written by an older version is adopted rather than migrated by hand.
|
||||
/// See [`adopt_comments`].
|
||||
pub const COMMENTS_DIR: &str = "comments";
|
||||
|
||||
/// How an entry filename is stamped.
|
||||
///
|
||||
/// Microseconds, not seconds: at second resolution two entries in the same second
|
||||
/// produced the same name and the second silently truncated the first. Fixed width and
|
||||
/// first in the name, so the lexicographic sort in [`read_history`] stays chronological
|
||||
/// whatever kind follows it.
|
||||
pub const ENTRY_FILE_FORMAT: &str = "%Y%m%d_%H%M%S_%6f";
|
||||
|
||||
/// The history root of a board.
|
||||
pub fn history_root(board: &Path) -> PathBuf {
|
||||
board.join(HISTORY_DIR)
|
||||
}
|
||||
|
||||
/// The history directory for one ticket, named by its full uuid.
|
||||
pub fn history_dir(board: &Path, uuid: &str) -> PathBuf {
|
||||
history_root(board).join(uuid)
|
||||
}
|
||||
|
||||
/// What an entry records.
|
||||
///
|
||||
/// An enum rather than a string, so a kind the reader does not know is a compile error
|
||||
/// instead of a word that renders as itself. The variants are the five things worth
|
||||
/// keeping: what somebody said, and the four fields whose history answers a question.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum Kind {
|
||||
Comment,
|
||||
Status,
|
||||
Owner,
|
||||
Tags,
|
||||
Campaign,
|
||||
}
|
||||
|
||||
impl Kind {
|
||||
/// Every kind, which is what the reader matches a marker against and what the
|
||||
/// counter matches a filename against.
|
||||
pub const ALL: [Kind; 5] = [
|
||||
Kind::Comment,
|
||||
Kind::Status,
|
||||
Kind::Owner,
|
||||
Kind::Tags,
|
||||
Kind::Campaign,
|
||||
];
|
||||
|
||||
/// The width the mechanical labels are padded to, `campaign` being the longest of
|
||||
/// the four. `comment` renders as a header and a body, not as a row, so it is not
|
||||
/// among them.
|
||||
const LABEL_WIDTH: usize = 8;
|
||||
|
||||
/// The word in the filename, and the label a mechanical entry renders under.
|
||||
pub fn slug(self) -> &'static str {
|
||||
match self {
|
||||
Kind::Comment => "comment",
|
||||
Kind::Status => "status",
|
||||
Kind::Owner => "owner",
|
||||
Kind::Tags => "tags",
|
||||
Kind::Campaign => "campaign",
|
||||
}
|
||||
}
|
||||
|
||||
/// The marker the file opens with, which is what the reader keys the kind off.
|
||||
///
|
||||
/// The file is the record and the filename is an index into it: a name can be
|
||||
/// changed by anything that touches the directory, so the kind is read from the
|
||||
/// content and only counted from the name.
|
||||
fn marker(self) -> &'static str {
|
||||
match self {
|
||||
Kind::Comment => "**Comment**",
|
||||
Kind::Status => "**Status**",
|
||||
Kind::Owner => "**Owner**",
|
||||
Kind::Tags => "**Tags**",
|
||||
Kind::Campaign => "**Campaign**",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// One entry: what happened, who wrote it and when.
|
||||
#[derive(Debug)]
|
||||
pub struct Entry {
|
||||
/// The file stem, which is what the entries are sorted by.
|
||||
pub filename: String,
|
||||
pub kind: Kind,
|
||||
pub author: String,
|
||||
pub time: String,
|
||||
/// A comment's text, or the before and after of the field a mechanical entry names.
|
||||
pub body: String,
|
||||
/// Why a mechanical entry happened, as `mv --reason` gave it. Empty for every entry
|
||||
/// that carries no such field, which is all of them but a reasoned move — including
|
||||
/// every entry written before reasons existed.
|
||||
pub reason: String,
|
||||
}
|
||||
|
||||
/// Rename an old `comments` directory to `history`, before anything reads or writes it.
|
||||
///
|
||||
/// One rename rather than a migration command: the entries themselves need no rewriting,
|
||||
/// since [`parse_entry`] reads a file with no marker as the comment it is. Called by the
|
||||
/// reader, the writer and the counter, so no caller has to remember it and a board can
|
||||
/// never be reached through a path that skips it.
|
||||
///
|
||||
/// Both directories at once is refused rather than merged. Only the CLI writes there, so
|
||||
/// it cannot arrive at that state on its own, and choosing which of two entries with the
|
||||
/// same name survives is not a decision to make silently.
|
||||
pub fn adopt_comments(board: &Path) -> Result<()> {
|
||||
let old = board.join(COMMENTS_DIR);
|
||||
if !old.exists() {
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let new = history_root(board);
|
||||
if new.exists() {
|
||||
return Err(anyhow!(
|
||||
"Board holds both {} and {}. Only worklane writes there, so this needs a \
|
||||
person: move the entries under {} into the matching directories in {}, \
|
||||
then remove it.",
|
||||
old.display(),
|
||||
new.display(),
|
||||
COMMENTS_DIR,
|
||||
HISTORY_DIR,
|
||||
));
|
||||
}
|
||||
|
||||
fs::rename(&old, &new)
|
||||
.map_err(|e| anyhow!("Could not rename {} to {}: {}", old.display(), new.display(), e))
|
||||
}
|
||||
|
||||
/// One entry, from its filename and its content.
|
||||
///
|
||||
/// Split out from the directory walk so the parse can be tested without a fixture, and
|
||||
/// because it is where the compatibility lives: a file with no marker is a comment,
|
||||
/// which is what every entry written before the kinds existed is.
|
||||
fn parse_entry(filename: &str, content: &str) -> Entry {
|
||||
let field = |name: &str| {
|
||||
let marker = format!("**{}**:", name);
|
||||
content
|
||||
.lines()
|
||||
.find(|line| line.starts_with(&marker))
|
||||
.and_then(|line| line.split_once(&marker))
|
||||
.map(|(_, value)| value.trim().to_string())
|
||||
.unwrap_or_else(|| "unknown".to_string())
|
||||
};
|
||||
|
||||
let kind = Kind::ALL
|
||||
.into_iter()
|
||||
.find(|kind| content.starts_with(&format!("{}\n", kind.marker())))
|
||||
.unwrap_or(Kind::Comment);
|
||||
|
||||
let body = content
|
||||
.strip_prefix(&format!("{}\n", kind.marker()))
|
||||
.map(|rest| match rest.find("\n\n**Author**") {
|
||||
Some(end) => rest[..end].trim(),
|
||||
None => rest.trim(),
|
||||
})
|
||||
.unwrap_or("");
|
||||
|
||||
// A missing reason is legitimate rather than unreadable, which is why this does not
|
||||
// share the `unknown` fallback the two fields above carry: every entry written
|
||||
// before `mv --reason` existed has none.
|
||||
let reason = content
|
||||
.lines()
|
||||
.find_map(|line| line.strip_prefix("**Reason**:"))
|
||||
.map(str::trim)
|
||||
.unwrap_or_default()
|
||||
.to_string();
|
||||
|
||||
Entry {
|
||||
filename: filename.to_string(),
|
||||
kind,
|
||||
author: field("Author"),
|
||||
time: field("Time"),
|
||||
body: body.to_string(),
|
||||
reason,
|
||||
}
|
||||
}
|
||||
|
||||
/// Every entry on a ticket, oldest first.
|
||||
///
|
||||
/// Public for the TUI's detail view, which shows the same sequence `show` does.
|
||||
pub fn read_history(board: &Path, uuid: &str) -> Result<Vec<Entry>> {
|
||||
adopt_comments(board)?;
|
||||
|
||||
let dir = history_dir(board, uuid);
|
||||
if !dir.exists() {
|
||||
return Ok(vec![]);
|
||||
}
|
||||
|
||||
let mut entries: Vec<Entry> = Vec::new();
|
||||
|
||||
for entry in fs::read_dir(&dir)? {
|
||||
let path = entry?.path();
|
||||
if path.extension().is_some_and(|ext| ext == "md") {
|
||||
let content = fs::read_to_string(&path)?;
|
||||
let filename = path
|
||||
.file_stem()
|
||||
.map(|stem| stem.to_string_lossy().to_string())
|
||||
.unwrap_or_default();
|
||||
entries.push(parse_entry(&filename, &content));
|
||||
}
|
||||
}
|
||||
|
||||
// The stamp is fixed width and leads the name, so this is chronological.
|
||||
entries.sort_by(|a, b| a.filename.cmp(&b.filename));
|
||||
|
||||
Ok(entries)
|
||||
}
|
||||
|
||||
/// The kind a filename names, which is what the count reads instead of the file.
|
||||
///
|
||||
/// A stem with no kind in it is a comment, the same compatibility [`parse_entry`] has.
|
||||
/// The collision suffix is a number and matches no slug, so it is skipped.
|
||||
fn kind_from_stem(stem: &str) -> Kind {
|
||||
stem.split('_')
|
||||
.find_map(|part| Kind::ALL.into_iter().find(|kind| kind.slug() == part))
|
||||
.unwrap_or(Kind::Comment)
|
||||
}
|
||||
|
||||
/// How many comments a ticket carries, counted off the directory rather than read.
|
||||
///
|
||||
/// Comments only, so the card's counter still says how many things somebody said: a
|
||||
/// ticket that has moved three times has not been talked about. `.md` only, the filter
|
||||
/// [`read_history`] applies, so a stray file dropped in there is not counted. A missing
|
||||
/// directory is none, which is what a ticket nothing has happened to has.
|
||||
pub fn count_comments(board: &Path, uuid: &str) -> usize {
|
||||
// Swallowed, unlike the reader's: a count is drawn on every card and a board that
|
||||
// cannot be adopted has to draw as the zero it looks like rather than take the TUI
|
||||
// down. The next write reports the real reason.
|
||||
let _ = adopt_comments(board);
|
||||
|
||||
let Ok(entries) = fs::read_dir(history_dir(board, uuid)) else {
|
||||
return 0;
|
||||
};
|
||||
|
||||
entries
|
||||
.filter_map(|entry| entry.ok())
|
||||
.filter(|entry| entry.path().extension().is_some_and(|ext| ext == "md"))
|
||||
.filter(|entry| {
|
||||
let stem = entry.path().file_stem().map(|s| s.to_string_lossy().to_string());
|
||||
stem.is_some_and(|stem| kind_from_stem(&stem) == Kind::Comment)
|
||||
})
|
||||
.count()
|
||||
}
|
||||
|
||||
/// The file an entry is written as.
|
||||
///
|
||||
/// A comment's file is byte for byte what `comment` wrote before the kinds existed, so
|
||||
/// nothing has to be rewritten and a board can be read by either version.
|
||||
///
|
||||
/// The optional reason rides after **Time**, so the two fields every entry has always
|
||||
/// carried keep their places and an older binary reading this file finds its body and
|
||||
/// fields exactly where they were. Empty writes no line, which is what keeps a reasoned
|
||||
/// entry and one without reading as the same shape minus the field.
|
||||
fn entry_content(kind: Kind, body: &str, author: &str, time: &str, reason: &str) -> String {
|
||||
let mut content = format!(
|
||||
"{}\n\
|
||||
{}\n\
|
||||
\n\
|
||||
**Author**: {}\n\
|
||||
**Time**: {}\n",
|
||||
kind.marker(),
|
||||
body,
|
||||
author,
|
||||
time
|
||||
);
|
||||
if !reason.is_empty() {
|
||||
content.push_str(&format!("**Reason**: {}\n", reason));
|
||||
}
|
||||
content
|
||||
}
|
||||
|
||||
/// Write an entry under the first free name derived from the stamp.
|
||||
///
|
||||
/// `create_new` rather than `fs::write`: a name that already exists means another entry
|
||||
/// landed in the same microsecond, and truncating it is exactly the data loss this
|
||||
/// guards against. The suffix is zero padded so the names keep sorting in the order they
|
||||
/// were written.
|
||||
fn write_new(dir: &Path, stem: &str, content: &str) -> Result<String> {
|
||||
for attempt in 0..100 {
|
||||
let filename = match attempt {
|
||||
0 => format!("{}.md", stem),
|
||||
n => format!("{}_{:02}.md", stem, n),
|
||||
};
|
||||
|
||||
match fs::OpenOptions::new()
|
||||
.write(true)
|
||||
.create_new(true)
|
||||
.open(dir.join(&filename))
|
||||
{
|
||||
Ok(mut file) => {
|
||||
file.write_all(content.as_bytes())?;
|
||||
return Ok(filename);
|
||||
}
|
||||
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
|
||||
Err(e) => return Err(e.into()),
|
||||
}
|
||||
}
|
||||
|
||||
Err(anyhow!("No free entry filename for '{}' in {}", stem, dir.display()))
|
||||
}
|
||||
|
||||
/// Record one entry on a ticket, returning the filename it landed under.
|
||||
///
|
||||
/// Called after the edit it describes has been written, never before: an entry for a
|
||||
/// move that was refused would be a log of things that did not happen. The cost of that
|
||||
/// order is that a failed write here leaves the edit in place and reports the failure,
|
||||
/// which is the right way round — the ticket is the record and this is the story of it.
|
||||
///
|
||||
/// `reason` is the why [`Kind::Status`] can carry, from `mv --reason`; every other kind
|
||||
/// passes the empty slice and gets no field written.
|
||||
pub fn write_entry(
|
||||
board: &Path,
|
||||
uuid: &str,
|
||||
kind: Kind,
|
||||
body: &str,
|
||||
author: &str,
|
||||
reason: &str,
|
||||
) -> Result<String> {
|
||||
adopt_comments(board)?;
|
||||
|
||||
let dir = history_dir(board, uuid);
|
||||
fs::create_dir_all(&dir)?;
|
||||
|
||||
let now = Local::now();
|
||||
let stem = format!("{}_{}", now.format(ENTRY_FILE_FORMAT), kind.slug());
|
||||
let content =
|
||||
entry_content(kind, body, author, &now.format(TIMESTAMP_FORMAT).to_string(), reason);
|
||||
|
||||
write_new(&dir, &stem, &content)
|
||||
}
|
||||
|
||||
/// What a mechanical entry records: the field before the edit and after it.
|
||||
///
|
||||
/// The values as the ticket holds them, sentinels included, so `_Not set_` reads the way
|
||||
/// the field it came from does rather than being translated into a word this module
|
||||
/// invented.
|
||||
pub fn change(before: &str, after: &str) -> String {
|
||||
format!("{} → {}", before, after)
|
||||
}
|
||||
|
||||
pub fn format_history(entries: &[Entry]) -> String {
|
||||
format_history_with(entries, should_use_colors())
|
||||
}
|
||||
|
||||
/// As above, with the colour decision passed in.
|
||||
pub fn format_history_with(entries: &[Entry], colored: bool) -> String {
|
||||
paint_cells(&history_cells(entries), colored)
|
||||
}
|
||||
|
||||
/// The block laid out once, as [`Cell`]s: the CLI paints them and the board turns the
|
||||
/// same ones into styled spans, so the two views cannot draw two different blocks.
|
||||
pub fn history_cells(entries: &[Entry]) -> Vec<Cell> {
|
||||
if entries.is_empty() {
|
||||
return vec![Cell::colored("No history yet.", Color::Grey)];
|
||||
}
|
||||
|
||||
let mut cells = Vec::new();
|
||||
cells.push(Cell::plain("\n"));
|
||||
cells.push(Cell::colored("HISTORY", Color::Orange));
|
||||
cells.push(Cell::plain(format!("\n{}\n", "─".repeat(20))));
|
||||
|
||||
for entry in entries {
|
||||
cells.push(Cell::plain("\n"));
|
||||
let stamp = format!("{} ({})", entry.author, entry.time);
|
||||
|
||||
match entry.kind {
|
||||
// As it has always read: a header naming who said it, then the text.
|
||||
Kind::Comment => {
|
||||
cells.push(Cell::colored(format!("From {}", stamp), Color::Cyan));
|
||||
cells.push(Cell::plain("\n"));
|
||||
if !entry.body.is_empty() {
|
||||
cells.push(Cell::plain(format!(" {}", entry.body)));
|
||||
}
|
||||
cells.push(Cell::plain("\n"));
|
||||
}
|
||||
// One line: a field change is one fact and a paragraph for it would bury the
|
||||
// comments it sits between. A reason grows an indented line under the row,
|
||||
// the way a comment's text sits under its From header, so it reads as
|
||||
// attached to the transition it explains rather than as the next entry.
|
||||
_ => {
|
||||
let padding = Kind::LABEL_WIDTH.saturating_sub(entry.kind.slug().chars().count());
|
||||
cells.push(Cell::colored(entry.kind.slug(), Color::Orange));
|
||||
cells.push(Cell::plain(format!("{} ", " ".repeat(padding))));
|
||||
cells.push(Cell::plain(entry.body.clone()));
|
||||
cells.push(Cell::plain(" "));
|
||||
cells.push(Cell::colored(stamp, Color::Cyan));
|
||||
cells.push(Cell::plain("\n"));
|
||||
if !entry.reason.is_empty() {
|
||||
cells.push(Cell::plain(format!(" {}", entry.reason)));
|
||||
cells.push(Cell::plain("\n"));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
cells
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::util::{Fixture, paint};
|
||||
|
||||
fn board() -> Fixture {
|
||||
Fixture::new("worklane-history")
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_entry_names_its_kind_in_the_file_and_in_the_filename() {
|
||||
let board = board();
|
||||
let filename =
|
||||
write_entry(&board, "uuid", Kind::Status, "committed → reviewing", "claude", "")
|
||||
.unwrap();
|
||||
|
||||
assert!(filename.ends_with("_status.md"), "was {filename}");
|
||||
|
||||
let entries = read_history(&board, "uuid").unwrap();
|
||||
assert_eq!(entries.len(), 1);
|
||||
assert_eq!(entries[0].kind, Kind::Status);
|
||||
assert_eq!(entries[0].body, "committed → reviewing");
|
||||
assert_eq!(entries[0].author, "claude");
|
||||
assert_eq!(entries[0].reason, "");
|
||||
}
|
||||
|
||||
/// One file, one event, its explanation: the reason rides in the entry that records
|
||||
/// the transition it explains, as a field after **Time**, and round-trips.
|
||||
#[test]
|
||||
fn a_reason_is_recorded_in_the_file_and_read_back() {
|
||||
let board = board();
|
||||
let filename = write_entry(
|
||||
&board,
|
||||
"uuid",
|
||||
Kind::Status,
|
||||
"reviewing → backlog",
|
||||
"claude",
|
||||
"sent back: the first plan was wrong",
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let content = fs::read_to_string(history_dir(&board, "uuid").join(filename)).unwrap();
|
||||
assert!(
|
||||
content.ends_with("**Reason**: sent back: the first plan was wrong\n"),
|
||||
"{content}"
|
||||
);
|
||||
// The fields every reader keys off keep their places above it
|
||||
assert!(content.contains("**Time**:"), "{content}");
|
||||
assert!(content.find("**Author**").unwrap() < content.find("**Reason**").unwrap());
|
||||
|
||||
let entries = read_history(&board, "uuid").unwrap();
|
||||
assert_eq!(entries.len(), 1);
|
||||
assert_eq!(entries[0].body, "reviewing → backlog");
|
||||
assert_eq!(entries[0].reason, "sent back: the first plan was wrong");
|
||||
}
|
||||
|
||||
/// The stamp leads the name and is fixed width, so the kind that follows it cannot
|
||||
/// reorder the log.
|
||||
#[test]
|
||||
fn the_kind_in_the_name_does_not_disturb_the_order() {
|
||||
let mut names = [
|
||||
"20260824_120000_000000_status",
|
||||
"20260824_115959_999999_tags",
|
||||
"20260824_120000_000001_comment",
|
||||
];
|
||||
names.sort();
|
||||
assert_eq!(
|
||||
names,
|
||||
[
|
||||
"20260824_115959_999999_tags",
|
||||
"20260824_120000_000000_status",
|
||||
"20260824_120000_000001_comment",
|
||||
]
|
||||
);
|
||||
}
|
||||
|
||||
/// A file written before the kinds existed: no marker, so it is the comment it was,
|
||||
/// and nothing rewrites it.
|
||||
#[test]
|
||||
fn an_entry_with_no_marker_is_a_comment() {
|
||||
let legacy = parse_entry(
|
||||
"20260820_143012_123456",
|
||||
"**Comment**\nSomething said\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n",
|
||||
);
|
||||
assert_eq!(legacy.kind, Kind::Comment);
|
||||
assert_eq!(legacy.body, "Something said");
|
||||
assert_eq!(legacy.author, "Ansho Rei");
|
||||
|
||||
// And one with no marker at all, which is what `read_comments` read as empty.
|
||||
let bare = parse_entry("20260820_143012_123457", "notes\n");
|
||||
assert_eq!(bare.kind, Kind::Comment);
|
||||
assert_eq!(bare.body, "");
|
||||
}
|
||||
|
||||
/// The comment file is byte for byte what `comment` wrote before this module, which
|
||||
/// is what lets an old board be read without a migration.
|
||||
#[test]
|
||||
fn a_comment_file_is_shaped_as_it_always_was() {
|
||||
let content = entry_content(Kind::Comment, "A body", "claude", "2026-08-24 12:00:00", "");
|
||||
assert_eq!(
|
||||
content,
|
||||
"**Comment**\nA body\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
|
||||
);
|
||||
}
|
||||
|
||||
/// Same microsecond, three entries: the guard is `create_new`, and the suffix keeps
|
||||
/// them in the order they were written.
|
||||
#[test]
|
||||
fn entries_in_one_microsecond_get_names_of_their_own() {
|
||||
let board = board();
|
||||
let dir = history_dir(&board, "uuid");
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
|
||||
let first = write_new(&dir, "20260820_143012_123456_comment", "first").unwrap();
|
||||
let second = write_new(&dir, "20260820_143012_123456_comment", "second").unwrap();
|
||||
let third = write_new(&dir, "20260820_143012_123456_comment", "third").unwrap();
|
||||
|
||||
assert_eq!(first, "20260820_143012_123456_comment.md");
|
||||
assert_eq!(second, "20260820_143012_123456_comment_01.md");
|
||||
assert_eq!(third, "20260820_143012_123456_comment_02.md");
|
||||
|
||||
// Nothing was truncated on the way through
|
||||
assert_eq!(fs::read_to_string(dir.join(&first)).unwrap(), "first");
|
||||
assert_eq!(fs::read_to_string(dir.join(&second)).unwrap(), "second");
|
||||
assert_eq!(fs::read_to_string(dir.join(&third)).unwrap(), "third");
|
||||
|
||||
// read_history sorts on the stem, so the names must sort in write order
|
||||
assert!(first < second && second < third, "the names lost their order");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_old_comments_directory_is_adopted_on_access() {
|
||||
let board = board();
|
||||
let comments = board.join(COMMENTS_DIR).join("uuid");
|
||||
fs::create_dir_all(&comments).unwrap();
|
||||
fs::write(
|
||||
comments.join("20260820_143012_123456.md"),
|
||||
"**Comment**\nOld news\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n",
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let entries = read_history(&board, "uuid").unwrap();
|
||||
assert_eq!(entries.len(), 1);
|
||||
assert_eq!(entries[0].body, "Old news");
|
||||
|
||||
assert!(!board.join(COMMENTS_DIR).exists(), "the old directory survived");
|
||||
assert!(history_dir(&board, "uuid").exists(), "the entries did not arrive");
|
||||
}
|
||||
|
||||
/// Refused rather than merged: only the CLI writes there, so this is a board somebody
|
||||
/// has been in by hand, and picking a survivor per name is not a silent decision.
|
||||
#[test]
|
||||
fn a_board_holding_both_directories_is_refused() {
|
||||
let board = board();
|
||||
fs::create_dir_all(board.join(COMMENTS_DIR).join("uuid")).unwrap();
|
||||
fs::create_dir_all(history_dir(&board, "uuid")).unwrap();
|
||||
|
||||
let refused = read_history(&board, "uuid");
|
||||
let message = refused.unwrap_err().to_string();
|
||||
assert!(
|
||||
message.contains(COMMENTS_DIR) && message.contains(HISTORY_DIR),
|
||||
"{message}"
|
||||
);
|
||||
}
|
||||
|
||||
/// The count is the card's, and a card counts what somebody said.
|
||||
#[test]
|
||||
fn only_comments_are_counted() {
|
||||
let board = board();
|
||||
write_entry(&board, "uuid", Kind::Comment, "said", "claude", "").unwrap();
|
||||
write_entry(&board, "uuid", Kind::Status, "backlog → committed", "claude", "").unwrap();
|
||||
write_entry(&board, "uuid", Kind::Owner, "_Not set_ → alice", "claude", "").unwrap();
|
||||
write_entry(&board, "uuid", Kind::Tags, "bug → bug, cli", "claude", "").unwrap();
|
||||
|
||||
assert_eq!(read_history(&board, "uuid").unwrap().len(), 4);
|
||||
assert_eq!(count_comments(&board, "uuid"), 1);
|
||||
}
|
||||
|
||||
/// A stem written before the kinds existed counts as the comment it is.
|
||||
#[test]
|
||||
fn a_legacy_name_counts_as_a_comment() {
|
||||
assert_eq!(kind_from_stem("20260820_143012_123456"), Kind::Comment);
|
||||
assert_eq!(kind_from_stem("20260820_143012_123456_01"), Kind::Comment);
|
||||
assert_eq!(kind_from_stem("20260820_143012_123456_status"), Kind::Status);
|
||||
assert_eq!(kind_from_stem("20260820_143012_123456_status_01"), Kind::Status);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_mechanical_entry_renders_as_one_line_and_a_comment_as_it_did() {
|
||||
let entries = vec![
|
||||
parse_entry(
|
||||
"20260824_120000_000000_status",
|
||||
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
|
||||
),
|
||||
parse_entry(
|
||||
"20260824_120001_000000_comment",
|
||||
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
|
||||
),
|
||||
];
|
||||
|
||||
let rendered = format_history_with(&entries, false);
|
||||
assert!(rendered.contains("HISTORY"), "{rendered}");
|
||||
assert!(
|
||||
rendered.contains("status committed → reviewing claude (2026-08-24 12:00:00)\n"),
|
||||
"{rendered}"
|
||||
);
|
||||
assert!(
|
||||
rendered
|
||||
.contains("From Ansho Rei (2026-08-24 12:00:01)\n The offset was never passed"),
|
||||
"{rendered}"
|
||||
);
|
||||
assert!(!rendered.contains('\x1b'), "colour off still painted: {rendered:?}");
|
||||
}
|
||||
|
||||
/// The pin for the cells conversion: `show` prints the block exactly as it printed
|
||||
/// it before, every painted run spelled out, the way
|
||||
/// `show_prints_the_same_body_it_printed_before_the_cells_conversion` pins the body.
|
||||
///
|
||||
/// Updated once since, deliberately: `campaign` widened the label column from 6 to
|
||||
/// 8, and the campaign row itself joined the pin (f774a33).
|
||||
#[test]
|
||||
fn show_prints_the_same_history_it_printed_before_the_cells_conversion() {
|
||||
let entries = vec![
|
||||
parse_entry(
|
||||
"20260824_120000_000000_status",
|
||||
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
|
||||
),
|
||||
parse_entry(
|
||||
"20260824_120001_000000_comment",
|
||||
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
|
||||
),
|
||||
parse_entry(
|
||||
"20260824_120002_000000_campaign",
|
||||
"**Campaign**\n_Not set_ → v1\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:02\n",
|
||||
),
|
||||
];
|
||||
|
||||
let expected = format!(
|
||||
"\n{}\n{}\n\n{} committed → reviewing {}\n\n{}\n The offset was never passed\n\n{} _Not set_ → v1 {}\n",
|
||||
paint("HISTORY", Color::Orange, true),
|
||||
"─".repeat(20),
|
||||
paint("status", Color::Orange, true),
|
||||
paint("claude (2026-08-24 12:00:00)", Color::Cyan, true),
|
||||
paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true),
|
||||
paint("campaign", Color::Orange, true),
|
||||
paint("claude (2026-08-24 12:00:02)", Color::Cyan, true),
|
||||
);
|
||||
|
||||
assert_eq!(format_history_with(&entries, true), expected);
|
||||
assert_eq!(format_history_with(&[], true), paint("No history yet.", Color::Grey, true));
|
||||
}
|
||||
|
||||
/// The reason is the row's, so it renders indented under the row it explains and
|
||||
/// before whatever entry follows, in both renderers — this is the one layout they
|
||||
/// share. Paired with the pin above: an entry without a reason renders exactly as
|
||||
/// it always did.
|
||||
#[test]
|
||||
fn a_reason_renders_indented_under_its_row() {
|
||||
let entries = vec![
|
||||
parse_entry(
|
||||
"20260824_120000_000000_status",
|
||||
"**Status**\nreviewing → backlog\n\n**Author**: claude\n**Time**: 2026-08-24 \
|
||||
12:00:00\n**Reason**: sent back, the first plan was wrong\n",
|
||||
),
|
||||
parse_entry(
|
||||
"20260824_120001_000000_comment",
|
||||
"**Comment**\nAnd why.\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
|
||||
),
|
||||
];
|
||||
|
||||
let expected = format!(
|
||||
"\n{}\n{}\n\n{} reviewing → backlog {}\n sent back, the first plan was wrong\n\n{}\n And why.\n",
|
||||
paint("HISTORY", Color::Orange, true),
|
||||
"─".repeat(20),
|
||||
paint("status", Color::Orange, true),
|
||||
paint("claude (2026-08-24 12:00:00)", Color::Cyan, true),
|
||||
paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true),
|
||||
);
|
||||
|
||||
assert_eq!(format_history_with(&entries, true), expected);
|
||||
assert!(
|
||||
format_history_with(&entries, false)
|
||||
.contains("claude (2026-08-24 12:00:00)\n sent back, the first plan was wrong"),
|
||||
"colour off lost the reason: {}",
|
||||
format_history_with(&entries, false)
|
||||
);
|
||||
}
|
||||
|
||||
/// Padded to the longest of the four, so every body starts in the same column
|
||||
/// however short the label above it is.
|
||||
#[test]
|
||||
fn the_mechanical_labels_are_aligned() {
|
||||
let bodies = [
|
||||
("status", "backlog → committed"),
|
||||
("owner", "_Not set_ → alice"),
|
||||
("tags", "bug → bug, cli"),
|
||||
("campaign", "v1 → beaver"),
|
||||
];
|
||||
let entries: Vec<Entry> = bodies
|
||||
.into_iter()
|
||||
.map(|(kind, body)| {
|
||||
let marker = format!("**{}{}**", kind[..1].to_uppercase(), &kind[1..]);
|
||||
parse_entry(
|
||||
&format!("20260824_120000_000000_{kind}"),
|
||||
&format!(
|
||||
"{marker}\n{body}\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
|
||||
),
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
|
||||
let rendered = format_history_with(&entries, false);
|
||||
let columns: Vec<usize> = bodies
|
||||
.into_iter()
|
||||
.map(|(_, body)| rendered.find(body).expect("body missing"))
|
||||
.map(|at| {
|
||||
let line_start = rendered[..at].rfind('\n').map_or(0, |nl| nl + 1);
|
||||
at - line_start
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(columns.len(), 4);
|
||||
assert!(columns.windows(2).all(|pair| pair[0] == pair[1]), "{rendered}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn nothing_recorded_says_so() {
|
||||
assert_eq!(format_history_with(&[], false), "No history yet.");
|
||||
}
|
||||
}
|
||||
+47
-1
@@ -69,11 +69,29 @@ pub const PLAN_SKILL: Asset = Asset {
|
||||
content: include_str!("../assets/PLAN.md"),
|
||||
};
|
||||
|
||||
/// The skill that sets a board up and puts one back together.
|
||||
///
|
||||
/// Its own document for the reason the two above are, and the split against `PLAN_SKILL`
|
||||
/// is the one worth stating: that document grooms the *work*, priorities and dates and
|
||||
/// campaigns, and this one configures the *board*, the tag vocabulary and the faults a
|
||||
/// board can develop. The tag section is where they meet, so each points at the other.
|
||||
///
|
||||
/// The one document that has to hold for a board that tracks no software at all. The other
|
||||
/// three describe a workflow that happens to be this repo's; a vocabulary skill written
|
||||
/// around `bug` and `cli` would teach nothing to a board tracking a household, so the
|
||||
/// examples in it deliberately span three subjects.
|
||||
pub const ADMIN_SKILL: Asset = Asset {
|
||||
name: "worklane-admin",
|
||||
what: "skill",
|
||||
relative: "worklane-admin/SKILL.md",
|
||||
content: include_str!("../assets/ADMIN.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; 3] = [SKILL, REVIEW_SKILL, PLAN_SKILL];
|
||||
pub static SKILLS: [Asset; 4] = [SKILL, REVIEW_SKILL, PLAN_SKILL, ADMIN_SKILL];
|
||||
|
||||
/// The opencode tool definitions, the second kind of asset this binary carries.
|
||||
///
|
||||
@@ -466,6 +484,34 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
/// What makes the admin document usable on a board that tracks no software, and what
|
||||
/// keeps its repairs honest.
|
||||
///
|
||||
/// The domain examples are the first thing an edit would quietly drop, since every
|
||||
/// other skill here is written around this repo, and dropping them leaves a document
|
||||
/// that teaches a household board to file `cli` tickets. The two-step repair is the
|
||||
/// second: it looks like a typo until you have watched `mv` refuse the one-step
|
||||
/// version, which is why the ticket for this skill demanded every repair be run rather
|
||||
/// than reasoned about.
|
||||
#[test]
|
||||
fn the_admin_skill_stays_domain_neutral_and_keeps_its_verified_repairs() {
|
||||
for required in [
|
||||
"household", // the vocabulary section spans three subjects
|
||||
"product strategy", //
|
||||
"worklane tags add", // the vocabulary is declared through the CLI
|
||||
"--tags` replaces the whole field", // the destructive one, restated where it bites
|
||||
"two moves, not one", // the repair `mv` cannot do in one step
|
||||
"do not edit a ticket file",
|
||||
"File exception", // and the three places that rule does not reach
|
||||
"worklane-plan", // the boundary against the sweep document
|
||||
] {
|
||||
assert!(
|
||||
ADMIN_SKILL.content.contains(required),
|
||||
"the admin 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
|
||||
|
||||
+47
-16
@@ -6,7 +6,9 @@ mod clipboard;
|
||||
mod command;
|
||||
mod completions;
|
||||
mod handlers;
|
||||
mod history;
|
||||
mod install;
|
||||
mod tag;
|
||||
mod tui;
|
||||
mod util;
|
||||
|
||||
@@ -55,15 +57,21 @@ fn main() -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_show(&id, &worklane_dir)
|
||||
}
|
||||
Some(Command::Mv { ticket, status, force }) => cmd_mv(&ticket, status, force, &start),
|
||||
Some(Command::Mv {
|
||||
ticket,
|
||||
status,
|
||||
force,
|
||||
actor,
|
||||
reason,
|
||||
}) => cmd_mv(&ticket, status, force, &actor, &reason, &start),
|
||||
Some(Command::Set(args)) => cmd_set(&args, &start),
|
||||
Some(Command::Append(args)) => cmd_append(&args, &start),
|
||||
Some(Command::Relate(args)) => cmd_relate(&args, &start),
|
||||
Some(Command::Chown(args)) => cmd_chown(&args, &start),
|
||||
Some(Command::Check(args)) => cmd_check(&args, true, &start),
|
||||
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start),
|
||||
Some(Command::Comment { ticket, body, owner }) => {
|
||||
cmd_comment(&ticket, &body, &owner, &start)
|
||||
Some(Command::Comment { ticket, body, actor }) => {
|
||||
cmd_comment(&ticket, &body, &actor, &start)
|
||||
}
|
||||
Some(Command::Campaign { command }) => match command {
|
||||
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start),
|
||||
@@ -72,16 +80,26 @@ fn main() -> Result<()> {
|
||||
cmd_campaign_ls(&worklane_dir, ids)
|
||||
}
|
||||
CampaignCommand::Set(args) => cmd_campaign_set(&args, &start),
|
||||
CampaignCommand::Append(args) => cmd_campaign_append(&args, &start),
|
||||
CampaignCommand::Show { campaign } => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_campaign_show(&campaign, &worklane_dir)
|
||||
}
|
||||
},
|
||||
Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start),
|
||||
Some(Command::Tags) => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_tags(&worklane_dir)
|
||||
Some(Command::Assign { campaign, ticket, actor }) => {
|
||||
cmd_assign(&campaign, &ticket, &actor, &start)
|
||||
}
|
||||
// The bare form and `ls` are one arm: `worklane tags` was the listing before the
|
||||
// group existed and the fish completion still calls it that way, so the two
|
||||
// spellings cannot be allowed to drift into two behaviours.
|
||||
Some(Command::Tags { command }) => match command {
|
||||
None | Some(TagCommand::Ls) => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_tags(&worklane_dir)
|
||||
}
|
||||
Some(TagCommand::Add(args)) => cmd_tag_add(&args, &start),
|
||||
Some(TagCommand::Set(args)) => cmd_tag_set(&args, &start),
|
||||
},
|
||||
// No board either, for the reason `install-skill` has none: a completion script
|
||||
// is generated from the clap definition and is the same wherever it is run.
|
||||
Some(Command::Completions { shell }) => {
|
||||
@@ -202,27 +220,36 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
|
||||
board.should_quit = true
|
||||
}
|
||||
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_detail(),
|
||||
// The frame's own height while it holds the selection, and the detail
|
||||
// overlay on a card. `Board::toggle_focused` rather than a condition here,
|
||||
// for the reason the scroll keys route there.
|
||||
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_focused(screen),
|
||||
KeyCode::Left | KeyCode::Char('h') => board.select_column(-1, screen),
|
||||
KeyCode::Right | KeyCode::Char('l') => board.select_column(1, screen),
|
||||
// Up and down stay on the selection, open detail view or not, so a
|
||||
// column can be read through without closing the modal. Scrolling the
|
||||
// open ticket is a page at a time.
|
||||
// open ticket is a page at a time, and so is scrolling the campaign
|
||||
// frame that up reaches from the top card of a column.
|
||||
KeyCode::Up | KeyCode::Char('k') => board.select_card(-1, screen),
|
||||
KeyCode::Down | KeyCode::Char('j') => board.select_card(1, screen),
|
||||
KeyCode::PageUp => board.scroll_detail(-1, screen),
|
||||
KeyCode::PageDown => board.scroll_detail(1, screen),
|
||||
// The open ticket first and the campaign frame behind it, which is
|
||||
// `Board::scroll_page` rather than a condition written here: the arms in
|
||||
// this dispatch are not reachable from a test.
|
||||
KeyCode::PageUp => board.scroll_page(-1, screen),
|
||||
KeyCode::PageDown => board.scroll_page(1, screen),
|
||||
// Tabs cycle rather than clamp, the way tabs everywhere do, and are
|
||||
// a no-op with a single board. Free of every other binding: the
|
||||
// columns took hjkl and the arrows.
|
||||
KeyCode::Tab => board.select_tab(1, screen),
|
||||
KeyCode::BackTab => board.select_tab(-1, screen),
|
||||
// Free of the other bindings, and the footer names it in both states.
|
||||
KeyCode::Char('d') => board.toggle_done(screen),
|
||||
// Free of the other bindings, and the footer names what the next press
|
||||
// does in every state of the rotation.
|
||||
KeyCode::Char('d') => board.rotate_visibility(screen),
|
||||
// An ordinary single-shot action like the rest: it opens the prompt, and
|
||||
// from the next keypress on `search_key` above has the keyboard. A `/`
|
||||
// typed into an open prompt is taken there as a character, so this arm
|
||||
// is only ever the way in.
|
||||
// typed into an open prompt is taken there as a character, and one pressed
|
||||
// at an open picker is taken by `picker_key` to open the picker's own
|
||||
// query, so this arm is only ever the way in to the board's prompt.
|
||||
KeyCode::Char('/') => board.open_search(),
|
||||
// `y` as in yank, for the readers this board is for, and the only letter
|
||||
// left that a vim hand would reach for. The clipboard is handed in rather
|
||||
@@ -231,7 +258,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),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
+361
@@ -0,0 +1,361 @@
|
||||
//! The tag vocabulary: which tags the board declares, and what each one means.
|
||||
//!
|
||||
//! One file, `.worklane/tags.md`, beside the status directories rather than among them,
|
||||
//! for the reason the campaigns directory sits there: a tag has no status. One section
|
||||
//! per tag, the tag as the heading and its annotation as the prose under it, so the file
|
||||
//! reads as a document to whoever opens it and parses by heading to the CLI.
|
||||
//!
|
||||
//! **Declaring a tag tags no ticket, and tagging a ticket declares nothing.** This is a
|
||||
//! vocabulary and not an index of what carries what: the counts stay derived from the
|
||||
//! status directories, where `cmd_tags` already reads them. So the file and the board can
|
||||
//! disagree, and that disagreement is the point — a tag carried but never declared is a
|
||||
//! word nobody agreed to, which is what `campaign` and `campaigns` on this board were.
|
||||
//!
|
||||
//! Unlike a campaign, a tag has no uuid and no file of its own. It *is* its name, which is
|
||||
//! what `ls --tag` matches whole and case sensitively, so the name is the key here and
|
||||
//! there is nothing to resolve by prefix.
|
||||
|
||||
use anyhow::{Result, anyhow};
|
||||
use std::collections::BTreeMap;
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use crate::util::trim_blank_ends;
|
||||
|
||||
/// The vocabulary file, beside the status directories rather than among them.
|
||||
pub const TAGS_FILE: &str = "tags.md";
|
||||
|
||||
pub fn tags_path(worklane_dir: &Path) -> PathBuf {
|
||||
worklane_dir.join(TAGS_FILE)
|
||||
}
|
||||
|
||||
/// What one tag's heading looks like, and therefore what an annotation may not start a
|
||||
/// line with.
|
||||
///
|
||||
/// Public so the `--annotation` parser refuses the one line that would split a section,
|
||||
/// rather than carrying its own copy of the spelling. Two places knowing what a heading
|
||||
/// is, is how the file comes to be written in a shape it cannot be read back in.
|
||||
pub const SECTION: &str = "## ";
|
||||
|
||||
/// What a tag declared with nothing to say about it writes.
|
||||
///
|
||||
/// A placeholder rather than an empty section, for the reason `add` writes one into an
|
||||
/// empty Description: a heading with nothing under it reads as a file that failed to
|
||||
/// write, and the round trip has nothing to be right about.
|
||||
pub const NO_ANNOTATION: &str = "_No annotation provided._";
|
||||
|
||||
/// The heading the file opens with. Not a tag: [`tag_heading`] only reads level two.
|
||||
const TITLE: &str = "# Tags";
|
||||
|
||||
/// What the file says for itself, for whoever opens it rather than for the parser.
|
||||
///
|
||||
/// Re-rendered on every write, so it is present whether `init` made the file or
|
||||
/// `tags add` did. It says what declaring does and does not do, because the file's one
|
||||
/// real trap is reading it as the list of tags in use.
|
||||
const PREAMBLE: &str = "\
|
||||
What each tag on this board means, and when it is appropriate to reach for it. Declaring a
|
||||
tag here tags nothing: the counts come from the tickets themselves, and `worklane tags` is
|
||||
what reports them. Written by `worklane tags`, not by hand.";
|
||||
|
||||
/// The tag a level-two heading names, or nothing for any other line.
|
||||
///
|
||||
/// Exactly two hashes. A `### ` line inside an annotation is prose about the tag it sits
|
||||
/// under and not the start of another one, which a bare `strip_prefix` would read as a tag
|
||||
/// called `# something`.
|
||||
fn tag_heading(line: &str) -> Option<&str> {
|
||||
let rest = line.strip_prefix(SECTION)?;
|
||||
|
||||
match rest.starts_with('#') {
|
||||
true => None,
|
||||
false => Some(rest.trim()),
|
||||
}
|
||||
}
|
||||
|
||||
/// The board's declared tags, each with what it means.
|
||||
///
|
||||
/// A `BTreeMap` rather than a `Vec`: the order is alphabetical by byte, which is the order
|
||||
/// `cmd_tags` already prints in, so `Bug` and `bug` stay two entries and land next to each
|
||||
/// other. Near-duplicates being adjacent is the property the whole file is for.
|
||||
///
|
||||
/// An annotation of `""` is a tag declared with nothing said about it, which is why the
|
||||
/// placeholder is a rendering detail rather than a value anything holds.
|
||||
#[derive(Default)]
|
||||
pub struct TagIndex {
|
||||
tags: BTreeMap<String, String>,
|
||||
}
|
||||
|
||||
impl TagIndex {
|
||||
/// The vocabulary as the file declares it.
|
||||
///
|
||||
/// A missing file is an empty vocabulary and not an error: every board made before this
|
||||
/// existed has none, and refusing there would mean a `worklane init` over a live board
|
||||
/// just to get a file.
|
||||
///
|
||||
/// An *unreadable* file is an error, which is the opposite of what [`CampaignIndex`]
|
||||
/// does with its directory, and deliberately. The whole file is re-rendered on every
|
||||
/// write, so treating one that is there as empty would erase every tag in it on the
|
||||
/// next `tags add`. A campaign index that comes back empty loses a label on a card;
|
||||
/// this one would lose the file.
|
||||
///
|
||||
/// [`CampaignIndex`]: crate::campaign::CampaignIndex
|
||||
pub fn load(worklane_dir: &Path) -> Result<Self> {
|
||||
let path = tags_path(worklane_dir);
|
||||
|
||||
if !path.exists() {
|
||||
return Ok(Self::default());
|
||||
}
|
||||
|
||||
let content = fs::read_to_string(&path).map_err(|e| {
|
||||
anyhow!("Could not read the tag vocabulary at {}: {}", path.display(), e)
|
||||
})?;
|
||||
|
||||
Ok(Self::parse(&content))
|
||||
}
|
||||
|
||||
/// The vocabulary out of the file's text.
|
||||
///
|
||||
/// Everything above the first tag heading is prose for whoever opens the file and is
|
||||
/// dropped: the title, the preamble, and anything else that ended up there. A heading
|
||||
/// with no tag in it starts nothing, and the lines under it belong to no tag, so a
|
||||
/// damaged file loses that section rather than attaching it to the tag above.
|
||||
pub fn parse(content: &str) -> Self {
|
||||
let mut tags = BTreeMap::new();
|
||||
let mut open: Option<(String, Vec<String>)> = None;
|
||||
|
||||
for line in content.lines() {
|
||||
match tag_heading(line) {
|
||||
Some(tag) => {
|
||||
if let Some((held, body)) = open.take() {
|
||||
tags.insert(held, annotation(&body));
|
||||
}
|
||||
if !tag.is_empty() {
|
||||
open = Some((tag.to_string(), Vec::new()));
|
||||
}
|
||||
}
|
||||
None => {
|
||||
if let Some((_, body)) = &mut open {
|
||||
body.push(line.to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if let Some((held, body)) = open {
|
||||
tags.insert(held, annotation(&body));
|
||||
}
|
||||
|
||||
Self { tags }
|
||||
}
|
||||
|
||||
/// Whether the file already declares this tag, matched whole and case sensitively, the
|
||||
/// way `ls --tag` matches it.
|
||||
pub fn declared(&self, tag: &str) -> bool {
|
||||
self.tags.contains_key(tag)
|
||||
}
|
||||
|
||||
/// Every tag the file declares, alphabetical, whatever the board carries.
|
||||
///
|
||||
/// The half of the listing the status directories cannot answer. A tag declared and
|
||||
/// never applied is carried by no ticket, so counting alone drops it, and that tag is
|
||||
/// most of the reason the file exists: a word the board agreed on and nobody has
|
||||
/// reached for yet is exactly what a grooming sweep wants to see.
|
||||
pub fn names(&self) -> impl Iterator<Item = &str> {
|
||||
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
|
||||
/// [`CampaignRow::summary`] takes one line off a description the read carries whole:
|
||||
/// the annotation is prose with paragraphs in it, and which view wants how much of it
|
||||
/// is the view's business.
|
||||
///
|
||||
/// **`None` is what marks a carried but undeclared tag**, since `cmd_tags` prints no
|
||||
/// third field for it. Nothing is appended to the tag itself and nothing is added to
|
||||
/// the count, so `cut -f1` still yields the tag values and a board with no file at all
|
||||
/// lists what it listed before the file existed.
|
||||
///
|
||||
/// A declared tag with nothing said about it answers [`NO_ANNOTATION`] rather than an
|
||||
/// empty string, because an empty third field is a trailing tab and nothing else: it
|
||||
/// would be the only difference between declared and not, and it would be invisible in
|
||||
/// a terminal and in a completion alike. The placeholder is also what the file itself
|
||||
/// holds under that heading, so the field stays the section's opening line either way.
|
||||
///
|
||||
/// [`CampaignRow::summary`]: crate::tui::CampaignRow::summary
|
||||
/// [`NO_ANNOTATION`]: crate::tag::NO_ANNOTATION
|
||||
pub fn summary(&self, tag: &str) -> Option<&str> {
|
||||
let annotation = self.tags.get(tag)?;
|
||||
|
||||
Some(match annotation.lines().next() {
|
||||
Some(line) => line,
|
||||
None => NO_ANNOTATION,
|
||||
})
|
||||
}
|
||||
|
||||
/// Declare `tag`, or replace what it means.
|
||||
///
|
||||
/// One writer for both, because the file holds one section per tag either way and the
|
||||
/// question of whether a caller may overwrite is the caller's: `tags add` refuses a tag
|
||||
/// already declared, and `tags set` refuses one that is not.
|
||||
pub fn declare(&mut self, tag: &str, annotation: &str) {
|
||||
self.tags.insert(tag.to_string(), annotation.to_string());
|
||||
}
|
||||
|
||||
/// The whole file, rendered from the whole vocabulary.
|
||||
///
|
||||
/// Every write goes through here rather than splicing one section in place, which is
|
||||
/// what keeps the file canonical: alphabetical, one blank line between sections, and
|
||||
/// the preamble present however the file came to exist. The cost is that nothing
|
||||
/// hand-written above the first heading survives a write, which is the bargain every
|
||||
/// file under `.worklane/` already makes — the CLI is its only writer.
|
||||
pub fn render(&self) -> String {
|
||||
let mut out = format!("{TITLE}\n\n{PREAMBLE}\n");
|
||||
|
||||
for (tag, annotation) in &self.tags {
|
||||
let body = match annotation.is_empty() {
|
||||
true => NO_ANNOTATION,
|
||||
false => annotation,
|
||||
};
|
||||
out.push_str(&format!("\n{SECTION}{tag}\n{body}\n"));
|
||||
}
|
||||
|
||||
out
|
||||
}
|
||||
}
|
||||
|
||||
/// One section's prose, with the blank lines around it dropped and the placeholder read
|
||||
/// back as nothing.
|
||||
///
|
||||
/// Through `trim_blank_ends`, the same function that decides where a ticket's description
|
||||
/// starts and ends, so a blank line inside an annotation is kept and one at either end is
|
||||
/// not.
|
||||
fn annotation(body: &[String]) -> String {
|
||||
let text = trim_blank_ends(body).join("\n");
|
||||
|
||||
match text == NO_ANNOTATION {
|
||||
true => String::new(),
|
||||
false => text,
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// What a tag holds, read back out of the file it was written into. The round trip is
|
||||
/// the property that matters: nothing else keeps the writer and the parser agreeing on
|
||||
/// what a section is.
|
||||
fn round_trip(tag: &str, annotation: &str) -> String {
|
||||
let mut index = TagIndex::default();
|
||||
index.declare(tag, annotation);
|
||||
|
||||
let read = TagIndex::parse(&index.render());
|
||||
read.tags
|
||||
.get(tag)
|
||||
.cloned()
|
||||
.expect("the tag did not survive the round trip")
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_annotation_survives_the_round_trip() {
|
||||
assert_eq!(
|
||||
round_trip("bug", "Something the binary does wrong."),
|
||||
"Something the binary does wrong."
|
||||
);
|
||||
}
|
||||
|
||||
/// A blank line inside an annotation is a paragraph break and is kept, which is what
|
||||
/// `trim_blank_ends` is doing here rather than a blanket trim.
|
||||
#[test]
|
||||
fn a_paragraph_break_inside_an_annotation_is_kept() {
|
||||
assert_eq!(round_trip("bug", "One.\n\nTwo."), "One.\n\nTwo.");
|
||||
}
|
||||
|
||||
/// A tag declared with nothing to say writes the placeholder and reads back as nothing,
|
||||
/// so the file never holds a heading with a blank under it and nothing ever holds the
|
||||
/// placeholder as if it were prose.
|
||||
#[test]
|
||||
fn a_tag_with_no_annotation_writes_the_placeholder_and_reads_back_empty() {
|
||||
let mut index = TagIndex::default();
|
||||
index.declare("cli", "");
|
||||
|
||||
let rendered = index.render();
|
||||
assert!(rendered.contains(NO_ANNOTATION), "{rendered}");
|
||||
assert_eq!(TagIndex::parse(&rendered).tags["cli"], "");
|
||||
}
|
||||
|
||||
/// Byte order, so `Bug` and `bug` are two tags and sit next to each other. The same
|
||||
/// order `tags` prints in, and the reason the file is worth reading at all: a
|
||||
/// near-duplicate is spotted by being adjacent to what it duplicates.
|
||||
#[test]
|
||||
fn the_file_is_alphabetical_and_keeps_case_apart() {
|
||||
let mut index = TagIndex::default();
|
||||
for tag in ["tui", "bug", "Bug", "cli"] {
|
||||
index.declare(tag, "");
|
||||
}
|
||||
|
||||
let rendered = index.render();
|
||||
let headings: Vec<&str> = rendered.lines().filter_map(tag_heading).collect();
|
||||
assert_eq!(headings, vec!["Bug", "bug", "cli", "tui"]);
|
||||
}
|
||||
|
||||
/// Everything above the first heading is for whoever opens the file. The preamble says
|
||||
/// `## ` nowhere, but a parser that took the title for a tag would declare one called
|
||||
/// `Tags` on the next write.
|
||||
#[test]
|
||||
fn the_prose_above_the_first_heading_declares_nothing() {
|
||||
let index = TagIndex::parse(&TagIndex::default().render());
|
||||
assert!(index.tags.is_empty(), "the preamble declared a tag");
|
||||
}
|
||||
|
||||
/// A deeper heading is prose about the tag it sits under. `strip_prefix` alone read it
|
||||
/// as a tag called `# whatever`, which then became a real section on the next write.
|
||||
#[test]
|
||||
fn a_deeper_heading_inside_an_annotation_is_not_a_tag() {
|
||||
let index = TagIndex::parse("# Tags\n\n## bug\nProse.\n\n### An aside\nMore prose.\n");
|
||||
|
||||
assert_eq!(index.tags.len(), 1, "a sub-heading was read as a tag");
|
||||
assert_eq!(index.tags["bug"], "Prose.\n\n### An aside\nMore prose.");
|
||||
}
|
||||
|
||||
/// A heading naming nothing starts no section, and takes the lines under it with it
|
||||
/// rather than attaching them to the tag above.
|
||||
#[test]
|
||||
fn an_empty_heading_declares_nothing_and_swallows_its_own_body() {
|
||||
let index = TagIndex::parse("## bug\nProse.\n\n## \nOrphaned.\n");
|
||||
|
||||
assert_eq!(index.tags.len(), 1);
|
||||
assert_eq!(index.tags["bug"], "Prose.");
|
||||
}
|
||||
|
||||
/// A board that never had the file has an empty vocabulary rather than an error: every
|
||||
/// board made before this existed is in that state.
|
||||
#[test]
|
||||
fn a_board_with_no_file_has_no_tags() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
assert!(TagIndex::load(dir.path()).unwrap().tags.is_empty());
|
||||
}
|
||||
|
||||
/// And a file that is there but cannot be read is an error, not an empty vocabulary.
|
||||
/// The whole file is re-rendered on every write, so empty here would mean erased on the
|
||||
/// next `tags add`.
|
||||
#[test]
|
||||
fn a_file_that_cannot_be_read_is_an_error_rather_than_an_empty_vocabulary() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
// A directory where the file should be: `read_to_string` fails on it, which a
|
||||
// missing file does not, so this is the path the error is actually for.
|
||||
fs::create_dir(tags_path(dir.path())).unwrap();
|
||||
|
||||
assert!(TagIndex::load(dir.path()).is_err());
|
||||
}
|
||||
}
|
||||
+3848
-440
File diff suppressed because it is too large
Load Diff
+825
-283
File diff suppressed because it is too large
Load Diff
+485
-5
@@ -1129,11 +1129,13 @@ fn an_unknown_campaign_is_refused_and_nothing_is_written() {
|
||||
);
|
||||
}
|
||||
|
||||
/// No `--description`: `set` and `append` are a pair for a prose section, and a way to
|
||||
/// replace a description with no way to add a paragraph is half of it. Pinned so the
|
||||
/// omission stays a decision rather than becoming an oversight somebody fills in.
|
||||
/// `--description` arrived with `campaign append`, 32e98ab, because for a prose section the
|
||||
/// two are a pair. What is still deliberately absent is what this pins: no `--owner`, which
|
||||
/// would settle by accident whether `chown` grows a campaign, and no `--clear`, because a
|
||||
/// campaign's description has no cleared form and `Clearable`'s variants are a ticket's
|
||||
/// fields.
|
||||
#[test]
|
||||
fn campaign_set_offers_no_description_and_no_owner() {
|
||||
fn campaign_set_offers_no_owner_and_no_clear() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
@@ -1142,7 +1144,7 @@ fn campaign_set_offers_no_description_and_no_owner() {
|
||||
|
||||
assert!(help.contains("--codename"), "{help}");
|
||||
assert!(help.contains("--title"), "{help}");
|
||||
assert!(!help.contains("--description"), "{help}");
|
||||
assert!(help.contains("--description"), "{help}");
|
||||
assert!(!help.contains("--owner"), "{help}");
|
||||
assert!(!help.contains("--clear"), "{help}");
|
||||
}
|
||||
@@ -1263,3 +1265,481 @@ fn the_title_is_replaced_without_force() {
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).starts_with("# First public release\n"));
|
||||
}
|
||||
|
||||
// ---------------------------------------------- campaign set --description --
|
||||
|
||||
/// The point of 32e98ab: the description a campaign was filed with is no longer the one it
|
||||
/// keeps. `create_campaign` writes prose, so this is a replacement rather than a first line.
|
||||
#[test]
|
||||
fn campaign_set_replaces_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"--description",
|
||||
"What the tag has to hold.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("Updated description"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("What the tag has to hold."), "{content}");
|
||||
assert!(
|
||||
!content.contains("What has to ship together."),
|
||||
"the old description survived: {content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// An empty value between two others is the paragraph break, the rule every prose argument
|
||||
/// in the tool follows: `add --description`, `set --description` and `tags --annotation`.
|
||||
#[test]
|
||||
fn an_empty_value_is_a_paragraph_break_in_a_campaigns_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"The tag itself.",
|
||||
"-d",
|
||||
"",
|
||||
"-d",
|
||||
"And what blocks it.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("The tag itself.\n\nAnd what blocks it."), "{content}");
|
||||
}
|
||||
|
||||
/// And an all-blank value is refused rather than emptying the section. The refusal names no
|
||||
/// flag, because there is none: a campaign's description has no cleared form, which is the
|
||||
/// `Clearable` question 32e98ab settled rather than deferred.
|
||||
#[test]
|
||||
fn an_all_blank_description_is_refused_and_names_no_clear_flag() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "-d", "", "-d", " "]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
let said = stderr(&out);
|
||||
assert!(said.contains("An empty value is a paragraph break"), "{said}");
|
||||
assert!(said.contains("no cleared form"), "{said}");
|
||||
assert!(!said.contains("--clear"), "it named a flag that does not exist: {said}");
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written");
|
||||
}
|
||||
|
||||
/// The whole-file comparison `set`, `chown` and the codename already use, so a description
|
||||
/// replaced with the one it already holds writes nothing.
|
||||
#[test]
|
||||
fn setting_the_description_a_campaign_already_has_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"What has to ship together.",
|
||||
],
|
||||
);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was rewritten");
|
||||
}
|
||||
|
||||
/// Three fields in one call, since the group is `multiple` and the description is in it.
|
||||
#[test]
|
||||
fn campaign_set_takes_the_title_the_description_and_the_codename_together() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-t",
|
||||
"First public release",
|
||||
"-d",
|
||||
"What the tag has to hold.",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("title, description, codename"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.starts_with("# First public release\n"), "{content}");
|
||||
assert!(content.contains("What the tag has to hold."), "{content}");
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
}
|
||||
|
||||
/// A refused codename takes the description down with it, the way it already takes the
|
||||
/// title: checked before any edit is applied, so a call writes all of what it asked for or
|
||||
/// none of it.
|
||||
#[test]
|
||||
fn a_refused_codename_takes_the_description_down_with_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1",
|
||||
"-d",
|
||||
"Rewritten anyway.",
|
||||
"-c",
|
||||
"beaver",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the description went through");
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------- campaign append --
|
||||
|
||||
/// The other half of the pair, and the reason `set --description` is not a flag on its own:
|
||||
/// adding a line to a description must not mean retyping the rest of it.
|
||||
#[test]
|
||||
fn campaign_append_adds_a_paragraph_without_replacing_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"And what is out of scope.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("Appended to description"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
// The paragraph lands after the one that was there, with the blank line between them
|
||||
// that makes it a paragraph rather than a run-on.
|
||||
assert!(
|
||||
content.contains("What has to ship together.\n\nAnd what is out of scope.\n"),
|
||||
"{content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Several values in one call are lines *within* the paragraph, not several paragraphs. The
|
||||
/// same reading `append --description` gives a ticket, since it is the same section entry.
|
||||
#[test]
|
||||
fn the_values_of_one_append_are_lines_within_the_paragraph() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"Out of scope:",
|
||||
"-d",
|
||||
"the installer.",
|
||||
],
|
||||
);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("Out of scope:\nthe installer.\n"), "{content}");
|
||||
}
|
||||
|
||||
/// A campaign filed with no description holds the placeholder, and appending replaces it
|
||||
/// rather than following it: the alternative reads `_No description provided._` above the
|
||||
/// description. `append_section_body`'s rule, so nothing here handles the case.
|
||||
#[test]
|
||||
fn appending_to_an_empty_description_replaces_the_placeholder() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "add", "--title", "No prose yet"]);
|
||||
|
||||
let uuid = {
|
||||
let names = campaigns(&worklane);
|
||||
let name = names
|
||||
.iter()
|
||||
.find(|name| name.ends_with("_no-prose-yet.md"))
|
||||
.expect("the campaign was not filed");
|
||||
name.split('_').next().unwrap().to_string()
|
||||
};
|
||||
assert!(
|
||||
campaign_file(&worklane, &uuid).contains("_No description provided._"),
|
||||
"the placeholder is not what add writes any more"
|
||||
);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"No prose yet",
|
||||
"-d",
|
||||
"The first thing said.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let content = campaign_file(&worklane, &uuid);
|
||||
assert!(content.contains("The first thing said."), "{content}");
|
||||
assert!(
|
||||
!content.contains("_No description provided._"),
|
||||
"the placeholder is still above the description: {content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Every value blank is refused rather than writing nothing quietly, the answer `append`
|
||||
/// gives a ticket, in the same words: appending nothing was never a way to empty anything,
|
||||
/// so there is no flag to name.
|
||||
#[test]
|
||||
fn an_all_blank_append_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "v1 release", "-d", " "]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("Nothing to append"), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written");
|
||||
}
|
||||
|
||||
/// A bare `campaign append <campaign>` is a usage error rather than a silent no-op, the way
|
||||
/// a bare `campaign set` is. `--description` is `required` rather than a group of one.
|
||||
#[test]
|
||||
fn campaign_append_with_no_description_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "v1 release"]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written");
|
||||
}
|
||||
|
||||
/// Appending to a scalar has no meaning, which is the line `append` already draws for a
|
||||
/// ticket: no `--title` there and none here, and no `--codename` either.
|
||||
#[test]
|
||||
fn campaign_append_offers_only_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "--help"]);
|
||||
let help = stdout(&out);
|
||||
|
||||
assert!(help.contains("--description"), "{help}");
|
||||
assert!(!help.contains("--title"), "{help}");
|
||||
assert!(!help.contains("--codename"), "{help}");
|
||||
assert!(!help.contains("--force"), "{help}");
|
||||
}
|
||||
|
||||
/// A campaign is addressed here by the same tiers everything else takes, codename included,
|
||||
/// because it goes through `resolve_campaign` rather than a lookup of its own.
|
||||
#[test]
|
||||
fn campaign_append_resolves_the_campaign_by_its_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "beaver"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "beaver", "-d", "One more thing."]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
campaign_file(&worklane, CAMP_A).contains("One more thing."),
|
||||
"{}",
|
||||
campaign_file(&worklane, CAMP_A)
|
||||
);
|
||||
}
|
||||
|
||||
/// An unknown campaign leaves every campaign alone, the answer `campaign set` and `assign`
|
||||
/// already give.
|
||||
#[test]
|
||||
fn campaign_append_refuses_an_unknown_campaign() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "nothing-by-that-name", "-d", "Text."]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("No campaign found"), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written");
|
||||
}
|
||||
|
||||
// ------------------------------------------------------ the shared machinery --
|
||||
|
||||
/// A campaign has one section where a ticket has four, and the section table in `util.rs` is
|
||||
/// what both go through. So the surgery has to land against `## Metadata`, which is the only
|
||||
/// heading that follows a campaign's description, and leave everything outside the body
|
||||
/// alone: a handwritten section, the owner, and the codename in its place.
|
||||
#[test]
|
||||
fn the_description_is_edited_in_place_in_a_file_with_one_section() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let original = fs::read_to_string(&path).unwrap();
|
||||
fs::write(
|
||||
&path,
|
||||
original.replace("## Metadata", "## Notes\nA handwritten note.\n\n## Metadata"),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
run(&temp, &["campaign", "set", "v1", "-d", "Replaced."]);
|
||||
run(&temp, &["campaign", "append", "v1", "-d", "Added."]);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("## Description\nReplaced.\n\nAdded.\n"), "{content}");
|
||||
// Nothing outside the body moved: the section that follows it, the handwritten one
|
||||
// between them, and the fields under it.
|
||||
assert!(content.contains("## Notes\nA handwritten note."), "{content}");
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
assert!(content.contains("- **Owner**: alice"), "{content}");
|
||||
assert!(!content.contains("**Status**"), "a status was invented: {content}");
|
||||
// And no section a campaign does not have was inserted to anchor against.
|
||||
assert!(!content.contains("## Acceptance Criteria"), "{content}");
|
||||
assert!(!content.contains("## Implementation Plan"), "{content}");
|
||||
}
|
||||
|
||||
/// The heading is the one in the section table, so `campaign set --description` reaches the
|
||||
/// section `campaign_body` wrote and `campaign show` prints. A second spelling scoped to
|
||||
/// campaigns is what this would catch.
|
||||
#[test]
|
||||
fn the_description_a_campaign_is_filed_with_is_the_one_set_replaces() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"Filed with prose",
|
||||
"--description",
|
||||
"As filed.",
|
||||
],
|
||||
);
|
||||
run(&temp, &["campaign", "set", "Filed with prose", "-d", "As replaced."]);
|
||||
|
||||
let out = run(&temp, &["campaign", "show", "Filed with prose"]);
|
||||
let shown = stdout(&out);
|
||||
assert!(shown.contains("As replaced."), "{shown}");
|
||||
assert!(!shown.contains("As filed."), "{shown}");
|
||||
// One Description heading in the file, not a second one written beside it.
|
||||
let names = campaigns(&worklane);
|
||||
let name = names
|
||||
.iter()
|
||||
.find(|name| name.ends_with("_filed-with-prose.md"))
|
||||
.expect("not filed");
|
||||
let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap();
|
||||
assert_eq!(content.matches("## Description").count(), 1, "{content}");
|
||||
}
|
||||
|
||||
/// A campaign file with no Description heading is refused rather than given one back. Every
|
||||
/// campaign the tool files carries the heading, so an insertion path here would be reachable
|
||||
/// only from a hand-edited file, which is the opposite of the Relations case. The message
|
||||
/// names the section and not the object, because both a ticket and a campaign reach it.
|
||||
#[test]
|
||||
fn a_campaign_with_no_description_section_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let original = fs::read_to_string(&path).unwrap();
|
||||
fs::write(
|
||||
&path,
|
||||
original.replace("## Description\nWhat has to ship together.\n\n", ""),
|
||||
)
|
||||
.unwrap();
|
||||
let before = fs::read_to_string(&path).unwrap();
|
||||
|
||||
for args in [
|
||||
["campaign", "set", "v1 release", "-d", "Text."],
|
||||
["campaign", "append", "v1 release", "-d", "Text."],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
let said = stderr(&out);
|
||||
assert!(said.contains("no description section"), "{said}");
|
||||
assert!(!said.contains("Ticket"), "a campaign was called a ticket: {said}");
|
||||
assert_eq!(fs::read_to_string(&path).unwrap(), before, "the file was written");
|
||||
}
|
||||
}
|
||||
|
||||
/// A discarded member counts as finished. The work was decided out of the campaign
|
||||
/// rather than left in it, and counting it as outstanding would hold the campaign open
|
||||
/// forever over a ticket nobody will ever do.
|
||||
#[test]
|
||||
fn a_discarded_member_counts_as_finished() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let _worklane = board(&temp);
|
||||
|
||||
run(&temp, &["assign", "v1 release", MEMBER]);
|
||||
run(&temp, &["assign", "v1 release", OTHER]);
|
||||
|
||||
// Two members, one done and one in the backlog: open and half finished.
|
||||
let listing = stdout(&run(&temp, &["campaign", "ls"]));
|
||||
assert!(listing.contains("v1 release | 1/2 done [open]"), "{listing}");
|
||||
|
||||
let discarded = run(&temp, &["mv", MEMBER, "--status", "discarded"]);
|
||||
assert!(discarded.status.success(), "{}", stderr(&discarded));
|
||||
|
||||
let listing = stdout(&run(&temp, &["campaign", "ls"]));
|
||||
assert!(listing.contains("v1 release | 2/2 done [done]"), "{listing}");
|
||||
}
|
||||
|
||||
/// `campaign show` groups the members by status, and a discarded one has a group to
|
||||
/// land in rather than dropping out of the campaign it belongs to.
|
||||
#[test]
|
||||
fn campaign_show_lists_a_discarded_member() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let _worklane = board(&temp);
|
||||
|
||||
run(&temp, &["assign", "v1 release", MEMBER]);
|
||||
assert!(
|
||||
run(&temp, &["mv", MEMBER, "--status", "discarded"])
|
||||
.status
|
||||
.success()
|
||||
);
|
||||
|
||||
let shown = stdout(&run(&temp, &["campaign", "show", "aa11"]));
|
||||
assert!(shown.contains("The member"), "the discarded member is gone: {shown}");
|
||||
}
|
||||
|
||||
+1
-1
@@ -314,7 +314,7 @@ fn check_leaves_nothing_behind() {
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(strays, Vec::<String>::new());
|
||||
|
||||
+1
-1
@@ -77,7 +77,7 @@ fn stray_files(worklane: &Path) -> Vec<String> {
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
+150
-30
@@ -41,6 +41,24 @@ fn create_ticket(worklane_dir: &Path, status: &str, title: &str) -> String {
|
||||
uuid
|
||||
}
|
||||
|
||||
/// The one comment on a ticket, which every author test writes exactly one of.
|
||||
fn only_comment(worklane_dir: &Path, uuid: &str) -> String {
|
||||
let files: Vec<_> = fs::read_dir(worklane_dir.join("history").join(uuid))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
assert_eq!(files.len(), 1, "expected one comment");
|
||||
fs::read_to_string(files[0].path()).unwrap()
|
||||
}
|
||||
|
||||
/// A git config file holding nothing but a `user.name`, for the tests that need the
|
||||
/// fallback to answer something known instead of whatever the machine is configured with.
|
||||
fn git_config_naming(temp: &TempDir, name: &str) -> PathBuf {
|
||||
let path = temp.path().join("gitconfig");
|
||||
fs::write(&path, format!("[user]\n\tname = {}\n", name)).unwrap();
|
||||
path
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_creates_file_with_valid_ticket_uuid() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
@@ -55,9 +73,9 @@ fn comment_creates_file_with_valid_ticket_uuid() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
assert!(comments_dir.exists());
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
assert!(history_dir.exists());
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -107,8 +125,8 @@ fn comment_includes_git_user_and_body() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -131,8 +149,8 @@ fn comment_stored_in_timestamped_file() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -142,14 +160,14 @@ fn comment_stored_in_timestamped_file() {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_creates_comments_directory() {
|
||||
fn comment_creates_the_history_directory() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let uuid = create_ticket(&worklane, "reviewing", "Dir Test");
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
assert!(!comments_dir.exists());
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
assert!(!history_dir.exists());
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
@@ -158,36 +176,138 @@ fn comment_creates_comments_directory() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(comments_dir.exists());
|
||||
assert!(history_dir.exists());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_uses_owner_flag_when_provided() {
|
||||
fn comment_uses_actor_flag_when_provided() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let uuid = create_ticket(&worklane, "backlog", "Owner Test");
|
||||
let uuid = create_ticket(&worklane, "backlog", "Actor Test");
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.arg("comment")
|
||||
.args([&uuid, "Test comment with owner"])
|
||||
.arg("-o")
|
||||
.arg("TestUser")
|
||||
.args([&uuid, "Test comment with actor"])
|
||||
.args(["--actor", "TestUser"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: TestUser"));
|
||||
}
|
||||
|
||||
/// The flag it was, which named the ticket's assignee and not the writer of the entry.
|
||||
/// Renamed without an alias, so the old spelling is a usage error rather than something
|
||||
/// that half works.
|
||||
#[test]
|
||||
fn the_owner_flag_is_gone() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Gone Test");
|
||||
|
||||
for flag in ["--owner", "-o"] {
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.arg("comment")
|
||||
.args([&uuid, "A body"])
|
||||
.args([flag, "TestUser"])
|
||||
.assert()
|
||||
.failure();
|
||||
}
|
||||
|
||||
assert!(
|
||||
!worklane.join("history").join(&uuid).exists(),
|
||||
"a comment was written despite the usage error"
|
||||
);
|
||||
}
|
||||
|
||||
/// The variable is the case an agent runs in: set once by its configuration and
|
||||
/// inherited by every call, where a flag can be forgotten on the fortieth one.
|
||||
#[test]
|
||||
fn comment_takes_the_author_from_the_actor_variable() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Variable Test");
|
||||
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
let content = fs::read_to_string(files[0].path()).unwrap();
|
||||
assert!(content.contains("**Author**: TestUser"));
|
||||
.current_dir(temp.path())
|
||||
.env("WORKLANE_ACTOR", "claude")
|
||||
.arg("comment")
|
||||
.args([&uuid, "Written by an agent"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: claude"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_falls_back_to_git_user_when_owner_omitted() {
|
||||
fn the_actor_flag_overrides_the_variable() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Override Test");
|
||||
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.env("WORKLANE_ACTOR", "claude")
|
||||
.arg("comment")
|
||||
.args([&uuid, "Written by the other one"])
|
||||
.args(["--actor", "opencode"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: opencode"));
|
||||
}
|
||||
|
||||
/// An empty variable counts as unset, the convention `NO_COLOR` follows, so a wrapper
|
||||
/// script can clear an inherited one and get the git user back.
|
||||
#[test]
|
||||
fn an_empty_actor_variable_falls_through_to_the_git_user() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Empty Variable Test");
|
||||
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.env("WORKLANE_ACTOR", "")
|
||||
.env("GIT_CONFIG_GLOBAL", git_config_naming(&temp, "Configured User"))
|
||||
.env("GIT_CONFIG_NOSYSTEM", "1")
|
||||
.arg("comment")
|
||||
.args([&uuid, "Written by a person"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: Configured User"));
|
||||
}
|
||||
|
||||
/// The last resort. Reached with a git that has no `user.name`, which is why the config
|
||||
/// files are redirected: the machine running the suite has one.
|
||||
#[test]
|
||||
fn the_author_is_unknown_when_nothing_names_one() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Unknown Test");
|
||||
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.env_remove("WORKLANE_ACTOR")
|
||||
.env("GIT_CONFIG_GLOBAL", temp.path().join("no-such-gitconfig"))
|
||||
.env("GIT_CONFIG_NOSYSTEM", "1")
|
||||
.arg("comment")
|
||||
.args([&uuid, "Written by nobody in particular"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: unknown"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_falls_back_to_git_user_when_actor_omitted() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
@@ -200,8 +320,8 @@ fn comment_falls_back_to_git_user_when_owner_omitted() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -228,8 +348,8 @@ fn comments_added_back_to_back_are_both_kept() {
|
||||
.success();
|
||||
}
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -263,7 +383,7 @@ fn comment_accepts_a_body_that_begins_with_a_hyphen() {
|
||||
.success();
|
||||
}
|
||||
|
||||
let bodies: String = fs::read_dir(worklane.join("comments").join(&uuid))
|
||||
let bodies: String = fs::read_dir(worklane.join("history").join(&uuid))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| fs::read_to_string(e.path()).unwrap())
|
||||
@@ -318,7 +438,7 @@ fn a_bare_double_hyphen_body_needs_a_separator() {
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains("<BODY>"), "unclear error: {stderr}");
|
||||
assert!(
|
||||
!worklane.join("comments").join(&uuid).exists(),
|
||||
!worklane.join("history").join(&uuid).exists(),
|
||||
"a comment was written despite the error"
|
||||
);
|
||||
|
||||
@@ -328,7 +448,7 @@ fn a_bare_double_hyphen_body_needs_a_separator() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let stored: String = fs::read_dir(worklane.join("comments").join(&uuid))
|
||||
let stored: String = fs::read_dir(worklane.join("history").join(&uuid))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| fs::read_to_string(e.path()).unwrap())
|
||||
|
||||
@@ -62,10 +62,10 @@ fn no_other_shell_gets_the_fish_half() {
|
||||
#[test]
|
||||
fn fish_is_offered_every_status() {
|
||||
let out = script("fish");
|
||||
for status in ["backlog", "committed", "reviewing", "done"] {
|
||||
for status in ["backlog", "committed", "reviewing", "done", "discarded"] {
|
||||
assert!(out.contains(status), "fish is never offered {status}");
|
||||
}
|
||||
assert!(out.contains("-a 'backlog committed reviewing done' -d status"));
|
||||
assert!(out.contains("-a 'backlog committed reviewing done discarded' -d status"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
||||
@@ -903,3 +903,47 @@ fn ls_ids_prints_the_same_order_the_listing_does() {
|
||||
let seen = positions(&stdout, ["Oldest", "Newest", "Unstamped"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
/// Discarded is the other terminal status, so the decorated listing leaves it out the
|
||||
/// way it leaves done out: it is counted in the summary and not listed. The positional
|
||||
/// and `--ids` still reach it, since a ticket nobody will work still has to be nameable.
|
||||
#[test]
|
||||
fn ls_hides_discarded_but_counts_and_can_name_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
temp.child(".worklane")
|
||||
.child("discarded")
|
||||
.create_dir_all()
|
||||
.unwrap();
|
||||
|
||||
create_ticket_with_id(
|
||||
&worklane,
|
||||
"backlog",
|
||||
"Still open",
|
||||
"aaaaaaa1-0000-0000-0000-000000000001",
|
||||
"bug",
|
||||
);
|
||||
create_ticket_with_id(
|
||||
&worklane,
|
||||
"discarded",
|
||||
"Abandoned",
|
||||
"ccccccc3-0000-0000-0000-000000000003",
|
||||
"bug",
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).arg("ls");
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert!(stdout.contains("Still open"), "{stdout}");
|
||||
assert!(!stdout.contains("Abandoned"), "discarded was listed: {stdout}");
|
||||
assert!(stdout.contains("DISCARDED"), "discarded is not counted: {stdout}");
|
||||
|
||||
// Nameable both ways, the way done is.
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "--ids"]);
|
||||
assert!(get_stdout(&mut cmd).contains("Abandoned"));
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "discarded"]);
|
||||
assert!(get_stdout(&mut cmd).contains("Abandoned"));
|
||||
}
|
||||
|
||||
+258
-1
@@ -474,7 +474,7 @@ fn stray_files(worklane: &std::path::Path) -> Vec<String> {
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
|
||||
})
|
||||
.collect();
|
||||
|
||||
@@ -1144,3 +1144,260 @@ fn mv_does_not_restamp_a_no_op_move() {
|
||||
|
||||
assert_eq!(ticket_at(&worklane, "committed", &filename), before);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- discarded --
|
||||
|
||||
/// Discarding is not a stage of work, so it is reachable from wherever the ticket
|
||||
/// stands and needs no `-f`: a backlog ticket that turns out to be a duplicate should
|
||||
/// not have to be walked through committed and reviewing to be abandoned.
|
||||
#[test]
|
||||
fn mv_discards_from_every_status_without_force() {
|
||||
for from in ["backlog", "committed", "reviewing", "done"] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, from);
|
||||
|
||||
let out = move_ticket(&temp, "cccc3333", "discarded", false);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"discarding from {from}: {}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
assert!(
|
||||
worklane.join("discarded").join(&filename).exists(),
|
||||
"the ticket did not land in discarded from {from}"
|
||||
);
|
||||
assert_eq!(md_files(&worklane.join(from)).len(), 0, "left behind in {from}");
|
||||
}
|
||||
}
|
||||
|
||||
/// The fixture board has the four directories the tool shipped with. The first discard
|
||||
/// on a board that predates the status creates the fifth rather than refusing.
|
||||
#[test]
|
||||
fn mv_creates_the_discarded_directory_on_a_board_that_predates_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
assert!(
|
||||
!worklane.join("discarded").exists(),
|
||||
"the fixture already had the directory"
|
||||
);
|
||||
|
||||
let out = move_ticket(&temp, "cccc3333", "discarded", false);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(worklane.join("discarded").join(&filename).exists());
|
||||
}
|
||||
|
||||
/// Leaving discarded is a backward move, which is the rule that already needs `-f`.
|
||||
/// Un-discarding is a correction rather than a stage, so it is allowed under it.
|
||||
#[test]
|
||||
fn leaving_discarded_needs_force() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
assert!(
|
||||
move_ticket(&temp, "cccc3333", "discarded", false)
|
||||
.status
|
||||
.success()
|
||||
);
|
||||
|
||||
let refused = move_ticket(&temp, "cccc3333", "backlog", false);
|
||||
assert!(!refused.status.success());
|
||||
assert!(
|
||||
String::from_utf8_lossy(&refused.stderr).contains("--force"),
|
||||
"{}",
|
||||
String::from_utf8_lossy(&refused.stderr)
|
||||
);
|
||||
assert!(worklane.join("discarded").join(&filename).exists());
|
||||
|
||||
let forced = move_ticket(&temp, "cccc3333", "backlog", true);
|
||||
assert!(forced.status.success(), "{}", String::from_utf8_lossy(&forced.stderr));
|
||||
assert!(worklane.join("backlog").join(&filename).exists());
|
||||
}
|
||||
|
||||
/// The guard looks the other way round from `check_blockers`: a ticket being abandoned
|
||||
/// owes nothing to what it waits on, but the tickets waiting on *it* recorded a
|
||||
/// dependency on work that is about to be declared never-happening.
|
||||
#[test]
|
||||
fn mv_refuses_to_discard_a_ticket_open_tickets_are_blocked_by() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_gated_pair(&worklane, &temp, "backlog");
|
||||
|
||||
let out = move_ticket(&temp, "bbbb2222", "discarded", false);
|
||||
assert!(!out.status.success());
|
||||
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains("Gated Task"), "the dependent is not named: {stderr}");
|
||||
assert!(stderr.contains("--force"), "{stderr}");
|
||||
assert!(
|
||||
!worklane.join("discarded").exists(),
|
||||
"a refused discard made the directory"
|
||||
);
|
||||
}
|
||||
|
||||
/// `-f` is the caller saying they looked at the dependents.
|
||||
#[test]
|
||||
fn mv_discards_a_blocked_from_ticket_with_force() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_gated_pair(&worklane, &temp, "backlog");
|
||||
|
||||
let out = move_ticket(&temp, "bbbb2222", "discarded", true);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
}
|
||||
|
||||
/// A dependent that is itself finished or abandoned is nobody's plan, so it does not
|
||||
/// hold up the discard.
|
||||
#[test]
|
||||
fn a_done_or_discarded_dependent_does_not_hold_up_a_discard() {
|
||||
for status in ["done", "discarded"] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_gated_pair(&worklane, &temp, "backlog");
|
||||
|
||||
assert!(
|
||||
move_ticket(&temp, "aaaa1111", status, true).status.success(),
|
||||
"the dependent could not be moved to {status}"
|
||||
);
|
||||
|
||||
let out = move_ticket(&temp, "bbbb2222", "discarded", false);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"a {status} dependent held up the discard: {}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// A discarded blocker satisfies the block the way a done one does: there is nothing
|
||||
/// left to wait for. Whether the dependent still makes sense was asked when the blocker
|
||||
/// was discarded, which is the refusal above.
|
||||
#[test]
|
||||
fn a_discarded_blocker_does_not_block() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = create_gated_pair(&worklane, &temp, "backlog");
|
||||
|
||||
assert!(
|
||||
move_ticket(&temp, "bbbb2222", "discarded", true)
|
||||
.status
|
||||
.success()
|
||||
);
|
||||
|
||||
let out = move_ticket(&temp, "aaaa1111", "committed", false);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(worklane.join("committed").join(&filename).exists());
|
||||
}
|
||||
|
||||
/// Entering discarded clears no stamp, which is what discarded being last in
|
||||
/// `Status::ALL` buys: a ticket abandoned from reviewing keeps the journey it made, so
|
||||
/// the log still says how far it got before it was dropped.
|
||||
#[test]
|
||||
fn discarding_keeps_the_stamps_the_ticket_already_had() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
assert!(
|
||||
move_ticket(&temp, "cccc3333", "committed", false)
|
||||
.status
|
||||
.success()
|
||||
);
|
||||
assert!(
|
||||
move_ticket(&temp, "cccc3333", "reviewing", false)
|
||||
.status
|
||||
.success()
|
||||
);
|
||||
let before = ticket_at(&worklane, "reviewing", &filename);
|
||||
let committed_on = field(&before, "Committed On").expect(&before);
|
||||
let submitted_on = field(&before, "Submitted On").expect(&before);
|
||||
|
||||
assert!(
|
||||
move_ticket(&temp, "cccc3333", "discarded", false)
|
||||
.status
|
||||
.success()
|
||||
);
|
||||
|
||||
let after = ticket_at(&worklane, "discarded", &filename);
|
||||
assert_eq!(
|
||||
field(&after, "Committed On").as_deref(),
|
||||
Some(committed_on.as_str()),
|
||||
"{after}"
|
||||
);
|
||||
assert_eq!(
|
||||
field(&after, "Submitted On").as_deref(),
|
||||
Some(submitted_on.as_str()),
|
||||
"{after}"
|
||||
);
|
||||
assert!(field(&after, "Discarded On").is_some(), "no discard stamp: {after}");
|
||||
assert!(
|
||||
field(&after, "Completed On").is_none(),
|
||||
"a discard claimed the ticket was done"
|
||||
);
|
||||
}
|
||||
|
||||
/// The other end of the same rule: a forced move back out of discarded truncates the
|
||||
/// journey at the target the way every backward move does.
|
||||
#[test]
|
||||
fn un_discarding_drops_the_discard_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
assert!(
|
||||
move_ticket(&temp, "cccc3333", "discarded", false)
|
||||
.status
|
||||
.success()
|
||||
);
|
||||
assert!(
|
||||
move_ticket(&temp, "cccc3333", "committed", true)
|
||||
.status
|
||||
.success()
|
||||
);
|
||||
|
||||
let content = ticket_at(&worklane, "committed", &filename);
|
||||
assert!(field(&content, "Discarded On").is_none(), "{content}");
|
||||
assert!(field(&content, "Committed On").is_some(), "{content}");
|
||||
}
|
||||
|
||||
/// Prose takes a leading hyphen, so a reason that reads like a flag is stored as the
|
||||
/// content it is rather than refused or swallowed. The cost of that bargain is that a
|
||||
/// genuinely mistyped flag here lands in the log too.
|
||||
#[test]
|
||||
fn a_reason_takes_a_leading_hyphen_as_content() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(
|
||||
&worklane,
|
||||
"backlog",
|
||||
"Hyphen Reason",
|
||||
"Prose trap.",
|
||||
"bbbb2222",
|
||||
"alice",
|
||||
"_Not set_",
|
||||
"",
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.args([
|
||||
"mv",
|
||||
"bbbb2222",
|
||||
"--status",
|
||||
"committed",
|
||||
"--reason",
|
||||
"-not-a-flag",
|
||||
])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let dir = worklane.join("history").join("bbbb2222");
|
||||
let entry = fs::read_dir(&dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| fs::read_to_string(e.path()).unwrap())
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n");
|
||||
assert!(entry.contains("**Reason**: -not-a-flag\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
+1
-1
@@ -80,7 +80,7 @@ fn stray_files(worklane: &Path) -> Vec<String> {
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
@@ -4,6 +4,12 @@
|
||||
//! tags exist, which is the question a grooming sweep starts from. So the properties
|
||||
//! under test are the ones that question needs: every status counted, case kept apart,
|
||||
//! alphabetical order, and an output a shell can parse.
|
||||
//!
|
||||
//! `tags add` is the other half of the same question. The file reports the vocabulary the
|
||||
//! board *intends* and the tickets carry the one it *has*, and the tests below are mostly
|
||||
//! about the two being allowed to disagree without either one damaging the other. The
|
||||
//! listing reports both and marks which is which, so the tests for the output shape are
|
||||
//! about the marking: which field it lands in, and what a board with no file still prints.
|
||||
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
@@ -175,3 +181,454 @@ fn tags_skips_a_missing_status_directory() {
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t1"]);
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------- the vocabulary --
|
||||
|
||||
fn vocabulary(temp: &TempDir) -> String {
|
||||
fs::read_to_string(temp.path().join(".worklane").join("tags.md")).unwrap()
|
||||
}
|
||||
|
||||
/// The section a tag holds in the file, heading excluded, or `None` when it is not
|
||||
/// declared. Cut out of the file rather than asserted against a whole rendering, so a
|
||||
/// change to the preamble does not fail every test here.
|
||||
fn declared(temp: &TempDir, tag: &str) -> Option<String> {
|
||||
let file = vocabulary(temp);
|
||||
let (_, rest) = file.split_once(&format!("\n## {tag}\n"))?;
|
||||
let body = match rest.split_once("\n## ") {
|
||||
Some((body, _)) => body,
|
||||
None => rest,
|
||||
};
|
||||
|
||||
Some(body.trim().to_string())
|
||||
}
|
||||
|
||||
/// The declaration lands in the file, with the annotation under it.
|
||||
#[test]
|
||||
fn tags_add_declares_a_tag_with_what_it_means() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"tags",
|
||||
"add",
|
||||
"bug",
|
||||
"--annotation",
|
||||
"Something the binary does wrong.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("Something the binary does wrong."));
|
||||
}
|
||||
|
||||
/// Several flags are several lines, and an empty one is a paragraph break, the way a
|
||||
/// description is written.
|
||||
#[test]
|
||||
fn an_annotation_takes_several_lines_and_a_paragraph_break() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"tags",
|
||||
"add",
|
||||
"bug",
|
||||
"-a",
|
||||
"What it is.",
|
||||
"-a",
|
||||
"",
|
||||
"-a",
|
||||
"When to use it.",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it."));
|
||||
}
|
||||
|
||||
/// A tag can be declared with nothing said about it. The word being agreed on is worth
|
||||
/// recording before anyone has written the sentence.
|
||||
#[test]
|
||||
fn a_tag_can_be_declared_without_an_annotation() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["tags", "add", "cli"]);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
assert_eq!(declared(&temp, "cli").as_deref(), Some("_No annotation provided._"));
|
||||
}
|
||||
|
||||
/// Refused rather than overwritten, and the refusal names what does overwrite it: an
|
||||
/// annotation is the sentence a team files tickets against, not something to replace by
|
||||
/// typing `add` twice.
|
||||
#[test]
|
||||
fn declaring_a_tag_twice_is_refused_and_names_the_command_that_replaces_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]);
|
||||
let out = run(&temp, &["tags", "add", "bug", "-a", "A different sentence."]);
|
||||
|
||||
assert!(!out.status.success());
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains("tags set"), "{stderr}");
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("The first sentence."));
|
||||
}
|
||||
|
||||
/// A comma is what separates one tag from the next, so a value carrying one could never be
|
||||
/// matched by `--tag`. Refused at parse, with nothing written.
|
||||
#[test]
|
||||
fn a_tag_the_filter_could_never_match_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
for value in ["bug,cli", ""] {
|
||||
let out = run(&temp, &["tags", "add", value]);
|
||||
assert!(!out.status.success(), "'{value}' was accepted");
|
||||
}
|
||||
|
||||
// Nothing was written on the way past, not even the empty file.
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
}
|
||||
|
||||
/// Surrounding space is trimmed rather than refused, because a ticket's Tags field is read
|
||||
/// that way too: ` bug ` on a card is the tag `bug`, and the vocabulary has to agree.
|
||||
#[test]
|
||||
fn a_padded_tag_is_declared_under_its_trimmed_name() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["tags", "add", " bug "]);
|
||||
assert!(declared(&temp, "bug").is_some(), "{}", vocabulary(&temp));
|
||||
}
|
||||
|
||||
/// An annotation line that would be read back as a heading is refused, since it would split
|
||||
/// the section and declare whatever followed it.
|
||||
#[test]
|
||||
fn an_annotation_that_would_read_as_a_heading_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["tags", "add", "bug", "-a", "## cli"]);
|
||||
assert!(!out.status.success());
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
}
|
||||
|
||||
/// The file is made on demand, the way `campaign add` makes the campaigns directory: a board
|
||||
/// that predates the vocabulary must not need `worklane init` run over it.
|
||||
#[test]
|
||||
fn the_file_is_created_on_a_board_that_predates_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
|
||||
run(&temp, &["tags", "add", "bug"]);
|
||||
assert!(declared(&temp, "bug").is_some());
|
||||
}
|
||||
|
||||
/// `init` writes it, so a new board has one file shape rather than two.
|
||||
#[test]
|
||||
fn init_writes_the_vocabulary_beside_the_status_directories() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let out = run(&temp, &["init"]);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
let file = vocabulary(&temp);
|
||||
assert!(file.starts_with("# Tags"), "{file}");
|
||||
// The preamble and nothing else: a new board declares no tags.
|
||||
assert!(!file.contains("\n## "), "{file}");
|
||||
}
|
||||
|
||||
/// A second declaration keeps the first, and the file stays alphabetical: the whole file is
|
||||
/// re-rendered, so this is the test that the re-render is not a truncation.
|
||||
#[test]
|
||||
fn declaring_a_tag_leaves_the_others_alone_and_keeps_the_order() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["tags", "add", "tui", "-a", "The board view."]);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "Something wrong."]);
|
||||
|
||||
assert_eq!(declared(&temp, "tui").as_deref(), Some("The board view."));
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("Something wrong."));
|
||||
|
||||
let file = vocabulary(&temp);
|
||||
assert!(file.find("## bug").unwrap() < file.find("## tui").unwrap(), "{file}");
|
||||
}
|
||||
|
||||
/// A file that is there and cannot be read stops the write rather than being taken for an
|
||||
/// empty vocabulary. Empty would mean erased, since every declaration re-renders the file.
|
||||
#[test]
|
||||
fn a_vocabulary_that_cannot_be_read_is_refused_rather_than_replaced() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
// A directory where the file should be: `read_to_string` fails on it, which a missing
|
||||
// file does not.
|
||||
fs::create_dir(worklane.join("tags.md")).unwrap();
|
||||
|
||||
let out = run(&temp, &["tags", "add", "bug"]);
|
||||
assert!(!out.status.success());
|
||||
assert!(worklane.join("tags.md").is_dir(), "the file was replaced");
|
||||
|
||||
// And nothing was staged and left behind.
|
||||
let stray: Vec<_> = fs::read_dir(&worklane)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.filter(|e| e.file_name().to_string_lossy().starts_with(".wl-"))
|
||||
.collect();
|
||||
assert!(stray.is_empty(), "a temp file was left in .worklane");
|
||||
}
|
||||
|
||||
/// The listing is the union of the two vocabularies, and the two disagreeing is the normal
|
||||
/// state rather than a fault: a declaration tags no ticket, and tagging a ticket declares
|
||||
/// nothing.
|
||||
///
|
||||
/// Both halves of the disagreement in one assertion, since neither is legible without the
|
||||
/// other. `chore` is declared and carried by nothing, so it lists at zero with what it
|
||||
/// means; `bug` is carried and declared by nothing, so it lists with a count and no third
|
||||
/// field at all.
|
||||
#[test]
|
||||
fn the_listing_is_the_union_of_the_declared_and_the_carried() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
|
||||
run(&temp, &["tags", "add", "chore", "-a", "Housekeeping."]);
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t1", "chore\t0\tHousekeeping."]);
|
||||
}
|
||||
|
||||
/// The third field is the annotation's *opening* line. An annotation is prose with
|
||||
/// paragraphs in it, and a second line in this output would be read as a second tag.
|
||||
#[test]
|
||||
fn the_annotation_is_cut_to_its_opening_line() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"tags",
|
||||
"add",
|
||||
"bug",
|
||||
"-a",
|
||||
"What it is.",
|
||||
"-a",
|
||||
"",
|
||||
"-a",
|
||||
"When to use it.",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t0\tWhat it is."]);
|
||||
}
|
||||
|
||||
/// A tag declared with nothing said about it still carries a third field, and it is the
|
||||
/// placeholder the file itself holds under that heading.
|
||||
///
|
||||
/// The subtle case, and the reason the field is not simply left empty: an empty third field
|
||||
/// is a trailing tab, so the only difference between a declared tag and an undeclared one
|
||||
/// would be invisible in a terminal and in a completion alike.
|
||||
#[test]
|
||||
fn a_tag_declared_without_an_annotation_is_still_marked_as_declared() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "carried");
|
||||
|
||||
run(&temp, &["tags", "add", "declared"]);
|
||||
|
||||
assert_eq!(tags(&temp), vec!["carried\t1", "declared\t0\t_No annotation provided._"]);
|
||||
}
|
||||
|
||||
/// `cut -f1` over the listing yields exactly the tag values, undeclared ones included.
|
||||
///
|
||||
/// The constraint the whole output shape is built around: whatever marks a carried but
|
||||
/// undeclared tag must stay out of the first field, or a completion offers a tag that does
|
||||
/// not exist and `ls --tag` comes back empty for it.
|
||||
#[test]
|
||||
fn the_first_field_is_the_bare_tag_whether_it_is_declared_or_not() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "carried,both");
|
||||
run(&temp, &["tags", "add", "both", "-a", "Carried and declared."]);
|
||||
run(&temp, &["tags", "add", "declared", "-a", "Declared only."]);
|
||||
|
||||
let first: Vec<String> = tags(&temp)
|
||||
.iter()
|
||||
.map(|line| line.split('\t').next().unwrap().to_string())
|
||||
.collect();
|
||||
assert_eq!(first, vec!["both", "carried", "declared"]);
|
||||
|
||||
// And each of them is a value `--tag` can match, which is what the first field is for.
|
||||
for tag in ["both", "carried"] {
|
||||
let out = run(&temp, &["ls", "--tag", tag, "--ids"]);
|
||||
assert_eq!(
|
||||
String::from_utf8_lossy(&out.stdout).lines().count(),
|
||||
1,
|
||||
"--tag {tag} matched nothing"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// A board with no vocabulary lists what it listed before the file existed, byte for byte.
|
||||
///
|
||||
/// Every tag on such a board is carried and undeclared, so the absence of the third field
|
||||
/// is what keeps the old output shape: a marker in it would have changed every line of
|
||||
/// every board that predates the file, and the shipped fish completion of an older version
|
||||
/// is still reading this.
|
||||
#[test]
|
||||
fn a_board_with_no_vocabulary_lists_what_it_listed_before_the_file_existed() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
|
||||
create_ticket(&worklane, "done", "22222222", "bug");
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
|
||||
let out = run(&temp, &["tags"]);
|
||||
assert_eq!(String::from_utf8_lossy(&out.stdout), "bug\t2\ncli\t1\n");
|
||||
}
|
||||
|
||||
/// The bare form is the listing, byte for byte, because the shipped fish completion calls it
|
||||
/// that way to fill in `ls --tag`. `tags ls` is the same thing spelled as a group.
|
||||
#[test]
|
||||
fn the_bare_form_and_ls_are_the_same_listing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
|
||||
run(&temp, &["tags", "add", "chore"]);
|
||||
|
||||
let bare = run(&temp, &["tags"]);
|
||||
let group = run(&temp, &["tags", "ls"]);
|
||||
|
||||
assert!(bare.status.success());
|
||||
assert_eq!(bare.stdout, group.stdout);
|
||||
assert_eq!(
|
||||
String::from_utf8_lossy(&bare.stdout),
|
||||
"bug\t1\nchore\t0\t_No annotation provided._\ncli\t1\n"
|
||||
);
|
||||
}
|
||||
|
||||
// -------------------------------------------------- changing what a tag means --
|
||||
|
||||
/// The replacement lands, and replaces rather than appends.
|
||||
#[test]
|
||||
fn tags_set_replaces_what_a_tag_means() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]);
|
||||
|
||||
let out = run(&temp, &["tags", "set", "bug", "-a", "The second sentence."]);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("The second sentence."));
|
||||
assert!(!vocabulary(&temp).contains("first"), "the old annotation survived");
|
||||
}
|
||||
|
||||
/// Paragraph breaks survive the round trip, which is the whole difference between an
|
||||
/// annotation and a one-line description of a tag.
|
||||
#[test]
|
||||
fn a_multiline_annotation_survives_being_set() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug"]);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"tags",
|
||||
"set",
|
||||
"bug",
|
||||
"-a",
|
||||
"What it is.",
|
||||
"-a",
|
||||
"",
|
||||
"-a",
|
||||
"When to use it.",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it."));
|
||||
}
|
||||
|
||||
/// Set to what it already says, nothing is written and the command says so, the way `set`
|
||||
/// and `chown` report a field that already holds the value.
|
||||
#[test]
|
||||
fn setting_an_annotation_to_what_it_already_says_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
|
||||
|
||||
let before = fs::metadata(temp.path().join(".worklane").join("tags.md"))
|
||||
.unwrap()
|
||||
.modified()
|
||||
.unwrap();
|
||||
|
||||
let out = run(&temp, &["tags", "set", "bug", "-a", "The sentence."]);
|
||||
assert!(out.status.success());
|
||||
assert!(String::from_utf8_lossy(&out.stdout).contains("No changes"), "{out:?}");
|
||||
|
||||
let after = fs::metadata(temp.path().join(".worklane").join("tags.md"))
|
||||
.unwrap()
|
||||
.modified()
|
||||
.unwrap();
|
||||
assert_eq!(before, after, "the file was rewritten for a no-op");
|
||||
}
|
||||
|
||||
/// `add` and `set` are a pair, each refusing what the other is for, so the refusal names
|
||||
/// the other command rather than leaving it to be found.
|
||||
#[test]
|
||||
fn setting_a_tag_that_is_not_declared_is_refused_and_names_add() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug"]);
|
||||
|
||||
let out = run(&temp, &["tags", "set", "cli", "-a", "Anything."]);
|
||||
|
||||
assert!(!out.status.success());
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains("tags add"), "{stderr}");
|
||||
assert!(declared(&temp, "cli").is_none(), "the tag was declared by set");
|
||||
}
|
||||
|
||||
/// A bare `tags set <tag>` is a usage error. Nothing to write is a mistake in the call, not
|
||||
/// a command that quietly does nothing.
|
||||
#[test]
|
||||
fn setting_nothing_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
|
||||
|
||||
let out = run(&temp, &["tags", "set", "bug"]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{out:?}");
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("The sentence."));
|
||||
}
|
||||
|
||||
/// An annotation can be emptied back to the placeholder, which is the state a tag declared
|
||||
/// without one is already in. That is why there is no `--clear`.
|
||||
#[test]
|
||||
fn an_annotation_can_be_emptied_back_to_the_placeholder() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
|
||||
|
||||
run(&temp, &["tags", "set", "bug", "-a", ""]);
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("_No annotation provided._"));
|
||||
}
|
||||
|
||||
/// The other tags keep their sections, since the whole file is re-rendered on every write.
|
||||
#[test]
|
||||
fn setting_one_annotation_leaves_the_others_alone() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "About bugs."]);
|
||||
run(&temp, &["tags", "add", "tui", "-a", "About the board."]);
|
||||
|
||||
run(&temp, &["tags", "set", "bug", "-a", "Rewritten."]);
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("Rewritten."));
|
||||
assert_eq!(declared(&temp, "tui").as_deref(), Some("About the board."));
|
||||
}
|
||||
|
||||
@@ -0,0 +1,564 @@
|
||||
//! The history log: what the CLI records about a ticket besides what somebody said.
|
||||
//!
|
||||
//! One file rather than a few tests in each command's suite: the rules are about the log
|
||||
//! and not about `mv` or `chown`, and the interesting cases are the ones where two
|
||||
//! commands have to agree — every mechanical entry has the same shape, and every refusal
|
||||
//! writes nothing.
|
||||
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
use assert_fs::fixture::{PathChild, PathCreateDir};
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::Output;
|
||||
|
||||
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
const UUID: &str = "475534a3-8a0d-45cb-9a97-39c251dd8e39";
|
||||
|
||||
fn setup_worklane(temp: &TempDir) -> PathBuf {
|
||||
let worklane = temp.child(".worklane");
|
||||
worklane.create_dir_all().unwrap();
|
||||
|
||||
for dir in ["backlog", "committed", "reviewing", "done"] {
|
||||
worklane.child(dir).create_dir_all().unwrap();
|
||||
}
|
||||
|
||||
worklane.path().to_path_buf()
|
||||
}
|
||||
|
||||
/// A ticket with every field an entry can record a change to.
|
||||
fn create_ticket(worklane: &Path, status: &str) -> String {
|
||||
let filename = format!("{}_a-ticket.md", UUID);
|
||||
fs::write(
|
||||
worklane.join(status).join(&filename),
|
||||
format!(
|
||||
"# A ticket\n\
|
||||
\n\
|
||||
## Description\n\
|
||||
Something to do.\n\
|
||||
\n\
|
||||
## Acceptance Criteria\n\
|
||||
- [ ] Crit one\n\
|
||||
- [ ] Crit two\n\
|
||||
\n\
|
||||
## Implementation Plan\n\
|
||||
1. Step one\n\
|
||||
\n\
|
||||
## Metadata\n\
|
||||
\n\
|
||||
- **ID**: {}\n\
|
||||
- **Priority**: 3\n\
|
||||
- **Tags**: alpha\n\
|
||||
- **Due**: 2026-09-01\n\
|
||||
- **Owner**: alice\n\
|
||||
- **Status**: {}\n",
|
||||
UUID, status
|
||||
),
|
||||
)
|
||||
.unwrap();
|
||||
filename
|
||||
}
|
||||
|
||||
/// Run with the actor named, so every author assertion is about the log and not about
|
||||
/// the git user of whoever runs the suite.
|
||||
fn run(temp: &TempDir, args: &[&str]) -> Output {
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.env("WORKLANE_ACTOR", "claude")
|
||||
.args(args)
|
||||
.assert()
|
||||
.get_output()
|
||||
.clone()
|
||||
}
|
||||
|
||||
/// Every entry on the ticket, name and content, in the order the log sorts them.
|
||||
fn entries(worklane: &Path) -> Vec<(String, String)> {
|
||||
let dir = worklane.join("history").join(UUID);
|
||||
if !dir.exists() {
|
||||
return vec![];
|
||||
}
|
||||
|
||||
let mut found: Vec<(String, String)> = fs::read_dir(&dir)
|
||||
.unwrap()
|
||||
.filter_map(|entry| entry.ok())
|
||||
.map(|entry| {
|
||||
(
|
||||
entry.file_name().into_string().unwrap(),
|
||||
fs::read_to_string(entry.path()).unwrap(),
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
found.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
found
|
||||
}
|
||||
|
||||
/// The one entry a call wrote, with its kind checked off the filename.
|
||||
fn only_entry(worklane: &Path, kind: &str) -> String {
|
||||
let found = entries(worklane);
|
||||
assert_eq!(found.len(), 1, "expected one entry, got {found:?}");
|
||||
assert!(found[0].0.ends_with(&format!("_{kind}.md")), "was {}", found[0].0);
|
||||
found[0].1.clone()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn mv_writes_a_status_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["mv", UUID, "--status", "committed"]);
|
||||
|
||||
let entry = only_entry(&worklane, "status");
|
||||
assert!(entry.starts_with("**Status**\nbacklog → committed\n"), "{entry:?}");
|
||||
assert!(entry.contains("**Author**: claude"), "{entry:?}");
|
||||
}
|
||||
|
||||
/// One file, one event, its explanation: `--reason` rides in the status entry that
|
||||
/// records the transition it explains, as a field after **Time**, and `show` renders it
|
||||
/// indented under the row rather than as a paragraph of its own.
|
||||
#[test]
|
||||
fn the_reason_travels_with_its_transition() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "reviewing");
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"mv",
|
||||
UUID,
|
||||
"--status",
|
||||
"backlog",
|
||||
"-f",
|
||||
"--reason",
|
||||
"sent back: the first plan was wrong",
|
||||
],
|
||||
);
|
||||
|
||||
let entry = only_entry(&worklane, "status");
|
||||
assert!(entry.starts_with("**Status**\nreviewing → backlog\n"), "{entry:?}");
|
||||
assert!(
|
||||
entry.ends_with("**Reason**: sent back: the first plan was wrong\n"),
|
||||
"{entry:?}"
|
||||
);
|
||||
|
||||
let out = run(&temp, &["show", UUID]);
|
||||
let stdout = String::from_utf8(out.stdout).unwrap();
|
||||
|
||||
let moved = stdout.find("reviewing → backlog").expect("the move is missing");
|
||||
let reason = stdout
|
||||
.find("\n sent back: the first plan was wrong")
|
||||
.expect("the reason is missing");
|
||||
// Attached means the very next line: nothing, not even a blank line, between.
|
||||
assert!(
|
||||
!stdout[moved..reason].contains('\n'),
|
||||
"the reason is detached from its row:\n{stdout}"
|
||||
);
|
||||
}
|
||||
|
||||
/// The unusual moves are exactly the ones that need a why, so a refused one must not
|
||||
/// log one either: the entry is written after the edit, and there was no edit.
|
||||
#[test]
|
||||
fn a_refused_move_writes_no_reason_either() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "reviewing");
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"mv",
|
||||
UUID,
|
||||
"--status",
|
||||
"backlog",
|
||||
"--reason",
|
||||
"this move never happened",
|
||||
],
|
||||
);
|
||||
assert_eq!(out.status.code(), Some(1));
|
||||
assert_eq!(entries(&worklane), vec![], "a refused move logged its reason");
|
||||
}
|
||||
|
||||
/// Same for the move that changes nothing.
|
||||
#[test]
|
||||
fn a_no_op_move_writes_no_reason_either() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "committed");
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"mv",
|
||||
UUID,
|
||||
"--status",
|
||||
"committed",
|
||||
"--reason",
|
||||
"nothing moved",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
assert_eq!(entries(&worklane), vec![], "a no-op move logged its reason");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn chown_writes_an_owner_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["chown", "bob", UUID]);
|
||||
|
||||
let entry = only_entry(&worklane, "owner");
|
||||
assert!(entry.starts_with("**Owner**\nalice → bob\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
/// Clearing is the same field going somewhere, so it is logged, and the value it goes to
|
||||
/// is the sentinel the ticket now holds rather than a word this log invented.
|
||||
#[test]
|
||||
fn clearing_the_owner_writes_an_owner_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["chown", "--clear", UUID]);
|
||||
|
||||
let entry = only_entry(&worklane, "owner");
|
||||
assert!(entry.starts_with("**Owner**\nalice → _Not set_\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn set_tags_writes_a_tags_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["set", UUID, "--tags", "beta", "--tags", "gamma"]);
|
||||
|
||||
let entry = only_entry(&worklane, "tags");
|
||||
assert!(entry.starts_with("**Tags**\nalpha → beta, gamma\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn clearing_the_tags_writes_a_tags_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["set", UUID, "--clear", "tags"]);
|
||||
|
||||
let entry = only_entry(&worklane, "tags");
|
||||
assert!(entry.starts_with("**Tags**\nalpha → _None_\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
/// The entry names the campaign the way a reader knows it, the codename, not the uuid
|
||||
/// the field actually holds. A ticket never assigned starts from the sentinel an unset
|
||||
/// field reads as everywhere else.
|
||||
#[test]
|
||||
fn assign_writes_a_campaign_entry_naming_the_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First public release",
|
||||
"--codename",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
|
||||
run(&temp, &["assign", "v1", UUID]);
|
||||
|
||||
let entry = only_entry(&worklane, "campaign");
|
||||
assert!(entry.starts_with("**Campaign**\n_Not set_ → v1\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
/// A campaign filed without a codename is recorded by its title, the name `show` and
|
||||
/// `campaign ls` fall back to.
|
||||
#[test]
|
||||
fn a_campaign_without_a_codename_is_recorded_by_its_title() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
run(&temp, &["campaign", "add", "--title", "First public release"]);
|
||||
|
||||
run(&temp, &["assign", "First public", UUID]);
|
||||
|
||||
let entry = only_entry(&worklane, "campaign");
|
||||
assert!(
|
||||
entry.starts_with("**Campaign**\n_Not set_ → First public release\n"),
|
||||
"{entry:?}"
|
||||
);
|
||||
}
|
||||
|
||||
/// A ticket leaving one campaign for another records both ends, which is the move the
|
||||
/// log exists to answer for: the field is rewritten, so nothing else remembers where the
|
||||
/// ticket was.
|
||||
#[test]
|
||||
fn moving_between_campaigns_records_both_names() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First release",
|
||||
"--codename",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"Second release",
|
||||
"--codename",
|
||||
"beaver",
|
||||
],
|
||||
);
|
||||
|
||||
run(&temp, &["assign", "v1", UUID]);
|
||||
run(&temp, &["assign", "beaver", UUID]);
|
||||
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 2, "{found:?}");
|
||||
assert!(found[1].1.starts_with("**Campaign**\nv1 → beaver\n"), "{:?}", found[1].1);
|
||||
}
|
||||
|
||||
/// Assigning the campaign a ticket already names is reported as no change, and a log of
|
||||
/// no change would be a log of nothing happening.
|
||||
#[test]
|
||||
fn a_no_op_assign_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First release",
|
||||
"--codename",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
|
||||
run(&temp, &["assign", "v1", UUID]);
|
||||
let out = run(&temp, &["assign", "v1", UUID]);
|
||||
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
assert_eq!(
|
||||
entries(&worklane).len(),
|
||||
1,
|
||||
"a no-op assign logged a change it did not make"
|
||||
);
|
||||
}
|
||||
|
||||
/// The fields that change often enough that a log of them is noise. `set` writing one of
|
||||
/// them is not an entry, and neither is a criterion being ticked.
|
||||
#[test]
|
||||
fn the_edits_that_are_not_logged_write_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
for args in [
|
||||
vec!["set", UUID, "--title", "A better title"],
|
||||
vec!["set", UUID, "--due", "2026-10-01"],
|
||||
vec!["set", UUID, "--priority", "1"],
|
||||
vec!["set", UUID, "--description", "Rewritten."],
|
||||
vec!["set", UUID, "--plan", "One step"],
|
||||
vec!["check", UUID, "1"],
|
||||
vec!["uncheck", UUID, "1"],
|
||||
vec!["append", UUID, "--description", "One more paragraph."],
|
||||
vec!["comment", UUID, "-", "--"],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"{args:?}: {:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
}
|
||||
|
||||
// The comment is the exception: it is an entry, and the only one this run wrote.
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 1, "{found:?}");
|
||||
assert!(found[0].0.ends_with("_comment.md"), "was {}", found[0].0);
|
||||
}
|
||||
|
||||
/// An edit reported as no change writes no entry: the field is already what the call
|
||||
/// asked for, and a log of that would be a log of nothing happening.
|
||||
#[test]
|
||||
fn a_no_op_edit_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
for args in [
|
||||
vec!["mv", UUID, "--status", "backlog"],
|
||||
vec!["chown", "alice", UUID],
|
||||
vec!["set", UUID, "--tags", "alpha"],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"{args:?}: {:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
assert_eq!(entries(&worklane), vec![], "{args:?} logged a change it did not make");
|
||||
}
|
||||
}
|
||||
|
||||
/// A refused move is not a move. The entry is written after the edit for exactly this.
|
||||
#[test]
|
||||
fn a_refused_move_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "reviewing");
|
||||
|
||||
let backward = run(&temp, &["mv", UUID, "--status", "backlog"]);
|
||||
assert_eq!(backward.status.code(), Some(1));
|
||||
|
||||
let skipped = run(&temp, &["mv", UUID, "--status", "backlog", "-f"]);
|
||||
assert!(skipped.status.success(), "{:?}", String::from_utf8_lossy(&skipped.stderr));
|
||||
|
||||
// The forced one moved, so it is logged; the refused one is not.
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 1, "{found:?}");
|
||||
assert!(found[0].1.contains("reviewing → backlog"), "{:?}", found[0].1);
|
||||
}
|
||||
|
||||
/// A failed edit logs nothing, whatever the failure. This ticket has no Owner field, so
|
||||
/// `chown` refuses it after resolving it and before writing anything.
|
||||
#[test]
|
||||
fn a_failed_edit_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
fs::write(
|
||||
worklane.join("backlog").join(format!("{}_bare.md", UUID)),
|
||||
format!("# Bare\n\n## Metadata\n\n- **ID**: {}\n- **Status**: backlog\n", UUID),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let out = run(&temp, &["chown", "bob", UUID]);
|
||||
assert_eq!(out.status.code(), Some(1));
|
||||
assert_eq!(entries(&worklane), vec![], "a refused chown was logged");
|
||||
}
|
||||
|
||||
/// One sequence, oldest first, with a comment rendered as it always was and a field
|
||||
/// change as one line.
|
||||
#[test]
|
||||
fn show_prints_the_comments_and_the_changes_in_one_sequence() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["comment", UUID, "Picked this up."]);
|
||||
run(&temp, &["mv", UUID, "--status", "committed"]);
|
||||
run(&temp, &["chown", "bob", UUID]);
|
||||
|
||||
let out = run(&temp, &["show", UUID]);
|
||||
let stdout = String::from_utf8(out.stdout).unwrap();
|
||||
|
||||
assert!(stdout.contains("HISTORY"), "{stdout}");
|
||||
let said = stdout.find("Picked this up.").expect("the comment is missing");
|
||||
let moved = stdout.find("backlog → committed").expect("the move is missing");
|
||||
let owned = stdout.find("alice → bob").expect("the chown is missing");
|
||||
assert!(said < moved && moved < owned, "out of order:\n{stdout}");
|
||||
|
||||
for line in ["status backlog → committed", "owner alice → bob"] {
|
||||
assert!(stdout.contains(line), "{line:?} not in:\n{stdout}");
|
||||
}
|
||||
assert!(stdout.contains("From claude ("), "{stdout}");
|
||||
}
|
||||
|
||||
/// A ticket nothing has happened to says so, where it used to say there were no comments.
|
||||
#[test]
|
||||
fn show_says_so_when_there_is_no_history() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
let out = run(&temp, &["show", UUID]);
|
||||
assert!(
|
||||
String::from_utf8(out.stdout)
|
||||
.unwrap()
|
||||
.contains("No history yet.")
|
||||
);
|
||||
}
|
||||
|
||||
/// A board written by an older version: the directory is adopted on the first access,
|
||||
/// the entries in it are read as the comments they are, and nothing is rewritten.
|
||||
#[test]
|
||||
fn an_old_comments_directory_is_adopted() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
let legacy = worklane.join("comments").join(UUID);
|
||||
fs::create_dir_all(&legacy).unwrap();
|
||||
let name = "20260820_143012_123456.md";
|
||||
let content =
|
||||
"**Comment**\nSaid long ago.\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n";
|
||||
fs::write(legacy.join(name), content).unwrap();
|
||||
|
||||
let out = run(&temp, &["show", UUID]);
|
||||
let stdout = String::from_utf8(out.stdout).unwrap();
|
||||
assert!(stdout.contains("Said long ago."), "{stdout}");
|
||||
assert!(stdout.contains("From Ansho Rei ("), "{stdout}");
|
||||
|
||||
assert!(!worklane.join("comments").exists(), "the old directory survived");
|
||||
let moved = worklane.join("history").join(UUID).join(name);
|
||||
assert_eq!(fs::read_to_string(&moved).unwrap(), content, "the entry was rewritten");
|
||||
|
||||
// And a new entry lands beside it, in the order it was written.
|
||||
run(&temp, &["mv", UUID, "--status", "committed"]);
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 2, "{found:?}");
|
||||
assert_eq!(found[0].0, name);
|
||||
assert!(found[1].0.ends_with("_status.md"), "was {}", found[1].0);
|
||||
}
|
||||
|
||||
/// The flag is spelled the same on every command that writes an entry, and it overrides
|
||||
/// the variable on each of them.
|
||||
#[test]
|
||||
fn the_actor_flag_names_the_writer_on_every_command_that_writes_one() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First release",
|
||||
"--codename",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
|
||||
run(&temp, &["comment", UUID, "By hand.", "--actor", "opencode"]);
|
||||
run(&temp, &["mv", UUID, "--status", "committed", "--actor", "opencode"]);
|
||||
run(&temp, &["chown", "bob", UUID, "--actor", "opencode"]);
|
||||
run(&temp, &["set", UUID, "--tags", "beta", "--actor", "opencode"]);
|
||||
run(&temp, &["assign", "v1", UUID, "--actor", "opencode"]);
|
||||
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 5, "{found:?}");
|
||||
for (name, content) in found {
|
||||
assert!(content.contains("**Author**: opencode"), "{name}: {content:?}");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user