Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(rtl-audit): resolve component filters through the Storybook index (#9319)

Cindy Zhang49c549fa7462
diff --git a/.github/scripts/rtl-audit-coverage.test.mjs b/.github/scripts/rtl-audit-coverage.test.mjs
index fa5e55f722..9b477b5f90 100644
--- a/.github/scripts/rtl-audit-coverage.test.mjs
+++ b/.github/scripts/rtl-audit-coverage.test.mjs
@@ -23,6 +23,7 @@ import {
finishFiniteAnimations,
orderD1StoryCandidates,
resolveD1Applicability,
+ resolveFilterRoutes,
storyIdsForComponentFilters,
unresolvedComponentFilters,
validateStoryRtlAuditParameters,
@@ -1014,3 +1015,83 @@ describe('finishFiniteAnimations', () => {
expect(finishFiniteAnimations({})).toBe(0);
});
});
+
+describe('resolveFilterRoutes (filters resolve through the Storybook index)', () => {
+ // Core/Resizable's stories route to `core/resizable`, which no public
+ // component is called; ResizeHandle, the folder's export, has no title and
+ // its story file renders it. Core/Chat's stories route to `core/Chat`, also
+ // no public component, and Chat.stories.tsx never renders the scroll button.
+ const routes = [
+ {id: 'core-resizable--horizontal-split', component: 'core/resizable'},
+ {id: 'core-resizable--snap-points', component: 'core/resizable'},
+ {id: 'core-button--primary', component: 'core/Button'},
+ {id: 'core-chat--default', component: 'core/Chat'},
+ ];
+ const componentPaths = {
+ 'core-resizable--horizontal-split':
+ '../../packages/core/src/Resizable/index.ts',
+ 'core-resizable--snap-points': '../../packages/core/src/Resizable/index.ts',
+ 'core-button--primary': '../../packages/core/src/Button/index.ts',
+ 'core-chat--default': '../../packages/core/src/Chat/index.ts',
+ };
+ const owners = {
+ 'core/resizehandle': {
+ component: 'core/ResizeHandle',
+ folder: 'packages/core/src/Resizable',
+ },
+ 'core/chatlayoutscrollbutton': {
+ component: 'core/ChatLayoutScrollButton',
+ folder: 'packages/core/src/Chat',
+ },
+ };
+ const resolve = filters =>
+ resolveFilterRoutes({
+ routes,
+ filters,
+ knownComponents: [
+ 'core/Button',
+ 'core/ChatLayout',
+ 'core/ChatLayoutScrollButton',
+ 'core/ResizeHandle',
+ ],
+ componentPathOf: id => componentPaths[id],
+ ownerOf: filter => owners[filter] ?? null,
+ // Which story files use which component.
+ renders: (id, component) =>
+ id.startsWith('core-resizable--') && component === 'core/ResizeHandle',
+ });
+
+ it("audits a sub-component's stories under its own name (ResizeHandle → Core/Resizable)", () => {
+ const resolved = resolve(['core/resizehandle']);
+ expect(resolved.routes).toEqual([
+ {id: 'core-resizable--horizontal-split', component: 'core/ResizeHandle'},
+ {id: 'core-resizable--snap-points', component: 'core/ResizeHandle'},
+ ]);
+ expect(resolved.adopted).toEqual({
+ 'core/ResizeHandle': [
+ 'core-resizable--horizontal-split',
+ 'core-resizable--snap-points',
+ ],
+ });
+ });
+
+ it('adopts only stories that render the component: ChatLayoutScrollButton adopts none of Core/Chat', () => {
+ const resolved = resolve(['core/chatlayoutscrollbutton']);
+ expect(resolved.routes).toEqual([]);
+ expect(resolved.adopted).toEqual({});
+ });
+
+ it('keeps a filter a story title names, unchanged', () => {
+ expect(resolve(['core/button']).routes).toEqual([
+ {id: 'core-button--primary', component: 'core/Button'},
+ ]);
+ });
+
+ it('selects nothing for a filter with no story, which stays a coverage gap', () => {
+ expect(resolve(['core/nosuchthing']).routes).toEqual([]);
+ });
+
+ it('is the whole route list when no filter is given', () => {
+ expect(resolve([]).routes).toBe(routes);
+ });
+});
diff --git a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs b/apps/storybook/rtl-audit/rtl-audit-coverage.mjs
index 1d6657f042..5493dba3ef 100644
--- a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs
+++ b/apps/storybook/rtl-audit/rtl-audit-coverage.mjs
@@ -207,6 +207,68 @@ export function componentRoutesForFilters(routes, filters) {
);
}
+/**
+ * Resolve component filters to story routes through the Storybook index, not
+ * the export name alone. A filter a route names selects that route. A filter
+ * no route names adopts its source folder's orphan stories that render it:
+ * stories whose index `componentPath` lies in that folder, whose title names
+ * no public component, and whose story file uses the component
+ * (ResizeHandle adopts Core/Resizable's; ChatLayoutScrollButton adopts none
+ * of Core/Chat's, which never render it). Adopted stories are routed to the filter's
+ * own component, so it keeps its own coverage entry and verified-N/A record.
+ * A filter with neither selects nothing and stays a coverage gap
+ * (`architecture:rtl-audit-evidence` INV5).
+ * @param {{
+ * routes: {id: string, component: string}[],
+ * filters: string[],
+ * knownComponents: string[],
+ * componentPathOf: (storyId: string) => string | undefined,
+ * ownerOf: (filter: string) => {component: string, folder: string} | null,
+ * renders: (storyId: string, component: string) => boolean,
+ * }} input
+ */
+export function resolveFilterRoutes({
+ routes,
+ filters,
+ knownComponents,
+ componentPathOf,
+ ownerOf,
+ renders,
+}) {
+ if (filters.length === 0) return {routes, adopted: {}};
+ const known = new Set(knownComponents.map(name => name.toLowerCase()));
+ const selected = new Map();
+ const adopted = {};
+ for (const filter of filters) {
+ const direct = routes.filter(route =>
+ routeMatchesComponentFilter(route, filter),
+ );
+ for (const route of direct) {
+ selected.set(`${route.component}::${route.id}`, route);
+ }
+ if (direct.length > 0) continue;
+ const owner = ownerOf(filter);
+ if (owner == null) continue;
+ const orphans = routes.filter(
+ route =>
+ !known.has(route.component.toLowerCase()) &&
+ (componentPathOf(route.id) ?? '')
+ .replace(/^(\.\.\/)+/, '')
+ .startsWith(`${owner.folder}/`) &&
+ renders(route.id, owner.component),
+ );
+ if (orphans.length === 0) continue;
+ adopted[owner.component] = orphans.map(route => route.id).sort();
+ for (const {id} of orphans) {
+ selected.set(`${owner.component}::${id}`, {
+ id,
+ component: owner.component,
+ });
+ }
+ }
+ return {routes: [...selected.values()], adopted};
+}
+
/** Story ids owned by any bare or package-qualified component filter. */
export function storyIdsForComponentFilters(routes, filters) {
return [
diff --git a/apps/storybook/rtl-audit/rtl-audit.mjs b/apps/storybook/rtl-audit/rtl-audit.mjs
index 393d366633..a380de414f 100644
--- a/apps/storybook/rtl-audit/rtl-audit.mjs
+++ b/apps/storybook/rtl-audit/rtl-audit.mjs
@@ -66,6 +66,7 @@ import {
componentFromTarget,
evaluateDirectionalDecorations,
filterStoryRoutesByPackages,
+ resolveFilterRoutes,
finishFiniteAnimations,
orderD1StoryCandidates,
resolveD1Applicability,
@@ -88,6 +89,7 @@ import {
} from './rtl-audit-shards.mjs';
const {
+ componentExportsFromBarrel,
componentPackage,
flatPackageComponentNames,
nestedPackageComponentNames,
@@ -1193,6 +1195,64 @@ function matchesFilter(component) {
return !FILTER.length || FILTER.includes(normalized) || FILTER.includes(name);
}
+const storyFileSources = new Map();
+
+/** Whether a story file (an index `importPath`) uses a component by name. */
+function storyFileUses(importPath, component) {
+ if (!importPath) return false;
+ const file = path.join(PROJECT_ROOT, 'apps/storybook', importPath);
+ if (!storyFileSources.has(file)) {
+ let source = '';
+ try {
+ source = fs.readFileSync(file, 'utf8');
+ } catch {}
+ storyFileSources.set(file, source);
+ }
+ const name = component.split('/').at(-1);
+ return new RegExp(`\\b${name}\\b`).test(storyFileSources.get(file));
+}
+
+function readVerifiedNa() {
+ try {
+ const parsed = JSON.parse(fs.readFileSync(VERIFIED_NA_PATH, 'utf8'));
+ if (!Array.isArray(parsed)) throw new Error('verified-not-applicable registry must be a JSON array');
+ return {verifiedNa: parsed, verifiedNaError: null};
+ } catch (error) {
+ return {verifiedNa: [], verifiedNaError: String(error).slice(0, 200)};
+ }
+}
+
+/**
+ * A filter's public component and the source folder that implements it, from
+ * its package's barrel (`core/resizehandle` → core/ResizeHandle in
+ * packages/core/src/Resizable), or null.
+ */
+function sourceOwnerOf(filter, publicComponentsByPackage) {
+ const [packageName, requested] = filter.includes('/')
+ ? filter.split('/')
+ : [null, filter];
+ for (const name of packageName ? [packageName] : ACTIVE_PACKAGE_NAMES) {
+ const pkg = componentPackage(name);
+ if (!pkg) continue;
+ const component = (publicComponentsByPackage[name] ?? []).find(
+ candidate => candidate.toLowerCase() === requested,
+ );
+ if (!component) continue;
+ const sourceRoot = path.join(PROJECT_ROOT, pkg.src);
+ const implementation = componentExportsFromBarrel(
+ path.join(sourceRoot, 'index.ts'),
+ sourceRoot,
+ ).get(component);
+ if (!implementation) continue;
+ const folder = path
+ .relative(PROJECT_ROOT, path.dirname(implementation))
+ .split(path.sep)
+ .join('/');
+ return {component: `${name}/${component}`, folder};
+ }
+ return null;
+}
+
function belongsToActivePackage(route) {
return filterStoryRoutesByPackages([route], ACTIVE_PACKAGE_NAMES).length === 1;
}
@@ -1267,15 +1327,62 @@ async function cleanupRuntime() {
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`);
+ // Filters resolve through the index: a sub-component whose stories carry
+ // its parent folder's non-component title (ResizeHandle under
+ // Core/Resizable) audits them under its own name.
+ const resolvedFilters = resolveFilterRoutes({
+ routes: storyRoutes,
+ filters: FILTER,
+ knownComponents: Object.entries(publicComponentsByPackage).flatMap(
+ ([packageName, names]) => names.map(name => `${packageName}/${name}`),
+ ),
+ componentPathOf: id => entries[id]?.componentPath,
+ ownerOf: filter => sourceOwnerOf(filter, publicComponentsByPackage),
+ renders: (id, component) => storyFileUses(entries[id]?.importPath, component),
+ });
+ // A curated target on an adopted story checks the adopting component.
+ const adoptedBy = new Map(
+ Object.entries(resolvedFilters.adopted).flatMap(([component, storyIds]) =>
+ storyIds.map(id => [id, component]),
+ ),
+ );
+ const scopedStoryRoutes = resolvedFilters.routes;
+ for (const [component, storyIds] of Object.entries(resolvedFilters.adopted)) {
+ console.error(`NOTE ${component}: audits its folder's stories ${storyIds.join(', ')}`);
}
const auditedComponents = buildAuditedComponentRoster({
sourceComponents,
storyComponents: scopedStoryRoutes.map(route => route.component),
filters: FILTER,
});
+ if (scopedStoryRoutes.length === 0) {
+ if (FILTER.length === 0 || SHARD !== null) {
+ throw new Error(`no runnable stories resolved for ${ACTIVE_PACKAGE_NAMES.join(',')} scope`);
+ }
+ // A filtered run whose components have no story renders nothing, but its
+ // components are still in scope: write the coverage report, where each
+ // reads as a coverage gap or its verified N/A (INV5), instead of crashing.
+ const {verifiedNa, verifiedNaError} = readVerifiedNa();
+ const coverage = buildComponentCoverage({components: auditedComponents, verifiedNa});
+ if (verifiedNaError) coverage.registryError = verifiedNaError;
+ fs.writeFileSync(
+ OUT,
+ `${JSON.stringify(
+ {
+ generatedAt: new Date().toISOString(),
+ scope: {packages: ACTIVE_PACKAGE_NAMES, filters: FILTER},
+ coverage,
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ console.error(`NOTE no stories for ${FILTER.join(',')}; WROTE ${OUT} with coverage only`);
+ console.error(`COV : ${coverage.measured} measured / ${coverage.verifiedNa} verified N-A / ${coverage.gaps} gap / ${coverage.staleVerifiedNa} stale`);
+ process.exitCode =
+ coverage.gaps > 0 || coverage.staleVerifiedNa > 0 || coverage.registryError != null ? 1 : 0;
+ return;
+ }
// The audit's plan: D1 uses one deterministic representative story per
// component. Repository story-file/export order preserves the existing
@@ -1298,11 +1405,9 @@ async function cleanupRuntime() {
const storyTargets = scopedStoryRoutes.map(({id, component}) => ({id, comp: component}));
const curatedTargets = [];
for (const t of targets) {
- const component = componentFromTarget(
- t,
- AUDITED_PACKAGE_NAMES,
- publicComponentsByPackage,
- );
+ const component =
+ adoptedBy.get(t.storyId) ??
+ componentFromTarget(t, AUDITED_PACKAGE_NAMES, publicComponentsByPackage);
if (!belongsToActivePackage({component, id: t.storyId})) continue;
if (!matchesFilter(component)) continue;
if (!entries[t.storyId]) {
@@ -1468,15 +1573,7 @@ async function cleanupRuntime() {
}
}
- let verifiedNa = [];
- let verifiedNaError = null;
- try {
- const parsed = JSON.parse(fs.readFileSync(VERIFIED_NA_PATH, 'utf8'));
- if (!Array.isArray(parsed)) throw new Error('verified-not-applicable registry must be a JSON array');
- verifiedNa = parsed;
- } catch (error) {
- verifiedNaError = String(error).slice(0, 200);
- }
+ const {verifiedNa, verifiedNaError} = readVerifiedNa();
const coverage = buildComponentCoverage({
components: auditedComponents,