@astryxdesign/cli 0.1.2 → 0.1.3

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/ensure-core-built.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared test helper: build @astryxdesign/core once, race-free.
+ *
+ * `astryx theme build` imports the compiled @astryxdesign/core/theme entry
+ * (there is no in-CLI fallback generator), so any test exercising it needs a
+ * built core. The CI `test` job runs `pnpm test` without a prior core build,
+ * and Vitest runs test files in parallel worker forks. When two build-theme
+ * suites each ran `if (!exists) pnpm -F @astryxdesign/core build` in their own
+ * beforeAll, both workers saw dist missing and launched concurrent builds that
+ * collided on the shared packages/core/dist (core's build starts with
+ * `rimraf dist`): one worker wiped dist while the other was mid-write, failing
+ * nondeterministically ("Could not resolve dist/index.js" / "ENOTEMPTY rmdir
+ * dist/hooks").
+ *
+ * This serializes the build behind a filesystem lock so exactly one worker
+ * builds and the rest wait for it to finish before reading dist.
+ */
+
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+const CORE_THEME_ENTRY = path.join(
+  REPO_ROOT,
+  'packages/core/dist/theme/index.js',
+);
+// A lock directory (mkdir is atomic across processes) guards the build.
+const LOCK_DIR = path.join(os.tmpdir(), 'astryx-core-build.lock');
+
+const BUILD_TIMEOUT_MS = 180_000;
+// A lock older than this is assumed abandoned by a crashed/killed worker.
+const STALE_LOCK_MS = BUILD_TIMEOUT_MS + 20_000;
+const POLL_MS = 250;
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function buildCore() {
+  execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
+    cwd: REPO_ROOT,
+    stdio: 'pipe',
+    timeout: BUILD_TIMEOUT_MS,
+  });
+}
+
+function lockIsStale() {
+  try {
+    return Date.now() - fs.statSync(LOCK_DIR).mtimeMs > STALE_LOCK_MS;
+  } catch {
+    // Vanished between the exists check and stat — treat as released.
+    return false;
+  }
+}
+
+/** Try to acquire the lock. Returns true if this worker now holds it. */
+function tryAcquire() {
+  try {
+    fs.mkdirSync(LOCK_DIR);
+    return true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') {
+      throw err;
+    }
+    if (lockIsStale()) {
+      fs.rmSync(LOCK_DIR, {recursive: true, force: true});
+      try {
+        fs.mkdirSync(LOCK_DIR);
+        return true;
+      } catch (retryErr) {
+        if (retryErr.code !== 'EEXIST') {
+          throw retryErr;
+        }
+      }
+    }
+    return false;
+  }
+}
+
+/**
+ * Ensure packages/core/dist is built exactly once, even when called
+ * concurrently from parallel Vitest workers. Safe to call from every
+ * build-theme suite's beforeAll.
+ */
+export function ensureCoreBuilt() {
+  if (fs.existsSync(CORE_THEME_ENTRY)) {
+    return;
+  }
+
+  const deadline = Date.now() + STALE_LOCK_MS;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(CORE_THEME_ENTRY)) {
+      return;
+    }
+    if (tryAcquire()) {
+      try {
+        if (!fs.existsSync(CORE_THEME_ENTRY)) {
+          buildCore();
+        }
+      } finally {
+        fs.rmSync(LOCK_DIR, {recursive: true, force: true});
+      }
+      return;
+    }
+    // Another worker is building; wait for it to finish and release the lock.
+    sleepSync(POLL_MS);
+  }
+
+  // Waited past the stale threshold without the artifact appearing — build it
+  // ourselves rather than let the suite fail on a missing entry.
+  buildCore();
+}

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