Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

pr-visual: show before, after, and diff in the PR comment (#5572)

Cindy Zhang0ac4e83df879
diff --git a/.github/scripts/generate-pr-comment.js b/.github/scripts/generate-pr-comment.js
index 882676aa33..7f66a6a072 100644
--- a/.github/scripts/generate-pr-comment.js
+++ b/.github/scripts/generate-pr-comment.js
@@ -133,7 +133,11 @@ if (visualFile) {
visualVerdict = null;
}
}
-const visualSection = buildVisualSection(visualVerdict, getArg('visual-report-url'));
+const visualSection = buildVisualSection(
+ visualVerdict,
+ getArg('visual-report-url'),
+ getArg('visual-image-url'),
+);
// Build bundle size section — one row per package the PR actually touched.
let bundleSection = '### Bundle Size Summary\n\n';
diff --git a/.github/scripts/lib/visual-format.js b/.github/scripts/lib/visual-format.js
index 3f06409660..1b719fe7f5 100644
--- a/.github/scripts/lib/visual-format.js
+++ b/.github/scripts/lib/visual-format.js
@@ -16,10 +16,11 @@ const {inline, num, safeUrl} = require('./report-text');
* the daily gate.
*
* @param {object|null} verdict - the gate's verdict.json, or null when the job did not run
- * @param {string} [reportUrl] - published report for this PR, if there is one
+ * @param {string} [reportUrl] - immutable published report for this run
+ * @param {string} [imageUrl] - immutable raw-image base for inline evidence
* @returns {string} markdown
*/
-function buildVisualSection(verdict, reportUrl) {
+function buildVisualSection(verdict, reportUrl, imageUrl) {
if (!verdict) return '';
// Verdict fields are report data: render them as literal inline text (and
@@ -54,6 +55,45 @@ function buildVisualSection(verdict, reportUrl) {
`| ${inline(change.component || change.title)} | ${inline(change.name)} | ${inline(change.theme)} | ${inline(change.mode)} | ${num(change.diffPixels).toLocaleString()} |`,
)
.join('\n');
+
+ // Put the evidence where the decision is made. A link to an artifact ZIP is
+ // not a visual review: it makes the reviewer download, unzip, and match file
+ // names before they can answer whether the after is correct. The static
+ // report is published beside the PR preview, and its first three deltas
+ // render directly in the comment; the full report carries the rest + wipe UI.
+ const reportBase = safeReportUrl
+ ? `${safeReportUrl.replace(/\/+$/, '')}/`
+ : null;
+ // GitHub comments fetch raw branch images directly. The repository's Pages
+ // deployment can be delayed or errored independently of the gh-pages push;
+ // coupling inline evidence to that deployment produced six broken images in
+ // the first live demo even though every PNG existed in the branch.
+ const imageBase = safeUrl(imageUrl)
+ ? `${safeUrl(imageUrl).replace(/\/+$/, '')}/`
+ : reportBase;
+ const evidence = imageBase
+ ? verdict.changes
+ .slice(0, 3)
+ .map(change => {
+ const key = encodeURIComponent(String(change.key ?? ''));
+ if (!key) return '';
+ const label = `${inline(change.component || change.title)} — ${inline(change.name)} — ${inline(change.theme)} ${inline(change.mode)}`;
+ return `
+<details open>
+<summary>${label}</summary>
+<table>
+<tr><th>Before</th><th>After</th><th>Diff</th></tr>
+<tr>
+<td><img src="${imageBase}before/${key}.png" width="300" alt="Before visual regression frame"></td>
+<td><img src="${imageBase}after/${key}.png" width="300" alt="After visual regression frame"></td>
+<td><img src="${imageBase}diff/${key}.png" width="300" alt="Pixel difference frame"></td>
+</tr>
+</table>
+</details>`;
+ })
+ .filter(Boolean)
+ .join('\n')
+ : '';
const more =
verdict.changes.length > 20
? `\n\n_and ${verdict.changes.length - 20} more._`
@@ -71,6 +111,8 @@ is updated deliberately, and this check never rewrites it.
|---|---|---|---|---|
${rows}${more}
+${evidence}
+
`;
}
diff --git a/.github/scripts/lib/visual-format.test.mjs b/.github/scripts/lib/visual-format.test.mjs
index e8b8e04cb3..bab8243237 100644
--- a/.github/scripts/lib/visual-format.test.mjs
+++ b/.github/scripts/lib/visual-format.test.mjs
@@ -105,6 +105,50 @@ describe('buildVisualSection', () => {
expect(section).toContain('and 5 more');
});
+ it('embeds before, after, and diff images for changed shots', () => {
+ const section = buildVisualSection(
+ verdict({
+ status: 'changed',
+ counts: {total: 2, unchanged: 1, changed: 1, added: 0, removed: 0, failed: 0},
+ changes: [
+ {
+ key: 'core-button--primary__y2k-light',
+ component: 'Button',
+ name: 'Primary',
+ theme: 'y2k',
+ mode: 'light',
+ diffPixels: 12,
+ },
+ ],
+ }),
+ 'https://facebook.github.io/astryx/pr/123/visual/head/run/',
+ 'https://raw.githubusercontent.com/facebook/astryx/gh-pages/pr/123/visual/head/run/',
+ );
+ expect(section).toContain(
+ 'https://raw.githubusercontent.com/facebook/astryx/gh-pages/pr/123/visual/head/run/before/core-button--primary__y2k-light.png',
+ );
+ expect(section).toContain('raw.githubusercontent.com/facebook/astryx/gh-pages/pr/123/visual/head/run/after/core-button--primary__y2k-light.png');
+ expect(section).toContain('raw.githubusercontent.com/facebook/astryx/gh-pages/pr/123/visual/head/run/diff/core-button--primary__y2k-light.png');
+ expect(section).toContain('<th>Before</th><th>After</th><th>Diff</th>');
+ });
+
+ it('embeds at most three deltas so the PR comment stays readable', () => {
+ const changes = Array.from({length: 5}, (_, index) => ({
+ key: `shot-${index}`,
+ component: 'C',
+ name: 'S',
+ theme: 't',
+ mode: 'light',
+ diffPixels: 1,
+ }));
+ const section = buildVisualSection(
+ verdict({status: 'changed', counts: {total: 5, changed: 5}, changes}),
+ 'https://example.com/visual/',
+ );
+ expect((section.match(/<details open>/g) ?? []).length).toBe(3);
+ expect(section).not.toContain('/before/shot-3.png');
+ });
+
it('reports a capture failure distinctly from a change', () => {
const section = buildVisualSection(
verdict({status: 'failed', counts: {total: 4, failed: 2, changed: 0}}),
diff --git a/.github/scripts/visual-gate/publish-pr-report.mjs b/.github/scripts/visual-gate/publish-pr-report.mjs
new file mode 100644
index 0000000000..eddeff4230
--- /dev/null
+++ b/.github/scripts/visual-gate/publish-pr-report.mjs
@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Turn an untrusted pr-visual artifact into publishable evidence.
+ *
+ * @input verdict.json + before/after/diff PNGs emitted by PR-controlled CI
+ * @output schema-validated, decoded/re-encoded PNGs and a report whose HTML is
+ * generated by DEFAULT-BRANCH code
+ *
+ * This script runs only in the trusted `workflow_run` publisher. It never
+ * imports or executes a file from the artifact. A fork may choose every byte
+ * in its artifact, so paths, counts, identity fields and image bytes are all
+ * validated before anything is copied onto the shared GitHub Pages origin.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {PNG} from 'pngjs';
+
+import {renderReport} from './lib/report.mjs';
+
+const args = process.argv.slice(2);
+const flag = name => {
+ const index = args.indexOf(`--${name}`);
+ return index === -1 ? null : args[index + 1];
+};
+
+const input = path.resolve(flag('input') ?? 'visual');
+const output = path.resolve(flag('output') ?? 'trusted-visual');
+const pr = Number(flag('pr'));
+const headSha = flag('head-sha') ?? '';
+const runId = flag('run-id') ?? '';
+const runAttempt = flag('run-attempt') ?? '';
+
+const KEY = /^[A-Za-z0-9._-]{1,240}$/;
+const SHA = /^[0-9a-f]{40}$/;
+const MAX_CHANGES = 240;
+const MAX_PNG_BYTES = 12 * 1024 * 1024;
+const MAX_EDGE = 5000;
+
+function fail(message) {
+ throw new Error(`visual evidence rejected: ${message}`);
+}
+
+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');
+
+const verdictPath = path.join(input, 'verdict.json');
+if (!fs.existsSync(verdictPath)) fail('verdict.json is missing');
+if (fs.lstatSync(verdictPath).isSymbolicLink()) fail('verdict.json is a symlink');
+const verdict = JSON.parse(fs.readFileSync(verdictPath, 'utf8'));
+
+if (verdict.version !== 1) fail(`unsupported verdict version ${verdict.version}`);
+if (!['pass', 'changed', 'failed', 'skipped'].includes(verdict.status)) {
+ fail(`invalid verdict status ${verdict.status}`);
+}
+if (String(verdict.context?.runId ?? '') !== runId) {
+ fail(`verdict run ${verdict.context?.runId ?? 'missing'} does not match ${runId}`);
+}
+if (verdict.context?.runAttempt && String(verdict.context.runAttempt) !== runAttempt) {
+ fail(`verdict attempt ${verdict.context.runAttempt} does not match ${runAttempt}`);
+}
+if (!SHA.test(verdict.context?.sha ?? '')) {
+ fail('verdict tested SHA is missing or invalid');
+}
+if (verdict.context?.headSha && verdict.context.headSha !== headSha) {
+ fail(`verdict head ${verdict.context.headSha} does not match trusted head ${headSha}`);
+}
+if (!Array.isArray(verdict.changes) || verdict.changes.length > MAX_CHANGES) {
+ fail(`invalid change count ${verdict.changes?.length ?? 'missing'}`);
+}
+if (!Array.isArray(verdict.added) || !Array.isArray(verdict.removed)) {
+ fail('added/removed shot lists are missing');
+}
+if (verdict.changes.length + verdict.added.length + verdict.removed.length > MAX_CHANGES) {
+ fail('visual delta bundle exceeds the review budget');
+}
+
+const seen = new Set();
+const validateKey = key => {
+ if (!KEY.test(key ?? '')) fail(`invalid shot key ${JSON.stringify(key)}`);
+ if (seen.has(key)) fail(`duplicate shot key ${key}`);
+ seen.add(key);
+};
+for (const change of verdict.changes) {
+ validateKey(change.key);
+ if (!Number.isFinite(Number(change.diffPixels)) || Number(change.diffPixels) < 0) {
+ fail(`invalid diff pixel count for ${change.key}`);
+ }
+}
+for (const key of verdict.added) validateKey(key);
+for (const key of verdict.removed) validateKey(key);
+
+fs.rmSync(output, {recursive: true, force: true});
+for (const kind of ['before', 'after', 'diff']) {
+ fs.mkdirSync(path.join(output, kind), {recursive: true});
+}
+
+/** Decode + re-encode: validates the bytes and strips ancillary metadata. */
+function copyPng(kind, key, sourceDir = path.join(input, 'report', kind)) {
+ const source = path.join(sourceDir, `${key}.png`);
+ if (!fs.existsSync(source)) fail(`${kind}/${key}.png is missing`);
+ const stat = fs.lstatSync(source);
+ if (!stat.isFile() || stat.isSymbolicLink()) fail(`${kind}/${key}.png is not a regular file`);
+ if (stat.size <= 0 || stat.size > MAX_PNG_BYTES) fail(`${kind}/${key}.png has invalid size`);
+
+ let image;
+ try {
+ image = PNG.sync.read(fs.readFileSync(source), {checkCRC: true});
+ } catch (error) {
+ fail(`${kind}/${key}.png is not a valid PNG: ${error.message}`);
+ }
+ if (
+ image.width <= 0 ||
+ image.height <= 0 ||
+ image.width > MAX_EDGE ||
+ image.height > MAX_EDGE
+ ) {
+ fail(`${kind}/${key}.png has invalid dimensions ${image.width}x${image.height}`);
+ }
+ fs.writeFileSync(path.join(output, kind, `${key}.png`), PNG.sync.write(image));
+}
+
+for (const {key} of verdict.changes) {
+ for (const kind of ['before', 'after', 'diff']) copyPng(kind, key);
+}
+// New stable shots have no before/diff, but their AFTER is the image a human
+// accepts and the post-merge verifier must reproduce. Preserve it now; the
+// Actions artifact expires and the per-PR path is deleted when the PR closes.
+for (const key of verdict.added) {
+ copyPng('after', key, path.join(input, 'shots'));
+}
+
+const evidence = {
+ version: 1,
+ repo: 'facebook/astryx',
+ pr,
+ headSha,
+ testedSha: verdict.context?.sha ?? null,
+ baseSha: verdict.context?.baseSha ?? null,
+ run: {id: Number(runId), attempt: Number(runAttempt)},
+ deltas: [
+ ...verdict.changes.map(change => ({key: change.key, kind: 'changed'})),
+ ...verdict.added.map(key => ({key, kind: 'added'})),
+ ...verdict.removed.map(key => ({key, kind: 'removed'})),
+ ],
+ verdict,
+};
+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, {acceptHint: '/accept-visual <why every changed frame is correct>'}),
+);
+
+process.stdout.write(
+ `Validated ${verdict.changes.length} visual delta(s) for PR #${pr}, head ${headSha.slice(0, 12)}, run ${runId}/${runAttempt}.\n`,
+);
diff --git a/.github/scripts/visual-gate/publish-pr-report.test.mjs b/.github/scripts/visual-gate/publish-pr-report.test.mjs
new file mode 100644
index 0000000000..12a95891a0
--- /dev/null
+++ b/.github/scripts/visual-gate/publish-pr-report.test.mjs
@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {execFileSync} from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+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',
+);
+const HEAD = 'a'.repeat(40);
+const RUN = '123456';
+
+let root;
+let input;
+let output;
+
+function png() {
+ const image = new PNG({width: 2, height: 2});
+ for (let i = 0; i < image.data.length; i += 4) {
+ image.data[i] = 255;
+ image.data[i + 3] = 255;
+ }
+ return PNG.sync.write(image);
+}
+
+function writeFixture(overrides = {}) {
+ const key = overrides.key ?? 'core-button--default__neutral-light';
+ const verdict = {
+ version: 1,
+ status: 'changed',
+ context: {runId: RUN, headSha: HEAD, sha: 'b'.repeat(40)},
+ counts: {total: 1, changed: 1, added: 0, removed: 0, failed: 0},
+ changes: [
+ {
+ key,
+ component: 'Button',
+ name: 'Default',
+ theme: 'neutral',
+ mode: 'light',
+ diffPixels: 4,
+ },
+ ],
+ added: [],
+ removed: [],
+ ...overrides.verdict,
+ };
+ fs.mkdirSync(input, {recursive: true});
+ fs.writeFileSync(path.join(input, 'verdict.json'), JSON.stringify(verdict));
+ for (const kind of ['before', 'after', 'diff']) {
+ const dir = path.join(input, 'report', kind);
+ fs.mkdirSync(dir, {recursive: true});
+ fs.writeFileSync(path.join(dir, `${key}.png`), overrides.bytes ?? png());
+ }
+}
+
+function run(extra = []) {
+ return execFileSync(
+ process.execPath,
+ [
+ SCRIPT,
+ '--input',
+ input,
+ '--output',
+ output,
+ '--pr',
+ '42',
+ '--head-sha',
+ HEAD,
+ '--run-id',
+ RUN,
+ '--run-attempt',
+ '1',
+ ...extra,
+ ],
+ {encoding: 'utf8'},
+ );
+}
+
+beforeEach(() => {
+ root = fs.mkdtempSync(path.join(os.tmpdir(), 'publish-visual-'));
+ input = path.join(root, 'input');
+ output = path.join(root, 'output');
+});
+afterEach(() => fs.rmSync(root, {recursive: true, force: true}));
+
+describe('trusted PR visual publisher', () => {
+ it('decodes/re-encodes images and generates the wrapper from trusted code', () => {
+ writeFixture();
+ expect(run()).toContain('Validated 1 visual delta');
+ expect(fs.existsSync(path.join(output, 'index.html'))).toBe(true);
+ expect(fs.existsSync(path.join(output, 'before', 'core-button--default__neutral-light.png'))).toBe(true);
+ const evidence = JSON.parse(fs.readFileSync(path.join(output, 'evidence.json'), 'utf8'));
+ expect(evidence).toMatchObject({pr: 42, headSha: HEAD, testedSha: 'b'.repeat(40)});
+ });
+
+ it('preserves the after image for a newly added stable shot', () => {
+ const key = 'core-new--default__neutral-light';
+ writeFixture({
+ key,
+ verdict: {
+ status: 'changed',
+ changes: [],
+ added: [key],
+ removed: [],
+ counts: {total: 1, changed: 0, added: 1, removed: 0, failed: 0},
+ },
+ });
+ // Added shots come from capture/shots, not report/after.
+ fs.mkdirSync(path.join(input, 'shots'), {recursive: true});
+ fs.writeFileSync(path.join(input, 'shots', `${key}.png`), png());
+ run();
+ expect(fs.existsSync(path.join(output, 'after', `${key}.png`))).toBe(true);
+ const evidence = JSON.parse(fs.readFileSync(path.join(output, 'evidence.json'), 'utf8'));
+ expect(evidence.deltas).toEqual([{key, kind: 'added'}]);
+ });
+
+ it('rejects a key repeated across changed/added/removed lists', () => {
+ writeFixture({verdict: {added: ['core-button--default__neutral-light']}});
+ expect(() => run()).toThrow(/duplicate shot key/);
+ });
+
+ it('rejects an artifact that claims another run', () => {
+ writeFixture({verdict: {context: {runId: '999', headSha: HEAD}}});
+ expect(() => run()).toThrow(/does not match/);
+ });
+
+ it('rejects traversal and shell-shaped shot keys', () => {
+ writeFixture({key: '../bad;rm'});
+ expect(() => run()).toThrow(/invalid shot key/);
+ });
+
+ it('rejects bytes that are not a decodable PNG', () => {
+ writeFixture({bytes: Buffer.from('not png')});
+ expect(() => run()).toThrow(/not a valid PNG/);
+ });
+});
diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml
index 0fdc411ec9..c5d85a84a5 100644
--- a/.github/workflows/pr-comment.yml
+++ b/.github/workflows/pr-comment.yml
@@ -9,9 +9,11 @@
# write), so it can comment on fork PRs too — one code path for every PR, no
# drift between a fork path and a same-repo path.
#
-# Safety: this never checks out or runs PR-controlled code. It only downloads
-# the analysis + a11y artifacts (JSON) produced by CI and posts a comment. Do
-# not add checkout of the PR head or execution of PR code here.
+# Safety: resolves the PR from the GitHub API, then cross-checks every artifact's
+# claimed PR/head/run identity. Visual evidence is untrusted: default-branch
+# code schema-validates it, rejects unsafe paths/symlinks, decodes and
+# re-encodes PNGs, and generates the HTML wrapper itself. PR-produced HTML/JS
+# is never published or executed. Do not add checkout/execution of the PR head.
name: PR Comment
@@ -22,6 +24,12 @@ on:
permissions: {}
+# A newer run for the same branch supersedes an older comment/publication. The
+# trusted identity step also fails a stale run after the PR head moves.
+concurrency:
+ group: pr-comment-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_branch }}
+ cancel-in-progress: true
+
jobs:
comment:
# Only for CI runs triggered by a pull request.
@@ -30,16 +38,62 @@ jobs:
permissions:
pull-requests: write
actions: read
+ contents: write # immutable validated visual evidence on gh-pages
steps:
- name: Checkout base repo (scripts only)
uses: actions/checkout@v7
- - name: Setup Node.js
- uses: actions/setup-node@v7
+ - name: Setup Node and pnpm
+ uses: ./.github/actions/setup
+
+ # Never trust the PR number inside a PR-produced artifact. Resolve the PR
+ # from the workflow_run through the GitHub API, then require its current
+ # head to be the run's head. A fork cannot redirect this privileged job
+ # at another PR by editing pr-meta.json.
+ - name: Resolve trusted PR identity
+ id: identity
+ uses: actions/github-script@v9
with:
- node-version: 24
+ script: |
+ const run = context.payload.workflow_run;
+ const {owner, repo} = context.repo;
+ let numbers = (run.pull_requests || []).map((pr) => pr.number);
+ if (numbers.length === 0) {
+ const associated = await github.paginate(
+ github.rest.repos.listPullRequestsAssociatedWithCommit,
+ {owner, repo, commit_sha: run.head_sha, per_page: 100},
+ );
+ numbers = associated.map((pr) => pr.number);
+ }
+ numbers = [...new Set(numbers)];
+ if (numbers.length !== 1) {
+ core.setFailed(`Expected exactly one PR for run ${run.id}; found ${numbers.join(',') || 'none'}`);
+ return;
+ }
+ const {data: pr} = await github.rest.pulls.get({
+ owner, repo, pull_number: numbers[0],
+ });
+ if (pr.head.sha !== run.head_sha) {
+ core.setFailed(`Run head ${run.head_sha} is stale; PR head is ${pr.head.sha}`);
+ return;
+ }
+ if (pr.head.repo.full_name !== run.head_repository.full_name) {
+ core.setFailed(`Run repository ${run.head_repository.full_name} does not match PR head ${pr.head.repo.full_name}`);
+ return;
+ }
+ if (pr.base.repo.full_name !== `${owner}/${repo}`) {
+ core.setFailed(`PR #${pr.number} targets another repository`);
+ return;
+ }
+ core.setOutput('valid', 'true');
+ core.setOutput('pr_number', String(pr.number));
+ core.setOutput('head_sha', pr.head.sha);
+ core.setOutput('head_repo', pr.head.repo.full_name);
+ core.setOutput('run_id', String(run.id));
+ core.setOutput('run_attempt', String(run.run_attempt));
- name: Download analysis artifact from the CI run
+ if: steps.identity.outputs.valid == 'true'
uses: actions/download-artifact@v8
with:
name: pr-analysis
@@ -49,6 +103,7 @@ jobs:
continue-on-error: true
- name: Download a11y artifact from the CI run
+ if: steps.identity.outputs.valid == 'true'
uses: actions/download-artifact@v8
with:
name: a11y-report
@@ -58,6 +113,7 @@ jobs:
continue-on-error: true
- name: Download visual verdict from the CI run
+ if: steps.identity.outputs.valid == 'true'
uses: actions/download-artifact@v8
with:
name: visual-pr-report
@@ -66,8 +122,95 @@ jobs:
github-token: ${{ secrets.GITHUB_TOKEN }}
continue-on-error: true
+ - name: Cross-check artifact identity
+ if: steps.identity.outputs.valid == 'true' && hashFiles('pr-analysis/pr-meta.json') != ''
+ env:
+ EXPECTED_PR: ${{ steps.identity.outputs.pr_number }}
+ EXPECTED_HEAD: ${{ steps.identity.outputs.head_sha }}
+ EXPECTED_RUN: ${{ steps.identity.outputs.run_id }}
+ run: |
+ node - <<'NODE'
+ const fs = require('node:fs');
+ const meta = JSON.parse(fs.readFileSync('pr-analysis/pr-meta.json', 'utf8'));
+ const fail = (message) => { console.error(`::error::${message}`); process.exit(1); };
+ if (String(meta.prNumber) !== process.env.EXPECTED_PR) fail('artifact PR number does not match trusted PR');
+ const shortHash = String(meta.shortHash ?? '');
+ if (!/^[0-9a-f]{7,40}$/.test(shortHash)) fail('artifact head is not a valid hash');
+ if (!process.env.EXPECTED_HEAD.startsWith(shortHash)) fail('artifact head does not match trusted PR head');
+ if (String(meta.runId) !== process.env.EXPECTED_RUN) fail('artifact run id does not match workflow_run');
+ NODE
+
+ # The artifact is untrusted. Default-branch code validates its schema,
+ # keys, identity and PNG bytes, decodes/re-encodes every image, and
+ # generates the HTML wrapper. PR-produced HTML/JS is never published.
+ - name: Validate visual evidence and generate trusted report
+ id: visual
+ if: steps.identity.outputs.valid == 'true' && hashFiles('visual/verdict.json') != ''
+ env:
+ PR_NUMBER: ${{ steps.identity.outputs.pr_number }}
+ HEAD_SHA: ${{ steps.identity.outputs.head_sha }}
+ RUN_ID: ${{ steps.identity.outputs.run_id }}
+ RUN_ATTEMPT: ${{ steps.identity.outputs.run_attempt }}
+ run: |
+ node .github/scripts/visual-gate/publish-pr-report.mjs \
+ --input visual \
+ --output trusted-visual \
+ --pr "$PR_NUMBER" \
+ --head-sha "$HEAD_SHA" \
+ --run-id "$RUN_ID" \
+ --run-attempt "$RUN_ATTEMPT"
+ echo "ready=true" >> "$GITHUB_OUTPUT"
+ echo "path=pr/${PR_NUMBER}/visual/${HEAD_SHA}/${RUN_ID}" >> "$GITHUB_OUTPUT"
+
+ - name: Publish immutable visual evidence
+ id: publish
+ if: steps.visual.outputs.ready == 'true'
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ EVIDENCE_PATH: ${{ steps.visual.outputs.path }}
+ run: |
+ set -eu
+ REPO_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+ WORK_DIR="$PWD"
+ for attempt in 1 2 3 4 5; do
+ rm -rf /tmp/gh-pages
+ git clone --depth=1 --single-branch --branch gh-pages "$REPO_URL" /tmp/gh-pages
+ DEST="/tmp/gh-pages/${EVIDENCE_PATH}"
+ if [ -e "$DEST" ]; then
+ if diff -qr "$WORK_DIR/trusted-visual" "$DEST" >/dev/null; then
+ echo "Immutable evidence already published"
+ echo "published=true" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ echo "::error::Immutable evidence path already exists with different bytes"
+ exit 1
+ fi
+ mkdir -p "$DEST"
+ cp -r "$WORK_DIR/trusted-visual/." "$DEST/"
+ cd /tmp/gh-pages
+ git config user.name "github-actions[bot]"
+ git config user.email "github-actions[bot]@users.noreply.github.com"
+ git add "$EVIDENCE_PATH"
+ git commit -m "Visual evidence: ${EVIDENCE_PATH}"
+ if git push origin gh-pages; then
+ echo "published=true" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ cd "$WORK_DIR"
+ sleep $((attempt * 2))
+ done
+ echo "::error::Could not publish visual evidence after 5 attempts"
+ exit 1
+
- name: Generate and post PR comment
+ if: steps.identity.outputs.valid == 'true'
uses: actions/github-script@v9
+ env:
+ PR_NUMBER: ${{ steps.identity.outputs.pr_number }}
+ HEAD_SHA: ${{ steps.identity.outputs.head_sha }}
+ RUN_ID: ${{ steps.identity.outputs.run_id }}
+ VISUAL_PUBLISHED: ${{ steps.publish.outputs.published }}
+ VISUAL_PATH: ${{ steps.visual.outputs.path }}
with:
script: |
const fs = require('node:fs');
@@ -81,10 +224,11 @@ jobs:
return;
}
- const meta = JSON.parse(fs.readFileSync('pr-analysis/pr-meta.json', 'utf8'));
- const prNumber = parseInt(meta.prNumber, 10);
- if (!prNumber) {
- core.warning('No PR number in metadata — cannot comment.');
+ const prNumber = parseInt(process.env.PR_NUMBER, 10);
+ const headSha = process.env.HEAD_SHA;
+ const runId = process.env.RUN_ID;
+ if (!prNumber || !headSha || !runId) {
+ core.setFailed('Trusted PR identity outputs are missing.');
return;
}
@@ -104,11 +248,21 @@ jobs:
'--analysis', 'pr-analysis/analysis.json',
'--a11y', a11yPath,
...(fs.existsSync('visual/verdict.json')
- ? ['--visual', 'visual/verdict.json']
+ ? [
+ '--visual', 'visual/verdict.json',
+ ...(process.env.VISUAL_PUBLISHED === 'true'
+ ? [
+ '--visual-report-url',
+ `https://facebook.github.io/astryx/${process.env.VISUAL_PATH}/`,
+ '--visual-image-url',
+ `https://raw.githubusercontent.com/facebook/astryx/gh-pages/${process.env.VISUAL_PATH}/`,
+ ]
+ : []),
+ ]
: []),
- '--storybook-url', meta.storybookUrl || '',
- '--sandbox-url', meta.sandboxUrl || '',
- '--run-url', meta.runUrl || '',
+ '--storybook-url', `https://facebook.github.io/astryx/pr/${prNumber}/`,
+ '--sandbox-url', `https://facebook.github.io/astryx/pr/${prNumber}/sandbox/`,
+ '--run-url', `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`,
'--pr-number', String(prNumber),
];