@astryxdesign/cli 0.1.1 → 0.1.2-canary.2149fa3

package/src/lib/integrations.mjs

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration manifest loading for Astryx config.
+ *
+ * Integrations are package names or direct manifest paths listed in
+ * astryx.config.mjs. A manifest can contribute docs/discovery metadata,
+ * gap-report/template hooks, upgrade codemods, and post-codemod hooks.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {validateIntegration} from './config-schema.mjs';
+
+export function isPathSpec(spec) {
+  return (
+    spec.startsWith('.') ||
+    spec.startsWith('/') ||
+    spec.endsWith('.mjs') ||
+    spec.endsWith('.js')
+  );
+}
+
+export function resolvePackageDir(packageName, cwd = process.cwd()) {
+  return path.resolve(cwd, 'node_modules', ...packageName.split('/'));
+}
+
+export function resolveIntegrationFile(spec, cwd = process.cwd()) {
+  if (isPathSpec(spec)) {
+    return path.resolve(cwd, spec);
+  }
+
+  const packageDir = resolvePackageDir(spec, cwd);
+  const pkgPath = path.join(packageDir, 'package.json');
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    throw new Error(
+      `Could not find installed integration package "${spec}" at ${pkgPath}. Install it first or pass a direct integration file path.`,
+    );
+  }
+
+  const manifestPath = pkg.astryx?.integration ?? pkg.xds?.integration;
+  if (!manifestPath) {
+    throw new Error(
+      `Package "${spec}" does not declare astryx.integration (or legacy xds.integration) in package.json.`,
+    );
+  }
+  return path.resolve(packageDir, manifestPath);
+}
+
+function normalizePackageContribution(integration) {
+  const docs = integration.docs;
+  if (!docs) return null;
+  const packageDir = integration.__packageDir ?? integration.__dir;
+  const docsDir = path.resolve(packageDir, docs);
+  return {
+    name: integration.name ?? integration.__spec,
+    version: integration.version,
+    description: integration.description,
+    displayName: integration.displayName,
+    dir: packageDir,
+    astryx: {
+      docs,
+      category: integration.category,
+      blocks: integration.blocks,
+    },
+    category: integration.category ?? integration.name ?? integration.__spec,
+    docsDir,
+  };
+}
+
+function resolveHookFunction(hook, integration) {
+  if (typeof hook === 'function') return hook;
+  if (typeof hook !== 'string') return hook;
+  const [moduleSpec, exportName = 'default'] = hook.split('#');
+  return async (...args) => {
+    const mod = isPathSpec(moduleSpec)
+      ? await import(
+          pathToFileURL(path.resolve(integration.__dir, moduleSpec)).href
+        )
+      : await import(moduleSpec);
+    const fn = exportName === 'default' ? mod.default : mod[exportName];
+    if (typeof fn !== 'function') {
+      throw new Error(
+        `Integration hook ${hook} did not resolve to a function.`,
+      );
+    }
+    return fn(...args);
+  };
+}
+
+export async function loadIntegrations(specs = [], {cwd = process.cwd()} = {}) {
+  const integrations = [];
+  const seen = new Set();
+
+  for (const spec of specs) {
+    if (!spec || seen.has(spec)) continue;
+    seen.add(spec);
+
+    const file = resolveIntegrationFile(spec, cwd);
+    const mod = await import(pathToFileURL(file).href);
+    const exported = mod.default ?? mod.integration ?? mod;
+    if (!exported || typeof exported !== 'object') {
+      throw new Error(`Integration ${spec} did not export an object.`);
+    }
+    const integration = validateIntegration(exported, `Integration ${spec}`);
+
+    const integrationDir = path.dirname(file);
+    const packageDir = isPathSpec(spec)
+      ? integrationDir
+      : resolvePackageDir(spec, cwd);
+    const normalized = {
+      ...integration,
+      __file: file,
+      __dir: integrationDir,
+      __packageDir: packageDir,
+      __spec: spec,
+    };
+
+    if (Array.isArray(normalized.codemods)) {
+      for (const codemod of normalized.codemods) {
+        if (typeof codemod.transform === 'string') {
+          const transformPath = path.resolve(integrationDir, codemod.transform);
+          const transformMod = await import(pathToFileURL(transformPath).href);
+          codemod.transform =
+            transformMod.default ?? transformMod.transform ?? transformMod;
+        }
+      }
+    }
+
+    normalized.package = normalizePackageContribution(normalized);
+    if (
+      normalized.gapReport?.command &&
+      isPathSpec(normalized.gapReport.command)
+    ) {
+      normalized.gapReport = {
+        ...normalized.gapReport,
+        command: path.resolve(packageDir, normalized.gapReport.command),
+      };
+    }
+    if (normalized.template?.get) {
+      normalized.template = {
+        ...normalized.template,
+        get: resolveHookFunction(normalized.template.get, normalized),
+      };
+    }
+
+    integrations.push(normalized);
+  }
+
+  return integrations;
+}

package/src/lib/integrations.test.mjs

@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadConfig} from './config.mjs';
+import {discover} from '../api/discover.mjs';
+import {loadGapReportConfig} from '../utils/github.mjs';
+import {getTemplateById} from '../api/template.mjs';
+
+let tmpDir;
+let originalCwd;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-integration-test-'),
+  );
+  fs.mkdirSync(path.join(tmpDir, 'node_modules', '@acme', 'widgets'), {
+    recursive: true,
+  });
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    `export default { integrations: '@acme/widgets' };\n`,
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'package.json'),
+    JSON.stringify({
+      name: '@acme/widgets',
+      version: '1.2.3',
+      displayName: 'Acme Widgets',
+      astryx: {integration: './astryx.integration.mjs'},
+    }),
+  );
+  fs.writeFileSync(
+    path.join(
+      tmpDir,
+      'node_modules',
+      '@acme',
+      'widgets',
+      'astryx.integration.mjs',
+    ),
+    `export default {
+      name: '@acme/widgets',
+      version: '1.2.3',
+      displayName: 'Acme Widgets',
+      docs: './docs',
+      category: 'Acme',
+      gapReport: {command: './scripts/report-gap.sh'},
+      template: {get: './template.mjs#getTemplate'},
+      codemods: [{name: 'noop', from: '0.0.0', to: '9.0.0', transform: './codemod.mjs'}],
+    };\n`,
+  );
+  fs.mkdirSync(path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'docs'));
+  fs.writeFileSync(
+    path.join(
+      tmpDir,
+      'node_modules',
+      '@acme',
+      'widgets',
+      'docs',
+      'Widget.doc.mjs',
+    ),
+    `export const doc = {
+      name: 'Widget',
+      usage: {description: 'Acme widget'},
+      props: [],
+    };\n`,
+  );
+  fs.mkdirSync(
+    path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'scripts'),
+  );
+  fs.writeFileSync(
+    path.join(
+      tmpDir,
+      'node_modules',
+      '@acme',
+      'widgets',
+      'scripts',
+      'report-gap.sh',
+    ),
+    '#!/bin/sh\ncat >/dev/null\necho ok\n',
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'template.mjs'),
+    `export async function getTemplate(id) { return 'template:' + id; }\n`,
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'codemod.mjs'),
+    `export default function transform() { return undefined; }\n`,
+  );
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('configured integrations', () => {
+  it('load docs/gap/template/codemod metadata from integration manifests', async () => {
+    const config = await loadConfig(tmpDir);
+    expect(config.integrations).toEqual(['@acme/widgets']);
+    expect(config.loadedIntegrations[0].name).toBe('@acme/widgets');
+    expect(config.loadedIntegrations[0].package).toMatchObject({
+      name: '@acme/widgets',
+      category: 'Acme',
+    });
+    expect(config.loadedIntegrations[0].codemods[0].transform).toEqual(
+      expect.any(Function),
+    );
+    expect(config.gapReport.command).toBe(
+      path.join(
+        tmpDir,
+        'node_modules',
+        '@acme',
+        'widgets',
+        'scripts',
+        'report-gap.sh',
+      ),
+    );
+    await expect(config.template.get('P123')).resolves.toBe('template:P123');
+  });
+
+  it('makes integration docs discoverable without packages config', async () => {
+    const result = await discover(undefined, {});
+    expect(result.type).toBe('discover.list');
+    expect(result.data).toEqual([
+      expect.objectContaining({
+        name: '@acme/widgets',
+        category: 'Acme',
+        components: ['Widget'],
+      }),
+    ]);
+  });
+
+  it('uses integration gap-report and template hooks', async () => {
+    await expect(loadGapReportConfig()).resolves.toMatchObject({
+      enabled: true,
+      command: path.join(
+        tmpDir,
+        'node_modules',
+        '@acme',
+        'widgets',
+        'scripts',
+        'report-gap.sh',
+      ),
+    });
+    await expect(getTemplateById('P123', {cwd: tmpDir})).resolves.toEqual({
+      type: 'template.get',
+      data: {id: 'P123', source: 'template:P123'},
+    });
+  });
+});

package/src/lib/levenshtein.mjs

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Levenshtein edit distance — pure, dependency-free.
+ *
+ * Lives apart from string-utils.mjs (which dynamically imports node:fs/path
+ * for component search) so browser-bundled code — the XLE/XLO layout
+ * language — can use fuzzy matching without dragging node: schemes into the
+ * webpack graph.
+ *
+ * @input  two strings
+ * @output edit distance (number)
+ * @position lib — shared by string-utils.mjs and lib/xle/validate.mjs
+ */
+
+export function levenshteinDistance(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i-1] === b[j-1]
+        ? dp[i-1][j-1]
+        : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+    }
+  }
+  return dp[m][n];
+}

package/src/lib/manifest.mjs

@@ -60,10 +60,15 @@ export const RESPONSE_TYPES = {
   ],
   hook: ['hook.list', 'hook.brief', 'hook.full', 'hook.detail', 'hook.detail.params'],
   'theme build': ['theme.build'],
+  'theme list': ['theme.list'],
+  'theme add': ['theme.list', 'theme.add'],
   upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
   'gap-report': ['gap-report.categories', 'gap-report.dryRun', 'gap-report.file'],
   manifest: ['manifest'],
   doctor: ['doctor'],
+  'layout expand': ['layout.expand'],
+  'layout check': ['layout.check'],
+  'layout grammar': ['layout.grammar'],
 };
 
 /**
@@ -79,10 +84,15 @@ const EXAMPLES = {
   template: ['astryx template --json', 'astryx template dashboard ./src/app'],
   hook: ['astryx hook', 'astryx hook useToggle --json'],
   'theme build': ['astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css'],
+  'theme list': ['astryx theme list --json'],
+  'theme add': ['astryx theme add matcha', 'astryx theme add matcha ./src/themes/matcha'],
   upgrade: ['astryx upgrade --json'],
   manifest: ['astryx manifest --json', 'astryx --json'],
   doctor: ['astryx doctor', 'astryx doctor --json'],
   init: ['astryx init'],
+  'layout expand': [`astryx layout expand 'V[g6] > C{card-callout}*4' ./src/Page.tsx`],
+  'layout check': [`astryx layout check 'A[cp6] > L > LC > S[p6]' --json`],
+  'layout grammar': ['astryx layout grammar'],
 };
 
 /**

package/src/lib/package-scanner.mjs

@@ -15,7 +15,11 @@ export function scanDirectory(scanDir) {
     const pkgPath = path.join(scanDir, entry.name, 'package.json');
     if (!fs.existsSync(pkgPath)) continue;
     let pkg;
-    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')); } catch { continue; }
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    } catch {
+      continue;
+    }
     if (!pkg.astryx || !pkg.astryx.docs) continue;
     const pkgDir = path.join(scanDir, entry.name);
     const docsDir = path.resolve(pkgDir, pkg.astryx.docs);
@@ -36,9 +40,18 @@ export function scanDirectory(scanDir) {
   return packages;
 }
 
-export function scanAllPackages(packageDirs) {
+export function scanAllPackages(packageDirs, explicitPackages = []) {
   const all = [];
   const seen = new Set();
+
+  for (const pkg of explicitPackages) {
+    if (!pkg || seen.has(pkg.name)) continue;
+    const components = discoverDocComponents(pkg.docsDir);
+    if (components.length === 0) continue;
+    seen.add(pkg.name);
+    all.push({...pkg, components});
+  }
+
   for (const dir of packageDirs) {
     for (const pkg of scanDirectory(dir)) {
       if (seen.has(pkg.name)) continue;
@@ -54,12 +67,17 @@ function discoverDocComponents(docsDir) {
   const components = [];
   function walk(dir) {
     let entries;
-    try { entries = fs.readdirSync(dir, {withFileTypes: true}); } catch { return; }
+    try {
+      entries = fs.readdirSync(dir, {withFileTypes: true});
+    } catch {
+      return;
+    }
     for (const entry of entries) {
       if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
-      else if (entry.name.endsWith('.doc.mjs')) components.push(entry.name.replace('.doc.mjs', ''));
+      else if (entry.name.endsWith('.doc.mjs'))
+        components.push(entry.name.replace('.doc.mjs', ''));
     }
   }
   walk(docsDir);
@@ -81,12 +99,18 @@ function findDocFile(docsDir, name) {
   const target = name + '.doc.mjs';
   function walk(dir) {
     let entries;
-    try { entries = fs.readdirSync(dir, {withFileTypes: true}); } catch { return null; }
+    try {
+      entries = fs.readdirSync(dir, {withFileTypes: true});
+    } catch {
+      return null;
+    }
     for (const entry of entries) {
       if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
       const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) { const f = walk(full); if (f) return f; }
-      else if (entry.name === target) return full;
+      if (entry.isDirectory()) {
+        const f = walk(full);
+        if (f) return f;
+      } else if (entry.name === target) return full;
     }
     return null;
   }

package/src/lib/string-utils.mjs

@@ -4,20 +4,11 @@
  * @file String utilities — fuzzy matching and semantic search for component names
  */
 
-export function levenshteinDistance(a, b) {
-  const m = a.length, n = b.length;
-  const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
-  for (let i = 0; i <= m; i++) dp[i][0] = i;
-  for (let j = 0; j <= n; j++) dp[0][j] = j;
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      dp[i][j] = a[i-1] === b[j-1]
-        ? dp[i-1][j-1]
-        : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
-    }
-  }
-  return dp[m][n];
-}
+// levenshteinDistance lives in its own pure module so browser-bundled code
+// (the XLE/XLO language) can use it without this file's dynamic node:fs/path
+// imports landing in the webpack graph. Re-exported for existing consumers.
+import {levenshteinDistance} from './levenshtein.mjs';
+export {levenshteinDistance} from './levenshtein.mjs';
 
 /**
  * Find the closest component names to a given (possibly misspelled) name.

package/src/lib/xle/browser.d.ts

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Type surface for `@astryxdesign/cli/xle` — the browser-safe layout language. */
+
+export interface XLEIssue {
+  message: string;
+  line?: number;
+  col?: number;
+  formatted: string;
+  suggestions?: string[];
+  kind?: string;
+}
+
+export interface SerializedRegistry {
+  components: Array<{
+    name: string;
+    exportName: string;
+    dirName: string;
+    importPath: string;
+    undocumented?: boolean;
+    props: Array<Record<string, unknown>>;
+  }>;
+  aliases: Array<[string, string]>;
+  componentNames: string[];
+}
+
+export interface XLEBlock {
+  dirName: string;
+  description?: string;
+  category?: string;
+}
+
+export interface CheckOptions {
+  blocks?: XLEBlock[];
+  form?: 'auto' | 'compact' | 'outline';
+  loose?: boolean;
+}
+
+export interface CheckResult {
+  ok: boolean;
+  valid?: boolean;
+  form?: 'compact' | 'outline';
+  errors: XLEIssue[];
+  warnings: string[];
+  compact?: string;
+  outline?: string;
+  parseError?: {message: string; line?: number; col?: number};
+}
+
+export interface ExpandOptions extends CheckOptions {
+  name?: string;
+}
+
+export type ExpandResult =
+  | {ok: false; errors: XLEIssue[]}
+  | {
+      ok: true;
+      form: 'compact' | 'outline';
+      code: string;
+      componentsUsed: string[];
+      states: number;
+      todos: string[];
+      warnings: string[];
+    };
+
+export function checkExpression(
+  expression: string,
+  registry: SerializedRegistry | object,
+  opts?: CheckOptions,
+): CheckResult;
+
+export function expandExpression(
+  expression: string,
+  registry: SerializedRegistry | object,
+  opts?: ExpandOptions,
+): ExpandResult;
+
+export function hydrateRegistry(json: SerializedRegistry): object;
+export function serializeRegistry(registry: object): SerializedRegistry;
+export function parse(source: string, opts?: {form?: string}): unknown;
+export function detectForm(source: string): 'compact' | 'outline';
+export function validate(
+  doc: unknown,
+  registry: object,
+  blocks?: XLEBlock[],
+  opts?: {loose?: boolean},
+): {errors: XLEIssue[]; warnings: XLEIssue[]};
+export function expand(
+  doc: unknown,
+  registry: object,
+  opts?: {componentName?: string},
+): {code: string; componentsUsed: string[]; states: number; todos: string[]};
+export function toCompact(doc: unknown): string;
+export function toOutline(doc: unknown): string;
+export const ALIAS_TABLE: Record<string, string>;
+export const SPACING_STEPS: number[];
+export class XLEParseError extends Error {
+  line: number;
+  col: number;
+}

package/src/lib/xle/browser.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file XLE/XLO browser barrel — the layout language without Node deps.
+ *
+ * The CLI builds its registry by reading .doc.mjs from disk (registry.mjs,
+ * Node-only). The browser playground instead receives a *serialized*
+ * registry (built at deploy time) and hydrates it here, then runs the same
+ * pure parse → validate → expand → print pipeline. Importing this module
+ * never pulls in node:fs, so it bundles cleanly for the web.
+ *
+ * @input  expression string + a serialized-or-hydrated registry (+ blocks)
+ * @output checkExpression / expandExpression + the raw pipeline pieces
+ * @position lib/xle — exported as `@astryxdesign/cli/xle`
+ */
+
+import {parse, detectForm, XLEParseError} from './parse.mjs';
+import {validate} from './validate.mjs';
+import {expand} from './expand.mjs';
+import {toCompact, toOutline} from './print.mjs';
+import {hydrateRegistry} from './registry-core.mjs';
+
+export {parse, detectForm, XLEParseError, validate, expand, toCompact, toOutline};
+export {hydrateRegistry, serializeRegistry, ALIAS_TABLE, resolveComponent, SPACING_STEPS} from './registry-core.mjs';
+
+/** Accept either a hydrated registry (Map fields) or serialized JSON. */
+function asRegistry(registry) {
+  return registry && registry.components instanceof Map ? registry : hydrateRegistry(registry);
+}
+
+function formatIssue(issue) {
+  const where = issue.line != null ? `line ${issue.line}: ` : '';
+  return `${where}${issue.message}`;
+}
+
+/**
+ * Validate an expression and return both canonical surfaces — the browser
+ * twin of `layout check`. Never throws on invalid input; returns the errors.
+ *
+ * @param {string} expression
+ * @param {object} registry - serialized or hydrated
+ * @param {object} [opts]
+ * @param {Array} [opts.blocks] - block list for {hint} resolution (default [])
+ * @param {'compact'|'outline'|'auto'} [opts.form]
+ * @param {boolean} [opts.loose]
+ * @returns {{ok: boolean, valid?: boolean, form?: string, errors: Array, warnings: string[], compact?: string, outline?: string, parseError?: object}}
+ */
+export function checkExpression(expression, registry, opts = {}) {
+  const {blocks = [], form = 'auto', loose = false} = opts;
+  let doc;
+  try {
+    doc = parse(expression, {form});
+  } catch (e) {
+    if (e instanceof XLEParseError) {
+      return {
+        ok: false,
+        valid: false,
+        errors: [{message: e.message, line: e.line, col: e.col, formatted: formatIssue(e), kind: 'parse'}],
+        warnings: [],
+        parseError: {message: e.message, line: e.line, col: e.col},
+      };
+    }
+    throw e;
+  }
+  const {errors, warnings} = validate(doc, asRegistry(registry), blocks, {loose});
+  return {
+    ok: true,
+    valid: errors.length === 0,
+    form: doc.form,
+    errors: errors.map(e => ({...e, formatted: formatIssue(e)})),
+    warnings: warnings.map(formatIssue),
+    compact: toCompact(doc),
+    outline: toOutline(doc),
+  };
+}
+
+/**
+ * Validate + expand to TSX — the browser twin of `layout expand`.
+ * Returns either {code, ...} or {errors} (never writes files).
+ *
+ * @param {string} expression
+ * @param {object} registry
+ * @param {object} [opts]
+ * @param {Array} [opts.blocks]
+ * @param {'compact'|'outline'|'auto'} [opts.form]
+ * @param {boolean} [opts.loose]
+ * @param {string} [opts.name] - generated component name (PascalCase)
+ * @param {Map} [opts.blockModules] - prepared block sources/imports for splicing;
+ *   omit in the browser (hints stay as TODO markers without sources)
+ */
+export function expandExpression(expression, registry, opts = {}) {
+  const {blocks = [], form = 'auto', loose = false, name = 'GeneratedLayout', blockModules} = opts;
+  const reg = asRegistry(registry);
+  let doc;
+  try {
+    doc = parse(expression, {form});
+  } catch (e) {
+    if (e instanceof XLEParseError) {
+      return {ok: false, errors: [{message: e.message, line: e.line, col: e.col, formatted: formatIssue(e), kind: 'parse'}]};
+    }
+    throw e;
+  }
+  const {errors, warnings} = validate(doc, reg, blocks, {loose});
+  if (errors.length > 0) {
+    return {ok: false, errors: errors.map(e => ({...e, formatted: formatIssue(e)}))};
+  }
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) {
+    return {ok: false, errors: [{message: `Component name must be PascalCase, got '${name}'`, formatted: `Component name must be PascalCase, got '${name}'`}]};
+  }
+  const result = expand(doc, reg, {componentName: name, blockModules});
+  return {
+    ok: true,
+    form: form === 'auto' ? detectForm(expression) : form,
+    code: result.code,
+    componentsUsed: result.componentsUsed,
+    states: result.states,
+    todos: result.todos,
+    warnings: warnings.map(formatIssue),
+  };
+}