Skip to content

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.mjs
new file mode 100644
index 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.js
index 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 stories
const 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 analysis
const 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.mjs
index 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.js
index 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.mjs
index 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.mjs
index 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.mjs
index 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.cjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.js
index 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.mjs
index 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.js
new file mode 100644
index 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.mjs
new file mode 100644
index 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.js
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.yml
index 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-slim
permissions:
contents: read
outputs:
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 changes
id: check
run: |
- 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 0
fi
- 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 audit
run: |
- 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."
+ fi
node .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: 30
permissions:
contents: read
steps:
@@ -982,33 +1015,79 @@ jobs:
- name: Install Playwright
run: 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 audit
id: rtl
+ if: steps.rtl-scope.outputs.should_run == 'true'
+ continue-on-error: true
run: |
- 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@v7
with:
- 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: error
retention-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-reports
diff --git a/apps/storybook/rtl-audit/README.md b/apps/storybook/rtl-audit/README.md
index 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 registry
The point of the audit is to auto-catch **new or changed** components, so the
auto-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.mjs
index 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.mjs
index 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-mirror
const pmResults = []; // D5 positional-mirror
const 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.json
index 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.json
index 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.mjs
index 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.mjs
index 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.cjs
index 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,