Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
45.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * Direct API tests for `themeBuild()` — the programmatic surface behind
 * `astryx theme build` (`@astryxdesign/cli/api`).
 *
 * The CLI suites (cli/commands/build-theme.*.test.mjs) drive `registerTheme`
 * end-to-end; these assert the API contract you get calling `themeBuild()` in
 * code: the typed `theme.build` receipt (with files actually written to disk),
 * that it honors the `cwd` option, stays SILENT under the default noopLogger,
 * returns `null` when there is nothing to build, and rejects unsupported icon
 * registries without creating or changing outputs in build and check modes.
 *
 * `themeBuild` compiles via @astryxdesign/core's generator, so it needs a built
 * core — the `node` project's globalSetup (vitest.global-setup.node.mjs) builds
 * it once before workers fork.
 */

import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import {
  makeLinkedFixture,
  removeLinkedFixture,
} from '../../../test-utils/linked-fixture.mjs';
import {
  generateThemeRulesSplit as mockGenerateThemeRulesSplit,
  generateOnMediaCSS as mockGenerateOnMediaCSS,
} from '@astryxdesign/core/theme';
import {
  themeBuild,
  validateComponentOverridesAgainstRegistry,
  validateThemePrivateInputs,
} from './build.mjs';

// `themeBuild` captures core's generator once at module load. Wrap the two
// CSS-emitting exports in vi.fn (call-through by default) so the receipt tests
// exercise the REAL generator, while the "nothing to build" test can force an
// empty result for a single call — the only way to reach that branch, since
// core's prose element defaults otherwise always ship a non-empty CSS block.
vi.mock('@astryxdesign/core/theme', async importActual => {
  const actual = /** @type {Record<string, unknown>} */ (await importActual());
  return {
    ...actual,
    generateThemeRulesSplit: vi.fn(actual.generateThemeRulesSplit),
    generateOnMediaCSS: vi.fn(actual.generateOnMediaCSS),
  };
});

vi.setConfig({testTimeout: 30000});

let tmpDir;
beforeEach(() => {
  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-build-api-'));
});
afterEach(() => {
  fs.rmSync(tmpDir, {recursive: true, force: true});
  // Clear call history only — do NOT restore, which would drop the vi.fn
  // call-through implementations set up in the factory above.
  vi.clearAllMocks();
});

describe('themeBuild() — receipt', () => {
  it('compiles a minimal theme and returns a theme.build receipt with files on disk', async () => {
    const themeFile = path.join(tmpDir, 'apitheme.mjs');
    fs.writeFileSync(
      themeFile,
      `export default { name: 'apitheme', tokens: { '--color-bg': '#0a0a0a' } };\n`,
    );

    // Resolve `file` against the cwd option (not process.cwd()).
    const result = await themeBuild('apitheme.mjs', {}, {cwd: tmpDir});

    expect(result).not.toBeNull();
    expect(result?.type).toBe('theme.build');
    expect(result?.data.name).toBe('apitheme');
    expect(result?.data.sizeKB).toBeGreaterThan(0);

    // Output paths are cwd-relative and derive from the theme name…
    expect(result?.data.outputs.css).toBe('apitheme.css');
    expect(result?.data.outputs.cssDts).toBe('apitheme.css.d.ts');
    expect(result?.data.outputs.js).toBe('apitheme.js');
    expect(result?.data.outputs.dts).toBe('apitheme.d.ts');
    // …and every declared output actually exists on disk.
    for (const rel of [
      result?.data.outputs.css,
      result?.data.outputs.cssDts,
      result?.data.outputs.js,
      result?.data.outputs.dts,
    ]) {
      expect(
        fs.existsSync(path.join(tmpDir, /** @type {string} */ (rel))),
      ).toBe(true);
    }
    expect(
      fs.readFileSync(path.join(tmpDir, 'apitheme.css.d.ts'), 'utf8'),
    ).toContain('export {};');
  });

  it('emits local tokens and preserves enrollment metadata in the built module', async () => {
    const themeFile = path.join(tmpDir, 'local-theme.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'local-theme',
        localTokens: {
          '--ac-selection-ink': ['#0077b6', '#48cae4'],
        },
        components: {
          badge: {
            'variant:info': {
              backgroundColor: 'var(--ac-selection-ink)',
            },
          },
        },
      };\n`,
    );

    const result = await themeBuild('local-theme.mjs', {}, {cwd: tmpDir});
    const css = fs.readFileSync(path.join(tmpDir, 'local-theme.css'), 'utf8');
    const built = fs.readFileSync(path.join(tmpDir, 'local-theme.js'), 'utf8');

    expect(result?.data.tokenCount).toBe(1);
    expect(css).toContain('--ac-selection-ink: light-dark(#0077b6, #48cae4);');
    expect(built).toContain('localTokens: {');
    expect(built).toContain('__localTokenOwners: {');
    expect(built).toContain('__localTokenLineage: ["local-theme"]');
  });

  it.each(['VAR', 'vAr'])(
    'rejects local-token cycles using %s() before writing outputs',
    async functionName => {
      const themeFile = path.join(tmpDir, 'cyclic-local-theme.mjs');
      fs.writeFileSync(
        themeFile,
        `export default {
          name: 'cyclic-local-theme',
          localTokens: {
            '--astryx-theme-cyclic-local-theme-color-a': '${functionName}(--astryx-theme-cyclic-local-theme-color-b)',
            '--astryx-theme-cyclic-local-theme-color-b': '${functionName}(--astryx-theme-cyclic-local-theme-color-a)',
          },
        };\n`,
      );

      await expect(
        themeBuild('cyclic-local-theme.mjs', {}, {cwd: tmpDir}),
      ).rejects.toThrow(/cycle detected/);
      expect(fs.existsSync(path.join(tmpDir, 'cyclic-local-theme.css'))).toBe(
        false,
      );
      expect(fs.existsSync(path.join(tmpDir, 'cyclic-local-theme.js'))).toBe(
        false,
      );
      expect(fs.existsSync(path.join(tmpDir, 'cyclic-local-theme.d.ts'))).toBe(
        false,
      );
    },
  );

  it('rejects cross-map duplicate token names before writing outputs', async () => {
    const themeFile = path.join(tmpDir, 'duplicate-local-theme.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'duplicate-local-theme',
        tokens: {
          '--astryx-theme-duplicate-local-theme-color-accent': '#0077b6',
        },
        localTokens: {
          '--astryx-theme-duplicate-local-theme-color-accent': '#48cae4',
        },
      };\n`,
    );

    await expect(
      themeBuild('duplicate-local-theme.mjs', {}, {cwd: tmpDir}),
    ).rejects.toThrow(/both tokens and localTokens/);
    expect(fs.existsSync(path.join(tmpDir, 'duplicate-local-theme.css'))).toBe(
      false,
    );
    expect(fs.existsSync(path.join(tmpDir, 'duplicate-local-theme.js'))).toBe(
      false,
    );
    expect(fs.existsSync(path.join(tmpDir, 'duplicate-local-theme.d.ts'))).toBe(
      false,
    );
  });

  it('is silent by default (noopLogger) — no console output for a scripted caller', async () => {
    const themeFile = path.join(tmpDir, 'quiet.mjs');
    fs.writeFileSync(
      themeFile,
      `export default { name: 'quiet', tokens: { '--color-bg': '#fff' } };\n`,
    );

    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const outSpy = vi
      .spyOn(process.stdout, 'write')
      .mockImplementation(() => true);

    try {
      const result = await themeBuild('quiet.mjs', {}, {cwd: tmpDir});
      expect(result?.type).toBe('theme.build');
      expect(logSpy).not.toHaveBeenCalled();
      expect(warnSpy).not.toHaveBeenCalled();
      expect(errSpy).not.toHaveBeenCalled();
      expect(outSpy).not.toHaveBeenCalled();
    } finally {
      logSpy.mockRestore();
      warnSpy.mockRestore();
      errSpy.mockRestore();
      outSpy.mockRestore();
    }
  });
});

describe.each(['mjs', 'ts'])('a .%s theme module with no theme export', ext => {
  beforeEach(() => {
    fs.writeFileSync(
      path.join(tmpDir, `none.${ext}`),
      'export const notATheme = 42;\n',
    );
  });

  it('fails the build as a module that does not load a theme', async () => {
    const build = themeBuild(`none.${ext}`, {}, {cwd: tmpDir});
    await expect(build).rejects.toThrow(
      /Could not find a defineTheme\(\) result/,
    );
    await expect(build).rejects.toMatchObject({code: 'ERR_THEME_LOAD'});
  });

  it("fails doctor's private-input check the same way, rather than read its exports as a theme", async () => {
    await expect(
      validateThemePrivateInputs(`none.${ext}`, {cwd: tmpDir}),
    ).rejects.toThrow(/Could not find a defineTheme\(\) result/);
  });
});

describe('themeBuild() — a theme module that does not load', () => {
  it('fails with the import error, rather than build the theme from the file text', async () => {
    fs.writeFileSync(
      path.join(tmpDir, 'unresolved.mjs'),
      "import './missing-helper.mjs';\nexport default {name: 'unresolved', tokens: {'--color-bg': '#000'}};\n",
    );
    await expect(
      themeBuild('unresolved.mjs', {}, {cwd: tmpDir}),
    ).rejects.toThrow(
      /Failed to load theme from .*unresolved\.mjs: .*missing-helper\.mjs/s,
    );
    expect(fs.existsSync(path.join(tmpDir, 'unresolved.css'))).toBe(false);
  });

  it('fails with the error the module throws, rather than build the theme from the file text', async () => {
    fs.writeFileSync(
      path.join(tmpDir, 'throws.mjs'),
      "throw new Error('the theme module failed');\nexport default {name: 'throws', tokens: {'--color-bg': '#000'}};\n",
    );
    await expect(themeBuild('throws.mjs', {}, {cwd: tmpDir})).rejects.toThrow(
      /the theme module failed/,
    );
    expect(fs.existsSync(path.join(tmpDir, 'throws.css'))).toBe(false);
  });
});

describe('themeBuild() — dropped declarations reach the receipt', () => {
  // Core's generator refuses a declaration whose value would end it early
  // (an unquoted `;` or brace, an unclosed string/comment/url). The runtime
  // says so on the console; a build has a receipt, so every drop must land in
  // `warnings` — a programmatic caller otherwise sees `warnings: []` while the
  // CSS silently omits a value the generated JS still carries.
  it('reports every dropped declaration, from every generator path, in warnings', async () => {
    const themeFile = path.join(tmpDir, 'dropped.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'dropped',
        tokens: {
          '--color-bg': '#0a0a0a } body { background: url(https://example.com/token) ',
        },
        components: {
          button: {
            'variant:secondary': {
              backgroundColor: 'red; background-image: url(https://example.com/component)',
              ':hover': {color: '"https://example.com/pseudo'},
            },
          },
        },
        onDark: {
          tokens: {'--color-bg': 'url(https://example.com/dark'},
        },
        adaptations: {
          rules: [
            {
              when: {pointer: 'coarse'},
              value: {tokens: {'--color-bg': 'red /* https://example.com/adaptation'}},
            },
          ],
        },
      };\n`,
    );

    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    let result;
    try {
      result = await themeBuild('dropped.mjs', {}, {cwd: tmpDir});
      // Drops are collected, not printed: the programmatic API stays silent.
      expect(warnSpy).not.toHaveBeenCalled();
    } finally {
      warnSpy.mockRestore();
    }

    const css = fs.readFileSync(path.join(tmpDir, 'dropped.css'), 'utf8');
    expect(css).not.toContain('example.com');

    const warnings = result?.data.warnings ?? [];
    expect(warnings).toHaveLength(5);
    expect(warnings).toEqual(
      expect.arrayContaining([
        expect.stringMatching(
          /^Declaration dropped "--color-bg" in tokens: an unquoted "}" would close the rule/,
        ),
        expect.stringMatching(
          /^Declaration dropped "background-color" in components\.button\["variant:secondary"\]: an unquoted ";" would end the declaration/,
        ),
        expect.stringMatching(
          /^Declaration dropped "color" in components\.button\["variant:secondary"\]\[":hover"\]: an unclosed " string/,
        ),
        expect.stringMatching(
          /^Declaration dropped "--color-bg" in onDark\.tokens: an unclosed url\(/,
        ),
        expect.stringMatching(
          /^Declaration dropped "--color-bg" in adaptations\[0\]\.tokens: an unclosed \/\* comment/,
        ),
      ]),
    );
    for (const w of warnings) {
      expect(w).toContain('The generated CSS omits it');
    }
  });

  it('generates CSS for legacy null tokens without losing neighboring declarations', async () => {
    fs.writeFileSync(
      path.join(tmpDir, 'legacy.mjs'),
      `export default {
        name: 'legacy',
        tokens: {'--color-background-body': null, '--spacing-4': 12},
        onDark: {tokens: {'--color-background-body': null}},
        components: {button: {base: {borderRadius: '4px'}}},
      };\n`,
    );

    const result = await themeBuild('legacy.mjs', {}, {cwd: tmpDir});
    const css = fs.readFileSync(path.join(tmpDir, 'legacy.css'), 'utf8');
    expect(css).toContain('--color-background-body: null;');
    expect(css).toContain('--spacing-4: 12;');
    expect(css).toContain('border-radius: 4px;');
    expect(result?.data.warnings).toEqual([]);
  });

  it('keeps valid CSS that carries semicolons, and reports nothing', async () => {
    const themeFile = path.join(tmpDir, 'kept.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'kept',
        tokens: {'--font-family-body': 'Gill\\\\ Sans, "Segoe;UI", serif /* ; */'},
        components: {
          button: {
            'variant:secondary': {
              backgroundImage: 'URL(data:image/svg+xml;base64,PHN2Zz4=)',
              WebkitLineClamp: '2',
            },
          },
        },
      };\n`,
    );

    const result = await themeBuild('kept.mjs', {}, {cwd: tmpDir});
    const css = fs.readFileSync(path.join(tmpDir, 'kept.css'), 'utf8');

    expect(css).toContain(
      '--font-family-body: Gill\\ Sans, "Segoe;UI", serif /* ; */;',
    );
    expect(css).toContain(
      'background-image: URL(data:image/svg+xml;base64,PHN2Zz4=);',
    );
    expect(css).toContain('-webkit-line-clamp: 2;');
    expect(result?.data.warnings).toEqual([]);
  });
});

describe('themeBuild() — nothing to build', () => {
  it('returns null and writes nothing when the generator yields no CSS', async () => {
    const themeFile = path.join(tmpDir, 'empty.mjs');
    fs.writeFileSync(
      themeFile,
      `export default { name: 'empty', tokens: {} };\n`,
    );

    // Force the generator to emit nothing for this one build (prose defaults
    // otherwise always ship, so this branch is unreachable with real output).
    mockGenerateThemeRulesSplit.mockReturnValueOnce({component: [], prose: []});
    mockGenerateOnMediaCSS.mockReturnValueOnce('');

    const result = await themeBuild('empty.mjs', {}, {cwd: tmpDir});

    expect(result).toBeNull();
    // Nothing written — the tmp dir still holds only the source fixture.
    expect(fs.readdirSync(tmpDir)).toEqual(['empty.mjs']);
  });
});

describe('themeBuild() — check mode', () => {
  it('reports upToDate with no stale files and writes nothing when outputs match the source', async () => {
    const themeFile = path.join(tmpDir, 'chk.mjs');
    fs.writeFileSync(
      themeFile,
      `export default { name: 'chk', tokens: { '--color-bg': '#0a0a0a' } };\n`,
    );

    // Build once for real to produce the committed outputs.
    await themeBuild('chk.mjs', {}, {cwd: tmpDir});
    const before = fs.readFileSync(path.join(tmpDir, 'chk.css'), 'utf8');

    const result = await themeBuild('chk.mjs', {check: true}, {cwd: tmpDir});

    expect(result?.type).toBe('theme.build.check');
    expect(result?.data.upToDate).toBe(true);
    expect(result?.data.stale).toEqual([]);
    expect(result?.data.checked).toContain('chk.css');
    // Check mode must not rewrite the file.
    expect(fs.readFileSync(path.join(tmpDir, 'chk.css'), 'utf8')).toBe(before);
  });

  it('accepts released outputs that do not have a CSS type stub', async () => {
    const themeFile = path.join(tmpDir, 'released.mjs');
    fs.writeFileSync(
      themeFile,
      `export default { name: 'released', tokens: { '--color-bg': '#0a0a0a' } };\n`,
    );
    await themeBuild('released.mjs', {}, {cwd: tmpDir});
    fs.rmSync(path.join(tmpDir, 'released.css.d.ts'));

    const result = await themeBuild(
      'released.mjs',
      {check: true},
      {cwd: tmpDir},
    );

    expect(result?.data.upToDate).toBe(true);
    expect(result?.data.stale).toEqual([]);
    expect(result?.data.checked).toEqual([
      'released.css',
      'released.js',
      'released.d.ts',
    ]);
    expect(fs.existsSync(path.join(tmpDir, 'released.css.d.ts'))).toBe(false);
  });

  it('flags a stale output when the committed CSS content drifts from the source', async () => {
    const themeFile = path.join(tmpDir, 'drift.mjs');
    fs.writeFileSync(
      themeFile,
      `export default { name: 'drift', tokens: { '--color-bg': '#0a0a0a' } };\n`,
    );
    await themeBuild('drift.mjs', {}, {cwd: tmpDir});

    // Tamper with the committed CSS (real content change, not just the header).
    const cssPath = path.join(tmpDir, 'drift.css');
    fs.writeFileSync(
      cssPath,
      fs.readFileSync(cssPath, 'utf8') + '\n.injected{}\n',
    );

    const result = await themeBuild('drift.mjs', {check: true}, {cwd: tmpDir});

    expect(result?.data.upToDate).toBe(false);
    expect(
      result?.data.stale.some(
        s => s.path === 'drift.css' && s.reason === 'outdated',
      ),
    ).toBe(true);
  });

  it('flags a missing output', async () => {
    const themeFile = path.join(tmpDir, 'gone.mjs');
    fs.writeFileSync(
      themeFile,
      `export default { name: 'gone', tokens: { '--color-bg': '#0a0a0a' } };\n`,
    );
    await themeBuild('gone.mjs', {}, {cwd: tmpDir});
    fs.rmSync(path.join(tmpDir, 'gone.css'));

    const result = await themeBuild('gone.mjs', {check: true}, {cwd: tmpDir});

    expect(result?.data.upToDate).toBe(false);
    expect(
      result?.data.stale.some(
        s => s.path === 'gone.css' && s.reason === 'missing',
      ),
    ).toBe(true);
  });

  it('ignores volatile @generated header lines (a differing timestamp is NOT stale)', async () => {
    const themeFile = path.join(tmpDir, 'stamp.mjs');
    fs.writeFileSync(
      themeFile,
      `export default { name: 'stamp', tokens: { '--color-bg': '#0a0a0a' } };\n`,
    );
    await themeBuild('stamp.mjs', {}, {cwd: tmpDir});

    // Rewrite ONLY the Generated: timestamp line in the committed CSS.
    const cssPath = path.join(tmpDir, 'stamp.css');
    const tampered = fs
      .readFileSync(cssPath, 'utf8')
      .replace(/Generated: .*/, 'Generated: 1999-01-01T00:00:00.000Z');
    fs.writeFileSync(cssPath, tampered);

    const result = await themeBuild('stamp.mjs', {check: true}, {cwd: tmpDir});

    expect(result?.data.upToDate).toBe(true);
    expect(result?.data.stale).toEqual([]);
  });
});

describe('themeBuild() — component override validation', () => {
  it('accepts documented state keys without an "Unknown prop" warning', async () => {
    // The state-key syntax the Theming Infrastructure wiki documents —
    // `radio-indicator: {checked}`, `calendar-day: {today, selected}` — is declared in
    // each component's doc under `theming.targets[].states`, not
    // `visualProps`. `loadKnownComponents()` read only `visualProps`, so every
    // one of these warned "Unknown prop": documented syntax that looked broken.
    const themeFile = path.join(tmpDir, 'states.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'states',
        tokens: {'--color-bg': '#0a0a0a'},
        components: {
          'radio-indicator': {
            checked: {borderColor: 'var(--color-accent)'},
            'checked+disabled': {opacity: '0.5'},
          },
          'calendar-day': {
            today: {fontWeight: '700'},
            selected: {backgroundColor: 'var(--color-accent)'},
          },
        },
      };\n`,
    );

    const result = await themeBuild('states.mjs', {}, {cwd: tmpDir});

    expect(result?.data.warnings).toEqual([]);
  });

  it('accepts the heading type rules a type scale generates', async () => {
    // `typography.scale` makes defineTheme emit `heading: {'type:display-1' …}`
    // (Heading renders a `type:` class alongside `level:`), so any theme with a
    // type scale carried override keys the validator called unknown — including
    // the shipped neutralTheme.
    const themeFile = path.join(tmpDir, 'typescale.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'typescale',
        tokens: {'--color-bg': '#0a0a0a'},
        components: {
          heading: {'type:display-1': {letterSpacing: '0.01em'}},
        },
      };\n`,
    );

    const result = await themeBuild('typescale.mjs', {}, {cwd: tmpDir});

    expect(result?.data.warnings).toEqual([]);
  });

  it('still warns on a key that is neither a visual prop nor a state', async () => {
    // Widening the known set to states must not turn the guard off.
    const themeFile = path.join(tmpDir, 'bogus.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'bogus',
        tokens: {'--color-bg': '#0a0a0a'},
        components: {'radio-indicator': {notAState: {opacity: '0.5'}}},
      };\n`,
    );

    const result = await themeBuild('bogus.mjs', {}, {cwd: tmpDir});

    expect(result?.data.warnings).toEqual([
      expect.stringContaining(
        'Unknown prop "notAState" on component "radio-indicator"',
      ),
    ]);
  });

  it('deduplicates removed aliases as unknown across root and conditional layers', () => {
    const registry = {
      propsByKey: {'new-target': ['variant']},
    };

    expect(
      validateComponentOverridesAgainstRegistry(
        {
          components: {'old-target': {base: {color: 'red'}}},
          onDark: {
            components: {'old-target': {'variant:quiet': {color: 'pink'}}},
          },
          adaptations: {
            rules: [
              {
                when: {contrast: 'more'},
                value: {
                  components: {
                    'old-target': {'variant:loud': {color: 'purple'}},
                  },
                },
              },
            ],
          },
        },
        registry,
      ),
    ).toEqual(['Unknown component "old-target".']);
  });

  it('reports a removed target alias as an unknown component key', async () => {
    const themeFile = path.join(tmpDir, 'removed-target.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'removed-target',
        tokens: {},
        components: {progressbar: {base: {color: 'red'}}},
      };\n`,
    );

    const result = await themeBuild('removed-target.mjs', {}, {cwd: tmpDir});

    expect(result?.data.warnings).toContain(
      'Unknown component "progressbar". Did you mean: progress-bar?',
    );
    expect(
      fs.readFileSync(path.join(tmpDir, 'removed-target.css'), 'utf8'),
    ).toContain('.astryx-progressbar');
  });
});

describe('themeBuild() — Icon size dimensions', () => {
  it('writes width and height on an icon size into the vars the glyph reads, with no warnings', async () => {
    // spec:AST-087 FR10: a built theme sets an Icon size's glyph dimension the
    // way the runtime provider does, through the shared compiler's derived
    // vars. Raw width/height would lose to a consumer's unlayered StyleX.
    const themeFile = path.join(tmpDir, 'iconsizes.mjs');
    fs.writeFileSync(
      themeFile,
      `export default {
        name: 'iconsizes',
        tokens: {'--color-bg': '#0a0a0a'},
        components: {icon: {'size:sm': {width: '18px', height: '22px'}}},
      };\n`,
    );

    const result = await themeBuild('iconsizes.mjs', {}, {cwd: tmpDir});

    expect(result?.data.warnings).toEqual([]);
    const css = fs.readFileSync(path.join(tmpDir, 'iconsizes.css'), 'utf8');
    const rule =
      css.match(/\.astryx-icon\[data-size="sm"\]\s*\{([^}]*)\}/)?.[1] ?? '';
    expect(rule).toMatch(/--_icon-width:\s*18px/);
    expect(rule).toMatch(/--_icon-height:\s*22px/);
    expect(rule).not.toMatch(/(^|[\s;])(width|height)\s*:/);
  });
});

describe('themeBuild() — the shipped theme template', () => {
  // `assets/theme.template.ts` is what `astryx theme template` puts in a
  // consumer's project. It is the one theme file we hand out, so it has to
  // compile as shipped — and cleanly: a template that greets its first reader
  // with warnings teaches them to ignore warnings. The claims its comments make
  // are checked separately by scripts/check-theme-template.test.mjs.
  it('compiles as shipped, with no warnings', async () => {
    const src = path.resolve(
      import.meta.dirname,
      '../../../assets/theme.template.ts',
    );
    fs.copyFileSync(src, path.join(tmpDir, 'theme.template.ts'));

    const result = await themeBuild('theme.template.ts', {}, {cwd: tmpDir});

    expect(result?.data.warnings).toEqual([]);
    // It DOES name Inter and Geist Mono without loading them, to teach "SHIP
    // THE FONTS YOU NAME" — advisories about a correct file, which is why they
    // are notices. Asserted here so moving them out of `warnings` cannot
    // quietly become dropping them.
    expect(result?.data.notices).toHaveLength(2);
    expect(fs.existsSync(path.join(tmpDir, 'my-theme.css'))).toBe(true);
    // The template teaches custom variants; the augmentation it promises the
    // reader has to actually be generated.
    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(
      true,
    );
  });
});

describe('themeBuild() — icon registry detection', () => {
  /**
   * The emitted icon import statement, or null. Reads the statement rather
   * than the whole file: the `@generated` header quotes a usage example, so a
   * substring search over the file would match comment text too.
   */
  function iconImportLine(generated) {
    const match = generated.match(/^import .*$/m);
    return match ? match[0] : null;
  }

  it('emits the import, icons key and re-export for a registry that arrives via an import', async () => {
    fs.writeFileSync(
      path.join(tmpDir, 'icons.mjs'),
      'export const liveIcons = {};\n',
    );
    fs.writeFileSync(
      path.join(tmpDir, 'live.mjs'),
      `import {liveIcons} from './icons';\n` +
        `export default {name: 'live', icons: liveIcons, tokens: {'--color-bg': '#fff'}};\n`,
    );

    const result = await themeBuild('live.mjs', {}, {cwd: tmpDir});

    const generated = fs.readFileSync(path.join(tmpDir, 'live.js'), 'utf8');
    expect(iconImportLine(generated)).toBe(
      "import { liveIcons } from './icons';",
    );
    expect(generated).toContain('icons: liveIcons,');
    expect(generated).toContain('export { liveIcons };');
    expect(result?.data.warnings).toEqual([]);
  });

  it('does not re-emit an import that only appears inside a comment (#5058)', async () => {
    // The reported repro: the registry was inlined into the theme source, and
    // a doc comment kept the old import line for context. The comment's
    // specifier was scraped and emitted as live code in the built module,
    // pointing at a file that no longer exists.
    fs.writeFileSync(
      path.join(tmpDir, 'commented.mjs'),
      `/**\n` +
        ` * The scaffold put this in a sibling icons file, so the built module\n` +
        ` * carried \`import { ghostIcons } from './icons'\` — which Node\n` +
        ` * cannot resolve.\n` +
        ` */\n` +
        `const ghostIcons = {close: 'inline'};\n` +
        `export default {name: 'commented', icons: ghostIcons, tokens: {'--color-bg': '#fff'}};\n`,
    );

    await expect(
      themeBuild('commented.mjs', {}, {cwd: tmpDir}),
    ).rejects.toMatchObject({
      code: 'ERR_THEME_INVALID',
      message: expect.stringContaining('icons: ghostIcons'),
    });
    expect(fs.readdirSync(tmpDir)).toEqual(['commented.mjs']);
  });

  it('scrapes the live import even when a comment quotes a stale one', async () => {
    fs.writeFileSync(
      path.join(tmpDir, 'icons.mjs'),
      'export const realIcons = {};\n',
    );
    fs.writeFileSync(
      path.join(tmpDir, 'both.mjs'),
      `// was: import { realIcons } from './old-icons';\n` +
        `import {realIcons} from './icons';\n` +
        `export default {name: 'both', icons: realIcons, tokens: {'--color-bg': '#fff'}};\n`,
    );

    const result = await themeBuild('both.mjs', {}, {cwd: tmpDir});

    // The comment comes first in the source, so the old scan matched it first
    // and emitted `./old-icons` — the live import must win.
    const generated = fs.readFileSync(path.join(tmpDir, 'both.js'), 'utf8');
    expect(iconImportLine(generated)).toBe(
      "import { realIcons } from './icons';",
    );
    expect(generated).not.toContain('old-icons');
    expect(result?.data.warnings).toEqual([]);
  });

  it('ignores a commented-out icons: field entirely', async () => {
    fs.writeFileSync(
      path.join(tmpDir, 'nofield.mjs'),
      `// icons: retiredIcons,\n` +
        `export default {name: 'nofield', tokens: {'--color-bg': '#fff'}};\n`,
    );

    const result = await themeBuild('nofield.mjs', {}, {cwd: tmpDir});

    const generated = fs.readFileSync(path.join(tmpDir, 'nofield.js'), 'utf8');
    expect(iconImportLine(generated)).toBeNull();
    expect(generated).not.toContain('icons:');
    // No icons field means nothing was dropped — no warning either.
    expect(result?.data.warnings).toEqual([]);
  });

  describe.each([false, true])('unsupported registries (check: %s)', check => {
    it('rejects before the generator can return no CSS', async () => {
      fs.writeFileSync(
        path.join(tmpDir, 'inline.mjs'),
        `const inlineIcons = {chevron: 'stub'};\n` +
          `export default {name: 'inline', icons: inlineIcons, tokens: {}};\n`,
      );

      await mockGenerateThemeRulesSplit.withImplementation(
        () => ({component: [], prose: []}),
        async () => {
          await mockGenerateOnMediaCSS.withImplementation(
            () => '',
            async () => {
              await expect(
                themeBuild('inline.mjs', {check}, {cwd: tmpDir}),
              ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
            },
          );
        },
      );
      expect(mockGenerateThemeRulesSplit).not.toHaveBeenCalled();
      expect(fs.readdirSync(tmpDir)).toEqual(['inline.mjs']);
    });

    it.each([
      ['local binding', 'icons: inlineIcons'],
      ['object literal', "icons: {chevron: 'stub'}"],
      ['shorthand', 'icons'],
    ])('rejects a %s without creating output files', async (_label, field) => {
      fs.writeFileSync(
        path.join(tmpDir, 'inline.mjs'),
        `const inlineIcons = {chevron: 'stub'};\n` +
          `const icons = inlineIcons;\n` +
          `export default {name: 'inline', ${field}, tokens: {'--color-bg': '#fff'}};\n`,
      );

      await expect(
        themeBuild(
          'inline.mjs',
          {check, out: 'dist/inline.css'},
          {cwd: tmpDir},
        ),
      ).rejects.toMatchObject({
        code: 'ERR_THEME_INVALID',
        message: expect.stringContaining(
          'Move the registry to its own module and import it',
        ),
      });
      expect(fs.readdirSync(tmpDir)).toEqual(['inline.mjs']);
    });

    it('rejects even when committed output already matches the missing-icons result', async () => {
      const themeFile = path.join(tmpDir, 'inline.mjs');
      const withoutIcons =
        `export default {name: 'inline', tokens: {'--color-bg': '#fff'}, ` +
        `components: {button: {'variant:custom': {color: 'red'}}}};\n`;
      fs.writeFileSync(themeFile, withoutIcons);
      const built = await themeBuild('inline.mjs', {}, {cwd: tmpDir});
      expect(built?.data.outputs.variantsDts).toBe('inline.variants.d.ts');
      const outputs = Object.values(built.data.outputs);
      const before = outputs.map(file =>
        fs.readFileSync(path.join(tmpDir, file), 'utf8'),
      );
      // This source used to emit exactly the same output as the icon-free
      // theme, so --check passed after the incomplete artifacts were committed.
      fs.writeFileSync(
        themeFile,
        `const inlineIcons = {chevron: 'stub'};\n` +
          withoutIcons.replace(
            "name: 'inline',",
            "name: 'inline', icons: inlineIcons,",
          ),
      );
      const filesBefore = fs.readdirSync(tmpDir).sort();

      await expect(
        themeBuild('inline.mjs', {check}, {cwd: tmpDir}),
      ).rejects.toMatchObject({
        code: 'ERR_THEME_INVALID',
        message: expect.stringContaining('icons: inlineIcons'),
      });
      expect(
        outputs.map(file => fs.readFileSync(path.join(tmpDir, file), 'utf8')),
      ).toEqual(before);
      expect(fs.readdirSync(tmpDir).sort()).toEqual(filesBefore);
    });
  });
});

describe('themeBuild() — extends', () => {
  // These fixtures `import {defineTheme} from '@astryxdesign/core/theme'` the
  // way a real theme file does, so each links the CLI's packages.
  let extDir;
  beforeEach(() => {
    extDir = makeLinkedFixture('astryx-extends-', ['@astryxdesign']);
  });
  afterEach(() => {
    removeLinkedFixture(extDir);
  });

  /**
   * Every `prop: value` a generated stylesheet actually applies. Header
   * comments and scope wrappers are ignored — two themes never share those.
   */
  function declarations(css) {
    return new Set(
      css
        .split('\n')
        .map(l => l.trim())
        .filter(l => /^[-a-z][^{}]*:.+;$/.test(l)),
    );
  }
  /** Every component rule a stylesheet opens, e.g. `.astryx-switch {`. */
  function selectors(css) {
    return new Set(
      css
        .split('\n')
        .map(l => l.trim())
        .filter(l => l.endsWith('{') && l.startsWith('.')),
    );
  }

  /** A base theme with geometry, elevation and a component override. */
  const BASE_SOURCE = `export const brandTheme = {
    name: 'ext-base',
    tokens: {
      '--radius-element': '6px',
      '--shadow-low': '0 1px 3px rgb(0 0 0 / 0.1)',
      '--color-border-emphasized': '#D4D4D4',
    },
    components: {
      switch: {base: {backgroundColor: 'var(--color-border-emphasized)'}},
    },
  };\n`;

  /**
   * The child names its base with a plain relative specifier, exactly as a
   * generated palette does. `theme build` writes `ext-base.js` next to
   * `ext-base.mjs`, so `./ext-base` is ambiguous — and the artifact, which
   * exports `extBaseTheme` rather than `brandTheme`, is the wrong answer.
   */
  const CHILD_SOURCE = `import {defineTheme} from '@astryxdesign/core/theme';
  import {brandTheme} from './ext-base';
  export const paletteTheme = defineTheme({
    name: 'ext-child',
    extends: brandTheme,
    tokens: {'--color-accent': 'hsl(220 88% 72%)'},
  });\n`;

  it('emits every declaration its base emits (the child stylesheet is self-contained)', async () => {
    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);

    // Build the base FIRST, as any real project does — that write is what
    // used to poison the child's build.
    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
    await themeBuild('ext-child.mjs', {}, {cwd: extDir});

    const baseCss = fs.readFileSync(path.join(extDir, 'ext-base.css'), 'utf8');
    const childCss = fs.readFileSync(
      path.join(extDir, 'ext-child.css'),
      'utf8',
    );

    const childDecls = declarations(childCss);
    expect([...declarations(baseCss)].filter(d => !childDecls.has(d))).toEqual(
      [],
    );

    const childSelectors = selectors(childCss);
    expect([...selectors(baseCss)].filter(s => !childSelectors.has(s))).toEqual(
      [],
    );

    // …and the child's own override still wins.
    expect(childCss).toContain('--color-accent: hsl(220 88% 72%);');
  });

  it('resolves the base from its source, not from the generated sibling artifact', async () => {
    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);

    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
    const result = await themeBuild('ext-child.mjs', {}, {cwd: extDir});

    expect(result?.data.componentCount).toBe(1);
    expect(result?.data.tokenCount).toBe(4);
  });

  it('inherits component overrides when the base IS a built theme module', async () => {
    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
    await themeBuild('ext-base.mjs', {}, {cwd: extDir});

    // Extending a package's pre-built theme module (e.g. the `./built`
    // subpath the shipped themes expose) must not silently drop its
    // component overrides.
    fs.writeFileSync(
      path.join(extDir, 'ext-built-child.mjs'),
      `import {defineTheme} from '@astryxdesign/core/theme';
      import {extBaseTheme} from './ext-base.js';
      export const builtChildTheme = defineTheme({
        name: 'ext-built-child',
        extends: extBaseTheme,
      });\n`,
    );

    await themeBuild('ext-built-child.mjs', {}, {cwd: extDir});
    const css = fs.readFileSync(
      path.join(extDir, 'ext-built-child.css'),
      'utf8',
    );

    expect(css).toContain('.astryx-switch {');
    expect(css).toContain('--radius-element: 6px;');
  });

  it('preserves local-token enrollment when extending a built theme module', async () => {
    fs.writeFileSync(
      path.join(extDir, 'local-base.mjs'),
      `import {defineTheme} from '@astryxdesign/core/theme';
      export const localBaseTheme = defineTheme({
        name: 'local-base',
        localTokens: {
          '--astryx-theme-local-base-color-status-fill': ['#123456', '#abcdef'],
        },
        components: {
          badge: {
            base: {
              backgroundColor: 'var(--astryx-theme-local-base-color-status-fill)',
            },
          },
        },
      });\n`,
    );
    await themeBuild('local-base.mjs', {}, {cwd: extDir});

    fs.writeFileSync(
      path.join(extDir, 'local-child.mjs'),
      `import {defineTheme} from '@astryxdesign/core/theme';
      import {localBaseTheme} from './local-base.js';
      export const localChildTheme = defineTheme({
        name: 'local-child',
        extends: localBaseTheme,
        localTokens: {
          '--astryx-theme-local-base-color-status-fill': '#654321',
          '--astryx-theme-local-child-color-surface-raised': '#fedcba',
        },
      });\n`,
    );

    await themeBuild('local-child.mjs', {}, {cwd: extDir});
    const css = fs.readFileSync(path.join(extDir, 'local-child.css'), 'utf8');
    const built = fs.readFileSync(path.join(extDir, 'local-child.js'), 'utf8');

    expect(css).toContain(
      '--astryx-theme-local-base-color-status-fill: #654321;',
    );
    expect(css).toContain(
      '--astryx-theme-local-child-color-surface-raised: #fedcba;',
    );
    expect(built).toContain(
      '__localTokenLineage: ["local-base","local-child"]',
    );
  });

  it('resolves extends on a plain object theme file (no defineTheme call)', async () => {
    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
    fs.writeFileSync(
      path.join(extDir, 'ext-plain.mjs'),
      `import {brandTheme} from './ext-base.mjs';
      export default {
        name: 'ext-plain',
        extends: brandTheme,
        tokens: {'--color-accent': '#ff0000'},
      };\n`,
    );

    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
    await themeBuild('ext-plain.mjs', {}, {cwd: extDir});

    const css = fs.readFileSync(path.join(extDir, 'ext-plain.css'), 'utf8');
    expect(css).toContain('--radius-element: 6px;');
    expect(css).toContain('.astryx-switch {');
  });

  it('fails loudly when the base import resolved to nothing', async () => {
    fs.writeFileSync(
      path.join(extDir, 'ext-broken.mjs'),
      `import {defineTheme} from '@astryxdesign/core/theme';
      import {notAThing} from './ext-missing.mjs';
      export const brokenTheme = defineTheme({
        name: 'ext-broken',
        extends: notAThing,
        tokens: {'--color-accent': '#ff0000'},
      });\n`,
    );
    fs.writeFileSync(
      path.join(extDir, 'ext-missing.mjs'),
      `export const somethingElse = 1;\n`,
    );

    await expect(
      themeBuild('ext-broken.mjs', {}, {cwd: extDir}),
    ).rejects.toThrow(/extends/);
  });
});

// =============================================================================
// Theme name → valid JS identifier contract (deterministic from theme.name)
// =============================================================================

describe('themeBuild() — theme name identifier sanitization', () => {
  /**
   * Write a theme source with a given theme name and return the generated JS
   * and declarations. The identifier is derived only from theme.name.
   */
  async function buildNamed(themeName) {
    const themeFile = path.join(
      tmpDir,
      `src-${themeName.replace(/[^a-z0-9]/gi, '')}.mjs`,
    );
    // Use a default export so no source export name is available — the
    // identifier must come purely from toIdentifier(themeName) + 'Theme'.
    fs.writeFileSync(
      themeFile,
      `export default { name: '${themeName}', tokens: { '--color-bg': '#000' } };\n`,
    );
    await themeBuild(path.basename(themeFile), {}, {cwd: tmpDir});
    const js = fs.readFileSync(path.join(tmpDir, `${themeName}.js`), 'utf8');
    const dts = fs.readFileSync(path.join(tmpDir, `${themeName}.d.ts`), 'utf8');
    return {js, dts};
  }

  // -- Core bug: hyphen followed by digit -----------------------------------

  it('chaos-07 → chaos07Theme (the motivating bug)', async () => {
    const {js, dts} = await buildNamed('chaos-07');
    expect(js).toContain('export const chaos07Theme = {');
    expect(js).not.toMatch(/export const chaos-07/);
    expect(dts).toContain('export declare const chaos07Theme: DefinedTheme;');
    // Must parse as valid JS
    expect(() => new Function(js.replace(/^export /gm, ''))).not.toThrow();
  });

  // -- Dot separator --------------------------------------------------------

  it('brand.v2 → brandV2Theme', async () => {
    const {js, dts} = await buildNamed('brand.v2');
    expect(js).toContain('export const brandV2Theme = {');
    expect(dts).toContain('export declare const brandV2Theme: DefinedTheme;');
  });

  it('ui.dark.3 → uiDark3Theme', async () => {
    const {js, dts} = await buildNamed('ui.dark.3');
    expect(js).toContain('export const uiDark3Theme = {');
    expect(dts).toContain('export declare const uiDark3Theme: DefinedTheme;');
  });

  // -- Underscore preserved (already valid) ---------------------------------

  it('my_theme → my_themeTheme (underscore preserved)', async () => {
    const {js, dts} = await buildNamed('my_theme');
    expect(js).toContain('export const my_themeTheme = {');
    expect(dts).toContain('export declare const my_themeTheme: DefinedTheme;');
  });

  // -- Mixed separators -----------------------------------------------------

  it('neo_wave-2.x → neo_wave2XTheme (underscore kept, others camelCased)', async () => {
    const {js, dts} = await buildNamed('neo_wave-2.x');
    expect(js).toContain('export const neo_wave2XTheme = {');
    expect(dts).toContain(
      'export declare const neo_wave2XTheme: DefinedTheme;',
    );
  });

  // -- Multiple and consecutive separators ----------------------------------

  it('a-1-b → a1BTheme', async () => {
    const {js, dts} = await buildNamed('a-1-b');
    expect(js).toContain('export const a1BTheme = {');
    expect(dts).toContain('export declare const a1BTheme: DefinedTheme;');
  });

  it('my--theme → myThemeTheme (consecutive hyphens)', async () => {
    const {js, dts} = await buildNamed('my--theme');
    expect(js).toContain('export const myThemeTheme = {');
    expect(dts).toContain('export declare const myThemeTheme: DefinedTheme;');
  });

  it('trailing- → trailingTheme (trailing separator stripped)', async () => {
    const {js, dts} = await buildNamed('trailing-');
    expect(js).toContain('export const trailingTheme = {');
    expect(dts).toContain('export declare const trailingTheme: DefinedTheme;');
  });

  it('neon-green-42 → neonGreen42Theme', async () => {
    const {js, dts} = await buildNamed('neon-green-42');
    expect(js).toContain('export const neonGreen42Theme = {');
    expect(dts).toContain(
      'export declare const neonGreen42Theme: DefinedTheme;',
    );
  });

  // -- JS and d.ts agree on every case --------------------------------------

  it('JS, d.ts, and install example agree', async () => {
    const {js, dts} = await buildNamed('dark-v2');
    const jsMatch = js.match(/export const (\w+) = \{/);
    const dtsMatch = dts.match(/export declare const (\w+): DefinedTheme;/);
    expect(jsMatch?.[1]).toBe('darkV2Theme');
    expect(dtsMatch?.[1]).toBe('darkV2Theme');
    // Import example in JSDoc
    expect(js).toContain("import { darkV2Theme } from './dark-v2'");
  });

  // -- Check mode -----------------------------------------------------------

  it('check mode agrees with the deterministic identifier', async () => {
    await buildNamed('wave-99');
    // Source file was written by buildNamed; re-run in check mode
    const checkResult = await themeBuild(
      path.basename(
        fs.readdirSync(tmpDir).find(f => f.startsWith('src-wave99')),
      ),
      {check: true},
      {cwd: tmpDir},
    );
    expect(checkResult?.data.upToDate).toBe(true);
  });

  // -- Reserved words are safe via the Theme suffix -------------------------

  it('reserved word "for" → forTheme (safe)', async () => {
    const {js, dts} = await buildNamed('for');
    expect(js).toContain('export const forTheme = {');
    expect(dts).toContain('export declare const forTheme: DefinedTheme;');
    expect(() => new Function(js.replace(/^export /gm, ''))).not.toThrow();
  });

  // -- Simple name (no separators) is unchanged -----------------------------

  it('ocean → oceanTheme (no-op sanitization)', async () => {
    const {js, dts} = await buildNamed('ocean');
    expect(js).toContain('export const oceanTheme = {');
    expect(dts).toContain('export declare const oceanTheme: DefinedTheme;');
  });
});