styleproof 3.20.0 → 4.0.0

package/dist/runner.js

@@ -1,10 +1,10 @@
 import { test, expect } from '@playwright/test';
 import fs from 'node:fs';
 import path from 'node:path';
-import { captureStyleMap, saveStyleMap, trackInflightRequests, } from './capture.js';
+import { captureStyleMap, saveStyleMap, trackInflightRequests, trackDataResidue, } from './capture.js';
 import { diffStyleMaps } from './diff.js';
 import { coverageGaps, coverageKeys, translateExpected, COVERAGE_LEDGER, } from './coverage.js';
-import { writeBrowserBuildSidecar } from './map-store.js';
+import { writeBrowserBuildSidecar, writeCaptureManifest } from './map-store.js';
 import { detectViewportWidths } from './breakpoints.js';
 import { selectCrawlLinks, crawlCoverageError } from './crawl.js';
 /** One-line description of the first drift finding, for the self-check error. */
@@ -476,6 +476,10 @@ async function captureSurface(page, surface, width, s) {
     // count toward the network-aware settle — a request that starts during navigation
     // fired its event before captureStyleMap could attach a listener of its own.
     const requests = trackInflightRequests(page);
+    // Same timing for the residue watcher: a data request that fails during navigation
+    // must be seen. Keyed on the BASE surface key so a liveStates split (`-loading`/
+    // `-loaded`) and every width dedupe to one `<surface>·<endpoint>` residue entry.
+    const residue = trackDataResidue(page, s.replayUrl, surface.metadata?.surfaceKey ?? surface.key);
     try {
         await surface.go(page);
         const map = await captureStyleMap(page, {
@@ -488,6 +492,9 @@ async function captureSurface(page, surface, width, s) {
         });
         if (s.selfCheck)
             await assertDeterministic(page, surface, map, s.captureText, requests.pending);
+        // Attach data-residue AFTER the self-check re-run so both runs' failures are folded
+        // (deduped in the watcher). Warn always; the recorded residue is what the gate reads.
+        attachDataResidue(map, residue.residue());
         const stem = path.join(s.baseDir, s.dir, `${surface.key}@${width}`);
         saveStyleMap(`${stem}.json.gz`, map);
         if (s.screenshots) {
@@ -499,6 +506,21 @@ async function captureSurface(page, surface, width, s) {
     }
     finally {
         requests.dispose();
+        residue.dispose();
+    }
+}
+/** Attach any observed data-residue to the map and NAME each failure on stderr — what
+ *  failed, what it means (fallback branch captured), what to do. One warning per
+ *  (surface, endpoint); the watcher already deduped across widths / the self-check. */
+function attachDataResidue(map, residue) {
+    if (!residue.length)
+        return;
+    map.dataResidue = residue;
+    for (const r of residue) {
+        // eslint-disable-next-line no-console
+        console.warn(`styleproof: surface '${r.surface}' — data request ${r.endpoint} FAILED during capture (${r.reason}). ` +
+            `The captured state renders this endpoint's fallback branch; states driven by its real responses are ` +
+            `uncaptured and unproven. Fixture it (page.route / liveStates) or acknowledge it in styleproof.data-residue.json.`);
     }
 }
 /**
@@ -527,6 +549,14 @@ export function resolveBaseDir(baseDir, env = process.env.STYLEPROOF_BASEDIR) {
 export function resolveScreenshots(screenshots, env = process.env.STYLEPROOF_SCREENSHOTS) {
     return screenshots ?? env !== '0';
 }
+/**
+ * The data-residue guard mode: `'gate'` (the v4 default) blocks the diff on an
+ * unacknowledged failing data endpoint; `'warn'` is the explicit opt-out that records +
+ * warns without gating. Single source of truth for the default, so the flip lives here.
+ */
+export function resolveDataResidue(mode) {
+    return mode ?? 'gate';
+}
 /**
  * Apply the capture defaults once, so explicit-surface and crawl capture can't
  * drift — the replay boundary, frozen clock and self-check policy resolve to the
@@ -541,6 +571,7 @@ function resolveSettings(c) {
         screenshots: resolveScreenshots(c.screenshots),
         replayFrom,
         replayUrl: c.replayUrl ?? process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**',
+        dataResidue: resolveDataResidue(c.dataResidue),
         freezeClock: c.freezeClock ?? true,
         clockTime: c.clockTime ?? '2025-01-01T00:00:00Z',
         selfCheck: c.selfCheck ?? defaultSelfCheck(replayFrom),
@@ -584,19 +615,42 @@ function writeCoverageLedgerTest(settings, dir, expected, exclude, captureSurfac
         // 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 };
+        // Carry the residue-gate mode in the bundle so styleproof-diff knows whether an
+        // unacknowledged failing endpoint should BLOCK ('gate', the v4 default) or only
+        // inform ('warn', the explicit opt-out). Recorded verbatim so the bundle is
+        // self-documenting; an absent field (older bundles) is still read as warn, so
+        // maps captured before this default flip never start gating retroactively.
+        const ledger = {
+            version: 1,
+            expected: ledgerExpected,
+            exclude,
+            determinism,
+            dataResidue: settings.dataResidue,
+        };
         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. */
+/** Record the real browser build into the capture bundle, then stamp the manifest. 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.
+ *
+ *  The manifest is stamped HERE, at the runner level, so every capture flow produces a
+ *  manifest-bearing dir — including a raw `STYLEMAP_DIR=x npx playwright test` run (the
+ *  fork capture workflow's shape), which never goes through the styleproof-map CLI. Since
+ *  v4 the diff refuses a map-bearing dir without one. It's written in the same test as
+ *  the sidecar (not a sibling test) because the manifest reads the sidecar back for
+ *  `browserVersion`, and fullyParallel gives sibling tests no ordering. styleproof-map
+ *  re-stamps a richer manifest (real spec hash, git identity) after the run; the runtime
+ *  fields the compare guard reads are the same either way. */
 function writeBrowserBuildTest(settings, dir) {
     test('styleproof browser build', ({ page }) => {
         const version = page.context().browser()?.version();
-        writeBrowserBuildSidecar(path.join(settings.baseDir, dir), version);
+        const outDir = path.join(settings.baseDir, dir);
+        writeBrowserBuildSidecar(outDir, version);
+        writeCaptureManifest({ dir: outDir, screenshots: settings.screenshots });
     });
 }
 export function defineStyleMapCapture(options) {

package/example/styleproof-approve.yml

@@ -0,0 +1,108 @@
+# StyleProof approval gate — copy to .github/workflows/ on your DEFAULT branch.
+#
+# issue_comment workflows only ever run from the default branch, so this must
+# live on main (not on the feature branch) to take effect. It flips the
+# `StyleProof` commit status when a write-access reviewer ticks the single
+# "Approve all changes" box in the StyleProof report comment — one tick signs
+# off every changed or new surface. Pair it with the Action's `require-approval: true` input and
+# either a branch-protection rule requiring the `StyleProof` status, or
+# `styleproof.config.json`'s `"blocking": true` to fail the job on unapproved
+# changes (the blocking option for repos without branch protection).
+name: StyleProof approve
+
+on:
+  issue_comment:
+    types: [edited] # ticking a checkbox edits the comment
+
+# statuses:write to flip the gate; pull-requests:read to resolve the PR head SHA;
+# issues:write only for the "needs write access" reply on an unauthorized tick.
+permissions:
+  statuses: write
+  pull-requests: read
+  issues: write
+
+jobs:
+  approve:
+    # A HUMAN editing the BOT's own StyleProof report comment on a PR. This is the
+    # trust gate, not the marker: it excludes the bot's own upsert-edits
+    # (sender is a Bot) and any attacker-authored comment (comment.user is a User),
+    # so the only edits that reach the logic are humans ticking boxes in our comment.
+    if: >-
+      github.event.issue.pull_request &&
+      github.event.comment.user.type == 'Bot' &&
+      github.event.sender.type == 'User' &&
+      contains(github.event.comment.body, '<!-- styleproof-report -->')
+    # ubuntu-latest is fine where you have GitHub-hosted Actions minutes. On a
+    # PRIVATE repo without them, this job silently fails to start — point it at
+    # the same self-hosted runner your CI uses, e.g. runs-on: [self-hosted, …].
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const STATUS = 'StyleProof'; // must match the Action's status-context input
+
+            // Re-fetch the comment so concurrent ticks all compute from the LATEST
+            // body and converge (the event payload is the body as of one edit). The
+            // body is untrusted — only ever pattern-matched here, never evaluated.
+            const fresh = await github.rest.issues.getComment({ ...context.repo, comment_id: context.payload.comment.id });
+            const body = fresh.data.body || '';
+
+            // Bind approval to the exact commit the report was generated for. A
+            // push after the report leaves this stale, so a new render can never
+            // inherit a green status.
+            const shaMatch = body.match(/<!-- styleproof-sha:([0-9a-f]{40}) -->/i);
+            if (!shaMatch) return;
+            const reportSha = shaMatch[1];
+
+            // One "Approve all changes" box signs off every changed or new surface.
+            // No box means nothing to approve, leave the status as the Action set it.
+            const allBox = body.split('\n').find((l) => /^\s*-\s+\[[ xX]\]\s+\*\*Approve all changes\*\*/.test(l));
+            if (!allBox) return;
+            const approved = /\[[xX]\]/.test(allBox);
+
+            // The human who toggled the box must have write access. (`sender` on an
+            // edited event is the editor; combined with the bot-authored + non-bot
+            // guards in `if:`, that's the person who ticked.)
+            const actor = context.payload.sender.login;
+            let perm = 'none';
+            try {
+              perm = (await github.rest.repos.getCollaboratorPermissionLevel({ ...context.repo, username: actor })).data.permission;
+            } catch {
+              /* not a collaborator → stays 'none', fails closed */
+            }
+            if (!['admin', 'maintain', 'write'].includes(perm)) {
+              await github.rest.issues.createComment({
+                ...context.repo,
+                issue_number: context.payload.issue.number,
+                body: `@${actor} — approving the StyleProof gate needs write access to this repo, so the check stays red.`,
+              });
+              return;
+            }
+
+            // Only ever stamp the exact reviewed commit. If the PR moved since the
+            // report was posted, do nothing — the Action re-posts (red) for the new SHA.
+            const pr = await github.rest.pulls.get({ ...context.repo, pull_number: context.payload.issue.number });
+            const headSha = pr.data.head.sha;
+            if (headSha !== reportSha) return;
+
+            // The status description is the source of truth for WHO approved, so a
+            // later report re-run (e.g. to clear a blocking check) can reconstruct
+            // "approved by @x" without this workflow having run again.
+            await github.rest.repos.createCommitStatus({
+              ...context.repo,
+              sha: headSha,
+              context: STATUS,
+              state: approved ? 'success' : 'failure',
+              description: approved ? `Approved by @${actor}` : 'Tick "Approve all changes" to sign off',
+            });
+
+            // Reflect the approver in the comment itself for instant feedback. Rebuild
+            // the box line from scratch (dropping any prior "approved by" suffix) so a
+            // re-tick by someone else updates it and an untick clears it. Editing our
+            // own comment via GITHUB_TOKEN never retriggers this workflow.
+            const boxRe = /^(\s*-\s+\[[ xX]\]\s+\*\*Approve all changes\*\*).*$/m;
+            const newBody = body.replace(boxRe, (_, head) => (approved ? `${head} — _approved by @${actor}_` : head));
+            if (newBody !== body) {
+              await github.rest.issues.updateComment({ ...context.repo, comment_id: context.payload.comment.id, body: newBody });
+            }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.20.0",
+  "version": "4.0.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",
@@ -46,6 +46,7 @@
   "files": [
     "dist",
     "bin",
+    "example/styleproof-approve.yml",
     "docs/demo-composite.png",
     "README.md",
     "CHANGELOG.md",
@@ -80,16 +81,18 @@
     "pngjs": "^7.0.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.2.0",
+    "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
     "@types/node": "^26.0.0",
     "@types/pngjs": "^6.0.5",
     "eslint": "^10.5.0",
+    "fallow": "^3.2.0",
     "globals": "^17.6.0",
+    "husky": "^9.1.7",
     "prettier": "^3.4.2",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.18.0",
-    "husky": "^9.1.7",
-    "fallow": "^3.2.0"
+    "typescript-eslint": "^8.18.0"
   }
 }