supercov 0.0.0

package/src/transport.ts

@@ -0,0 +1,132 @@
+import type { CoverageCarrier, CoverageExecutionScope } from "./types.ts";
+
+export const COVERAGE_SCOPE_HEADER = "x-supercov-scope";
+export const COVERAGE_PHASE_HEADER = "x-supercov-phase";
+export const COVERAGE_CARRIER_ENV = "SUPERCOV_CONTEXT";
+export const DEFAULT_SERVER_EVIDENCE_ROOT =
+  "/tmp/supercov-server-evidence";
+
+function nonEmpty(value: string | null): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function safeKey(value: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(value);
+}
+
+function pathComponent(value: string): string {
+  const safe = value.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return safe || "unscoped";
+}
+
+export function encodeCoverageScope(scope: CoverageExecutionScope): string {
+  return new URLSearchParams({
+    v: String(scope.version),
+    r: scope.runId,
+    w: scope.workerId,
+    t: scope.testId,
+    k: scope.testKey,
+    a: String(scope.retry),
+    i: scope.attemptId,
+  }).toString();
+}
+
+export function decodeCoverageScope(
+  encoded: string | undefined,
+): CoverageExecutionScope | undefined {
+  if (!encoded) return undefined;
+  try {
+    const values = new URLSearchParams(encoded);
+    const runId = values.get("r");
+    const workerId = values.get("w");
+    const testId = values.get("t");
+    const testKey = values.get("k");
+    const attemptId = values.get("i");
+    const retry = Number(values.get("a"));
+    if (
+      values.get("v") !== "1" ||
+      !nonEmpty(runId) ||
+      !nonEmpty(workerId) ||
+      !nonEmpty(testId) ||
+      !nonEmpty(testKey) ||
+      !safeKey(testKey) ||
+      !nonEmpty(attemptId) ||
+      !safeKey(attemptId) ||
+      !Number.isSafeInteger(retry) ||
+      retry < 0
+    )
+      return undefined;
+    return {
+      version: 1,
+      runId,
+      workerId,
+      testId,
+      testKey,
+      retry,
+      attemptId,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function encodeCoverageCarrier(carrier: CoverageCarrier): string {
+  return Buffer.from(JSON.stringify(carrier), "utf8").toString("base64url");
+}
+
+export function decodeCoverageCarrier(
+  encoded: string | undefined,
+): CoverageCarrier | undefined {
+  if (!encoded) return undefined;
+  try {
+    const value = JSON.parse(
+      Buffer.from(encoded, "base64url").toString("utf8"),
+    ) as CoverageCarrier;
+    if (value.version !== 1) return undefined;
+    if (value.scope) {
+      const roundTrip = decodeCoverageScope(encodeCoverageScope(value.scope));
+      if (!roundTrip) return undefined;
+    }
+    if (value.phaseId !== undefined && value.phaseId.length === 0)
+      return undefined;
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+export function serverRunEvidenceDirectory(
+  runId: string,
+  root = DEFAULT_SERVER_EVIDENCE_ROOT,
+): string {
+  return `${root.replace(/\/+$/, "")}/${pathComponent(runId)}`;
+}
+
+export function serverEvidenceDirectory(
+  scope: CoverageExecutionScope,
+  root = DEFAULT_SERVER_EVIDENCE_ROOT,
+): string {
+  return `${serverRunEvidenceDirectory(scope.runId, root)}/${pathComponent(scope.workerId)}/${scope.testKey}/${scope.retry}`;
+}
+
+export function serverEvidencePath(
+  scope: CoverageExecutionScope,
+  root = DEFAULT_SERVER_EVIDENCE_ROOT,
+): string {
+  return `${serverEvidenceDirectory(scope, root)}/server.jsonl`;
+}
+
+export function backgroundEvidenceDirectory(
+  runId: string,
+  root = DEFAULT_SERVER_EVIDENCE_ROOT,
+): string {
+  return `${serverRunEvidenceDirectory(runId, root)}/background`;
+}
+
+export function backgroundEvidencePath(
+  runId: string,
+  processId = typeof process === "undefined" ? "unknown" : String(process.pid),
+  root = DEFAULT_SERVER_EVIDENCE_ROOT,
+): string {
+  return `${backgroundEvidenceDirectory(runId, root)}/${pathComponent(processId)}.jsonl`;
+}

package/src/types.ts

@@ -0,0 +1,412 @@
+export interface McdcDecisionMeta {
+  id: string;
+  file: string;
+  line: number;
+  column: number;
+  source: string;
+  conditions: string[];
+  kind: "if" | "ternary" | "while" | "do-while" | "for";
+}
+
+export interface McdcVector {
+  values: Array<boolean | null>;
+  outcome: boolean;
+}
+
+export interface McdcDecisionSnapshot {
+  meta: McdcDecisionMeta;
+  vectors: McdcVector[];
+}
+
+export type CoveragePointKind = "statement" | "function";
+
+export interface CoveragePointMeta {
+  id: string;
+  kind: CoveragePointKind;
+  file: string;
+  line: number;
+  column: number;
+  source: string;
+  label?: string;
+}
+
+export type CoverageBranchKind =
+  | "logical-value"
+  | "logical-assignment"
+  | "optional-chain"
+  | "default-value"
+  | "try-catch"
+  | "for-in"
+  | "for-of"
+  | "switch"
+  | "dynamic-code";
+
+export interface CoverageBranchMeta {
+  id: string;
+  kind: CoverageBranchKind;
+  file: string;
+  line: number;
+  column: number;
+  source: string;
+  alternatives: Array<{
+    id: string;
+    label: string;
+  }>;
+}
+
+export interface CoverageManifest {
+  decisions: McdcDecisionMeta[];
+  points: CoveragePointMeta[];
+  branches: CoverageBranchMeta[];
+  limitations?: CoverageLimitation[];
+}
+
+export interface CoverageLimitation {
+  id: string;
+  kind: "dynamic-code";
+  file: string;
+  line: number;
+  column: number;
+  source: string;
+  reason: string;
+}
+
+export interface CoverageRuntimeSnapshot {
+  decisions: McdcDecisionSnapshot[];
+  hits: string[];
+  events?: CoverageRuntimeEvent[];
+}
+
+export interface CoverageExecutionScope {
+  version: 1;
+  runId: string;
+  workerId: string;
+  testId: string;
+  testKey: string;
+  retry: number;
+  attemptId: string;
+}
+
+export type CoverageRuntimeEvent =
+  | {
+      type: "hit";
+      id: string;
+      timestampMs: number;
+      phaseId?: string;
+      environment: "browser" | "server";
+    }
+  | {
+      type: "decision";
+      id: string;
+      vector: McdcVector;
+      timestampMs: number;
+      phaseId?: string;
+      environment: "browser" | "server";
+    };
+
+export type CoverageServerRecord =
+  | {
+      type: "decision";
+      meta: McdcDecisionMeta;
+      vector: McdcVector;
+      timestampMs?: number;
+      phaseId?: string;
+      scope?: CoverageExecutionScope;
+    }
+  | {
+      type: "hit";
+      id: string;
+      timestampMs?: number;
+      phaseId?: string;
+      scope?: CoverageExecutionScope;
+    };
+
+export interface CoverageCarrier {
+  version: 1;
+  scope?: CoverageExecutionScope;
+  phaseId?: string;
+}
+
+export interface CoveragePhase {
+  id: string;
+  kind: "action" | "assertion";
+  operation: string;
+  source?: string;
+  causedByPhaseId?: string;
+  startedAtMs: number;
+  endedAtMs?: number;
+  status?: "passed" | "failed";
+  error?: string;
+}
+
+export interface TestProvenance {
+  /** The process responsible for executing the test, such as playwright or vitest. */
+  runner: string;
+  /** The semantic testing level, such as unit, integration, e2e, or component. */
+  kind: string;
+  project?: string;
+  /** How the kind was established so inferred labels are never presented as explicit. */
+  source: "explicit" | "project" | "path" | "runner-default" | "unknown";
+}
+
+export interface McdcRawTestResult {
+  testId?: string;
+  /** Run/worker/test/retry identity for an exact concurrently executed attempt. */
+  scope?: CoverageExecutionScope;
+  test: string;
+  testFile?: string;
+  title?: string;
+  retry?: number;
+  /** Outcome of this exact attempt, normalized across test runners. */
+  status?: TestAttemptStatus;
+  /** Runner-level expected outcome (notably Playwright's test.fail()). */
+  expectedStatus?: TestAttemptStatus;
+  /** True when the runner reports that an earlier attempt failed. */
+  flaky?: boolean;
+  provenance?: TestProvenance;
+  role?: "test" | "setup" | "background";
+  phases?: CoveragePhase[];
+  runtime?: CoverageRuntimeSnapshot[];
+  browser: CoverageRuntimeSnapshot[];
+  server: CoverageServerRecord[];
+}
+
+export type TestAttemptStatus =
+  | "passed"
+  | "failed"
+  | "skipped"
+  | "timedOut"
+  | "interrupted"
+  | "unknown";
+
+export type TestOutcome =
+  | "passed"
+  | "failed"
+  | "flaky"
+  | "skipped"
+  | "timedOut"
+  | "interrupted"
+  | "unknown";
+
+export interface TestAttemptResult {
+  retry: number;
+  status: TestAttemptStatus;
+  expectedStatus?: TestAttemptStatus;
+}
+
+export interface McdcVectorObservation {
+  vector: McdcVector;
+  tests: string[];
+  phases?: string[];
+  explicitPhases?: string[];
+  confidence?: CoverageConfidence;
+}
+
+export interface CoverageConfidence {
+  level: "unexecuted" | "executed" | "action" | "asserted";
+  setupOnly: boolean;
+  backgroundOnly: boolean;
+  asserted: boolean;
+  tests: string[];
+  assertedTests: string[];
+  runners: string[];
+  kinds: string[];
+  e2e: boolean;
+}
+
+export interface McdcConditionResult {
+  index: number;
+  source: string;
+  covered: boolean;
+  witness?: [McdcVector, McdcVector];
+  witnessTests?: [string[], string[]];
+  assertionCovered?: boolean;
+}
+
+export interface McdcDecisionResult {
+  meta: McdcDecisionMeta;
+  executed: boolean;
+  covered: boolean;
+  vectors: McdcVector[];
+  vectorObservations: McdcVectorObservation[];
+  conditions: McdcConditionResult[];
+  tests: string[];
+  confidence?: CoverageConfidence;
+}
+
+export interface CoverageCount {
+  covered: number;
+  total: number;
+  percentage: number;
+}
+
+export interface CoveragePointResult {
+  meta: CoveragePointMeta;
+  covered: boolean;
+  tests: string[];
+  phases?: string[];
+  confidence?: CoverageConfidence;
+}
+
+export interface CoverageBranchResult {
+  meta: CoverageBranchMeta;
+  covered: boolean;
+  alternatives: Array<{
+    id: string;
+    label: string;
+    covered: boolean;
+    tests: string[];
+    phases?: string[];
+    confidence?: CoverageConfidence;
+  }>;
+}
+
+export interface CoveragePhaseResult extends CoveragePhase {
+  test: string;
+  hits: string[];
+  decisions: Array<{
+    id: string;
+    vectors: McdcVector[];
+  }>;
+  lines: Array<{
+    file: string;
+    line: number;
+  }>;
+  browserEvents: number;
+  serverEvents: number;
+  explicitEvents: number;
+  inferredEvents: number;
+  explicitBrowserEvents: number;
+  inferredBrowserEvents: number;
+  explicitServerEvents: number;
+  inferredServerEvents: number;
+}
+
+export interface TestCoverageResult {
+  id: string;
+  name: string;
+  file?: string;
+  title?: string;
+  retries: number[];
+  attempts: TestAttemptResult[];
+  outcome: TestOutcome;
+  provenance: TestProvenance;
+  role: "test" | "setup" | "background";
+  hits: string[];
+  decisions: Array<{
+    id: string;
+    vectors: McdcVector[];
+  }>;
+  lines: Array<{
+    file: string;
+    line: number;
+  }>;
+}
+
+export interface TestFileCoverageResult {
+  file: string;
+  tests: string[];
+  runners: string[];
+  kinds: string[];
+  lines: Array<{
+    file: string;
+    line: number;
+  }>;
+}
+
+export interface CoverageSummary {
+  decisions: number;
+  executedDecisions: number;
+  coveredDecisions: number;
+  conditions: number;
+  coveredConditions: number;
+  conditionCoveragePct: number;
+  lines: CoverageCount;
+  statements: CoverageCount;
+  functions: CoverageCount;
+  branches: CoverageCount;
+  decisionOutcomes: CoverageCount;
+  conditionOutcomes: CoverageCount;
+  valueSelections: CoverageCount;
+  coverageComplete: boolean;
+  completenessBlocked?: boolean;
+}
+
+export interface CoverageRunFingerprint {
+  algorithm: "sha256";
+  source: string;
+  tests: string;
+  dependencies: string;
+  configuration: string;
+  instrumenter: string;
+  combined: string;
+  sourceFiles: number;
+  testFiles: number;
+}
+
+export interface CoverageRunIntegrity {
+  schemaVersion: number;
+  instrumenterVersion: string;
+  git?: {
+    revision?: string;
+    dirty: boolean;
+  };
+  fingerprint: CoverageRunFingerprint;
+  stale?: boolean;
+  staleReasons?: string[];
+}
+
+export interface McdcCoverageView {
+  generatedAt: string;
+  variant: "masking-short-circuit";
+  model: {
+    name: string;
+    completenessMeaning: string;
+    measured: string[];
+    notMeasured: string[];
+  };
+  integrity?: CoverageRunIntegrity;
+  limitations?: CoverageLimitation[];
+  summary: CoverageSummary;
+  coverageByKind: Array<{
+    kind: string;
+    tests: number;
+    setups: number;
+    summary: CoverageSummary;
+  }>;
+  coverageByRunner: Array<{
+    runner: string;
+    tests: number;
+    setups: number;
+    summary: CoverageSummary;
+  }>;
+  decisions: McdcDecisionResult[];
+  points: CoveragePointResult[];
+  branches: CoverageBranchResult[];
+  tests: TestCoverageResult[];
+  testFiles: TestFileCoverageResult[];
+  phases: CoveragePhaseResult[];
+  lines: Array<{
+    file: string;
+    line: number;
+    covered: boolean;
+    tests: string[];
+    runners: string[];
+    kinds: string[];
+    exclusiveKind?: string;
+    phases?: string[];
+    confidence?: CoverageConfidence;
+  }>;
+}
+
+export interface McdcReport extends McdcCoverageView {
+  execution?: {
+    testExitCode?: number | null;
+    valid: boolean;
+  };
+  /** Materialized evidence filters; top-level coverage contains all attempts. */
+  filters?: {
+    passed: McdcCoverageView;
+    failed: McdcCoverageView;
+  };
+}

package/src/vitePlugin.ts

@@ -0,0 +1,121 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Plugin } from "vite";
+import { instrumentMcdc, mcdcRuntimeModuleId } from "./instrumenter.ts";
+import type {
+  CoverageBranchMeta,
+  CoverageLimitation,
+  CoveragePointMeta,
+  McdcDecisionMeta,
+} from "./types.ts";
+
+export interface McdcVitePluginOptions {
+  root?: string;
+  sourceRoots?: string[];
+  manifestPath?: string;
+}
+
+export function mcdcVitePlugin(options: McdcVitePluginOptions = {}): Plugin {
+  const root = options.root ?? process.cwd();
+  const sourceRoots = (options.sourceRoots ?? ["app", "src"])
+    .map((directory) => resolve(root, directory))
+    .filter((directory) => existsSync(directory));
+  const runtimePath = fileURLToPath(new URL("./runtime.ts", import.meta.url));
+  const manifestPath = options.manifestPath
+    ? resolve(root, options.manifestPath)
+    : resolve(root, ".supercov/mcdc-manifest.json");
+  const markerPath = resolve(dirname(manifestPath), ".mcdc-enabled");
+  const decisions = new Map<string, McdcDecisionMeta>();
+  const points = new Map<string, CoveragePointMeta>();
+  const branches = new Map<string, CoverageBranchMeta>();
+  const limitations = new Map<string, CoverageLimitation>();
+
+  const recordManifest = (manifest: {
+    decisions: McdcDecisionMeta[];
+    points: CoveragePointMeta[];
+    branches: CoverageBranchMeta[];
+    limitations?: CoverageLimitation[];
+  }): void => {
+    for (const decision of manifest.decisions)
+      decisions.set(decision.id, decision);
+    for (const point of manifest.points) points.set(point.id, point);
+    for (const branch of manifest.branches) branches.set(branch.id, branch);
+    for (const limitation of manifest.limitations ?? [])
+      limitations.set(limitation.id, limitation);
+  };
+
+  const sourceFiles = (directory: string): string[] =>
+    readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) return sourceFiles(path);
+      return /\.[cm]?[jt]sx?$/.test(entry.name) ? [path] : [];
+    });
+
+  return {
+    name: "supercov-mcdc",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === mcdcRuntimeModuleId) return runtimePath;
+      return null;
+    },
+    buildStart() {
+      // Vite only transforms modules reachable from a build entry. Scan every
+      // source file up front so never-imported executable code is still in the
+      // denominator and appears as uncovered rather than disappearing.
+      for (const sourceRoot of sourceRoots) {
+        for (const id of sourceFiles(sourceRoot)) {
+          const file = relative(root, id).split(sep).join("/");
+          recordManifest(
+            instrumentMcdc(readFileSync(id, "utf8"), file).manifest,
+          );
+        }
+      }
+    },
+    transform(code, rawId) {
+      const id = rawId.split("?")[0] ?? rawId;
+      if (
+        !sourceRoots.some(
+          (sourceRoot) =>
+            id === sourceRoot || id.startsWith(`${sourceRoot}${sep}`),
+        ) ||
+        !/\.[cm]?[jt]sx?$/.test(id)
+      )
+        return null;
+      const file = relative(root, id).split(sep).join("/");
+      const result = instrumentMcdc(code, file);
+      recordManifest(result.manifest);
+      return {
+        code: result.code,
+        ...(result.map ? { map: JSON.parse(JSON.stringify(result.map)) } : {}),
+      };
+    },
+    closeBundle() {
+      mkdirSync(dirname(manifestPath), { recursive: true });
+      const sortByLocation = <
+        T extends { file: string; line: number; column: number },
+      >(
+        values: T[],
+      ): T[] =>
+        values.sort((left, right) =>
+          left.file === right.file
+            ? left.line - right.line || left.column - right.column
+            : left.file.localeCompare(right.file),
+        );
+      const manifest = {
+        decisions: sortByLocation([...decisions.values()]),
+        points: sortByLocation([...points.values()]),
+        branches: sortByLocation([...branches.values()]),
+        limitations: sortByLocation([...limitations.values()]),
+      };
+      writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+      writeFileSync(markerPath, "coverage-completeness-v2\n");
+    },
+  };
+}