An open source design system that's fully customizable and agent ready
TypeScript
fix(ci): retry visual promotion from archived acceptance (#5595)
Cindy Zhang9fb6144691f4
diff --git a/.github/scripts/visual-gate/lib/canonical-png.mjs b/.github/scripts/visual-gate/lib/canonical-png.mjsnew file mode 100644index 0000000000..b050bb58e9--- /dev/null+++ b/.github/scripts/visual-gate/lib/canonical-png.mjs@@ -0,0 +1,29 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {createRequire} from 'node:module';++const require = createRequire(import.meta.url);++export const CANONICAL_PNG_OPTIONS = Object.freeze({+ bitDepth: 8,+ colorType: 6,+ deflateChunkSize: 32 * 1024,+ deflateLevel: 9,+ deflateStrategy: 3,+ filterType: -1,+ inputColorType: 6,+ inputHasAlpha: true,+});++export function canonicalizePng(bytes) {+ const {PNG} = require('pngjs');+ const image = PNG.sync.read(bytes, {checkCRC: true});+ return {+ bytes: PNG.sync.write(+ {data: image.data, height: image.height, width: image.width},+ {...CANONICAL_PNG_OPTIONS},+ ),+ height: image.height,+ width: image.width,+ };+}diff --git a/.github/scripts/visual-gate/lib/canonical-png.test.mjs b/.github/scripts/visual-gate/lib/canonical-png.test.mjsnew file mode 100644index 0000000000..d04e70554c--- /dev/null+++ b/.github/scripts/visual-gate/lib/canonical-png.test.mjs@@ -0,0 +1,56 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import {PNG} from 'pngjs';++import {CANONICAL_PNG_OPTIONS, canonicalizePng} from './canonical-png.mjs';++function image(red, green = 0, blue = 0) {+ const value = new PNG({width: 2, height: 2});+ for (let offset = 0; offset < value.data.length; offset += 4) {+ value.data[offset] = red;+ value.data[offset + 1] = green;+ value.data[offset + 2] = blue;+ value.data[offset + 3] = 255;+ }+ return value;+}++describe('canonical PNG encoding', () => {+ it('pins every encoder option that affects durable bytes', () => {+ expect(CANONICAL_PNG_OPTIONS).toEqual({+ bitDepth: 8,+ colorType: 6,+ deflateChunkSize: 32 * 1024,+ deflateLevel: 9,+ deflateStrategy: 3,+ filterType: -1,+ inputColorType: 6,+ inputHasAlpha: true,+ });+ });++ it('normalizes compression and metadata without changing pixels', () => {+ const plain = PNG.sync.write(image(0, 0, 255));+ const withMetadata = image(0, 0, 255);+ withMetadata.gamma = 0.45455;+ const alternate = PNG.sync.write(withMetadata, {+ deflateLevel: 0,+ deflateStrategy: 0,+ filterType: 0,+ });++ expect(alternate).not.toEqual(plain);+ expect(PNG.sync.read(alternate).data).toEqual(PNG.sync.read(plain).data);+ expect(canonicalizePng(alternate).bytes).toEqual(+ canonicalizePng(plain).bytes,+ );+ });++ it('keeps changed pixels distinct and rejects corrupt bytes', () => {+ expect(canonicalizePng(PNG.sync.write(image(255))).bytes).not.toEqual(+ canonicalizePng(PNG.sync.write(image(0, 255))).bytes,+ );+ expect(() => canonicalizePng(Buffer.from('not a PNG'))).toThrow();+ });+});diff --git a/.github/scripts/visual-gate/publish-pr-report.mjs b/.github/scripts/visual-gate/publish-pr-report.mjsindex 15c10ef824..36a74ca4b3 100644--- a/.github/scripts/visual-gate/publish-pr-report.mjs+++ b/.github/scripts/visual-gate/publish-pr-report.mjs@@ -13,9 +13,9 @@import {createHash} from 'node:crypto';import fs from 'node:fs';import path from 'node:path';-import {PNG} from 'pngjs';import {incomparable} from './lib/baseline.mjs';+import {canonicalizePng} from './lib/canonical-png.mjs';import {buildVerdict, compareCaptures} from './lib/compare.mjs';import {shotKey} from './lib/plan.mjs';import {renderReport} from './lib/report.mjs';@@ -35,7 +35,10 @@ const headSha = flag('head-sha') ?? '';const runId = flag('run-id') ?? '';const runAttempt = flag('run-attempt') ?? '';const config = JSON.parse(- fs.readFileSync(new URL('./visual-gate.config.json', import.meta.url), 'utf8'),+ fs.readFileSync(+ new URL('./visual-gate.config.json', import.meta.url),+ 'utf8',+ ),);const KEY = /^[A-Za-z0-9._-]{1,240}$/;@@ -64,25 +67,33 @@ function shaFile(file) {function copyPng(source, target, label) {if (!fs.existsSync(source)) fail(`${label} is missing`);const stat = fs.lstatSync(source);- if (!stat.isFile() || stat.isSymbolicLink()) fail(`${label} is not a regular file`);- if (stat.size <= 0 || stat.size > MAX_PNG_BYTES) fail(`${label} has invalid size`);+ if (!stat.isFile() || stat.isSymbolicLink())+ fail(`${label} is not a regular file`);+ if (stat.size <= 0 || stat.size > MAX_PNG_BYTES)+ fail(`${label} has invalid size`);let image;try {- image = PNG.sync.read(fs.readFileSync(source), {checkCRC: true});+ image = canonicalizePng(fs.readFileSync(source));} catch (error) {fail(`${label} is not a valid PNG: ${error.message}`);}- if (image.width <= 0 || image.height <= 0 || image.width > MAX_EDGE || image.height > MAX_EDGE) {+ if (+ image.width <= 0 ||+ image.height <= 0 ||+ image.width > MAX_EDGE ||+ image.height > MAX_EDGE+ ) {fail(`${label} has invalid dimensions ${image.width}x${image.height}`);}fs.mkdirSync(path.dirname(target), {recursive: true});- fs.writeFileSync(target, PNG.sync.write(image));+ fs.writeFileSync(target, image.bytes);return image;}if (!Number.isSafeInteger(pr) || pr <= 0) fail('invalid PR number');if (!SHA.test(headSha)) fail('invalid trusted head SHA');-if (!/^\d+$/.test(runId) || !/^\d+$/.test(runAttempt)) fail('invalid run identity');+if (!/^\d+$/.test(runId) || !/^\d+$/.test(runAttempt))+ fail('invalid run identity');if (scope?.hasStableVisual !== true ||typeof scope.broadStableVisual !== 'boolean' ||@@ -95,7 +106,10 @@ if (}const manifestPath = path.join(input, 'manifest.json');-if (!fs.existsSync(manifestPath) || fs.lstatSync(manifestPath).isSymbolicLink()) {+if (+ !fs.existsSync(manifestPath) ||+ fs.lstatSync(manifestPath).isSymbolicLink()+) {fail('trusted capture manifest is missing or symbolic');}const manifest = readJSON(manifestPath);@@ -128,7 +142,8 @@ const blocker = incomparable(baselineManifest, manifest);if (blocker) fail(`baseline is not comparable: ${blocker}`);const entries = Object.entries(manifest.shots);-if (entries.length > MAX_SHOTS) fail(`trusted capture exceeds ${MAX_SHOTS} shots`);+if (entries.length > MAX_SHOTS)+ fail(`trusted capture exceeds ${MAX_SHOTS} shots`);for (const [key, shot] of entries) {if (!KEY.test(key) ||@@ -154,19 +169,30 @@ const sourceNames = fs.existsSync(sourceShots)? fs.readdirSync(sourceShots, {withFileTypes: true}): [];const sourceKeys = sourceNames.map(entry => {- if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith('.png')) {+ if (+ !entry.isFile() ||+ entry.isSymbolicLink() ||+ !entry.name.endsWith('.png')+ ) {fail(`unexpected capture entry ${entry.name}`);}return entry.name.slice(0, -4);});-if (sourceKeys.length !== entries.length || sourceKeys.some(key => !manifest.shots[key])) {+if (+ sourceKeys.length !== entries.length ||+ sourceKeys.some(key => !manifest.shots[key])+) {fail('capture PNG set does not match its manifest');}const trustedManifest = {...manifest, shots: {}};for (const [key, shot] of entries) {const target = path.join(output, 'current', `${key}.png`);- const image = copyPng(path.join(sourceShots, `${key}.png`), target, `shots/${key}.png`);+ const image = copyPng(+ path.join(sourceShots, `${key}.png`),+ target,+ `shots/${key}.png`,+ );trustedManifest.shots[key] = {...shot,sha256: shaFile(target),@@ -179,8 +205,10 @@ const baselineEntries = Object.entries(baselineManifest.shots ?? {});const expected = scope.broadStableVisual? baselineEntries.map(([key]) => key): baselineEntries- .filter(([, shot]) =>- scope.stableComponents.includes(shot.component) || scope.stableThemes.includes(shot.theme),+ .filter(+ ([, shot]) =>+ scope.stableComponents.includes(shot.component) ||+ scope.stableThemes.includes(shot.theme),).map(([key]) => key);if (entries.length === 0 && expected.length === 0) {@@ -203,7 +231,11 @@ const verdict = buildVerdict({comparison,currentManifest: trustedManifest,baselineManifest,- targeting: {unexercisedOverrides: [], undeclaredTargets: [], uncoveredTargets: []},+ targeting: {+ unexercisedOverrides: [],+ undeclaredTargets: [],+ uncoveredTargets: [],+ },failures: [],context: {...manifest.context, trustedScope: scope},});@@ -212,17 +244,31 @@ const beforeSha256 = {};for (const change of verdict.changes) {const key = change.key;const baselineFile = path.join(baseline, 'shots', `${key}.png`);- copyPng(baselineFile, path.join(output, 'before', `${key}.png`), `baseline/${key}.png`);- fs.copyFileSync(path.join(output, 'current', `${key}.png`), path.join(output, 'after', `${key}.png`));+ copyPng(+ baselineFile,+ path.join(output, 'before', `${key}.png`),+ `baseline/${key}.png`,+ );+ fs.copyFileSync(+ path.join(output, 'current', `${key}.png`),+ path.join(output, 'after', `${key}.png`),+ );beforeSha256[key] = shaFile(baselineFile);}for (const key of verdict.added) {- fs.copyFileSync(path.join(output, 'current', `${key}.png`), path.join(output, 'after', `${key}.png`));+ fs.copyFileSync(+ path.join(output, 'current', `${key}.png`),+ path.join(output, 'after', `${key}.png`),+ );beforeSha256[key] = null;}for (const key of verdict.removed) {const baselineFile = path.join(baseline, 'shots', `${key}.png`);- copyPng(baselineFile, path.join(output, 'before', `${key}.png`), `baseline/${key}.png`);+ copyPng(+ baselineFile,+ path.join(output, 'before', `${key}.png`),+ `baseline/${key}.png`,+ );beforeSha256[key] = shaFile(baselineFile);}@@ -263,8 +309,14 @@ const evidence = {};fs.rmSync(path.join(output, 'current'), {recursive: true, force: true});-fs.writeFileSync(path.join(output, 'evidence.json'), `${JSON.stringify(evidence, null, 2)}\n`);-fs.writeFileSync(path.join(output, 'verdict.json'), `${JSON.stringify(verdict, null, 2)}\n`);+fs.writeFileSync(+ path.join(output, 'evidence.json'),+ `${JSON.stringify(evidence, null, 2)}\n`,+);+fs.writeFileSync(+ path.join(output, 'verdict.json'),+ `${JSON.stringify(verdict, null, 2)}\n`,+);fs.writeFileSync(path.join(output, 'index.html'),renderReport(verdict, {diff --git a/.github/scripts/visual-gate/publish-pr-report.test.mjs b/.github/scripts/visual-gate/publish-pr-report.test.mjsindex 2a99b05cbb..dfc22c5643 100644--- a/.github/scripts/visual-gate/publish-pr-report.test.mjs+++ b/.github/scripts/visual-gate/publish-pr-report.test.mjs@@ -10,7 +10,16 @@ import {fileURLToPath} from 'node:url';import {afterEach, beforeEach, describe, expect, it} from 'vitest';import {PNG} from 'pngjs';-const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'publish-pr-report.mjs');+import {canonicalizePng} from './lib/canonical-png.mjs';++const SCRIPT = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ 'publish-pr-report.mjs',+);+const ACCEPTANCE_SCRIPT = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ 'visual-acceptance.mjs',+);const HEAD = 'a'.repeat(40);const RUN = '123456';const KEY = 'core-button--default__neutral-light';@@ -52,7 +61,10 @@ function writeBaseline(shots = {[KEY]: {shot: SHOT, bytes: png()}}) {const file = path.join(baseline, 'shots', `${key}.png`);fs.mkdirSync(path.dirname(file), {recursive: true});fs.writeFileSync(file, bytes);- manifestShots[key] = {...shot, sha256: createHash('sha256').update(bytes).digest('hex')};+ manifestShots[key] = {+ ...shot,+ sha256: createHash('sha256').update(bytes).digest('hex'),+ };}writeJSON(path.join(baseline, 'manifest.json'), {version: 1,@@ -64,7 +76,10 @@ function writeBaseline(shots = {[KEY]: {shot: SHOT, bytes: png()}}) {});}-function writeCapture(shots = {[KEY]: {shot: SHOT, bytes: png(0, 0, 255)}}, overrides = {}) {+function writeCapture(+ shots = {[KEY]: {shot: SHOT, bytes: png(0, 0, 255)}},+ overrides = {},+) {fs.rmSync(input, {recursive: true, force: true});const manifestShots = {};const shotsDir = path.join(input, 'shots');@@ -104,19 +119,35 @@ function run() {process.execPath,[SCRIPT,- '--input', input,- '--output', output,- '--baseline', baseline,- '--scope', scope,- '--pr', '42',- '--head-sha', HEAD,- '--run-id', RUN,- '--run-attempt', '1',+ '--input',+ input,+ '--output',+ output,+ '--baseline',+ baseline,+ '--scope',+ scope,+ '--pr',+ '42',+ '--head-sha',+ HEAD,+ '--run-id',+ RUN,+ '--run-attempt',+ '1',],{encoding: 'utf8'},);}+function runAcceptance(command, flags) {+ const args = [ACCEPTANCE_SCRIPT, command];+ for (const [name, value] of Object.entries(flags)) {+ args.push(`--${name}`, String(value));+ }+ return execFileSync(process.execPath, args, {encoding: 'utf8'});+}+beforeEach(() => {root = fs.mkdtempSync(path.join(os.tmpdir(), 'trusted-visual-'));input = path.join(root, 'input');@@ -136,9 +167,119 @@ beforeEach(() => {afterEach(() => fs.rmSync(root, {recursive: true, force: true}));describe('trusted PR visual publisher', () => {+ it('canonicalizes raw capture bytes through acceptance and promotion', () => {+ const rawImage = PNG.sync.read(png(0, 0, 255));+ rawImage.gamma = 0.45455;+ const rawAfter = PNG.sync.write(rawImage, {+ deflateLevel: 0,+ deflateStrategy: 0,+ filterType: 0,+ });+ writeCapture({[KEY]: {shot: SHOT, bytes: rawAfter}});+ run();++ const publishedAfter = fs.readFileSync(+ path.join(output, 'after', `${KEY}.png`),+ );+ expect(publishedAfter).toEqual(canonicalizePng(rawAfter).bytes);+ expect(publishedAfter).not.toEqual(rawAfter);+ const evidence = JSON.parse(+ fs.readFileSync(path.join(output, 'evidence.json'), 'utf8'),+ );+ expect(evidence.deltas[0].shot.sha256).toBe(+ createHash('sha256').update(publishedAfter).digest('hex'),+ );++ const pages = path.join(root, 'pages');+ fs.mkdirSync(path.join(pages, 'visual-gate'), {recursive: true});+ fs.cpSync(baseline, path.join(pages, 'visual-gate', 'baseline'), {+ recursive: true,+ });+ const evidenceDir = path.join(pages, 'pr', '42', 'visual', HEAD, RUN, '1');+ fs.mkdirSync(path.dirname(evidenceDir), {recursive: true});+ fs.cpSync(output, evidenceDir, {recursive: true});+ execFileSync('git', ['init', '-q', '-b', 'gh-pages'], {cwd: pages});+ execFileSync('git', ['config', 'user.name', 'Test'], {cwd: pages});+ execFileSync('git', ['config', 'user.email', '[email protected]'], {+ cwd: pages,+ });+ execFileSync('git', ['add', '.'], {cwd: pages});+ execFileSync('git', ['commit', '-qm', 'trusted evidence'], {cwd: pages});++ runAcceptance('accept', {+ pages,+ pr: 42,+ head: HEAD,+ 'run-id': RUN,+ 'run-attempt': 1,+ approver: 'maintainer',+ 'approver-id': 99,+ permission: 'maintain',+ 'effective-permission': 'maintain',+ 'comment-id': 1234,+ reason: 'The changed frame matches the approved component design.',+ });+ const acceptance = path.join(+ pages,+ 'visual-gate',+ 'acceptances',+ '42',+ HEAD,+ RUN,+ '1',+ 'acceptance.json',+ );+ expect(+ JSON.parse(fs.readFileSync(acceptance, 'utf8')).keys[0].afterSha256,+ ).toBe(createHash('sha256').update(publishedAfter).digest('hex'));++ const mergeImage = PNG.sync.read(rawAfter);+ mergeImage.gamma = 0.8;+ const rawMerged = PNG.sync.write(mergeImage, {+ deflateLevel: 1,+ deflateStrategy: 1,+ filterType: 4,+ });+ expect(rawMerged).not.toEqual(rawAfter);+ expect(canonicalizePng(rawMerged).bytes).toEqual(publishedAfter);+ const merged = path.join(root, 'merged');+ fs.mkdirSync(path.join(merged, 'shots'), {recursive: true});+ fs.writeFileSync(path.join(merged, 'shots', `${KEY}.png`), rawMerged);+ writeJSON(path.join(merged, 'manifest.json'), {+ version: 1,+ platform: 'linux-arm64',+ browser: 'chromium-140.0',+ viewport: {width: 1280, height: 900},+ capturedAt: '2026-08-27T09:00:00.000Z',+ context: {sha: 'd'.repeat(40)},+ shots: {+ [KEY]: {+ ...SHOT,+ sha256: createHash('sha256').update(rawMerged).digest('hex'),+ width: 2,+ height: 2,+ },+ },+ });++ runAcceptance('promote', {+ pages,+ acceptance,+ capture: merged,+ 'merge-sha': 'd'.repeat(40),+ });+ expect(+ fs.readFileSync(+ path.join(pages, 'visual-gate', 'baseline', 'shots', `${KEY}.png`),+ ),+ ).toEqual(publishedAfter);+ });+it('derives a changed verdict even when PR data claims pass', () => {expect(run()).toContain('trusted changed verdict');- const verdict = JSON.parse(fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'));+ const verdict = JSON.parse(+ fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'),+ );expect(verdict).toMatchObject({status: 'changed', counts: {changed: 1}});expect(fs.existsSync(path.join(output, 'before', `${KEY}.png`))).toBe(true);expect(fs.existsSync(path.join(output, 'after', `${KEY}.png`))).toBe(true);@@ -148,7 +289,9 @@ describe('trusted PR visual publisher', () => {it('derives pass only from a trusted capture matching the baseline', () => {writeCapture({[KEY]: {shot: SHOT, bytes: png()}});run();- const verdict = JSON.parse(fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'));+ const verdict = JSON.parse(+ fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'),+ );expect(verdict.status).toBe('pass');});@@ -164,7 +307,9 @@ describe('trusted PR visual publisher', () => {});writeCapture({[key]: {shot, bytes: png(0, 255, 0)}});run();- const verdict = JSON.parse(fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'));+ const verdict = JSON.parse(+ fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'),+ );expect(verdict).toMatchObject({status: 'changed', added: [key]});expect(fs.existsSync(path.join(output, 'after', `${key}.png`))).toBe(true);});@@ -172,20 +317,26 @@ describe('trusted PR visual publisher', () => {it('derives a removed baseline shot when trusted capture omits expected scope', () => {writeCapture({});run();- const verdict = JSON.parse(fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'));+ const verdict = JSON.parse(+ fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'),+ );expect(verdict).toMatchObject({status: 'changed', removed: [KEY]});expect(fs.existsSync(path.join(output, 'before', `${KEY}.png`))).toBe(true);});it('rejects a trusted capture that claims another run', () => {- const manifest = JSON.parse(fs.readFileSync(path.join(input, 'manifest.json'), 'utf8'));+ const manifest = JSON.parse(+ fs.readFileSync(path.join(input, 'manifest.json'), 'utf8'),+ );manifest.context.runId = '999';writeJSON(path.join(input, 'manifest.json'), manifest);expect(() => run()).toThrow(/identity mismatch/);});it('rejects traversal-shaped manifest keys', () => {- writeCapture({'../bad': {shot: {...SHOT, storyId: '../bad'}, bytes: png()}});+ writeCapture({+ '../bad': {shot: {...SHOT, storyId: '../bad'}, bytes: png()},+ });expect(() => run()).toThrow(/metadata is invalid/);});diff --git a/.github/scripts/visual-gate/visual-acceptance.mjs b/.github/scripts/visual-gate/visual-acceptance.mjsindex de728b9610..faadcf14d1 100644--- a/.github/scripts/visual-gate/visual-acceptance.mjs+++ b/.github/scripts/visual-gate/visual-acceptance.mjs@@ -11,13 +11,13 @@import {execFileSync} from 'node:child_process';import {createHash} from 'node:crypto';import fs from 'node:fs';-import {createRequire} from 'node:module';import path from 'node:path';import {isVisualAcceptanceEndpointMaintainer,isVisualAcceptanceRecordMaintainer,} from './authorization.mjs';+import {canonicalizePng} from './lib/canonical-png.mjs';import {readStoryIndex, shotKey, storiesInPackages} from './lib/plan.mjs';const args = process.argv.slice(2);@@ -76,14 +76,25 @@ function evidenceRoot(pages, pr, head) {}function evidenceAt(pages, pr, head, run, attempt) {- if (!Number.isSafeInteger(run) || run <= 0 || !Number.isSafeInteger(attempt) || attempt <= 0) {+ if (+ !Number.isSafeInteger(run) ||+ run <= 0 ||+ !Number.isSafeInteger(attempt) ||+ attempt <= 0+ ) {fail('invalid evidence run/attempt');}- const dir = path.join(evidenceRoot(pages, pr, head), String(run), String(attempt));- if (!fs.existsSync(dir)) fail(`no published evidence for run ${run}/${attempt}`);+ const dir = path.join(+ evidenceRoot(pages, pr, head),+ String(run),+ String(attempt),+ );+ if (!fs.existsSync(dir))+ fail(`no published evidence for run ${run}/${attempt}`);const evidence = readJSON(path.join(dir, 'evidence.json'));validateEvidence(evidence, {pr, head, run});- if (evidence.run.attempt !== attempt) fail('evidence attempt identity mismatch');+ if (evidence.run.attempt !== attempt)+ fail('evidence attempt identity mismatch');return {dir, evidence};}@@ -109,7 +120,8 @@ function latestEvidence(pages, pr, head, {required = true} = {}) {.filter(entry => entry.isDirectory() && /^\d+$/.test(entry.name)).map(entry => Number(entry.name)).sort((a, b) => b - a);- const dir = attempts.length > 0 ? path.join(runDir, String(attempts[0])) : runDir;+ const dir =+ attempts.length > 0 ? path.join(runDir, String(attempts[0])) : runDir;const evidence = readJSON(path.join(dir, 'evidence.json'));validateEvidence(evidence, {pr, head, run});if (attempts.length > 0 && evidence.run.attempt !== attempts[0]) {@@ -268,7 +280,14 @@ function recordPath(pages, pr, head, run, attempt) {}function pointerPath(pages, pr, head) {- return path.join(pages, 'visual-gate', 'acceptances', String(pr), head, 'current.json');+ return path.join(+ pages,+ 'visual-gate',+ 'acceptances',+ String(pr),+ head,+ 'current.json',+ );}function accept() {@@ -294,7 +313,13 @@ function accept() {if (!Number.isSafeInteger(commentId) || commentId <= 0)fail('invalid comment id');- const {dir: evidenceDir, evidence} = evidenceAt(pages, pr, head, runId, runAttempt);+ const {dir: evidenceDir, evidence} = evidenceAt(+ pages,+ pr,+ head,+ runId,+ runAttempt,+ );if (evidence.verdict.status !== 'changed' || evidence.deltas.length === 0) {fail('current visual bundle has no delta to accept');}@@ -506,7 +531,10 @@ function validateAcceptance(value, expected = {}) {validateShot(entry.shot, entry.key);if (expected.dir) {const archived = path.join(expected.dir, 'after', `${entry.key}.png`);- if (!fs.existsSync(archived) || shaFile(archived) !== entry.afterSha256) {+ if (+ !fs.existsSync(archived) ||+ shaFile(archived) !== entry.afterSha256+ ) {fail(`archived AFTER is missing or changed for ${entry.key}`);}}@@ -522,7 +550,9 @@ function validateAcceptance(value, expected = {}) {function trustedPlan() {const scope = readJSON(path.resolve(flag('scope')));- const baseline = readJSON(path.join(path.resolve(flag('baseline')), 'manifest.json'));+ const baseline = readJSON(+ path.join(path.resolve(flag('baseline')), 'manifest.json'),+ );const storybookDir = path.resolve(flag('storybook-dir'));const output = path.resolve(flag('output'));if (@@ -535,15 +565,25 @@ function trustedPlan() {}const baselineEntries = Object.entries(baseline.shots ?? {});- const baselineThemes = [...new Set(baselineEntries.map(([, shot]) => shot.theme))].filter(Boolean);+ const baselineThemes = [+ ...new Set(baselineEntries.map(([, shot]) => shot.theme)),+ ].filter(Boolean);const shots = scope.broadStableVisual- ? baselineEntries.map(([key, shot]) => ({...shot, key, reasons: ['trusted:broad']}))+ ? baselineEntries.map(([key, shot]) => ({+ ...shot,+ key,+ reasons: ['trusted:broad'],+ })): [];if (scope.stableComponents.length > 0 || scope.stableThemes.length > 0) {- const indexed = storiesInPackages(readStoryIndex(storybookDir, []), ['Core']);+ const indexed = storiesInPackages(readStoryIndex(storybookDir, []), [+ 'Core',+ ]);const stories = new Map();- const newTheme = scope.stableThemes.some(theme => !baselineThemes.includes(theme));+ const newTheme = scope.stableThemes.some(+ theme => !baselineThemes.includes(theme),+ );for (const [, shot] of baselineEntries) {if (newTheme ||@@ -554,9 +594,11 @@ function trustedPlan() {}}for (const story of indexed) {- if (scope.stableComponents.includes(story.component)) stories.set(story.id, story);+ if (scope.stableComponents.includes(story.component))+ stories.set(story.id, story);}- const themes = scope.stableThemes.length > 0 ? scope.stableThemes : baselineThemes;+ const themes =+ scope.stableThemes.length > 0 ? scope.stableThemes : baselineThemes;for (const story of stories.values()) {for (const theme of themes) {for (const mode of ['light', 'dark']) {@@ -579,7 +621,9 @@ function trustedPlan() {fail(`trusted visual plan has invalid size ${unique.length}`);}writeJSON(output, unique);- process.stdout.write(`Wrote ${unique.length} trusted PR shot(s) to ${output}.\n`);+ process.stdout.write(+ `Wrote ${unique.length} trusted PR shot(s) to ${output}.\n`,+ );}function plan() {@@ -596,19 +640,6 @@ function plan() {);}-const require = createRequire(import.meta.url);--function samePixels(first, second) {- const {PNG} = require('pngjs');- const a = PNG.sync.read(fs.readFileSync(first));- const b = PNG.sync.read(fs.readFileSync(second));- return (- a.width === b.width &&- a.height === b.height &&- Buffer.compare(a.data, b.data) === 0- );-}-function sameViewport(first, second) {return first?.width === second?.width && first?.height === second?.height;}@@ -686,9 +717,24 @@ function promote() {if (!fs.existsSync(recaptured) || !capturedShot) {fail(`post-merge capture is missing ${entry.key}`);}- if (capturedShot.sha256 !== shaFile(recaptured)) {+ const rawRecapturedSha256 = shaFile(recaptured);+ if (capturedShot.sha256 !== rawRecapturedSha256) {fail(`post-merge manifest hash does not match ${entry.key}`);}+ let canonical;+ try {+ canonical = canonicalizePng(fs.readFileSync(recaptured));+ } catch (error) {+ fail(+ `post-merge capture is not a valid PNG for ${entry.key}: ${error.message}`,+ );+ }+ const canonicalSha256 = shaBytes(canonical.bytes);+ if (canonicalSha256 !== entry.afterSha256) {+ fail(+ `canonical post-merge hash does not match accepted AFTER for ${entry.key}`,+ );+ }for (const field of ['storyId', 'theme', 'mode']) {if (capturedShot[field] !== entry.shot[field]) {fail(@@ -696,14 +742,24 @@ function promote() {);}}- if (!samePixels(acceptedAfter, recaptured)) {- fail(`post-merge pixels do not match accepted AFTER for ${entry.key}`);+ if (+ capturedShot.width !== canonical.width ||+ capturedShot.height !== canonical.height+ ) {+ fail(`post-merge dimensions do not match ${entry.key}`);}- actions.push({entry, baselineFile, recaptured, capturedShot});+ actions.push({+ entry,+ baselineFile,+ canonicalBytes: canonical.bytes,+ capturedShot: {...capturedShot, sha256: canonicalSha256},+ });}if (actions.every(action => action.alreadyPromoted)) {- process.stdout.write(`Accepted visual bundle for PR #${acceptance.pr} was already promoted.\n`);+ process.stdout.write(+ `Accepted visual bundle for PR #${acceptance.pr} was already promoted.\n`,+ );return;}@@ -713,7 +769,7 @@ function promote() {if (fs.existsSync(action.baselineFile)) fs.rmSync(action.baselineFile);delete manifest.shots[action.entry.key];} else {- fs.copyFileSync(action.recaptured, action.baselineFile);+ fs.writeFileSync(action.baselineFile, action.canonicalBytes);manifest.shots[action.entry.key] = action.capturedShot;}}@@ -763,5 +819,7 @@ switch (command) {promote();break;default:- fail('usage: visual-acceptance.mjs <accept|state|trusted-plan|plan|promote>');+ fail(+ 'usage: visual-acceptance.mjs <accept|state|trusted-plan|plan|promote>',+ );}diff --git a/.github/scripts/visual-gate/visual-acceptance.test.mjs b/.github/scripts/visual-gate/visual-acceptance.test.mjsindex c14c8539f9..9229fcc280 100644--- a/.github/scripts/visual-gate/visual-acceptance.test.mjs+++ b/.github/scripts/visual-gate/visual-acceptance.test.mjs@@ -10,6 +10,8 @@ import {fileURLToPath} from 'node:url';import {afterEach, beforeEach, describe, expect, it} from 'vitest';import {PNG} from 'pngjs';+import {canonicalizePng} from './lib/canonical-png.mjs';+const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)),'visual-acceptance.mjs',@@ -133,7 +135,15 @@ function writeEvidence({attempt = 1,status = 'changed',} = {}) {- const dir = path.join(pages, 'pr', '42', 'visual', HEAD, String(run), String(attempt));+ const dir = path.join(+ pages,+ 'pr',+ '42',+ 'visual',+ HEAD,+ String(run),+ String(attempt),+ );fs.mkdirSync(path.join(dir, 'after'), {recursive: true});if (status === 'changed' && kind !== 'removed') {fs.writeFileSync(path.join(dir, 'after', `${key}.png`), after);@@ -295,7 +305,9 @@ describe('visual acceptance', () => {delete record.decision.roleName;delete record.decision.effectivePermission;writeJSON(acceptanceFile(), record);- expect(JSON.parse(run('state', {pages, pr: 42, head: HEAD}))).toMatchObject({+ expect(+ JSON.parse(run('state', {pages, pr: 42, head: HEAD})),+ ).toMatchObject({state: 'success',reason: 'accepted',});@@ -383,10 +395,12 @@ describe('visual acceptance', () => {it('returns success for a clean trusted capture without acceptance', () => {writeEvidence({run: 124, status: 'pass'});- expect(JSON.parse(run('state', {pages, pr: 42, head: HEAD}))).toMatchObject({- state: 'success',- reason: 'clean',- });+ expect(JSON.parse(run('state', {pages, pr: 42, head: HEAD}))).toMatchObject(+ {+ state: 'success',+ reason: 'clean',+ },+ );});it('derives a trusted component plan from baseline themes and the Storybook index', () => {@@ -417,7 +431,9 @@ describe('visual acceptance', () => {'storybook-dir': storybook,output,});- expect(JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key)).toEqual([+ expect(+ JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),+ ).toEqual(['core-button--default__neutral-light','core-button--default__neutral-dark',]);@@ -441,7 +457,9 @@ describe('visual acceptance', () => {'storybook-dir': storybook,output,});- expect(JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key)).toEqual([+ expect(+ JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),+ ).toEqual(['core-button--default__new-theme-light','core-button--default__new-theme-dark',]);@@ -462,7 +480,9 @@ describe('visual acceptance', () => {'storybook-dir': root,output,});- expect(JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key)).toEqual([KEY]);+ expect(+ JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),+ ).toEqual([KEY]);});it('allows the trusted 520-shot broad plan through the capture CLI', () => {@@ -478,9 +498,13 @@ describe('visual acceptance', () => {}));const file = path.join(root, 'large-plan.json');writeJSON(file, plan);- const printed = execFileSync(process.execPath, [GATE, 'plan', '--plan-file', file], {- encoding: 'utf8',- });+ const printed = execFileSync(+ process.execPath,+ [GATE, 'plan', '--plan-file', file],+ {+ encoding: 'utf8',+ },+ );expect(printed).toContain('520 shots');});@@ -512,7 +536,9 @@ describe('visual acceptance', () => {'storybook-dir': storybook,output,});- expect(JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key)).toEqual([+ expect(+ JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),+ ).toEqual([KEY,'core-new--default__neutral-light','core-new--default__neutral-dark',@@ -521,7 +547,15 @@ describe('visual acceptance', () => {it('accepts a trusted 520-delta broad bundle', () => {const runId = 130;- const dir = path.join(pages, 'pr', '42', 'visual', HEAD, String(runId), '1');+ const dir = path.join(+ pages,+ 'pr',+ '42',+ 'visual',+ HEAD,+ String(runId),+ '1',+ );const deltas = [];fs.mkdirSync(path.join(dir, 'after'), {recursive: true});for (let index = 0; index < 520; index += 1) {@@ -631,7 +665,129 @@ describe('visual acceptance', () => {});});- it('rejects changed post-merge pixels and a stale merge identity', () => {+ it.each([+ {kind: 'changed', key: KEY, runId: 123},+ {kind: 'added', key: 'core-new--default__neutral-light', runId: 124},+ ])(+ 'canonicalizes equivalent raw PNG bytes when promoting a $kind shot',+ ({kind, key, runId}) => {+ if (kind === 'added') writeEvidence({kind, key, run: runId});+ run('accept', acceptanceFlags({'run-id': runId}));+ const record = acceptanceFile(runId);+ const accepted = fs.readFileSync(+ path.join(path.dirname(record), 'after', `${key}.png`),+ );+ const decoded = PNG.sync.read(accepted);+ decoded.gamma = 0.45455;+ const rawRecapture = PNG.sync.write(decoded, {deflateLevel: 0});+ expect(rawRecapture).not.toEqual(accepted);+ expect(PNG.sync.read(rawRecapture).data).toEqual(+ PNG.sync.read(accepted).data,+ );+ expect(canonicalizePng(rawRecapture).bytes).toEqual(accepted);++ const capture = path.join(root, `capture-${kind}`);+ fs.mkdirSync(path.join(capture, 'shots'), {recursive: true});+ fs.writeFileSync(path.join(capture, 'shots', `${key}.png`), rawRecapture);+ writeJSON(path.join(capture, 'manifest.json'), {+ version: 1,+ platform: 'linux-arm64',+ browser: 'chromium-140.0',+ viewport: {width: 1280, height: 900},+ capturedAt: '2026-08-26T22:00:00.000Z',+ context: {sha: MERGE},+ shots: {+ [key]: {+ ...SHOT,+ sha256: digest(rawRecapture),+ width: 2,+ height: 2,+ },+ },+ });++ expect(+ run('promote', {+ pages,+ acceptance: record,+ capture,+ 'merge-sha': MERGE,+ }),+ ).toContain('Promoted accepted visual bundle');+ expect(+ fs.readFileSync(+ path.join(pages, 'visual-gate', 'baseline', 'shots', `${key}.png`),+ ),+ ).toEqual(accepted);+ const baselineManifest = JSON.parse(+ fs.readFileSync(+ path.join(pages, 'visual-gate', 'baseline', 'manifest.json'),+ 'utf8',+ ),+ );+ expect(baselineManifest.shots[key].sha256).toBe(digest(accepted));+ },+ );++ it('promotes a removed shot without an AFTER hash or recaptured file', () => {+ writeEvidence({kind: 'removed', run: 125});+ run('accept', acceptanceFlags({'run-id': 125}));+ const capture = path.join(root, 'capture-removed');+ fs.mkdirSync(capture);+ writeJSON(path.join(capture, 'manifest.json'), {+ version: 1,+ platform: 'linux-arm64',+ browser: 'chromium-140.0',+ viewport: {width: 1280, height: 900},+ capturedAt: '2026-08-26T22:00:00.000Z',+ context: {sha: MERGE},+ shots: {},+ });++ expect(+ run('promote', {+ pages,+ acceptance: acceptanceFile(125),+ capture,+ 'merge-sha': MERGE,+ }),+ ).toContain('Promoted accepted visual bundle');+ expect(+ fs.existsSync(+ path.join(pages, 'visual-gate', 'baseline', 'shots', `${KEY}.png`),+ ),+ ).toBe(false);+ });++ it('rejects a merged recapture whose canonical pixels changed', () => {+ run('accept', acceptanceFlags());+ const capture = path.join(root, 'capture-changed-pixels');+ const changed = png(0, 255, 0);+ fs.mkdirSync(path.join(capture, 'shots'), {recursive: true});+ fs.writeFileSync(path.join(capture, 'shots', `${KEY}.png`), changed);+ writeJSON(path.join(capture, 'manifest.json'), {+ version: 1,+ platform: 'linux-arm64',+ browser: 'chromium-140.0',+ viewport: {width: 1280, height: 900},+ capturedAt: '2026-08-26T22:00:00.000Z',+ context: {sha: MERGE},+ shots: {+ [KEY]: {...SHOT, sha256: digest(changed), width: 2, height: 2},+ },+ });++ expect(+ fail('promote', {+ pages,+ acceptance: acceptanceFile(),+ capture,+ 'merge-sha': MERGE,+ }),+ ).toMatch(/canonical post-merge hash does not match accepted AFTER/);+ });++ it('rejects a stale merge identity', () => {run('accept', acceptanceFlags());const capture = path.join(root, 'capture');fs.mkdirSync(path.join(capture, 'shots'), {recursive: true});diff --git a/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs b/.github/scripts/visual-gate/visual-promotion-workflow.test.mjsnew file mode 100644index 0000000000..bc6f117e35--- /dev/null+++ b/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs@@ -0,0 +1,401 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {execFileSync, spawnSync} from 'node:child_process';+import {createHash} from 'node:crypto';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';++import {afterEach, describe, expect, it} from 'vitest';+import {PNG} from 'pngjs';++const ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../..',+);+const SCRIPT = path.join(+ ROOT,+ '.github',+ 'scripts',+ 'visual-gate',+ 'visual-acceptance.mjs',+);+const WORKFLOW = path.join(+ ROOT,+ '.github',+ 'workflows',+ 'visual-acceptance-promote.yml',+);+const HEAD = 'a'.repeat(40);+const MERGE = 'c'.repeat(40);+const KEY = 'core-button--default__neutral-light';+const RECORD_REL = '123/1/acceptance.json';+const SHOT = {+ storyId: 'core-button--default',+ title: 'Core/Button',+ name: 'Default',+ component: 'Button',+ theme: 'neutral',+ mode: 'light',+ reasons: ['component:Button'],+};++const roots = [];++afterEach(() => {+ for (const root of roots.splice(0)) {+ fs.rmSync(root, {recursive: true, force: true});+ }+});++function png(red, green = 0, blue = 0) {+ const image = new PNG({width: 2, height: 2});+ for (let offset = 0; offset < image.data.length; offset += 4) {+ image.data[offset] = red;+ image.data[offset + 1] = green;+ image.data[offset + 2] = blue;+ image.data[offset + 3] = 255;+ }+ return PNG.sync.write(image);+}++function digest(bytes) {+ return createHash('sha256').update(bytes).digest('hex');+}++function writeJSON(file, value) {+ fs.mkdirSync(path.dirname(file), {recursive: true});+ fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);+}++function git(cwd, ...args) {+ return execFileSync('git', args, {cwd, encoding: 'utf8'}).trim();+}++function runAcceptance(command, flags) {+ const args = [SCRIPT, command];+ for (const [name, value] of Object.entries(flags)) {+ args.push(`--${name}`, String(value));+ }+ return execFileSync(process.execPath, args, {encoding: 'utf8'});+}++function workflowStepScript(name) {+ const workflow = fs.readFileSync(WORKFLOW, 'utf8');+ const start = workflow.indexOf(` - name: ${name}\n`);+ expect(start).toBeGreaterThan(-1);+ const next = workflow.indexOf('\n - name:', start + 1);+ const step = workflow.slice(start, next === -1 ? undefined : next);+ const runMarker = ' run: |\n';+ const runStart = step.indexOf(runMarker);+ expect(runStart).toBeGreaterThan(-1);+ return step+ .slice(runStart + runMarker.length)+ .split('\n')+ .map(line => (line.startsWith(' ') ? line.slice(10) : line))+ .join('\n');+}++function writeCommandShims(root) {+ const bin = path.join(root, 'bin');+ fs.mkdirSync(bin);+ const gitShim = path.join(bin, 'git');+ fs.writeFileSync(+ gitShim,+ [+ '#!/bin/bash',+ 'set -e',+ 'REAL_GIT="$TEST_REAL_GIT"',+ 'if [ "${1:-}" = "clone" ]; then',+ ' args=("$@")',+ ' for ((i = 0; i < ${#args[@]}; i += 1)); do',+ ' case "${args[$i]}" in',+ ' https://x-access-token:*) args[$i]="file://${TEST_REMOTE}" ;;',+ ' esac',+ ' done',+ ' exec "$REAL_GIT" "${args[@]}"',+ 'fi',+ 'if [ "${1:-}" = "-C" ] && [ "${3:-}" = "push" ] && [ "${TEST_INJECT_RACE:-0}" = "1" ] && [ ! -e "$TEST_RACE_MARKER" ]; then',+ ' CLEANUP="$TEST_ROOT/cleanup-clone"',+ ' "$REAL_GIT" clone -q --branch gh-pages "file://${TEST_REMOTE}" "$CLEANUP"',+ ' "$REAL_GIT" -C "$CLEANUP" config user.name Test',+ ' "$REAL_GIT" -C "$CLEANUP" config user.email [email protected]',+ ' rm -rf "$CLEANUP/pr/${PR_NUMBER}"',+ ' "$REAL_GIT" -C "$CLEANUP" add -A',+ ' "$REAL_GIT" -C "$CLEANUP" commit -qm "cleanup merged preview"',+ ' "$REAL_GIT" -C "$CLEANUP" push -q origin gh-pages',+ ' touch "$TEST_RACE_MARKER"',+ 'fi',+ 'exec "$REAL_GIT" "$@"',+ '',+ ].join('\n'),+ );+ fs.chmodSync(gitShim, 0o755);++ const ghShim = path.join(bin, 'gh');+ fs.writeFileSync(ghShim, '#!/bin/sh\nprintf "%b\\n" "$GH_LATEST"\n');+ fs.chmodSync(ghShim, 0o755);++ const sleepShim = path.join(bin, 'sleep');+ fs.writeFileSync(sleepShim, '#!/bin/sh\nexit 0\n');+ fs.chmodSync(sleepShim, 0o755);+ return bin;+}++function makeFixture(mutate) {+ const root = fs.mkdtempSync(+ path.join(os.tmpdir(), 'visual-promotion-workflow-'),+ );+ roots.push(root);+ const pages = path.join(root, 'pages');+ fs.mkdirSync(pages);+ git(pages, 'init', '-q', '-b', 'gh-pages');+ git(pages, 'config', 'user.name', 'Test');+ git(pages, 'config', 'user.email', '[email protected]');++ const before = png(255);+ const after = png(0, 0, 255);+ const baselineShot = path.join(+ pages,+ 'visual-gate',+ 'baseline',+ 'shots',+ `${KEY}.png`,+ );+ fs.mkdirSync(path.dirname(baselineShot), {recursive: true});+ fs.writeFileSync(baselineShot, before);+ writeJSON(path.join(pages, 'visual-gate', 'baseline', 'manifest.json'), {+ version: 1,+ platform: 'linux-arm64',+ browser: 'chromium-140.0',+ viewport: {width: 1280, height: 900},+ shots: {+ [KEY]: {...SHOT, key: KEY, sha256: digest(before), width: 2, height: 2},+ },+ decisions: [],+ });++ const evidence = path.join(pages, 'pr', '42', 'visual', HEAD, '123', '1');+ fs.mkdirSync(path.join(evidence, 'after'), {recursive: true});+ fs.writeFileSync(path.join(evidence, 'after', `${KEY}.png`), after);+ writeJSON(path.join(evidence, 'evidence.json'), {+ version: 1,+ repo: 'facebook/astryx',+ pr: 42,+ headSha: HEAD,+ testedSha: 'b'.repeat(40),+ baseSha: 'd'.repeat(40),+ run: {id: 123, attempt: 1},+ capture: {+ platform: 'linux-arm64',+ browser: 'chromium-140.0',+ viewport: {width: 1280, height: 900},+ },+ deltas: [+ {+ key: KEY,+ kind: 'changed',+ beforeSha256: digest(before),+ shot: SHOT,+ },+ ],+ verdict: {version: 1, status: 'changed'},+ });+ git(pages, 'add', '.');+ git(pages, 'commit', '-qm', 'fixture');++ runAcceptance('accept', {+ pages,+ pr: 42,+ head: HEAD,+ 'run-id': 123,+ 'run-attempt': 1,+ approver: 'maintainer',+ 'approver-id': 99,+ permission: 'maintain',+ 'effective-permission': 'maintain',+ 'comment-id': 1234,+ reason: 'The new radius matches the approved component design.',+ });++ const acceptance = path.join(+ pages,+ 'visual-gate',+ 'acceptances',+ '42',+ HEAD,+ RECORD_REL,+ );+ const sandbox = path.join(root, 'sandbox');+ fs.mkdirSync(path.join(sandbox, '.github', 'scripts'), {recursive: true});+ fs.symlinkSync(+ path.join(ROOT, '.github', 'scripts', 'visual-gate'),+ path.join(sandbox, '.github', 'scripts', 'visual-gate'),+ );+ const plan = path.join(sandbox, 'accepted-plan.json');+ runAcceptance('plan', {acceptance, output: plan});++ const capture = path.join(sandbox, '.visual-merged');+ fs.mkdirSync(path.join(capture, 'shots'), {recursive: true});+ fs.writeFileSync(path.join(capture, 'shots', `${KEY}.png`), after);+ writeJSON(path.join(capture, 'manifest.json'), {+ version: 1,+ platform: 'linux-arm64',+ browser: 'chromium-140.0',+ viewport: {width: 1280, height: 900},+ capturedAt: '2026-08-27T08:00:00.000Z',+ context: {sha: MERGE},+ shots: {[KEY]: {...SHOT, sha256: digest(after), width: 2, height: 2}},+ });++ mutate?.({acceptance, baselineShot, pages});+ git(pages, 'add', '.');+ git(pages, 'commit', '-qm', 'record acceptance');++ const remote = path.join(root, 'remote.git');+ git(root, 'clone', '-q', '--bare', pages, remote);+ const bin = writeCommandShims(root);+ return {root, remote, sandbox, bin, after};+}++function runPromotion({fixture, latest = '123\\t1\\tcompleted', race = false}) {+ const marker = path.join(fixture.root, 'race-injected');+ const result = spawnSync(+ '/bin/bash',+ ['-c', workflowStepScript('Verify and promote the baseline')],+ {+ cwd: fixture.sandbox,+ encoding: 'utf8',+ env: {+ ...process.env,+ PATH: `${fixture.bin}:${process.env.PATH}`,+ GH_TOKEN: 'test-token',+ GITHUB_REPOSITORY: 'facebook/astryx',+ PR_NUMBER: '42',+ HEAD_SHA: HEAD,+ MERGE_SHA: MERGE,+ RECORD_REL,+ RUNNER_TEMP: path.join(fixture.root, 'runner'),+ GH_LATEST: latest,+ TEST_INJECT_RACE: race ? '1' : '0',+ TEST_RACE_MARKER: marker,+ TEST_REAL_GIT: execFileSync('which', ['git'], {+ encoding: 'utf8',+ }).trim(),+ TEST_REMOTE: fixture.remote,+ TEST_ROOT: fixture.root,+ },+ },+ );+ return {...result, marker};+}++describe('visual acceptance promotion workflow', () => {+ it('retries from the immutable record after cleanup wins the first push race', () => {+ const fixture = makeFixture();+ const result = runPromotion({fixture, race: true});+ expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(0);+ expect(fs.existsSync(result.marker)).toBe(true);++ const final = path.join(fixture.root, 'final');+ git(+ fixture.root,+ 'clone',+ '-q',+ '--branch',+ 'gh-pages',+ fixture.remote,+ final,+ );+ expect(fs.existsSync(path.join(final, 'pr', '42'))).toBe(false);+ expect(+ fs.readFileSync(+ path.join(final, 'visual-gate', 'baseline', 'shots', `${KEY}.png`),+ ),+ ).toEqual(fixture.after);+ const manifest = JSON.parse(+ fs.readFileSync(+ path.join(final, 'visual-gate', 'baseline', 'manifest.json'),+ 'utf8',+ ),+ );+ expect(manifest.decisions.at(-1)).toMatchObject({+ pr: 42,+ headSha: HEAD,+ mergeSha: MERGE,+ });+ });++ it.each([+ {+ name: 'a stale current pointer',+ mutate: ({pages}) =>+ writeJSON(+ path.join(+ pages,+ 'visual-gate',+ 'acceptances',+ '42',+ HEAD,+ 'current.json',+ ),+ {version: 1, run: 124, attempt: 1, record: '124/1/acceptance.json'},+ ),+ error: /newer visual acceptance superseded/,+ },+ {+ name: 'a superseded CI run',+ latest: '124\\t1\\tcompleted',+ error: /not from the latest completed CI attempt/,+ },+ {+ name: 'the wrong head identity',+ mutate: ({acceptance}) => {+ const record = JSON.parse(fs.readFileSync(acceptance, 'utf8'));+ record.headSha = 'e'.repeat(40);+ writeJSON(acceptance, record);+ },+ error: /record identity does not match this merged head/,+ },+ {+ name: 'a run identity that disagrees with the immutable path',+ mutate: ({acceptance}) => {+ const record = JSON.parse(fs.readFileSync(acceptance, 'utf8'));+ record.run.id = 124;+ writeJSON(acceptance, record);+ },+ latest: '124\\t1\\tcompleted',+ error: /record identity does not match this merged head/,+ },+ {+ name: 'tampered archived pixels',+ mutate: ({acceptance}) =>+ fs.writeFileSync(+ path.join(path.dirname(acceptance), 'after', `${KEY}.png`),+ png(0, 255, 0),+ ),+ error: /archived AFTER is missing or changed/,+ },+ {+ name: 'a changed baseline preimage',+ mutate: ({baselineShot}) =>+ fs.writeFileSync(baselineShot, png(0, 255, 0)),+ error: /baseline conflict/,+ },+ ])('fails closed for $name', ({mutate, latest, error}) => {+ const fixture = makeFixture(mutate);+ const result = runPromotion({fixture, latest});+ expect(result.status).not.toBe(0);+ expect(`${result.stdout}\n${result.stderr}`).toMatch(error);+ });++ it('does not consult ephemeral PR evidence during promotion', () => {+ const script = workflowStepScript('Verify and promote the baseline');+ expect(script).toContain('current.json');+ expect(script).toContain('LATEST_STATUS');+ expect(script).toContain('visual-acceptance.mjs promote');+ expect(script).not.toContain('visual-acceptance.mjs state');+ expect(script).not.toContain('/pr/');+ });+});diff --git a/.github/workflows/visual-acceptance-promote.yml b/.github/workflows/visual-acceptance-promote.ymlindex faa7053407..1e758d1077 100644--- a/.github/workflows/visual-acceptance-promote.yml+++ b/.github/workflows/visual-acceptance-promote.yml@@ -120,24 +120,25 @@ jobs:echo "::error::A newer visual acceptance superseded the reviewed record"exit 1fi+ ACCEPTED_IDENTITY=$(jq -er '[.pr, .headSha, .run.id, .run.attempt] | @tsv' \+ "$PAGES/$RECORD")+ IFS=$'\t' read -r ACCEPTED_PR ACCEPTED_HEAD ACCEPTED_RUN ACCEPTED_ATTEMPT <<< "$ACCEPTED_IDENTITY"+ if [ "$ACCEPTED_PR" != "$PR_NUMBER" ] || \+ [ "$ACCEPTED_HEAD" != "$HEAD_SHA" ] || \+ [ "$RECORD_REL" != "${ACCEPTED_RUN}/${ACCEPTED_ATTEMPT}/acceptance.json" ]; then+ echo "::error::Visual acceptance record identity does not match this merged head"+ exit 1+ fiLATEST=$(gh api \"repos/${GITHUB_REPOSITORY}/actions/runs?event=pull_request&head_sha=${HEAD_SHA}&per_page=100" \--jq '[.workflow_runs[] | select(.name == "CI")][0] | [.id, .run_attempt, .status] | @tsv')IFS=$'\t' read -r LATEST_RUN LATEST_ATTEMPT LATEST_STATUS <<< "$LATEST"- ACCEPTED_RUN=$(jq -r '.run.id' "$PAGES/$RECORD")- ACCEPTED_ATTEMPT=$(jq -r '.run.attempt' "$PAGES/$RECORD")if [ "$LATEST_RUN" != "$ACCEPTED_RUN" ] || \[ "$LATEST_ATTEMPT" != "$ACCEPTED_ATTEMPT" ] || \[ "$LATEST_STATUS" != "completed" ]; thenecho "::error::Accepted evidence is not from the latest completed CI attempt"exit 1fi- node .github/scripts/visual-gate/visual-acceptance.mjs state \- --pages "$PAGES" --pr "$PR_NUMBER" --head "$HEAD_SHA" > "$RUNNER_TEMP/promotion-state.json"- if [ "$(jq -r '.state + ":" + .reason' "$RUNNER_TEMP/promotion-state.json")" != "success:accepted" ]; then- echo "::error::Accepted evidence is no longer the latest visual result"- exit 1- finode .github/scripts/visual-gate/visual-acceptance.mjs promote \--pages "$PAGES" \--acceptance "$PAGES/$RECORD" \