Skip to content

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.mjs
index 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.mjs
index 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);
+ }
+ });
+});