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

package/foundation/discovery/component-discovery.d.mts

@@ -115,19 +115,36 @@ export function discoverExternalComponentsGrouped(docsDir: string): Record<strin
  * @returns {string | null}
  */
 export function findExternalComponentDoc(docsDir: string, name: string): string | null;
+/** @param {string} docPath */
+export function docStem(docPath: string): string;
+/**
+ * Visit every component doc under an integration's components root, hidden
+ * ones included, in discovery order, with its stem.
+ * @param {string | undefined} componentsDir
+ * @param {(docPath: string, stem: string) => void} visit
+ */
+export function forEachIntegrationDoc(componentsDir: string | undefined, visit: (docPath: string, stem: string) => void): void;
 /**
  * Discover ownership records for the components contributed by a single loaded
  * integration. Scans the integration's resolved `components` dir for same-stem
- * doc files and records each with owner package + issuesUrl + sourcePath.
+ * doc files and records each with owner package + issuesUrl + sourcePath. A doc
+ * that names a differently named export of its file is recorded under that
+ * export unless the name is taken: every doc's file name (a hidden doc's too),
+ * a Core name a doc in the package replaces, and a name an earlier doc records.
  *
  * @param {{name: string, components?: string, issuesUrl?: string}} integration
  *   a single entry from `loadedIntegrations` (lib/integrations.mjs)
+ * @param {{documentedNames?: boolean}} [options] `documentedNames: false`
+ *   records each doc under its file name alone, without reading the names
+ *   docs document: for a caller that needs only what each doc says
  * @returns {Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>}
  */
 export function discoverIntegrationComponents(integration: {
     name: string;
     components?: string;
     issuesUrl?: string;
+}, { documentedNames }?: {
+    documentedNames?: boolean;
 }): Array<{
     name: string;
     package: string;
@@ -141,9 +158,12 @@ export function discoverIntegrationComponents(integration: {
  * Invalid metadata or a missing same-stem source removes only that component;
  * callers can report the returned errors while retaining valid siblings. A
  * component whose doc sets `replaces` carries the value as written; the
- * component replacement resolver decides what it means.
+ * component replacement resolver decides what it means. A doc that fails to
+ * load is reported under its file name: what it says cannot be trusted.
  *
  * @param {{name: string, components?: string, issuesUrl?: string}} integration
+ * @param {{documentedNames?: boolean}} [options] as for
+ *   {@link discoverIntegrationComponents}
  * @returns {Promise<{
  *   components: Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>,
  *   discovered: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>,
@@ -154,6 +174,8 @@ export function discoverValidIntegrationComponents(integration: {
     name: string;
     components?: string;
     issuesUrl?: string;
+}, options?: {
+    documentedNames?: boolean;
 }): Promise<{
     components: Array<{
         name: string;
@@ -177,10 +199,43 @@ export function discoverValidIntegrationComponents(integration: {
         message: string;
     }>;
 }>;
+/**
+ * How an owner holds a component name, which the owner rule
+ * ({@link unscopedComponentOwners}) reads: `core` when Core documents it;
+ * `file` when an integration doc named after its file is recorded under it;
+ * `doc` when only a doc records it: an export name, or the file name of a doc
+ * recorded under another export.
+ * @typedef {'core' | 'file' | 'doc'} NameHold
+ */
+/**
+ * How a discovered integration record holds its name.
+ * @param {{name: string, docPath: string|null}} record
+ * @returns {'file' | 'doc'}
+ */
+export function integrationRecordHold(record: {
+    name: string;
+    docPath: string | null;
+}): "file" | "doc";
+/**
+ * The integration component a name finds, as discovery records it, and its
+ * hold: the same-stem doc first, then a doc that records the name.
+ *
+ * @param {{components?: string}} integration
+ * @param {string} name
+ * @returns {{docPath: string, sourcePath: string|null, hold: 'file' | 'doc'} | null}
+ */
+export function findIntegrationComponent(integration: {
+    components?: string;
+}, name: string): {
+    docPath: string;
+    sourcePath: string | null;
+    hold: "file" | "doc";
+} | null;
 /**
  * Find an integration component's doc file by name within a loaded
  * integration's resolved `components` dir. Honors the same-stem convention
- * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`.
+ * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`, and finds a
+ * doc that records the component under a differently named export of its file.
  *
  * @param {{components?: string}} integration
  * @param {string} name bare component name (no `XDS`/`Astryx` prefix)
@@ -190,9 +245,9 @@ export function findIntegrationComponentDoc(integration: {
     components?: string;
 }, name: string): string | null;
 /**
- * Find an integration component's swizzleable source file (`{Name}.tsx`) by
- * name within a loaded integration's resolved `components` dir. Returns null
- * when the integration ships docs without source.
+ * Find an integration component's swizzleable source file by name within a
+ * loaded integration's resolved `components` dir: the same-stem `{Name}.tsx`
+ * of its doc. Returns null when the integration ships docs without source.
  *
  * @param {{components?: string}} integration
  * @param {string} name bare component name
@@ -201,6 +256,20 @@ export function findIntegrationComponentDoc(integration: {
 export function findIntegrationComponentSource(integration: {
     components?: string;
 }, name: string): string | null;
+/**
+ * The owner rule: an owner that holds a name only because a doc records it
+ * (`hold: 'doc'`) yields to Core and to every file-named owner; `--package`
+ * still reaches it. Surfaces resolve a replacement first, then this rule, then
+ * which docs load.
+ *
+ * @template {{hold?: string}} T
+ * @param {T[]} owners each with its {@link NameHold}; an owner without one
+ *   counts as Core's or file-named
+ * @returns {T[]}
+ */
+export function unscopedComponentOwners<T extends {
+    hold?: string;
+}>(owners: T[]): T[];
 /**
  * Build a flat list of ownership records for ALL discoverable components —
  * core (built-in) plus every loaded integration. This is the authoritative
@@ -229,3 +298,11 @@ export function discoverOwnedComponents(coreDir: string, loadedIntegrations?: Ar
 }>;
 /** The owner package name for built-in (core) components. */
 export const CORE_PACKAGE: import("../../authoring/index.js").ProviderId;
+/**
+ * How an owner holds a component name, which the owner rule
+ * ({@link unscopedComponentOwners}) reads: `core` when Core documents it;
+ * `file` when an integration doc named after its file is recorded under it;
+ * `doc` when only a doc records it: an export name, or the file name of a doc
+ * recorded under another export.
+ */
+export type NameHold = "core" | "file" | "doc";

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

@@ -0,0 +1,293 @@
+// 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.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  discoverIntegrationComponents,
+  discoverValidIntegrationComponents,
+  findIntegrationComponent,
+  findIntegrationComponentDoc,
+  findIntegrationComponentSource,
+  unscopedComponentOwners,
+} from './component-discovery.mjs';
+
+/** @type {string} the integration's components root */
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-export-names-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/**
+ * Write a component doc, and its same-stem source when given.
+ * @param {string} file path under the root, without extension
+ * @param {{name: string, source?: string, form?: 'default' | 'docs', suffix?: string, extra?: string}} options
+ *   `name` is written as a JavaScript expression
+ */
+function writeComponent(
+  file,
+  {name, source, form = 'default', suffix = '.doc.mjs', extra = ''},
+) {
+  const target = path.join(root, file);
+  fs.mkdirSync(path.dirname(target), {recursive: true});
+  const doc = `{\n  type: 'component',\n  name: ${name},\n  usage: {description: 'A component.'},\n  props: [],${extra}\n}`;
+  fs.writeFileSync(
+    `${target}${suffix}`,
+    form === 'default'
+      ? `export default ${doc};\n`
+      : `export const docs = ${doc};\n`,
+  );
+  if (source != null) fs.writeFileSync(`${target}.tsx`, source);
+}
+
+const integration = () => ({name: '@acme/widgets', components: root});
+
+/** @returns {string[]} */
+const names = () =>
+  discoverIntegrationComponents(integration())
+    .map(record => record.name)
+    .sort();
+
+describe('integration components whose doc names another export of its file', () => {
+  it('records a doc beside a kebab-case file under the export its doc names', async () => {
+    writeComponent('artifact-viewer', {
+      name: "'AcmeArtifactViewer'",
+      source: 'export function AcmeArtifactViewer() { return null; }\n',
+    });
+
+    const [record] = discoverIntegrationComponents(integration());
+    expect(record).toMatchObject({
+      name: 'AcmeArtifactViewer',
+      package: '@acme/widgets',
+      docPath: path.join(root, 'artifact-viewer.doc.mjs'),
+      sourcePath: path.join(root, 'artifact-viewer.tsx'),
+    });
+    expect(
+      (await discoverValidIntegrationComponents(integration())).components,
+    ).toEqual([expect.objectContaining({name: 'AcmeArtifactViewer'})]);
+    expect(
+      findIntegrationComponentDoc(integration(), 'AcmeArtifactViewer'),
+    ).toBe(record.docPath);
+    expect(findIntegrationComponentDoc(integration(), 'artifact-viewer')).toBe(
+      record.docPath,
+    );
+    expect(
+      findIntegrationComponentSource(integration(), 'AcmeArtifactViewer'),
+    ).toBe(record.sourcePath);
+  });
+
+  it('leaves a name to Core or a file-named component over one a doc records', () => {
+    const core = {package: '@astryxdesign/core', hold: 'core'};
+    const fileNamed = {package: '@beta/kit', hold: 'file'};
+    const documented = {package: '@acme/widgets', hold: 'doc'};
+    expect(unscopedComponentOwners([documented, fileNamed])).toEqual([
+      fileNamed,
+    ]);
+    expect(unscopedComponentOwners([core, documented])).toEqual([core]);
+    expect(unscopedComponentOwners([documented])).toEqual([documented]);
+
+    // Badge.doc.mjs records AcmeBadge, so the doc holds both names only
+    // because it documents them; Panel.doc.mjs names an export another file
+    // has, so it keeps its file name.
+    writeComponent('Badge', {
+      name: "'AcmeBadge'",
+      source: 'export function AcmeBadge() { return null; }\n',
+    });
+    writeComponent('Panel', {
+      name: "'AcmeChip'",
+      source: 'export function AcmeChip() { return null; }\n',
+    });
+    writeComponent('AcmeChip', {
+      name: "'AcmeChip'",
+      source: 'export function AcmeChip() { return null; }\n',
+    });
+    const hold = (/** @type {string} */ name) =>
+      findIntegrationComponent(integration(), name)?.hold;
+    expect(hold('AcmeBadge')).toBe('doc');
+    expect(hold('Badge')).toBe('doc');
+    expect(hold('Panel')).toBe('file');
+    expect(hold('AcmeChip')).toBe('file');
+  });
+
+  it('takes no name a hidden doc or a replacement in the package claims', () => {
+    // A hidden doc is still the file named AcmeCarousel: its name stays its own.
+    writeComponent('AcmeCarousel', {
+      name: "'AcmeCarousel'",
+      extra: '\n  hidden: true,',
+      source: 'export function AcmeCarousel() { return null; }\n',
+    });
+    writeComponent('gallery/Slides', {
+      name: "'AcmeCarousel'",
+      source: 'export function AcmeCarousel() { return null; }\n',
+    });
+    // A doc in the package replaces Carousel, so that name answers with it.
+    writeComponent('Pager', {
+      name: "'AcmePager'",
+      extra: "\n  replaces: 'Carousel',",
+      source: 'export function AcmePager() { return null; }\n',
+    });
+    writeComponent('Kit', {
+      name: "'Carousel'",
+      source: 'export function Carousel() { return null; }\n',
+    });
+
+    expect(names()).toEqual(['AcmePager', 'Kit', 'Slides']);
+    expect(findIntegrationComponentDoc(integration(), 'AcmeCarousel')).toBe(
+      path.join(root, 'AcmeCarousel.doc.mjs'),
+    );
+    expect(findIntegrationComponentDoc(integration(), 'Carousel')).toBeNull();
+  });
+
+  it('settles a name two docs document by path, the same in every locale', () => {
+    // By UTF-16 code unit `B/` sorts before `a/`; a locale's collation puts
+    // `a/` first.
+    for (const [file, stem] of [
+      ['a/Alpha', 'Alpha'],
+      ['B/Beta', 'Beta'],
+    ]) {
+      writeComponent(file, {
+        name: "'Twin'",
+        source: `export function Twin() { return null; }\n// ${stem}\n`,
+      });
+    }
+
+    expect(names()).toEqual(['Alpha', 'Twin']);
+    expect(findIntegrationComponentDoc(integration(), 'Twin')).toBe(
+      path.join(root, 'B', 'Beta.doc.mjs'),
+    );
+  });
+
+  it('reads a name a spread can override, and reports an unreadable doc under its file name', async () => {
+    fs.writeFileSync(
+      path.join(root, 'Based.doc.mjs'),
+      "const base = {\n  name: 'Based',\n  type: 'component',\n  usage: {description: 'x'},\n  props: [],\n};\nexport default {...base, name: 'AcmeBased'};\n",
+    );
+    fs.writeFileSync(
+      path.join(root, 'Based.tsx'),
+      'export function AcmeBased() { return null; }\n',
+    );
+    writeComponent('Throws', {
+      name: "'AcmeThrows'",
+      source: 'export function AcmeThrows() { return null; }\n',
+    });
+    const throws = path.join(root, 'Throws.doc.mjs');
+    fs.writeFileSync(
+      throws,
+      `throw new Error('boom');\n${fs.readFileSync(throws, 'utf-8')}`,
+    );
+
+    expect(names()).toEqual(['AcmeBased', 'AcmeThrows']);
+    const {errors} = await discoverValidIntegrationComponents(integration());
+    expect(errors).toEqual([
+      {
+        name: 'Throws',
+        message: 'Component "Throws" has invalid metadata: boom',
+      },
+    ]);
+  });
+
+  it('reads a legacy export, a .doc.ts doc and a re-exported component the same way', () => {
+    writeComponent('Slides', {
+      name: "'AcmeCarousel'",
+      form: 'docs',
+      source: "export {AcmeCarousel} from './carousel/impl';\n",
+    });
+    fs.mkdirSync(path.join(root, 'carousel'));
+    fs.writeFileSync(
+      path.join(root, 'carousel', 'impl.tsx'),
+      'export function AcmeCarousel() { return null; }\n',
+    );
+    writeComponent('Pager', {
+      name: "'AcmePager'",
+      suffix: '.doc.ts',
+      source: 'export const AcmePager = () => null;\n',
+    });
+
+    expect(names()).toEqual(['AcmeCarousel', 'AcmePager']);
+  });
+
+  it('keeps the file name for every doc that reads as before', async () => {
+    // Named after its file.
+    writeComponent('AcmeBadge', {
+      name: "'AcmeBadge'",
+      source: 'export function AcmeBadge() { return null; }\n',
+    });
+    // The file exports its own name, so that name stays.
+    writeComponent('Chip', {
+      name: "'AcmeChip'",
+      source:
+        'export function Chip() { return null; }\nexport function AcmeChip() { return null; }\n',
+    });
+    // The doc names an export the file does not have.
+    writeComponent('Menu', {
+      name: "'AcmeMenu'",
+      source: 'export function Dropdown() { return null; }\n',
+    });
+    // A type is not a runtime export.
+    writeComponent('Shape', {
+      name: "'AcmeShape'",
+      source: 'export type AcmeShape = {id: string};\n',
+    });
+    // A name the doc computes is not read.
+    writeComponent('Tile', {
+      name: "`${'Acme'}Tile`",
+      source: 'export function AcmeTile() { return null; }\n',
+    });
+    // Another file already has the name.
+    writeComponent('Panel', {
+      name: "'AcmeBadge'",
+      source: 'export function AcmeBadge() { return null; }\n',
+    });
+    // No source beside it.
+    writeComponent('Orphan', {name: "'AcmeOrphan'"});
+
+    expect(names()).toEqual([
+      'AcmeBadge',
+      'Chip',
+      'Menu',
+      'Orphan',
+      'Panel',
+      'Shape',
+      'Tile',
+    ]);
+    for (const name of [
+      'AcmeChip',
+      'AcmeMenu',
+      'AcmeShape',
+      'AcmeTile',
+      'AcmeOrphan',
+    ]) {
+      expect(findIntegrationComponentDoc(integration(), name)).toBeNull();
+    }
+    expect(
+      (await discoverValidIntegrationComponents(integration())).errors,
+    ).toEqual([
+      {
+        name: 'Orphan',
+        message:
+          'Component "Orphan" is missing its same-stem source file Orphan.tsx.',
+      },
+    ]);
+  });
+
+  it('still leaves a hidden doc out', () => {
+    writeComponent('Slides', {
+      name: "'AcmeCarousel'",
+      extra: '\n  hidden: true,',
+      source: 'export function AcmeCarousel() { return null; }\n',
+    });
+
+    expect(names()).toEqual([]);
+  });
+});