An open source design system that's fully customizable and agent ready
TypeScript
ci: per-suite ci:run-visual, ci:run-a11y and ci:run-rtl labels replace ci:heavy-lanes (#9165)
Cindy Zhang4cb7f27aa654
diff --git a/.github/scripts/ci-heavy-lanes.test.mjs b/.github/scripts/ci-heavy-lanes.test.mjsindex da1d133992..031b6bf7c3 100644--- a/.github/scripts/ci-heavy-lanes.test.mjs+++ b/.github/scripts/ci-heavy-lanes.test.mjs@@ -21,34 +21,83 @@ const ci = read('ci.yml');const heavy = read('main-heavy-lanes.yml');const main = read('deploy.yml');-const LABEL = 'ci:heavy-lanes';-const HEAVY = [- 'pr-a11y-guards',- 'pr-a11y-specs',- 'pr-a11y',- 'visual-scout',- 'pr-visual',- 'pr-rtl-shard',- 'pr-rtl-merge',- 'pr-rtl',-];-const PR_CLAUSE = `(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, '${LABEL}'))`;+const SUITE = {+ 'pr-a11y-guards': 'a11y',+ 'pr-a11y-specs': 'a11y',+ 'pr-a11y': 'a11y',+ 'visual-scout': 'visual',+ 'pr-visual': 'visual',+ 'pr-rtl-shard': 'rtl',+ 'pr-rtl-merge': 'rtl',+ 'pr-rtl': 'rtl',+};+const HEAVY = Object.keys(SUITE);+const prClause = suite =>+ `(github.event_name == 'pull_request' && needs.run-labels.outputs.${suite} == 'true')`;describe('visual, accessibility and RTL owners', () => {// release-check-workflow.test.mjs evaluates them for release-check and- // visual-maintenance-workflow.test.mjs for labelled and unlabelled pull+ // visual-maintenance-workflow.test.mjs for opted-in and other pull// requests; this pins the shape on every owner.it.each(HEAVY)(- '%s runs on a pull request only with the ci:heavy-lanes label',+ '%s runs on a pull request only when run-labels opts in its own suite',name => {const condition = ungated(ci.jobs[name].if);- expect(condition).toContain(PR_CLAUSE);- expect(condition.replaceAll(PR_CLAUSE, '')).not.toContain(+ expect(condition).toContain(prClause(SUITE[name]));+ expect(condition.replaceAll(prClause(SUITE[name]), '')).not.toContain("'pull_request'",);+ // No other suite's decision, and no label read directly.+ for (const other of ['visual', 'a11y', 'rtl']) {+ if (other !== SUITE[name])+ expect(condition).not.toContain(`outputs.${other}`);+ }+ expect(condition).not.toMatch(/labels\.\*\.name, 'ci:(heavy|run-)/);+ expect([ci.jobs[name].needs].flat()).toContain('run-labels');},);+ it('decides the suites in one gate job from the trusted decision script', () => {+ const gate = ci.jobs['run-labels'];+ expect(gate['runs-on']).toBe('ubuntu-slim');+ expect(gate.permissions).toEqual({+ contents: 'read',+ 'pull-requests': 'read',+ });+ expect(gate.outputs).toEqual({+ visual: '${{ steps.decide.outputs.visual }}',+ a11y: '${{ steps.decide.outputs.a11y }}',+ rtl: '${{ steps.decide.outputs.rtl }}',+ });+ expect(gate.steps[0].with).toMatchObject({+ 'sparse-checkout':+ '.github/scripts/run-labels.cjs\n.github/scripts/review-signal-decision.cjs\n',+ path: '.run-labels',+ 'persist-credentials': false,+ });+ expect(gate.steps[0].with.ref).toBeUndefined();+ expect(gate.steps[1].with.script).toContain(+ '.run-labels/.github/scripts/run-labels.cjs',+ );+ // It runs for the release check too, so its owners' needs succeed there.+ expect(ungated(gate.if)).toBe(+ "github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check'",+ );+ });++ it('names no catch-all heavy label anywhere in the workflows', () => {+ for (const name of fs.readdirSync(+ new URL('../workflows/', import.meta.url),+ ))+ expect(+ fs.readFileSync(+ new URL(`../workflows/${name}`, import.meta.url),+ 'utf8',+ ),+ name,+ ).not.toContain('ci:heavy-lanes');+ });+it('leaves the required joins without a heavy owner, so they still report on every pull request', () => {for (const join of ['test', 'build', 'docsite-test']) {const needs = [ci.jobs[join].needs].flat();diff --git a/.github/scripts/ci-pr-gate.test.mjs b/.github/scripts/ci-pr-gate.test.mjsindex f170e27f62..f22da8cfff 100644--- a/.github/scripts/ci-pr-gate.test.mjs+++ b/.github/scripts/ci-pr-gate.test.mjs@@ -228,7 +228,7 @@ describe('pull-request CI gate (spec:AST-030 FR17)', () => {expect(runs({})).toBe(true);expect(runs({fork: true})).toBe(false);expect(runs({fork: true, labels: ['ci:run']})).toBe(true);- expect(runs({fork: true, labels: ['ci:heavy-lanes']})).toBe(false);+ expect(runs({fork: true, labels: ['ci:run-visual']})).toBe(false);expect(runs({draft: true})).toBe(false);expect(runs({draft: true, fork: true, labels: ['ci:run']})).toBe(false);});diff --git a/.github/scripts/lib/a11y-format.js b/.github/scripts/lib/a11y-format.jsindex bd2b189c52..1f2f82aaa8 100644--- a/.github/scripts/lib/a11y-format.js+++ b/.github/scripts/lib/a11y-format.js@@ -6,6 +6,7 @@*/const {inline, num, safeUrl} = require('./report-text');+const {notRunSentence} = require('../run-labels.cjs');// Impact emoji badgesconst impactEmoji = {@@ -45,9 +46,9 @@ function formatWcagTags(tags) {function buildA11ySection(a11yReport, storiesAuditedByComponent) {let a11ySection = '### Accessibility Audit\n\n';// No report: the audit did not run (pull requests run it only with the- // `ci:heavy-lanes` label, spec:AST-030 FR12). Never claim a clean result.+ // `ci:run-a11y` label, spec:AST-030 FR12). Never claim a clean result.if (!a11yReport) {- return a11ySection + '**Status:** The accessibility audit did not run on this pull request. It runs after merges to `main` and before each release; pull requests that touch components run it with the `ci:heavy-lanes` label.\n\n';+ return `${a11ySection}**Status:** ${notRunSentence('a11y')} It runs after merges to \`main\` and before each release.\n\n`;}const totalViolations = Object.values(a11yReport.components || {}).reduce((sum, comp) => sum + (comp.violations?.length || 0), 0);diff --git a/.github/scripts/lib/a11y-format.test.mjs b/.github/scripts/lib/a11y-format.test.mjsindex a2ee2983fd..63b9180f80 100644--- a/.github/scripts/lib/a11y-format.test.mjs+++ b/.github/scripts/lib/a11y-format.test.mjs@@ -3,19 +3,28 @@import {describe, expect, it} from 'vitest';import {createRequire} from 'node:module';-const {buildA11ySection, formatWcagTags} = createRequire(import.meta.url)('./a11y-format.js');+const {buildA11ySection, formatWcagTags} = createRequire(import.meta.url)(+ './a11y-format.js',+);-const report = (violations) => ({+const report = violations => ({components: {Button: {storiesAudited: 4, violations}},});describe('buildA11ySection', () => {it('says so plainly when there is nothing to report', () => {- expect(buildA11ySection({components: {}})).toContain('No accessibility violations detected');+ expect(buildA11ySection({components: {}})).toContain(+ 'No accessibility violations detected',+ );});it('says the audit did not run when there is no report', () => {- expect(buildA11ySection(null)).toContain('did not run on this pull request');+ expect(buildA11ySection(null)).toContain(+ 'did not run on this pull request',+ );+ expect(buildA11ySection(null)).toContain(+ 'Accessibility did not run on this pull request; add `ci:run-a11y` to run it.',+ );});it('lists a violation with its rule, story count, and help link', () => {@@ -31,10 +40,14 @@ describe('buildA11ySection', () => {},]),);- expect(section).toContain('**serious**: Elements must have sufficient color contrast');+ expect(section).toContain(+ '**serious**: Elements must have sufficient color contrast',+ );expect(section).toContain('Rule: `color-contrast`');expect(section).toContain('Affects 2/4 stories');- expect(section).toContain('[Learn more](https://dequeuniversity.com/rules/axe/4.10/color-contrast)');+ expect(section).toContain(+ '[Learn more](https://dequeuniversity.com/rules/axe/4.10/color-contrast)',+ );expect(section).toContain('WCAG: 1.4.3 (Level AA)');});@@ -49,7 +62,9 @@ describe('buildA11ySection', () => {},]),);- expect(section).toContain('line one line two with <em>markup</em> and \\[brackets\\]');+ expect(section).toContain(+ 'line one line two with <em>markup</em> and \\[brackets\\]',+ );// Rule ids keep their own alphabet only, so the code span stays a code span.expect(section).toContain('Rule: `ruleoddname`');// A help value that is not a plain https URL renders no link at all.diff --git a/.github/scripts/lib/pr-preview.mjs b/.github/scripts/lib/pr-preview.mjsindex fafbfb4a8c..6424e2899a 100644--- a/.github/scripts/lib/pr-preview.mjs+++ b/.github/scripts/lib/pr-preview.mjs@@ -566,7 +566,7 @@ export async function reconcilePrComment({? ['--base-stats', baseStatsPath]: []),// No report means the audit did not run (it runs on main and release- // checks, or with the ci:heavy-lanes label); the comment says so.+ // checks, or with the ci:run-a11y label); the comment says so....(fs.existsSync(a11yPath) ? ['--a11y', a11yPath] : []),...(fs.existsSync(visualPath) ? ['--visual', visualPath] : []),...(storybook ? ['--storybook-url', `${previewOrigin}/storybook/`] : []),diff --git a/.github/scripts/release-check-workflow.test.mjs b/.github/scripts/release-check-workflow.test.mjsindex 02a3d28e22..a7d17e1b2c 100644--- a/.github/scripts/release-check-workflow.test.mjs+++ b/.github/scripts/release-check-workflow.test.mjs@@ -25,6 +25,9 @@ const packageJson = JSON.parse(const releaseJobs = ['release-authority','test-registry-e2e',+ // Decides the pull-request opt-ins; on a release check it opts nothing in+ // and succeeds, so the owners that need it run.+ 'run-labels','build-storybook','typecheck','visual-scout',diff --git a/.github/scripts/run-labels.cjs b/.github/scripts/run-labels.cjsnew file mode 100644index 0000000000..2a549ce9ac--- /dev/null+++ b/.github/scripts/run-labels.cjs@@ -0,0 +1,145 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Decides which heavy suites a pull request opted into with a+ * `ci:run-<suite>` label (spec:AST-030 FR12, DEC-7).+ *+ * A suite runs on a pull request only while the pull request carries its+ * label, and only when the newest application of that label came from someone+ * with write, maintain or admin access. Agent lanes push with write access,+ * so their labels count. The decision reads the payload of the event that+ * started the run, so applying or removing a label starts nothing; it takes+ * effect on the next push or reopen (FR17). Outside a pull request no label+ * applies, and the release check runs every suite on its own terms. Any+ * lookup that fails denies the suite (fail closed).+ */++'use strict';++// The review gate's own write-access rule, so a label and a review answer the+// same question the same way (custom write-based roles report `write`).+const {hasWritePermission} = require('./review-signal-decision.cjs');++/** Suites a pull request can opt into, by output name and label. */+const SUITE_LABELS = Object.freeze({+ visual: 'ci:run-visual',+ a11y: 'ci:run-a11y',+ rtl: 'ci:run-rtl',+});++/** Display names for the pull-request comment's not-run sentence. */+const SUITE_NAMES = Object.freeze({+ visual: 'Visual',+ a11y: 'Accessibility',+ rtl: 'RTL',+});++/**+ * The comment's sentence for a suite a pull request did not run, with the+ * label that runs it.+ */+function notRunSentence(suite) {+ return `${SUITE_NAMES[suite]} did not run on this pull request; add \`ci:run-${suite}\` to run it.`;+}++/**+ * The newest actor that applied each label, from the pull request's timeline.+ * Only the newest application counts: a later one by someone without write+ * access does not inherit an earlier maintainer's.+ */+async function newestLabelers(github, {owner, repo, number}) {+ const data = await github.graphql(+ `query($owner: String!, $repo: String!, $number: Int!) {+ repository(owner: $owner, name: $repo) {+ pullRequest(number: $number) {+ timelineItems(last: 100, itemTypes: [LABELED_EVENT]) {+ nodes { ... on LabeledEvent { actor { login } label { name } } }+ }+ }+ }+ }`,+ {owner, repo, number},+ );+ const labelers = new Map();+ for (const event of data.repository.pullRequest.timelineItems.nodes) {+ const name = event?.label?.name;+ if (name != null) labelers.set(name, event.actor?.login ?? null);+ }+ return labelers;+}++/**+ * Decides every suite and sets one `true`/`false` output per suite.+ * @returns {Promise<Record<string, boolean>>}+ */+async function decideRunLabels({github, context, core}) {+ const decisions = Object.fromEntries(+ Object.keys(SUITE_LABELS).map(suite => [suite, false]),+ );+ const pr = context.payload.pull_request;+ if (context.eventName === 'pull_request' && pr != null) {+ const carried = new Set((pr.labels ?? []).map(label => label.name));+ const wanted = Object.entries(SUITE_LABELS).filter(([, label]) =>+ carried.has(label),+ );+ if (wanted.length > 0) {+ const {owner, repo} = context.repo;+ let labelers = new Map();+ try {+ labelers = await newestLabelers(github, {+ owner,+ repo,+ number: pr.number,+ });+ } catch (error) {+ core.warning(+ `Could not read who applied the ci:run labels: ${error.message}`,+ );+ }+ // One lookup per labeler; a failed lookup denies only that labeler's+ // suites.+ const access = new Map();+ const accessOf = async login => {+ if (!access.has(login)) {+ try {+ const {data} =+ await github.rest.repos.getCollaboratorPermissionLevel({+ owner,+ repo,+ username: login,+ });+ access.set(login, {+ writes: hasWritePermission(data),+ permission: data?.permission ?? null,+ });+ } catch (error) {+ core.warning(`Could not check ${login}'s access: ${error.message}`);+ access.set(login, {writes: false, permission: null});+ }+ }+ return access.get(login);+ };+ for (const [suite, label] of wanted) {+ const login = labelers.get(label) ?? null;+ const {writes, permission} =+ login == null+ ? {writes: false, permission: null}+ : await accessOf(login);+ decisions[suite] = writes;+ if (!writes) {+ core.notice(+ login == null+ ? `No ${label} label event could be read; the ${suite} suite does not run.`+ : `${label} was applied by ${login} (${permission ?? 'unknown access'}); only write access runs the ${suite} suite.`,+ );+ }+ }+ }+ }+ for (const [suite, runs] of Object.entries(decisions)) {+ core.setOutput(suite, String(runs));+ }+ return decisions;+}++module.exports = {SUITE_LABELS, decideRunLabels, notRunSentence};diff --git a/.github/scripts/run-labels.test.mjs b/.github/scripts/run-labels.test.mjsnew file mode 100644index 0000000000..87cccc66e8--- /dev/null+++ b/.github/scripts/run-labels.test.mjs@@ -0,0 +1,253 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Per-suite opt-in labels for the heavy owners.+ * @input run-labels.cjs with a mocked GitHub API, and ci.yml's owner conditions+ * @output Each `ci:run-<suite>` label, applied with write access, runs only its+ * own suite; a missing, removed or unauthorized label runs none+ * @position Node contracts for AST-030 FR12 and FR17+ */++import fs from 'node:fs';+import {createRequire} from 'node:module';+import {describe, expect, it} from 'vitest';+import yaml from 'yaml';+import {ungated} from './ci-pr-gate.mjs';++const require = createRequire(import.meta.url);+const {+ SUITE_LABELS,+ decideRunLabels,+ notRunSentence,+} = require('./run-labels.cjs');++const ci = yaml.parse(+ fs.readFileSync(new URL('../workflows/ci.yml', import.meta.url), 'utf8'),+);++/** Runs the decision against a mocked pull request and GitHub API. */+async function decide({+ eventName = 'pull_request',+ labels = [],+ events = labels.map(name => ({actor: {login: 'maintainer'}, label: {name}})),+ permissions = {maintainer: 'write'},+ failLookup = false,+ failPermission = [],+} = {}) {+ const outputs = {};+ const notices = [];+ const lookups = [];+ const core = {+ setOutput: (name, value) => {+ outputs[name] = value;+ },+ notice: message => notices.push(message),+ warning: message => notices.push(message),+ };+ const github = {+ graphql: async (_query, variables) => {+ if (failLookup) throw new Error('rate limited');+ expect(variables).toEqual({owner: 'meta', repo: 'astryx', number: 7});+ return {repository: {pullRequest: {timelineItems: {nodes: events}}}};+ },+ rest: {+ repos: {+ getCollaboratorPermissionLevel: async ({username}) => {+ lookups.push(username);+ if (failPermission.includes(username)) throw new Error('timeout');+ return {data: {permission: permissions[username] ?? 'read'}};+ },+ },+ },+ };+ const context = {+ eventName,+ repo: {owner: 'meta', repo: 'astryx'},+ payload: {+ pull_request:+ eventName === 'pull_request'+ ? {number: 7, labels: labels.map(name => ({name}))}+ : undefined,+ },+ };+ await decideRunLabels({github, context, core});+ return {outputs, notices, lookups};+}++describe('run-labels decision', () => {+ it('words the not-run sentence the comment shows for each suite', () => {+ expect(notRunSentence('visual')).toBe(+ 'Visual did not run on this pull request; add `ci:run-visual` to run it.',+ );+ expect(notRunSentence('a11y')).toBe(+ 'Accessibility did not run on this pull request; add `ci:run-a11y` to run it.',+ );+ expect(notRunSentence('rtl')).toBe(+ 'RTL did not run on this pull request; add `ci:run-rtl` to run it.',+ );+ });++ it('names one label per suite', () => {+ expect(SUITE_LABELS).toEqual({+ visual: 'ci:run-visual',+ a11y: 'ci:run-a11y',+ rtl: 'ci:run-rtl',+ });+ });++ it.each(Object.entries(SUITE_LABELS))(+ 'opts in only %s for %s',+ async (suite, label) => {+ const {outputs} = await decide({labels: [label]});+ for (const other of Object.keys(SUITE_LABELS))+ expect(outputs[other], other).toBe(String(other === suite));+ },+ );++ // GitHub reports maintain and custom write-based roles as `write`; the+ // review gate's hasWritePermission decides, so labels and reviews agree.+ it('runs a suite when its label came from write or admin access', async () => {+ for (const permission of ['write', 'admin']) {+ const {outputs} = await decide({+ labels: ['ci:run-a11y'],+ permissions: {maintainer: permission},+ });+ expect(outputs.a11y, permission).toBe('true');+ }+ });++ it('does not run a suite labelled with read or no access, and says why', async () => {+ for (const permission of ['read', 'none']) {+ const {outputs, notices} = await decide({+ labels: ['ci:run-rtl'],+ permissions: {maintainer: permission},+ });+ expect(outputs.rtl, permission).toBe('false');+ expect(notices.join('\n')).toContain('maintainer');+ }+ });++ it('denies only the suites of a labeler whose access lookup fails', async () => {+ const {outputs} = await decide({+ labels: ['ci:run-visual', 'ci:run-rtl'],+ events: [+ {actor: {login: 'maintainer'}, label: {name: 'ci:run-visual'}},+ {actor: {login: 'flaky'}, label: {name: 'ci:run-rtl'}},+ ],+ permissions: {maintainer: 'write', flaky: 'write'},+ failPermission: ['flaky'],+ });+ expect(outputs).toEqual({visual: 'true', a11y: 'false', rtl: 'false'});+ });++ it("judges each label's newest application, not an earlier one", async () => {+ const {outputs} = await decide({+ labels: ['ci:run-visual', 'ci:run-rtl'],+ events: [+ {actor: {login: 'maintainer'}, label: {name: 'ci:run-visual'}},+ {actor: {login: 'maintainer'}, label: {name: 'ci:run-rtl'}},+ {actor: {login: 'triager'}, label: {name: 'ci:run-visual'}},+ ],+ permissions: {maintainer: 'write', triager: 'read'},+ });+ expect(outputs).toEqual({visual: 'false', a11y: 'false', rtl: 'true'});+ });++ it('runs nothing for a removed label, even though its event is in the timeline', async () => {+ const {outputs} = await decide({+ labels: [],+ events: [{actor: {login: 'maintainer'}, label: {name: 'ci:run-visual'}}],+ });+ expect(outputs).toEqual({visual: 'false', a11y: 'false', rtl: 'false'});+ });++ it('fails closed when the lookup fails or finds no label event', async () => {+ expect(+ (await decide({labels: ['ci:run-visual'], failLookup: true})).outputs,+ ).toEqual({visual: 'false', a11y: 'false', rtl: 'false'});+ expect(+ (await decide({labels: ['ci:run-visual'], events: []})).outputs.visual,+ ).toBe('false');+ });++ it('looks each labeler up once and makes no call without a suite label', async () => {+ const {lookups} = await decide({+ labels: ['ci:run-visual', 'ci:run-a11y', 'ci:run-rtl'],+ });+ expect(lookups).toEqual(['maintainer']);+ const none = await decide({labels: ['ci:run', 'bug']});+ expect(none.lookups).toEqual([]);+ expect(none.outputs).toEqual({+ visual: 'false',+ a11y: 'false',+ rtl: 'false',+ });+ });++ it('opts nothing in outside a pull request', async () => {+ for (const eventName of ['push', 'workflow_dispatch', 'merge_group']) {+ const {outputs} = await decide({eventName});+ expect(outputs, eventName).toEqual({+ visual: 'false',+ a11y: 'false',+ rtl: 'false',+ });+ }+ });+});++// Replay: each label's decision through every heavy owner's condition on a+// pull request whose other needs succeeded.+describe('each label runs only its own suite', () => {+ const OWNERS = {+ visual: ['visual-scout', 'pr-visual'],+ a11y: ['pr-a11y-guards', 'pr-a11y-specs', 'pr-a11y'],+ rtl: ['pr-rtl-shard', 'pr-rtl-merge', 'pr-rtl'],+ };++ function runsOnPullRequest(job, decision) {+ const expression = ungated(job.if)+ .replace(/^\$\{\{\s*|\s*\}\}$/g, '')+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');+ const needs = Object.fromEntries(+ [job.needs].flat().map(name => [+ name,+ {+ result: 'success',+ outputs: name === 'run-labels' ? decision : {},+ },+ ]),+ );+ return Function(+ 'github',+ 'inputs',+ 'needs',+ 'always',+ 'cancelled',+ `return Boolean(${expression});`,+ )(+ {event_name: 'pull_request', event: {pull_request: {labels: []}}},+ {},+ needs,+ () => true,+ () => false,+ );+ }++ it.each([+ [[]],+ [['ci:run-visual']],+ [['ci:run-a11y']],+ [['ci:run-rtl']],+ [['ci:run-visual', 'ci:run-rtl']],+ ])('with %j', async labels => {+ const {outputs} = await decide({labels});+ const ran = Object.entries(OWNERS)+ .flatMap(([, owners]) => owners)+ .filter(owner => runsOnPullRequest(ci.jobs[owner], outputs));+ const expected = Object.entries(OWNERS)+ .filter(([suite]) => labels.includes(SUITE_LABELS[suite]))+ .flatMap(([, owners]) => owners);+ expect(ran.sort()).toEqual(expected.sort());+ });+});diff --git a/.github/scripts/visual-gate/README.md b/.github/scripts/visual-gate/README.mdindex 6963070656..a70b86b278 100644--- a/.github/scripts/visual-gate/README.md+++ b/.github/scripts/visual-gate/README.md@@ -4,7 +4,7 @@ Every visual-regression test uses the shared Storybook framework and`.github/workflows/ci.yml` → `pr-visual` (**Stable visual regression**). It runsin `release-check`, which `main-heavy-lanes.yml` dispatches after merges to`main` (a burst is checked once, at its newest commit) and the release gate dispatches before a cut; a pull request runs it only-with the `ci:heavy-lanes` label (AST-030 FR12, DEC-7).+with the `ci:run-visual` label (AST-030 FR12, DEC-7).[AST-030 FR12](../../../docs/specs/AST-030/spec.md) owns this requirement.Add coverage to that owner, not to a new component, package, theme, scheduled,post-CI, or post-merge workflow.diff --git a/.github/scripts/visual-gate/workflow-concurrency.test.mjs b/.github/scripts/visual-gate/workflow-concurrency.test.mjsindex 352f875843..8cb4c7978d 100644--- a/.github/scripts/visual-gate/workflow-concurrency.test.mjs+++ b/.github/scripts/visual-gate/workflow-concurrency.test.mjs@@ -89,7 +89,7 @@ describe('PR report and deployment workflow contracts', () => {value.indexOf(' pr-rtl-shard:'),);expect(visual).toContain(- '[build-storybook, maintenance-request, visual-scout]',+ '[build-storybook, maintenance-request, visual-scout, run-labels]',);expect(visual).toContain('name: storybook-${{ needs.build-storybook.outputs.short_hash }}',diff --git a/.github/scripts/visual-maintenance-workflow.test.mjs b/.github/scripts/visual-maintenance-workflow.test.mjsindex 344258cce8..10cae5b6bb 100644--- a/.github/scripts/visual-maintenance-workflow.test.mjs+++ b/.github/scripts/visual-maintenance-workflow.test.mjs@@ -122,11 +122,16 @@ describe('CI baseline maintenance routing', () => {it('runs on an opted-in pull request when the maintenance guard is skipped', () => {const needs = dependencies(visual);needs['maintenance-request'].result = 'skipped';- const optedIn = {event: 'pull_request', needs, labels: ['ci:heavy-lanes']};+ // run-labels decided the pull request opted into visual (ci:run-visual).+ needs['run-labels'].outputs = {visual: 'true', a11y: 'false', rtl: 'false'};+ const optedIn = {event: 'pull_request', needs};// The job decides its stable visual scope in its own steps.expect(runs(visual, optedIn)).toBe(true);- // Without the opt-in label a pull request update runs no visual owner.+ // Without the opt-in a pull request update runs no visual owner, and+ // another suite's label does not opt it in.+ needs['run-labels'].outputs = {visual: 'false', a11y: 'true', rtl: 'true'};expect(runs(visual, {event: 'pull_request', needs})).toBe(false);+ needs['run-labels'].outputs = {visual: 'true', a11y: 'false', rtl: 'false'};needs['build-storybook'].result = 'failure';expect(runs(visual, optedIn)).toBe(false);expect(runs(visual, {event: 'merge_group', needs})).toBe(false);diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 5e9d912a1b..885ee277f4 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -57,9 +57,11 @@ permissions: {}# Visual, accessibility and RTL owners (pr-a11y*, visual-scout, pr-visual,# pr-rtl*) do not run on pull request updates: they run for release-check,# which the Main heavy lanes workflow (main-heavy-lanes.yml) dispatches on every-# push to main and the release gate dispatches before a cut, and on a pull request labelled `ci:heavy-lanes` (add the label,-# then push or close and reopen). A main failure is fixed forward-# (spec:AST-030 FR12, DEC-7).+# push to main and the release gate dispatches before a cut. A pull request+# opts into one suite with its label, `ci:run-visual`, `ci:run-a11y` or+# `ci:run-rtl`, applied by someone with write access (add the label, then push+# or close and reopen); run-labels decides. A main failure is fixed forward+# (spec:AST-030 FR12, FR17, DEC-7).## Runners: every job uses GitHub's standard hosted runners, except the release# path's long jobs, which take a paid larger-runner pool so pull request load@@ -874,6 +876,47 @@ jobs:# test). Uploads the storybook preview and analysis artifacts for downstream# jobs. Sandbox previews come from the exact-head Vercel deployment, so CI# builds no Sandbox of its own.+ # Which heavy suites this pull request opted into: one output per suite,+ # `true` while the pull request carries that suite's `ci:run-<suite>` label+ # and its newest application came from someone with write, maintain or+ # admin access (spec:AST-030 FR12). It reads the event that started the run,+ # so a label takes effect on the next push or reopen (FR17). Outside a pull+ # request every output is `false`; the release check runs every suite on its+ # own terms. The decision script comes from the merge commit's trusted+ # sparse checkout, and a lookup that fails denies the suite.+ run-labels:+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') }}+ runs-on: ubuntu-slim+ timeout-minutes: 5+ permissions:+ contents: read+ pull-requests: read+ outputs:+ visual: ${{ steps.decide.outputs.visual }}+ a11y: ${{ steps.decide.outputs.a11y }}+ rtl: ${{ steps.decide.outputs.rtl }}+ steps:+ - name: Check out the decision script+ uses: actions/checkout@v7+ with:+ sparse-checkout: |+ .github/scripts/run-labels.cjs+ .github/scripts/review-signal-decision.cjs+ sparse-checkout-cone-mode: false+ path: .run-labels+ persist-credentials: false++ - name: Decide which suites run+ id: decide+ uses: actions/github-script@v9+ with:+ retries: 3+ script: |+ const {decideRunLabels} = require(+ `${process.env.GITHUB_WORKSPACE}/.run-labels/.github/scripts/run-labels.cjs`,+ );+ await decideRunLabels({github, context, core});+build-storybook:if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') && always() && !cancelled()) }}# Every browser lane waits for this job, and the package builds and the@@ -1403,8 +1446,8 @@ jobs:pr-a11y-guards:name: pr-a11y (audit and guards)- needs: [build-storybook]- if: ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))+ needs: [build-storybook, run-labels]+ if: ((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}permissions:@@ -1534,8 +1577,8 @@ jobs:# inside the budget without weakening the stable pr-a11y join.pr-a11y-specs:name: pr-a11y (browser specs)- needs: [build-storybook]- if: ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))+ needs: [build-storybook, run-labels]+ if: ((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}permissions:@@ -1624,8 +1667,8 @@ jobs:# Stable required context joining the scoped audit/guards and browser specs.pr-a11y:- needs: [pr-a11y-guards, pr-a11y-specs]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (always() && ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) }}+ needs: [pr-a11y-guards, pr-a11y-specs, run-labels]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (always() && ((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) }}runs-on: ubuntu-slimtimeout-minutes: 5permissions:@@ -2059,11 +2102,11 @@ jobs:# joins them only when every shard succeeded, and otherwise scouts inline.visual-scout:name: Stable visual scout (${{ matrix.shard }}/${{ strategy.job-total }})- needs: [build-storybook]+ needs: [build-storybook, run-labels]if: >-(github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() &&needs.build-storybook.result == 'success' &&- ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) ||+ ((github.event_name == 'pull_request' && needs.run-labels.outputs.visual == 'true') ||(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')))# Five legs: at three, each leg's scout took ~4.5 minutes and the visual# regression waited for the slowest one.@@ -2174,10 +2217,10 @@ jobs:# Audit and interaction fixtures stay with their existing browser checks.pr-visual:name: Stable visual regression- needs: [build-storybook, maintenance-request, visual-scout]+ needs: [build-storybook, maintenance-request, visual-scout, run-labels]if: >-(github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() &&- (((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) &&+ (((github.event_name == 'pull_request' && needs.run-labels.outputs.visual == 'true') &&needs.build-storybook.result == 'success') ||(github.event_name == 'workflow_dispatch' &&((inputs.operation == 'release-check' &&@@ -2492,9 +2535,9 @@ jobs:# To promote findings too, remove the audit step's continue-on-error.pr-rtl-shard:name: pr-rtl (${{ matrix.package }}${{ matrix.parts > 1 && format(' {0}/{1}', matrix.part, matrix.parts) || '' }})- needs: [build-storybook]+ needs: [build-storybook, run-labels]if: >-- ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) ||+ ((github.event_name == 'pull_request' && needs.run-labels.outputs.rtl == 'true') ||(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))# Core is the largest package, so its audit is split three ways# (`--shard`) and joined by pr-rtl-merge; every other package runs whole.@@ -2694,10 +2737,10 @@ jobs:# part fails here.pr-rtl-merge:name: pr-rtl (core)- needs: [build-storybook, pr-rtl-shard]+ needs: [build-storybook, pr-rtl-shard, run-labels]if: >-(github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (always() && !cancelled() &&- ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) ||+ ((github.event_name == 'pull_request' && needs.run-labels.outputs.rtl == 'true') ||(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')))runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}timeout-minutes: 15@@ -2802,8 +2845,8 @@ jobs:# Stable required context joining the five package shards above.pr-rtl:- needs: [pr-rtl-shard, pr-rtl-merge]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (always() && !cancelled() && ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) }}+ needs: [pr-rtl-shard, pr-rtl-merge, run-labels]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (always() && !cancelled() && ((github.event_name == 'pull_request' && needs.run-labels.outputs.rtl == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) }}runs-on: ubuntu-slimtimeout-minutes: 5permissions:diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex d160091f39..05c65e6fdb 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -386,7 +386,7 @@ Two repo-side rules worth restating here:one is a review reject.- CI is the enforcement layer, not a replacement for the checklist: the`pr-a11y` job in `ci.yml` runs an axe audit after merges to `main` and- before each release (and on a pull request labelled `ci:heavy-lanes`), at+ before each release (and on a pull request labelled `ci:run-a11y`), atfull scope across the component surface, and the `useAnnounce` lint rulerejects hand-wired `aria-live` regions. axe onlycatches static, DOM-level issues — keyboard behavior, focus management, and@@ -533,7 +533,7 @@ any other value:```These routes apply when a pull request runs the accessibility owner, which it-does only with the `ci:heavy-lanes` label; `main` and release checks run every+does only with the `ci:run-a11y` label; `main` and release checks run everyspec. `pnpm test:a11y-contract:pr origin/main --dry-run` prints what a pull requestfrom your branch would run (component tokens need CI's `analysis.json`; withoutit the runner says so and leaves those specs out). A spec writes its receipts under@@ -548,7 +548,7 @@ component set, or has no audit spec has an entry in### Accessibility auditsMerges to `main` (checked at the newest commit of a burst), every release-check, and a PR labelled `ci:heavy-lanes`+check, and a PR labelled `ci:run-a11y`that touches components run an axe-core audit (the `pr-a11y` CI job); on a PRit covers the Storybook stories of the changed components. The job **fails** when itfinds a violation that is not listed in the checked-in baseline,@@ -924,10 +924,14 @@ Storybook story for anything you added or altered.push, or when the maintainer closes and reopens the pull request; CI thenruns on each push while the label stays. Until then the required checks failwith "Waiting for a maintainer's ci:run label".-- **`ci:heavy-lanes` opts a pull request into the visual, accessibility and- RTL suites**, which otherwise run on `main` after it merges. A maintainer- applies it when a change needs that evidence before merging; like `ci:run`,- it takes effect on the next push or a close and reopen.+- **`ci:run-visual`, `ci:run-a11y` and `ci:run-rtl` each opt a pull request+ into one heavy suite** (visual regression, accessibility, RTL), which+ otherwise runs on `main` after the pull request merges. Someone with write+ access applies the label for the evidence a change needs before merging; a+ label applied without write access runs nothing. Like `ci:run`, a label+ takes effect on the next push or a close and reopen, and removing it stops+ that suite from the next run. When the accessibility audit did not run, the+ pull-request comment names `ci:run-a11y`.- **Pull requests from a branch in this repository run CI without the label**,since pushing a branch here needs write access. Maintainers who work from afork either push their branches here or apply `ci:run` themselves.diff --git a/apps/storybook/rtl-audit/README.md b/apps/storybook/rtl-audit/README.mdindex b237e75025..31084cfd85 100644--- a/apps/storybook/rtl-audit/README.md+++ b/apps/storybook/rtl-audit/README.md@@ -19,7 +19,7 @@ independent auto passes: **D1 (icon-mirror)**, **D5 (positional-mirror)**, and**D6 (directional-decoration)**.> **Scope in CI.** `pr-rtl` runs after merges to `main` and in release checks at-> full scope, and on a PR only with the `ci:heavy-lanes` label (spec:AST-030+> full scope, and on a PR only with the `ci:run-rtl` label (spec:AST-030> FR12). On a labelled PR it passes `--filter` with the components the PR> touched (from `analysis.json`), matching `pr-a11y`. Eligibility is classified> by the component policy and package registry loaded from the trusted base ref;@@ -36,7 +36,7 @@ independent auto passes: **D1 (icon-mirror)**, **D5 (positional-mirror)**, and> policy requires full scope, every manifest must be runnable with an empty> filter and all five package reports must arrive. A planned scan ending in ERROR> is incomplete. Missing or malformed analysis/index/manifest input, a noncanonical owner, stale output, a missing or unexpected report, and-> an all-skipped required matrix all fail closed. An RTL-harness-only PR labelled `ci:heavy-lanes` runs the fixed+> an all-skipped required matrix all fail closed. An RTL-harness-only PR labelled `ci:run-rtl` runs the fixed> `Chart,ChartLegend` routing smoke scope so package discovery and curated aliases> cannot skip their own check; without the label, `main`'s `release-check` covers> the harness after merge (spec:AST-030 FR12). Thediff --git a/docs/architecture/rtl-audit-evidence.md b/docs/architecture/rtl-audit-evidence.mdindex 17ea4b7491..70124d51c8 100644--- a/docs/architecture/rtl-audit-evidence.md+++ b/docs/architecture/rtl-audit-evidence.md@@ -152,7 +152,7 @@ Lint and rendered audit are complementary:- **INV7 — PR scope and full-roster scope answer different questions.** The RTLaudit runs after merges to `main` (a burst of pushes is checked once, at itsnewest commit) and before each release, at full scope; a pull request runs it- only with the `ci:heavy-lanes` label (spec:AST-030 FR12, DEC-7). When a pull+ only with the `ci:run-rtl` label (spec:AST-030 FR12, DEC-7). When a pullrequest runs it, it checks components affected by the change; it may run perpackage, but the PR result is the join of every package scope and cannot passwith one scope missing. The full-scope run checks the live roster and shareddiff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex af737b39e5..9fdc9bf939 100644--- a/docs/specs/AST-030/spec.md+++ b/docs/specs/AST-030/spec.md@@ -191,10 +191,13 @@ they are separately named.visual plan and unfiltered accessibility/RTL component rosters. Changed-file,focused, smoke, and no-op paths MUST NOT narrow release checks. On a pullrequest, the visual (`visual-scout`, `pr-visual`), accessibility (`pr-a11y`- with its guards and specs) and RTL (`pr-rtl` with its legs) owners MUST run- only when the pull request carries the `ci:heavy-lanes` label at the event; a- pull request update without it runs none of them, and no required context- depends on them. An opted-in PR's a11y MUST remain scoped to changed components+ with its guards and specs) and RTL (`pr-rtl` with its legs) owners MUST each+ run only when the pull request carries that suite's label at the event:+ `ci:run-visual`, `ci:run-a11y` or `ci:run-rtl`, in each case last applied by+ someone with write, maintain or admin access, and a lookup that cannot+ confirm that runs nothing. A label runs only its own suite; a pull request+ update without one runs none of them, and no required context depends on+ them. An opted-in PR's a11y MUST remain scoped to changed componentsplus fast interaction guards; full a11ysweeps, whole-repository spec-test contracts, and their evidence uploads MUSTrun only for `release-check` in this workflow. Missing,@@ -232,7 +235,7 @@ they are separately named.reads sources for it (the TypeScript compiler, a bundler) counts as readingsources; and every test that loads a changed workspace package from its build,by the package's name or a path into its `dist/`. When a pull request runs- them (FR12: only with the `ci:heavy-lanes` label), the visual and RTL owners+ them (FR12: only with their `ci:run-visual` or `ci:run-rtl` label), the visual and RTL ownersaudit one affected set of component folders: the changed componentsand their reverse dependents, the folders of the components, in any package,whose built bundle, `import()` targets included, reaches a changed module.@@ -241,8 +244,8 @@ they are separately named.audits every component each of those folders implements. A Changeset renders nothing and widens no audit. A changed module that no component bundle holds adds none, and withouta readable build the audits run in full. PR accessibility, when it runs, staysscoped to changed components (FR12). Shared infrastructure runs the full suite of- the owners the pull request runs (visual, accessibility and RTL only with the- `ci:heavy-lanes` label, FR12): root+ the owners the pull request runs (visual, accessibility and RTL only with+ their `ci:run-*` labels, FR12): rootdependency manifests and lockfile, root configuration, a package's manifest,build or test configuration and test setup, `internal/` (the test harnessincluded), `theme-build` paths (tokens and themes), Storybook configuration,@@ -301,7 +304,8 @@ they are separately named.suites. A re-run, which is the pre-merge restart, is exempt from both limits,and when the limits cannot be looked up the suite runs. Merge-queue entries,`main`, release checks and the visual, accessibility and RTL owners a- maintainer opts a pull request into with `ci:heavy-lanes` are unaffected.+ maintainer opts a pull request into with their `ci:run-*` labels are+ unaffected.- **FR17 — A pull request runs CI when it is ready and a maintainer can vouchfor it.** A draft pull request runs no CI, and marking it ready for reviewstarts its pull-request run, which runs what the change reaches (FR13,@@ -472,7 +476,7 @@ retroactive status as release evidence.Run the visual, accessibility and RTL owners on every push to `main`, throughthe same exact-commit `release-check` the release gate uses, and before a cut;-a pull request runs them only when it opts in with the `ci:heavy-lanes` label. Main-push checks are throttled: one runs at a time, a+a pull request runs each only when it opts in with that suite's `ci:run-visual`, `ci:run-a11y` or `ci:run-rtl` label. Main-push checks are throttled: one runs at a time, aburst of pushes collapses to its newest commit, and a running check is nevercancelled, so every check that starts finishes.Pull request updates keep the fast checks and every required context; the@@ -500,7 +504,7 @@ read sources through the file system run whole, because no import reaches whatthey read. Shared infrastructure, uncertainty, `main`, merge-group entries andrelease checks run everything, so no landing or release gate narrows; a pullrequest runs the visual, accessibility and RTL owners only with the-`ci:heavy-lanes` label (DEC-7).+suite's `ci:run-*` label (DEC-7).Rejected: a full run triggered by approval, a label or a draft-to-ready change,which tests the pull request's head rather than the merged result.