134 lines
6.8 KiB
Markdown
134 lines
6.8 KiB
Markdown
# Counter-bearing Coverage Provenance 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:** Align repository coverage provenance names and static classification with the counters that Vitest/V8 actually emits, without making claims about JavaScript runtime executability.
|
|
|
|
**Architecture:** The inventory parser classifies source files only by whether their top-level AST contains statements known to receive V8 counters. Coverage evaluation requires exact agreement between that static counter-bearing/counterless partition and producer rows, while policy-sensitive modules must remain counter-bearing. The JSON artifact exposes the same terminology as the inventory and diagnostics.
|
|
|
|
**Tech Stack:** TypeScript 7, Node.js 24, `@babel/eslint-parser`, Vitest 4, V8 coverage.
|
|
|
|
## Global Constraints
|
|
|
|
- Runtime declarations/initializers and direct execution statements are counter-bearing.
|
|
- Type-only modules, `import type {}`, `import {}`, bare side-effect imports, value imports, named value re-exports, and star value re-exports are counterless under the observed Vitest/V8 producer.
|
|
- Counterless does not mean non-executable; code, artifacts, diagnostics, tests, and documentation must not make that claim.
|
|
- Exact all-zero rows are accepted only for statically counterless modules.
|
|
- Critical and high-risk policy modules cannot be counterless.
|
|
- All source edits use `apply_patch` and behavior changes follow RED-GREEN TDD.
|
|
|
|
---
|
|
|
|
### Task 1: Lock the Vitest/V8 classifier contract with RED tests
|
|
|
|
**Files:**
|
|
- Modify: `tests/unit/risk-coverage.test.ts`
|
|
|
|
**Interfaces:**
|
|
- Consumes: `buildProductionModuleInventory()` and `evaluateRiskCoverage()`.
|
|
- Produces: expectations for `counterBearingModules`, `counterlessModules`, `counterBearingTotal`, `instrumentedCounterBearingTotal`, `counterlessTotal`, and `counterlessModules`.
|
|
|
|
- [x] **Step 1: Rename the test inventory helper and artifact assertions to the desired API.**
|
|
|
|
```ts
|
|
function inventory(
|
|
files: readonly string[],
|
|
generatedExclusions: readonly string[] = [],
|
|
counterlessModules: readonly string[] = [],
|
|
): ProductionModuleInventory {
|
|
return {
|
|
files,
|
|
preExclusionTotal: files.length + generatedExclusions.length,
|
|
generatedExclusions,
|
|
counterBearingModules: files.filter((file) => !counterlessModules.includes(file)),
|
|
counterlessModules,
|
|
};
|
|
}
|
|
```
|
|
|
|
- [x] **Step 2: Add a real-source inventory regression table.**
|
|
|
|
```ts
|
|
const counterlessSources = {
|
|
"import-type-empty.ts": "import type {} from './a.ts';\n",
|
|
"import-value-empty.ts": "import {} from './a.ts';\n",
|
|
"import-side-effect.ts": "import './a.ts';\n",
|
|
"import-value.ts": "import { a } from './a.ts';\n",
|
|
"reexport-named.ts": "export { a } from './a.ts';\n",
|
|
"reexport-star.ts": "export * from './a.ts';\n",
|
|
};
|
|
```
|
|
|
|
Assert every key appears in `counterlessModules`, while `export const runtimeValue = 1` and `void globalThis` appear in `counterBearingModules`.
|
|
|
|
- [x] **Step 3: Run the focused test and verify RED.**
|
|
|
|
Run: `./node_modules/.bin/vitest run tests/unit/risk-coverage.test.ts --reporter=dot`
|
|
|
|
Expected: TypeScript/test failures because the counter-bearing API fields do not exist and the current bare import classifier is executable-labelled.
|
|
|
|
### Task 2: Rename and align static coverage provenance
|
|
|
|
**Files:**
|
|
- Modify: `scripts/lib/risk-coverage.ts`
|
|
- Modify: `tests/unit/risk-coverage.test.ts`
|
|
|
|
**Interfaces:**
|
|
- Consumes: Babel `Program.body` nodes and parsed Istanbul/V8 counters.
|
|
- Produces: `hasCoverageCounterBearingStatements(source, relativePath)`, a complete `counterBearingModules`/`counterlessModules` partition, and consistently named `RiskCoverageResult` fields.
|
|
|
|
- [x] **Step 1: Implement the minimal classifier needed by the RED cases.**
|
|
|
|
`ImportDeclaration`, `ExportAllDeclaration`, and export declarations without a local declaration return `false`; `importKind === "type"` therefore remains counterless even with an empty specifier list. Runtime declarations/initializers and direct statements return `true`.
|
|
|
|
- [x] **Step 2: Rename inventory, evaluator sets, totals, diagnostics, and policy guards.**
|
|
|
|
Use these exact artifact fields: `counterBearingTotal`, `instrumentedCounterBearingTotal`, `counterlessTotal`, `counterlessModules`. Use diagnostics containing `counter-bearing`, `counterless`, and `policy-sensitive module cannot be counterless`; remove executable/non-executable terminology from the risk-coverage implementation and tests.
|
|
|
|
- [x] **Step 3: Run focused GREEN verification.**
|
|
|
|
Run: `./node_modules/.bin/vitest run tests/unit/risk-coverage.test.ts tests/unit/risk-coverage-files.test.ts tests/unit/bounded-body-reader.test.ts --reporter=dot`
|
|
|
|
Expected: all focused tests pass and both static partition directions remain fail-closed.
|
|
|
|
### Task 3: Refresh documentation, repository evidence, and removal evidence
|
|
|
|
**Files:**
|
|
- 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: root and sample-removal checker output after Task 2.
|
|
- Produces: documented V8 counter-bearing semantics and current 285/285 plus 268/268 evidence.
|
|
|
|
- [x] **Step 1: Document that counterless imports/re-exports may execute at runtime but receive no file counters in the observed producer.**
|
|
|
|
- [x] **Step 2: Run relevant verification.**
|
|
|
|
```sh
|
|
./node_modules/.bin/tsc --noEmit -p tsconfig.node.json
|
|
./node_modules/.bin/tsc --noEmit -p tsconfig.test.json
|
|
./node_modules/.bin/eslint scripts/lib/risk-coverage.ts tests/unit/risk-coverage.test.ts --max-warnings=0
|
|
node scripts/check-risk-coverage.ts
|
|
corepack pnpm test:sample-removal
|
|
git diff --check
|
|
```
|
|
|
|
Expected root checker: `Risk coverage: PASS (285/285 production modules, 80 thresholds)`.
|
|
|
|
Expected removal checker: `Risk coverage: PASS (268/268 production modules, 76 thresholds)`; the already-known dependency-cruiser architecture diagnostic may remain the sole removal failure.
|
|
|
|
- [x] **Step 3: Commit the independently verified follow-up.**
|
|
|
|
```sh
|
|
git add docs/superpowers/plans/2026-08-02-counter-bearing-coverage-provenance.md docs/testing/frontend-platform-testing-strategy.md scripts/lib/risk-coverage.ts tests/unit/risk-coverage.test.ts
|
|
git commit -m "refactor: align coverage counter provenance"
|
|
```
|
|
|
|
## Self-review
|
|
|
|
- Spec coverage: terminology, import/re-export edge cases, policy diagnostics, artifact fields, root/removal evidence, report, and ledger are each assigned above.
|
|
- Placeholder scan: no deferred implementation or unspecified test step remains.
|
|
- Type consistency: inventory and result names use `counterBearing*`/`counterless*` throughout; the classifier is `hasCoverageCounterBearingStatements`.
|