@astryxdesign/cli 0.1.1 → 0.1.2-canary.043f3fd

package/src/lib/integrations.test.mjs

@@ -0,0 +1,135 @@
+// 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 {Project} from './project.mjs';
+import {loadIntegrations} from './integrations.mjs';
+import {discover} from '../api/discover.mjs';
+
+let tmpDir;
+let originalCwd;
+
+function writeManifestPackage(dir, {basename = 'astryx.integration.mjs', body}) {
+  const pkgDir = path.join(dir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(pkgDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({
+      name: '@acme/widgets',
+      version: '1.2.3',
+    }),
+  );
+  fs.writeFileSync(path.join(pkgDir, basename), body);
+  return pkgDir;
+}
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-integration-test-'),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    `export default { integrations: ['@acme/widgets'] };\n`,
+  );
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('configured integrations', () => {
+  it('resolves identity from package.json and contribution roots to absolute paths', async () => {
+    const pkgDir = writeManifestPackage(tmpDir, {
+      body: `export default {
+        components: './docs',
+        templates: './blocks',
+        codemods: './codemods',
+        issuesUrl: 'https://example.com/issues',
+      };\n`,
+    });
+    fs.mkdirSync(path.join(pkgDir, 'docs'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'docs', 'Widget.doc.mjs'),
+      `export const doc = {
+        name: 'Widget',
+        usage: {description: 'Acme widget'},
+        props: [],
+      };\n`,
+    );
+
+    const project = await Project.load(tmpDir);
+    expect(project.integrations).toEqual(['@acme/widgets']);
+    const loaded = project.loadedIntegrations[0];
+    // Identity comes from package.json, not the manifest.
+    expect(loaded.name).toBe('@acme/widgets');
+    expect(loaded.version).toBe('1.2.3');
+    expect(loaded.components).toBe(path.join(pkgDir, 'docs'));
+    expect(loaded.templates).toBe(path.join(pkgDir, 'blocks'));
+    expect(loaded.codemods).toBe(path.join(pkgDir, 'codemods'));
+    expect(loaded.issuesUrl).toBe('https://example.com/issues');
+  });
+
+  it('makes integration components discoverable', async () => {
+    const pkgDir = writeManifestPackage(tmpDir, {
+      body: `export default { components: './docs' };\n`,
+    });
+    fs.mkdirSync(path.join(pkgDir, 'docs'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'docs', 'Widget.doc.mjs'),
+      `export const doc = {
+        name: 'Widget',
+        usage: {description: 'Acme widget'},
+        props: [],
+      };\n`,
+    );
+
+    const result = await discover(undefined, {});
+    expect(result.type).toBe('discover.list');
+    expect(result.data).toEqual([
+      expect.objectContaining({
+        name: '@acme/widgets',
+        category: '@acme/widgets',
+        components: ['Widget'],
+      }),
+    ]);
+  });
+
+  it('errors when the package has no conventional root manifest', async () => {
+    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+    fs.mkdirSync(pkgDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets'}),
+    );
+    await expect(loadIntegrations(['@acme/widgets'], {cwd: tmpDir})).rejects.toThrow(
+      /no conventional root manifest/,
+    );
+  });
+
+  it('errors when the package has multiple root manifests', async () => {
+    const pkgDir = writeManifestPackage(tmpDir, {
+      body: `export default {};\n`,
+    });
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.js'),
+      `module.exports = {};\n`,
+    );
+    await expect(loadIntegrations(['@acme/widgets'], {cwd: tmpDir})).rejects.toThrow(
+      /multiple root manifests/,
+    );
+  });
+
+  it('errors when the package is not installed', async () => {
+    await expect(loadIntegrations(['@acme/missing'], {cwd: tmpDir})).rejects.toThrow(
+      /Could not find installed integration package/,
+    );
+  });
+});

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

@@ -56,14 +56,18 @@ export const RESPONSE_TYPES = {
     'template.show',
     'template.skeleton',
     'template.copy',
-    'template.get',
   ],
   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'],
+  'validate-integration': ['integration.validate'],
+  'layout expand': ['layout.expand'],
+  'layout check': ['layout.check'],
+  'layout grammar': ['layout.grammar'],
 };
 
 /**
@@ -79,10 +83,19 @@ 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'],
+  'validate-integration': [
+    'astryx validate-integration',
+    'astryx validate-integration @acme/widgets --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/module-loader.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared module-loading + conventional-file-discovery primitives.
+ *
+ * Both config loading and integration loading need to (a) import a
+ * user-authored module (`.ts` via jiti, `.mjs`/`.js` via native dynamic
+ * import) and (b) find conventional files by basename in a fixed
+ * load-precedence order. These helpers centralize that so the two callers stay
+ * in lockstep.
+ *
+ * `loadModuleWithSchema` builds on these primitives to provide the single
+ * load/validation boundary shared by config, integration, codemod, and
+ * template discovery: import the module, take its default export, and validate
+ * it against the expected zod schema.
+ */
+
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import * as fs from 'node:fs';
+import {createJiti} from 'jiti';
+import {formatZodError} from './config-schema.mjs';
+
+let jitiInstance;
+function getJiti() {
+  if (!jitiInstance) {
+    jitiInstance = createJiti(import.meta.url);
+  }
+  return jitiInstance;
+}
+
+/**
+ * Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` via
+ * native dynamic import (file:// URL). Returns the full module namespace.
+ * @param {string} file absolute path
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function importUserModule(file) {
+  if (file.endsWith('.ts')) {
+    return await getJiti().import(file);
+  }
+  return await import(pathToFileURL(file).href);
+}
+
+/**
+ * Return the conventional files (by basename, in the given precedence order)
+ * that exist directly in `dir`, as absolute paths. Never throws.
+ * @param {string} dir
+ * @param {string[]} basenames precedence-ordered
+ * @returns {string[]} absolute paths of present files, in basenames order
+ */
+export function findPresentFiles(dir, basenames) {
+  return basenames
+    .filter(name => fs.existsSync(path.join(dir, name)))
+    .map(name => path.join(dir, name));
+}
+
+/**
+ * Import a user-authored module, take its default export, and validate it
+ * against a zod schema. This is the single load/validation boundary for all
+ * user-authored modules (config, integration, codemod, template): execute the
+ * module, take the default export, validate it against the expected schema.
+ * Throws a clear, readable error if the default export is missing or fails
+ * validation.
+ *
+ * @template {import('zod').ZodType} S
+ * @param {string} file absolute path
+ * @param {S} schema
+ * @param {{label?: string}} [opts] label used in error messages
+ * @returns {Promise<import('zod').infer<S>>} parsed + typed value
+ */
+export async function loadModuleWithSchema(file, schema, {label} = {}) {
+  const mod = await importUserModule(file);
+  const exported = mod?.default;
+  const result = schema.safeParse(exported);
+  if (!result.success) {
+    throw new Error(formatZodError(label ?? file, result.error));
+  }
+  return result.data;
+}

package/src/lib/module-loader.test.mjs

@@ -0,0 +1,106 @@
+// 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 {z} from 'zod';
+import {
+  findPresentFiles,
+  importUserModule,
+  loadModuleWithSchema,
+} from './module-loader.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-module-loader-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('findPresentFiles', () => {
+  const basenames = ['a.ts', 'b.mjs', 'c.js'];
+
+  it('returns [] when none of the basenames are present', () => {
+    expect(findPresentFiles(tmpDir, basenames)).toEqual([]);
+  });
+
+  it('returns only the present files, in basenames precedence order', () => {
+    // Create out of order to prove the result follows `basenames`, not disk order.
+    fs.writeFileSync(path.join(tmpDir, 'c.js'), '');
+    fs.writeFileSync(path.join(tmpDir, 'a.ts'), '');
+    const present = findPresentFiles(tmpDir, basenames);
+    expect(present.map(p => path.basename(p))).toEqual(['a.ts', 'c.js']);
+  });
+
+  it('returns absolute paths joined to the given directory', () => {
+    fs.writeFileSync(path.join(tmpDir, 'b.mjs'), '');
+    const present = findPresentFiles(tmpDir, basenames);
+    expect(present).toEqual([path.join(tmpDir, 'b.mjs')]);
+    expect(path.isAbsolute(present[0])).toBe(true);
+  });
+
+  it('does not match files in nested subdirectories', () => {
+    const nested = path.join(tmpDir, 'nested');
+    fs.mkdirSync(nested);
+    fs.writeFileSync(path.join(nested, 'a.ts'), '');
+    expect(findPresentFiles(tmpDir, basenames)).toEqual([]);
+  });
+});
+
+describe('importUserModule', () => {
+  it('imports a .mjs file and returns its module namespace', async () => {
+    const file = path.join(tmpDir, 'mod.mjs');
+    fs.writeFileSync(
+      file,
+      `export default {answer: 42};\nexport const named = 'hi';\n`,
+    );
+    const mod = await importUserModule(file);
+    expect(mod.default).toEqual({answer: 42});
+    expect(mod.named).toBe('hi');
+  });
+});
+
+describe('loadModuleWithSchema', () => {
+  // Temp module files live under a repo-local dir (not /tmp): Vite's dynamic
+  // import blocks /tmp, so we mirror the existing repo-local temp pattern.
+  const schema = z
+    .object({
+      name: z.string(),
+      count: z.number().optional(),
+    })
+    .strict();
+
+  it('returns the parsed default export when it satisfies the schema', async () => {
+    const file = path.join(tmpDir, 'valid.mjs');
+    fs.writeFileSync(file, `export default {name: 'ok', count: 3};\n`);
+    const value = await loadModuleWithSchema(file, schema, {label: 'thing'});
+    expect(value).toEqual({name: 'ok', count: 3});
+  });
+
+  it('throws a readable error when there is no default export', async () => {
+    const file = path.join(tmpDir, 'no-default.mjs');
+    fs.writeFileSync(file, `export const named = {name: 'x'};\n`);
+    await expect(
+      loadModuleWithSchema(file, schema, {label: 'thing'}),
+    ).rejects.toThrow(/thing is invalid/i);
+  });
+
+  it('throws a readable error when the default export fails the schema', async () => {
+    const file = path.join(tmpDir, 'invalid.mjs');
+    fs.writeFileSync(file, `export default {count: 'not-a-number'};\n`);
+    await expect(
+      loadModuleWithSchema(file, schema, {label: 'thing'}),
+    ).rejects.toThrow(/thing is invalid:.*name/i);
+  });
+
+  it('falls back to the file path in the message when no label is given', async () => {
+    const file = path.join(tmpDir, 'unlabeled.mjs');
+    fs.writeFileSync(file, `export default {bogus: true};\n`);
+    await expect(loadModuleWithSchema(file, schema)).rejects.toThrow(
+      new RegExp(`${path.basename(file)} is invalid`),
+    );
+  });
+});

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