@bensandee/tooling 0.55.1 → 0.56.0

package/README.md

@@ -162,6 +162,80 @@ Convention and overrides coexist — a repo can use both.
 
 Works for both `changesets` and `simple` release strategies, on Forgejo (via API upload) and GitHub (via `gh release upload --clobber`). The asset step in the workflow is gated on the release itself having published/pushed, so failed releases never upload stale artifacts.
 
+### Coverage tracking
+
+| Command                    | Description                                                                                   |
+| -------------------------- | --------------------------------------------------------------------------------------------- |
+| `tooling coverage:summary` | Print a labeled per-package summary of the latest run. `--json` for machine-readable form.    |
+| `tooling coverage:check`   | Compare the latest run against `coverage-baseline.json`; exit non-zero on regression.         |
+| `tooling coverage:record`  | Append the latest run to a `bst/coverage-metrics` orphan branch (CI: push to default branch). |
+| `tooling coverage:status`  | Show recent coverage trend. Read-only — fetches the orphan branch, no checkout.               |
+
+The feature has two halves: a **CI history** that captures one record per commit on the default branch (visible to anyone with the repo), and a **local ratchet** that the agent (or developer) consults before declaring a task complete.
+
+#### How it works
+
+`repo:sync` enables coverage tracking automatically when a `vitest.config.ts` is present. The generated `vitest.config.ts` includes the `json-summary` reporter so each `pnpm test:coverage` writes `coverage/coverage-summary.json` alongside the human-readable HTML report. A generated `coverage.yml` workflow runs on push to the default branch and pipes:
+
+```text
+pnpm test:coverage  →  coverage:summary  →  coverage:record  →  coverage:status
+```
+
+so every CI log ends with the trend table for the last 10 records.
+
+The history file (`coverage-history.jsonl`) lives on a dedicated `bst/coverage-metrics` orphan branch — never on `main`. This sidesteps branch protection (no privileged token needed beyond `contents: write`) and keeps `git log main` clean. `coverage:record` uses pure git plumbing (`hash-object` → `mktree` → `commit-tree` → `push --force-with-lease`) so the working tree is never touched, and concurrent CI runs are handled safely via compare-and-swap with retry.
+
+#### The local ratchet
+
+A tracked `coverage-baseline.json` at the repo root captures the four overall totals (lines/statements/branches/functions) plus per-package numbers. `coverage:check` compares the latest run against it and exits non-zero if any total drops more than the configured `tolerancePp` (default 0.1). When all four are flat-or-up, `--update-baseline` rewrites the file so it can be staged with the change.
+
+`repo:sync` also inserts a `<!-- @tooling:coverage-rule -->` managed block into `CLAUDE.md` describing the workflow:
+
+> Before declaring a task complete that touched files under `packages/*/src/`, run `pnpm test:coverage` then `pnpm exec bst coverage:check`. If any total dropped, add tests until parity is restored — or, if a touched file is genuinely not worth covering, exclude it via `coverage.exclude` in `vitest.config.ts` and explain why in the commit message. If all four are flat-or-up, run `pnpm exec bst coverage:check --update-baseline` and stage `coverage-baseline.json`.
+
+Skip the rule for docs-only, config-only, dependency-bump, or test-only changes.
+
+#### Bootstrap
+
+On a clean default branch, generate the initial baseline:
+
+```bash
+pnpm test:coverage
+pnpm exec bst coverage:check --update-baseline --no-fail-on-missing-baseline
+git add coverage-baseline.json
+```
+
+The first CI run on the default branch creates the orphan `bst/coverage-metrics` branch automatically. From any clone, inspect the trend with:
+
+```bash
+pnpm exec bst coverage:status --limit 20
+```
+
+#### Opt-out
+
+Disable the feature entirely:
+
+```json
+{ "coverage": false }
+```
+
+Or keep the local ratchet but skip the CI history append:
+
+```json
+{ "coverage": { "history": "none" } }
+```
+
+| Override field       | Default                  | Description                                                            |
+| -------------------- | ------------------------ | ---------------------------------------------------------------------- |
+| `history`            | `"orphan-branch"`        | `"none"` disables CI history; the local ratchet still works            |
+| `historyBranch`      | `"bst/coverage-metrics"` | Override the orphan branch name                                        |
+| `tolerancePp`        | `0.1`                    | Tolerance in percentage points before `coverage:check` flags a drop    |
+| `gateOnPullRequests` | `false`                  | Run coverage on PR builds too (deferred follow-up — currently a no-op) |
+
+#### Per-package re-sum
+
+The trimmed record's `packages` map is computed by aggregating files whose path starts with `packages/<name>/`, so monorepo packages get their own line/branch percentages without per-package vitest configs. Single-package repos collapse to one entry keyed by the directory basename. Per-package numbers are recorded but **not gated** — only the four overall totals control the ratchet.
+
 ### Docker
 
 | Command                  | Description                                                         |