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.mjsindex 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.mjsindex 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.mjsindex 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,