styleproof 3.9.0 → 3.10.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.10.0] - 2026-07-06
+
+### Added
+
+- **Determinism provenance — a green needs a proven-deterministic capture.** Source-of-
+  truth step 2: a clean diff of two _nondeterministic_ captures is meaningless (they
+  might just happen to match). The capture now records its determinism basis in the
+  ledger — `self-checked` (captured twice, styles matched — a drift would have failed the
+  capture), `replayed` (rendered against a recorded HAR, deterministic by construction),
+  or `unproven` (neither) — and `styleproof-diff`:
+  - **blocks (exit 1) when either side is `unproven`**, even on an empty style diff;
+  - prints `✓ determinism proven — base X, head Y`, `✗ determinism NOT proven …`, or
+    `⚠ determinism basis unknown` (an older bundle with no field — degrades, never a
+    false red). The record-then-replay flow (base `self-checked`, head `replayed`) is
+    proven, as it should be.
+
 ## [3.9.0] - 2026-07-05
 
 ### Added

package/bin/styleproof-diff.mjs

@@ -41,7 +41,7 @@ import {
 } from '../dist/cli-errors.js';
 import { loadStyleMap } from '../dist/capture.js';
 import { auditRunInventory } from '../dist/inventory.js';
-import { auditCoverage, COVERAGE_LEDGER } from '../dist/coverage.js';
+import { auditCoverage, auditDeterminism, COVERAGE_LEDGER } from '../dist/coverage.js';
 import { isMapFile } from '../dist/map-store.js';
 
 const COMMAND = path.basename(process.argv[1] ?? 'styleproof-diff').replace(/\.mjs$/, '');
@@ -129,17 +129,14 @@ function capturedSurfaceKeys(dir) {
   ];
 }
 
-function readCoverageVerdict(dir) {
-  let ledger = null;
+function readLedger(dir) {
   const p = path.join(dir, COVERAGE_LEDGER);
-  if (fs.existsSync(p)) {
-    try {
-      ledger = JSON.parse(fs.readFileSync(p, 'utf8'));
-    } catch {
-      /* a corrupt ledger reads as no registry → "not asserted", never a false green */
-    }
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null; // a corrupt ledger reads as no registry → "not asserted", never a false green
   }
-  return auditCoverage(capturedSurfaceKeys(dir), ledger);
 }
 
 // Print the completeness verdict; return true if it BLOCKS (a registered surface is missing).
@@ -165,6 +162,23 @@ function printCoverageVerdict(v) {
   return true;
 }
 
+// Print the determinism verdict; return true if it BLOCKS (a side's capture was unproven).
+function printDeterminismVerdict(v) {
+  if (v.status === 'proven') {
+    console.log(`\n✓ determinism proven — base ${v.base}, head ${v.head}`);
+    return false;
+  }
+  if (v.status === 'unknown') {
+    console.log('\n⚠ determinism basis unknown — a capture predates the determinism ledger; recapture to certify it.');
+    return false;
+  }
+  console.log(
+    `\n✗ determinism NOT proven — base ${v.base}, head ${v.head}. An unproven capture can drift, so a clean\n` +
+      '  diff might be two matching NONDETERMINISTIC reads. Enable selfCheck (default) or replay a recorded HAR.',
+  );
+  return true;
+}
+
 const HELP = `${COMMAND} — certify a CSS refactor by diffing two computed-style map captures
 
 usage: ${COMMAND} [baseRef] [options]
@@ -257,14 +271,17 @@ if (args.length <= 1) {
 let result;
 let inventoryAudit = null;
 let coverageVerdict = null;
+let determinismVerdict = null;
 try {
   assertCompatibleMapDirs(dirA, dirB);
   result = diffStyleMapDirs(dirA, dirB);
-  // Read inventory + coverage here, while the (possibly cached/restored) dirs still
-  // exist — the finally below deletes them in cached-map mode. Coverage is the HEAD
-  // bundle's completeness basis.
+  // Read inventory + the certification ledgers here, while the (possibly cached/restored)
+  // dirs still exist — the finally below deletes them in cached-map mode. Coverage is the
+  // HEAD bundle's completeness basis; determinism needs both sides.
   inventoryAudit = readInventoryAudit(dirA, dirB);
-  coverageVerdict = readCoverageVerdict(dirB);
+  const headLedger = readLedger(dirB);
+  coverageVerdict = auditCoverage(capturedSurfaceKeys(dirB), headLedger);
+  determinismVerdict = auditDeterminism(readLedger(dirA), headLedger);
 } catch (e) {
   console.error(e.message);
   process.exit(2);
@@ -302,9 +319,13 @@ for (const sd of surfaces) {
 
 const invRemovals = printInventoryAudit(inventoryAudit);
 const coverageFails = printCoverageVerdict(coverageVerdict);
+const determinismFails = printDeterminismVerdict(determinismVerdict);
 
 if (jsonOut)
-  fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces, compared, coverage: coverageVerdict }, null, 2));
+  fs.writeFileSync(
+    jsonOut,
+    JSON.stringify({ counts, surfaces, compared, coverage: coverageVerdict, determinism: determinismVerdict }, null, 2),
+  );
 
 const total = counts.dom + counts.style + counts.state;
 const newSurfaces = surfaces.filter((s) => s.missing).length;
@@ -313,14 +334,16 @@ const surfaceCount = surfaces.length;
 const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
 const invNote = invRemovals ? ` + ${invRemovals} unacknowledged inventory removal(s)` : '';
 const covNote = coverageFails ? ` + ${coverageVerdict.uncovered.length} uncaptured registered surface(s)` : '';
-const clean = total === 0 && invRemovals === 0 && !coverageFails;
+const detNote = determinismFails ? ' + determinism unproven' : '';
+const clean = total === 0 && invRemovals === 0 && !coverageFails && !determinismFails;
 console.log(
   clean
     ? newSurfaces === 0
       ? `\n✓ 0 changed surfaces across ${compared} captured surface(s): every computed style, pseudo-element, and hover/focus/active state matches`
       : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — review before baselining`
-    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}${covNote}`,
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}${covNote}${detNote}`,
 );
-// 0 = identical, 1 = reviewable differences (incl. unacknowledged inventory removals or
-// an incomplete coverage registry), 3 = only new surfaces (no baseline). 2 = usage/capture error.
-process.exit(total > 0 || invRemovals > 0 || coverageFails ? 1 : newSurfaces > 0 ? 3 : 0);
+// 0 = identical, 1 = reviewable differences (incl. unacknowledged inventory removals, an
+// incomplete coverage registry, or an unproven-determinism capture), 3 = only new surfaces
+// (no baseline). 2 = usage/capture error.
+process.exit(total > 0 || invRemovals > 0 || coverageFails || determinismFails ? 1 : newSurfaces > 0 ? 3 : 0);

package/dist/coverage.d.ts

@@ -36,13 +36,32 @@ export type CoverageGaps = {
 export declare function coverageGaps(capturedKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CoverageGaps;
 /** Bundled next to the maps, so the completeness basis travels with the capture. */
 export declare const COVERAGE_LEDGER = "styleproof-coverage.json";
+/**
+ * How a capture's determinism was established — the second half of a trustworthy green.
+ * `self-checked`: captured twice and the computed styles matched (a drift would have
+ * failed the capture). `replayed`: rendered against a recorded HAR, so deterministic by
+ * construction. `unproven`: neither — the styles could have drifted and no one checked.
+ */
+export type DeterminismBasis = 'self-checked' | 'replayed' | 'unproven';
 export type CoverageLedger = {
     version: 1;
     /** The declared surface registry, or null when the spec asserted none. */
     expected: string[] | null;
     /** Reviewed opt-outs (`key → reason`). */
     exclude: Record<string, string>;
+    /** How this capture's determinism was established (3.10.0). Absent on older bundles. */
+    determinism?: DeterminismBasis;
+};
+export type DeterminismVerdict = {
+    /** `proven` — both sides self-checked or replayed; `unproven` — a side was neither, so
+     *  a clean diff might just be two matching NONDETERMINISTIC captures; `unknown` — an
+     *  older bundle with no determinism field (degrade, don't block). */
+    status: 'proven' | 'unproven' | 'unknown';
+    base: DeterminismBasis | 'unknown';
+    head: DeterminismBasis | 'unknown';
 };
+/** The gate's determinism call: a green needs BOTH sides proven (self-checked or replayed). */
+export declare function auditDeterminism(base: CoverageLedger | null, head: CoverageLedger | null): DeterminismVerdict;
 export type CoverageVerdict = {
     /** `complete` — every registered surface captured; `incomplete` — a registered
      *  surface is missing (gates); `unasserted` — no registry, so a green can only

package/dist/coverage.js

@@ -44,6 +44,17 @@ export function coverageGaps(capturedKeys, expected, exclude = {}) {
 // the suite guard — which checks the declared list — cannot see it).
 /** Bundled next to the maps, so the completeness basis travels with the capture. */
 export const COVERAGE_LEDGER = 'styleproof-coverage.json';
+/** The gate's determinism call: a green needs BOTH sides proven (self-checked or replayed). */
+export function auditDeterminism(base, head) {
+    const b = base?.determinism ?? 'unknown';
+    const h = head?.determinism ?? 'unknown';
+    const proven = (d) => d === 'self-checked' || d === 'replayed';
+    if (b === 'unproven' || h === 'unproven')
+        return { status: 'unproven', base: b, head: h };
+    if (proven(b) && proven(h))
+        return { status: 'proven', base: b, head: h };
+    return { status: 'unknown', base: b, head: h };
+}
 /** The gate's completeness call: audit what was actually captured against the ledger. */
 export function auditCoverage(capturedKeys, ledger) {
     if (!ledger || ledger.expected == null) {

package/dist/runner.js

@@ -458,11 +458,18 @@ function resolveSettings(c) {
  * `expected: null` records that the spec declared no registry, so a green can only
  * certify the captured surfaces. Runs on a capture run (dir set) only.
  */
-function writeCoverageLedgerTest(baseDir, dir, expected, exclude) {
+function writeCoverageLedgerTest(settings, dir, expected, exclude) {
     test('styleproof coverage ledger', () => {
-        const outDir = path.join(baseDir, dir);
+        const outDir = path.join(settings.baseDir, dir);
         fs.mkdirSync(outDir, { recursive: true });
-        const ledger = { version: 1, expected, exclude };
+        // Determinism basis: self-check ON proves it (a drift would have failed the capture);
+        // else a replay run is deterministic by construction; else it's unproven.
+        const determinism = settings.selfCheck
+            ? 'self-checked'
+            : settings.replayFrom
+                ? 'replayed'
+                : 'unproven';
+        const ledger = { version: 1, expected, exclude, determinism };
         fs.writeFileSync(path.join(outDir, COVERAGE_LEDGER), JSON.stringify(ledger, null, 2));
     });
 }
@@ -490,7 +497,7 @@ export function defineStyleMapCapture(options) {
     test.describe('styleproof capture', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         if (dir)
-            writeCoverageLedgerTest(settings.baseDir, dir, expected ?? null, exclude);
+            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
         for (const surface of captureSurfaces) {
             if (surface.widths && surface.widths.length > 0) {
                 // Explicit widths: one parallelizable test per surface × width.
@@ -545,7 +552,7 @@ export function defineCrawlCapture(options) {
         // so it records `expected: null` (completeness honestly "not asserted": the crawl
         // captures what the nav links to, and can't prove that's every route in the app).
         if (dir)
-            writeCoverageLedgerTest(settings.baseDir, dir, null, {});
+            writeCoverageLedgerTest(settings, dir, null, {});
         test('discover surfaces by crawling links, then capture each', async ({ page }) => {
             // 1. Load the root and wait for its nav links to hydrate — an SPA renders them
             //    client-side, so they aren't in the initial HTML.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",