@astryxdesign/cli 0.1.2-canary.b712653 → 0.1.2-canary.bbf77ea

package/src/commands/component/index.mjs

@@ -24,6 +24,8 @@ import {cliError} from '../../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../lib/error-codes.mjs';
 import {component as componentApi} from '../../api/component.mjs';
 import {findRelatedBlocks} from '../../api/template.mjs';
+import {Project} from '../../lib/project.mjs';
+import {warnOnIntegrationIssues} from '../../lib/integration-warnings.mjs';
 
 export function registerComponent(program) {
   program
@@ -55,6 +57,16 @@ export function registerComponent(program) {
         return;
       }
 
+      // Non-blocking nudge: if any configured integration has validation
+      // issues, print one compact line to stderr pointing at
+      // validate-integration. Best-effort; suppressed in --json mode.
+      try {
+        const project = await Project.load(process.cwd());
+        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+      } catch {
+        // Never let the nudge break the command.
+      }
+
       let result;
       try {
         result = await componentApi(name, {
@@ -82,27 +94,49 @@ export function registerComponent(program) {
 
       switch (result.type) {
         case 'component.list': {
-          // --detail brief (default for list views) — names with import paths.
+          // --detail brief (default for list views). The API now returns
+          // package-qualified entries ({name, package}); the human view omits
+          // the core package label for readability but ALWAYS shows the package
+          // for integration components (and whenever names collide).
+          const CORE_PKG = '@astryxdesign/core';
+          // Names that appear under more than one package across the whole
+          // listing — these must always be package-qualified to disambiguate.
+          const nameCounts = new Map();
+          for (const items of Object.values(result.data)) {
+            for (const item of items) {
+              const set = nameCounts.get(item.name) ?? new Set();
+              set.add(item.package);
+              nameCounts.set(item.name, set);
+            }
+          }
+          const isCollision = n => (nameCounts.get(n)?.size ?? 0) > 1;
+          const pkgSuffix = item => {
+            if (item.package !== CORE_PKG) return `  [${item.package}]`;
+            if (isCollision(item.name)) return `  [${item.package}]`;
+            return '';
+          };
+
           if (options.category) {
             const [cat, comps] = Object.entries(result.data)[0];
             humanLog(`\n${cat}:`);
-            for (const comp of comps) {
-              const importPath = resolveImportPath(coreDir, comp);
-              humanLog(`  ${comp}  ← ${importPath}`);
+            for (const item of comps) {
+              const importPath = resolveImportPath(coreDir, item.name);
+              humanLog(`  ${item.name}  ← ${importPath}${pkgSuffix(item)}`);
             }
             humanLog('');
           } else {
             humanLog('');
             for (const [key, comps] of Object.entries(result.data)) {
-              const isUngrouped = comps.length === 1 && comps[0] === key;
+              const isUngrouped = comps.length === 1 && comps[0]?.name === key;
               if (isUngrouped) {
-                const importPath = resolveImportPath(coreDir, key);
-                humanLog(`${key}  ← ${importPath}`);
+                const item = comps[0];
+                const importPath = resolveImportPath(coreDir, item.name);
+                humanLog(`${item.name}  ← ${importPath}${pkgSuffix(item)}`);
               } else {
                 humanLog(`${key} (group)`);
-                for (const comp of comps) {
-                  const importPath = resolveImportPath(coreDir, comp);
-                  humanLog(`  ${comp}  ← ${importPath}`);
+                for (const item of comps) {
+                  const importPath = resolveImportPath(coreDir, item.name);
+                  humanLog(`  ${item.name}  ← ${importPath}${pkgSuffix(item)}`);
                 }
               }
             }

package/src/commands/component-ownership.test.mjs

@@ -0,0 +1,227 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  discoverIntegrationComponents,
+  discoverOwnedComponents,
+  findIntegrationComponentDoc,
+  findIntegrationComponentSource,
+  CORE_PACKAGE,
+} from '../lib/component-discovery.mjs';
+
+// The api `component()` reads integrations via Project.load(). In the vitest
+// environment, Vite's `server.fs.allow` only permits loading modules from
+// under `node_modules`, so a real astryx.config.mjs at a tmp root cannot be
+// imported. We therefore mock Project.load to return a project whose
+// `loadedIntegrations` are resolved (exactly the shape lib/integrations.mjs
+// produces) while keeping the integration's `components` dir on disk under
+// node_modules so its `.doc.mjs` files load normally.
+const projectLoadMock = vi.fn();
+vi.mock('../lib/project.mjs', () => ({
+  Project: {load: (...args) => projectLoadMock(...args)},
+}));
+
+// Import the api AFTER the mock is registered.
+const {component} = await import('../api/component.mjs');
+
+let tmpDir;
+
+const INTEGRATION_NAME = '@test/meta';
+const INTEGRATION_ISSUES = 'https://example.com/meta/issues';
+
+/**
+ * Build a consumer fixture:
+ * - packages/core symlinked to the real @astryxdesign/core (loadDocs source)
+ * - node_modules/@test/meta with a `components` dir using the same-stem
+ *   source/doc convention (MetaAppShell.tsx + MetaAppShell.doc.mjs)
+ * Returns the absolute `components` dir so the Project.load mock can hand back a
+ * resolved integration entry.
+ */
+function createFixture({withSource = true, extraComponent = null} = {}) {
+  const realCoreDir = path.resolve(import.meta.dirname, '..', '..', '..', 'core');
+  const coreDir = path.join(tmpDir, 'packages', 'core');
+  fs.mkdirSync(path.dirname(coreDir), {recursive: true});
+  fs.symlinkSync(realCoreDir, coreDir);
+
+  const intDir = path.join(tmpDir, 'node_modules', '@test', 'meta');
+  const compDir = path.join(intDir, 'components');
+  fs.mkdirSync(compDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(intDir, 'package.json'),
+    JSON.stringify({name: INTEGRATION_NAME, version: '1.2.3'}),
+  );
+  fs.writeFileSync(
+    path.join(compDir, 'MetaAppShell.doc.mjs'),
+    `export const docs = {\n  name: 'MetaAppShell',\n  usage: { description: 'Meta-flavored app shell.' },\n  props: [{ name: 'title', type: 'string', description: 'Header title' }],\n};\n`,
+  );
+  if (withSource) {
+    fs.writeFileSync(
+      path.join(compDir, 'MetaAppShell.tsx'),
+      "'use client';\nexport function MetaAppShell() { return null; }\n",
+    );
+  }
+  if (extraComponent) {
+    fs.writeFileSync(
+      path.join(compDir, `${extraComponent}.doc.mjs`),
+      `export const docs = {\n  name: '${extraComponent}',\n  usage: { description: '${extraComponent} from meta.' },\n};\n`,
+    );
+    fs.writeFileSync(
+      path.join(compDir, `${extraComponent}.tsx`),
+      `export function ${extraComponent}() { return null; }\n`,
+    );
+  }
+
+  const integration = {
+    name: INTEGRATION_NAME,
+    version: '1.2.3',
+    components: compDir,
+    templates: undefined,
+    codemods: undefined,
+    issuesUrl: INTEGRATION_ISSUES,
+  };
+  projectLoadMock.mockResolvedValue({
+    integrations: [INTEGRATION_NAME],
+    loadedIntegrations: [integration],
+  });
+  return {coreDir, intDir, compDir, integration};
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-ownership-'));
+  projectLoadMock.mockReset();
+  // Default: no integrations (core only).
+  projectLoadMock.mockResolvedValue({integrations: [], loadedIntegrations: []});
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('discoverIntegrationComponents (ownership records)', () => {
+  it('records name, package, sourcePath, and issuesUrl for same-stem components', () => {
+    const {integration, compDir} = createFixture();
+    const records = discoverIntegrationComponents(integration);
+    expect(records).toHaveLength(1);
+    const rec = records[0];
+    expect(rec.name).toBe('MetaAppShell');
+    expect(rec.package).toBe(INTEGRATION_NAME);
+    expect(rec.issuesUrl).toBe(INTEGRATION_ISSUES);
+    expect(rec.sourcePath).toBe(path.join(compDir, 'MetaAppShell.tsx'));
+    expect(fs.existsSync(rec.sourcePath)).toBe(true);
+  });
+
+  it('records sourcePath: null when the integration ships docs without source', () => {
+    const {integration} = createFixture({withSource: false});
+    const [rec] = discoverIntegrationComponents(integration);
+    expect(rec.sourcePath).toBeNull();
+  });
+});
+
+describe('discoverOwnedComponents (core + integrations)', () => {
+  it('marks core components with the core package and integration components with their owner', () => {
+    const {coreDir, integration} = createFixture();
+    const records = discoverOwnedComponents(coreDir, [integration]);
+    const core = records.find(r => r.package === CORE_PACKAGE);
+    expect(core).toBeTruthy();
+    expect(core.issuesUrl).toBeUndefined();
+    const meta = records.find(r => r.name === 'MetaAppShell');
+    expect(meta.package).toBe(INTEGRATION_NAME);
+    expect(meta.issuesUrl).toBe(INTEGRATION_ISSUES);
+    expect(meta.sourcePath).toContain('MetaAppShell.tsx');
+  });
+});
+
+describe('findIntegrationComponentDoc / Source', () => {
+  it('finds doc + source by name', () => {
+    const {integration} = createFixture();
+    expect(findIntegrationComponentDoc(integration, 'MetaAppShell')).toContain('MetaAppShell.doc.mjs');
+    expect(findIntegrationComponentSource(integration, 'MetaAppShell')).toContain('MetaAppShell.tsx');
+  });
+
+  it('returns null source when none present', () => {
+    const {integration} = createFixture({withSource: false});
+    expect(findIntegrationComponentSource(integration, 'MetaAppShell')).toBeNull();
+  });
+});
+
+describe('component() — integration ownership via config', () => {
+  it('discovers a config integration component by package ownership (detail)', async () => {
+    createFixture();
+    const result = await component('MetaAppShell', {cwd: tmpDir});
+    expect(result.type).toBe('component.detail');
+    expect(result.data.name).toBe('MetaAppShell');
+    expect(result.data.package).toBe(INTEGRATION_NAME);
+    expect(result.data.sourceAvailable).toBe(true);
+    expect(result.data.import).toBe(`${INTEGRATION_NAME}/MetaAppShell`);
+  });
+
+  it('--package resolves the integration component', async () => {
+    createFixture();
+    const result = await component('MetaAppShell', {cwd: tmpDir, package: INTEGRATION_NAME});
+    expect(result.type).toBe('component.detail');
+    expect(result.data.package).toBe(INTEGRATION_NAME);
+  });
+
+  it('--source returns the integration source when available', async () => {
+    createFixture();
+    const result = await component('MetaAppShell', {cwd: tmpDir, source: true});
+    expect(result.type).toBe('component.detail.source');
+    expect(result.data.component).toBe('MetaAppShell');
+    expect(result.data.source).toContain('MetaAppShell');
+  });
+
+  it('--source throws ERR_NO_SOURCE when the integration ships no source', async () => {
+    createFixture({withSource: false});
+    await expect(
+      component('MetaAppShell', {cwd: tmpDir, source: true}),
+    ).rejects.toMatchObject({code: 'ERR_NO_SOURCE'});
+  });
+
+  it('errors with candidate packages when a name is ambiguous (core + integration)', async () => {
+    // 'AppShell' exists in core; add a same-named integration component.
+    createFixture({extraComponent: 'AppShell'});
+    let caught;
+    try {
+      await component('AppShell', {cwd: tmpDir});
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeTruthy();
+    expect(caught.code).toBe('ERR_UNKNOWN_COMPONENT');
+    const pkgs = (caught.suggestions ?? []).map(s => s.name);
+    expect(pkgs).toContain(CORE_PACKAGE);
+    expect(pkgs).toContain(INTEGRATION_NAME);
+  });
+
+  it('--package disambiguates an ambiguous name to core', async () => {
+    createFixture({extraComponent: 'AppShell'});
+    const result = await component('AppShell', {cwd: tmpDir, package: CORE_PACKAGE});
+    expect(result.type).toBe('component.detail');
+    expect(result.data.package).toBe(CORE_PACKAGE);
+  });
+
+  it('--package disambiguates an ambiguous name to the integration', async () => {
+    createFixture({extraComponent: 'AppShell'});
+    const result = await component('AppShell', {cwd: tmpDir, package: INTEGRATION_NAME});
+    expect(result.type).toBe('component.detail');
+    expect(result.data.package).toBe(INTEGRATION_NAME);
+  });
+
+  it('JSON list includes integration components as {name, package} objects', async () => {
+    createFixture();
+    const result = await component(undefined, {cwd: tmpDir, list: true});
+    expect(result.type).toBe('component.list');
+    const allEntries = Object.values(result.data).flat();
+    for (const entry of allEntries) {
+      expect(typeof entry.name).toBe('string');
+      expect(typeof entry.package).toBe('string');
+    }
+    const meta = allEntries.find(e => e.name === 'MetaAppShell');
+    expect(meta).toBeTruthy();
+    expect(meta.package).toBe(INTEGRATION_NAME);
+    expect(allEntries.some(e => e.package === CORE_PACKAGE)).toBe(true);
+  });
+});

package/src/commands/discover.mjs

@@ -10,7 +10,6 @@
  *   astryx discover searchterm                Search across all packages
  */
 
-import {loadConfig} from '../lib/config.mjs';
 import {formatFull, formatBrief, formatCompact} from '../lib/component-format.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
@@ -45,27 +44,17 @@ export function registerDiscover(program) {
       switch (result.type) {
         case 'discover.list': {
           if (result.data.length === 0) {
-            const config = await loadConfig();
             humanLog('');
-            if (config.packages.length === 0) {
-              humanLog('No package directories configured.');
+            if (result.meta && result.meta.configured === false) {
+              humanLog('No integrations configured.');
               humanLog('');
-              humanLog('Add a packages field to astryx.config.mjs:');
+              humanLog('Add integration package names to astryx.config.mjs:');
               humanLog('');
               humanLog('  export default {');
-              humanLog("    packages: ['/path/to/your/libs'],");
+              humanLog("    integrations: ['@scope/your-integration'],");
               humanLog('  };');
             } else {
-              humanLog('No external packages found.');
-              humanLog('');
-              humanLog('Packages opt in by adding an "astryx" field to package.json:');
-              humanLog('');
-              humanLog('  {');
-              humanLog('    "astryx": {');
-              humanLog('      "docs": "./src",');
-              humanLog('      "category": "Common"');
-              humanLog('    }');
-              humanLog('  }');
+              humanLog('No external components found in configured integrations.');
             }
             humanLog('');
           } else {

package/src/commands/doctor.test.mjs

@@ -132,7 +132,7 @@ describe('doctor — individual checks', () => {
     );
     const configPath = path.join(fixtureDir, 'astryx.config.mjs');
     try {
-      fs.writeFileSync(configPath, 'export default { theme: "default" };');
+      fs.writeFileSync(configPath, 'export default { integrations: [] };');
       const res = await checkConfig({cwd: fixtureDir, configPath});
       if (res.status !== 'pass') {
         throw new Error(`expected pass, got ${res.status}: ${res.message}`);
@@ -158,13 +158,13 @@ describe('doctor — individual checks', () => {
     }
   });
 
-  it('config: FAIL when packages is the wrong shape', async () => {
+  it('config: FAIL when default export is not an object', async () => {
     const fixtureDir = fs.mkdtempSync(
       path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),
     );
     const configPath = path.join(fixtureDir, 'astryx.config.mjs');
     try {
-      fs.writeFileSync(configPath, 'export default { packages: [123] };');
+      fs.writeFileSync(configPath, 'export default 123;');
       const res = await checkConfig({cwd: fixtureDir, configPath});
       expect(res.status).toBe('fail');
     } finally {

package/src/commands/json-contract.test.mjs

@@ -91,15 +91,6 @@ describe('--json contract: rejects before side effects', () => {
     expect(fs.readdirSync(tmpDir)).toEqual([]);
   });
 
-  it('astryx gap-report setup --json rejects before prompting', () => {
-    const {status, stdout} = runCli(['gap-report', 'setup', '--json'], {cwd: tmpDir});
-    expect(status).toBe(1);
-    const parsed = parseJson(stdout);
-    expect(parsed.error).toMatch(/gap-report setup/);
-    // No astryx.config.mjs written.
-    expect(fs.existsSync(path.join(tmpDir, 'astryx.config.mjs'))).toBe(false);
-  });
-
   it('astryx theme --json (parent, no subcommand) rejects without printing help', () => {
     const {status, stdout, stderr} = runCli(['theme', '--json'], {cwd: tmpDir});
     expect(status).toBe(1);
@@ -145,29 +136,6 @@ describe('--json contract: supported commands emit valid envelopes', () => {
     expect(Array.isArray(parsed.data.jsonSupported)).toBe(true);
   });
 
-  it('astryx gap-report --json --list-categories returns a typed envelope', () => {
-    const {status, stdout} = runCli(['gap-report', '--json', '--list-categories'], {cwd: tmpDir});
-    expect(status).toBe(0);
-    const parsed = parseJson(stdout);
-    expect(parsed.type).toBe('gap-report.categories');
-    expect(Array.isArray(parsed.data)).toBe(true);
-  });
-
-  it('astryx gap-report --json without required flags emits a structured error (no clack)', () => {
-    // Configure gap-report so it doesn't error on "disabled" — we want to
-    // hit the "interactive prompt would start" branch.
-    fs.writeFileSync(
-      path.join(tmpDir, 'astryx.config.mjs'),
-      'export default { gapReport: { command: "true" } };\n',
-    );
-    const {status, stdout} = runCli(['gap-report', '--json'], {cwd: tmpDir});
-    expect(status).toBe(1);
-    const parsed = parseJson(stdout);
-    expect(parsed.error).toMatch(/component/i);
-    // Must not contain clack-rendered prompt characters.
-    expect(stdout).not.toMatch(/Which component/);
-  });
-
   it('astryx upgrade --json --list returns the codemod list', () => {
     const {status, stdout} = runCli(['upgrade', '--json', '--list'], {cwd: tmpDir});
     expect(status).toBe(0);