An open source design system that's fully customizable and agent ready
TypeScript
ci: a new Lab component's own routes, discovery entry and story keep it Lab-only (component in its own folder) (#9785)
Cindy Zhang9f85c3c0d7e7
diff --git a/.github/actions/test-scope/action.yml b/.github/actions/test-scope/action.ymlindex e38cc692bf..a9d5b434c5 100644--- a/.github/actions/test-scope/action.yml+++ b/.github/actions/test-scope/action.yml@@ -206,7 +206,10 @@ runs:'.github/scripts/knowledge-paths.cjs','scripts/component-packages.cjs',...(audit ? ['.github/scripts/component-audit-scope.cjs'] : []),+ // Data, not code: the Lab entry check reads the base's copy.+ 'packages/cli/assets/discover/official-packages.json',];+ const optionalPolicy = new Set(['packages/cli/assets/discover/official-packages.json']);const {repository} = await github.graphql(`query($owner: String!, $repo: String!, ${policy.map((_, i) => `$f${i}: String!`).join(', ')}) {repository(owner: $owner, name: $repo) {@@ -217,6 +220,8 @@ runs:);for (const [i, file] of policy.entries()) {const blob = repository?.[`f${i}`];+ // A missing data file only keeps the change out of the Lab-only lane.+ if (optionalPolicy.has(file) && (typeof blob?.text !== 'string' || blob.isTruncated)) continue;if (typeof blob?.text !== 'string' || blob.isTruncated) throw new Error(`the base has no readable ${file}`);fs.mkdirSync(path.join(root, path.dirname(file)), {recursive: true});fs.writeFileSync(path.join(root, file), blob.text);@@ -235,8 +240,21 @@ runs:.join('\n');const outputFile = path.join(root, 'classification');fs.writeFileSync(outputFile, '');+ // GitHub's patch text for the Lab entry files, handed over as data:+ // the classifier reads it and never runs it. GitHub leaves out the+ // patch of a large diff; such a file then keeps full CI.+ const LAB_ENTRY = /^(internal\/shadcn-registry\/routes\.lock\.json|packages\/cli\/assets\/discover\/official-packages\.json|apps\/storybook\/stories\/[A-Z][A-Za-z0-9]*\.stories\.tsx)$/;+ const patchesFile = path.join(root, 'lab-entry-patches.json');+ fs.writeFileSync(patchesFile, JSON.stringify(Object.fromEntries(+ files.filter(f => LAB_ENTRY.test(f.filename)).map(f => [f.filename, typeof f.patch === 'string' ? f.patch : null]),+ )));try {- execFileSync('node', [path.join(root, '.github/scripts/change-scope.cjs'), '--github-output'], {+ execFileSync('node', [+ path.join(root, '.github/scripts/change-scope.cjs'),+ '--github-output',+ '--patches', patchesFile,+ '--official-packages-base', path.join(root, 'packages/cli/assets/discover/official-packages.json'),+ ], {input: `${nameStatus}\n`,env: {...process.env, GITHUB_OUTPUT: outputFile},stdio: ['pipe', 'inherit', 'inherit'],diff --git a/.github/scripts/change-scope.cjs b/.github/scripts/change-scope.cjsindex e3f302320c..9ed398e98a 100644--- a/.github/scripts/change-scope.cjs+++ b/.github/scripts/change-scope.cjs@@ -11,7 +11,9 @@ const {} = require('./knowledge-paths.cjs');/**- * Classifies changed paths without reading PR-controlled content.+ * Classifies changed paths. It reads no pull-request content as code: the+ * only content it reads is GitHub's patch text for a Lab component's three+ * entry files, as data (spec:AST-030 FR26).** A spec-only PR may change only spec records. Templates, schemas, indexes,* architecture, guidance, audits, workflows, and code deliberately do not@@ -31,6 +33,152 @@ const CHANGESET_PATTERN = /^\.changeset\/(?!README\.md$)[^/]+\.md$/;// runs the Lab tests and the Storybook build (spec:AST-030 FR26).const LAB_ROOT = 'packages/lab/';+// A new Lab component also adds its routes, its CLI discovery entry and its+// Storybook story. These three files still count toward a Lab-only change when+// their diff names only Lab components the change itself carries. The diff is+// read as data (GitHub's patch text, never run); a missing patch, or any line+// the checks do not recognize, keeps the change out of the Lab-only lane.+const ROUTES_LOCK = 'internal/shadcn-registry/routes.lock.json';+const OFFICIAL_PACKAGES = 'packages/cli/assets/discover/official-packages.json';+const LAB_STORY =+ /^apps\/storybook\/stories\/([A-Z][A-Za-z0-9]*)\.stories\.tsx$/;+const LAB_COMPONENT_DIR = /^packages\/lab\/src\/([A-Z][A-Za-z0-9]*)\//;++// The registry's route slug for a component name. It mirrors+// slugifyRegistryName in apps/docsite/src/lib/shadcnRegistry.mjs (a test pins+// the two equal): the trusted classifier loads no docsite module.+function labRouteSlug(name) {+ return String(name)+ .replace(/([a-z0-9])([A-Z])/g, '$1-$2')+ .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')+ .replace(/[^a-zA-Z0-9]+/g, '-')+ .replace(/^-+|-+$/g, '')+ .toLowerCase();+}++// The changed lines of a unified diff, without the file headers.+function changedLines(patch) {+ return patch+ .split('\n')+ .filter(line => /^[+-]/.test(line) && !/^(\+\+\+|---) /.test(line))+ .map(line => ({+ sign: line[0],+ text: line.slice(1).trim().replace(/,$/, ''),+ }));+}++function routesLockNamesLabOnly(patch, slugs) {+ const ownSlug = value =>+ [...slugs].some(+ slug =>+ value === `components/lab/${slug}` ||+ value.startsWith(`examples/${slug}/`) ||+ value.startsWith(`showcases/${slug}/`),+ );+ const ownName = value =>+ [...slugs].some(+ slug =>+ value === `component-lab-${slug}` ||+ value.startsWith(`example-${slug}-`) ||+ value.startsWith(`showcase-${slug}-`),+ );+ const lines = changedLines(patch);+ return (+ lines.length > 0 &&+ lines.every(({text}) => {+ if (['{', '}', ']', '"aliases": []', '"aliases": ['].includes(text))+ return true;+ const name = /^"name": "([^"]+)"$/.exec(text);+ if (name) return ownName(name[1]);+ const route = /^"path": "([^"]+)"$/.exec(text);+ if (route) return ownSlug(route[1]);+ const alias = /^"([^"]+)"$/.exec(text);+ return (+ alias != null &&+ /^components\/lab\//.test(alias[1]) &&+ ownSlug(alias[1])+ );+ })+ );+}++// The Lab package's line range in the base's official-packages.json.+function labPackageLines(baseText) {+ const lines = baseText.split('\n');+ const start = lines.findIndex(line =>+ line.includes('"package": "@astryxdesign/lab"'),+ );+ if (start === -1) return null;+ const next = lines.findIndex(+ (line, index) => index > start && line.includes('"package": "'),+ );+ return {first: start + 1, last: next === -1 ? lines.length : next};+}++function officialPackagesNamesLabOnly(patch, names, baseText) {+ if (typeof baseText !== 'string') return false;+ const range = labPackageLines(baseText);+ if (range == null) return false;+ const hunks = [+ ...patch.matchAll(/^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/gm),+ ];+ if (hunks.length === 0) return false;+ // Every hunk edits inside the Lab package's entry of the base file.+ const inLab = hunks.every(([, start, count = '1']) => {+ const first = Number(start);+ const last = first + Math.max(Number(count), 1) - 1;+ return first > range.first && last < range.last;+ });+ const lines = changedLines(patch);+ return (+ inLab &&+ lines.length > 0 &&+ lines.every(({text}) => {+ if (['{', '}', '"kind": "component"'].includes(text)) return true;+ const name = /^"name": "([^"]+)"$/.exec(text);+ return name != null && names.has(name[1]);+ })+ );+}++function storyImportsLab(patch) {+ const added = patch+ .split('\n')+ .filter(line => line.startsWith('+') && !line.startsWith('+++ '))+ .map(line => line.slice(1))+ .join('\n');+ return /from '@astryxdesign\/lab(?:\/[^']*)?';/.test(added);+}++/**+ * Whether a Lab entry file's change belongs to the Lab components this change+ * carries (spec:AST-030 FR26). `names` are the Lab component folders the change+ * touches; `patches` maps a path to GitHub's patch text; `officialPackagesBase`+ * is the base's official-packages.json.+ */+function isLabEntryChange(change, {names, patches, officialPackagesBase}) {+ const patch = patches?.[change.filename];+ if (+ typeof patch !== 'string' ||+ patch === '' ||+ change.previous_filename != null+ )+ return false;+ const slugs = new Set([...names].map(labRouteSlug));+ if (change.filename === ROUTES_LOCK)+ return routesLockNamesLabOnly(patch, slugs);+ if (change.filename === OFFICIAL_PACKAGES)+ return officialPackagesNamesLabOnly(patch, names, officialPackagesBase);+ const story = LAB_STORY.exec(change.filename);+ // Only a new story: its whole text is in the patch.+ return (+ story != null &&+ change.status === 'A' &&+ names.has(story[1]) &&+ storyImportsLab(patch)+ );+}+const SURFACES = Object.freeze({KNOWLEDGE: 'knowledge',DOCSITE: 'docsite',@@ -175,7 +323,10 @@ function normalizeChange(change) {};}-function classifyChanges(changes, {expectedCount} = {}) {+function classifyChanges(+ changes,+ {expectedCount, patches = null, officialPackagesBase = null} = {},+) {const normalized = changes.map(normalizeChange).filter(change => change.filename);@@ -239,16 +390,42 @@ function classifyChanges(changes, {expectedCount} = {}) {const docsiteOnly = exactSurface(SURFACES.DOCSITE);const toolingOnly = exactSurface(SURFACES.NODE_TOOLING);// Every changed path is in the Lab package, besides Changesets, which no- // test or build reads (spec:AST-030 FR26).+ // test or build reads, and the Lab entry files of the Lab components the+ // change carries (spec:AST-030 FR26).+ const labNames = new Set(+ allPaths.flatMap(filePath => {+ const match = LAB_COMPONENT_DIR.exec(filePath);+ return match ? [match[1]] : [];+ }),+ );+ const labEntries = new Set(+ normalized+ .filter(change =>+ isLabEntryChange(change, {+ names: labNames,+ patches,+ officialPackagesBase,+ }),+ )+ .map(change => change.filename),+ );const labOnly =complete &&allPaths.some(filePath => filePath.startsWith(LAB_ROOT)) &&allPaths.every(filePath =>- filePath.startsWith(LAB_ROOT) || CHANGESET_PATTERN.test(filePath),+ filePath.startsWith(LAB_ROOT) ||+ CHANGESET_PATTERN.test(filePath) ||+ labEntries.has(filePath),+ );+ // An incomplete list, or any shared infrastructure, runs everything. A Lab+ // entry file of a Lab-only change is not shared infrastructure for it.+ const fullSuite =+ !complete ||+ allPaths.some(+ filePath =>+ isSharedInfraPath(filePath) && !(labOnly && labEntries.has(filePath)),);- // An incomplete list, or any shared infrastructure, runs everything.- const fullSuite = !complete || allPaths.some(isSharedInfraPath);return {specOnly,toolingOnly,@@ -324,7 +501,23 @@ if (require.main === module) {.filter(Boolean);process.stdout.write(`${JSON.stringify(classifyPaths(paths))}\n`);} else {- const result = classifyChanges(parseNameStatus(fs.readFileSync(0, 'utf8')));+ // `--patches <file>`: GitHub's patch text per path, as JSON, for the Lab+ // entry files. `--official-packages-base <file>`: the base's copy.+ const flag = name => {+ const index = process.argv.indexOf(name);+ return index === -1 ? null : process.argv[index + 1];+ };+ const readJson = file =>+ file ? JSON.parse(fs.readFileSync(file, 'utf8')) : null;+ const readText = file =>+ file && fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;+ const result = classifyChanges(+ parseNameStatus(fs.readFileSync(0, 'utf8')),+ {+ patches: readJson(flag('--patches')),+ officialPackagesBase: readText(flag('--official-packages-base')),+ },+ );if (result.specChangesetConflict) {console.error('Pure spec-record changes must not add a Changeset; they do not release packages.',@@ -346,6 +539,8 @@ if (require.main === module) {module.exports = {LAB_ROOT,+ OFFICIAL_PACKAGES,+ ROUTES_LOCK,NODE_TOOLING_PATHS,SURFACES,classifyChanges,@@ -354,6 +549,8 @@ module.exports = {isNodeToolingPath,isPackageReleasePath,isSharedInfraPath,+ isLabEntryChange,isSpecRecordPath,+ labRouteSlug,parseNameStatus,};diff --git a/.github/scripts/change-scope.test.mjs b/.github/scripts/change-scope.test.mjsindex d1cb036530..09016f4c3b 100644--- a/.github/scripts/change-scope.test.mjs+++ b/.github/scripts/change-scope.test.mjs@@ -594,3 +594,265 @@ describe('Lab-only change scope (spec:AST-030 FR26)', () => {expect(classifyChanges([]).labOnly).toBe(false);});});++describe('Lab entry files (spec:AST-030 FR26)', () => {+ const {+ isLabEntryChange,+ labRouteSlug,+ ROUTES_LOCK,+ OFFICIAL_PACKAGES,+ } = require('./change-scope.cjs');+ const names = new Set(['CommentPin']);+ const route = lines => `@@ -556,6 +556,11 @@\n${lines.join('\n')}`;+ const ownRoute = [+ '+ {',+ '+ "name": "component-lab-comment-pin",',+ '+ "path": "components/lab/comment-pin",',+ '+ "aliases": []',+ '+ },',+ ];+ const routes = patch => ({+ change: {filename: ROUTES_LOCK, status: 'M'},+ patches: {[ROUTES_LOCK]: patch},+ });+ const entry = ({change, patches}, base = null) =>+ isLabEntryChange(change, {names, patches, officialPackagesBase: base});++ it('accepts a carried component route', () => {+ expect(entry(routes(route(ownRoute)))).toBe(true);+ });++ it('refuses a renamed route lock, even with the right lines', () => {+ expect(+ entry({+ change: {+ filename: ROUTES_LOCK,+ previous_filename: 'packages/lab/routes.lock.json',+ status: 'R100',+ },+ patches: {[ROUTES_LOCK]: route(ownRoute)},+ }),+ ).toBe(false);+ });++ it("refuses a route item named for another component, though its path is the carried one's", () => {+ const lines = ownRoute.map(line =>+ line.replace('component-lab-comment-pin', 'component-lab-drawer'),+ );+ expect(entry(routes(route(lines)))).toBe(false);+ });++ it("refuses a route path for another component, though its name is the carried one's", () => {+ const lines = ownRoute.map(line =>+ line.replace('components/lab/comment-pin', 'components/lab/drawer'),+ );+ expect(entry(routes(route(lines)))).toBe(false);+ });++ it('refuses an example or showcase name for a component the change does not carry', () => {+ for (const name of ['example-button-basic', 'showcase-button-tour']) {+ expect(entry(routes(route([`+ "name": "${name}",`]))), name).toBe(+ false,+ );+ }+ });++ it('matches a route name and path exactly, not by prefix', () => {+ const swap = (from, to) => ownRoute.map(line => line.replace(from, to));+ expect(+ entry(+ routes(+ route(+ swap('component-lab-comment-pin"', 'component-lab-comment-pin-x"'),+ ),+ ),+ ),+ ).toBe(false);+ expect(+ entry(+ routes(+ route(+ swap('components/lab/comment-pin"', 'components/lab/comment-pinx"'),+ ),+ ),+ ),+ ).toBe(false);+ });++ it("matches an example or showcase path only under the component's own folder", () => {+ for (const prefix of ['examples', 'showcases']) {+ const item = [+ '+ {',+ `+ "name": "${prefix === 'examples' ? 'example' : 'showcase'}-comment-pin-basic",`,+ `+ "path": "${prefix}/comment-pinx/basic",`,+ '+ "aliases": []',+ '+ },',+ ];+ expect(entry(routes(route(item))), prefix).toBe(false);+ }+ });++ it('refuses an alias outside the Lab components, and a Lab alias for another component', () => {+ const withAlias = alias => [+ '+ {',+ '+ "name": "component-lab-comment-pin",',+ '+ "path": "components/lab/comment-pin",',+ '+ "aliases": [',+ `+ "${alias}"`,+ '+ ]',+ '+ },',+ ];+ expect(entry(routes(route(withAlias('components/lab/comment-pin'))))).toBe(+ true,+ );+ expect(entry(routes(route(withAlias('components/comment-pin'))))).toBe(+ false,+ );+ expect(entry(routes(route(withAlias('components/lab/drawer'))))).toBe(+ false,+ );+ // A new component has no old route to alias, so only a Lab path counts,+ // even one under the component's own example prefix.+ expect(+ entry(routes(route(withAlias('examples/comment-pin/old-name')))),+ ).toBe(false);+ });++ const base = [+ '{',+ ' "packages": [',+ ' {',+ ' "package": "@astryxdesign/charts",',+ ' "contributions": [',+ ' {',+ ' "kind": "component",',+ ' "name": "Chart"',+ ' }',+ ' ]',+ ' },',+ ' {',+ ' "package": "@astryxdesign/lab",',+ ' "contributions": [',+ ' {',+ ' "kind": "component",',+ ' "name": "ChartArea"',+ ' }',+ ' ]',+ ' }',+ ' ]',+ '}',+ ].join('\n');+ const discovery = (added, at = 15) => ({+ change: {filename: OFFICIAL_PACKAGES, status: 'M'},+ patches: {+ [OFFICIAL_PACKAGES]: `@@ -${at},2 +${at},${2 + added.length} @@\n${added.join('\n')}`,+ },+ });+ const ownEntry = [+ '+ {',+ '+ "kind": "component",',+ '+ "name": "CommentPin"',+ '+ },',+ ];++ it("accepts a carried component's entry inside Lab's part of the base", () => {+ expect(entry(discovery(ownEntry), base)).toBe(true);+ });++ it('refuses an entry for a component the change does not carry', () => {+ expect(+ entry(+ discovery(ownEntry.map(line => line.replace('CommentPin', 'Drawer'))),+ base,+ ),+ ).toBe(false);+ });++ it("refuses an edit in the package that follows Lab's part of the base", () => {+ const baseWithNext = base.replace(+ ' }\n ]\n}',+ [+ ' },',+ ' {',+ ' "package": "@astryxdesign/richtext",',+ ' "contributions": [',+ ' {',+ ' "kind": "component",',+ ' "name": "RichText"',+ ' }',+ ' ]',+ ' }',+ ' ]',+ '}',+ ].join('\n'),+ );+ expect(baseWithNext.split('\n')[21]).toContain('@astryxdesign/richtext');+ // Inside Lab's part: accepted; inside the next package's part: refused.+ expect(entry(discovery(ownEntry), baseWithNext)).toBe(true);+ expect(entry(discovery(ownEntry, 25), baseWithNext)).toBe(false);+ // A hunk that starts in Lab's last lines but runs into the next package.+ const crossing = {+ change: {filename: OFFICIAL_PACKAGES, status: 'M'},+ patches: {+ [OFFICIAL_PACKAGES]: `@@ -19,4 +19,8 @@\n${ownEntry.join('\n')}`,+ },+ };+ expect(entry(crossing, baseWithNext)).toBe(false);+ });++ it("refuses the discovery list when the base's copy is missing", () => {+ expect(entry(discovery(ownEntry), null)).toBe(false);+ });++ it('refuses a line that is not a component entry', () => {+ expect(+ entry(+ discovery(ownEntry.map(line => line.replace('"component"', '"hook"'))),+ base,+ ),+ ).toBe(false);+ });++ it("refuses an edit outside Lab's part of the base", () => {+ expect(entry(discovery(ownEntry, 6), base)).toBe(false);+ });++ it('derives the same route slug as the registry for every Lab folder', async () => {+ const fs = await import('node:fs');+ const path = await import('node:path');+ const {slugifyRegistryName} =+ await import('../../apps/docsite/src/lib/shadcnRegistry.mjs');+ const root = path.resolve(import.meta.dirname, '../..');+ const folders = fs+ .readdirSync(path.join(root, 'packages/lab/src'), {withFileTypes: true})+ .filter(entry => entry.isDirectory() && /^[A-Z]/.test(entry.name))+ .map(entry => entry.name);+ expect(folders.length).toBeGreaterThan(0);+ for (const name of [...folders, 'SVGIcon', 'ThreeDBar', 'CommentPin']) {+ expect(labRouteSlug(name), name).toBe(slugifyRegistryName(name));+ }+ expect(labRouteSlug('SVGIcon')).toBe('svg-icon');+ });+});++describe('Lab component folders (spec:AST-030 FR26)', () => {+ it('reads a carried component only from a component folder, not a shared one', () => {+ const {ROUTES_LOCK} = require('./change-scope.cjs');+ const routePatch = [+ '@@ -556,6 +556,11 @@',+ '+ {',+ '+ "name": "component-lab-tests",',+ '+ "path": "components/lab/tests",',+ '+ "aliases": []',+ '+ },',+ ].join('\n');+ const result = classifyChanges(+ [+ {filename: 'packages/lab/src/__tests__/helpers.ts', status: 'M'},+ {filename: ROUTES_LOCK, status: 'M'},+ ],+ {patches: {[ROUTES_LOCK]: routePatch}},+ );+ expect(result.labOnly).toBe(false);+ });+});diff --git a/.github/scripts/ci-head-checkout-scripts.test.mjs b/.github/scripts/ci-head-checkout-scripts.test.mjsindex add1c105d0..84b1af5775 100644--- a/.github/scripts/ci-head-checkout-scripts.test.mjs+++ b/.github/scripts/ci-head-checkout-scripts.test.mjs@@ -51,6 +51,8 @@ const ESTABLISHED = new Set(['scripts/verify-exports.mjs',// Builds the packages and Storybook: a head without it has nothing to test.'.github/scripts/build-packages-and-storybook.mjs',+ // The docsite's data generator, on main since the docsite began.+ 'apps/docsite/scripts/generate-data.mjs',]);/**@@ -66,7 +68,7 @@ const NOT_ON_STALE_BRANCHES = new Set([]);const SCRIPT =- /(?:\.github\/scripts|scripts|apps\/storybook\/rtl-audit)\/[A-Za-z0-9_./-]+\.(?:mjs|cjs|js)/g;+ /(?:\.github\/scripts|apps\/docsite\/scripts|scripts|apps\/storybook\/rtl-audit)\/[A-Za-z0-9_./-]+\.(?:mjs|cjs|js)/g;function checksOutHead(job) {return (job.steps ?? []).some(diff --git a/.github/scripts/ci-lab-only-routing.test.mjs b/.github/scripts/ci-lab-only-routing.test.mjsindex abdece37b0..9623d9711b 100644--- a/.github/scripts/ci-lab-only-routing.test.mjs+++ b/.github/scripts/ci-lab-only-routing.test.mjs@@ -108,7 +108,13 @@ describe('Lab-only lane (spec:AST-030 FR26)', () => {it('runs the Node lane as any scoped pull request does, source-reading guards included', () => {// A Lab file that broke a guard would turn every later pull request red.- for (const s of steps('test-node')) {+ // The one Lab-only step adds a check; none skips one.+ const official = step('test-node', 'Lab-only: CLI official-packages check');+ expect(official.if).toBe(`matrix.shard == 1 && ${LAB_TRUE}`);+ expect(official.run).toBe(+ 'pnpm exec vitest run scripts/check-cli-official-packages.test.mjs --maxWorkers=1',+ );+ for (const s of steps('test-node').filter(s => s !== official)) {expect(String(s.if ?? ''), s.name ?? s.uses ?? s.run).not.toContain('lab_only',);@@ -185,7 +191,29 @@ describe('Lab-only lane (spec:AST-030 FR26)', () => {expect(all.indexOf(typecheck)).toBeGreaterThan(all.findIndex(s => s.name === 'Build packages and Storybook'),);- for (const s of all.filter(s => s !== typecheck)) {+ // A Lab-only change that carries a Lab component's routes checks them+ // against the registry the docsite builds from these packages.+ const routeLock = step(+ 'build-storybook',+ 'Lab-only: check the ShadCN route lock',+ );+ expect(routeLock.if).toBe(+ `steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && ${LAB_TRUE}`,+ );+ // Compared with the merge base, not the head's parent commit.+ expect(routeLock.env.MERGE_BASE).toBe(+ '${{ steps.merge-base.outputs.sha }}',+ );+ expect(routeLock.env.DOCSITE_TARGET).toBe('canary');+ expect(routeLock.run).toContain(+ 'git diff --quiet "$MERGE_BASE" HEAD -- internal/shadcn-registry/routes.lock.json',+ );+ expect(routeLock.run).not.toContain('HEAD^1');+ expect(routeLock.run).toContain(+ 'node apps/docsite/scripts/generate-data.mjs',+ );+ expect(all.indexOf(routeLock)).toBeGreaterThan(all.indexOf(typecheck));+ for (const s of all.filter(s => s !== typecheck && s !== routeLock)) {expect(String(s.if ?? ''), s.name ?? s.uses ?? s.run).not.toContain('lab_only',);diff --git a/.github/scripts/test-scope-action.test.mjs b/.github/scripts/test-scope-action.test.mjsindex 61aaf887fc..615a27296a 100644--- a/.github/scripts/test-scope-action.test.mjs+++ b/.github/scripts/test-scope-action.test.mjs@@ -41,6 +41,7 @@ const CLASSIFIER_FILES = new Set(['scripts/component-packages.cjs',]);const AUDIT_FILE = '.github/scripts/component-audit-scope.cjs';+const OFFICIAL_PACKAGES = 'packages/cli/assets/discover/official-packages.json';function pullRequestContext(baseRef = 'main') {return {@@ -101,7 +102,10 @@ async function decide({if (!/^f\d+$/.test(key)) continue;const [ref, file] = [expression.slice(0, 40), expression.slice(41)];contentCalls.push({file, ref});- const known = CLASSIFIER_FILES.has(file) || file === AUDIT_FILE;+ const known =+ CLASSIFIER_FILES.has(file) ||+ file === AUDIT_FILE ||+ file === OFFICIAL_PACKAGES;const text = ref === BASE_SHA && known ? policyText(file) : null;repository[key] =text == null ? null : {text, isTruncated: truncated.includes(file)};@@ -241,6 +245,7 @@ describe('per-job scope step', () => {f1: `${BASE_SHA}:.github/scripts/knowledge-paths.cjs`,f2: `${BASE_SHA}:scripts/component-packages.cjs`,f3: `${BASE_SHA}:${AUDIT_FILE}`,+ f4: `${BASE_SHA}:${OFFICIAL_PACKAGES}`,});expect(contentCalls.filter(call => call.rest)).toEqual([]);});@@ -599,6 +604,165 @@ describe('per-job scope step', () => {});});+describe('a new Lab component (spec:AST-030 FR26)', () => {+ const component = [+ {filename: 'packages/lab/src/CommentPin/CommentPin.tsx', status: 'added'},+ {filename: 'packages/lab/src/CommentPin/index.ts', status: 'added'},+ {filename: 'packages/lab/src/index.ts', status: 'modified'},+ ];+ const routes = {+ filename: 'internal/shadcn-registry/routes.lock.json',+ status: 'modified',+ patch: [+ '@@ -556,6 +556,11 @@',+ ' "path": "components/lab/code-editor",',+ ' "aliases": []',+ ' },',+ '+ {',+ '+ "name": "component-lab-comment-pin",',+ '+ "path": "components/lab/comment-pin",',+ '+ "aliases": []',+ '+ },',+ '@@ -1885,6 +1890,11 @@',+ '+ {',+ '+ "name": "example-comment-pin-host-owned-placement",',+ '+ "path": "examples/comment-pin/host-owned-placement",',+ '+ "aliases": []',+ '+ },',+ ].join('\n'),+ };+ const labStory = {+ filename: 'apps/storybook/stories/CommentPin.stories.tsx',+ status: 'added',+ patch: [+ '@@ -0,0 +1,3 @@',+ "+import type {Meta} from '@storybook/react';",+ "+import {CommentPin} from '@astryxdesign/lab';",+ "+import {Text} from '@astryxdesign/core/Text';",+ ].join('\n'),+ };+ const officialLines = fs+ .readFileSync(path.join(root, OFFICIAL_PACKAGES), 'utf8')+ .split('\n');+ const labLine =+ officialLines.findIndex(line =>+ line.includes('"package": "@astryxdesign/lab"'),+ ) + 1;+ const official = at => ({+ filename: OFFICIAL_PACKAGES,+ status: 'modified',+ patch: [+ `@@ -${at},3 +${at},7 @@`,+ ` ${officialLines[at - 1]}`,+ '+ {',+ '+ "kind": "component",',+ '+ "name": "CommentPin"',+ '+ },',+ ` ${officialLines[at]}`,+ ` ${officialLines[at + 1]}`,+ ].join('\n'),+ });++ it('stays in the Lab-only lane with its routes, discovery entry and story', async () => {+ const {outputs} = await decide({+ files: [...component, routes, labStory, official(labLine + 6)],+ });+ expect(outputs.lab_only).toBe('true');+ expect(outputs.full_suite).toBe('false');+ });++ it('runs full CI when a core story changes with it', async () => {+ const {outputs} = await decide({+ files: [+ ...component,+ routes,+ labStory,+ {+ filename: 'apps/storybook/stories/Button.stories.tsx',+ status: 'added',+ patch: "@@ -0,0 +1 @@\n+import {Button} from '@astryxdesign/core';",+ },+ ],+ });+ expect(outputs.lab_only).toBe('false');+ });++ it("runs full CI when a route names another component, or the discovery edit is outside Lab's entry", async () => {+ const otherRoute = {+ ...routes,+ patch: routes.patch.replaceAll('comment-pin', 'button'),+ };+ expect(+ (await decide({files: [...component, otherRoute]})).outputs.lab_only,+ ).toBe('false');+ expect(+ (await decide({files: [...component, official(10)]})).outputs.lab_only,+ ).toBe('false');+ });++ it('runs full CI for a changed existing story, even one that imports Lab', async () => {+ const {outputs} = await decide({+ files: [...component, routes, {...labStory, status: 'modified'}],+ });+ expect(outputs.lab_only).toBe('false');+ });++ it('runs full CI for a new Lab story of a component the change does not carry', async () => {+ const {outputs} = await decide({+ files: [+ ...component,+ routes,+ {+ ...labStory,+ filename: 'apps/storybook/stories/Drawer.stories.tsx',+ patch: "@@ -0,0 +1 @@\n+import {Drawer} from '@astryxdesign/lab';",+ },+ ],+ });+ expect(outputs.lab_only).toBe('false');+ });++ it('runs full CI for a renamed entry file', async () => {+ const {outputs} = await decide({+ files: [+ ...component,+ {+ ...labStory,+ status: 'renamed',+ previous_filename: 'apps/storybook/stories/OldPin.stories.tsx',+ },+ ],+ });+ expect(outputs.lab_only).toBe('false');+ });++ it('keeps the full suite for a mixed change that carries Lab routes', async () => {+ const {outputs} = await decide({+ files: [+ ...component,+ routes,+ {filename: 'packages/core/src/Button/Button.tsx', status: 'modified'},+ ],+ });+ expect(outputs.lab_only).toBe('false');+ expect(outputs.full_suite).toBe('true');+ });++ it('runs full CI when GitHub leaves out a patch, or the story does not import Lab', async () => {+ const {patch: _omitted, ...noPatch} = routes;+ expect(+ (await decide({files: [...component, noPatch]})).outputs.lab_only,+ ).toBe('false');+ const coreOnlyStory = {+ ...labStory,+ patch: "@@ -0,0 +1 @@\n+import {Text} from '@astryxdesign/core/Text';",+ };+ expect(+ (await decide({files: [...component, coreOnlyStory]})).outputs.lab_only,+ ).toBe('false');+ });+});+describe('the temporary policy folder', () => {// os.tmpdir() reads TMPDIR on each call, so each case gets its own folder.async function inFreshTemp(run) {diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex c9461df02c..21870e0b0c 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -1003,6 +1003,13 @@ jobs:fiif: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'+ # A Lab-only change may carry a Lab component's CLI discovery entry; the+ # committed list must match its generator (spec:AST-030 FR26).+ - name: 'Lab-only: CLI official-packages check'+ if: matrix.shard == 1 && steps.scope.outputs.lab_only == 'true'+ # One Node-project test file: Vitest finds its project from the path.+ run: pnpm exec vitest run scripts/check-cli-official-packages.test.mjs --maxWorkers=1+# Theme-family compilation is owned by `theme-build`, not Build. Until# that surface has an admitted dedicated lane, broad CI keeps its browser# contract inside the existing Node test owner rather than `test-build`.@@ -1481,6 +1488,21 @@ jobs:if: steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.lab_only == 'true'run: pnpm -F @astryxdesign/lab -F @astryxdesign/storybook typecheck+ # A Lab-only change whose route lock differs from the merge base checks+ # the lock against the registry the docsite builds from these packages+ # (spec:AST-030 FR26). Without a merge base, it checks anyway.+ - name: 'Lab-only: check the ShadCN route lock'+ if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only == 'true'+ env:+ DOCSITE_TARGET: canary+ MERGE_BASE: ${{ steps.merge-base.outputs.sha }}+ run: |+ if [ -n "$MERGE_BASE" ] && git diff --quiet "$MERGE_BASE" HEAD -- internal/shadcn-registry/routes.lock.json 2>/dev/null; then+ echo "The route lock matches the merge base."+ exit 0+ fi+ node apps/docsite/scripts/generate-data.mjs+- name: Verify package exportsif: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'run: node scripts/verify-exports.mjsdiff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex abc2b14483..e84dfbc53c 100644--- a/docs/specs/AST-030/spec.md+++ b/docs/specs/AST-030/spec.md@@ -109,13 +109,17 @@ they are separately named.A category does not earn a specialized lane merely by existing in this table.Until every selected surface has an admitted, complete specialized owner route,that surface set uses the broad check set. `shared-or-unknown` always uses the- broad check set, except a Changeset beside a Lab-only change, which keeps the- Lab-only route (FR26).+ broad check set, except a Changeset or a carried Lab component's entry file+ beside a Lab-only change, which keeps the Lab-only route (FR26).- **FR3 — Classification uses trusted base policy.** Pull-request code MUST NOTchoose its own lane. The workflow MUST load the classifier and every classifierdependency from the trusted base ref, then apply that policy to the merge-base- three-dot path set. Workflow changes use the broad lane unless they are an+ three-dot path set. For a Lab component's entry files (FR26), the trusted+ classifier also reads GitHub's patch text for those three files. It reads+ the text as data, matches each line against fixed patterns and never runs+ it, so a pull request supplies only data that the base policy judges, never+ the policy. Workflow changes use the broad lane unless they are anadmitted tool's non-PR dispatch workflow. Classifier,classifier-dependency, and routing-test changes use the broad lane.- **FR4 — Uncertainty fails closed.** A missing merge base, missing trusted@@ -125,7 +129,8 @@ they are separately named.- **FR5 — Mixed scope keeps every owner.** A change touching multiple classifiedsurfaces MUST run the union of their checks. It MUST NOT run specialized lanesfor untouched surfaces. A set containing `shared-or-unknown` (apart from a- Changeset beside a Lab-only change, FR26), a fail-closed+ Changeset or a carried Lab component's entry file beside a Lab-only change,+ FR26), a fail-closedcondition from FR3–FR4, or any selected surface without a complete admittedspecialized owner route MUST use broad CI. A specification beside runtime codedoes not hide the runtime surface.@@ -319,7 +324,9 @@ they are separately named.build or test configuration and test setup, `internal/` (the test harnessincluded), `theme-build` paths (tokens and themes), Storybook configuration,`node-tooling` paths (FR8 keeps their whole Node project), and every other- `shared-or-unknown` path except Changesets. Every fail-closed+ `shared-or-unknown` path. Changesets are excepted, and so, in a Lab-only+ change, are a carried Lab component's entry files (FR26), the route lock+ under `internal/` included. Every fail-closedcondition of FR3–FR4 also runs the full suite. `main`, release branches,merge-group entries and `release-check` dispatches always run the full suite,and release checks keep FR12's full scope.@@ -521,23 +528,37 @@ they are separately named.- **FR26 — A Lab-only pull request runs the Lab tests and the Storybookbuild.** A pull request whose every changed path is in the Lab package- (`packages/lab/`), beside any Changesets, runs the Lab package's tests on the+ (`packages/lab/`), beside any Changesets and the entry files of the Lab+ components the change itself carries, runs the Lab package's tests on theUI legs, the source-reading guard tests on the UI and Node legs as any scopedpull request runs them (FR13), the Storybook build, a typecheck of the Lab package and theStorybook stories against the packages that build made, and therepository-wide guards: full lint and the UI lane's copyright,package-exports, CLI API type, token-docs, Lab readiness and knowledge-schema- checks. It runs no docsite build or tests, no full typecheck, no+ checks. It runs no docsite build or tests (beyond the route-lock check+ below), no full typecheck, noBuild-package tests, no interaction proofs, no touched-components check,and no visual, accessibility or RTL suite unless a maintainer's label runsone (FR12), and an agent lane's push defersnothing (FR20). The required `build`, `test` and `docsite-test` contextsreport success with the notice "Lab-only: Lab tests + Storybook build",- never a skip. A change to any other path is mixed and runs CI as for any+ never a skip. A Lab component's entry files are its routes in+ `internal/shadcn-registry/routes.lock.json`, its entry in the Lab package's+ part of `packages/cli/assets/discover/official-packages.json`, and a new+ story `apps/storybook/stories/<Name>.stories.tsx` that imports from+ `@astryxdesign/lab`, for a Lab component named for its own folder, which+ the change touches. A component in a family folder keeps the full suite.+ The classifier reads those files' diffs as data and never runs them; a diff+ it cannot read, or a line naming anything else, makes the change mixed. A+ Lab-only change also runs the CLI official-packages check on the first Node+ leg, and, when its route lock differs from the merge base (or the merge base+ is unknown), the route-lock check: the docsite's data generation at the+ canary target, against the packages the Storybook build made. One that adds+ or changes a story also builds Storybook, which the lane always does. A change to any other path is mixed and runs CI as for anypull request: Core (its internal modules included), the CLI, scripts, shared- or root configuration, the lockfile, and Lab stories under- `apps/storybook/stories/`. So does an incomplete file list or a base whose- classifier has no Lab-only lane. An outside+ or root configuration, the lockfile, a change to an existing story, and a+ story of a component the change does not carry. So does an incomplete file+ list or a base whose classifier has no Lab-only lane. An outsidecontributor's pull request still needs `ci:run` (FR17), and `main` and therelease-check cover Lab as before (DEC-21).- **FR27 — Lint fails a pull request whose public text carries an internal@@ -591,33 +612,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` waits, a job admission could skip, or a peak below the jobs its run holds 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 | 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; Lab beside core, charts, a Storybook story, 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 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 | 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` waits, a job admission could skip, or a peak below the jobs its run holds 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 | 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@@ -1049,9 +1070,11 @@ hundred is Lab-only, and each skips most of a full run's work.Rejected: keeping full CI for Lab (it spends shipped-surface checks on apackage no stable release includes); Lab tests alone, without therepository-wide guards (a landed guard break blocks everyone else's pull-requests); counting Lab stories under `apps/storybook/stories/` as Lab-only-(they share the visual surface, and a path cannot tell a Lab story from a core-one without reading pull-request content, FR3).+requests); counting a story under `apps/storybook/stories/` as Lab-only by its+path alone (stories share the visual surface, and a path cannot tell a Lab+story from a core one). FR26 admits only a carried Lab component's new story,+and only after the trusted classifier reads the story's patch text as data+(FR3).### DEC-22 — A touched component's own accessibility contracts run, and block, on its pull request