huskies: merge 474_story_per_file_test_coverage_report_with_improvement_targets

2026-04-04 15:07:37 +00:00
parent c4e2f600de
commit df135e9373
4 changed files with 338 additions and 38 deletions
@@ -266,3 +266,44 @@ The `bot.toml` file is gitignored (it contains secrets). The example files are c
 **ALWAYS FIX DIAGNOSTICS:** At every stage, you must proactively fix all errors and warnings without waiting for user confirmation. Do not pause to ask whether to fix diagnostics—fix them immediately as part of the workflow.

 **Consult `specs/tech/STACK.md`** for the specific tools, commands, linter configurations, and quality gates for this project. The STACK file is the single source of truth for what must pass before a story can be accepted.
+
+---
+
+## 8. Coverage Report Format
+
+Huskies reads a language-agnostic `.coverage_report.json` file at the project root. Any project can produce this file from its own coverage tooling — the huskies server has no language-specific coverage logic.
+
+### Format
+
+```json
+{
+  "overall": 66.25,
+  "threshold": 60.0,
+  "files": [
+    { "path": "server/src/agents/pty.rs", "coverage": 12.5 },
+    { "path": "frontend/src/components/Chat.tsx", "coverage": 31.2 }
+  ]
+}
+```
+
+*   **`overall`** — overall line coverage percentage (float, 0–100).
+*   **`threshold`** — the minimum acceptable coverage (float, 0–100).
+*   **`files`** — per-file coverage array, sorted ascending (lowest coverage first). Each entry has:
+    *   **`path`** — file path relative to the project root (string).
+    *   **`coverage`** — line coverage percentage for this file (float, 0–100).
+
+### How to produce this file
+
+The project's `script/test_coverage` is responsible for generating `.coverage_report.json`. Other projects can adapt this approach for any language:
+
+*   **Rust:** Use `cargo llvm-cov --json` for per-file data; parse `data[0].files[*].summary.lines.percent`.
+*   **TypeScript/Vitest:** Use `--coverage.reporter=json-summary`; parse `coverage/coverage-summary.json` (Istanbul format).
+*   **Any other language:** Run your coverage tool, extract per-file line percentages, and write the JSON in the format above.
+
+### How the bot uses it
+
+The `coverage` bot command reads `.coverage_report.json` and displays:
+1.  Overall coverage and threshold.
+2.  The **top 5 lowest-covered files** as improvement targets.
+
+Run `coverage run` in the bot to regenerate the file via `script/test_coverage`.