styleproof 3.17.0 → 3.19.0

package/dist/runner.d.ts

@@ -185,6 +185,23 @@ type ExpandedSurface = Omit<Surface, 'variants' | 'liveStates'> & {
     metadata?: CaptureMetadata;
 };
 export declare function expandSurfaceVariants(surface: Surface): ExpandedSurface[];
+/** The identity fields of an expanded surface a collision check needs. */
+type ExpandedKeyed = {
+    key: string;
+    metadata?: CaptureMetadata;
+};
+/**
+ * Fail LOUDLY on two expanded surfaces sharing a capture key.
+ *
+ * The expanded key is `surface.key-variant.key`, and that key is the map filename
+ * (`<key>@<width>.json.gz`) and the report identity — so it's public and can't
+ * change without breaking backward compatibility. But the `-` join is ambiguous:
+ * surface `a` + variant `b-c` and surface `a-b` + variant `c` both expand to
+ * `a-b-c`, and the second capture would silently overwrite the first, dropping a
+ * surface with no error. Rather than mangle the public key format, we assert
+ * uniqueness up front and name BOTH origins so the author can rename one.
+ */
+export declare function assertUniqueExpandedKeys(surfaces: ExpandedKeyed[]): void;
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
  * server. A long-lived stream can't round-trip through a HAR entry: recording
@@ -255,25 +272,29 @@ export type CrawlOptions = CaptureConfig & {
     /** Max ms to wait for the crawl root's links to render before reading them
      *  (an SPA hydrates its nav client-side). Default 15000. */
     linkTimeout?: number;
+    /**
+     * The full set of surface keys the app knows its nav should link to — its route
+     * universe. When set, the crawl reconciles the DISCOVERED link set against it, both
+     * directions: an `expected` key with no rendered link fails (nav regression), and a
+     * rendered link with no `expected` entry fails (a new route with no owner). For a
+     * link-crawled SPA the rendered nav IS the route universe, so this is the same
+     * list-vs-ledger discipline as `defineStyleMapCapture`'s guard with the nav as the
+     * source of truth.
+     *
+     * Unlike the spec guard, this runs INSIDE the crawl capture test — the link set
+     * isn't known until a browser renders the page — so it only fires when the capture
+     * runs (STYLEMAP_DIR set), not in every `npm test`. Omit to keep the current
+     * behaviour: capture what the nav links to, assert no completeness.
+     */
+    expected?: string[];
+    /**
+     * Expected/rendered keys deliberately not reconciled, each mapped to its reason — a
+     * visible, reviewed opt-out ledger for links that render CONDITIONALLY (behind auth
+     * or a feature flag) and so can't be asserted present or absent on every run. An
+     * excluded key never triggers a missing- or unexpected-link failure; an `exclude`
+     * key in neither `expected` nor the rendered set fails, so the ledger can't rot.
+     */
+    exclude?: Record<string, string>;
 };
-/**
- * Like {@link defineStyleMapCapture}, but the surface set is DISCOVERED at run time
- * by crawling a page's links instead of being hand-listed — for a single-route SPA
- * whose views are `?tab=`/client-routed and so invisible to the filesystem
- * {@link discoverNextRoutes}. It navigates `from`, reads its same-origin `<a href>`s
- * (filtered by `match`), and captures each as a surface keyed by `key`. The app just
- * has to render its nav as real links; nothing to hand-maintain, so the surface list
- * can't drift from the nav.
- *
- * One Playwright test does the whole sweep (the link set isn't known until a browser
- * has rendered the page, so per-surface tests can't be generated at collection time).
- * Per-surface failures are aggregated — one bad surface reports without hiding the
- * rest. Replay/self-check/clock-freeze behave exactly as for explicit surfaces.
- *
- * ```ts
- * // styleproof.spec.ts — capture every tab the nav links to
- * defineCrawlCapture({ from: '/', match: /\?tab=/, widths: [1440, 1024, 768], dir: process.env.STYLEMAP_DIR });
- * ```
- */
 export declare function defineCrawlCapture(options: CrawlOptions): void;
 export {};

package/dist/runner.js

@@ -3,9 +3,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests, } from './capture.js';
 import { diffStyleMaps } from './diff.js';
-import { coverageGaps, COVERAGE_LEDGER } from './coverage.js';
+import { coverageGaps, coverageKeys, translateExpected, COVERAGE_LEDGER, } from './coverage.js';
+import { writeBrowserBuildSidecar } from './map-store.js';
 import { detectViewportWidths } from './breakpoints.js';
-import { selectCrawlLinks } from './crawl.js';
+import { selectCrawlLinks, crawlCoverageError } from './crawl.js';
 /** One-line description of the first drift finding, for the self-check error. */
 function driftDesc(f) {
     if (f.kind === 'dom')
@@ -209,6 +210,36 @@ export function expandSurfaceVariants(surface) {
         return [baseSurface, ...expandedVariants];
     return [...expandedVariants, ...liveStates.map((state) => expandOne(surface, state, 'live-state'))];
 }
+/** Human-readable origin of an expanded surface for a collision message. */
+function expandedOrigin(s) {
+    const surfaceKey = s.metadata?.surfaceKey ?? s.key;
+    const variantKey = s.metadata?.variantKey;
+    return variantKey ? `surface '${surfaceKey}' variant '${variantKey}'` : `surface '${surfaceKey}'`;
+}
+/**
+ * Fail LOUDLY on two expanded surfaces sharing a capture key.
+ *
+ * The expanded key is `surface.key-variant.key`, and that key is the map filename
+ * (`<key>@<width>.json.gz`) and the report identity — so it's public and can't
+ * change without breaking backward compatibility. But the `-` join is ambiguous:
+ * surface `a` + variant `b-c` and surface `a-b` + variant `c` both expand to
+ * `a-b-c`, and the second capture would silently overwrite the first, dropping a
+ * surface with no error. Rather than mangle the public key format, we assert
+ * uniqueness up front and name BOTH origins so the author can rename one.
+ */
+export function assertUniqueExpandedKeys(surfaces) {
+    const byKey = new Map();
+    for (const s of surfaces) {
+        const prior = byKey.get(s.key);
+        if (prior) {
+            throw new Error(`styleproof: capture key '${s.key}' is produced by two surfaces — ` +
+                `${expandedOrigin(prior)} collides with ${expandedOrigin(s)}. ` +
+                `Keys must expand uniquely (they name the map files and report entries); ` +
+                `rename one surface or variant.`);
+        }
+        byKey.set(s.key, s);
+    }
+}
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
  * server. A long-lived stream can't round-trip through a HAR entry: recording
@@ -458,7 +489,7 @@ 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(settings, dir, expected, exclude) {
+function writeCoverageLedgerTest(settings, dir, expected, exclude, captureSurfaces) {
     test('styleproof coverage ledger', () => {
         const outDir = path.join(settings.baseDir, dir);
         fs.mkdirSync(outDir, { recursive: true });
@@ -469,14 +500,30 @@ function writeCoverageLedgerTest(settings, dir, expected, exclude) {
             : settings.replayFrom
                 ? 'replayed'
                 : 'unproven';
-        const ledger = { version: 1, expected, exclude, determinism };
+        // Pre-translate the declared universe into the keys actually captured to disk, so
+        // the GATE (which reads expanded map filenames and can't see `surfaceKey` metadata)
+        // compares literally — a liveStates surface's `-loading`/`-loaded` splits satisfy it.
+        const ledgerExpected = expected == null ? null : translateExpected(expected, captureSurfaces);
+        const ledger = { version: 1, expected: ledgerExpected, exclude, determinism };
         fs.writeFileSync(path.join(outDir, COVERAGE_LEDGER), JSON.stringify(ledger, null, 2));
     });
 }
+/** Record the real browser build into the capture bundle. The npm `@playwright/test`
+ *  version (in the manifest) is only a proxy — the actual Chromium binary can change while
+ *  it holds constant (a re-download, a different browser store, a CI image bump). The
+ *  compatibility guard reads this back to refuse a cross-build compare instead of walling
+ *  a PR with false diffs. Best-effort: an unavailable version leaves the guard as-is. */
+function writeBrowserBuildTest(settings, dir) {
+    test('styleproof browser build', ({ page }) => {
+        const version = page.context().browser()?.version();
+        writeBrowserBuildSidecar(path.join(settings.baseDir, dir), version);
+    });
+}
 export function defineStyleMapCapture(options) {
     const { surfaces, expected, exclude = {}, dir } = options;
     const settings = resolveSettings(options);
     const captureSurfaces = surfaces.flatMap(expandSurfaceVariants);
+    assertUniqueExpandedKeys(captureSurfaces);
     // Coverage guard. Runs in the NORMAL test suite (NOT gated on a capture dir), so
     // a route added without a surface fails the app's own tests — long before, and
     // independent of, a capture run. This is the one gap captures can't catch: a
@@ -485,7 +532,10 @@ export function defineStyleMapCapture(options) {
     if (expected) {
         test.describe('styleproof coverage', () => {
             test('every expected surface is captured or explicitly excluded', () => {
-                const { uncovered, staleExclusions } = coverageGaps(captureSurfaces.map((s) => s.key), expected, exclude);
+                const { uncovered, staleExclusions } = coverageGaps(
+                // A liveStates surface is captured only as its `-loading`/`-loaded` splits;
+                // map each back to the declared base key so the split satisfies `expected`.
+                coverageKeys(captureSurfaces), expected, exclude);
                 expect(uncovered, `StyleProof coverage gap: ${uncovered.length} expected surface(s) are neither captured ` +
                     `nor excluded — add each to \`surfaces\`, or to \`exclude\` with a reason. ` +
                     `Missing: ${uncovered.join(', ')}`).toEqual([]);
@@ -497,7 +547,9 @@ export function defineStyleMapCapture(options) {
     test.describe('styleproof capture', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         if (dir)
-            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
+            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude, captureSurfaces);
+        if (dir)
+            writeBrowserBuildTest(settings, dir);
         for (const surface of captureSurfaces) {
             if (surface.widths && surface.widths.length > 0) {
                 // Explicit widths: one parallelizable test per surface × width.
@@ -541,38 +593,96 @@ export function defineStyleMapCapture(options) {
  * defineCrawlCapture({ from: '/', match: /\?tab=/, widths: [1440, 1024, 768], dir: process.env.STYLEMAP_DIR });
  * ```
  */
+/**
+ * Load the crawl root, wait for its nav links to hydrate, and read them into a
+ * deduped, keyed surface list. A link-less page is fine for an unfiltered crawl —
+ * it still captures `from` itself (includeSelf); a `match`-filtered crawl genuinely
+ * needs links, so its hydration timeout surfaces. Throws when nothing matched.
+ */
+async function discoverCrawlLinks(page, { from, match, key, linkTimeout }) {
+    await page.goto(from, { waitUntil: 'load' });
+    await page.waitForSelector('a[href]', { timeout: linkTimeout }).catch((e) => {
+        if (match !== undefined)
+            throw e;
+    });
+    const hrefs = await page.$$eval('a[href]', (els) => els.map((e) => e.getAttribute('href')));
+    // Unfiltered crawl → also capture `from` itself, so the root is always covered and
+    // a single-page (or no-nav-self-link) app still yields a surface. A `match`-filtered
+    // crawl captures only the links the caller asked for.
+    const links = selectCrawlLinks(hrefs, { base: page.url(), match, key, includeSelf: match === undefined });
+    if (links.length === 0) {
+        throw new Error(`styleproof crawl: no links matched at ${from}. The nav must render same-origin ` +
+            `<a href> links (a button-only nav exposes nothing to crawl), and \`match\` must keep them.`);
+    }
+    return links;
+}
+/**
+ * Capture every discovered surface, aggregating per-surface failures so one bad
+ * surface reports without skipping the rest — they're an independent set, not a
+ * chain. Auto-width parity with explicit surfaces: no widths given → navigate once,
+ * detect the surface's @media bands, then sweep one viewport per band.
+ */
+async function sweepCrawlSurfaces(page, captureSurfaces, settings) {
+    const failures = [];
+    for (const surface of captureSurfaces) {
+        let sweep = surface.widths;
+        if (!sweep || sweep.length === 0) {
+            try {
+                await surface.go(page);
+                sweep = await detectViewportWidths(page);
+            }
+            catch (e) {
+                failures.push(`${surface.key} @ auto: ${e.message}`);
+                continue;
+            }
+        }
+        for (const width of sweep) {
+            try {
+                await captureSurface(page, surface, width, settings);
+            }
+            catch (e) {
+                failures.push(`${surface.key} @ ${width}: ${e.message}`);
+            }
+        }
+    }
+    if (failures.length) {
+        throw new Error(`styleproof crawl-capture: ${failures.length} surface(s) failed:\n${failures.join('\n')}`);
+    }
+}
 export function defineCrawlCapture(options) {
-    const { from, match, key, widths, height, ignore, variants, liveStates, popups, linkTimeout = 15_000, dir, settle, } = options;
+    const { from, match, key, widths, height, ignore, variants, liveStates, popups, linkTimeout = 15_000, dir, settle, expected, exclude = {}, } = options;
     const settings = resolveSettings(options);
     // Title contains "styleproof capture" so the same `--grep 'styleproof capture'`
     // that styleproof-map uses to select capture tests picks up crawl specs too.
     test.describe('styleproof capture (crawl)', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
-        // A crawl DISCOVERS its surfaces from the nav — it has no registry to check against,
-        // 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).
+        // Record the completeness basis. Without `expected` a crawl has no registry to
+        // check against, so it records `expected: null` (honestly "not asserted": it
+        // captures what the nav links to, and can't prove that's every route). With
+        // `expected` the crawl reconciles the DISCOVERED link set against it below and the
+        // ledger travels with the declared universe.
+        // The crawl applies the SAME variants/liveStates to every discovered link, so the
+        // expansion of a declared key is knowable up front (before discovery): expand each
+        // `expected` key with this crawl's variants/liveStates to get the keys captured to
+        // disk, so a liveStates crawl's ledger is pre-translated like the spec-driven one.
+        const ledgerSurfaces = (expected ?? []).flatMap((key) => expandSurfaceVariants({ key, go: async () => { }, variants, liveStates }));
+        if (dir)
+            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude, ledgerSurfaces);
         if (dir)
-            writeCoverageLedgerTest(settings, dir, null, {});
+            writeBrowserBuildTest(settings, dir);
         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.
-            await page.goto(from, { waitUntil: 'load' });
-            // Wait for the nav's links to hydrate (an SPA renders them client-side). A link-less
-            // page is fine for an unfiltered crawl — it still captures `from` itself (includeSelf);
-            // a `match`-filtered crawl genuinely needs links, so let its timeout surface.
-            await page.waitForSelector('a[href]', { timeout: linkTimeout }).catch((e) => {
-                if (match !== undefined)
-                    throw e;
-            });
-            const hrefs = await page.$$eval('a[href]', (els) => els.map((e) => e.getAttribute('href')));
-            // Unfiltered crawl → also capture `from` itself, so the root is always covered and
-            // a single-page (or no-nav-self-link) app still yields a surface. A `match`-filtered
-            // crawl captures only the links the caller asked for.
-            const links = selectCrawlLinks(hrefs, { base: page.url(), match, key, includeSelf: match === undefined });
-            if (links.length === 0) {
-                throw new Error(`styleproof crawl: no links matched at ${from}. The nav must render same-origin ` +
-                    `<a href> links (a button-only nav exposes nothing to crawl), and \`match\` must keep them.`);
-            }
+            // 1. Load the root and read its hydrated nav links into the surface set.
+            const links = await discoverCrawlLinks(page, { from, match, key, linkTimeout });
+            // Coverage guard for a crawled nav. The rendered link set IS the route universe
+            // for a link-crawled SPA, so reconciling it against `expected` (both directions)
+            // is the spec guard's list-vs-ledger discipline with the nav as source of truth.
+            // Runs here — inside the capture test — because the link set isn't known until
+            // the page renders (unlike the static spec guard, which runs in the plain suite).
+            const gap = expected
+                ? crawlCoverageError(from, links.map((l) => l.key), expected, exclude)
+                : null;
+            if (gap)
+                throw new Error(gap);
             const captureSurfaces = links.flatMap((link) => expandSurfaceVariants({
                 key: link.key,
                 go: async (p) => {
@@ -587,40 +697,14 @@ export function defineCrawlCapture(options) {
                 liveStates,
                 popups,
             }));
+            assertUniqueExpandedKeys(captureSurfaces);
             // Budget the whole sweep up front: one test captures every surface, and
             // captureSurface no longer sets its own timeout, so size it to the work found.
             // With auto-width the band count isn't known until each surface renders, so
             // assume up to 4 bands per surface.
             test.setTimeout(Math.max(180_000, captureSurfaces.reduce((sum, surface) => sum + (surface.widths?.length ?? 4), 0) * 60_000));
-            // 2. Capture each discovered surface. Aggregate failures so one bad surface
-            //    reports without skipping the rest — they're an independent set, not a chain.
-            const failures = [];
-            for (const surface of captureSurfaces) {
-                // Auto-width parity with explicit surfaces: no widths given → navigate once and
-                // detect this surface's @media bands, then sweep one viewport per band.
-                let sweep = surface.widths;
-                if (!sweep || sweep.length === 0) {
-                    try {
-                        await surface.go(page);
-                        sweep = await detectViewportWidths(page);
-                    }
-                    catch (e) {
-                        failures.push(`${surface.key} @ auto: ${e.message}`);
-                        continue;
-                    }
-                }
-                for (const width of sweep) {
-                    try {
-                        await captureSurface(page, surface, width, settings);
-                    }
-                    catch (e) {
-                        failures.push(`${surface.key} @ ${width}: ${e.message}`);
-                    }
-                }
-            }
-            if (failures.length) {
-                throw new Error(`styleproof crawl-capture: ${failures.length} surface(s) failed:\n${failures.join('\n')}`);
-            }
+            // 2. Capture each discovered surface, aggregating per-surface failures.
+            await sweepCrawlSurfaces(page, captureSurfaces, settings);
         });
     });
 }

package/dist/variant-crawler.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { captureStyleMap } from './capture.js';
 import { diffStyleMaps } from './diff.js';
+import { DANGER_SOURCE } from './danger.js';
 function slug(value) {
     return (value
         .toLowerCase()
@@ -39,8 +40,11 @@ function liveKey(candidate) {
 function liveSelector(candidate) {
     return candidate.path;
 }
+// `dangerSource` is the shared destructive-label pattern (see {@link DANGER_SOURCE}),
+// passed in because this function is serialized into the browser and can't close over
+// a Node `RegExp`.
 // fallow-ignore-next-line complexity
-function collectCandidates() {
+function collectCandidates(dangerSource) {
     const controls = [
         '[aria-expanded]',
         '[aria-haspopup]',
@@ -53,7 +57,7 @@ function collectCandidates() {
         'select',
         'form',
     ].join(',');
-    const dangerous = /\b(delete|remove|destroy|logout|log out|sign out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect)\b/i;
+    const dangerous = new RegExp(dangerSource, 'i');
     const esc = (value) => CSS.escape(value);
     const quote = (value) => JSON.stringify(value);
     const visible = (el) => {
@@ -93,7 +97,15 @@ function collectCandidates() {
         return pathSelector(el);
     };
     const labelFor = (el) => {
-        const own = (el.getAttribute('aria-label') || el.getAttribute('name') || el.textContent || '').trim();
+        // Include `title` so an icon-only control (no text, no aria-label) announcing
+        // itself via a native tooltip — `<button title="Delete">🗑</button>` — still
+        // yields a real label. Without it the label is "button", slipping past the
+        // destructive guard below that this harvester's clicks must respect.
+        const own = (el.getAttribute('aria-label') ||
+            el.getAttribute('name') ||
+            el.textContent ||
+            el.getAttribute('title') ||
+            '').trim();
         return own.replace(/\s+/g, ' ').slice(0, 80) || el.tagName.toLowerCase();
     };
     const reasonFor = (el) => {
@@ -144,7 +156,7 @@ function collectCandidates() {
     return out;
 }
 async function discoverCandidates(page) {
-    return page.evaluate(collectCandidates);
+    return page.evaluate(collectCandidates, DANGER_SOURCE);
 }
 async function perform(page, candidate) {
     const target = page.locator(candidate.selector).first();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.17.0",
+  "version": "3.19.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",