Skip to content

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

TypeScript

ci: route visual gh-pages writers through publisher (#5631)

Cindy Zhang20cf2b575d16
diff --git a/.github/scripts/lib/gh-pages-publisher.mjs b/.github/scripts/lib/gh-pages-publisher.mjs
index 9aa700b322..b7f271120b 100755
--- a/.github/scripts/lib/gh-pages-publisher.mjs
+++ b/.github/scripts/lib/gh-pages-publisher.mjs
@@ -9,6 +9,8 @@ import {fileURLToPath} from 'node:url';
const PAGES_BRANCH = 'gh-pages';
const QUEUE_REL = path.join('.astryx-gh-pages', 'publication-queue');
+const LEGACY_BASELINE_QUEUE_REL = path.join('visual-gate', 'publication-queue');
+const BASELINE_SCOPE = 'visual-gate/baseline';
const HOLDER_NAME = 'holder.json';
const RUN_ID = /^[1-9][0-9]*$/;
const SCOPE = /^[a-z0-9][a-z0-9._/-]*$/;
@@ -157,6 +159,330 @@ function queueState(checkout, repository) {
return {entries, invalid, holder};
}
+function baselineScope(scope) {
+ return scope === BASELINE_SCOPE;
+}
+
+function legacyTicketValue(repository, runId) {
+ return {version: 1, repository, runId};
+}
+
+function validLegacyTicket(value, repository, runId) {
+ return (
+ Number.isSafeInteger(runId) &&
+ runId > 0 &&
+ value?.version === 1 &&
+ value.repository === repository &&
+ value.runId === runId
+ );
+}
+
+function legacyQueueState(checkout, repository) {
+ const root = path.join(checkout, LEGACY_BASELINE_QUEUE_REL);
+ if (!fs.existsSync(root)) return {entries: [], invalid: [], holder: null};
+ const entries = [];
+ const invalid = [];
+ let holder = null;
+ for (const entry of fs.readdirSync(root, {withFileTypes: true})) {
+ if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+ const value = readJSON(path.join(root, entry.name));
+ if (entry.name === HOLDER_NAME) {
+ if (!validLegacyTicket(value, repository, value?.runId)) {
+ refuse('legacy publication holder has invalid identity');
+ }
+ holder = value;
+ continue;
+ }
+ const name = entry.name.slice(0, -'.json'.length);
+ if (!RUN_ID.test(name)) {
+ invalid.push(entry.name);
+ continue;
+ }
+ const runId = Number(name);
+ if (!validLegacyTicket(value, repository, runId)) {
+ invalid.push(entry.name);
+ continue;
+ }
+ entries.push({name, value});
+ }
+ return {entries, invalid, holder};
+}
+
+function orderedLegacyTickets(entries, repository) {
+ const tickets = [];
+ const seen = new Set();
+ for (const entry of entries) {
+ if (!RUN_ID.test(entry?.name ?? '')) continue;
+ const runId = Number(entry.name);
+ if (!validLegacyTicket(entry.value, repository, runId)) {
+ refuse(`legacy queue ticket ${entry.name} has invalid identity`);
+ }
+ if (seen.has(runId)) refuse('legacy queue repeats a run id');
+ seen.add(runId);
+ tickets.push(entry.value);
+ }
+ return tickets.sort((a, b) => a.runId - b.runId);
+}
+
+function legacyPublicationBlockers(entries, repository, currentRunId) {
+ validateIdentity(repository, currentRunId, BASELINE_SCOPE);
+ const tickets = orderedLegacyTickets(entries, repository);
+ if (!tickets.some(ticket => ticket.runId === currentRunId)) {
+ refuse(`legacy queue ticket for run ${currentRunId} is missing`);
+ }
+ return tickets.filter(ticket => ticket.runId < currentRunId);
+}
+
+async function mutateLegacyBaselineQueue({
+ repository,
+ runId,
+ token,
+ tempRoot,
+ remoteURL,
+ mutate,
+}) {
+ validateIdentity(repository, runId, BASELINE_SCOPE);
+ for (let attempt = 1; attempt <= 10; attempt += 1) {
+ const checkout = checkoutPages({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ sparsePaths: [LEGACY_BASELINE_QUEUE_REL],
+ prefix: 'gh-pages-legacy-queue-',
+ });
+ try {
+ const mutation = mutate(checkout);
+ if (!mutation.changed) return mutation.value;
+ configureGitIdentity(checkout);
+ git(checkout, 'add', '-A', LEGACY_BASELINE_QUEUE_REL);
+ git(
+ checkout,
+ 'commit',
+ '-qm',
+ 'visual baseline: update publication queue',
+ );
+ const pushed = tryRun('git', [
+ '-C',
+ checkout,
+ 'push',
+ 'origin',
+ PAGES_BRANCH,
+ ]);
+ if (pushed.status === 0) return mutation.value;
+ if (permissionDenied(pushed)) {
+ refuse(
+ 'push to gh-pages denied while updating the legacy publication queue',
+ );
+ }
+ } finally {
+ fs.rmSync(checkout, {recursive: true, force: true});
+ }
+ await sleep(attempt * 1000);
+ }
+ refuse('could not update the legacy publication queue after 10 attempts');
+}
+
+async function enqueueLegacyBaseline(options) {
+ const {repository, runId} = options;
+ await mutateLegacyBaselineQueue({
+ ...options,
+ mutate(checkout) {
+ const file = path.join(
+ checkout,
+ LEGACY_BASELINE_QUEUE_REL,
+ `${runId}.json`,
+ );
+ if (fs.existsSync(file)) {
+ if (!validLegacyTicket(readJSON(file), repository, runId)) {
+ refuse('existing legacy queue ticket has invalid identity');
+ }
+ return {changed: false};
+ }
+ fs.mkdirSync(path.dirname(file), {recursive: true});
+ fs.writeFileSync(
+ file,
+ `${JSON.stringify(legacyTicketValue(repository, runId), null, 2)}\n`,
+ );
+ return {changed: true};
+ },
+ });
+}
+
+async function releaseLegacyBaseline(options) {
+ const {runId} = options;
+ await mutateLegacyBaselineQueue({
+ ...options,
+ mutate(checkout) {
+ const root = path.join(checkout, LEGACY_BASELINE_QUEUE_REL);
+ const ticket = path.join(root, `${runId}.json`);
+ const holder = path.join(root, HOLDER_NAME);
+ let changed = false;
+ if (fs.existsSync(ticket)) {
+ fs.rmSync(ticket);
+ changed = true;
+ }
+ const held = readJSON(holder);
+ if (held?.runId === runId) {
+ fs.rmSync(holder);
+ changed = true;
+ }
+ return {changed};
+ },
+ });
+}
+
+async function removeInvalidLegacyBaseline({
+ repository,
+ runId,
+ names,
+ token,
+ tempRoot,
+ remoteURL,
+}) {
+ await mutateLegacyBaselineQueue({
+ repository,
+ runId,
+ token,
+ tempRoot,
+ remoteURL,
+ mutate(checkout) {
+ let changed = false;
+ for (const name of names) {
+ const file = path.join(checkout, LEGACY_BASELINE_QUEUE_REL, name);
+ if (fs.existsSync(file)) {
+ fs.rmSync(file);
+ changed = true;
+ }
+ }
+ return {changed};
+ },
+ });
+}
+
+async function claimLegacyBaseline(options) {
+ const {repository, runId} = options;
+ return mutateLegacyBaselineQueue({
+ ...options,
+ mutate(checkout) {
+ const state = legacyQueueState(checkout, repository);
+ if (state.invalid.length > 0) return {changed: false, value: false};
+ if (state.holder)
+ return {changed: false, value: state.holder.runId === runId};
+ const tickets = orderedLegacyTickets(state.entries, repository);
+ if (tickets[0]?.runId !== runId) return {changed: false, value: false};
+ fs.writeFileSync(
+ path.join(checkout, LEGACY_BASELINE_QUEUE_REL, HOLDER_NAME),
+ `${JSON.stringify(legacyTicketValue(repository, runId), null, 2)}\n`,
+ );
+ return {changed: true, value: true};
+ },
+ });
+}
+
+async function waitForLegacyBaselineTurn({
+ repository,
+ runId,
+ token,
+ tempRoot,
+ remoteURL,
+ timeoutMs = DEFAULT_WAIT_MS,
+ beforeClaimPush,
+}) {
+ validateIdentity(repository, runId, BASELINE_SCOPE);
+ const started = Date.now();
+ const checkTimeout = blocker => {
+ if (Date.now() - started >= timeoutMs) {
+ refuse(
+ `timed out behind legacy baseline publication run ${blocker ?? 'unknown'}`,
+ );
+ }
+ };
+ while (true) {
+ const checkout = checkoutPages({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ sparsePaths: [LEGACY_BASELINE_QUEUE_REL],
+ prefix: 'gh-pages-legacy-queue-',
+ });
+ let state;
+ try {
+ state = legacyQueueState(checkout, repository);
+ } finally {
+ fs.rmSync(checkout, {recursive: true, force: true});
+ }
+ if (state.invalid.length > 0) {
+ checkTimeout(state.holder?.runId);
+ await removeInvalidLegacyBaseline({
+ repository,
+ runId,
+ names: state.invalid,
+ token,
+ tempRoot,
+ remoteURL,
+ });
+ continue;
+ }
+ if (state.holder?.runId === runId) return;
+ if (state.holder) {
+ if (isTerminalRun(runStatus(repository, state.holder.runId))) {
+ checkTimeout(state.holder.runId);
+ await releaseLegacyBaseline({
+ repository,
+ runId: state.holder.runId,
+ token,
+ tempRoot,
+ remoteURL,
+ });
+ continue;
+ }
+ } else {
+ const blockers = legacyPublicationBlockers(
+ state.entries,
+ repository,
+ runId,
+ );
+ let pruned = false;
+ for (const blocker of blockers) {
+ if (isTerminalRun(runStatus(repository, blocker.runId))) {
+ checkTimeout(blocker.runId);
+ await releaseLegacyBaseline({
+ repository,
+ runId: blocker.runId,
+ token,
+ tempRoot,
+ remoteURL,
+ });
+ pruned = true;
+ }
+ }
+ if (pruned) continue;
+ if (
+ blockers.length === 0 &&
+ (await claimLegacyBaseline({
+ repository,
+ runId,
+ token,
+ tempRoot,
+ remoteURL,
+ }))
+ ) {
+ return;
+ }
+ }
+ const blocker =
+ state.holder?.runId ??
+ orderedLegacyTickets(state.entries, repository)[0]?.runId;
+ checkTimeout(blocker);
+ process.stdout.write(
+ `Waiting for legacy baseline publication run ${blocker}.\n`,
+ );
+ await sleep(30000);
+ }
+}
+
function remoteURL({repository, token, remoteURL}) {
return (
remoteURL ??
@@ -248,24 +574,118 @@ async function mutateQueue({
refuse('could not update the publication queue after 10 attempts');
}
+async function mutateDualQueue({
+ repository,
+ runId,
+ scope,
+ token,
+ tempRoot,
+ remoteURL,
+ message = 'ci: update gh-pages publication queues',
+ mutate,
+ beforePush,
+}) {
+ validateIdentity(repository, runId, scope);
+ for (let attempt = 1; attempt <= 10; attempt += 1) {
+ const checkout = checkoutPages({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ sparsePaths: [QUEUE_REL, LEGACY_BASELINE_QUEUE_REL],
+ prefix: 'gh-pages-dual-queue-',
+ });
+ try {
+ const mutation = mutate(checkout);
+ if (!mutation.changed) return mutation.value;
+ configureGitIdentity(checkout);
+ git(checkout, 'add', '-A', QUEUE_REL, LEGACY_BASELINE_QUEUE_REL);
+ git(checkout, 'commit', '-qm', message);
+ await beforePush?.({attempt, checkout});
+ const pushed = tryRun('git', [
+ '-C',
+ checkout,
+ 'push',
+ 'origin',
+ PAGES_BRANCH,
+ ]);
+ if (pushed.status === 0) return mutation.value;
+ if (permissionDenied(pushed)) {
+ refuse('push to gh-pages denied while updating publication queues');
+ }
+ } finally {
+ fs.rmSync(checkout, {recursive: true, force: true});
+ }
+ await sleep(attempt * 1000);
+ }
+ refuse('could not update the publication queues after 10 attempts');
+}
+
+function ensureSharedTicket(checkout, repository, runId, scope) {
+ const file = path.join(checkout, QUEUE_REL, `${runId}.json`);
+ if (fs.existsSync(file)) {
+ if (!validTicket(readJSON(file), repository, runId, scope)) {
+ refuse('existing queue ticket has invalid identity');
+ }
+ return false;
+ }
+ fs.mkdirSync(path.dirname(file), {recursive: true});
+ fs.writeFileSync(
+ file,
+ `${JSON.stringify(ticketValue(repository, runId, scope), null, 2)}\n`,
+ );
+ return true;
+}
+
+function ensureLegacyTicket(checkout, repository, runId) {
+ const file = path.join(checkout, LEGACY_BASELINE_QUEUE_REL, `${runId}.json`);
+ if (fs.existsSync(file)) {
+ if (!validLegacyTicket(readJSON(file), repository, runId)) {
+ refuse('existing legacy queue ticket has invalid identity');
+ }
+ return false;
+ }
+ fs.mkdirSync(path.dirname(file), {recursive: true});
+ fs.writeFileSync(
+ file,
+ `${JSON.stringify(legacyTicketValue(repository, runId), null, 2)}\n`,
+ );
+ return true;
+}
+
+function dualQueueState(checkout, repository) {
+ return {
+ shared: queueState(checkout, repository),
+ legacy: legacyQueueState(checkout, repository),
+ };
+}
+
+function currentSharedTicket(entries, repository, runId, scope) {
+ return orderedTickets(entries, repository).some(
+ ticket => ticket.runId === runId && ticket.scope === scope,
+ );
+}
+
+function currentLegacyTicket(entries, repository, runId) {
+ return orderedLegacyTickets(entries, repository).some(
+ ticket => ticket.runId === runId,
+ );
+}
+
export async function enqueuePublication(options) {
const {repository, runId, scope} = options;
- await mutateQueue({
+ await mutateDualQueue({
...options,
+ message: 'ci: update gh-pages publication queues',
mutate(checkout) {
- const file = path.join(checkout, QUEUE_REL, `${runId}.json`);
- if (fs.existsSync(file)) {
- if (!validTicket(readJSON(file), repository, runId, scope)) {
- refuse('existing queue ticket has invalid identity');
- }
- return {changed: false};
- }
- fs.mkdirSync(path.dirname(file), {recursive: true});
- fs.writeFileSync(
- file,
- `${JSON.stringify(ticketValue(repository, runId, scope), null, 2)}\n`,
+ const sharedChanged = ensureSharedTicket(
+ checkout,
+ repository,
+ runId,
+ scope,
);
- return {changed: true};
+ const legacyChanged = ensureLegacyTicket(checkout, repository, runId);
+ return {changed: sharedChanged || legacyChanged};
},
});
process.stdout.write(
@@ -274,21 +694,34 @@ export async function enqueuePublication(options) {
}
export async function releasePublication(options) {
- const {repository, runId, scope} = options;
- await mutateQueue({
+ const {runId, scope} = options;
+ await mutateDualQueue({
...options,
+ message: 'ci: release gh-pages publication turn',
mutate(checkout) {
- const root = path.join(checkout, QUEUE_REL);
- const ticket = path.join(root, `${runId}.json`);
- const holder = path.join(root, HOLDER_NAME);
+ const sharedRoot = path.join(checkout, QUEUE_REL);
+ const sharedTicket = path.join(sharedRoot, `${runId}.json`);
+ const sharedHolder = path.join(sharedRoot, HOLDER_NAME);
+ const legacyRoot = path.join(checkout, LEGACY_BASELINE_QUEUE_REL);
+ const legacyTicket = path.join(legacyRoot, `${runId}.json`);
+ const legacyHolder = path.join(legacyRoot, HOLDER_NAME);
let changed = false;
- if (fs.existsSync(ticket)) {
- fs.rmSync(ticket);
+ if (fs.existsSync(legacyTicket)) {
+ fs.rmSync(legacyTicket);
changed = true;
}
- const held = readJSON(holder);
- if (held?.runId === runId && held?.scope === scope) {
- fs.rmSync(holder);
+ const legacyHeld = readJSON(legacyHolder);
+ if (legacyHeld?.runId === runId) {
+ fs.rmSync(legacyHolder);
+ changed = true;
+ }
+ if (fs.existsSync(sharedTicket)) {
+ fs.rmSync(sharedTicket);
+ changed = true;
+ }
+ const sharedHeld = readJSON(sharedHolder);
+ if (sharedHeld?.runId === runId && sharedHeld?.scope === scope) {
+ fs.rmSync(sharedHolder);
changed = true;
}
return {changed};
@@ -383,6 +816,7 @@ export async function waitForPublicationTurn({
tempRoot,
remoteURL,
timeoutMs = DEFAULT_WAIT_MS,
+ beforeClaimPush,
}) {
validateIdentity(repository, runId, scope);
const started = Date.now();
@@ -399,90 +833,203 @@ export async function waitForPublicationTurn({
token,
tempRoot,
remoteURL,
- sparsePaths: [QUEUE_REL],
- prefix: 'gh-pages-queue-',
+ sparsePaths: [QUEUE_REL, LEGACY_BASELINE_QUEUE_REL],
+ prefix: 'gh-pages-dual-queue-',
});
let state;
try {
- state = queueState(checkout, repository);
+ state = dualQueueState(checkout, repository);
} finally {
fs.rmSync(checkout, {recursive: true, force: true});
}
- if (state.invalid.length > 0) {
- checkTimeout(state.holder?.runId);
+
+ if (state.shared.invalid.length > 0) {
+ checkTimeout(state.shared.holder?.runId);
await removeInvalid({
repository,
runId,
scope,
- names: state.invalid,
+ names: state.shared.invalid,
+ token,
+ tempRoot,
+ remoteURL,
+ });
+ continue;
+ }
+ if (state.legacy.invalid.length > 0) {
+ checkTimeout(state.legacy.holder?.runId);
+ await removeInvalidLegacyBaseline({
+ repository,
+ runId,
+ names: state.legacy.invalid,
token,
tempRoot,
remoteURL,
});
continue;
}
- if (state.holder?.runId === runId && state.holder?.scope === scope) {
+
+ const sharedHeldByCurrent =
+ state.shared.holder?.runId === runId &&
+ state.shared.holder?.scope === scope;
+ const legacyHeldByCurrent = state.legacy.holder?.runId === runId;
+ if (sharedHeldByCurrent && legacyHeldByCurrent) {
process.stdout.write(
`gh-pages publication turn acquired by run ${runId}.\n`,
);
return;
}
- if (state.holder) {
- if (isTerminalRun(runStatus(repository, state.holder.runId))) {
- checkTimeout(state.holder.runId);
+
+ if (state.shared.holder && !sharedHeldByCurrent) {
+ if (isTerminalRun(runStatus(repository, state.shared.holder.runId))) {
+ checkTimeout(state.shared.holder.runId);
await releasePublication({
repository,
- runId: state.holder.runId,
- scope: state.holder.scope,
+ runId: state.shared.holder.runId,
+ scope: state.shared.holder.scope,
token,
tempRoot,
remoteURL,
});
continue;
}
- } else {
- const blockers = publicationBlockers(
- state.entries,
- repository,
- runId,
- scope,
+ const blocker = state.shared.holder.runId;
+ checkTimeout(blocker);
+ process.stdout.write(
+ `Waiting for gh-pages publication run ${blocker}.\n`,
);
- let pruned = false;
- for (const blocker of blockers) {
- if (isTerminalRun(runStatus(repository, blocker.runId))) {
- checkTimeout(blocker.runId);
- await releasePublication({
- repository,
- runId: blocker.runId,
- scope: blocker.scope,
- token,
- tempRoot,
- remoteURL,
- });
- pruned = true;
- }
+ await sleep(30000);
+ continue;
+ }
+
+ if (state.legacy.holder && !legacyHeldByCurrent) {
+ if (isTerminalRun(runStatus(repository, state.legacy.holder.runId))) {
+ checkTimeout(state.legacy.holder.runId);
+ await releaseLegacyBaseline({
+ repository,
+ runId: state.legacy.holder.runId,
+ token,
+ tempRoot,
+ remoteURL,
+ });
+ continue;
}
- if (pruned) continue;
- if (
- blockers.length === 0 &&
- (await claimPublication({
+ const blocker = state.legacy.holder.runId;
+ checkTimeout(blocker);
+ process.stdout.write(
+ `Waiting for legacy baseline publication run ${blocker}.\n`,
+ );
+ await sleep(30000);
+ continue;
+ }
+
+ const sharedHasTicket = currentSharedTicket(
+ state.shared.entries,
+ repository,
+ runId,
+ scope,
+ );
+ const legacyHasTicket = currentLegacyTicket(
+ state.legacy.entries,
+ repository,
+ runId,
+ );
+ if (!sharedHasTicket || !legacyHasTicket) {
+ refuse(`queue ticket for run ${runId} is missing`);
+ }
+
+ const sharedBlockers = publicationBlockers(
+ state.shared.entries,
+ repository,
+ runId,
+ scope,
+ );
+ const legacyBlockers = legacyPublicationBlockers(
+ state.legacy.entries,
+ repository,
+ runId,
+ );
+ let pruned = false;
+ for (const blocker of sharedBlockers) {
+ if (isTerminalRun(runStatus(repository, blocker.runId))) {
+ checkTimeout(blocker.runId);
+ await releasePublication({
repository,
- runId,
- scope,
+ runId: blocker.runId,
+ scope: blocker.scope,
token,
tempRoot,
remoteURL,
- }))
- ) {
+ });
+ pruned = true;
+ }
+ }
+ for (const blocker of legacyBlockers) {
+ if (isTerminalRun(runStatus(repository, blocker.runId))) {
+ checkTimeout(blocker.runId);
+ await releaseLegacyBaseline({
+ repository,
+ runId: blocker.runId,
+ token,
+ tempRoot,
+ remoteURL,
+ });
+ pruned = true;
+ }
+ }
+ if (pruned) continue;
+
+ if (sharedBlockers.length === 0 && legacyBlockers.length === 0) {
+ const claimed = await mutateDualQueue({
+ repository,
+ runId,
+ scope,
+ token,
+ tempRoot,
+ remoteURL,
+ message: 'ci: claim gh-pages publication turn',
+ beforePush: beforeClaimPush,
+ mutate(claimCheckout) {
+ const claimState = dualQueueState(claimCheckout, repository);
+ const sharedClear =
+ !claimState.shared.holder &&
+ publicationBlockers(
+ claimState.shared.entries,
+ repository,
+ runId,
+ scope,
+ ).length === 0;
+ const legacyClear =
+ !claimState.legacy.holder &&
+ legacyPublicationBlockers(
+ claimState.legacy.entries,
+ repository,
+ runId,
+ ).length === 0;
+ if (!sharedClear || !legacyClear)
+ return {changed: false, value: false};
+ fs.writeFileSync(
+ path.join(claimCheckout, QUEUE_REL, HOLDER_NAME),
+ `${JSON.stringify(ticketValue(repository, runId, scope), null, 2)}\n`,
+ );
+ fs.writeFileSync(
+ path.join(claimCheckout, LEGACY_BASELINE_QUEUE_REL, HOLDER_NAME),
+ `${JSON.stringify(legacyTicketValue(repository, runId), null, 2)}\n`,
+ );
+ return {changed: true, value: true};
+ },
+ });
+ if (claimed) {
process.stdout.write(
`gh-pages publication turn acquired by run ${runId}.\n`,
);
return;
}
+ continue;
}
+
const blocker =
- state.holder?.runId ??
- orderedTickets(state.entries, repository)[0]?.runId;
+ sharedBlockers[0]?.runId ?? legacyBlockers[0]?.runId ?? 'unknown';
checkTimeout(blocker);
process.stdout.write(`Waiting for gh-pages publication run ${blocker}.\n`);
await sleep(30000);
@@ -525,6 +1072,467 @@ function commitIfNeeded(checkout, message, addArgs) {
return git(checkout, 'rev-parse', 'HEAD');
}
+function output(name, value) {
+ if (!process.env.GITHUB_OUTPUT) return;
+ fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${value}\n`);
+}
+
+function safeRelativePath(value, name) {
+ const normalized = path.posix.normalize(
+ String(value ?? '').replace(/\\/g, '/'),
+ );
+ if (
+ !normalized ||
+ normalized === '.' ||
+ normalized.startsWith('../') ||
+ normalized.includes('/../') ||
+ path.isAbsolute(normalized)
+ ) {
+ refuse(`${name} is invalid`);
+ }
+ return normalized;
+}
+
+function fileList(root) {
+ const files = [];
+ function visit(dir, prefix = '') {
+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+ const rel = path.posix.join(prefix, entry.name);
+ const file = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ visit(file, rel);
+ } else if (entry.isFile()) {
+ files.push(rel);
+ }
+ }
+ }
+ visit(root);
+ return files.sort();
+}
+
+function sameDirectoryContents(first, second) {
+ if (!fs.existsSync(first) || !fs.existsSync(second)) return false;
+ const firstFiles = fileList(first);
+ const secondFiles = fileList(second);
+ if (firstFiles.length !== secondFiles.length) return false;
+ for (let index = 0; index < firstFiles.length; index += 1) {
+ if (firstFiles[index] !== secondFiles[index]) return false;
+ if (
+ !fs
+ .readFileSync(path.join(first, firstFiles[index]))
+ .equals(fs.readFileSync(path.join(second, secondFiles[index])))
+ ) {
+ return false;
+ }
+ }
+ return true;
+}
+
+function scriptPath(...parts) {
+ return path.join(process.cwd(), '.github', 'scripts', ...parts);
+}
+
+function runNodeScript(parts, args) {
+ const out = run(process.execPath, [scriptPath(...parts), ...args]);
+ if (out) process.stdout.write(`${out}\n`);
+ return out;
+}
+
+function assertHoldingPublicationTurn({
+ repository,
+ runId,
+ scope,
+ token,
+ tempRoot,
+ remoteURL,
+}) {
+ validateIdentity(repository, runId, scope);
+ const checkout = checkoutPages({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ sparsePaths: [QUEUE_REL],
+ prefix: 'gh-pages-queue-check-',
+ });
+ try {
+ const holder = queueState(checkout, repository).holder;
+ if (holder?.runId !== runId || holder?.scope !== scope) {
+ refuse(`publication turn for ${scope} is not held by run ${runId}`);
+ }
+ } finally {
+ fs.rmSync(checkout, {recursive: true, force: true});
+ }
+}
+
+export async function publishImmutablePath({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ source,
+ destination,
+ message,
+ maxAttempts = 5,
+ beforePush,
+}) {
+ const sourceDir = path.resolve(source);
+ const destinationRel = safeRelativePath(destination, '--destination');
+ if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) {
+ refuse('--source must be a directory');
+ }
+ for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+ const checkout = checkoutPages({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ sparsePaths: [destinationRel],
+ prefix: 'gh-pages-immutable-',
+ });
+ try {
+ const destinationDir = path.join(checkout, destinationRel);
+ if (fs.existsSync(destinationDir)) {
+ if (sameDirectoryContents(sourceDir, destinationDir)) {
+ process.stdout.write('Immutable path already published.\n');
+ output('published', 'true');
+ return {published: true, alreadyPublished: true};
+ }
+ refuse('immutable destination already exists with different bytes');
+ }
+ copyContents(sourceDir, destinationDir);
+ const commit = commitIfNeeded(
+ checkout,
+ message ?? `publish ${destinationRel}`,
+ [destinationRel],
+ );
+ if (commit === null) {
+ output('published', 'true');
+ return {published: true};
+ }
+ await beforePush?.({attempt, checkout, commit});
+ const pushed = tryRun('git', [
+ '-C',
+ checkout,
+ 'push',
+ 'origin',
+ PAGES_BRANCH,
+ ]);
+ if (pushOrRetry(pushed)) {
+ output('published', 'true');
+ return {published: true, commit};
+ }
+ } finally {
+ fs.rmSync(checkout, {recursive: true, force: true});
+ }
+ process.stdout.write(
+ `Push rejected; retrying immutable publish (${attempt}/${maxAttempts}).\n`,
+ );
+ await sleep(attempt * 2000);
+ }
+ refuse(`could not publish ${destinationRel} after ${maxAttempts} attempts`);
+}
+
+export async function publishVisualAcceptanceRecord({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ pr,
+ head,
+ acceptedRunId,
+ acceptedRunAttempt,
+ approver,
+ approverId,
+ permission,
+ effectivePermission,
+ roleName,
+ commentId,
+ reason,
+ maxAttempts = 5,
+ beforePush,
+}) {
+ const destinationRel = safeRelativePath(
+ `visual-gate/acceptances/${pr}/${head}`,
+ 'acceptance destination',
+ );
+ for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+ const checkout = checkoutPages({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ sparsePaths: [
+ 'visual-gate/baseline',
+ `pr/${pr}/visual/${head}/${acceptedRunId}/${acceptedRunAttempt}`,
+ destinationRel,
+ ],
+ prefix: 'gh-pages-acceptance-',
+ });
+ try {
+ runNodeScript(
+ ['visual-gate', 'visual-acceptance.mjs'],
+ [
+ 'accept',
+ '--pages',
+ checkout,
+ '--pr',
+ String(pr),
+ '--head',
+ String(head),
+ '--run-id',
+ String(acceptedRunId),
+ '--run-attempt',
+ String(acceptedRunAttempt),
+ '--approver',
+ String(approver),
+ '--approver-id',
+ String(approverId),
+ '--permission',
+ String(permission),
+ '--effective-permission',
+ String(effectivePermission),
+ '--role-name',
+ String(roleName ?? ''),
+ '--comment-id',
+ String(commentId),
+ '--reason',
+ String(reason),
+ ],
+ );
+ const commit = commitIfNeeded(
+ checkout,
+ `visual acceptance: PR #${pr} at ${head}`,
+ [destinationRel],
+ );
+ if (commit === null) {
+ process.stdout.write(
+ 'The current visual bundle was already accepted.\n',
+ );
+ return {published: false};
+ }
+ await beforePush?.({attempt, checkout, commit});
+ const pushed = tryRun('git', [
+ '-C',
+ checkout,
+ 'push',
+ 'origin',
+ PAGES_BRANCH,
+ ]);
+ if (pushOrRetry(pushed)) return {published: true, commit};
+ } finally {
+ fs.rmSync(checkout, {recursive: true, force: true});
+ }
+ process.stdout.write(
+ `Push rejected; retrying acceptance publish (${attempt}/${maxAttempts}).\n`,
+ );
+ await sleep(attempt * 2000);
+ }
+ refuse(`could not archive visual acceptance after ${maxAttempts} attempts`);
+}
+
+export async function publishAcceptedVisualBaseline({
+ repository,
+ runId,
+ token,
+ tempRoot,
+ remoteURL,
+ pr,
+ head,
+ mergeSha,
+ expectedRecordRel,
+ capture,
+ maxAttempts = 5,
+ beforePush,
+}) {
+ const scope = 'visual-gate/baseline';
+ assertHoldingPublicationTurn({
+ repository,
+ runId,
+ scope,
+ token,
+ tempRoot,
+ remoteURL,
+ });
+ for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+ const checkout = checkoutPages({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ sparsePaths: [
+ 'visual-gate/baseline',
+ `visual-gate/acceptances/${pr}/${head}`,
+ ],
+ prefix: 'gh-pages-baseline-',
+ });
+ try {
+ const resolved = JSON.parse(
+ runNodeScript(
+ ['visual-gate', 'lib', 'promotion-identity.mjs'],
+ [
+ 'resolve-acceptance',
+ '--pages',
+ checkout,
+ '--pr',
+ String(pr),
+ '--head',
+ String(head),
+ '--missing-ok',
+ 'false',
+ '--expected-record-rel',
+ String(expectedRecordRel),
+ ],
+ ),
+ );
+ if (resolved.ok !== true) {
+ output('failure_description', resolved.description);
+ refuse(
+ resolved.message ??
+ resolved.description ??
+ 'acceptance validation failed',
+ );
+ }
+ if (resolved.deferred === true) {
+ output('deferred', 'true');
+ output('deferred_description', resolved.deferredDescription);
+ return {deferred: true};
+ }
+ runNodeScript(
+ ['visual-gate', 'visual-acceptance.mjs'],
+ [
+ 'promote',
+ '--pages',
+ checkout,
+ '--acceptance',
+ resolved.recordPath,
+ '--capture',
+ path.resolve(capture),
+ '--merge-sha',
+ String(mergeSha),
+ ],
+ );
+ const commit = commitIfNeeded(
+ checkout,
+ `visual baseline: accepted PR #${pr}`,
+ ['-A', 'visual-gate/baseline'],
+ );
+ if (commit === null) {
+ process.stdout.write(
+ 'Baseline already contains the accepted pixels.\n',
+ );
+ output('publication_confirmed', 'true');
+ return {published: false};
+ }
+ await beforePush?.({attempt, checkout, commit});
+ const pushed = tryRun('git', [
+ '-C',
+ checkout,
+ 'push',
+ 'origin',
+ PAGES_BRANCH,
+ ]);
+ if (pushOrRetry(pushed)) {
+ output('publication_confirmed', 'true');
+ return {published: true, commit};
+ }
+ } finally {
+ fs.rmSync(checkout, {recursive: true, force: true});
+ }
+ process.stdout.write(
+ `Push rejected; retrying accepted baseline publish (${attempt}/${maxAttempts}).\n`,
+ );
+ await sleep(attempt * 2000);
+ }
+ output(
+ 'failure_description',
+ 'Merged pixels did not promote to the visual baseline.',
+ );
+ refuse(
+ `could not promote the accepted baseline after ${maxAttempts} attempts`,
+ );
+}
+
+export async function publishManualVisualBaseline({
+ repository,
+ runId,
+ token,
+ tempRoot,
+ remoteURL,
+ capture,
+ keys,
+ reason,
+ actor,
+ prune = false,
+ maxAttempts = 5,
+ beforePush,
+}) {
+ const scope = 'visual-gate/baseline';
+ assertHoldingPublicationTurn({
+ repository,
+ runId,
+ scope,
+ token,
+ tempRoot,
+ remoteURL,
+ });
+ for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+ const checkout = checkoutPages({
+ repository,
+ token,
+ tempRoot,
+ remoteURL,
+ sparsePaths: ['visual-gate/baseline'],
+ prefix: 'gh-pages-manual-baseline-',
+ });
+ try {
+ const args = [
+ 'accept',
+ '--baseline',
+ path.join(checkout, 'visual-gate', 'baseline'),
+ '--out',
+ path.resolve(capture),
+ '--keys',
+ String(keys),
+ '--reason',
+ String(reason),
+ '--actor',
+ String(actor),
+ ];
+ if (prune) args.push('--prune');
+ runNodeScript(['visual-gate', 'gate.mjs'], args);
+ const commit = commitIfNeeded(
+ checkout,
+ `visual baseline: ${keys} (run ${runId})`,
+ ['-A', 'visual-gate/baseline'],
+ );
+ if (commit === null) {
+ process.stdout.write('Baseline unchanged.\n');
+ return {published: false};
+ }
+ await beforePush?.({attempt, checkout, commit});
+ const pushed = tryRun('git', [
+ '-C',
+ checkout,
+ 'push',
+ 'origin',
+ PAGES_BRANCH,
+ ]);
+ if (pushOrRetry(pushed)) {
+ process.stdout.write('Baseline updated.\n');
+ return {published: true, commit};
+ }
+ } finally {
+ fs.rmSync(checkout, {recursive: true, force: true});
+ }
+ process.stdout.write(
+ `Push rejected; retrying manual baseline publish (${attempt}/${maxAttempts}).\n`,
+ );
+ await sleep(attempt * 2000);
+ }
+ refuse(`could not push the updated baseline after ${maxAttempts} attempts`);
+}
+
export async function publishReleaseGateReport({
repository,
token,
@@ -750,7 +1758,17 @@ function cliContext(args) {
export async function main(argv = process.argv.slice(2)) {
const command = argv[0];
const context = cliContext(argv);
- if (command === 'stable-site') {
+ if (command === 'enqueue' || command === 'wait' || command === 'release') {
+ const scope = flag(argv, '--scope');
+ if (!scope) refuse('--scope is required');
+ if (command === 'enqueue') {
+ await enqueuePublication({...context, scope});
+ } else if (command === 'wait') {
+ await waitForPublicationTurn({...context, scope});
+ } else {
+ await releasePublication({...context, scope});
+ }
+ } else if (command === 'stable-site') {
const source = flag(argv, '--source');
const sha = flag(argv, '--sha', process.env.GITHUB_SHA ?? '');
if (!source) refuse('--source is required');
@@ -768,9 +1786,65 @@ export async function main(argv = process.argv.slice(2)) {
scope: 'visual-gate/reports',
publish: () => publishReleaseGateReport({...context, source}),
});
+ } else if (command === 'immutable-path') {
+ const source = flag(argv, '--source');
+ const destination = flag(argv, '--destination');
+ const scope = flag(argv, '--scope');
+ if (!source) refuse('--source is required');
+ if (!destination) refuse('--destination is required');
+ if (!scope) refuse('--scope is required');
+ await withPublicationTurn({
+ ...context,
+ scope,
+ publish: () =>
+ publishImmutablePath({
+ ...context,
+ source,
+ destination,
+ message: flag(argv, '--message'),
+ }),
+ });
+ } else if (command === 'visual-acceptance-record') {
+ await withPublicationTurn({
+ ...context,
+ scope: 'visual-gate/acceptances',
+ publish: () =>
+ publishVisualAcceptanceRecord({
+ ...context,
+ pr: flag(argv, '--pr'),
+ head: flag(argv, '--head'),
+ acceptedRunId: flag(argv, '--accepted-run-id'),
+ acceptedRunAttempt: flag(argv, '--accepted-run-attempt'),
+ approver: flag(argv, '--approver'),
+ approverId: flag(argv, '--approver-id'),
+ permission: flag(argv, '--permission'),
+ effectivePermission: flag(argv, '--effective-permission'),
+ roleName: flag(argv, '--role-name', ''),
+ commentId: flag(argv, '--comment-id'),
+ reason: flag(argv, '--reason'),
+ }),
+ });
+ } else if (command === 'visual-baseline-accepted') {
+ await publishAcceptedVisualBaseline({
+ ...context,
+ pr: flag(argv, '--pr'),
+ head: flag(argv, '--head'),
+ mergeSha: flag(argv, '--merge-sha'),
+ expectedRecordRel: flag(argv, '--expected-record-rel'),
+ capture: flag(argv, '--capture'),
+ });
+ } else if (command === 'visual-baseline-manual') {
+ await publishManualVisualBaseline({
+ ...context,
+ capture: flag(argv, '--capture'),
+ keys: flag(argv, '--keys'),
+ reason: flag(argv, '--reason'),
+ actor: flag(argv, '--actor'),
+ prune: flag(argv, '--prune', 'false') === 'true',
+ });
} else {
refuse(
- 'usage: gh-pages-publisher.mjs <stable-site|release-gate> --source <dir>',
+ 'usage: gh-pages-publisher.mjs <enqueue|wait|release|stable-site|release-gate|immutable-path|visual-acceptance-record|visual-baseline-accepted|visual-baseline-manual>',
);
}
}
diff --git a/.github/scripts/lib/gh-pages-publisher.test.mjs b/.github/scripts/lib/gh-pages-publisher.test.mjs
index e10ad3e210..4fc2b06fc3 100644
--- a/.github/scripts/lib/gh-pages-publisher.test.mjs
+++ b/.github/scripts/lib/gh-pages-publisher.test.mjs
@@ -1,15 +1,21 @@
// 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';
import {
enqueuePublication,
+ publishAcceptedVisualBaseline,
+ publishImmutablePath,
publishReleaseGateReport,
+ publishVisualAcceptanceRecord,
publishStableSite,
releasePublication,
waitForPublicationTurn,
@@ -18,6 +24,90 @@ import {
const REPO = 'facebook/astryx';
const roots = [];
+const LEGACY_LOCK = fileURLToPath(
+ new URL('../visual-gate/lib/baseline-publication-lock.mjs', import.meta.url),
+);
+
+const HEAD = 'a'.repeat(40);
+const TESTED = 'b'.repeat(40);
+const BASE = 'd'.repeat(40);
+const MERGE = 'c'.repeat(40);
+const KEY = 'core-button--default__neutral-light';
+
+const SHARED_HOLDER = path.join(
+ '.astryx-gh-pages',
+ 'publication-queue',
+ 'holder.json',
+);
+const LEGACY_HOLDER = path.join(
+ 'visual-gate',
+ 'publication-queue',
+ 'holder.json',
+);
+
+function holderCommit(checkout, holder) {
+ return git(checkout, 'log', '-1', '--format=%H', '--', holder);
+}
+
+function holderAt(checkout, commit, holder) {
+ const result = spawnSync(
+ 'git',
+ ['-C', checkout, 'show', `${commit}:${holder}`],
+ {
+ encoding: 'utf8',
+ },
+ );
+ if (result.status !== 0) return null;
+ return JSON.parse(result.stdout);
+}
+
+function holderStates(checkout, runId) {
+ return git(checkout, 'rev-list', '--reverse', 'HEAD')
+ .split('\n')
+ .filter(Boolean)
+ .map(commit => ({
+ commit,
+ shared: holderAt(checkout, commit, SHARED_HOLDER)?.runId === runId,
+ legacy: holderAt(checkout, commit, LEGACY_HOLDER)?.runId === runId,
+ }));
+}
+
+function expectNoPartialHolderState(checkout, runId) {
+ expect(
+ holderStates(checkout, runId).filter(
+ state => state.shared !== state.legacy,
+ ),
+ ).toEqual([]);
+}
+
+const SHOT = {
+ storyId: 'core-button--default',
+ title: 'Core/Button',
+ name: 'Default',
+ component: 'Button',
+ theme: 'neutral',
+ mode: 'light',
+ reasons: ['component:Button'],
+};
+
+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) {
+ writeFile(file, `${JSON.stringify(value, null, 2)}\n`);
+}
function git(cwd, ...args) {
return execFileSync('git', ['-C', cwd, ...args], {encoding: 'utf8'}).trim();
@@ -50,10 +140,47 @@ function fixture() {
writeFile(path.join(seed, 'assets', 'old.css'), 'old asset');
writeFile(path.join(seed, 'pr', '123', 'index.html'), 'preview');
writeFile(path.join(seed, 'reports', 'vibe', 'index.html'), 'vibe');
+ const before = png(255);
+ const after = png(0, 0, 255);
writeFile(
- path.join(seed, 'visual-gate', 'baseline', 'manifest.json'),
- '{}\n',
+ path.join(seed, 'visual-gate', 'baseline', 'shots', `${KEY}.png`),
+ before,
);
+ writeJSON(path.join(seed, '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(seed, 'pr', '42', 'visual', HEAD, '123', '1');
+ writeFile(path.join(evidence, 'after', `${KEY}.png`), after);
+ writeJSON(path.join(evidence, 'evidence.json'), {
+ version: 1,
+ repo: REPO,
+ pr: 42,
+ headSha: HEAD,
+ testedSha: TESTED,
+ baseSha: BASE,
+ 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'},
+ });
writeFile(path.join(seed, 'visual-gate', '55', 'old.html'), 'old report');
writeFile(path.join(seed, 'index.html'), 'old landing');
writeFile(path.join(seed, 'latest'), 'oldsha');
@@ -63,12 +190,122 @@ function fixture() {
git(root, 'clone', '-q', '--bare', seed, remote);
writeFile(
path.join(bin, 'gh'),
- '#!/bin/sh\nprintf \'{"status":"in_progress"}\\n\'\n',
+ `#!/bin/sh
+printf '{"workflow_runs":[{"name":"CI","id":123,"run_attempt":1,"status":"completed","conclusion":"success"}],"name":"CI","id":123,"run_attempt":1,"status":"completed","conclusion":"success","head_sha":"${HEAD}"}\n'
+`,
);
fs.chmodSync(path.join(bin, 'gh'), 0o755);
return {root, remote, bin};
}
+function writeLegacyTicket(remote, root, runId) {
+ const writer = cloneRemote(remote, root, `legacy-${runId}`);
+ git(writer, 'config', 'user.name', 'Test');
+ git(writer, 'config', 'user.email', '[email protected]');
+ writeJSON(
+ path.join(writer, 'visual-gate', 'publication-queue', `${runId}.json`),
+ {
+ version: 1,
+ repository: REPO,
+ runId,
+ },
+ );
+ git(writer, 'add', '.');
+ git(writer, 'commit', '-qm', `legacy ticket ${runId}`);
+ git(writer, 'push', '-q', 'origin', 'gh-pages');
+}
+
+function runLegacyLock(fx, command, runId, extra = {}) {
+ return spawnSync(process.execPath, [LEGACY_LOCK, command], {
+ encoding: 'utf8',
+ env: {
+ ...process.env,
+ PATH: `${fx.bin}:${process.env.PATH}`,
+ ASTRYX_BASELINE_QUEUE_URL: `file://${fx.remote}`,
+ GH_TOKEN: 'test-token',
+ GITHUB_REPOSITORY: REPO,
+ GITHUB_RUN_ID: String(runId),
+ RUNNER_TEMP: fx.root,
+ ...extra,
+ },
+ });
+}
+
+function writeSharedHolder(remote, root, runId, scope) {
+ const writer = cloneRemote(remote, root, `shared-holder-${runId}`);
+ git(writer, 'config', 'user.name', 'Test');
+ git(writer, 'config', 'user.email', '[email protected]');
+ writeJSON(
+ path.join(writer, '.astryx-gh-pages', 'publication-queue', `${runId}.json`),
+ {
+ version: 1,
+ repository: REPO,
+ runId,
+ scope,
+ },
+ );
+ writeJSON(
+ path.join(writer, '.astryx-gh-pages', 'publication-queue', 'holder.json'),
+ {
+ version: 1,
+ repository: REPO,
+ runId,
+ scope,
+ },
+ );
+ git(writer, 'add', '.');
+ git(writer, 'commit', '-qm', `shared holder ${runId}`);
+ git(writer, 'push', '-q', 'origin', 'gh-pages');
+}
+
+function writeLegacyHolder(remote, root, runId, {withTicket = false} = {}) {
+ const writer = cloneRemote(remote, root, `legacy-holder-${runId}`);
+ git(writer, 'config', 'user.name', 'Test');
+ git(writer, 'config', 'user.email', '[email protected]');
+ if (withTicket) {
+ writeJSON(
+ path.join(writer, 'visual-gate', 'publication-queue', `${runId}.json`),
+ {
+ version: 1,
+ repository: REPO,
+ runId,
+ },
+ );
+ }
+ writeJSON(path.join(writer, LEGACY_HOLDER), {
+ version: 1,
+ repository: REPO,
+ runId,
+ });
+ git(writer, 'add', '.');
+ git(writer, 'commit', '-qm', `legacy holder ${runId}`);
+ git(writer, 'push', '-q', 'origin', 'gh-pages');
+}
+
+function writeCompetingSharedHolder(remote, root, runId, scope) {
+ const writer = cloneRemote(remote, root, `competing-shared-${runId}`);
+ git(writer, 'config', 'user.name', 'Test');
+ git(writer, 'config', 'user.email', '[email protected]');
+ writeJSON(
+ path.join(writer, '.astryx-gh-pages', 'publication-queue', `${runId}.json`),
+ {
+ version: 1,
+ repository: REPO,
+ runId,
+ scope,
+ },
+ );
+ writeJSON(path.join(writer, SHARED_HOLDER), {
+ version: 1,
+ repository: REPO,
+ runId,
+ scope,
+ });
+ git(writer, 'add', '.');
+ git(writer, 'commit', '-qm', `competing shared holder ${runId}`);
+ git(writer, 'push', '-q', 'origin', 'gh-pages');
+}
+
function cloneRemote(remote, root, name = 'final') {
const checkout = path.join(root, name);
git(root, 'clone', '-q', '--branch', 'gh-pages', remote, checkout);
@@ -206,11 +443,13 @@ describe('gh-pages publisher', () => {
),
).toBe('vibe');
expect(
- fs.readFileSync(
- path.join(final, 'visual-gate', 'baseline', 'manifest.json'),
- 'utf8',
- ),
- ).toBe('{}\n');
+ JSON.parse(
+ fs.readFileSync(
+ path.join(final, 'visual-gate', 'baseline', 'manifest.json'),
+ 'utf8',
+ ),
+ ).version,
+ ).toBe(1);
expect(
fs.readFileSync(
path.join(final, '.astryx-gh-pages', 'publication-queue', '700.json'),
@@ -249,11 +488,13 @@ describe('gh-pages publisher', () => {
),
).toBe('new report');
expect(
- fs.readFileSync(
- path.join(final, 'visual-gate', 'baseline', 'manifest.json'),
- 'utf8',
- ),
- ).toBe('{}\n');
+ JSON.parse(
+ fs.readFileSync(
+ path.join(final, 'visual-gate', 'baseline', 'manifest.json'),
+ 'utf8',
+ ),
+ ).version,
+ ).toBe(1);
expect(
fs.readFileSync(path.join(final, 'storybook', 'old.html'), 'utf8'),
).toBe('old storybook');
@@ -333,4 +574,426 @@ describe('gh-pages publisher', () => {
fs.existsSync(path.join(final, '.astryx-gh-pages', 'publication-queue')),
).toBe(true);
});
+
+ it('does not claim either holder while waiting for an older legacy baseline ticket', async () => {
+ const fx = fixture();
+ writeLegacyTicket(fx.remote, fx.root, 899);
+ const turn = context(fx, 900, 'visual-gate/reports');
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await enqueuePublication(turn);
+ await expect(
+ waitForPublicationTurn({...turn, timeoutMs: 0}),
+ ).rejects.toThrow(/timed out behind gh-pages publication run 899/);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(
+ fs.existsSync(
+ path.join(
+ final,
+ '.astryx-gh-pages',
+ 'publication-queue',
+ 'holder.json',
+ ),
+ ),
+ ).toBe(false);
+ expect(
+ fs.existsSync(
+ path.join(final, 'visual-gate', 'publication-queue', 'holder.json'),
+ ),
+ ).toBe(false);
+ });
+
+ it('lets a late older legacy run finish while the newer shared holder waits', async () => {
+ const fx = fixture();
+ const turn = context(fx, 900, 'visual-gate/reports');
+ await enqueuePublication(turn);
+ writeLegacyTicket(fx.remote, fx.root, 899);
+
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await expect(
+ waitForPublicationTurn({...turn, timeoutMs: 0}),
+ ).rejects.toThrow(/timed out behind gh-pages publication run 899/);
+ expect(runLegacyLock(fx, 'wait', 899).status).toBe(0);
+ expect(runLegacyLock(fx, 'release', 899).status).toBe(0);
+ await waitForPublicationTurn(turn);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(
+ JSON.parse(fs.readFileSync(path.join(final, SHARED_HOLDER), 'utf8')),
+ ).toMatchObject({runId: 900, scope: 'visual-gate/reports'});
+ expect(
+ JSON.parse(fs.readFileSync(path.join(final, LEGACY_HOLDER), 'utf8')),
+ ).toMatchObject({runId: 900});
+ expect(holderCommit(final, SHARED_HOLDER)).toBe(
+ holderCommit(final, LEGACY_HOLDER),
+ );
+ expectNoPartialHolderState(final, 900);
+ });
+
+ it('bridges the legacy and shared queues for a new report writer', async () => {
+ const fx = fixture();
+ const turn = context(fx, 900, 'visual-gate/reports');
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await enqueuePublication(turn);
+ await waitForPublicationTurn(turn);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(
+ JSON.parse(
+ fs.readFileSync(
+ path.join(
+ final,
+ '.astryx-gh-pages',
+ 'publication-queue',
+ 'holder.json',
+ ),
+ 'utf8',
+ ),
+ ),
+ ).toMatchObject({runId: 900, scope: 'visual-gate/reports'});
+ expect(
+ JSON.parse(
+ fs.readFileSync(
+ path.join(final, 'visual-gate', 'publication-queue', 'holder.json'),
+ 'utf8',
+ ),
+ ),
+ ).toMatchObject({runId: 900});
+ });
+
+ it('allows only one simultaneous current writer to claim both holders', async () => {
+ const fx = fixture();
+ const first = context(fx, 900, 'visual-gate/reports');
+ const second = context(fx, 901, 'pr-visual/evidence');
+ await enqueuePublication(first);
+ await enqueuePublication(second);
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await Promise.all([
+ waitForPublicationTurn(first),
+ expect(
+ waitForPublicationTurn({...second, timeoutMs: 0}),
+ ).rejects.toThrow(/timed out behind gh-pages publication run 900/),
+ ]);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(
+ JSON.parse(fs.readFileSync(path.join(final, SHARED_HOLDER), 'utf8')),
+ ).toMatchObject({runId: 900, scope: 'visual-gate/reports'});
+ expect(
+ JSON.parse(fs.readFileSync(path.join(final, LEGACY_HOLDER), 'utf8')),
+ ).toMatchObject({runId: 900});
+ expect(holderCommit(final, SHARED_HOLDER)).toBe(
+ holderCommit(final, LEGACY_HOLDER),
+ );
+ expectNoPartialHolderState(final, 900);
+ });
+
+ it('retries an interrupted dual-holder claim without publishing a partial holder', async () => {
+ const fx = fixture();
+ const turn = context(fx, 900, 'visual-gate/reports');
+ await enqueuePublication(turn);
+ let raced = false;
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await waitForPublicationTurn({
+ ...turn,
+ beforeClaimPush: async ({attempt}) => {
+ if (attempt !== 1 || raced) return;
+ raced = true;
+ const writer = cloneRemote(fx.remote, fx.root, 'dual-queue-race');
+ git(writer, 'config', 'user.name', 'Test');
+ git(writer, 'config', 'user.email', '[email protected]');
+ writeFile(path.join(writer, 'race.txt'), 'race');
+ git(writer, 'add', '.');
+ git(writer, 'commit', '-qm', 'race');
+ git(writer, 'push', '-q', 'origin', 'gh-pages');
+ },
+ });
+ } finally {
+ process.env.PATH = previousPath;
+ }
+ expect(raced).toBe(true);
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(fs.readFileSync(path.join(final, 'race.txt'), 'utf8')).toBe('race');
+ expect(holderCommit(final, SHARED_HOLDER)).toBe(
+ holderCommit(final, LEGACY_HOLDER),
+ );
+ expectNoPartialHolderState(final, 900);
+ });
+
+ it('prunes a completed legacy blocker and then acquires both holders', async () => {
+ const fx = fixture();
+ writeLegacyTicket(fx.remote, fx.root, 899);
+ const turn = context(fx, 900, 'visual-gate/reports');
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await enqueuePublication(turn);
+ await waitForPublicationTurn(turn);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(
+ fs.existsSync(
+ path.join(final, 'visual-gate', 'publication-queue', '899.json'),
+ ),
+ ).toBe(false);
+ expect(
+ JSON.parse(
+ fs.readFileSync(
+ path.join(final, 'visual-gate', 'publication-queue', 'holder.json'),
+ 'utf8',
+ ),
+ ),
+ ).toMatchObject({runId: 900});
+ });
+
+ it('releases both holders in one commit without an observable partial release', async () => {
+ const fx = fixture();
+ const turn = context(fx, 900, 'visual-gate/reports');
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await enqueuePublication(turn);
+ await waitForPublicationTurn(turn);
+ await releasePublication(turn);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(fs.existsSync(path.join(final, SHARED_HOLDER))).toBe(false);
+ expect(fs.existsSync(path.join(final, LEGACY_HOLDER))).toBe(false);
+ expectNoPartialHolderState(final, 900);
+ });
+
+ it('prunes a terminal legacy holder without a ticket before claiming both holders', async () => {
+ const fx = fixture();
+ writeLegacyHolder(fx.remote, fx.root, 899);
+ const turn = context(fx, 900, 'visual-gate/reports');
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await enqueuePublication(turn);
+ await waitForPublicationTurn(turn);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(
+ fs.existsSync(
+ path.join(final, 'visual-gate', 'publication-queue', '899.json'),
+ ),
+ ).toBe(false);
+ expect(
+ JSON.parse(fs.readFileSync(path.join(final, SHARED_HOLDER), 'utf8')),
+ ).toMatchObject({runId: 900});
+ expect(
+ JSON.parse(fs.readFileSync(path.join(final, LEGACY_HOLDER), 'utf8')),
+ ).toMatchObject({runId: 900});
+ expectNoPartialHolderState(final, 900);
+ });
+
+ it('rechecks a fresh tip before claiming when a competing holder appears', async () => {
+ const fx = fixture();
+ const turn = context(fx, 900, 'visual-gate/reports');
+ await enqueuePublication(turn);
+ let raced = false;
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await expect(
+ waitForPublicationTurn({
+ ...turn,
+ timeoutMs: 0,
+ beforeClaimPush: async ({attempt}) => {
+ if (attempt !== 1 || raced) return;
+ raced = true;
+ writeCompetingSharedHolder(fx.remote, fx.root, 899, 'whole-tree');
+ },
+ }),
+ ).rejects.toThrow(/timed out behind gh-pages publication run 899/);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+ expect(raced).toBe(true);
+ const final = cloneRemote(fx.remote, fx.root);
+ expect(
+ JSON.parse(fs.readFileSync(path.join(final, SHARED_HOLDER), 'utf8')),
+ ).toMatchObject({runId: 899, scope: 'whole-tree'});
+ expect(fs.existsSync(path.join(final, LEGACY_HOLDER))).toBe(false);
+ });
+
+ it('publishes immutable visual evidence without overwriting different bytes', async () => {
+ const fx = fixture();
+ const source = path.join(fx.root, 'immutable-source');
+ writeFile(path.join(source, 'index.html'), 'evidence');
+ writeJSON(path.join(source, 'evidence.json'), {ok: true});
+
+ await queuedPublish(fx, 910, 'pr-visual/evidence', () =>
+ publishImmutablePath({
+ ...context(fx, 910, 'pr-visual/evidence'),
+ source,
+ destination: 'pr/42/visual/head/run/1',
+ message: 'Visual evidence: pr/42/visual/head/run/1',
+ }),
+ );
+ await queuedPublish(fx, 911, 'pr-visual/evidence', () =>
+ publishImmutablePath({
+ ...context(fx, 911, 'pr-visual/evidence'),
+ source,
+ destination: 'pr/42/visual/head/run/1',
+ message: 'Visual evidence: pr/42/visual/head/run/1',
+ }),
+ );
+ writeFile(path.join(source, 'index.html'), 'changed evidence');
+ await expect(
+ queuedPublish(fx, 912, 'pr-visual/evidence', () =>
+ publishImmutablePath({
+ ...context(fx, 912, 'pr-visual/evidence'),
+ source,
+ destination: 'pr/42/visual/head/run/1',
+ message: 'Visual evidence: pr/42/visual/head/run/1',
+ }),
+ ),
+ ).rejects.toThrow(/immutable destination already exists/);
+ });
+
+ it('archives acceptance records through the shared queue', async () => {
+ const fx = fixture();
+ await queuedPublish(fx, 920, 'visual-gate/acceptances', () =>
+ publishVisualAcceptanceRecord({
+ ...context(fx, 920, 'visual-gate/acceptances'),
+ pr: 42,
+ head: HEAD,
+ acceptedRunId: 123,
+ acceptedRunAttempt: 1,
+ approver: 'maintainer',
+ approverId: 99,
+ permission: 'maintain',
+ effectivePermission: 'maintain',
+ roleName: '',
+ commentId: 1234,
+ reason: 'The new radius matches the approved component design.',
+ }),
+ );
+
+ const final = cloneRemote(fx.remote, fx.root);
+ const acceptance = JSON.parse(
+ fs.readFileSync(
+ path.join(
+ final,
+ 'visual-gate',
+ 'acceptances',
+ '42',
+ HEAD,
+ '123',
+ '1',
+ 'acceptance.json',
+ ),
+ 'utf8',
+ ),
+ );
+ expect(acceptance.keys.map(entry => entry.key)).toEqual([KEY]);
+ expect(
+ fs.existsSync(
+ path.join(
+ final,
+ 'visual-gate',
+ 'acceptances',
+ '42',
+ HEAD,
+ '123',
+ '1',
+ 'after',
+ `${KEY}.png`,
+ ),
+ ),
+ ).toBe(true);
+ });
+
+ it('promotes accepted baseline pixels only while holding the shared turn', async () => {
+ const fx = fixture();
+ await queuedPublish(fx, 930, 'visual-gate/acceptances', () =>
+ publishVisualAcceptanceRecord({
+ ...context(fx, 930, 'visual-gate/acceptances'),
+ pr: 42,
+ head: HEAD,
+ acceptedRunId: 123,
+ acceptedRunAttempt: 1,
+ approver: 'maintainer',
+ approverId: 99,
+ permission: 'maintain',
+ effectivePermission: 'maintain',
+ roleName: '',
+ commentId: 1234,
+ reason: 'The new radius matches the approved component design.',
+ }),
+ );
+ const capture = path.join(fx.root, 'merged-capture');
+ const after = png(0, 0, 255);
+ writeFile(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},
+ context: {sha: MERGE},
+ shots: {
+ [KEY]: {...SHOT, key: KEY, sha256: digest(after), width: 2, height: 2},
+ },
+ });
+ const turn = context(fx, 931, 'visual-gate/baseline');
+ const previousPath = process.env.PATH;
+ process.env.PATH = `${fx.bin}:${previousPath}`;
+ try {
+ await enqueuePublication(turn);
+ await waitForPublicationTurn(turn);
+ await publishAcceptedVisualBaseline({
+ ...turn,
+ pr: 42,
+ head: HEAD,
+ mergeSha: MERGE,
+ expectedRecordRel: '123/1/acceptance.json',
+ capture,
+ });
+ await releasePublication(turn);
+ } finally {
+ process.env.PATH = previousPath;
+ }
+
+ const final = cloneRemote(fx.remote, fx.root);
+ const manifest = JSON.parse(
+ fs.readFileSync(
+ path.join(final, 'visual-gate', 'baseline', 'manifest.json'),
+ 'utf8',
+ ),
+ );
+ expect(manifest.shots[KEY].sha256).toBe(digest(after));
+ expect(manifest.decisions.at(-1)).toMatchObject({
+ pr: 42,
+ headSha: HEAD,
+ mergeSha: MERGE,
+ });
+ });
});
diff --git a/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs b/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs
index 1d45a356ef..b129f307ee 100644
--- a/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs
+++ b/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs
@@ -22,6 +22,13 @@ const SCRIPT = path.join(
'visual-acceptance.mjs',
);
const GATE = path.join(ROOT, '.github', 'scripts', 'visual-gate', 'gate.mjs');
+const PUBLISHER = path.join(
+ ROOT,
+ '.github',
+ 'scripts',
+ 'lib',
+ 'gh-pages-publisher.mjs',
+);
const WORKFLOW = path.join(
ROOT,
'.github',
@@ -92,14 +99,23 @@ function workflowStep(name) {
function workflowStepScript(name) {
const step = workflowStep(name);
- 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');
+ for (const [marker, fold] of [
+ [' run: |\n', false],
+ [' run: >\n', true],
+ ]) {
+ const runStart = step.indexOf(marker);
+ if (runStart === -1) continue;
+ const lines = step
+ .slice(runStart + marker.length)
+ .split('\n')
+ .map(line => (line.startsWith(' ') ? line.slice(10) : line));
+ if (!fold) return lines.join('\n');
+ return `${lines
+ .map(line => line.trim())
+ .filter(Boolean)
+ .join(' ')}\n`;
+ }
+ throw new Error(`Step ${name} has no runnable script`);
}
function writeCommandShims(root) {
@@ -233,11 +249,14 @@ function makeFixture(mutate) {
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 sandboxScripts = path.join(sandbox, '.github', 'scripts');
+ fs.mkdirSync(sandboxScripts, {recursive: true});
+ for (const entry of ['visual-gate', 'lib', 'gh-pages-publisher.mjs']) {
+ fs.symlinkSync(
+ path.join(ROOT, '.github', 'scripts', entry),
+ path.join(sandboxScripts, entry),
+ );
+ }
const plan = path.join(sandbox, 'accepted-plan.json');
runAcceptance('plan', {acceptance, output: plan});
@@ -255,6 +274,37 @@ function makeFixture(mutate) {
});
mutate?.({acceptance, baselineShot, capture, pages});
+ writeJSON(
+ path.join(pages, '.astryx-gh-pages', 'publication-queue', '900.json'),
+ {
+ version: 1,
+ repository: 'facebook/astryx',
+ runId: 900,
+ scope: 'visual-gate/baseline',
+ },
+ );
+ writeJSON(
+ path.join(pages, '.astryx-gh-pages', 'publication-queue', 'holder.json'),
+ {
+ version: 1,
+ repository: 'facebook/astryx',
+ runId: 900,
+ scope: 'visual-gate/baseline',
+ },
+ );
+ writeJSON(path.join(pages, 'visual-gate', 'publication-queue', '900.json'), {
+ version: 1,
+ repository: 'facebook/astryx',
+ runId: 900,
+ });
+ writeJSON(
+ path.join(pages, 'visual-gate', 'publication-queue', 'holder.json'),
+ {
+ version: 1,
+ repository: 'facebook/astryx',
+ runId: 900,
+ },
+ );
git(pages, 'add', '.');
git(pages, 'commit', '-qm', 'record acceptance');
@@ -270,6 +320,8 @@ function runPromotion({
race = false,
}) {
const marker = path.join(fixture.root, 'race-injected');
+ const runnerTemp = path.join(fixture.root, 'runner');
+ fs.mkdirSync(runnerTemp, {recursive: true});
const result = spawnSync(
'/bin/bash',
['-c', workflowStepScript('Verify and promote the baseline')],
@@ -281,11 +333,12 @@ function runPromotion({
PATH: `${fixture.bin}:${process.env.PATH}`,
GH_TOKEN: 'test-token',
GITHUB_REPOSITORY: 'facebook/astryx',
+ GITHUB_RUN_ID: '900',
PR_NUMBER: '42',
HEAD_SHA: HEAD,
MERGE_SHA: MERGE,
RECORD_REL,
- RUNNER_TEMP: path.join(fixture.root, 'runner'),
+ RUNNER_TEMP: runnerTemp,
GITHUB_OUTPUT: path.join(fixture.root, 'github-output'),
GH_RUNS_JSON: JSON.stringify({
workflow_runs: [{name: 'CI', ...latest}],
@@ -367,6 +420,35 @@ describe('visual acceptance promotion workflow', () => {
expect(checkout).toContain('allow-unsafe-pr-checkout: true');
});
+ it('executes the migrated publisher from the workflow sandbox root', () => {
+ const fixture = makeFixture();
+ const script = workflowStepScript('Verify and promote the baseline');
+ expect(script).toContain('gh-pages-publisher.mjs visual-baseline-accepted');
+ expect(
+ fs.existsSync(
+ path.join(
+ fixture.sandbox,
+ '.github',
+ 'scripts',
+ 'gh-pages-publisher.mjs',
+ ),
+ ),
+ ).toBe(true);
+ expect(
+ fs.existsSync(
+ path.join(
+ fixture.sandbox,
+ '.github',
+ 'scripts',
+ 'lib',
+ 'gh-pages-publisher.mjs',
+ ),
+ ),
+ ).toBe(true);
+ const result = runPromotion({fixture});
+ expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(0);
+ });
+
it('retries from the immutable record after cleanup wins the first push race', () => {
const fixture = makeFixture();
const result = runPromotion({fixture, race: true});
@@ -511,10 +593,19 @@ describe('visual acceptance promotion workflow', () => {
it('does not consult ephemeral PR evidence during promotion', () => {
const script = workflowStepScript('Verify and promote the baseline');
- expect(script).toContain('promotion-identity.mjs resolve-acceptance');
+ const publisher = fs.readFileSync(PUBLISHER, 'utf8');
+ const promotion = publisher.slice(
+ publisher.indexOf('export async function publishAcceptedVisualBaseline'),
+ publisher.indexOf('export async function publishManualVisualBaseline'),
+ );
+
+ expect(script).toContain('gh-pages-publisher.mjs visual-baseline-accepted');
expect(script).toContain('--expected-record-rel "$RECORD_REL"');
- expect(script).toContain('visual-acceptance.mjs promote');
- expect(script).not.toContain('visual-acceptance.mjs state');
- expect(script).not.toContain('/pr/');
+ expect(promotion).toContain('promotion-identity.mjs');
+ expect(promotion).toContain('resolve-acceptance');
+ expect(promotion).toContain('visual-acceptance.mjs');
+ expect(promotion).toContain('promote');
+ expect(promotion).not.toContain('visual-acceptance.mjs state');
+ expect(promotion).not.toContain("'pr'");
});
});
diff --git a/.github/scripts/visual-gate/workflow-concurrency.test.mjs b/.github/scripts/visual-gate/workflow-concurrency.test.mjs
index fec47d782c..23bd380489 100644
--- a/.github/scripts/visual-gate/workflow-concurrency.test.mjs
+++ b/.github/scripts/visual-gate/workflow-concurrency.test.mjs
@@ -187,7 +187,7 @@ describe('visual acceptance workflow concurrency', () => {
expect(accept.indexOf('uses: ./.github/actions/setup')).toBeGreaterThan(-1);
expect(accept.indexOf('uses: ./.github/actions/setup')).toBeLessThan(
accept.indexOf(
- 'node .github/scripts/visual-gate/visual-acceptance.mjs accept',
+ 'node .github/scripts/gh-pages-publisher.mjs visual-acceptance-record',
),
);
});
@@ -195,8 +195,7 @@ describe('visual acceptance workflow concurrency', () => {
it('serializes normal, recovery, and manual publication without Actions cancellation', () => {
const value = workflow('visual-acceptance-promote.yml');
const manual = workflow('visual-baseline.yml');
- const helper =
- 'node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs';
+ const helper = 'node .github/scripts/gh-pages-publisher.mjs';
expect(value).toContain('workflow_dispatch:');
expect(value).toContain("context.ref !== 'refs/heads/main'");
@@ -208,11 +207,15 @@ describe('visual acceptance workflow concurrency', () => {
);
expect(value).toContain('ref: main');
for (const command of ['enqueue', 'wait', 'release']) {
- expect(value.match(new RegExp(`${helper} ${command}`, 'g'))).toHaveLength(
- 1,
- );
expect(
- manual.match(new RegExp(`${helper} ${command}`, 'g')),
+ value.match(
+ new RegExp(`${helper} ${command} --scope visual-gate/baseline`, 'g'),
+ ),
+ ).toHaveLength(1);
+ expect(
+ manual.match(
+ new RegExp(`${helper} ${command} --scope visual-gate/baseline`, 'g'),
+ ),
).toHaveLength(1);
}
expect(value).not.toContain('group: visual-baseline');
@@ -223,13 +226,14 @@ describe('visual acceptance workflow concurrency', () => {
expect(
value.indexOf('Wait for the baseline publication turn'),
).toBeLessThan(value.indexOf('Verify and promote the baseline'));
+ expect(value).toContain('visual-baseline-accepted');
expect(value).toContain('--expected-record-rel "$RECORD_REL"');
expect(workflow('pr-comment.yml')).toContain(
'Post-merge promotion does not join this cancellation group',
);
expect(
manual.indexOf('Wait for the baseline publication turn'),
- ).toBeLessThan(manual.indexOf('Fetch the current baseline'));
+ ).toBeLessThan(manual.indexOf('Promote and publish the baseline'));
expect(workflow('release-gate.yml')).toContain(
'node .github/scripts/gh-pages-publisher.mjs release-gate --source report',
);
@@ -278,6 +282,63 @@ describe('visual acceptance workflow concurrency', () => {
expect(releaseGate).toContain('gh-pages-publisher.mjs release-gate');
});
+ it('moves high-conflict visual gh-pages writers behind the shared publisher', () => {
+ const comment = workflow('pr-comment.yml');
+ const acceptance = workflow('visual-acceptance.yml');
+ const promote = workflow('visual-acceptance-promote.yml');
+ const manual = workflow('visual-baseline.yml');
+
+ expect(comment).toContain('gh-pages-publisher.mjs immutable-path');
+ expect(comment).toContain('--scope pr-visual/evidence');
+ expect(comment).not.toContain('Immutable evidence already published');
+ expect(acceptance).toContain(
+ 'gh-pages-publisher.mjs visual-acceptance-record',
+ );
+ expect(acceptance).not.toContain('DEST="visual-gate/acceptances');
+ expect(promote).toContain(
+ 'gh-pages-publisher.mjs visual-baseline-accepted',
+ );
+ expect(promote).not.toContain('baseline-publication-lock.mjs');
+ expect(manual).toContain('gh-pages-publisher.mjs visual-baseline-manual');
+ expect(manual).not.toContain('baseline-publication-lock.mjs');
+ expect(manual).not.toContain('git rebase origin/gh-pages');
+ });
+
+ it('grants visual publisher jobs read access to overlapping workflow runs', () => {
+ const comment = workflow('pr-comment.yml');
+ const commentJob = comment.slice(
+ comment.indexOf(' comment:'),
+ comment.indexOf(' - name: Checkout trusted default-branch code'),
+ );
+ const acceptance = workflow('visual-acceptance.yml');
+ const acceptJob = acceptance.slice(
+ acceptance.indexOf(' accept:'),
+ acceptance.indexOf(
+ ' - name: Reject an invalid visual acceptance request',
+ ),
+ );
+ const promote = workflow('visual-acceptance-promote.yml');
+ const promoteJob = promote.slice(
+ promote.indexOf(' promote:'),
+ promote.indexOf(
+ ' - name: Checkout trusted current main',
+ promote.indexOf(' promote:'),
+ ),
+ );
+ const manual = workflow('visual-baseline.yml');
+ const manualJob = manual.slice(
+ manual.indexOf(' promote:'),
+ manual.indexOf(' - name: Checkout'),
+ );
+
+ for (const job of [commentJob, acceptJob, manualJob]) {
+ expect(job).toContain('actions: read');
+ expect(job).toContain('contents: write');
+ }
+ expect(promoteJob).toContain('actions: write');
+ expect(promoteJob).toContain('contents: write');
+ });
+
it('projects every known validation or publication failure from an always-running job', () => {
const value = workflow('visual-acceptance-promote.yml');
const status = value.slice(value.indexOf(' project-status:'));
@@ -349,7 +410,8 @@ describe('visual acceptance workflow concurrency', () => {
value.indexOf(' project-status:'),
);
- expect(value).toContain('publication_confirmed=true');
+ expect(value).toContain("publication_confirmed == 'true'");
+ expect(value).toContain('visual-baseline-accepted');
expect(gate).toContain(
"steps.promote.outputs.publication_confirmed == 'true'",
);
diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml
index 63a740c7eb..f50dd2b2d5 100644
--- a/.github/workflows/pr-comment.yml
+++ b/.github/workflows/pr-comment.yml
@@ -386,39 +386,26 @@ jobs:
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
+ run: >
+ node .github/scripts/gh-pages-publisher.mjs immutable-path
+ --source trusted-visual
+ --destination "$EVIDENCE_PATH"
+ --scope pr-visual/evidence
+ --message "Visual evidence: ${EVIDENCE_PATH}"
+
+ - name: Refresh trusted visual state checkout
+ if: steps.publish.outputs.published == 'true'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ PR_NUMBER: ${{ steps.identity.outputs.pr_number }}
+ HEAD_SHA: ${{ steps.identity.outputs.head_sha }}
+ run: >
+ rm -rf /tmp/gh-pages &&
+ git clone --depth=1 --filter=blob:none --sparse --single-branch --branch gh-pages
+ "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" /tmp/gh-pages &&
+ git -C /tmp/gh-pages sparse-checkout set
+ visual-gate/baseline
+ "pr/${PR_NUMBER}/visual/${HEAD_SHA}"
- name: Generate and post PR comment
if: steps.identity.outputs.valid == 'true'
diff --git a/.github/workflows/visual-acceptance-promote.yml b/.github/workflows/visual-acceptance-promote.yml
index e9dd7ea11f..8a8c76f2e2 100644
--- a/.github/workflows/visual-acceptance-promote.yml
+++ b/.github/workflows/visual-acceptance-promote.yml
@@ -234,7 +234,7 @@ jobs:
if: steps.defer.outputs.deferred != 'true'
env:
GH_TOKEN: ${{ github.token }}
- run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs enqueue
+ run: node .github/scripts/gh-pages-publisher.mjs enqueue --scope visual-gate/baseline
- name: Load and verify the immutable acceptance
id: acceptance
@@ -330,7 +330,7 @@ jobs:
if: steps.acceptance.outputs.found == 'true'
env:
GH_TOKEN: ${{ github.token }}
- run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs wait
+ run: node .github/scripts/gh-pages-publisher.mjs wait --scope visual-gate/baseline
- name: Verify and promote the baseline
id: promote
@@ -341,62 +341,13 @@ jobs:
HEAD_SHA: ${{ needs.resolve.outputs.head_sha }}
MERGE_SHA: ${{ needs.resolve.outputs.merge_sha }}
RECORD_REL: ${{ steps.acceptance.outputs.record_rel }}
- run: |
- set -eu
- REPO_URL="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
- PAGES="$RUNNER_TEMP/visual-promote-pages"
- for attempt in 1 2 3 4 5; do
- rm -rf "$PAGES"
- git clone --depth=1 --filter=blob:none --sparse --single-branch --branch gh-pages \
- "$REPO_URL" "$PAGES"
- git -C "$PAGES" sparse-checkout set \
- visual-gate/baseline \
- "visual-gate/acceptances/${PR_NUMBER}/${HEAD_SHA}"
- RESOLVED=$(node .github/scripts/visual-gate/lib/promotion-identity.mjs resolve-acceptance \
- --pages "$PAGES" \
- --pr "$PR_NUMBER" \
- --head "$HEAD_SHA" \
- --missing-ok false \
- --expected-record-rel "$RECORD_REL")
- OK=$(printf '%s' "$RESOLVED" | jq -r '.ok')
- if [ "$OK" != 'true' ]; then
- DESCRIPTION=$(printf '%s' "$RESOLVED" | jq -er '.description')
- echo "failure_description=$DESCRIPTION" >> "$GITHUB_OUTPUT"
- echo "::error::$(printf '%s' "$RESOLVED" | jq -er '.message')"
- exit 1
- fi
- DEFERRED=$(printf '%s' "$RESOLVED" | jq -r '.deferred // false')
- if [ "$DEFERRED" = 'true' ]; then
- {
- echo "deferred=true"
- echo "deferred_description=$(printf '%s' "$RESOLVED" | jq -er '.deferredDescription')"
- } >> "$GITHUB_OUTPUT"
- exit 0
- fi
- RECORD=$(printf '%s' "$RESOLVED" | jq -er '.recordPath')
- node .github/scripts/visual-gate/visual-acceptance.mjs promote \
- --pages "$PAGES" \
- --acceptance "$RECORD" \
- --capture .visual-merged \
- --merge-sha "$MERGE_SHA"
- git -C "$PAGES" config user.name "github-actions[bot]"
- git -C "$PAGES" config user.email "github-actions[bot]@users.noreply.github.com"
- git -C "$PAGES" add visual-gate/baseline
- if git -C "$PAGES" diff --cached --quiet; then
- echo "Baseline already contains the accepted pixels."
- echo "publication_confirmed=true" >> "$GITHUB_OUTPUT"
- exit 0
- fi
- git -C "$PAGES" commit -m "visual baseline: accepted PR #${PR_NUMBER}"
- if git -C "$PAGES" push origin gh-pages; then
- echo "publication_confirmed=true" >> "$GITHUB_OUTPUT"
- exit 0
- fi
- sleep $((attempt * 2))
- done
- echo "failure_description=Merged pixels did not promote to the visual baseline." >> "$GITHUB_OUTPUT"
- echo "::error::Could not promote the accepted baseline after 5 attempts"
- exit 1
+ run: >
+ node .github/scripts/gh-pages-publisher.mjs visual-baseline-accepted
+ --pr "$PR_NUMBER"
+ --head "$HEAD_SHA"
+ --merge-sha "$MERGE_SHA"
+ --expected-record-rel "$RECORD_REL"
+ --capture .visual-merged
- name: Run a fresh release gate
id: gate
@@ -426,7 +377,7 @@ jobs:
GH_TOKEN: ${{ github.token }}
run: |
set -eu
- if ! OUTPUT=$(node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs release 2>&1); then
+ if ! OUTPUT=$(node .github/scripts/gh-pages-publisher.mjs release --scope visual-gate/baseline 2>&1); then
echo "failure_description=Baseline publication finished, but lock release failed." >> "$GITHUB_OUTPUT"
echo "::error::$OUTPUT"
exit 1
diff --git a/.github/workflows/visual-acceptance.yml b/.github/workflows/visual-acceptance.yml
index 13e8d5a4b9..34441bb4dd 100644
--- a/.github/workflows/visual-acceptance.yml
+++ b/.github/workflows/visual-acceptance.yml
@@ -142,6 +142,7 @@ jobs:
cancel-in-progress: false
runs-on: ubuntu-slim
permissions:
+ actions: read
contents: write
pull-requests: write
statuses: write
@@ -185,42 +186,19 @@ jobs:
ROLE_NAME: ${{ needs.authorize.outputs.role_name }}
COMMENT_ID: ${{ needs.authorize.outputs.comment_id }}
REASON: ${{ needs.authorize.outputs.reason }}
- run: |
- set -eu
- REPO_URL="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
- PAGES="$RUNNER_TEMP/visual-acceptance-pages"
- DEST="visual-gate/acceptances/${PR_NUMBER}/${HEAD_SHA}"
- for attempt in 1 2 3 4 5; do
- rm -rf "$PAGES"
- git clone --depth=1 --single-branch --branch gh-pages "$REPO_URL" "$PAGES"
- node .github/scripts/visual-gate/visual-acceptance.mjs accept \
- --pages "$PAGES" \
- --pr "$PR_NUMBER" \
- --head "$HEAD_SHA" \
- --run-id "$RUN_ID" \
- --run-attempt "$RUN_ATTEMPT" \
- --approver "$APPROVER" \
- --approver-id "$APPROVER_ID" \
- --permission "$PERMISSION" \
- --effective-permission "$EFFECTIVE_PERMISSION" \
- --role-name "$ROLE_NAME" \
- --comment-id "$COMMENT_ID" \
- --reason "$REASON"
- if [ -z "$(git -C "$PAGES" status --porcelain -- "$DEST")" ]; then
- echo "The current visual bundle was already accepted."
- exit 0
- fi
- git -C "$PAGES" config user.name "github-actions[bot]"
- git -C "$PAGES" config user.email "github-actions[bot]@users.noreply.github.com"
- git -C "$PAGES" add "$DEST"
- git -C "$PAGES" commit -m "visual acceptance: PR #${PR_NUMBER} at ${HEAD_SHA}"
- if git -C "$PAGES" push origin gh-pages; then
- exit 0
- fi
- sleep $((attempt * 2))
- done
- echo "::error::Could not archive visual acceptance after 5 attempts"
- exit 1
+ run: >
+ node .github/scripts/gh-pages-publisher.mjs visual-acceptance-record
+ --pr "$PR_NUMBER"
+ --head "$HEAD_SHA"
+ --accepted-run-id "$RUN_ID"
+ --accepted-run-attempt "$RUN_ATTEMPT"
+ --approver "$APPROVER"
+ --approver-id "$APPROVER_ID"
+ --permission "$PERMISSION"
+ --effective-permission "$EFFECTIVE_PERMISSION"
+ --role-name "$ROLE_NAME"
+ --comment-id "$COMMENT_ID"
+ --reason "$REASON"
- name: Reconcile acceptance against the latest published evidence
id: reconcile
diff --git a/.github/workflows/visual-baseline.yml b/.github/workflows/visual-baseline.yml
index 2382421b42..f9b206bd20 100644
--- a/.github/workflows/visual-baseline.yml
+++ b/.github/workflows/visual-baseline.yml
@@ -58,7 +58,7 @@ jobs:
- name: Queue baseline publication
env:
GH_TOKEN: ${{ github.token }}
- run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs enqueue
+ run: node .github/scripts/gh-pages-publisher.mjs enqueue --scope visual-gate/baseline
- name: Download the capture being promoted
uses: actions/download-artifact@v8
@@ -71,58 +71,28 @@ jobs:
- name: Wait for the baseline publication turn
env:
GH_TOKEN: ${{ github.token }}
- run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs wait
+ run: node .github/scripts/gh-pages-publisher.mjs wait --scope visual-gate/baseline
- - name: Fetch the current baseline
- run: |
- set -eu
- rm -rf /tmp/gh-pages
- git clone --depth=1 --filter=blob:none --sparse --single-branch --branch gh-pages \
- "https://x-access-token:${{ github.token }}@github.com/${GITHUB_REPOSITORY}.git" /tmp/gh-pages
- git -C /tmp/gh-pages sparse-checkout set visual-gate/baseline
- mkdir -p /tmp/gh-pages/visual-gate/baseline
-
- - name: Promote
+ - name: Promote and publish the baseline
env:
KEYS: ${{ inputs.keys }}
REASON: ${{ inputs.reason }}
PROMOTER: ${{ github.actor }}
- run: |
- set -eu
- node .github/scripts/visual-gate/gate.mjs accept \
- --baseline /tmp/gh-pages/visual-gate/baseline \
- --out .visual-run \
- --keys "$KEYS" \
- --reason "$REASON" \
- --actor "$PROMOTER" \
- ${{ inputs.prune && '--prune' || '' }}
-
- - name: Push the baseline
- run: |
- set -eu
- cd /tmp/gh-pages
- git config user.name "github-actions[bot]"
- git config user.email "github-actions[bot]@users.noreply.github.com"
- git add -A visual-gate/baseline
- git commit -m "visual baseline: ${{ inputs.keys }} (run ${{ inputs.run_id }})" || {
- echo "Baseline unchanged"; exit 0;
- }
- for attempt in 1 2 3; do
- if git push origin gh-pages; then
- echo "Baseline updated"
- exit 0
- fi
- git fetch origin gh-pages && git rebase origin/gh-pages || true
- sleep $((attempt * 10))
- done
- echo "::error::Could not push the updated baseline"
- exit 1
+ PRUNE: ${{ inputs.prune && 'true' || 'false' }}
+ GH_TOKEN: ${{ github.token }}
+ run: >
+ node .github/scripts/gh-pages-publisher.mjs visual-baseline-manual
+ --capture .visual-run
+ --keys "$KEYS"
+ --reason "$REASON"
+ --actor "$PROMOTER"
+ --prune "$PRUNE"
- name: Release the baseline publication turn
if: always()
env:
GH_TOKEN: ${{ github.token }}
- run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs release
+ run: node .github/scripts/gh-pages-publisher.mjs release --scope visual-gate/baseline
- name: Summary
run: |