Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
f515d69930 | ||
|
|
b1dbf3ed75 | ||
|
|
154ffbdeb3 | ||
|
|
50e67483d8 | ||
|
|
11145b228e | ||
|
|
2ddd0addf6 | ||
|
|
cbc20848f6 | ||
|
|
eae411ab50 | ||
|
|
95426e87be | ||
|
|
72dbdec2ec | ||
|
|
528566d103 | ||
|
|
c65e1b4ed7 | ||
|
|
6a800fb385 | ||
|
|
4ae7ef03ff | ||
|
|
73ffcad733 | ||
|
|
964ca342d8 | ||
|
|
cc5f9b8a46 | ||
|
|
175c1d016d | ||
|
|
139c9b012f | ||
|
|
373ba519b3 | ||
|
|
88918b2f8a |
@@ -0,0 +1,8 @@
|
||||
# Revisions that changed layout and nothing else. Teach git to look through them:
|
||||
#
|
||||
# git config blame.ignoreRevsFile .git-blame-ignore-revs
|
||||
#
|
||||
# Only a commit whose diff is pure formatting belongs here.
|
||||
|
||||
# Reformat with cargo fmt, and nothing else
|
||||
73ffcad73314621e299dc06ee688db9b4c4d6b29
|
||||
@@ -17,7 +17,7 @@ permissions:
|
||||
bash:
|
||||
"sudo *": "deny"
|
||||
skill:
|
||||
"worklane_kanban": "allow"
|
||||
"worklane": "allow"
|
||||
---
|
||||
|
||||
# Feature Planner Agent
|
||||
|
||||
@@ -17,7 +17,7 @@ permissions:
|
||||
bash:
|
||||
"sudo *": "deny"
|
||||
skill:
|
||||
"worklane_kanban": "allow"
|
||||
"worklane": "allow"
|
||||
"testing-skill": "allow"
|
||||
---
|
||||
|
||||
|
||||
@@ -1,223 +0,0 @@
|
||||
---
|
||||
id: worklane_kanban
|
||||
name: worklane_kanban
|
||||
version: 1.0.0
|
||||
description: >
|
||||
Creates Kanban-style tickets in Worklane using the `worklane add` CLI command.
|
||||
Supports listing tickets with `worklane ls`. Both commands support title, description,
|
||||
acceptance criteria, implementation plan, tags, due date, owner assignment, and status filtering.
|
||||
rendering:
|
||||
strategy: cli_args
|
||||
join_arrays_with: ","
|
||||
omit_empty: true
|
||||
---
|
||||
|
||||
# Worklane Kanban Skill
|
||||
|
||||
Use this skill when creating, listing, or managing Kanban-style tickets via the `worklane` CLI.
|
||||
|
||||
When asked to "create a ticket", use the `worklane add` command.
|
||||
When using backticks in the command arguments, escape them so the terminal doesn't execute them.
|
||||
|
||||
When asked to "implement", "work on" or "read" a ticket, use the `worklane show` command.
|
||||
|
||||
## Commands
|
||||
|
||||
### `worklane add`
|
||||
|
||||
Add a new ticket to the backlog.
|
||||
|
||||
**Required:**
|
||||
- `--title` (or `-t`): Ticket title
|
||||
|
||||
**Optional:**
|
||||
- `--description` (or `-d`): Ticket description
|
||||
- `--acceptance` (or `-a`): Acceptance criteria (repeat flag for each criterium)
|
||||
- `--plan` (or `-p`): Implementation plan steps (repeat flag for each step)
|
||||
- `--tags` (or `-g`): Tags (comma-separated)
|
||||
- `--due`: Due date in YYYY-MM-DD format. No short form
|
||||
- `--owner` (or `-o`): Owner name
|
||||
- `--priority`: Priority level, 1 (most urgent) to 5 (least). Unset if omitted. No short form
|
||||
|
||||
Tags are `-g`, not `-t`: `-t` is the title, and passing it twice is an error. Each
|
||||
plan step needs its own `-p`, since a bare value after one is not a second step.
|
||||
|
||||
```bash
|
||||
worklane add -t "Implement login" -d "Add user login page" -g login,auth -p "Design UI" -p "Build backend" -p "Write tests" --due 2026-06-01 --owner "ilya"
|
||||
```
|
||||
|
||||
When there's multiple acceptance criteria, add each using a separate `--acceptance` or `-a` flag.
|
||||
When there's mulitple steps to the implementation plan, add each using a separate `--plan` or `-p` flag.
|
||||
|
||||
```bash
|
||||
worklane add -t "Implement logic" -a "Acceptance criterium 1" -a "Acceptance criterium 2" -p "Step 1" -p "Step 2"
|
||||
```
|
||||
|
||||
### `worklane ls`
|
||||
|
||||
List tickets, optionally filtered by status.
|
||||
|
||||
**Valid statuses:** `backlog`, `committed`, `reviewing`, `done`
|
||||
|
||||
```
|
||||
worklane ls # List all tickets
|
||||
worklane ls backlog # List tickets in backlog
|
||||
worklane ls done # List completed tickets
|
||||
worklane ls --priority 1 # Only the most urgent, any status
|
||||
worklane ls backlog --priority 2 # Composes with the status filter
|
||||
```
|
||||
|
||||
Tickets are listed priority first, then by title. Tickets with no priority sort last.
|
||||
|
||||
### `worklane show`
|
||||
|
||||
Show the full details of a single ticket by UUID or title.
|
||||
|
||||
```
|
||||
worklane show "ticket title or uuid"
|
||||
```
|
||||
|
||||
### `worklane mv`
|
||||
|
||||
Move a ticket between statuses.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<id>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Required options:**
|
||||
- `--status <target>`: Target status (`backlog`, `committed`, `reviewing`, `done`)
|
||||
|
||||
**Options:**
|
||||
- `-f`: Force move (allows skipping stages and backward moves)
|
||||
|
||||
**Default behavior:** Only allows forward moves, one stage at a time (`backlog` -> `committed` -> `reviewing` -> `done`).
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
worklane mv ticket-id --status committed # Move forward one stage
|
||||
worklane mv ticket-title --status reviewing -f # Force skip stages
|
||||
worklane mv a1b2c3d4 --status committed # Move by UUID prefix
|
||||
worklane mv "My Ticket" --status done -f # Move by title with force
|
||||
```
|
||||
|
||||
### `worklane set`
|
||||
|
||||
Replace fields on an existing ticket. Only the fields given are touched; ticked
|
||||
criteria and handwritten sections are left alone. At least one field is required.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Options:** `--title`, `--description` (or `-d`), `--acceptance` (or `-a`), `--plan`
|
||||
(or `-p`), `--tags` (or `-g`), `--due`, `--priority`
|
||||
|
||||
Owner is not settable here, and neither is status: `chown` owns owner and `mv` owns
|
||||
status. Changing the title renames the file, keeping the UUID.
|
||||
|
||||
```bash
|
||||
worklane set a1b2c3d4 --priority 1
|
||||
worklane set a1b2c3d4 --title "A clearer title" --due 2026-12-31
|
||||
worklane set a1b2c3d4 -a "First criterium" -a "Second criterium"
|
||||
```
|
||||
|
||||
### `worklane append`
|
||||
|
||||
Add to a section without replacing what is there. The description gains a new
|
||||
paragraph; criteria and steps go on the end of their lists, steps numbered on from
|
||||
the last. At least one section is required.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Options:** `--description` (or `-d`), `--acceptance` (or `-a`), `--plan` (or `-p`)
|
||||
|
||||
```bash
|
||||
worklane append a1b2c3d4 -d "A paragraph amending the description."
|
||||
worklane append a1b2c3d4 -a "One more criterium"
|
||||
worklane append a1b2c3d4 -p "A later step"
|
||||
```
|
||||
|
||||
### `worklane chown`
|
||||
|
||||
Set the owner of a ticket. The only command that writes the Owner field: `set` does
|
||||
not offer it.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<user>`: The new owner. Free text, checked against nothing
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
The user comes first and the ticket second, after Unix `chown`. That is the one
|
||||
command here that does not start with the ticket, so mind the order: swap the two and
|
||||
the call fails, because the username has to resolve as a ticket. An owner set to the
|
||||
value it already holds is reported unchanged and nothing is written.
|
||||
|
||||
```bash
|
||||
worklane chown alice a1b2c3d4
|
||||
worklane chown "Ansho Rei" "A clearer title"
|
||||
```
|
||||
|
||||
### `worklane check` and `worklane uncheck`
|
||||
|
||||
Tick or untick a single acceptance criterion. Every other criterion keeps its state,
|
||||
and handwritten lines in the section are left alone.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
- `[criterion]`: The number as shown by `worklane show`, or a substring of its text
|
||||
|
||||
Omit the criterion and the numbered criteria are listed and the number asked for. With
|
||||
no terminal, as when driving the CLI from a tool, the same list comes back as an error
|
||||
instead, so re-run with the number. A substring matching more than one criterion is an
|
||||
error listing the matches with their real numbers.
|
||||
|
||||
```bash
|
||||
worklane check a1b2c3d4 2
|
||||
worklane check a1b2c3d4 "renames the file"
|
||||
worklane uncheck a1b2c3d4 2
|
||||
```
|
||||
|
||||
### `worklane comment`
|
||||
|
||||
Add a comment to a ticket.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
- `<body>`: Comment text
|
||||
|
||||
Comments are stored as timestamped markdown files in `.worklane/comments/<ticket-uuid>/` and include the git author and timestamp.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
worklane comment ticket-id "Reviewed, looks good"
|
||||
worklane comment "My Ticket" "Needs changes to the UI"
|
||||
worklane comment a1b2c3d4 "LGTM, approved"
|
||||
```
|
||||
|
||||
## Working a ticket
|
||||
|
||||
Move the ticket as you work it, not afterwards. The board should say what is happening
|
||||
now, not only what already landed.
|
||||
|
||||
1. `worklane show <id>` to read it
|
||||
2. **`worklane mv <id> --status committed` before writing any code.** This is what marks
|
||||
the ticket as being worked on, so it belongs at the start
|
||||
3. Do the work. `worklane check <id> <n>` as each criterion is met
|
||||
4. `worklane comment <id> <body>` with anything worth recording: a decision, a rejected
|
||||
acceptance criterion, something the ticket got wrong
|
||||
5. **`worklane mv <id> --status reviewing` once it is done and the tests pass**
|
||||
|
||||
Only one stage forward is allowed at a time, so a ticket left in `backlog` until the end
|
||||
cannot go straight to `reviewing`. It has to be walked through `committed` anyway, which
|
||||
makes moving it up front the same two commands in a more useful order.
|
||||
|
||||
## Commands
|
||||
|
||||
- `worklane add` creates tickets with all relevant details
|
||||
- `worklane ls [status]` views tickets by status
|
||||
- `worklane show <id>` views full ticket details
|
||||
- `worklane mv <id> --status <target>` moves tickets through the workflow
|
||||
- `worklane set <ticket>` corrects a field, `worklane append <ticket>` adds to a section
|
||||
- `worklane check <ticket> <n>` ticks a criterion as it is met
|
||||
- `worklane comment <ticket> <body>` adds notes to tickets
|
||||
@@ -3,6 +3,7 @@
|
||||
## Project Structure
|
||||
- `src/main.rs` - dispatch, the SIGPIPE reset, and the TUI event loop
|
||||
- `src/command.rs` - CLI argument definitions using clap derive
|
||||
- `src/completions.rs` - the generated completion script and the fish half that asks the board
|
||||
- `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
|
||||
@@ -12,6 +13,7 @@
|
||||
- `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/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`
|
||||
- Ticket files stored as `.md` in `.worklane/<status>/` directories
|
||||
@@ -20,9 +22,12 @@
|
||||
## 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`, `Campaign`, `Status`. `Campaign` is the one no ticket is born with: `add` does not write it, so it is inserted on demand
|
||||
- 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
|
||||
- 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
|
||||
|
||||
## Status Workflow
|
||||
@@ -39,7 +44,22 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- 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
|
||||
- `create_ticket()` writes fully-formed markdown files directly (no `--` separator for positional args in test commands)
|
||||
- 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:
|
||||
|
||||
| setting | value | why |
|
||||
|---|---|---|
|
||||
| `max_width` | 100 | The tree's own habit, and the measured optimum: 90 costs 268 hunks and 120 costs 194, against 161 at 100 |
|
||||
| `fn_call_width` | 75 | A call stays whole if it fits in three quarters of the line. rustfmt's default of 60 is what expanded 276 of the 305 hunks the default config wanted |
|
||||
| `chain_width` | 65 | The same for a method chain |
|
||||
| `struct_lit_width` | 30 | A small struct literal stays whole, so `Size { width: 120, height: 20 }` is not six lines |
|
||||
|
||||
**The numbers were measured, not chosen.** Default rustfmt wanted 305 hunks and would have added 1418 lines of pure layout, because its sub-widths sit far below the 100 columns this tree is written to. `use_small_heuristics = "Max"` went the other way, 308 hunks and 796 lines *removed*, one-lining `if`/`else` and collapsing struct literals that were split on purpose. Coordinate descent over the stable width knobs landed here, at 161 hunks, and 98 of those are rustfmt *joining* calls that fit rather than breaking them. Sweeping any one of these four in either direction makes the diff bigger, so do not adjust one by eye; measure it the same way, with `cargo fmt --check | grep -c '^Diff in'`
|
||||
- What this does not buy: rustfmt has no rule for "keep parallel arms parallel", so a match whose arms are one line and four lines depending on the length of their contents is what it produces, and that is accepted. Reach for `#[rustfmt::skip]` only where the layout carries meaning a reader needs, not to win an argument about density
|
||||
- Do not add an unstable option. `cargo fmt` on stable ignores them with a warning, so the tree would format differently for whoever ran nightly
|
||||
- **Sixteen lines still run past 100 columns and every one of them is a single string literal**, a test fixture or an error message rustfmt cannot break. `format_strings` is deliberately left at its default: turning it on would let the formatter rewrite message text, and a message is prose. So `max_width` is where rustfmt breaks lines, not a limit the tree keeps
|
||||
- The reformat is `73ffcad`, and `.git-blame-ignore-revs` names it so `git blame` looks through it. Turn that on once per clone with `git config blame.ignoreRevsFile .git-blame-ignore-revs`. A commit belongs in that file only if its diff is pure layout
|
||||
|
||||
## Coding Guidelines
|
||||
|
||||
@@ -57,32 +77,61 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **`--due` is validated at parse time by `iso_date`, the way `--priority` is by `priority_level`.** A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars without `PROSE`. One parser serves `add` and `set`: the field has one definition of what it accepts, and validating only `add` would leave `set` open, which is the command a grooming sweep actually uses
|
||||
- **The shape is checked before chrono is asked.** `%Y-%m-%d` accepts an unpadded `2026-8-9`, which would be stored exactly as typed and sort before `2026-10-01` in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting
|
||||
- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
|
||||
- An empty `--due` keeps `non_empty`'s message about clearing rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is that clearing is not supported yet
|
||||
- An empty `--due` keeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it
|
||||
- **`campaign add --codename` is validated at parse time by `codename`**, which is `non_empty` plus one word. The board draws it as a label with a mark and no quoting, so `~beaver release` on that row reads as two labels and the second one is not a campaign; a title is where a sentence goes. Nothing else is checked: there is no registry of codenames, the same reason `ls --tag` refuses to validate a tag, and a length limit would be a number invented in the parser when the row that draws it already drops a label it cannot hold
|
||||
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser
|
||||
- **A status is a `util::Status`, not a string.** `mv --status` and the `ls` positional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain `--due` and `--priority` take, and it is what lets the shells complete the four for free. `Status::ALL` is the flow order, which `status_dirs()` and `cmd_mv` both read rather than spelling the names again, and `DONE` is defined from it
|
||||
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title`
|
||||
- A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment <ticket> -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
|
||||
- `add` has no positionals, so anything after a bare `--` is an unexpected argument and fails
|
||||
- **A paragraph break in a description is an empty `--description` value.** `cmd_add` joins the values with a single newline, so `-d "First." -d "" -d "Second."` writes the blank line. `trim_blank_ends()` drops blank values at either end, so a break never lands against a section heading, and an all-blank description reads as no description. Interior runs are kept verbatim rather than collapsed
|
||||
- `--acceptance` and `--plan` are lists, one criterium or step per value, so a blank there is spacing rather than content and the opencode wrapper drops it. Only `--description` preserves blanks
|
||||
|
||||
### Completions
|
||||
|
||||
- **Two halves, and the split is the point.** `clap_complete` generates the structure from the clap definition, so a new flag or subcommand is completed without anyone touching `completions.rs`. Only fish gets the second half, appended by `fish_dynamic()`, and it holds exactly what clap cannot know: the tickets on the board
|
||||
- **The dynamic values come from worklane itself**, as `worklane ls --ids` in a command substitution, one run per keypress at 2.5ms in release. So the completions are only as current as the binary on PATH: an older one without `--ids` completes nothing, which is a reinstall rather than a bug
|
||||
- **What clap does and does not emit.** It emits the possible values of an *option*, which is why `mv --status <TAB>` needs nothing here, and nothing for a *positional*, which is why the `ls` status and the `completions` shell are listed in the fish half. Both lists are read off the enums with `possible_values`, never written out, so a fifth status appears in the script on its own
|
||||
- **Position is counted, not inferred.** The four `__worklane_*` predicates all read `$tokens[2]` and the token count rather than using `__fish_seen_subcommand_from`, because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen, and because matching against the ticket list would run worklane again inside the condition. `first_arg_of` and `second_arg_of` count a top-level command's arguments, `nested_arg_of` matches a parent and a child so `campaign show <TAB>` can be told from `chown alice <TAB>`, which sit at the same token count, and `command_is` asks only which command this is, at any position in it
|
||||
- **Every rule carrying `-l` needs a `__worklane_command_is`, and `every_rule_naming_an_option_is_scoped_to_a_command` is what enforces it.** A bare `complete -c worklane -l tag` does not just complete that option's values, it tells fish the whole tool accepts `--tag`: `worklane init --<TAB>` offered six options that only `relate` and `ls` have. Fixed in 55ee6e3. `__fish_seen_subcommand_from ls` is not the scope to use, for the nesting reason above
|
||||
- **The five completion lists are kept honest by tests** that walk the clap definition and fail on an argument left out of them. `TICKET_COMMANDS` and `TICKET_SECOND_COMMANDS` by position, `TICKET_FLAGS`, `CAMPAIGN_COMMANDS`, `CAMPAIGN_NESTED_COMMANDS`, `CAMPAIGN_FLAGS` and `TAG_FLAGS` likewise. The walk is one function, `every_argument`, since the tests differ only in the id they look for. Each also asserts *how many* it found, so a walker that stopped finding arguments fails rather than passing every assertion by never running them
|
||||
- **A campaign is named in three shapes and a tag in one**, which is why the lists are not one list: a campaign is `assign`'s first positional, the first argument of `campaign show` and `campaign set`, and `ls --campaign`'s value, and each needs a different fish rule. A tag is only ever an option value, and its values come from a different command
|
||||
- **`ls --ids` is the machine-readable listing**, and one of the three outputs in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script reads `cut -f1`. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown `--campaign` is still refused
|
||||
- **`campaign ls --ids` is the same flag and the same two fields for the other object**, and it deliberately skips the member counting the decorated listing does: `members()` reads every ticket on the board, and the caller here is a shell filling in candidates on a keypress. It also prints nothing on an empty board, where the decorated listing prints a sentence, because a sentence offered as a candidate is worse than no candidates
|
||||
- **`worklane tags` is the third, and it is a command rather than a mode on `ls`.** Two reasons: `ls --tag <tag>` answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a `--tags` beside a `--tag` is one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, so `bug` and `Bug` list separately and land next to each other, which is where a near-duplicate is spotted. Every status, done included: a tag that has fallen out of use is still part of what the vocabulary has been. `assets/PLAN.md` used to tell the agent to count tags with a `show` per ticket, and now points here
|
||||
|
||||
### Filtering the Listing
|
||||
- **The filters are one call, `filtered`,** because `ls` collects a column in three places (a named status, the counts, and the grouped listing) and three call sites are three chances to apply a different set. Every filter is an `Option` and none asked for keeps everything, which is what makes them compose in any combination without a rule per pair
|
||||
- **`--tag` matches whole values, not the field.** `parse_tags` has already split the comma-separated field, so the filter compares against those trimmed values: `--tag bug` is not answered by a ticket tagged `bugfix`, and `--tag "cli, filter"` matches nothing, because the field as written is not itself a tag. A ticket with no tags matches none
|
||||
- **Case sensitive**, the opinion the field already takes: `tag_color` draws `Bug` and `bug` in two colours because they are two tags. A filter that folded them would list tickets carrying a tag nobody asked for, and would hide exactly the split a grooming sweep is looking for
|
||||
- **One tag per invocation.** Several would have to decide between and and or, and neither reading is obviously right for a board this size. That decision is its own ticket, along with a substring or regex match and a tag filter on the tui
|
||||
- **A tag nothing carries lists nothing rather than being refused**, which is the opposite of `--campaign`. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have. `assets/PLAN.md` tells the agent to check the spelling when a listing comes back empty, since that is the failure this trades for
|
||||
- **A tag nothing carries lists nothing rather than being refused**, which is the opposite of `--campaign`. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have. `assets/PLAN.md` tells the agent to check the spelling when a listing comes back empty, and `worklane tags` is what it checks against, since that is the failure this trades for
|
||||
- An emptied status keeps the message `ls` already gives, `No tickets in '<status>' status.`, rather than one per filter naming what excluded them. That is pre-existing behaviour for `--priority` and `--campaign`, and one message for every filter is the consistent half of it. If it should name the filter, that is a change to what the CLI prints for three flags at once and belongs in its own ticket
|
||||
- **`cmd_ls` is now at the boundary the Rust Style rule names:** four filters and the directory. Two of them are adjacent `&Option<String>` parameters, which a caller can swap silently, so the next filter added here takes an `LsArgs` struct the way `add` took `AddArgs`, rather than a fifth positional
|
||||
- **`cmd_ls` takes an `LsArgs`**, which is what the boundary in the Rust Style rule came to: four filters, an output mode and the directory, two of them adjacent `Option<String>` values a caller could swap silently. `--ids` was the argument that tipped it, the way `add` became `AddArgs`. A new filter is a field there, not a parameter
|
||||
|
||||
### Editing a Ticket
|
||||
- `set` replaces a field, `append` adds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, and `append` only offers the sections that hold multiple lines
|
||||
- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s). Do not add either
|
||||
- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s), and neither `add`, `set`, `append` nor `chown` can reach the three status stamps, which `mv` writes as a side effect of the move. Do not add any of them
|
||||
- `chown` takes the **user first and the ticket second**, after Unix `chown`, and is the only command that does not start with the ticket. Deliberate: the name borrows the Unix association, so the order borrows it too. A swap is left to `resolve_ticket`, which refuses a bare username as a ticket. No argument is inspected to see whether it *also* names a ticket, since such a check would only fire where resolution already fails and would stay silent on the one case it cannot catch, a ticket whose title is the username
|
||||
- `cmd_chown` is `set_metadata_field` plus `save_ticket`, with the same whole-file no-op comparison `set` uses and the same `report()` output, so nothing about writing a field lives twice
|
||||
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, and a `SectionKind`. Adding a section later is one entry, not edits in both commands
|
||||
- `apply()` is the one place an edit is taken or dropped, shared by `set`'s replaced list and its cleared one. It was a closure over the single list until there were two, and two closures carrying one rule is how a later edit changes it for one and not the other
|
||||
- Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, a `SectionKind` and the `--clear` value that empties it. Adding a section later is one entry, not edits in both commands
|
||||
- Everything is targeted line surgery, never a regenerated file. That is what keeps a ticked criterion ticked and a handwritten `## Notes` section intact when an unrelated field changes. `section_body()` finds the lines to touch, `set_metadata_line()` does the metadata, and every other byte is copied through
|
||||
- Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
|
||||
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read `_No description provided._` above its description
|
||||
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` in `command.rs`. Clearing a field is not supported yet, and the error says so rather than guessing
|
||||
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` and `clearable` in `command.rs`. Neither spells clearing, and both errors name the flag that does
|
||||
|
||||
### Clearing a Field
|
||||
- **`set --clear <field>` is the one way to take a value away, and it is a flag with the field as its value.** Not a per-field `--clear-due`, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likes
|
||||
- **`Clearable` is a `ValueEnum` in `util.rs`**, so an unknown field is a usage error at the door listing the six that are not, and the shells complete them for free. It is also the whole table of what can be cleared: `Due`, `Tags` and `Priority` clear to a sentinel, `Description`, `Acceptance` and `Plan` to their section's placeholder. `Title` is absent because it addresses the ticket and names its file, so there is no state to go back to; `Owner`, `Status`, `Campaign` and the stamps because clearing them through `set` is exactly the second writer the missing `set --owner` exists to prevent
|
||||
- **What is written is `NOT_SET` and `NONE`, the constants `add` writes.** A cleared ticket and one that was never given the field have to read the same, or clearing would be a third state that every parser then has to know about. `a_cleared_ticket_reads_like_one_filed_without_the_fields` compares the two files byte for byte, which is what keeps a new field honest
|
||||
- **The placeholder goes into a section bare, via `clear_section_body`.** `set_section_body` runs its items through `Section::render`, which would write `- [ ] _No acceptance criteria provided._`. Both are `replace_section_body` underneath, so the line surgery and the trailing blank line live once
|
||||
- **The pairing between a section and its `--clear` value is stored on both**, `Clearable::unset` one way and `Section::clear` the other, because the error for an empty value has to name the flag for *that* section and the section's label ("acceptance criteria") is not the flag's value ("acceptance"). `every_clearable_section_points_back_at_the_field_that_clears_it` keeps the two directions from drifting. `RELATIONS.clear` is `None`, the same rule that keeps it out of `section_args`
|
||||
- **Cleared fields are reported apart from replaced ones**, as `Cleared due on '...'` beside `Updated priority on '...'`. One list would say `Updated` of a field that was emptied, which is the opposite of what a caller needs to read back. The labels are the ones `set` already prints when it *writes* the field, so the two lines name a field the same way
|
||||
- **Replacing and clearing one field in a single call is refused**, by `SetArgs::contested`. clap cannot express it, because the field arrives as `--clear`'s value rather than in its name, and answering by whichever was applied last is a silent answer to a contradictory call
|
||||
- **Clearing the owner is `chown --clear <ticket>`, and `--clear` carries the ticket.** Owner has one writer and clearing it cannot introduce a second, so it lives on `chown`; but the ticket is `chown`'s *second* positional, and a bare flag would land it in the user's slot for the handler to read back out, which is hand-parsing what clap can state. The typed call is identical either way. `ChownArgs::target` returns the one shape the constraints allow, and an error rather than a panic for the combination they already refuse
|
||||
- **Clearing the owner writes `NOT_SET`, not the git user.** `add` falls back to the git user because it is filing something new; an owner taken away says nobody owns this, and putting the person running the command there instead hands them a ticket they were giving up
|
||||
- Clearing a field that is already unset writes the sentinel that is already there, so the whole-file comparison below reports no change and nothing is written. That is not a special case, and must not become one
|
||||
- No-op detection compares the whole file before and after each edit, so a field set to the value it already holds is reported unchanged and nothing is written
|
||||
- `find_ticket_file()` matches on the uuid, never the title. Duplicate titles are allowed, so a title scan can land on a different ticket than the one resolved: `mv <uuid-of-second>` used to move the first ticket sharing its title
|
||||
- `write_then_replace()` is the only way a ticket file is written. Content first, rename second, so a failure leaves a correct ticket under a stale name rather than a half-written one
|
||||
@@ -123,12 +172,19 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **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
|
||||
- **`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 three 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
|
||||
- **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
|
||||
- **An exact `Codename` is the top tier, and it lives in the shared resolver rather than in a campaign-only path.** Only campaigns carry the field, so `parse_codename` returns `None` for every ticket and the tier is always empty for one: ticket resolution is unchanged, which `a_ticket_search_is_unaffected_by_the_codename_tier` pins. It goes above the uuid prefix because it is an exact match on a field written for the purpose, where a substring can be a coincidence, and because a codename like `v1` is below `MIN_ID_SEARCH` and would never be tried as an id at all. A codename that a title also contains, `v2` against `v2 release`, has to win outright rather than be reported ambiguous against it
|
||||
- **`resolve_ticket` explains a search that names a campaign**, rather than each command doing it. One place, so `mv`, `show`, `chown` and everything else that takes a ticket give the same reason instead of a bare "no ticket found". Checked only on the zero-match path, so it costs nothing normally, and only when exactly one campaign matches: an ambiguous ticket error must not be replaced by a complaint about a directory the caller never mentioned
|
||||
- **`Resolved` carries what `content_trim` cannot render from the file.** The relations block and the campaign cell both come from elsewhere on the board. A struct rather than two more parameters, so the next such field is one entry here instead of an edit at every call site
|
||||
- `campaign show` lists **done** members, unlike `ls`, which leaves the done column out of its listing. What is finished against what is left is the whole question a campaign asks, so hiding half the answer is not an option. `ls --campaign` is the other way round: it is the ordinary board filtered, and keeps every rule `ls` already has
|
||||
- `campaign ls` scans the status directories **once per campaign** to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice
|
||||
- **The TUI gets neither a campaign tab nor a card marker**, for now. The detail view resolves the field because it renders the body, and that is all. A marker on a card would want a campaigns read per reload, which is more than the blocked mark cost: that one reads the ticket's own Relations section on the pass that already builds the card, and a campaign title is in another directory
|
||||
- **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
|
||||
- **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 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
|
||||
- The campaigns directory is created by `init` and **on demand** by `campaign add`, since every board made before campaigns existed has none and a `worklane init` over a live board to get one would be a strange thing to have to do
|
||||
|
||||
@@ -145,6 +201,12 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- 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
|
||||
- **The overlay carries a page indicator on the bottom right of its border**, `pg 2/8`, so a long ticket does not open looking exactly like a short one. `Block::title_bottom` with a right-aligned `Line`, which spends no text row, the trade the title already makes on the top border. The two cannot crowd each other: they are on opposite borders
|
||||
- **`wrapped_height` is the one measurement.** `last_offset` is it less the viewport and `page_indicator` takes the same two numbers, so the clamp and the indicator cannot disagree. A second `line_count` call, or a count of the raw lines, is a number free to drift, and an indicator that says there is more to read where the scroll refuses to move is worse than none
|
||||
- **The furthest offset is the last page by definition, not by division.** The clamp stops at the wrapped height less the viewport, which is not a page boundary, so the final screenful is partial: `offset / step + 1` reads `pg 2/3` at the bottom of a 25 row ticket in a 10 row viewport and claims there is more below
|
||||
- **The pages are counted in `scroll_step`, a screenful less the overlap line, not in whole screenfuls.** The step is what the keys take, so counting in it names only pages `pgdn` can land on. Counting by screenfuls puts a 30 row ticket in a 10 row viewport at `pg 3/3` two rows short of its end, since three presses are what it takes to get there
|
||||
- The indicator is dropped whole on an overlay too narrow for it, the rule a corner and the tags row already follow, and absent entirely when nothing scrolls, the way an untagged card spends no row on tags
|
||||
- `page_indicator` takes four numbers and returns an `Option<String>`, so every case above is pinned without a terminal. The drawn tests exist for the two things arithmetic cannot answer: which border it landed on and what colour it reached the screen in
|
||||
- **Columns scroll to keep the selected card in view.** `Board::offsets` holds one offset per column, parallel to `columns` and resized in step by `reload`, so a column you leave stays where it was. The keypress aligns the focused column via `follow_selection(screen)`, taking the screen size for the same reason `scroll_detail` does: the visible height belongs to the terminal, which only the caller measures between draws
|
||||
- Card heights are measured on `card_lines`, never assumed, on both the keypress and the draw side (`card_height`, and the `starts` vec as the cards are built). An alignment that trusted a fixed card height would drift from the renderer the first time the card changed shape
|
||||
- The draw aligns the focused column again on its own geometry, so a resize between keypress and frame cannot hide the selection, and caps every column against blank space past its last card. The stored value may go stale after a tick shrinks the column; that is fine, because what is drawn is corrected immediately and the next navigation writes the correction back
|
||||
@@ -157,11 +219,44 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `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
|
||||
- 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, criteria count bottom right. The two numbers are in corners because that is where the eye goes for one, and both were invisible at the end of a line of prose
|
||||
- **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
|
||||
- **A card's height therefore depends on the column's width**, so `card_lines` and `card_height` both take it. `column_areas` is shared between the draw and `follow_selection` for the same reason: `Ratio` hands the remainder column to whichever slot it likes, and reproducing that arithmetic by hand is how the measurement and the draw come to disagree about where a card starts
|
||||
- **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 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
|
||||
- **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
|
||||
- **`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 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
|
||||
- **`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
|
||||
- **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
|
||||
@@ -227,6 +322,13 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `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
|
||||
|
||||
### 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
|
||||
- Anything other than `NotFound` from `symlink_metadata` is an error rather than an `Absent`. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place
|
||||
- The dangling failure **names the target and says the boards repo may not be cloned**, and deliberately does not say to run `worklane init`. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem
|
||||
- **A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.** `.worklane/backlog/*.md` has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on
|
||||
- A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today
|
||||
|
||||
### Monitoring Several Boards
|
||||
- `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
|
||||
@@ -234,7 +336,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **`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
|
||||
- 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. That comparator is exported for this and is the one `collect_ticket_items` uses, so the two orders cannot drift
|
||||
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes `by_status_order`: the merge spans statuses, so no single entry stamp governs it
|
||||
- `Card` wraps a `TicketItem` with the project it came from, `Some` only on the merge tab. Decided at reload rather than passed down to `card_lines` as a "which tab is this" flag. `TicketItem` is therefore `Clone`: the merge holds a second copy rather than re-reading every tree
|
||||
- **The project follows the id, on the card and on the overlay border.** Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live. `project_label` takes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is what `corner_line` drops
|
||||
- `tab` and `shift+tab` cycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns took `hjkl` and the arrows
|
||||
@@ -243,13 +345,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
|
||||
### 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
|
||||
- **One install path serves both agents:** `~/.claude/skills/worklane/SKILL.md`. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own `~/.config/opencode/skill/`. Verified against opencode 1.15.10, whose built-in `customize-opencode` skill documents the table and whose `opencode debug skill` lists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain
|
||||
- `Asset` carries the content, the path under its root and the word used in messages, so `install-tool` adds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module is `install.rs` and not `skill.rs`
|
||||
- `install()` takes the root as an argument. That is what lets the tests install into a temp directory instead of the home of whoever runs the suite, and the integration test redirects `HOME` for the same reason
|
||||
- **A modified copy is refused, not overwritten.** Someone may have edited it on purpose, and the message names `--print` so it can be diffed and `--force` so it can be replaced. A read error is not treated as absent either: the write reports the real reason
|
||||
- Three tests guard the document rather than the mechanism, and they are the ones that earn their keep: the frontmatter has to parse (both agents silently ignore a document without it), every `worklane <x>` the skill shows has to be a real subcommand, and every subcommand outside `NOT_FOR_AGENTS` has to appear in the skill. The last one catches a new command that nothing tells an agent about
|
||||
- `install-skill` looks for no board. The skill is what teaches an agent worklane, so needing a `.worklane` to install it would put it out of reach exactly when it is wanted
|
||||
- The assets under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them. `reviewing-agent.md` there is the prior art the review skill grew out of and is deliberately **left in place**: its content is now in `assets/REVIEW.md`, but deleting a file under `.opencode/` is not this repo's call. Whether the stale copies there go is b2c5531's question
|
||||
- The **agent files** under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them. `reviewing-agent.md` there is the prior art the review skill grew out of and is deliberately **left in place**: its content is now in `assets/REVIEW.md`, but deleting a file under `.opencode/` is not this repo's call. Whether the stale copies there go is b2c5531's question. The tool file is the exception and no longer lives there: it was `.opencode/tools/worklane.ts`, which meant it existed only inside a checkout, and it is now `assets/TOOL.ts` and shipped like every other asset
|
||||
- **`install-skill` writes every shipped document, and the name narrows it.** One document teaches the CLI and the others teach a job done with it, so a person who learned the invocation before a document existed still receives it. Requiring a name per document would mean a new skill silently never arrives for anyone who does not read the changelog
|
||||
- **`--print` requires the name.** It exists so a modified copy can be diffed, and a diff is against one document; printing them concatenated would be neither of them. The unnamed case errors with the list of names rather than guessing, the same choice the `comment --` body makes
|
||||
- The refusal message names the document it is about, `install-skill worklane --print`, since with several installed "compare with --print" does not say compare what
|
||||
@@ -258,6 +361,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- The review skill's own rules are guarded by `the_review_skill_keeps_the_decisions_that_define_it`, because each of them is a line an edit could drop without breaking anything: **the reviewer never ticks a criterion** (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), **never moves the ticket** (`mv` belongs to whoever does the work, the reviewer's half is the recommendation), and **never reviews the working tree when no commit names the ticket** (it says what it searched for and stops, since an untraceable ticket in `reviewing` is itself the finding)
|
||||
- **The plan skill is the one that can do damage, so its rules are the ones under test.** `set --tags` replaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable. `the_plan_skill_keeps_the_rules_that_bound_a_sweep` pins propose-then-apply and those two traps, because a document that loses them still reads like a plan
|
||||
- `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document
|
||||
- **`install-tool` is a second command, not a flag on `install-skill`, because the two artifacts are not alike.** A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: `claude mcp add` with a `stdio`, `sse` or `http` transport is the only way a tool enters its tool list, and its plugin system adopts `agents`, `hooks`, `monitors`, `workflows`, `output-styles` and `themes` and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238
|
||||
- **`tools_root()` follows `XDG_CONFIG_HOME`, `skills_root()` does not.** `~/.claude` is not an XDG path and opencode's config root is: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without. An empty value counts as unset, the convention `colors_wanted` follows for `NO_COLOR`. `opencode_tool_dir` takes both variables as arguments for the reason `colors_wanted` does, since a threaded test binary cannot mutate the process environment to reach one branch at a time
|
||||
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered all eleven worklane tools. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
|
||||
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's eleven `export const` lines become `worklane_add` through `worklane_uncheck`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
|
||||
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all eleven tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
|
||||
- **The closing line differs from the skills', and that is not a wording choice.** opencode reads its config once at startup and never reloads it, so a running one keeps the tools it began with; the skills' "on their next session" would be a claim that is not true here
|
||||
- **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
|
||||
|
||||
### Color and Output
|
||||
@@ -280,6 +391,9 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
|
||||
- Relation kind mark → brightred `×` blocked by and blocks, cyan `→` relates to, orange `←` regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking
|
||||
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `?` for a target the board does not hold. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
|
||||
- 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
|
||||
- **The palette splits in two: seven colours that each mean one thing, and `TAG_COLORS`, the eight a tag may be drawn in.** A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour in `TAG_COLORS`, and do not draw a tag in one outside it
|
||||
- `tag_color()` is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, because `Bug` and `bug` are two different tags to the field and to every search
|
||||
- **The hash is FNV-1a written out here, not `DefaultHasher`.** std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for. `the_tag_mapping_is_pinned` fails on any change to it, so a repaint is a decision rather than a surprise
|
||||
@@ -299,11 +413,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
|
||||
### Ticket Resolution
|
||||
- `resolve_ticket()` returns `(status, title, content)` tuple
|
||||
- Three tiers, evaluated in order: UUID prefix > title substring > filename substring. The first non-empty tier wins outright and later tiers are not consulted. This is not cosmetic: ticket titles reference other tickets by id, so a flat OR of the three reported an exact prefix match as ambiguous against whichever title mentioned it
|
||||
- Four tiers, evaluated in order: exact codename > UUID prefix > title substring > filename substring. The first non-empty tier wins outright and later tiers are not consulted. This is not cosmetic: ticket titles reference other tickets by id, so a flat OR of the tiers reported an exact prefix match as ambiguous against whichever title mentioned it
|
||||
- The codename tier is a campaign's, and empty for a ticket, which has no such field. Case insensitive like the other three, so a codename typed back off a listing resolves whatever case it was read in. See Campaigns for why it sits above the uuid prefix
|
||||
- The UUID tier applies from `MIN_ID_SEARCH` (4) characters up. Not 8: `ls` prints `SHORT_ID_WIDTH` (7) characters, so a longer minimum would drop the printed id out of the UUID tier and let any title quoting it win instead. Below the minimum the search is text, so `show 641` is a title search
|
||||
- The filename tier earns its place by reaching the middle of a UUID, which the prefix tier cannot. It is also why a short UUID search still resolves under a longer minimum, just at the wrong precedence, so a test for the minimum needs a decoy title to be meaningful
|
||||
- Ambiguous matches (multiple results) print options and exit(1)
|
||||
- Never return empty strings for required fields — use `_Not set_` or `_None_` as defaults
|
||||
- Never return empty strings for required fields — use the `NOT_SET` and `NONE` constants in `util.rs`, which are what `add` writes and what `--clear` puts back. `is_unknown_value` reads those two and nothing else
|
||||
- **`-None-` and `-Not set-` are not unset, and re-adding them would be a mistake with a plausible story behind it.** They were accepted by `is_unknown_value` from the day it was written, by analogy with the `**-Status**` field name the `mv` splicing bug really did produce, c230d2c. But no version of this tool ever wrote a hyphenated *value*: `git log -S` finds both spellings in exactly one commit, the one that added them to the check. Dead from birth, and dropped by bdddc09. `a_hyphenated_marker_is_not_unset` is what stops the analogy being drawn a second time
|
||||
- **The `**-Status**` repair in `is_status_line` is the opposite case and stays.** That corruption was real, `mv` wrote it, and the repair is what fixes a damaged ticket as it moves. Do not tidy the two away together on the grounds that they look alike
|
||||
|
||||
### Git Workflow
|
||||
- Commit format: `([ticketID]) [short description]`
|
||||
|
||||
Generated
+11
-1
@@ -208,6 +208,15 @@ dependencies = [
|
||||
"strsim",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "clap_complete"
|
||||
version = "4.6.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3be2ad0423bdbbb0e25bc89add796f3559706d4a95e1bc98e4d9662a957b6a19"
|
||||
dependencies = [
|
||||
"clap",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "clap_derive"
|
||||
version = "4.6.1"
|
||||
@@ -1494,13 +1503,14 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "worklane"
|
||||
version = "0.16.0"
|
||||
version = "0.25.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"assert_fs",
|
||||
"chrono",
|
||||
"clap",
|
||||
"clap_complete",
|
||||
"crossterm",
|
||||
"libc",
|
||||
"ratatui",
|
||||
|
||||
+2
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "worklane"
|
||||
version = "0.16.0"
|
||||
version = "0.25.0"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
@@ -14,6 +14,7 @@ libc = "0.2"
|
||||
# widget until one of us changed.
|
||||
ratatui = { version = "0.29", features = ["unstable-rendered-line-info"] }
|
||||
crossterm = "0.28"
|
||||
clap_complete = "4.6.9"
|
||||
|
||||
[dev-dependencies]
|
||||
assert_cmd = "2"
|
||||
|
||||
@@ -5,27 +5,67 @@ 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, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `q` to quit. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
|
||||
| `worklane` 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 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` |
|
||||
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring |
|
||||
| `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 |
|
||||
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused |
|
||||
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last |
|
||||
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning. `mv` refuses to move a ticket blocked by one that is not done, unless `-f` |
|
||||
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown` |
|
||||
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to |
|
||||
| `worklane check <ticket> [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal |
|
||||
| `worklane uncheck <ticket> [criteria...]` | Unticks acceptance criteria, addressed the same way |
|
||||
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
|
||||
| `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 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-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 |
|
||||
|
||||
## Completions
|
||||
|
||||
```sh
|
||||
worklane completions fish > ~/.config/fish/completions/worklane.fish
|
||||
```
|
||||
|
||||
Also `bash`, `zsh`, `elvish` and `powershell`, though only fish gets the dynamic half.
|
||||
|
||||
The structure comes from clap, so new flags appear without anyone remembering to add them. The four
|
||||
statuses come with it, because a status is a value enum rather than a string. On top of that, fish
|
||||
asks worklane for the one thing only the board knows:
|
||||
|
||||
```
|
||||
worklane show <TAB> every ticket, id and title, done included
|
||||
worklane mv <TAB> the same, then --status <TAB> for the four
|
||||
worklane chown alice <TAB> the ticket, which is the second argument here
|
||||
worklane chown --clear <TAB> the ticket, which the flag carries here
|
||||
worklane relate x --blocked-by <TAB>
|
||||
worklane campaign show <TAB> the campaigns, from `campaign ls --ids`
|
||||
worklane assign <TAB> the same, since a campaign comes first here
|
||||
worklane ls --campaign <TAB> and again
|
||||
worklane ls --tag <TAB> the tags, from `worklane tags`, with their counts
|
||||
```
|
||||
|
||||
The tickets come from `worklane ls --ids`, the campaigns from `worklane campaign ls --ids` and the tags
|
||||
from `worklane tags`, one run per keypress, 2.5ms in release on a board of seventy-five tickets. Since fish runs whatever `worklane` is on PATH, **completions need the
|
||||
installed binary to be current**: an older one without `--ids` completes nothing. Re-run
|
||||
`cargo install --path .` after pulling.
|
||||
|
||||
`tui` is the one command whose argument is a path, so it is the one place fish still offers
|
||||
directories.
|
||||
|
||||
## Exit codes
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | An error, such as no matching ticket or an ambiguous search |
|
||||
| 2 | A usage mistake, such as an unknown flag |
|
||||
| 2 | A usage mistake, such as an unknown flag, an unreal `--due` date, a priority out of range or a status that is not one of the four |
|
||||
| 141 | Output was piped to a reader that stopped early, for example `worklane ls \| head -3` |
|
||||
|
||||
141 is 128 + 13, the shell's way of reporting death by `SIGPIPE`. Worklane restores
|
||||
|
||||
+39
-21
@@ -16,11 +16,12 @@ which command owns which field. Read it too. This document is the judgement.
|
||||
|
||||
**Propose the whole set of edits, wait, then apply exactly what was approved.**
|
||||
|
||||
Every job here writes to many tickets at once, and no field can be cleared back to unset
|
||||
yet, so a date written onto the wrong ticket can only be overwritten, never taken off. A wrong
|
||||
edit to one ticket is a mistake; a wrong sweep is thirty of them with no undo. So a
|
||||
proposal is a list, one line per intended edit, each naming the ticket and the command
|
||||
that would make it:
|
||||
Every job here writes to many tickets at once, and nothing on the board records what a
|
||||
field held before you wrote to it. `--clear` puts a field back to unset, which is **not
|
||||
back to what it held**, so a date written over another date is gone. A wrong edit to one
|
||||
ticket is a mistake; a wrong sweep is thirty of them with no undo. So a proposal is a
|
||||
list, one line per intended edit, each naming the ticket and the command that would make
|
||||
it:
|
||||
|
||||
```
|
||||
(1b78a24) priority 3 -> 1 worklane set 1b78a24 --priority 1
|
||||
@@ -37,10 +38,10 @@ other way is editing the file by hand:
|
||||
|
||||
| Field | Writer |
|
||||
|-------|--------|
|
||||
| Priority, Due, Tags | `worklane set <ticket> --priority` / `--due` / `--tags` |
|
||||
| Priority, Due, Tags | `worklane set <ticket> --priority` / `--due` / `--tags`, and `--clear <field>` to empty one |
|
||||
| Relations | `worklane relate <ticket> --blocked-by` / `--regression-of` / `--relates-to` |
|
||||
| Campaign membership | `worklane assign <campaign> <ticket>` |
|
||||
| Owner | `worklane chown <user> <ticket>` |
|
||||
| Owner | `worklane chown <user> <ticket>`, and `worklane chown --clear <ticket>` to empty it |
|
||||
| Status | `worklane mv <ticket> --status <target>` |
|
||||
|
||||
**Never edit a ticket file directly.** The filename, the `Status` field and the directory
|
||||
@@ -57,16 +58,17 @@ worklane ls # every status, counts then tickets
|
||||
worklane ls backlog # one status
|
||||
worklane ls --priority 1 # the top of the pile
|
||||
worklane ls --tag bug # one tag's worth of the board
|
||||
worklane tags # the whole vocabulary, with counts
|
||||
worklane show 1b78a24 # one ticket, with its relations and comments
|
||||
worklane campaign ls # the goals that already exist
|
||||
```
|
||||
|
||||
`ls` prints the mark, the id, the title, the owner and the due date. It does **not**
|
||||
print tags, so the vocabulary itself still has to be read off the tickets: `--tag` answers
|
||||
"what is tagged `bug`" and cannot answer "what tags exist", which is the question a
|
||||
grooming sweep starts from. Count the vocabulary with a `show` per ticket, then use
|
||||
`--tag` to check each candidate, and remember that `--tag` matches whole values case
|
||||
sensitively: `bug` and `Bug` are two answers, which is exactly the split worth reporting.
|
||||
`ls` prints the mark, the id, the title, the owner and the due date, and **not** the tags.
|
||||
So the vocabulary comes from `worklane tags`, which is the one command that answers what
|
||||
tags exist rather than what carries a tag you already know. One line per tag, alphabetical,
|
||||
as the tag, a tab and its count. It is case sensitive like the filter, so `bug` and `Bug`
|
||||
list separately and, being alphabetical, land next to each other, which is where a
|
||||
near-duplicate is spotted. Start a tag sweep there rather than with a `show` per ticket.
|
||||
|
||||
Read `done` too when the question is about what to do next. What was finished last is the
|
||||
best evidence of what this board actually moves at, and a plan that ignores it is a wish.
|
||||
@@ -101,8 +103,9 @@ What to look for:
|
||||
|
||||
A value that is not a real calendar date in that exact form is refused before anything
|
||||
is written, so a typo costs nothing. `2026-8-9` is refused too: the padding is part of
|
||||
the format. What is still true is that a date, once written, **cannot be cleared**, only
|
||||
replaced by another date, so a plan applied to the wrong ticket has no undo.
|
||||
the format. A date can be taken off again with `worklane set <ticket> --clear due`. What
|
||||
that cannot do is recover the date that was there before it, so a plan applied over
|
||||
existing dates still has no undo.
|
||||
|
||||
Ask the system what today is rather than assuming it. A plan built on a guessed date is
|
||||
wrong by however much the guess was wrong.
|
||||
@@ -119,15 +122,21 @@ The rules a dating plan has to keep:
|
||||
whole backlog produces a board where every ticket is late, which is the same as no
|
||||
dates at all.
|
||||
- **Do not date `done`.** It is finished; a date on it is noise in every listing.
|
||||
- Leave the rest unset. An unset due date is honest about what has not been planned.
|
||||
- Leave the rest unset. An unset due date is honest about what has not been planned, and
|
||||
a date that turned out to be wrong is better cleared than left to read as a plan.
|
||||
|
||||
## Tags
|
||||
|
||||
`worklane set <ticket> --tags bug,cli` is the writer, and it **replaces the whole
|
||||
field**. Restate every tag the ticket should keep, or the ones you left out are gone.
|
||||
This is the single most destructive thing in this document.
|
||||
This is the single most destructive thing in this document. `--clear tags` empties the
|
||||
field on purpose, which is a different thing from emptying it by forgetting a tag.
|
||||
|
||||
Derive the vocabulary from the board rather than inventing one. Read the tickets, count
|
||||
`worklane tags` before and after a tag sweep is the cheapest check that it did what was
|
||||
proposed: a count that dropped where nothing was meant to change is a tag lost to the
|
||||
replace-the-whole-field rule above.
|
||||
|
||||
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:
|
||||
|
||||
- **Two spellings of one idea.** `bug` and `bugfix`, `tui` and `ui`. Pick the one already
|
||||
@@ -149,9 +158,10 @@ fields; a goal is a campaign.
|
||||
|
||||
```
|
||||
worklane campaign ls
|
||||
worklane campaign show "v1 release"
|
||||
worklane campaign add --title "..." --description "..."
|
||||
worklane assign "v1 release" 1b78a24
|
||||
worklane campaign show v1
|
||||
worklane campaign add --title "..." --codename v1 --description "..."
|
||||
worklane campaign set v1 --title "..." # or --codename, on one already filed
|
||||
worklane assign v1 1b78a24
|
||||
```
|
||||
|
||||
A campaign is the tickets that have to be finished **together** for one outcome. The test
|
||||
@@ -168,6 +178,14 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
|
||||
- **A campaign's state is derived**, open until every member is done. There is nothing to
|
||||
close and nothing to move. A campaign whose members are all done is finished already.
|
||||
- `assign` takes the **campaign first and the ticket second**, like `chown`.
|
||||
- **Propose a codename with the campaign**, one word, `v1` or `beaver`. It is what the
|
||||
board draws on every card in it and the shortest thing that addresses it at the command
|
||||
line, and a campaign filed without one is drawn by its short id, which says nothing. A
|
||||
campaign already on the board that has no codename is worth pointing out for the same
|
||||
reason a near-duplicate tag is, and `campaign set` is how it gets one without refiling.
|
||||
- **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.
|
||||
|
||||
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.
|
||||
|
||||
+73
-14
@@ -35,6 +35,12 @@ 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.
|
||||
|
||||
## Reading the board
|
||||
|
||||
```
|
||||
@@ -47,6 +53,11 @@ worklane show 1b78a24 # one ticket, body and comments
|
||||
|
||||
`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
|
||||
when you want the ids themselves: `worklane ls --ids | cut -f1`. The decorated listing is
|
||||
for reading, not for cutting up.
|
||||
|
||||
The filters compose in any combination, with each other and with the status positional:
|
||||
`worklane ls backlog --tag bug --priority 1`. `--tag` takes one tag and matches it
|
||||
against the whole values of the comma-separated `Tags` field, case sensitively, so
|
||||
@@ -54,6 +65,12 @@ against the whole values of the comma-separated `Tags` field, case sensitively,
|
||||
tags matches none. A tag nothing carries lists nothing rather than failing, so when a
|
||||
listing comes back empty check the spelling against a ticket you know is tagged.
|
||||
|
||||
`worklane tags` answers the other question, the one `--tag` cannot: **what tags exist**.
|
||||
One line per tag, alphabetical, as the tag, a tab and how many tickets carry it. Case
|
||||
sensitive, like the filter, so `bug` and `Bug` list separately and land next to each
|
||||
other, which is where a near-duplicate is spotted. Read it before inventing a tag, and
|
||||
read it when a `--tag` filter comes back emptier than expected.
|
||||
|
||||
## Working a ticket
|
||||
|
||||
```
|
||||
@@ -113,21 +130,34 @@ worklane add \
|
||||
Editing afterwards, on a ticket in any status:
|
||||
|
||||
```
|
||||
worklane set 1b78a24 --priority 1 # replace a field
|
||||
worklane set 1b78a24 --priority 1 # replace a field
|
||||
worklane set 1b78a24 --title "A better title" # renames the file, keeps the uuid
|
||||
worklane set 1b78a24 --clear due # take a value away again
|
||||
worklane set 1b78a24 --clear tags --clear plan # as many fields as you like
|
||||
worklane append 1b78a24 --acceptance "One more criterion"
|
||||
worklane append 1b78a24 --description "What was learned since."
|
||||
worklane chown alice 1b78a24 # hand the ticket to someone
|
||||
worklane chown --clear 1b78a24 # hand it back to nobody
|
||||
```
|
||||
|
||||
`set` replaces, `append` adds. Neither has `--owner` or `--status`: owner is `chown`'s
|
||||
and status is `mv`'s, so each field has exactly one writer. A field set to the value it
|
||||
already holds is reported unchanged and nothing is written.
|
||||
`set` replaces, `append` adds, `--clear` empties. Neither `set` nor `append` has
|
||||
`--owner` or `--status`: owner is `chown`'s and status is `mv`'s, so each field has
|
||||
exactly one writer. A field set to the value it already holds is reported unchanged and
|
||||
nothing is written, and so is a field cleared that was already unset.
|
||||
|
||||
**`--clear` takes the field as its value**, one of `due`, `tags`, `priority`,
|
||||
`description`, `acceptance` or `plan`, and repeats. It writes back exactly what `add`
|
||||
writes for a field it was never given: `_Not set_`, `_None_` for tags, and the section
|
||||
placeholder. There is no `--clear title`, because a title addresses the ticket and names
|
||||
its file. There is no `--clear owner` either: that is `chown --clear <ticket>`, which
|
||||
takes the ticket in the flag since there is no user to give, and returns the field to
|
||||
unset rather than to the git user. Replacing and clearing the same field in one call is
|
||||
refused rather than resolved.
|
||||
|
||||
`chown` takes the **user first and the ticket second**, after Unix `chown`, which is the
|
||||
one command here that does not start with the ticket. The user is free text and is
|
||||
checked against nothing. Swap the two and the call fails, because the username has to
|
||||
resolve as a ticket.
|
||||
resolve as a ticket. `--clear` replaces both arguments with the ticket alone.
|
||||
|
||||
`worklane init` creates `.worklane/` with the four status directories and the campaigns
|
||||
directory beside them, for a repo that has no board yet.
|
||||
@@ -176,14 +206,30 @@ status directory. Its state is derived instead, open until every member is done,
|
||||
there is no such thing as a done campaign holding an open ticket.
|
||||
|
||||
```
|
||||
worklane campaign add --title "v1 release" \
|
||||
worklane campaign add --title "First public release" --codename v1 \
|
||||
--description "Everything that has to ship before the tag."
|
||||
worklane campaign ls # every campaign and how far it has got
|
||||
worklane campaign show "v1 release" # its body, then its members by status
|
||||
worklane assign "v1 release" 1b78a24 # put a ticket in it
|
||||
worklane ls --campaign "v1 release" # only that campaign's tickets
|
||||
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 assign v1 1b78a24 # put a ticket in it
|
||||
worklane ls --campaign v1 # only that campaign's tickets
|
||||
```
|
||||
|
||||
**Give a campaign a `--codename`.** One word, `v1` or `beaver`. It is what the board
|
||||
draws on every card in the campaign, because a uuid does not fit there and a title is a
|
||||
sentence, and it is the shortest thing that addresses the campaign at the command line.
|
||||
Optional: a campaign without one is drawn and listed by its short id instead, which
|
||||
resolves but says nothing. `campaign set <campaign> --codename <word>` gives one to a
|
||||
campaign that is already filed, which is what every campaign filed before the field
|
||||
existed needs. **Replacing a codename it already has needs `--force`**: that word is how
|
||||
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.
|
||||
|
||||
`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
|
||||
has one writer the way owner and status do.
|
||||
@@ -196,8 +242,10 @@ reports no change and writes nothing.
|
||||
its listing: a campaign is precisely the question of what is finished against what is
|
||||
left.
|
||||
|
||||
A campaign is addressed the way a ticket is, by uuid prefix, title or filename, but it
|
||||
is not a ticket. Passing one where a ticket is expected is refused with a message saying
|
||||
A campaign is addressed the way a ticket is, by uuid prefix, title or filename, and by
|
||||
its exact codename, which wins over all three. So `assign v1 1b78a24` reaches the
|
||||
campaign codenamed `v1` even if another campaign's title contains `v1`. It is not a
|
||||
ticket, though. Passing one where a ticket is expected is refused with a message saying
|
||||
so, and there is no way to move a campaign, because it has no status to move.
|
||||
|
||||
## Search the backlog before filing
|
||||
@@ -214,6 +262,16 @@ 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.
|
||||
|
||||
## Shell completions
|
||||
|
||||
```
|
||||
worklane completions fish > ~/.config/fish/completions/worklane.fish
|
||||
```
|
||||
|
||||
For the person's shell, not for you, and `bash`, `zsh`, `elvish` and `powershell` are
|
||||
there too. Only fish completes ticket ids, which it does by running `worklane ls --ids`,
|
||||
so a stale binary on PATH completes nothing and the fix is to reinstall it.
|
||||
|
||||
## Addressing a ticket
|
||||
|
||||
Every command that takes a ticket accepts, in this order of precedence:
|
||||
@@ -240,6 +298,7 @@ the candidates and exits 1 rather than guessing.
|
||||
`worklane mv --status committed -- -leading-title`.
|
||||
- A comment body of exactly `--` needs its own separator:
|
||||
`worklane comment 1b78a24 -- --`.
|
||||
- An empty value for a scalar is a usage error. Clearing a field back to unset is not
|
||||
supported yet.
|
||||
- An empty value for a scalar is a usage error, not a way to clear the field: use
|
||||
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
|
||||
the section either, and an all-blank one is refused with the `--clear` for it named.
|
||||
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
|
||||
|
||||
@@ -24,9 +24,9 @@ fn git_sha() -> String {
|
||||
.output();
|
||||
|
||||
let sha = match output {
|
||||
Ok(output) if output.status.success() => String::from_utf8_lossy(&output.stdout)
|
||||
.trim()
|
||||
.to_string(),
|
||||
Ok(output) if output.status.success() => {
|
||||
String::from_utf8_lossy(&output.stdout).trim().to_string()
|
||||
}
|
||||
_ => String::new(),
|
||||
};
|
||||
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# rustfmt is the formatter for this tree, and these four widths are what make it agree
|
||||
# with how the tree is already written. Measured, not chosen: the default config wanted
|
||||
# 305 hunks and +1418 lines of layout, `use_small_heuristics = "Max"` wanted 308 the
|
||||
# other way, and this lands at 161. The reasoning is in AGENTS.md beside the clippy rule.
|
||||
#
|
||||
# Sweeping any one of these in either direction makes the diff bigger. Measure before
|
||||
# changing one: `cargo fmt --check | grep -c '^Diff in'`.
|
||||
|
||||
# The habit the tree is written to, and the measured optimum: 90 costs 268 hunks, 120
|
||||
# costs 194.
|
||||
max_width = 100
|
||||
|
||||
# A call stays whole if it fits in three quarters of the line. rustfmt's default of 60
|
||||
# is what expands 276 of the 305 hunks the default config wants.
|
||||
fn_call_width = 75
|
||||
|
||||
# The same for a method chain.
|
||||
chain_width = 65
|
||||
|
||||
# A small struct literal stays whole, so `Size { width: 120, height: 20 }` is not six
|
||||
# lines. Above the default of 18, which is what explodes it.
|
||||
struct_lit_width = 30
|
||||
+42
-17
@@ -32,8 +32,7 @@ pub fn campaigns_dir(worklane_dir: &Path) -> PathBuf {
|
||||
pub fn ensure_campaigns_dir(worklane_dir: &Path) -> Result<PathBuf> {
|
||||
let dir = campaigns_dir(worklane_dir);
|
||||
|
||||
fs::create_dir_all(&dir)
|
||||
.map_err(|e| anyhow!("Could not create {}: {}", dir.display(), e))?;
|
||||
fs::create_dir_all(&dir).map_err(|e| anyhow!("Could not create {}: {}", dir.display(), e))?;
|
||||
|
||||
Ok(dir)
|
||||
}
|
||||
@@ -42,6 +41,12 @@ pub fn ensure_campaigns_dir(worklane_dir: &Path) -> Result<PathBuf> {
|
||||
pub struct Campaign {
|
||||
pub uuid: String,
|
||||
pub title: String,
|
||||
/// The word the campaign is called by, or `None` for one filed without a codename.
|
||||
///
|
||||
/// Read here rather than parsed at each call site for the reason the title is: the
|
||||
/// board draws it on every card that names this campaign, and the picker draws it on
|
||||
/// every row, so it comes off the one read of the directory.
|
||||
pub codename: Option<String>,
|
||||
pub content: String,
|
||||
}
|
||||
|
||||
@@ -81,6 +86,7 @@ pub fn resolve_campaign(search: &str, worklane_dir: &Path) -> Result<Campaign> {
|
||||
}
|
||||
|
||||
Ok(Campaign {
|
||||
codename: parse_codename(&found.content),
|
||||
uuid,
|
||||
title: found.title,
|
||||
content: found.content,
|
||||
@@ -104,6 +110,11 @@ pub fn campaign_named(search: &str, worklane_dir: &Path) -> Option<String> {
|
||||
/// One pass for the same reason [`RelationIndex`] takes one: rendering a ticket's
|
||||
/// Campaign field or listing the campaigns both need every one of them, and a lookup
|
||||
/// per ticket would read the directory once per row.
|
||||
///
|
||||
/// `Default` is the empty index, which is what a board whose campaigns directory cannot be
|
||||
/// read has: it still draws, with no campaign on any card. A *missing* directory is already
|
||||
/// not an error, per [`CampaignIndex::load`]; this is for the unreadable one.
|
||||
#[derive(Default)]
|
||||
pub struct CampaignIndex {
|
||||
campaigns: Vec<Campaign>,
|
||||
}
|
||||
@@ -131,6 +142,7 @@ impl CampaignIndex {
|
||||
campaigns.push(Campaign {
|
||||
uuid: parse_ticket_field(&content, "ID"),
|
||||
title: heading_title(&content),
|
||||
codename: parse_codename(&content),
|
||||
content,
|
||||
});
|
||||
}
|
||||
@@ -166,11 +178,7 @@ pub fn campaign_cell(content: &str, index: &CampaignIndex, colored: bool) -> Str
|
||||
return String::new();
|
||||
};
|
||||
|
||||
reference_cell(
|
||||
&uuid,
|
||||
index.get(&uuid).map(|campaign| campaign.title.as_str()),
|
||||
colored,
|
||||
)
|
||||
reference_cell(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()), colored)
|
||||
}
|
||||
|
||||
/// The parts [`content_trim`] cannot render from the ticket file alone.
|
||||
@@ -193,26 +201,33 @@ pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result
|
||||
pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec<TicketItem>)>> {
|
||||
let mut grouped = Vec::new();
|
||||
|
||||
for status in status_dirs() {
|
||||
let status_path = worklane_dir.join(status);
|
||||
// Over `Status::ALL` rather than the names, so each group can be put in its own
|
||||
// column's order: a campaign's committed list answers what has waited longest for
|
||||
// the same reason the board's column does.
|
||||
for status in Status::ALL {
|
||||
let status_path = worklane_dir.join(status.as_str());
|
||||
let items = match status_path.exists() {
|
||||
true => collect_ticket_items(&status_path)?,
|
||||
false => Vec::new(),
|
||||
};
|
||||
|
||||
grouped.push((
|
||||
status,
|
||||
items
|
||||
.into_iter()
|
||||
.filter(|item| item.campaign.as_deref() == Some(uuid))
|
||||
.collect(),
|
||||
));
|
||||
let mut members: Vec<TicketItem> = items
|
||||
.into_iter()
|
||||
.filter(|item| item.campaign.as_deref() == Some(uuid))
|
||||
.collect();
|
||||
members.sort_by(|a, b| by_status_order(status, a, b));
|
||||
|
||||
grouped.push((status.as_str(), members));
|
||||
}
|
||||
|
||||
Ok(grouped)
|
||||
}
|
||||
|
||||
/// 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,
|
||||
@@ -255,6 +270,9 @@ impl Standing {
|
||||
|
||||
/// The campaign file as it is written.
|
||||
///
|
||||
/// The codename sits directly under the ID, because that is what it is: a second way to
|
||||
/// say which campaign this is, in a word rather than in thirty-six characters.
|
||||
///
|
||||
/// The same shape a ticket has, minus what a campaign has no use for: no acceptance
|
||||
/// criteria, because its definition of done is derived from its members rather than
|
||||
/// written down, no implementation plan, and no Status, because it sits in no status
|
||||
@@ -263,6 +281,7 @@ impl Standing {
|
||||
pub fn campaign_body(
|
||||
title: &str,
|
||||
description: &[String],
|
||||
codename: Option<&str>,
|
||||
id: &uuid::Uuid,
|
||||
owner: Option<&str>,
|
||||
created_at: &str,
|
||||
@@ -284,11 +303,17 @@ pub fn campaign_body(
|
||||
{metadata_heading}\n\
|
||||
\n\
|
||||
- **ID**: {id}\n\
|
||||
- **{codename_field}**: {codename}\n\
|
||||
- **Owner**: {owner}\n\
|
||||
- **Created At**: {created_at}\n\
|
||||
",
|
||||
description_heading = DESCRIPTION.heading,
|
||||
metadata_heading = METADATA_HEADING,
|
||||
owner = owner.unwrap_or("_Not set_"),
|
||||
codename_field = CODENAME_FIELD,
|
||||
// Written unset rather than left out, the way `add` writes an unset Due on every
|
||||
// ticket: the line is then there to read and there to edit by hand, and one shape
|
||||
// of file is one thing for the parser to be right about.
|
||||
codename = codename.unwrap_or(NOT_SET),
|
||||
owner = owner.unwrap_or(NOT_SET),
|
||||
)
|
||||
}
|
||||
|
||||
+368
-39
@@ -4,7 +4,7 @@ use std::sync::LazyLock;
|
||||
|
||||
use chrono::NaiveDate;
|
||||
|
||||
use crate::util::{PRIORITY_RANGE, RelationKind, priority_legend};
|
||||
use crate::util::{Clearable, PRIORITY_RANGE, RelationKind, Status, priority_legend};
|
||||
|
||||
/// clap wants a `&str` with a long enough lifetime, and the legend is built from
|
||||
/// the same ramp the listing uses rather than spelled out a second time.
|
||||
@@ -43,13 +43,31 @@ pub struct Cli {
|
||||
/// Reject an empty value at parse time, so it lands as a usage error rather than a
|
||||
/// runtime one.
|
||||
///
|
||||
/// An empty value looks like a way to clear a field, and clearing is not supported
|
||||
/// yet. Refusing it keeps the gap visible and stops an accidentally empty variable
|
||||
/// from silently blanking a field. Only the scalars use this: for the multi-line
|
||||
/// sections an empty value is a paragraph break.
|
||||
/// Two messages rather than one, because the arguments that use this fall into two
|
||||
/// kinds. A search term or a title has no empty form at all, and that is all this says.
|
||||
/// A field that *can* be emptied says so and names `--clear`, which is [`clearable`]
|
||||
/// below: an accidentally empty variable must not blank a field silently, and somebody
|
||||
/// typing an empty value on purpose is reaching for exactly the flag that does it.
|
||||
///
|
||||
/// Only the scalars use either one. For the multi-line sections an empty value is a
|
||||
/// paragraph break.
|
||||
fn non_empty(raw: &str) -> Result<String, String> {
|
||||
if raw.trim().is_empty() {
|
||||
return Err("value cannot be empty, and clearing a field is not supported yet".to_string());
|
||||
return Err("value cannot be empty".to_string());
|
||||
}
|
||||
|
||||
Ok(raw.to_string())
|
||||
}
|
||||
|
||||
/// Reject an empty value on an argument whose field can be cleared, and say how.
|
||||
///
|
||||
/// The message names no command, because the arguments that use this belong to three:
|
||||
/// `set --tags`, `set --due`, `add --due` and the `chown` user. `set` and `chown` both
|
||||
/// take a `--clear`; `add` does not, and there a field is left unset by omitting the
|
||||
/// flag, which is what the caller was reaching for anyway.
|
||||
fn clearable(raw: &str) -> Result<String, String> {
|
||||
if raw.trim().is_empty() {
|
||||
return Err("value cannot be empty, use --clear to return a field to unset".to_string());
|
||||
}
|
||||
|
||||
Ok(raw.to_string())
|
||||
@@ -73,7 +91,7 @@ fn non_empty(raw: &str) -> Result<String, String> {
|
||||
fn iso_date(raw: &str) -> Result<String, String> {
|
||||
// An empty value keeps the message that explains why it is refused, since somebody
|
||||
// typing it is reaching for a way to clear the field rather than mistyping a date.
|
||||
non_empty(raw)?;
|
||||
clearable(raw)?;
|
||||
|
||||
let bytes = raw.as_bytes();
|
||||
let shaped = raw.len() == 10 && bytes[4] == b'-' && bytes[7] == b'-';
|
||||
@@ -91,6 +109,77 @@ fn iso_date(raw: &str) -> Result<String, String> {
|
||||
Ok(raw.to_string())
|
||||
}
|
||||
|
||||
/// Reject a codename that is not one word.
|
||||
///
|
||||
/// At parse time, like `iso_date` and `priority_level`, so a mistyped value is a usage
|
||||
/// error with nothing written. One word because the board draws it as a label beside the
|
||||
/// tags, with a mark and no quoting: `~beaver release` on that row reads as two labels, and
|
||||
/// the second one is not a campaign. A title is where a sentence goes.
|
||||
///
|
||||
/// Nothing else is checked. There is no registry of codenames to check against, the same
|
||||
/// reason `ls --tag` refuses to validate a tag, and a length limit would be a number
|
||||
/// invented here: a label the column will not hold is dropped whole by the row that draws
|
||||
/// it.
|
||||
fn codename(raw: &str) -> Result<String, String> {
|
||||
let value = non_empty(raw)?;
|
||||
|
||||
if value.split_whitespace().count() > 1 {
|
||||
return Err("codename must be a single word, for example v1 or beaver".to_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()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Arguments that carry prose, and therefore have to accept a value starting with
|
||||
/// a hyphen.
|
||||
///
|
||||
@@ -112,22 +201,7 @@ pub enum Command {
|
||||
|
||||
/// List tickets, optionally filtered by status
|
||||
#[command(after_help = PRIORITY_LEGEND.as_str())]
|
||||
Ls {
|
||||
/// Filter by status (backlog, committed, reviewing, done)
|
||||
status: Option<String>,
|
||||
|
||||
/// Only show tickets at this priority, 1 (most urgent) to 5 (least)
|
||||
#[arg(long, value_parser = priority_level)]
|
||||
priority: Option<u8>,
|
||||
|
||||
/// Only show tickets carrying this tag, matched whole
|
||||
#[arg(long, value_parser = non_empty)]
|
||||
tag: Option<String>,
|
||||
|
||||
/// Only show the members of this campaign, by UUID or title
|
||||
#[arg(long, value_parser = non_empty)]
|
||||
campaign: Option<String>,
|
||||
},
|
||||
Ls(LsArgs),
|
||||
|
||||
/// Show a ticket by UUID or title
|
||||
Show {
|
||||
@@ -140,9 +214,9 @@ pub enum Command {
|
||||
/// Ticket UUID or title
|
||||
ticket: String,
|
||||
|
||||
/// Target status (backlog, committed, reviewing, done)
|
||||
/// Target status
|
||||
#[arg(short, long)]
|
||||
status: String,
|
||||
status: Status,
|
||||
|
||||
/// Force move (allows backward or non-sequential moves)
|
||||
#[arg(short, long)]
|
||||
@@ -158,7 +232,7 @@ pub enum Command {
|
||||
/// Record a relation from one ticket to another
|
||||
Relate(RelateArgs),
|
||||
|
||||
/// Change the owner of a ticket
|
||||
/// Change the owner of a ticket, or return it to unset
|
||||
///
|
||||
/// User first, ticket second, after Unix `chown`. That reverses the ticket-first
|
||||
/// order `mv`, `comment` and `show` use, deliberately: the name borrows the Unix
|
||||
@@ -169,14 +243,7 @@ pub enum Command {
|
||||
/// username usually will not, so the call fails on its own. It is silently wrong
|
||||
/// only when both arguments resolve, which needs a ticket whose title matches the
|
||||
/// username.
|
||||
Chown {
|
||||
/// New owner. Free text, like `add --owner`, checked against nothing
|
||||
#[arg(value_parser = non_empty)]
|
||||
user: String,
|
||||
|
||||
/// Ticket UUID or title
|
||||
ticket: String,
|
||||
},
|
||||
Chown(ChownArgs),
|
||||
|
||||
/// Open the board view
|
||||
Tui {
|
||||
@@ -227,6 +294,29 @@ pub enum Command {
|
||||
ticket: String,
|
||||
},
|
||||
|
||||
/// 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 listing is machine-readable, like `ls --ids`: the tag, a tab, the count.
|
||||
Tags {
|
||||
#[command(subcommand)]
|
||||
command: Option<TagCommand>,
|
||||
},
|
||||
|
||||
/// Print a shell completion script
|
||||
///
|
||||
/// The structure comes from the clap definition, so a flag added here appears
|
||||
/// without anyone remembering to. Fish gets a hand-written half appended for the
|
||||
/// values only the board knows, see `completions.rs`.
|
||||
Completions {
|
||||
/// fish, bash, zsh, elvish or powershell
|
||||
shell: clap_complete::Shell,
|
||||
},
|
||||
|
||||
/// Install the agent skills that teach an agent to use worklane
|
||||
///
|
||||
/// Every shipped document by default. The optional name narrows it to one, and
|
||||
@@ -244,20 +334,58 @@ pub enum Command {
|
||||
#[arg(long)]
|
||||
print: bool,
|
||||
},
|
||||
|
||||
/// Install the opencode tool definitions that wrap the worklane CLI
|
||||
///
|
||||
/// One artifact, so no name to pass where `install-skill` takes an optional one:
|
||||
/// `--print` here can only mean the one file. opencode alone, and globally, so the
|
||||
/// tools are there in every project rather than in a checkout that happens to carry
|
||||
/// them. Claude Code has no directory it scans for a tool definition; reaching it
|
||||
/// would mean an MCP server, which is not this file.
|
||||
InstallTool {
|
||||
/// Overwrite an existing copy that has been modified
|
||||
#[arg(long)]
|
||||
force: bool,
|
||||
|
||||
/// Write it to stdout instead of installing it
|
||||
#[arg(long)]
|
||||
print: bool,
|
||||
},
|
||||
}
|
||||
|
||||
/// What a campaign can be asked for.
|
||||
///
|
||||
/// No `mv`: a campaign has no status to move it to, its state is derived from its
|
||||
/// members. No `set` or `append` either, which is a gap rather than a decision, since
|
||||
/// nothing yet edits a campaign after it is filed.
|
||||
/// 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.
|
||||
#[derive(clap::Subcommand)]
|
||||
pub enum CampaignCommand {
|
||||
/// File a new campaign
|
||||
Add(CampaignAddArgs),
|
||||
|
||||
/// 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.
|
||||
Set(CampaignSetArgs),
|
||||
|
||||
/// List campaigns with their member counts
|
||||
Ls,
|
||||
Ls {
|
||||
/// Print one campaign per line as its id and title, tab separated, for a script
|
||||
/// or a completion
|
||||
///
|
||||
/// The same flag and the same two fields as `ls --ids`, since it answers the same
|
||||
/// question about a different object. Member counts are left out: counting them
|
||||
/// reads every ticket on the board, and the caller here is a shell filling in a
|
||||
/// candidate list on a keypress
|
||||
#[arg(long)]
|
||||
ids: bool,
|
||||
},
|
||||
|
||||
/// Show a campaign and its members grouped by status
|
||||
Show {
|
||||
@@ -266,6 +394,61 @@ 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`].
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
/// `--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.
|
||||
///
|
||||
/// 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`].
|
||||
#[derive(clap::Args)]
|
||||
#[command(group(
|
||||
clap::ArgGroup::new("campaign_set_fields")
|
||||
.required(true)
|
||||
.multiple(true)
|
||||
.args(["title", "codename"])
|
||||
))]
|
||||
pub struct CampaignSetArgs {
|
||||
/// Campaign UUID, title, filename or codename
|
||||
pub campaign: String,
|
||||
|
||||
/// Replace the campaign title, renaming the file to match
|
||||
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)]
|
||||
pub title: Option<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
|
||||
/// it was written. Replacing one a campaign already has needs `--force`
|
||||
#[arg(short, long, value_parser = codename)]
|
||||
pub codename: Option<String>,
|
||||
|
||||
/// Replace a codename the campaign already has
|
||||
///
|
||||
/// Without it, `--codename` on a campaign that already has one is refused and nothing
|
||||
/// is written. The codename is how a campaign is referred to once it has one, on every
|
||||
/// card in it and at the command line, so changing it is a decision rather than a
|
||||
/// correction. Setting the codename a campaign already carries is a no-op either way,
|
||||
/// not a refusal: there is nothing to overwrite
|
||||
#[arg(short, long)]
|
||||
pub force: bool,
|
||||
}
|
||||
|
||||
/// What a campaign holds: a title, a description and an owner.
|
||||
///
|
||||
/// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a
|
||||
@@ -273,6 +456,9 @@ pub enum CampaignCommand {
|
||||
/// and no implementation plan. Priority, tags and a due date are left out because
|
||||
/// nothing reads them yet, and a field written but never shown is a field that goes
|
||||
/// stale unnoticed.
|
||||
///
|
||||
/// `--codename` is the exception to that last rule and earns it: the board draws it on
|
||||
/// every card in the campaign, and it exists because the uuid does not fit there.
|
||||
#[derive(clap::Args)]
|
||||
pub struct CampaignAddArgs {
|
||||
/// Campaign title
|
||||
@@ -283,11 +469,82 @@ pub struct CampaignAddArgs {
|
||||
#[arg(short, long, allow_hyphen_values = PROSE)]
|
||||
pub description: Vec<String>,
|
||||
|
||||
/// A single word to call the campaign by, for example v1 or beaver
|
||||
///
|
||||
/// The uuid is what every command stores and the title is a sentence, so neither is
|
||||
/// what a card has room to print. This is the short form the board draws, and it is
|
||||
/// optional: a campaign without one is drawn by its short id instead.
|
||||
#[arg(short, long, value_parser = codename)]
|
||||
pub codename: Option<String>,
|
||||
|
||||
/// Owner. Defaults to the git user
|
||||
#[arg(short, long)]
|
||||
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.
|
||||
///
|
||||
/// No `set`: changing an annotation is 9688d34, and a half of `add`/`set` that only ever
|
||||
/// declares is the honest half to ship first.
|
||||
#[derive(clap::Subcommand)]
|
||||
pub enum TagCommand {
|
||||
/// Declare a tag, and what it means
|
||||
Add(TagAddArgs),
|
||||
|
||||
/// 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>,
|
||||
}
|
||||
|
||||
/// `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
|
||||
/// struct rather than a sixth parameter, the way `add` became [`AddArgs`].
|
||||
#[derive(clap::Args)]
|
||||
pub struct LsArgs {
|
||||
/// Filter by status
|
||||
pub status: Option<Status>,
|
||||
|
||||
/// Only show tickets at this priority, 1 (most urgent) to 5 (least)
|
||||
#[arg(long, value_parser = priority_level)]
|
||||
pub priority: Option<u8>,
|
||||
|
||||
/// Only show tickets carrying this tag, matched whole
|
||||
#[arg(long, value_parser = non_empty)]
|
||||
pub tag: Option<String>,
|
||||
|
||||
/// Only show the members of this campaign, by UUID or title
|
||||
#[arg(long, value_parser = non_empty)]
|
||||
pub campaign: Option<String>,
|
||||
|
||||
/// Print one ticket per line as its id and title, tab separated, for a script or a
|
||||
/// completion. Done included, and the filters still apply
|
||||
#[arg(long)]
|
||||
pub ids: bool,
|
||||
}
|
||||
|
||||
/// `add` carries every field a new ticket can hold, so it is a struct rather than an
|
||||
/// inline variant: nine parameters at the call site is what `too_many_arguments` is
|
||||
/// for, and `set`, `append` and `check` already pass their arguments this way.
|
||||
@@ -339,7 +596,7 @@ pub struct AddArgs {
|
||||
clap::ArgGroup::new("set_fields")
|
||||
.required(true)
|
||||
.multiple(true)
|
||||
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority"])
|
||||
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority", "clear"])
|
||||
))]
|
||||
pub struct SetArgs {
|
||||
/// Ticket UUID or title
|
||||
@@ -362,7 +619,7 @@ pub struct SetArgs {
|
||||
pub plan: Vec<String>,
|
||||
|
||||
/// Replace the tags
|
||||
#[arg(short = 'g', long, value_parser = non_empty)]
|
||||
#[arg(short = 'g', long, value_parser = clearable)]
|
||||
pub tags: Vec<String>,
|
||||
|
||||
/// Replace the due date (YYYY-MM-DD)
|
||||
@@ -376,6 +633,78 @@ pub struct SetArgs {
|
||||
/// Replace the priority, 1 (most urgent) to 5 (least)
|
||||
#[arg(long, value_parser = priority_level)]
|
||||
pub priority: Option<u8>,
|
||||
|
||||
/// Return a field to unset. Repeat the flag for more than one
|
||||
///
|
||||
/// The counterpart to the flag it names, and the only way to take a value away: an
|
||||
/// empty value is a paragraph break for a section and a usage error for a scalar, so
|
||||
/// neither can spell this. What goes back is what `add` writes for a field it was
|
||||
/// never given.
|
||||
///
|
||||
/// No `title`, which addresses the ticket and names its file, and no `owner`, which
|
||||
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
|
||||
#[arg(long, value_name = "FIELD")]
|
||||
pub clear: Vec<Clearable>,
|
||||
}
|
||||
|
||||
impl SetArgs {
|
||||
/// A field this call both replaces and clears, if there is one.
|
||||
///
|
||||
/// clap cannot express the conflict, because `--clear` carries the field as a value
|
||||
/// rather than in the flag's own name. So it is checked once here and refused, rather
|
||||
/// than resolved by whichever of the two happens to be applied last, which is a
|
||||
/// silent answer to a contradictory call.
|
||||
pub fn contested(&self) -> Option<Clearable> {
|
||||
self.clear.iter().copied().find(|field| match field {
|
||||
Clearable::Due => self.due.is_some(),
|
||||
Clearable::Tags => !self.tags.is_empty(),
|
||||
Clearable::Priority => self.priority.is_some(),
|
||||
Clearable::Description => !self.description.is_empty(),
|
||||
Clearable::Acceptance => !self.acceptance.is_empty(),
|
||||
Clearable::Plan => !self.plan.is_empty(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// `chown` is the only writer of Owner, so clearing the field has to live here too, and
|
||||
/// that is what shapes the arguments.
|
||||
///
|
||||
/// **`--clear` carries the ticket rather than being a bare flag.** The ticket is the
|
||||
/// *second* positional, so `chown --clear 1b78a24` with a plain flag would land the
|
||||
/// ticket in the user's slot, and reading it back out of there is hand-parsing what clap
|
||||
/// can state outright. The typed call is the same either way; only who checks it differs.
|
||||
///
|
||||
/// The two forms are mutually exclusive, and each argument says so, so a call carrying
|
||||
/// both is a usage error from clap rather than a decision made here.
|
||||
#[derive(clap::Args)]
|
||||
pub struct ChownArgs {
|
||||
/// New owner. Free text, like `add --owner`, checked against nothing
|
||||
#[arg(value_parser = clearable, required_unless_present = "clear", conflicts_with = "clear")]
|
||||
pub user: Option<String>,
|
||||
|
||||
/// Ticket UUID or title
|
||||
#[arg(required_unless_present = "clear", conflicts_with = "clear")]
|
||||
pub ticket: Option<String>,
|
||||
|
||||
/// Return the owner to unset on this ticket, which is named here since there is no
|
||||
/// user to name
|
||||
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
|
||||
pub clear: Option<String>,
|
||||
}
|
||||
|
||||
impl ChownArgs {
|
||||
/// The ticket the call names, and the owner to write on it, `None` being unset.
|
||||
///
|
||||
/// `None` for the pair is unreachable while the constraints above hold, and is an
|
||||
/// error at the call site rather than a panic, so loosening one of them costs a
|
||||
/// message instead of a crash.
|
||||
pub fn target(&self) -> Option<(&str, Option<&str>)> {
|
||||
match (self.clear.as_deref(), self.user.as_deref(), self.ticket.as_deref()) {
|
||||
(Some(ticket), None, None) => Some((ticket, None)),
|
||||
(None, Some(user), Some(ticket)) => Some((ticket, Some(user))),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// `append` only offers the sections that hold multiple lines, since appending to a
|
||||
|
||||
@@ -0,0 +1,554 @@
|
||||
//! Shell completions.
|
||||
//!
|
||||
//! Two halves, because neither alone is enough.
|
||||
//!
|
||||
//! `clap_complete` generates the structure (subcommands, flags, their arguments)
|
||||
//! straight from the clap definition, so a new flag never needs remembering here. But it
|
||||
//! can only offer values it knows at compile time, and the value worth completing for
|
||||
//! worklane is the ticket, which lives in the board the command is run above.
|
||||
//!
|
||||
//! So the fish output gets a hand-written block appended that asks worklane itself. That
|
||||
//! costs one `worklane ls --ids` per keypress, which measured at 2.5ms in release on a
|
||||
//! board of seventy-five tickets, comfortably below anything a person notices.
|
||||
//!
|
||||
//! The four statuses are half clap's: `Status` is a `ValueEnum`, so it emits them for
|
||||
//! `mv --status`, but the fish generator does not emit possible values for a *positional*
|
||||
//! and `ls <status>` gets nothing. Same for `completions <shell>`. So the block below
|
||||
//! lists those two, from the enums rather than by hand.
|
||||
|
||||
use std::io;
|
||||
|
||||
use clap::{CommandFactory, ValueEnum};
|
||||
use clap_complete::Shell;
|
||||
|
||||
use crate::install::SKILLS;
|
||||
use crate::util::Status;
|
||||
|
||||
/// Subcommands whose first positional is a ticket.
|
||||
///
|
||||
/// Kept honest by a test rather than by memory: a new ticket-taking subcommand that is
|
||||
/// missing here silently loses completion, which nothing else would catch.
|
||||
pub const TICKET_COMMANDS: [&str; 8] = [
|
||||
"show", "mv", "comment", "set", "append", "relate", "check", "uncheck",
|
||||
];
|
||||
|
||||
/// Subcommands whose *second* positional is the ticket, because they name two things.
|
||||
///
|
||||
/// `chown alice <ticket>` and `assign "v1 release" <ticket>`, which put the ticket
|
||||
/// second deliberately, see AGENTS.md. The first argument of each is a user or a
|
||||
/// campaign, and neither is completed.
|
||||
pub const TICKET_SECOND_COMMANDS: [&str; 2] = ["chown", "assign"];
|
||||
|
||||
/// Options whose value is a ticket, as `relate` takes three of.
|
||||
pub const TICKET_FLAGS: [&str; 3] = ["blocked-by", "regression-of", "relates-to"];
|
||||
|
||||
/// Subcommands whose first positional is a campaign.
|
||||
///
|
||||
/// `assign` alone, which takes the campaign first and the ticket second. Kept honest by
|
||||
/// the same test the ticket lists are.
|
||||
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")];
|
||||
|
||||
/// Options whose value is a campaign.
|
||||
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
|
||||
|
||||
/// Options whose value is a tag.
|
||||
///
|
||||
/// Its own list rather than a line in the block below, because the values come from a
|
||||
/// different command: a tag is not an object with an id, so `worklane tags` answers this
|
||||
/// one where `ls --ids` answers the tickets.
|
||||
pub const TAG_FLAGS: [&str; 1] = ["tag"];
|
||||
|
||||
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);
|
||||
|
||||
if shell == Shell::Fish {
|
||||
write!(out, "{}", fish_dynamic())?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// The dynamic half, appended to what clap generated.
|
||||
///
|
||||
/// Fish merges completions from every `complete` call, so these add to the generated
|
||||
/// rules rather than replacing them.
|
||||
fn fish_dynamic() -> String {
|
||||
let ticket_commands = TICKET_COMMANDS.join(" ");
|
||||
let ticket_second_commands = TICKET_SECOND_COMMANDS.join(" ");
|
||||
let ticket_flags = flag_list(&TICKET_FLAGS);
|
||||
let campaign_commands = CAMPAIGN_COMMANDS.join(" ");
|
||||
let campaign_nested = CAMPAIGN_NESTED_COMMANDS
|
||||
.iter()
|
||||
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("; or ");
|
||||
let campaign_flags = flag_list(&CAMPAIGN_FLAGS);
|
||||
let tag_flags = flag_list(&TAG_FLAGS);
|
||||
let statuses = possible_values(Status::value_variants());
|
||||
let shells = possible_values(Shell::value_variants());
|
||||
let skills = SKILLS
|
||||
.iter()
|
||||
.map(|skill| skill.name)
|
||||
.collect::<Vec<_>>()
|
||||
.join(" ");
|
||||
|
||||
format!(
|
||||
r#"
|
||||
# ---------------------------------------------------------------------------
|
||||
# Dynamic values, appended by `worklane completions fish`. Fish accumulates
|
||||
# completions, so these add to the generated rules above.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
# Almost every argument worklane takes names something on the board rather than
|
||||
# something on disk, so stop fish falling back to the directory listing. Without this,
|
||||
# `worklane show 1b78a24 <TAB>` offers Cargo.toml and src/.
|
||||
complete -c worklane -f
|
||||
|
||||
# The exception, and the reason the line above is not the whole story: `tui` takes
|
||||
# project paths, as many as you like. Directories only, since each is resolved to the
|
||||
# first `.worklane` at or above it.
|
||||
complete -c worklane -n '__worklane_command_is tui' \
|
||||
-a '(__fish_complete_directories)' -d project
|
||||
|
||||
# Position is counted rather than inferred from what has been typed: matching against
|
||||
# the ticket list would run worklane again inside the condition, and would also keep
|
||||
# offering tickets after one had been chosen.
|
||||
#
|
||||
# The subcommand is the second token, so its first argument is being typed once two
|
||||
# tokens are there. `$tokens[2]` rather than `__fish_seen_subcommand_from`, because
|
||||
# `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen,
|
||||
# and their arguments are not what these complete.
|
||||
function __worklane_first_arg_of
|
||||
set -l tokens (commandline -opc)
|
||||
test (count $tokens) -eq 2; and contains -- $tokens[2] $argv
|
||||
end
|
||||
|
||||
function __worklane_second_arg_of
|
||||
set -l tokens (commandline -opc)
|
||||
test (count $tokens) -eq 3; and contains -- $tokens[2] $argv
|
||||
end
|
||||
|
||||
# The first argument of a nested subcommand, `worklane campaign show <TAB>`. Three tokens
|
||||
# with both names matched, rather than the token counting the two above do: `campaign show`
|
||||
# puts its argument where a top-level command puts its second, so counting alone would
|
||||
# offer campaigns to `chown alice <TAB>` and tickets here.
|
||||
function __worklane_nested_arg_of
|
||||
set -l tokens (commandline -opc)
|
||||
test (count $tokens) -eq 3; and test "$tokens[2]" = "$argv[1]"; and test "$tokens[3]" = "$argv[2]"
|
||||
end
|
||||
|
||||
# Which command this is, at any position in it. `$tokens[2]` again rather than
|
||||
# `__fish_seen_subcommand_from`, and for the reason spelled out above: `campaign ls` is an
|
||||
# `ls` that fish has seen, so scoping `--tag` with fish's own helper would offer it under a
|
||||
# command that does not take it.
|
||||
#
|
||||
# A rule carrying `-l` needs one of these. Without it fish takes the option as one the
|
||||
# whole tool accepts, and `worklane init --<TAB>` offered `--blocked-by`, `--tag` and four
|
||||
# others that only `relate` and `ls` have.
|
||||
function __worklane_command_is
|
||||
set -l tokens (commandline -opc)
|
||||
test (count $tokens) -ge 2; and contains -- $tokens[2] $argv
|
||||
end
|
||||
|
||||
# No `-d`: `ls --ids` prints the id and the title separated by a tab, which is fish's
|
||||
# own form for a candidate and its description, so every ticket carries its own.
|
||||
complete -c worklane \
|
||||
-n '__worklane_first_arg_of {ticket_commands}; or __worklane_second_arg_of {ticket_second_commands}' \
|
||||
-a '(worklane ls --ids)'
|
||||
|
||||
# `relate` takes its targets as option values, so they are completed by flag rather
|
||||
# than by position.
|
||||
complete -c worklane -n '__worklane_command_is relate' {ticket_flags} \
|
||||
-x -a '(worklane ls --ids)'
|
||||
|
||||
# Campaigns, from `campaign ls --ids`, in the three places one is named: `assign`'s first
|
||||
# argument, `campaign show`'s only one, and `ls --campaign`.
|
||||
complete -c worklane \
|
||||
-n '__worklane_first_arg_of {campaign_commands}; or {campaign_nested}' \
|
||||
-a '(worklane campaign ls --ids)'
|
||||
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)'
|
||||
|
||||
# `chown --clear` names the ticket in the flag too, since with no user to give there is
|
||||
# no second positional to put it in. Scoped to `chown`, unlike the rule above: `set`
|
||||
# has a `--clear` of its own that takes a field name, and clap already offers those.
|
||||
complete -c worklane -n '__worklane_command_is chown' -l clear -x -a '(worklane ls --ids)'
|
||||
|
||||
# clap emits the four for `mv --status`, which is an option, but the fish generator
|
||||
# emits nothing for the possible values of a positional. So the one place a status is
|
||||
# positional needs them listed, and the same goes for the shell below.
|
||||
complete -c worklane -n '__worklane_first_arg_of ls' -a '{statuses}' -d status
|
||||
complete -c worklane -n '__worklane_first_arg_of completions' -a '{shells}' -d shell
|
||||
|
||||
# Shipped with the binary, so this list comes from `install::SKILLS` and cannot fall
|
||||
# behind it.
|
||||
complete -c worklane -n '__worklane_first_arg_of install-skill' -a '{skills}' -d skill
|
||||
"#
|
||||
)
|
||||
}
|
||||
|
||||
/// Option names as fish wants them on a `complete` line, `-l one -l two`.
|
||||
fn flag_list(flags: &[&str]) -> String {
|
||||
flags
|
||||
.iter()
|
||||
.map(|flag| format!("-l {flag}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join(" ")
|
||||
}
|
||||
|
||||
/// The names a `ValueEnum` accepts, for a fish `-a` list.
|
||||
///
|
||||
/// Read off the enum rather than written out, so a status or a shell added to either one
|
||||
/// is offered without anybody remembering this file. A variant marked hidden is left out,
|
||||
/// which is what `to_possible_value` returning `None` means.
|
||||
fn possible_values<T: ValueEnum>(variants: &[T]) -> String {
|
||||
variants
|
||||
.iter()
|
||||
.filter_map(|variant| variant.to_possible_value())
|
||||
.map(|value| value.get_name().to_string())
|
||||
.collect::<Vec<_>>()
|
||||
.join(" ")
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// Built, not just derived: an index is assigned when the command is built, and the
|
||||
/// positionals of an unbuilt one all report `None`.
|
||||
fn command() -> clap::Command {
|
||||
let mut cli = crate::command::Cli::command();
|
||||
cli.build();
|
||||
cli
|
||||
}
|
||||
|
||||
/// Every argument in the tool, as the path that reaches it and the argument itself.
|
||||
///
|
||||
/// One walker for the honesty tests below, rather than each one repeating the
|
||||
/// traversal: they differ only in which id they are looking for. Two levels, which is
|
||||
/// as deep as the tool goes, and `help` is skipped because clap generates it and it
|
||||
/// takes no object of ours.
|
||||
fn every_argument() -> Vec<(Vec<String>, clap::Arg)> {
|
||||
let cli = command();
|
||||
let mut found = Vec::new();
|
||||
|
||||
for subcommand in cli.get_subcommands() {
|
||||
let name = subcommand.get_name().to_string();
|
||||
if name == "help" {
|
||||
continue;
|
||||
}
|
||||
for arg in subcommand.get_arguments() {
|
||||
found.push((vec![name.clone()], arg.clone()));
|
||||
}
|
||||
for nested in subcommand.get_subcommands() {
|
||||
let child = nested.get_name().to_string();
|
||||
if child == "help" {
|
||||
continue;
|
||||
}
|
||||
for arg in nested.get_arguments() {
|
||||
found.push((vec![name.clone(), child.clone()], arg.clone()));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
found
|
||||
}
|
||||
|
||||
/// Every subcommand that takes a ticket must be listed, at the position it takes it,
|
||||
/// or it silently loses completion.
|
||||
///
|
||||
/// Nested subcommands are walked now that `__worklane_nested_arg_of` exists, but
|
||||
/// nothing under `campaign` takes a ticket, so a nested one is a panic rather than a
|
||||
/// list: it would need a rule of its own in the fish block, and a name in a list here
|
||||
/// would look like it already had one.
|
||||
#[test]
|
||||
fn no_ticket_taking_subcommand_is_missing() {
|
||||
for (path, arg) in every_argument() {
|
||||
// `show` calls it `id`; everything else calls it `ticket`.
|
||||
if !matches!(arg.get_id().as_str(), "ticket" | "id") {
|
||||
continue;
|
||||
}
|
||||
let name = path.join(" ");
|
||||
if arg.is_positional() {
|
||||
assert_eq!(
|
||||
path.len(),
|
||||
1,
|
||||
"`worklane {name}` takes a nested ticket argument, \
|
||||
which needs a rule in the fish block"
|
||||
);
|
||||
let top = path[0].as_str();
|
||||
match arg.get_index() {
|
||||
Some(1) => assert!(
|
||||
TICKET_COMMANDS.contains(&top),
|
||||
"`worklane {name}` takes a ticket first but is not in TICKET_COMMANDS"
|
||||
),
|
||||
Some(2) => assert!(
|
||||
TICKET_SECOND_COMMANDS.contains(&top),
|
||||
"`worklane {name}` takes a ticket second but is not in \
|
||||
TICKET_SECOND_COMMANDS"
|
||||
),
|
||||
index => panic!("`worklane {name}` takes a ticket at position {index:?}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The same for campaigns, which is why the lists above are three rather than one:
|
||||
/// a campaign is named as a first positional, as a nested subcommand's only argument,
|
||||
/// and as an option value, and each needs a different rule in the fish block.
|
||||
#[test]
|
||||
fn no_campaign_taking_argument_is_missing() {
|
||||
let mut seen = 0;
|
||||
for (path, arg) in every_argument() {
|
||||
if arg.get_id().as_str() != "campaign" {
|
||||
continue;
|
||||
}
|
||||
seen += 1;
|
||||
let name = path.join(" ");
|
||||
|
||||
if let Some(long) = arg.get_long() {
|
||||
assert!(
|
||||
CAMPAIGN_FLAGS.contains(&long),
|
||||
"`worklane {name} --{long}` takes a campaign but is not in CAMPAIGN_FLAGS"
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
assert_eq!(
|
||||
arg.get_index(),
|
||||
Some(1),
|
||||
"`worklane {name}` takes a campaign somewhere the fish block has no rule for"
|
||||
);
|
||||
|
||||
match path.as_slice() {
|
||||
[top] => assert!(
|
||||
CAMPAIGN_COMMANDS.contains(&top.as_str()),
|
||||
"`worklane {name}` takes a campaign first but is not in CAMPAIGN_COMMANDS"
|
||||
),
|
||||
[parent, child] => assert!(
|
||||
CAMPAIGN_NESTED_COMMANDS.contains(&(parent.as_str(), child.as_str())),
|
||||
"`worklane {name}` takes a campaign but is not in CAMPAIGN_NESTED_COMMANDS"
|
||||
),
|
||||
_ => panic!("`worklane {name}` is nested deeper than the fish block goes"),
|
||||
}
|
||||
}
|
||||
|
||||
// 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");
|
||||
}
|
||||
|
||||
/// 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.
|
||||
#[test]
|
||||
fn no_tag_taking_option_is_missing() {
|
||||
let mut seen = 0;
|
||||
for (path, arg) in every_argument() {
|
||||
if arg.get_id().as_str() != "tag" {
|
||||
continue;
|
||||
}
|
||||
seen += 1;
|
||||
let name = path.join(" ");
|
||||
|
||||
let Some(long) = arg.get_long() else {
|
||||
let nested = match path.as_slice() {
|
||||
[parent, child] => {
|
||||
TAG_NEW_COMMANDS.contains(&(parent.as_str(), child.as_str()))
|
||||
}
|
||||
_ => false,
|
||||
};
|
||||
assert!(
|
||||
nested,
|
||||
"`worklane {name}` takes a tag as a positional, \
|
||||
which the fish block has no rule for"
|
||||
);
|
||||
continue;
|
||||
};
|
||||
|
||||
assert!(
|
||||
TAG_FLAGS.contains(&long),
|
||||
"`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS"
|
||||
);
|
||||
}
|
||||
|
||||
assert_eq!(seen, 2, "expected ls --tag and tags add");
|
||||
}
|
||||
|
||||
/// **Every rule naming an option has to say which command it belongs to.** A bare
|
||||
/// `complete -c worklane -l tag` tells fish the whole tool takes `--tag`, so
|
||||
/// `worklane init --<TAB>` offered six options that only `relate` and `ls` have. This
|
||||
/// is what stops the next rule being written the same way.
|
||||
#[test]
|
||||
fn every_rule_naming_an_option_is_scoped_to_a_command() {
|
||||
let script = fish_dynamic();
|
||||
// Rules are one logical line, continued with a trailing backslash.
|
||||
for rule in script.replace("\\\n", " ").lines() {
|
||||
if !rule.starts_with("complete") || !rule.contains("-l ") {
|
||||
continue;
|
||||
}
|
||||
assert!(
|
||||
rule.contains("__worklane_command_is"),
|
||||
"this rule declares an option for the whole tool: {rule}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn every_listed_command_is_a_real_subcommand() {
|
||||
let cli = command();
|
||||
let known: Vec<&str> = cli.get_subcommands().map(|c| c.get_name()).collect();
|
||||
for name in TICKET_COMMANDS.iter().chain(TICKET_SECOND_COMMANDS.iter()) {
|
||||
assert!(known.contains(name), "no such subcommand: {name}");
|
||||
}
|
||||
}
|
||||
|
||||
/// `chown --clear` takes a ticket, so it is completed like one, and only under
|
||||
/// `chown`: `set --clear` is the same flag name carrying a field.
|
||||
#[test]
|
||||
fn chowns_clear_is_completed_with_tickets_and_sets_is_not() {
|
||||
let script = fish_dynamic();
|
||||
let rule = script
|
||||
.lines()
|
||||
.find(|line| line.starts_with("complete") && line.contains("-l clear"))
|
||||
.expect("chown --clear has a rule of its own");
|
||||
assert!(rule.contains("__worklane_command_is chown"), "{rule}");
|
||||
assert!(rule.contains("worklane ls --ids"), "{rule}");
|
||||
let chown = command().find_subcommand("chown").expect("chown exists").clone();
|
||||
assert!(
|
||||
chown.get_arguments().any(|arg| arg.get_long() == Some("clear")),
|
||||
"`chown` has no --clear for the rule to complete"
|
||||
);
|
||||
assert!(
|
||||
!TICKET_FLAGS.contains(&"clear"),
|
||||
"--clear in TICKET_FLAGS would offer tickets to `set --clear`, which takes a field"
|
||||
);
|
||||
}
|
||||
|
||||
/// The flags completed as tickets have to be `relate`'s actual flags, or the rule
|
||||
/// completes an option nothing accepts.
|
||||
#[test]
|
||||
fn every_ticket_flag_is_a_real_option() {
|
||||
let relate = command()
|
||||
.find_subcommand("relate")
|
||||
.expect("relate exists")
|
||||
.clone();
|
||||
let known: Vec<String> = relate
|
||||
.get_arguments()
|
||||
.filter_map(|arg| arg.get_long().map(str::to_string))
|
||||
.collect();
|
||||
for flag in TICKET_FLAGS {
|
||||
assert!(known.contains(&flag.to_string()), "`relate` has no --{flag}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_fish_script_asks_worklane_for_its_tickets() {
|
||||
let script = fish_dynamic();
|
||||
assert!(script.contains("worklane ls --ids"));
|
||||
// Both positions, in one rule.
|
||||
assert!(script.contains("__worklane_first_arg_of show"));
|
||||
assert!(script.contains("__worklane_second_arg_of chown assign"));
|
||||
// Nothing here takes a file, bar the one that does.
|
||||
assert!(script.contains("complete -c worklane -f\n"));
|
||||
assert!(script.contains("__fish_complete_directories"));
|
||||
// Generated from `install::SKILLS`, so every shipped skill is in it.
|
||||
assert!(script.contains("worklane-review"));
|
||||
}
|
||||
|
||||
/// The two listings the campaign and tag rules read, which are separate commands
|
||||
/// because a campaign has an id and a tag does not.
|
||||
#[test]
|
||||
fn the_fish_script_asks_worklane_for_its_campaigns_and_tags() {
|
||||
let script = fish_dynamic();
|
||||
assert!(script.contains("worklane campaign ls --ids"), "{script}");
|
||||
assert!(script.contains("worklane tags"), "{script}");
|
||||
// The nested position, which neither of the two counting helpers can reach.
|
||||
assert!(script.contains("__worklane_nested_arg_of campaign show"), "{script}");
|
||||
assert!(script.contains("__worklane_first_arg_of assign"), "{script}");
|
||||
}
|
||||
|
||||
/// 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.
|
||||
#[test]
|
||||
fn the_fish_script_lists_the_statuses_and_the_shells() {
|
||||
let script = fish_dynamic();
|
||||
for status in Status::ALL {
|
||||
assert!(
|
||||
script.contains(status.as_str()),
|
||||
"the ls positional is never offered {}",
|
||||
status.as_str()
|
||||
);
|
||||
}
|
||||
assert!(script.contains("-a 'backlog committed reviewing done' -d status"));
|
||||
for shell in ["fish", "bash", "zsh", "elvish", "powershell"] {
|
||||
assert!(script.contains(shell), "the shell positional is never offered {shell}");
|
||||
}
|
||||
}
|
||||
|
||||
/// The four for `mv --status` are clap's, which is half of why `Status` is a
|
||||
/// `ValueEnum`. If clap ever stops emitting them, the fish half has to carry them
|
||||
/// too, and this is what says so.
|
||||
#[test]
|
||||
fn clap_emits_the_statuses_for_the_status_flag() {
|
||||
let mut out = Vec::new();
|
||||
generate(Shell::Fish, &mut out).expect("generates");
|
||||
let script = String::from_utf8(out).expect("utf8");
|
||||
let flag = script
|
||||
.lines()
|
||||
.find(|line| line.contains("using_subcommand mv") && line.contains("-l status"))
|
||||
.expect("mv --status has a rule of its own");
|
||||
assert!(flag.contains("backlog"), "{flag}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn generating_fish_produces_both_halves() {
|
||||
let mut out = Vec::new();
|
||||
generate(Shell::Fish, &mut out).expect("generates");
|
||||
let script = String::from_utf8(out).expect("utf8");
|
||||
// clap's half.
|
||||
assert!(script.contains("complete -c worklane"));
|
||||
assert!(script.contains("install-skill"));
|
||||
// Ours.
|
||||
assert!(script.contains("__worklane_first_arg_of"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn other_shells_get_only_the_generated_half() {
|
||||
for shell in [Shell::Bash, Shell::Zsh] {
|
||||
let mut out = Vec::new();
|
||||
generate(shell, &mut out).expect("generates");
|
||||
let script = String::from_utf8(out).expect("utf8");
|
||||
assert!(
|
||||
!script.contains("__worklane_first_arg_of"),
|
||||
"fish-only helpers leaked into {shell}"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
+523
-150
File diff suppressed because it is too large
Load Diff
+169
-26
@@ -11,9 +11,11 @@
|
||||
//! has learned the invocation should not have to learn a new name for each document
|
||||
//! added later, or the new one silently never arrives.
|
||||
//!
|
||||
//! The machinery is written once for both kinds of asset this repo will ship. The tool
|
||||
//! file for opencode is executable code needing Bun, so it gets its own command and its
|
||||
//! own root, but the compare-and-refuse logic is the same and lives here.
|
||||
//! The machinery is written once for both kinds of asset. The tool file is executable
|
||||
//! code and reaches opencode alone, so it gets its own command and its own root, but the
|
||||
//! compare-and-refuse logic is the same and lives here. What it needs at runtime is
|
||||
//! opencode and nothing else: it is loaded into opencode's own runtime, so neither Bun
|
||||
//! nor `@opencode-ai/plugin` has to be installed for the import in it to resolve.
|
||||
|
||||
use std::io;
|
||||
use std::path::{Path, PathBuf};
|
||||
@@ -73,11 +75,39 @@ pub const PLAN_SKILL: Asset = Asset {
|
||||
/// 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];
|
||||
|
||||
/// The opencode tool definitions, the second kind of asset this binary carries.
|
||||
///
|
||||
/// Executable TypeScript rather than a document, and it reaches one agent where a skill
|
||||
/// reaches both: opencode loads a `.ts` file from its tool directory and Claude Code has
|
||||
/// no directory it scans for one, so this is not the artifact that would reach it. That
|
||||
/// asymmetry is the whole reason it is its own command with its own root rather than a
|
||||
/// flag on `install-skill`.
|
||||
///
|
||||
/// Flat in the root rather than in a directory of its own, and the file name is load
|
||||
/// bearing: opencode builds each tool id as the file name then the export, so this file
|
||||
/// is what makes them `worklane_add` and `worklane_mv` rather than `tool_add`. A skill
|
||||
/// carries the equivalent in its frontmatter `name:`, which its directory has to agree
|
||||
/// with; a tool carries it in the file name alone.
|
||||
pub const TOOL: Asset = Asset {
|
||||
name: "worklane",
|
||||
what: "tool",
|
||||
relative: "worklane.ts",
|
||||
content: include_str!("../assets/TOOL.ts"),
|
||||
};
|
||||
|
||||
/// Every tool this binary carries.
|
||||
///
|
||||
/// One, and an array anyway: it is what keeps the install loop the same shape as the
|
||||
/// skills', so a second tool needs no new machinery. A `static` for the reason `SKILLS`
|
||||
/// is one.
|
||||
pub static TOOLS: [Asset; 1] = [TOOL];
|
||||
|
||||
/// The skill a name on the command line asks for.
|
||||
pub fn skill_named(name: &str) -> Result<&'static Asset> {
|
||||
SKILLS.iter().find(|asset| asset.name == name).ok_or_else(|| {
|
||||
anyhow!("no skill named {name:?}. This binary ships {}", skill_names())
|
||||
})
|
||||
SKILLS
|
||||
.iter()
|
||||
.find(|asset| asset.name == name)
|
||||
.ok_or_else(|| anyhow!("no skill named {name:?}. This binary ships {}", skill_names()))
|
||||
}
|
||||
|
||||
/// The names, for the errors that have to say what there is to choose from.
|
||||
@@ -105,6 +135,48 @@ pub fn skills_root() -> Result<PathBuf> {
|
||||
Ok(Path::new(&home).join(".claude/skills"))
|
||||
}
|
||||
|
||||
/// Where the tool has to sit for opencode to load it in every project.
|
||||
///
|
||||
/// `XDG_CONFIG_HOME` when it is set and non-empty, `~/.config` otherwise, which is what
|
||||
/// opencode itself resolves: `opencode debug paths` reports its config root under
|
||||
/// `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without.
|
||||
/// An empty value counts as unset, the convention `colors_wanted` already follows for
|
||||
/// `NO_COLOR`. Checked against opencode 1.15.10.
|
||||
///
|
||||
/// Singular `tool`, though 1.15.10 loads `tools` as well: each was served in turn from a
|
||||
/// directory outside any project and registered all eleven worklane tools. The singular
|
||||
/// is the spelling opencode's own documentation puts first, the way it writes `agent(s)`
|
||||
/// and `skill(s)`.
|
||||
///
|
||||
/// One agent, unlike `skills_root`. Claude Code has no path that belongs here at all: a
|
||||
/// tool reaches it through an MCP server, which is a different artifact and not one this
|
||||
/// binary carries.
|
||||
pub fn tools_root() -> Result<PathBuf> {
|
||||
let xdg = std::env::var_os("XDG_CONFIG_HOME");
|
||||
let home = std::env::var_os("HOME");
|
||||
|
||||
opencode_tool_dir(xdg.as_deref().map(Path::new), home.as_deref().map(Path::new))
|
||||
}
|
||||
|
||||
/// `tools_root` with the two variables passed in rather than read.
|
||||
///
|
||||
/// The seam exists for the reason `colors_wanted` has one: both branches and the failure
|
||||
/// have to be reachable from a test, and a threaded test binary cannot mutate the process
|
||||
/// environment to reach them one at a time.
|
||||
fn opencode_tool_dir(xdg: Option<&Path>, home: Option<&Path>) -> Result<PathBuf> {
|
||||
if let Some(xdg) = xdg.filter(|value| !value.as_os_str().is_empty()) {
|
||||
return Ok(xdg.join("opencode/tool"));
|
||||
}
|
||||
|
||||
let home = home.ok_or_else(|| {
|
||||
anyhow!(
|
||||
"cannot tell where your opencode config lives because neither XDG_CONFIG_HOME nor HOME is set in the environment"
|
||||
)
|
||||
})?;
|
||||
|
||||
Ok(home.join(".config/opencode/tool"))
|
||||
}
|
||||
|
||||
#[derive(Debug, PartialEq, Eq)]
|
||||
pub enum Outcome {
|
||||
Written(PathBuf),
|
||||
@@ -173,10 +245,7 @@ mod tests {
|
||||
let root = root();
|
||||
let path = SKILL.path(root.path());
|
||||
|
||||
assert_eq!(
|
||||
SKILL.install(root.path(), false).unwrap(),
|
||||
Outcome::Written(path.clone())
|
||||
);
|
||||
assert_eq!(SKILL.install(root.path(), false).unwrap(), Outcome::Written(path.clone()));
|
||||
assert_eq!(std::fs::read_to_string(&path).unwrap(), SKILL.content);
|
||||
}
|
||||
|
||||
@@ -201,16 +270,10 @@ mod tests {
|
||||
SKILL.install(root.path(), false).unwrap();
|
||||
std::fs::write(&path, "hand written\n").unwrap();
|
||||
|
||||
assert_eq!(
|
||||
SKILL.install(root.path(), false).unwrap(),
|
||||
Outcome::Refused(path.clone())
|
||||
);
|
||||
assert_eq!(SKILL.install(root.path(), false).unwrap(), Outcome::Refused(path.clone()));
|
||||
assert_eq!(std::fs::read_to_string(&path).unwrap(), "hand written\n");
|
||||
|
||||
assert_eq!(
|
||||
SKILL.install(root.path(), true).unwrap(),
|
||||
Outcome::Written(path.clone())
|
||||
);
|
||||
assert_eq!(SKILL.install(root.path(), true).unwrap(), Outcome::Written(path.clone()));
|
||||
assert_eq!(std::fs::read_to_string(&path).unwrap(), SKILL.content);
|
||||
}
|
||||
|
||||
@@ -254,8 +317,10 @@ mod tests {
|
||||
"the frontmatter name has to match the directory it installs into"
|
||||
);
|
||||
|
||||
let description = frontmatter_field(asset.content, "description")
|
||||
.unwrap_or_else(|| panic!("{} ships without a description to trigger on", asset.name));
|
||||
let description =
|
||||
frontmatter_field(asset.content, "description").unwrap_or_else(|| {
|
||||
panic!("{} ships without a description to trigger on", asset.name)
|
||||
});
|
||||
assert!(
|
||||
description.len() > 80,
|
||||
"{}: the description is what decides whether the skill loads at all",
|
||||
@@ -311,7 +376,9 @@ mod tests {
|
||||
if words.next() != Some("worklane") {
|
||||
continue;
|
||||
}
|
||||
let Some(candidate) = words.next() else { continue };
|
||||
let Some(candidate) = words.next() else {
|
||||
continue;
|
||||
};
|
||||
// A flag before the subcommand, as in the `mv -- -leading-title` example.
|
||||
if candidate.starts_with("--") && !known.iter().any(|k| k == candidate) {
|
||||
continue;
|
||||
@@ -335,7 +402,7 @@ mod tests {
|
||||
/// Subcommands the skill has no business teaching: the board is interactive and
|
||||
/// belongs to a person, `install-skill` is how the document arrived, and `help`
|
||||
/// is clap's own.
|
||||
const NOT_FOR_AGENTS: [&str; 3] = ["tui", "install-skill", "help"];
|
||||
const NOT_FOR_AGENTS: [&str; 4] = ["tui", "install-skill", "install-tool", "help"];
|
||||
|
||||
/// The converse, and the one that goes stale on its own: a *new* subcommand absent
|
||||
/// from the skill is invisible to an agent, and nothing else would notice.
|
||||
@@ -386,9 +453,9 @@ mod tests {
|
||||
fn the_plan_skill_keeps_the_rules_that_bound_a_sweep() {
|
||||
for required in [
|
||||
"Propose the whole set of edits",
|
||||
"replaces the whole\nfield", // `set --tags` is the destructive one
|
||||
"cannot be cleared", // and a due date cannot be taken back
|
||||
"blocked by", // ordering constrains any dating plan
|
||||
"replaces the whole\nfield", // `set --tags` is the destructive one
|
||||
"not\nback to what it held", // and --clear is not an undo
|
||||
"blocked by", // ordering constrains any dating plan
|
||||
"worklane campaign ls",
|
||||
"does not touch",
|
||||
] {
|
||||
@@ -407,7 +474,7 @@ mod tests {
|
||||
#[test]
|
||||
fn the_review_skill_keeps_the_decisions_that_define_it() {
|
||||
for required in [
|
||||
"worklane show", // the ticket is read before the code
|
||||
"worklane show", // the ticket is read before the code
|
||||
"nothing names the ticket", // and the no-work-found case is answered
|
||||
"Never tick a criterion",
|
||||
"Do not move the ticket",
|
||||
@@ -421,4 +488,80 @@ mod tests {
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------ the tool --
|
||||
|
||||
/// `XDG_CONFIG_HOME` wins, because it is what opencode itself resolves its config
|
||||
/// root from: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with it set.
|
||||
#[test]
|
||||
fn the_tool_root_follows_xdg_config_home_when_it_is_set() {
|
||||
let root = opencode_tool_dir(Some(Path::new("/tmp/xdg")), Some(Path::new("/home/x")));
|
||||
assert_eq!(root.unwrap(), Path::new("/tmp/xdg/opencode/tool"));
|
||||
}
|
||||
|
||||
/// An empty value counts as unset, the convention `colors_wanted` already follows, so
|
||||
/// a wrapper script that cleared an inherited one still lands in the home directory
|
||||
/// rather than at `/opencode/tool`.
|
||||
#[test]
|
||||
fn an_empty_xdg_config_home_falls_back_to_the_home_directory() {
|
||||
let root = opencode_tool_dir(Some(Path::new("")), Some(Path::new("/home/x")));
|
||||
assert_eq!(root.unwrap(), Path::new("/home/x/.config/opencode/tool"));
|
||||
|
||||
let unset = opencode_tool_dir(None, Some(Path::new("/home/x")));
|
||||
assert_eq!(unset.unwrap(), Path::new("/home/x/.config/opencode/tool"));
|
||||
}
|
||||
|
||||
/// Neither one set is the case that has to fail rather than guess: writing to a
|
||||
/// relative `.config/opencode/tool` would put the tool wherever the caller happened
|
||||
/// to be standing.
|
||||
#[test]
|
||||
fn neither_variable_set_is_an_error_rather_than_a_relative_path() {
|
||||
let error = opencode_tool_dir(None, None).unwrap_err().to_string();
|
||||
assert!(error.contains("XDG_CONFIG_HOME"), "{error}");
|
||||
assert!(error.contains("HOME"), "{error}");
|
||||
}
|
||||
|
||||
/// The file name is the tool id prefix, not decoration: opencode names each tool as
|
||||
/// the file then the export, so a renamed file renames all eleven tools and every
|
||||
/// permission rule that mentions one.
|
||||
#[test]
|
||||
fn the_tool_lands_flat_in_the_root_under_the_name_that_prefixes_its_ids() {
|
||||
let root = opencode_tool_dir(None, Some(Path::new("/home/x"))).unwrap();
|
||||
|
||||
assert_eq!(TOOL.path(&root), Path::new("/home/x/.config/opencode/tool/worklane.ts"));
|
||||
assert_eq!(TOOL.relative, "worklane.ts");
|
||||
}
|
||||
|
||||
/// Every tool the file exports names a real subcommand.
|
||||
///
|
||||
/// The guard the fish completion lists already have, pointed the other way: this
|
||||
/// catches a tool wrapping a command that has been renamed or dropped, which would
|
||||
/// fail only when an agent finally called it. It cannot catch the reverse, a
|
||||
/// subcommand the wrapper never grew a tool for, and the wrapper is behind by
|
||||
/// several: `relate`, `campaign`, `assign` and `tags` have no tool. That is its own
|
||||
/// ticket, and asserting it here would fail on a gap nobody has decided to close.
|
||||
#[test]
|
||||
fn every_tool_the_wrapper_exports_is_a_real_subcommand() {
|
||||
use clap::CommandFactory;
|
||||
|
||||
let commands: Vec<String> = crate::Cli::command()
|
||||
.get_subcommands()
|
||||
.map(|command| command.get_name().to_string())
|
||||
.collect();
|
||||
|
||||
let exported: Vec<&str> = TOOL
|
||||
.content
|
||||
.lines()
|
||||
.filter_map(|line| line.strip_prefix("export const "))
|
||||
.filter_map(|rest| rest.split_whitespace().next())
|
||||
.collect();
|
||||
|
||||
assert_eq!(exported.len(), 11, "{exported:?}");
|
||||
for name in exported {
|
||||
assert!(
|
||||
commands.iter().any(|command| command == name),
|
||||
"the wrapper exports {name:?}, which is not a subcommand: {commands:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+48
-27
@@ -4,8 +4,10 @@ use clap::Parser;
|
||||
mod campaign;
|
||||
mod clipboard;
|
||||
mod command;
|
||||
mod completions;
|
||||
mod handlers;
|
||||
mod install;
|
||||
mod tag;
|
||||
mod tui;
|
||||
mod util;
|
||||
|
||||
@@ -46,52 +48,60 @@ fn main() -> Result<()> {
|
||||
Some(Command::Tui { paths }) => run_tui(&paths, &start),
|
||||
Some(Command::Init) => cmd_init(&start),
|
||||
Some(Command::Add(args)) => cmd_add(&args, &start),
|
||||
Some(Command::Ls {
|
||||
status,
|
||||
priority,
|
||||
tag,
|
||||
campaign,
|
||||
}) => {
|
||||
Some(Command::Ls(args)) => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_ls(&status, priority, &tag, &campaign, &worklane_dir)
|
||||
cmd_ls(&args, &worklane_dir)
|
||||
}
|
||||
Some(Command::Show { id }) => {
|
||||
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 }) => cmd_mv(&ticket, status, force, &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 { user, ticket }) => cmd_chown(&user, &ticket, &start),
|
||||
Some(Command::Chown(args)) => cmd_chown(&args, &start),
|
||||
Some(Command::Check(args)) => cmd_check(&args, true, &start),
|
||||
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start),
|
||||
Some(Command::Comment {
|
||||
ticket,
|
||||
body,
|
||||
owner,
|
||||
}) => cmd_comment(&ticket, &body, &owner, &start),
|
||||
Some(Command::Comment { ticket, body, owner }) => {
|
||||
cmd_comment(&ticket, &body, &owner, &start)
|
||||
}
|
||||
Some(Command::Campaign { command }) => match command {
|
||||
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start),
|
||||
CampaignCommand::Ls => {
|
||||
CampaignCommand::Ls { ids } => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_campaign_ls(&worklane_dir)
|
||||
cmd_campaign_ls(&worklane_dir, ids)
|
||||
}
|
||||
CampaignCommand::Set(args) => cmd_campaign_set(&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),
|
||||
// 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),
|
||||
},
|
||||
// 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 }) => {
|
||||
completions::generate(shell, &mut std::io::stdout()).map_err(Into::into)
|
||||
}
|
||||
// No board is looked for: the point of the skill is to teach an agent worklane
|
||||
// before there is a `.worklane` anywhere.
|
||||
Some(Command::InstallSkill { skill, force, print }) => {
|
||||
cmd_install_skill(skill.as_deref(), force, print)
|
||||
}
|
||||
// No board either, and one agent rather than both: opencode loads the tool file,
|
||||
// Claude Code has no path for one.
|
||||
Some(Command::InstallTool { force, print }) => cmd_install_tool(force, print),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -111,10 +121,7 @@ fn install_panic_hook() {
|
||||
|
||||
fn restore_terminal() -> std::io::Result<()> {
|
||||
crossterm::terminal::disable_raw_mode()?;
|
||||
crossterm::execute!(
|
||||
std::io::stdout(),
|
||||
crossterm::terminal::LeaveAlternateScreen
|
||||
)
|
||||
crossterm::execute!(std::io::stdout(), crossterm::terminal::LeaveAlternateScreen)
|
||||
}
|
||||
|
||||
fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()> {
|
||||
@@ -181,13 +188,22 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
continue;
|
||||
}
|
||||
|
||||
// The same contract for the campaign picker, which is the other mode that owns
|
||||
// the keyboard while it is open. Two calls rather than one combined pre-branch,
|
||||
// because only one of the two can be open at a time and each reports for
|
||||
// itself; the rules are `Board::search_key` and `Board::picker_key`, where a
|
||||
// test can reach them.
|
||||
if board.picker_key(key, screen) {
|
||||
continue;
|
||||
}
|
||||
|
||||
match key.code {
|
||||
// One arm, because the two keys mean one thing: close what is open, and
|
||||
// quit when there is nothing left to close. Two arms carrying one rule
|
||||
// is how a later edit changes it for one key and not the other, which is
|
||||
// what `q` quitting out from under an open ticket already was. The rule
|
||||
// itself is `Board::dismiss`, where a test can reach it.
|
||||
KeyCode::Esc | KeyCode::Char('q') => board.dismiss(),
|
||||
KeyCode::Esc | KeyCode::Char('q') => board.dismiss(screen),
|
||||
// The only key that leaves the board from an open ticket, which is why
|
||||
// the footer names it there.
|
||||
KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
|
||||
@@ -212,13 +228,18 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
KeyCode::Char('d') => board.toggle_done(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
|
||||
// than reached for inside `Board`, so the suite can drive both answers.
|
||||
KeyCode::Char('y') => board.copy_selected_id(clipboard::copy),
|
||||
// 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(),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
+312
@@ -0,0 +1,312 @@
|
||||
//! 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)
|
||||
}
|
||||
|
||||
/// 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());
|
||||
}
|
||||
}
|
||||
+3156
-211
File diff suppressed because it is too large
Load Diff
+1309
-143
File diff suppressed because it is too large
Load Diff
+87
-24
@@ -1,6 +1,6 @@
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::fixture::{PathChild, PathCreateDir};
|
||||
use assert_fs::TempDir;
|
||||
use assert_fs::fixture::{PathChild, PathCreateDir};
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
@@ -106,9 +106,12 @@ fn add_joins_multiple_descriptions() {
|
||||
cmd.current_dir(temp.path())
|
||||
.args([
|
||||
"add",
|
||||
"--title", "Multi desc ticket",
|
||||
"--description", "Line one",
|
||||
"--description", "Line two",
|
||||
"--title",
|
||||
"Multi desc ticket",
|
||||
"--description",
|
||||
"Line one",
|
||||
"--description",
|
||||
"Line two",
|
||||
])
|
||||
.assert()
|
||||
.success();
|
||||
@@ -285,10 +288,7 @@ fn add_accepts_prose_values_that_begin_with_a_hyphen() {
|
||||
// Stored verbatim, hyphens and all
|
||||
assert!(content.contains("# -t is a flag name"), "was {content:?}");
|
||||
assert!(content.contains("-x does nothing"), "was {content:?}");
|
||||
assert!(
|
||||
content.contains("- [ ] --print should be supported"),
|
||||
"was {content:?}"
|
||||
);
|
||||
assert!(content.contains("- [ ] --print should be supported"), "was {content:?}");
|
||||
assert!(content.contains("1. -f skips the check"), "was {content:?}");
|
||||
}
|
||||
|
||||
@@ -308,10 +308,7 @@ fn add_still_accepts_the_equals_form() {
|
||||
|
||||
let content = only_ticket(&worklane);
|
||||
assert!(content.contains("# -x equals form"), "was {content:?}");
|
||||
assert!(
|
||||
content.contains("- [ ] --print via equals"),
|
||||
"was {content:?}"
|
||||
);
|
||||
assert!(content.contains("- [ ] --print via equals"), "was {content:?}");
|
||||
}
|
||||
|
||||
/// Never silently dropped: a value that is nothing but hyphens is content.
|
||||
@@ -328,10 +325,7 @@ fn add_stores_a_title_that_is_only_hyphens() {
|
||||
.success();
|
||||
|
||||
let content = only_ticket(&worklane);
|
||||
assert!(
|
||||
content.starts_with(&format!("# {}\n", bare)),
|
||||
"for {bare:?}: {content:?}"
|
||||
);
|
||||
assert!(content.starts_with(&format!("# {}\n", bare)), "for {bare:?}: {content:?}");
|
||||
}
|
||||
}
|
||||
|
||||
@@ -408,10 +402,7 @@ fn add_keeps_a_paragraph_break_in_the_description() {
|
||||
let mut show = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
show.current_dir(temp.path()).args(["show", "Two Paras"]);
|
||||
let stdout = String::from_utf8(show.assert().success().get_output().stdout.clone()).unwrap();
|
||||
assert!(
|
||||
stdout.contains("First paragraph.\n\nSecond paragraph."),
|
||||
"was {stdout:?}"
|
||||
);
|
||||
assert!(stdout.contains("First paragraph.\n\nSecond paragraph."), "was {stdout:?}");
|
||||
}
|
||||
|
||||
/// A break belongs between paragraphs, not against the section headings.
|
||||
@@ -482,7 +473,14 @@ fn add_stores_a_valid_due_date_unchanged() {
|
||||
/// and is not a day.
|
||||
#[test]
|
||||
fn add_refuses_a_due_date_that_is_not_a_real_iso_date() {
|
||||
for value in ["next friday", "29-08-2026", "2026-13-01", "2026-02-30", "2026/08/29", ""] {
|
||||
for value in [
|
||||
"next friday",
|
||||
"29-08-2026",
|
||||
"2026-13-01",
|
||||
"2026-02-30",
|
||||
"2026/08/29",
|
||||
"",
|
||||
] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
@@ -530,9 +528,10 @@ fn add_refuses_an_unpadded_due_date_rather_than_padding_it() {
|
||||
}
|
||||
|
||||
/// An empty value keeps the message about clearing, since that is what somebody typing
|
||||
/// it is reaching for.
|
||||
/// it is reaching for. On `add` the answer is to omit the flag, but the message names
|
||||
/// `--clear` because the same parser guards `set --due`, where that is the answer.
|
||||
#[test]
|
||||
fn an_empty_due_date_says_clearing_is_not_supported() {
|
||||
fn an_empty_due_date_points_at_clear() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
@@ -549,7 +548,8 @@ fn an_empty_due_date_says_clearing_is_not_supported() {
|
||||
)
|
||||
.to_string();
|
||||
|
||||
assert!(stderr.contains("clearing a field is not supported"), "{stderr}");
|
||||
assert!(stderr.contains("use --clear"), "{stderr}");
|
||||
assert!(!stderr.contains("not supported"), "{stderr}");
|
||||
}
|
||||
|
||||
fn read_only_ticket(dir: &Path) -> String {
|
||||
@@ -561,3 +561,66 @@ fn read_only_ticket(dir: &Path) -> String {
|
||||
|
||||
fs::read_to_string(file.path()).unwrap()
|
||||
}
|
||||
|
||||
fn chmod(path: &Path, mode: u32) {
|
||||
use std::os::unix::fs::PermissionsExt;
|
||||
|
||||
let mut perms = fs::metadata(path).unwrap().permissions();
|
||||
perms.set_mode(mode);
|
||||
fs::set_permissions(path, perms).unwrap();
|
||||
}
|
||||
|
||||
/// A duplicate title is not a failure, so the only thing left to refuse is the write
|
||||
/// itself, and it is named with the ticket and the path rather than raised as a bare io
|
||||
/// error. The branch this replaces could not fire at all: the filename carries a fresh
|
||||
/// uuid, and its message claimed the title was taken.
|
||||
#[test]
|
||||
fn add_names_the_ticket_and_the_path_when_the_write_fails() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let backlog = worklane.join("backlog");
|
||||
|
||||
chmod(&backlog, 0o555);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let assert = cmd
|
||||
.current_dir(temp.path())
|
||||
.args(["add", "--title", "Unwritable"])
|
||||
.assert()
|
||||
.failure();
|
||||
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains("Unwritable"), "{stderr}");
|
||||
assert!(stderr.contains("unwritable.md"), "{stderr}");
|
||||
assert!(!stderr.contains("already exists"), "{stderr}");
|
||||
|
||||
chmod(&backlog, 0o755);
|
||||
assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0);
|
||||
}
|
||||
|
||||
/// The board above the project is real and empty, and stays empty: a dangling
|
||||
/// `.worklane` link used to read as no board here, and the walk then wrote the
|
||||
/// ticket into whatever board sat above it.
|
||||
#[test]
|
||||
fn add_writes_nothing_when_the_board_link_does_not_resolve() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let above = setup_worklane(&temp);
|
||||
|
||||
let project = temp.child("project");
|
||||
project.create_dir_all().unwrap();
|
||||
let target = temp.path().join("boards/2fed877-the-board");
|
||||
std::os::unix::fs::symlink(&target, project.path().join(".worklane")).unwrap();
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let assert = cmd
|
||||
.current_dir(project.path())
|
||||
.args(["add", "--title", "Should not land"])
|
||||
.assert()
|
||||
.failure();
|
||||
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains(&target.display().to_string()), "{stderr}");
|
||||
assert!(stderr.contains("boards repo"), "{stderr}");
|
||||
|
||||
assert_eq!(fs::read_dir(above.join("backlog")).unwrap().count(), 0);
|
||||
}
|
||||
|
||||
+669
-6
@@ -13,6 +13,8 @@ const CAMP_B: &str = "bb22cc33-44dd-4ee5-8ff6-001122334455";
|
||||
const MEMBER: &str = "641e3d5c-1b0e-4d2f-9a7e-3c8b5f0a2d61";
|
||||
const OTHER: &str = "b1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
|
||||
const LONER: &str = "f1f2f3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f";
|
||||
/// A second done member, for the one test that needs two in one column to see an order.
|
||||
const LATE: &str = "a9a8a7a6-5b4c-4d3e-8f2a-1b0c9d8e7f60";
|
||||
|
||||
fn setup_worklane(temp: &TempDir) -> PathBuf {
|
||||
let worklane = temp.child(".worklane");
|
||||
@@ -144,6 +146,21 @@ fn find(worklane: &Path, uuid: &str) -> PathBuf {
|
||||
panic!("no file for ticket {uuid}");
|
||||
}
|
||||
|
||||
/// A campaign's content by uuid, found rather than named, since `campaign set --title`
|
||||
/// renames the file and a test that named it would be asserting the old name.
|
||||
fn campaign_file(worklane: &Path, uuid: &str) -> String {
|
||||
for entry in fs::read_dir(worklane.join("campaigns"))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
{
|
||||
if entry.file_name().to_string_lossy().starts_with(uuid) {
|
||||
return fs::read_to_string(entry.path()).unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
panic!("no file for campaign {uuid}");
|
||||
}
|
||||
|
||||
fn ticket(worklane: &Path, uuid: &str) -> String {
|
||||
fs::read_to_string(find(worklane, uuid)).unwrap()
|
||||
}
|
||||
@@ -413,6 +430,47 @@ fn campaign_ls_lists_campaigns_with_their_member_counts() {
|
||||
assert!(listing.contains("v2 release | no members"), "{listing}");
|
||||
}
|
||||
|
||||
/// The machine-readable listing, the same two fields and the same shape as `ls --ids`.
|
||||
#[test]
|
||||
fn campaign_ls_ids_prints_the_id_and_the_title_tab_separated() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let _worklane = board(&temp);
|
||||
|
||||
run(&temp, &["assign", "v1 release", MEMBER]);
|
||||
|
||||
let out = run(&temp, &["campaign", "ls", "--ids"]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let listing = stdout(&out);
|
||||
assert_eq!(
|
||||
listing.lines().collect::<Vec<_>>(),
|
||||
vec![
|
||||
format!("{}\tv1 release", &CAMP_A[..7]),
|
||||
format!("{}\tv2 release", &CAMP_B[..7]),
|
||||
]
|
||||
);
|
||||
|
||||
// Nothing decorated: no heading, no member count, no escape.
|
||||
assert!(!listing.contains("Campaigns:"), "{listing}");
|
||||
assert!(!listing.contains("done"), "{listing}");
|
||||
assert!(!listing.contains('\u{1b}'), "{listing}");
|
||||
}
|
||||
|
||||
/// A completion offers nothing rather than a sentence, so the empty case that prints
|
||||
/// prose for a reader has to stay out of the parsed path.
|
||||
#[test]
|
||||
fn campaign_ls_ids_says_nothing_on_a_board_with_no_campaigns() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "ls", "--ids"]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert_eq!(stdout(&out), "");
|
||||
|
||||
// The decorated listing still explains itself.
|
||||
assert!(stdout(&run(&temp, &["campaign", "ls"])).contains("No campaigns yet"));
|
||||
}
|
||||
|
||||
/// A campaign is done when it holds members and every one of them is done. An empty one
|
||||
/// is neither, which is why it reads `no members` rather than `0/0 done`.
|
||||
#[test]
|
||||
@@ -451,6 +509,37 @@ fn campaign_show_prints_the_body_and_the_members_grouped_by_status() {
|
||||
assert!(!shown.contains("The loner"), "{shown}");
|
||||
}
|
||||
|
||||
/// The members of a status are listed in that status's own order, not in the board-wide
|
||||
/// one: a campaign's done list answers what just landed, for the same reason the board's
|
||||
/// column does. Every fixture is a p3, so the stamp is doing all of the work.
|
||||
#[test]
|
||||
fn campaign_show_lists_each_status_in_its_own_order() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let stamp = |uuid: &str, day: &str| {
|
||||
let path = find(&worklane, uuid);
|
||||
let body = fs::read_to_string(&path).unwrap().replace(
|
||||
"- **Status**: done\n",
|
||||
&format!("- **Completed On**: 2026-08-0{day} 09:00:00\n- **Status**: done\n"),
|
||||
);
|
||||
fs::write(&path, body).unwrap();
|
||||
};
|
||||
|
||||
// A second done member, finished after the one the fixture writes.
|
||||
create_ticket(&worklane, "done", "The late member", LATE);
|
||||
stamp(OTHER, "1");
|
||||
stamp(LATE, "3");
|
||||
|
||||
run(&temp, &["assign", "v1 release", OTHER]);
|
||||
run(&temp, &["assign", "v1 release", LATE]);
|
||||
|
||||
let shown = stdout(&run(&temp, &["campaign", "show", "aa11"]));
|
||||
let at = |needle: &str| shown.find(needle).unwrap_or_else(|| panic!("{needle}: {shown}"));
|
||||
|
||||
assert!(at("The late member") < at("The other member"), "{shown}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ls_campaign_lists_only_that_campaigns_members() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
@@ -487,7 +576,12 @@ fn a_campaign_that_no_longer_exists_reads_as_missing() {
|
||||
let worklane = board(&temp);
|
||||
|
||||
run(&temp, &["assign", "v1 release", MEMBER]);
|
||||
fs::remove_file(worklane.join("campaigns").join(format!("{CAMP_A}_v1-release.md"))).unwrap();
|
||||
fs::remove_file(
|
||||
worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{CAMP_A}_v1-release.md")),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let out = run(&temp, &["show", MEMBER]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
@@ -578,11 +672,7 @@ fn a_search_that_names_nothing_still_reports_no_ticket() {
|
||||
let out = run(&temp, &["show", "nothing at all"]);
|
||||
|
||||
assert!(!out.status.success());
|
||||
assert!(
|
||||
stderr(&out).contains("No ticket found matching"),
|
||||
"{}",
|
||||
stderr(&out)
|
||||
);
|
||||
assert!(stderr(&out).contains("No ticket found matching"), "{}", stderr(&out));
|
||||
}
|
||||
|
||||
/// A campaign resolves by the same tiers a ticket does, so it can be ambiguous the same
|
||||
@@ -600,3 +690,576 @@ fn an_ambiguous_campaign_lists_the_candidates() {
|
||||
assert!(message.contains("v1 release"), "{message}");
|
||||
assert!(message.contains("v2 release"), "{message}");
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------ codenames --
|
||||
|
||||
/// The codename is what the board draws on every card in a campaign, since a uuid does
|
||||
/// not fit there and a title is a sentence.
|
||||
#[test]
|
||||
fn campaign_add_writes_the_codename_under_the_id() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First public release",
|
||||
"--codename",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let name = campaigns(&worklane).remove(0);
|
||||
let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap();
|
||||
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
// Under the ID, because that is what it is: a second way to say which campaign this
|
||||
// is, in a word rather than in thirty-six characters.
|
||||
let id = content.find("- **ID**:").expect("no id");
|
||||
let codename = content.find("- **Codename**:").expect("no codename");
|
||||
let owner = content.find("- **Owner**:").expect("no owner");
|
||||
assert!(id < codename && codename < owner, "{content}");
|
||||
}
|
||||
|
||||
/// A campaign filed without one carries the line unset rather than not at all, the way
|
||||
/// `add` writes an unset Due on every ticket: one shape of file is one thing for the
|
||||
/// parser to be right about, and the line is there to fill in by hand.
|
||||
#[test]
|
||||
fn a_campaign_filed_without_a_codename_carries_the_field_unset() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["campaign", "add", "--title", "No codename here"]);
|
||||
|
||||
let name = campaigns(&worklane).remove(0);
|
||||
let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap();
|
||||
|
||||
assert!(content.contains("- **Codename**: _Not set_"), "{content}");
|
||||
}
|
||||
|
||||
/// One word, checked at parse time like `--due` and `--priority`, because the board draws
|
||||
/// it as a label with a mark and no quoting: `~beaver release` on that row reads as two
|
||||
/// labels and the second one is not a campaign.
|
||||
#[test]
|
||||
fn a_codename_of_more_than_one_word_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"v1 release",
|
||||
"--codename",
|
||||
"beaver release",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("single word"), "{}", stderr(&out));
|
||||
assert!(campaigns(&worklane).is_empty(), "a campaign was filed anyway");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_empty_codename_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "add", "--title", "v1 release", "--codename", ""]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert!(campaigns(&worklane).is_empty(), "a campaign was filed anyway");
|
||||
}
|
||||
|
||||
/// The listing is where the codename is read back, so it goes between the id and the
|
||||
/// title with the mark the board draws it with: one word for one campaign, spelled the
|
||||
/// same wherever it is shown.
|
||||
#[test]
|
||||
fn campaign_ls_names_the_codename_between_the_id_and_the_title() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_campaign(&worklane, "No codename here", CAMP_B);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First public release",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
|
||||
let out = run(&temp, &["campaign", "ls"]);
|
||||
let listing = stdout(&out);
|
||||
|
||||
assert!(listing.contains("~v1 First public release"), "{listing}");
|
||||
// And a campaign without one spends nothing on it, the way an untagged card spends no
|
||||
// row.
|
||||
assert!(listing.contains(") No codename here"), "{listing}");
|
||||
assert!(!listing.contains("~No codename"), "{listing}");
|
||||
let _ = worklane;
|
||||
}
|
||||
|
||||
/// `campaign show` renders its metadata as a table, so the field is there to read without
|
||||
/// anything being written twice.
|
||||
#[test]
|
||||
fn campaign_show_renders_the_codename_in_its_metadata() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First public release",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
|
||||
let out = run(&temp, &["campaign", "show", "First public"]);
|
||||
assert!(stdout(&out).contains("Codename"), "{}", stdout(&out));
|
||||
assert!(stdout(&out).contains("v1"), "{}", stdout(&out));
|
||||
let _ = worklane;
|
||||
}
|
||||
|
||||
/// A codename nobody can type is half a field, so it resolves a campaign the way its
|
||||
/// uuid and its title do. Exact, and ahead of all three: it is a match on a field written
|
||||
/// for the purpose rather than a substring that could be a coincidence.
|
||||
#[test]
|
||||
fn a_campaign_resolves_by_its_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
// Same file, plus a codename, since `create_campaign` writes none.
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let content = fs::read_to_string(&path).unwrap();
|
||||
fs::write(
|
||||
&path,
|
||||
content.replace("- **Owner**:", "- **Codename**: beaver\n- **Owner**:"),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let out = run(&temp, &["assign", "beaver", MEMBER]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
ticket(&worklane, MEMBER).contains(&format!("- **Campaign**: {CAMP_A}")),
|
||||
"{}",
|
||||
ticket(&worklane, MEMBER)
|
||||
);
|
||||
|
||||
// And every other command that takes a campaign, since they share one resolver.
|
||||
let out = run(&temp, &["campaign", "show", "beaver"]);
|
||||
assert!(stdout(&out).contains("v1 release"), "{}", stdout(&out));
|
||||
|
||||
let out = run(&temp, &["ls", "--campaign", "beaver"]);
|
||||
assert!(stdout(&out).contains("The member"), "{}", stdout(&out));
|
||||
}
|
||||
|
||||
/// An exact codename beats a title that merely contains the search, which is the whole
|
||||
/// reason it is a tier of its own: `v2` is a substring of `v2 release` and the exact
|
||||
/// match has to win outright rather than be reported as ambiguous against it.
|
||||
#[test]
|
||||
fn an_exact_codename_beats_a_title_that_contains_the_search() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let content = fs::read_to_string(&path).unwrap();
|
||||
fs::write(&path, content.replace("- **Owner**:", "- **Codename**: v2\n- **Owner**:")).unwrap();
|
||||
|
||||
let out = run(&temp, &["assign", "v2", MEMBER]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
ticket(&worklane, MEMBER).contains(&format!("- **Campaign**: {CAMP_A}")),
|
||||
"the title tier won: {}",
|
||||
ticket(&worklane, MEMBER)
|
||||
);
|
||||
}
|
||||
|
||||
/// A ticket carries no codename, so the tier is empty for one and ticket resolution is
|
||||
/// exactly what it was. Pinned because the tier lives in the shared resolver: this is the
|
||||
/// half of it that must not have changed.
|
||||
#[test]
|
||||
fn a_ticket_search_is_unaffected_by_the_codename_tier() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
// The uuid prefix still wins over a title that quotes it, which is the precedence the
|
||||
// three tiers were written for.
|
||||
let out = run(&temp, &["show", "641e3d5"]);
|
||||
assert!(stdout(&out).contains("The member"), "{}", stdout(&out));
|
||||
let _ = worklane;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- campaign set --
|
||||
|
||||
/// The point of the command: a campaign already on the board can be given a codename,
|
||||
/// which `campaign add --codename` cannot do because `add` files a new one.
|
||||
#[test]
|
||||
fn campaign_set_gives_a_filed_campaign_a_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "--codename", "beaver"]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("Updated codename"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("- **Codename**: beaver"), "{content}");
|
||||
}
|
||||
|
||||
/// `create_campaign` writes no Codename line at all, which is every campaign filed before
|
||||
/// the field existed, so the insertion path is the one this command is actually for.
|
||||
/// It lands under the ID, where `campaign add` writes it, so a campaign given a codename
|
||||
/// later is the same file as one filed with it.
|
||||
#[test]
|
||||
fn the_codename_is_inserted_under_the_id_when_the_line_is_absent() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"the fixture changed"
|
||||
);
|
||||
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
let id = content.find("- **ID**:").expect("no id");
|
||||
let codename = content.find("- **Codename**:").expect("no codename");
|
||||
let owner = content.find("- **Owner**:").expect("no owner");
|
||||
assert!(id < codename && codename < owner, "{content}");
|
||||
}
|
||||
|
||||
/// One parser, so a codename is one thing however it was written. The board draws it as a
|
||||
/// label with a mark and no quoting, and that does not depend on which command wrote it.
|
||||
#[test]
|
||||
fn campaign_set_validates_the_codename_the_way_add_does() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
for value in ["two words", ""] {
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "--codename", value]);
|
||||
assert_eq!(out.status.code(), Some(2), "{value:?}: {}", stderr(&out));
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"{value:?} was written"
|
||||
);
|
||||
}
|
||||
|
||||
// And the message is the one `campaign add` gives, since the parser is the same.
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "--codename", "two words"]);
|
||||
assert!(stderr(&out).contains("single word"), "{}", stderr(&out));
|
||||
}
|
||||
|
||||
/// A bare `campaign set <campaign>` is a usage error rather than a silent no-op, exactly
|
||||
/// as it is for `set`.
|
||||
#[test]
|
||||
fn campaign_set_with_no_field_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release"]);
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"something was written"
|
||||
);
|
||||
}
|
||||
|
||||
/// Replacing the title renames the file, keeping the uuid, the way `set --title` does. That
|
||||
/// is the reason this is a `set` rather than a flag on something narrower.
|
||||
#[test]
|
||||
fn campaign_set_renames_the_file_with_the_title() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
// A member first, so the rename has something to break.
|
||||
run(&temp, &["assign", "v1 release", MEMBER]);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"--title",
|
||||
"First public release",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let names = campaigns(&worklane);
|
||||
assert!(
|
||||
names.contains(&format!("{CAMP_A}_first-public-release.md")),
|
||||
"not renamed: {names:?}"
|
||||
);
|
||||
assert!(
|
||||
!names.contains(&format!("{CAMP_A}_v1-release.md")),
|
||||
"the old file is still there: {names:?}"
|
||||
);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.starts_with("# First public release\n"), "{content}");
|
||||
// The uuid is kept, so membership survives the rename: it is stored on the member as
|
||||
// the uuid, and nothing has to be rewritten when the campaign is renamed.
|
||||
assert!(content.contains(&format!("- **ID**: {CAMP_A}")), "{content}");
|
||||
let out = run(&temp, &["ls", "--campaign", "First public release"]);
|
||||
assert!(
|
||||
stdout(&out).contains("The member"),
|
||||
"membership was lost: {}",
|
||||
stdout(&out)
|
||||
);
|
||||
}
|
||||
|
||||
/// Both fields in one call, since the group is `multiple`.
|
||||
#[test]
|
||||
fn campaign_set_takes_the_title_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",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("title, codename"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.starts_with("# First public release\n"), "{content}");
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
}
|
||||
|
||||
/// The whole-file comparison `set` and `chown` use, so writing what is already there
|
||||
/// writes nothing and says so.
|
||||
#[test]
|
||||
fn setting_the_codename_a_campaign_already_has_writes_nothing() {
|
||||
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", "-c", "v1"]);
|
||||
|
||||
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");
|
||||
}
|
||||
|
||||
/// A codename set here resolves the campaign afterwards, which is the whole point of the
|
||||
/// field being typable: the tier is in the shared resolver, not in `campaign add`.
|
||||
#[test]
|
||||
fn a_codename_set_afterwards_resolves_the_campaign() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "beaver"]);
|
||||
|
||||
let out = run(&temp, &["assign", "beaver", MEMBER]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
ticket(&worklane, MEMBER).contains(&format!("- **Campaign**: {CAMP_A}")),
|
||||
"{}",
|
||||
ticket(&worklane, MEMBER)
|
||||
);
|
||||
}
|
||||
|
||||
/// Nothing else in the file moves. A campaign carries prose and an owner this command
|
||||
/// cannot reach, and a hand-written section has to survive an edit to a field.
|
||||
#[test]
|
||||
fn content_the_command_cannot_reach_survives_a_set() {
|
||||
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("## Metadata", "## Notes\nA handwritten note.\n\n## Metadata"),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("A handwritten note."), "{content}");
|
||||
assert!(content.contains("What has to ship together."), "{content}");
|
||||
assert!(content.contains("- **Owner**: alice"), "{content}");
|
||||
assert!(!content.contains("**Status**"), "a status was invented: {content}");
|
||||
}
|
||||
|
||||
/// A campaign that does not resolve leaves everything alone, the answer `assign` already
|
||||
/// gives an unknown campaign.
|
||||
#[test]
|
||||
fn an_unknown_campaign_is_refused_and_nothing_is_written() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "nothing-by-that-name", "-c", "v1"]);
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("No campaign found"), "{}", stderr(&out));
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"something was written"
|
||||
);
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_B).contains("Codename"),
|
||||
"something was 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.
|
||||
#[test]
|
||||
fn campaign_set_offers_no_description_and_no_owner() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "--help"]);
|
||||
let help = stdout(&out);
|
||||
|
||||
assert!(help.contains("--codename"), "{help}");
|
||||
assert!(help.contains("--title"), "{help}");
|
||||
assert!(!help.contains("--description"), "{help}");
|
||||
assert!(!help.contains("--owner"), "{help}");
|
||||
assert!(!help.contains("--clear"), "{help}");
|
||||
}
|
||||
|
||||
/// A codename is how a campaign is referred to once it has one: on every card in it and at
|
||||
/// the command line. Replacing that silently is the mistake `install-skill --force` exists
|
||||
/// to prevent, so it is refused and the refusal names the flag.
|
||||
#[test]
|
||||
fn an_existing_codename_is_not_replaced_without_force() {
|
||||
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", "-c", "beaver"]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
let said = stderr(&out);
|
||||
// Both words and the flag, so the message says what is there, what was asked for and
|
||||
// how to get it.
|
||||
assert!(said.contains("already codenamed 'v1'"), "{said}");
|
||||
assert!(said.contains("'beaver'"), "{said}");
|
||||
assert!(said.contains("--force"), "{said}");
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written anyway");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn force_replaces_an_existing_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1", "-c", "beaver", "--force"]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("- **Codename**: beaver"), "{content}");
|
||||
// The line is replaced, not added beside the old one. Asserted on the field rather
|
||||
// than on the word, since the campaign's title is "v1 release" and holds it too.
|
||||
assert!(!content.contains("- **Codename**: v1"), "the old line survived: {content}");
|
||||
assert_eq!(content.matches("**Codename**").count(), 1, "two codenames: {content}");
|
||||
}
|
||||
|
||||
/// The guard is about overwriting a *different* word. A campaign with no codename has
|
||||
/// nothing to overwrite, so `--force` is not the price of the first one.
|
||||
#[test]
|
||||
fn the_first_codename_needs_no_force() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"the fixture changed"
|
||||
);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).contains("- **Codename**: v1"));
|
||||
}
|
||||
|
||||
/// And setting the one it already has stays a no-op rather than becoming a refusal: there
|
||||
/// is nothing to overwrite, which is the same answer `install-skill` gives an identical
|
||||
/// document.
|
||||
#[test]
|
||||
fn setting_the_same_codename_again_is_a_no_op_not_a_refusal() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1", "-c", "v1"]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).contains("- **Codename**: v1"));
|
||||
}
|
||||
|
||||
/// Refused before any edit is applied, like `SetArgs::contested`, so a call carrying both
|
||||
/// fields writes neither rather than half of what was asked for.
|
||||
#[test]
|
||||
fn a_refused_codename_takes_the_title_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",
|
||||
"-t",
|
||||
"Renamed anyway",
|
||||
"-c",
|
||||
"beaver",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the title went through");
|
||||
let names = campaigns(&worklane);
|
||||
assert!(
|
||||
!names.iter().any(|name| name.contains("renamed-anyway")),
|
||||
"renamed: {names:?}"
|
||||
);
|
||||
}
|
||||
|
||||
/// The title needs no guard, since a campaign always has one and replacing it is what the
|
||||
/// flag is for. `--force` is the codename's alone.
|
||||
#[test]
|
||||
fn the_title_is_replaced_without_force() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1", "--title", "First public release"]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).starts_with("# First public release\n"));
|
||||
}
|
||||
|
||||
+2
-9
@@ -298,10 +298,7 @@ fn show_numbers_the_criteria() {
|
||||
assert!(!stdout.contains("4. ["), "the handwritten line was numbered: {stdout:?}");
|
||||
|
||||
// And the description checkbox is left as it is, outside the numbering
|
||||
assert!(
|
||||
stdout.contains("- [ ] A checkbox in the description"),
|
||||
"{stdout:?}"
|
||||
);
|
||||
assert!(stdout.contains("- [ ] A checkbox in the description"), "{stdout:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -418,11 +415,7 @@ fn a_batch_that_would_change_nothing_writes_nothing() {
|
||||
assert!(out.status.success());
|
||||
|
||||
let stdout = String::from_utf8_lossy(&out.stdout);
|
||||
assert_eq!(
|
||||
stdout.matches("Already checked").count(),
|
||||
3,
|
||||
"{stdout:?}"
|
||||
);
|
||||
assert_eq!(stdout.matches("Already checked").count(), 3, "{stdout:?}");
|
||||
assert_eq!(ticket(&worklane), before, "the file was rewritten anyway");
|
||||
}
|
||||
|
||||
|
||||
+90
-11
@@ -89,11 +89,7 @@ fn chown_sets_the_owner() {
|
||||
create_ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["chown", "bob", UUID]);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stdout).contains("owner"),
|
||||
"{:?}",
|
||||
@@ -139,10 +135,7 @@ fn chown_leaves_everything_it_was_not_asked_about_alone() {
|
||||
run(&temp, &["chown", "bob", UUID]);
|
||||
|
||||
let content = ticket(&worklane);
|
||||
assert!(
|
||||
content.contains("- [x] Crit one"),
|
||||
"the tick was lost: {content}"
|
||||
);
|
||||
assert!(content.contains("- [x] Crit one"), "the tick was lost: {content}");
|
||||
assert!(
|
||||
content.contains("## Notes\nA handwritten note the tool knows nothing about.\n"),
|
||||
"the unknown section was lost: {content}"
|
||||
@@ -213,7 +206,8 @@ fn chown_refuses_a_swapped_call() {
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
}
|
||||
|
||||
/// An empty user looks like a way to clear the field, and clearing is not supported.
|
||||
/// An empty user is still a usage error, and now points at the flag that does take the
|
||||
/// owner away.
|
||||
#[test]
|
||||
fn chown_refuses_an_empty_user_as_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
@@ -223,11 +217,96 @@ fn chown_refuses_an_empty_user_as_a_usage_error() {
|
||||
|
||||
let out = run(&temp, &["chown", "", UUID]);
|
||||
assert_eq!(out.status.code(), Some(2));
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains("use --clear"), "{stderr:?}");
|
||||
assert!(!stderr.contains("not supported"), "{stderr:?}");
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
}
|
||||
|
||||
/// The owner goes back to the sentinel, not to the git user: an owner taken away says
|
||||
/// nobody owns this.
|
||||
#[test]
|
||||
fn chown_clear_returns_the_owner_to_unset() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["chown", "--clear", UUID]);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stderr).contains("clearing a field is not supported"),
|
||||
String::from_utf8_lossy(&out.stdout).contains("Cleared owner"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stdout)
|
||||
);
|
||||
|
||||
let content = ticket(&worklane);
|
||||
assert!(content.contains("- **Owner**: _Not set_"), "{content}");
|
||||
// Nothing else on the way past.
|
||||
assert!(content.contains("- **Status**: backlog"), "{content}");
|
||||
}
|
||||
|
||||
/// The ticket is still resolved the three usual ways when it arrives in the flag.
|
||||
#[test]
|
||||
fn chown_clear_resolves_the_ticket_it_is_given() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["chown", "--clear", "Original"]);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(ticket(&worklane).contains("- **Owner**: _Not set_"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn chown_clear_on_an_unowned_ticket_is_no_change() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
run(&temp, &["chown", "--clear", UUID]);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["chown", "--clear", UUID]);
|
||||
assert!(out.status.success());
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stdout).contains("No changes"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stdout)
|
||||
);
|
||||
assert_eq!(ticket(&worklane), before, "the file was rewritten anyway");
|
||||
}
|
||||
|
||||
/// Setting an owner and clearing it are the two forms of the command, and clap keeps
|
||||
/// them apart rather than the handler picking one.
|
||||
#[test]
|
||||
fn chown_refuses_a_user_and_a_clear_together() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
for args in [
|
||||
vec!["chown", "bob", "--clear", UUID],
|
||||
vec!["chown", "bob", UUID, "--clear", UUID],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert_eq!(out.status.code(), Some(2), "{args:?} was accepted");
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stderr).contains("cannot be used with"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
}
|
||||
|
||||
// And a bare --clear still needs the ticket it is meant to name.
|
||||
let out = run(&temp, &["chown", "--clear"]);
|
||||
assert_eq!(out.status.code(), Some(2));
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stderr).contains("a value is required"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
}
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::fixture::{PathChild, PathCreateDir};
|
||||
use assert_fs::TempDir;
|
||||
use assert_fs::fixture::{PathChild, PathCreateDir};
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
@@ -17,11 +17,7 @@ fn setup_worklane(temp: &TempDir) -> PathBuf {
|
||||
worklane.path().to_path_buf()
|
||||
}
|
||||
|
||||
fn create_ticket(
|
||||
worklane_dir: &Path,
|
||||
status: &str,
|
||||
title: &str,
|
||||
) -> String {
|
||||
fn create_ticket(worklane_dir: &Path, status: &str, title: &str) -> String {
|
||||
let uuid = uuid::Uuid::new_v4().to_string();
|
||||
let slug = title
|
||||
.to_lowercase()
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
use assert_cmd::Command;
|
||||
|
||||
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
|
||||
fn script(shell: &str) -> String {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let assert = cmd.arg("completions").arg(shell).assert().success();
|
||||
String::from_utf8(assert.get_output().stdout.clone()).unwrap()
|
||||
}
|
||||
|
||||
/// Every shell clap can generate for, since the README names all five.
|
||||
#[test]
|
||||
fn completions_prints_a_script_for_every_shell() {
|
||||
for shell in ["fish", "bash", "zsh", "elvish", "powershell"] {
|
||||
let out = script(shell);
|
||||
assert!(out.contains("worklane"), "the {shell} script never names the command");
|
||||
// Long enough to be a script rather than an empty file with a comment in it.
|
||||
assert!(out.len() > 500, "the {shell} script is {} bytes", out.len());
|
||||
}
|
||||
}
|
||||
|
||||
/// No board is looked for, the way `install-skill` looks for none: the script comes off
|
||||
/// the clap definition and is the same wherever it is run. Run from a temp directory
|
||||
/// with no `.worklane` above it, which every other command refuses.
|
||||
#[test]
|
||||
fn completions_needs_no_board() {
|
||||
let temp = assert_fs::TempDir::new().unwrap();
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.arg("completions")
|
||||
.arg("fish")
|
||||
.assert()
|
||||
.success();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn fish_gets_both_halves() {
|
||||
let out = script("fish");
|
||||
// clap's, which is where the subcommands and the flags come from.
|
||||
assert!(out.contains("__fish_worklane_needs_command"));
|
||||
assert!(out.contains("install-skill"));
|
||||
// Ours, which is where the tickets come from.
|
||||
assert!(out.contains("__worklane_first_arg_of"));
|
||||
assert!(out.contains("worklane ls --ids"));
|
||||
}
|
||||
|
||||
/// The fish half is fish syntax, so it must not reach any other shell's output.
|
||||
#[test]
|
||||
fn no_other_shell_gets_the_fish_half() {
|
||||
for shell in ["bash", "zsh", "elvish", "powershell"] {
|
||||
let out = script(shell);
|
||||
assert!(
|
||||
!out.contains("__worklane_first_arg_of"),
|
||||
"fish-only helpers leaked into {shell}"
|
||||
);
|
||||
assert!(!out.contains("worklane ls --ids"), "the dynamic half leaked into {shell}");
|
||||
}
|
||||
}
|
||||
|
||||
/// The four statuses reach fish twice over, from clap for the `mv` option and from the
|
||||
/// appended half for the `ls` positional, which clap emits nothing for.
|
||||
#[test]
|
||||
fn fish_is_offered_every_status() {
|
||||
let out = script("fish");
|
||||
for status in ["backlog", "committed", "reviewing", "done"] {
|
||||
assert!(out.contains(status), "fish is never offered {status}");
|
||||
}
|
||||
assert!(out.contains("-a 'backlog committed reviewing done' -d status"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_unknown_shell_is_a_usage_error() {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let assert = cmd.arg("completions").arg("tcsh").assert().code(2);
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains("invalid value 'tcsh'"), "{stderr}");
|
||||
}
|
||||
@@ -54,11 +54,7 @@ fn every_skill_installs_outside_a_worklane_directory() {
|
||||
assert_eq!(std::fs::read_to_string(installed_plan(&home)).unwrap(), PLAN);
|
||||
|
||||
// Once, not per document: it is the one thing to do next, not part of an outcome.
|
||||
assert_eq!(
|
||||
stdout.matches("pick it up on their next session").count(),
|
||||
1,
|
||||
"{stdout}"
|
||||
);
|
||||
assert_eq!(stdout.matches("pick it up on their next session").count(), 1, "{stdout}");
|
||||
}
|
||||
|
||||
/// Narrowing to one document is the exception, and it must leave the others alone.
|
||||
@@ -72,7 +68,10 @@ fn a_named_skill_installs_only_that_one() {
|
||||
assert_eq!(out.status.code(), Some(0), "{stdout}");
|
||||
assert_eq!(std::fs::read_to_string(installed_review(&home)).unwrap(), REVIEW);
|
||||
assert!(!installed(&home).exists(), "a named install wrote the other document too");
|
||||
assert!(!installed_plan(&home).exists(), "a named install wrote the other document too");
|
||||
assert!(
|
||||
!installed_plan(&home).exists(),
|
||||
"a named install wrote the other document too"
|
||||
);
|
||||
}
|
||||
|
||||
/// A name nothing ships is a stop, with the choices in the message: guessing at the
|
||||
@@ -118,7 +117,10 @@ fn a_modified_copy_is_reported_and_needs_force() {
|
||||
assert_eq!(out.status.code(), Some(0), "{stdout}");
|
||||
assert!(stdout.contains("Differs from the version in this binary"), "{stdout}");
|
||||
assert!(stdout.contains("--force"), "{stdout}");
|
||||
assert!(stdout.contains("--print"), "the message never says how to compare: {stdout}");
|
||||
assert!(
|
||||
stdout.contains("--print"),
|
||||
"the message never says how to compare: {stdout}"
|
||||
);
|
||||
assert_eq!(
|
||||
std::fs::read_to_string(installed(&home)).unwrap(),
|
||||
"hand written\n",
|
||||
@@ -186,7 +188,10 @@ fn print_without_a_name_says_which_names_there_are() {
|
||||
assert_ne!(out.status.code(), Some(0), "{stderr}");
|
||||
assert!(stderr.contains("name the skill to print"), "{stderr}");
|
||||
assert!(stderr.contains("worklane-review"), "{stderr}");
|
||||
assert!(String::from_utf8_lossy(&out.stdout).is_empty(), "a document was printed anyway");
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stdout).is_empty(),
|
||||
"a document was printed anyway"
|
||||
);
|
||||
}
|
||||
|
||||
/// The command has to be findable by someone who does not already know it exists.
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
|
||||
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
|
||||
/// The tool as this test's binary carries it, so the print path is pinned to the file in
|
||||
/// the repo rather than to a description of it.
|
||||
const TOOL: &str = include_str!("../assets/TOOL.ts");
|
||||
|
||||
/// `XDG_CONFIG_HOME` is redirected, and `HOME` with it, so the suite never writes into
|
||||
/// the config of whoever runs it. Both, because the fallback reads `HOME` and a machine
|
||||
/// that has neither set is not the case under test here.
|
||||
fn run(config: &TempDir, args: &[&str]) -> std::process::Output {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.env("XDG_CONFIG_HOME", config.path())
|
||||
.env("HOME", config.path())
|
||||
.args(args);
|
||||
cmd.assert().get_output().clone()
|
||||
}
|
||||
|
||||
fn installed(config: &TempDir) -> std::path::PathBuf {
|
||||
config.path().join("opencode/tool/worklane.ts")
|
||||
}
|
||||
|
||||
fn stdout(output: &std::process::Output) -> String {
|
||||
String::from_utf8(output.stdout.clone()).unwrap()
|
||||
}
|
||||
|
||||
/// Nothing about the tool needs a board, and it is wanted before there is one.
|
||||
///
|
||||
/// The file name is asserted, not just the directory: opencode names each tool as the
|
||||
/// file then the export, so `worklane.ts` is what makes them `worklane_add` and
|
||||
/// `worklane_mv`.
|
||||
#[test]
|
||||
fn the_tool_installs_outside_a_worklane_directory() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let output = run(&config, &["install-tool"]);
|
||||
|
||||
assert!(output.status.success());
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
|
||||
assert!(
|
||||
stdout(&output).contains("Installed the worklane tool"),
|
||||
"{}",
|
||||
stdout(&output)
|
||||
);
|
||||
}
|
||||
|
||||
/// What the message has to carry, and it is not the skills' "next session": opencode
|
||||
/// reads its config once at startup and never reloads it, so a running one keeps the
|
||||
/// tools it began with. The second half is there because the file is executable and
|
||||
/// looks like it needs a toolchain, which it does not.
|
||||
#[test]
|
||||
fn the_tool_says_to_restart_opencode_and_that_nothing_else_is_needed() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let out = stdout(&run(&config, &["install-tool"]));
|
||||
|
||||
assert!(out.contains("Restart it"), "{out}");
|
||||
assert!(out.contains("never reloaded"), "{out}");
|
||||
assert!(out.contains("Nothing else to install"), "{out}");
|
||||
assert!(out.contains("Bun"), "{out}");
|
||||
}
|
||||
|
||||
/// Installing twice is a no-op rather than a rewrite, exactly as `install-skill` is.
|
||||
#[test]
|
||||
fn a_second_install_reports_the_copy_unchanged() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
let out = stdout(&run(&config, &["install-tool"]));
|
||||
|
||||
assert!(out.contains("Already up to date"), "{out}");
|
||||
assert!(!out.contains("Installed the"), "{out}");
|
||||
}
|
||||
|
||||
/// An edited copy is somebody's work, and the refusal names the invocation that shows
|
||||
/// what it would be replaced with. `--print` there and not a skill name: there is one
|
||||
/// tool file, so nothing has to say which.
|
||||
#[test]
|
||||
fn a_modified_copy_is_refused_until_force() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
std::fs::write(installed(&config), "// hand written\n").unwrap();
|
||||
|
||||
let refused = stdout(&run(&config, &["install-tool"]));
|
||||
assert!(refused.contains("Differs from the version in this binary"), "{refused}");
|
||||
assert!(refused.contains("worklane install-tool --print"), "{refused}");
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), "// hand written\n");
|
||||
|
||||
let forced = stdout(&run(&config, &["install-tool", "--force"]));
|
||||
assert!(forced.contains("Installed the worklane tool"), "{forced}");
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
|
||||
}
|
||||
|
||||
/// `--print` is for diffing against an installed copy, so it writes nothing.
|
||||
#[test]
|
||||
fn print_writes_the_tool_to_stdout_and_installs_nothing() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let output = run(&config, &["install-tool", "--print"]);
|
||||
|
||||
assert_eq!(stdout(&output), TOOL);
|
||||
assert!(!installed(&config).exists());
|
||||
}
|
||||
|
||||
/// With no `XDG_CONFIG_HOME` the tool lands under `HOME`, which is the same answer
|
||||
/// opencode gives: its config root is `$XDG_CONFIG_HOME/opencode` when that is set and
|
||||
/// `~/.config/opencode` when it is not.
|
||||
#[test]
|
||||
fn the_tool_falls_back_to_the_home_directory_without_xdg_config_home() {
|
||||
let home = TempDir::new().unwrap();
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let output = cmd
|
||||
.env_remove("XDG_CONFIG_HOME")
|
||||
.env("HOME", home.path())
|
||||
.arg("install-tool")
|
||||
.assert()
|
||||
.success()
|
||||
.get_output()
|
||||
.clone();
|
||||
|
||||
let path = home.path().join(".config/opencode/tool/worklane.ts");
|
||||
assert_eq!(std::fs::read_to_string(&path).unwrap(), TOOL);
|
||||
assert!(
|
||||
stdout(&output).contains(&path.display().to_string()),
|
||||
"{}",
|
||||
stdout(&output)
|
||||
);
|
||||
}
|
||||
|
||||
/// The two commands are independent, which is the whole point of them being two: a
|
||||
/// person on Claude Code takes the skills and never the tool, and one who wants the
|
||||
/// tools is not made to take a second copy of the documents to get them.
|
||||
#[test]
|
||||
fn each_install_command_leaves_the_other_target_alone() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
|
||||
assert!(installed(&config).exists());
|
||||
assert!(!config.path().join(".claude/skills").exists());
|
||||
|
||||
let skills_only = TempDir::new().unwrap();
|
||||
run(&skills_only, &["install-skill"]);
|
||||
|
||||
assert!(
|
||||
skills_only
|
||||
.path()
|
||||
.join(".claude/skills/worklane/SKILL.md")
|
||||
.exists()
|
||||
);
|
||||
assert!(!installed(&skills_only).exists());
|
||||
}
|
||||
+439
-6
@@ -191,7 +191,11 @@ fn ls_handles_short_and_non_ascii_filenames() {
|
||||
}
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).arg("ls").arg("backlog").assert().success();
|
||||
cmd.current_dir(temp.path())
|
||||
.arg("ls")
|
||||
.arg("backlog")
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert_eq!(stdout.matches("Odd Name").count(), 3);
|
||||
@@ -209,7 +213,11 @@ fn ls_survives_a_malformed_created_at() {
|
||||
.unwrap();
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).arg("ls").arg("backlog").assert().success();
|
||||
cmd.current_dir(temp.path())
|
||||
.arg("ls")
|
||||
.arg("backlog")
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert!(stdout.contains("Bad Date"));
|
||||
@@ -290,7 +298,10 @@ fn ls_shows_a_mark_for_the_level() {
|
||||
|
||||
// Piped, so no escapes: the glyph is carrying the level by itself
|
||||
assert!(!stdout.contains('\u{1b}'));
|
||||
assert!(stdout.contains("\u{25cf}\u{25cf} "), "no full meter for level 1 in {stdout:?}");
|
||||
assert!(
|
||||
stdout.contains("\u{25cf}\u{25cf} "),
|
||||
"no full meter for level 1 in {stdout:?}"
|
||||
);
|
||||
assert!(stdout.contains("\u{25cb}\u{25cb} "), "no empty meter for level 5");
|
||||
assert!(stdout.contains("\u{b7}\u{b7} "), "no unset mark");
|
||||
// The raw number is not what the listing shows
|
||||
@@ -340,7 +351,10 @@ fn ls_filters_by_tag_and_composes_with_status_and_priority() {
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert!(stdout.contains("Tagged bug"), "{stdout}");
|
||||
assert!(stdout.contains("Lower bug"), "{stdout}");
|
||||
assert!(stdout.contains("Started bug"), "a tagged ticket in another status was dropped");
|
||||
assert!(
|
||||
stdout.contains("Started bug"),
|
||||
"a tagged ticket in another status was dropped"
|
||||
);
|
||||
assert!(!stdout.contains("Tagged feature"), "an untagged ticket came through");
|
||||
// The counts are filtered too, since they are the same collect.
|
||||
assert!(stdout.contains("[BACKLOG] 2 tickets"), "{stdout}");
|
||||
@@ -436,8 +450,7 @@ fn ls_never_matches_a_ticket_carrying_no_tags() {
|
||||
// Nor does an empty tag reach the filter: the value parser refuses it, so nothing is
|
||||
// listed rather than everything.
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.args(["ls", "backlog", "--tag", ""]);
|
||||
cmd.current_dir(temp.path()).args(["ls", "backlog", "--tag", ""]);
|
||||
cmd.assert().failure().code(2);
|
||||
}
|
||||
|
||||
@@ -470,3 +483,423 @@ fn ls_with_a_tag_nothing_carries_lists_nothing() {
|
||||
assert!(stdout.contains("[BACKLOG] 0 tickets"), "{stdout}");
|
||||
assert!(!stdout.contains("Tagged bug"), "{stdout}");
|
||||
}
|
||||
|
||||
/// A ticket with an id of its own, since `create_ticket` gives every fixture the same
|
||||
/// uuid and `--ids` is the one output where the id is the whole point.
|
||||
fn create_ticket_with_id(
|
||||
worklane_dir: &std::path::Path,
|
||||
status: &str,
|
||||
title: &str,
|
||||
uuid: &str,
|
||||
tags: &str,
|
||||
) {
|
||||
let ticket_body = format!(
|
||||
"# {title}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Tags**: {tags}\n- **Owner**: alice\n- **Status**: {status}\n"
|
||||
);
|
||||
let filename = format!("{uuid}_{}.md", slug(title));
|
||||
fs::write(worklane_dir.join(status).join(filename), ticket_body).unwrap();
|
||||
}
|
||||
|
||||
/// The slug rule, as AGENTS.md requires: derived, never written by hand.
|
||||
fn slug(title: &str) -> String {
|
||||
title
|
||||
.to_lowercase()
|
||||
.chars()
|
||||
.filter(|c| c.is_alphanumeric() || *c == ' ' || *c == '-' || *c == '_')
|
||||
.map(|c| if c == ' ' { '-' } else { c })
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// One ticket per line, the seven-character id then a tab then the title, and nothing
|
||||
/// else: no heading, no counts, no owner or due column.
|
||||
#[test]
|
||||
fn ls_ids_prints_the_id_and_the_title_and_nothing_else() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket_with_id(
|
||||
&worklane,
|
||||
"backlog",
|
||||
"Feature A",
|
||||
"1b78a24c-0000-0000-0000-000000000001",
|
||||
"bug",
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "--ids"]);
|
||||
cmd.assert().success();
|
||||
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert_eq!(stdout, "1b78a24\tFeature A\n", "{stdout:?}");
|
||||
}
|
||||
|
||||
/// Every status, done included, where the decorated listing leaves done out. A
|
||||
/// completion has to be able to name a finished ticket.
|
||||
#[test]
|
||||
fn ls_ids_includes_done_and_narrows_to_a_named_status() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket_with_id(
|
||||
&worklane,
|
||||
"backlog",
|
||||
"Still open",
|
||||
"aaaaaaa1-0000-0000-0000-000000000001",
|
||||
"bug",
|
||||
);
|
||||
create_ticket_with_id(
|
||||
&worklane,
|
||||
"done",
|
||||
"Finished",
|
||||
"bbbbbbb2-0000-0000-0000-000000000002",
|
||||
"bug",
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "--ids"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert!(stdout.contains("Still open"), "{stdout}");
|
||||
assert!(stdout.contains("Finished"), "a done ticket cannot be named: {stdout}");
|
||||
|
||||
// The decorated listing is unchanged: done is counted, not listed.
|
||||
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("Finished"), "{stdout}");
|
||||
|
||||
// The positional still narrows it.
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "done", "--ids"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert_eq!(stdout, "bbbbbbb\tFinished\n", "{stdout:?}");
|
||||
}
|
||||
|
||||
/// The filters apply to `--ids` exactly as they do to the listing, so a completion can
|
||||
/// be narrowed the same way.
|
||||
#[test]
|
||||
fn ls_ids_still_takes_the_filters() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket_with_id(
|
||||
&worklane,
|
||||
"backlog",
|
||||
"Tagged bug",
|
||||
"aaaaaaa1-0000-0000-0000-000000000001",
|
||||
"bug",
|
||||
);
|
||||
create_ticket_with_id(
|
||||
&worklane,
|
||||
"backlog",
|
||||
"Tagged cli",
|
||||
"bbbbbbb2-0000-0000-0000-000000000002",
|
||||
"cli",
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.args(["ls", "--ids", "--tag", "cli"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert_eq!(stdout, "bbbbbbb\tTagged cli\n", "{stdout:?}");
|
||||
}
|
||||
|
||||
/// An unknown campaign is refused before anything is read, even here. A completion that
|
||||
/// listed the whole board because the name was misspelled would be worse than one that
|
||||
/// printed nothing.
|
||||
#[test]
|
||||
fn ls_ids_still_refuses_an_unknown_campaign() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket_with_id(
|
||||
&worklane,
|
||||
"backlog",
|
||||
"Feature A",
|
||||
"aaaaaaa1-0000-0000-0000-000000000001",
|
||||
"bug",
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.args(["ls", "--ids", "--campaign", "no such campaign"]);
|
||||
cmd.assert().failure();
|
||||
}
|
||||
|
||||
/// A status the board is missing is skipped rather than refused, unlike the listing:
|
||||
/// the caller is a shell filling in candidates, and an error printed over the prompt is
|
||||
/// worse there than no candidates.
|
||||
#[test]
|
||||
fn ls_ids_is_quiet_about_a_missing_status_directory() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = temp.child(".worklane");
|
||||
worklane.create_dir_all().unwrap();
|
||||
worklane.child("backlog").create_dir_all().unwrap();
|
||||
|
||||
create_ticket_with_id(
|
||||
worklane.path(),
|
||||
"backlog",
|
||||
"Feature A",
|
||||
"aaaaaaa1-0000-0000-0000-000000000001",
|
||||
"bug",
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "--ids"]);
|
||||
cmd.assert().success();
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
assert_eq!(stdout, "aaaaaaa\tFeature A\n", "{stdout:?}");
|
||||
|
||||
// The listing still says so, since a person reading it can act on it.
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "done"]);
|
||||
let assert = cmd.assert().failure();
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains("No 'done' directory"), "{stderr}");
|
||||
}
|
||||
|
||||
/// A status outside the four is clap's to refuse now, so it is a usage error naming the
|
||||
/// four rather than a runtime one.
|
||||
#[test]
|
||||
fn ls_names_the_four_statuses_when_given_another() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let assert = cmd
|
||||
.current_dir(temp.path())
|
||||
.args(["ls", "nonexistent"])
|
||||
.assert()
|
||||
.code(2);
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains("invalid value 'nonexistent'"), "{stderr}");
|
||||
for status in ["backlog", "committed", "reviewing", "done"] {
|
||||
assert!(stderr.contains(status), "{status} is not offered: {stderr}");
|
||||
}
|
||||
}
|
||||
|
||||
/// The listing reads the stamps to order the column by them, and prints none of them.
|
||||
/// Pinned against a ticket carrying one, since a listing that started showing them would
|
||||
/// change the output every board and completion script parses.
|
||||
#[test]
|
||||
fn ls_output_is_unchanged_by_a_status_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "committed", "Stamped", "alice", "2026-06-01");
|
||||
let path = worklane
|
||||
.join("committed")
|
||||
.join("00000000-0000-0000-0000-000000000001_stamped.md");
|
||||
let before = {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).arg("ls").arg("committed");
|
||||
get_stdout(&mut cmd)
|
||||
};
|
||||
|
||||
let stamped = fs::read_to_string(&path)
|
||||
.unwrap()
|
||||
.replace("- **Status**:", "- **Committed On**: 2026-08-22 09:14:30\n- **Status**:");
|
||||
fs::write(&path, stamped).unwrap();
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).arg("ls").arg("committed");
|
||||
let after = get_stdout(&mut cmd);
|
||||
|
||||
assert_eq!(after, before);
|
||||
assert!(!after.contains("Committed On"), "{after}");
|
||||
}
|
||||
|
||||
/// A ticket in a status with the entry stamp that status is ordered by, or none.
|
||||
///
|
||||
/// The field is derived from the status rather than passed, so a case says which column
|
||||
/// it is about and cannot name the wrong stamp for it.
|
||||
fn create_stamped_ticket(
|
||||
worklane_dir: &std::path::Path,
|
||||
status: &str,
|
||||
title: &str,
|
||||
uuid: &str,
|
||||
priority: &str,
|
||||
stamp: Option<&str>,
|
||||
) {
|
||||
let field = match status {
|
||||
"committed" => "Committed On",
|
||||
"reviewing" => "Submitted On",
|
||||
"done" => "Completed On",
|
||||
other => panic!("{other} has no entry stamp"),
|
||||
};
|
||||
let line = match stamp {
|
||||
Some(value) => format!("- **{field}**: {value}\n"),
|
||||
None => String::new(),
|
||||
};
|
||||
let body = format!(
|
||||
"# {title}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Priority**: {priority}\n\
|
||||
- **Tags**: test\n- **Due**: _Not set_\n- **Owner**: alice\n{line}\
|
||||
- **Status**: {status}\n"
|
||||
);
|
||||
fs::write(
|
||||
worklane_dir
|
||||
.join(status)
|
||||
.join(format!("{uuid}_{}.md", slug(title))),
|
||||
body,
|
||||
)
|
||||
.unwrap();
|
||||
}
|
||||
|
||||
fn positions(stdout: &str, titles: [&str; 3]) -> Vec<usize> {
|
||||
titles
|
||||
.iter()
|
||||
.map(|title| {
|
||||
stdout
|
||||
.find(title)
|
||||
.unwrap_or_else(|| panic!("{title} missing from {stdout}"))
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Committed and reviewing are queues, and the head is what has waited longest: that is
|
||||
/// what the reader picks next from. Priority no longer decides it, which is why the
|
||||
/// oldest here is the least urgent of the three.
|
||||
#[test]
|
||||
fn ls_orders_committed_and_reviewing_by_the_oldest_entry_stamp() {
|
||||
for status in ["committed", "reviewing"] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("aaaa000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Newest",
|
||||
&at(1),
|
||||
"1",
|
||||
Some("2026-08-03 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Oldest",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Middle",
|
||||
&at(3),
|
||||
"1",
|
||||
Some("2026-08-02 09:00:00"),
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", status]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Oldest", "Middle", "Newest"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{status}: {stdout}");
|
||||
|
||||
// The overview lists the same columns, so it has to agree with the narrowed
|
||||
// listing rather than falling back to priority for the same tickets.
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).arg("ls");
|
||||
let overview = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&overview, ["Oldest", "Middle", "Newest"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{status} overview: {overview}");
|
||||
}
|
||||
}
|
||||
|
||||
/// Done reads like a changelog: what just landed is at the top. The p1 that finished
|
||||
/// first is at the bottom, which is the whole point of the column not being priority.
|
||||
#[test]
|
||||
fn ls_orders_done_by_the_newest_entry_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("bbbb000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(&worklane, "done", "First", &at(1), "1", Some("2026-08-01 09:00:00"));
|
||||
create_stamped_ticket(&worklane, "done", "Last", &at(2), "5", Some("2026-08-03 09:00:00"));
|
||||
create_stamped_ticket(&worklane, "done", "Middle", &at(3), "1", Some("2026-08-02 09:00:00"));
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "done"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Last", "Middle", "First"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
/// A missing stamp is unknown, not ancient, so it sinks below every stamped ticket
|
||||
/// rather than claiming the head of the queue. Every ticket on a board older than the
|
||||
/// stamps is one of these.
|
||||
#[test]
|
||||
fn ls_sinks_an_unstamped_ticket_below_the_stamped_ones() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("cccc000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(&worklane, "committed", "Unstamped", &at(1), "1", None);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"committed",
|
||||
"Waited",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"committed",
|
||||
"Fresh",
|
||||
&at(3),
|
||||
"5",
|
||||
Some("2026-08-09 09:00:00"),
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "committed"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Waited", "Fresh", "Unstamped"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
/// The two listings are one order. A completion offering candidates in a different
|
||||
/// order than the board prints them would make the head of a column mean two things.
|
||||
#[test]
|
||||
fn ls_ids_prints_the_same_order_the_listing_does() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("dddd000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"reviewing",
|
||||
"Newest",
|
||||
&at(1),
|
||||
"1",
|
||||
Some("2026-08-03 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"reviewing",
|
||||
"Oldest",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(&worklane, "reviewing", "Unstamped", &at(3), "1", None);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "reviewing", "--ids"]);
|
||||
let ids = get_stdout(&mut cmd);
|
||||
|
||||
let titles: Vec<&str> = ids.lines().filter_map(|line| line.split('\t').nth(1)).collect();
|
||||
assert_eq!(titles, ["Oldest", "Newest", "Unstamped"], "{ids:?}");
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "reviewing"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Oldest", "Newest", "Unstamped"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
+278
-12
@@ -277,13 +277,16 @@ fn mv_ignores_already_in_same_status() {
|
||||
assert!(worklane.join("reviewing").join(&filename).exists());
|
||||
}
|
||||
|
||||
/// A status is a value enum, so an unknown one is clap's to refuse: exit 2, the four
|
||||
/// named, and the ticket untouched. The same bargain `--due` and `--priority` take, and
|
||||
/// the reason `cmd_mv` no longer checks.
|
||||
#[test]
|
||||
fn mv_rejects_invalid_status() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let id = "abc123def456789012345678901234567890";
|
||||
let _filename = create_ticket(
|
||||
let filename = create_ticket(
|
||||
&worklane,
|
||||
"backlog",
|
||||
"Invalid Target",
|
||||
@@ -301,10 +304,17 @@ fn mv_rejects_invalid_status() {
|
||||
.arg("--status")
|
||||
.arg("invalid")
|
||||
.assert()
|
||||
.failure();
|
||||
.code(2);
|
||||
|
||||
let stderr = get_stderr(&mut cmd);
|
||||
assert!(stderr.contains("Invalid target status"));
|
||||
assert!(stderr.contains("invalid value 'invalid'"), "{stderr}");
|
||||
for status in ["backlog", "committed", "reviewing", "done"] {
|
||||
assert!(stderr.contains(status), "{status} is not offered: {stderr}");
|
||||
}
|
||||
assert!(
|
||||
worklane.join("backlog").join(&filename).exists(),
|
||||
"the ticket moved anyway"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -463,7 +473,9 @@ fn stray_files(worklane: &std::path::Path) -> Vec<String> {
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| !["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str()))
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
})
|
||||
.collect();
|
||||
|
||||
for dir in ["backlog", "committed", "reviewing", "done"] {
|
||||
@@ -512,10 +524,7 @@ fn mv_never_leaves_stale_content_in_the_target_directory() {
|
||||
let moved = worklane.join("committed").join(&filename);
|
||||
assert!(moved.exists(), "ticket did not move");
|
||||
let content = fs::read_to_string(&moved).unwrap();
|
||||
assert!(
|
||||
content.contains("- **Status**: committed"),
|
||||
"stale status: {content:?}"
|
||||
);
|
||||
assert!(content.contains("- **Status**: committed"), "stale status: {content:?}");
|
||||
assert!(!content.contains("- **Status**: backlog"), "{content:?}");
|
||||
|
||||
assert_eq!(md_files(&worklane.join("backlog")).len(), 0);
|
||||
@@ -621,10 +630,7 @@ fn mv_moves_the_resolved_ticket_when_two_share_a_title() {
|
||||
] {
|
||||
fs::write(
|
||||
worklane.join("backlog").join(format!("{}_foo.md", uuid)),
|
||||
format!(
|
||||
"# Foo\n\n## Metadata\n\n- **ID**: {}\n- **Status**: backlog\n",
|
||||
uuid
|
||||
),
|
||||
format!("# Foo\n\n## Metadata\n\n- **ID**: {}\n- **Status**: backlog\n", uuid),
|
||||
)
|
||||
.unwrap();
|
||||
}
|
||||
@@ -878,3 +884,263 @@ fn mv_ignores_the_kinds_that_are_not_blockers() {
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(worklane.join("committed").join(&filename).exists());
|
||||
}
|
||||
|
||||
/// The value of a metadata field, or nothing when the ticket does not carry it.
|
||||
fn field(content: &str, name: &str) -> Option<String> {
|
||||
let prefix = format!("- **{}**: ", name);
|
||||
content
|
||||
.lines()
|
||||
.find_map(|line| line.strip_prefix(prefix.as_str()))
|
||||
.map(str::to_string)
|
||||
}
|
||||
|
||||
/// `%Y-%m-%d %H:%M:%S`, checked by shape. A test cannot pin the clock, so what it can
|
||||
/// assert is that the stamp carries the same format `Created At` does.
|
||||
fn is_timestamp(value: &str) -> bool {
|
||||
value.len() == 19
|
||||
&& value.chars().enumerate().all(|(index, c)| match index {
|
||||
4 | 7 => c == '-',
|
||||
10 => c == ' ',
|
||||
13 | 16 => c == ':',
|
||||
_ => c.is_ascii_digit(),
|
||||
})
|
||||
}
|
||||
|
||||
fn stamped_ticket(worklane: &Path, status: &str) -> String {
|
||||
create_ticket(
|
||||
worklane,
|
||||
status,
|
||||
"Stamped Task",
|
||||
"Carries the stamps.",
|
||||
"cccc3333cccc3333cccc3333cccc3333cccc",
|
||||
"alice",
|
||||
"_Not set_",
|
||||
"test",
|
||||
)
|
||||
}
|
||||
|
||||
fn ticket_at(worklane: &Path, status: &str, filename: &str) -> String {
|
||||
fs::read_to_string(worklane.join(status).join(filename)).unwrap()
|
||||
}
|
||||
|
||||
/// One field per status, written with the time of the move and added to the ones
|
||||
/// already there: walking the flow leaves the whole journey on the ticket.
|
||||
#[test]
|
||||
fn mv_stamps_the_field_of_the_status_it_enters() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
// The fixture predates Created At as well as the stamps, and the four reading as
|
||||
// one block is the point, so it is seeded rather than asserted around.
|
||||
let path = worklane.join("backlog").join(&filename);
|
||||
let seeded = fs::read_to_string(&path)
|
||||
.unwrap()
|
||||
.replace("- **Status**:", "- **Created At**: 2026-08-01 09:00:00\n- **Status**:");
|
||||
fs::write(&path, seeded).unwrap();
|
||||
|
||||
let mut carried: Vec<&str> = Vec::new();
|
||||
|
||||
for (status, stamp) in [
|
||||
("committed", "Committed On"),
|
||||
("reviewing", "Submitted On"),
|
||||
("done", "Completed On"),
|
||||
] {
|
||||
let out = move_ticket(&temp, "cccc3333", status, false);
|
||||
assert!(out.status.success(), "{:?}", out);
|
||||
carried.push(stamp);
|
||||
|
||||
let content = ticket_at(&worklane, status, &filename);
|
||||
|
||||
for stamp in &carried {
|
||||
let value = field(&content, stamp)
|
||||
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
|
||||
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
|
||||
}
|
||||
}
|
||||
|
||||
// The four side by side and in flow order, which is what a reader asking when this
|
||||
// was filed, picked up, handed over and finished gets one answer each from.
|
||||
let content = ticket_at(&worklane, "done", &filename);
|
||||
let block: Vec<&str> = content
|
||||
.lines()
|
||||
.filter_map(|line| line.strip_prefix("- **"))
|
||||
.filter_map(|line| line.split("**:").next())
|
||||
.skip_while(|name| *name != "Created At")
|
||||
.collect();
|
||||
|
||||
assert_eq!(
|
||||
block,
|
||||
[
|
||||
"Created At",
|
||||
"Committed On",
|
||||
"Submitted On",
|
||||
"Completed On",
|
||||
"Status"
|
||||
],
|
||||
"{content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Arrival clears what comes after it and nothing before, so a ticket sent back out of
|
||||
/// done keeps the stages it did get through.
|
||||
#[test]
|
||||
fn mv_removes_the_stamps_of_the_statuses_after_the_one_it_enters() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
for status in ["committed", "reviewing", "done"] {
|
||||
move_ticket(&temp, "cccc3333", status, false);
|
||||
}
|
||||
|
||||
move_ticket(&temp, "cccc3333", "reviewing", true);
|
||||
|
||||
let content = ticket_at(&worklane, "reviewing", &filename);
|
||||
assert_eq!(field(&content, "Completed On"), None, "{content}");
|
||||
assert!(field(&content, "Committed On").is_some(), "{content}");
|
||||
assert!(field(&content, "Submitted On").is_some(), "{content}");
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own and every status follows it, so a ticket forced back
|
||||
/// to it carries none at all rather than a Completed On for work that has been undone.
|
||||
#[test]
|
||||
fn mv_back_to_backlog_removes_all_three_stamps() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
move_ticket(&temp, "cccc3333", "done", true);
|
||||
let done = ticket_at(&worklane, "done", &filename);
|
||||
assert!(field(&done, "Completed On").is_some(), "{done}");
|
||||
|
||||
move_ticket(&temp, "cccc3333", "backlog", true);
|
||||
|
||||
let content = ticket_at(&worklane, "backlog", &filename);
|
||||
for stamp in ["Committed On", "Submitted On", "Completed On"] {
|
||||
assert_eq!(field(&content, stamp), None, "{content}");
|
||||
}
|
||||
}
|
||||
|
||||
/// A skip stamps where it lands and leaves the stages it jumped unwritten: an absent
|
||||
/// field says the ticket never got that far, and inventing one would say it did.
|
||||
#[test]
|
||||
fn mv_skipping_forward_stamps_only_the_target() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
move_ticket(&temp, "cccc3333", "done", true);
|
||||
|
||||
let content = ticket_at(&worklane, "done", &filename);
|
||||
assert!(field(&content, "Completed On").is_some(), "{content}");
|
||||
assert_eq!(field(&content, "Committed On"), None, "{content}");
|
||||
assert_eq!(field(&content, "Submitted On"), None, "{content}");
|
||||
}
|
||||
|
||||
/// The three are `mv`'s alone. Nothing that edits a ticket by hand offers a way to
|
||||
/// write one or take one away, so a stamp is always the record of a real move. Pinned
|
||||
/// so the omission stays a decision rather than becoming an oversight somebody fills in.
|
||||
#[test]
|
||||
fn no_other_command_can_write_or_clear_a_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
for command in ["add", "set", "append", "chown"] {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args([command, "--help"]);
|
||||
let out = cmd.assert().get_output().clone();
|
||||
let help = String::from_utf8_lossy(&out.stdout).to_lowercase();
|
||||
|
||||
for flag in ["committed-on", "submitted-on", "completed-on", "stamp"] {
|
||||
assert!(!help.contains(flag), "{command} --help names {flag}: {help}");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Re-entry is the time of the move that brought the ticket back, not the first one.
|
||||
#[test]
|
||||
fn mv_restamps_a_status_the_ticket_is_re_entering() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "committed");
|
||||
|
||||
// Hand-written so the earlier value is old enough to tell from the move's own time,
|
||||
// which two moves in the same second would not be.
|
||||
let path = worklane.join("committed").join(&filename);
|
||||
let seeded = fs::read_to_string(&path)
|
||||
.unwrap()
|
||||
.replace("- **Status**:", "- **Committed On**: 2020-01-01 00:00:00\n- **Status**:");
|
||||
fs::write(&path, seeded).unwrap();
|
||||
|
||||
move_ticket(&temp, "cccc3333", "backlog", true);
|
||||
move_ticket(&temp, "cccc3333", "committed", false);
|
||||
|
||||
let content = ticket_at(&worklane, "committed", &filename);
|
||||
let value = field(&content, "Committed On").expect(&content);
|
||||
|
||||
assert!(is_timestamp(&value), "{value}");
|
||||
assert_ne!(value, "2020-01-01 00:00:00");
|
||||
assert_eq!(content.matches("**Committed On**:").count(), 1, "{content}");
|
||||
}
|
||||
|
||||
/// The fixture predates the fields, as every ticket on a real board does, so the line
|
||||
/// is inserted rather than rewritten. Against METADATA_ORDER, which keeps Status last.
|
||||
#[test]
|
||||
fn mv_inserts_the_stamp_before_the_status_field() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
move_ticket(&temp, "cccc3333", "committed", false);
|
||||
|
||||
let content = ticket_at(&worklane, "committed", &filename);
|
||||
let value = field(&content, "Committed On").expect(&content);
|
||||
|
||||
assert!(
|
||||
content.contains(&format!(
|
||||
"- **Owner**: alice\n- **Committed On**: {}\n- **Status**: committed\n",
|
||||
value
|
||||
)),
|
||||
"{content}"
|
||||
);
|
||||
assert!(content.ends_with("- **Status**: committed\n"), "{content}");
|
||||
}
|
||||
|
||||
/// Behind the refusals, all of them: a move that does not happen leaves the file exactly
|
||||
/// as it was, stamp included.
|
||||
#[test]
|
||||
fn mv_writes_no_stamp_when_the_move_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let backward = stamped_ticket(&worklane, "committed");
|
||||
let before = ticket_at(&worklane, "committed", &backward);
|
||||
|
||||
let out = move_ticket(&temp, "cccc3333", "backlog", false);
|
||||
assert!(!out.status.success());
|
||||
assert_eq!(ticket_at(&worklane, "committed", &backward), before);
|
||||
|
||||
// The blocked ticket takes the other refusal, which sits after the no-op return.
|
||||
let blocked = create_gated_pair(&worklane, &temp, "backlog");
|
||||
let before = ticket_at(&worklane, "backlog", &blocked);
|
||||
|
||||
let out = move_ticket(&temp, "aaaa1111", "committed", false);
|
||||
assert!(!out.status.success());
|
||||
assert_eq!(ticket_at(&worklane, "backlog", &blocked), before);
|
||||
}
|
||||
|
||||
/// A move to the status the ticket is already in returns before anything is written, so
|
||||
/// it does not restamp either.
|
||||
#[test]
|
||||
fn mv_does_not_restamp_a_no_op_move() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "committed");
|
||||
let before = ticket_at(&worklane, "committed", &filename);
|
||||
|
||||
let out = move_ticket(&temp, "cccc3333", "committed", false);
|
||||
assert!(out.status.success());
|
||||
|
||||
assert_eq!(ticket_at(&worklane, "committed", &filename), before);
|
||||
}
|
||||
|
||||
+9
-17
@@ -118,11 +118,7 @@ fn a_target_resolves_by_uuid_prefix_title_or_filename() {
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(&temp, &["relate", GATED, "--blocked-by", search]);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"{search}: {}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
assert!(out.status.success(), "{search}: {}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(
|
||||
ticket(&worklane, GATED).contains(&format!("- blocked by {}", BLOCKER)),
|
||||
"{search}: {}",
|
||||
@@ -249,11 +245,7 @@ fn a_relation_already_held_reports_no_change_and_writes_nothing() {
|
||||
let out = run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
|
||||
assert!(out.status.success());
|
||||
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
|
||||
assert_eq!(
|
||||
ticket(&worklane, GATED),
|
||||
before,
|
||||
"the relation was recorded twice"
|
||||
);
|
||||
assert_eq!(ticket(&worklane, GATED), before, "the relation was recorded twice");
|
||||
}
|
||||
|
||||
/// One direction is stored. The inverse is derived by a scan, so the ticket at the
|
||||
@@ -354,7 +346,9 @@ fn show_lists_the_relation_the_other_ticket_holds() {
|
||||
// `relates to` is symmetric, so it reads the same way from either end.
|
||||
let shown = stdout(&run(&temp, &["show", FIXED]));
|
||||
assert!(
|
||||
shown.contains(&format!("relates to {RELATES_MARK} {BACKLOG_MARK} (641e3d5) The gated one")),
|
||||
shown.contains(&format!(
|
||||
"relates to {RELATES_MARK} {BACKLOG_MARK} (641e3d5) The gated one"
|
||||
)),
|
||||
"{shown}"
|
||||
);
|
||||
}
|
||||
@@ -382,12 +376,10 @@ fn a_line_that_is_not_a_relation_is_an_error() {
|
||||
let worklane = board(&temp);
|
||||
|
||||
let path = find(&worklane, GATED);
|
||||
let content = fs::read_to_string(&path)
|
||||
.unwrap()
|
||||
.replace(
|
||||
"## Metadata",
|
||||
&format!("## Relations\n- depends on {}\n\n## Metadata", BLOCKER),
|
||||
);
|
||||
let content = fs::read_to_string(&path).unwrap().replace(
|
||||
"## Metadata",
|
||||
&format!("## Relations\n- depends on {}\n\n## Metadata", BLOCKER),
|
||||
);
|
||||
fs::write(&path, content).unwrap();
|
||||
|
||||
let out = run(&temp, &["show", GATED]);
|
||||
|
||||
+318
-37
@@ -94,13 +94,20 @@ fn set_replaces_each_field_it_is_given() {
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"set", UUID,
|
||||
"--description", "Only paragraph.",
|
||||
"--acceptance", "New crit",
|
||||
"--plan", "New step",
|
||||
"--tags", "beta,gamma",
|
||||
"--due", "2026-12-31",
|
||||
"--priority", "1",
|
||||
"set",
|
||||
UUID,
|
||||
"--description",
|
||||
"Only paragraph.",
|
||||
"--acceptance",
|
||||
"New crit",
|
||||
"--plan",
|
||||
"New step",
|
||||
"--tags",
|
||||
"beta,gamma",
|
||||
"--due",
|
||||
"2026-12-31",
|
||||
"--priority",
|
||||
"1",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
@@ -190,7 +197,11 @@ fn set_reports_only_the_fields_that_changed() {
|
||||
assert!(!stdout.contains("due"), "{stdout:?}");
|
||||
}
|
||||
|
||||
/// An empty scalar looks like a way to clear a field, and clearing is not supported.
|
||||
/// An empty scalar is still a usage error, and the message now points at the flag that
|
||||
/// does clear a field, so the two do not contradict each other.
|
||||
///
|
||||
/// `--title` is the exception, and says only that the value cannot be empty: a title has
|
||||
/// no unset state to return to, so there is nothing to point at.
|
||||
#[test]
|
||||
fn set_refuses_an_empty_scalar_as_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
@@ -198,12 +209,244 @@ fn set_refuses_an_empty_scalar_as_a_usage_error() {
|
||||
create_ticket(&worklane);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
for flag in ["--title", "--due", "--tags"] {
|
||||
for (flag, expected) in [
|
||||
("--title", "value cannot be empty"),
|
||||
("--due", "use --clear"),
|
||||
("--tags", "use --clear"),
|
||||
] {
|
||||
let out = run(&temp, &["set", UUID, flag, ""]);
|
||||
assert_eq!(out.status.code(), Some(2), "{flag} was accepted");
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains(expected), "{flag}: {stderr:?}");
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stderr).contains("clearing a field is not supported"),
|
||||
"{flag}: {:?}",
|
||||
!stderr.contains("not supported"),
|
||||
"{flag} still says clearing is unsupported: {stderr:?}"
|
||||
);
|
||||
}
|
||||
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
}
|
||||
|
||||
/// An empty value is a paragraph break for a section, so it cannot also mean empty the
|
||||
/// section. The error names the flag that does, per section.
|
||||
#[test]
|
||||
fn set_refuses_an_empty_section_and_names_the_clear_for_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
for (flag, expected) in [
|
||||
("--description", "--clear description"),
|
||||
("--acceptance", "--clear acceptance"),
|
||||
("--plan", "--clear plan"),
|
||||
] {
|
||||
let out = run(&temp, &["set", UUID, flag, ""]);
|
||||
assert_eq!(out.status.code(), Some(1), "{flag} was accepted");
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains(expected), "{flag}: {stderr:?}");
|
||||
}
|
||||
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
}
|
||||
|
||||
/// Every field `--clear` reaches, in one call, back to what a ticket is born with.
|
||||
#[test]
|
||||
fn clear_returns_every_field_it_reaches_to_unset() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"set",
|
||||
UUID,
|
||||
"--clear",
|
||||
"due",
|
||||
"--clear",
|
||||
"tags",
|
||||
"--clear",
|
||||
"priority",
|
||||
"--clear",
|
||||
"description",
|
||||
"--clear",
|
||||
"acceptance",
|
||||
"--clear",
|
||||
"plan",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
let content = ticket(&worklane);
|
||||
assert!(content.contains("- **Due**: _Not set_"), "{content}");
|
||||
assert!(content.contains("- **Tags**: _None_"), "{content}");
|
||||
assert!(content.contains("- **Priority**: _Not set_"), "{content}");
|
||||
assert!(
|
||||
content.contains("## Description\n_No description provided._\n"),
|
||||
"{content}"
|
||||
);
|
||||
assert!(
|
||||
content.contains("## Acceptance Criteria\n_No acceptance criteria provided._\n"),
|
||||
"{content}"
|
||||
);
|
||||
assert!(
|
||||
content.contains("## Implementation Plan\n_No implementation plan provided._\n"),
|
||||
"{content}"
|
||||
);
|
||||
|
||||
// The placeholder goes in bare, not dressed as an item of the section it replaces.
|
||||
assert!(!content.contains("- [ ] _No"), "{content}");
|
||||
assert!(!content.contains("1. _No"), "{content}");
|
||||
|
||||
// What --clear cannot reach is untouched, the handwritten section included.
|
||||
assert!(content.starts_with("# Original title\n"), "{content}");
|
||||
assert!(content.contains("- **Owner**: alice"), "{content}");
|
||||
assert!(content.contains("- **Status**: backlog"), "{content}");
|
||||
assert!(
|
||||
content.contains("## Notes\nA handwritten note the tool knows nothing about.\n"),
|
||||
"{content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// A cleared ticket and one that was never given the field have to read the same, or
|
||||
/// clearing would be its own third state.
|
||||
#[test]
|
||||
fn a_cleared_ticket_reads_like_one_filed_without_the_fields() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["add", "--title", "Bare"]);
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"add",
|
||||
"--title",
|
||||
"Full",
|
||||
"--description",
|
||||
"A body.",
|
||||
"--acceptance",
|
||||
"One criterion",
|
||||
"--plan",
|
||||
"One step",
|
||||
"--tags",
|
||||
"alpha,beta",
|
||||
"--due",
|
||||
"2026-09-01",
|
||||
"--priority",
|
||||
"2",
|
||||
],
|
||||
);
|
||||
|
||||
let full = added(&worklane, "full");
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"set",
|
||||
&full.0,
|
||||
"--clear",
|
||||
"due",
|
||||
"--clear",
|
||||
"tags",
|
||||
"--clear",
|
||||
"priority",
|
||||
"--clear",
|
||||
"description",
|
||||
"--clear",
|
||||
"acceptance",
|
||||
"--clear",
|
||||
"plan",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
let cleared = comparable(&fs::read_to_string(&full.1).unwrap());
|
||||
let bare = comparable(&fs::read_to_string(&added(&worklane, "bare").1).unwrap());
|
||||
assert_eq!(cleared, bare);
|
||||
}
|
||||
|
||||
/// The uuid and the file of the one ticket whose slug matches, as `add` wrote it.
|
||||
fn added(worklane: &Path, slug: &str) -> (String, PathBuf) {
|
||||
let entry = fs::read_dir(worklane.join("backlog"))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.find(|e| e.file_name().to_string_lossy().ends_with(&format!("_{slug}.md")))
|
||||
.unwrap_or_else(|| panic!("no ticket slugged {slug}"));
|
||||
let name = entry.file_name().into_string().unwrap();
|
||||
let uuid = name.split('_').next().unwrap().to_string();
|
||||
(uuid, entry.path())
|
||||
}
|
||||
|
||||
/// A ticket without the three lines that are different by definition: its title, its
|
||||
/// uuid and the moment it was filed.
|
||||
fn comparable(content: &str) -> String {
|
||||
content
|
||||
.lines()
|
||||
.filter(|line| {
|
||||
!line.starts_with("# ")
|
||||
&& !line.contains("**ID**:")
|
||||
&& !line.contains("**Created At**:")
|
||||
})
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n")
|
||||
}
|
||||
|
||||
/// Nothing to take away is not a rewrite, per the same whole-file comparison a
|
||||
/// replacement uses.
|
||||
#[test]
|
||||
fn clearing_a_field_that_is_already_unset_is_no_change() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
run(&temp, &["set", UUID, "--clear", "due", "--clear", "tags"]);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["set", UUID, "--clear", "due", "--clear", "tags"]);
|
||||
assert!(out.status.success());
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stdout).contains("No changes"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stdout)
|
||||
);
|
||||
assert_eq!(ticket(&worklane), before, "the file was rewritten anyway");
|
||||
}
|
||||
|
||||
/// Replaced and emptied are reported in those words, since a caller doing both in one
|
||||
/// call cannot tell which happened to which field otherwise.
|
||||
#[test]
|
||||
fn clear_is_reported_apart_from_a_replacement() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["set", UUID, "--priority", "1", "--clear", "due"]);
|
||||
assert!(out.status.success());
|
||||
let stdout = String::from_utf8_lossy(&out.stdout);
|
||||
assert!(stdout.contains("Updated priority on 'Original title'"), "{stdout:?}");
|
||||
assert!(stdout.contains("Cleared due on 'Original title'"), "{stdout:?}");
|
||||
}
|
||||
|
||||
/// Replacing and clearing one field in a single call is a contradiction, and answering
|
||||
/// it by whichever was applied last would be a silent answer.
|
||||
#[test]
|
||||
fn clearing_and_replacing_the_same_field_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
for (flag, value, field) in [
|
||||
("--due", "2026-12-31", "due"),
|
||||
("--tags", "beta", "tags"),
|
||||
("--priority", "1", "priority"),
|
||||
("--acceptance", "A criterion", "acceptance"),
|
||||
] {
|
||||
let out = run(&temp, &["set", UUID, flag, value, "--clear", field]);
|
||||
assert_eq!(out.status.code(), Some(1), "{flag} with --clear {field} was accepted");
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stderr).contains("contradict each other"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
}
|
||||
@@ -211,25 +454,45 @@ fn set_refuses_an_empty_scalar_as_a_usage_error() {
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
}
|
||||
|
||||
/// An empty value is a paragraph break for a section, so an all-blank one is a
|
||||
/// clearing attempt rather than a break.
|
||||
/// The fields no writer of `set` can reach are not reachable through `--clear` either,
|
||||
/// and an unknown one is a usage error listing what is.
|
||||
#[test]
|
||||
fn set_refuses_to_clear_a_section() {
|
||||
fn clear_refuses_a_field_it_does_not_own() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["set", UUID, "--description", ""]);
|
||||
assert_eq!(out.status.code(), Some(1));
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stderr).contains("clearing is not supported"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
for field in [
|
||||
"owner",
|
||||
"title",
|
||||
"status",
|
||||
"campaign",
|
||||
"relations",
|
||||
"nonsense",
|
||||
] {
|
||||
let out = run(&temp, &["set", UUID, "--clear", field]);
|
||||
assert_eq!(out.status.code(), Some(2), "--clear {field} was accepted");
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains("possible values"), "{field}: {stderr:?}");
|
||||
}
|
||||
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
}
|
||||
|
||||
/// `--clear` on its own satisfies the at-least-one-field rule, since it is a field
|
||||
/// being written like any other.
|
||||
#[test]
|
||||
fn clear_alone_is_enough_of_a_field() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["set", UUID, "--clear", "due"]);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(ticket(&worklane).contains("- **Due**: _Not set_"));
|
||||
}
|
||||
|
||||
/// A bare `set <ticket>` would otherwise be a silent no-op.
|
||||
#[test]
|
||||
fn set_requires_at_least_one_field() {
|
||||
@@ -248,10 +511,7 @@ fn set_keeps_a_paragraph_break_in_a_replaced_description() {
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&["set", UUID, "-d", "One.", "-d", "", "-d", "Two."],
|
||||
);
|
||||
run(&temp, &["set", UUID, "-d", "One.", "-d", "", "-d", "Two."]);
|
||||
|
||||
assert!(
|
||||
ticket(&worklane).contains("## Description\nOne.\n\nTwo.\n\n## Acceptance"),
|
||||
@@ -268,7 +528,14 @@ fn set_accepts_prose_that_begins_with_a_hyphen() {
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&["set", UUID, "-a", "--print should be supported", "-t", "-t is the title flag"],
|
||||
&[
|
||||
"set",
|
||||
UUID,
|
||||
"-a",
|
||||
"--print should be supported",
|
||||
"-t",
|
||||
"-t is the title flag",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
@@ -296,11 +563,16 @@ fn append_adds_a_paragraph_items_and_numbered_steps() {
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"append", UUID,
|
||||
"-d", "A third paragraph.",
|
||||
"-a", "Crit three",
|
||||
"-a", "Crit four",
|
||||
"-p", "Step three",
|
||||
"append",
|
||||
UUID,
|
||||
"-d",
|
||||
"A third paragraph.",
|
||||
"-a",
|
||||
"Crit three",
|
||||
"-a",
|
||||
"Crit four",
|
||||
"-p",
|
||||
"Step three",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
@@ -315,10 +587,7 @@ fn append_adds_a_paragraph_items_and_numbered_steps() {
|
||||
"{content}"
|
||||
);
|
||||
// Numbered on from the last step, and the steps above are untouched
|
||||
assert!(
|
||||
content.contains("1. Step one\n2. Step two\n3. Step three\n"),
|
||||
"{content}"
|
||||
);
|
||||
assert!(content.contains("1. Step one\n2. Step two\n3. Step three\n"), "{content}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -342,14 +611,26 @@ fn append_replaces_an_empty_section_rather_than_following_its_placeholder() {
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&["append", &uuid, "-d", "A description arrives late.", "-a", "First crit", "-p", "First step"],
|
||||
&[
|
||||
"append",
|
||||
&uuid,
|
||||
"-d",
|
||||
"A description arrives late.",
|
||||
"-a",
|
||||
"First crit",
|
||||
"-p",
|
||||
"First step",
|
||||
],
|
||||
);
|
||||
|
||||
let content = ticket(&worklane);
|
||||
assert!(!content.contains("_No description provided._"), "{content}");
|
||||
assert!(!content.contains("_No acceptance criteria provided._"), "{content}");
|
||||
assert!(!content.contains("_No implementation plan provided._"), "{content}");
|
||||
assert!(content.contains("## Description\nA description arrives late.\n"), "{content}");
|
||||
assert!(
|
||||
content.contains("## Description\nA description arrives late.\n"),
|
||||
"{content}"
|
||||
);
|
||||
assert!(content.contains("## Implementation Plan\n1. First step\n"), "{content}");
|
||||
}
|
||||
|
||||
|
||||
+38
-6
@@ -350,7 +350,10 @@ fn show_disambiguates_tickets_with_non_ascii_filenames() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
for (filename, title) in [("émigré-un.md", "Accented One"), ("日本語-二.md", "Accented Two")] {
|
||||
for (filename, title) in [
|
||||
("émigré-un.md", "Accented One"),
|
||||
("日本語-二.md", "Accented Two"),
|
||||
] {
|
||||
fs::write(
|
||||
worklane.join("backlog").join(filename),
|
||||
format!("# {}\n\n## Metadata\n\n- **ID**: 1234\n", title),
|
||||
@@ -444,11 +447,7 @@ fn show_prints_the_title_once() {
|
||||
cmd.current_dir(temp.path()).arg("show").arg("Once Only");
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
assert_eq!(
|
||||
stdout.matches("Once Only").count(),
|
||||
1,
|
||||
"title repeated in {stdout:?}"
|
||||
);
|
||||
assert_eq!(stdout.matches("Once Only").count(), 1, "title repeated in {stdout:?}");
|
||||
// The rule under it is still the width of the title
|
||||
assert!(stdout.contains("Once Only\n─────────\n"), "{stdout:?}");
|
||||
}
|
||||
@@ -489,6 +488,39 @@ fn show_renders_the_metadata_as_an_aligned_table() {
|
||||
assert!(content.contains("- **Owner**: alice"));
|
||||
}
|
||||
|
||||
/// The stamps `mv` writes are fields like any other: the table renders what the file
|
||||
/// holds, so nothing here knows their names, and the column widens to the longest of
|
||||
/// them the way it does for anything else.
|
||||
#[test]
|
||||
fn show_renders_a_status_stamp_in_the_metadata_table() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let filename = "abc123def456789012345678901234567890_stamped.md";
|
||||
fs::write(
|
||||
worklane.join("committed").join(filename),
|
||||
"# Stamped Ticket\n\n## Metadata\n\n\
|
||||
- **ID**: abc123def456789012345678901234567890\n\
|
||||
- **Created At**: 2026-08-20 15:51:01\n\
|
||||
- **Committed On**: 2026-08-22 09:14:30\n\
|
||||
- **Status**: committed\n",
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).arg("show").arg("Stamped");
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
assert!(
|
||||
stdout.contains(
|
||||
"Created At 2026-08-20 15:51:01\n\
|
||||
Committed On 2026-08-22 09:14:30\n\
|
||||
Status committed\n"
|
||||
),
|
||||
"{stdout:?}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Write a ticket with an exact uuid and title, since both matter to resolution.
|
||||
fn ticket_with(worklane: &std::path::Path, status: &str, uuid: &str, title: &str, slug: &str) {
|
||||
fs::write(
|
||||
|
||||
@@ -0,0 +1,413 @@
|
||||
//! `worklane tags`, the tag vocabulary.
|
||||
//!
|
||||
//! The command exists because `--tag` answers what carries a tag and cannot answer what
|
||||
//! 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 listing reports the vocabulary
|
||||
//! the tickets *carry*; the file reports the one the board *intends*, and the tests below
|
||||
//! are mostly about the two being allowed to disagree without either one damaging the
|
||||
//! other.
|
||||
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
use assert_fs::fixture::{PathChild, PathCreateDir};
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
|
||||
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 carrying `tags` verbatim, so a test can write the field the way a hand-made
|
||||
/// ticket would: spaced, unspaced, unset or absent.
|
||||
fn create_ticket(worklane: &Path, status: &str, uuid: &str, tags: &str) {
|
||||
let path = worklane.join(status).join(format!("{uuid}_ticket.md"));
|
||||
fs::write(
|
||||
&path,
|
||||
format!(
|
||||
"# Ticket {uuid}\n\
|
||||
\n\
|
||||
## Description\n\
|
||||
Prose that says **Tags**: not-a-field, in the body.\n\
|
||||
\n\
|
||||
## Metadata\n\
|
||||
\n\
|
||||
- **ID**: {uuid}\n\
|
||||
- **Priority**: 3\n\
|
||||
- **Tags**: {tags}\n\
|
||||
- **Owner**: alice\n\
|
||||
- **Created At**: 2026-08-21 02:10:17\n\
|
||||
- **Status**: {status}\n"
|
||||
),
|
||||
)
|
||||
.unwrap();
|
||||
}
|
||||
|
||||
fn run(temp: &TempDir, args: &[&str]) -> std::process::Output {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(args);
|
||||
cmd.assert().get_output().clone()
|
||||
}
|
||||
|
||||
fn tags(temp: &TempDir) -> Vec<String> {
|
||||
let out = run(temp, &["tags"]);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
String::from_utf8_lossy(&out.stdout)
|
||||
.lines()
|
||||
.map(str::to_string)
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Every status, done included, and the count is tickets rather than mentions.
|
||||
#[test]
|
||||
fn tags_counts_every_tag_on_the_board() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
|
||||
create_ticket(&worklane, "committed", "22222222", "bug,tui");
|
||||
create_ticket(&worklane, "done", "33333333", "bug");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t3", "cli\t1", "tui\t1"]);
|
||||
}
|
||||
|
||||
/// Alphabetical, which is the property that makes a near-duplicate findable: the two
|
||||
/// spellings land next to each other.
|
||||
#[test]
|
||||
fn tags_are_alphabetical_so_near_duplicates_are_adjacent() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "backlog", "11111111", "tui,bug,bugfix,cli");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t1", "bugfix\t1", "cli\t1", "tui\t1"]);
|
||||
}
|
||||
|
||||
/// Case sensitive, like the `--tag` filter. Folding the two together here would hide the
|
||||
/// reason a filter came back short.
|
||||
#[test]
|
||||
fn tags_keeps_case_apart_the_way_the_filter_does() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
create_ticket(&worklane, "backlog", "22222222", "Bug");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["Bug\t1", "bug\t1"]);
|
||||
|
||||
// And the filter agrees with the listing, which is the point of keeping them apart.
|
||||
let filtered = String::from_utf8_lossy(&run(&temp, &["ls", "--tag", "bug", "--ids"]).stdout)
|
||||
.lines()
|
||||
.count();
|
||||
assert_eq!(filtered, 1);
|
||||
}
|
||||
|
||||
/// An unset field, an absent one and a field of separators are all no tags, the same
|
||||
/// three cases `parse_tags` folds together.
|
||||
#[test]
|
||||
fn tags_ignores_a_ticket_with_nothing_to_count() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "backlog", "11111111", "_None_");
|
||||
create_ticket(&worklane, "backlog", "22222222", " , ,");
|
||||
create_ticket(&worklane, "backlog", "33333333", "");
|
||||
// No Tags field at all, the way a hand-made ticket can be.
|
||||
fs::write(
|
||||
worklane.join("backlog").join("44444444_bare.md"),
|
||||
"# Bare\n\n## Metadata\n\n- **ID**: 44444444\n- **Status**: backlog\n",
|
||||
)
|
||||
.unwrap();
|
||||
create_ticket(&worklane, "backlog", "55555555", "real");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["real\t1"]);
|
||||
}
|
||||
|
||||
/// A board with no tags prints nothing rather than a sentence, since a completion reads
|
||||
/// this and a sentence would become a candidate.
|
||||
#[test]
|
||||
fn tags_says_nothing_on_a_board_with_no_tags() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["tags"]);
|
||||
assert!(out.status.success());
|
||||
assert_eq!(String::from_utf8_lossy(&out.stdout), "");
|
||||
}
|
||||
|
||||
/// Unstyled, like `ls --ids`: a shell reads this and an escape sequence would land in
|
||||
/// the candidate.
|
||||
#[test]
|
||||
fn tags_is_unstyled() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
|
||||
let listing = String::from_utf8_lossy(&run(&temp, &["tags"]).stdout).to_string();
|
||||
assert!(!listing.contains('\u{1b}'), "{listing:?}");
|
||||
}
|
||||
|
||||
/// The Tags line in a Description is prose, not a field, the same rule every other
|
||||
/// metadata read follows.
|
||||
#[test]
|
||||
fn tags_reads_only_the_metadata_section() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t1"]);
|
||||
}
|
||||
|
||||
/// A missing status directory is skipped rather than refused, as in `ls --ids`: the
|
||||
/// caller is usually a shell, and an error over the prompt is worse than fewer answers.
|
||||
#[test]
|
||||
fn tags_skips_a_missing_status_directory() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
fs::remove_dir_all(worklane.join("reviewing")).unwrap();
|
||||
|
||||
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 vocabulary does not touch the listing, which counts tickets. The two disagreeing is
|
||||
/// the normal state and the thing the file is for.
|
||||
#[test]
|
||||
fn a_declared_tag_is_not_a_carried_one() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
|
||||
run(&temp, &["tags", "add", "chore", "-a", "Housekeeping."]);
|
||||
|
||||
// `chore` is declared and carried by nothing, `bug` is carried and declared by nothing,
|
||||
// and the listing still answers only the second question. Reporting both is 9564ac9.
|
||||
assert_eq!(tags(&temp), vec!["bug\t1"]);
|
||||
}
|
||||
|
||||
/// 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\ncli\t1\n");
|
||||
}
|
||||
+3
-12
@@ -44,10 +44,7 @@ fn the_tui_outside_a_worklane_directory_gives_the_usual_message() {
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{args:?}");
|
||||
assert!(
|
||||
stderr.contains("No .worklane directory found"),
|
||||
"{args:?}: {stderr:?}"
|
||||
);
|
||||
assert!(stderr.contains("No .worklane directory found"), "{args:?}: {stderr:?}");
|
||||
}
|
||||
}
|
||||
|
||||
@@ -66,10 +63,7 @@ fn the_tui_without_a_terminal_says_so_and_names_an_alternative() {
|
||||
assert_eq!(out.status.code(), Some(1), "{args:?}");
|
||||
assert!(stderr.contains("needs a terminal"), "{args:?}: {stderr:?}");
|
||||
assert!(stderr.contains("worklane ls"), "{args:?}: {stderr:?}");
|
||||
assert!(
|
||||
!stderr.contains("os error"),
|
||||
"the raw mode error leaked: {stderr:?}"
|
||||
);
|
||||
assert!(!stderr.contains("os error"), "the raw mode error leaked: {stderr:?}");
|
||||
}
|
||||
}
|
||||
|
||||
@@ -105,10 +99,7 @@ fn several_path_arguments_are_accepted() {
|
||||
let first = setup_project(&temp, "first");
|
||||
let second = setup_project(&temp, "second");
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&["tui", first.to_str().unwrap(), second.to_str().unwrap()],
|
||||
);
|
||||
let out = run(&temp, &["tui", first.to_str().unwrap(), second.to_str().unwrap()]);
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{stderr:?}");
|
||||
|
||||
Reference in New Issue
Block a user