@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

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,100 @@ 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('answers a Core-scoped lookup of a member with that member, as the unscoped lookup does', async () => {
+    for (const name of ['HStack', 'VStack']) {
+      const unscoped = await component(name, {cwd});
+      const scoped = await component(name, {
+        cwd,
+        package: '@astryxdesign/core',
+      });
+      expect(scoped.data.name).toBe(name);
+      expect(scoped.data.parentDoc).toBe('Stack');
+      expect(scoped.data.import).toBe(`@astryxdesign/core/${name}`);
+      expect(scoped.data.props).toEqual(unscoped.data.props);
+      expect(scoped.data.props.length).toBeGreaterThan(0);
+    }
+  }, 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(
+          'authoring/building-blocks/themes/document-the-theme',
+          undefined,
+          {cwd: tmpDir, full: true},
+        )
+      );
+      expect(guide.data.description).toBe(expected);
+      const namespace = /** @type {any} */ (
+        await docs('authoring/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,
+  );
+});