An open source design system that's fully customizable and agent ready
TypeScript
fix(build): make fully-specified diagnostics theme-aware (#5126)
Xinzi Zhou840d66f0669f
diff --git a/scripts/check-fully-specified.mjs b/scripts/check-fully-specified.mjsindex 96f4a629e2..6b25527222 100644--- a/scripts/check-fully-specified.mjs+++ b/scripts/check-fully-specified.mjs@@ -5,21 +5,22 @@* Build-output check: verify every relative specifier in the compiled dist* is fully specified (carries an explicit file extension).*- * The packages publish "type": "module" dist, where Node ESM makes- * extensions mandatory for relative specifiers — strict-ESM consumers (Node- * itself, Rspack, webpack's `fullySpecified`) refuse to resolve- * './XDSButton' where './XDSButton.js' is required.- * babel-plugin-add-extensions rewrites specifiers during compilation; this- * guard makes sure nothing slips past it into the artifact again (#4569:- * dynamic `import()` specifiers did exactly that).+ * These runtime files are consumed as ESM, where relative specifiers need an+ * explicit extension — strict-ESM consumers (Node itself, Rspack, webpack's+ * `fullySpecified`) refuse to resolve './XDSButton' where './XDSButton.js' is+ * required. Different packages use different compilers to produce those+ * specifiers; this guard makes sure nothing slips into the artifact again+ * (#4569: dynamic `import()` specifiers did exactly that).** Like check-no-dev-jsx.mjs this is a textual scan, not a parse. Comment* lines are skipped: dist keeps some JSDoc comments whose usage examples* legitimately mention extensionless specifiers. Only runtime files are* scanned — the .d.ts surface resolves through TypeScript, not Node.*- * Usage: node ../../scripts/check-fully-specified.mjs (run from a package- * root, after the package's dist has been built)+ * Usage: node <repo-root>/scripts/check-fully-specified.mjs (run from a+ * package root, after the package's dist has been built; the relative depth+ * differs per package — ../../ from packages/*, ../../../ from+ * packages/themes/*)*/import fs from 'node:fs';import path from 'node:path';@@ -90,6 +91,45 @@ export function findOffenders(distDir) {return {checked: files.length, offenders};}+/**+ * Return remediation guidance for the package whose dist is being checked.+ *+ * The package name is consulted before the Babel plugin file: a maintained+ * theme generates its icon import through `astryx theme build`, so the theme+ * branch stays correct even if such a package later picks up the plugin for+ * some other part of its build.+ */+export function failureGuidance(packageDir) {+ let packageName = '';+ try {+ const packageJson = JSON.parse(+ fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),+ );+ packageName = typeof packageJson.name === 'string' ? packageJson.name : '';+ } catch {+ // A package manifest is useful context, not a requirement for the scan.+ }++ if (packageName.startsWith('@astryxdesign/theme-')) {+ return (+ "Fix: check the package's `astryx theme build --icons-specifier` " ++ 'value and any other build step that emitted the reported file.'+ );+ }++ if (fs.existsSync(path.join(packageDir, 'babel-plugin-add-extensions.cjs'))) {+ return (+ "Fix: make sure the package's babel-plugin-add-extensions.cjs " ++ 'rewrites the syntax form that produced them.'+ );+ }++ return (+ 'Fix: update the build step that emitted the reported file so its ' ++ 'relative specifiers include explicit extensions.'+ );+}+function main() {const distDir = path.resolve(process.cwd(), 'dist');if (!fs.existsSync(distDir)) {@@ -111,10 +151,8 @@ function main() {}console.error(`\n${offenders.length} file(s) ship specifiers without a file ` +- 'extension. The dist is "type": "module", so Node ESM and ' +- 'strict-ESM bundlers cannot resolve them (see #4569).\n' +- "Fix: make sure the package's babel-plugin-add-extensions.cjs " +- 'rewrites the syntax form that produced them.',+ 'extension. ESM loaders and strict-ESM bundlers cannot resolve ' ++ `them (see #4569).\n${failureGuidance(process.cwd())}`,);process.exit(1);}diff --git a/scripts/check-fully-specified.test.mjs b/scripts/check-fully-specified.test.mjsindex f8fbacf90d..d5c1873a3f 100644--- a/scripts/check-fully-specified.test.mjs+++ b/scripts/check-fully-specified.test.mjs@@ -10,8 +10,18 @@import fs from 'node:fs';import os from 'node:os';import path from 'node:path';+import {fileURLToPath} from 'node:url';import {describe, it, expect, beforeAll, afterAll} from 'vitest';-import {scanSource, findOffenders} from './check-fully-specified.mjs';+import {+ scanSource,+ findOffenders,+ failureGuidance,+} from './check-fully-specified.mjs';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');++/** Escape a literal string for embedding in a RegExp source. */+const escapeRegExp = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');describe('scanSource', () => {it('flags an extensionless static import specifier', () => {@@ -164,3 +174,97 @@ describe('findOffenders', () => {}});});++describe('failureGuidance', () => {+ it('points maintained themes at --icons-specifier', () => {+ const dir = fs.mkdtempSync(+ path.join(os.tmpdir(), 'fully-specified-theme-'),+ );+ try {+ fs.writeFileSync(+ path.join(dir, 'package.json'),+ JSON.stringify({name: '@astryxdesign/theme-example'}),+ );+ expect(failureGuidance(dir)).toContain('--icons-specifier');+ expect(failureGuidance(dir)).not.toContain(+ 'babel-plugin-add-extensions.cjs',+ );+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });++ it('retains the Babel hint for packages that use the extension plugin', () => {+ const dir = fs.mkdtempSync(+ path.join(os.tmpdir(), 'fully-specified-babel-'),+ );+ try {+ fs.writeFileSync(path.join(dir, 'package.json'), '{}');+ fs.writeFileSync(path.join(dir, 'babel-plugin-add-extensions.cjs'), '');+ expect(failureGuidance(dir)).toContain('babel-plugin-add-extensions.cjs');+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });++ it('gives package-neutral guidance for other build pipelines', () => {+ const dir = fs.mkdtempSync(+ path.join(os.tmpdir(), 'fully-specified-generic-'),+ );+ try {+ fs.writeFileSync(+ path.join(dir, 'package.json'),+ JSON.stringify({name: '@astryxdesign/example'}),+ );+ expect(failureGuidance(dir)).toContain('build step');+ expect(failureGuidance(dir)).not.toContain('--icons-specifier');+ expect(failureGuidance(dir)).not.toContain(+ 'babel-plugin-add-extensions.cjs',+ );+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });++ it('falls back to neutral guidance when the manifest is unreadable', () => {+ const dir = fs.mkdtempSync(+ path.join(os.tmpdir(), 'fully-specified-no-manifest-'),+ );+ try {+ expect(failureGuidance(dir)).toContain('build step');+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });+});++describe('maintained-theme build wiring', () => {+ it('keeps the fully-specified gate wired into every maintained-theme build', () => {+ const themesRoot = path.join(ROOT, 'packages', 'themes');+ const gate = path.join(ROOT, 'scripts', 'check-fully-specified.mjs');+ const packages = fs+ .readdirSync(themesRoot, {withFileTypes: true})+ .filter(entry => entry.isDirectory())+ .map(entry => path.join(themesRoot, entry.name))+ .filter(dir => fs.existsSync(path.join(dir, 'package.json')))+ .map(dir => ({+ dir,+ pkg: JSON.parse(+ fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'),+ ),+ }))+ .filter(({pkg}) => pkg.name?.startsWith('@astryxdesign/theme-'));++ expect(packages.length).toBeGreaterThan(0);+ for (const {dir, pkg} of packages) {+ // Derive the specifier so a move of packages/themes fails loudly here+ // instead of silently matching nothing. Any trailing build step or flag+ // is fine — what matters is that the gate still runs.+ const specifier = path.relative(dir, gate).split(path.sep).join('/');+ const invocation = new RegExp(+ `\\bnode\\s+${escapeRegExp(specifier)}(?:\\s|$)`,+ );+ expect(pkg.scripts?.build ?? '', pkg.name).toMatch(invocation);+ }+ });+});