tech-log-frontend/docs/superpowers/plans/2026-08-02-counter-bearing-coverage-provenance.md

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.

• Step 1: Rename the test inventory helper and artifact assertions to the desired API.

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,
  };
}

• Step 2: Add a real-source inventory regression table.

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.

• 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.

• 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.

• 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.

• 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.

• Step 1: Document that counterless imports/re-exports may execute at runtime but receive no file counters in the observed producer.

• Step 2: Run relevant verification.

./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.

• Step 3: Commit the independently verified follow-up.

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.