Skip to content

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

TypeScript

ci: dispatch canonical release checks on exact main (#6504)

Cindy Zhangbea59f609fdb
diff --git a/.github/scripts/a11y-pr-scope.mjs b/.github/scripts/a11y-pr-scope.mjs
new file mode 100644
index 0000000000..a916aa6e1b
--- /dev/null
+++ b/.github/scripts/a11y-pr-scope.mjs
@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Resolve explicit changed-component scope for fast PR accessibility.
+ * @input Exact PR analysis and the canonical component package registry
+ * @output Qualified component filters; an empty set never means a full audit
+ * @position PR-only projection; exhaustive accessibility belongs to release-check
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import componentPackages from '../../scripts/component-packages.cjs';
+import {buildStoryComponentRoutes} from '../../apps/storybook/rtl-audit/rtl-audit-coverage.mjs';
+import storyIdentity from './lib/a11y-story-identity.js';
+
+const {
+ componentPackage,
+ componentExportsFromBarrel,
+ documentedComponentNames,
+ COMPONENT_PACKAGES,
+ flatPackageComponentNames,
+ nestedPackageComponentNames,
+} = componentPackages;
+
+export function readPrA11yRoutes(repoRoot) {
+ const index = JSON.parse(
+ fs.readFileSync(
+ path.join(repoRoot, 'apps/storybook/dist/index.json'),
+ 'utf8',
+ ),
+ );
+ const entries = index.entries ?? index.stories;
+ if (!entries || typeof entries !== 'object' || Array.isArray(entries)) {
+ throw new Error('PR accessibility requires a valid Storybook index');
+ }
+ const stories = Object.entries(entries)
+ .filter(([, story]) => story.type === 'story')
+ .map(([id, story]) => ({id, title: story.title}));
+ if (stories.length === 0)
+ throw new Error('PR accessibility requires runnable stories');
+ const publicComponentsByPackage = Object.fromEntries(
+ COMPONENT_PACKAGES.map(pkg => [
+ pkg.name,
+ pkg.layout === 'flat'
+ ? flatPackageComponentNames(repoRoot, pkg)
+ : nestedPackageComponentNames(repoRoot, pkg),
+ ]),
+ );
+ const targets = JSON.parse(
+ fs.readFileSync(
+ path.join(repoRoot, 'apps/storybook/rtl-audit/targets.json'),
+ 'utf8',
+ ),
+ );
+ return buildStoryComponentRoutes({
+ stories,
+ targets,
+ publicComponentsByPackage,
+ }).map(route => ({
+ ...route,
+ component: storyIdentity.ownerForA11yStory(route.id) ?? route.component,
+ }));
+}
+
+export function resolvePrA11yComponents(
+ analysis,
+ repoRoot = process.cwd(),
+ routes = null,
+) {
+ if (analysis?.diffMode !== 'three-dot') {
+ throw new Error(
+ 'PR accessibility requires exact three-dot component analysis',
+ );
+ }
+ for (const key of [
+ 'newComponentOwners',
+ 'modifiedComponentOwners',
+ 'unresolvedComponentSources',
+ ]) {
+ if (
+ !Array.isArray(analysis[key]) ||
+ analysis[key].some(value => typeof value !== 'string')
+ ) {
+ throw new Error(`PR accessibility requires explicit ${key}`);
+ }
+ }
+ const owners = new Set([
+ ...analysis.newComponentOwners,
+ ...analysis.modifiedComponentOwners,
+ ]);
+ for (const owner of owners) {
+ const [packageName, name, extra] = owner.split('/');
+ if (
+ extra !== undefined ||
+ !componentPackage(packageName) ||
+ !/^[A-Z][A-Za-z0-9]*$/.test(name ?? '')
+ ) {
+ throw new Error(`Invalid package-qualified component owner: ${owner}`);
+ }
+ }
+ // Analysis deliberately leaves multi-component folders (such as Chat)
+ // unresolved. Expand only that changed folder, not the whole package roster.
+ for (const source of analysis.unresolvedComponentSources) {
+ const [packageName, directory, extra] = source.split('/');
+ const pkg = componentPackage(packageName);
+ if (
+ !pkg ||
+ extra !== undefined ||
+ !/^[A-Za-z0-9_.-]+$/.test(directory ?? '') ||
+ ['.', '..'].includes(directory)
+ ) {
+ throw new Error(`Invalid unresolved component source: ${source}`);
+ }
+ const sourceRoot = path.join(repoRoot, pkg.src);
+ const changedDirectory = path.join(sourceRoot, directory);
+ const names = documentedComponentNames(changedDirectory);
+ if (names.length === 0) continue;
+ const exports = componentExportsFromBarrel(
+ path.join(sourceRoot, 'index.ts'),
+ sourceRoot,
+ );
+ for (const name of names) {
+ const implementation = exports.get(name);
+ // A doc can mention a dependency such as Avatar; it does not make that
+ // component part of the changed folder's scope.
+ if (implementation?.startsWith(`${changedDirectory}${path.sep}`)) {
+ routes ??= readPrA11yRoutes(repoRoot);
+ const owner = `${packageName}/${name}`;
+ const umbrella = `${packageName}/${directory}`;
+ if (routes.some(route => route.component === owner)) {
+ owners.add(owner);
+ } else if (routes.some(route => route.component === umbrella)) {
+ // Some grouped exports are exercised only by their family's stories.
+ owners.add(umbrella);
+ } else {
+ throw new Error(
+ `No scoped Storybook route for ${owner} or ${umbrella}`,
+ );
+ }
+ }
+ }
+ }
+ return [...owners].sort();
+}
+
+if (
+ process.argv[1] &&
+ import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+ const analysis = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+ console.log(resolvePrA11yComponents(analysis).join(','));
+}
diff --git a/.github/scripts/a11y-pr-scope.test.mjs b/.github/scripts/a11y-pr-scope.test.mjs
new file mode 100644
index 0000000000..544ef24d84
--- /dev/null
+++ b/.github/scripts/a11y-pr-scope.test.mjs
@@ -0,0 +1,174 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Fast PR accessibility scope contracts.
+ * @input Exact/invalid analysis fixtures and public component ownership
+ * @output No full-suite fallback, qualified owners, and grouped-owner coverage
+ * @position Regression tests for the PR-only accessibility scope projection
+ */
+
+import fs from 'node:fs';
+import {describe, expect, it} from 'vitest';
+import {resolvePrA11yComponents} from './a11y-pr-scope.mjs';
+import {
+ buildStoryComponentRoutes,
+ storyIdsForComponentFilters,
+ unresolvedComponentFilters,
+} from '../../apps/storybook/rtl-audit/rtl-audit-coverage.mjs';
+import storyIdentity from './lib/a11y-story-identity.js';
+
+const analysis = overrides => ({
+ diffMode: 'three-dot',
+ newComponentOwners: [],
+ modifiedComponentOwners: [],
+ unresolvedComponentSources: [],
+ forceFullComponentAudits: false,
+ ...overrides,
+});
+
+describe('fast PR accessibility scope', () => {
+ it('keeps changed owners qualified and deduplicated even for a broad PR', () => {
+ expect(
+ resolvePrA11yComponents(
+ analysis({
+ newComponentOwners: ['charts/Chart', 'core/Button'],
+ modifiedComponentOwners: ['core/Button', 'lab/Chart'],
+ forceFullComponentAudits: true,
+ }),
+ ),
+ ).toEqual(['charts/Chart', 'core/Button', 'lab/Chart']);
+ });
+
+ it.each([false, true])(
+ 'returns an explicit empty set, never the whole roster (broad=%s)',
+ forceFullComponentAudits => {
+ expect(
+ resolvePrA11yComponents(analysis({forceFullComponentAudits})),
+ ).toEqual([]);
+ },
+ );
+
+ it('routes grouped exports through their actual component and umbrella stories', () => {
+ // Titles/IDs from the checked-in Chat, ChatLayout, ChatComposer and Button
+ // pattern stories. Exercise the same route matching the axe consumer uses.
+ const routes = buildStoryComponentRoutes({
+ stories: [
+ {id: 'core-chat--mixed-content', title: 'Core/Chat'},
+ {id: 'core-chatlayout--default', title: 'Core/ChatLayout'},
+ {id: 'core-chatcomposer--default', title: 'Core/ChatComposer'},
+ {
+ id: 'a11y-button-pattern--chat-send-default',
+ title: 'A11y/Button Pattern',
+ },
+ {id: 'core-button--default', title: 'Core/Button'},
+ ],
+ targets: JSON.parse(
+ fs.readFileSync(
+ new URL(
+ '../../apps/storybook/rtl-audit/targets.json',
+ import.meta.url,
+ ),
+ 'utf8',
+ ),
+ ),
+ publicComponentsByPackage: {
+ core: ['ChatLayout', 'ChatComposer', 'ChatSendButton', 'Button'],
+ },
+ }).map(route => ({
+ ...route,
+ component: storyIdentity.ownerForA11yStory(route.id) ?? route.component,
+ }));
+ const result = resolvePrA11yComponents(
+ analysis({unresolvedComponentSources: ['core/Chat']}),
+ process.cwd(),
+ routes,
+ );
+ expect(result).toEqual([
+ 'core/Chat',
+ 'core/ChatComposer',
+ 'core/ChatLayout',
+ 'core/ChatSendButton',
+ ]);
+ expect(unresolvedComponentFilters(routes, result)).toEqual([]);
+ expect(storyIdsForComponentFilters(routes, result)).toEqual([
+ 'core-chat--mixed-content',
+ 'core-chatlayout--default',
+ 'core-chatcomposer--default',
+ 'a11y-button-pattern--chat-send-default',
+ ]);
+ // Red arm: exported names alone made the consumer fail before running axe.
+ expect(
+ unresolvedComponentFilters(routes, [
+ 'core/ChatMessage',
+ 'core/ChatMessageBubble',
+ ]),
+ ).toEqual(['core/ChatMessage', 'core/ChatMessageBubble']);
+ expect(() =>
+ resolvePrA11yComponents(
+ analysis({unresolvedComponentSources: ['core/Chat']}),
+ process.cwd(),
+ routes.filter(route => route.component !== 'core/Chat'),
+ ),
+ ).toThrow('No scoped Storybook route');
+ });
+
+ it('does not turn a shared source into a full audit', () => {
+ expect(
+ resolvePrA11yComponents(
+ analysis({
+ unresolvedComponentSources: [
+ 'core/context',
+ 'core/index.ts',
+ 'core/__tests__',
+ ],
+ }),
+ ),
+ ).toEqual([]);
+ });
+
+ it.each(['two-dot', '', undefined])(
+ 'rejects approximate/missing diff mode %s',
+ diffMode => {
+ expect(() => resolvePrA11yComponents(analysis({diffMode}))).toThrow(
+ 'exact three-dot',
+ );
+ },
+ );
+
+ it.each([
+ 'newComponentOwners',
+ 'modifiedComponentOwners',
+ 'unresolvedComponentSources',
+ ])('rejects missing or malformed %s', key => {
+ for (const value of [undefined, null, 'core/Button', [null], [12]]) {
+ expect(() => resolvePrA11yComponents(analysis({[key]: value}))).toThrow(
+ key,
+ );
+ }
+ });
+
+ it.each([
+ 'Button',
+ 'core/',
+ 'unknown/Button',
+ 'core/Button,core/Dialog',
+ 'core/Button/other',
+ 'core/Button\n',
+ ])('rejects invalid owner %s', owner => {
+ expect(() =>
+ resolvePrA11yComponents(analysis({newComponentOwners: [owner]})),
+ ).toThrow('Invalid package-qualified');
+ });
+
+ it.each([
+ 'core/..',
+ 'core/../Button',
+ 'unknown/Chat',
+ 'core/',
+ 'core/Chat\n',
+ ])('rejects unsafe unresolved source %s', source => {
+ expect(() =>
+ resolvePrA11yComponents(analysis({unresolvedComponentSources: [source]})),
+ ).toThrow('Invalid unresolved');
+ });
+});
diff --git a/.github/scripts/ci-test-routing.test.mjs b/.github/scripts/ci-test-routing.test.mjs
index edcf10e8f5..67e5cd4bef 100644
--- a/.github/scripts/ci-test-routing.test.mjs
+++ b/.github/scripts/ci-test-routing.test.mjs
@@ -229,9 +229,12 @@ describe('ci.yml RTL package sharding', () => {
expect(commands).toContain('has_stable_visual=false');
});
- it('broadens both browser audits for unresolved canonical source ownership', () => {
+ it('keeps PR accessibility scoped while RTL retains its canonical resolver', () => {
expect(runLines(workflow.jobs['pr-a11y'])).toContain(
- '.forceFullComponentAudits // false',
+ '.github/scripts/a11y-pr-scope.mjs',
+ );
+ expect(runLines(workflow.jobs['pr-a11y'])).toContain(
+ 'SCOPE_ARGS=(--components "$COMPONENTS")',
);
expect(runLines(shard)).toContain('.github/scripts/rtl-shard-scope.mjs');
});
diff --git a/.github/scripts/release-check-workflow.test.mjs b/.github/scripts/release-check-workflow.test.mjs
new file mode 100644
index 0000000000..36bbfd50c8
--- /dev/null
+++ b/.github/scripts/release-check-workflow.test.mjs
@@ -0,0 +1,564 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Exact-main release dispatch contracts.
+ * @input CI workflow and independent event, dependency, scope, and API fixtures
+ * @output Fail-closed release routing and unchanged maintenance/PR assertions
+ * @position Node contracts for AST-030 FR12 and DEC-5
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {describe, expect, it} from 'vitest';
+import yaml from 'yaml';
+
+const workflow = yaml.parse(
+ fs.readFileSync(new URL('../workflows/ci.yml', import.meta.url), 'utf8'),
+);
+const jobs = workflow.jobs;
+const step = (job, name) => jobs[job].steps.find(item => item.name === name);
+const releaseJobs = [
+ 'check-scope',
+ 'check-components',
+ 'build-storybook',
+ 'pr-visual',
+ 'pr-a11y',
+ 'pr-rtl-shard',
+ 'pr-rtl',
+ 'release-check',
+];
+const fullOutputs = {
+ docsite_only: 'false',
+ spec_only: 'false',
+ tooling_only: 'false',
+ has_components: 'true',
+ has_rtl_components: 'true',
+ has_rtl_harness: 'true',
+ force_full_component_audits: 'true',
+ has_stable_visual: 'true',
+ broad_stable_visual: 'true',
+};
+
+function dependencies(job) {
+ const names = job.needs == null ? [] : [job.needs].flat();
+ return Object.fromEntries(
+ names.map(name => [
+ name,
+ {
+ result: name === 'maintenance-request' ? 'skipped' : 'success',
+ outputs: {...fullOutputs},
+ },
+ ]),
+ );
+}
+
+function runs(
+ job,
+ {
+ event = 'workflow_dispatch',
+ operation = 'release-check',
+ needs = dependencies(job),
+ cancelled = false,
+ } = {},
+) {
+ const expression = (job.if ?? 'true')
+ .replace(/^\$\{\{\s*|\s*\}\}$/g, '')
+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');
+ // GitHub injects success() unless the expression has a status function.
+ if (
+ !/\b(always|cancelled|success|failure)\(/.test(expression) &&
+ (cancelled || Object.values(needs).some(item => item.result !== 'success'))
+ )
+ return false;
+ return Function(
+ 'github',
+ 'inputs',
+ 'needs',
+ 'always',
+ 'cancelled',
+ `return Boolean(${expression});`,
+ )(
+ {event_name: event},
+ {operation},
+ needs,
+ () => true,
+ () => cancelled,
+ );
+}
+
+function shell(script, env = {}, prefix = '') {
+ return spawnSync('bash', ['-eu', '-c', `${prefix}\n${script}`], {
+ env: {...process.env, ...env},
+ encoding: 'utf8',
+ });
+}
+
+const sha = 'a'.repeat(40);
+async function githubScript(
+ script,
+ {ref = 'refs/heads/main', mainSha = sha, needs, apiFails = false} = {},
+) {
+ const summary = {
+ addHeading() {
+ return this;
+ },
+ addRaw() {
+ return this;
+ },
+ async write() {},
+ };
+ const execute = Object.getPrototypeOf(async function () {}).constructor(
+ 'context',
+ 'github',
+ 'core',
+ 'process',
+ script,
+ );
+ return execute(
+ {ref, sha, repo: {owner: 'example', repo: 'design-system'}},
+ {
+ rest: {
+ git: {
+ async getRef(request) {
+ expect(request.ref).toBe('heads/main');
+ if (apiFails) throw new Error('API unavailable');
+ return {data: {object: {sha: mainSha}}};
+ },
+ },
+ },
+ },
+ {summary},
+ {env: {RELEASE_NEEDS: JSON.stringify(needs)}},
+ );
+}
+
+function assertReleaseRouting(candidate) {
+ for (const [name, job] of Object.entries(candidate.jobs)) {
+ expect(runs(job), name).toBe(releaseJobs.includes(name));
+ }
+}
+
+describe('explicit release routing', () => {
+ it('uses only the existing workflow and canonical owners, never a push or schedule', () => {
+ expect(workflow.on.workflow_dispatch.inputs.operation.options).toContain(
+ 'release-check',
+ );
+ expect(workflow.on).not.toHaveProperty('push');
+ expect(workflow.on).not.toHaveProperty('schedule');
+ expect(jobs['pr-visual'].name).toBe('Stable visual regression');
+ assertReleaseRouting(workflow);
+ });
+
+ it.each(releaseJobs)('detects a mutation that skips %s', name => {
+ const mutant = structuredClone(workflow);
+ mutant.jobs[name].if = 'false';
+ expect(() => assertReleaseRouting(mutant)).toThrow();
+ });
+
+ it.each(['capture', 'promote'])(
+ 'does not start release-only projection on %s',
+ operation => {
+ expect(runs(jobs['release-check'], {operation})).toBe(false);
+ },
+ );
+
+ it.each(['failure', 'cancelled', 'skipped', ''])(
+ 'keeps the release join reachable after upstream %s',
+ result => {
+ const needs = dependencies(jobs['release-check']);
+ for (const item of Object.values(needs)) item.result = result;
+ expect(
+ runs(jobs['release-check'], {needs, cancelled: result === 'cancelled'}),
+ ).toBe(true);
+ },
+ );
+
+ it.each(['pr-a11y', 'pr-visual', 'pr-rtl-shard'])(
+ 'blocks %s when its build fails',
+ name => {
+ const needs = dependencies(jobs[name]);
+ needs['build-storybook'].result = 'failure';
+ expect(runs(jobs[name], {needs})).toBe(false);
+ },
+ );
+
+ it('keeps dispatch concurrency separate and non-cancelling', () => {
+ expect(workflow.concurrency.group).toContain('|| github.run_id');
+ expect(workflow.concurrency['cancel-in-progress']).toBe(
+ "${{ github.event_name != 'workflow_dispatch' }}",
+ );
+ });
+
+ it('preserves read-only release jobs and exact-event checkout', () => {
+ expect(workflow.permissions).toEqual({});
+ for (const name of releaseJobs) {
+ expect(jobs[name].permissions ?? {}).not.toHaveProperty(
+ 'contents',
+ 'write',
+ );
+ expect(jobs[name].permissions ?? {}).not.toHaveProperty(
+ 'actions',
+ 'write',
+ );
+ for (const item of jobs[name].steps) {
+ if (item.uses?.startsWith('actions/checkout@')) {
+ // Omitted ref is the event SHA, not the mutable default branch.
+ expect([undefined, '${{ github.sha }}']).toContain(item.with?.ref);
+ expect(item.with?.repository).toBeUndefined();
+ }
+ }
+ }
+ });
+});
+
+describe('exact current main request and completion', () => {
+ const request = step('check-scope', 'Require exact current main for release')
+ .with.script;
+ const join = step(
+ 'release-check',
+ 'Require complete exact-main release checks',
+ ).with.script;
+ const complete = Object.fromEntries(
+ jobs['release-check'].needs.map(name => [name, {result: 'success'}]),
+ );
+
+ it('checks main before checkout and accepts only complete exact-main evidence', async () => {
+ expect(jobs['check-scope'].steps[0].with.script).toBe(request);
+ await expect(githubScript(request)).resolves.toBeUndefined();
+ await expect(
+ githubScript(join, {needs: complete}),
+ ).resolves.toBeUndefined();
+ expect(jobs['release-check'].needs).toEqual([
+ 'check-scope',
+ 'check-components',
+ 'build-storybook',
+ 'pr-visual',
+ 'pr-a11y',
+ 'pr-rtl',
+ ]);
+ });
+
+ it.each(['refs/heads/feature', 'refs/tags/main', ''])(
+ 'rejects ref %s at request and completion',
+ async ref => {
+ for (const script of [request, join]) {
+ await expect(
+ githubScript(script, {ref, needs: complete}),
+ ).rejects.toThrow('dispatched from main');
+ }
+ },
+ );
+
+ it.each(['b'.repeat(40), undefined])(
+ 'rejects main drift or missing SHA %s',
+ async mainSha => {
+ for (const script of [request, join]) {
+ await expect(
+ githubScript(script, {mainSha: mainSha ?? '', needs: complete}),
+ ).rejects.toThrow('Main changed');
+ }
+ },
+ );
+
+ it('fails closed when current main cannot be read', async () => {
+ for (const script of [request, join]) {
+ await expect(
+ githubScript(script, {apiFails: true, needs: complete}),
+ ).rejects.toThrow('API unavailable');
+ }
+ });
+
+ it.each(['failure', 'cancelled', 'skipped', 'neutral', ''])(
+ 'rejects each required job with outcome %s',
+ async result => {
+ for (const name of Object.keys(complete)) {
+ await expect(
+ githubScript(join, {needs: {...complete, [name]: {result}}}),
+ ).rejects.toThrow(name);
+ const missing = {...complete};
+ delete missing[name];
+ await expect(githubScript(join, {needs: missing})).rejects.toThrow(
+ name,
+ );
+ }
+ },
+ );
+});
+
+describe('full release scope without PR metadata or maintenance writes', () => {
+ it('forces broad scope before any changed-file classification', () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-release-scope-'));
+ try {
+ for (const [job, name, expected] of [
+ [
+ 'check-scope',
+ 'Determine change scope',
+ {docsite_only: 'false', spec_only: 'false', tooling_only: 'false'},
+ ],
+ [
+ 'check-components',
+ 'Check for component changes',
+ Object.fromEntries(
+ Object.entries(fullOutputs).filter(
+ ([key]) => !key.endsWith('_only'),
+ ),
+ ),
+ ],
+ ]) {
+ const output = path.join(dir, `${job}.txt`);
+ const script = step(job, name).run.replaceAll(
+ '${{ github.event_name }}',
+ 'workflow_dispatch',
+ );
+ const result = shell(
+ script,
+ {GITHUB_OUTPUT: output},
+ 'git() { echo "must not inspect changed files" >&2; return 99; }',
+ );
+ expect(result.status, result.stderr).toBe(0);
+ expect(
+ Object.fromEntries(
+ fs
+ .readFileSync(output, 'utf8')
+ .trim()
+ .split('\n')
+ .map(line => line.split('=')),
+ ),
+ ).toEqual(expected);
+ }
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+ });
+
+ it('builds event-SHA Storybook and supplies explicit full audit analysis', () => {
+ const identify = step(
+ 'build-storybook',
+ 'Identify full release audit scope',
+ );
+ expect(identify.run).toContain(
+ 'test "$(git rev-parse HEAD)" = "$GITHUB_SHA"',
+ );
+ expect(identify.run).toContain('{"forceFullComponentAudits":true}');
+ for (const name of [
+ 'Upload Storybook artifact',
+ 'Upload built themes and core',
+ 'Upload analysis artifact',
+ ]) {
+ expect(
+ runs(step('build-storybook', name), {
+ needs: dependencies(jobs['build-storybook']),
+ }),
+ name,
+ ).toBe(true);
+ }
+ for (const name of [
+ 'Compute PR preview path',
+ 'Analyze components',
+ 'Write PR comment metadata',
+ ]) {
+ expect(
+ runs(step('build-storybook', name), {
+ needs: dependencies(jobs['build-storybook']),
+ }),
+ name,
+ ).toBe(false);
+ }
+ });
+
+ it('runs the canonical accessibility command without a component filter for full scope', () => {
+ const audit = step('pr-a11y', 'Run accessibility audit');
+ const result = shell(
+ audit.run.replaceAll('${{ github.event_name }}', 'workflow_dispatch'),
+ {},
+ `
+ node() {
+ if [ "$1" != '.github/scripts/accessibility-audit.js' ]; then return 99; fi
+ printf '%s\\n' "$@"
+ }
+ `,
+ );
+ expect(result.status, result.stderr).toBe(0);
+ expect(result.stdout).toContain('--fail-on-new');
+ expect(result.stdout).not.toContain('--components');
+ expect(audit['continue-on-error']).toBeUndefined();
+ expect(
+ step('pr-a11y', 'Run accessibility spec-test contracts').env
+ .ASTRYX_HEAD_SHA,
+ ).toBe('${{ github.event.pull_request.head.sha || github.sha }}');
+ });
+
+ it.each([
+ [['core/Button'], false],
+ [['core/Button', 'lab/Chart'], true],
+ [[], true],
+ ])(
+ 'always supplies explicit PR owner filters %j (broad=%s)',
+ (owners, broad) => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-pr-a11y-'));
+ try {
+ fs.writeFileSync(
+ path.join(dir, 'analysis.json'),
+ JSON.stringify({
+ diffMode: 'three-dot',
+ newComponentOwners: owners,
+ modifiedComponentOwners: [],
+ unresolvedComponentSources: [],
+ forceFullComponentAudits: broad,
+ }),
+ );
+ const result = shell(
+ step('pr-a11y', 'Run accessibility audit').run.replaceAll(
+ '${{ github.event_name }}',
+ 'pull_request',
+ ),
+ {TEST_DIR: dir},
+ `node() {
+ if [ "$1" = '.github/scripts/a11y-pr-scope.mjs' ]; then
+ command node "$1" "$TEST_DIR/analysis.json"
+ else
+ printf '[%s]\\n' "$@"
+ fi
+ }`,
+ );
+ expect(result.status, result.stderr).toBe(0);
+ expect(result.stdout).toContain(
+ `[--components]\n[${owners.join(',')}]`,
+ );
+ expect(result.stdout).toContain('[--fail-on-new]');
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+ },
+ );
+
+ it('does not silently audit everything when PR scope resolution fails', () => {
+ const result = shell(
+ step('pr-a11y', 'Run accessibility audit').run.replaceAll(
+ '${{ github.event_name }}',
+ 'pull_request',
+ ),
+ {},
+ `node() {
+ if [ "$1" = '.github/scripts/a11y-pr-scope.mjs' ]; then return 1; fi
+ echo 'AUDIT MUST NOT RUN'
+ }`,
+ );
+ expect(result.status).not.toBe(0);
+ expect(result.stdout).not.toContain('AUDIT MUST NOT RUN');
+ });
+
+ it('keeps exhaustive a11y contracts, their artifacts, and Probe reach release-only', () => {
+ for (const name of [
+ 'Run accessibility spec-test contracts',
+ 'Upload pressed-state pixel evidence',
+ 'Upload component-audit browser evidence',
+ 'Check Probe theme reach',
+ 'Upload Probe reach report',
+ ]) {
+ expect(runs(step('pr-a11y', name)), name).toBe(true);
+ expect(
+ runs(step('pr-a11y', name), {event: 'pull_request', operation: ''}),
+ name,
+ ).toBe(false);
+ expect(runs(step('pr-a11y', name), {operation: 'capture'}), name).toBe(
+ false,
+ );
+ }
+ expect(step('pr-a11y', 'Run accessibility spec-test contracts').run).toBe(
+ 'pnpm test:a11y-contract',
+ );
+ expect(
+ step('pr-a11y', 'Run accessibility spec-test contracts')[
+ 'continue-on-error'
+ ],
+ ).toBeUndefined();
+ for (const name of [
+ 'Run modal close visibility guard',
+ 'Run theme var reachability guard',
+ 'Run story play guard',
+ ]) {
+ expect(
+ runs(step('pr-a11y', name), {event: 'pull_request', operation: ''}),
+ name,
+ ).toBe(true);
+ expect(runs(step('pr-a11y', name)), name).toBe(true);
+ expect(step('pr-a11y', name)['continue-on-error']).toBeUndefined();
+ }
+ });
+
+ it('keeps all canonical RTL packages and passes full scope to resolver and join', () => {
+ expect(jobs['pr-rtl-shard'].strategy.matrix.package).toEqual([
+ 'core',
+ 'lab',
+ 'charts',
+ 'richtext',
+ 'vega',
+ ]);
+ expect(step('pr-rtl-shard', 'Resolve RTL shard scope').run).toContain(
+ '--force-full "${{ needs.check-components.outputs.force_full_component_audits }}"',
+ );
+ expect(step('pr-rtl', 'Require every applicable RTL shard').run).toContain(
+ '--force-full "${{ needs.check-components.outputs.force_full_component_audits }}"',
+ );
+ expect(step('pr-rtl-shard', 'Require completed RTL shard report').if).toBe(
+ 'always()',
+ );
+ expect(step('pr-rtl-shard', 'Run RTL audit')['continue-on-error']).toBe(
+ true,
+ );
+ });
+
+ it('does not run candidate capture, validation, or publication during release checks', () => {
+ for (const name of [
+ 'Build canonical maintenance Storybook',
+ 'Capture canonical visual baseline',
+ 'Validate canonical baseline capture',
+ ]) {
+ expect(runs(step('pr-visual', name)), name).toBe(false);
+ }
+ expect(runs(jobs['maintenance-request'])).toBe(false);
+ expect(runs(jobs['baseline-publication'])).toBe(false);
+ expect(runs(step('pr-visual', 'Download Storybook artifact'))).toBe(true);
+ const visual = step('pr-visual', 'Run full release visual check');
+ expect(visual.run).toContain('gate.mjs release');
+ expect(visual.run).not.toMatch(
+ /--(?:sample|only|components|themes|max-shots|tiers|no-scout)\b/,
+ );
+ expect(visual['continue-on-error']).toBeUndefined();
+ expect(
+ step('pr-visual', 'Upload release visual verdict and report').with[
+ 'if-no-files-found'
+ ],
+ ).toBe('error');
+ });
+
+ it.each([
+ [0, 'pass', 0],
+ [2, 'changed', 0],
+ [1, 'failed', 1],
+ [0, 'skipped', 1],
+ [0, 'unknown', 1],
+ [0, '', 1],
+ ])(
+ 'preserves canonical visual policy but rejects incomplete evidence (%s/%s)',
+ (code, verdict, expected) => {
+ const result = shell(
+ step('pr-visual', 'Run full release visual check').run,
+ {
+ TEST_CODE: String(code),
+ TEST_VERDICT: verdict,
+ GITHUB_STEP_SUMMARY: '/dev/null',
+ },
+ `
+ node() { return "$TEST_CODE"; }
+ jq() { printf '%s' "$TEST_VERDICT"; }
+ cat() { :; }
+ `,
+ );
+ expect(result.status, result.stderr).toBe(expected);
+ },
+ );
+});
diff --git a/.github/scripts/visual-gate/README.md b/.github/scripts/visual-gate/README.md
index e3f2538d81..a51076c6f3 100644
--- a/.github/scripts/visual-gate/README.md
+++ b/.github/scripts/visual-gate/README.md
@@ -6,10 +6,39 @@ Every visual-regression test uses the shared Storybook framework and
Add coverage to that owner, not to a new component, package, theme, scheduled,
post-CI, or post-merge workflow.
-Release evidence is the constituent pull request's exact-head `pr-visual` and
-`pr-a11y` checks, as defined in the public
-[Release Process](https://github.com/facebook/astryx/wiki/Release-Process).
-There is no separate daily release gate or retroactive visual-acceptance gate.
+## Explicit release checks
+
+Dispatch **CI** from `main` with `operation=release-check`. The event SHA is
+immutable for the run; the request and final `release-check` join reject a
+non-main ref or a SHA that is no longer current main. After main advances, dispatch
+again rather than reusing an earlier green run.
+
+The existing Storybook build feeds the same **Stable visual regression**
+(`pr-visual`), `pr-a11y`, and `pr-rtl` owners. Release scope is the closed full
+stable visual plan, unfiltered accessibility roster, and all five unfiltered RTL
+package shards. No changed-file, focused-component, or smoke scope applies.
+`release-check` requires every owner and setup job to succeed; failed, missing,
+cancelled, and skipped work is not release evidence.
+
+This changes when and where release evidence runs, not finding policy: visual
+`changed` still requires review, a11y fails on new baseline violations, and RTL
+findings remain soft while report completeness is mandatory. The dispatch does
+not capture baseline candidates, promote baselines, publish previews, or replace
+PR checks. It runs only on request, not every push. `visual-release-report` holds
+the visual evidence for that exact run/attempt.
+
+PR accessibility is intentionally smaller: explicit changed-component axe scope
+(including grouped-folder owners), plus the fast modal-close, theme-var, and
+story-play guards. Empty/shared scope never falls back to all stories, and
+missing or approximate analysis fails rather than granting an empty scope.
+The full axe roster, whole-repository accessibility spec-test contracts and their
+pixel/evidence uploads, and Probe reach sweep run only during `release-check`.
+
+Release callers must bind the CI run/attempt and all three job outcomes to its
+exact main SHA, and recheck main immediately before release mutation. The public
+[Release Process](https://github.com/facebook/astryx/wiki/Release-Process) needs a
+separate follow-up to replace constituent-PR-only gating with this dispatch; this
+CI capability does not update release automation.
## Coverage and results
@@ -89,8 +118,8 @@ pnpm visual:check --baseline .visual-baseline --out .visual-run
open .visual-run/report/index.html
```
-CLI exit codes: `0` clean, `1` crashed, `2` changed. `gate.mjs release` is the
-legacy command name for the closed full canonical plan, not a release gate.
+CLI exit codes: `0` clean, `1` crashed, `2` changed. `gate.mjs release` selects the
+closed full canonical plan used by broad PRs, release checks, and maintenance.
`gate.mjs accept` is an explicit local write; CI baseline publication uses it
inside the serialized publication turn. Local baselines must stay local:
platform and browser differences make them incomparable with the pinned CI
diff --git a/.github/scripts/visual-maintenance-workflow.test.mjs b/.github/scripts/visual-maintenance-workflow.test.mjs
index ce0b1fa67f..390aadbdc4 100644
--- a/.github/scripts/visual-maintenance-workflow.test.mjs
+++ b/.github/scripts/visual-maintenance-workflow.test.mjs
@@ -84,6 +84,7 @@ describe('CI baseline maintenance routing', () => {
expect(workflow.on.workflow_dispatch.inputs.operation.options).toEqual([
'capture',
'promote',
+ 'release-check',
]);
expect(visual.name).toBe('Stable visual regression');
expect(visual['runs-on']).toBe('2-core-ubuntu-arm');
@@ -195,12 +196,16 @@ describe('CI baseline maintenance routing', () => {
describe('canonical capture and publication separation', () => {
it('builds full maintenance Storybook only inside the existing visual owner', () => {
const build = step(visual, 'Build canonical maintenance Storybook');
- expect(build.if).toBe("github.event_name == 'workflow_dispatch'");
+ expect(build.if).toBe(
+ "github.event_name == 'workflow_dispatch' && inputs.operation == 'capture'",
+ );
expect(build.run).toBe(
'pnpm build && pnpm -F @astryxdesign/storybook build',
);
const capture = step(visual, 'Capture canonical visual baseline');
- expect(capture.if).toBe("github.event_name == 'workflow_dispatch'");
+ expect(capture.if).toBe(
+ "github.event_name == 'workflow_dispatch' && inputs.operation == 'capture'",
+ );
expect(capture.run).toContain('gate.mjs release');
expect(capture.run).not.toMatch(
/--(?:sample|only|components|themes|max-shots|tiers)\b/,
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 05eb777d5f..51a272ba64 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -11,14 +11,14 @@ on:
pull_request:
branches: ['main']
merge_group:
- # Explicit baseline maintenance shares the PR visual owner. It never runs as
- # a release gate and never changes the baseline without a reviewed promotion.
+ # Explicit release checks and baseline maintenance share the canonical owners.
+ # Only a reviewed promotion may change the baseline.
workflow_dispatch:
inputs:
operation:
- description: 'Capture canonical baseline candidates or promote a reviewed capture'
+ description: 'Check exact main for release, capture candidates, or promote a reviewed capture'
type: choice
- options: [capture, promote]
+ options: [capture, promote, release-check]
default: capture
required: true
run_id:
@@ -47,7 +47,7 @@ concurrency:
jobs:
maintenance-request:
- if: github.event_name == 'workflow_dispatch'
+ if: github.event_name == 'workflow_dispatch' && inputs.operation != 'release-check'
runs-on: ubuntu-slim
steps:
- name: Require explicit main-branch maintenance
@@ -76,7 +76,7 @@ jobs:
# Detect lightweight changes. Missing merge-base data fails closed.
check-scope:
- if: github.event_name != 'workflow_dispatch'
+ if: github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check'
runs-on: ubuntu-slim
permissions:
contents: read
@@ -85,8 +85,22 @@ jobs:
spec_only: ${{ steps.scope.outputs.spec_only }}
tooling_only: ${{ steps.scope.outputs.tooling_only }}
steps:
+ - name: Require exact current main for release
+ if: github.event_name == 'workflow_dispatch'
+ uses: actions/github-script@v9
+ with:
+ script: |
+ if (context.ref !== 'refs/heads/main') {
+ throw new Error('Release checks must be dispatched from main.');
+ }
+ const {data} = await github.rest.git.getRef({...context.repo, ref: 'heads/main'});
+ if (data.object.sha !== context.sha) {
+ throw new Error('Main changed since dispatch; dispatch release-check again.');
+ }
+
- uses: actions/checkout@v7
with:
+ ref: ${{ github.sha }}
fetch-depth: 50
- name: Fetch base branch
@@ -186,7 +200,7 @@ jobs:
# runner or fan out into visual, accessibility, or RTL work.
check-components:
needs: [check-scope]
- if: github.event_name == 'pull_request' && needs.check-scope.outputs.spec_only != 'true'
+ if: (github.event_name == 'pull_request' && needs.check-scope.outputs.spec_only != 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')
runs-on: ubuntu-slim
permissions:
contents: read
@@ -210,11 +224,16 @@ jobs:
fetch-depth: 50
- name: Fetch base branch
+ if: github.event_name == 'pull_request'
run: git fetch origin ${{ github.base_ref }} --depth=50
- name: Check for component changes
id: check
run: |
+ if [ "${{ github.event_name }}" = 'workflow_dispatch' ]; then
+ printf 'has_components=true\nhas_rtl_components=true\nhas_rtl_harness=true\nforce_full_component_audits=true\nhas_stable_visual=true\nbroad_stable_visual=true\n' >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
if [ "${{ needs.check-scope.outputs.docsite_only }}" = "true" ] \
|| [ "${{ needs.check-scope.outputs.spec_only }}" = "true" ] \
|| [ "${{ needs.check-scope.outputs.tooling_only }}" = "true" ]; then
@@ -476,13 +495,13 @@ jobs:
# `build` join below folds their results into the historical check name.
build-storybook:
needs: [check-scope]
- if: ${{ github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.check-scope.outputs.spec_only != 'true' }}
+ if: ${{ (github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') && always() && !cancelled() && needs.check-scope.outputs.spec_only != 'true' }}
runs-on: 2-core-ubuntu-arm
permissions:
contents: read
outputs:
storybook_url: ${{ steps.urls.outputs.storybook_url }}
- short_hash: ${{ steps.urls.outputs.short_hash }}
+ short_hash: ${{ steps.release.outputs.short_hash || steps.urls.outputs.short_hash }}
sandbox_url: ${{ steps.urls.outputs.sandbox_url }}
pr_number: ${{ steps.urls.outputs.pr_number }}
steps:
@@ -586,11 +605,19 @@ jobs:
echo "storybook_url=https://${REPO_OWNER}.github.io/${REPO_NAME}/pr/${PR_NUMBER}/" >> $GITHUB_OUTPUT
echo "sandbox_url=https://${REPO_OWNER}.github.io/${REPO_NAME}/pr/${PR_NUMBER}/sandbox/" >> $GITHUB_OUTPUT
+ - name: Identify full release audit scope
+ if: github.event_name == 'workflow_dispatch' && needs.check-scope.outputs.tooling_only != 'true'
+ id: release
+ run: |
+ test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
+ echo "short_hash=${GITHUB_SHA:0:7}" >> "$GITHUB_OUTPUT"
+ printf '{"forceFullComponentAudits":true}\n' > analysis.json
+
- name: Upload Storybook artifact
- if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
+ if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true' && (github.event_name == 'pull_request' || inputs.operation == 'release-check')
uses: actions/upload-artifact@v7
with:
- name: storybook-${{ steps.urls.outputs.short_hash }}
+ name: storybook-${{ steps.release.outputs.short_hash || steps.urls.outputs.short_hash }}
path: apps/storybook/dist/
retention-days: 30
@@ -606,10 +633,10 @@ jobs:
# Two paths, so the artifact is rooted at their common ancestor
# (packages/) — the download below unpacks it there.
- name: Upload built themes and core
- if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
+ if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true' && (github.event_name == 'pull_request' || inputs.operation == 'release-check')
uses: actions/upload-artifact@v7
with:
- name: dists-${{ steps.urls.outputs.short_hash }}
+ name: dists-${{ steps.release.outputs.short_hash || steps.urls.outputs.short_hash }}
path: |
packages/themes/*/dist/
packages/core/dist/
@@ -648,7 +675,7 @@ jobs:
EOF
- name: Upload analysis artifact
- if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
+ if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true' && (github.event_name == 'pull_request' || inputs.operation == 'release-check')
uses: actions/upload-artifact@v7
with:
name: pr-analysis
@@ -771,7 +798,7 @@ jobs:
# for the slower sandbox build.
pr-a11y:
needs: [build-storybook, check-components]
- if: github.event_name == 'pull_request' && needs.check-components.outputs.has_components == 'true'
+ if: (github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'
runs-on: 2-core-ubuntu-arm
permissions:
contents: read
@@ -805,13 +832,13 @@ jobs:
# audits" for the baseline workflow.
- name: Run accessibility audit
run: |
- COMPONENTS=$(jq -r '((.newComponentOwners // .newComponents // []) + (.modifiedComponentOwners // .modifiedComponents // [])) | join(",")' analysis.json)
- ANALYSIS_FORCE_FULL=$(jq -r '.forceFullComponentAudits // false' analysis.json)
SCOPE_ARGS=()
- if [ "${{ needs.check-components.outputs.force_full_component_audits }}" != "true" ] && [ "$ANALYSIS_FORCE_FULL" != "true" ] && [ -n "$COMPONENTS" ]; then
+ if [ "${{ github.event_name }}" = 'pull_request' ]; then
+ COMPONENTS=$(node .github/scripts/a11y-pr-scope.mjs analysis.json)
+ # An explicit empty filter means no changed components, never all
+ # stories. Shared-surface full sweeps belong to release-check.
SCOPE_ARGS=(--components "$COMPONENTS")
- else
- echo "Component scope is policy-sensitive or unresolved — running the full accessibility audit."
+ echo "PR accessibility scope: ${COMPONENTS:-no changed components; fast browser guards still run}"
fi
node .github/scripts/accessibility-audit.js \
--storybook-dir apps/storybook/dist \
@@ -858,20 +885,17 @@ jobs:
- name: Run story play guard
run: node .github/scripts/story-play-guard.js --storybook-dir apps/storybook/dist
- # The reusable accessibility spec-test contracts (internal/a11y-spec) and
- # the component bindings that adopt them. jsdom cannot compute a role or
- # an accessible name, resolve a real tab sequence, or turn a key press
- # into an activation, so those expectations are reported `unrun` in the
- # unit lane and proven here or not at all. Hosted with the sibling
- # Chromium guards for the same reason they are: pr-a11y is the blocking
- # job that runs whenever components change.
+ # Run the exhaustive contract/fixture matrix at release time. PRs retain
+ # scoped axe validation and the fast interaction guards above; they must
+ # not pay for every component's browser bindings on every change.
- name: Run accessibility spec-test contracts
+ if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
env:
- ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
run: pnpm test:a11y-contract
- name: Upload pressed-state pixel evidence
- if: always()
+ if: always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
uses: actions/upload-artifact@v7
with:
name: pressed-state-evidence-${{ needs.build-storybook.outputs.short_hash }}
@@ -884,7 +908,7 @@ jobs:
# so the frames and their sensor receipts are produced here, bound to the
# same exact head as every other check in this job.
- name: Upload component-audit browser evidence
- if: always()
+ if: always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
uses: actions/upload-artifact@v7
with:
name: component-audit-evidence-${{ needs.build-storybook.outputs.short_hash }}
@@ -895,6 +919,7 @@ jobs:
# Baseline-free target/axis diagnostics are not a visual-regression lane.
# Keep their existing report-only behavior with the other browser guards.
- name: Check Probe theme reach
+ if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
continue-on-error: true
run: |
node .github/scripts/visual-gate/gate.mjs reach \
@@ -902,7 +927,7 @@ jobs:
--out .visual-reach
- name: Upload Probe reach report
- if: always()
+ if: always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
uses: actions/upload-artifact@v7
with:
name: visual-reach
@@ -977,7 +1002,10 @@ jobs:
needs.check-components.result == 'success' &&
needs.check-components.outputs.has_stable_visual == 'true') ||
(github.event_name == 'workflow_dispatch' &&
- needs.maintenance-request.result == 'success' && inputs.operation == 'capture'))
+ ((inputs.operation == 'release-check' &&
+ needs.build-storybook.result == 'success' &&
+ needs.check-components.result == 'success') ||
+ (needs.maintenance-request.result == 'success' && inputs.operation == 'capture'))))
runs-on: 2-core-ubuntu-arm
permissions:
contents: read
@@ -997,7 +1025,7 @@ jobs:
name: pr-analysis
- name: Download Storybook artifact
- if: github.event_name == 'pull_request'
+ if: github.event_name == 'pull_request' || inputs.operation == 'release-check'
uses: actions/download-artifact@v8
with:
name: storybook-${{ needs.build-storybook.outputs.short_hash }}
@@ -1005,7 +1033,7 @@ jobs:
# If the optional theme artifact is missing, the gate builds the themes.
- name: Download built themes and core
- if: github.event_name == 'pull_request'
+ if: github.event_name == 'pull_request' || inputs.operation == 'release-check'
continue-on-error: true
uses: actions/download-artifact@v8
with:
@@ -1017,11 +1045,11 @@ jobs:
# Downloaded theme builds import Core's consumer-facing dist files.
- name: Build Core dependency for theme inspection
- if: github.event_name == 'pull_request'
+ if: github.event_name == 'pull_request' || inputs.operation == 'release-check'
run: pnpm -F @astryxdesign/core build
- name: Build canonical maintenance Storybook
- if: github.event_name == 'workflow_dispatch'
+ if: github.event_name == 'workflow_dispatch' && inputs.operation == 'capture'
run: pnpm build && pnpm -F @astryxdesign/storybook build
- name: Fetch visual baseline from gh-pages
@@ -1113,9 +1141,42 @@ jobs:
retention-days: 7
if-no-files-found: ignore
+ - name: Run full release visual check
+ if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
+ run: |
+ set -eu
+ set +e
+ node .github/scripts/visual-gate/gate.mjs release \
+ --storybook-dir apps/storybook/dist \
+ --baseline .visual-baseline \
+ --out .visual-run \
+ --summary-output visual-summary.md
+ code=$?
+ set -e
+ case "$code" in 0|2) ;; *) exit "$code" ;; esac
+ STATUS=$(jq -er '.status' .visual-run/verdict.json)
+ case "$STATUS" in
+ pass|changed) ;;
+ *) echo "Visual evidence is incomplete: $STATUS"; exit 1 ;;
+ esac
+ cat visual-summary.md >> "$GITHUB_STEP_SUMMARY"
+
+ - name: Upload release visual verdict and report
+ if: always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
+ uses: actions/upload-artifact@v7
+ with:
+ name: visual-release-report
+ path: |
+ .visual-run/verdict.json
+ .visual-run/manifest.json
+ .visual-run/shots/
+ .visual-run/report/
+ retention-days: 14
+ if-no-files-found: error
+
- name: Capture canonical visual baseline
id: maintenance-capture
- if: github.event_name == 'workflow_dispatch'
+ if: github.event_name == 'workflow_dispatch' && inputs.operation == 'capture'
# A complete browser-refresh capture can be incomparable with the old
# baseline. The next step requires full capture, not a clean comparison.
continue-on-error: true
@@ -1129,7 +1190,7 @@ jobs:
- name: Validate canonical baseline capture
id: maintenance-validation
if: >-
- always() && github.event_name == 'workflow_dispatch' &&
+ always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'capture' &&
steps.maintenance-capture.outcome != 'skipped'
env:
CAPTURE_SHA: ${{ github.sha }}
@@ -1285,7 +1346,8 @@ jobs:
name: pr-rtl (${{ matrix.package }})
needs: [build-storybook, check-components]
if: >-
- github.event_name == 'pull_request' &&
+ (github.event_name == 'pull_request' ||
+ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) &&
(needs.check-components.outputs.has_rtl_components == 'true' ||
needs.check-components.outputs.has_rtl_harness == 'true' ||
needs.check-components.outputs.force_full_component_audits == 'true')
@@ -1504,7 +1566,7 @@ jobs:
# Stable required context joining the five package shards above.
pr-rtl:
needs: [check-scope, check-components, pr-rtl-shard]
- if: ${{ github.event_name != 'workflow_dispatch' && always() && !cancelled() && github.event_name == 'pull_request' && needs.check-scope.outputs.spec_only != 'true' }}
+ if: ${{ always() && !cancelled() && ((github.event_name == 'pull_request' && needs.check-scope.outputs.spec_only != 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) }}
runs-on: ubuntu-slim
timeout-minutes: 5
steps:
@@ -1527,3 +1589,45 @@ jobs:
--should-run "${{ needs.check-components.outputs.has_rtl_components == 'true' || needs.check-components.outputs.has_rtl_harness == 'true' || needs.check-components.outputs.force_full_component_audits == 'true' }}" \
--force-full "${{ needs.check-components.outputs.force_full_component_audits }}" \
--reports-dir rtl-shard-reports
+
+ # Release-time projection only: the existing owners above do all measurement.
+ # A skipped owner or main drift must never look like passing release evidence.
+ release-check:
+ needs:
+ [
+ check-scope,
+ check-components,
+ build-storybook,
+ pr-visual,
+ pr-a11y,
+ pr-rtl,
+ ]
+ if: ${{ always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' }}
+ runs-on: ubuntu-slim
+ permissions:
+ contents: read
+ steps:
+ - name: Require complete exact-main release checks
+ uses: actions/github-script@v9
+ env:
+ RELEASE_NEEDS: ${{ toJSON(needs) }}
+ with:
+ script: |
+ const needs = JSON.parse(process.env.RELEASE_NEEDS);
+ for (const name of ['check-scope', 'check-components', 'build-storybook', 'pr-visual', 'pr-a11y', 'pr-rtl']) {
+ if (needs[name]?.result !== 'success') {
+ throw new Error(`Required release job ${name} did not succeed: ${needs[name]?.result}`);
+ }
+ }
+ if (context.ref !== 'refs/heads/main') {
+ throw new Error('Release checks must be dispatched from main.');
+ }
+ const {data} = await github.rest.git.getRef({...context.repo, ref: 'heads/main'});
+ if (data.object.sha !== context.sha) {
+ throw new Error('Main changed during checks; dispatch release-check again.');
+ }
+ await core.summary
+ .addHeading('Release checks complete')
+ .addRaw(`Exact main SHA: ${context.sha}\n\n`)
+ .addRaw('Canonical visual, accessibility, and RTL checks completed with full scope. Recheck main before release mutation; this run does not approve or publish a baseline.')
+ .write();
diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.md
index bd279874d9..f2a0c05b9d 100644
--- a/docs/specs/AST-030/spec.md
+++ b/docs/specs/AST-030/spec.md
@@ -159,8 +159,22 @@ they are separately named.
consume that run's artifacts without recapturing or recomparing pixels.
Explicit full-plan baseline capture and reviewed baseline publication MUST
remain in `ci.yml`; they are maintenance operations, not release gates.
- Release evidence remains the constituent PR's exact-head `pr-visual` and
- `pr-a11y` checks, never a daily gate or retroactive acceptance status.
+ Release evidence MUST come from an explicit `operation=release-check`
+ `workflow_dispatch` in this same workflow, dispatched from `main` and bound to
+ its exact event SHA. It MUST run the canonical `pr-visual` (**Stable visual
+ regression**), `pr-a11y`, and `pr-rtl` owners with full scope: the closed stable
+ visual plan and unfiltered accessibility/RTL component rosters. Changed-file,
+ focused, smoke, and no-op paths MUST NOT narrow release checks. PR a11y MUST
+ remain scoped to changed components plus fast interaction guards; full a11y
+ sweeps, whole-repository spec-test contracts, their evidence uploads, and Probe
+ reach MUST run only for `release-check` in this workflow. Missing,
+ failed, cancelled, or skipped required work MUST block the release-check join.
+ The request and join MUST verify that the checked SHA is still current `main`;
+ release callers MUST recheck it before mutation and dispatch again after drift.
+ This replaces constituent-PR-only release gating, not the canonical checks'
+ existing finding policies. Release checks MUST NOT run on every push, capture
+ baseline candidates, publish baselines, or use a separate daily workflow or
+ retroactive acceptance status.
Deployment, accessibility, RTL, and vibe evidence MAY retain their workflows
and artifacts when they do not duplicate visual regression. A new or existing
surface, component, package, theme family, or visual suite MUST join the
@@ -273,6 +287,31 @@ PR visual owners; counting internal jobs or required status projections as
lanes; and implicit expansion under an undefined “additional specialized
surface” exception.
+### DEC-5 — Release checks reuse the canonical owners on exact main
+
+**Reference:** `spec:AST-030/DEC-5`
+**Decider:** `cixzhang`, `2026-09-23`
+
+Run release evidence against exact current `main`, not only constituent PR heads.
+Use an explicit release-time dispatch in `ci.yml` so full visual, accessibility,
+and RTL checks do not run on every main push. Reuse existing test/build owners,
+keep their finding policies, and fail closed on incomplete scope, missing work,
+or main drift. Baseline capture and reviewed promotion remain separate operations.
+
+PR accessibility remains a scoped, fast check: audit only explicitly resolved
+changed component owners and retain the fast modal-close, theme-var, and story-play
+browser guards. Never widen a PR to the exhaustive accessibility sweep because a
+shared path changed or the component set is empty. Missing or approximate analysis
+fails the scoped check rather than silently claiming no work. Multi-component
+folders expand only to their own canonical component owners or existing umbrella
+Storybook routes; an exported name without either route cannot be passed to axe. The full
+accessibility roster, whole-repository spec-test contracts and their evidence
+uploads, and Probe reach sweep run only on `release-check` in this workflow.
+The release path retains the complete suite and cannot substitute a scoped result.
+
+Rejected: a separate workflow, per-push full audits, and treating a maintenance
+capture, skipped check, old main SHA, or retroactive status as release evidence.
+
## Open questions
None.