@astryxdesign/cli 0.7.2-canary.e2909cf → 0.7.2-canary.ebcc404

package/api/component/_adapter.d.mts

@@ -26,6 +26,8 @@
  * @property {string|null} sourcePath
  * @property {string|undefined} issuesUrl
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
+ * @property {import('../../foundation/discovery/component-discovery.mjs').NameHold} hold
+ *   how the owner holds the name, for the owner rule
  */
 /**
  * What ownership shaping needs from an owner. The core and legacy-external
@@ -138,6 +140,25 @@ export function assertUnambiguousOwners(owners: ComponentOwner[], dirName: strin
  * @returns {string | null}
  */
 export function resolveLegacyExternalDoc(ext: ExternalPackageRef, dirName: string): string | null;
+/**
+ * Whether a legacy external package documents `dirName`.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @returns {boolean}
+ */
+export function legacyExternalDocuments(cwd: string, dirName: string): boolean;
+/**
+ * Whether a legacy docs package keeps `dirName` over these owners, each of which
+ * holds it only as an export a doc records.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @param {Array<{hold?: string, docPath?: string | null}>} owners
+ * @returns {boolean}
+ */
+export function legacyExternalKeeps(cwd: string, dirName: string, owners: Array<{
+    hold?: string;
+    docPath?: string | null;
+}>): boolean;
 /**
  * The core source file for `dirName` (the no-scope `--source` path reads core
  * directly — it does NOT fall back to externals or fuzzy search).
@@ -210,7 +231,6 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
     };
     matchingComponent: any;
 } | null;
-export { CORE_PACKAGE };
 /**
  * Internal ambiguity marker. Single-component callers still receive the same
  * AstryxError code, message, and suggestions; batch callers can additionally
@@ -261,6 +281,10 @@ export type ComponentOwner = {
     sourcePath: string | null;
     issuesUrl: string | undefined;
     integration: import("../../foundation/integrations/integrations.mjs").LoadedIntegration | null;
+    /**
+     *   how the owner holds the name, for the owner rule
+     */
+    hold: import("../../foundation/discovery/component-discovery.mjs").NameHold;
 };
 /**
  * What ownership shaping needs from an owner. The core and legacy-external
@@ -303,4 +327,6 @@ export type ResolvedUnscopedDoc = {
     resolvedSourcePath: string | null;
 };
 import { CORE_PACKAGE } from '../../foundation/discovery/component-discovery.mjs';
+import { unscopedComponentOwners } from '../../foundation/discovery/component-discovery.mjs';
 import { AstryxError } from '../error.mjs';
+export { CORE_PACKAGE, unscopedComponentOwners };

package/api/component/_adapter.mjs

@@ -28,13 +28,14 @@ import {
 import {
   CORE_PACKAGE,
   discoverComponents,
+  docStem,
   findComponentReadme,
   findComponentSource,
   findExternalComponentDoc,
-  findIntegrationComponentDoc,
-  findIntegrationComponentSource,
+  findIntegrationComponent,
   resolveImportPath,
   resolveIntegrationImportPath as resolveIntegrationImport,
+  unscopedComponentOwners,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {Project} from '../../foundation/config/project.mjs';
 import {loadComponentDoc as loadValidatedComponentDoc} from '../../foundation/discovery/component-loader.mjs';
@@ -42,7 +43,7 @@ import {resolveComponentReplacements} from '../../foundation/discovery/component
 import {searchComponents} from '../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../error.mjs';
 
-export {CORE_PACKAGE};
+export {CORE_PACKAGE, unscopedComponentOwners};
 
 /**
  * A loaded component doc. The shared validated loader accepts stamped and legacy
@@ -71,6 +72,8 @@ export {CORE_PACKAGE};
  * @property {string|null} sourcePath
  * @property {string|undefined} issuesUrl
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
+ * @property {import('../../foundation/discovery/component-discovery.mjs').NameHold} hold
+ *   how the owner holds the name, for the owner rule
  */
 
 /**
@@ -240,17 +243,19 @@ export function resolveOwners(coreDir, dirName, loadedIntegrations) {
       sourcePath: findComponentSource(coreDir, dirName),
       issuesUrl: undefined,
       integration: null,
+      hold: 'core',
     });
   }
   for (const integration of loadedIntegrations) {
-    const docPath = findIntegrationComponentDoc(integration, dirName);
-    if (!docPath) continue;
+    const found = findIntegrationComponent(integration, dirName);
+    if (!found) continue;
     owners.push({
       package: integration.name,
-      docPath,
-      sourcePath: findIntegrationComponentSource(integration, dirName),
+      docPath: found.docPath,
+      sourcePath: found.sourcePath,
       issuesUrl: integration.issuesUrl,
       integration,
+      hold: found.hold,
     });
   }
   return owners;
@@ -361,6 +366,39 @@ export function resolveLegacyExternalDoc(ext, dirName) {
   return extDocPath && extDocPath.endsWith('.doc.mjs') ? extDocPath : null;
 }
 
+/**
+ * Whether a legacy external package documents `dirName`.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @returns {boolean}
+ */
+export function legacyExternalDocuments(cwd, dirName) {
+  return discoverExternalPackages(cwd).some(
+    ext => resolveLegacyExternalDoc(ext, dirName) != null,
+  );
+}
+
+/**
+ * Whether a legacy docs package keeps `dirName` over these owners, each of which
+ * holds it only as an export a doc records.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @param {Array<{hold?: string, docPath?: string | null}>} owners
+ * @returns {boolean}
+ */
+export function legacyExternalKeeps(cwd, dirName, owners) {
+  return (
+    owners.length > 0 &&
+    owners.every(
+      owner =>
+        owner.hold === 'doc' &&
+        owner.docPath != null &&
+        docStem(owner.docPath).toLowerCase() !== dirName.toLowerCase(),
+    ) &&
+    legacyExternalDocuments(cwd, dirName)
+  );
+}
+
 /**
  * The core source file for `dirName` (the no-scope `--source` path reads core
  * directly — it does NOT fall back to externals or fuzzy search).

package/api/component/component.mjs

@@ -22,6 +22,7 @@ import {
   classifyScope,
   assertUnambiguousOwners,
   resolveLegacyExternalDoc,
+  legacyExternalKeeps,
   resolveCoreSourcePath,
   resolveUnscopedDoc,
   loadComponentDoc,
@@ -29,6 +30,7 @@ import {
   ComponentAmbiguityError,
   installedComponentPackageVersion,
   resolveComponentReplacement,
+  unscopedComponentOwners,
 } from './_adapter.mjs';
 import {componentList} from './list/list.mjs';
 import {componentDetail} from './detail/detail.mjs';
@@ -481,12 +483,14 @@ export async function component(name, options = {}) {
     });
   }
 
+  // The owner rule runs first, over valid and invalid owners alike.
+  const ruled = unscopedComponentOwners(owners);
   // Invalid integration metadata does not create ambiguity against a valid
-  // owner. Keep raw owners only when no doc owner is valid, so an integration-
+  // owner. Keep ruled owners only when no doc owner is valid, so an integration-
   // only component still exposes its source and returns ERR_INVALID_DOC for
   // detail instead of degrading to an unrelated unknown-component error.
   const validOwners = [];
-  for (const owner of owners) {
+  for (const owner of ruled) {
     if (owner.package === CORE_PACKAGE) {
       validOwners.push(owner);
       continue;
@@ -498,7 +502,12 @@ export async function component(name, options = {}) {
       // Project/Doctor report invalid metadata; it is not an effective owner.
     }
   }
-  const effectiveOwners = validOwners.length > 0 ? validOwners : owners;
+  const loadable = validOwners.length > 0 ? validOwners : ruled;
+  // A legacy docs package's exact doc keeps its name over an export name a doc
+  // records, as Core and file-named owners do.
+  const effectiveOwners = legacyExternalKeeps(cwd, dirName, loadable)
+    ? []
+    : loadable;
 
   // ── Ambiguity: owned by MORE THAN ONE valid package, no --package ──
   assertUnambiguousOwners(effectiveOwners, dirName);

package/api/component/integration-export-name.test.mjs

@@ -0,0 +1,419 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every surface knows an integration component by the name its doc
+ * documents. Fixtures live under a repo-local temp dir: Vite refuses to import
+ * a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {component} from './component.mjs';
+import {search} from '../search/search.mjs';
+import {validateIntegration} from '../integration/validate-integration.mjs';
+import {integrationComponentConflicts} from '../integration/authoring-checks.mjs';
+import {swizzleCopy} from '../swizzle/copy/copy.mjs';
+import {gapReport} from '../gap-report/gap-report.mjs';
+import {COMPONENT_REPLACES_CLI} from '../../foundation/integrations/cli-requirement.mjs';
+
+const SLOW = 30_000;
+
+/** @type {string} */
+let tmpDir;
+/** @type {string} */
+let pkgDir;
+
+/**
+ * @param {string} file path under the package's src/, without extension
+ * @param {string} name
+ * @param {string} source
+ * @param {string} description
+ * @param {object} [extra] more doc fields
+ */
+function writeComponent(file, name, source, description, extra = {}) {
+  const target = path.join(pkgDir, 'src', file);
+  fs.mkdirSync(path.dirname(target), {recursive: true});
+  fs.writeFileSync(`${target}.tsx`, source);
+  fs.writeFileSync(
+    `${target}.doc.mjs`,
+    `export default ${JSON.stringify(
+      {
+        type: 'component',
+        name,
+        displayName: name,
+        import: `@acme/widgets/${file}`,
+        usage: {description},
+        props: [],
+        ...extra,
+      },
+      null,
+      2,
+    )};\n`,
+  );
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-export-name-test-'),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    "export default {integrations: ['@acme/widgets']};\n",
+  );
+  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',
+      version: '1.0.0',
+      exports: {
+        './gallery/Slides': './src/gallery/Slides.tsx',
+        './gallery/Overlays': './src/gallery/Overlays.tsx',
+        './AcmeBadge': './src/AcmeBadge.tsx',
+      },
+    }),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    "export default {components: './src', issuesUrl: 'https://example.com/acme/issues'};\n",
+  );
+  writeComponent(
+    'gallery/Slides',
+    'AcmeCarousel',
+    'export function AcmeCarousel() { return null; }\nexport function useSlides() { return []; }\n',
+    'Cycles through a row of slides.',
+  );
+  writeComponent(
+    'AcmeBadge',
+    'AcmeBadge',
+    'export function AcmeBadge() { return null; }\n',
+    'A small status label.',
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {any} list @returns {string[]} the integration's listed names */
+function listedNames(list) {
+  return Object.values(list.data.components)
+    .flat()
+    .filter(entry => entry.package === '@acme/widgets')
+    .map(entry => entry.name)
+    .sort();
+}
+
+describe('a component doc that names another export of its file', () => {
+  it(
+    "leaves a name a legacy docs package documents to that package's doc",
+    async () => {
+      const legacy = path.join(tmpDir, 'node_modules', '@legacy', 'docs');
+      fs.mkdirSync(path.join(legacy, 'docs'), {recursive: true});
+      fs.writeFileSync(
+        path.join(legacy, 'package.json'),
+        JSON.stringify({name: '@legacy/docs', astryx: {docs: './docs'}}),
+      );
+      for (const name of ['AcmeCarousel', 'Slides']) {
+        fs.writeFileSync(
+          path.join(legacy, 'docs', `${name}.doc.mjs`),
+          `export default {type: 'component', name: '${name}', usage: {description: 'Legacy.'}, props: []};\n`,
+        );
+      }
+      const cwd = tmpDir;
+      expect((await component('AcmeCarousel', {cwd})).data.package).toBe(
+        '@legacy/docs',
+      );
+      const scoped = {cwd, package: '@acme/widgets'};
+      expect((await component('AcmeCarousel', scoped)).data.package).toBe(
+        '@acme/widgets',
+      );
+      // Slides.doc.mjs's file name still answers first, as on main.
+      expect((await component('Slides', {cwd})).data.package).toBe(
+        '@acme/widgets',
+      );
+      const report = {cwd, category: 'other', reason: 'Needs a size.'};
+      for (const name of ['AcmeCarousel', 'acmecarousel']) {
+        expect((await gapReport(name, report)).data.package).toBe(
+          '@astryxdesign/core',
+        );
+      }
+      const hits = (await search('AcmeCarousel', {cwd, type: 'component'})).data
+        .results;
+      expect(hits.find(hit => hit.package === '@acme/widgets')?.command).toBe(
+        'astryx component AcmeCarousel --package @acme/widgets',
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'is listed, opened and found by the export name',
+    async () => {
+      expect(
+        listedNames(await component(undefined, {cwd: tmpDir, list: true})),
+      ).toEqual(['AcmeBadge', 'AcmeCarousel']);
+
+      const detail = await component('AcmeCarousel', {cwd: tmpDir});
+      expect(detail.type).toBe('component.detail');
+      expect(detail.data).toMatchObject({
+        name: 'AcmeCarousel',
+        package: '@acme/widgets',
+        import: '@acme/widgets/gallery/Slides',
+        sourceAvailable: true,
+      });
+
+      const hits = (
+        await search('AcmeCarousel', {cwd: tmpDir, type: 'component'})
+      ).data.results;
+      expect(hits[0]).toMatchObject({
+        name: 'AcmeCarousel',
+        package: '@acme/widgets',
+        import: '@acme/widgets/gallery/Slides',
+      });
+
+      // The file name opens the same doc, as it did before, routes a gap
+      // report to the package, and search finds the component by it, a word
+      // of it included.
+      expect((await component('Slides', {cwd: tmpDir})).data.name).toBe(
+        'AcmeCarousel',
+      );
+      const report = {cwd: tmpDir, category: 'other', reason: 'Needs a size.'};
+      expect((await gapReport('Slides', report)).data.package).toBe(
+        '@acme/widgets',
+      );
+      for (const query of ['Slides', 'slide']) {
+        const byFileName = (
+          await search(query, {cwd: tmpDir, type: 'component'})
+        ).data.results;
+        expect(byFileName[0]?.name).toBe('AcmeCarousel');
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    "leaves a Core name to Core unless --package names it, and passes Doctor's package checks",
+    async () => {
+      // Overlays.tsx exports Dialog, a Core name, and nothing named Overlays.
+      writeComponent(
+        'gallery/Overlays',
+        'Dialog',
+        'export function AcmeOverlays() { return null; }\nexport function Dialog() { return null; }\n',
+        'Overlays.',
+      );
+
+      const validation = await validateIntegration(undefined, {cwd: pkgDir});
+      expect(validation.data.issues).toEqual([]);
+
+      const conflicts = await integrationComponentConflicts(undefined, {
+        cwd: pkgDir,
+      });
+      expect(conflicts.data.conflicts.map(conflict => conflict.name)).toEqual([
+        'Dialog',
+      ]);
+
+      // Lookups by the bare name still answer with Core's Dialog, as before.
+      const cwd = tmpDir;
+      const core = '@astryxdesign/core';
+      expect((await component('Dialog', {cwd})).data.package).toBe(core);
+      expect((await component('Dialog', {cwd, props: true})).package).toBe(
+        core,
+      );
+      expect((await swizzleCopy('Dialog', {cwd})).package).toBe(core);
+      const report = {cwd, category: 'other', reason: 'Needs a size.'};
+      expect((await gapReport('Dialog', report)).data.package).toBe(core);
+      // The list and --package reach the integration's Dialog.
+      const scoped = {cwd, package: '@acme/widgets'};
+      expect((await component('Dialog', scoped)).data.import).toBe(
+        '@acme/widgets/gallery/Overlays',
+      );
+      expect(
+        listedNames(await component(undefined, {cwd, list: true})),
+      ).toContain('Dialog');
+      // Search shows both; the package's hit names its package and follows
+      // Core's.
+      const hits = (await search('Dialog', {cwd, type: 'component'})).data
+        .results;
+      const ours = hits.findIndex(hit => hit.package === '@acme/widgets');
+      expect(hits[0]).toMatchObject({name: 'Dialog', package: core});
+      expect(hits[ours]).toMatchObject({
+        name: 'Dialog',
+        command: 'astryx component Dialog --package @acme/widgets',
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'leaves a Core name with no folder of its own unknown to swizzle, as before',
+    async () => {
+      // Core documents CheckboxIndicator inside Indicator's doc, with no folder.
+      // BaseTable, named after its file, keeps routing reports to its package.
+      writeComponent(
+        'BaseTable',
+        'BaseTable',
+        'export function BaseTable() { return null; }\n',
+        'A file-named table.',
+      );
+      writeComponent(
+        'gallery/Indicator',
+        'CheckboxIndicator',
+        'export function CheckboxIndicator() { return null; }\n',
+        'A header.',
+      );
+      const cwd = tmpDir;
+      expect((await component('CheckboxIndicator', {cwd})).data.package).toBe(
+        '@astryxdesign/core',
+      );
+      await expect(
+        swizzleCopy('CheckboxIndicator', {cwd}),
+      ).rejects.toMatchObject({
+        code: 'ERR_UNKNOWN_COMPONENT',
+      });
+      const scoped = {cwd, package: '@acme/widgets'};
+      expect((await swizzleCopy('CheckboxIndicator', scoped)).package).toBe(
+        '@acme/widgets',
+      );
+      const report = {cwd, category: 'other', reason: 'Needs a size.'};
+      expect((await gapReport('CheckboxIndicator', report)).data.package).toBe(
+        '@astryxdesign/core',
+      );
+      const hit = (
+        await search('CheckboxIndicator', {cwd, type: 'component'})
+      ).data.results.find(result => result.package === '@acme/widgets');
+      expect(hit?.command).toBe(
+        'astryx component CheckboxIndicator --package @acme/widgets',
+      );
+      expect((await gapReport('BaseTable', report)).data.package).toBe(
+        '@acme/widgets',
+      );
+    },
+    SLOW,
+  );
+
+  it.each([
+    // props must be an array: the loader rejects this doc.
+    [
+      'invalid',
+      "export default {type: 'component', name: 'AcmeTab', props: 'x'};",
+    ],
+    [
+      'hidden',
+      "export default {\n  type: 'component',\n  name: 'AcmeTab',\n  hidden: true,\n  usage: {description: 'x'},\n  props: [],\n};",
+    ],
+  ])(
+    "leaves a name to another package's file-named doc even when that doc is %s",
+    async (kind, doc) => {
+      writeComponent(
+        'gallery/Strip',
+        'AcmeTab',
+        'export function AcmeTab() { return null; }\n',
+        'A strip of tabs.',
+      );
+      const beta = path.join(tmpDir, 'node_modules', '@beta', 'kit');
+      fs.mkdirSync(path.join(beta, 'src'), {recursive: true});
+      for (const [file, text] of Object.entries({
+        'package.json': '{"name": "@beta/kit", "version": "1.0.0"}',
+        'astryx.integration.mjs': "export default {components: './src'};",
+        'src/AcmeTab.tsx': 'export function AcmeTab() { return null; }',
+        'src/AcmeTab.doc.mjs': doc,
+      })) {
+        fs.writeFileSync(path.join(beta, file), `${text}\n`);
+      }
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.config.mjs'),
+        "export default {integrations: ['@acme/widgets', '@beta/kit']};\n",
+      );
+
+      const cwd = tmpDir;
+      expect((await component('AcmeTab', {cwd, source: true})).package).toBe(
+        '@beta/kit',
+      );
+      if (kind === 'invalid') {
+        await expect(component('AcmeTab', {cwd})).rejects.toMatchObject({
+          code: 'ERR_INVALID_DOC',
+        });
+      }
+      const report = {cwd, category: 'other', reason: 'Needs a size.'};
+      for (const name of ['AcmeTab', 'acmetab']) {
+        expect((await gapReport(name, report)).data.package).toBe(
+          '@astryxdesign/core',
+        );
+      }
+      const hit = (
+        await search('AcmeTab', {cwd, type: 'component'})
+      ).data.results.find(result => result.package === '@acme/widgets');
+      expect(hit?.command).toBe(
+        'astryx component AcmeTab --package @acme/widgets',
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'leaves a file name Core also has to Core in search, as in detail',
+    async () => {
+      // Badge.doc.mjs documents AcmeStatusBadge; its file name is Core's.
+      writeComponent(
+        'status/Badge',
+        'AcmeStatusBadge',
+        'export function AcmeStatusBadge() { return null; }\n',
+        'Shows a status.',
+      );
+      const cwd = tmpDir;
+      const [first] = (await search('Badge', {cwd, type: 'component'})).data
+        .results;
+      expect(first).toMatchObject({
+        name: 'Badge',
+        package: '@astryxdesign/core',
+      });
+      expect((await component('Badge', {cwd})).data.package).toBe(
+        '@astryxdesign/core',
+      );
+      const [own] = (await search('AcmeStatusBadge', {cwd, type: 'component'}))
+        .data.results;
+      expect(own).toMatchObject({
+        name: 'AcmeStatusBadge',
+        command: 'astryx component AcmeStatusBadge',
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'copies a replacement recorded under its export into its file name folder, as before',
+    async () => {
+      const manifest = path.join(pkgDir, 'package.json');
+      fs.writeFileSync(
+        manifest,
+        JSON.stringify({
+          ...JSON.parse(fs.readFileSync(manifest, 'utf-8')),
+          peerDependencies: {
+            '@astryxdesign/cli': `>=${COMPONENT_REPLACES_CLI}`,
+          },
+        }),
+      );
+      writeComponent(
+        'gallery/Slides',
+        'AcmeCarousel',
+        'export function AcmeCarousel() { return null; }\n',
+        'Cycles through a row of slides.',
+        {replaces: 'Carousel'},
+      );
+
+      const copied = await swizzleCopy('Carousel', {cwd: tmpDir});
+      expect(copied.data).toMatchObject({
+        package: '@acme/widgets',
+        outputDir: path.join('components', 'astryx', 'Slides'),
+      });
+    },
+    SLOW,
+  );
+});