styleproof 3.16.0 → 3.18.0

package/dist/report.js

@@ -385,6 +385,14 @@ export function prettyLabel(p, cls) {
     const first = cls.split(/\s+/)[0] ?? '';
     return /^[a-z][a-z0-9-]*$/.test(first) ? `${tag}.${first}` : tag;
 }
+// Surface keys originate from artifact filenames — attacker-controlled in the
+// fork capture/report split, and they flow into the PRIVILEGED PR-comment summary
+// (the Action slices report.md above the first `### `). Strip the Markdown/HTML
+// control characters (`` ` ``, [ ] ( ), < >, |) that could inject a link, image,
+// or table into that bot comment. Escaping at the render boundary — the keys stay
+// legible; only the injection surface is removed. (Crop FILENAMES are separately
+// restricted to [a-z0-9-]; this is the display-side equivalent.)
+const safeKey = (s) => s.replace(/[`[\]()<>|]/g, '-');
 const surfaceBase = (s) => s.replace(/@\d+$/, '');
 const surfaceWidth = (s) => Number(s.match(/@(\d+)$/)?.[1] ?? 0);
 function pushSurfaceWidth(byBase, base, surface) {
@@ -396,7 +404,7 @@ function renderSurfaceGroups(byBase) {
     return [...byBase]
         .map(([base, ws]) => {
         const widths = ws.filter((w) => w > 0).sort((a, b) => b - a);
-        return widths.length ? `${base} @ ${widths.join(', ')}` : base;
+        return widths.length ? `${safeKey(base)} @ ${widths.join(', ')}` : safeKey(base);
     })
         .join(' · ');
 }
@@ -821,7 +829,7 @@ function renderContentSurface(ctx, surface, changes, seq) {
     const mapB = loadStyleMap(findCapture(ctx.afterDir, surface));
     const pngA = readPng(path.join(ctx.beforeDir, `${surface}.png`));
     const pngB = readPng(path.join(ctx.afterDir, `${surface}.png`));
-    const md = ['', `### \`${surface}\` · ${changes.length} content change(s)`];
+    const md = ['', `### \`${safeKey(surface)}\` · ${changes.length} content change(s)`];
     for (const c of changes) {
         seq++;
         md.push('', `**\`${prettyLabel(c.path, c.cls)}\`**`, '', `- before: \`${clipText(c.before) || '(empty)'}\``, `- after: \`${clipText(c.after) || '(empty)'}\``, ...contentCropLines(ctx, surface, c, mapA, mapB, pngA, pngB, seq));
@@ -888,7 +896,7 @@ function coverageLine(cov) {
     if (cov.basis === 'complete')
         return `- **Coverage** — ✓ complete (all ${cov.registrySize} registered surface(s) captured)`;
     if (cov.basis === 'incomplete')
-        return `- **Coverage** — ✗ INCOMPLETE (${cov.uncovered.length} registered surface(s) not captured: ${cov.uncovered.join(', ')})`;
+        return `- **Coverage** — ✗ INCOMPLETE (${cov.uncovered.length} registered surface(s) not captured: ${cov.uncovered.map(safeKey).join(', ')})`;
     return '- **Coverage** — ⚠ not asserted (no `expected` registry; certifies only the captured surfaces)';
 }
 function determinismLine(det) {
@@ -900,7 +908,7 @@ function determinismLine(det) {
 }
 function inventoryLine(inv) {
     if (inv.unexplained.length > 0) {
-        const keys = inv.unexplained.map((i) => i.key);
+        const keys = inv.unexplained.map((i) => safeKey(i.key));
         return `- **Inventory** — ⚠ ${inv.unexplained.length} navigable affordance(s) removed, unacknowledged: ${keys.slice(0, 8).join(', ')}${keys.length > 8 ? ', …' : ''}`;
     }
     if (inv.delta.removed.length > 0)
@@ -1176,7 +1184,7 @@ function renderNewSurface(p, ctx, cropSeq) {
     const png = readPng(path.join(srcDir, `${p.sd.surface}.png`));
     const md = [
         '',
-        `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`,
+        `### \`${safeKey(p.sd.surface)}\` · new surface ${NEW_SURFACE_MARKER}`,
         '',
         `_${formatSurfaceWithContext(p.sd.surface, map)}_`,
     ];
@@ -1196,6 +1204,31 @@ function renderNewSurface(p, ctx, cropSeq) {
     md.push('', `_No baseline to compare against — this surface is new. Review and approve it before it becomes part of the baseline._`);
     return { md, json, cropSeq };
 }
+/** The one-time banner where report.md switches from full detail to one-line
+ *  summaries, so the reader knows nothing is missing — only relocated to report.json. */
+function cappedNoticeLines(budget) {
+    return [
+        '',
+        '## … more changed surfaces (summarized to keep this report renderable)',
+        '',
+        `_This report reached its ~${Math.round(budget / 1000)} KB display budget (GitHub does not render ` +
+            `markdown past ~512 KB), so the surfaces below are listed as one-liners. Their full property ` +
+            `tables are in \`report.json\` and their crops in \`crops/\` — the certification above covers every ` +
+            `surface; only the inline detail is capped._`,
+        '',
+    ];
+}
+/** One-line summary for a changed surface whose full detail was budget-capped: its
+ *  name (and how many surfaces share the identical change) · change count · a crop
+ *  link so the reviewer can still see it without opening report.json. */
+function compactChangeSummary(cg, json, img) {
+    const surface = safeKey(cg.rep.sd.surface);
+    const more = cg.surfaces.length > 1 ? ` (+${cg.surfaces.length - 1} more)` : '';
+    const regions = json.regions ?? [];
+    const composite = regions[0]?.images?.composite;
+    const link = composite ? ` — [crop](${img(composite)})` : '';
+    return `- \`${surface}\`${more} · ${cg.rep.findings.length} change(s)${link}`;
+}
 export function generateStyleMapReport(opts) {
     const { beforeDir, afterDir, outDir, imageBaseUrl = '', 
     // Tighter than before (was 24) so the change fills the frame — the annotation
@@ -1203,7 +1236,7 @@ export function generateStyleMapReport(opts) {
     pad: padBy = 12, minWidth = 320, minHeight = 180, maxHeight = 1600, zoomBelow = 64, 
     // More, smaller crops before collapsing (was 6), so distinct changes get their
     // own focused frame rather than one wide merged one.
-    maxCrops = 8, foldDetailsAt = 0, } = opts;
+    maxCrops = 8, foldDetailsAt = 0, maxReportBytes = 400_000, } = opts;
     const includeNoise = opts.includeLayoutNoise ?? false;
     const includeContent = opts.includeContent ?? false;
     const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
@@ -1261,18 +1294,38 @@ export function generateStyleMapReport(opts) {
     }));
     let totalFindings = 0;
     let cropSeq = 0;
+    // report.md must stay renderable — GitHub refuses to render markdown past ~512 KB.
+    // Emit full detail greedily until the byte budget is reached, then list any remaining
+    // surfaces as one-liners. The exhaustive per-row detail is always in report.json and
+    // every crop in crops/, so the cap changes what's shown inline, never what's certified.
+    let reportBytes = md.join('\n').length;
+    let capped = false;
+    const emitDetail = (detail, summary) => {
+        const cost = detail.join('\n').length + 1;
+        if (!capped && reportBytes + cost <= maxReportBytes) {
+            md.push(...detail);
+            reportBytes += cost;
+            return;
+        }
+        if (!capped) {
+            md.push(...cappedNoticeLines(maxReportBytes));
+            capped = true;
+        }
+        md.push(summary);
+        reportBytes += summary.length + 1;
+    };
     for (const cg of changeGroups) {
         const r = renderChangeGroup(cg, ctx, maxCrops, cropSeq);
-        md.push(...r.md);
         json.push(r.json);
         totalFindings += r.findingCount;
         cropSeq = r.cropSeq;
+        emitDetail(r.md, compactChangeSummary(cg, r.json, img));
     }
     for (const p of missing) {
         const r = renderNewSurface(p, ctx, cropSeq);
-        md.push(...r.md);
         json.push(r.json);
         cropSeq = r.cropSeq;
+        emitDetail(r.md, `- \`${safeKey(p.sd.surface)}\` · new surface`);
     }
     md.push(...contentSection.md);
     const reportMdPath = path.join(outDir, 'report.md');

package/dist/runner.d.ts

@@ -255,25 +255,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

@@ -4,8 +4,9 @@ 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 { 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')
@@ -473,6 +474,17 @@ function writeCoverageLedgerTest(settings, dir, expected, exclude) {
         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);
@@ -498,6 +510,8 @@ export function defineStyleMapCapture(options) {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         if (dir)
             writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
+        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 +555,91 @@ 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.
+        if (dir)
+            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
         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) => {
@@ -592,35 +659,8 @@ export function defineCrawlCapture(options) {
             // 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/package.json

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