An open source design system that's fully customizable and agent ready
TypeScript
ci: the contract job runs a touched component's own specs on a wide change, then, for up to a minute, the folders that render it (#10215)
Cindy Zhangc36274ce2074
diff --git a/.github/scripts/a11y-pr-contracts.mjs b/.github/scripts/a11y-pr-contracts.mjsindex c5441f6731..aac9d378ab 100644--- a/.github/scripts/a11y-pr-contracts.mjs+++ b/.github/scripts/a11y-pr-contracts.mjs@@ -41,14 +41,16 @@* component folder changes, or a component it is named after is in scope;* never for a `scope` token or an unknown scope.*- * `--changed-only <specs> --changed-files <files> --owned-by <components>`- * (the default check of the components a pull request touches): run the- * browser specs the pull request adds or modifies, listed one per line in- * <specs>, then the `scoped` and `release-only` specs that the comma-separated- * touched components own (`ownedSpecs`; <files> lists every changed path, one- * per line, for the folder-change rule). It reads no title, runs no component- * audit, and runs no spec of a reverse dependent; a changed `audit` spec still- * waits for its audit pull request. To stay inside the job's 15-minute budget+ * `--changed-only <specs> --changed-files <files> --owned-by <components>+ * [--dependents-of <folders>]` (the default check of the components a pull+ * request touches, a wide change included): run the browser specs the pull+ * request adds or modifies, listed one per line in <specs>, then the `scoped`+ * and `release-only` specs that the comma-separated touched components own+ * (`ownedSpecs`; <files> lists every changed path, one per line, for the+ * folder-change rule), then the `scoped` and `release-only` specs of the+ * component folders that render a touched folder (`dependentSpecs`, nearest+ * first), in the time left. It reads no title and runs no component audit; a+ * changed `audit` spec still waits for its audit pull request. To stay inside the job's 15-minute budget* it takes at most CHANGED_SPEC_LIMIT changed files, starts each file only* when the run still fits DEFAULT_CHECK_BUDGET_MS at that file's recorded time* (.github/a11y-contract-durations.json), and stops at that budget. Each file@@ -322,6 +324,13 @@ export const DEFAULT_CHECK_BUDGET_MS = 8 * 60 * 1000;export const RECORDED_TIME_MARGIN = 1.25;export const STARTUP_MS = 30 * 1000;+/**+ * The most a run spends on the specs of folders that render a touched+ * component: their share of the projected time, after the changed and owned+ * specs.+ */+export const DEPENDENT_SHARE_MS = 60 * 1000;+/** The expected time of a file that has no recorded time. */const UNRECORDED_FILE_SECONDS = 60;@@ -375,6 +384,264 @@ export function ownedSpecs({specs, components, changedPaths}) {});}+// The component folders that render a touched component (spec:AST-030 FR12).+// The CI step runs this file alone from the merge commit, so it imports no+// repository module. The graph is file by file over value imports and+// re-exports (`import type` and `export type` put no code on a page): a+// relative specifier, a package subpath (`@astryxdesign/core/internal/touch`),+// or a named import from a package root, through that package's folder+// barrels. Reach crosses shared files (`utils`, `hooks`, `internal`) without+// counting a step; each step into another component folder counts one.++const SOURCE = /\.(?:[cm]?[jt]sx?)$/;+const NOT_RENDERED =+ /(?:^|\/)__tests__\/|\.(?:test|stories|doc)\.[^/]+$|\.spec\.[^/]+$|\.d\.ts$/;+const STATEMENT =+ /(?:^|[\n;])\s*(import|export)\s+(type\s+)?([^'";]*?)\s*from\s*['"]([^'"]+)['"]|(?:^|[\n;])\s*import\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;+const RESOLVE_SUFFIXES = [+ '',+ '.ts',+ '.tsx',+ '.mts',+ '.js',+ '.jsx',+ '.mjs',+ '/index.ts',+ '/index.tsx',+ '/index.js',+];++const componentFolderOf = file => {+ const match = /^packages\/([^/]+)\/src\/([A-Z][^/]*)\//.exec(file);+ return match ? `${match[1]}/${match[2]}` : null;+};++function sourceFiles(root, dir) {+ const out = [];+ const full = path.join(root, dir);+ if (!fs.existsSync(full)) return out;+ for (const entry of fs.readdirSync(full, {withFileTypes: true})) {+ const file = `${dir}/${entry.name}`;+ if (entry.isDirectory()) {+ if (entry.name !== 'node_modules' && entry.name !== 'dist')+ out.push(...sourceFiles(root, file));+ } else if (SOURCE.test(entry.name) && !NOT_RENDERED.test(file)) {+ out.push(file);+ }+ }+ return out;+}++/**+ * The value imports of one source text: `[{specifier, names}]`, where `names`+ * lists the named value bindings (empty for a default, namespace or bare+ * import, which take the whole module).+ */+export function valueImports(text) {+ const out = [];+ for (const match of text.matchAll(STATEMENT)) {+ // A bare `import './x'` or a dynamic `import('./x')` takes the module.+ if (match[5] || match[6]) {+ out.push({specifier: match[5] ?? match[6], names: []});+ continue;+ }+ if (match[2]) continue;+ const clause = match[3] ?? '';+ const braced = /\{([^}]*)\}/.exec(clause);+ const names = braced+ ? braced[1]+ .split(',')+ .map(part => part.trim())+ .filter(part => part && !part.startsWith('type '))+ .map(part => part.split(/\s+as\s+/)[0].trim())+ : [];+ const outsideBraces = clause+ .replace(/\{[^}]*\}/, '')+ .replace(/,/g, '')+ .trim();+ // `import {type A, type B} from` imports no value.+ if (braced && names.length === 0 && !outsideBraces) continue;+ out.push({specifier: match[4], names: outsideBraces ? [] : names});+ }+ return out;+}++/**+ * Edges `imported file -> importing files` over the packages' rendered+ * sources.+ * @param {string} root+ * @returns {Map<string, Set<string>>}+ */+export function importerGraph(root) {+ const packagesDir = path.join(root, 'packages');+ const packages = fs.existsSync(packagesDir)+ ? fs+ .readdirSync(packagesDir)+ .filter(pkg => fs.existsSync(path.join(packagesDir, pkg, 'src')))+ : [];+ const files = packages.flatMap(pkg =>+ sourceFiles(root, `packages/${pkg}/src`),+ );+ const known = new Set(files);+ const texts = new Map(+ files.map(file => [file, fs.readFileSync(path.join(root, file), 'utf8')]),+ );+ const resolve = target => {+ for (const suffix of RESOLVE_SUFFIXES) {+ if (known.has(`${target}${suffix}`)) return `${target}${suffix}`;+ }+ return null;+ };+ // A barrel's named exports (`index.ts`): each name to the file it comes+ // from, one `export *` level deep.+ const barrels = new Map();+ const namesOf = index => {+ if (barrels.has(index)) return barrels.get(index);+ const names = new Map();+ barrels.set(index, names);+ for (const {specifier, names: own} of valueImports(texts.get(index))) {+ if (!specifier.startsWith('.')) continue;+ const target = resolve(+ path.posix.normalize(`${path.posix.dirname(index)}/${specifier}`),+ );+ if (!target) continue;+ for (const name of own) names.set(name, target);+ if (own.length === 0) {+ for (const inner of valueImports(texts.get(target))) {+ for (const name of inner.names) names.set(name, target);+ }+ for (const match of texts+ .get(target)+ .matchAll(/export\s+(?:const|function|class)\s+(\w+)/g)) {+ names.set(match[1], target);+ }+ }+ }+ return names;+ };+ const isBarrel = file => /\/index\.[cm]?[jt]sx?$/.test(file ?? '');+ const importers = new Map();+ const add = (imported, importer) => {+ if (!imported || imported === importer) return;+ if (!importers.has(imported)) importers.set(imported, new Set());+ importers.get(imported).add(importer);+ };+ // Named imports from a barrel reach only the files those names come from.+ const link = (target, names, file) => {+ if (!target) return;+ if (!isBarrel(target) || names.length === 0) return add(target, file);+ const barrel = namesOf(target);+ for (const name of names) add(barrel.get(name) ?? target, file);+ };+ for (const file of files) {+ for (const {specifier, names} of valueImports(texts.get(file))) {+ if (specifier.startsWith('.')) {+ link(+ resolve(+ path.posix.normalize(`${path.posix.dirname(file)}/${specifier}`),+ ),+ names,+ file,+ );+ continue;+ }+ const match = /^@astryxdesign\/([^/]+)(?:\/(.+))?$/.exec(specifier);+ if (!match || !packages.includes(match[1])) continue;+ const [, pkg, subpath] = match;+ link(+ resolve(+ subpath+ ? `packages/${pkg}/src/${subpath}`+ : `packages/${pkg}/src/index`,+ ),+ names,+ file,+ );+ }+ }+ return importers;+}++/**+ * The component folders that render a touched folder, nearest first, then in+ * path order. A step from one component folder into another counts one;+ * steps inside a folder or through shared files count none.+ * @param {Map<string, Set<string>>} importers+ * @param {string[]} touched `<pkg>/<Folder>`+ * @returns {{folder: string, depth: number}[]}+ */+export function renderingFolders(importers, touched) {+ const touchedSet = new Set(touched);+ const depth = new Map();+ const deque = [];+ for (const file of importers.keys()) {+ if (touchedSet.has(componentFolderOf(file))) {+ depth.set(file, 0);+ deque.push(file);+ }+ }+ for (const [, set] of importers) {+ for (const file of set) {+ if (touchedSet.has(componentFolderOf(file)) && !depth.has(file)) {+ depth.set(file, 0);+ deque.push(file);+ }+ }+ }+ while (deque.length > 0) {+ const file = deque.shift();+ const here = depth.get(file);+ const folder = componentFolderOf(file);+ for (const importer of importers.get(file) ?? []) {+ const target = componentFolderOf(importer);+ if (touchedSet.has(target)) continue;+ const step = target && target !== folder ? 1 : 0;+ const next = here + step;+ if (depth.has(importer) && depth.get(importer) <= next) continue;+ depth.set(importer, next);+ if (step === 0) deque.unshift(importer);+ else deque.push(importer);+ }+ }+ const folders = new Map();+ for (const [file, d] of depth) {+ const folder = componentFolderOf(file);+ if (!folder || touchedSet.has(folder)) continue;+ if (!folders.has(folder) || folders.get(folder) > d) folders.set(folder, d);+ }+ return [...folders]+ .map(([folder, d]) => ({folder, depth: d}))+ .sort((a, b) => a.depth - b.depth || a.folder.localeCompare(b.folder));+}++/**+ * The `scoped` and `release-only` specs of the component folders that render a+ * touched folder, nearest first, then in path order, leaving out `planned`.+ * @param {{file: string, routing: {mode: string}}[]} specs+ * @param {{folder: string, depth: number}[]} rendering+ * @param {Set<string>} planned+ */+export function dependentSpecs(specs, rendering, planned) {+ const depthOf = new Map(rendering.map(({folder, depth}) => [folder, depth]));+ const folderOf = file => {+ const match = /^packages\/([^/]+)\/src\/([^/]+)\//.exec(file);+ return match ? `${match[1]}/${match[2]}` : null;+ };+ return specs+ .filter(+ ({file, routing}) =>+ (routing.mode === 'scoped' || routing.mode === 'release-only') &&+ !planned.has(file) &&+ depthOf.has(folderOf(file)),+ )+ .map(({file}) => ({file, depth: depthOf.get(folderOf(file))}))+ .sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file))+ .map(({file, depth}) => ({+ file,+ reason: `renders a touched component${depth > 1 ? ` (${depth} folders away)` : ''}`,+ }));+}+/*** Recorded seconds per spec file. Test entries (file and title path) are left* out.@@ -416,22 +683,28 @@ function median(values) {/*** The default check's run. First the changed specs, at most the limit, in path- * order. Then the owned specs, in path order. A file starts only when the run- * still fits the budget with that file at its recorded time (with the margin).- * The other files are not run, with the label that runs them.+ * order. Then the owned specs, in path order. Then the dependents' specs, in+ * the order given (nearest first), within their own share of the time. A file+ * starts only when the run still fits the budget with that file at its+ * recorded time (with the margin). The other files are not run, with the+ * label that runs them.* @param {object} options* @param {{file: string, reason: string}[]} options.changed* @param {{file: string, reason: string}[]} options.owned+ * @param {{file: string, reason: string}[]} [options.dependents]* @param {Record<string, number>} options.seconds recorded seconds per file* @param {number} options.workers* @param {number} [options.budgetMs]+ * @param {number} [options.dependentShareMs]*/export function planDefaultCheck({changed,owned,+ dependents = [],seconds,workers,budgetMs = DEFAULT_CHECK_BUDGET_MS,+ dependentShareMs = DEPENDENT_SHARE_MS,}) {const {run: changedInLimit, notRun} = withinBudget(changed);const fallback = median(Object.values(seconds));@@ -443,17 +716,38 @@ export function planDefaultCheck({const ordered = [...owned].filter(({file}) => !planned.has(file)).sort((a, b) => a.file.localeCompare(b.file));- for (const entry of [...changedInLimit, ...ordered]) {+ const ownedFiles = new Set(ordered.map(({file}) => file));+ const after = dependents.filter(+ ({file}) => !planned.has(file) && !ownedFiles.has(file),+ );+ const tryRun = (entry, fits, limit) => {const withFile = [...files, entry.file];- if (STARTUP_MS + projectedMs(withFile, msOf, workers) <= budgetMs) {- run.push(entry);- files.push(entry.file);- } else {+ if (STARTUP_MS + projectedMs(withFile, msOf, workers) > budgetMs) {notRun.push({file: entry.file,reason: `${entry.reason}; its expected ${Math.round(secondsOf(entry.file))} s does not fit the default check's ${budgetMs / 60000}-minute budget; add ci:run-a11y to run it`,});+ } else if (!fits(withFile)) {+ notRun.push({+ file: entry.file,+ reason: `${entry.reason}; its expected ${Math.round(secondsOf(entry.file))} s does not fit the ${limit}; add ci:run-a11y to run it`,+ });+ } else {+ run.push(entry);+ files.push(entry.file);}+ };+ for (const entry of [...changedInLimit, ...ordered])+ tryRun(entry, () => true);+ const beforeDependents = projectedMs(files, msOf, workers);+ for (const entry of after) {+ tryRun(+ entry,+ withFile =>+ projectedMs(withFile, msOf, workers) - beforeDependents <=+ dependentShareMs,+ `${dependentShareMs / 60000}-minute share for folders that render a touched component`,+ );}return {run, notRun};}@@ -463,13 +757,24 @@ export function planDefaultCheck({* run, so it never reads as passed.* @param {{components: string[], selected: {file: string, reason: string}[], notRun: {file: string, reason: string}[]}} plan*/-export function summaryMarkdown({components, selected, notRun}) {+export function summaryMarkdown({+ components,+ selected,+ notRun,+ rendering = [],+}) {const lines = ['### Component accessibility contracts', ''];lines.push(components.length? `Touched components: ${components.map(c => `\`${c}\``).join(', ')}.`: 'No touched component.',);+ if (rendering.length) {+ lines.push(+ '',+ `Folders that render a touched component: ${rendering.length}; their specs run, nearest first, within ${DEPENDENT_SHARE_MS === 60 * 1000 ? 'one minute' : `${DEPENDENT_SHARE_MS / 60000} minutes`} of the time left.`,+ );+ }lines.push('');if (selected.length === 0 && notRun.length === 0) {lines.push('No accessibility contract to run.');@@ -720,11 +1025,17 @@ function main() {const changedFilesFile = flagValue(argv, '--changed-files');const ownedByValue = flagValue(argv, '--owned-by');const ownedBy = (ownedByValue ?? '').split(',').filter(Boolean);+ const dependentsOfValue = flagValue(argv, '--dependents-of');+ const dependentsOf = (dependentsOfValue ?? '').split(',').filter(Boolean);if (- (ownedByValue != null || changedFilesFile != null) &&+ (ownedByValue != null ||+ changedFilesFile != null ||+ dependentsOfValue != null) &&changedOnlyFile == null) {- throw new Error('--owned-by and --changed-files need --changed-only');+ throw new Error(+ '--owned-by, --changed-files and --dependents-of need --changed-only',+ );}// Without every changed path the folder rule selects nothing, and the// dropped contracts would read as passed.@@ -733,7 +1044,12 @@ function main() {'--owned-by needs --changed-files with the list of changed paths',);}- const flagValues = new Set([changedOnlyFile, changedFilesFile, ownedByValue]);+ const flagValues = new Set([+ changedOnlyFile,+ changedFilesFile,+ ownedByValue,+ dependentsOfValue,+ ]);// Outside CI, a run with no base compares with origin/main.const base =process.env.BASE_SHA ||@@ -764,19 +1080,27 @@ function main() {components,title,});- const budgeted =- changedOnlyFile != null- ? planDefaultCheck({- changed: changedOnly(routed, changedPaths),- owned: ownedSpecs({- specs,- components: ownedBy,- changedPaths: readLines(changedFilesFile) ?? changedPaths,- }),- seconds: readDurations(root, policySha),- workers: contractWorkers(),- })- : {run: routed, notRun: []};+ const rendering =+ changedOnlyFile != null && dependentsOf.length > 0+ ? renderingFolders(importerGraph(root), dependentsOf)+ : [];+ const budgeted = (() => {+ if (changedOnlyFile == null) return {run: routed, notRun: []};+ const changed = changedOnly(routed, changedPaths);+ const owned = ownedSpecs({+ specs,+ components: ownedBy,+ changedPaths: readLines(changedFilesFile) ?? changedPaths,+ });+ const planned = new Set([...changed, ...owned].map(({file}) => file));+ return planDefaultCheck({+ changed,+ owned,+ dependents: dependentSpecs(specs, rendering, planned),+ seconds: readDurations(root, policySha),+ workers: contractWorkers(),+ });+ })();const selected = budgeted.run;const notRun = budgeted.notRun;const [audited] = auditedComponents(title);@@ -820,7 +1144,7 @@ function main() {if (changedOnlyFile != null && process.env.GITHUB_STEP_SUMMARY) {fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY,- summaryMarkdown({components: ownedBy, selected, notRun}),+ summaryMarkdown({components: ownedBy, selected, notRun, rendering}),);}if (process.argv.includes('--dry-run')) return 0;diff --git a/.github/scripts/a11y-pr-contracts.test.mjs b/.github/scripts/a11y-pr-contracts.test.mjsindex f4bf2c9dd7..7d2004b556 100644--- a/.github/scripts/a11y-pr-contracts.test.mjs+++ b/.github/scripts/a11y-pr-contracts.test.mjs@@ -27,6 +27,11 @@ import {changedOnly,changedSinceMergeBase,DEFAULT_CHECK_BUDGET_MS,+ DEPENDENT_SHARE_MS,+ dependentSpecs,+ importerGraph,+ renderingFolders,+ valueImports,fileSeconds,kebab,ownedSpecs,@@ -480,6 +485,202 @@ describe('the default check of the touched components', () => {});});+describe('the folders that render a touched component (spec:AST-030 FR12)', () => {+ const write = (root, file, text) => {+ fs.mkdirSync(path.dirname(path.join(root, file)), {recursive: true});+ fs.writeFileSync(path.join(root, file), text);+ };+ // #7910's shape: Spinner changes; TextInput renders it, CommandPalette+ // renders TextInput, a Lab component imports Spinner from Core's root, and+ // a shared file passes the reach on, file by file.+ const repo = () => {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'render-graph-'));+ const files = {+ 'packages/core/src/index.ts':+ "export * from './Spinner';\nexport * from './Button';\n",+ 'packages/core/src/Spinner/index.ts':+ "export {Spinner} from './Spinner';\n",+ 'packages/core/src/Spinner/Spinner.tsx': 'export function Spinner() {}\n',+ 'packages/core/src/Button/index.ts': "export {Button} from './Button';\n",+ 'packages/core/src/Button/Button.tsx': 'export function Button() {}\n',+ 'packages/core/src/TextInput/TextInput.tsx':+ "import {Spinner} from '../Spinner/Spinner';\n",+ 'packages/core/src/CommandPalette/CommandPaletteInput.tsx':+ "import {TextInput} from '../TextInput/TextInput';\n",+ // One shared file renders Spinner; its neighbour does not.+ 'packages/core/src/internal/loading.ts':+ "import {Spinner} from '../Spinner/Spinner';\n",+ 'packages/core/src/internal/mergeProps.ts':+ 'export function mergeProps() {}\n',+ 'packages/core/src/Banner/Banner.tsx':+ "import {loading} from '../internal/loading';\n",+ 'packages/core/src/Divider/Divider.tsx':+ "import {mergeProps} from '../internal/mergeProps';\n",+ // A type-only import puts no code on the page.+ 'packages/core/src/internal/groupItems.ts':+ "import type {SpinnerSize} from '../Spinner/Spinner';\nimport {type SpinnerTone} from '../Spinner/Spinner';\n",+ 'packages/core/src/Menu/Menu.tsx':+ "import {groupItems} from '../internal/groupItems';\n",+ 'packages/core/src/Avatar/__tests__/Avatar.test.tsx':+ "import {Spinner} from '../../Spinner/Spinner';\n",+ 'packages/core/src/Avatar/Avatar.stories.tsx':+ "import {Spinner} from '../Spinner/Spinner';\n",+ 'packages/lab/src/Schedule/shared.tsx':+ "import {Button, Spinner as Busy} from '@astryxdesign/core';\n",+ 'packages/lab/src/Rating/Rating.tsx':+ "import {Button} from '@astryxdesign/core';\n",+ // A lazy import is an edge; a barrel's names reach only their own files.+ 'packages/core/src/Tooltip/Tooltip.tsx':+ "const Busy = lazy(() => import('../Spinner/Spinner'));\n",+ 'packages/core/src/hooks/index.ts':+ "export {useAnnounce} from './useAnnounce';\nexport {useSpin} from './useSpin';\n",+ 'packages/core/src/hooks/useAnnounce.ts':+ 'export function useAnnounce() {}\n',+ 'packages/core/src/hooks/useSpin.ts':+ "import {Spinner} from '../Spinner/Spinner';\nexport function useSpin() {}\n",+ 'packages/core/src/Kbd/Kbd.tsx':+ "import {useAnnounce} from '../hooks';\n",+ 'packages/core/src/Meter/Meter.tsx':+ "import {useSpin} from '../hooks';\n",+ };+ for (const [file, text] of Object.entries(files)) write(root, file, text);+ return root;+ };++ it('lists every folder that renders a touched one, nearest first, never a shared folder, a test or a type-only import', () => {+ const root = repo();+ try {+ expect(renderingFolders(importerGraph(root), ['core/Spinner'])).toEqual([+ {folder: 'core/Banner', depth: 1},+ {folder: 'core/Meter', depth: 1},+ {folder: 'core/TextInput', depth: 1},+ {folder: 'core/Tooltip', depth: 1},+ {folder: 'lab/Schedule', depth: 1},+ {folder: 'core/CommandPalette', depth: 2},+ ]);+ // Nothing renders an untouched leaf.+ expect(+ renderingFolders(importerGraph(root), ['core/CommandPalette']),+ ).toEqual([]);+ } finally {+ fs.rmSync(root, {recursive: true, force: true});+ }+ });++ it('reads value imports and re-exports, never type-only ones', () => {+ expect(+ valueImports(+ "import type {A} from './a';\nimport {type B} from './b';\nimport {type C, D} from './c';\nexport {E} from './e';\nexport type {F} from './f';\nimport G from './g';\nimport './h';\nconst I = lazy(() => import('./i'));",+ ),+ ).toEqual([+ {specifier: './c', names: ['D']},+ {specifier: './e', names: ['E']},+ {specifier: './g', names: []},+ {specifier: './h', names: []},+ {specifier: './i', names: []},+ ]);+ });++ it("selects the rendering folders' scoped and release-only specs, nearest first, leaving out what is planned", () => {+ const at = (folder, name, lines = []) =>+ spec(`packages/${folder}/__tests__/${name}.a11y.chromium.spec.ts`, lines);+ const specs = [+ at('core/src/CommandPalette', 'CommandPalettePending'),+ at('core/src/CommandPalette', 'CommandPalette', [+ '// @pr-a11y audit CommandPalette',+ ]),+ at('core/src/TextInput', 'TextInput', ['// @pr-a11y release-only']),+ at('core/src/TextInput', 'TextInputAlways', ['// @pr-a11y always']),+ at('core/src/Spinner', 'SpinnerMotion'),+ ];+ const rendering = [+ {folder: 'core/TextInput', depth: 1},+ {folder: 'core/CommandPalette', depth: 2},+ ];+ expect(dependentSpecs(specs, rendering, new Set())).toEqual([+ {+ file: 'packages/core/src/TextInput/__tests__/TextInput.a11y.chromium.spec.ts',+ reason: 'renders a touched component',+ },+ {+ file: 'packages/core/src/CommandPalette/__tests__/CommandPalettePending.a11y.chromium.spec.ts',+ reason: 'renders a touched component (2 folders away)',+ },+ ]);+ expect(+ dependentSpecs(+ specs,+ rendering,+ new Set([+ 'packages/core/src/TextInput/__tests__/TextInput.a11y.chromium.spec.ts',+ ]),+ ),+ ).toHaveLength(1);+ });++ it("runs the dependents' specs after the owned ones, in the time left, and reports the rest as not run", () => {+ const own =+ 'packages/core/src/Spinner/__tests__/SpinnerMotion.a11y.chromium.spec.ts';+ const near =+ 'packages/core/src/TextInput/__tests__/TextInput.a11y.chromium.spec.ts';+ const far = 'packages/core/src/Aaa/__tests__/Far.a11y.chromium.spec.ts';+ const {run, notRun} = planDefaultCheck({+ changed: [],+ owned: [{file: own, reason: 'component core/Spinner'}],+ // Given nearest first: the far one is not sorted ahead by its path.+ dependents: [+ {file: near, reason: 'renders a touched component'},+ {file: far, reason: 'renders a touched component (3 folders away)'},+ ],+ seconds: {[own]: 60, [near]: 40, [far]: 400},+ workers: 1,+ });+ expect(run.map(({file}) => file)).toEqual([own, near]);+ expect(notRun.map(({file}) => file)).toEqual([far]);+ expect(notRun[0].reason).toContain(+ 'renders a touched component (3 folders away)',+ );+ expect(notRun[0].reason).toContain('add ci:run-a11y to run it');+ });++ it('gives the dependents at most their one-minute share, and reports the rest as not run', () => {+ const own =+ 'packages/core/src/Spinner/__tests__/SpinnerMotion.a11y.chromium.spec.ts';+ const deps = ['A', 'B', 'C'].map(name => ({+ file: `packages/core/src/${name}/__tests__/${name}.a11y.chromium.spec.ts`,+ reason: 'renders a touched component',+ }));+ // 40 s each with the 1.25 margin is 50 s: one fits 60 s, two do not.+ const {run, notRun} = planDefaultCheck({+ changed: [],+ owned: [{file: own, reason: 'component core/Spinner'}],+ dependents: deps,+ seconds: {+ [own]: 60,+ ...Object.fromEntries(deps.map(({file}) => [file, 40])),+ },+ workers: 1,+ });+ expect(run.map(({file}) => file)).toEqual([own, deps[0].file]);+ expect(notRun.map(({file}) => file)).toEqual([deps[1].file, deps[2].file]);+ expect(notRun[0].reason).toContain(+ '1-minute share for folders that render a touched component',+ );+ expect(DEPENDENT_SHARE_MS).toBe(60 * 1000);+ });++ it('says in the summary how many folders render a touched component', () => {+ expect(+ summaryMarkdown({+ components: ['core/Spinner'],+ selected: [],+ notRun: [],+ rendering: [{folder: 'core/TextInput', depth: 1}],+ }),+ ).toContain('Folders that render a touched component: 1');+ });+});+describe('a11y-spec-files (one spec list for Playwright and the touched check)', () => {it('is the list playwright.config.ts runs', () => {const config = fs.readFileSync(diff --git a/.github/scripts/touched-components.mjs b/.github/scripts/touched-components.mjsindex 75094a4062..3c28696f79 100644--- a/.github/scripts/touched-components.mjs+++ b/.github/scripts/touched-components.mjs@@ -604,6 +604,11 @@ export function main(argv = process.argv.slice(2)) {changed_stories: String(files.some(file => STORY_FILE.test(file))),visual_components: scope.visualComponents.join(','),a11y_owners: scope.a11yOwners.join(','),+ // The contract job runs the touched components' own specs, and those of+ // the folders that render them, wide change or not, inside its own+ // budget (spec:AST-030 FR12).+ contract_owners: scope.touched.join(','),+ contract_folders: scope.folders.join(','),rtl_packages: Object.keys(scope.rtlOwnersByPackage).join(','),rtl_owners: scope.touched.join(','),});diff --git a/.github/scripts/touched-components.test.mjs b/.github/scripts/touched-components.test.mjsindex a1bac5231c..1591c40c37 100644--- a/.github/scripts/touched-components.test.mjs+++ b/.github/scripts/touched-components.test.mjs@@ -674,7 +674,7 @@ describe('pr-component-a11y-contracts routing', () => {"Run the touched components' accessibility contracts",);const ran =- "steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'";+ "steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'";it('starts after the Storybook build, beside the test owners, never after pr-visual or the touched check', () => {expect(contracts.needs).toEqual([@@ -725,7 +725,7 @@ describe('pr-component-a11y-contracts routing', () => {);for (const candidate of contracts.steps.slice(skipIndex + 1)) {expect(candidate.if, candidate.name).toMatch(- /steps\.scope\.outputs\.applies == 'true'|steps\.touched\.outputs\.has_components == 'true'|steps\.contracts\.outcome/,+ /steps\.scope\.outputs\.applies == 'true'|steps\.touched\.outputs\.contract_owners != ''|steps\.contracts\.outcome/,);}});@@ -807,16 +807,20 @@ describe('pr-component-a11y-contracts routing', () => {'git show "$WORKFLOW_SHA:.github/scripts/a11y-pr-contracts.mjs" > "$runner"',);expect(runStep.run).toContain(- 'node "$runner" --changed-only "$SPECS_PATH" --changed-files "$FILES_PATH" --owned-by "$OWNERS"',+ 'node "$runner" --changed-only "$SPECS_PATH" --changed-files "$FILES_PATH" --owned-by "$OWNERS" --dependents-of "$FOLDERS"',);// Every changed path, not only the changed specs: a change in a// component folder owns that folder's specs.expect(runStep.env.FILES_PATH).toBe('${{ steps.scope.outputs.changed_files_path }}',);- // A wide change has no owned specs.+ // A wide change still runs the touched components' own specs, then the+ // specs of the folders that render them (FR12).expect(runStep.env.OWNERS).toBe(- "${{ steps.touched.outputs.has_components == 'true' && steps.touched.outputs.a11y_owners || '' }}",+ '${{ steps.touched.outputs.contract_owners }}',+ );+ expect(runStep.env.FOLDERS).toBe(+ '${{ steps.touched.outputs.contract_folders }}',);expect(runStep.env.A11Y_CONTRACT_WORKERS).toBe(4);expect(runStep.env.WORKFLOW_SHA).toBe('${{ github.sha }}');@@ -941,4 +945,60 @@ describe('the audit of changed stories no other audit covers', () => {fs.rmSync(dir, {recursive: true, force: true});}});++ it("gives the contract job the touched components and folders, wide change or not (#7910's shape)", 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-contracts-'));+ try {+ const owners = [+ 'core/FieldStatus',+ 'core/Spinner',+ 'core/Tokenizer',+ 'core/Typeahead',+ 'core/CheckboxList',+ 'lab/EmojiPicker',+ 'lab/Schedule',+ ];+ fs.writeFileSync(+ path.join(dir, 'files.txt'),+ 'packages/core/src/Spinner/Spinner.tsx\n',+ );+ fs.writeFileSync(+ path.join(dir, 'analysis.json'),+ JSON.stringify({modifiedComponentOwners: owners}),+ );+ 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, GITHUB_STEP_SUMMARY: ''}},+ );+ const outputs = Object.fromEntries(+ fs+ .readFileSync(out, 'utf8')+ .split('\n')+ .filter(Boolean)+ .map(line => line.split('=')),+ );+ expect(outputs.wide_change).toBe('true');+ expect(outputs.has_components).toBe('false');+ expect(outputs.contract_owners.split(',')).toEqual([...owners].sort());+ expect(outputs.contract_folders.split(',')).toContain('core/Spinner');+ expect(outputs.contract_folders.split(',')).toContain('lab/Schedule');+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });});diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 30b462b1c2..a12e059107 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -4156,9 +4156,11 @@ jobs:with:name: pr-analysis- # The same touched components as the touched-components job. More than- # five, or a change to shared styles, is a wide change: no owned spec- # runs, and the comment points to the ci:run-<suite> labels.+ # The same touched components as the touched-components job. Their own+ # specs run even for a wide change (more than five components, or shared+ # styles), and then the specs of the folders that render them, inside+ # this job's budget; what does not fit is reported as not run+ # (spec:AST-030 FR12).- name: Decide the touched componentsid: touchedif: steps.scope.outputs.applies == 'true'@@ -4196,7 +4198,7 @@ jobs:fi- name: Skip when no contract applies- if: steps.scope.outputs.applies == 'true' && steps.touched.outputs.has_components != 'true' && steps.specs.outputs.has_specs != 'true'+ if: steps.scope.outputs.applies == 'true' && steps.touched.outputs.contract_owners == '' && steps.specs.outputs.has_specs != 'true'env:WIDE: ${{ steps.touched.outputs.wide_change }}COUNT: ${{ steps.touched.outputs.component_count }}@@ -4212,7 +4214,7 @@ jobs:# does not have, and those specs fail. Merge-level interactions are the# job of the post-merge and release checks.- name: Check out the head that built the Storybook- if: steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'+ if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'uses: actions/checkout@v7with:ref: ${{ github.event.pull_request.head.sha || github.sha }}@@ -4221,27 +4223,27 @@ jobs:# The head's specs run in this lane's environment, which comes from the# merge commit. A head older than that environment stops here.- name: Require this lane's environment in the branch- if: steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'+ if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'run: >-node "$RUNNER_TEMP/lane-environment/.github/scripts/lane-environment.mjs" check --lane a11y-contracts--workflow "$RUNNER_TEMP/lane-environment/.github/lane-environments.json"--head .github/lane-environments.json- name: Setup Node and pnpm- if: steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'+ if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'uses: ./.github/actions/setupwith:install: 'false'- name: Download Storybook artifact- if: steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'+ if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'uses: actions/download-artifact@v8with:name: storybook-${{ needs.build-storybook.outputs.short_hash }}path: apps/storybook/dist- name: Install Playwright- if: steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'+ if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'run: pnpm install --frozen-lockfile && npx playwright install chromium# The runner and the routing lines come from the merge commit, so an@@ -4251,7 +4253,7 @@ jobs:# that does not fit the budget is not run and does not fail the job.- name: Run the touched components' accessibility contractsid: contracts- if: steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'+ if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'# The runner stops at eight minutes; this bounds a hung browser and# the spec listing inside the job's 15 minutes.timeout-minutes: 10@@ -4260,13 +4262,14 @@ jobs:WORKFLOW_SHA: ${{ github.sha }}SPECS_PATH: ${{ steps.specs.outputs.path }}FILES_PATH: ${{ steps.scope.outputs.changed_files_path }}- OWNERS: ${{ steps.touched.outputs.has_components == 'true' && steps.touched.outputs.a11y_owners || '' }}+ OWNERS: ${{ steps.touched.outputs.contract_owners }}+ FOLDERS: ${{ steps.touched.outputs.contract_folders }}A11Y_CONTRACT_WORKERS: 4run: |runner="$RUNNER_TEMP/a11y-pr-contracts.mjs"git cat-file -e "$WORKFLOW_SHA^{commit}" 2>/dev/null || git fetch --quiet --no-tags --depth=1 origin "$WORKFLOW_SHA"git show "$WORKFLOW_SHA:.github/scripts/a11y-pr-contracts.mjs" > "$runner"- node "$runner" --changed-only "$SPECS_PATH" --changed-files "$FILES_PATH" --owned-by "$OWNERS"+ node "$runner" --changed-only "$SPECS_PATH" --changed-files "$FILES_PATH" --owned-by "$OWNERS" --dependents-of "$FOLDERS"- name: Upload contract evidenceif: always() && (steps.contracts.outcome == 'success' || steps.contracts.outcome == 'failure')diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex 78745c20b4..e784680ff1 100644--- a/docs/specs/AST-030/spec.md+++ b/docs/specs/AST-030/spec.md@@ -243,12 +243,13 @@ they are separately named.needs only the pull request's Storybook build. First it runs the browseraccessibility spec files the change adds or modifies, at most four, in pathorder, routed by their own `@pr-a11y` lines read from the merge commit; a- changed `audit` spec waits for its component-audit pull request. Then, unless- the change is wide, it runs the `scoped` and `release-only` spec files that+ changed `audit` spec waits for its component-audit pull request. Then, a+ wide change included, it runs the `scoped` and `release-only` spec files thateach touched component owns, in path order, found by the same `@pr-a11y`- scope and spec-location mapping the labelled run uses. It runs no spec of- another component or of a reverse dependent, and no unchanged `audit` or- `always` spec. The contract job runs in parallel with the unit-test jobs and+ scope and spec-location mapping the labelled run uses. Then, in the time+ left and for at most one minute of it, it runs the `scoped` and+ `release-only` spec files of the component folders that render a touched+ component through their source value imports, nearest first. It runs no unchanged `audit` or `always` spec. The contract job runs in parallel with the unit-test jobs andMUST NOT become the pull request's critical path: it starts after theStorybook build and MUST finish before the slowest unit-test job, so thetime until the required `test` join reports does not grow. It stops after@@ -317,9 +318,10 @@ they are separately named.a readable build the audits run in full. PR accessibility, when it runs, staysscoped to changed components (FR12). Without a label, the defaulttouched-components check audits only the touched components, and the- contract job runs only the browser accessibility spec files the change adds- or modifies and those the touched components own; neither widens to reverse- dependents, shared modules or other components (FR12). Shared infrastructure runs the full suite of the owners the+ contract job runs the browser accessibility spec files the change adds or+ modifies, those the touched components own, and, for at most one minute of the time left, those of the component folders that render a touched+ component (FR12, DEC-23); neither+ widens to shared modules or to a full suite. Shared infrastructure runs the full suite of the owners thepull request runs (visual, accessibility and RTL only with their `ci:run-*`labels, FR12): rootdependency manifests and lockfile, root configuration, a package's manifest,@@ -626,8 +628,8 @@ The nightly perf lane is the one scheduled measurement outside them (FR18).| 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; one that adds a story to an untouched component's story file beside a touched component | 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 |+| 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; one that adds a story to an untouched component's story file beside a touched component | a pull request that adds a browser accessibility spec that fails is not caught on that pull request, a spec of a component that is neither changed, touched nor rendering a touched component runs in the contract job, or an unchanged `audit` spec does, 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 wide change touching Spinner (its own specs run); the folders that render a touched component, nearest first, type-only imports left out, within a one-minute share, and one that does not fit (reported as not run) | 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 touched component's own spec does not run on a wide change, or a rendering folder's spec runs before an owned one || 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 |@@ -1109,16 +1111,42 @@ merge and no new required name appears.The result reports what happened. A file that the budget or a limit leaves outis "not run" in the check's summary and annotations, with the label that runs-it, and is never split; it never reads as a pass and never fails the join. Wide changes (more than five touched components, or-shared styles), shared modules and reverse dependents keep their scope, `audit`-bindings still first run on their audit pull request, and the release check-still runs every contract.+it, and is never split; it never reads as a pass and never fails the join. Shared modules keep their scope (DEC-23 covers wide changes and the folders+that render a touched component), `audit` bindings+still first run on their audit pull request, and the release check still runs+every contract.Rejected: an advisory result (a red advisory check does not stop a merge whenthe required checks are green, so it would not have stopped the Switch change);release-check-only owned contracts (each miss holds a release until afix-forward lands).+### DEC-23 — The contract job also runs for a wide change, and for the folders that render a touched component++**Reference:** `spec:AST-030/DEC-23`+**Decider:** chief of staff with the release owner, `2026-11-05`++A wide refactor that changed Spinner's behavior (its role and its shared+announcement, across eight components) merged without Spinner's own motion+contract running: a wide change ran only the spec files it edited. A consumer's+contract that rendered the changed Spinner did not run either. Main's release+check found both failures, and the release waited a day for fix-forwards.++The decider chose, for the contract job only, to run each touched component's+own `scoped` and `release-only` contracts for a wide change too, and then, in+the time left, those of the component folders that render a touched component+through their source value imports, nearest first, for at most one minute.+The job keeps its eight-minute budget, so a wide change cannot make it slower+or the critical path; each file that does not fit is reported as not run with+the label that runs it. The one-minute share holds the added runner time to about 360 minutes a day: the owned contracts are the proven catch, and the+rendering folders' share widens only if it catches failures the owned+contracts miss. The default touched-components check keeps its wide-change skip, and+unchanged `audit` and `always` specs still do not run on a pull request.++Rejected: dropping the five-component limit for every audit (the visual,+accessibility and RTL audits of a wide change do not fit the default check's+time).+## Open questionsNone.