@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/component/component.mjs

@@ -19,9 +19,11 @@ import {
   requireCoreDir,
   loadIntegrationsSafely,
   resolveOwners,
+  scopeIntegrationMember,
   classifyScope,
   assertUnambiguousOwners,
   resolveLegacyExternalDoc,
+  legacyExternalKeeps,
   resolveCoreSourcePath,
   resolveUnscopedDoc,
   loadComponentDoc,
@@ -29,6 +31,8 @@ import {
   ComponentAmbiguityError,
   installedComponentPackageVersion,
   resolveComponentReplacement,
+  unscopedComponentOwners,
+  linkComponentResponse,
 } from './_adapter.mjs';
 import {componentList} from './list/list.mjs';
 import {componentDetail} from './detail/detail.mjs';
@@ -254,6 +258,23 @@ async function componentBatch(selectors, options, coreDir) {
  * )>}
  */
 export async function component(name, options = {}) {
+  // Every read resolves the links in the doc text it returns (spec:AST-047
+  // FR9); a batch's results are each a read of their own.
+  return /** @type {any} */ (
+    await linkComponentResponse(
+      await componentRead(name, options),
+      options.cwd ?? process.cwd(),
+    )
+  );
+}
+
+/**
+ * {@link component}, with each `{@link}` in its doc text as written.
+ * @param {string|string[]} [name]
+ * @param {Parameters<typeof component>[1]} [options]
+ * @returns {ReturnType<typeof component>}
+ */
+async function componentRead(name, options = {}) {
   const {
     cwd = process.cwd(),
     list = false,
@@ -354,7 +375,7 @@ export async function component(name, options = {}) {
       requireInstalledSelectorVersion(target, coreDir, loadedIntegrations);
     }
     if (target.name !== name || target.package !== packageScope) {
-      return component(target.name, {...options, package: target.package});
+      return componentRead(target.name, {...options, package: target.package});
     }
     name = target.name;
   }
@@ -393,7 +414,10 @@ export async function component(name, options = {}) {
         dirName,
       );
       if (replacement?.package === packageScope) {
-        return component(replacement.name, {...options, package: packageScope});
+        return componentRead(replacement.name, {
+          ...options,
+          package: packageScope,
+        });
       }
     }
     const scoped = classifyScope(packageScope, {
@@ -421,20 +445,40 @@ export async function component(name, options = {}) {
       // a showcase, so skip discovery entirely.
       if (showcase) {
         return scoped.kind === 'core'
-          ? componentDetailShowcase(dirName, {cwd, name, ownerPackage: owner.package})
-          : componentDetailShowcase(dirName, {cwd, name, resolve: false, ownerPackage: owner.package});
+          ? componentDetailShowcase(dirName, {
+              cwd,
+              name,
+              ownerPackage: owner.package,
+            })
+          : componentDetailShowcase(dirName, {
+              cwd,
+              name,
+              resolve: false,
+              ownerPackage: owner.package,
+            });
       }
       if (blocks) {
         return componentDetailBlocks(dirName, cwd, owner.package);
       }
-      const docs = await loadComponentDoc(owner.docPath, docOpts);
+      const loaded = await loadComponentDoc(owner.docPath, docOpts);
+      // A family member an integration lists under its own name reads as that
+      // member, the way a Core sub-component does below.
+      const docs =
+        scoped.kind === 'integration'
+          ? scopeIntegrationMember(loaded, owner, dirName)
+          : loaded;
       if (props) return componentDetailProps(docs, owner.package);
       return componentDetail(docs, owner, dirName, coreDir);
     }
 
     // Legacy `pkg.astryx.docs` external package.
     if (showcase) {
-      return componentDetailShowcase(dirName, {cwd, name, packageScope, ownerPackage: packageScope});
+      return componentDetailShowcase(dirName, {
+        cwd,
+        name,
+        packageScope,
+        ownerPackage: packageScope,
+      });
     }
     const extDocPath = resolveLegacyExternalDoc(scoped.ext, dirName);
     if (extDocPath) {
@@ -475,18 +519,20 @@ export async function component(name, options = {}) {
     dirName,
   );
   if (replacement) {
-    return component(replacement.name, {
+    return componentRead(replacement.name, {
       ...options,
       package: replacement.package,
     });
   }
 
+  // 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 +544,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);
@@ -510,13 +561,22 @@ export async function component(name, options = {}) {
   ) {
     const owner = effectiveOwners[0];
     if (source) {
-      return componentDetailSource(dirName, owner.sourcePath, {name, ownerPackage: owner.package});
+      return componentDetailSource(dirName, owner.sourcePath, {
+        name,
+        ownerPackage: owner.package,
+      });
     }
     if (showcase) {
       // Integration components don't carry showcases — fail without scanning.
-      return componentDetailShowcase(dirName, {cwd, name, resolve: false, ownerPackage: owner.package});
+      return componentDetailShowcase(dirName, {
+        cwd,
+        name,
+        resolve: false,
+        ownerPackage: owner.package,
+      });
     }
-    const docs = await loadComponentDoc(owner.docPath, docOpts);
+    const loaded = await loadComponentDoc(owner.docPath, docOpts);
+    const docs = scopeIntegrationMember(loaded, owner, dirName);
     if (props) return componentDetailProps(docs, owner.package);
     return componentDetail(docs, owner, dirName, coreDir);
   }
@@ -531,7 +591,11 @@ export async function component(name, options = {}) {
     );
   }
   if (showcase) {
-    return componentDetailShowcase(dirName, {cwd, name, ownerPackage: CORE_PACKAGE});
+    return componentDetailShowcase(dirName, {
+      cwd,
+      name,
+      ownerPackage: CORE_PACKAGE,
+    });
   }
 
   const resolved = await resolveUnscopedDoc(dirName, {coreDir, cwd, name});
@@ -548,7 +612,10 @@ export async function component(name, options = {}) {
   const sub = scopeSubComponent(docs, dirName, coreDir);
   if (sub) {
     if (props)
-      return componentDetailProps({props: sub.matchingComponent.props}, resolved.resolvedOwnerPackage);
+      return componentDetailProps(
+        {props: sub.matchingComponent.props},
+        resolved.resolvedOwnerPackage,
+      );
     return componentDetail(
       sub.scoped,
       {

package/api/component/component.test.mjs

@@ -13,6 +13,7 @@ import {describe, it, expect} from 'vitest';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {component} from './component.mjs';
+import {search} from '../search/search.mjs';
 import {AstryxError} from '../error.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
 
@@ -92,6 +93,85 @@ describe('component dispatcher — detail levels on list', () => {
   );
 });
 
+describe('component list — components whose docs live in a family folder', () => {
+  it('lists HStack, VStack and Heading at every detail level, each with its own import', async () => {
+    const {docs: stackDoc} = await import(
+      path.join(REPO, 'packages', 'core', 'src', 'Stack', 'Stack.doc.mjs')
+    );
+    const vstackMember = stackDoc.components.find(c => c.name === 'VStack');
+
+    const names = await component(undefined, {cwd, list: true});
+    const listed = Object.values(names.data.components).flat();
+    for (const name of ['HStack', 'VStack', 'Heading']) {
+      expect(listed).toContainEqual({name, package: '@astryxdesign/core'});
+    }
+
+    const compact = await component(undefined, {cwd, list: true, detail: 'compact'});
+    const brief = Object.values(compact.data.components).flat();
+    expect(brief.find(e => e.name === 'VStack')).toEqual({
+      name: 'VStack',
+      package: '@astryxdesign/core',
+      description: vstackMember.description,
+      import: '@astryxdesign/core/VStack',
+    });
+
+    const full = await component(undefined, {cwd, list: true, detail: 'full'});
+    const entry = Object.values(full.data.components)
+      .flat()
+      .find(e => e.name === 'VStack');
+    // Shaped like every other full entry (a component doc plus its package):
+    // the member's own name, display name and summary, and no scoping field
+    // the full-entry type does not describe.
+    expect(entry).toEqual({
+      name: 'VStack',
+      package: '@astryxdesign/core',
+      displayName: vstackMember.displayName,
+      group: stackDoc.group,
+      category: stackDoc.category,
+      usage: {description: vstackMember.description},
+      props: vstackMember.props,
+      theming: stackDoc.theming,
+      import: '@astryxdesign/core/VStack',
+    });
+  }, SLOW);
+
+  it('prints each one\'s own import path in the list, the detail, and search', async () => {
+    // The path `component <Name>` prints is the one docs and examples teach:
+    // the component's own entry point, never its family's (/Stack, /Text) or
+    // a re-export (/Layout).
+    const compact = Object.values(
+      (await component(undefined, {cwd, list: true, detail: 'compact'})).data.components,
+    ).flat();
+    const full = Object.values(
+      (await component(undefined, {cwd, list: true, detail: 'full'})).data.components,
+    ).flat();
+    const textList = (await runCli(['component', '--list'], cwd)).stdout;
+    const textCompact = (
+      await runCli(['component', '--list', '--detail', 'compact'], cwd)
+    ).stdout;
+    /** The `import:` line of a text record, found by its `name:` line. */
+    const textImport = (text, name) =>
+      new RegExp(`^name:\\s+${name}\\n(?:(?!name:).*\\n)*?import:\\s+(\\S+)`, 'm').exec(
+        text,
+      )?.[1];
+    for (const name of ['VStack', 'HStack', 'Heading']) {
+      const expected = `@astryxdesign/core/${name}`;
+      expect(compact.find(e => e.name === name)?.import).toBe(expected);
+      expect((await component(name, {cwd})).data.import).toBe(expected);
+      const hits = (await search(name, {cwd, type: 'component'})).data.results;
+      expect(hits.find(r => r.name === name)?.import).toBe(expected);
+      expect(textImport(textList, name)).toBe(expected);
+      expect(textImport(textCompact, name)).toBe(expected);
+    }
+    // The full level spreads a component's own doc, which states no import
+    // (Button's entry has none either); a member's entry is scoped to the
+    // member and states its own.
+    for (const name of ['VStack', 'HStack']) {
+      expect(full.find(e => e.name === name)?.import).toBe(`@astryxdesign/core/${name}`);
+    }
+  }, SLOW);
+});
+
 describe('component dispatcher — projection precedence (locked)', () => {
   it(
     '--props routes to component.detail.props',

package/api/component/doc-links.test.mjs

@@ -0,0 +1,386 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Links in a component doc's text and a topic's description
+ * (spec:AST-047 FR9): a read resolves each `{@link <target>}` to the command
+ * that opens its doc, in text and JSON, the way a topic section's links read.
+ * Code fields and code ticks show the syntax as written.
+ *
+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
+ * dynamically import a module from outside the project root.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {component} from './component.mjs';
+import {CORE_PACKAGE, linkComponentResponse} from './_adapter.mjs';
+import {docs} from '../docs/docs.mjs';
+import {search} from '../search/search.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const SLOW = 60_000;
+
+let tmpDir;
+
+const ACME_BUTTON = {
+  type: 'component',
+  name: 'AcmeButton',
+  displayName: 'Acme Button',
+  usage: {
+    description:
+      'A button. Set it up as {@link generic:acme-setup} says; theme it with {@link @astryxdesign/cli:generic:theme}.',
+    bestPractices: [
+      {
+        guidance: true,
+        description: 'Pair it with {@link component:AcmeButton}.',
+      },
+    ],
+  },
+  props: [
+    {
+      name: 'tone',
+      type: 'string',
+      description:
+        'Read {@link generic:acme-setup}; write `{@link generic:acme-setup}` to link.',
+      default: "'{@link generic:acme-setup}'",
+    },
+  ],
+  examples: [
+    {
+      label: 'As {@link generic:acme-setup} shows',
+      code: '// {@link generic:acme-setup}',
+    },
+  ],
+};
+
+const ACME_SETUP = {
+  type: 'generic',
+  name: 'acme-setup',
+  title: 'Acme setup',
+  description:
+    'Set up Acme, then theme it as {@link @astryxdesign/cli:generic:theme} says.',
+  sections: [
+    {title: 'Overview', content: [{type: 'prose', text: 'Install it.'}]},
+  ],
+};
+
+function scaffold() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    "export default {integrations: ['@acme/widgets']};\n",
+  );
+  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(path.join(pkgDir, 'components'), {recursive: true});
+  fs.mkdirSync(path.join(pkgDir, 'docs'), {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    "export default {components: './components', docs: './docs'};\n",
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+    `export default ${JSON.stringify(ACME_BUTTON, null, 2)};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+    'export function AcmeButton() { return null; }\n',
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'docs', 'acme-setup.doc.mjs'),
+    `export default ${JSON.stringify(ACME_SETUP, null, 2)};\n`,
+  );
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-component-links-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe("a link in a component doc's text", () => {
+  it(
+    "reads as the command that opens its doc, against the integration's own docs",
+    async () => {
+      scaffold();
+      const read = /** @type {any} */ (
+        await component('AcmeButton', {cwd: tmpDir})
+      );
+      expect(read.type).toBe('component.detail');
+      expect(read.data.usage.description).toBe(
+        'A button. Set it up as `astryx docs acme-setup` says; theme it with `astryx docs theme`.',
+      );
+      expect(read.data.usage.bestPractices[0].description).toBe(
+        'Pair it with `astryx component AcmeButton --package @acme/widgets`.',
+      );
+      // Code ticks and code fields show the syntax as written.
+      expect(read.data.props[0].description).toBe(
+        'Read `astryx docs acme-setup`; write `{@link generic:acme-setup}` to link.',
+      );
+      expect(read.data.props[0].default).toBe("'{@link generic:acme-setup}'");
+      expect(read.data.examples[0]).toEqual({
+        label: 'As `astryx docs acme-setup` shows',
+        code: '// {@link generic:acme-setup}',
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'reads the same in `astryx discover <package>/<Component>`',
+    async () => {
+      scaffold();
+      const json = await runCli(
+        ['--json', 'discover', '@acme/widgets/AcmeButton'],
+        tmpDir,
+      );
+      expect(json.status).toBe(0);
+      expect(JSON.parse(json.stdout).data.usage.description).toBe(
+        'A button. Set it up as `astryx docs acme-setup` says; theme it with `astryx docs theme`.',
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    "reads the same in a search hit's description",
+    async () => {
+      scaffold();
+      const found = /** @type {any} */ (
+        await search('AcmeButton', {cwd: tmpDir, type: 'component'})
+      );
+      const hit = found.data.results.find(
+        (/** @type {any} */ result) => result.name === 'AcmeButton',
+      );
+      expect(hit.description).toBe(
+        'A button. Set it up as `astryx docs acme-setup` says; theme it with `astryx docs theme`.',
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'reads the same in the props projection, in JSON, and in text',
+    async () => {
+      scaffold();
+      const props = /** @type {any} */ (
+        await component('AcmeButton', {cwd: tmpDir, props: true})
+      );
+      expect(props.data[0].description).toBe(
+        'Read `astryx docs acme-setup`; write `{@link generic:acme-setup}` to link.',
+      );
+
+      const json = await runCli(['--json', 'component', 'AcmeButton'], tmpDir);
+      expect(json.status).toBe(0);
+      expect(JSON.parse(json.stdout).data.usage.description).toContain(
+        '`astryx docs acme-setup`',
+      );
+
+      const text = await runCli(['component', 'AcmeButton'], tmpDir);
+      expect(text.status).toBe(0);
+      expect(text.stdout).toContain('`astryx docs acme-setup`');
+      expect(text.stdout).not.toContain('{@link generic:acme-setup} says');
+    },
+    SLOW,
+  );
+
+  it("resolves a Core component's links against the CLI's own docs", async () => {
+    const read = await linkComponentResponse(
+      {
+        type: 'component.detail',
+        package: CORE_PACKAGE,
+        data: {
+          usage: {description: 'Theme it with {@link generic:theme}.'},
+          props: [
+            {
+              name: 'x',
+              type: 'string',
+              description: 'See {@link generic:nope}.',
+            },
+          ],
+        },
+      },
+      tmpDir,
+    );
+    expect(read.data.usage.description).toBe(
+      'Theme it with `astryx docs theme`.',
+    );
+    // A link that names no doc prints as written.
+    expect(read.data.props[0].description).toBe('See {@link generic:nope}.');
+  });
+});
+
+describe("a link in a topic's description", () => {
+  it(
+    'reads as the command that opens its doc, in the detail and the list',
+    async () => {
+      scaffold();
+      const detail = /** @type {any} */ (
+        await docs('acme-setup', undefined, {cwd: tmpDir, full: true})
+      );
+      expect(detail.data.description).toBe(
+        'Set up Acme, then theme it as `astryx docs theme` says.',
+      );
+      const listed = /** @type {any} */ (
+        await docs(undefined, undefined, {cwd: tmpDir})
+      );
+      expect(
+        listed.data.find((/** @type {any} */ t) => t.topic === 'acme-setup')
+          .description,
+      ).toBe('Set up Acme, then theme it as `astryx docs theme` says.');
+    },
+    SLOW,
+  );
+});
+
+describe("a link in a guide's description, as the docs tree shows it", () => {
+  it(
+    'reads as the command that opens its doc in the guide and its namespace',
+    async () => {
+      const expected =
+        'Document a theme by extending the core theme topic, so an app reads it in `astryx docs theme`.';
+      const guide = /** @type {any} */ (
+        await docs(
+          'cli/integrations/building-blocks/themes/document-the-theme',
+          undefined,
+          {cwd: tmpDir, full: true},
+        )
+      );
+      expect(guide.data.description).toBe(expected);
+      const namespace = /** @type {any} */ (
+        await docs('cli/integrations/building-blocks/themes', undefined, {
+          cwd: tmpDir,
+        })
+      );
+      const child = namespace.data.slots
+        .flatMap((/** @type {any} */ slot) => slot.children)
+        .find((/** @type {any} */ each) => each.name === 'document-the-theme');
+      expect(child.summary).toBe(expected);
+    },
+    SLOW,
+  );
+});
+
+describe("a reference block's summary of another package's component", () => {
+  it(
+    "resolves the summary's links against the component's own package",
+    async () => {
+      const write = (
+        /** @type {string} */ file,
+        /** @type {string} */ text,
+      ) => {
+        fs.mkdirSync(path.dirname(path.join(tmpDir, file)), {recursive: true});
+        fs.writeFileSync(path.join(tmpDir, file), text);
+      };
+      const doc = (/** @type {object} */ value) =>
+        `export default ${JSON.stringify(value)};\n`;
+      write('package.json', JSON.stringify({name: 'consumer'}));
+      write(
+        'astryx.config.mjs',
+        "export default {integrations: ['@acme/widgets', '@acme/other']};\n",
+      );
+      const widgets = 'node_modules/@acme/widgets';
+      write(
+        `${widgets}/package.json`,
+        JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+      );
+      write(
+        `${widgets}/astryx.integration.mjs`,
+        "export default {docs: './docs'};\n",
+      );
+      write(
+        `${widgets}/docs/acme-ref.doc.mjs`,
+        doc({
+          type: 'generic',
+          name: 'acme-ref',
+          title: 'Acme ref',
+          description: 'Where the card is documented.',
+          sections: [
+            {
+              title: 'Overview',
+              content: [
+                {
+                  type: 'reference',
+                  target: '@acme/other:component:OtherCardBody',
+                },
+              ],
+            },
+          ],
+        }),
+      );
+      const other = 'node_modules/@acme/other';
+      write(
+        `${other}/package.json`,
+        JSON.stringify({name: '@acme/other', version: '1.0.0'}),
+      );
+      write(
+        `${other}/astryx.integration.mjs`,
+        "export default {components: './components', docs: './docs'};\n",
+      );
+      write(
+        `${other}/docs/other-setup.doc.mjs`,
+        doc({
+          type: 'generic',
+          name: 'other-setup',
+          title: 'Other setup',
+          description: 'Set up Other.',
+          sections: [
+            {
+              title: 'Overview',
+              content: [{type: 'prose', text: 'Install it.'}],
+            },
+          ],
+        }),
+      );
+      write(
+        `${other}/components/OtherCard.doc.mjs`,
+        doc({
+          type: 'component',
+          name: 'OtherCard',
+          displayName: 'Other Card',
+          usage: {description: 'A card.'},
+          props: [],
+        }),
+      );
+      write(
+        `${other}/components/OtherCard.tsx`,
+        'export function OtherCard() { return null; }\n',
+      );
+      write(
+        `${other}/components/OtherCardBody.doc.mjs`,
+        doc({
+          type: 'component',
+          name: 'OtherCardBody',
+          displayName: 'Other Card Body',
+          subComponentOf: 'OtherCard',
+          description: 'Its body, set up as {@link generic:other-setup} says.',
+          props: [],
+        }),
+      );
+      write(
+        `${other}/components/OtherCardBody.tsx`,
+        'export function OtherCardBody() { return null; }\n',
+      );
+
+      const read = /** @type {any} */ (
+        await docs('acme-ref', undefined, {cwd: tmpDir, full: true})
+      );
+
+      // `other-setup` is @acme/other's topic: from @acme/widgets, the
+      // linking package, the same link names no doc.
+      expect(read.data.sections[0].content[0].text).toContain(
+        'Its body, set up as `astryx docs other-setup` says.',
+      );
+    },
+    SLOW,
+  );
+});