@astryxdesign/cli 0.2.0 → 0.3.0

package/api/theme/build/build.mjs

@@ -13,22 +13,34 @@
  *
  * It performs the writes and returns a `theme.build` receipt, or `null` when
  * the theme produced no CSS (nothing to build). Errors throw AstryxError (with
- * a stable code). Human progress is emitted through the injected `logger`
+ * a stable code). Human progress is emitted through the shared `logger`
  * (silent by default), so the CLI keeps its exact output while a programmatic
  * caller stays quiet.
+ *
+ * With `{check: true}`, it compiles the same outputs in memory but writes
+ * nothing: it compares each generated file against what is on disk (ignoring
+ * only the volatile `@generated` `Command:` line) and returns a
+ * `theme.build.check` receipt listing any stale or missing outputs. This is
+ * the CI guard for committed, generated theme CSS: the source of truth is
+ * `<theme>.ts`, and `theme build --check` fails when the committed
+ * `<theme>.css`/`.js`/`.d.ts` no longer match it.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL, fileURLToPath} from 'node:url';
 import {createJiti} from 'jiti';
-import {getCliInvocation} from '../../../utils/package-manager.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {CLI_ROOT, findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {
+  assertWithin,
   sanitizeName,
   PathSafetyError,
-} from '../../../utils/path-safety.mjs';
-import {ERROR_CODES} from '../../../lib/error-codes.mjs';
+} from '../../../foundation/fs/path-safety.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
+import {logger} from '../../logger.mjs';
+import {loadComponentDoc} from '../../../foundation/discovery/component-loader.mjs';
 
 // Import shared theme processing from core. `astryx theme build` MUST produce the
 // exact same CSS as the `<Theme>` runtime, so it has exactly one generation
@@ -55,14 +67,47 @@ try {
   _coreImportError = e;
 }
 
+/**
+ * Read a package's `version` from a resolved directory. Returns `'unknown'`
+ * when it can't be read so the header always has a value.
+ * @param {string|null} dir
+ * @returns {string}
+ */
+function readPkgVersion(dir) {
+  if (!dir) return 'unknown';
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'),
+    );
+    return pkg?.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Resolve the CLI and core package versions recorded in generated headers.
+ * These are stable (unlike a timestamp): identical inputs produce byte-identical
+ * output, so rebuilds don't churn git and `theme build --check` stays a pure
+ * content-drift signal.
+ * @param {string} cwd - Consumer cwd, used to locate the installed core.
+ * @returns {{cli: string, core: string}}
+ */
+function resolveToolVersions(cwd) {
+  return {
+    cli: readPkgVersion(CLI_ROOT),
+    core: readPkgVersion(findCoreDir(cwd)),
+  };
+}
+
 /**
  * Build a @generated attribution header for generated files.
  * @param {string} sourceFile - Relative path to the source theme file
  * @param {'css'|'js'|'ts'} lang - File language (determines comment syntax)
  * @param {string} [command] - The full CLI command used to generate this file
+ * @param {{cli: string, core: string}} [versions] - CLI/core versions used to build
  */
-function generatedHeader(sourceFile, lang = 'js', command) {
-  const timestamp = new Date().toISOString();
+function generatedHeader(sourceFile, lang = 'js', command, versions) {
   const body = [
     `@generated by \`astryx theme build\` — do not edit manually.`,
     `Source: ${sourceFile}`,
@@ -70,13 +115,37 @@ function generatedHeader(sourceFile, lang = 'js', command) {
   if (command) {
     body.push(`Command: ${command}`);
   }
-  body.push(`Generated: ${timestamp}`);
+  if (versions) {
+    body.push(`CLI: @astryxdesign/cli@${versions.cli}`);
+    body.push(`Core: @astryxdesign/core@${versions.core}`);
+  }
   if (lang === 'css') {
     return `/*\n * ${body.join('\n * ')}\n */\n\n`;
   }
   return `/**\n * ${body.join('\n * ')}\n */\n\n`;
 }
 
+/**
+ * Normalize generated file content for staleness comparison by dropping the
+ * volatile `Command:` line of the `@generated` header (it embeds the
+ * invocation, e.g. an explicit --out). Everything else — including the rest of
+ * the header and all real content — is compared verbatim. Used only by
+ * `--check`: a differing command must NOT report a file as stale, but any real
+ * content drift must. The `CLI:`/`Core:` provenance lines are deterministic
+ * for a given toolchain, so they compare verbatim like real content.
+ * @param {string} content
+ * @returns {string}
+ */
+function normalizeForCompare(content) {
+  return content
+    .split('\n')
+    .filter(line => {
+      const t = line.replace(/^\s*\*?\s?/, '');
+      return !t.startsWith('Command:');
+    })
+    .join('\n');
+}
+
 /**
  * Convert a theme name to a valid JS identifier.
  * e.g. 'default-minimal' → 'defaultMinimal', 'ocean' → 'ocean'
@@ -84,7 +153,10 @@ function generatedHeader(sourceFile, lang = 'js', command) {
  * @returns {string}
  */
 function toIdentifier(name) {
-  return name.replace(/-([a-z])/g, (/** @type {string} */ _, /** @type {string} */ c) => c.toUpperCase());
+  return name.replace(
+    /-([a-z])/g,
+    (/** @type {string} */ _, /** @type {string} */ c) => c.toUpperCase(),
+  );
 }
 
 /**
@@ -113,7 +185,10 @@ export function importSpecifier(relDir, base) {
 function toPascalCase(name) {
   return name
     .split('-')
-    .map((/** @type {string} */ part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .map(
+      (/** @type {string} */ part) =>
+        part.charAt(0).toUpperCase() + part.slice(1),
+    )
     .join('');
 }
 
@@ -129,12 +204,16 @@ async function loadKnownValues(componentName) {
   const cliDir = path.dirname(fileURLToPath(import.meta.url));
   const coreSrc = path.resolve(cliDir, '../../../../core/src');
   if (!fs.existsSync(coreSrc)) return {};
-  // Map component name to directory (e.g. 'banner' → 'Banner', 'dropdownmenu' → 'DropdownMenu')
-  const dirs = fs.readdirSync(coreSrc, { withFileTypes: true })
+  // Map component name to directory (e.g. 'banner' → 'Banner',
+  // 'dropdown-menu' → 'DropdownMenu'). Theme keys use the rendered class
+  // token, which hyphenates multi-word names, so strip non-letters from BOTH
+  // sides before comparing.
+  const dirs = fs
+    .readdirSync(coreSrc, {withFileTypes: true})
     .filter(d => d.isDirectory())
     .map(d => d.name);
-  const dir = dirs.find(d => d.toLowerCase() === componentName.toLowerCase()
-    || d.toLowerCase().replace(/[^a-z]/g, '') === componentName.toLowerCase());
+  const target = componentName.toLowerCase().replace(/[^a-z]/g, '');
+  const dir = dirs.find(d => d.toLowerCase().replace(/[^a-z]/g, '') === target);
   if (!dir) return {};
 
   const docPath = path.join(coreSrc, dir, `${dir}.doc.mjs`);
@@ -174,7 +253,9 @@ async function loadKnownValues(componentName) {
       // Parse union type: "'info' | 'warning' | 'error' | 'success'" → ['info', 'warning', 'error', 'success']
       const matches = prop.type.match(/'([^']+)'/g);
       if (matches) {
-        result[prop.name] = matches.map((/** @type {string} */ m) => m.replace(/'/g, ''));
+        result[prop.name] = matches.map((/** @type {string} */ m) =>
+          m.replace(/'/g, ''),
+        );
       }
     }
     return result;
@@ -250,6 +331,113 @@ function readComponentDeclarations(pascalName) {
   return contents;
 }
 
+
+/** @type {Map<string, Array<{moduleName: string, interfacePrefix: string}>>} */
+const _augmentationTargetCache = new Map();
+
+/**
+ * Resolve a rendered theme class token (the key without `astryx-`) to candidate
+ * public core subpaths and interface prefixes that may own its augmentable prop
+ * maps. Some tokens are subtargets documented by a parent component
+ * (`avatar-status-dot` augments `@astryxdesign/core/Avatar`), and some stable
+ * class tokens intentionally omit word separators (`progressbar`, `statusdot`)
+ * while the public API keeps `ProgressBar`/`StatusDot` casing. Component docs
+ * are the source of truth for the target token → owning component relationship.
+ *
+ * @param {string} componentName
+ * @returns {Promise<Array<{moduleName: string, interfacePrefix: string}>>}
+ */
+async function resolveAugmentationTargetCandidates(componentName) {
+  if (_augmentationTargetCache.has(componentName)) {
+    return /** @type {Array<{moduleName: string, interfacePrefix: string}>} */ (
+      _augmentationTargetCache.get(componentName)
+    );
+  }
+
+  const fallback = [
+    {
+      moduleName: toPascalCase(componentName),
+      interfacePrefix: toPascalCase(componentName),
+    },
+  ];
+
+  const coreRoot = resolveCoreRoot();
+  const coreSrc = coreRoot ? path.join(coreRoot, 'src') : null;
+  if (!coreSrc || !fs.existsSync(coreSrc)) {
+    _augmentationTargetCache.set(componentName, fallback);
+    return fallback;
+  }
+
+  /** @type {Array<{moduleName: string, interfacePrefix: string}>} */
+  const matches = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+
+  /**
+   * @param {string} moduleName
+   * @param {string} interfacePrefix
+   */
+  function addCandidate(moduleName, interfacePrefix) {
+    const key = `${moduleName}:${interfacePrefix}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    matches.push({moduleName, interfacePrefix});
+  }
+
+  /** @param {string} dir */
+  async function scan(dir) {
+    const entries = fs.readdirSync(dir, {withFileTypes: true});
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+        await scan(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.doc.mjs')) continue;
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(full);
+      } catch {
+        continue;
+      }
+
+      const matchesTarget = (doc?.theming?.targets || []).some(
+        (/** @type {any} */ target) =>
+          typeof target?.className === 'string' &&
+          target.className.replace(/^astryx-/, '') === componentName,
+      );
+      if (!matchesTarget) continue;
+
+      const moduleName =
+        typeof doc?.name === 'string' && doc.name
+          ? doc.name
+          : path.basename(path.dirname(full));
+
+      // Try the exact rendered token first for documented subtargets such as
+      // avatar-status-dot → AvatarStatusDotVariantMap, then the owning public
+      // component name for unhyphenated public casings such as progressbar →
+      // ProgressBarVariantMap/statusdot → StatusDotVariantMap.
+      addCandidate(moduleName, toPascalCase(componentName));
+      addCandidate(moduleName, moduleName);
+      if (Array.isArray(doc?.components)) {
+        for (const comp of doc.components) {
+          if (typeof comp?.name === 'string') {
+            addCandidate(moduleName, comp.name);
+          }
+        }
+      }
+    }
+  }
+
+  await scan(coreSrc);
+  const resolved = matches.length > 0 ? matches : fallback;
+  _augmentationTargetCache.set(componentName, resolved);
+  return resolved;
+}
+
 /**
  * Determine whether `@astryxdesign/core/<Component>` exports an interface named
  * `interfaceName` that can be augmented via module augmentation.
@@ -265,8 +453,12 @@ function readComponentDeclarations(pascalName) {
 function componentHasAugmentableInterface(pascalName, interfaceName) {
   const decl = readComponentDeclarations(pascalName);
   if (!decl) return false;
-  // Word-boundary match so `ButtonVariantMap` doesn't match `XButtonVariantMap`.
-  const re = new RegExp(`\\b${interfaceName}\\b`);
+  // Require an actual interface declaration in this public subpath, not just a
+  // type re-export. Module augmentation only widens consumers that import the
+  // module where the interface is declared; augmenting a barrel that re-exports
+  // the type (e.g. Field re-exporting FieldStatusVariantMap) creates a dead
+  // sibling interface for consumers of the real FieldStatus subpath.
+  const re = new RegExp(String.raw`\binterface\s+${interfaceName}\b`);
   return re.test(decl);
 }
 
@@ -315,15 +507,16 @@ async function generateVariantDeclarationsAsync(themeDef) {
         if (knownForProp && knownForProp.includes(value)) continue;
 
         if (!customValues[component]) customValues[component] = {};
-        if (!customValues[component][prop]) customValues[component][prop] = new Set();
+        if (!customValues[component][prop])
+          customValues[component][prop] = new Set();
         customValues[component][prop].add(value);
       }
     }
   }
 
   // Check if we found any custom values
-  const hasCustom = Object.values(customValues).some(
-    props => Object.values(props).some(values => values.size > 0)
+  const hasCustom = Object.values(customValues).some(props =>
+    Object.values(props).some(values => values.size > 0),
   );
   if (!hasCustom) return null;
 
@@ -333,17 +526,24 @@ async function generateVariantDeclarationsAsync(themeDef) {
     for (const [prop, values] of Object.entries(props)) {
       if (values.size === 0) continue;
 
-      const pascal = toPascalCase(component);
       const propPascal = prop.charAt(0).toUpperCase() + prop.slice(1);
-      const modulePath = `@astryxdesign/core/${pascal}`;
-      const interfaceName = `${pascal}${propPascal}Map`;
+      const target = (await resolveAugmentationTargetCandidates(component)).find(
+        candidate =>
+          componentHasAugmentableInterface(
+            candidate.moduleName,
+            `${candidate.interfacePrefix}${propPascal}Map`,
+          ),
+      );
 
       // Only augment interfaces that actually exist as an extension point in
       // core. Props backed by closed literal-union types (e.g. Button `size`,
       // Heading `type`/`level`) have no `*Map` interface — a `declare module`
       // block against a non-existent interface just creates a new, unused
       // interface and never extends the component's prop union, so skip it.
-      if (!componentHasAugmentableInterface(pascal, interfaceName)) continue;
+      if (!target) continue;
+
+      const modulePath = `@astryxdesign/core/${target.moduleName}`;
+      const interfaceName = `${target.interfacePrefix}${propPascal}Map`;
 
       sections.push(`declare module '${modulePath}' {`);
       sections.push(`  interface ${interfaceName} {`);
@@ -381,7 +581,8 @@ function resolveTokenValue(value) {
 // Theme @scope selector helpers. Keep the `astryx` literal in sync with
 // packages/core/src/naming.ts (NAMESPACE) and generateThemeRules.ts.
 // Theme scopes to data-astryx-theme; the static build path must match.
-const themeScopeStart = (/** @type {string} */ name) => `[data-astryx-theme="${name}"]`;
+const themeScopeStart = (/** @type {string} */ name) =>
+  `[data-astryx-theme="${name}"]`;
 const THEME_SCOPE_TO = `[data-astryx-theme]`;
 
 /**
@@ -408,7 +609,7 @@ async function importThemeModule(filePath) {
 
   throw new Error(
     `Could not find a defineTheme() result in ${filePath}.\n` +
-    `Expected an export like: export const myTheme = defineTheme({ name: '...', tokens: {...} })`,
+      `Expected an export like: export const myTheme = defineTheme({ name: '...', tokens: {...} })`,
   );
 }
 
@@ -442,7 +643,7 @@ async function extractThemeDefinition(filePath) {
       const je = /** @type {Error} */ (jitiError);
       throw new Error(
         `Failed to load theme from ${filePath}: ${je.message}\n` +
-        `Make sure all imports in the theme file are resolvable.`,
+          `Make sure all imports in the theme file are resolvable.`,
       );
     }
   }
@@ -463,25 +664,27 @@ function extractThemeDefinitionLegacy(filePath) {
     if (!defaultMatch) {
       throw new Error(
         `Could not find defineTheme() call or default export in ${filePath}.\n` +
-        `Expected: defineTheme({ name: '...', tokens: {...} })`,
+          `Expected: defineTheme({ name: '...', tokens: {...} })`,
       );
     }
-     
+
     return eval(`(${defaultMatch[1]})`);
   }
 
   let objStr = defineMatch[1];
   objStr = objStr.replace(/\s+as\s+const/g, '');
-  objStr = objStr.replace(/icons:\s*[a-zA-Z_][a-zA-Z0-9_]*/g, 'icons: undefined');
+  objStr = objStr.replace(
+    /icons:\s*[a-zA-Z_][a-zA-Z0-9_]*/g,
+    'icons: undefined',
+  );
 
   try {
-     
     return eval(`(${objStr})`);
   } catch (e) {
     const err = /** @type {Error} */ (e);
     throw new Error(
       `Failed to parse theme definition in ${filePath}: ${err.message}\n` +
-      `Make sure the defineTheme() argument is a plain object literal.`,
+        `Make sure the defineTheme() argument is a plain object literal.`,
       {cause: e},
     );
   }
@@ -532,9 +735,7 @@ function generateBuiltModule(themeDef, iconInfo) {
     ? `import { ${iconInfo.exportName} } from '${iconInfo.importPath}';\n`
     : '';
   const iconsField = iconInfo ? `  icons: ${iconInfo.exportName},` : '';
-  const iconReExport = iconInfo
-    ? `\nexport { ${iconInfo.exportName} };\n`
-    : '';
+  const iconReExport = iconInfo ? `\nexport { ${iconInfo.exportName} };\n` : '';
 
   // Resolve token values — tuples become light-dark() strings
   /** @type {Record<string, unknown>} */
@@ -597,83 +798,90 @@ ${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedThem
 // =============================================================================
 
 /**
- * Known Astryx component names and their visual props.
- * Used to warn on typos in defineTheme component overrides.
- * @type {Record<string, string[]>}
+ * Load known theme target keys and visual props from core component docs.
+ * Returns null when docs are unavailable so validation can skip unknown-key
+ * warnings rather than guessing from a second registry.
+ *
+ * @returns {Promise<Record<string, string[]> | null>}
  */
-const KNOWN_COMPONENTS = {
-  'app-shell': ['position'],
-  'aspect-ratio': [],
-  avatar: ['size'],
-  badge: ['variant', 'color'],
-  banner: ['container', 'status'],
-  breadcrumbs: ['variant'],
-  button: ['variant', 'size'],
-  calendar: [],
-  card: ['variant'],
-  center: [],
-  'checkbox-input': [],
-  collapsible: [],
-  'date-input': [],
-  dialog: ['variant', 'position'],
-  divider: ['variant', 'orientation'],
-  'dropdown-menu': [],
-  'empty-state': [],
-  field: [],
-  'form-layout': [],
-  grid: ['align'],
-  heading: ['level'],
-  icon: ['size', 'color'],
-  kbd: [],
-  layer: [],
-  layout: [],
-  link: ['color'],
-  list: ['type', 'density'],
-  'mobile-nav': [],
-  'more-menu': [],
-  navicon: [],
-  'number-input': [],
-  pagination: ['variant'],
-  progressbar: ['variant', 'size'],
-  'radio-list': ['orientation'],
-  section: ['variant'],
-  selector: ['type', 'size', 'color'],
-  'side-nav': [],
-  skeleton: [],
-  slider: ['orientation'],
-  spinner: ['size'],
-  stack: [],
-  statusdot: ['variant', 'size'],
-  switch: [],
-  table: [],
-  'tab-list': ['type'],
-  text: ['type', 'color'],
-  textarea: [],
-  'text-input': [],
-  'time-input': [],
-  token: ['color'],
-  tokenizer: [],
-  'top-nav': [],
-  typeahead: ['type', 'size', 'color'],
-};
+async function loadKnownComponents() {
+  const coreRoot = resolveCoreRoot();
+  const coreSrc = coreRoot ? path.join(coreRoot, 'src') : null;
+  if (!coreSrc || !fs.existsSync(coreSrc)) return null;
+
+  /** @type {Record<string, string[]>} */
+  const targets = {};
+
+  /** @param {string} dir */
+  async function scan(dir) {
+    const entries = fs.readdirSync(dir, {withFileTypes: true});
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+        await scan(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.doc.mjs')) continue;
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(full);
+      } catch {
+        continue;
+      }
+
+      for (const target of doc?.theming?.targets || []) {
+        const className = target?.className;
+        if (typeof className !== 'string') continue;
+        const key = className.replace(/^astryx-/, '');
+        if (!key) continue;
+        const props = Array.isArray(target.visualProps)
+          ? target.visualProps.filter((/** @type {unknown} */ p) => typeof p === 'string')
+          : [];
+        targets[key] = [...new Set([...(targets[key] || []), ...props])];
+      }
+    }
+  }
+
+  await scan(coreSrc);
+  return Object.keys(targets).length > 0 ? targets : null;
+}
+
+/** @type {Record<string, string[]> | null | undefined} */
+let knownComponentsCache;
+
+/**
+ * @returns {Promise<Record<string, string[]> | null>}
+ */
+async function getKnownComponents() {
+  if (knownComponentsCache === undefined) {
+    knownComponentsCache = await loadKnownComponents();
+  }
+  return knownComponentsCache;
+}
 
 /**
  * Validate component overrides in a theme definition.
  * Warns on unknown component names and unknown prop names.
  * Returns array of warning strings.
  * @param {{components?: Record<string, Record<string, unknown>>}} themeDef
- * @returns {string[]}
+ * @returns {Promise<string[]>}
  */
-function validateComponentOverrides(themeDef) {
+async function validateComponentOverrides(themeDef) {
   /** @type {string[]} */
   const warnings = [];
   if (!themeDef.components) return warnings;
 
+  const knownComponents = await getKnownComponents();
+  if (knownComponents == null) return warnings;
+
   for (const [component, rules] of Object.entries(themeDef.components)) {
     // Check component name
-    if (!(component in KNOWN_COMPONENTS)) {
-      const similar = Object.keys(KNOWN_COMPONENTS)
-        .filter((k) => {
+    if (!(component in knownComponents)) {
+      const similar = Object.keys(knownComponents)
+        .filter(k => {
           if (k.includes(component) || component.includes(k)) return true;
           // Levenshtein distance 1-2 for short names
           if (Math.abs(k.length - component.length) <= 2) {
@@ -691,13 +899,14 @@ function validateComponentOverrides(themeDef) {
           return false;
         })
         .slice(0, 3);
-      const hint = similar.length > 0 ? ` Did you mean: ${similar.join(', ')}?` : '';
+      const hint =
+        similar.length > 0 ? ` Did you mean: ${similar.join(', ')}?` : '';
       warnings.push(`Unknown component "${component}".${hint}`);
       continue;
     }
 
     // Check prop names in prop:value keys
-    const knownProps = KNOWN_COMPONENTS[component];
+    const knownProps = knownComponents[component];
     for (const key of Object.keys(rules)) {
       if (key === 'base') continue;
 
@@ -742,8 +951,8 @@ function validatePrivateVars(themeDef) {
         if (typeof prop === 'string' && prop.startsWith('--_')) {
           errors.push(
             `Component "${component}" (${key}) sets private var "${prop}". ` +
-            `Private vars (--_*) are internal — use standard CSS properties ` +
-            `(e.g. borderRadius, padding) instead. The pipeline expands them automatically.`,
+              `Private vars (--_*) are internal — use standard CSS properties ` +
+              `(e.g. borderRadius, padding) instead. The pipeline expands them automatically.`,
           );
         }
       }
@@ -753,39 +962,31 @@ function validatePrivateVars(themeDef) {
   return errors;
 }
 
-/**
- * @typedef {object} ThemeBuildLogger
- * @property {(m?: string) => void} log   - stdout (install/receipt lines)
- * @property {(m?: string) => void} warn  - stderr (component-override warnings)
- * @property {(m?: string) => void} error - stderr (private-var errors)
- */
-
-/**
- * No-op logger — the default so a programmatic caller stays silent. The CLI
- * injects a real logger (humanLog / console.warn / console.error) in human
- * mode, and this same no-op shape in --json mode so human chatter never
- * corrupts the single JSON envelope.
- * @type {ThemeBuildLogger}
- */
-const noopLogger = {log() {}, warn() {}, error() {}};
-
 /**
  * Compile a defineTheme file to CSS + JS + .d.ts (and an optional
  * `.variants.d.ts`). Performs the writes and returns a `theme.build` receipt,
  * or `null` when the theme produced no CSS (nothing to build). Throws
- * AstryxError (stable code) on failure. Progress is emitted through `logger`
- * (silent by default).
+ * AstryxError (stable code) on failure. Progress is emitted through the shared
+ * `logger` (silent by default).
  *
  * @param {string} file - Theme file path, resolved against `cwd`.
- * @param {{out?: string}} [options] - `out` overrides the output CSS path.
- * @param {{cwd?: string, logger?: ThemeBuildLogger}} [ctx]
- * @returns {Promise<import('../../../types/theme').ThemeBuildResponse | null>}
+ * @param {{out?: string, check?: boolean}} [options] - `out` overrides the output CSS path; `check` compares against on-disk outputs instead of writing.
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null>}
  */
-export async function themeBuild(file, options = {}, {cwd = process.cwd(), logger = noopLogger} = {}) {
+export async function themeBuild(
+  file,
+  options = {},
+  {cwd = process.cwd()} = {},
+) {
   const filePath = path.resolve(cwd, file);
 
   if (!fs.existsSync(filePath)) {
-    throw new AstryxError(`File not found: ${filePath}`, undefined, ERROR_CODES.ERR_FILE_NOT_FOUND);
+    throw new AstryxError(
+      `File not found: ${filePath}`,
+      undefined,
+      ERROR_CODES.ERR_FILE_NOT_FOUND,
+    );
   }
 
   logger.log(`\nBuilding theme from ${path.relative(cwd, filePath)}...`);
@@ -800,7 +1001,11 @@ export async function themeBuild(file, options = {}, {cwd = process.cwd(), logge
   }
 
   if (!themeDef.name) {
-    throw new AstryxError('Theme must have a name property.', undefined, ERROR_CODES.ERR_THEME_INVALID);
+    throw new AstryxError(
+      'Theme must have a name property.',
+      undefined,
+      ERROR_CODES.ERR_THEME_INVALID,
+    );
   }
 
   // Path-safety: the theme name is used to derive output filenames
@@ -811,13 +1016,17 @@ export async function themeBuild(file, options = {}, {cwd = process.cwd(), logge
     sanitizeName(themeDef.name, {label: 'theme name'});
   } catch (err) {
     if (err instanceof PathSafetyError) {
-      throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+      throw new AstryxError(
+        err.message,
+        undefined,
+        ERROR_CODES.ERR_PATH_TRAVERSAL,
+      );
     }
     throw err;
   }
 
   // Validate component overrides
-  const warnings = validateComponentOverrides(themeDef);
+  const warnings = await validateComponentOverrides(themeDef);
   const warningMessages = [];
   for (const w of warnings) {
     warningMessages.push(w);
@@ -831,7 +1040,9 @@ export async function themeBuild(file, options = {}, {cwd = process.cwd(), logge
     logger.error(`  ✗ ${e}`);
   }
   if (privateVarErrors.length > 0) {
-    logger.error(`\n  ${privateVarErrors.length} private var error(s). Use standard CSS properties instead.`);
+    logger.error(
+      `\n  ${privateVarErrors.length} private var error(s). Use standard CSS properties instead.`,
+    );
   }
 
   // Generate CSS via core's shared generator — the SINGLE source of truth.
@@ -844,7 +1055,9 @@ export async function themeBuild(file, options = {}, {cwd = process.cwd(), logge
         'built, resolvable @astryxdesign/core so it emits the same CSS as the ' +
         'runtime <Theme>. Build @astryxdesign/core first (e.g. `pnpm -F @astryxdesign/core ' +
         'build`)' +
-        (_coreImportError ? `.\n  Import error: ${_coreImportError.message}` : '.'),
+        (_coreImportError
+          ? `.\n  Import error: ${_coreImportError.message}`
+          : '.'),
       undefined,
       ERROR_CODES.ERR_CORE_NOT_FOUND,
     );
@@ -911,17 +1124,32 @@ export async function themeBuild(file, options = {}, {cwd = process.cwd(), logge
   // Source path relative to cwd — used in @generated headers
   const sourceRelative = path.relative(cwd, filePath);
   const buildCommand = `astryx theme build ${sourceRelative}${options.out ? ' --out ' + path.relative(cwd, path.resolve(cwd, options.out)) : ''}`;
+  // Stable provenance recorded in @generated headers — versions, not a
+  // timestamp, so identical inputs produce byte-identical output.
+  const versions = resolveToolVersions(cwd);
 
   // Derive the default CSS name from the theme name so .css/.js/.d.ts
   // share one scheme; an explicit --out still wins.
   const baseName = themeDef.name;
-  const outPath = options.out
-    ? path.resolve(cwd, options.out)
-    : path.join(path.dirname(filePath), `${baseName}.css`);
+  let outPath;
+  if (options.out) {
+    outPath = path.resolve(cwd, options.out);
+    // Guard: relative paths must not escape cwd via `../`. Absolute paths are
+    // trusted (the user explicitly controls where output goes, like gcc -o).
+    if (!path.isAbsolute(options.out)) {
+      assertWithin(options.out, cwd, {label: 'output path'});
+    }
+  } else {
+    outPath = path.join(path.dirname(filePath), `${baseName}.css`);
+  }
 
   const displayTheme = resolvedTheme || themeDef;
-  const tokenCount = displayTheme.tokens ? Object.keys(displayTheme.tokens).length : 0;
-  const componentCount = displayTheme.components ? Object.keys(displayTheme.components).length : 0;
+  const tokenCount = displayTheme.tokens
+    ? Object.keys(displayTheme.tokens).length
+    : 0;
+  const componentCount = displayTheme.components
+    ? Object.keys(displayTheme.components).length
+    : 0;
   const size = (Buffer.byteLength(css) / 1024).toFixed(1);
 
   // Compute all output paths up front so we can validate them as a
@@ -938,22 +1166,29 @@ export async function themeBuild(file, options = {}, {cwd = process.cwd(), logge
   // Type augmentation .d.ts if theme has custom prop values. Computed
   // before the main .d.ts so the latter can reference it (see below).
   const augmentationSource = resolvedTheme || themeDef;
-  const variantDecl = await generateVariantDeclarationsAsync(augmentationSource);
+  const variantDecl =
+    await generateVariantDeclarationsAsync(augmentationSource);
   const variantsFileName = variantDecl ? `${baseName}.variants.d.ts` : null;
   const variantDtsPath =
     variantDecl && variantsFileName
       ? path.join(outDir, variantsFileName)
       : null;
   const variantContent = variantDecl
-    ? generatedHeader(sourceRelative, 'ts', buildCommand) + variantDecl
+    ? generatedHeader(sourceRelative, 'ts', buildCommand, versions) +
+      variantDecl
     : null;
 
   // Generate all file contents in memory first. The main .d.ts references
   // the variants file (when present) via a triple-slash directive so
   // importing the theme also loads the custom-variant augmentations.
-  const cssContent = generatedHeader(sourceRelative, 'css', buildCommand) + css;
-  const jsContent = generatedHeader(sourceRelative, 'js', buildCommand) + generateBuiltModule(resolvedTheme || themeDef, iconInfo);
-  const dtsContent = generatedHeader(sourceRelative, 'ts', buildCommand) + generateBuiltTypes(themeDef, iconInfo, variantsFileName);
+  const cssContent =
+    generatedHeader(sourceRelative, 'css', buildCommand, versions) + css;
+  const jsContent =
+    generatedHeader(sourceRelative, 'js', buildCommand, versions) +
+    generateBuiltModule(resolvedTheme || themeDef, iconInfo);
+  const dtsContent =
+    generatedHeader(sourceRelative, 'ts', buildCommand, versions) +
+    generateBuiltTypes(themeDef, iconInfo, variantsFileName);
 
   // Atomic-ish write: stage every file as `<dest>.tmp`, then rename
   // each into place. If any stage step fails we clean up partials and
@@ -968,6 +1203,49 @@ export async function themeBuild(file, options = {}, {cwd = process.cwd(), logge
     writes.push({dest: variantDtsPath, content: variantContent});
   }
 
+  // Check mode: compare generated content against what's on disk instead of
+  // writing. A file is "stale" if it's missing or its content differs once the
+  // volatile @generated `Command:` line is ignored. Returns a
+  // receipt listing stale/missing outputs so callers (CI) can fail on drift.
+  if (options.check) {
+    /** @type {Array<{path: string, reason: 'missing' | 'outdated'}>} */
+    const stale = [];
+    for (const w of writes) {
+      const rel = path.relative(cwd, w.dest);
+      if (!fs.existsSync(w.dest)) {
+        stale.push({path: rel, reason: 'missing'});
+        continue;
+      }
+      const onDisk = fs.readFileSync(w.dest, 'utf8');
+      if (normalizeForCompare(onDisk) !== normalizeForCompare(w.content)) {
+        stale.push({path: rel, reason: 'outdated'});
+      }
+    }
+    const upToDate = stale.length === 0;
+    if (upToDate) {
+      logger.log(`\n✓ Theme outputs are up to date with ${sourceRelative}.`);
+    } else {
+      logger.error(
+        `\n✗ ${stale.length} theme output(s) are out of date with ${sourceRelative}:`,
+      );
+      for (const s of stale) {
+        logger.error(
+          `  ${s.reason === 'missing' ? 'missing' : 'stale'}: ${s.path}`,
+        );
+      }
+      logger.error(`\n  Rebuild with: ${buildCommand}`);
+    }
+    return {
+      type: 'theme.build.check',
+      data: {
+        name: themeDef.name,
+        upToDate,
+        stale,
+        checked: writes.map(w => path.relative(cwd, w.dest)),
+      },
+    };
+  }
+
   fs.mkdirSync(outDir, {recursive: true});
   /** @type {Array<{tmp: string, dest: string}>} */
   const staged = [];
@@ -983,20 +1261,28 @@ export async function themeBuild(file, options = {}, {cwd = process.cwd(), logge
   } catch (err) {
     // Roll back any temp files we managed to create.
     for (const s of staged) {
-      try { fs.rmSync(s.tmp, {force: true}); } catch { /* best-effort */ }
+      try {
+        fs.rmSync(s.tmp, {force: true});
+      } catch {
+        /* best-effort */
+      }
     }
     const msg = `Failed to write theme outputs: ${/** @type {Error} */ (err).message}`;
     throw new AstryxError(msg, undefined, ERROR_CODES.ERR_WRITE_FAILED);
   }
 
   logger.log(`\n✓ ${path.relative(cwd, outPath)}`);
-  logger.log(`  ${tokenCount} token overrides, ${componentCount} component overrides`);
+  logger.log(
+    `  ${tokenCount} token overrides, ${componentCount} component overrides`,
+  );
   logger.log(`  ${size} KB`);
   logger.log(`✓ ${path.relative(cwd, jsPath)}`);
   logger.log(`✓ ${path.relative(cwd, dtsPath)}`);
   if (variantDtsPath && variantDecl) {
     const augCount = (variantDecl.match(/': true;/g) || []).length;
-    logger.log(`✓ ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`);
+    logger.log(
+      `✓ ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
+    );
   }
 
   const relOutDir = path.relative(cwd, outDir) || '.';
@@ -1026,7 +1312,9 @@ Or with a <link> tag:
 
   // Print font declaration warnings (derived from typography roles)
   if (resolvedTheme && resolvedTheme.fonts && resolvedTheme.fonts.length > 0) {
-    logger.log(`\n⚠ Theme "${themeDef.name}" requires fonts not included in the build:`);
+    logger.log(
+      `\n⚠ Theme "${themeDef.name}" requires fonts not included in the build:`,
+    );
     for (const font of resolvedTheme.fonts) {
       logger.log(`  ${font.family} — add to your document <head>:`);
       logger.log(`  <link rel="stylesheet" href="${font.url}" />`);
@@ -1045,7 +1333,9 @@ Or with a <link> tag:
         css: path.relative(cwd, outPath),
         js: path.relative(cwd, jsPath),
         dts: path.relative(cwd, dtsPath),
-        ...(variantDecl && variantDtsPath ? {variantsDts: path.relative(cwd, variantDtsPath)} : {}),
+        ...(variantDecl && variantDtsPath
+          ? {variantsDts: path.relative(cwd, variantDtsPath)}
+          : {}),
       },
       warnings: warningMessages,
     },