@astryxdesign/cli 0.1.1-canary.a514b99 → 0.1.1-canary.ac73e47

package/src/config.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {validateConfig, validateIntegration} from './lib/config-schema.mjs';
+
+/**
+ * Type-preserving helpers for Astryx config and integration manifests.
+ *
+ * These are intentionally tiny runtime identity functions. Their value is the
+ * exported TypeScript surface from `@astryxdesign/cli/config`, so config files
+ * can get editor/type feedback without coupling to CLI internals.
+ */
+
+/**
+ * @template {import('./types/config').AstryxConfig} T
+ * @param {T} config
+ * @returns {T}
+ */
+export function createConfig(config) {
+  validateConfig(config);
+  return config;
+}
+
+/**
+ * @template {import('./types/config').AstryxIntegration} T
+ * @param {T} integration
+ * @returns {T}
+ */
+export function createIntegration(integration) {
+  validateIntegration(integration);
+  return integration;
+}

package/src/config.test.mjs

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {createConfig, createIntegration} from './config.mjs';
+
+describe('config helpers', () => {
+  it('return config and integration objects unchanged', () => {
+    const config = {integrations: ['@acme/widgets']};
+    const integration = {name: '@acme/widgets', docs: './docs'};
+    expect(createConfig(config)).toBe(config);
+    expect(createIntegration(integration)).toBe(integration);
+  });
+
+  it('validates config and integration shapes', () => {
+    expect(() => createConfig({integrations: [42]})).toThrow(/integrations/);
+    expect(() => createIntegration({docs: './docs'})).toThrow(/name/);
+    expect(() =>
+      createIntegration({
+        name: '@acme/widgets',
+        postCodemod: [{name: 'empty'}],
+      }),
+    ).toThrow(/postCodemod/);
+  });
+});

package/src/index.mjs

@@ -63,6 +63,9 @@ export const JSON_SUPPORTED = new Set([
   'upgrade',
   'manifest',
   'doctor',
+  'layout expand',
+  'layout check',
+  'layout grammar',
 ]);
 
 program
@@ -243,6 +246,7 @@ const commands = [
   {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
   // agent-docs folded into init — functions still importable from agent-docs.mjs
   {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
+  {name: 'layout', path: './commands/layout.mjs', register: 'registerLayout'},
   {name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},
   {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
   {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},

package/src/lib/config-schema.mjs

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Runtime schemas for Astryx config and integration manifests. */
+
+import {z} from 'zod';
+
+const Fn = z.custom(value => typeof value === 'function', {
+  message: 'Expected function',
+});
+
+const StringOrStringArray = z.union([z.string(), z.array(z.string())]);
+const GapReportSchema = z.union([
+  z.literal(false),
+  z.object({command: z.string()}).passthrough(),
+]);
+
+export const AstryxConfigSchema = z
+  .object({
+    packages: StringOrStringArray.optional(),
+    integrations: StringOrStringArray.optional(),
+    gapReport: GapReportSchema.optional(),
+    template: z
+      .object({
+        get: Fn.optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+export const AstryxIntegrationCodemodSchema = z
+  .object({
+    name: z.string(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    pr: z.string().optional(),
+    optional: z.boolean().optional(),
+    fileExtensions: z.array(z.string()).optional(),
+    transform: z.union([z.string(), Fn]),
+  })
+  .passthrough();
+
+export const AstryxPostCodemodHookSchema = z
+  .object({
+    name: z.string().optional(),
+    run: Fn.optional(),
+    command: Fn.optional(),
+  })
+  .passthrough()
+  .refine(value => value.run || value.command, {
+    message: 'postCodemod hook must define run() or command()',
+  });
+
+export const AstryxIntegrationSchema = z
+  .object({
+    name: z.string(),
+    version: z.string().optional(),
+    displayName: z.string().optional(),
+    description: z.string().optional(),
+    docs: z.string().optional(),
+    category: z.string().optional(),
+    blocks: z.string().optional(),
+    gapReport: GapReportSchema.optional(),
+    template: z
+      .object({
+        get: z.union([z.string(), Fn]).optional(),
+      })
+      .passthrough()
+      .optional(),
+    codemods: z.array(AstryxIntegrationCodemodSchema).optional(),
+    postCodemod: z.array(AstryxPostCodemodHookSchema).optional(),
+  })
+  .passthrough();
+
+/**
+ * @param {string} label
+ * @param {import('zod').ZodError} error
+ */
+function formatZodError(label, error) {
+  const issues = error.issues
+    .map(issue => {
+      const path = issue.path.length ? issue.path.join('.') : '(root)';
+      return `${path}: ${issue.message}`;
+    })
+    .join('; ');
+  return `${label} is invalid: ${issues}`;
+}
+
+/**
+ * @param {unknown} config
+ * @returns {import('../types/config').AstryxConfig}
+ */
+export function validateConfig(config) {
+  const result = AstryxConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new Error(
+      formatZodError('astryx.config.mjs default export', result.error),
+    );
+  }
+  return result.data;
+}
+
+/**
+ * @param {unknown} integration
+ * @param {string} [label]
+ * @returns {import('../types/config').AstryxIntegration}
+ */
+export function validateIntegration(
+  integration,
+  label = 'integration manifest',
+) {
+  const result = AstryxIntegrationSchema.safeParse(integration);
+  if (!result.success) {
+    throw new Error(formatZodError(label, result.error));
+  }
+  return result.data;
+}

package/src/lib/config.mjs

@@ -10,6 +10,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
+import {loadIntegrations} from './integrations.mjs';
+import {validateConfig} from './config-schema.mjs';
 
 const DEFAULTS = {
   packages: [],
@@ -40,18 +42,30 @@ export async function loadConfig(startDir = process.cwd()) {
   const configPath = findConfigPath(startDir);
   if (!configPath) return {...DEFAULTS};
 
+  let rawConfig;
   try {
     const mod = await import(pathToFileURL(configPath).href);
-    const config = mod.default || {};
-    return {
-      ...DEFAULTS,
-      ...config,
-      packages: normalizePackages(config.packages, path.dirname(configPath)),
-      integrations: normalizeIntegrations(config.integrations),
-    };
+    rawConfig = mod.default || {};
   } catch {
     return {...DEFAULTS};
   }
+
+  const config = validateConfig(rawConfig);
+  const configDir = path.dirname(configPath);
+  const integrationSpecs = normalizeIntegrations(config.integrations);
+  const loadedIntegrations = await loadIntegrations(integrationSpecs, {
+    cwd: configDir,
+  });
+  return {
+    ...DEFAULTS,
+    ...config,
+    packages: normalizePackages(config.packages, configDir),
+    integrations: integrationSpecs,
+    loadedIntegrations,
+    gapReport:
+      config.gapReport ?? firstDefined(loadedIntegrations, 'gapReport'),
+    template: mergeTemplateConfig(config.template, loadedIntegrations),
+  };
 }
 
 /**
@@ -84,3 +98,16 @@ function normalizeIntegrations(integrations) {
   const arr = Array.isArray(integrations) ? integrations : [integrations];
   return arr.filter(value => typeof value === 'string' && value !== '');
 }
+
+function firstDefined(integrations, key) {
+  for (const integration of integrations) {
+    if (integration[key] !== undefined) return integration[key];
+  }
+  return undefined;
+}
+
+function mergeTemplateConfig(template, integrations) {
+  if (template?.get) return template;
+  const integrationTemplate = firstDefined(integrations, 'template');
+  return integrationTemplate ?? template;
+}

package/src/lib/config.test.mjs

@@ -15,10 +15,25 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
+function installIntegrationPackage(dir, name = '@nest/xds-meta') {
+  const packageDir = path.join(dir, 'node_modules', ...name.split('/'));
+  fs.mkdirSync(packageDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({name, astryx: {integration: './astryx.integration.mjs'}}),
+  );
+  fs.writeFileSync(
+    path.join(packageDir, 'astryx.integration.mjs'),
+    `export default { name: '${name}' };
+`,
+  );
+}
+
 describe('loadConfig', () => {
   it('normalizes integrations from astryx.config.mjs', async () => {
     const dir = path.join(tmpDir, 'one');
     fs.mkdirSync(dir);
+    installIntegrationPackage(dir);
     fs.writeFileSync(
       path.join(dir, 'astryx.config.mjs'),
       `export default { integrations: '@nest/xds-meta' };\n`,
@@ -28,15 +43,49 @@ describe('loadConfig', () => {
     });
   });
 
-  it('normalizes integration arrays and filters non-strings', async () => {
+  it('rejects invalid integration package manifests', async () => {
+    const dir = path.join(tmpDir, 'bad');
+    fs.mkdirSync(dir);
+    const packageDir = path.join(dir, 'node_modules', '@bad', 'widgets');
+    fs.mkdirSync(packageDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'astryx.config.mjs'),
+      `export default { integrations: '@bad/widgets' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(packageDir, 'package.json'),
+      JSON.stringify({
+        name: '@bad/widgets',
+        astryx: {integration: './astryx.integration.mjs'},
+      }),
+    );
+    fs.writeFileSync(
+      path.join(packageDir, 'astryx.integration.mjs'),
+      `export default { docs: './docs' };\n`,
+    );
+    await expect(loadConfig(dir)).rejects.toThrow(/name/);
+  });
+
+  it('normalizes integration arrays', async () => {
     const dir = path.join(tmpDir, 'two');
     fs.mkdirSync(dir);
+    installIntegrationPackage(dir);
     fs.writeFileSync(
       path.join(dir, 'astryx.config.mjs'),
-      `export default { integrations: ['@nest/xds-meta', '', 42] };\n`,
+      `export default { integrations: ['@nest/xds-meta', ''] };\n`,
     );
     await expect(loadConfig(dir)).resolves.toMatchObject({
       integrations: ['@nest/xds-meta'],
     });
   });
+
+  it('rejects invalid config shapes', async () => {
+    const dir = path.join(tmpDir, 'invalid');
+    fs.mkdirSync(dir);
+    fs.writeFileSync(
+      path.join(dir, 'astryx.config.mjs'),
+      `export default { integrations: [42] };\n`,
+    );
+    await expect(loadConfig(dir)).rejects.toThrow(/integrations/);
+  });
 });

package/src/lib/error-codes.mjs

@@ -75,6 +75,8 @@
  *   | 'ERR_DEP_MISSING'
  *   | 'ERR_GH_CLI'
  *   | 'ERR_GAP_REPORT_FAILED'
+ *   | 'ERR_LAYOUT_PARSE'
+ *   | 'ERR_LAYOUT_INVALID'
  * )} ErrorCode
  */
 
@@ -180,6 +182,12 @@ export const ERROR_CODES = Object.freeze({
   ERR_GH_CLI: 'ERR_GH_CLI',
   /** Filing a gap report failed at the command/integration boundary. */
   ERR_GAP_REPORT_FAILED: 'ERR_GAP_REPORT_FAILED',
+
+  // ── Layout expressions (XLE/XLO) ─────────────────────────────────
+  /** A layout expression failed to parse (syntax error, with line/col). */
+  ERR_LAYOUT_PARSE: 'ERR_LAYOUT_PARSE',
+  /** A layout expression parsed but failed validation (unknown component/prop/enum/block). */
+  ERR_LAYOUT_INVALID: 'ERR_LAYOUT_INVALID',
 });
 
 /**

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];
+}