feat: add stats command with terminal charts #18

Merged

jwarykowski merged 1 commit from feat/stats into master

2026-07-13 11:39:35 +00:00

jwarykowski commented

2026-07-13 11:32:23 +00:00

(Migrated from github.com)

What

Adds shepherd stats [--json] [--all] (plus a --stats launch flag) that summarises a board as terminal charts.

Metrics:

status — total / open / done + completion rate
due & urgency — overdue, due today, due this week, no date, deferred
priority load — open by !H/!M/!L/none
by category — full-width, all categories (long names clipped)
throughput — done/day 30d sparkline
backlog trend — created vs done 14d (braille)
by project — --all only
aging — oldest / avg open age / stale>30d / avg cycle time

Done-based counts include the archive so completion rate stays honest. --json emits the raw numbers (no charts) for scripts/agents; charts render to a tty in a responsive grid.

How

todo.Compute([]Item) Stats — pure, I/O-free, clock pinnable for tests.
store.LoadArchive / LoadAllArchives — done-item history.
internal/cli/charts.go — the only ntcharts import. Sparkline + braille time-series come from ntcharts; horizontal bars are hand-drawn (ntcharts' horizontal barchart reversed row order and left mid-bar artifacts for the single-value case).
help and -h/--help unified via cli.Usage() so they never diverge.

Test

internal/todo/stats_test.go — every bucket asserted against a pinned clock.
internal/cli/stats_test.go — archive counted, --all populates by-project, --json emits no chart glyphs.
go build / go vet / go test ./... / golangci-lint run all green.

## What Adds `shepherd stats [--json] [--all]` (plus a `--stats` launch flag) that summarises a board as terminal charts. Metrics: - **status** — total / open / done + completion rate - **due & urgency** — overdue, due today, due this week, no date, deferred - **priority load** — open by !H/!M/!L/none - **by category** — full-width, all categories (long names clipped) - **throughput** — done/day 30d sparkline - **backlog trend** — created vs done 14d (braille) - **by project** — `--all` only - **aging** — oldest / avg open age / stale>30d / avg cycle time Done-based counts include the archive so completion rate stays honest. `--json` emits the raw numbers (no charts) for scripts/agents; charts render to a tty in a responsive grid. ## How - `todo.Compute([]Item) Stats` — pure, I/O-free, clock pinnable for tests. - `store.LoadArchive` / `LoadAllArchives` — done-item history. - `internal/cli/charts.go` — the only ntcharts import. Sparkline + braille time-series come from [ntcharts](https://github.com/NimbleMarkets/ntcharts); horizontal bars are hand-drawn (ntcharts' horizontal barchart reversed row order and left mid-bar artifacts for the single-value case). - `help` and `-h`/`--help` unified via `cli.Usage()` so they never diverge. ## Test - `internal/todo/stats_test.go` — every bucket asserted against a pinned clock. - `internal/cli/stats_test.go` — archive counted, `--all` populates by-project, `--json` emits no chart glyphs. - `go build` / `go vet` / `go test ./...` / `golangci-lint run` all green.