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

package/foundation/discovery/component-discovery.export-names.test.mjs

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Integration components are found by the names their docs document;
- * every doc that works today reads exactly as before.
+ * @file Integration components, and the members a family doc lists, are found
+ * by the names their docs document; every doc that works today reads as before.
  */
 
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
@@ -291,3 +291,470 @@ describe('integration components whose doc names another export of its file', ()
     expect(names()).toEqual([]);
   });
 });
+
+/**
+ * Write a family doc and its source.
+ * @param {string} file path under the root, without extension
+ * @param {{name: string, members: string, source: string, extra?: string}} options
+ *   `members` is the `components` array, written as JavaScript
+ */
+function writeFamily(file, {name, members, source, extra = ''}) {
+  const target = path.join(root, file);
+  fs.mkdirSync(path.dirname(target), {recursive: true});
+  fs.writeFileSync(
+    `${target}.doc.mjs`,
+    `export default {\n  type: 'component',\n  name: '${name}',\n  usage: {description: 'A family.'},${extra}\n  components: ${members},\n};\n`,
+  );
+  fs.writeFileSync(`${target}.tsx`, source);
+}
+
+describe('integration components a family doc lists in components', () => {
+  it('records each exported full entry under its own name, with the file that declares it', async () => {
+    writeFamily('carousel/AcmeCarousel', {
+      name: 'AcmeCarousel',
+      members:
+        "[{name: 'AcmeCarousel', description: 'The carousel.'}, {name: 'AcmeSlide', description: 'One slide.'}, {name: 'AcmeDots', description: 'The dots.'}]",
+      source:
+        "export function AcmeCarousel() { return null; }\nexport function AcmeSlide() { return null; }\nexport {AcmeDots} from './dots';\n",
+    });
+    fs.writeFileSync(
+      path.join(root, 'carousel', 'dots.tsx'),
+      'export const AcmeDots = () => null;\n',
+    );
+
+    const records = discoverIntegrationComponents(integration());
+    const docPath = path.join(root, 'carousel', 'AcmeCarousel.doc.mjs');
+    expect(records.map(record => record.name)).toEqual([
+      'AcmeCarousel',
+      'AcmeSlide',
+      'AcmeDots',
+    ]);
+    expect(records.find(record => record.name === 'AcmeSlide')).toMatchObject({
+      docPath,
+      sourcePath: path.join(root, 'carousel', 'AcmeCarousel.tsx'),
+    });
+    expect(findIntegrationComponentDoc(integration(), 'AcmeDots')).toBe(
+      docPath,
+    );
+    expect(findIntegrationComponentSource(integration(), 'AcmeDots')).toBe(
+      path.join(root, 'carousel', 'dots.tsx'),
+    );
+    const {components, errors} =
+      await discoverValidIntegrationComponents(integration());
+    expect(errors).toEqual([]);
+    expect(components.map(record => record.name)).toEqual([
+      'AcmeCarousel',
+      'AcmeSlide',
+      'AcmeDots',
+    ]);
+  });
+
+  it('reads members from the module the doc imports, through the package exports', () => {
+    // The components root inside a package whose exports publish the module.
+    const componentsRoot = path.join(root, 'src');
+    fs.mkdirSync(path.join(componentsRoot, 'carousel'), {recursive: true});
+    fs.writeFileSync(
+      path.join(root, 'package.json'),
+      JSON.stringify({
+        name: '@acme/widgets',
+        exports: {'./carousel': './src/carousel/index.ts'},
+      }),
+    );
+    fs.writeFileSync(
+      path.join(componentsRoot, 'carousel', 'AcmeCarousel.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeCarousel', import: '@acme/widgets/carousel', usage: {description: 'x'}, components: [{name: 'AcmeCarousel', description: 'x'}, {name: 'AcmeSlide', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(componentsRoot, 'carousel', 'AcmeCarousel.tsx'),
+      'export function AcmeCarousel() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(componentsRoot, 'carousel', 'index.ts'),
+      "export * from './AcmeCarousel';\nexport {AcmeSlide} from './slide';\n",
+    );
+    fs.writeFileSync(
+      path.join(componentsRoot, 'carousel', 'slide.tsx'),
+      'export function AcmeSlide() { return null; }\n',
+    );
+
+    const loaded = {
+      name: '@acme/widgets',
+      components: componentsRoot,
+      __packageDir: root,
+    };
+    expect(
+      discoverIntegrationComponents(loaded).find(
+        record => record.name === 'AcmeSlide',
+      ),
+    ).toMatchObject({
+      sourcePath: path.join(componentsRoot, 'carousel', 'slide.tsx'),
+    });
+    // Without the package, only the doc's own source is read, and it lacks
+    // the member.
+    expect(
+      discoverIntegrationComponents({...loaded, __packageDir: undefined}).map(
+        record => record.name,
+      ),
+    ).toEqual(['AcmeCarousel']);
+  });
+
+  it('leaves every other entry as before', () => {
+    writeFamily('Gallery', {
+      name: 'AcmeGallery',
+      extra: "\n  hiddenComponents: ['AcmeHidden'],",
+      members: [
+        '[',
+        "  {name: 'AcmeGallery', description: 'x'},",
+        // Not exported by the source.
+        "  {name: 'AcmeMissing', description: 'x'},",
+        // Hidden by the doc.
+        "  {name: 'AcmeHidden', description: 'x'},",
+        // A hook.
+        "  {name: 'useGallery', description: 'x'},",
+        // A name-only entry points at the member's own doc.
+        "  {name: 'AcmeThumb'},",
+        // Another file already has the name.
+        "  {name: 'AcmeBadge', description: 'x'},",
+        // A computed name.
+        "  {name: `${'Acme'}Tile`, description: 'x'},",
+        ']',
+      ].join('\n'),
+      source: [
+        'export function AcmeGallery() { return null; }',
+        'export function AcmeHidden() { return null; }',
+        'export function useGallery() { return []; }',
+        'export function AcmeThumb() { return null; }',
+        'export function AcmeBadge() { return null; }',
+        'export function AcmeTile() { return null; }',
+        '',
+      ].join('\n'),
+    });
+    writeComponent('AcmeBadge', {
+      name: "'AcmeBadge'",
+      source: 'export function AcmeBadge() { return null; }\n',
+    });
+
+    // Gallery.tsx exports no `Gallery`, so the doc's own name is its export.
+    expect(names()).toEqual(['AcmeBadge', 'AcmeGallery']);
+    for (const name of [
+      'AcmeMissing',
+      'AcmeHidden',
+      'useGallery',
+      'AcmeThumb',
+      'AcmeTile',
+    ]) {
+      expect(findIntegrationComponentDoc(integration(), name)).toBeNull();
+    }
+  });
+
+  it("does not hand a family's replaces to its members", async () => {
+    writeFamily('AcmeCarousel', {
+      name: 'AcmeCarousel',
+      extra: "\n  replaces: 'Carousel',",
+      members:
+        "[{name: 'AcmeCarousel', description: 'x'}, {name: 'AcmeSlide', description: 'x'}]",
+      source:
+        'export function AcmeCarousel() { return null; }\nexport function AcmeSlide() { return null; }\n',
+    });
+    const {components} =
+      await discoverValidIntegrationComponents(integration());
+    expect(components.map(record => [record.name, record.replaces])).toEqual([
+      ['AcmeCarousel', 'Carousel'],
+      ['AcmeSlide', undefined],
+    ]);
+  });
+
+  it('drops a member once the file its source re-exports stops exporting it', () => {
+    writeFamily('AcmeTabs', {
+      name: 'AcmeTabs',
+      members: "[{name: 'AcmeTab', description: 'x'}]",
+      source:
+        "export function AcmeTabs() { return null; }\nexport * from './tab';\n",
+    });
+    const tab = path.join(root, 'tab.tsx');
+    fs.writeFileSync(tab, 'export function AcmeTab() { return null; }\n');
+    expect(names()).toEqual(['AcmeTab', 'AcmeTabs']);
+    fs.writeFileSync(tab, 'export function AcmeTabLegacy() { return null; }\n');
+    expect(names()).toEqual(['AcmeTabs']);
+  });
+
+  it('reads members a doc lists through a shorthand property', () => {
+    fs.writeFileSync(
+      path.join(root, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(root, 'AcmeTabs.doc.mjs'),
+      "const components = [{name: 'AcmeTab', description: 'x'}];\nexport default {type: 'component', name: 'AcmeTabs', usage: {description: 'x'}, components};\n",
+    );
+    expect(names()).toEqual(['AcmeTab', 'AcmeTabs']);
+  });
+
+  it('reports a family doc the loader rejects once, not once per member', async () => {
+    writeFamily('AcmeStrip', {
+      name: 'AcmeStrip',
+      extra: '\n  displayName: 7,',
+      members:
+        "[{name: 'AcmeStrip', description: 'x'}, {name: 'AcmeStripItem', description: 'x'}]",
+      source:
+        'export function AcmeStrip() { return null; }\nexport function AcmeStripItem() { return null; }\n',
+    });
+    const {components, errors} =
+      await discoverValidIntegrationComponents(integration());
+    expect(components).toEqual([]);
+    expect(errors.map(error => error.name)).toEqual(['AcmeStrip']);
+  });
+
+  /**
+   * A package around the components root `src/`, with these files.
+   * @param {Record<string, unknown>} manifest package.json fields
+   * @param {Record<string, string>} files paths under the package
+   */
+  function writePackage(manifest, files) {
+    fs.writeFileSync(
+      path.join(root, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', ...manifest}),
+    );
+    for (const [file, text] of Object.entries(files)) {
+      fs.mkdirSync(path.dirname(path.join(root, file)), {recursive: true});
+      fs.writeFileSync(path.join(root, file), text);
+    }
+    return {
+      name: '@acme/widgets',
+      components: path.join(root, 'src'),
+      __packageDir: root,
+    };
+  }
+
+  /** @param {object} loaded */
+  const namesIn = loaded =>
+    discoverIntegrationComponents(/** @type {any} */ (loaded))
+      .map(record => record.name)
+      .sort();
+
+  const family = (/** @type {string} */ name, /** @type {string} */ entries) =>
+    `export default {type: 'component', name: '${name}', usage: {description: 'x'}, components: [${entries}]};\n`;
+
+  it('reads members from the main file of a package without exports, and none it cannot resolve', () => {
+    const loaded = writePackage(
+      {main: './src/index.ts'},
+      {
+        'src/list/AcmeList.doc.mjs': family(
+          'AcmeList',
+          "{name: 'AcmeListRow', description: 'x'}, {name: 'AcmeListCell', description: 'x'}",
+        ).replace('usage:', "import: '@acme/widgets', usage:"),
+        'src/list/AcmeList.tsx':
+          'export function AcmeList() { return null; }\nexport function AcmeListRow() { return null; }\n',
+        'src/list/cell.tsx':
+          'export function AcmeListCell() { return null; }\n',
+        'src/index.ts':
+          "export {AcmeList} from './list/AcmeList';\nexport {AcmeListCell} from './list/cell';\n",
+      },
+    );
+    expect(namesIn(loaded)).toEqual(['AcmeList', 'AcmeListCell']);
+    // An import the package cannot resolve lists no members, not the
+    // same-stem file's.
+    fs.rmSync(path.join(root, 'src', 'index.ts'));
+    expect(namesIn(loaded)).toEqual(['AcmeList']);
+  });
+
+  it("takes a member's source from the family's folder, never a bundle or the package root", () => {
+    const loaded = writePackage(
+      {exports: {'.': {import: './dist/index.mjs'}}},
+      {
+        'src/tabs/AcmeTabs.doc.mjs': family(
+          'AcmeTabs',
+          "{name: 'AcmeTab', description: 'x'}",
+        ),
+        'src/tabs/AcmeTabs.tsx':
+          'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\n',
+        'dist/index.mjs':
+          'function AcmeTabs() { return null; }\nfunction AcmeTab() { return null; }\nexport {AcmeTabs, AcmeTab};\n',
+        // A member only the package's root file and the bundle declare is
+        // listed, with no source.
+        'src/cards/AcmeCards.doc.mjs': family(
+          'AcmeCards',
+          "{name: 'AcmeCard', description: 'x'}",
+        ),
+        'src/cards/AcmeCards.tsx':
+          'export function AcmeCards() { return null; }\n',
+        'src/index.tsx':
+          "export {AcmeCards} from './cards/AcmeCards';\nexport function AcmeCard() { return null; }\n",
+      },
+    );
+    fs.writeFileSync(
+      path.join(root, 'dist', 'index.mjs'),
+      `${fs.readFileSync(path.join(root, 'dist', 'index.mjs'), 'utf-8')}export function AcmeCard() { return null; }\n`,
+    );
+
+    const records = discoverIntegrationComponents(loaded);
+    expect(records.map(record => record.name).sort()).toEqual([
+      'AcmeCard',
+      'AcmeCards',
+      'AcmeTab',
+      'AcmeTabs',
+    ]);
+    expect(findIntegrationComponentSource(loaded, 'AcmeTab')).toBe(
+      path.join(root, 'src', 'tabs', 'AcmeTabs.tsx'),
+    );
+    expect(findIntegrationComponentDoc(loaded, 'AcmeCard')).toBe(
+      path.join(root, 'src', 'cards', 'AcmeCards.doc.mjs'),
+    );
+    expect(findIntegrationComponentSource(loaded, 'AcmeCard')).toBeNull();
+    expect(
+      records.find(record => record.name === 'AcmeCard')?.sourcePath,
+    ).toBeNull();
+  });
+
+  it('lists a member only a bundle declares, with no source, when the family doc sits at the package root', () => {
+    const loaded = {
+      ...writePackage(
+        {exports: {'.': './dist/index.mjs'}},
+        {
+          'AcmeStrip.doc.mjs': family(
+            'AcmeStrip',
+            "{name: 'AcmeStripItem', description: 'x'}",
+          ).replace('usage:', "import: '@acme/widgets', usage:"),
+          'AcmeStrip.tsx': 'export function AcmeStrip() { return null; }\n',
+          'dist/index.mjs':
+            'export function AcmeStrip() { return null; }\nexport function AcmeStripItem() { return null; }\n',
+        },
+      ),
+      components: root,
+    };
+    expect(namesIn(loaded)).toEqual(['AcmeStrip', 'AcmeStripItem']);
+    expect(findIntegrationComponentSource(loaded, 'AcmeStripItem')).toBeNull();
+  });
+
+  it('lists the members a family doc without its own source imports', () => {
+    const loaded = writePackage(
+      {exports: {'./group': './src/group/index.ts'}},
+      {
+        'src/group/AcmeGroup.doc.mjs': family(
+          'AcmeGroup',
+          "{name: 'AcmeGroupItem', description: 'x'}",
+        ).replace('usage:', "import: '@acme/widgets/group', usage:"),
+        'src/group/index.ts':
+          "export {AcmeGroupItem} from './AcmeGroupItem';\n",
+        'src/group/AcmeGroupItem.tsx':
+          'export function AcmeGroupItem() { return null; }\n',
+      },
+    );
+    expect(namesIn(loaded)).toEqual(['AcmeGroup', 'AcmeGroupItem']);
+    expect(findIntegrationComponentSource(loaded, 'AcmeGroupItem')).toBe(
+      path.join(root, 'src', 'group', 'AcmeGroupItem.tsx'),
+    );
+  });
+
+  it("finds a member's source in the family's folder when the import names built output", () => {
+    const loaded = writePackage(
+      {exports: {'./list': './dist/list/index.js'}},
+      {
+        'src/list/AcmeList.doc.mjs': family(
+          'AcmeList',
+          "{name: 'AcmeListRow', description: 'x'}",
+        ).replace('usage:', "import: '@acme/widgets/list', usage:"),
+        'src/list/AcmeList.tsx':
+          'export function AcmeList() { return null; }\n',
+        'src/list/row.tsx': 'export function AcmeListRow() { return null; }\n',
+        'src/list/row.test.tsx':
+          'export function AcmeListRow() { return null; }\n',
+        'dist/list/index.js':
+          "export {AcmeList} from './list.js';\nexport * from './row.js';\n",
+        'dist/list/list.js': 'export function AcmeList() { return null; }\n',
+        'dist/list/row.js': 'export function AcmeListRow() { return null; }\n',
+      },
+    );
+    expect(namesIn(loaded)).toEqual(['AcmeList', 'AcmeListRow']);
+    expect(findIntegrationComponentSource(loaded, 'AcmeListRow')).toBe(
+      path.join(root, 'src', 'list', 'row.tsx'),
+    );
+    // Until the output exists, the import exports nothing.
+    fs.rmSync(path.join(root, 'dist'), {recursive: true});
+    expect(namesIn(loaded)).toEqual(['AcmeList']);
+  });
+
+  it('lists a member another folder declares, with no source', async () => {
+    const loaded = writePackage(
+      {exports: {'./menu': './src/menu/index.ts'}},
+      {
+        'src/menu/AcmeMenu.doc.mjs': family(
+          'AcmeMenu',
+          "{name: 'AcmeMenuItem', description: 'x'}",
+        ).replace('usage:', "import: '@acme/widgets/menu', usage:"),
+        'src/menu/AcmeMenu.tsx':
+          'export function AcmeMenu() { return null; }\n',
+        'src/menu/index.ts':
+          "export {AcmeMenu} from './AcmeMenu';\nexport {AcmeMenuItem} from '../shared/AcmeMenuItem';\n",
+        'src/shared/AcmeMenuItem.tsx':
+          'export function AcmeMenuItem() { return null; }\n',
+      },
+    );
+    expect(namesIn(loaded)).toEqual(['AcmeMenu', 'AcmeMenuItem']);
+    expect(findIntegrationComponentDoc(loaded, 'AcmeMenuItem')).toBe(
+      path.join(root, 'src', 'menu', 'AcmeMenu.doc.mjs'),
+    );
+    expect(findIntegrationComponentSource(loaded, 'AcmeMenuItem')).toBeNull();
+    // A member without a source is valid: only a doc's own component needs
+    // its same-stem file.
+    const {components, errors} = await discoverValidIntegrationComponents(
+      /** @type {any} */ (loaded),
+    );
+    expect(errors).toEqual([]);
+    expect(components.map(component => component.name).sort()).toEqual([
+      'AcmeMenu',
+      'AcmeMenuItem',
+    ]);
+  });
+
+  it('reads members a binding holds and entries with computed fields', () => {
+    fs.writeFileSync(
+      path.join(root, 'AcmeRows.doc.mjs'),
+      "const describe = text => text;\nconst MEMBERS = [{name: 'AcmeRow', description: describe('A row.')}];\nexport default {type: 'component', name: 'AcmeRows', usage: {description: 'x'}, components: MEMBERS};\n",
+    );
+    fs.writeFileSync(
+      path.join(root, 'AcmeRows.tsx'),
+      'export function AcmeRows() { return null; }\nexport function AcmeRow() { return null; }\n',
+    );
+    expect(names()).toEqual(['AcmeRow', 'AcmeRows']);
+  });
+
+  it("lists the doc's own name when its file keeps its own, and declares replaces once", async () => {
+    writeFamily('Chip', {
+      name: 'AcmeChip',
+      extra: "\n  replaces: 'Badge',",
+      members:
+        "[{name: 'AcmeChip', description: 'x'}, {name: 'AcmeChipIcon', description: 'x'}]",
+      source:
+        'export function Chip() { return null; }\nexport function AcmeChip() { return null; }\nexport function AcmeChipIcon() { return null; }\n',
+    });
+    const {components} =
+      await discoverValidIntegrationComponents(integration());
+    expect(components.map(record => [record.name, record.replaces])).toEqual([
+      ['Chip', 'Badge'],
+      ['AcmeChip', undefined],
+      ['AcmeChipIcon', undefined],
+    ]);
+  });
+
+  it('takes no member name a hidden doc or a replacement in the package claims', () => {
+    writeFamily('menu/AcmeMenu', {
+      name: 'AcmeMenu',
+      members:
+        "[{name: 'AcmeMenuDivider', description: 'x'}, {name: 'Carousel', description: 'x'}, {name: 'AcmeMenuItem', description: 'x'}]",
+      source:
+        'export function AcmeMenu() { return null; }\nexport function AcmeMenuDivider() { return null; }\nexport function Carousel() { return null; }\nexport function AcmeMenuItem() { return null; }\n',
+    });
+    writeComponent('menu/AcmeMenuDivider', {
+      name: "'AcmeMenuDivider'",
+      extra: '\n  hidden: true,',
+    });
+    writeComponent('Slides', {
+      name: "'AcmeCarousel'",
+      extra: "\n  replaces: 'Carousel',",
+      source: 'export function AcmeCarousel() { return null; }\n',
+    });
+    expect(names()).toEqual(['AcmeCarousel', 'AcmeMenu', 'AcmeMenuItem']);
+    expect(findIntegrationComponentDoc(integration(), 'Carousel')).toBeNull();
+  });
+});