An open source design system that's fully customizable and agent ready
TypeScript
test(theme): guard participating Lab theming targets (#5717)
Cindy Zhange4f8e4ea3390
diff --git a/packages/core/src/theme/themingTargets.test.ts b/packages/core/src/theme/themingTargets.test.tsindex 11ba11453a..28f75d0997 100644--- a/packages/core/src/theme/themingTargets.test.ts+++ b/packages/core/src/theme/themingTargets.test.ts@@ -3,8 +3,10 @@/* eslint-disable @typescript-eslint/no-require-imports *//*** @file Guards `theming.targets` against the real `themeProps()` call sites (#3741).- * @input Component sources (*.tsx/*.ts) and their `{Name}.doc.mjs` files.- * @output Vitest failures naming each undocumented class / visual prop.+ * @input Core/Lab component sources (*.tsx/*.ts), their `{Name}.doc.mjs`+ * files, and the Lab promotion-candidate manifest.+ * @output Vitest failures naming each undocumented class / visual prop on the+ * stable Core surface or a capability-participating Lab component.* @position Sibling of derivedVarRegistry.test.ts, which already validates the* OTHER fields of the same `theming` block (`vars`, `derived`). `targets` was* the one field with no machine check, so it drifted — twice (#3652, #3680).@@ -22,6 +24,11 @@* `visualProps` or `states`. Docs may list MORE than the source passes —* components forward props they don't themselves reflect (Timestamp passes* `{format}` but documents `type`/`color`/`format`), and that is intentional.+ *+ * Lab is capability-based: a component participates when it already declares+ * `theming.targets` or enters the existing promotion-candidate manifest. Other+ * Lab components remain free to iterate with runtime hooks that are not yet a+ * documented public theming promise.*/import {describe, it, expect} from 'vitest';@@ -30,7 +37,23 @@ import {join, relative} from 'node:path';import ts from 'typescript';import {stableClassName} from '../naming';-const SRC_DIR = join(__dirname, '..');+const CORE_SRC_DIR = join(__dirname, '..');+const LAB_SRC_DIR = join(__dirname, '../../../lab/src');+const LAB_PROMOTION_MANIFEST = join(+ __dirname,+ '../../../../internal/lab-readiness/manifest.mjs',+);++interface LabPromotionCandidate {+ sourceDir: string;+}++const {CANDIDATES: labPromotionCandidates} = require(+ LAB_PROMOTION_MANIFEST,+) as {CANDIDATES: LabPromotionCandidate[]};+const LAB_PROMOTION_DIRS = new Set(+ labPromotionCandidates.map(candidate => candidate.sourceDir),+);// ---------------------------------------------------------------------------// Source scanning: find themeProps() call sites via the TypeScript AST@@ -314,6 +337,7 @@ type DocBlock = {theming?: {targets?: DocTarget[]}};type ComponentDocModule = {docs?: DocBlock; docsZh?: DocBlock};interface ComponentInfo {+ packageName: 'core' | 'lab';dir: string;sites: ThemeTargetSite[];/** The doc blocks that carry theming.targets, by the key they live under. */@@ -328,7 +352,10 @@ interface ComponentInfo {* Reads the file as text rather than requiring it: this runs for directories* that have no doc of their own, so most candidates are misses.*/-function docFilesDocumenting(classNames: Set<string>): string[] {+function docFilesDocumenting(+ srcDir: string,+ classNames: Set<string>,+): string[] {const matches: string[] = [];const walk = (dir: string): void => {for (const entry of readdirSync(dir, {withFileTypes: true})) {@@ -346,18 +373,22 @@ function docFilesDocumenting(classNames: Set<string>): string[] {}}};- walk(SRC_DIR);+ walk(srcDir);return matches;}-function discoverComponents(): ComponentInfo[] {+function discoverComponents(+ srcDir: string,+ packageName: ComponentInfo['packageName'],+ requiredDirs: ReadonlySet<string> = new Set(),+): ComponentInfo[] {const results: ComponentInfo[] = [];- const dirs = readdirSync(SRC_DIR, {withFileTypes: true})+ const dirs = readdirSync(srcDir, {withFileTypes: true}).filter(d => d.isDirectory()).map(d => d.name);for (const dir of dirs) {- const dirPath = join(SRC_DIR, dir);+ const dirPath = join(srcDir, dir);const dirEntries = readdirSync(dirPath);const sourceFiles = dirEntries.filter(@@ -389,10 +420,7 @@ function discoverComponents(): ComponentInfo[] {// doc file that CI never checks. (Same guard as derivedVarRegistry.test.ts.)const docFiles = dirEntries.includes(`${dir}.doc.mjs`)? [join(dirPath, `${dir}.doc.mjs`)]- : docFilesDocumenting(new Set(sites.map(s => s.className)));- if (docFiles.length === 0) {- continue;- }+ : docFilesDocumenting(srcDir, new Set(sites.map(s => s.className)));const docBlocks: ComponentInfo['docBlocks'] = [];for (const docFile of docFiles) {@@ -404,18 +432,23 @@ function discoverComponents(): ComponentInfo[] {}for (const key of ['docs', 'docsZh'] as const) {const targets = mod[key]?.theming?.targets;- // Only blocks that already document a theming surface are held to it —- // a doc with no theming block at all is a separate (documentation) gap.+ // A normal Core or Lab component enrolls by declaring a theming+ // surface. Promotion candidates are also enrolled here so a missing+ // block is a failure rather than a silently skipped readiness gap.if (targets != null) {- docBlocks.push({key, file: relative(SRC_DIR, docFile), targets});+ docBlocks.push({key, file: relative(srcDir, docFile), targets});}}}- if (docBlocks.length === 0) {+ const participates =+ packageName === 'core'+ ? docBlocks.length > 0+ : requiredDirs.has(dir) || docBlocks.length > 0;+ if (!participates) {continue;}- results.push({dir, sites, docBlocks});+ results.push({packageName, dir, sites, docBlocks});}return results;}@@ -425,24 +458,57 @@ function discoverComponents(): ComponentInfo[] {// ---------------------------------------------------------------------------describe('theming.targets matches the themeProps() call sites', () => {- const components = discoverComponents();+ const components = [+ ...discoverComponents(CORE_SRC_DIR, 'core'),+ ...discoverComponents(LAB_SRC_DIR, 'lab', LAB_PROMOTION_DIRS),+ ];++ it('finds participating Core and Lab components', () => {+ // A refactor that renames themeProps or drops the Lab package from this+ // inventory must not silently disable either side of the guard.+ expect(components.some(component => component.packageName === 'core')).toBe(+ true,+ );+ expect(components.some(component => component.packageName === 'lab')).toBe(+ true,+ );+ });- it('finds components to check', () => {- // A refactor that renames themeProps must not silently disable this file.- expect(components.length).toBeGreaterThan(0);+ it('enrolls every Lab promotion candidate and explicit theming capability', () => {+ const labDirs = new Set(+ components+ .filter(component => component.packageName === 'lab')+ .map(component => component.dir),+ );+ expect([...LAB_PROMOTION_DIRS].filter(dir => !labDirs.has(dir))).toEqual(+ [],+ );+ expect(LAB_PROMOTION_DIRS.has('CircularProgress')).toBe(false);+ expect(labDirs.has('CircularProgress')).toBe(true);+ expect(labDirs.has('Schedule')).toBe(false);});- for (const {dir, sites, docBlocks} of components) {+ for (const {packageName, dir, sites, docBlocks} of components) {+ const componentLabel = `${packageName}/${dir}`;const renderedClasses = [...new Set(sites.map(s => s.className))].sort();+ it(`${componentLabel}: participating components declare theming metadata`, () => {+ expect(+ docBlocks,+ `${componentLabel} participates in the public theming contract but has ` ++ `no loadable .doc.mjs theming.targets. Lab components participate ` ++ `when they declare theming.targets or enter the promotion manifest.`,+ ).not.toHaveLength(0);+ });+for (const {key, file, targets} of docBlocks) {const documented = new Set(targets.map(t => t.className));- it(`${dir} (${file} ${key}): every rendered class is documented`, () => {+ it(`${componentLabel} (${file} ${key}): every rendered class is documented`, () => {const undocumented = renderedClasses.filter(c => !documented.has(c));expect(undocumented,- `${dir} renders ${undocumented.length} astryx-* class(es) that ` ++ `${componentLabel} renders ${undocumented.length} astryx-* class(es) that ` +`${file} ${key}.theming.targets does not document: ` +`${undocumented.join(', ')}. An undocumented class is an ` +`unthemeable element — theme authors and codegen read targets[] ` +@@ -450,7 +516,7 @@ describe('theming.targets matches the themeProps() call sites', () => {).toEqual([]);});- it(`${dir} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {+ it(`${componentLabel} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {const missing: string[] = [];for (const site of sites) {const target = targets.find(t => t.className === site.className);