docs: surface 80% coverage gate and scripts/debug runners (#1108)

2026-07-27 21:08:00 +00:00 · 2026-05-02 14:53:35 -07:00
parent dff8f953e1
commit da410e9d7f
6 changed files with 73 additions and 0 deletions
@@ -23,6 +23,7 @@ Suspected cause, workaround, or proposed fix. Skip if unknown.

 - [ ] **Repro gone** — Bug no longer reproduces on the stated environment (or root cause documented if intentional).
 - [ ] **Regression safety** — Unit, integration, or E2E coverage added or updated if this should not come back.
+- [ ] **Diff coverage ≥ 80%** — the fix PR meets the changed-lines coverage gate (Vitest + cargo-llvm-cov, enforced by [`.github/workflows/coverage.yml`](../../.github/workflows/coverage.yml)).
 - [ ] **…** — Other verify-before-close items.

 ## Related
@@ -24,6 +24,7 @@ How you plan to solve it — scope (core / app / both), approach, tradeoffs. Ski
 - [ ] **Feature 1** — TODO
 - [ ] **Feature 2** — TODO
 - [ ] **Feature 3** — TODO
+- [ ] **Diff coverage ≥ 80%** — the implementing PR meets the changed-lines coverage gate (Vitest + cargo-llvm-cov, enforced by [`.github/workflows/coverage.yml`](../../.github/workflows/coverage.yml)).

 - …

@@ -18,6 +18,7 @@
 > If a section does not apply to this change, mark the item as `N/A` with a one-line reason. Do not delete items.

 - [ ] Tests added or updated (happy path + at least one failure / edge case) per [`docs/TESTING-STRATEGY.md`](../docs/TESTING-STRATEGY.md#failure-path-requirement)
+- [ ] **Diff coverage ≥ 80%** — changed lines (Vitest + cargo-llvm-cov merged via `diff-cover`) meet the gate enforced by [`.github/workflows/coverage.yml`](../.github/workflows/coverage.yml). Run `pnpm test:coverage` and `pnpm test:rust` locally; PRs below 80% on changed lines will not merge.
 - [ ] Coverage matrix updated — added/removed/renamed feature rows in [`docs/TEST-COVERAGE-MATRIX.md`](../docs/TEST-COVERAGE-MATRIX.md) reflect this change (or `N/A: behaviour-only change`)
 - [ ] All affected feature IDs from the matrix are listed in the PR description under `## Related`
 - [ ] No new external network dependencies introduced (mock backend used per [`docs/TESTING-STRATEGY.md`](../docs/TESTING-STRATEGY.md#mock-policy))
@@ -12,6 +12,12 @@ concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.head_ref || github.ref }}
  cancel-in-progress: true

+defaults:
+  run:
+    # The CI container's default `sh` is dash, which rejects `set -o pipefail`
+    # and bashisms like `mapfile`. Force bash for every `run:` step.
+    shell: bash
+
 jobs:
  frontend-coverage:
    name: Frontend Coverage (Vitest)
@@ -73,6 +73,38 @@ cargo check --manifest-path app/src-tauri/Cargo.toml

 **Quality**: ESLint + Prettier + Husky in the `app` workspace.

+### Agent debug runners (`scripts/debug/`)
+
+Use these wrappers instead of invoking Vitest / WDIO / cargo directly when iterating — they keep stdout summary-sized and tee full output to `target/debug-logs/<kind>-<suffix>-<timestamp>.log`. Add `--verbose` to also stream raw output. See [`scripts/debug/README.md`](scripts/debug/README.md).
+
+```bash
+# Vitest
+pnpm debug unit                                    # full suite
+pnpm debug unit src/components/Foo.test.tsx        # one file (positional pattern)
+pnpm debug unit -t "renders empty state"           # filter by test name
+pnpm debug unit Foo -t "renders empty" --verbose
+
+# WDIO E2E (one spec at a time)
+pnpm debug e2e test/e2e/specs/smoke.spec.ts
+pnpm debug e2e test/e2e/specs/cron-jobs-flow.spec.ts cron-jobs --verbose
+
+# cargo tests (delegates to scripts/test-rust-with-mock.sh)
+pnpm debug rust
+pnpm debug rust json_rpc_e2e
+
+# Inspect saved logs
+pnpm debug logs                  # list 50 most recent
+pnpm debug logs last             # print most recent (last 400 lines)
+pnpm debug logs unit             # most recent matching prefix "unit"
+pnpm debug logs last --tail 100
+```
+
+Files: `scripts/debug/{cli,unit,e2e,rust,logs,lib}.sh`. Entry point: `pnpm debug` (`scripts/debug/cli.sh`).
+
+### Coverage requirement (merge gate)
+
+PRs must meet **≥ 80% coverage on changed lines**. Enforced by [`.github/workflows/coverage.yml`](.github/workflows/coverage.yml) via `diff-cover` over merged Vitest + `cargo-llvm-cov` (core + Tauri shell) lcov outputs. Below the threshold the PR will not merge. Run `pnpm test:coverage` and `pnpm test:rust` locally; add tests for new/changed lines (happy path + at least one failure / edge case).
+
 ---

 ## Configuration
@@ -54,6 +54,38 @@ cargo check --manifest-path app/src-tauri/Cargo.toml
 **Tests**: Vitest in `app/` (`pnpm test:unit`, `pnpm test:coverage`); Rust via `cargo test`.
 **Quality**: ESLint + Prettier + Husky in `app`.

+### Agent debug runners (`scripts/debug/`)
+
+Bounded-output wrappers around the project test runners. Stdout stays summary-sized (so it fits in agent context); full output is teed to `target/debug-logs/<kind>-<suffix>-<timestamp>.log`. Add `--verbose` to also stream raw output. Prefer these over invoking Vitest / WDIO / cargo directly when iterating.
+
+```bash
+# Vitest
+pnpm debug unit                                    # full suite
+pnpm debug unit src/components/Foo.test.tsx        # one file (positional pattern)
+pnpm debug unit -t "renders empty state"           # filter by test name
+pnpm debug unit Foo -t "renders empty" --verbose
+
+# WDIO E2E (one spec at a time)
+pnpm debug e2e test/e2e/specs/smoke.spec.ts
+pnpm debug e2e test/e2e/specs/cron-jobs-flow.spec.ts cron-jobs --verbose
+
+# cargo tests (delegates to scripts/test-rust-with-mock.sh)
+pnpm debug rust
+pnpm debug rust json_rpc_e2e
+
+# Inspect saved logs
+pnpm debug logs                  # list 50 most recent
+pnpm debug logs last             # print most recent (last 400 lines)
+pnpm debug logs unit             # most recent matching prefix "unit"
+pnpm debug logs last --tail 100
+```
+
+Files: `scripts/debug/{cli,unit,e2e,rust,logs,lib}.sh` plus `README.md`. Entry point is `pnpm debug` (`scripts/debug/cli.sh`).
+
+### Coverage requirement (merge gate)
+
+PRs must meet **≥ 80% coverage on changed lines**. Enforced by [`.github/workflows/coverage.yml`](.github/workflows/coverage.yml) using `diff-cover` over merged Vitest (`app/coverage/lcov.info`) and `cargo-llvm-cov` (core + Tauri shell) lcov outputs. Below the threshold the PR will not merge — add tests for new/changed lines, not just the happy path.
+
 ---

 ## Configuration