An open source design system that's fully customizable and agent ready
TypeScript
fix(themes,cli): gate theme dists with check-fully-specified and pin --icons-specifier coverage (#4625)
AK8b07cb95244b
diff --git a/.changeset/theme-built-entry-node-esm.md b/.changeset/theme-built-entry-node-esm.mdnew file mode 100644index 0000000000..67bdf848b6--- /dev/null+++ b/.changeset/theme-built-entry-node-esm.md@@ -0,0 +1,12 @@+---+'@astryxdesign/theme-butter': patch+'@astryxdesign/theme-chocolate': patch+'@astryxdesign/theme-gothic': patch+'@astryxdesign/theme-matcha': patch+'@astryxdesign/theme-neutral': patch+'@astryxdesign/theme-stone': patch+'@astryxdesign/theme-y2k': patch+---++[fix] The `/built` entry now loads under Node ESM and externalized SSR (Vite `--ssr`, Remix / React Router v7): it imports `./icons.mjs` instead of the extensionless `./icons` Node cannot resolve.+@AKnassadiff --git a/packages/cli/api/theme/build/build.icons-specifier.test.mjs b/packages/cli/api/theme/build/build.icons-specifier.test.mjsnew file mode 100644index 0000000000..054f0ce863--- /dev/null+++ b/packages/cli/api/theme/build/build.icons-specifier.test.mjs@@ -0,0 +1,149 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Direct-API tests for `themeBuild`'s `iconsSpecifier` option (#4620).+ *+ * The CLI surface of `--icons-specifier` is pinned in+ * clients/cli/commands/build-theme.icons-specifier.test.mjs; these tests pin+ * the programmatic surface that watch mode, editor tooling, and build scripts+ * call directly: the option reaches the emitted module, its absence leaves the+ * scraped specifier byte-for-byte alone, and `check` mode compares the+ * specifier-bearing text like any other generated byte — outputs built with a+ * different specifier than the one being checked against are stale, not clean.+ */++import {describe, it, expect, beforeEach, afterEach} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import * as os from 'node:os';+import {themeBuild} from './build.mjs';++let tmpDir;+beforeEach(() => {+ tmpDir = fs.mkdtempSync(+ path.join(os.tmpdir(), 'astryx-api-icons-specifier-'),+ );+});+afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++/**+ * Write a theme source (plus a loadable icons source beside it) under+ * `<tmpDir>/src/`. The registry is a plain object — the emit path only+ * re-exports it, so no React is needed.+ */+function writeIconTheme({withIcons = true, name = 'icotheme'} = {}) {+ const srcDir = path.join(tmpDir, 'src');+ fs.mkdirSync(srcDir, {recursive: true});+ fs.writeFileSync(+ path.join(srcDir, 'icons.ts'),+ `export const myIcons = { close: 'x' };\n`,+ );+ const iconLines = withIcons ? [`import { myIcons } from './icons';`] : [];+ fs.writeFileSync(+ path.join(srcDir, `${name}.ts`),+ [+ ...iconLines,+ `export default { name: '${name}', tokens: { '--color-bg': '#fff' }${+ withIcons ? ', icons: myIcons' : ''+ } };`,+ '',+ ].join('\n'),+ );+ return `src/${name}.ts`;+}++function builtModule(name = 'icotheme') {+ return fs.readFileSync(path.join(tmpDir, 'dist', `${name}.js`), 'utf8');+}++describe('themeBuild({iconsSpecifier}) — direct API', () => {+ it('emits the declared specifier into the generated module', async () => {+ const file = writeIconTheme();++ const result = await themeBuild(+ file,+ {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},+ {cwd: tmpDir},+ );++ expect(result?.type).toBe('theme.build');+ const js = builtModule();+ expect(js).toContain(`import { myIcons } from "./icons.mjs";`);+ // The registry re-export survives the override.+ expect(js).toContain('export { myIcons }');+ });++ it('emits the scraped specifier unchanged when the option is omitted', async () => {+ const file = writeIconTheme();++ const result = await themeBuild(+ file,+ {out: 'dist/theme.css'},+ {cwd: tmpDir},+ );++ expect(result?.type).toBe('theme.build');+ expect(builtModule()).toContain(`import { myIcons } from './icons';`);+ });++ it('is inert for a theme with no icons field', async () => {+ const file = writeIconTheme({withIcons: false});++ const result = await themeBuild(+ file,+ {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},+ {cwd: tmpDir},+ );++ expect(result?.type).toBe('theme.build');+ // The header comment's usage example mentions imports; only a real+ // statement (line-leading `import`) would be a leak.+ const js = builtModule();+ expect(js).not.toMatch(/^import /m);+ expect(js).not.toContain('icons.mjs');+ });++ it('check mode is clean against outputs built with the same specifier', async () => {+ const file = writeIconTheme();+ await themeBuild(+ file,+ {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},+ {cwd: tmpDir},+ );++ const result = await themeBuild(+ file,+ {out: 'dist/theme.css', check: true, iconsSpecifier: './icons.mjs'},+ {cwd: tmpDir},+ );++ expect(result?.type).toBe('theme.build.check');+ expect(result?.data.upToDate).toBe(true);+ expect(result?.data.stale).toEqual([]);+ });++ it('check mode reports outputs stale when the specifier differs', async () => {+ const file = writeIconTheme();+ await themeBuild(+ file,+ {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},+ {cwd: tmpDir},+ );++ // Checking without the option regenerates with the scraped './icons' —+ // different bytes than the on-disk module, so the check must flag it.+ const result = await themeBuild(+ file,+ {out: 'dist/theme.css', check: true},+ {cwd: tmpDir},+ );++ expect(result?.type).toBe('theme.build.check');+ expect(result?.data.upToDate).toBe(false);+ expect(result?.data.stale.some(entry => entry.reason === 'outdated')).toBe(+ true,+ );+ });+});diff --git a/packages/cli/clients/cli/commands/build-theme.icons-specifier.test.mjs b/packages/cli/clients/cli/commands/build-theme.icons-specifier.test.mjsindex c130d9dfc4..0768a5177f 100644--- a/packages/cli/clients/cli/commands/build-theme.icons-specifier.test.mjs+++ b/packages/cli/clients/cli/commands/build-theme.icons-specifier.test.mjs@@ -15,15 +15,34 @@* declared rather than inferred. Absent the flag, output is byte-for-byte what* it was before, which keeps the default no-`--out` flow — where the neighbour* is an uncompiled `icons.tsx` that only a bundler can resolve — working.+ *+ * The spawned-process block at the bottom pins what only real processes can+ * prove: the emitted module actually loads under Node ESM, and the watch+ * loop's child re-invocations carry the flag to every rebuild.*/import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';+import {spawn, spawnSync} from 'node:child_process';import * as fs from 'node:fs';import * as path from 'node:path';import * as os from 'node:os';+import {fileURLToPath, pathToFileURL} from 'node:url';import {ensureCoreBuilt} from './ensure-core-built.mjs';import {runCli} from '../../../test-utils/run-cli.mjs';+const __dirname = path.dirname(fileURLToPath(import.meta.url));+const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');++/** Poll until `predicate()` is true or the timeout elapses. */+async function waitFor(predicate, {timeout = 20000, interval = 100} = {}) {+ const start = Date.now();+ for (;;) {+ if (predicate()) return true;+ if (Date.now() - start > timeout) return false;+ await new Promise(r => setTimeout(r, interval));+ }+}+/*** The emitted icon import, or null. Reads the statement rather than the whole* file: the `@generated` header quotes the source filename and a usage example,@@ -142,13 +161,7 @@ describe('theme build --icons-specifier', () => {const relativeTheme = path.relative(project, themeFile);const built = await runCli(- [- 'theme',- 'build',- relativeTheme,- '--icons-specifier',- './icons.mjs',- ],+ ['theme', 'build', relativeTheme, '--icons-specifier', './icons.mjs'],project,);expect(built.code).toBe(0);@@ -223,3 +236,114 @@ describe('theme build --icons-specifier', () => {expect(generated).not.toContain('icons:');});});++describe('theme build --icons-specifier (spawned processes)', () => {+ it('emits a module Node can actually load', async () => {+ const project = path.join(tmpDir, 'project');+ const themeFile = writeThemeWithIcons(project, 'loadable');++ const result = await runCli(+ [+ 'theme',+ 'build',+ path.relative(project, themeFile),+ '--icons-specifier',+ './icons.mjs',+ ],+ project,+ );+ expect(result.code).toBe(0);++ // The text assertions above prove the emitted line; only a real Node+ // process proves the module resolves and evaluates. That distinction is+ // the regression #4620 shipped: every byte existed, none of them loaded.+ const builtUrl = pathToFileURL(path.join(project, 'loadable.js'));+ const probe = spawnSync(+ process.execPath,+ [+ '--input-type=module',+ '-e',+ `const m = await import(${JSON.stringify(builtUrl.href)});` ++ `if (m.loadableTheme?.name !== 'loadable') throw new Error('bad theme export');` ++ `if (typeof m.testIcons !== 'object') throw new Error('bad registry export');`,+ ],+ {encoding: 'utf8'},+ );+ expect(probe.stderr).toBe('');+ expect(probe.status).toBe(0);+ });++ it('watch mode forwards the flag to every rebuild', async () => {+ const project = path.join(tmpDir, 'project');+ const themeFile = writeThemeWithIcons(project, 'watched');+ const cssFile = path.join(project, 'out', 'theme.css');+ const builtFile = path.join(project, 'out', 'watched.js');+ const declaredImport = 'import { testIcons } from "./icons.mjs";';++ const child = spawn(+ process.execPath,+ [+ CLI_BIN,+ 'theme',+ 'build',+ path.relative(project, themeFile),+ '--out',+ 'out/theme.css',+ '--icons-specifier',+ './icons.mjs',+ '--watch',+ ],+ {cwd: project, env: {...process.env, FORCE_COLOR: '0'}},+ );+ let output = '';+ child.stdout.on('data', d => (output += d.toString()));+ child.stderr.on('data', d => (output += d.toString()));++ try {+ // Initial build: the declared specifier reaches the module.+ expect(await waitFor(() => fs.existsSync(cssFile))).toBe(true);+ expect(await waitFor(() => /Watching/i.test(output))).toBe(true);+ expect(iconImportLine(fs.readFileSync(builtFile, 'utf8'))).toBe(+ declaredImport,+ );++ // Rebuilds run through a child re-invocation of `theme build`, so the+ // flag reaches them only if the watch loop forwards it. Change a token+ // and wait for the rebuilt CSS. fs.watch delivery is best-effort under+ // load, so re-touch until the rebuild shows up (idempotent write).+ const touched =+ `import {testIcons} from './icons';\n` ++ `export default {\n` ++ ` name: "watched",\n` ++ ` icons: testIcons,\n` ++ ` tokens: {'--color-bg': '#0a0b0c'},\n` ++ `};\n`;+ fs.writeFileSync(themeFile, touched);+ const rebuilt = await waitFor(() => {+ try {+ if (fs.readFileSync(cssFile, 'utf-8').includes('#0a0b0c'))+ return true;+ } catch {+ // CSS mid-write; fall through to re-touch.+ }+ try {+ fs.writeFileSync(themeFile, touched);+ } catch {+ // Retried on the next poll.+ }+ return false;+ });+ expect(rebuilt).toBe(true);++ // The regenerated module still carries the declared specifier — the+ // forwarding is what this test pins. A watch loop that dropped the flag+ // would regenerate with the scraped './icons' here and ship the #4620+ // bytes on every save.+ expect(iconImportLine(fs.readFileSync(builtFile, 'utf8'))).toBe(+ declaredImport,+ );+ } finally {+ child.kill('SIGINT');+ }+ }, 60_000);+});diff --git a/packages/themes/butter/package.json b/packages/themes/butter/package.jsonindex a8a8cb2f6e..7489d85ae4 100644--- a/packages/themes/butter/package.json+++ b/packages/themes/butter/package.json@@ -46,7 +46,7 @@"src"],"scripts": {- "build": "astryx theme build src/butterTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"+ "build": "astryx theme build src/butterTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"},"dependencies": {"lucide-react": "^1.18.0"diff --git a/packages/themes/chocolate/package.json b/packages/themes/chocolate/package.jsonindex f26b62b5b8..4b37009e3e 100644--- a/packages/themes/chocolate/package.json+++ b/packages/themes/chocolate/package.json@@ -46,7 +46,7 @@"src"],"scripts": {- "build": "astryx theme build src/chocolateTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"+ "build": "astryx theme build src/chocolateTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"},"dependencies": {"lucide-react": "^1.18.0"diff --git a/packages/themes/gothic/package.json b/packages/themes/gothic/package.jsonindex e2dccf07c8..789ca5a474 100644--- a/packages/themes/gothic/package.json+++ b/packages/themes/gothic/package.json@@ -46,7 +46,7 @@"src"],"scripts": {- "build": "astryx theme build src/gothicTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"+ "build": "astryx theme build src/gothicTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"},"dependencies": {"lucide-react": "^1.18.0"diff --git a/packages/themes/matcha/package.json b/packages/themes/matcha/package.jsonindex 888313d7e9..e2ee53b2f6 100644--- a/packages/themes/matcha/package.json+++ b/packages/themes/matcha/package.json@@ -45,7 +45,7 @@"src"],"scripts": {- "build": "astryx theme build src/matchaTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"+ "build": "astryx theme build src/matchaTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"},"dependencies": {"lucide-react": "^1.18.0"diff --git a/packages/themes/neutral/package.json b/packages/themes/neutral/package.jsonindex 3c5026bbbf..6689692278 100644--- a/packages/themes/neutral/package.json+++ b/packages/themes/neutral/package.json@@ -46,7 +46,7 @@"src"],"scripts": {- "build": "astryx theme build src/neutralTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"+ "build": "astryx theme build src/neutralTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"},"dependencies": {"lucide-react": "^1.18.0"diff --git a/packages/themes/stone/package.json b/packages/themes/stone/package.jsonindex ac0bcb331a..1109fd6c98 100644--- a/packages/themes/stone/package.json+++ b/packages/themes/stone/package.json@@ -46,7 +46,7 @@"src"],"scripts": {- "build": "astryx theme build src/stoneTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"+ "build": "astryx theme build src/stoneTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"},"dependencies": {"lucide-react": "^1.18.0"diff --git a/packages/themes/y2k/package.json b/packages/themes/y2k/package.jsonindex bc708b6da8..84916a4731 100644--- a/packages/themes/y2k/package.json+++ b/packages/themes/y2k/package.json@@ -46,7 +46,7 @@"src"],"scripts": {- "build": "astryx theme build src/y2kTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json"+ "build": "astryx theme build src/y2kTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"},"dependencies": {"lucide-react": "^1.18.0"