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

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,
+  );
+});

package/api/component/list/list.mjs

@@ -16,6 +16,7 @@ import {
   discoverComponents,
   discoverExternalComponentsGrouped,
   discoverValidIntegrationComponents,
+  familyMember,
   findComponentReadme,
   findExternalComponentDoc,
   resolveImportPath,
@@ -66,6 +67,33 @@ async function legacyImport(ext, name, coreDir, docOpts) {
  */
 const coreEntry = doc => ({name: doc.name, package: CORE_PACKAGE, ...doc});
 
+/**
+ * The full-level entry for a component documented as a member of its family's
+ * doc (VStack in Stack's doc): a component doc built from the member's own
+ * entry, under its own name, display name and import, shaped like every other
+ * full entry. Null when the doc is the component's own.
+ * @param {any} docs
+ * @param {string} name
+ * @param {string} coreDir
+ * @returns {any}
+ */
+function memberEntry(docs, name, coreDir) {
+  const member = familyMember(docs, name);
+  if (!member) return null;
+  return {
+    name,
+    package: CORE_PACKAGE,
+    displayName: member.displayName ?? name,
+    ...(docs.group ? {group: docs.group} : {}),
+    ...(docs.category ? {category: docs.category} : {}),
+    usage: member.usage ?? {description: member.description ?? ''},
+    props: member.props ?? [],
+    ...(member.examples ? {examples: member.examples} : {}),
+    ...(docs.theming ? {theming: docs.theming} : {}),
+    import: resolveImportPath(coreDir, name),
+  };
+}
+
 /**
  * The entry for a Core slot an integration component replaces
  * (spec:AST-035 FR11), at the list's detail level: the replacement's own name,
@@ -177,7 +205,11 @@ export async function componentList(
             entries.push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -215,7 +247,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            entries.push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            entries.push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             entries.push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }
@@ -269,7 +302,11 @@ export async function componentList(
             result[cat].push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -310,7 +347,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            result[cat].push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            result[cat].push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             result[cat].push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }

package/api/gap-report/gap-report.mjs

@@ -17,7 +17,17 @@
 import {Worker} from 'node:worker_threads';
 import {AstryxError} from '../error.mjs';
 import {Project} from '../../foundation/config/project.mjs';
-import {CORE_PACKAGE} from '../../foundation/discovery/component-discovery.mjs';
+import {
+  CORE_PACKAGE,
+  discoverIntegrationComponents,
+  docStem,
+  findComponentReadme,
+  findIntegrationComponent,
+  integrationRecordHold,
+  unscopedComponentOwners,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {legacyExternalKeeps} from '../component/_adapter.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {captureEnv} from '../../foundation/debug/event.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {parseGapReportReceipt} from '../../authoring/gap-report/parse.mjs';
@@ -178,13 +188,65 @@ async function selectTarget(project, component, packageName) {
     coreName,
   );
   if (replacement) return targetForPackage(project, replacement.package);
+  // The owner rule runs over every owner discovery finds, loadable or not
+  // (a doc recorded under another export still answers to its file's name);
+  // then only owners whose docs load route a report.
+  const wanted = bareComponent.toLowerCase();
+  const loads = new Set(records.map(r => `${r.package}\0${r.docPath}`));
+  const recorded = project.loadedIntegrations.flatMap(integration =>
+    discoverIntegrationComponents(integration).flatMap(r =>
+      r.name.toLowerCase() === wanted
+        ? [{...r, hold: integrationRecordHold(r)}]
+        : docStem(r.docPath).toLowerCase() === wanted
+          ? [{...r, hold: 'doc'}]
+          : [],
+    ),
+  );
+  // The checks below find files by name, so they run on every spelling the
+  // case-blind match above found, as well as the one typed.
+  const spellings = new Set([
+    bareComponent,
+    ...recorded.flatMap(r =>
+      [r.name, docStem(r.docPath)].filter(n => n.toLowerCase() === wanted),
+    ),
+  ]);
+  // Core also holds a name only its doc lookup finds, as in detail: a name a
+  // doc records yields to it, though it routes no report itself.
+  const coreDir = findCoreDir(project.cwd);
+  const coreDocs =
+    coreDir != null &&
+    [...spellings].some(name => findComponentReadme(coreDir, name) != null);
+  const ruled = unscopedComponentOwners([
+    ...records
+      .filter(
+        r => r.package === CORE_PACKAGE && r.name.toLowerCase() === wanted,
+      )
+      .map(r => ({...r, hold: 'core'})),
+    ...recorded,
+    // A hidden doc named after its file still holds that name, as the
+    // component lookup finds it; it routes no report.
+    ...project.loadedIntegrations.flatMap(integration =>
+      [...spellings].flatMap(spelling => {
+        const found = findIntegrationComponent(integration, spelling);
+        return found?.hold === 'file'
+          ? [{...found, package: integration.name}]
+          : [];
+      }),
+    ),
+  ]).filter(r => !coreDocs || r.hold !== 'doc');
+  // A legacy docs package keeps an export name a doc records, as in detail.
   const owners = [
     ...new Set(
-      records
+      ([...spellings].some(name =>
+        legacyExternalKeeps(project.cwd, name, ruled),
+      )
+        ? []
+        : ruled
+      )
         .filter(
-          record => record.name.toLowerCase() === bareComponent.toLowerCase(),
+          r => r.hold === 'core' || loads.has(`${r.package}\0${r.docPath}`),
         )
-        .map(record => record.package),
+        .map(r => r.package),
     ),
   ];