177 lines
8.9 KiB
Markdown
177 lines
8.9 KiB
Markdown
# V8 Coverage Counter Contract Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Publish risk-coverage artifact schema version 3 and continuously verify the installed Vitest/V8 producer's counter-bearing/counterless row semantics in an isolated child run.
|
|
|
|
**Architecture:** A real CLI contract test owns the serialized artifact assertion. A standalone producer checker copies fixed source templates into one OS-temp root, creates its child config and report there, validates an exact JSON summary, bounds child diagnostics, and removes the owned root in `finally`. `test:coverage` invokes the checker before repository coverage, which also carries it into CI and sample removal.
|
|
|
|
**Tech Stack:** TypeScript 7, Node.js 24 child processes and filesystem APIs, Vitest 4, V8 coverage.
|
|
|
|
## Global Constraints
|
|
|
|
- Policy schema remains version 2; serialized risk-coverage artifact schema becomes version 3.
|
|
- Child root, config, and reports directory are all below one owned OS temporary directory.
|
|
- Main Vitest must not discover the child `.fixture.ts` file.
|
|
- Child exit, summary absence, malformed/missing/additional rows, counterless nonzero drift, and runtime all-zero drift fail closed.
|
|
- Child stdout/stderr included in diagnostics is bounded.
|
|
- Cleanup uses `finally` and targets only the exact owned temporary root.
|
|
- Source edits use `apply_patch`; behavior changes follow RED-GREEN TDD.
|
|
|
|
---
|
|
|
|
### Task 1: Version the real serialized artifact
|
|
|
|
**Files:**
|
|
- Modify: `tests/unit/risk-coverage.test.ts`
|
|
- Modify: `scripts/check-risk-coverage.ts`
|
|
|
|
**Interfaces:**
|
|
- Consumes: the real `check-risk-coverage.ts` CLI, current policy structure, and an exact temporary coverage summary.
|
|
- Produces: serialized artifact schema version 3 with `counterBearingTotal`, `instrumentedCounterBearingTotal`, `counterlessTotal`, and `counterlessModules` only.
|
|
|
|
- [x] **Step 1: Add the actual CLI serialization contract test.**
|
|
|
|
Create a temporary repository with the 19 current policy paths, write each as `export const covered = true`, set the cloned policy baseline to 19, write one full counter row per module, run the CLI with `process.execPath`, and assert:
|
|
|
|
```ts
|
|
expect(artifact).toMatchObject({
|
|
schemaVersion: 3,
|
|
counterBearingTotal: 19,
|
|
instrumentedCounterBearingTotal: 19,
|
|
counterlessTotal: 0,
|
|
counterlessModules: [],
|
|
});
|
|
expect(artifact).not.toHaveProperty("executableTotal");
|
|
expect(artifact).not.toHaveProperty("instrumentedExecutableTotal");
|
|
expect(artifact).not.toHaveProperty("nonExecutableTotal");
|
|
expect(artifact).not.toHaveProperty("nonExecutableModules");
|
|
```
|
|
|
|
- [x] **Step 2: Run the single test and verify RED.**
|
|
|
|
Run: `./node_modules/.bin/vitest run tests/unit/risk-coverage.test.ts -t "publishes artifact schema version 3" --reporter=dot`
|
|
|
|
Expected: FAIL because the actual artifact contains `schemaVersion: 2`.
|
|
|
|
- [x] **Step 3: Change only the serialized envelope to version 3.**
|
|
|
|
Change `schemaVersion: 2` to `schemaVersion: 3` in the value passed to `writeRiskCoverageArtifactAtomic`; do not change policy parsing.
|
|
|
|
- [x] **Step 4: Re-run the single test and verify GREEN.**
|
|
|
|
Run the Step 2 command and expect one passing test.
|
|
|
|
### Task 2: Lock actual Vitest/V8 counter semantics
|
|
|
|
**Files:**
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/counter-semantics.fixture.ts`
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/src/runtime.ts`
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/src/import-type-empty.ts`
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/src/import-empty.ts`
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/src/import-side-effect.ts`
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/src/import-value.ts`
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/src/reexport-named.ts`
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/src/reexport-star.ts`
|
|
- Create: `tests/fixtures/v8-coverage-counter-semantics/src/type-only.ts`
|
|
- Create: `tests/unit/v8-coverage-counter-semantics.test.ts`
|
|
- Create: `scripts/lib/v8-coverage-counter-semantics.ts`
|
|
- Create: `scripts/check-v8-coverage-counter-semantics.ts`
|
|
- Modify: `vitest.config.ts`
|
|
|
|
**Interfaces:**
|
|
- Produces: `assertV8CoverageCounterSemantics(summary, fixtureRoot)` and `checkV8CoverageCounterSemantics(options?)`.
|
|
- Consumes: fixed fixture templates, owned temp paths, a shell-free Vitest child result, and `coverage-summary.json`.
|
|
|
|
- [x] **Step 1: Add fixture templates and failing checker tests.**
|
|
|
|
The fixture test imports the seven counterless modules and observes the direct/named/star runtime values. The unit tests use literal summaries to require exact rows and mutate them for missing row, extra row, counterless nonzero, and runtime all-zero failures. Runner tests inject child exit and successful-without-summary results and require bounded diagnostics plus removal of the owned root.
|
|
|
|
- [x] **Step 2: Run the new unit file and verify RED.**
|
|
|
|
Run: `./node_modules/.bin/vitest run tests/unit/v8-coverage-counter-semantics.test.ts --reporter=dot`
|
|
|
|
Expected: FAIL because `scripts/lib/v8-coverage-counter-semantics.ts` does not exist.
|
|
|
|
- [x] **Step 3: Implement exact summary validation and owned child execution.**
|
|
|
|
The default runner executes:
|
|
|
|
```ts
|
|
execFile(process.execPath, [
|
|
path.join(repositoryRoot, "node_modules/vitest/vitest.mjs"),
|
|
"run",
|
|
"--config",
|
|
configPath,
|
|
"--coverage",
|
|
"--reporter=dot",
|
|
"--no-color",
|
|
], { cwd: ownedRoot, timeout: 30_000, maxBuffer: 256 * 1024 });
|
|
```
|
|
|
|
The generated config has `root`, `include`, `coverage.reportsDirectory`, and `coverage.include` paths inside the owned root. Always remove the root in `finally`.
|
|
|
|
- [x] **Step 4: Add a behavioral main-discovery assertion.**
|
|
|
|
Run main `vitest list` filtered to the fixture directory with `--filesOnly --passWithNoTests`; require empty stdout. Add an explicit fixture-directory exclude in `vitest.config.ts`.
|
|
|
|
- [x] **Step 5: Run the new unit file and standalone checker for GREEN.**
|
|
|
|
Run:
|
|
|
|
```sh
|
|
./node_modules/.bin/vitest run tests/unit/v8-coverage-counter-semantics.test.ts --reporter=dot
|
|
node scripts/check-v8-coverage-counter-semantics.ts
|
|
```
|
|
|
|
Expected checker output: `V8 coverage counter semantics: PASS (1 counter-bearing, 7 counterless)`.
|
|
|
|
### Task 3: Wire coverage/CI and refresh documentation
|
|
|
|
**Files:**
|
|
- Modify: `package.json`
|
|
- Modify: `docs/testing/frontend-platform-testing-strategy.md`
|
|
- Modify: `.superpowers/sdd/2026-08-01-quality-architecture-remediation/task-1-report.md`
|
|
- Modify: `.superpowers/sdd/2026-08-01-quality-architecture-remediation/progress.md`
|
|
|
|
**Interfaces:**
|
|
- Consumes: `check:v8-coverage-counter-semantics` and existing FE-GATE-005 `test:coverage` step.
|
|
- Produces: package/CI/sample-removal execution and current 19-module/80-threshold documentation.
|
|
|
|
- [x] **Step 1: Add the package checker and prepend it to `test:coverage`.**
|
|
|
|
```json
|
|
"check:v8-coverage-counter-semantics": "node scripts/check-v8-coverage-counter-semantics.ts",
|
|
"test:coverage": "corepack pnpm check:v8-coverage-counter-semantics && vitest run ..."
|
|
```
|
|
|
|
- [x] **Step 2: Synchronize documentation.**
|
|
|
|
Replace stale `12개 high-risk module` and `52개 scoped threshold` with `19개` and `80개`; document artifact schema 3 and policy schema 2 separately.
|
|
|
|
- [x] **Step 3: Run full relevant verification.**
|
|
|
|
```sh
|
|
./node_modules/.bin/vitest run tests/unit/risk-coverage.test.ts tests/unit/risk-coverage-files.test.ts tests/unit/v8-coverage-counter-semantics.test.ts tests/unit/bounded-body-reader.test.ts --reporter=dot
|
|
./node_modules/.bin/tsc --noEmit -p tsconfig.node.json
|
|
./node_modules/.bin/tsc --noEmit -p tsconfig.test.json
|
|
./node_modules/.bin/eslint scripts/check-risk-coverage.ts scripts/check-v8-coverage-counter-semantics.ts scripts/lib/v8-coverage-counter-semantics.ts tests/unit/risk-coverage.test.ts tests/unit/v8-coverage-counter-semantics.test.ts vitest.config.ts --max-warnings=0
|
|
corepack pnpm check:v8-coverage-counter-semantics
|
|
node scripts/check-risk-coverage.ts
|
|
corepack pnpm test:sample-removal
|
|
git diff --check
|
|
```
|
|
|
|
- [x] **Step 4: Commit the verified closeout.**
|
|
|
|
```sh
|
|
git add package.json vitest.config.ts scripts/check-risk-coverage.ts scripts/check-v8-coverage-counter-semantics.ts scripts/lib/v8-coverage-counter-semantics.ts tests/fixtures/v8-coverage-counter-semantics tests/unit/risk-coverage.test.ts tests/unit/v8-coverage-counter-semantics.test.ts docs/testing/frontend-platform-testing-strategy.md docs/superpowers/plans/2026-08-02-v8-coverage-counter-contract.md
|
|
git commit -m "test: lock V8 coverage counter semantics"
|
|
```
|
|
|
|
## Self-review
|
|
|
|
- Spec coverage: artifact versioning, actual producer rows, discovery isolation, every fail-closed path, bounded diagnostics, cleanup, coverage/CI linkage, sample-removal preservation, and documentation counts are assigned.
|
|
- Placeholder scan: no deferred implementation remains.
|
|
- Type consistency: parser and runner names match in tests, script, and plan.
|