@astryxdesign/cli 0.1.2 → 0.1.3

package/src/commands/validate-integration.mjs

@@ -0,0 +1,110 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx validate-integration` command — validate ONE integration
+ * package's manifest and contributions and report findings using the
+ * AstryxIntegrationIssue model.
+ *
+ *   astryx validate-integration            validate the local package (cwd)
+ *   astryx validate-integration <pkg>      validate an installed package
+ *
+ * Exit code is the contract: 0 when there are no severity:'error' issues
+ * (warnings are fine), 1 when any error issue is present — so it works as a CI
+ * gate. The no-arg + no-local-manifest case prints guidance and exits 0 (not
+ * an integration package is not a failure).
+ */
+
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {
+  validateLocalIntegration,
+  validateInstalledIntegration,
+  summarizeIssues,
+} from '../api/validate-integration.mjs';
+
+/**
+ * Render a validation result for humans.
+ * @param {import('../api/validate-integration.mjs').ValidateResult} result
+ */
+function printHuman(result) {
+  const label =
+    result.version != null
+      ? `${result.name}@${result.version}`
+      : result.name;
+  humanLog(`Validating integration: ${label}`);
+
+  if (result.issues.length === 0) {
+    humanLog('\n\u2713 No issues found.');
+    return;
+  }
+
+  humanLog('');
+  for (const issue of result.issues) {
+    humanLog(`  ${issue.severity} ${issue.code}: ${issue.message}`);
+  }
+
+  const {errors, warnings} = summarizeIssues(result.issues);
+  humanLog(
+    `\n${result.issues.length} issue(s): ${errors} error(s), ${warnings} warning(s)`,
+  );
+}
+
+const NO_MANIFEST_GUIDANCE =
+  'No astryx.integration.* found next to package.json. ' +
+  'To validate an installed integration: astryx validate-integration <package>';
+
+/**
+ * Register the `astryx validate-integration` command.
+ * @param {import('commander').Command} program
+ */
+export function registerValidateIntegration(program) {
+  program
+    .command('validate-integration [package]')
+    .description(
+      'Validate an Astryx integration package (manifest + contributions)',
+    )
+    .addHelpText(
+      'after',
+      '\nWith no argument, validates the integration package rooted at the\n' +
+        'current directory. Pass a package name to validate an installed\n' +
+        'integration resolved from ./node_modules.\n\n' +
+        'Exit code:\n' +
+        '  0  no error issues (warnings are allowed) — safe as a CI gate\n' +
+        '  1  one or more error issues\n',
+    )
+    .action(async pkg => {
+      const json = program.opts().json || false;
+
+      const result = pkg
+        ? await validateInstalledIntegration(pkg)
+        : await validateLocalIntegration();
+
+      // No-arg + no local manifest: guidance, not an error.
+      if (!result.found) {
+        if (json) {
+          jsonOut('integration.validate', {
+            name: null,
+            version: null,
+            issues: [],
+          });
+        } else {
+          humanLog(NO_MANIFEST_GUIDANCE);
+        }
+        return;
+      }
+
+      if (json) {
+        jsonOut('integration.validate', {
+          name: result.name ?? null,
+          version: result.version ?? null,
+          issues: result.issues,
+        });
+      } else {
+        printHuman(result);
+      }
+
+      const {errors} = summarizeIssues(result.issues);
+      if (errors > 0) {
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/validate-integration.test.mjs

@@ -0,0 +1,124 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Command-level tests for `astryx validate-integration` — envelope shape
+ * and the no-manifest guidance path.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {Command} from 'commander';
+
+import {registerValidateIntegration} from './validate-integration.mjs';
+
+let tmpDir;
+let logCalls;
+let prevCwd;
+let prevExit;
+
+beforeEach(() => {
+  // Temp dir under the repo root so manifest/node_modules paths are within
+  // Vite's allowed fs roots.
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-validate-cmd-'));
+  logCalls = [];
+  vi.spyOn(console, 'log').mockImplementation((...args) => {
+    logCalls.push(args.join(' '));
+  });
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  prevCwd = process.cwd();
+  prevExit = process.exitCode;
+  process.exitCode = undefined;
+});
+
+afterEach(() => {
+  process.chdir(prevCwd);
+  process.exitCode = prevExit;
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  vi.restoreAllMocks();
+});
+
+function createProgram() {
+  const program = new Command();
+  program.exitOverride();
+  program.option('--json', 'Output as typed JSON');
+  registerValidateIntegration(program);
+  return program;
+}
+
+describe('validate-integration — command', () => {
+  it('--json emits an integration.validate envelope for a valid package', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    process.chdir(tmpDir);
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', '--json', 'validate-integration']);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.type).toBe('integration.validate');
+    expect(parsed.data.name).toBe('@acme/widgets');
+    expect(parsed.data.version).toBe('1.2.3');
+    expect(Array.isArray(parsed.data.issues)).toBe(true);
+    expect(parsed.data.issues).toHaveLength(0);
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('--json envelope carries issues and sets exit 1 on errors', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/bad', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default { templates: "./gone" };\n',
+    );
+    process.chdir(tmpDir);
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', '--json', 'validate-integration']);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.type).toBe('integration.validate');
+    expect(parsed.data.issues.some(i => i.code === 'missing_root')).toBe(true);
+    expect(process.exitCode).toBe(1);
+  });
+
+  it('no-arg + no manifest prints guidance and stays exit 0', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'plain'}),
+    );
+    process.chdir(tmpDir);
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'validate-integration']);
+
+    const out = logCalls.join('\n');
+    expect(out).toContain('No astryx.integration.* found next to package.json');
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('--json with no manifest yields a null-identity envelope', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'plain'}),
+    );
+    process.chdir(tmpDir);
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', '--json', 'validate-integration']);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.type).toBe('integration.validate');
+    expect(parsed.data.name).toBeNull();
+    expect(parsed.data.issues).toEqual([]);
+  });
+});

package/src/config.mjs

@@ -1,31 +1,18 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {validateConfig, validateIntegration} from './lib/config-schema.mjs';
-
 /**
- * Type-preserving helpers for Astryx config and integration manifests.
+ * Type-preserving helper for the Astryx config file.
+ *
+ * This is an intentionally tiny runtime identity function: it returns its
+ * argument unchanged. Its value is the exported TypeScript surface from
+ * `@astryxdesign/cli/config`, so config files get editor/type feedback without
+ * coupling to CLI internals. Validation is NOT performed here — it happens at
+ * the load boundary (see `loadModuleWithSchema` + `AstryxConfigSchema`).
  *
- * 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

@@ -1,24 +1,100 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, expect, it} from 'vitest';
-import {createConfig, createIntegration} from './config.mjs';
+import {createConfig} from './config.mjs';
+import {createIntegration} from './integration.mjs';
+import {
+  AstryxConfigSchema,
+  AstryxIntegrationSchema,
+} from './lib/config-schema.mjs';
 
-describe('config helpers', () => {
-  it('return config and integration objects unchanged', () => {
+// createConfig/createIntegration are now pure typed-identity helpers: they
+// return their argument unchanged and perform NO runtime validation. Validation
+// happens at the LOAD boundary (loadModuleWithSchema against the schemas below),
+// so the rejection cases that used to assert factory throws now assert the
+// schema rejects the same shapes.
+
+describe('createConfig (typed identity)', () => {
+  it('returns the config unchanged', () => {
     const config = {integrations: ['@acme/widgets']};
-    const integration = {name: '@acme/widgets', docs: './docs'};
     expect(createConfig(config)).toBe(config);
-    expect(createIntegration(integration)).toBe(integration);
+    expect(createConfig({})).toEqual({});
+  });
+
+  it('does NOT validate — returns invalid shapes unchanged', () => {
+    const bogus = {packages: ['./libs']};
+    expect(createConfig(bogus)).toBe(bogus);
+    const badIntegrations = {integrations: '@acme/widgets'};
+    expect(createConfig(badIntegrations)).toBe(badIntegrations);
+  });
+});
+
+describe('AstryxConfigSchema (load-boundary validation)', () => {
+  it('accepts a valid minimal config', () => {
+    expect(AstryxConfigSchema.parse({})).toEqual({});
+    expect(
+      AstryxConfigSchema.parse({integrations: ['@acme/widgets']}),
+    ).toEqual({integrations: ['@acme/widgets']});
   });
 
-  it('validates config and integration shapes', () => {
-    expect(() => createConfig({integrations: [42]})).toThrow(/integrations/);
-    expect(() => createIntegration({docs: './docs'})).toThrow(/name/);
+  it('accepts hooks.postCodemod with a buildCommand function', () => {
+    const config = {
+      hooks: {postCodemod: [{name: 'format', buildCommand: () => null}]},
+    };
+    expect(() => AstryxConfigSchema.parse(config)).not.toThrow();
+  });
+
+  it('rejects unknown keys (strict)', () => {
+    expect(() => AstryxConfigSchema.parse({packages: ['./libs']})).toThrow(
+      /packages|Unrecognized/,
+    );
+  });
+
+  it('rejects a non-array integrations field', () => {
     expect(() =>
-      createIntegration({
-        name: '@acme/widgets',
-        postCodemod: [{name: 'empty'}],
-      }),
-    ).toThrow(/postCodemod/);
+      AstryxConfigSchema.parse({integrations: '@acme/widgets'}),
+    ).toThrow();
+  });
+
+  it('rejects a non-URL issuesUrl', () => {
+    expect(() => AstryxConfigSchema.parse({issuesUrl: 'not-a-url'})).toThrow();
+  });
+
+  it('rejects a postCodemod hook without buildCommand', () => {
+    expect(() =>
+      AstryxConfigSchema.parse({hooks: {postCodemod: [{name: 'empty'}]}}),
+    ).toThrow();
+  });
+});
+
+describe('createIntegration (typed identity)', () => {
+  it('returns the integration unchanged', () => {
+    const integration = {components: './src'};
+    expect(createIntegration(integration)).toBe(integration);
+    expect(createIntegration({})).toEqual({});
+  });
+
+  it('does NOT validate — returns invalid shapes unchanged', () => {
+    const bogus = {name: '@acme/widgets'};
+    expect(createIntegration(bogus)).toBe(bogus);
+  });
+});
+
+describe('AstryxIntegrationSchema (load-boundary validation)', () => {
+  it('accepts a valid minimal integration', () => {
+    expect(AstryxIntegrationSchema.parse({components: './src'})).toEqual({
+      components: './src',
+    });
+    expect(AstryxIntegrationSchema.parse({})).toEqual({});
+  });
+
+  it('rejects unknown keys (strict)', () => {
+    expect(() => AstryxIntegrationSchema.parse({name: '@acme/widgets'})).toThrow(
+      /name|Unrecognized/,
+    );
+  });
+
+  it('rejects a non-URL issuesUrl', () => {
+    expect(() => AstryxIntegrationSchema.parse({issuesUrl: 'nope'})).toThrow();
   });
 });

package/src/index.mjs

@@ -61,10 +61,10 @@ export const JSON_SUPPORTED = new Set([
   'theme build',
   'theme list',
   'theme add',
-  'gap-report',
   'upgrade',
   'manifest',
   'doctor',
+  'validate-integration',
   'layout expand',
   'layout check',
   'layout grammar',
@@ -155,7 +155,7 @@ program
   });
 
 /**
- * Compute the fully qualified command name, e.g. "theme build" or "gap-report".
+ * Compute the fully qualified command name, e.g. "theme build" or "swizzle".
  * @param {import('commander').Command} actionCommand
  * @returns {string}
  */
@@ -245,11 +245,11 @@ const commands = [
   {name: 'init', path: './commands/init.mjs', register: 'registerInit'},
   {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
   {name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
+  {name: 'blog', path: './commands/blog.mjs', register: 'registerBlog'},
   {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'},
   {name: 'hook', path: './commands/hook/index.mjs', register: 'registerHook'},
@@ -257,6 +257,11 @@ const commands = [
   {name: 'search', path: './commands/search.mjs', register: 'registerSearch'},
   {name: 'build', path: './commands/build.mjs', register: 'registerBuild'},
   {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
+  {
+    name: 'validate-integration',
+    path: './commands/validate-integration.mjs',
+    register: 'registerValidateIntegration',
+  },
 ];
 
 for (const cmd of commands) {

package/src/integration.mjs

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Type-preserving helper for an Astryx integration manifest.
+ *
+ * This is an intentionally tiny runtime identity function: it returns its
+ * argument unchanged. Its value is the exported TypeScript surface from
+ * `@astryxdesign/cli/integration`, so manifests get editor/type feedback
+ * without coupling to CLI internals. Validation is NOT performed here — it
+ * happens at the load boundary (see `loadModuleWithSchema` +
+ * `AstryxIntegrationSchema`).
+ *
+ * @template {import('./types/integration').AstryxIntegration} T
+ * @param {T} integration
+ * @returns {T}
+ */
+export function createIntegration(integration) {
+  return integration;
+}

package/src/lib/component-discovery.mjs

@@ -9,6 +9,12 @@ import * as path from 'node:path';
 
 const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);
 
+/** The owner package name for built-in (core) components. */
+export const CORE_PACKAGE = '@astryxdesign/core';
+
+/** Conventional doc-file suffixes for integration components (same-stem). */
+const INTEGRATION_DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
+
 // Component source files are named `XDS{Name}.tsx` today. The XDS-prefix
 // migration (P2380608025, P4) renames them to the bare `{Name}.tsx` form, so
 // discovery must recognize BOTH. The `XDS` prefix has historically doubled as
@@ -475,6 +481,177 @@ export function findExternalComponentDoc(docsDir, name) {
   return scanDir(docsDir);
 }
 
+// ── Integration component discovery (ownership-aware) ────────────────
+//
+// Integration packages contribute a `components` root (resolved absolute path
+// in `loadedIntegrations`, see lib/integrations.mjs). Each component uses a
+// same-stem source/doc convention — e.g. `MetaAppShell.tsx` next to
+// `MetaAppShell.doc.{ts,mjs,js}`. The doc file is authoritative for discovery;
+// the sibling `.tsx` (if present) is the swizzleable source.
+//
+// Each discovered component is recorded with its OWNER package (the
+// integration's package name) and the owner's `issuesUrl` so downstream
+// commands — and the future integration-component swizzle — can disambiguate
+// by package and route source/issues correctly.
+
+/**
+ * Given an integration component doc path, return the sibling component source
+ * (`{Name}.tsx`) if one exists, else null.
+ *
+ * @param {string} docPath absolute path to a `{Name}.doc.{ts,mjs,js}` file
+ * @returns {string|null}
+ */
+function integrationSourceForDoc(docPath) {
+  const dir = path.dirname(docPath);
+  const base = path.basename(docPath).replace(/\.doc\.(ts|mjs|js)$/, '');
+  const candidate = path.join(dir, `${base}.tsx`);
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+/**
+ * Discover ownership records for the components contributed by a single loaded
+ * integration. Scans the integration's resolved `components` dir for same-stem
+ * doc files and records each with owner package + issuesUrl + sourcePath.
+ *
+ * @param {{name: string, components?: string, issuesUrl?: string}} integration
+ *   a single entry from `loadedIntegrations` (lib/integrations.mjs)
+ * @returns {Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>}
+ */
+export function discoverIntegrationComponents(integration) {
+  const componentsDir = integration?.components;
+  if (!componentsDir || !fs.existsSync(componentsDir)) return [];
+
+  /** @type {Map<string, {name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>} */
+  const byName = new Map();
+
+  function scanDir(dirPath) {
+    const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        scanDir(fullPath);
+        continue;
+      }
+      const suffix = INTEGRATION_DOC_SUFFIXES.find(s => entry.name.endsWith(s));
+      if (!suffix) continue;
+      const name = entry.name.slice(0, -suffix.length);
+      const {group, hidden} = readDocMeta(fullPath);
+      if (hidden) continue;
+      // First doc wins per name (precedence matches INTEGRATION_DOC_SUFFIXES).
+      if (byName.has(name)) continue;
+      byName.set(name, {
+        name,
+        package: integration.name,
+        docPath: fullPath,
+        sourcePath: integrationSourceForDoc(fullPath),
+        issuesUrl: integration.issuesUrl,
+        group: group ?? null,
+      });
+    }
+  }
+
+  scanDir(componentsDir);
+  return [...byName.values()];
+}
+
+/**
+ * Find an integration component's doc file by name within a loaded
+ * integration's resolved `components` dir. Honors the same-stem convention
+ * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`.
+ *
+ * @param {{components?: string}} integration
+ * @param {string} name bare component name (no `XDS`/`Astryx` prefix)
+ * @returns {string|null}
+ */
+export function findIntegrationComponentDoc(integration, name) {
+  const componentsDir = integration?.components;
+  if (!componentsDir || !fs.existsSync(componentsDir)) return null;
+
+  function scanDir(dirPath) {
+    const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+    // Exact same-stem match (precedence order) first in this dir.
+    for (const suffix of INTEGRATION_DOC_SUFFIXES) {
+      const candidate = path.join(dirPath, `${name}${suffix}`);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+      if (entry.isDirectory()) {
+        const found = scanDir(path.join(dirPath, entry.name));
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  return scanDir(componentsDir);
+}
+
+/**
+ * Find an integration component's swizzleable source file (`{Name}.tsx`) by
+ * name within a loaded integration's resolved `components` dir. Returns null
+ * when the integration ships docs without source.
+ *
+ * @param {{components?: string}} integration
+ * @param {string} name bare component name
+ * @returns {string|null}
+ */
+export function findIntegrationComponentSource(integration, name) {
+  const docPath = findIntegrationComponentDoc(integration, name);
+  if (!docPath) return null;
+  return integrationSourceForDoc(docPath);
+}
+
+/**
+ * Build a flat list of ownership records for ALL discoverable components —
+ * core (built-in) plus every loaded integration. This is the authoritative
+ * source for package-aware listing and disambiguation.
+ *
+ * Core records carry `package: '@astryxdesign/core'`, `issuesUrl: undefined`
+ * (the default core issues URL), and the resolved `.tsx` source via
+ * findComponentSource(). Integration records carry their owner package name,
+ * the manifest `issuesUrl`, and the same-stem `.tsx` source if present.
+ *
+ * @param {string} coreDir
+ * @param {Array<{name: string, components?: string, issuesUrl?: string}>} [loadedIntegrations]
+ * @returns {Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>}
+ */
+export function discoverOwnedComponents(coreDir, loadedIntegrations = []) {
+  /** @type {Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>} */
+  const records = [];
+
+  // Core components — derive group from discoverComponents (grouped record).
+  const grouped = discoverComponents(coreDir);
+  /** @type {Map<string, string|null>} name → group */
+  const coreGroup = new Map();
+  for (const [key, members] of Object.entries(grouped)) {
+    const isUngrouped = members.length === 1 && members[0] === key;
+    for (const name of members) {
+      coreGroup.set(name, isUngrouped ? null : key);
+    }
+  }
+  for (const [name, group] of coreGroup) {
+    records.push({
+      name,
+      package: CORE_PACKAGE,
+      group,
+      docPath: findComponentReadme(coreDir, name),
+      sourcePath: findComponentSource(coreDir, name),
+      issuesUrl: undefined,
+    });
+  }
+
+  // Integration components.
+  for (const integration of loadedIntegrations) {
+    for (const rec of discoverIntegrationComponents(integration)) {
+      records.push(rec);
+    }
+  }
+
+  return records;
+}
+
 // ── Legacy markdown-parsing functions ────────────────────────────────
 // These are kept for backward compatibility with existing tests.
 // The CLI action handler uses the new format functions below instead.