An open source design system that's fully customizable and agent ready
TypeScript
ci(a11y): the touched check audits changed stories no component owns (#10026)
Cindy Zhanga64c6891d7db
diff --git a/.github/scripts/accessibility-audit.js b/.github/scripts/accessibility-audit.jsindex a365dc4b90..fc4be60918 100644--- a/.github/scripts/accessibility-audit.js+++ b/.github/scripts/accessibility-audit.js@@ -6,6 +6,8 @@* @description Runs accessibility audits on component stories using axe-core* @input --storybook-dir <path> --output <file> [--components <comma-separated>]* [--stories <comma-separated-story-ids>] [--port <number, 0 = any free>]+ * [--changed-story-files <file>] (the stories of these changed story files+ * that no component owns, instead of --components or --stories)* [--ready-selector <css-selector>] [--concurrency <pages, default 1>]* [--shard <i>/<n> --shard-output <file>] (scan every n-th story, write it)* [--merge-shards <dir>] (read a complete shard set instead of scanning)@@ -53,6 +55,7 @@ const {legacyBaselineStoryKeys,ownerForA11yStory,} = require('./lib/a11y-story-identity');+const {changedUnownedStoryIds} = require('./lib/a11y-changed-stories');const args = process.argv.slice(2);const getArg = (name) => {@@ -71,6 +74,10 @@ const componentsArg = getArg('components');const components = (componentsArg || '').split(',').filter(Boolean);const storiesArg = getArg('stories');const requestedStories = (storiesArg || '').split(',').filter(Boolean);+const changedStoryFilesArg = getArg('changed-story-files');+if (changedStoryFilesArg !== null && (storiesArg !== null || componentsArg !== null)) {+ throw new Error('--changed-story-files selects its own stories; pass it without --stories or --components');+}// --components present but EMPTY means the caller derived an explicit empty// audit set (pr-a11y on a PR whose core/src changes map to no component —// e.g. a shared test file). Audit nothing and pass. Only an ABSENT flag@@ -328,17 +335,34 @@ async function runAccessibilityAudit() {)) {console.log(`Owner route: ${owner} -> ${ownedStoryIds.join(', ')}`);}+ let selectedStories = storiesArg !== null ? requestedStories : null;+ if (changedStoryFilesArg !== null) {+ const changedFiles = fs.existsSync(changedStoryFilesArg)+ ? fs.readFileSync(changedStoryFilesArg, 'utf8').split('\n')+ : [];+ selectedStories = changedUnownedStoryIds(stories, routed.allRoutes, changedFiles);+ if (selectedStories.length === 0) {+ console.log('No changed story without a component owner — skipping.');+ const report = {+ components: {},+ summary: { componentsAudited: 0, totalViolations: 0 },+ };+ fs.writeFileSync(outputFile, JSON.stringify(report, null, 2));+ return report;+ }+ console.log(`Changed stories no component owns: ${selectedStories.join(', ')}`);+ }const routedIds = new Set(routed.storyIds);- const requestedStoryIds = new Set(requestedStories);+ const requestedStoryIds = new Set(selectedStories ?? []);const relevantStories = storyIds.filter(id => {if (id.endsWith('--docs')) return false;return (routedIds.has(id) &&- (storiesArg === null || requestedStoryIds.has(id))+ (selectedStories === null || requestedStoryIds.has(id)));});- if (storiesArg !== null) {- const unresolvedStories = requestedStories.filter(+ if (selectedStories !== null) {+ const unresolvedStories = selectedStories.filter(id => !relevantStories.includes(id),);if (unresolvedStories.length > 0) {@@ -636,7 +660,7 @@ async function runAccessibilityAudit() {}const report = {- requestedStories,+ requestedStories: selectedStories ?? requestedStories,readySelector,ownerStoryRoutes: routed.ownerStoryRoutes,ownerStoryKeys,diff --git a/.github/scripts/lib/a11y-changed-stories.js b/.github/scripts/lib/a11y-changed-stories.jsnew file mode 100644index 0000000000..4b1a55098c--- /dev/null+++ b/.github/scripts/lib/a11y-changed-stories.js@@ -0,0 +1,50 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file a11y-changed-stories.js+ * @input The Storybook index's story entries, the story routes the audit+ * builds (story id and owner), and the pull request's changed file paths.+ * @output The ids of the changed story files' stories that no component owns.+ * @position Selects the stories the touched-components check audits on their+ * own (spec:AST-030 FR12): a touched component's audit never reaches a story+ * whose owner is no component.+ */++const path = require('node:path');++/** Story index import paths are relative to the Storybook app. */+const STORYBOOK_DIR = 'apps/storybook';++/** The repository path of a story entry's file. */+function storyFilePath(importPath) {+ return path.posix.normalize(path.posix.join(STORYBOOK_DIR, importPath));+}++/**+ * The stories of the changed story files whose owner is no component. A story+ * with no route counts as unowned, so it is audited rather than dropped.+ *+ * @param {Record<string, {type?: string, importPath?: string}>} stories+ * @param {Array<{id: string, component: string}>} routes+ * @param {string[]} changedFiles+ * @returns {string[]}+ */+function changedUnownedStoryIds(stories, routes, changedFiles) {+ const changed = new Set(+ changedFiles.map(file => file.trim()).filter(Boolean),+ );+ const owners = new Map(routes.map(route => [route.id, route.component]));+ return Object.entries(stories)+ .filter(+ ([id, story]) =>+ story?.type === 'story' &&+ !id.endsWith('--docs') &&+ typeof story.importPath === 'string' &&+ changed.has(storyFilePath(story.importPath)) &&+ String(owners.get(id) ?? 'unknown/').startsWith('unknown/'),+ )+ .map(([id]) => id)+ .sort();+}++module.exports = {changedUnownedStoryIds, storyFilePath};diff --git a/.github/scripts/lib/a11y-changed-stories.test.mjs b/.github/scripts/lib/a11y-changed-stories.test.mjsnew file mode 100644index 0000000000..309a166475--- /dev/null+++ b/.github/scripts/lib/a11y-changed-stories.test.mjs@@ -0,0 +1,128 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file a11y-changed-stories.test.mjs+ * Tests for the selection of changed stories no component owns, the ones the+ * touched-components check audits on their own (spec:AST-030 FR12).+ */++import fs from 'node:fs';+import path from 'node:path';+import {describe, expect, it} from 'vitest';+import {changedUnownedStoryIds, storyFilePath} from './a11y-changed-stories.js';+import {STORY_FILE} from '../touched-components.mjs';++const root = path.resolve(import.meta.dirname, '../../..');+const story = importPath => ({type: 'story', importPath});++// #9985's shape: an `a11y/` story file whose stories route to an unknown+// owner, beside a component's own story file.+const stories = {+ 'a11y-scroll-region-name--content-scrolls': story(+ './stories/ScrollRegionA11y.stories.tsx',+ ),+ 'a11y-scroll-region-name--panel-scrolls': story(+ './stories/ScrollRegionA11y.stories.tsx',+ ),+ 'a11y-scroll-region-name--docs': {+ type: 'docs',+ importPath: './stories/ScrollRegionA11y.stories.tsx',+ },+ 'core-alertdialog--delete': story('./stories/AlertDialog.stories.tsx'),+ 'core-chip--default': story('../../packages/core/src/Chip/Chip.stories.tsx'),+ 'pattern-x--unrouted': story('./stories/Unrouted.stories.tsx'),+};+const routes = [+ {+ id: 'a11y-scroll-region-name--content-scrolls',+ component: 'unknown/a11y-scroll-region-name',+ },+ {+ id: 'a11y-scroll-region-name--panel-scrolls',+ component: 'unknown/a11y-scroll-region-name',+ },+ {id: 'core-alertdialog--delete', component: 'core/AlertDialog'},+ {id: 'core-chip--default', component: 'core/Chip'},+];++describe('changed stories no component owns', () => {+ it('reads an index import path as a repository path', () => {+ expect(storyFilePath('./stories/X.stories.tsx')).toBe(+ 'apps/storybook/stories/X.stories.tsx',+ );+ expect(storyFilePath('../../packages/core/src/Chip/Chip.stories.tsx')).toBe(+ 'packages/core/src/Chip/Chip.stories.tsx',+ );+ });++ it("selects a changed `a11y/` story file's stories, not its docs page", () => {+ expect(+ changedUnownedStoryIds(stories, routes, [+ 'apps/storybook/stories/ScrollRegionA11y.stories.tsx',+ ]),+ ).toEqual([+ 'a11y-scroll-region-name--content-scrolls',+ 'a11y-scroll-region-name--panel-scrolls',+ ]);+ });++ it("leaves a component's own stories to its touched-component audit", () => {+ expect(+ changedUnownedStoryIds(stories, routes, [+ 'apps/storybook/stories/AlertDialog.stories.tsx',+ 'packages/core/src/Chip/Chip.stories.tsx',+ ]),+ ).toEqual([]);+ });++ it('audits a story with no route rather than dropping it', () => {+ expect(+ changedUnownedStoryIds(stories, routes, [+ 'apps/storybook/stories/Unrouted.stories.tsx',+ ]),+ ).toEqual(['pattern-x--unrouted']);+ });++ it('selects nothing for unchanged story files or an empty list', () => {+ expect(+ changedUnownedStoryIds(stories, routes, [+ 'packages/core/src/Chip/Chip.tsx',+ '',+ ]),+ ).toEqual([]);+ expect(changedUnownedStoryIds(stories, routes, [])).toEqual([]);+ });++ it('selects the six #9985 stories from the real Storybook index, when one is built', () => {+ const index = path.join(root, 'apps/storybook/dist/index.json');+ if (!fs.existsSync(index)) return;+ const entries = JSON.parse(fs.readFileSync(index, 'utf8')).entries;+ const unknown = Object.keys(entries)+ .filter(id => id.startsWith('a11y-scroll-region-name--'))+ .map(id => ({id, component: 'unknown/a11y-scroll-region-name'}));+ const ids = changedUnownedStoryIds(entries, unknown, [+ 'apps/storybook/stories/ScrollRegionA11y.stories.tsx',+ ]);+ expect(ids.length).toBeGreaterThanOrEqual(6);+ expect(ids.every(id => id.startsWith('a11y-scroll-region-name--'))).toBe(+ true,+ );+ });++ it('knows a story file when it sees one', () => {+ for (const file of [+ 'apps/storybook/stories/A.stories.tsx',+ 'packages/lab/src/X/X.stories.ts',+ 'a/B.stories.mdx',+ ]) {+ expect(STORY_FILE.test(file), file).toBe(true);+ }+ for (const file of [+ 'packages/core/src/A.tsx',+ 'apps/storybook/stories/README.md',+ 'a/stories.tsx',+ ]) {+ expect(STORY_FILE.test(file), file).toBe(false);+ }+ });+});diff --git a/.github/scripts/touched-components.mjs b/.github/scripts/touched-components.mjsindex 8b738af156..cfb2fa5d98 100644--- a/.github/scripts/touched-components.mjs+++ b/.github/scripts/touched-components.mjs@@ -47,6 +47,9 @@ const FOUNDATION_PATTERNS = [];/** The changed paths that are style-affecting foundations. */+/** A Storybook story file. */+export const STORY_FILE = /\.stories\.(?:[cm]?[jt]sx?|mdx)$/;+export function foundationChanges(files) {return files.filter(file =>FOUNDATION_PATTERNS.some(pattern => pattern.test(file)),@@ -596,6 +599,9 @@ export function main(argv = process.argv.slice(2)) {wide_change: String(decision.wideChange),component_count: String(decision.componentCount),has_components: String(scope.touched.length > 0 && !decision.wideChange),+ // A changed story no component owns is audited on its own (FR12),+ // wide change or not.+ changed_stories: String(files.some(file => STORY_FILE.test(file))),visual_components: scope.visualComponents.join(','),a11y_owners: scope.a11yOwners.join(','),rtl_packages: Object.keys(scope.rtlOwnersByPackage).join(','),diff --git a/.github/scripts/touched-components.test.mjs b/.github/scripts/touched-components.test.mjsindex b5de2fe10b..e10d4d982e 100644--- a/.github/scripts/touched-components.test.mjs+++ b/.github/scripts/touched-components.test.mjs@@ -590,8 +590,9 @@ describe('pr-touched-components routing', () => {'Download Storybook artifact','Install Playwright',]) {+ // A changed story no component owns needs the same setup (FR12).expect(step(name).if).toBe(- "steps.touched.outputs.has_components == 'true'",+ "(steps.touched.outputs.has_components == 'true' || steps.touched.outputs.changed_stories == 'true')",);}expect(step('Upload touched-components results').with.path).not.toContain(@@ -643,7 +644,8 @@ describe('pr-touched-components routing', () => {expect(step('Skip when no component changed or the change is wide').if,).toBe("steps.touched.outputs.has_components != 'true'");- // Every later step runs for touched components only.+ // Every later step runs for touched components only, or for a changed+ // story no component owns (FR12).const skipIndex = job.steps.findIndex(candidate =>candidate.name ===@@ -651,7 +653,7 @@ describe('pr-touched-components routing', () => {);for (const candidate of job.steps.slice(skipIndex + 1)) {expect(candidate.if, candidate.name).toMatch(- /steps\.touched\.outputs\.has_components == 'true'/,+ /steps\.touched\.outputs\.(has_components|changed_stories) == 'true'/,);}});@@ -835,3 +837,95 @@ describe('pr-component-a11y-contracts routing', () => {);});});++// A story the change adds or changes that no component owns is audited on+// its own (spec:AST-030 FR12), new violations only.+describe('the audit of changed stories no component owns', () => {+ const audit = step(+ 'Accessibility audit for changed stories no component owns',+ );+ const either =+ "(steps.touched.outputs.has_components == 'true' || steps.touched.outputs.changed_stories == 'true')";++ it('runs after the Storybook build and browser are in place, whenever a story file changed', () => {+ expect(audit.if).toBe(+ "always() && steps.playwright.outcome == 'success' && steps.touched.outputs.changed_stories == 'true'",+ );+ for (const name of [+ 'Setup Node and pnpm',+ 'Download Storybook artifact',+ 'Install Playwright',+ ]) {+ expect(step(name).if, name).toBe(either);+ }+ expect(job.steps.indexOf(audit)).toBeGreaterThan(+ job.steps.indexOf(step('Install Playwright')),+ );+ });++ it("audits only those stories, against the head's baseline, failing on a new violation", () => {+ expect(audit.env).toEqual({+ FILES_PATH: '${{ steps.scope.outputs.changed_files_path }}',+ });+ expect(audit.run).toContain('--changed-story-files "$FILES_PATH"');+ expect(audit.run).toContain(+ '--baseline .head-baseline/.github/a11y-baseline.json',+ );+ expect(audit.run).toContain('--fail-on-new');+ expect(audit.run).not.toContain('--components');+ expect(step('Upload touched-components results').with.path).toContain(+ 'a11y-stories-report.json',+ );+ });++ it('still leaves a Lab-only pull request to its own lane (FR26)', () => {+ expect(job.if).toContain(+ "needs.build-storybook.outputs.lab_only != 'true'",+ );+ });++ it('reports whether a story file changed, wide change or not', async () => {+ const os = await import('node:os');+ const path = await import('node:path');+ const {execFileSync} = await import('node:child_process');+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'touched-stories-'));+ try {+ const run = files => {+ fs.writeFileSync(path.join(dir, 'files.txt'), `${files.join('\n')}\n`);+ fs.writeFileSync(path.join(dir, 'analysis.json'), '{}');+ const out = path.join(dir, 'out.txt');+ fs.writeFileSync(out, '');+ execFileSync(+ 'node',+ [+ new URL('./touched-components.mjs', import.meta.url).pathname,+ 'scope',+ '--analysis',+ path.join(dir, 'analysis.json'),+ '--files',+ path.join(dir, 'files.txt'),+ '--out',+ path.join(dir, 'touched.json'),+ ],+ {env: {...process.env, GITHUB_OUTPUT: out}},+ );+ return Object.fromEntries(+ fs+ .readFileSync(out, 'utf8')+ .split('\n')+ .filter(Boolean)+ .map(line => line.split('=')),+ );+ };+ expect(+ run(['apps/storybook/stories/ScrollRegionA11y.stories.tsx'])+ .changed_stories,+ ).toBe('true');+ expect(+ run(['packages/core/src/Layout/LayoutContent.tsx']).changed_stories,+ ).toBe('false');+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });+});diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 6134820ee4..5afe433f92 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -3874,21 +3874,25 @@ jobs:env:WIDE: ${{ steps.touched.outputs.wide_change }}COUNT: ${{ steps.touched.outputs.component_count }}+ STORIES: ${{ steps.touched.outputs.changed_stories }}run: |if [ "$WIDE" = true ]; thenecho "Wide change ($COUNT components): add ci:run-visual, ci:run-a11y or ci:run-rtl to run the full suite."else- echo "No component changed; nothing to audit."+ echo "No component changed; no component audit."+ fi+ if [ "$STORIES" = true ]; then+ echo "Changed stories no component owns are audited below."fi- name: Setup Node and pnpm- if: steps.touched.outputs.has_components == 'true'+ if: (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.changed_stories == 'true')uses: ./.github/actions/setupwith:install: 'false'- name: Download Storybook artifact- if: steps.touched.outputs.has_components == 'true'+ if: (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.changed_stories == 'true')uses: actions/download-artifact@v8with:name: storybook-${{ needs.build-storybook.outputs.short_hash }}@@ -3896,7 +3900,7 @@ jobs:- name: Install Playwrightid: playwright- if: steps.touched.outputs.has_components == 'true'+ if: (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.changed_stories == 'true')run: pnpm install --frozen-lockfile && npx playwright install chromium# The same changed-component filters an opted-in pull request uses.@@ -3915,6 +3919,24 @@ jobs:--concurrency 4 \--components "$COMPONENTS"+ # A story the change adds or changes that no component owns (an `a11y/`+ # page, say) is in no touched component's audit, so it is audited on its+ # own: new violations against the head's baseline fail the job+ # (spec:AST-030 FR12).+ - name: Accessibility audit for changed stories no component owns+ id: story-a11y+ if: always() && steps.playwright.outcome == 'success' && steps.touched.outputs.changed_stories == 'true'+ env:+ FILES_PATH: ${{ steps.scope.outputs.changed_files_path }}+ run: |+ node .github/scripts/accessibility-audit.js \+ --storybook-dir apps/storybook/dist \+ --output a11y-stories-report.json \+ --concurrency 4 \+ --changed-story-files "$FILES_PATH" \+ --baseline .head-baseline/.github/a11y-baseline.json \+ --fail-on-new+# A failed accessibility audit must not skip RTL: each suite reports# its own result.- name: RTL audit for the touched components@@ -3975,13 +3997,14 @@ jobs:--out touched-components.json- name: Upload touched-components results- if: always() && (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.wide_change == 'true')+ if: always() && (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.wide_change == 'true' || steps.touched.outputs.changed_stories == 'true')uses: actions/upload-artifact@v7with:name: touched-componentspath: |touched-components.jsona11y-report.json+ a11y-stories-report.jsonrtl-reports/if-no-files-found: ignoreretention-days: 7diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex d09a44d4cc..6a3572e6e6 100644--- a/docs/specs/AST-030/spec.md+++ b/docs/specs/AST-030/spec.md@@ -232,7 +232,9 @@ they are separately named.that touches more than five components, or changes shared styles (themes,tokens, or a `.stylex.ts` file in a package's shared `theme`, `utils`,`hooks`, `internal` or `Layer` folder); behaviour-only shared code is not a- wide change. Nothing starts a full suite on its own; a wide change's check+ wide change. Every change, a wide one included, also gets an+ accessibility audit, new violations only, of each story file it adds or+ changes whose owner is no component. Nothing starts a full suite on its own; a wide change's checkis the full suites behind the labels. No required context depends on thetouched check, and it records each touched component's pass, fail, changedor not-run result per suite, or that the change was wide and how many@@ -614,33 +616,33 @@ The nightly perf lane is the one scheduled measurement outside them (FR18).## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| FR1–FR2 | classifier unit tests expose the surface set; `fs-guard-tests.test.mjs` spec-reader cases | knowledge; docsite; admitted tool; Core/Lab/Charts/Rich Text/Vega source; shared config; unknown; a spec-only change to a record a test reads | an unclassified path receives a specialized lane, a category has no check owner, or a spec-only change skips a test that reads its record |-| FR3–FR4 | workflow contract tests execute an isolated trusted-base classifier | valid base; missing merge base; missing matcher/registry; classifier self-change; merge group | PR-controlled policy grants a lane, or missing trust data skips checks |-| FR5 | mixed-surface and incomplete-owner routing tests | spec+component; tooling+component; named surface without admitted lane; docsite+shared | one surface hides another owner or a named-but-incomplete surface skips broad CI |-| FR6–FR8 | Node-tooling dependency, CI workflow, and trusted post-CI workflow tests | both admitted score-ledger paths; Sandbox projection imports; test/build joins; preview/visual publisher | UI/browser/build work or preview publication runs for the singleton tool set, an operational consumer is untested, a visual status stays pending, or a required context disappears |-| FR9 | mutation-sensitive classifier and workflow fixtures | unknown path; rename from unknown; truncated list; package-specific public paths | weakening a fail-closed rule leaves the suite green |-| FR10 | surface-admission and routing contract tests | existing surface; proposed surface with and without the full admission contract | a new surface adds lanes without its approved paths, commands, ownership, projections, and routing tests |-| FR11 | surface owner, internal-job, and required-join contract tests | Build package browser behavior; CLI; theme-family broad fallback; mixed Core+CLI | a second owner is routed for one surface, an internal job masquerades as a lane, an owned failure misses its join, or an unrelated owner runs |-| FR12 | Storybook visual-plan, canonical workflow, and repository-owner guard tests | PR scope; full-plan maintenance; report-only publication; deployment/a11y/RTL/vibe artifacts | another workflow captures or compares pixels, a renamed or aliased owner escapes the guard, or legitimate non-visual artifacts are rejected |-| FR12 | `touched-components.test.mjs` changed-spec routing; `a11y-pr-contracts.test.mjs` `changedOnly` cases | a pull request that adds a browser accessibility spec; one that changes an `always` spec; one that changes a `release-only` or an `audit` spec; one that changes more spec files than the limit; a component change with no spec change | a pull request that adds a browser accessibility spec that fails is not caught on that pull request, another component's spec or an unchanged `audit` spec runs in the contract job, a not-run file reads as passed or fails the join, or a failing contract leaves the `test` join green |-| FR12 | `a11y-pr-contracts.test.mjs` ownership cases; the CI workflow contract; contract-job and unit-test-job timings on 17 component pull requests | a pull request that touches one component with an owned `release-only` contract, passing and failing; a contract file that cannot finish within the budget; a wide change; a reverse dependent of the touched component; measured: setup up to about 1.5 minutes plus the 8-minute stop, against the slowest unit-test job finishing 9.9 to 25 minutes after the Storybook build | a touched component's owned `release-only` contract does not run on its pull request, a failing contract leaves the `test` join green, a skipped file is split, does not show as "not run" in the check's summary or fails the join, the contract job finishes after the slowest unit-test job, or a wide change or reverse dependent runs owned contracts |-| FR13 | classifier, workflow contract, component-analysis and RTL-scope tests | component change; shared module; Changeset beside code; infrastructure path; incomplete list; no build | an infrastructure path is scoped, a file-system guard test is skipped, a reverse dependent leaves visual/RTL or enters PR accessibility, or a full-suite event is narrowed |-| FR14 | `workflow-paths.test.mjs` over every workflow | path allowlist; required-context workflow | a `paths-ignore`, a match-all or exclusion glob, or a path filter on a workflow that reports a required context fails |-| FR15 | workflow contract and reconciler tests | ENGOWNER spec PR; owner command; other comment; fork review; non-spec PR; run over the request budget; maintainer dispatch; fork PR, code-only: an owner's exact-head approval plus the owner command clears the code half | `review-required` succeeds while spec approval is missing, another workflow publishes a review context, a fork review starts the spec checks, a non-command comment starts a runner, an over-budget run decides, or a fork's approved code-only PR stays pending after the owner command |-| FR16 | `heavy-caps-action.test.mjs` cap cases and heavy-job contract; `ci-admission.test.mjs` | sixteenth-oldest PR; 101st heavy run of the day, beside cancelled, light and other-branch runs; agent lane and its five-PR and forty-run backstops; an engineering owner, including the shared login past those backstops, a commented-out or trailing-comment handle and an unreadable roster; bot; the deciding run; re-run; failed lookup; a run with room, without room, past its longest wait, beside a waiting `main` check, as a draft or unlabelled fork, with opt-in labels, beside small workflows past their measured most, and with the API unreadable; each workflow's most jobs; every required context's rule | a heavy suite that runs ahead of the author's fifteen oldest PRs, or past the daily cap, a capped job that passes, an engineering owner or a re-run that is held, or a roster read from the pull request's head, a run that starts without room before its longest wait, a pull-request run that starts while `main` has waited under fifteen minutes, a job admission could skip, a peak below the jobs its run holds, or a job on a slim runner planned past its fifteen-minute cap fails |-| FR16 | `ci-admission.test.mjs` cases for one start at the longest wait at a time and the workflow contract | a pull-request run at its longest wait alone, within ten minutes of another pull-request run's start there and after them, behind a run that waited longer and ahead of a younger one; another run that found room earlier, a fork's stopped run and a `main` run that waited its longest; a `main` run and a merge-queue entry at their longest wait; the rest of a run whose Storybook build found room; ten runs out of time together; the required contexts and ci-full for either wait; a pull-request run that finds ten others waiting and room only for its Storybook build, and one at its longest wait behind more than ten that waited longer | two pull-request runs start at their longest wait within ten minutes, a younger run starts ahead of a longer waiter, a `main` run or merge-queue entry stops, a run CI is full for builds, or a required context passes or skips |-| FR17 | `ci-pr-gate.test.mjs` over every `pull_request` workflow and the shared conditions | branch here, fork with and without `ci:run`, another label, draft with the label, ready, push, merge group, dispatch | a job that can start on a pull request without the condition, a label trigger, a required job that skips for a pull request that may not run CI, or a draft or unlabelled fork that runs fails |-| FR18 | `perf-nightly-workflow.test.mjs`, `perf-trend.test.mjs` and `run-labels.test.mjs` | nightly and dispatch; labelled, unlabelled, draft and unvouched-fork pull requests; write, read and no access; newest label event; failed lookup; 10% boundary; metric floors; seven-day window edges; fewer than three runs; a metric over once, twice in a row, or a different metric before; recorded and pull request runs | a run on an unlabelled pull request, a label honoured from read access, a regression called at exactly 10%, under its floor or on one run alone, a run outside the window in the baseline, a pull request run that records, or a second regression issue fails |-| FR19 | `ci-impact.test.mjs`, `pr-preview.test.mjs` and the maintenance template | CI change and non-CI change; standard, non-standard and expression runners; added, removed and changed jobs; trigger change | a CI change reports no impact, a move onto a non-standard runner or a pool or time-to-green rise past its threshold goes unflagged, or the section names a price |-| FR20 | `ci-heavy-deferral.test.mjs` over ci.yml, lint.yml and pr-comment.yml | agent push; marked ready; opened; reopened; re-run; another author; release branch; merge-back; spec-only change; Lab-only change; a release-check and an opt-in label run, where the decision skips; a failed-jobs re-run of a deferred push | a heavy job runs on a deferred push, a required context passes or skips on one, a ready, reopened or re-run pull request defers, a spec-only or Lab-only change defers, the report hides the deferral, or a job below the decision skips because it skipped |-| FR21 | `ci-heavy-lanes.test.mjs` dispatch cases, `main-unit-run.test.mjs` over deploy.yml, `release-check-receipt.test.mjs` | push run; dispatched unit run; tip with the scheduler's or a person's release-check, or a person's maintenance capture; unit run cancelled, skipped or timed out; newer recheck or person's run of the tip; a person's validation of an older commit; cut commit with and without a passing unit run | a push runs the unit suites, a push cancels a unit run, a release-check comes without a unit run of its commit, an incomplete run goes unreported or waits a window, or a cut publishes without a passing unit run |-| FR22 | `main-validation-workflow.test.mjs` over the Main workflow and its commit resolver; `vitest-shard-sequencer.test.mjs` over the recorded Node times | six UI and six Node legs; dispatch without a commit, with a commit in main's history, with a commit outside it and with a malformed one; a re-check from the workflow token and from a person, and one that names `sha`; a `sha` before the size records, and one of only spaces; four and six Node legs over the recorded suite, a file with no recorded time, a project other than `node` | a hold, a leg past the fifteen-minute budget, a commit outside main's history that validates, a person's dispatch or a person's `sha` run that cancels or replaces a validation of main, a `sha` lane that checks out another commit, or a `sha` run named for main's tip, or two of the slowest Node files in one leg, a file run by no leg or by two, or a split that depends on collection order fails |-| FR23 | `release-check-shape.test.mjs`, `a11y-contract-shard.test.mjs` and the release-check workflow contract | release-check and pull-request legs; a contract file longer than a leg's share, one it cannot name exactly, and a serial one; the recorded suite; a re-check from an admin, a maintainer and a writer, from another branch, with a short SHA and with an older commit; failed-only beside a passed, a running and a missing run | a narrower release-check, a held or over-budget leg, a test selected by no leg or by two, a re-check that a writer can start, that waits for main's running check, or that re-runs jobs of another commit fails |-| FR24 | `ci-heavy-lanes.test.mjs` cadence cases | release-check 170 and 176 minutes old; the unit lane hourly beside it; weekday 06:37 Pacific inside the window in standard and daylight time; the pre-cut check already started; the tip already checked; a weekend morning; before 06:30 and after 07:30 | a release-check starts inside the 175-minute window, the pre-cut check is skipped or starts twice, or it runs on a weekend |-| FR26 | `ci-lab-only-routing.test.mjs`, `change-scope.test.mjs` and `test-scope-action.test.mjs` Lab-only cases | a Lab-only change, with and without a Changeset; a new Lab component with its routes, discovery entry and story; Lab beside core, charts, a core Storybook story, a route or discovery entry for another component, an entry-file diff GitHub leaves out, the docsite, the Sandbox, a workflow, the lockfile, root configuration, internal tooling or a spec record; a rename into or out of Lab; an incomplete list; a base classifier without the lane; each required context, its owners, the UI legs' Lab tests, the UI and Node guard tests, the repository guards, the Storybook build and Lab typecheck, the heavy suites with and without a label, lint and an agent push | a mixed change takes the Lab-only lane; a new Lab component's own entry files make it mixed, or another component's do not; a changed existing story, a story for a component the change does not carry, or a renamed entry file keeps the lane; the CLI official-packages check, the route-lock check when the lock changed, or the Storybook build does not run for one; a required context skips or fails, or passes without its notice; a Lab test, a guard test, a repository guard, the Lab typecheck or the Storybook build does not run; an unlabelled heavy suite, the docsite or the full typecheck runs, or a label's suite cannot audit Lab; lint is skipped |-| FR27 | `check-public-text.test.mjs` over the check and the Lint workflow step | each identifier shape; a hashed name and host made up in the test; ordinary text; a finding in a commit message, an added line and the description; a match before the merge base; an empty range, a bad sha, a missing commit and a missing digest file | a reference passes; the output holds the matched text; a match on the base branch fails a later pull request; an unreadable range passes; the step runs the pull request's own copy |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| FR1–FR2 | classifier unit tests expose the surface set; `fs-guard-tests.test.mjs` spec-reader cases | knowledge; docsite; admitted tool; Core/Lab/Charts/Rich Text/Vega source; shared config; unknown; a spec-only change to a record a test reads | an unclassified path receives a specialized lane, a category has no check owner, or a spec-only change skips a test that reads its record |+| FR3–FR4 | workflow contract tests execute an isolated trusted-base classifier | valid base; missing merge base; missing matcher/registry; classifier self-change; merge group | PR-controlled policy grants a lane, or missing trust data skips checks |+| FR5 | mixed-surface and incomplete-owner routing tests | spec+component; tooling+component; named surface without admitted lane; docsite+shared | one surface hides another owner or a named-but-incomplete surface skips broad CI |+| FR6–FR8 | Node-tooling dependency, CI workflow, and trusted post-CI workflow tests | both admitted score-ledger paths; Sandbox projection imports; test/build joins; preview/visual publisher | UI/browser/build work or preview publication runs for the singleton tool set, an operational consumer is untested, a visual status stays pending, or a required context disappears |+| FR9 | mutation-sensitive classifier and workflow fixtures | unknown path; rename from unknown; truncated list; package-specific public paths | weakening a fail-closed rule leaves the suite green |+| FR10 | surface-admission and routing contract tests | existing surface; proposed surface with and without the full admission contract | a new surface adds lanes without its approved paths, commands, ownership, projections, and routing tests |+| FR11 | surface owner, internal-job, and required-join contract tests | Build package browser behavior; CLI; theme-family broad fallback; mixed Core+CLI | a second owner is routed for one surface, an internal job masquerades as a lane, an owned failure misses its join, or an unrelated owner runs |+| FR12 | Storybook visual-plan, canonical workflow, and repository-owner guard tests | PR scope; full-plan maintenance; report-only publication; deployment/a11y/RTL/vibe artifacts | another workflow captures or compares pixels, a renamed or aliased owner escapes the guard, or legitimate non-visual artifacts are rejected |+| FR12 | `touched-components.test.mjs` changed-spec routing; `a11y-pr-contracts.test.mjs` `changedOnly` cases; `a11y-changed-stories.test.mjs` and the touched job's story-audit contract | a pull request that adds a browser accessibility spec; one that changes an `always` spec; one that changes a `release-only` or an `audit` spec; one that changes more spec files than the limit; a component change with no spec change; a pull request that adds an `a11y/` story no component owns | a pull request that adds a browser accessibility spec that fails is not caught on that pull request, another component's spec or an unchanged `audit` spec runs in the contract job, a not-run file reads as passed or fails the join, a failing contract leaves the `test` join green, or a new violation in a changed story no component owns passes the touched check |+| FR12 | `a11y-pr-contracts.test.mjs` ownership cases; the CI workflow contract; contract-job and unit-test-job timings on 17 component pull requests | a pull request that touches one component with an owned `release-only` contract, passing and failing; a contract file that cannot finish within the budget; a wide change; a reverse dependent of the touched component; measured: setup up to about 1.5 minutes plus the 8-minute stop, against the slowest unit-test job finishing 9.9 to 25 minutes after the Storybook build | a touched component's owned `release-only` contract does not run on its pull request, a failing contract leaves the `test` join green, a skipped file is split, does not show as "not run" in the check's summary or fails the join, the contract job finishes after the slowest unit-test job, or a wide change or reverse dependent runs owned contracts |+| FR13 | classifier, workflow contract, component-analysis and RTL-scope tests | component change; shared module; Changeset beside code; infrastructure path; incomplete list; no build | an infrastructure path is scoped, a file-system guard test is skipped, a reverse dependent leaves visual/RTL or enters PR accessibility, or a full-suite event is narrowed |+| FR14 | `workflow-paths.test.mjs` over every workflow | path allowlist; required-context workflow | a `paths-ignore`, a match-all or exclusion glob, or a path filter on a workflow that reports a required context fails |+| FR15 | workflow contract and reconciler tests | ENGOWNER spec PR; owner command; other comment; fork review; non-spec PR; run over the request budget; maintainer dispatch; fork PR, code-only: an owner's exact-head approval plus the owner command clears the code half | `review-required` succeeds while spec approval is missing, another workflow publishes a review context, a fork review starts the spec checks, a non-command comment starts a runner, an over-budget run decides, or a fork's approved code-only PR stays pending after the owner command |+| FR16 | `heavy-caps-action.test.mjs` cap cases and heavy-job contract; `ci-admission.test.mjs` | sixteenth-oldest PR; 101st heavy run of the day, beside cancelled, light and other-branch runs; agent lane and its five-PR and forty-run backstops; an engineering owner, including the shared login past those backstops, a commented-out or trailing-comment handle and an unreadable roster; bot; the deciding run; re-run; failed lookup; a run with room, without room, past its longest wait, beside a waiting `main` check, as a draft or unlabelled fork, with opt-in labels, beside small workflows past their measured most, and with the API unreadable; each workflow's most jobs; every required context's rule | a heavy suite that runs ahead of the author's fifteen oldest PRs, or past the daily cap, a capped job that passes, an engineering owner or a re-run that is held, or a roster read from the pull request's head, a run that starts without room before its longest wait, a pull-request run that starts while `main` has waited under fifteen minutes, a job admission could skip, a peak below the jobs its run holds, or a job on a slim runner planned past its fifteen-minute cap fails |+| FR16 | `ci-admission.test.mjs` cases for one start at the longest wait at a time and the workflow contract | a pull-request run at its longest wait alone, within ten minutes of another pull-request run's start there and after them, behind a run that waited longer and ahead of a younger one; another run that found room earlier, a fork's stopped run and a `main` run that waited its longest; a `main` run and a merge-queue entry at their longest wait; the rest of a run whose Storybook build found room; ten runs out of time together; the required contexts and ci-full for either wait; a pull-request run that finds ten others waiting and room only for its Storybook build, and one at its longest wait behind more than ten that waited longer | two pull-request runs start at their longest wait within ten minutes, a younger run starts ahead of a longer waiter, a `main` run or merge-queue entry stops, a run CI is full for builds, or a required context passes or skips |+| FR17 | `ci-pr-gate.test.mjs` over every `pull_request` workflow and the shared conditions | branch here, fork with and without `ci:run`, another label, draft with the label, ready, push, merge group, dispatch | a job that can start on a pull request without the condition, a label trigger, a required job that skips for a pull request that may not run CI, or a draft or unlabelled fork that runs fails |+| FR18 | `perf-nightly-workflow.test.mjs`, `perf-trend.test.mjs` and `run-labels.test.mjs` | nightly and dispatch; labelled, unlabelled, draft and unvouched-fork pull requests; write, read and no access; newest label event; failed lookup; 10% boundary; metric floors; seven-day window edges; fewer than three runs; a metric over once, twice in a row, or a different metric before; recorded and pull request runs | a run on an unlabelled pull request, a label honoured from read access, a regression called at exactly 10%, under its floor or on one run alone, a run outside the window in the baseline, a pull request run that records, or a second regression issue fails |+| FR19 | `ci-impact.test.mjs`, `pr-preview.test.mjs` and the maintenance template | CI change and non-CI change; standard, non-standard and expression runners; added, removed and changed jobs; trigger change | a CI change reports no impact, a move onto a non-standard runner or a pool or time-to-green rise past its threshold goes unflagged, or the section names a price |+| FR20 | `ci-heavy-deferral.test.mjs` over ci.yml, lint.yml and pr-comment.yml | agent push; marked ready; opened; reopened; re-run; another author; release branch; merge-back; spec-only change; Lab-only change; a release-check and an opt-in label run, where the decision skips; a failed-jobs re-run of a deferred push | a heavy job runs on a deferred push, a required context passes or skips on one, a ready, reopened or re-run pull request defers, a spec-only or Lab-only change defers, the report hides the deferral, or a job below the decision skips because it skipped |+| FR21 | `ci-heavy-lanes.test.mjs` dispatch cases, `main-unit-run.test.mjs` over deploy.yml, `release-check-receipt.test.mjs` | push run; dispatched unit run; tip with the scheduler's or a person's release-check, or a person's maintenance capture; unit run cancelled, skipped or timed out; newer recheck or person's run of the tip; a person's validation of an older commit; cut commit with and without a passing unit run | a push runs the unit suites, a push cancels a unit run, a release-check comes without a unit run of its commit, an incomplete run goes unreported or waits a window, or a cut publishes without a passing unit run |+| FR22 | `main-validation-workflow.test.mjs` over the Main workflow and its commit resolver; `vitest-shard-sequencer.test.mjs` over the recorded Node times | six UI and six Node legs; dispatch without a commit, with a commit in main's history, with a commit outside it and with a malformed one; a re-check from the workflow token and from a person, and one that names `sha`; a `sha` before the size records, and one of only spaces; four and six Node legs over the recorded suite, a file with no recorded time, a project other than `node` | a hold, a leg past the fifteen-minute budget, a commit outside main's history that validates, a person's dispatch or a person's `sha` run that cancels or replaces a validation of main, a `sha` lane that checks out another commit, or a `sha` run named for main's tip, or two of the slowest Node files in one leg, a file run by no leg or by two, or a split that depends on collection order fails |+| FR23 | `release-check-shape.test.mjs`, `a11y-contract-shard.test.mjs` and the release-check workflow contract | release-check and pull-request legs; a contract file longer than a leg's share, one it cannot name exactly, and a serial one; the recorded suite; a re-check from an admin, a maintainer and a writer, from another branch, with a short SHA and with an older commit; failed-only beside a passed, a running and a missing run | a narrower release-check, a held or over-budget leg, a test selected by no leg or by two, a re-check that a writer can start, that waits for main's running check, or that re-runs jobs of another commit fails |+| FR24 | `ci-heavy-lanes.test.mjs` cadence cases | release-check 170 and 176 minutes old; the unit lane hourly beside it; weekday 06:37 Pacific inside the window in standard and daylight time; the pre-cut check already started; the tip already checked; a weekend morning; before 06:30 and after 07:30 | a release-check starts inside the 175-minute window, the pre-cut check is skipped or starts twice, or it runs on a weekend |+| FR26 | `ci-lab-only-routing.test.mjs`, `change-scope.test.mjs` and `test-scope-action.test.mjs` Lab-only cases | a Lab-only change, with and without a Changeset; a new Lab component with its routes, discovery entry and story; Lab beside core, charts, a core Storybook story, a route or discovery entry for another component, an entry-file diff GitHub leaves out, the docsite, the Sandbox, a workflow, the lockfile, root configuration, internal tooling or a spec record; a rename into or out of Lab; an incomplete list; a base classifier without the lane; each required context, its owners, the UI legs' Lab tests, the UI and Node guard tests, the repository guards, the Storybook build and Lab typecheck, the heavy suites with and without a label, lint and an agent push | a mixed change takes the Lab-only lane; a new Lab component's own entry files make it mixed, or another component's do not; a changed existing story, a story for a component the change does not carry, or a renamed entry file keeps the lane; the CLI official-packages check, the route-lock check when the lock changed, or the Storybook build does not run for one; a required context skips or fails, or passes without its notice; a Lab test, a guard test, a repository guard, the Lab typecheck or the Storybook build does not run; an unlabelled heavy suite, the docsite or the full typecheck runs, or a label's suite cannot audit Lab; lint is skipped |+| FR27 | `check-public-text.test.mjs` over the check and the Lint workflow step | each identifier shape; a hashed name and host made up in the test; ordinary text; a finding in a commit message, an added line and the description; a match before the merge base; an empty range, a bad sha, a missing commit and a missing digest file | a reference passes; the output holds the matched text; a match on the base branch fails a later pull request; an unreadable range passes; the step runs the pull request's own copy |## Decision log