show printed the Metadata block as the markdown list the file stores, so with seven fields the values did not line up and the block read as file contents rather than as a summary. It now renders as two aligned columns: field names left, values right. The file is untouched, this is display only. content_trim_colored streamed one line at a time, so nothing ever saw the whole section. The Metadata lines are now taken as a block, since the field column cannot be sized until every name has been seen. Column width is measured on the raw names, in characters, and padding is applied before anything is styled. Measuring a coloured name counts its escape sequences towards its width, which tilts the table with colour on and not with it off. paint() is color_text() with the decision passed in, which is what lets a test render both ways in one process and compare. colorize_metadata is folded into the renderer, its only caller. A line in the section that is not a field is carried through rather than dropped, so a hand written note survives, and an unrecognised field still gets a row. Plain columns, no border characters: nothing to degrade on a font that lacks them, and the section rules already carry the only box drawing here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
80 lines
5.3 KiB
Markdown
80 lines
5.3 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Structure
|
|
- `src/main.rs` - All application logic
|
|
- `src/command.rs` - CLI argument definitions using clap derive
|
|
- `tests/` - Integration tests using `assert_cmd` and `assert_fs`
|
|
- Ticket files stored as `.md` in `.worklane/<status>/` directories
|
|
|
|
## Ticket File Format
|
|
- Filenames: `<uuid_v4>_<slug>.md`
|
|
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Status`
|
|
- Format: `**Field Name**: value`
|
|
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
|
|
- Comments stored in `.worklane/comments/<ticket_uuid>/<timestamp>.md` with `**Comment**`, `**Author**`, `**Time**` fields
|
|
|
|
## Status Workflow
|
|
`backlog` → `committed` → `reviewing` → `done`
|
|
|
|
## Testing
|
|
- Run: `cargo test`
|
|
- Tests use `assert_cmd` and `assert_fs` for CLI testing
|
|
- `setup_worklane()` creates temp `.worklane/` with all four status folders pre-created
|
|
- `create_ticket()` writes fully-formed markdown files directly (no `--` separator for positional args in test commands)
|
|
|
|
## Coding Guidelines
|
|
|
|
### Rust Style
|
|
- Use `if matches!(expr, Variant)` instead of `if let Some(Variant) = expr` for enum variant matching
|
|
- Use `if let Some(x) = expr` instead of `if let Some(Some(x)) = expr` — drop unnecessary nesting
|
|
- Prefer explicit `match` over `unwrap_or_default()` for clarity
|
|
- Use `unwrap_or_else(|| expr)` for lazy defaults, `unwrap_or(val)` for eager defaults
|
|
- Use `anyhow!()` with context strings that include identifying info (e.g. UUID, title) not bare values
|
|
|
|
### Color and Output
|
|
- Use `color_text()` helper for colored output — it respects `should_use_colors()` (terminal detection)
|
|
- Color codes are defined in `get_color()`: red (31), cyan (36), orange (33), green (32), grey (38;5;8), magenta (1;35), brightred (38;5;9)
|
|
- Reset color with `\x1b[0m` after colored text
|
|
- Bold uses `\x1b[1;35m` (magenta bold)
|
|
- Always test color output works correctly in both terminal and pipe modes
|
|
|
|
### Color Guideline
|
|
- UUID → red (31)
|
|
- Status → orange (33)
|
|
- Timestamp → cyan (36)
|
|
- Title → green (32)
|
|
- Unknown values (`_None_`, `_Not set_`) → grey (38;5;8)
|
|
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
|
|
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground. `\x1b[38;5;8m` is byte for byte what crossterm emits for ratatui's `Color::DarkGray`, the grey frig and pantop use for dimmed rows
|
|
|
|
### Code Organization
|
|
- Colorization functions (`colorize_line`, `colorize_ordered`, `content_trim_colored`) handle markdown formatting
|
|
- `show` renders the Metadata section as a two column table via `render_metadata_table`, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
|
|
- The title is printed once, by `cmd_show`. `content_trim_colored` skips the `# ` heading in the file content
|
|
- Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
|
|
- `resolve_ticket()` scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filename
|
|
- `parse_ticket_field()` handles extracting metadata values from markdown format
|
|
- Field lookup, read and write, is scoped to the lines under the `## Metadata` heading and anchored to the start of the line. Prose above it is free text: tickets in this repo quote field markers in their descriptions, and an unscoped search reads or rewrites those instead. `set_status_field()` carries the same scoping
|
|
|
|
### Ticket Resolution
|
|
- `resolve_ticket()` returns `(status, title, content)` tuple
|
|
- Priority: exact UUID prefix (8+ chars) > title substring > filename substring
|
|
- Ambiguous matches (multiple results) print options and exit(1)
|
|
- Never return empty strings for required fields — use `_Not set_` or `_None_` as defaults
|
|
|
|
### Git Workflow
|
|
- Commit format: `([ticketID]) [short description]`
|
|
- Use `--fixup` for incremental changes
|
|
- Test before moving to reviewing status
|
|
|
|
### Version Bumps
|
|
- Before every commit, decide whether the change warrants a version bump in `Cargo.toml`
|
|
- Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
|
|
- Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
|
|
- No bump for docs-only, tests-only or `--fixup` commits
|
|
- When one body of work spans several commits, bump once on the final commit rather than on each
|
|
- Bump `Cargo.toml` and the `worklane` entry in `Cargo.lock` together, in the commit that carries the bump
|
|
- Every bump gets a matching annotated tag, `v<version>`, on the bump commit — a bumped version is never left untagged
|
|
- Tag locally only; never push a tag unless asked
|
|
- `worklane --version` reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another
|