An open source design system that's fully customizable and agent ready
TypeScript
test(rtl): route Charts package audits (#6252)
Cindy Zhang47ba5526fa93
diff --git a/.github/scripts/accessibility-audit.integration.test.mjs b/.github/scripts/accessibility-audit.integration.test.mjsnew file mode 100644index 0000000000..04cf035378--- /dev/null+++ b/.github/scripts/accessibility-audit.integration.test.mjs@@ -0,0 +1,221 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file CLI-level accessibility audit readiness fixtures.+ * Runs the real command, routing, server lifecycle, and report path with only+ * the browser transport replaced by a deterministic page implementation.+ */++import {spawnSync} from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';++const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));+const REPO_ROOT = path.resolve(SCRIPTS_DIR, '../..');+const SCRIPT = path.join(SCRIPTS_DIR, 'accessibility-audit.js');+let nextPort = 40000 + (process.pid % 10000);++const BROWSER_MOCK = String.raw`+const Module = require('node:module');+const originalLoad = Module._load;+let requestedUrl = '';+let reads = 0;++function scenarioState() {+ const scenario = process.env.A11Y_TEST_SCENARIO;+ reads += 1;+ if (scenario === 'redirect') {+ return {url: 'chrome-error://chromewebdata/', classes: [], content: false};+ }+ if (scenario === 'error') {+ return {url: requestedUrl, classes: ['sb-show-errordisplay'], content: false};+ }+ if (scenario === 'empty') {+ return {url: requestedUrl, classes: ['sb-show-main'], content: false};+ }+ return {+ url: requestedUrl,+ classes: ['sb-show-main'],+ content: reads >= 3,+ };+}++function evaluateInFixture(fn, arg) {+ const state = scenarioState();+ const previousWindow = global.window;+ const previousDocument = global.document;+ global.window = {location: {href: state.url}};+ global.document = {+ body: {classList: {contains: name => state.classes.includes(name)}},+ querySelector: selector =>+ selector === '#storybook-root'+ ? {childElementCount: state.content ? 1 : 0, textContent: ''}+ : null,+ };+ try {+ return fn(arg);+ } finally {+ global.window = previousWindow;+ global.document = previousDocument;+ }+}++const page = {+ goto: async url => { requestedUrl = url; },+ addStyleTag: async () => {},+ evaluate: async (fn, arg) => evaluateInFixture(fn, arg),+ close: async () => {},+};+const context = {newPage: async () => page, close: async () => {}};+const browser = {newContext: async () => context, close: async () => {}};++class FakeAxeBuilder {+ disableRules() { return this; }+ async analyze() { return {violations: []}; }+}++Module._load = function(request, parent, isMain) {+ if (request === 'playwright') {+ return {chromium: {launch: async () => browser}};+ }+ if (request === '@axe-core/playwright') {+ return {AxeBuilder: FakeAxeBuilder};+ }+ return originalLoad.call(this, request, parent, isMain);+};+`;++function runFixture(scenario, indexContent, components = 'core/Button') {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'a11y-cli-fixture-'));+ const storybook = path.join(dir, 'storybook');+ const output = path.join(dir, 'report.json');+ const mock = path.join(dir, 'browser-mock.cjs');+ fs.mkdirSync(storybook, {recursive: true});+ fs.writeFileSync(path.join(storybook, 'index.json'), indexContent);+ fs.writeFileSync(path.join(storybook, 'iframe.html'), '<!doctype html>');+ fs.writeFileSync(mock, BROWSER_MOCK);+ const port = nextPort++;+ try {+ const result = spawnSync(+ process.execPath,+ [+ SCRIPT,+ '--storybook-dir',+ storybook,+ '--output',+ output,+ '--components',+ components,+ '--port',+ String(port),+ ],+ {+ cwd: REPO_ROOT,+ encoding: 'utf8',+ env: {+ ...process.env,+ A11Y_TEST_SCENARIO: scenario,+ NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --require=${mock}`.trim(),+ },+ },+ );+ return {+ ...result,+ report: fs.existsSync(output)+ ? JSON.parse(fs.readFileSync(output, 'utf8'))+ : null,+ };+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+}++const VALID_INDEX = JSON.stringify({+ entries: {+ 'core-button--fixture': {+ id: 'core-button--fixture',+ title: 'Core/Button',+ name: 'Fixture',+ type: 'story',+ },+ },+});++const PATTERN_INDEX = JSON.stringify({+ entries: {+ 'a11y-button-pattern--clickable-card-disabled': {+ id: 'a11y-button-pattern--clickable-card-disabled',+ title: 'a11y/Button pattern',+ name: 'Clickable Card Disabled',+ type: 'story',+ },+ },+});++describe.sequential('accessibility-audit CLI readiness', () => {+ it('waits through a delayed valid Storybook root and writes audited evidence', () => {+ const result = runFixture('delayed', VALID_INDEX);+ expect(result.status).toBe(0);+ expect(result.stdout).toContain('✓ Audited: Button / Fixture');+ expect(result.report.auditedStoryKeys).toHaveLength(1);+ });++ it('routes a11y contract fixtures to canonical owners and legacy aliases', () => {+ const result = runFixture(+ 'delayed',+ PATTERN_INDEX,+ 'core/ClickableCard',+ );+ expect(result.status).toBe(0);+ expect(result.report.ownerStoryRoutes).toEqual({+ 'core/ClickableCard': [+ 'a11y-button-pattern--clickable-card-disabled',+ ],+ });+ expect(result.report.legacyBaselineAliases).toEqual({+ 'ClickableCard::Disabled': [+ 'core/ClickableCard::a11y-button-pattern--clickable-card-disabled',+ ],+ });+ });++ it('fails a redirect without writing a report', () => {+ const result = runFixture('redirect', VALID_INDEX);+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain(+ 'story navigation ended at chrome-error://chromewebdata/',+ );+ expect(result.report).toBeNull();+ });++ it('fails a Storybook render-error state without writing a report', () => {+ const result = runFixture('error', VALID_INDEX);+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain('Storybook reported a story render error');+ expect(result.report).toBeNull();+ });++ it(+ 'fails an attached but empty Storybook root without writing a report',+ () => {+ const result = runFixture('empty', VALID_INDEX);+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain(+ 'Storybook root did not render story content before timeout',+ );+ expect(result.report).toBeNull();+ },+ 10000,+ );++ it('fails an invalid index before browser readiness or routing', () => {+ const result = runFixture('delayed', '{invalid json');+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain('Could not read Storybook index');+ expect(result.stderr).not.toContain('No owned Storybook stories resolved');+ expect(result.report).toBeNull();+ });+});diff --git a/.github/scripts/accessibility-audit.js b/.github/scripts/accessibility-audit.jsindex acd037fcaf..62187f9904 100644--- a/.github/scripts/accessibility-audit.js+++ b/.github/scripts/accessibility-audit.js@@ -4,7 +4,8 @@/*** @description Runs accessibility audits on component stories using axe-core- * @input --storybook-dir <path> --output <file> --components <comma-separated>+ * @input --storybook-dir <path> --output <file> [--components <comma-separated>]+ * [--port <number>]* --baseline <path> (compare violations against a checked-in baseline)* --fail-on-new (exit 1 when violations not present in the baseline exist)* --update-baseline (rewrite the baseline file from this run's report)@@ -13,6 +14,8 @@* when --fail-on-new finds regressions. Diff logic lives in* lib/a11y-baseline.js. Pages are scanned with animations held at their end* state.+ * @position Blocking PR accessibility audit; scoped stories share canonical+ * package-qualified ownership with the RTL audit.*/const { chromium } = require('playwright');@@ -20,11 +23,22 @@ const { AxeBuilder } = require('@axe-core/playwright');const fs = require('node:fs');const path = require('node:path');const http = require('node:http');+const {+ COMPONENT_PACKAGES,+ flatPackageComponentNames,+ nestedPackageComponentNames,+} = require('../../scripts/component-packages.cjs');const {buildBaseline,diffAgainstBaseline,formatDiffSummary,+ storyKey,} = require('./lib/a11y-baseline');+const {waitForStoryReadiness} = require('./lib/a11y-story-readiness');+const {+ legacyBaselineStoryKeys,+ ownerForA11yStory,+} = require('./lib/a11y-story-identity');const args = process.argv.slice(2);const getArg = (name) => {@@ -35,6 +49,10 @@ const hasFlag = (name) => args.includes(`--${name}`);const storybookDir = getArg('storybook-dir') || 'apps/storybook/dist';const outputFile = getArg('output') || 'a11y-report.json';+const port = Number(getArg('port') || 6007);+if (!Number.isInteger(port) || port < 1 || port > 65535) {+ throw new Error(`Invalid --port value: ${getArg('port')}`);+}const componentsArg = getArg('components');const components = (componentsArg || '').split(',').filter(Boolean);// --components present but EMPTY means the caller derived an explicit empty@@ -117,18 +135,87 @@ function createServer(dir, port) {async function getStories(storybookPath) {const storiesJsonPath = path.join(storybookPath, 'index.json');+ let data;try {- const content = fs.readFileSync(storiesJsonPath, 'utf8');- const data = JSON.parse(content);- return data.entries || data.stories || {};- } catch (e) {- console.error('Could not read stories index:', e.message);- return {};+ data = JSON.parse(fs.readFileSync(storiesJsonPath, 'utf8'));+ } catch (error) {+ throw new Error(`Could not read Storybook index: ${error.message}`, {+ cause: error,+ });+ }+ const stories = data.entries || data.stories;+ if (+ stories == null ||+ typeof stories !== 'object' ||+ Array.isArray(stories)+ ) {+ throw new Error('Storybook index does not contain a story entries object');+ }+ const hasRunnableStory = Object.entries(stories).some(+ ([id, story]) => story?.type === 'story' && !id.endsWith('--docs'),+ );+ if (!hasRunnableStory) {+ throw new Error('Storybook index contains no runnable story entries');+ }+ return stories;+}++async function routedStoryIds(stories, componentFilters) {+ const {+ buildStoryComponentRoutes,+ componentRoutesForFilters,+ storyIdsForComponentFilters,+ unresolvedComponentFilters,+ } = await import(+ '../../apps/storybook/rtl-audit/rtl-audit-coverage.mjs'+ );+ const publicComponentsByPackage = Object.fromEntries(+ COMPONENT_PACKAGES.map(pkg => [+ pkg.name,+ pkg.layout === 'flat'+ ? flatPackageComponentNames(process.cwd(), pkg)+ : nestedPackageComponentNames(process.cwd(), pkg),+ ]),+ );+ const targets = JSON.parse(+ fs.readFileSync(+ path.resolve('apps/storybook/rtl-audit/targets.json'),+ 'utf8',+ ),+ );+ const routes = buildStoryComponentRoutes({+ stories: Object.entries(stories)+ .filter(([id, story]) => story.type === 'story' && !id.endsWith('--docs'))+ .map(([id, story]) => ({+ id,+ title: story.title || '',+ })),+ targets,+ publicComponentsByPackage,+ }).map(route => ({+ ...route,+ component: ownerForA11yStory(route.id) ?? route.component,+ }));+ const selectedRoutes = componentRoutesForFilters(routes, componentFilters);+ const ownerStoryRoutes = {};+ for (const route of selectedRoutes) {+ ownerStoryRoutes[route.component] ??= [];+ if (!ownerStoryRoutes[route.component].includes(route.id)) {+ ownerStoryRoutes[route.component].push(route.id);+ }}+ return {+ routes: selectedRoutes,+ allRoutes: routes,+ storyIds: storyIdsForComponentFilters(routes, componentFilters),+ unresolvedFilters: unresolvedComponentFilters(routes, componentFilters),+ ownerStoryRoutes,+ };}async function runAccessibilityAudit() {console.log('Starting accessibility audit...');+ fs.rmSync(outputFile, {force: true});if (emptyComponentSet) {console.log('No components to audit (--components is empty) — skipping.');@@ -145,60 +232,62 @@ async function runAccessibilityAudit() {const storybookPath = path.resolve(process.cwd(), storybookDir);if (!fs.existsSync(storybookPath)) {- console.error(`Storybook build not found at ${storybookPath}`);- const report = {- error: 'Storybook not built',- components: {},- summary: { total: 0, violations: 0 },- };- fs.writeFileSync(outputFile, JSON.stringify(report, null, 2));- return report;+ throw new Error(`Storybook build not found at ${storybookPath}`);}- // Start server- const port = 6007;- const server = await createServer(storybookPath, port);-// Get storiesconst stories = await getStories(storybookPath);const storyIds = Object.keys(stories);console.log(`Found ${storyIds.length} stories`);- // Filter stories for relevant components- const relevantStories = storyIds.filter((id) => {- // Skip docs pages- if (id.endsWith('--docs')) return false;-- if (components.length === 0) return true;- const story = stories[id];- const title = story.title || '';-- // Titles are like "Core/XDSButton" or "Layout/XDSCard"- const titleParts = title.split('/');- const componentPart = titleParts.length > 1 ? titleParts[1] : titleParts[0];- const normalizedComponent = componentPart.replace(/^XDS/i, '').toLowerCase();-- return components.some(- (comp) => normalizedComponent === comp.toLowerCase()+ // Reuse the same canonical package-qualified owner map as the RTL audit.+ // Grouped Storybook titles such as Charts/Chrome/Legend and the historical+ // Lab/RichTextEditor namespace otherwise resolve to zero stories here.+ const routed = await routedStoryIds(stories, components);+ if (routed.unresolvedFilters.length > 0) {+ throw new Error(+ `No owned Storybook stories resolved for: ${routed.unresolvedFilters.join(', ')}`,);+ }+ for (const [owner, ownedStoryIds] of Object.entries(+ routed.ownerStoryRoutes,+ )) {+ console.log(`Owner route: ${owner} -> ${ownedStoryIds.join(', ')}`);+ }+ const routedIds = new Set(routed.storyIds);+ const relevantStories = storyIds.filter(id => {+ if (id.endsWith('--docs')) return false;+ return routedIds.has(id);});- // Group stories by component+ // Group stories for scanning while retaining the legacy display identity for+ // safe baseline migration.const storyGroups = {};+ const storyKeyById = new Map(+ storyIds+ .filter(id => !id.endsWith('--docs'))+ .map(id => {+ const story = stories[id];+ const component = (story.title || '').split('/').pop() || id;+ return [id, storyKey(component, story.name || id)];+ }),+ );for (const storyId of relevantStories) {const story = stories[storyId];const component = (story.title || '').split('/').pop() || storyId;if (!storyGroups[component]) {storyGroups[component] = [];}- storyGroups[component].push({ id: storyId, ...story });+ storyGroups[component].push({id: storyId, ...story});}console.log(`Auditing ${Object.keys(storyGroups).length} components`);+ const server = await createServer(storybookPath, port);const browser = await chromium.launch();const componentResults = {};+ const auditedStoryIds = new Set();let totalViolations = 0;try {@@ -216,19 +305,49 @@ async function runAccessibilityAudit() {try {const url = `http://localhost:${port}/iframe.html?id=${story.id}&viewMode=story`;// Higher timeout to accommodate axe-core's heavier DOM analysis- await page.goto(url, { waitUntil: 'networkidle', timeout: 15000 });+ await page.goto(url, {+ waitUntil: 'domcontentloaded',+ timeout: 15000,+ });await page.addStyleTag({ content: FREEZE_CSS }).catch(() => {});- // Brief wait for any post-load rendering before axe-core scans the DOM- await page.waitForTimeout(500);+ await waitForStoryReadiness(+ () =>+ page.evaluate(+ ({expectedOrigin, storyId}) => {+ const currentUrl = new URL(window.location.href);+ const root = document.querySelector('#storybook-root');+ return {+ url: currentUrl.href,+ urlMatches:+ currentUrl.origin === expectedOrigin &&+ currentUrl.pathname === '/iframe.html' &&+ currentUrl.searchParams.get('id') === storyId,+ errorVisible:+ document.body.classList.contains('sb-show-errordisplay') ||+ document.body.classList.contains('sb-show-nopreview'),+ mainVisible:+ document.body.classList.contains('sb-show-main'),+ hasContent:+ root != null &&+ (root.childElementCount > 0 ||+ (root.textContent ?? '').trim().length > 0),+ };+ },+ {expectedOrigin: `http://localhost:${port}`, storyId: story.id},+ ),+ {timeoutMs: 5000, pollMs: 50},+ );// Run axe-core accessibility analysisconst results = await new AxeBuilder({ page }).disableRules(DISABLED_RULES).analyze();+ auditedStoryIds.add(story.id);if (results.violations.length > 0) {componentViolations.push({story: story.name || story.id,+ storyId: story.id,violations: results.violations,});totalViolations += results.violations.length;@@ -238,13 +357,10 @@ async function runAccessibilityAudit() {`✓ Audited: ${component} / ${story.name} - ${results.violations.length} issues`);} catch (e) {- console.error(`✗ Failed: ${story.id} - ${e.message}`);- // Record the failure but continue- componentViolations.push({- story: story.name || story.id,- error: e.message,- violations: [],- });+ throw new Error(+ `Accessibility scan failed for selected story ${story.id}: ${e.message}`,+ {cause: e},+ );} finally {await page.close();}@@ -296,7 +412,55 @@ async function runAccessibilityAudit() {server.close();}+ const auditedStories = routed.routes+ .filter(route => auditedStoryIds.has(route.id))+ .map(route => ({+ owner: route.component,+ storyId: route.id,+ legacyStoryKey: storyKeyById.get(route.id),+ }));+ const auditedStoryKeys = auditedStories.map(({owner, storyId}) =>+ storyKey(owner, storyId),+ );+ const ownerStoryKeys = {};+ for (const auditedStory of auditedStories) {+ ownerStoryKeys[auditedStory.owner] ??= [];+ ownerStoryKeys[auditedStory.owner].push(+ storyKey(auditedStory.owner, auditedStory.storyId),+ );+ }+ const legacyStoryOwners = {};+ for (const route of routed.allRoutes) {+ const legacyStory = storyKeyById.get(route.id);+ if (legacyStory == null) continue;+ legacyStoryOwners[legacyStory] ??= [];+ const canonicalStory = storyKey(route.component, route.id);+ if (!legacyStoryOwners[legacyStory].includes(canonicalStory)) {+ legacyStoryOwners[legacyStory].push(canonicalStory);+ }+ }++ const legacyBaselineAliases = {};+ for (const auditedStory of auditedStories) {+ for (const legacyStory of legacyBaselineStoryKeys(auditedStory.storyId)) {+ legacyBaselineAliases[legacyStory] ??= [];+ const canonicalStory = storyKey(+ auditedStory.owner,+ auditedStory.storyId,+ );+ if (!legacyBaselineAliases[legacyStory].includes(canonicalStory)) {+ legacyBaselineAliases[legacyStory].push(canonicalStory);+ }+ }+ }+const report = {+ ownerStoryRoutes: routed.ownerStoryRoutes,+ ownerStoryKeys,+ auditedStories,+ auditedStoryKeys,+ legacyStoryOwners,+ legacyBaselineAliases,components: componentResults,summary: {componentsAudited: Object.keys(componentResults).length,diff --git a/.github/scripts/accessibility-audit.test.mjs b/.github/scripts/accessibility-audit.test.mjsindex fecbb8e6f0..7bd283a00b 100644--- a/.github/scripts/accessibility-audit.test.mjs+++ b/.github/scripts/accessibility-audit.test.mjs@@ -2,74 +2,109 @@/*** @file accessibility-audit.test.mjs- * Pins the --components contract of the a11y audit CLI. The pr-a11y job- * derives its component list from the PR analysis and passes it as- * `--components "$COMPONENTS"`; when a core/src change maps to no component- * (a shared test file, docs-types.ts, …) that list is EMPTY, and the audit- * must skip and pass rather than fan out into a full-repo audit that fails- * on violations the PR never touched. An ABSENT --components flag keeps the- * a11y-weekly contract: audit all stories.+ * Pins the --components and Storybook-index contracts of the a11y audit CLI.+ * An explicitly empty component set is the only zero-work success. Missing or+ * malformed Storybook input must fail without leaving a success-shaped report.*/-import {execFileSync} from 'node:child_process';+import {spawnSync} from 'node:child_process';import fs from 'node:fs';import os from 'node:os';import path from 'node:path';import {fileURLToPath} from 'node:url';-import {describe, it, expect} from 'vitest';+import {describe, expect, it} from 'vitest';const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));const SCRIPT = path.join(SCRIPTS_DIR, 'accessibility-audit.js');const BASELINE = path.resolve(SCRIPTS_DIR, '..', 'a11y-baseline.json');-/** Run the audit CLI in an empty temp cwd; return {stdout, report}. */-function runAudit(args) {+function runAudit(args, setup) {const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'a11y-audit-'));+ const output = path.join(dir, 'report.json');try {- const stdout = execFileSync(+ setup?.(dir, output);+ const result = spawnSync(process.execPath,- [SCRIPT, '--output', 'report.json', ...args],+ [SCRIPT, '--output', output, ...args],{cwd: dir, encoding: 'utf8'},);- const report = JSON.parse(- fs.readFileSync(path.join(dir, 'report.json'), 'utf8'),- );- return {stdout, report};+ const report = fs.existsSync(output)+ ? JSON.parse(fs.readFileSync(output, 'utf8'))+ : null;+ return {...result, report};} finally {fs.rmSync(dir, {recursive: true, force: true});}}describe('accessibility-audit --components contract', () => {- it('audits nothing and passes when --components is explicitly empty', () => {- // The exact pr-a11y invocation shape for a PR whose analysis found no- // new or modified components. execFileSync throws on a non-zero exit,- // so reaching the assertions proves the gate passed.- const {stdout, report} = runAudit([+ it('audits nothing only when --components is explicitly empty', () => {+ const result = runAudit(['--components','','--baseline',BASELINE,'--fail-on-new',]);- expect(stdout).toContain('No components to audit');- expect(report.components).toEqual({});- expect(report.summary.totalViolations).toBe(0);+ expect(result.status).toBe(0);+ expect(result.stdout).toContain('No components to audit');+ expect(result.report.components).toEqual({});+ expect(result.report.summary.totalViolations).toBe(0);+ });++ it('fails closed when the all-stories audit has no Storybook build', () => {+ const result = runAudit([], (_dir, output) => {+ fs.writeFileSync(output, '{"summary":{"totalViolations":0}}');+ });+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain('Storybook build not found');+ expect(result.report).toBeNull();});- it('still audits all stories when the flag is absent (a11y-weekly)', () => {- // No storybook build exists in the temp cwd, so the all-stories path- // reports the missing build instead of skipping — absent ≠ empty.- const {stdout, report} = runAudit([]);- expect(stdout).not.toContain('No components to audit');- expect(stdout).toContain('all affected');- expect(report.error).toBe('Storybook not built');+ it('fails closed when selected components have no Storybook build', () => {+ const result = runAudit(['--components', 'Text,Heading']);+ expect(result.status).not.toBe(0);+ expect(result.stdout).toContain('Text, Heading');+ expect(result.stderr).toContain('Storybook build not found');+ expect(result.report).toBeNull();+ });++ it.each([+ ['empty', {entries: {}}],+ [+ 'docs-only',+ {+ entries: {+ 'core-button--docs': {+ id: 'core-button--docs',+ title: 'Core/Button',+ type: 'docs',+ },+ },+ },+ ],+ ])('fails closed when the Storybook index is %s', (_name, index) => {+ const result = runAudit([], dir => {+ const storybook = path.join(dir, 'apps/storybook/dist');+ fs.mkdirSync(storybook, {recursive: true});+ fs.writeFileSync(path.join(storybook, 'index.json'), JSON.stringify(index));+ });+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain(+ 'Storybook index contains no runnable story entries',+ );+ expect(result.report).toBeNull();});- it('proceeds to audit when --components names components', () => {- const {stdout, report} = runAudit(['--components', 'Text,Heading']);- expect(stdout).not.toContain('No components to audit');- expect(stdout).toContain('Text, Heading');- expect(report.error).toBe('Storybook not built');+ it('fails closed before routing when the Storybook index is invalid', () => {+ const result = runAudit(['--components', 'core/Button'], dir => {+ const storybook = path.join(dir, 'apps/storybook/dist');+ fs.mkdirSync(storybook, {recursive: true});+ fs.writeFileSync(path.join(storybook, 'index.json'), '{not json');+ });+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain('Could not read Storybook index');+ expect(result.stderr).not.toContain('No owned Storybook stories resolved');+ expect(result.report).toBeNull();});});diff --git a/.github/scripts/analyze-pr.js b/.github/scripts/analyze-pr.jsindex 64dda8469e..dbb972ebaa 100644--- a/.github/scripts/analyze-pr.js+++ b/.github/scripts/analyze-pr.js@@ -11,6 +11,12 @@const fs = require('node:fs');const path = require('node:path');const { execSync } = require('node:child_process');+const {+ COMPONENT_PACKAGES,+ documentedComponentNames,+ flatPackageComponentNames,+ nestedPackageComponentNames,+} = require('../../scripts/component-packages.cjs');const args = process.argv.slice(2);const getArg = (name) => {@@ -24,51 +30,39 @@ const outputFile = getArg('output') || 'analysis.json';const STORYBOOK_STORIES = 'apps/storybook/stories';-// The publishable component packages the report covers. Each PR is attributed-// to the package(s) it actually touches — the report is no longer hardcoded to-// `core` (which silently mislabelled every lab/charts PR).-//-// layout:-// 'nested' — components live in per-component dirs: src/<Name>/... (core, lab)-// 'flat' — components live as single files: src/<Name>.tsx (charts,-// richtext). The score-ledger's canonical predicate narrows a flat-// package to its documented component(s) downstream, so listing-// the internal helpers here is harmless — they get filtered out.-const PACKAGES = [- { name: '@astryxdesign/core', dir: 'packages/core', layout: 'nested' },- { name: '@astryxdesign/lab', dir: 'packages/lab', layout: 'nested' },- { name: '@astryxdesign/charts', dir: 'packages/charts', layout: 'flat' },- { name: '@astryxdesign/richtext', dir: 'packages/richtext', layout: 'flat' },-];--const pkgSrc = (pkg) => `${pkg.dir}/src`;+// Project the canonical component-package registry into the analyzer's existing+// shape. Package participation and layouts have one checked-in owner; this file+// only adds the published package name and derives its package directory.+const PACKAGES = COMPONENT_PACKAGES.map(pkg => ({+ ...pkg,+ packageName: pkg.name,+ name: `@astryxdesign/${pkg.name}`,+ dir: path.dirname(pkg.src),+}));++const pkgSrc = (pkg) => pkg.src;const pkgDist = (pkg) => `${pkg.dir}/dist`;-// Directories under a package's src that are not components.-const EXCLUDED_DIRS = ['hooks', 'theme', 'utils', 'i18n', '__tests__'];--// Get list of component names for a package, honoring its src layout.+// Get canonical direct public component names for a package. Nested family,+// context, and shared directories deliberately stay unresolved so audits widen.function getComponentNames(pkg) {- const srcPath = path.join(process.cwd(), pkgSrc(pkg));+ if (pkg.layout === 'flat') {+ return flatPackageComponentNames(process.cwd(), pkg);+ }+ const canonical = new Set(nestedPackageComponentNames(process.cwd(), pkg));+ const sourceDir = path.join(process.cwd(), pkgSrc(pkg));try {- const entries = fs.readdirSync(srcPath, { withFileTypes: true });- if (pkg.layout === 'flat') {- // Flat: each PascalCase *.tsx (not a test/story/context) is a component.- return entries- .filter(- (e) =>- e.isFile() &&- /^[A-Z]\w+\.tsx$/.test(e.name) &&- !e.name.includes('.test.') &&- !e.name.includes('.stories.') &&- !e.name.endsWith('Context.tsx'),- )- .map((e) => e.name.replace(/\.tsx$/, ''));- }- // Nested: each non-excluded directory is a component.- return entries- .filter((e) => e.isDirectory() && !EXCLUDED_DIRS.includes(e.name))- .map((e) => e.name);+ return fs+ .readdirSync(sourceDir, {withFileTypes: true})+ .filter(entry => entry.isDirectory())+ .filter(entry => {+ const names = documentedComponentNames(+ path.join(sourceDir, entry.name),+ ).filter(name => canonical.has(name));+ return names.length === 1 && names[0] === entry.name;+ })+ .map(entry => entry.name)+ .sort();} catch {return [];}@@ -529,6 +523,9 @@ function analyze() {const newComponents = [];const modifiedComponents = [];+ const newComponentOwners = [];+ const modifiedComponentOwners = [];+ const unresolvedComponentSources = [];const componentStats = {};const changedPackages = new Set();@@ -560,13 +557,27 @@ function analyze() {? relativePath.replace(/\.tsx?$/, '').split('/')[0]: relativePath.split('/')[0];- if (!allComponents.includes(componentName)) continue;+ if (!allComponents.includes(componentName)) {+ const source = `${pkg.packageName}/${componentName}`;+ if (!unresolvedComponentSources.includes(source)) {+ unresolvedComponentSources.push(source);+ }+ continue;+ }+ const existsInBase = componentExistsInBase(pkg, componentName);+ const owner = `${pkg.packageName}/${componentName}`;+ const owners = existsInBase ? modifiedComponentOwners : newComponentOwners;+ if (!owners.includes(owner)) owners.push(owner);++ // Keep the legacy bare-name shape for existing report consumers. The+ // package-qualified owner arrays below are the routing identity used by+ // browser audits and cannot collide across packages.const key = componentName;if (componentStats[key]) continue;const stats = getComponentStats(pkg, componentName);componentStats[key] = stats;- if (componentExistsInBase(pkg, componentName)) {+ if (existsInBase) {modifiedComponents.push(key);} else {newComponents.push(key);@@ -577,6 +588,9 @@ function analyze() {console.log(`Changed packages: ${[...changedPackages].join(', ') || 'none'}`);console.log(`New components: ${newComponents.join(', ') || 'none'}`);console.log(`Modified components: ${modifiedComponents.join(', ') || 'none'}`);+ console.log(+ `Component owners: ${[...newComponentOwners, ...modifiedComponentOwners].join(', ') || 'none'}`,+ );// Detect new exports in modified components (a dir may be "modified" yet add// brand-new exports alongside existing ones).@@ -602,6 +616,10 @@ function analyze() {const result = {newComponents,modifiedComponents,+ newComponentOwners,+ modifiedComponentOwners,+ unresolvedComponentSources,+ forceFullComponentAudits: unresolvedComponentSources.length > 0,newExports,componentStats,changedPackages: [...changedPackages],diff --git a/.github/scripts/analyze-pr.test.mjs b/.github/scripts/analyze-pr.test.mjsindex f7ac8743eb..3ae7d07a24 100644--- a/.github/scripts/analyze-pr.test.mjs+++ b/.github/scripts/analyze-pr.test.mjs@@ -14,7 +14,8 @@* feature branch off the branch point that touches exactly one component.* A shallow single-branch clone of the feature (depth 5) has no merge base* with origin/main, reproducing the CI failure; running analyze-pr.js against- * it must exit 0 and report exactly the component the branch touched.+ * it must exit 0 and report the Core, Rich Text, and Vega components the branch+ * touched.*/import {execFileSync} from 'node:child_process';@@ -45,7 +46,7 @@ function gitTry(dir, args) {/*** Build the synthetic repo and return the shallow clone dir:* upstream/: branch point, 60 churn commits on main, feature off the point- * touching only packages/core/src/Card/.+ * touching Core, Rich Text, and Vega components.* clone/ : --depth=5 --single-branch of feature (no merge base with main).*/function buildFixture() {@@ -56,6 +57,10 @@ function buildFixture() {fs.mkdirSync(path.join(upstream, 'packages/core/src/Card'), {recursive: true});fs.mkdirSync(path.join(upstream, 'packages/core/src/Button'), {recursive: true});fs.mkdirSync(path.join(upstream, 'packages/core/src/Line'), {recursive: true});+ fs.mkdirSync(path.join(upstream, 'packages/core/src/InteractiveRoleContext'), {recursive: true});+ fs.mkdirSync(path.join(upstream, 'packages/lab/src/Sankey'), {recursive: true});+ fs.mkdirSync(path.join(upstream, 'packages/richtext/src'), {recursive: true});+ fs.mkdirSync(path.join(upstream, 'packages/vega/src'), {recursive: true});fs.mkdirSync(path.join(upstream, 'packages/themes/neutral/src'), {recursive: true});fs.mkdirSync(path.join(upstream, 'packages/themes/probe/src'), {recursive: true});@@ -63,9 +68,40 @@ function buildFixture() {git(upstream, ['config', 'user.email', '[email protected]']);git(upstream, ['config', 'user.name', 'Test']);fs.writeFileSync(path.join(upstream, 'package.json'), '{}');- fs.writeFileSync(path.join(upstream, 'packages/core/src/Card/index.ts'), 'export {}\n');+ fs.writeFileSync(path.join(upstream, 'packages/core/src/index.ts'), "export {Card} from './Card';\n");+ fs.writeFileSync(path.join(upstream, 'packages/core/src/Card/Card.tsx'), 'export function Card() {}\n');+ fs.writeFileSync(path.join(upstream, 'packages/core/src/Card/Card.doc.mjs'), "export default {name: 'Card'};\n");+ fs.writeFileSync(path.join(upstream, 'packages/core/src/Card/index.ts'), "export {Card} from './Card';\n");fs.writeFileSync(path.join(upstream, 'packages/core/src/Button/index.ts'), 'export {}\n');fs.writeFileSync(path.join(upstream, 'packages/core/src/Line/index.ts'), 'export {}\n');+ fs.writeFileSync(+ path.join(upstream, 'packages/richtext/src/RichTextEditor.tsx'),+ 'export function RichTextEditor() {}\n',+ );+ fs.writeFileSync(+ path.join(upstream, 'packages/richtext/src/RichTextEditorAutoLinkPlugin.tsx'),+ 'export function RichTextEditorAutoLinkPlugin() {}\n',+ );+ fs.writeFileSync(+ path.join(upstream, 'packages/richtext/src/RichTextView.tsx'),+ 'export function RichTextView() {}\n',+ );+ fs.writeFileSync(+ path.join(upstream, 'packages/richtext/src/index.ts'),+ [+ "export {RichTextEditor} from './RichTextEditor';",+ "export {RichTextEditorAutoLinkPlugin} from './RichTextEditorAutoLinkPlugin';",+ "export {RichTextView} from './RichTextView';",+ '',+ ].join('\n'),+ );+ fs.writeFileSync(+ path.join(upstream, 'packages/vega/src/VegaChart.tsx'),+ 'export function VegaChart() {}\n',+ );+ fs.writeFileSync(path.join(upstream, 'packages/vega/src/index.ts'), "export {VegaChart} from './VegaChart';\n");+ fs.writeFileSync(path.join(upstream, 'packages/core/src/InteractiveRoleContext/internal.ts'), 'export const shared = true;\n');+ fs.writeFileSync(path.join(upstream, 'packages/lab/src/Sankey/internal.ts'), 'export const family = true;\n');fs.writeFileSync(path.join(upstream, 'packages/themes/neutral/package.json'),JSON.stringify({name: '@astryxdesign/theme-neutral', private: false}),@@ -88,14 +124,32 @@ function buildFixture() {git(upstream, ['commit', '-qm', `churn ${i}`]);}- // Feature branch off the branch point, touching only Card.+ // Feature branch off the branch point, touching Core, Rich Text, and Vega.git(upstream, ['branch', 'feature', branchPoint]);git(upstream, ['checkout', '-q', 'feature']);fs.appendFileSync(path.join(upstream, 'packages/core/src/Card/index.ts'), 'export const Card = {}\n');+ fs.appendFileSync(+ path.join(upstream, 'packages/richtext/src/RichTextEditor.tsx'),+ 'export const richTextChanged = true\n',+ );+ fs.appendFileSync(+ path.join(upstream, 'packages/richtext/src/RichTextEditorAutoLinkPlugin.tsx'),+ 'export const autoLinkChanged = true\n',+ );+ fs.appendFileSync(+ path.join(upstream, 'packages/richtext/src/RichTextView.tsx'),+ 'export const viewChanged = true\n',+ );+ fs.appendFileSync(+ path.join(upstream, 'packages/vega/src/VegaChart.tsx'),+ 'export const vegaChanged = true\n',+ );+ fs.appendFileSync(path.join(upstream, 'packages/core/src/InteractiveRoleContext/internal.ts'), 'export const sharedChanged = true\n');+ fs.appendFileSync(path.join(upstream, 'packages/lab/src/Sankey/internal.ts'), 'export const familyChanged = true\n');fs.appendFileSync(path.join(upstream, 'packages/themes/neutral/src/theme.ts'), 'export const changed = true\n');fs.appendFileSync(path.join(upstream, 'packages/themes/probe/src/theme.ts'), 'export const changed = true\n');git(upstream, ['add', '-A']);- git(upstream, ['commit', '-qm', 'touch Card only']);+ git(upstream, ['commit', '-qm', 'touch three component packages']);// Shallow single-branch clone of the feature branch.git(null, [@@ -107,7 +161,7 @@ function buildFixture() {}describe('analyze-pr shallow-clone recovery', () => {- it('recovers the three-dot diff by deepening and reports the exact component', () => {+ it('recovers the three-dot diff and reports Core, Rich Text, and Vega owners', () => {const {base, clone} = buildFixture();try {// Precondition: the clone really has no merge base (the CI failure).@@ -126,8 +180,32 @@ describe('analyze-pr shallow-clone recovery', () => {// Reaching the assertions proves exit 0 (execFileSync throws otherwise).expect(stdout).toContain('diff mode: three-dot');expect(analysis.diffMode).toBe('three-dot');- expect(analysis.modifiedComponents).toEqual(['Card']);- expect(analysis.changedPackages).toEqual(['@astryxdesign/core']);+ expect(analysis.modifiedComponents).toEqual([+ 'Card',+ 'RichTextEditor',+ 'RichTextEditorAutoLinkPlugin',+ 'RichTextView',+ 'VegaChart',+ ]);+ expect(analysis.modifiedComponentOwners).toEqual([+ 'core/Card',+ 'richtext/RichTextEditor',+ 'richtext/RichTextEditorAutoLinkPlugin',+ 'richtext/RichTextView',+ 'vega/VegaChart',+ ]);+ expect(analysis.modifiedComponentOwners).not.toContain('core/InteractiveRoleContext');+ expect(analysis.modifiedComponentOwners).not.toContain('lab/Sankey');+ expect(analysis.forceFullComponentAudits).toBe(true);+ expect(analysis.unresolvedComponentSources).toEqual(+ expect.arrayContaining(['core/InteractiveRoleContext', 'lab/Sankey']),+ );+ expect(analysis.changedPackages).toEqual([+ '@astryxdesign/core',+ '@astryxdesign/lab',+ '@astryxdesign/richtext',+ '@astryxdesign/vega',+ ]);expect(analysis.changedStableThemes).toEqual(['neutral']);} finally {fs.rmSync(base, {recursive: true, force: true});diff --git a/.github/scripts/ci-test-routing.test.mjs b/.github/scripts/ci-test-routing.test.mjsindex 524f7ddb17..27fa232910 100644--- a/.github/scripts/ci-test-routing.test.mjs+++ b/.github/scripts/ci-test-routing.test.mjs@@ -24,6 +24,9 @@ import path from 'node:path';import {describe, expect, it} from 'vitest';import yaml from 'yaml';+import componentPackages from '../../scripts/component-packages.cjs';++const {COMPONENT_PACKAGE_NAMES} = componentPackages;const root = path.resolve(import.meta.dirname, '../..');const read = relative => fs.readFileSync(path.join(root, relative), 'utf8');@@ -171,6 +174,99 @@ describe.each(Object.entries(WORKFLOWS))(},);+describe('ci.yml RTL package sharding', () => {+ const workflow = load('ci.yml');+ const shard = workflow.jobs['pr-rtl-shard'];+ const join = workflow.jobs['pr-rtl'];++ it('keeps specialized lanes as explicit successful no-audit classifications', () => {+ const classification = workflow.jobs['check-components'];+ expect(classification.if).toBe("github.event_name == 'pull_request'");+ const commands = runLines(classification);+ for (const lane of ['docsite_only', 'spec_only', 'tooling_only']) {+ expect(commands).toContain(`needs.check-scope.outputs.${lane}`);+ }+ expect(commands).toContain('has_components=false');+ expect(commands).toContain('has_rtl_components=false');+ expect(commands).toContain('has_rtl_harness=false');+ expect(commands).toContain('force_full_component_audits=false');+ expect(commands).toContain('has_stable_visual=false');+ });++ it('broadens both browser audits for unresolved canonical source ownership', () => {+ expect(runLines(workflow.jobs['pr-a11y'])).toContain(+ '.forceFullComponentAudits // false',+ );+ expect(runLines(shard)).toContain('.github/scripts/rtl-shard-scope.mjs');+ });++ it('runs one bounded shard for every canonical component package', () => {+ expect(shard.strategy.matrix.package).toEqual([...COMPONENT_PACKAGE_NAMES]);+ expect(shard['runs-on']).toBe('4-core-ubuntu');+ expect(shard['timeout-minutes']).toBeLessThanOrEqual(30);+ expect(shard['continue-on-error']).not.toBe(true);+ const scope = shard.steps.find(+ step => step.name === 'Resolve RTL shard scope',+ );+ const audit = shard.steps.find(step => step.name === 'Run RTL audit');+ const validation = shard.steps.find(+ step => step.name === 'Require completed RTL shard report',+ );+ expect(scope['continue-on-error']).not.toBe(true);+ expect(scope.run).toContain('.github/scripts/rtl-shard-scope.mjs');+ expect(scope.run).toContain('--manifest rtl-shard-scope.json');+ expect(audit.if).toContain("steps.rtl-scope.outputs.should_run == 'true'");+ expect(audit['continue-on-error']).toBe(true);+ expect(validation.if).toBe('always()');+ expect(validation.run).toContain('steps.rtl-scope.outcome');+ expect(validation.run).toContain(+ 'produced no explicit should_run decision',+ );+ expect(runLines(shard)).toContain('--packages "$PACKAGE"');+ expect(runLines(shard)).toContain('--concurrency 4');+ expect(runLines(shard)).toContain(+ '.github/scripts/rtl-report-completion.mjs',+ );+ expect(runLines(shard)).toContain(+ '--filter "${{ steps.rtl-scope.outputs.filter }}"',+ );+ });++ it('keeps pr-rtl as a fail-closed join over every matrix shard', () => {+ expect(join.needs).toEqual(+ expect.arrayContaining(['check-components', 'pr-rtl-shard']),+ );+ const commands = runLines(join);+ expect(commands).toContain('needs.check-components.result');+ expect(commands).toContain('needs.pr-rtl-shard.result');+ expect(commands).toContain('.github/scripts/rtl-join.mjs');+ expect(commands).toContain('--reports-dir rtl-shard-reports');+ expect(commands).toContain(+ '--force-full "${{ needs.check-components.outputs.force_full_component_audits }}"',+ );+ const download = join.steps.find(+ step => step.name === 'Download applicable RTL shard reports',+ );+ expect(download['continue-on-error']).toBe(true);+ expect(download.with.pattern).toBe('rtl-audit-report-*');+ const requireStep = join.steps.find(+ step => step.name === 'Require every applicable RTL shard',+ );+ expect(requireStep.if).toBe('always()');+ });++ it('publishes a distinct scope manifest and optional report for each shard', () => {+ const upload = shard.steps.find(step =>+ step.uses?.startsWith('actions/upload-artifact@'),+ );+ expect(upload.if).toBe('always()');+ expect(upload.with.name).toBe('rtl-audit-report-${{ matrix.package }}');+ expect(upload.with.path).toContain('rtl-shard-scope.json');+ expect(upload.with.path).toContain('rtl-audit-report.json');+ expect(upload.with['if-no-files-found']).toBe('error');+ });+});+describe('deploy.yml push gating', () => {const workflow = load('deploy.yml');diff --git a/.github/scripts/ci-tooling-routing.test.mjs b/.github/scripts/ci-tooling-routing.test.mjsindex 9b2b4ffe57..bb35fbf7cf 100644--- a/.github/scripts/ci-tooling-routing.test.mjs+++ b/.github/scripts/ci-tooling-routing.test.mjs@@ -84,12 +84,18 @@ describe('Node-tooling CI routing', () => {}});- it('skips the UI project and component/browser owners for tooling', () => {+ it('skips UI/browser owners but keeps an explicit component N/A reporter', () => {const uiSuite = ci.jobs['test-ui'].steps.find(candidate =>candidate.run?.includes('--project ui'),);expect(uiSuite.if).toContain(TOOLING_FALSE);- expect(ci.jobs['check-components'].if).toContain(TOOLING_FALSE);+ expect(ci.jobs['check-components'].if).not.toContain(TOOLING_FALSE);+ const componentCheck = step(+ ci.jobs['check-components'],+ 'Check for component changes',+ ).run;+ expect(componentCheck).toContain('needs.check-scope.outputs.tooling_only');+ expect(componentCheck).toContain('has_components=false');expect(ci.jobs['theme-layers'].if).toContain(TOOLING_FALSE);expect(ci.jobs['fixture-contrast'].if).toContain(TOOLING_FALSE);});diff --git a/.github/scripts/component-audit-scope.cjs b/.github/scripts/component-audit-scope.cjsnew file mode 100644index 0000000000..6175d9e472--- /dev/null+++ b/.github/scripts/component-audit-scope.cjs@@ -0,0 +1,114 @@+#!/usr/bin/env node+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use strict';+/* global module, require */++/**+ * @file Trusted component-audit scope classifier.+ * @input Git name-status rows on stdin and --registry <trusted-base registry>.+ * @output GitHub job outputs for component, RTL, and fail-closed full-audit scope;+ * empty or unmatched input always selects the full audits.+ * @position Loaded with its registry from the pull request's trusted base ref.+ */++const fs = require('node:fs');+const path = require('node:path');++function changedPathsFromNameStatus(input) {+ return input+ .split('\n')+ .filter(Boolean)+ .flatMap(line => line.split('\t').slice(1))+ .filter(Boolean);+}++function classifyComponentAuditScope(paths, componentPackages) {+ const sourceRoots = componentPackages.map(pkg => `${pkg.src}/`);+ const isComponentSource = file =>+ sourceRoots.some(root => file.startsWith(root));+ const isStory = file => file.startsWith('apps/storybook/stories/');+ const isAccessibilitySurface = file =>+ file.startsWith('internal/a11y-spec/') ||+ /(^|\/)src\/.*\.a11y\./.test(file) ||+ file === 'playwright.config.ts';+ const isRtlHarness = file =>+ file.startsWith('apps/storybook/rtl-audit/') ||+ file === '.github/scripts/rtl-audit-coverage.test.mjs' ||+ file === '.github/scripts/weekly-rtl-summary.test.mjs' ||+ file === '.github/workflows/rtl-weekly.yml';+ const isSharedRoutingPolicy = file =>+ file === 'apps/storybook/rtl-audit/rtl-audit-coverage.mjs' ||+ file === 'apps/storybook/rtl-audit/targets.json' ||+ file === 'apps/storybook/rtl-audit/verified-not-applicable.json' ||+ file === '.github/scripts/rtl-audit-coverage.test.mjs' ||+ file === 'scripts/component-packages.cjs';++ const componentSourceChanged = paths.some(isComponentSource);+ const storyChanged = paths.some(isStory);+ const accessibilityChanged = paths.some(isAccessibilitySurface);+ const rtlHarnessChanged = paths.some(isRtlHarness);+ const forceFullComponentAudits =+ paths.length === 0 ||+ paths.some(+ file =>+ isSharedRoutingPolicy(file) ||+ (!isComponentSource(file) &&+ !isStory(file) &&+ !isAccessibilitySurface(file) &&+ !isRtlHarness(file)),+ );++ return {+ has_components:+ componentSourceChanged ||+ storyChanged ||+ accessibilityChanged ||+ forceFullComponentAudits,+ has_rtl_components:+ componentSourceChanged || storyChanged || forceFullComponentAudits,+ has_rtl_harness: rtlHarnessChanged || forceFullComponentAudits,+ force_full_component_audits: forceFullComponentAudits,+ };+}++function parseArgs(argv) {+ const index = argv.indexOf('--registry');+ return {+ registry: index >= 0 ? argv[index + 1] : null,+ githubOutput: argv.includes('--github-output'),+ };+}++function main() {+ const args = parseArgs(process.argv.slice(2));+ if (!args.registry) {+ throw new Error('--registry is required');+ }+ const registry = require(path.resolve(args.registry));+ if (!Array.isArray(registry.COMPONENT_PACKAGES)) {+ throw new Error('trusted component registry is missing COMPONENT_PACKAGES');+ }+ const input = fs.readFileSync(0, 'utf8');+ const result = classifyComponentAuditScope(+ changedPathsFromNameStatus(input),+ registry.COMPONENT_PACKAGES,+ );+ const lines = Object.entries(result).map(+ ([key, value]) => `${key}=${String(value)}`,+ );+ if (args.githubOutput) {+ fs.appendFileSync(process.env.GITHUB_OUTPUT, `${lines.join('\n')}\n`);+ } else {+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);+ }+}++if (require.main === module) {+ main();+}++module.exports = {+ changedPathsFromNameStatus,+ classifyComponentAuditScope,+};diff --git a/.github/scripts/component-audit-scope.test.mjs b/.github/scripts/component-audit-scope.test.mjsnew file mode 100644index 0000000000..67f933dc78--- /dev/null+++ b/.github/scripts/component-audit-scope.test.mjs@@ -0,0 +1,114 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Mutation-sensitive tests for trusted component-audit scope routing.+ */++import fs from 'node:fs';+import {createRequire} from 'node:module';+import {describe, expect, it} from 'vitest';++const require = createRequire(import.meta.url);+const {COMPONENT_PACKAGES} = require('../../scripts/component-packages.cjs');+const {+ changedPathsFromNameStatus,+ classifyComponentAuditScope,+} = require('./component-audit-scope.cjs');++const FULL_AUDIT_SCOPE = {+ has_components: true,+ has_rtl_components: true,+ has_rtl_harness: true,+ force_full_component_audits: true,+};++describe('component audit scope', () => {+ it('loads the classifier and registry from the trusted base ref', () => {+ const workflow = fs.readFileSync(+ new URL('../workflows/ci.yml', import.meta.url),+ 'utf8',+ );+ expect(workflow).toContain(+ 'origin/${{ github.base_ref }}:.github/scripts/component-audit-scope.cjs',+ );+ expect(workflow).toContain(+ 'origin/${{ github.base_ref }}:scripts/component-packages.cjs',+ );+ expect(workflow).toContain('force_full_component_audits=true');+ });++ it.each([+ ['packages/core/src/Button/Button.tsx', 'core'],+ ['packages/lab/src/Drawer/Drawer.tsx', 'lab'],+ ['packages/charts/src/Chart.tsx', 'charts'],+ ['packages/richtext/src/RichTextEditor.tsx', 'richtext'],+ ['packages/vega/src/VegaChart.tsx', 'vega'],+ ])('routes a source-only %s change through component and RTL audits', file => {+ expect(classifyComponentAuditScope([file], COMPONENT_PACKAGES)).toMatchObject({+ has_components: true,+ has_rtl_components: true,+ force_full_component_audits: false,+ });+ });++ it('fails closed when a PR mutates the registry while changing a removed package', () => {+ const changedPaths = [+ 'scripts/component-packages.cjs',+ 'packages/vega/src/VegaChart.tsx',+ ];+ const prControlledPackages = COMPONENT_PACKAGES.filter(+ pkg => pkg.name !== 'vega',+ );+ expect(+ classifyComponentAuditScope(+ ['packages/vega/src/VegaChart.tsx'],+ prControlledPackages,+ ),+ ).toMatchObject(FULL_AUDIT_SCOPE);++ expect(+ classifyComponentAuditScope(changedPaths, prControlledPackages),+ ).toMatchObject(FULL_AUDIT_SCOPE);+ });++ it.each([+ [+ 'routing-test-only',+ ['.github/scripts/component-audit-scope.test.mjs'],+ ],+ ['trusted classifier dependency', ['.github/scripts/change-scope.cjs']],+ ['accessibility harness', ['.github/scripts/accessibility-audit.js']],+ ['target-only route policy', ['apps/storybook/rtl-audit/targets.json']],+ [+ 'route policy with component source',+ [+ 'apps/storybook/rtl-audit/rtl-audit-coverage.mjs',+ 'packages/vega/src/VegaChart.tsx',+ ],+ ],+ [+ 'verified-N/A policy with unrelated component source',+ [+ 'apps/storybook/rtl-audit/verified-not-applicable.json',+ 'packages/core/src/Button/Button.tsx',+ ],+ ],+ ['unknown path', ['new/unclassified/path.xyz']],+ ['empty input', []],+ ])('fails closed for %s', (_name, paths) => {+ expect(+ classifyComponentAuditScope(paths, COMPONENT_PACKAGES),+ ).toMatchObject(FULL_AUDIT_SCOPE);+ });++ it('keeps rename source and destination paths in scope', () => {+ expect(+ changedPathsFromNameStatus(+ 'R100\tpackages/vega/src/OldChart.tsx\tpackages/vega/src/VegaChart.tsx\n',+ ),+ ).toEqual([+ 'packages/vega/src/OldChart.tsx',+ 'packages/vega/src/VegaChart.tsx',+ ]);+ });+});diff --git a/.github/scripts/lib/a11y-baseline.js b/.github/scripts/lib/a11y-baseline.jsindex beb3635a8a..fdccdab72d 100644--- a/.github/scripts/lib/a11y-baseline.js+++ b/.github/scripts/lib/a11y-baseline.js@@ -12,7 +12,8 @@* --update-baseline). Kept free of Playwright/axe so it can be unit-tested* without a browser (see a11y-baseline.test.mjs).*- * Key design: `Component::Story::rule-id`.+ * Key design: `package/Component::story-id::rule-id` for current reports,+ * with safe matching and migration of legacy `Component::Story::rule-id` keys.* - Component + story + axe rule id is stable across unrelated DOM churn:* axe rule ids are versioned and stable, and story names only change when* someone renames a story (an intentional act).@@ -28,9 +29,40 @@const BASELINE_VERSION = 1;+/** Build the stable prefix for one audited component story. */+function storyKey(component, story) {+ return `${component}::${story}`;+}+/** Build the stable baseline key for one violation occurrence. */function violationKey(component, story, ruleId) {- return `${component}::${story}::${ruleId}`;+ return `${storyKey(component, story)}::${ruleId}`;+}++function violationIdentities(report, component, story, storyId) {+ const legacyStoryKey = storyKey(component, story);+ const auditedStories = Array.isArray(report?.auditedStories)+ ? report.auditedStories+ : [];+ const owners = storyId+ ? auditedStories.filter(entry => entry.storyId === storyId)+ : [];+ if (owners.length === 0) {+ return [+ {+ keyPrefix: legacyStoryKey,+ legacyKeyPrefix: legacyStoryKey,+ component,+ story,+ },+ ];+ }+ return owners.map(entry => ({+ keyPrefix: storyKey(entry.owner, entry.storyId),+ legacyKeyPrefix: entry.legacyStoryKey || legacyStoryKey,+ component: entry.owner,+ story: entry.storyId,+ }));}/**@@ -58,16 +90,24 @@ function collectViolations(report) {if (storyDetails.length > 0) {for (const storyResult of storyDetails) {for (const violation of storyResult.violations || []) {- occurrences.push({- key: violationKey(component, storyResult.story, violation.id),+ for (const identity of violationIdentities(+ report,component,- story: storyResult.story,- ruleId: violation.id,- impact: violation.impact || 'unknown',- help: violation.help || violation.description || '',- helpUrl: violation.helpUrl || '',- nodes: (violation.nodes || []).length,- });+ storyResult.story,+ storyResult.storyId,+ )) {+ occurrences.push({+ key: `${identity.keyPrefix}::${violation.id}`,+ legacyKey: `${identity.legacyKeyPrefix}::${violation.id}`,+ component: identity.component,+ story: identity.story,+ ruleId: violation.id,+ impact: violation.impact || 'unknown',+ help: violation.help || violation.description || '',+ helpUrl: violation.helpUrl || '',+ nodes: (violation.nodes || []).length,+ });+ }}}} else {@@ -78,8 +118,10 @@ function collectViolations(report) {? violation.stories: ['*'];for (const story of stories) {+ const key = violationKey(component, story, violation.id);occurrences.push({- key: violationKey(component, story, violation.id),+ key,+ legacyKey: key,component,story,ruleId: violation.id,@@ -117,23 +159,125 @@ function baselineKeySet(baseline) {);}+function canonicalPackage(canonicalStoryKey) {+ const owner = canonicalStoryKey.split('::')[0];+ return owner.includes('/') ? owner.split('/')[0] : null;+}++function hasOnePackage(owners) {+ const packages = new Set(owners.map(canonicalPackage).filter(Boolean));+ return packages.size === 1;+}++function auditedScope(report) {+ if (Array.isArray(report?.auditedStories)) {+ const canonicalStoryKeys = new Set(+ report.auditedStories.map(entry => storyKey(entry.owner, entry.storyId)),+ );+ const exactLegacyStoryKeys = Object.entries(report.legacyStoryOwners || {})+ .filter(+ ([, owners]) =>+ Array.isArray(owners) &&+ owners.length === 1 &&+ canonicalStoryKeys.has(owners[0]),+ )+ .map(([legacyStory]) => legacyStory);+ const migratedLegacyStoryKeys = Object.entries(+ report.legacyBaselineAliases || {},+ )+ .filter(+ ([, owners]) =>+ Array.isArray(owners) &&+ owners.length > 0 &&+ hasOnePackage(owners) &&+ owners.every(ownerStory => canonicalStoryKeys.has(ownerStory)),+ )+ .map(([legacyStory]) => legacyStory);+ return {+ canonicalStoryKeys,+ legacyStoryKeys: new Set([+ ...exactLegacyStoryKeys,+ ...migratedLegacyStoryKeys,+ ]),+ components: null,+ };+ }+ if (Array.isArray(report?.auditedStoryKeys)) {+ return {+ canonicalStoryKeys: new Set(),+ legacyStoryKeys: new Set(report.auditedStoryKeys),+ components: null,+ };+ }+ return {+ canonicalStoryKeys: null,+ legacyStoryKeys: null,+ components: new Set(Object.keys(report?.components || {})),+ };+}++function baselineKeyWasAudited(key, scope) {+ if (scope.canonicalStoryKeys != null) {+ const keyParts = key.split('::');+ const auditedStories = keyParts[0].includes('/')+ ? scope.canonicalStoryKeys+ : scope.legacyStoryKeys;+ return auditedStories.has(keyParts.slice(0, 2).join('::'));+ }+ return scope.components.has(key.split('::')[0]);+}++function safeLegacyAliases(occurrence, report) {+ const aliases = new Set();+ if (!occurrence.legacyKey) return aliases;+ if (occurrence.legacyKey === occurrence.key) {+ aliases.add(occurrence.legacyKey);+ return aliases;+ }++ const legacyStory = occurrence.legacyKey.split('::').slice(0, 2).join('::');+ const canonicalStory = occurrence.key.split('::').slice(0, 2).join('::');+ const exactOwners = report?.legacyStoryOwners?.[legacyStory];+ if (+ Array.isArray(exactOwners) &&+ exactOwners.length === 1 &&+ exactOwners[0] === canonicalStory+ ) {+ aliases.add(occurrence.legacyKey);+ }++ for (const [migratedLegacyStory, owners] of Object.entries(+ report?.legacyBaselineAliases || {},+ )) {+ if (+ Array.isArray(owners) &&+ owners.includes(canonicalStory) &&+ hasOnePackage(owners) &&+ canonicalPackage(canonicalStory) === canonicalPackage(owners[0])+ ) {+ aliases.add(`${migratedLegacyStory}::${occurrence.ruleId}`);+ }+ }+ return aliases;+}+/*** Build a baseline object from a report (for --update-baseline).** The audit is often scoped with --components, so the report only covers a- * subset of the library. Entries in `existing` that belong to components NOT- * audited in this report are preserved; entries for audited components are- * replaced wholesale by the report's current violations.+ * subset of the library. Entries in `existing` whose exact component/story was+ * not audited in this report are preserved; entries for audited stories are+ * replaced by the report's current violations.** @param {object} report* @param {{existing?: object|null, now?: Date}} [options]*/function buildBaseline(report, {existing = null, now = new Date()} = {}) {- const audited = new Set(Object.keys((report && report.components) || {}));+ const scope = auditedScope(report);const preserved = ((existing && existing.entries) || []).map(entry => (typeof entry === 'string' ? {key: entry} : entry)).filter(- entry => entry && entry.key && !audited.has(entry.key.split('::')[0]),+ entry => entry && entry.key && !baselineKeyWasAudited(entry.key, scope),);const fresh = collectViolations(report).map(v => ({key: v.key,@@ -144,7 +288,9 @@ function buildBaseline(report, {existing = null, now = new Date()} = {}) {return {$comment:'Known axe violations tolerated by the pr-a11y CI gate. Entries are ' +- 'keyed Component::Story::rule-id. Regenerate with `pnpm a11y:baseline` ' ++ 'keyed package/component::story-id::rule-id; legacy ' ++ 'Component::Story::rule-id entries are preserved until their exact ' ++ 'story can be migrated. Regenerate with `pnpm a11y:baseline` ' +'(requires a built Storybook + Playwright chromium). Remove entries ' +'as violations are fixed.',version: BASELINE_VERSION,@@ -160,10 +306,9 @@ function buildBaseline(report, {existing = null, now = new Date()} = {}) {** Anything in the report but missing from the baseline is NEW (a missing or* empty baseline means every violation is new). Baseline entries with no- * matching violation are RESOLVED and can be deleted from the baseline —- * but only for components that were actually audited in this run. The CI- * audit is scoped to changed components, so baseline entries for components- * outside this run are reported as `unchecked`, not resolved.+ * matching violation are RESOLVED and can be deleted from the baseline — but+ * only for exact component/story keys actually audited in this run. Entries+ * outside the audited story set are `unchecked`, not resolved.** @param {object} report* @param {object|null|undefined} baseline@@ -173,19 +318,26 @@ function buildBaseline(report, {existing = null, now = new Date()} = {}) {function diffAgainstBaseline(report, baseline) {const current = collectViolations(report);const known = baselineKeySet(baseline);- const currentKeys = new Set(current.map(v => v.key));- // Every audited component gets a report entry, even with zero violations.- const auditedComponents = new Set(- Object.keys((report && report.components) || {}),- );+ const currentKeys = new Set();+ const newViolations = [];+ for (const occurrence of current) {+ currentKeys.add(occurrence.key);+ const legacyAliases = safeLegacyAliases(occurrence, report);+ for (const alias of legacyAliases) currentKeys.add(alias);+ if (+ !known.has(occurrence.key) &&+ ![...legacyAliases].some(alias => known.has(alias))+ ) {+ newViolations.push(occurrence);+ }+ }+ const scope = auditedScope(report);- const newViolations = current.filter(v => !known.has(v.key));const resolved = [];const unchecked = [];for (const key of Array.from(known).sort()) {if (currentKeys.has(key)) continue;- const component = key.split('::')[0];- if (auditedComponents.has(component)) {+ if (baselineKeyWasAudited(key, scope)) {resolved.push(key);} else {unchecked.push(key);@@ -220,7 +372,7 @@ function formatDiffSummary(`${diff.newViolations.length} new, ${diff.matched} baselined, ` +`${diff.resolved.length} resolved` +(unchecked.length > 0- ? `, ${unchecked.length} baselined for components outside this run`+ ? `, ${unchecked.length} baselined for stories outside this run`: ''),);@@ -269,6 +421,7 @@ function formatDiffSummary(module.exports = {BASELINE_VERSION,+ storyKey,violationKey,collectViolations,baselineKeySet,diff --git a/.github/scripts/lib/a11y-baseline.test.mjs b/.github/scripts/lib/a11y-baseline.test.mjsindex 162cf89e73..96f2890962 100644--- a/.github/scripts/lib/a11y-baseline.test.mjs+++ b/.github/scripts/lib/a11y-baseline.test.mjs@@ -31,7 +31,11 @@ function makeReport(componentStories) {storyDetails,};}- return {components, summary: {}};+ const auditedStoryKeys = Object.entries(componentStories).flatMap(+ ([component, stories]) =>+ Object.keys(stories).map(story => `${component}::${story}`),+ );+ return {auditedStoryKeys, components, summary: {}};}function axeViolation(id, overrides = {}) {@@ -47,6 +51,94 @@ function axeViolation(id, overrides = {}) {};}+const RICH_TEXT_BASELINE_KEYS = [+ 'Controlled Persistence',+ 'Custom Transformers',+ 'Default',+ 'Error Status',+ 'Imperative Ref',+ 'Markdown Serializers',+ 'Read Only',+ 'Required',+ 'With Character Limit',+ 'With Description',+ 'With Initial Value',+ 'With Toolbar',+].flatMap(story => [+ `RichTextEditor::${story}::aria-input-field-name`,+ ...(story === 'Markdown Serializers'+ ? [`RichTextEditor::${story}::label`]+ : []),+]);++function makeRoutedReport({+ owner,+ storyId,+ component,+ story,+ violations = [],+ legacyStoryOwners,+ legacyBaselineAliases,+}) {+ const canonicalStoryKey = `${owner}::${storyId}`;+ const legacyStoryKey = `${component}::${story}`;+ return {+ ownerStoryRoutes: {[owner]: [storyId]},+ ownerStoryKeys: {[owner]: [canonicalStoryKey]},+ auditedStories: [{owner, storyId, legacyStoryKey}],+ auditedStoryKeys: [canonicalStoryKey],+ legacyStoryOwners: legacyStoryOwners ?? {+ [legacyStoryKey]: [canonicalStoryKey],+ },+ legacyBaselineAliases: legacyBaselineAliases ?? {},+ components: {+ [component]: {+ storiesAudited: 1,+ violations: [],+ storyDetails:+ violations.length > 0 ? [{story, storyId, violations}] : [],+ },+ },+ summary: {},+ };+}++function makeMultiRoutedReport(rows, {legacyBaselineAliases = {}} = {}) {+ const components = {};+ const auditedStories = [];+ const legacyStoryOwners = {};+ for (const row of rows) {+ const canonicalStoryKey = `${row.owner}::${row.storyId}`;+ const legacyStoryKey = `${row.component}::${row.story}`;+ auditedStories.push({+ owner: row.owner,+ storyId: row.storyId,+ legacyStoryKey,+ });+ legacyStoryOwners[legacyStoryKey] ??= [];+ legacyStoryOwners[legacyStoryKey].push(canonicalStoryKey);+ components[row.component] ??= {storiesAudited: 0, violations: [], storyDetails: []};+ components[row.component].storiesAudited += 1;+ if (row.ruleId) {+ components[row.component].storyDetails.push({+ story: row.story,+ storyId: row.storyId,+ violations: [axeViolation(row.ruleId)],+ });+ }+ }+ return {+ auditedStories,+ auditedStoryKeys: auditedStories.map(({owner, storyId}) =>+ `${owner}::${storyId}`,+ ),+ legacyStoryOwners,+ legacyBaselineAliases,+ components,+ summary: {},+ };+}+describe('violationKey', () => {it('is component + story + rule id, independent of DOM specifics', () => {expect(violationKey('Button', 'Primary', 'button-name')).toBe(@@ -175,6 +267,191 @@ describe('diffAgainstBaseline', () => {expect(diff.resolved).toEqual([]);expect(diff.unchecked).toEqual(['Dialog::Basic::aria-dialog-name']);});++ it('keeps baseline entries for unscanned stories of a routed owner unchecked', () => {+ const scopedReport = makeRoutedReport({+ owner: 'richtext/RichTextEditorToolbar',+ storyId: 'lab-richtexteditor--with-toolbar',+ component: 'RichTextEditor',+ story: 'With Toolbar',+ });+ const diff = diffAgainstBaseline(scopedReport, {+ version: 1,+ entries: RICH_TEXT_BASELINE_KEYS.map(key => ({key})),+ });++ expect(diff.resolved).toEqual([+ 'RichTextEditor::With Toolbar::aria-input-field-name',+ ]);+ expect(diff.unchecked).toHaveLength(12);+ expect(diff.unchecked).toContain(+ 'RichTextEditor::Default::aria-input-field-name',+ );+ });++ it('keeps colliding Core Tooltip baseline evidence outside a Charts-only audit', () => {+ const legacyStoryOwners = {+ 'Tooltip::Default': [+ 'core/Tooltip::core-tooltip--default',+ 'charts/ChartTooltip::charts-chrome-tooltip--default',+ ],+ };+ const scopedReport = makeRoutedReport({+ owner: 'charts/ChartTooltip',+ storyId: 'charts-chrome-tooltip--default',+ component: 'Tooltip',+ story: 'Default',+ legacyStoryOwners,+ });+ const legacyKey = 'Tooltip::Default::color-contrast';+ const coreKey =+ 'core/Tooltip::core-tooltip--default::color-contrast';+ const chartsKey =+ 'charts/ChartTooltip::charts-chrome-tooltip--default::color-contrast';+ const diff = diffAgainstBaseline(scopedReport, {+ version: 1,+ entries: [{key: legacyKey}, {key: coreKey}, {key: chartsKey}],+ });++ expect(diff.resolved).toEqual([chartsKey]);+ expect(diff.unchecked).toEqual([legacyKey, coreKey]);++ const violatingReport = makeRoutedReport({+ owner: 'charts/ChartTooltip',+ storyId: 'charts-chrome-tooltip--default',+ component: 'Tooltip',+ story: 'Default',+ violations: [axeViolation('color-contrast')],+ legacyStoryOwners,+ });+ const collisionDiff = diffAgainstBaseline(violatingReport, {+ version: 1,+ entries: [{key: legacyKey}],+ });+ expect(collisionDiff.newViolations.map(violation => violation.key)).toEqual([+ chartsKey,+ ]);+ expect(collisionDiff.unchecked).toEqual([legacyKey]);+ });++ it('keeps Core and Charts Tooltip distinct in a full audit', () => {+ const rows = [+ {+ owner: 'core/Tooltip',+ storyId: 'core-tooltip--default',+ component: 'Tooltip',+ story: 'Default',+ ruleId: 'color-contrast',+ },+ {+ owner: 'charts/ChartTooltip',+ storyId: 'charts-chrome-tooltip--default',+ component: 'Tooltip',+ story: 'Default',+ ruleId: 'color-contrast',+ },+ ];+ const report = makeMultiRoutedReport(rows);+ const legacyKey = 'Tooltip::Default::color-contrast';+ const diff = diffAgainstBaseline(report, {+ version: 1,+ entries: [{key: legacyKey}],+ });++ expect(diff.newViolations.map(violation => violation.key).sort()).toEqual(+ rows+ .map(row => `${row.owner}::${row.storyId}::${row.ruleId}`)+ .sort(),+ );+ expect(diff.resolved).toEqual([]);+ expect(diff.unchecked).toEqual([legacyKey]);+ });++ it('migrates proven same-package contract fixtures without new or resolved churn', () => {+ const rows = [+ {+ owner: 'core/ClickableCard',+ storyId: 'a11y-button-pattern--clickable-card-disabled',+ component: 'Button pattern',+ story: 'Clickable Card Disabled',+ ruleId: 'color-contrast',+ },+ {+ owner: 'core/CheckboxListItem',+ storyId:+ 'a11y-checkbox-pattern--list-item-group-disabled-with-message',+ component: 'Checkbox pattern',+ story: 'List Item Group Disabled With Message',+ ruleId: 'color-contrast',+ },+ {+ owner: 'core/SelectableCard',+ storyId: 'a11y-checkbox-pattern--card-disabled',+ component: 'Checkbox pattern',+ story: 'Card Disabled',+ ruleId: 'color-contrast',+ },+ {+ owner: 'core/RadioList',+ storyId:+ 'a11y-radio-group-pattern--radio-list-group-disabled-with-message',+ component: 'Radio group pattern',+ story: 'Radio List Group Disabled With Message',+ ruleId: 'color-contrast',+ },+ {+ owner: 'core/RadioListItem',+ storyId:+ 'a11y-radio-group-pattern--radio-list-option-group-disabled',+ component: 'Radio group pattern',+ story: 'Radio List Option Group Disabled',+ ruleId: 'color-contrast',+ },+ {+ owner: 'core/RadioListItem',+ storyId:+ 'a11y-radio-group-pattern--radio-list-option-disabled-with-message',+ component: 'Radio group pattern',+ story: 'Radio List Option Disabled With Message',+ ruleId: 'color-contrast',+ },+ ];+ const legacyBaselineAliases = {+ 'ClickableCard::Disabled': [+ 'core/ClickableCard::a11y-button-pattern--clickable-card-disabled',+ ],+ 'CheckboxList::Disabled With Message': [+ 'core/CheckboxListItem::a11y-checkbox-pattern--list-item-group-disabled-with-message',+ ],+ 'SelectableCard::Disabled': [+ 'core/SelectableCard::a11y-checkbox-pattern--card-disabled',+ ],+ 'RadioList::Disabled': [+ 'core/RadioListItem::a11y-radio-group-pattern--radio-list-option-group-disabled',+ ],+ 'RadioList::Disabled With Message': [+ 'core/RadioList::a11y-radio-group-pattern--radio-list-group-disabled-with-message',+ 'core/RadioListItem::a11y-radio-group-pattern--radio-list-option-disabled-with-message',+ ],+ };+ const report = makeMultiRoutedReport(rows, {legacyBaselineAliases});+ const legacyKeys = Object.keys(legacyBaselineAliases).map(key => ({+ key: `${key}::color-contrast`,+ }));+ const diff = diffAgainstBaseline(report, {version: 1, entries: legacyKeys});++ expect(diff.newViolations).toEqual([]);+ expect(diff.resolved).toEqual([]);+ expect(diff.matched).toBe(6);+ const migrated = buildBaseline(report, {+ existing: {version: 1, entries: legacyKeys},+ }).entries.map(entry => entry.key);+ expect(migrated).toEqual(+ rows+ .map(row => `${row.owner}::${row.storyId}::${row.ruleId}`)+ .sort(),+ );+ });});describe('buildBaseline', () => {@@ -221,6 +498,129 @@ describe('buildBaseline', () => {'Toast::Stacked::aria-live-region',]);});++ it('preserves unscanned stories when regenerating one routed owner story', () => {+ const existing = {+ version: 1,+ entries: RICH_TEXT_BASELINE_KEYS.map(key => ({key})),+ };+ const scopedReport = makeRoutedReport({+ owner: 'richtext/RichTextEditorToolbar',+ storyId: 'lab-richtexteditor--with-toolbar',+ component: 'RichTextEditor',+ story: 'With Toolbar',+ });+ const baseline = buildBaseline(scopedReport, {existing});++ expect(baseline.entries).toHaveLength(12);+ expect(baseline.entries.map(entry => entry.key)).not.toContain(+ 'RichTextEditor::With Toolbar::aria-input-field-name',+ );+ expect(baseline.entries.map(entry => entry.key)).toContain(+ 'RichTextEditor::Default::aria-input-field-name',+ );+ });++ it('migrates a full five-package baseline without false churn', () => {+ const rows = [+ {+ owner: 'core/Button',+ storyId: 'core-button--default',+ component: 'Button',+ story: 'Default',+ ruleId: 'button-name',+ },+ {+ owner: 'lab/CodeEditor',+ storyId: 'lab-codeeditor--python-editor',+ component: 'CodeEditor',+ story: 'Python Editor',+ ruleId: 'color-contrast',+ },+ {+ owner: 'charts/ChartLegend',+ storyId: 'charts-chrome-legend--default',+ component: 'Legend',+ story: 'Default',+ ruleId: 'color-contrast',+ },+ {+ owner: 'richtext/RichTextEditorToolbar',+ storyId: 'lab-richtexteditor--with-toolbar',+ component: 'RichTextEditor',+ story: 'With Toolbar',+ ruleId: 'aria-input-field-name',+ },+ {+ owner: 'vega/VegaChart',+ storyId: 'vega-vegachart--default',+ component: 'VegaChart',+ story: 'Default',+ ruleId: 'color-contrast',+ },+ {+ owner: 'core/Card',+ storyId: 'core-card--resolved',+ component: 'Card',+ story: 'Resolved',+ },+ ];+ const report = makeMultiRoutedReport(rows);+ const unchangedLegacyKeys = rows+ .filter(row => row.ruleId)+ .map(row => `${row.component}::${row.story}::${row.ruleId}`);+ const resolvedKey = 'Card::Resolved::color-contrast';+ const uncheckedKey = 'Dialog::Unaudited::aria-dialog-name';+ const existing = {+ version: 1,+ entries: [...unchangedLegacyKeys, resolvedKey, uncheckedKey].map(key => ({+ key,+ })),+ };++ const diff = diffAgainstBaseline(report, existing);+ expect(diff.newViolations).toEqual([]);+ expect(diff.resolved).toEqual([resolvedKey]);+ expect(diff.unchecked).toEqual([uncheckedKey]);+ expect(diff.matched).toBe(5);++ const migrated = buildBaseline(report, {existing}).entries.map(+ entry => entry.key,+ );+ expect(migrated).toEqual(+ [+ ...rows+ .filter(row => row.ruleId)+ .map(row => `${row.owner}::${row.storyId}::${row.ruleId}`),+ uncheckedKey,+ ].sort(),+ );+ });++ it('migrates a unique audited legacy key to package and story identity', () => {+ const legacyKey =+ 'RichTextEditor::With Toolbar::aria-input-field-name';+ const scopedReport = makeRoutedReport({+ owner: 'richtext/RichTextEditorToolbar',+ storyId: 'lab-richtexteditor--with-toolbar',+ component: 'RichTextEditor',+ story: 'With Toolbar',+ violations: [axeViolation('aria-input-field-name')],+ });+ const baseline = buildBaseline(scopedReport, {+ existing: {version: 1, entries: [{key: legacyKey}]},+ });++ expect(baseline.entries.map(entry => entry.key)).toEqual([+ 'richtext/RichTextEditorToolbar::lab-richtexteditor--with-toolbar::aria-input-field-name',+ ]);+ expect(+ diffAgainstBaseline(scopedReport, {+ version: 1,+ entries: [{key: legacyKey}],+ }).newViolations,+ ).toEqual([]);+ });});describe('formatDiffSummary', () => {diff --git a/.github/scripts/lib/a11y-story-identity.js b/.github/scripts/lib/a11y-story-identity.jsnew file mode 100644index 0000000000..fb3f540398--- /dev/null+++ b/.github/scripts/lib/a11y-story-identity.js@@ -0,0 +1,78 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use strict';+/* global module */++/**+ * @file Canonical owners and audited legacy-baseline aliases for a11y contract stories.+ * @input Stable Storybook IDs from the checked-in Button, Checkbox, and Radio inventories.+ * @output Canonical package owners plus exact prior baseline story identities.+ * @position Migration boundary between reusable contract fixtures and the a11y baseline.+ */++const A11Y_STORY_OWNER_PREFIXES = Object.freeze([+ ['a11y-button-pattern--icon-button-', 'core/IconButton'],+ ['a11y-button-pattern--clickable-card-', 'core/ClickableCard'],+ ['a11y-button-pattern--sidenav-collapse-', 'core/SideNavCollapseButton'],+ ['a11y-button-pattern--chat-send', 'core/ChatSendButton'],+ ['a11y-button-pattern--button-', 'core/Button'],+ ['a11y-checkbox-pattern--list-item-', 'core/CheckboxListItem'],+ ['a11y-checkbox-pattern--menu-item-', 'core/DropdownMenuCheckboxItem'],+ ['a11y-checkbox-pattern--card-', 'core/SelectableCard'],+ ['a11y-checkbox-pattern--input-', 'core/CheckboxInput'],+ ['a11y-radio-group-pattern--radio-list-group-', 'core/RadioList'],+ ['a11y-radio-group-pattern--radio-list-option-', 'core/RadioListItem'],+ ['a11y-radio-group-pattern--segmented-group-', 'core/SegmentedControl'],+ ['a11y-radio-group-pattern--segmented-option-', 'core/SegmentedControlItem'],+ ['a11y-radio-group-pattern--menu-group-', 'core/DropdownMenuRadioGroup'],+ ['a11y-radio-group-pattern--menu-option-', 'core/DropdownMenuRadioItem'],+]);++// These contract fixtures render the same disabled states already represented by+// the named legacy baseline stories. The mapping migrates identity only; it does+// not create a baseline for a rule or state that was not already recorded.+const LEGACY_BASELINE_STORY_MIGRATIONS = Object.freeze({+ 'a11y-button-pattern--clickable-card-disabled': Object.freeze({+ owner: 'core/ClickableCard',+ legacyStoryKeys: Object.freeze(['ClickableCard::Disabled']),+ }),+ 'a11y-checkbox-pattern--list-item-group-disabled-with-message': Object.freeze({+ owner: 'core/CheckboxListItem',+ legacyStoryKeys: Object.freeze(['CheckboxList::Disabled With Message']),+ }),+ 'a11y-checkbox-pattern--card-disabled': Object.freeze({+ owner: 'core/SelectableCard',+ legacyStoryKeys: Object.freeze(['SelectableCard::Disabled']),+ }),+ 'a11y-radio-group-pattern--radio-list-group-disabled-with-message': Object.freeze({+ owner: 'core/RadioList',+ legacyStoryKeys: Object.freeze(['RadioList::Disabled With Message']),+ }),+ 'a11y-radio-group-pattern--radio-list-option-group-disabled': Object.freeze({+ owner: 'core/RadioListItem',+ legacyStoryKeys: Object.freeze(['RadioList::Disabled']),+ }),+ 'a11y-radio-group-pattern--radio-list-option-disabled-with-message': Object.freeze({+ owner: 'core/RadioListItem',+ legacyStoryKeys: Object.freeze(['RadioList::Disabled With Message']),+ }),+});++function ownerForA11yStory(storyId) {+ const migration = LEGACY_BASELINE_STORY_MIGRATIONS[storyId];+ if (migration) return migration.owner;+ return A11Y_STORY_OWNER_PREFIXES.find(([prefix]) =>+ storyId.startsWith(prefix),+ )?.[1] ?? null;+}++function legacyBaselineStoryKeys(storyId) {+ return LEGACY_BASELINE_STORY_MIGRATIONS[storyId]?.legacyStoryKeys ?? [];+}++module.exports = {+ A11Y_STORY_OWNER_PREFIXES,+ LEGACY_BASELINE_STORY_MIGRATIONS,+ ownerForA11yStory,+ legacyBaselineStoryKeys,+};diff --git a/.github/scripts/lib/a11y-story-identity.test.mjs b/.github/scripts/lib/a11y-story-identity.test.mjsnew file mode 100644index 0000000000..6890e632cb--- /dev/null+++ b/.github/scripts/lib/a11y-story-identity.test.mjs@@ -0,0 +1,116 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import componentPackages from '../../../scripts/component-packages.cjs';+import {+ LEGACY_BASELINE_STORY_MIGRATIONS,+ legacyBaselineStoryKeys,+ ownerForA11yStory,+} from './a11y-story-identity.js';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');+const baseline = JSON.parse(+ fs.readFileSync(path.join(ROOT, '.github/a11y-baseline.json'), 'utf8'),+);+const baselineKeys = new Set(baseline.entries.map(entry => entry.key));++const EXPECTED_MIGRATIONS = [+ [+ 'ClickableCard::Disabled',+ 'core/ClickableCard',+ 'a11y-button-pattern--clickable-card-disabled',+ ],+ [+ 'CheckboxList::Disabled With Message',+ 'core/CheckboxListItem',+ 'a11y-checkbox-pattern--list-item-group-disabled-with-message',+ ],+ [+ 'SelectableCard::Disabled',+ 'core/SelectableCard',+ 'a11y-checkbox-pattern--card-disabled',+ ],+ [+ 'RadioList::Disabled With Message',+ 'core/RadioList',+ 'a11y-radio-group-pattern--radio-list-group-disabled-with-message',+ ],+ [+ 'RadioList::Disabled',+ 'core/RadioListItem',+ 'a11y-radio-group-pattern--radio-list-option-group-disabled',+ ],+ [+ 'RadioList::Disabled With Message',+ 'core/RadioListItem',+ 'a11y-radio-group-pattern--radio-list-option-disabled-with-message',+ ],+];++describe('a11y story identity migration', () => {+ it.each(EXPECTED_MIGRATIONS)(+ 'maps legacy %s to canonical %s::%s',+ (legacyStory, owner, storyId) => {+ expect(ownerForA11yStory(storyId)).toBe(owner);+ expect(legacyBaselineStoryKeys(storyId)).toContain(legacyStory);+ expect(baselineKeys.has(`${legacyStory}::color-contrast`)).toBe(true);+ const [packageName, componentName] = owner.split('/');+ expect(+ componentPackages.packageHasPublicComponent(+ ROOT,+ packageName,+ componentName,+ ),+ ).toBe(true);+ },+ );++ it('routes every pattern binding prefix to a canonical public owner', () => {+ for (const [prefix, owner] of [+ ['a11y-button-pattern--button-default', 'core/Button'],+ ['a11y-button-pattern--icon-button-default', 'core/IconButton'],+ [+ 'a11y-button-pattern--sidenav-collapse-icon',+ 'core/SideNavCollapseButton',+ ],+ ['a11y-button-pattern--chat-send', 'core/ChatSendButton'],+ ['a11y-checkbox-pattern--input-checked', 'core/CheckboxInput'],+ [+ 'a11y-checkbox-pattern--menu-item-checked',+ 'core/DropdownMenuCheckboxItem',+ ],+ [+ 'a11y-radio-group-pattern--segmented-group-selected-ltr',+ 'core/SegmentedControl',+ ],+ [+ 'a11y-radio-group-pattern--segmented-option-disabled',+ 'core/SegmentedControlItem',+ ],+ [+ 'a11y-radio-group-pattern--menu-group-selected',+ 'core/DropdownMenuRadioGroup',+ ],+ [+ 'a11y-radio-group-pattern--menu-option-disabled',+ 'core/DropdownMenuRadioItem',+ ],+ ]) {+ expect(ownerForA11yStory(prefix)).toBe(owner);+ }+ });++ it('contains only the six proven legacy migrations', () => {+ expect(Object.keys(LEGACY_BASELINE_STORY_MIGRATIONS).sort()).toEqual(+ EXPECTED_MIGRATIONS.map(([, , storyId]) => storyId).sort(),+ );+ expect(+ legacyBaselineStoryKeys(+ 'core-hooks-useresizable--structured-percent-sizing',+ ),+ ).toEqual([]);+ });+});diff --git a/.github/scripts/lib/a11y-story-readiness.js b/.github/scripts/lib/a11y-story-readiness.jsnew file mode 100644index 0000000000..fea73b7a68--- /dev/null+++ b/.github/scripts/lib/a11y-story-readiness.js@@ -0,0 +1,44 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use strict';+/* global module */++/**+ * @file Bounded readiness gate for one Storybook accessibility scan.+ * @input Repeated snapshots of URL, Storybook shell state, and root content.+ * @output Resolves only after the intended story has rendered; rejects redirects,+ * Storybook errors, and timeouts.+ * @position Pure timing policy used by accessibility-audit.js and unit tests.+ */++const defaultSleep = ms => new Promise(resolve => setTimeout(resolve, ms));++async function waitForStoryReadiness(+ readState,+ {+ timeoutMs = 5000,+ pollMs = 50,+ now = Date.now,+ sleep = defaultSleep,+ } = {},+) {+ const deadline = now() + timeoutMs;+ while (true) {+ const state = await readState();+ if (!state.urlMatches) {+ throw new Error(`story navigation ended at ${state.url}`);+ }+ if (state.errorVisible) {+ throw new Error('Storybook reported a story render error');+ }+ if (state.mainVisible && state.hasContent) {+ return;+ }+ if (now() >= deadline) {+ throw new Error('Storybook root did not render story content before timeout');+ }+ await sleep(pollMs);+ }+}++module.exports = {waitForStoryReadiness};diff --git a/.github/scripts/lib/a11y-story-readiness.test.mjs b/.github/scripts/lib/a11y-story-readiness.test.mjsnew file mode 100644index 0000000000..622f8c7417--- /dev/null+++ b/.github/scripts/lib/a11y-story-readiness.test.mjs@@ -0,0 +1,67 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {createRequire} from 'node:module';+import {describe, expect, it} from 'vitest';++const require = createRequire(import.meta.url);+const {waitForStoryReadiness} = require('./a11y-story-readiness.js');++function sequencedReader(states) {+ let index = 0;+ return async () => states[Math.min(index++, states.length - 1)];+}++const waiting = {+ url: 'http://localhost:6007/iframe.html?id=core-button--default',+ urlMatches: true,+ errorVisible: false,+ mainVisible: true,+ hasContent: false,+};++const ready = {...waiting, hasContent: true};++describe('waitForStoryReadiness', () => {+ it('waits for delayed story content instead of sampling the root once', async () => {+ let time = 0;+ const readState = sequencedReader([waiting, waiting, ready]);+ await expect(+ waitForStoryReadiness(readState, {+ timeoutMs: 5,+ pollMs: 0,+ now: () => time++,+ sleep: async () => {},+ }),+ ).resolves.toBeUndefined();+ });++ it('rejects a redirect away from the selected Storybook iframe', async () => {+ await expect(+ waitForStoryReadiness(+ async () => ({+ ...waiting,+ url: 'chrome-error://chromewebdata/',+ urlMatches: false,+ }),+ ),+ ).rejects.toThrow('story navigation ended at chrome-error://chromewebdata/');+ });++ it('rejects Storybook render errors before baseline reconciliation', async () => {+ await expect(+ waitForStoryReadiness(async () => ({...waiting, errorVisible: true})),+ ).rejects.toThrow('Storybook reported a story render error');+ });++ it('rejects a root that never renders within the bound', async () => {+ let time = 0;+ await expect(+ waitForStoryReadiness(async () => waiting, {+ timeoutMs: 2,+ pollMs: 0,+ now: () => time++,+ sleep: async () => {},+ }),+ ).rejects.toThrow('did not render story content before timeout');+ });+});diff --git a/.github/scripts/rtl-audit-cli.test.mjs b/.github/scripts/rtl-audit-cli.test.mjsnew file mode 100644index 0000000000..68211bbe1f--- /dev/null+++ b/.github/scripts/rtl-audit-cli.test.mjs@@ -0,0 +1,124 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {spawnSync} from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';++const SCRIPT = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../apps/storybook/rtl-audit/rtl-audit.mjs',+);++function runWithIndex(indexContent, {env = {}, timeout} = {}) {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rtl-audit-cli-'));+ const storybook = path.join(dir, 'storybook');+ const output = path.join(dir, 'rtl-audit-report.json');+ fs.mkdirSync(storybook, {recursive: true});+ if (indexContent !== null) {+ fs.writeFileSync(path.join(storybook, 'index.json'), indexContent);+ }+ // A previous successful result must never satisfy validation after this run.+ fs.writeFileSync(+ output,+ JSON.stringify({+ scope: {packages: ['charts'], filters: []},+ completion: {+ plannedComponentScans: 1,+ completedComponentScans: 1,+ plannedStoryScans: 1,+ completedPositionalScans: 1,+ completedDecorationScans: 1,+ },+ coverage: {total: 1},+ }),+ );+ try {+ const result = spawnSync(+ process.execPath,+ [+ SCRIPT,+ '--storybook-dir',+ storybook,+ '--output',+ output,+ '--packages',+ 'charts',+ '--concurrency',+ '1',+ ],+ {+ encoding: 'utf8',+ env: {...process.env, ...env},+ timeout,+ },+ );+ return {...result, reportExists: fs.existsSync(output)};+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+}++describe('RTL audit CLI input completion', () => {+ it.each([+ ['missing', null, 'cannot read index.json'],+ ['malformed', '{not json', 'cannot read index.json'],+ ['empty', '{"entries":{}}', 'no runnable audited stories'],+ ])(+ 'fails a %s index and removes stale report output',+ (_name, index, message) => {+ const result = runWithIndex(index);+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain(message);+ expect(result.reportExists).toBe(false);+ },+ );++ it('rejects an index with no runnable story for the requested package', () => {+ const result = runWithIndex(+ JSON.stringify({+ entries: {+ 'core-button--default': {+ id: 'core-button--default',+ title: 'Core/Button',+ type: 'story',+ },+ },+ }),+ );+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain(+ 'no runnable stories resolved for charts scope',+ );+ expect(result.reportExists).toBe(false);+ });++ it('closes the story server when Chromium cannot launch', () => {+ const result = runWithIndex(+ JSON.stringify({+ entries: {+ 'charts-legend--default': {+ id: 'charts-legend--default',+ title: 'Charts/ChartLegend',+ type: 'story',+ },+ },+ }),+ {+ env: {+ PLAYWRIGHT_BROWSERS_PATH: path.join(+ os.tmpdir(),+ 'missing-playwright-browsers',+ ),+ },+ timeout: 5000,+ },+ );+ expect(result.error).toBeUndefined();+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain('browserType.launch');+ expect(result.reportExists).toBe(false);+ });+});diff --git a/.github/scripts/rtl-audit-coverage.test.mjs b/.github/scripts/rtl-audit-coverage.test.mjsindex 4199e35b03..8de8fb913c 100644--- a/.github/scripts/rtl-audit-coverage.test.mjs+++ b/.github/scripts/rtl-audit-coverage.test.mjs@@ -4,16 +4,30 @@* @file Unit tests for RTL contextual decorations and applicability coverage.*/+import fs from 'node:fs';import {JSDOM} from 'jsdom';import {describe, expect, it} from 'vitest';+import componentPackages from '../../scripts/component-packages.cjs';import {+ AUDITED_PACKAGE_NAMES,+ AUDITED_STORY_PREFIXES,buildAuditedComponentRoster,buildComponentCoverage,+ buildStoryComponentRoutes,classifyDirectionalDecorationPair,classifyLogicalInlinePair,collectDirectionalDecorations,+ filterStoryRoutesByPackages,+ storyIdsForComponentFilters,+ unresolvedComponentFilters,} from '../../apps/storybook/rtl-audit/rtl-audit-coverage.mjs';+const {+ componentPackage,+ flatPackageComponentNames,+ nestedPackageComponentNames,+} = componentPackages;+const IDENTITY = [1, 0, 0, 1];const MIRROR = [-1, 0, 0, 1];@@ -340,3 +354,366 @@ describe('buildAuditedComponentRoster', () => {).toEqual(['unknown/missing']);});});++describe('audited package and story routing', () => {+ const publicComponentsByPackage = Object.fromEntries(+ AUDITED_PACKAGE_NAMES.map(packageName => {+ const pkg = componentPackage(packageName);+ const components =+ pkg.layout === 'flat'+ ? flatPackageComponentNames(process.cwd(), pkg)+ : nestedPackageComponentNames(process.cwd(), pkg);+ return [packageName, components];+ }),+ );+ const chartsComponents = publicComponentsByPackage.charts;+ const richTextComponents = publicComponentsByPackage.richtext;+ const vegaComponents = publicComponentsByPackage.vega;++ it('uses the canonical registry for all five component packages', () => {+ expect(chartsComponents).toEqual([+ 'Chart',+ 'ChartAxis',+ 'ChartGrid',+ 'ChartLegend',+ 'ChartSwatch',+ 'ChartTooltip',+ ]);+ expect(richTextComponents).toEqual([+ 'RichTextEditor',+ 'RichTextEditorAutoLinkPlugin',+ 'RichTextEditorToolbar',+ 'RichTextView',+ ]);+ expect(vegaComponents).toEqual(['VegaChart']);+ expect(AUDITED_PACKAGE_NAMES).toEqual([+ 'core',+ 'lab',+ 'charts',+ 'richtext',+ 'vega',+ ]);+ expect(AUDITED_STORY_PREFIXES).toEqual([+ 'core-',+ 'lab-',+ 'charts-',+ 'vega-',+ ]);+ });++ it('routes public owners across all five packages without losing aliases', () => {+ const routes = buildStoryComponentRoutes({+ stories: [+ {id: 'core-button--default', title: 'Core/Button'},+ {id: 'lab-chart--bar-chart', title: 'Lab/Chart'},+ {id: 'charts-chart--playground', title: 'Charts/Chart'},+ {id: 'charts-bar--simple', title: 'Charts/Bar'},+ {+ id: 'charts-chrome-legend--default',+ title: 'Charts/Chrome/Legend',+ },+ {+ id: 'charts-chrome-axes-grids--playground',+ title: 'Charts/Chrome/Axes & Grids',+ },+ {+ id: 'charts-chrome-swatch--gallery',+ title: 'Charts/Chrome/Swatch',+ },+ {+ id: 'charts-chrome-tooltip--default',+ title: 'Charts/Chrome/Tooltip',+ },+ {+ id: 'lab-richtexteditor--default',+ title: 'Lab/RichTextEditor',+ },+ {+ id: 'lab-richtexteditor--with-toolbar',+ title: 'Lab/RichTextEditor',+ },+ {+ id: 'lab-richtexteditor--with-auto-link',+ title: 'Lab/RichTextEditor',+ },+ {+ id: 'lab-richtexteditor--markdown-serializers',+ title: 'Lab/RichTextEditor',+ },+ {+ id: 'vega-vegachart--radial-plot',+ title: 'Vega/VegaChart',+ },+ ],+ targets: [+ {+ component: 'lab/Chart',+ storyId: 'lab-chart--bar-chart',+ },+ {+ component: 'ChartLegend',+ storyId: 'charts-chrome-legend--default',+ },+ {+ component: 'richtext/RichTextEditor',+ storyId: 'lab-richtexteditor--default',+ },+ {+ component: 'richtext/RichTextEditorToolbar',+ storyId: 'lab-richtexteditor--with-toolbar',+ },+ {+ component: 'richtext/RichTextEditorAutoLinkPlugin',+ storyId: 'lab-richtexteditor--with-auto-link',+ },+ {+ component: 'richtext/RichTextView',+ storyId: 'lab-richtexteditor--markdown-serializers',+ },+ ],+ publicComponentsByPackage,+ });++ expect(routes).toEqual([+ {id: 'core-button--default', component: 'core/Button'},+ {id: 'lab-chart--bar-chart', component: 'lab/Chart'},+ {id: 'charts-chart--playground', component: 'charts/Chart'},+ {id: 'charts-bar--simple', component: 'charts/Chart'},+ {+ id: 'charts-chrome-legend--default',+ component: 'charts/ChartLegend',+ },+ {+ id: 'charts-chrome-axes-grids--playground',+ component: 'charts/ChartAxis',+ },+ {+ id: 'charts-chrome-axes-grids--playground',+ component: 'charts/ChartGrid',+ },+ {+ id: 'charts-chrome-swatch--gallery',+ component: 'charts/ChartSwatch',+ },+ {+ id: 'charts-chrome-tooltip--default',+ component: 'charts/ChartTooltip',+ },+ {+ id: 'lab-richtexteditor--default',+ component: 'richtext/RichTextEditor',+ },+ {+ id: 'lab-richtexteditor--with-toolbar',+ component: 'richtext/RichTextEditorToolbar',+ },+ {+ id: 'lab-richtexteditor--with-auto-link',+ component: 'richtext/RichTextEditorAutoLinkPlugin',+ },+ {+ id: 'lab-richtexteditor--markdown-serializers',+ component: 'richtext/RichTextView',+ },+ {+ id: 'vega-vegachart--radial-plot',+ component: 'vega/VegaChart',+ },+ ]);++ const routesWithUnknown = [+ ...routes,+ {id: 'core-mystery--default', component: 'unknown/mystery'},+ ];+ const shardRoutes = Object.fromEntries(+ AUDITED_PACKAGE_NAMES.map(packageName => [+ packageName,+ filterStoryRoutesByPackages(routesWithUnknown, [packageName]),+ ]),+ );+ const routeKey = route => `${route.id}::${route.component}`;+ const assigned = Object.values(shardRoutes).flat().map(routeKey).sort();+ expect(assigned).toEqual(routesWithUnknown.map(routeKey).sort());+ expect(shardRoutes.richtext.map(routeKey)).toContain(+ 'lab-richtexteditor--with-toolbar::richtext/RichTextEditorToolbar',+ );+ expect(shardRoutes.lab.map(routeKey)).not.toContain(+ 'lab-richtexteditor--with-toolbar::richtext/RichTextEditorToolbar',+ );+ expect(shardRoutes.core.map(routeKey)).toContain(+ 'core-mystery--default::unknown/mystery',+ );++ const groupedOwners = [+ 'charts/ChartAxis',+ 'charts/ChartGrid',+ 'charts/ChartLegend',+ 'charts/ChartSwatch',+ 'charts/ChartTooltip',+ 'richtext/RichTextEditorAutoLinkPlugin',+ 'richtext/RichTextEditorToolbar',+ 'richtext/RichTextView',+ ];+ expect(storyIdsForComponentFilters(routes, groupedOwners)).toEqual([+ 'charts-chrome-legend--default',+ 'charts-chrome-axes-grids--playground',+ 'charts-chrome-swatch--gallery',+ 'charts-chrome-tooltip--default',+ 'lab-richtexteditor--with-toolbar',+ 'lab-richtexteditor--with-auto-link',+ 'lab-richtexteditor--markdown-serializers',+ ]);+ expect(unresolvedComponentFilters(routes, groupedOwners)).toEqual([]);+ expect(unresolvedComponentFilters(routes, ['charts/MissingOwner'])).toEqual(+ ['charts/MissingOwner'],+ );++ expect(+ buildAuditedComponentRoster({+ sourceComponents: [+ 'core/Button',+ 'lab/Chart',+ ...chartsComponents.map(component => `charts/${component}`),+ ...richTextComponents.map(component => `richtext/${component}`),+ ...vegaComponents.map(component => `vega/${component}`),+ ],+ storyComponents: routes.map(route => route.component),+ filters: [+ 'Button',+ 'Chart',+ ...chartsComponents.slice(1),+ ...richTextComponents,+ ...vegaComponents,+ ],+ }),+ ).toEqual([+ 'core/Button',+ 'lab/Chart',+ ...chartsComponents.map(component => `charts/${component}`),+ ...richTextComponents.map(component => `richtext/${component}`),+ ...vegaComponents.map(component => `vega/${component}`),+ ]);+ expect(+ buildAuditedComponentRoster({+ sourceComponents: [+ ...chartsComponents.map(component => `charts/${component}`),+ ...richTextComponents.map(component => `richtext/${component}`),+ ],+ storyComponents: routes.map(route => route.component),+ filters: groupedOwners,+ }),+ ).toEqual(groupedOwners);+ });++ it('routes every public Rich Text owner to a story that renders it', () => {+ const targets = JSON.parse(+ fs.readFileSync(+ new URL('../../apps/storybook/rtl-audit/targets.json', import.meta.url),+ 'utf8',+ ),+ );+ const routes = buildStoryComponentRoutes({+ stories: [+ {+ id: 'lab-richtexteditor--default',+ title: 'Lab/RichTextEditor',+ },+ {+ id: 'lab-richtexteditor--with-toolbar',+ title: 'Lab/RichTextEditor',+ },+ {+ id: 'lab-richtexteditor--with-auto-link',+ title: 'Lab/RichTextEditor',+ },+ {+ id: 'lab-richtexteditor--markdown-serializers',+ title: 'Lab/RichTextEditor',+ },+ ],+ targets,+ publicComponentsByPackage,+ });+ const owners = richTextComponents.map(component => `richtext/${component}`);+ expect(unresolvedComponentFilters(routes, owners)).toEqual([]);+ expect(storyIdsForComponentFilters(routes, owners)).toEqual([+ 'lab-richtexteditor--default',+ 'lab-richtexteditor--with-toolbar',+ 'lab-richtexteditor--with-auto-link',+ 'lab-richtexteditor--markdown-serializers',+ ]);+ });++ it('classifies measured Chart owners and verified direction-neutral owners without gaps', () => {+ const coverage = buildComponentCoverage({+ components: chartsComponents.map(component => `charts/${component}`),+ curatedResults: [+ {+ component: 'charts/Chart',+ storyId: 'charts-chart--playground',+ rollup: 'RTL-ready',+ },+ {+ component: 'charts/ChartLegend',+ storyId: 'charts-chrome-legend--default',+ rollup: 'RTL-ready',+ },+ ],+ verifiedNa: ['ChartAxis', 'ChartGrid', 'ChartSwatch', 'ChartTooltip'].map(+ component => ({+ component: `charts/${component}`,+ reason: 'Direction-neutral chart-space rendering.',+ }),+ ),+ });++ expect(coverage).toMatchObject({+ total: 6,+ measured: 2,+ verifiedNa: 4,+ gaps: 0,+ staleVerifiedNa: 0,+ });+ });++ it('classifies Rich Text and Vega owners without gaps or package aliases', () => {+ const components = [+ ...richTextComponents.map(component => `richtext/${component}`),+ ...vegaComponents.map(component => `vega/${component}`),+ ];+ const coverage = buildComponentCoverage({+ components,+ curatedResults: [+ {+ component: 'richtext/RichTextEditor',+ storyId: 'lab-richtexteditor--error-status',+ rollup: 'RTL-ready',+ },+ {+ component: 'richtext/RichTextEditorToolbar',+ storyId: 'lab-richtexteditor--with-toolbar',+ rollup: 'RTL-ready',+ },+ ],+ verifiedNa: [+ 'richtext/RichTextEditorAutoLinkPlugin',+ 'richtext/RichTextView',+ 'vega/VegaChart',+ ].map(component => ({+ component,+ reason: 'Direction-neutral rendering.',+ })),+ });++ expect(coverage).toMatchObject({+ total: 5,+ measured: 2,+ verifiedNa: 3,+ gaps: 0,+ staleVerifiedNa: 0,+ });+ expect(coverage.results.map(result => result.component)).toEqual(+ components,+ );+ });+});diff --git a/.github/scripts/rtl-join.mjs b/.github/scripts/rtl-join.mjsnew file mode 100644index 0000000000..02166d97c4--- /dev/null+++ b/.github/scripts/rtl-join.mjs@@ -0,0 +1,203 @@+#!/usr/bin/env node+// Copyright (c) Meta Platforms, Inc. and affiliates.++import fs from 'node:fs';+import path from 'node:path';+import {pathToFileURL} from 'node:url';+import componentPackages from '../../scripts/component-packages.cjs';++const {COMPONENT_PACKAGE_NAMES} = componentPackages;++/**+ * @file Fail-closed join policy for the pull-request RTL package matrix.+ * @input --check-components <result> --shards <result> --should-run <boolean>+ * --force-full <trusted-boolean> --reports-dir <path>+ * @output A successful exit only when classification succeeded and every+ * canonical shard declared scope and every applicable package produced its+ * own report.+ * @position Stable `pr-rtl` required-context join.+ */++function filesNamed(root, name) {+ if (!root || !fs.existsSync(root)) return [];+ const files = [];+ for (const entry of fs.readdirSync(root, {withFileTypes: true})) {+ const entryPath = path.join(root, entry.name);+ if (entry.isFile() && entry.name === name) files.push(entryPath);+ if (!entry.isDirectory()) continue;+ for (const child of fs.readdirSync(entryPath, {withFileTypes: true})) {+ if (child.isFile() && child.name === name) {+ files.push(path.join(entryPath, child.name));+ }+ }+ }+ return files;+}++export function readShardEvidence(reportsDir) {+ const scopes = [];+ const reports = [];+ const errors = [];+ for (const file of filesNamed(reportsDir, 'rtl-shard-scope.json')) {+ try {+ const scope = JSON.parse(fs.readFileSync(file, 'utf8'));+ if (+ !COMPONENT_PACKAGE_NAMES.includes(scope.package) ||+ typeof scope.shouldRun !== 'boolean' ||+ typeof scope.filter !== 'string'+ ) {+ throw new Error('invalid package, shouldRun, or filter');+ }+ scopes.push({+ package: scope.package,+ shouldRun: scope.shouldRun,+ filter: scope.filter,+ });+ } catch (error) {+ errors.push(`invalid scope manifest ${file}: ${error.message}`);+ }+ }+ for (const file of filesNamed(reportsDir, 'rtl-audit-report.json')) {+ try {+ const report = JSON.parse(fs.readFileSync(file, 'utf8'));+ if (+ !Array.isArray(report.scope?.packages) ||+ report.scope.packages.length !== 1 ||+ !COMPONENT_PACKAGE_NAMES.includes(report.scope.packages[0])+ ) {+ throw new Error('invalid package scope');+ }+ reports.push(report.scope.packages[0]);+ } catch (error) {+ errors.push(`invalid shard report ${file}: ${error.message}`);+ }+ }+ scopes.sort(+ (a, b) =>+ COMPONENT_PACKAGE_NAMES.indexOf(a.package) -+ COMPONENT_PACKAGE_NAMES.indexOf(b.package),+ );+ reports.sort(+ (a, b) =>+ COMPONENT_PACKAGE_NAMES.indexOf(a) - COMPONENT_PACKAGE_NAMES.indexOf(b),+ );+ return {scopes, reports, errors};+}++function sameSet(expected, actual) {+ return (+ new Set(expected).size === expected.length &&+ new Set(actual).size === actual.length &&+ JSON.stringify([...expected].sort()) === JSON.stringify([...actual].sort())+ );+}++export function evaluateRtlJoin({+ checkComponentsResult,+ shardResult,+ shouldRun,+ forceFull = false,+ evidence = {scopes: [], reports: [], errors: []},+}) {+ if (checkComponentsResult !== 'success') {+ return {+ ok: false,+ message: `component classification did not succeed: ${checkComponentsResult}`,+ };+ }+ if (forceFull && !shouldRun) {+ return {+ ok: false,+ message: 'Trusted full scope was not scheduled.',+ };+ }+ if (shouldRun) {+ if (shardResult !== 'success') {+ return {+ ok: false,+ message: `RTL package shards did not all succeed: ${shardResult}`,+ };+ }+ if (evidence.errors.length > 0) {+ return {ok: false, message: evidence.errors.join('; ')};+ }+ const scopePackages = evidence.scopes.map(scope => scope.package);+ if (!sameSet(COMPONENT_PACKAGE_NAMES, scopePackages)) {+ return {+ ok: false,+ message:+ 'RTL shard scope manifests are missing, duplicated, or unexpected.',+ };+ }+ if (+ forceFull &&+ evidence.scopes.some(scope => !scope.shouldRun || scope.filter !== '')+ ) {+ return {+ ok: false,+ message: 'Trusted full scope was narrowed by a package shard.',+ };+ }+ const expectedReports = evidence.scopes+ .filter(scope => scope.shouldRun)+ .map(scope => scope.package);+ if (expectedReports.length === 0) {+ return {+ ok: false,+ message: 'RTL scope required work, but every package shard skipped.',+ };+ }+ if (!sameSet(expectedReports, evidence.reports)) {+ return {+ ok: false,+ message: 'RTL shard reports do not match the applicable package set.',+ };+ }+ return {+ ok: true,+ message: 'All applicable RTL package shards produced reports.',+ };+ }+ return shardResult === 'skipped'+ ? {+ ok: true,+ message: 'No RTL-owned scope; package shards correctly skipped.',+ }+ : {+ ok: false,+ message: `RTL shards unexpectedly ran for an out-of-scope change: ${shardResult}`,+ };+}++function arg(name) {+ const index = process.argv.indexOf(`--${name}`);+ return index >= 0 ? process.argv[index + 1] : null;+}++function booleanArg(name) {+ const value = arg(name);+ if (value !== 'true' && value !== 'false') {+ throw new Error(`--${name} must be true or false`);+ }+ return value === 'true';+}++if (+ process.argv[1] &&+ import.meta.url === pathToFileURL(process.argv[1]).href+) {+ try {+ const result = evaluateRtlJoin({+ checkComponentsResult: arg('check-components'),+ shardResult: arg('shards'),+ shouldRun: booleanArg('should-run'),+ forceFull: booleanArg('force-full'),+ evidence: readShardEvidence(arg('reports-dir')),+ });+ (result.ok ? console.log : console.error)(result.message);+ if (!result.ok) process.exitCode = 1;+ } catch (error) {+ console.error(error.message);+ process.exitCode = 1;+ }+}diff --git a/.github/scripts/rtl-join.test.mjs b/.github/scripts/rtl-join.test.mjsnew file mode 100644index 0000000000..c7ca535279--- /dev/null+++ b/.github/scripts/rtl-join.test.mjs@@ -0,0 +1,227 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {spawnSync} from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import componentPackages from '../../scripts/component-packages.cjs';+import {evaluateRtlJoin, readShardEvidence} from './rtl-join.mjs';++const {COMPONENT_PACKAGE_NAMES} = componentPackages;+const SCRIPT = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ 'rtl-join.mjs',+);++function completeEvidence(applicable = [...COMPONENT_PACKAGE_NAMES]) {+ return {+ scopes: COMPONENT_PACKAGE_NAMES.map(packageName => ({+ package: packageName,+ shouldRun: applicable.includes(packageName),+ filter: '',+ })),+ reports: [...applicable],+ errors: [],+ };+}++function evaluate(overrides = {}) {+ return evaluateRtlJoin({+ checkComponentsResult: 'success',+ shardResult: 'success',+ shouldRun: true,+ evidence: completeEvidence(['charts']),+ ...overrides,+ });+}++describe('RTL matrix join', () => {+ it('accepts exact evidence for the applicable package set', () => {+ expect(evaluate()).toEqual({+ ok: true,+ message: 'All applicable RTL package shards produced reports.',+ });+ });++ it.each([+ ['failure', 'success'],+ ['cancelled', 'success'],+ ['success', 'failure'],+ ['success', 'cancelled'],+ ['success', 'skipped'],+ ])(+ 'rejects classification=%s shards=%s when work is required',+ (checkComponentsResult, shardResult) => {+ expect(evaluate({checkComponentsResult, shardResult}).ok).toBe(false);+ },+ );++ it('binds trusted full scope to five runnable empty-filter shards', () => {+ expect(+ evaluate({forceFull: true, evidence: completeEvidence(['charts'])}),+ ).toEqual({+ ok: false,+ message: 'Trusted full scope was narrowed by a package shard.',+ });+ expect(evaluate({forceFull: true, evidence: completeEvidence()}).ok).toBe(+ true,+ );+ const filtered = completeEvidence();+ filtered.scopes[0].filter = 'core/Button';+ expect(evaluate({forceFull: true, evidence: filtered}).ok).toBe(false);+ });++ it('accepts the no-scope skipped state only after classification succeeds', () => {+ expect(+ evaluateRtlJoin({+ checkComponentsResult: 'success',+ shardResult: 'skipped',+ shouldRun: false,+ }),+ ).toEqual({+ ok: true,+ message: 'No RTL-owned scope; package shards correctly skipped.',+ });+ expect(+ evaluateRtlJoin({+ checkComponentsResult: 'success',+ shardResult: 'skipped',+ shouldRun: false,+ forceFull: true,+ }).ok,+ ).toBe(false);+ expect(+ evaluateRtlJoin({+ checkComponentsResult: 'failure',+ shardResult: 'skipped',+ shouldRun: false,+ }).ok,+ ).toBe(false);+ expect(+ evaluateRtlJoin({+ checkComponentsResult: 'success',+ shardResult: 'success',+ shouldRun: false,+ }).ok,+ ).toBe(false);+ });++ it('rejects all-skipped manifests when trusted scope requires work', () => {+ expect(evaluate({evidence: completeEvidence([])})).toEqual({+ ok: false,+ message: 'RTL scope required work, but every package shard skipped.',+ });+ });++ it.each([0, 1, 4])(+ 'rejects %i reports when all five packages are applicable',+ reportCount => {+ const evidence = completeEvidence();+ evidence.reports = COMPONENT_PACKAGE_NAMES.slice(0, reportCount);+ expect(evaluate({evidence}).ok).toBe(false);+ },+ );++ it('accepts exactly five reports when all five packages are applicable', () => {+ expect(evaluate({evidence: completeEvidence()}).ok).toBe(true);+ });++ it('rejects duplicate, missing, and unexpected report packages', () => {+ const duplicate = completeEvidence(['charts']);+ duplicate.reports.push('charts');+ expect(evaluate({evidence: duplicate}).ok).toBe(false);++ const missing = completeEvidence(['charts', 'core']);+ missing.reports = ['charts'];+ expect(evaluate({evidence: missing}).ok).toBe(false);++ const unexpected = completeEvidence(['charts']);+ unexpected.reports.push('core');+ expect(evaluate({evidence: unexpected}).ok).toBe(false);+ });++ it('rejects missing, duplicate, and malformed scope manifests', () => {+ const missing = completeEvidence(['charts']);+ missing.scopes.pop();+ expect(evaluate({evidence: missing}).ok).toBe(false);++ const duplicate = completeEvidence(['charts']);+ duplicate.scopes.push({+ package: 'charts',+ shouldRun: true,+ filter: '',+ });+ expect(evaluate({evidence: duplicate}).ok).toBe(false);++ expect(+ evaluate({+ evidence: {+ ...completeEvidence(['charts']),+ errors: ['invalid scope manifest'],+ },+ }).ok,+ ).toBe(false);+ });++ it('reads nested scope and report artifacts with package identity', () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rtl-join-evidence-'));+ try {+ for (const packageName of COMPONENT_PACKAGE_NAMES) {+ const shard = path.join(dir, `rtl-audit-report-${packageName}`);+ fs.mkdirSync(shard);+ fs.writeFileSync(+ path.join(shard, 'rtl-shard-scope.json'),+ JSON.stringify({+ package: packageName,+ shouldRun: packageName === 'charts',+ filter: '',+ }),+ );+ if (packageName === 'charts') {+ fs.writeFileSync(+ path.join(shard, 'rtl-audit-report.json'),+ JSON.stringify({scope: {packages: ['charts']}}),+ );+ }+ }+ expect(readShardEvidence(dir)).toEqual(completeEvidence(['charts']));+ const narrowedFullScope = spawnSync(+ process.execPath,+ [+ SCRIPT,+ '--check-components',+ 'success',+ '--shards',+ 'success',+ '--should-run',+ 'true',+ '--force-full',+ 'true',+ '--reports-dir',+ dir,+ ],+ {encoding: 'utf8'},+ );+ expect(narrowedFullScope.status).not.toBe(0);+ expect(narrowedFullScope.stderr).toContain(+ 'Trusted full scope was narrowed',+ );+ fs.writeFileSync(+ path.join(dir, 'rtl-audit-report-charts', 'rtl-audit-report.json'),+ JSON.stringify({scope: {packages: ['unknown']}}),+ );+ expect(readShardEvidence(dir).errors[0]).toContain(+ 'invalid shard report',+ );+ expect(readShardEvidence(path.join(dir, 'missing'))).toEqual({+ scopes: [],+ reports: [],+ errors: [],+ });+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });+});diff --git a/.github/scripts/rtl-report-completion.mjs b/.github/scripts/rtl-report-completion.mjsnew file mode 100644index 0000000000..8f4180b7c8--- /dev/null+++ b/.github/scripts/rtl-report-completion.mjs@@ -0,0 +1,189 @@+#!/usr/bin/env node+// Copyright (c) Meta Platforms, Inc. and affiliates.++import fs from 'node:fs';+import {pathToFileURL} from 'node:url';++/**+ * @file Hard completion contract for one RTL package-shard report.+ * @input --report <path> --package <canonical-name> --filter <csv-or-empty>+ * @output Exit zero only when requested scope and planned/completed scans match.+ * @position Boundary between soft RTL findings and the required `pr-rtl` join.+ */++function expectedFilters(filter) {+ return (filter ?? '')+ .split(',')+ .map(value => value.trim().toLowerCase())+ .filter(Boolean);+}++function sameIdentitySet(planned, completed) {+ if (+ !Array.isArray(planned) ||+ !Array.isArray(completed) ||+ planned.length === 0+ ) {+ return false;+ }+ if (+ new Set(planned).size !== planned.length ||+ new Set(completed).size !== completed.length+ ) {+ return false;+ }+ return (+ JSON.stringify([...planned].sort()) ===+ JSON.stringify([...completed].sort())+ );+}++function successfulResultIdentities(results) {+ if (!Array.isArray(results)) return null;+ const identities = [];+ for (const result of results) {+ if (+ result == null ||+ typeof result.component !== 'string' ||+ typeof result.storyId !== 'string' ||+ !['pass', 'fail', 'N-A'].includes(result.verdict)+ ) {+ return null;+ }+ identities.push(`${result.component}::${result.storyId}`);+ }+ return identities;+}++export function validateRtlReport(report, {packageName, filter = ''}) {+ const fail = message => ({ok: false, message});+ if (report == null || typeof report !== 'object' || Array.isArray(report)) {+ return fail('RTL shard report is not a JSON object');+ }+ if (+ !Array.isArray(report.scope?.packages) ||+ report.scope.packages.length !== 1 ||+ report.scope.packages[0] !== packageName+ ) {+ return fail(`RTL shard report package does not match ${packageName}`);+ }+ const filters = expectedFilters(filter);+ if (+ !Array.isArray(report.scope?.filters) ||+ JSON.stringify(report.scope.filters) !== JSON.stringify(filters)+ ) {+ return fail('RTL shard report filter scope does not match the request');+ }+ const completion = report.completion;+ if (+ !Number.isInteger(completion?.plannedComponentScans) ||+ completion.plannedComponentScans <= 0 ||+ completion.completedComponentScans !== completion.plannedComponentScans+ ) {+ return fail('RTL component scan count is missing or incomplete');+ }+ if (+ !Number.isInteger(completion?.plannedStoryScans) ||+ completion.plannedStoryScans <= 0 ||+ completion.completedPositionalScans !== completion.plannedStoryScans ||+ completion.completedDecorationScans !== completion.plannedStoryScans+ ) {+ return fail('RTL story scan count is missing, zero, or incomplete');+ }+ if (+ !sameIdentitySet(+ completion.plannedComponentIdentities,+ completion.completedComponentIdentities,+ )+ ) {+ return fail(+ 'RTL component identity set is missing, duplicated, or substituted',+ );+ }+ if (+ !sameIdentitySet(+ completion.plannedD1Identities,+ completion.completedD1Identities,+ )+ ) {+ return fail('RTL D1 identity set is missing, duplicated, or substituted');+ }+ if (+ !sameIdentitySet(+ completion.plannedStoryIdentities,+ completion.completedPositionalIdentities,+ ) ||+ !sameIdentitySet(+ completion.plannedStoryIdentities,+ completion.completedDecorationIdentities,+ )+ ) {+ return fail(+ 'RTL story identity set is missing, duplicated, or substituted',+ );+ }+ const d1Results = successfulResultIdentities(report.autoDiscovery?.results);+ if (+ d1Results == null ||+ !sameIdentitySet(completion.plannedD1Identities, d1Results) ||+ !sameIdentitySet(+ completion.plannedComponentIdentities,+ report.autoDiscovery.results.map(result => result.component),+ )+ ) {+ return fail('RTL D1 results are missing, unsuccessful, or out of scope');+ }+ const positionalResults = successfulResultIdentities(+ report.positionalMirror?.results,+ );+ if (+ positionalResults == null ||+ !sameIdentitySet(completion.plannedStoryIdentities, positionalResults)+ ) {+ return fail('RTL D5 results are missing, unsuccessful, or out of scope');+ }+ const decorationResults = successfulResultIdentities(+ report.directionalDecorations?.results,+ );+ if (+ decorationResults == null ||+ !sameIdentitySet(completion.plannedStoryIdentities, decorationResults)+ ) {+ return fail('RTL D6 results are missing, unsuccessful, or out of scope');+ }+ if (!Number.isInteger(report.coverage?.total) || report.coverage.total <= 0) {+ return fail('RTL coverage roster is empty');+ }+ if (report.coverage.registryError != null) {+ return fail(+ `RTL coverage registry failed: ${report.coverage.registryError}`,+ );+ }+ return {ok: true, message: `Completed RTL evidence for ${packageName}.`};+}++function arg(name) {+ const index = process.argv.indexOf(`--${name}`);+ return index >= 0 ? process.argv[index + 1] : null;+}++if (+ process.argv[1] &&+ import.meta.url === pathToFileURL(process.argv[1]).href+) {+ let report;+ try {+ report = JSON.parse(fs.readFileSync(arg('report'), 'utf8'));+ } catch (error) {+ console.error(`Could not read RTL shard report: ${error.message}`);+ process.exitCode = 1;+ }+ if (report !== undefined) {+ const result = validateRtlReport(report, {+ packageName: arg('package'),+ filter: arg('filter') ?? '',+ });+ (result.ok ? console.log : console.error)(result.message);+ if (!result.ok) process.exitCode = 1;+ }+}diff --git a/.github/scripts/rtl-report-completion.test.mjs b/.github/scripts/rtl-report-completion.test.mjsnew file mode 100644index 0000000000..531f443a2f--- /dev/null+++ b/.github/scripts/rtl-report-completion.test.mjs@@ -0,0 +1,277 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {spawnSync} from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import {validateRtlReport} from './rtl-report-completion.mjs';++const SCRIPT = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ 'rtl-report-completion.mjs',+);++function completeReport() {+ return {+ scope: {packages: ['charts'], filters: ['charts/chartlegend']},+ completion: {+ plannedComponentScans: 1,+ completedComponentScans: 1,+ plannedStoryScans: 2,+ completedPositionalScans: 2,+ completedDecorationScans: 2,+ plannedComponentIdentities: ['charts/ChartLegend'],+ completedComponentIdentities: ['charts/ChartLegend'],+ plannedD1Identities: ['charts/ChartLegend::charts-legend--default'],+ completedD1Identities: ['charts/ChartLegend::charts-legend--default'],+ plannedStoryIdentities: [+ 'charts/ChartLegend::charts-legend--default',+ 'charts/ChartLegend::charts-legend--many-items',+ ],+ completedPositionalIdentities: [+ 'charts/ChartLegend::charts-legend--default',+ 'charts/ChartLegend::charts-legend--many-items',+ ],+ completedDecorationIdentities: [+ 'charts/ChartLegend::charts-legend--default',+ 'charts/ChartLegend::charts-legend--many-items',+ ],+ },+ autoDiscovery: {+ results: [+ {+ component: 'charts/ChartLegend',+ storyId: 'charts-legend--default',+ verdict: 'pass',+ },+ ],+ },+ positionalMirror: {+ results: [+ {+ component: 'charts/ChartLegend',+ storyId: 'charts-legend--default',+ verdict: 'fail',+ },+ {+ component: 'charts/ChartLegend',+ storyId: 'charts-legend--many-items',+ verdict: 'N-A',+ },+ ],+ },+ directionalDecorations: {+ results: [+ {+ component: 'charts/ChartLegend',+ storyId: 'charts-legend--default',+ verdict: 'pass',+ },+ {+ component: 'charts/ChartLegend',+ storyId: 'charts-legend--many-items',+ verdict: 'N-A',+ },+ ],+ },+ coverage: {total: 1},+ };+}++describe('RTL report completion contract', () => {+ it('accepts exact requested scope with nonzero completed scans', () => {+ expect(+ validateRtlReport(completeReport(), {+ packageName: 'charts',+ filter: 'charts/ChartLegend',+ }),+ ).toEqual({ok: true, message: 'Completed RTL evidence for charts.'});+ });++ it.each([+ [+ 'wrong package',+ report => {+ report.scope.packages = ['core'];+ },+ ],+ [+ 'stale filter',+ report => {+ report.scope.filters = [];+ },+ ],+ [+ 'zero planned components',+ report => {+ report.completion.plannedComponentScans = 0;+ report.completion.completedComponentScans = 0;+ },+ ],+ [+ 'incomplete component scans',+ report => {+ report.completion.completedComponentScans = 0;+ },+ ],+ [+ 'zero planned stories',+ report => {+ report.completion.plannedStoryScans = 0;+ report.completion.completedPositionalScans = 0;+ report.completion.completedDecorationScans = 0;+ },+ ],+ [+ 'incomplete positional scans',+ report => {+ report.completion.completedPositionalScans = 1;+ },+ ],+ [+ 'incomplete decoration scans',+ report => {+ report.completion.completedDecorationScans = 1;+ },+ ],+ [+ 'duplicate component identities',+ report => {+ report.completion.completedComponentIdentities = [+ 'charts/ChartLegend',+ 'charts/ChartLegend',+ ];+ },+ ],+ [+ 'substituted D1 identity',+ report => {+ report.completion.completedD1Identities[0] =+ 'charts/ChartLegend::charts-legend--substitute';+ },+ ],+ [+ 'missing story identity',+ report => {+ report.completion.completedPositionalIdentities.pop();+ },+ ],+ [+ 'substituted story identity',+ report => {+ report.completion.completedDecorationIdentities[1] =+ 'charts/ChartLegend::charts-legend--substitute';+ },+ ],+ [+ 'unexpected story identity',+ report => {+ report.completion.completedPositionalIdentities.push(+ 'charts/ChartLegend::charts-legend--unexpected',+ );+ },+ ],+ [+ 'D1 ERROR result',+ report => {+ report.autoDiscovery.results[0].verdict = 'ERROR';+ },+ ],+ [+ 'D5 ERROR result',+ report => {+ report.positionalMirror.results[0].verdict = 'ERROR';+ },+ ],+ [+ 'D6 ERROR result',+ report => {+ report.directionalDecorations.results[0].verdict = 'ERROR';+ },+ ],+ [+ 'empty coverage roster',+ report => {+ report.coverage.total = 0;+ },+ ],+ [+ 'registry error',+ report => {+ report.coverage.registryError = 'bad registry';+ },+ ],+ ])('rejects %s', (_name, mutate) => {+ const report = completeReport();+ mutate(report);+ expect(+ validateRtlReport(report, {+ packageName: 'charts',+ filter: 'charts/ChartLegend',+ }).ok,+ ).toBe(false);+ });++ it.each([+ ['missing', null],+ ['malformed', '{not json'],+ ])('CLI rejects a %s report', (_name, content) => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rtl-report-'));+ const report = path.join(dir, 'report.json');+ try {+ if (content !== null) fs.writeFileSync(report, content);+ const result = spawnSync(+ process.execPath,+ [+ SCRIPT,+ '--report',+ report,+ '--package',+ 'charts',+ '--filter',+ 'charts/ChartLegend',+ ],+ {encoding: 'utf8'},+ );+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain('Could not read RTL shard report');+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });++ it('CLI rejects a report whose planned scans all errored', () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rtl-report-error-'));+ const reportPath = path.join(dir, 'report.json');+ try {+ const report = completeReport();+ for (const section of [+ report.autoDiscovery,+ report.positionalMirror,+ report.directionalDecorations,+ ]) {+ for (const result of section.results) result.verdict = 'ERROR';+ }+ fs.writeFileSync(reportPath, JSON.stringify(report));+ const result = spawnSync(+ process.execPath,+ [+ SCRIPT,+ '--report',+ reportPath,+ '--package',+ 'charts',+ '--filter',+ 'charts/ChartLegend',+ ],+ {encoding: 'utf8'},+ );+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain('results are missing, unsuccessful');+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });+});diff --git a/.github/scripts/rtl-shard-scope.mjs b/.github/scripts/rtl-shard-scope.mjsnew file mode 100644index 0000000000..9413e83716--- /dev/null+++ b/.github/scripts/rtl-shard-scope.mjs@@ -0,0 +1,237 @@+#!/usr/bin/env node+// Copyright (c) Meta Platforms, Inc. and affiliates.++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath, pathToFileURL} from 'node:url';+import componentPackages from '../../scripts/component-packages.cjs';++/**+ * @file Strict per-package scope resolver for the pull-request RTL matrix.+ * @input Trusted classifier booleans, one canonical package, and analysis.json.+ * @output GitHub step outputs describing whether and how that shard must run.+ * @position Hard-fail setup step before the soft audit-findings step.+ */++const {COMPONENT_PACKAGE_NAMES, packageHasPublicComponent} = componentPackages;+const PROJECT_ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../..',+);++const HARNESS_SMOKE_OWNERS = {+ lab: ['lab/Chart'],+ charts: ['charts/Chart', 'charts/ChartLegend'],+};++function ownerArray(analysis, qualifiedKey, legacyKey) {+ const qualified = analysis[qualifiedKey];+ if (qualified != null) {+ if (+ !Array.isArray(qualified) ||+ qualified.some(value => typeof value !== 'string')+ ) {+ throw new Error(`${qualifiedKey} must be an array of strings`);+ }+ return {owners: qualified, qualified: true};+ }+ const legacy = analysis[legacyKey] ?? [];+ if (+ !Array.isArray(legacy) ||+ legacy.some(value => typeof value !== 'string')+ ) {+ throw new Error(`${legacyKey} must be an array of strings`);+ }+ return {owners: legacy, qualified: false};+}++function isCanonicalOwner(owner) {+ const separator = owner.indexOf('/');+ if (separator <= 0 || owner.indexOf('/', separator + 1) !== -1) return false;+ const packageName = owner.slice(0, separator);+ const componentName = owner.slice(separator + 1);+ return (+ COMPONENT_PACKAGE_NAMES.includes(packageName) &&+ packageHasPublicComponent(PROJECT_ROOT, packageName, componentName)+ );+}++export function readAnalysis(analysisPath) {+ let analysis;+ try {+ analysis = JSON.parse(fs.readFileSync(analysisPath, 'utf8'));+ } catch (error) {+ throw new Error(`Could not read analysis artifact: ${error.message}`, {+ cause: error,+ });+ }+ if (+ analysis == null ||+ typeof analysis !== 'object' ||+ Array.isArray(analysis)+ ) {+ throw new Error('Analysis artifact must be a JSON object');+ }+ const added = ownerArray(analysis, 'newComponentOwners', 'newComponents');+ const modified = ownerArray(+ analysis,+ 'modifiedComponentOwners',+ 'modifiedComponents',+ );+ const owners = [...added.owners, ...modified.owners];+ if (+ analysis.forceFullComponentAudits !== undefined &&+ typeof analysis.forceFullComponentAudits !== 'boolean'+ ) {+ throw new Error('Analysis forceFullComponentAudits must be a boolean');+ }+ if (owners.some(owner => owner.includes('\n') || owner.includes('\r'))) {+ throw new Error('Analysis owner values must not contain line breaks');+ }+ const qualified = added.qualified && modified.qualified;+ return {+ owners,+ qualified,+ forceFullComponentAudits: analysis.forceFullComponentAudits === true,+ invalidOwners: qualified+ ? owners.filter(owner => !isCanonicalOwner(owner))+ : [],+ };+}++export function resolveRtlShardScope({+ packageName,+ forceFull,+ hasComponents,+ hasHarness,+ analysis,+}) {+ if (!COMPONENT_PACKAGE_NAMES.includes(packageName)) {+ throw new Error(`Invalid canonical package name: ${packageName}`);+ }+ const full = reason => ({+ shouldRun: true,+ components: `full ${packageName} roster`,+ filter: '',+ reason,+ });+ if (forceFull) return full('policy-sensitive scope');+ if (analysis.forceFullComponentAudits) {+ return full('unresolved canonical component source');+ }+ if ((analysis.invalidOwners ?? []).length > 0) {+ return full('noncanonical component scope');+ }+ if (!analysis.qualified && analysis.owners.length > 0) {+ return full('unqualified component scope');+ }+ if (analysis.owners.length === 0 && hasComponents) {+ return full('unresolved component scope');+ }+ if (analysis.owners.length === 0 && hasHarness) {+ const owners = HARNESS_SMOKE_OWNERS[packageName] ?? [];+ return owners.length > 0+ ? {+ shouldRun: true,+ components: owners.join(','),+ filter: owners.join(','),+ reason: 'routing smoke scope',+ }+ : {+ shouldRun: false,+ components: '',+ filter: '',+ reason: 'no routing-smoke owner in package',+ };+ }+ if (analysis.owners.length > 0) {+ const owners = analysis.owners.filter(owner =>+ owner.startsWith(`${packageName}/`),+ );+ return owners.length > 0+ ? {+ shouldRun: true,+ components: [...new Set(owners)].join(','),+ filter: [...new Set(owners)].join(','),+ reason: 'changed owner scope',+ }+ : {+ shouldRun: false,+ components: '',+ filter: '',+ reason: 'no changed owner in package',+ };+ }+ return {+ shouldRun: false,+ components: '',+ filter: '',+ reason: 'no component or RTL harness changes',+ };+}++function arg(name) {+ const index = process.argv.indexOf(`--${name}`);+ return index >= 0 ? process.argv[index + 1] : null;+}++function booleanArg(name) {+ const value = arg(name);+ if (value !== 'true' && value !== 'false') {+ throw new Error(`--${name} must be true or false`);+ }+ return value === 'true';+}++function writeGithubOutputs(outputPath, scope) {+ if (!outputPath) throw new Error('--github-output is required');+ fs.appendFileSync(+ outputPath,+ [+ `should_run=${scope.shouldRun}`,+ `components=${scope.components}`,+ `filter=${scope.filter}`,+ `reason=${scope.reason}`,+ '',+ ].join('\n'),+ );+}++function writeScopeManifest(manifestPath, packageName, scope) {+ if (!manifestPath) return;+ fs.writeFileSync(+ manifestPath,+ JSON.stringify(+ {+ package: packageName,+ shouldRun: scope.shouldRun,+ filter: scope.filter,+ },+ null,+ 2,+ ),+ );+}++if (+ process.argv[1] &&+ import.meta.url === pathToFileURL(process.argv[1]).href+) {+ try {+ const analysis = readAnalysis(arg('analysis'));+ const packageName = arg('package');+ const scope = resolveRtlShardScope({+ packageName,+ forceFull: booleanArg('force-full'),+ hasComponents: booleanArg('has-components'),+ hasHarness: booleanArg('has-harness'),+ analysis,+ });+ writeGithubOutputs(arg('github-output'), scope);+ writeScopeManifest(arg('manifest'), packageName, scope);+ console.log(`${scope.reason}: ${scope.components || 'not applicable'}`);+ } catch (error) {+ console.error(error.message);+ process.exitCode = 1;+ }+}diff --git a/.github/scripts/rtl-shard-scope.test.mjs b/.github/scripts/rtl-shard-scope.test.mjsnew file mode 100644index 0000000000..d74a517708--- /dev/null+++ b/.github/scripts/rtl-shard-scope.test.mjs@@ -0,0 +1,279 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {spawnSync} from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import componentPackages from '../../scripts/component-packages.cjs';+import {readAnalysis, resolveRtlShardScope} from './rtl-shard-scope.mjs';++const {COMPONENT_PACKAGE_NAMES} = componentPackages;+const SCRIPT = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ 'rtl-shard-scope.mjs',+);+const qualifiedAnalysis = {+ owners: ['charts/ChartLegend', 'core/Button'],+ qualified: true,+};++function runCli(analysisText) {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rtl-shard-scope-'));+ const analysis = path.join(dir, 'analysis.json');+ const output = path.join(dir, 'github-output');+ const manifest = path.join(dir, 'scope.json');+ try {+ if (analysisText !== null) fs.writeFileSync(analysis, analysisText);+ const result = spawnSync(+ process.execPath,+ [+ SCRIPT,+ '--analysis',+ analysis,+ '--package',+ 'charts',+ '--force-full',+ 'false',+ '--has-components',+ 'true',+ '--has-harness',+ 'false',+ '--manifest',+ manifest,+ '--github-output',+ output,+ ],+ {encoding: 'utf8'},+ );+ return {+ ...result,+ output: fs.existsSync(output) ? fs.readFileSync(output, 'utf8') : '',+ manifest: fs.existsSync(manifest)+ ? JSON.parse(fs.readFileSync(manifest, 'utf8'))+ : null,+ };+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+}++describe('RTL shard scope', () => {+ it('selects only owners from the current package', () => {+ expect(+ resolveRtlShardScope({+ packageName: 'charts',+ forceFull: false,+ hasComponents: true,+ hasHarness: false,+ analysis: qualifiedAnalysis,+ }),+ ).toMatchObject({+ shouldRun: true,+ components: 'charts/ChartLegend',+ filter: 'charts/ChartLegend',+ });+ });++ it('skips a package with no changed owner', () => {+ expect(+ resolveRtlShardScope({+ packageName: 'vega',+ forceFull: false,+ hasComponents: true,+ hasHarness: false,+ analysis: qualifiedAnalysis,+ }),+ ).toMatchObject({shouldRun: false});+ });++ it('runs the full package for policy-sensitive scope', () => {+ expect(+ resolveRtlShardScope({+ packageName: 'vega',+ forceFull: true,+ hasComponents: true,+ hasHarness: false,+ analysis: {owners: [], qualified: true},+ }),+ ).toMatchObject({+ shouldRun: true,+ components: 'full vega roster',+ filter: '',+ });+ });++ it('runs the full package for unresolved component scope', () => {+ expect(+ resolveRtlShardScope({+ packageName: 'core',+ forceFull: false,+ hasComponents: true,+ hasHarness: false,+ analysis: {owners: [], qualified: true},+ }),+ ).toMatchObject({shouldRun: true, components: 'full core roster'});+ });++ it('runs every package fully when analysis found an unresolved source', () => {+ const analysis = {+ ...qualifiedAnalysis,+ forceFullComponentAudits: true,+ };+ for (const packageName of COMPONENT_PACKAGE_NAMES) {+ expect(+ resolveRtlShardScope({+ packageName,+ forceFull: false,+ hasComponents: true,+ hasHarness: false,+ analysis,+ }),+ ).toMatchObject({+ shouldRun: true,+ components: `full ${packageName} roster`,+ });+ }+ });++ it('runs only the canonical harness smoke packages', () => {+ const input = {+ forceFull: false,+ hasComponents: false,+ hasHarness: true,+ analysis: {owners: [], qualified: true},+ };+ expect(resolveRtlShardScope({...input, packageName: 'lab'})).toMatchObject({+ shouldRun: true,+ filter: 'lab/Chart',+ });+ expect(+ resolveRtlShardScope({...input, packageName: 'charts'}),+ ).toMatchObject({+ shouldRun: true,+ filter: 'charts/Chart,charts/ChartLegend',+ });+ expect(resolveRtlShardScope({...input, packageName: 'core'})).toMatchObject(+ {+ shouldRun: false,+ },+ );+ });++ it('fails closed to a full shard for unqualified legacy owner data', () => {+ expect(+ resolveRtlShardScope({+ packageName: 'core',+ forceFull: false,+ hasComponents: true,+ hasHarness: false,+ analysis: {owners: ['Button'], qualified: false},+ }),+ ).toMatchObject({shouldRun: true, components: 'full core roster'});+ });++ it('fails closed to full shards for a noncanonical qualified owner', () => {+ const analysis = {+ owners: ['unknown/Thing'],+ qualified: true,+ invalidOwners: ['unknown/Thing'],+ };+ for (const packageName of COMPONENT_PACKAGE_NAMES) {+ expect(+ resolveRtlShardScope({+ packageName,+ forceFull: false,+ hasComponents: true,+ hasHarness: false,+ analysis,+ }),+ ).toMatchObject({+ shouldRun: true,+ components: `full ${packageName} roster`,+ });+ }+ });+});++describe('RTL shard scope artifact handling', () => {+ it('reads qualified owner arrays', () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rtl-analysis-'));+ const file = path.join(dir, 'analysis.json');+ try {+ fs.writeFileSync(+ file,+ JSON.stringify({+ newComponentOwners: ['charts/ChartLegend'],+ modifiedComponentOwners: [],+ }),+ );+ expect(readAnalysis(file)).toEqual({+ owners: ['charts/ChartLegend'],+ qualified: true,+ forceFullComponentAudits: false,+ invalidOwners: [],+ });+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });++ it.each([+ ['missing', null, 'Could not read analysis artifact'],+ ['malformed', '{not json', 'Could not read analysis artifact'],+ [+ 'wrong force-full shape',+ JSON.stringify({+ newComponentOwners: [],+ modifiedComponentOwners: [],+ forceFullComponentAudits: 'true',+ }),+ 'forceFullComponentAudits must be a boolean',+ ],+ [+ 'wrong owner shape',+ JSON.stringify({newComponentOwners: 'charts/ChartLegend'}),+ 'newComponentOwners must be an array of strings',+ ],+ ])(+ 'rejects %s analysis before writing shard outputs',+ (_name, input, message) => {+ const result = runCli(input);+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain(message);+ expect(result.output).toBe('');+ expect(result.manifest).toBeNull();+ },+ );++ it('turns a noncanonical qualified owner into full package scope', () => {+ const result = runCli(+ JSON.stringify({+ newComponentOwners: ['unknown/Thing'],+ modifiedComponentOwners: [],+ }),+ );+ expect(result.status).toBe(0);+ expect(result.output).toContain('should_run=true');+ expect(result.output).toContain('components=full charts roster');+ expect(result.output).toContain('reason=noncanonical component scope');+ });++ it('writes explicit outputs only after valid analysis resolves', () => {+ const result = runCli(+ JSON.stringify({+ newComponentOwners: ['charts/ChartLegend'],+ modifiedComponentOwners: [],+ }),+ );+ expect(result.status).toBe(0);+ expect(result.output).toContain('should_run=true');+ expect(result.output).toContain('filter=charts/ChartLegend');+ expect(result.manifest).toEqual({+ package: 'charts',+ shouldRun: true,+ filter: 'charts/ChartLegend',+ });+ });+});diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 865a8fcaf1..2e3d1162e7 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -121,19 +121,21 @@ jobs:# Lightweight check — does the PR touch any published components?# Gates pr-a11y and pr-rtl to avoid unnecessary work.#- # Keep the roots and the exclude list in sync with analyze-pr.js: this job- # only decides *whether* the downstream audits run, while analyze-pr.js- # decides *which* components they audit. When the two disagree the audits- # silently no-op — lab components were invisible to both audits until this- # job learned about packages/lab/src.+ # `scripts/component-packages.cjs` owns the component source roots used here+ # and by the RTL roster. `analyze-pr.js` still decides which changed components+ # each downstream audit receives. When those projections disagree the audits+ # silently no-op, so harness/registry changes also exercise the RTL smoke scope.check-components:needs: [check-scope]- if: github.event_name == 'pull_request' && needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true'+ if: github.event_name == 'pull_request'runs-on: ubuntu-slimpermissions:contents: readoutputs:has_components: ${{ steps.check.outputs.has_components }}+ has_rtl_components: ${{ steps.check.outputs.has_rtl_components }}+ has_rtl_harness: ${{ steps.check.outputs.has_rtl_harness }}+ force_full_component_audits: ${{ steps.check.outputs.force_full_component_audits }}# Stable visual scope is separate from component scope: Core and the# non-private shipped themes participate; canaryOnly packages do not.has_stable_visual: ${{ steps.check.outputs.has_stable_visual }}@@ -153,25 +155,34 @@ jobs:- name: Check for component changesid: checkrun: |- if ! git merge-base HEAD origin/${{ github.base_ref }} >/dev/null 2>&1; then- echo "::warning::No merge base between HEAD and origin/${{ github.base_ref }} (clone too shallow) — assuming components changed so pr-a11y still runs"- echo "has_components=true" >> "$GITHUB_OUTPUT"- # Fail closed for the stable lane too: without a merge base we do- # not know whether a stable package changed.+ if [ "${{ needs.check-scope.outputs.docsite_only }}" = "true" ] \+ || [ "${{ needs.check-scope.outputs.spec_only }}" = "true" ] \+ || [ "${{ needs.check-scope.outputs.tooling_only }}" = "true" ]; then+ printf 'has_components=false\nhas_rtl_components=false\nhas_rtl_harness=false\nforce_full_component_audits=false\nhas_stable_visual=false\n' >> "$GITHUB_OUTPUT"+ echo "Trusted specialized lane — component audits explicitly not applicable."+ exit 0+ fi+ if ! MERGE_BASE=$(git merge-base HEAD origin/${{ github.base_ref }} 2>/dev/null); then+ echo "::warning::No merge base between HEAD and origin/${{ github.base_ref }} — running full component audits"+ printf 'has_components=true\nhas_rtl_components=true\nhas_rtl_harness=true\nforce_full_component_audits=true\n' >> "$GITHUB_OUTPUT"echo "has_stable_visual=true" >> "$GITHUB_OUTPUT"exit 0fi- FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)- CHANGED=$(printf '%s\n' "$FILES" | grep -E '^packages/(core|lab)/src/' | grep -v -E '(hooks|theme|utils|i18n|__tests__)/' | head -1 || true)- # The shared accessibility spec-test contracts gate inside pr-a11y,- # and their component bindings live under `__tests__/` — which the- # filter above deliberately excludes. Without this the contract could- # be changed, or a binding broken, with the only job that runs it- # skipped. Stories are in scope too: the Chromium bindings drive- # checked-in stories by id, so renaming or deleting one breaks the- # contract run and nothing else would notice.- A11Y=$(printf '%s\n' "$FILES" | grep -E '^internal/a11y-spec/|^packages/[^/]+/src/.*\.a11y\.|^apps/storybook/stories/|^playwright\.config\.ts$' | head -1 || true)- echo "has_components=$( { [ -n "$CHANGED" ] || [ -n "$A11Y" ]; } && echo true || echo false )" >> "$GITHUB_OUTPUT"++ POLICY_ROOT="$RUNNER_TEMP/component-audit-scope"+ mkdir -p "$POLICY_ROOT/.github/scripts" "$POLICY_ROOT/scripts"+ SCOPE="$POLICY_ROOT/.github/scripts/component-audit-scope.cjs"+ REGISTRY="$POLICY_ROOT/scripts/component-packages.cjs"+ if git show "origin/${{ github.base_ref }}:.github/scripts/component-audit-scope.cjs" > "$SCOPE" 2>/dev/null \+ && git show "origin/${{ github.base_ref }}:scripts/component-packages.cjs" > "$REGISTRY" 2>/dev/null; then+ git diff --name-status "$MERGE_BASE"...HEAD \+ | node "$SCOPE" --registry "$REGISTRY" --github-output+ else+ echo "::warning::Trusted component audit policy is unavailable — running full component audits"+ printf 'has_components=true\nhas_rtl_components=true\nhas_rtl_harness=true\nforce_full_component_audits=true\n' >> "$GITHUB_OUTPUT"+ fi++ FILES=$(git diff --name-only "$MERGE_BASE"...HEAD)# One classifier owns the release-channel rule. It reads each# package's `astryx.canaryOnly` metadata rather than hard-coding@@ -684,11 +695,18 @@ jobs:# audits" for the baseline workflow.- name: Run accessibility auditrun: |- COMPONENTS=$(cat analysis.json | jq -r '(.newComponents + .modifiedComponents) | join(",")')+ COMPONENTS=$(jq -r '((.newComponentOwners // .newComponents // []) + (.modifiedComponentOwners // .modifiedComponents // [])) | join(",")' analysis.json)+ ANALYSIS_FORCE_FULL=$(jq -r '.forceFullComponentAudits // false' analysis.json)+ SCOPE_ARGS=()+ if [ "${{ needs.check-components.outputs.force_full_component_audits }}" != "true" ] && [ "$ANALYSIS_FORCE_FULL" != "true" ] && [ -n "$COMPONENTS" ]; then+ SCOPE_ARGS=(--components "$COMPONENTS")+ else+ echo "Component scope is policy-sensitive or unresolved — running the full accessibility audit."+ finode .github/scripts/accessibility-audit.js \--storybook-dir apps/storybook/dist \--output a11y-report.json \- --components "$COMPONENTS" \+ "${SCOPE_ARGS[@]}" \--baseline .github/a11y-baseline.json \--fail-on-new@@ -939,24 +957,39 @@ jobs:if-no-files-found: ignore# RTL semantic audit. Sibling to pr-a11y: same build-storybook artifact, same- # analysis.json scoping, so a PR only pays for the components it touched.- # Unscoped this swept ~1400 stories and took ~26 min. The full sweep that- # covers untouched components runs in rtl-weekly.yml.+ # analysis.json scoping, so ordinary PRs only pay for the components they+ # touched. A harness-only PR runs the fixed Chart/ChartLegend smoke scope so+ # routing and target changes prove themselves instead of skipping their own+ # check. A policy-sensitive full run spans ~2,000 stories and exceeded the+ # single-job budget, so CI partitions it by canonical package; each shard runs+ # four browser workers, and the stable pr-rtl join requires all five scope+ # manifests plus a report from every applicable package.+ # The scheduled full sweep also runs in rtl-weekly.yml.## Three auto dimensions: D1 icon-mirror, D5 positional-mirror, and D6# contextual directional decorations. Curated D2/D3/D4 adds behavior that# needs selectors. The applicability rollup treats unexplained all-N/A as a# coverage gap for both new and existing components.#- # SOFT / NON-BLOCKING (continue-on-error): findings surface a scorecard in the- # job summary but don't block the merge, while the suite is observed for- # flake. To promote: drop continue-on-error and add `pr-rtl` to required- # checks. See apps/storybook/rtl-audit/README.md.- pr-rtl:+ # Audit findings remain SOFT while the stability window is observed: the audit+ # step may fail after writing a report. Missing/canceled/incomplete shards are+ # HARD failures, and the pr-rtl join cannot pass without every package scope+ # manifest and every applicable report.+ # To promote findings too, remove the audit step's continue-on-error.+ pr-rtl-shard:+ name: pr-rtl (${{ matrix.package }})needs: [build-storybook, check-components]- if: github.event_name == 'pull_request' && needs.check-components.outputs.has_components == 'true'- runs-on: 2-core-ubuntu-arm- continue-on-error: true+ if: >-+ github.event_name == 'pull_request' &&+ (needs.check-components.outputs.has_rtl_components == 'true' ||+ needs.check-components.outputs.has_rtl_harness == 'true' ||+ needs.check-components.outputs.force_full_component_audits == 'true')+ strategy:+ fail-fast: false+ matrix:+ package: [core, lab, charts, richtext, vega]+ runs-on: 4-core-ubuntu+ timeout-minutes: 30permissions:contents: readsteps:@@ -982,33 +1015,79 @@ jobs:- name: Install Playwrightrun: pnpm install --frozen-lockfile && npx playwright install chromium- # An empty --filter means "audit everything", so guard the empty case:- # has_components can be true while analysis.json resolves to no- # components (the two compute component-ness differently).+ # A registry/classifier mutation runs the full audit from the PR checkout,+ # while eligibility itself came from trusted base policy. Scope resolution+ # is strict: malformed or missing analysis fails before the soft findings+ # step can run. An ordinary harness-only change uses the bounded routing+ # smoke scope.+ - name: Resolve RTL shard scope+ id: rtl-scope+ run: |+ node .github/scripts/rtl-shard-scope.mjs \+ --analysis analysis.json \+ --package "${{ matrix.package }}" \+ --force-full "${{ needs.check-components.outputs.force_full_component_audits }}" \+ --has-components "${{ needs.check-components.outputs.has_rtl_components }}" \+ --has-harness "${{ needs.check-components.outputs.has_rtl_harness }}" \+ --manifest rtl-shard-scope.json \+ --github-output "$GITHUB_OUTPUT"+- name: Run RTL auditid: rtl+ if: steps.rtl-scope.outputs.should_run == 'true'+ continue-on-error: truerun: |- COMPONENTS=$(jq -r '(.newComponents + .modifiedComponents) | join(",")' analysis.json)- if [ -z "$COMPONENTS" ]; then- echo "No component changes resolved from analysis.json — skipping RTL audit."- echo "ran=false" >> "$GITHUB_OUTPUT"- exit 0+ PACKAGE=${{ matrix.package }}+ COMPONENTS="${{ steps.rtl-scope.outputs.components }}"+ FILTER="${{ steps.rtl-scope.outputs.filter }}"+ FILTER_ARGS=()+ if [ -n "$FILTER" ]; then+ FILTER_ARGS=(--filter "$FILTER")fi- echo "Auditing components: $COMPONENTS"- echo "ran=true" >> "$GITHUB_OUTPUT"- echo "components=$COMPONENTS" >> "$GITHUB_OUTPUT"+ echo "Auditing $PACKAGE components: $COMPONENTS"node apps/storybook/rtl-audit/rtl-audit.mjs \--storybook-dir apps/storybook/dist \--output rtl-audit-report.json \- --filter "$COMPONENTS"+ --packages "$PACKAGE" \+ --concurrency 4 \+ "${FILTER_ARGS[@]}"++ - name: Require completed RTL shard report+ if: always()+ run: |+ SCOPE_OUTCOME="${{ steps.rtl-scope.outcome }}"+ SHOULD_RUN="${{ steps.rtl-scope.outputs.should_run }}"+ AUDIT_OUTCOME="${{ steps.rtl.outcome }}"+ if [ "$SCOPE_OUTCOME" != "success" ]; then+ echo "RTL shard scope did not resolve successfully: $SCOPE_OUTCOME"+ exit 1+ fi+ if [ "$SHOULD_RUN" = "true" ]; then+ if [ "$AUDIT_OUTCOME" != "success" ] && [ "$AUDIT_OUTCOME" != "failure" ]; then+ echo "Applicable RTL audit did not run: $AUDIT_OUTCOME"+ exit 1+ fi+ node .github/scripts/rtl-report-completion.mjs \+ --report rtl-audit-report.json \+ --package "${{ matrix.package }}" \+ --filter "${{ steps.rtl-scope.outputs.filter }}"+ elif [ "$SHOULD_RUN" = "false" ]; then+ if [ "$AUDIT_OUTCOME" != "skipped" ]; then+ echo "Out-of-scope RTL audit unexpectedly ran: $AUDIT_OUTCOME"+ exit 1+ fi+ else+ echo "RTL shard scope produced no explicit should_run decision."+ exit 1+ fi- name: Write scorecard summary- if: always() && steps.rtl.outputs.ran == 'true'+ if: always() && steps.rtl-scope.outputs.should_run == 'true'run: |{echo "## RTL semantic audit"echo ""- echo "Scoped to the components this PR touches: **${{ steps.rtl.outputs.components }}**. The full unfiltered sweep runs weekly — see \`rtl-weekly.yml\`."+ echo "Audit scope: **${{ steps.rtl-scope.outputs.components }}**. The scheduled unfiltered sweep also runs weekly — see \`rtl-weekly.yml\`."echo ""echo "Relationship-based (LTR vs RTL in the same run) — no golden screenshots. **Soft-gated** pending a stability window."echo ""@@ -1106,10 +1185,40 @@ jobs:fi} >> "$GITHUB_STEP_SUMMARY"- - name: Upload RTL audit report- if: always() && steps.rtl.outputs.ran == 'true'+ - name: Upload RTL shard evidence+ if: always()uses: actions/upload-artifact@v7with:- name: rtl-audit-report- path: rtl-audit-report.json+ name: rtl-audit-report-${{ matrix.package }}+ path: |+ rtl-shard-scope.json+ rtl-audit-report.json+ if-no-files-found: errorretention-days: 1++ # Stable required context joining the five package shards above.+ pr-rtl:+ needs: [check-components, pr-rtl-shard]+ if: ${{ always() && !cancelled() && github.event_name == 'pull_request' }}+ runs-on: ubuntu-slim+ timeout-minutes: 5+ steps:+ - uses: actions/checkout@v7++ - name: Download applicable RTL shard reports+ if: ${{ needs.check-components.result == 'success' && (needs.check-components.outputs.has_rtl_components == 'true' || needs.check-components.outputs.has_rtl_harness == 'true' || needs.check-components.outputs.force_full_component_audits == 'true') }}+ continue-on-error: true+ uses: actions/download-artifact@v8+ with:+ pattern: rtl-audit-report-*+ path: rtl-shard-reports++ - name: Require every applicable RTL shard+ if: always()+ run: |+ node .github/scripts/rtl-join.mjs \+ --check-components "${{ needs.check-components.result }}" \+ --shards "${{ needs.pr-rtl-shard.result }}" \+ --should-run "${{ needs.check-components.outputs.has_rtl_components == 'true' || needs.check-components.outputs.has_rtl_harness == 'true' || needs.check-components.outputs.force_full_component_audits == 'true' }}" \+ --force-full "${{ needs.check-components.outputs.force_full_component_audits }}" \+ --reports-dir rtl-shard-reportsdiff --git a/apps/storybook/rtl-audit/README.md b/apps/storybook/rtl-audit/README.mdindex a2cf633c45..f17efe36cf 100644--- a/apps/storybook/rtl-audit/README.md+++ b/apps/storybook/rtl-audit/README.md@@ -11,7 +11,7 @@ is the `pr-rtl` job — the RTL sibling of `pr-a11y`.## Three layers-### A. Auto-discovery — over every `core-*` and `lab-*` story in scope+### A. Auto-discovery — over every story prefix in the component-package registryThe point of the audit is to auto-catch **new or changed** components, so theauto-discovery layer runs with **zero curated selectors**. There are three@@ -19,9 +19,24 @@ independent auto passes: **D1 (icon-mirror)**, **D5 (positional-mirror)**, and**D6 (directional-decoration)**.> **Scope in CI.** `pr-rtl` passes `--filter` with the components the PR-> touched (from `analysis.json`), matching `pr-a11y`. The full unfiltered sweep-> runs weekly in `.github/workflows/rtl-weekly.yml` — that is what covers a-> component no PR edited. Omit `--filter` to run it locally.+> touched (from `analysis.json`), matching `pr-a11y`. Eligibility is classified+> by the component policy and package registry loaded from the trusted base ref;+> a missing policy, empty or unmatched path set, unresolved component list, or+> registry/classifier/workflow mutation runs the full audit rather than accepting+> an empty scope. CI partitions that full scope into one bounded shard per+> canonical package, each with four browser workers; the stable `pr-rtl` context+> succeeds only after all five scope manifests arrive and every applicable+> package produces a report whose requested package/filter, duplicate-free exact+> D1/D5/D6 identities, and nonzero planned/completed scans match. When trusted+> policy requires full scope, every manifest must be runnable with an empty+> filter and all five package reports must arrive. A planned scan ending in ERROR+> is incomplete. Missing or malformed analysis/index/manifest input, a noncanonical owner, stale output, a missing or unexpected report, and+> an all-skipped required matrix all fail closed. An ordinary RTL-harness-only PR runs the fixed `Chart,ChartLegend` routing smoke+> scope so package discovery and curated aliases cannot skip their own check. The+> full unfiltered sweep also runs weekly in `.github/workflows/rtl-weekly.yml`.+> Omit `--filter` to run it locally. The blocking accessibility audit consumes the+> same package-qualified owner-to-story routes and fails if any selected owner+> resolves to zero stories.### A.1 D1 icon-mirror@@ -214,8 +229,15 @@ them universally.### C. Applicability: no unexplained all-N/A components-The report rolls every component in the live Core and Lab source roster into one-of three states:+The report rolls every public component in the canonical component-package+registry into one of three states. Package roots, layouts, story prefixes, and+public component names come from `scripts/component-packages.cjs`; Storybook+titles project onto that canonical roster across Core, Lab, Charts, Rich Text,+and Vega, including one-to-many grouped titles such as+`Charts/Chrome/Axes & Grids`. Curated targets remain the exact alias when a title+cannot name its owner. An entry with an empty `dims` array is route-only: it+binds a public owner to a story that renders it for universal D1/D5/D6 scanning+without inventing a curated measurement.- **measured**: at least one D1/D5/D6 or curated dimension was applicable;- **verified N-A**: `verified-not-applicable.json` records a specific reason@@ -298,10 +320,13 @@ Edit `targets.json`. Each entry is:```jsonc{- "component": "MyComponent",+ "component": "MyComponent", // explicit alias for grouped story titles"storyId": "core-mycomponent--some-story", // must exist in dist/index.json"dims": ["D2", "D3"], // D2/D3/D4 only (D1 is auto)- "setup": {"click": "img"}, // optional: reveal the target+ "setup": {+ "args": {"position": "start"}, // optional: drive Storybook args+ "click": "img", // optional: reveal the target after args settle+ },"selectors": {"prev": "button[aria-label=\"Prev\"]", // D2"next": "button[aria-label=\"Next\"]",diff --git a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs b/apps/storybook/rtl-audit/rtl-audit-coverage.mjsindex b8cd4b9914..74495889a7 100644--- a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs+++ b/apps/storybook/rtl-audit/rtl-audit-coverage.mjs@@ -2,13 +2,228 @@/*** @file Shared RTL coverage and directional-decoration helpers.- * @input Rendered DOM decorations plus D1/D5/D6/curated audit results.- * @output Contextual decoration candidates, pair verdicts, component-filter- * reconciliation, and per-component measured / verified-N-A / coverage-gap- * classifications.+ * @input Rendered DOM decorations, canonical package rosters, Storybook routes,+ * curated targets, and D1/D5/D6/curated audit results.+ * @output Audited package/story routing, contextual decoration candidates,+ * component-filter reconciliation, and per-component measured / verified-N-A /+ * coverage-gap classifications.* @position Pure support layer for rtl-audit.mjs and its unit tests.*/+import componentPackages from '../../../scripts/component-packages.cjs';++const {COMPONENT_PACKAGES, COMPONENT_PACKAGE_NAMES} = componentPackages;++export const AUDITED_PACKAGE_NAMES = COMPONENT_PACKAGE_NAMES;+export const AUDITED_STORY_PREFIXES = Object.freeze([+ ...new Set(COMPONENT_PACKAGES.flatMap(pkg => pkg.storyPrefixes)),+]);++function packageForStoryId(+ storyId,+ packageNames = AUDITED_PACKAGE_NAMES,+) {+ return COMPONENT_PACKAGES.find(+ pkg =>+ packageNames.includes(pkg.name) &&+ pkg.storyPrefixes.some(prefix => storyId.startsWith(prefix)),+ )?.name ?? null;+}++function pascalCase(value) {+ return (value.match(/[A-Za-z0-9]+/g) ?? [])+ .map(word => `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`)+ .join('');+}++function singularize(value) {+ if (value === 'Axes') return 'Axis';+ return value.endsWith('s') ? value.slice(0, -1) : value;+}++function componentsFromStoryTitle(+ title,+ preferredPackage,+ publicComponentsByPackage,+) {+ const titleSegments = title?.split('/') ?? [];+ const namespace = titleSegments[0] ?? '';+ const finalSegment = titleSegments.at(-1) ?? '';+ const candidates = new Set();+ for (const part of finalSegment.split(/\s*(?:&|\band\b)\s*/i)) {+ const name = pascalCase(part);+ if (!name) continue;+ const singular = singularize(name);+ candidates.add(name);+ candidates.add(singular);+ candidates.add(`Chart${name}`);+ candidates.add(`Chart${singular}`);+ }+ const matchesIn = packageName =>+ (publicComponentsByPackage[packageName] ?? [])+ .filter(component => candidates.has(component))+ .map(component => `${packageName}/${component}`);+ const namespacePackages = COMPONENT_PACKAGES+ .filter(pkg => pkg.storyNamespaces.includes(namespace))+ .map(pkg => pkg.name)+ .filter(packageName => packageName in publicComponentsByPackage);+ const eligiblePackages = namespacePackages.length > 0+ ? namespacePackages+ : Object.keys(publicComponentsByPackage);+ const preferred = preferredPackage && eligiblePackages.includes(preferredPackage)+ ? matchesIn(preferredPackage)+ : [];+ if (preferred.length > 0) return preferred;+ return eligiblePackages+ .filter(packageName => packageName !== preferredPackage)+ .flatMap(matchesIn);+}++/** Resolve the best default package/component route encoded in a story id. */+export function componentFromStoryId(+ storyId,+ packageNames = AUDITED_PACKAGE_NAMES,+ publicComponentsByPackage = {},+) {+ const packageName = packageForStoryId(storyId, packageNames);+ if (!packageName) {+ return `unknown/${storyId.split('--')[0]}`;+ }+ const segment = storyId.slice(packageName.length + 1).split('--')[0];+ const normalized = segment.replace(/[^a-z0-9]/gi, '').toLowerCase();+ const publicComponents = publicComponentsByPackage[packageName] ?? [];+ const exact = publicComponents.find(+ component => component.toLowerCase() === normalized,+ );+ const fallback = exact ??+ (publicComponents.includes('Chart') ? 'Chart' : segment);+ return `${packageName}/${fallback}`;+}++/** Resolve a curated target's declared component in the story's package. */+export function componentFromTarget(+ target,+ packageNames = AUDITED_PACKAGE_NAMES,+ publicComponentsByPackage = {},+) {+ const declared = target?.component?.trim();+ if (!declared) {+ return componentFromStoryId(+ target.storyId,+ packageNames,+ publicComponentsByPackage,+ );+ }+ if (declared.includes('/')) {+ return declared;+ }+ const packageName = packageForStoryId(target.storyId, packageNames);+ return packageName+ ? `${packageName}/${declared}`+ : `unknown/${declared}`;+}++/**+ * Route each story to its public component owner(s). Story titles project onto+ * the canonical public-component roster; curated targets provide exact aliases+ * for surfaces whose titles do not name their owner.+ */+export function buildStoryComponentRoutes({+ stories,+ storyIds,+ targets = [],+ packageNames = AUDITED_PACKAGE_NAMES,+ publicComponentsByPackage = {},+}) {+ const normalizedStories = stories ?? storyIds.map(id => ({id, title: ''}));+ const aliases = new Map();+ for (const target of targets) {+ const component = componentFromTarget(+ target,+ packageNames,+ publicComponentsByPackage,+ );+ const current = aliases.get(target.storyId) ?? [];+ current.push(component);+ aliases.set(target.storyId, current);+ }++ return normalizedStories.flatMap(story => {+ const packageName = packageForStoryId(story.id, packageNames);+ const explicitComponents = aliases.get(story.id) ?? [];+ const titleComponents = explicitComponents.length === 0+ ? componentsFromStoryTitle(+ story.title,+ packageName,+ publicComponentsByPackage,+ )+ : [];+ const components = [...explicitComponents, ...titleComponents];+ if (components.length === 0) {+ components.push(+ componentFromStoryId(+ story.id,+ packageNames,+ publicComponentsByPackage,+ ),+ );+ }+ return Array.from(+ new Map(+ components.map(component => [component.toLowerCase(), component]),+ ).values(),+ ).map(component => ({id: story.id, component}));+ });+}++export function filterStoryRoutesByPackages(+ routes,+ packageNames,+ packages = COMPONENT_PACKAGES,+) {+ return routes.filter(({component, id}) => {+ const ownerPackage = component.split('/')[0];+ if (packageNames.includes(ownerPackage)) return true;+ if (ownerPackage !== 'unknown') return false;+ const fallbackPackage = packages.find(pkg =>+ pkg.storyPrefixes.some(prefix => id.startsWith(prefix)),+ )?.name;+ return fallbackPackage != null && packageNames.includes(fallbackPackage);+ });+}++/** Whether a package-qualified route owns a bare or qualified filter. */+function routeMatchesComponentFilter(route, filter) {+ const component = route.component.toLowerCase();+ const bareComponent = component.split('/').at(-1);+ const requested = filter.toLowerCase();+ return component === requested || bareComponent === requested;+}++/** Package-qualified owner routes selected by bare or qualified filters. */+export function componentRoutesForFilters(routes, filters) {+ if (filters.length === 0) return routes;+ return routes.filter(route =>+ filters.some(filter => routeMatchesComponentFilter(route, filter)),+ );+}++/** Story ids owned by any bare or package-qualified component filter. */+export function storyIdsForComponentFilters(routes, filters) {+ return [+ ...new Set(+ componentRoutesForFilters(routes, filters).map(route => route.id),+ ),+ ];+}++/** Selected owners for which the canonical Storybook route has no story. */+export function unresolvedComponentFilters(routes, filters) {+ return filters.filter(+ filter => !routes.some(route => routeMatchesComponentFilter(route, filter)),+ );+}+const EXPLICIT_GLYPH_PAIRS = new Map([['/', '\\'],['\\', '/'],@@ -389,10 +604,12 @@ export function buildAuditedComponentRoster({}) {const normalizedFilters = filters.map(filter => filter.toLowerCase());const knownComponents = [...sourceComponents, ...storyComponents];+ const matchesFilter = (component, filter) =>+ component.toLowerCase() === filter || componentName(component) === filter;const unmatchedFilters = normalizedFilters.filter(filter =>- !knownComponents.some(component => componentName(component) === filter),+ !knownComponents.some(component => matchesFilter(component, filter)),).map(filter => `unknown/${filter}`);@@ -406,7 +623,7 @@ export function buildAuditedComponentRoster({).filter(component =>normalizedFilters.length === 0 ||- normalizedFilters.includes(componentName(component)),+ normalizedFilters.some(filter => matchesFilter(component, filter)),);}diff --git a/apps/storybook/rtl-audit/rtl-audit.mjs b/apps/storybook/rtl-audit/rtl-audit.mjsindex e0eb15e665..997b58ba32 100644--- a/apps/storybook/rtl-audit/rtl-audit.mjs+++ b/apps/storybook/rtl-audit/rtl-audit.mjs@@ -25,11 +25,11 @@* (C) APPLICABILITY: every component is measured, explicitly verified N/A,* or reported as a coverage gap. An all-N/A result is never called clean.* @input --storybook-dir <path> --output <file> [--targets <path>]- * [--verified-not-applicable <path>] [--filter <csv>] [--auto-only]- * [--curated-only]+ * [--verified-not-applicable <path>] [--filter <csv>] [--packages <csv>]+ * [--auto-only] [--curated-only]* @output JSON scorecard: D1/D5/D6 auto verdicts, curated D2/D3/D4/D7/D8- * results, and a component coverage rollup. Mirrors the pr-a11y accessibility-- * audit harness.+ * results, exact planned/completed scan counts, and a component coverage+ * rollup. Mirrors the pr-a11y accessibility-audit harness.* @position internal test harness; run by the soft-gated `pr-rtl` CI job and* locally via `pnpm -F @astryxdesign/storybook rtl-audit`.*@@ -47,15 +47,26 @@ import http from 'node:http';import fs from 'node:fs';import path from 'node:path';import {fileURLToPath} from 'node:url';-import {discoverComponents} from '../../../packages/cli/foundation/discovery/component-discovery.mjs';+import componentPackages from '../../../scripts/component-packages.cjs';import {+ AUDITED_PACKAGE_NAMES,+ AUDITED_STORY_PREFIXES,buildAuditedComponentRoster,buildComponentCoverage,+ buildStoryComponentRoutes,classifyLogicalInlinePair,collectDirectionalDecorations,+ componentFromTarget,evaluateDirectionalDecorations,+ filterStoryRoutesByPackages,} from './rtl-audit-coverage.mjs';+const {+ componentPackage,+ flatPackageComponentNames,+ nestedPackageComponentNames,+} = componentPackages;+const args = process.argv.slice(2);const getArg = name => {const i = args.indexOf(`--${name}`);@@ -71,14 +82,23 @@ const VERIFIED_NA_PATH =getArg('verified-not-applicable') ||path.join(HERE, 'verified-not-applicable.json');const FILTER = (getArg('filter') || '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);+const PACKAGE_FILTER = (getArg('packages') || '')+ .split(',')+ .map(value => value.trim().toLowerCase())+ .filter(Boolean);+const invalidPackages = PACKAGE_FILTER.filter(+ packageName => !AUDITED_PACKAGE_NAMES.includes(packageName),+);+if (invalidPackages.length > 0) {+ throw new Error(`unknown audited package(s): ${invalidPackages.join(', ')}`);+}+const ACTIVE_PACKAGE_NAMES = PACKAGE_FILTER.length > 0+ ? PACKAGE_FILTER+ : AUDITED_PACKAGE_NAMES;const AUTO_ONLY = hasFlag('auto-only');const CURATED_ONLY = hasFlag('curated-only');-// Story-id prefixes the auto-discovery layer sweeps. These mirror the-// publishable component packages in analyze-pr.js — a component the PR job can-// name in --filter must also be discoverable here, or the audit silently-// reports zero targets. Lab stories (`lab-*`) were excluded until this list-// existed, so no lab component had ever been RTL-audited.-const AUDITED_STORY_PREFIXES = ['core-', 'lab-'];+// Story-id prefixes the auto-discovery layer sweeps come from the same+// canonical package registry used for source discovery below.const AUDITED_STORY_PREFIX = new RegExp(`^(?:${AUDITED_STORY_PREFIXES.join('|')})`);// Worker pool size. Each worker owns its own Playwright page; stories are// independent, and the run is dominated by page-load latency rather than CPU.@@ -158,6 +178,23 @@ async function settle(page) {}async function doSetup(page, t) {+ if (t?.setup?.args) {+ await page+ .waitForFunction(() => window.__STORYBOOK_ADDONS_CHANNEL__ != null)+ .catch(() => {});+ await page+ .evaluate(+ ({storyId, updatedArgs}) => {+ window.__STORYBOOK_ADDONS_CHANNEL__?.emit('updateStoryArgs', {+ storyId,+ updatedArgs,+ });+ },+ {storyId: t.storyId, updatedArgs: t.setup.args},+ )+ .catch(() => {});+ await page.waitForTimeout(250);+ }if (t?.setup?.click) {for (const sel of [].concat(t.setup.click)) {await page.locator(sel).first().click({timeout: 2500}).catch(() => {});@@ -883,17 +920,14 @@ async function scoreCurated(page, coarsePage, port, t) {}// ----------------------------------------------------------------------------function componentFromId(id) {- // core-tabletree--default -> core/tabletree (best-effort display name)- // lab-listinput--tag-options -> lab/listinput- const packageName = id.startsWith('lab-') ? 'lab' : 'core';- const seg = id.replace(AUDITED_STORY_PREFIX, '').split('--')[0];- return `${packageName}/${seg}`;+function matchesFilter(component) {+ const normalized = component.toLowerCase();+ const name = normalized.split('/').at(-1) ?? normalized;+ return !FILTER.length || FILTER.includes(normalized) || FILTER.includes(name);}-function matchesFilter(component) {- const name = component.split('/').at(-1)?.toLowerCase() ?? component;- return !FILTER.length || FILTER.includes(name);+function belongsToActivePackage(route) {+ return filterStoryRoutesByPackages([route], ACTIVE_PACKAGE_NAMES).length === 1;}// Run `fn` over `items` with `pages.length` workers, each pinned to its own@@ -913,74 +947,122 @@ async function mapPool(items, pages, fn) {return out;}+const runtime = {+ server: null,+ browser: null,+ pages: [],+ coarseContext: null,+};++async function cleanupRuntime() {+ await Promise.all(runtime.pages.map(page => page.close().catch(() => {})));+ await runtime.coarseContext?.close().catch(() => {});+ await runtime.browser?.close().catch(() => {});+ if (runtime.server) {+ await new Promise(resolve => runtime.server.close(() => resolve()));+ }+}+(async () => {- const {server, port} = await serve(path.resolve(DIST));- const browser = await chromium.launch();- const pages = await Promise.all(- Array.from({length: CONCURRENCY}, () =>- browser.newPage({viewport: {width: 1100, height: 760}, deviceScaleFactor: 1}),- ),- );- const page = pages[0]; // curated dims run serially on the first page- const d8BrowserContract = await verifyD8BrowserContract(page);- const coarseContext = await browser.newContext({- viewport: {width: 1100, height: 760},- deviceScaleFactor: 1,- hasTouch: true,- isMobile: true,- });- const coarsePage = await coarseContext.newPage();+ // A failed invocation must never leave an earlier successful report behind.+ fs.rmSync(OUT, {force: true});- let entries = {};+ let entries;try {- entries = JSON.parse(fs.readFileSync(path.join(DIST, 'index.json'), 'utf8')).entries || {};- } catch (e) {- console.error('FATAL: cannot read index.json:', String(e).slice(0, 120));- process.exit(2);+ const index = JSON.parse(fs.readFileSync(path.join(DIST, 'index.json'), 'utf8'));+ entries = index.entries ?? index.stories;+ } catch (error) {+ throw new Error(`cannot read index.json: ${String(error).slice(0, 120)}`, {+ cause: error,+ });+ }+ if (entries == null || typeof entries !== 'object' || Array.isArray(entries)) {+ throw new Error('index.json does not contain a Storybook entries object');}+ let targets = [];+ try { targets = JSON.parse(fs.readFileSync(TARGETS_PATH, 'utf8')); } catch {}+const storyIds = Object.keys(entries).filter(id =>entries[id].type === 'story' &&AUDITED_STORY_PREFIX.test(id) &&!/--docs$/.test(id),);+ if (storyIds.length === 0) {+ throw new Error('index.json contains no runnable audited stories');+ }++ const publicComponentsByPackage = {};const sourceComponents = [];- for (const packageName of ['core', 'lab']) {+ for (const packageName of AUDITED_PACKAGE_NAMES) {try {- const grouped = discoverComponents(path.join(PROJECT_ROOT, 'packages', packageName));- sourceComponents.push(- ...Object.values(grouped)- .flat()- .map(component => `${packageName}/${component}`),- );+ const pkg = componentPackage(packageName);+ if (!pkg) throw new Error('package is missing from component registry');+ const componentNames = pkg.layout === 'flat'+ ? flatPackageComponentNames(PROJECT_ROOT, pkg)+ : nestedPackageComponentNames(PROJECT_ROOT, pkg);+ publicComponentsByPackage[packageName] = componentNames;+ if (ACTIVE_PACKAGE_NAMES.includes(packageName)) {+ sourceComponents.push(+ ...componentNames.map(component => `${packageName}/${component}`),+ );+ }} catch (error) {console.error(`WARN: cannot discover ${packageName} component roster: ${String(error).slice(0, 120)}`);}}+ const storyRoutes = buildStoryComponentRoutes({+ stories: storyIds.map(id => ({id, title: entries[id].title})),+ targets,+ publicComponentsByPackage,+ }).filter(belongsToActivePackage);+ const scopedStoryRoutes = storyRoutes.filter(route => matchesFilter(route.component));+ if (scopedStoryRoutes.length === 0) {+ throw new Error(`no runnable stories resolved for ${ACTIVE_PACKAGE_NAMES.join(',')} scope`);+ }const auditedComponents = buildAuditedComponentRoster({sourceComponents,- storyComponents: storyIds.map(componentFromId),+ storyComponents: scopedStoryRoutes.map(route => route.component),filters: FILTER,});+ const {server, port} = await serve(path.resolve(DIST));+ runtime.server = server;+ const browser = await chromium.launch();+ runtime.browser = browser;+ const pages = await Promise.all(+ Array.from({length: CONCURRENCY}, () =>+ browser.newPage({viewport: {width: 1100, height: 760}, deviceScaleFactor: 1}),+ ),+ );+ runtime.pages = pages;+ const page = pages[0]; // curated dims run serially on the first page+ const d8BrowserContract = await verifyD8BrowserContract(page);+ const coarseContext = await browser.newContext({+ viewport: {width: 1100, height: 760},+ deviceScaleFactor: 1,+ hasTouch: true,+ isMobile: true,+ });+ runtime.coarseContext = coarseContext;+ const coarsePage = await coarseContext.newPage();+// ---- (A) auto-discovery over every audited-package story ----const autoResults = []; // D1 icon-mirrorconst pmResults = []; // D5 positional-mirrorconst decorationResults = []; // D6 contextual directional decoration+ const perComponent = new Map();+ for (const {component, id} of scopedStoryRoutes) {+ if (!perComponent.has(component)) perComponent.set(component, id);+ }+ const d1Targets = [...perComponent]+ .map(([component, id]) => ({comp: component, id}));if (!CURATED_ONLY) {// D1 runs one representative story per component (extra stories add little// D1 signal). D5 (positional-mirror) runs over EVERY core story — a// positioned bug can be story-specific (only a `withStatus` variant mounts// the offending element), so we don't collapse to one-per-component.- const perComponent = new Map();- for (const id of storyIds) {- const comp = componentFromId(id);- if (!perComponent.has(comp)) perComponent.set(comp, id);- }- const d1Targets = [...perComponent]- .filter(([comp]) => matchesFilter(comp))- .map(([comp, id]) => ({comp, id}));autoResults.push(...(await mapPool(d1Targets, pages, async ({comp, id}, workerPage) => {try {@@ -996,9 +1078,7 @@ async function mapPool(items, pages, fn) {})),);// D5 positional-mirror over every audited story.- const pmTargets = storyIds- .map(id => ({id, comp: componentFromId(id)}))- .filter(({comp}) => matchesFilter(comp));+ const pmTargets = scopedStoryRoutes.map(({id, component}) => ({id, comp: component}));pmResults.push(...(await mapPool(pmTargets, pages, async ({id, comp}, workerPage) => {try {@@ -1037,10 +1117,13 @@ async function mapPool(items, pages, fn) {// machine under load is more likely to change behaviour than to save time.const curatedResults = [];if (!AUTO_ONLY) {- let targets = [];- try { targets = JSON.parse(fs.readFileSync(TARGETS_PATH, 'utf8')); } catch {}for (const t of targets) {- const component = componentFromId(t.storyId);+ const component = componentFromTarget(+ t,+ AUDITED_PACKAGE_NAMES,+ publicComponentsByPackage,+ );+ if (!belongsToActivePackage({component, id: t.storyId})) continue;if (!matchesFilter(component)) continue;if (!entries[t.storyId]) {curatedResults.push({component, storyId: t.storyId, rollup: 'MISSING-STORY', dims: {}, notes: ['story not in index.json']});@@ -1082,11 +1165,6 @@ async function mapPool(items, pages, fn) {});if (verifiedNaError) coverage.registryError = verifiedNaError;- await Promise.all(pages.map(p => p.close().catch(() => {})));- await coarseContext.close().catch(() => {});- await browser.close();- server.close();-const autoFails = autoResults.filter(r => r.verdict === 'fail' || r.verdict === 'ERROR');// No allowlist: every not-RTL component is a surprise. The RTL migration is// complete, so any directional icon that fails to mirror is a real regression.@@ -1095,6 +1173,34 @@ async function mapPool(items, pages, fn) {const decorationFails = decorationResults.filter(r => r.verdict === 'fail' || r.verdict === 'ERROR');const report = {generatedAt: new Date().toISOString(),+ scope: {+ packages: ACTIVE_PACKAGE_NAMES,+ filters: FILTER,+ },+ completion: {+ plannedComponentScans: new Set(scopedStoryRoutes.map(route => route.component)).size,+ completedComponentScans: autoResults.length,+ plannedStoryScans: scopedStoryRoutes.length,+ completedPositionalScans: pmResults.length,+ completedDecorationScans: decorationResults.length,+ plannedComponentIdentities: [+ ...new Set(scopedStoryRoutes.map(route => route.component)),+ ].sort(),+ completedComponentIdentities: autoResults.map(result => result.component).sort(),+ plannedD1Identities: d1Targets.map(target => `${target.comp}::${target.id}`).sort(),+ completedD1Identities: autoResults+ .map(result => `${result.component}::${result.storyId}`)+ .sort(),+ plannedStoryIdentities: scopedStoryRoutes+ .map(route => `${route.component}::${route.id}`)+ .sort(),+ completedPositionalIdentities: pmResults+ .map(result => `${result.component}::${result.storyId}`)+ .sort(),+ completedDecorationIdentities: decorationResults+ .map(result => `${result.component}::${result.storyId}`)+ .sort(),+ },dist: DIST,selfChecks: {d8LogicalInline: d8BrowserContract},autoDiscovery: {@@ -1141,5 +1247,10 @@ async function mapPool(items, pages, fn) {decorationFails.length > 0 ||(coverage.enforced && (coverage.gaps > 0 || coverage.staleVerifiedNa > 0 || coverage.registryError != null)) ||curatedResults.some(r => r.rollup === 'not-RTL' || r.rollup === 'ERROR' || r.rollup === 'MISSING-STORY');- process.exit(anySignal ? 1 : 0);-})();+ process.exitCode = anySignal ? 1 : 0;+})()+ .catch(error => {+ console.error(`FATAL: ${error.message}`);+ process.exitCode = 2;+ })+ .finally(cleanupRuntime);diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.jsonindex 80a178ed96..597c3b9b7b 100644--- a/apps/storybook/rtl-audit/targets.json+++ b/apps/storybook/rtl-audit/targets.json@@ -2,9 +2,7 @@{"component": "AppShell","storyId": "core-appshell--top-nav-with-side-nav",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": ".astryx-app-shell-sidenav","overlayRoot": ".astryx-app-shell"@@ -13,9 +11,7 @@{"component": "ButtonGroup","storyId": "core-buttongroup--horizontal",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": "[role=\"group\"] button:first-child","next": "[role=\"group\"] button:last-child"@@ -24,9 +20,7 @@{"component": "CommandPalette","storyId": "core-commandpalette--default",- "dims": [- "D2"- ],+ "dims": ["D2"],"setup": {"click": "button:has-text(\"Open Command Palette\")"},@@ -38,9 +32,7 @@{"component": "Center","storyId": "core-center--padding-per-edge",- "dims": [- "D8"- ],+ "dims": ["D8"],"selectors": {"subject": ".astryx-center"}@@ -48,9 +40,7 @@{"component": "CheckboxInput","storyId": "core-checkboxinput--size-comparison",- "dims": [- "D7"- ],+ "dims": ["D7"],"sizes": ["sm", "md"],"selectors": {"inputSelectorBySize": {@@ -62,9 +52,7 @@{"component": "CheckboxList","storyId": "core-checkboxlist--rich-descriptions",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-checkbox-input","next": "[data-testid=\"checkbox-end-content\"]"@@ -73,9 +61,7 @@{"component": "PowerSearch","storyId": "core-powersearch--with-date-filters",- "dims": [- "D2"- ],+ "dims": ["D2"],"setup": {"click": ["button:has-text(\"Created: is between\")",@@ -90,10 +76,7 @@{"component": "RadioList","storyId": "core-radiolist--rich-content",- "dims": [- "D2",- "D7"- ],+ "dims": ["D2", "D7"],"sizes": ["sm", "md"],"selectors": {"prev": "input[aria-label=\"Pro\"]",@@ -104,9 +87,7 @@{"component": "SegmentedControl","storyId": "core-segmentedcontrol--default",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": "button[role=\"radio\"][data-value=\"grid\"]","next": "button[role=\"radio\"][data-value=\"table\"]"@@ -115,9 +96,7 @@{"component": "Switch","storyId": "core-switch--default",- "dims": [- "D7"- ],+ "dims": ["D7"],"sizes": ["sm", "md"],"selectors": {"inputSelector": "input[type=\"checkbox\"]"@@ -126,9 +105,7 @@{"component": "Calendar","storyId": "core-calendar--default",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": "button[aria-label=\"Previous month\"]","next": "button[aria-label=\"Next month\"]"@@ -137,9 +114,7 @@{"component": "Carousel","storyId": "core-carousel--default",- "dims": [- "D3"- ],+ "dims": ["D3"],"selectors": {"scroller": "[aria-roledescription=\"carousel\"] > div:first-child","nextButton": "button[aria-label=\"Scroll right\"]"@@ -148,9 +123,7 @@{"component": "Chat","storyId": "core-chat--mixed-content",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-chat-message-bubble[data-sender=\"assistant\"]","next": ".astryx-chat-message-bubble[data-sender=\"user\"]"@@ -183,9 +156,7 @@{"component": "Lightbox","storyId": "core-lightbox--gallery",- "dims": [- "D2"- ],+ "dims": ["D2"],"setup": {"click": "img, [role=button]"},@@ -197,9 +168,7 @@{"component": "Layout","storyId": "core-layout--dual-panels",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-layout-panel:first-of-type","next": ".astryx-layout-panel:last-of-type"@@ -208,9 +177,7 @@{"component": "Resizable","storyId": "core-resizable--horizontal-split",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": ".astryx-resize-handle","overlayRoot": ".astryx-layout"@@ -219,9 +186,7 @@{"component": "Stepper","storyId": "core-stepper--default-horizontal",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-stepper > li:first-child","next": ".astryx-stepper > li:last-child"@@ -239,9 +204,7 @@{"component": "TabList","storyId": "core-tablist--overflow",- "dims": [- "D3"- ],+ "dims": ["D3"],"selectors": {"scroller": ".astryx-tab-strip","nextButton": ".astryx-tab-scroll-button"@@ -250,9 +213,7 @@{"component": "BaseTypeahead","storyId": "core-basetypeahead--logical-dropdown-placement",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": "[role=\"listbox\"]","overlayRoot": "[data-base-typeahead-anchor=\"true\"]"@@ -261,9 +222,7 @@{"component": "Typeahead","storyId": "core-typeahead--rtl-end-lane",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": "button[aria-label=\"Clear selection\"]","overlayRoot": ".astryx-typeahead"@@ -272,9 +231,7 @@{"component": "Tokenizer","storyId": "core-tokenizer--rtl-end-lane",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": "button[aria-label=\"Clear all\"]","overlayRoot": ".astryx-tokenizer"@@ -283,9 +240,7 @@{"component": "Tooltip","storyId": "core-tooltip--rtl-logical-placement",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": ".astryx-tooltip","overlayRoot": "button:has-text(\"RTL placement target\")"@@ -294,9 +249,7 @@{"component": "Toast","storyId": "core-toast--logical-placement",- "dims": [- "D4"- ],+ "dims": ["D4"],"setup": {"click": "button:has-text(\"Show toast\")"},@@ -308,9 +261,7 @@{"component": "InputGroup","storyId": "core-inputgroup--with-prefix-and-suffix",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-input-group > .astryx-input-group-text:first-child","next": ".astryx-input-group > .astryx-input-group-text:last-child"@@ -319,9 +270,7 @@{"component": "NumberInput","storyId": "core-numberinput--with-number-steppers",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": "input[role=\"spinbutton\"]","next": "button[aria-label=\"Increment Quantity\"]"@@ -330,9 +279,7 @@{"component": "TextArea","storyId": "core-textarea--max-length-with-value",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": ".astryx-text-area-counter","overlayRoot": ".astryx-text-area"@@ -341,9 +288,7 @@{"component": "Thumbnail","storyId": "core-thumbnail--with-remove",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": ".astryx-thumbnail .astryx-button","overlayRoot": ".astryx-thumbnail"@@ -352,9 +297,7 @@{"component": "CodeBlock","storyId": "core-codeblock--default",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-code-block-title","next": ".astryx-code-block-copy-button"@@ -363,9 +306,7 @@{"component": "FileInput","storyId": "core-fileinput--with-error-status",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-file-input > .astryx-icon:not(.astryx-input-status-icon)","next": ".astryx-file-input > .astryx-input-status-icon"@@ -374,9 +315,7 @@{"component": "Outline","storyId": "core-outline--controlled",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-outline > div[aria-hidden=\"true\"]","next": ".astryx-outline > ul"@@ -385,9 +324,7 @@{"component": "Popover","storyId": "core-popover--default",- "dims": [- "D4"- ],+ "dims": ["D4"],"setup": {"click": "button:has-text(\"Settings\")"},@@ -399,9 +336,7 @@{"component": "Selector","storyId": "core-selector--default",- "dims": [- "D4"- ],+ "dims": ["D4"],"setup": {"click": "[role=\"combobox\"]"},@@ -413,9 +348,7 @@{"component": "MultiSelector","storyId": "core-multiselector--default",- "dims": [- "D4"- ],+ "dims": ["D4"],"setup": {"click": "[role=\"combobox\"]"},@@ -427,9 +360,7 @@{"component": "SideNav","storyId": "core-sidenav--default",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": "a.astryx-side-nav-item[href=\"/projects\"] > svg.astryx-icon","next": "a.astryx-side-nav-item[href=\"/projects\"] .astryx-badge"@@ -438,20 +369,39 @@{"component": "Chart","storyId": "lab-chart--line-chart",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": "foreignObject > div > div:first-child","next": "foreignObject > div > div:last-child"}},+ {+ "component": "Chart",+ "storyId": "charts-chart--playground",+ "dims": ["D2"],+ "setup": {+ "args": {+ "legendPosition": "start"+ }+ },+ "selectors": {+ "prev": "[role=\"list\"]",+ "next": "svg[role=\"img\"]"+ }+ },+ {+ "component": "ChartLegend",+ "storyId": "charts-chrome-legend--default",+ "dims": ["D2"],+ "selectors": {+ "prev": "[role=\"listitem\"]:first-child",+ "next": "[role=\"listitem\"]:last-child"+ }+ },{"component": "Drawer","storyId": "lab-drawer--sides",- "dims": [- "D4"- ],+ "dims": ["D4"],"setup": {"click": "button:has-text(\"Open from end\")"},@@ -461,22 +411,37 @@}},{- "component": "RichTextEditor",+ "component": "richtext/RichTextEditor","storyId": "lab-richtexteditor--error-status",- "dims": [- "D4"- ],+ "dims": ["D4"],"selectors": {"overlay": ".astryx-rich-text-editor > div:first-child > div:last-child","overlayRoot": ".astryx-rich-text-editor"}},+ {+ "component": "richtext/RichTextEditorToolbar",+ "storyId": "lab-richtexteditor--with-toolbar",+ "dims": ["D2"],+ "selectors": {+ "prev": "[role=\"group\"][aria-label=\"Formatting actions\"] button:first-of-type",+ "next": "[role=\"group\"][aria-label=\"Formatting actions\"] button:last-of-type"+ }+ },+ {+ "component": "richtext/RichTextEditorAutoLinkPlugin",+ "storyId": "lab-richtexteditor--with-auto-link",+ "dims": []+ },+ {+ "component": "richtext/RichTextView",+ "storyId": "lab-richtexteditor--markdown-serializers",+ "dims": []+ },{"component": "AvatarGroupOverflow","storyId": "core-avatargroupoverflow--default",- "dims": [- "D2"- ],+ "dims": ["D2"],"selectors": {"prev": ".astryx-avatar-group > .astryx-avatar:first-child","next": ".astryx-avatar-group-overflow"diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex e2058b554b..c96165615e 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -53,9 +53,33 @@"reason": "BottomSheetSwitcher owns no direction-sensitive visual or interaction. Its shared dialog spans both axes symmetrically; sheet handoff, close, swipe, and alignment motion use only the block axis; and it owns no directional glyph, inline ordering, horizontal scroll action, or arrow-key behavior. Each child BottomSheet retains its own independently verified logical layout."},{- "component": "unknown/ChartTooltip",+ "component": "charts/ChartAxis",+ "reason": "ChartAxis renders Cartesian data coordinates on physical top, right, bottom, or left plot edges. Tick lines, labels, and value order stay tied to the data scale rather than reading direction; it owns no directional glyph, logical overlay, scroll, drag, or horizontal keyboard behavior."+ },+ {+ "component": "charts/ChartGrid",+ "reason": "ChartGrid renders direction-neutral horizontal and vertical Cartesian guide lines inside the plot. It owns no text, directional glyph, inline-axis ordering, overlay placement, scroll, drag, or keyboard behavior."+ },+ {+ "component": "charts/ChartSwatch",+ "reason": "ChartSwatch is a centered square, line, or dot sample whose mark shape and color identify a data series. Its geometry is symmetric and it owns no directional glyph, placement, order, scroll, drag, overlay, or keyboard behavior."+ },+ {+ "component": "charts/ChartTooltip","reason": "ChartTooltip uses explicitly physical left/right/top viewport placement and clamping. It has no logical start/end placement, direction-dependent control order, horizontal scrolling action, or coarse form hit target; tooltip rows inherit bidi layout without component-specific directional logic."},+ {+ "component": "richtext/RichTextEditorAutoLinkPlugin",+ "reason": "RichTextEditorAutoLinkPlugin renders no visual or interactive DOM of its own. It transforms typed URL and email text into native-direction links inside the editor and owns no directional glyph, layout, placement, order, scrolling, dragging, overlay, or keyboard behavior."+ },+ {+ "component": "richtext/RichTextView",+ "reason": "RichTextView renders serialized content in normal browser text flow. Content and nested bidi runs retain their authored direction through Lexical and the platform; the wrapper owns no directional glyph, physical inline placement, reordering, horizontal scroll action, drag, overlay, or keyboard behavior."+ },+ {+ "component": "vega/VegaChart",+ "reason": "VegaChart renders a caller-owned Vega or Vega-Lite data-space specification. Axes, marks, scales, pointer signals, and physical chart coordinates intentionally remain defined by that specification rather than document direction; the React wrapper owns no directional glyph, logical control order, overlay placement, or horizontal keyboard behavior."+ },{"component": "unknown/ThreeD","reason": "The ThreeD documentation family renders Cartesian x/y/z data visualizations in SVG and WebGL. Its axes and pointer-drag rotation are physical data-space interactions that intentionally remain invariant across writing directions; it has no reading-order controls, inline-start/end placement, directional glyphs, or overlays to mirror."diff --git a/internal/lab-readiness/audit.test.mjs b/internal/lab-readiness/audit.test.mjsindex e38a214587..0864142005 100644--- a/internal/lab-readiness/audit.test.mjs+++ b/internal/lab-readiness/audit.test.mjs@@ -348,11 +348,32 @@ describe('CI wiring parsers', () => {const roots = _internal.ciComponentRoots(repoRoot);expect(roots).toContain('packages/core/src/');expect(roots).toContain('packages/lab/src/');+ expect(roots).toContain('packages/charts/src/');+ expect(roots).toContain('packages/richtext/src/');+ expect(roots).toContain('packages/vega/src/');+ });++ it('routes Charts, Rich Text, and Vega source-only changes into component audit scope', () => {+ const repoRoot = path.resolve(import.meta.dirname, '..', '..');+ const roots = _internal.ciComponentRoots(repoRoot);+ const changedFiles = [+ 'packages/charts/src/Chart.tsx',+ 'packages/richtext/src/RichTextEditor.tsx',+ 'packages/vega/src/VegaChart.tsx',+ ];+ expect(+ changedFiles.every(file => roots.some(root => file.startsWith(root))),+ ).toBe(true);});it('reads the audited story prefixes out of the real rtl-audit', () => {const repoRoot = path.resolve(import.meta.dirname, '..', '..');- expect(_internal.rtlAuditedPrefixes(repoRoot)).toEqual(['core-', 'lab-']);+ expect(_internal.rtlAuditedPrefixes(repoRoot)).toEqual([+ 'core-',+ 'lab-',+ 'charts-',+ 'vega-',+ ]);});it('derives the component name pr-a11y matches against', () => {diff --git a/internal/lab-readiness/automated.mjs b/internal/lab-readiness/automated.mjsindex 1b26b3bb27..3247879aef 100644--- a/internal/lab-readiness/automated.mjs+++ b/internal/lab-readiness/automated.mjs@@ -24,6 +24,7 @@ import path from 'node:path';const LAB_SRC = 'packages/lab/src';const STORIES_DIR = 'apps/storybook/stories';const CI_WORKFLOW = '.github/workflows/ci.yml';+const COMPONENT_REGISTRY = 'scripts/component-packages.cjs';const RTL_AUDIT = 'apps/storybook/rtl-audit/rtl-audit.mjs';/** Read a repo-relative file, or null when it does not exist. */@@ -98,6 +99,17 @@ function a11yComponentFromTitle(title) {function ciComponentRoots(repoRoot) {const ci = read(repoRoot, CI_WORKFLOW);if (!ci) return [];+ const registry = read(repoRoot, COMPONENT_REGISTRY);+ const projectsRegistry =+ /COMPONENT_PACKAGES/.test(ci) ||+ (/component-audit-scope\.cjs/.test(ci) &&+ /scripts\/component-packages\.cjs/.test(ci));+ if (registry && projectsRegistry) {+ const roots = [...registry.matchAll(/\bsrc:\s*['"]([^'"]+)['"]/g)].map(+ match => `${match[1]}/`,+ );+ if (roots.length > 0) return roots;+ }const pathspec = ci.match(/git diff --name-only [^\n]*?\.\.\.HEAD --([^|\n]+)/);if (pathspec) return pathspec[1].trim().split(/\s+/).filter(Boolean);const filtered = ci.match(/grep -E ['"]\^packages\/\(([^)]+)\)\/src\/['"]/);@@ -106,6 +118,17 @@ function ciComponentRoots(repoRoot) {/** Story-id prefixes the RTL auto-discovery sweep covers. */function rtlAuditedPrefixes(repoRoot) {+ const registry = read(repoRoot, COMPONENT_REGISTRY);+ const registryPrefixes = registry+ ? [...registry.matchAll(/\bstoryPrefixes:\s*\[([^\]]*)\]/g)].flatMap(+ block => [...block[1].matchAll(/['"]([^'"]+)['"]/g)].map(match => match[1]),+ )+ : [];+ if (registryPrefixes.length > 0) {+ return [...new Set(registryPrefixes)];+ }++ // Older/scratch repositories keep the prefixes directly in rtl-audit.mjs.const rtl = read(repoRoot, RTL_AUDIT);if (!rtl) return [];const match = rtl.match(/AUDITED_STORY_PREFIXES\s*=\s*\[([^\]]+)\]/);diff --git a/scripts/component-packages.cjs b/scripts/component-packages.cjsindex 01e2057ef1..6ca7e88956 100644--- a/scripts/component-packages.cjs+++ b/scripts/component-packages.cjs@@ -5,7 +5,8 @@/*** @file Shared registry of component-bearing Astryx packages and their layouts.- * @input Repository package names, source roots, public barrels, and component docs.+ * @input Repository package names, source roots, public barrels, component docs,+ * and Storybook routing namespaces.* @output Package metadata and public component discovery helpers.* @position Single registry used by audit rosters and component knowledge paths.*/@@ -23,11 +24,41 @@ const path = require('node:path');* the package barrel.*/const COMPONENT_PACKAGES = Object.freeze([- {name: 'core', src: 'packages/core/src', layout: 'nested'},- {name: 'lab', src: 'packages/lab/src', layout: 'nested'},- {name: 'charts', src: 'packages/charts/src', layout: 'flat'},- {name: 'richtext', src: 'packages/richtext/src', layout: 'flat'},- {name: 'vega', src: 'packages/vega/src', layout: 'flat'},+ {+ name: 'core',+ src: 'packages/core/src',+ layout: 'nested',+ storyPrefixes: ['core-'],+ storyNamespaces: ['Core'],+ },+ {+ name: 'lab',+ src: 'packages/lab/src',+ layout: 'nested',+ storyPrefixes: ['lab-'],+ storyNamespaces: ['Lab'],+ },+ {+ name: 'charts',+ src: 'packages/charts/src',+ layout: 'flat',+ storyPrefixes: ['charts-'],+ storyNamespaces: ['Charts'],+ },+ {+ name: 'richtext',+ src: 'packages/richtext/src',+ layout: 'flat',+ storyPrefixes: ['lab-'],+ storyNamespaces: ['Lab'],+ },+ {+ name: 'vega',+ src: 'packages/vega/src',+ layout: 'flat',+ storyPrefixes: ['vega-'],+ storyNamespaces: ['Vega'],+ },]);const COMPONENT_PACKAGE_NAMES = Object.freeze(@@ -152,6 +183,27 @@ function flatPackageComponentNames(repoRoot, packageConfig) {return exportedComponentNames(path.join(repoRoot, packageConfig.src));}+/** Names one component directory's current consumer docs declare. */+function documentedComponentNames(componentDir) {+ const names = new Set();+ let files;+ try {+ files = fs.readdirSync(componentDir, {withFileTypes: true});+ } catch {+ return [];+ }+ for (const file of files) {+ if (!file.isFile() || !file.name.endsWith('.doc.mjs')) continue;+ const content = fs.readFileSync(path.join(componentDir, file.name), 'utf8');+ for (const match of content.matchAll(+ /\bname:\s*['"]([A-Z][A-Za-z0-9]*)['"]/g,+ )) {+ names.add(match[1]);+ }+ }+ return [...names];+}+/** Names current consumer docs identify as independent public components. */function documentedNestedComponentNames(sourceDir) {let entries;@@ -164,18 +216,10 @@ function documentedNestedComponentNames(sourceDir) {const names = new Set();for (const entry of entries) {if (!entry.isDirectory() || !COMPONENT_NAME.test(entry.name)) continue;- const componentDir = path.join(sourceDir, entry.name);- for (const file of fs.readdirSync(componentDir, {withFileTypes: true})) {- if (!file.isFile() || !file.name.endsWith('.doc.mjs')) continue;- const content = fs.readFileSync(- path.join(componentDir, file.name),- 'utf8',- );- for (const match of content.matchAll(- /\bname:\s*['"]([A-Z][A-Za-z0-9]*)['"]/g,- )) {- names.add(match[1]);- }+ for (const name of documentedComponentNames(+ path.join(sourceDir, entry.name),+ )) {+ names.add(name);}}return [...names];@@ -210,6 +254,7 @@ module.exports = {COMPONENT_PACKAGE_NAMES,componentExportsFromBarrel,componentPackage,+ documentedComponentNames,documentedNestedComponentNames,exportedComponentNames,flatPackageComponentNames,