@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.db4e378

package/api/theme/themeBuild.doc.mjs

@@ -73,7 +73,7 @@ export const doc = {
     {
       type: 'theme.build',
       description:
-        'Build receipt: theme name, token- and component-override counts, output size in KB, the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}, and validation warnings—including exact canonical replacements for deprecated component target keys. Resolves to null instead when the theme produced no CSS (nothing to build).',
+        'Build receipt {name, tokenCount, componentCount, sizeKB, outputs, warnings, notices}: the theme name; how many tokens (portable plus theme-local) and component targets it overrides; the CSS size in KB; the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}; warnings, the defects the author should fix, including exact canonical replacements for deprecated component target keys and declarations the generator dropped; and notices, advisories about a correct theme, such as a font it names but does not load. Resolves to null instead when the theme produced no CSS (nothing to build).',
     },
     {
       type: 'theme.build.check',
@@ -87,10 +87,13 @@ export const doc = {
       code: 'ERR_THEME_LOAD',
       when: 'the file cannot be loaded or parsed into a defineTheme() result',
     },
-    {code: 'ERR_THEME_INVALID', when: 'the resolved theme has no name'},
+    {
+      code: 'ERR_THEME_INVALID',
+      when: 'the resolved theme is invalid, for example it has no name, or a custom Heading type has no standalone rule with a declaration the compiler can emit',
+    },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the theme name contains a path separator or traversal marker',
+      when: 'the theme name contains a path separator or traversal marker, or a relative `out` path resolves outside cwd (including through a symlink)',
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
@@ -102,7 +105,7 @@ export const doc = {
     },
     {
       code: 'ERR_WRITE_FAILED',
-      when: 'writing the outputs fails (staged temp files are rolled back)',
+      when: 'creating the output directory or writing the outputs fails (staged temp files are rolled back)',
     },
   ],
   examples: [

package/api/theme/themeTemplate.doc.mjs

@@ -51,7 +51,10 @@ export const doc = {
         'Receipt: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success, not a failure.',
     },
   ],
-  throws: [{code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'}],
+  throws: [
+    {code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
+    {code: 'ERR_WRITE_FAILED', when: 'the template file cannot be written'},
+  ],
   examples: [
     {label: 'Write it at the project root', code: 'themeTemplate();'},
     {

package/api/upgrade/_adapter.mjs

@@ -104,6 +104,27 @@ export function uniqueFiles(files) {
   ];
 }
 
+/**
+ * Run app code with its stdout writes sent to stderr. Stdout carries only the
+ * command's own output, so a hook that prints cannot corrupt `--json`.
+ * @template T
+ * @param {() => T | Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+async function withStdoutOnStderr(fn) {
+  const realWrite = process.stdout.write;
+  process.stdout.write = /** @type {any} */ (
+    function (/** @type {any} */ chunk, /** @type {any[]} */ ...rest) {
+      return process.stderr.write(chunk, ...rest);
+    }
+  );
+  try {
+    return await fn();
+  } finally {
+    process.stdout.write = realWrite;
+  }
+}
+
 /**
  * Run the app config's post-codemod hooks (config.hooks.postCodemod).
  * Dry-run PREVIEWS (buildCommand still called, so a throw fails); apply executes.
@@ -123,7 +144,9 @@ export async function runPostCodemodHooks(hooks, context) {
       );
     }
 
-    const cmd = await hook.buildCommand({packageDir, files});
+    const cmd = await withStdoutOnStderr(() =>
+      hook.buildCommand({packageDir, files}),
+    );
     if (!cmd) {
       logger.log(`Post-codemod hook ${label} produced no command; skipping.`);
       continue;
@@ -147,7 +170,7 @@ export async function runPostCodemodHooks(hooks, context) {
         env: {...process.env, ...(cmd.options?.env ?? {})},
       }),
     );
-    logger.log(`✓ Post-codemod hook ${label} completed.`);
+    logger.log(`[ok] Post-codemod hook ${label} completed.`);
   }
 }
 
@@ -186,7 +209,7 @@ export async function prepareAgentDocsRefresh({
   if (initial.status === 'missing') {
     summary.action = 'nudge-init';
     logger.warn(
-      `No Astryx agent-docs block found — AI agents have no component index. Run \`${formatCliCommand('astryx init --features agents')}\` to install it.`,
+      `No Astryx agent-docs block found - AI agents have no component index. Run \`${formatCliCommand('astryx init --features agents')}\` to install it.`,
     );
     return {cwd, renderedBlock: null, summary};
   }
@@ -240,7 +263,7 @@ export function applyAgentDocsRefresh(plan) {
     summary.files = written;
     summary.action = summary.refreshed ? 'refreshed' : 'error';
     if (summary.refreshed) {
-      logger.log(`✓ Agent docs refreshed → ${written.join(', ')}`);
+      logger.log(`[ok] Agent docs refreshed -> ${written.join(', ')}`);
     } else {
       logger.warn(
         `Agent docs look stale but couldn't be refreshed. Run \`${formatCliCommand('astryx init --features agents')}\` to reinstall the block.`,

package/api/upgrade/list/list.mjs

@@ -10,6 +10,7 @@
 
 import {collectAllCodemods} from '../_adapter.mjs';
 import {logger} from '../../logger.mjs';
+import {toAscii} from '../../../assets/codemods/term-log.mjs';
 
 /**
  * List every available codemod (oldest→newest).
@@ -19,7 +20,7 @@ export async function list() {
   const codemods = await collectAllCodemods();
   logger.log('Available codemods:');
   for (const {name, title, pr, optional} of codemods) {
-    logger.log(`  ${name} — ${title}${optional ? ' (optional)' : ''} (${pr})`);
+    logger.log(`  ${name} - ${toAscii(title)}${optional ? ' (optional)' : ''} (${pr})`);
   }
   logger.log('Done\n');
   return {

package/api/upgrade/list/list.test.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for the upgrade.list leaf: every field an entry
+ * carries is declared on the canonical `UpgradeListEntry` type, and every
+ * declared field is present on every entry.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import ts from 'typescript';
+import {list} from './list.mjs';
+
+const TYPE_FILE = fileURLToPath(
+  new URL('../upgrade.type.mjs', import.meta.url),
+);
+
+/**
+ * Property names a JSDoc `@typedef {object}` declares, parsed from the file.
+ * @param {string} typedefName
+ * @returns {string[]}
+ */
+function declaredProperties(typedefName) {
+  const source = ts.createSourceFile(
+    TYPE_FILE,
+    fs.readFileSync(TYPE_FILE, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.JS,
+  );
+  /** @type {string[]} */
+  const names = [];
+  for (const statement of source.statements) {
+    for (const doc of /** @type {any} */ (statement).jsDoc ?? []) {
+      for (const tag of doc.tags ?? []) {
+        if (
+          !ts.isJSDocTypedefTag(tag) ||
+          tag.name?.getText(source) !== typedefName
+        ) {
+          continue;
+        }
+        const literal = tag.typeExpression;
+        if (literal && ts.isJSDocTypeLiteral(literal)) {
+          for (const property of literal.jsDocPropertyTags ?? []) {
+            names.push(property.name.getText(source));
+          }
+        }
+      }
+    }
+  }
+  return names.sort();
+}
+
+describe('upgrade.list entries', () => {
+  it('carry exactly the fields UpgradeListEntry declares', async () => {
+    const declared = declaredProperties('UpgradeListEntry');
+    expect(declared.length).toBeGreaterThan(0);
+
+    const {type, data} = await list();
+    expect(type).toBe('upgrade.list');
+    expect(data.length).toBeGreaterThan(0);
+    for (const entry of data) {
+      expect(Object.keys(entry).sort()).toEqual(declared);
+    }
+  });
+
+  it('marks optional codemods with a boolean', async () => {
+    const {data} = await list();
+    for (const entry of data) expect(typeof entry.optional).toBe('boolean');
+    expect(data.some(entry => entry.optional)).toBe(true);
+  });
+});

package/api/upgrade/status/status.mjs

@@ -24,7 +24,7 @@ import {logger} from '../../logger.mjs';
  * @returns {import('../upgrade.type.mjs').UpgradeStatusResponse}
  */
 export function statusUpToDate({from, to, agentDocs, registryCompositions}) {
-  logger.log('✓ Already up to date — no codemods to run.');
+  logger.log('[ok] Already up to date - no codemods to run.');
   logger.log('Use --force to run codemods anyway.');
   logger.log(registryCompositions?.ok === false ? 'Finished with unresolved registry items\n' : 'Done\n');
   return {
@@ -45,7 +45,7 @@ export function statusUpToDate({from, to, agentDocs, registryCompositions}) {
  * @returns {import('../upgrade.type.mjs').UpgradeStatusResponse}
  */
 export function statusNoCodemods({from, to, agentDocs, registryCompositions}) {
-  logger.log('✓ No codemods available for this version range.');
+  logger.log('[ok] No codemods available for this version range.');
   logger.log(registryCompositions?.ok === false ? 'Finished with unresolved registry items\n' : 'Done\n');
   return {
     type: 'upgrade.status',

package/api/upgrade/upgrade.doc.mjs

@@ -80,7 +80,8 @@ export const doc = {
     {
       name: 'options.installDeps',
       type: 'boolean',
-      description: 'Auto-install jscodeshift without prompting.',
+      description:
+        'Install jscodeshift when it is missing; otherwise a missing jscodeshift throws ERR_DEP_MISSING.',
     },
     {
       name: 'options.registry',

package/api/upgrade/upgrade.type.d.mts

@@ -12,6 +12,10 @@ export type UpgradeListEntry = {
     name: string;
     title: string;
     version: string;
+    /**
+     * True when the codemod runs only if named with `--codemod`.
+     */
+    optional: boolean;
 };
 /**
  * State of the managed agent-docs block (`<!-- ASTRYX:START --> … END -->`)

package/api/upgrade/upgrade.type.mjs

@@ -25,6 +25,7 @@
  * @property {string} name
  * @property {string} title
  * @property {string} version
+ * @property {boolean} optional True when the codemod runs only if named with `--codemod`.
  */
 
 /**

package/assets/codemods/term-log.mjs

@@ -11,6 +11,8 @@
  * `p.log.step(...)`, `p.log.success(...)`, etc. All output routes through
  * `humanLog`, the CLI's stdout-discipline primitive, which is a no-op in
  * `--json` mode — so these human logs can never corrupt a JSON envelope.
+ * Every line is plain ASCII: level prefixes are ASCII and typographic glyphs
+ * in a message are transliterated before it is printed.
  *
  * The side-effecting API commands (upgrade/init/themeBuild) do NOT use this;
  * they write through the shared `logger` (api/logger.mjs).
@@ -18,8 +20,30 @@
 
 import {humanLog} from '../../foundation/response/json.mjs';
 
-/** @param {unknown} msg */
-const toStr = (msg) => (msg === undefined || msg === null ? '' : String(msg));
+/** @type {Array<[RegExp, string]>} */
+const ASCII_GLYPHS = [
+  [/[\u2014\u2013]/g, '-'],
+  [/\u2192/g, '->'],
+  [/\u2713/g, '[ok]'],
+  [/\u2717/g, '!!'],
+  [/\u26a0\ufe0f?/g, '!'],
+  [/\u2022/g, '-'],
+  [/\u2026/g, '...'],
+  [/[\u2018\u2019]/g, "'"],
+  [/[\u201c\u201d]/g, '"'],
+  [/\u00a0/g, ' '],
+];
+
+/**
+ * A message as plain ASCII: typographic glyphs become their ASCII spelling.
+ * @param {unknown} msg
+ * @returns {string}
+ */
+export function toAscii(msg) {
+  let text = msg === undefined || msg === null ? '' : String(msg);
+  for (const [glyph, ascii] of ASCII_GLYPHS) text = text.replace(glyph, ascii);
+  return text;
+}
 
 /**
  * Human-facing log surface (the small `log` API codemods use). All lines go to
@@ -28,15 +52,15 @@ const toStr = (msg) => (msg === undefined || msg === null ? '' : String(msg));
  */
 export const log = {
   /** @param {unknown} msg */
-  message: (msg) => humanLog(toStr(msg)),
+  message: (msg) => humanLog(toAscii(msg)),
   /** @param {unknown} msg */
-  info: (msg) => humanLog(toStr(msg)),
+  info: (msg) => humanLog(toAscii(msg)),
   /** @param {unknown} msg */
-  step: (msg) => humanLog(toStr(msg)),
+  step: (msg) => humanLog(toAscii(msg)),
   /** @param {unknown} msg */
-  success: (msg) => humanLog(`✓ ${toStr(msg)}`),
+  success: (msg) => humanLog(`[ok] ${toAscii(msg)}`),
   /** @param {unknown} msg */
-  warn: (msg) => humanLog(`⚠ ${toStr(msg)}`),
+  warn: (msg) => humanLog(`! ${toAscii(msg)}`),
   /** @param {unknown} msg */
-  error: (msg) => humanLog(`✗ ${toStr(msg)}`),
+  error: (msg) => humanLog(`!! ${toAscii(msg)}`),
 };

package/assets/codemods/term-log.test.mjs

@@ -51,7 +51,7 @@ describe('sanity: helpers are live in human mode', () => {
     setJsonMode(false);
     p.log.success('done');
     expect(logSpy).toHaveBeenCalledTimes(1);
-    expect(logSpy).toHaveBeenCalledWith('✓ done');
+    expect(logSpy).toHaveBeenCalledWith('[ok] done');
   });
 
   it('every log helper emits exactly one stdout line in human mode', () => {
@@ -60,3 +60,21 @@ describe('sanity: helpers are live in human mode', () => {
     expect(logSpy).toHaveBeenCalledTimes(6);
   });
 });
+
+describe('ASCII output', () => {
+  it('prints ASCII level prefixes and transliterates glyphs in messages', () => {
+    setJsonMode(false);
+    p.log.success('src/a.tsx');
+    p.log.warn('stale \u2014 refresh');
+    p.log.error('    \u2717 src/b.tsx \u2014 rename \u2192 failed');
+    p.log.info('  \u2022 name \u2014 title\u2026');
+    const lines = logSpy.mock.calls.map(call => call.join(' '));
+    expect(lines).toEqual([
+      '[ok] src/a.tsx',
+      '! stale - refresh',
+      '!!     !! src/b.tsx - rename -> failed',
+      '  - name - title...',
+    ]);
+    for (const line of lines) expect(line).not.toMatch(/[\u0080-\uFFFF]/);
+  });
+});

package/assets/codemods/transform-prop.mjs

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Find imported components, resolve their local JSX names (including aliases),
+ * and yield matching JSX prop paths to a visitor.
+ *
+ * This helper intentionally stops at the JSX boundary. It does not follow
+ * variables, helper calls, object spreads, wrapper components, or types.
+ *
+ * @param {any} root jscodeshift collection for one source file
+ * @param {any} j configured jscodeshift instance
+ * @param {{
+ *   matchesImport: (source: string) => boolean,
+ *   components: ReadonlyMap<string, ReadonlySet<string>>,
+ *   normalizeComponentName?: (name: string) => string,
+ * }} options
+ * @param {(propPath: any, context: {component: string, localName: string}) => void} visit
+ */
+export function transformProp(root, j, options, visit) {
+  const normalize = options.normalizeComponentName ?? (name => name);
+  /** @type {Map<string, {component: string, props: ReadonlySet<string>}>} */
+  const directBindings = new Map();
+  /** @type {Set<string>} */
+  const namespaceBindings = new Set();
+
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ importPath) => {
+    const source = importPath.node.source.value;
+    if (
+      importPath.node.importKind === 'type' ||
+      typeof source !== 'string' ||
+      !options.matchesImport(source)
+    ) {
+      return;
+    }
+
+    const subpathName = normalize(source.split('/').at(-1) ?? '');
+    const subpathProps = options.components.get(subpathName);
+
+    for (const specifier of importPath.node.specifiers ?? []) {
+      if (specifier.importKind === 'type') continue;
+
+      if (specifier.type === 'ImportSpecifier') {
+        const importedName =
+          specifier.imported?.name ?? specifier.imported?.value;
+        if (typeof importedName !== 'string') continue;
+        const component = normalize(importedName);
+        const props = options.components.get(component);
+        if (!props) continue;
+        directBindings.set(specifier.local?.name ?? importedName, {
+          component,
+          props,
+        });
+      } else if (specifier.type === 'ImportDefaultSpecifier' && subpathProps) {
+        directBindings.set(specifier.local.name, {
+          component: subpathName,
+          props: subpathProps,
+        });
+      } else if (specifier.type === 'ImportNamespaceSpecifier') {
+        namespaceBindings.add(specifier.local.name);
+      }
+    }
+  });
+
+  if (directBindings.size === 0 && namespaceBindings.size === 0) return;
+
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ jsxPath) => {
+    const name = jsxPath.node.name;
+    let localName;
+    let component;
+    let props;
+
+    if (name.type === 'JSXIdentifier') {
+      localName = name.name;
+      const binding = directBindings.get(localName);
+      if (!binding) return;
+      ({component, props} = binding);
+    } else if (
+      name.type === 'JSXMemberExpression' &&
+      name.object?.type === 'JSXIdentifier' &&
+      name.property?.type === 'JSXIdentifier' &&
+      namespaceBindings.has(name.object.name)
+    ) {
+      localName = name.object.name;
+      component = normalize(name.property.name);
+      props = options.components.get(component);
+      if (!props) return;
+    } else {
+      return;
+    }
+
+    // A parameter or local declaration with the imported name shadows the
+    // module binding. Only JSX tags whose root binding resolves to Program are
+    // considered usages of the import discovered above.
+    const bindingScope = jsxPath.scope.lookup(localName);
+    if (!bindingScope || bindingScope.path.node.type !== 'Program') return;
+
+    for (let index = 0; index < jsxPath.node.attributes.length; index++) {
+      const attribute = jsxPath.node.attributes[index];
+      if (
+        attribute.type !== 'JSXAttribute' ||
+        attribute.name?.type !== 'JSXIdentifier' ||
+        !props.has(attribute.name.name)
+      ) {
+        continue;
+      }
+      visit(jsxPath.get('attributes', index), {component, localName});
+    }
+  });
+}

package/assets/codemods/transform-prop.test.mjs

@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import jscodeshift from 'jscodeshift';
+import {transformProp} from './transform-prop.mjs';
+
+const j = jscodeshift.withParser('tsx');
+const components = new Map([
+  ['Widget', new Set(['tone'])],
+  ['Group', new Set(['size'])],
+]);
+
+function apply(source) {
+  const root = j(source);
+  transformProp(
+    root,
+    j,
+    {
+      matchesImport: value => /^@example\/core(?:\/|$)/.test(value),
+      components,
+      normalizeComponentName: name =>
+        name.startsWith('XDS') ? name.slice(3) : name,
+    },
+    propPath => {
+      propPath.node.name.name = `migrated${propPath.node.name.name}`;
+    },
+  );
+  return root.toSource({quote: 'single'});
+}
+
+describe('transformProp', () => {
+  it('maps named import aliases to their JSX usages', () => {
+    const output = apply(`import {Widget as Card} from '@example/core';
+const view = <Card tone="old" other="old" />;`);
+
+    expect(output).toContain('<Card migratedtone="old" other="old"');
+  });
+
+  it('maps default subpath imports', () => {
+    const output = apply(`import Card from '@example/core/Widget';
+const view = <Card tone="old" />;`);
+
+    expect(output).toContain('<Card migratedtone="old"');
+  });
+
+  it('ignores declaration-level type imports', () => {
+    const output = apply(`import type {Widget} from '@example/core';
+const Widget = props => <div {...props} />;
+const view = <Widget tone="old" />;`);
+
+    expect(output).toContain('<Widget tone="old"');
+    expect(output).not.toContain('migratedtone');
+  });
+
+  it('ignores type specifiers in mixed imports', () => {
+    const output = apply(`import {type Widget, Group} from '@example/core';
+const Widget = props => <div {...props} />;
+const view = <><Widget tone="old" /><Group size="old" /></>;`);
+
+    expect(output).toContain('<Widget tone="old"');
+    expect(output).toContain('<Group migratedsize="old"');
+    expect(output).not.toContain('<Widget migratedtone');
+  });
+
+  it('maps namespace imports', () => {
+    const output = apply(`import * as Core from '@example/core';
+const view = <Core.Group size="old" />;`);
+
+    expect(output).toContain('<Core.Group migratedsize="old"');
+  });
+
+  it('ignores same-named imports from other packages', () => {
+    const source = `import {Widget} from '@other/core';
+const view = <Widget tone="old" />;`;
+    expect(apply(source)).toBe(source);
+  });
+
+  it('ignores a local binding that shadows an imported alias', () => {
+    const output = apply(`import {Widget as Card} from '@example/core';
+const migrated = <Card tone="old" />;
+function Local(Card) { return <Card tone="local" />; }`);
+
+    expect(output).toContain('<Card migratedtone="old"');
+    expect(output).toContain('<Card tone="local"');
+  });
+
+  it('yields only configured props on configured components', () => {
+    const output = apply(`import {Widget, Group} from '@example/core';
+const a = <Widget size="old" tone="old" />;
+const b = <Group tone="old" size="old" />;`);
+
+    expect(output).toContain('<Widget size="old" migratedtone="old"');
+    expect(output).toContain('<Group tone="old" migratedsize="old"');
+  });
+});