@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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

package/api/discover/_adapter.d.mts

@@ -36,19 +36,47 @@ export function describeInstalled(project: Project | undefined, scanned: Scanned
  * @returns {boolean}
  */
 export function hasSources(project: Project | undefined): boolean;
+/**
+ * The integrations installed for the computer that a project could add, as
+ * available entries with the project's install command (spec AST-081 FR12).
+ * Empty outside a project, where they load instead.
+ * @param {Project | undefined} project
+ * @param {Array<{name: string}>} installed
+ * @param {Set<string>} declared
+ * @param {(name: string, version?: string) => string} add
+ * @returns {Promise<import('./discover.type.mjs').DiscoverAvailableEntry[]>}
+ */
+export function computerAvailableEntries(project: Project | undefined, installed: Array<{
+    name: string;
+}>, declared: Set<string>, add: (name: string, version?: string) => string): Promise<import("./discover.type.mjs").DiscoverAvailableEntry[]>;
 /**
  * Package names the project's package.json declares in any dependency field.
  * @param {Project | undefined} project
  * @returns {Set<string>}
  */
 export function declaredDependencies(project: Project | undefined): Set<string>;
+/**
+ * What the project's own package.json, the nearest one above the folder
+ * discover runs in, declares among the official packages.
+ * @param {Project | undefined} project
+ * @param {OfficialPackage[]} official
+ * @returns {OfficialDeclarations}
+ */
+export function officialDeclarations(project: Project | undefined, official: OfficialPackage[]): OfficialDeclarations;
 /**
  * The command that adds a package with the project's package manager. Discover
- * only prints it; it never runs it.
+ * only prints it; it never runs it. Asked for one version, it adds that
+ * version. Given the official list, it otherwise pins an official package to
+ * what its entry names (spec:AST-051 FR2): the project's Core version or
+ * declared Core range, else the latest release. A range is quoted, because
+ * `^`, `<`, `>`, `|` and spaces mean something to a shell.
  * @param {Project | undefined} project
+ * @param {{official?: OfficialPackage[]}} [options]
  * @returns {(name: string, version?: string) => string}
  */
-export function addCommand(project: Project | undefined): (name: string, version?: string) => string;
+export function addCommand(project: Project | undefined, { official }?: {
+    official?: OfficialPackage[];
+}): (name: string, version?: string) => string;
 /**
  * The per-user cache directory the saved copies live in, never inside a
  * project. Standard platform locations only.
@@ -56,15 +84,17 @@ export function addCommand(project: Project | undefined): (name: string, version
  */
 export function defaultCacheDir(): string;
 /**
- * Call every discover source — the project's `discover` first, then each
- * integration's in load order — once per distinct function. A source that
- * throws, times out, or returns an invalid catalog falls back to its saved copy;
- * with none, it is reported and adds nothing. The others always count.
+ * Call every discover source (see {@link callOwnSources}), then read the
+ * official list (spec:AST-051 FR11). The list comes last, so a source keeps
+ * its entry for an official package, or for any package of the same
+ * integration (FR7); the list adds the official packages no source covers.
+ * The result stays in source order; discover puts official packages first
+ * only where it shows them ({@link officialFirst}).
  *
  * @param {Project | undefined} project
- * @param {{package?: string, version?: string}} [request] ask for one package,
- *   and optionally one version's contributions
- * @param {{cacheDir?: string, timeoutMs?: number}} [options]
+ * @param {{package?: string, version?: string}} [request]
+ * @param {{cacheDir?: string, timeoutMs?: number, official?: OfficialList}} [options]
+ *   `official`: the list {@link officialList} read; read here when absent
  * @returns {Promise<CatalogResult>}
  */
 export function callSources(project: Project | undefined, request?: {
@@ -73,7 +103,62 @@ export function callSources(project: Project | undefined, request?: {
 }, options?: {
     cacheDir?: string;
     timeoutMs?: number;
+    official?: OfficialList;
 }): Promise<CatalogResult>;
+/**
+ * Official packages first, in the official list's order; the rest keep theirs.
+ * @template T
+ * @param {T[]} items
+ * @param {OfficialPackage[]} official
+ * @param {(item: T) => string} nameOf
+ * @returns {T[]}
+ */
+export function officialFirst<T>(items: T[], official: OfficialPackage[], nameOf: (item: T) => string): T[];
+/**
+ * The official list this CLI carries (spec:AST-051 FR11). The file holds no
+ * versions; each entry takes them from this CLI and the project:
+ *
+ * - Its latest release is the newest release this CLI knows: its own version
+ *   on a release CLI, or the project's Core version when that is a newer
+ *   release.
+ * - A package released with Core lists a release CLI's own version and the
+ *   project's Core version (installed, else declared exactly), so each,
+ *   the latest release included, can be looked up. Its add command pins the project's Core version, else the Core range
+ *   the project declares, else the latest release; nothing on a canary CLI in
+ *   a project with no Core, which may have been published without it.
+ * - A canary-only package is listed only by a canary CLI, as a prerelease at
+ *   the project's Core version when that is a prerelease, else at the CLI's
+ *   own version when the project has no Core. It is not listed beside a
+ *   released or declared Core, which it cannot be installed with.
+ *
+ * @param {{file?: string, version?: string, project?: Project}} [options] the
+ *   list file and the CLI version to read it for, both defaulting to this
+ *   CLI's own, and the project whose Core decides the versions
+ * @returns {OfficialList}
+ */
+export function officialList({ file, version, project, }?: {
+    file?: string;
+    version?: string;
+    project?: Project;
+}): OfficialList;
+/**
+ * What the project has: its installed integrations plus each official package
+ * its own package.json declares as a dependency whose entry the official list
+ * supplied, official packages first. A declared official package that a source
+ * lists stays as that source shows it (FR7). One that failed to load as an
+ * integration stays out. A declared one takes what it adds from the list and
+ * its version from the copy the project installed, under an npm alias too.
+ *
+ * @param {Project | undefined} project
+ * @param {InstalledPackage[]} installed from {@link describeInstalled}
+ * @param {CatalogResult} catalog
+ * @param {OfficialDeclarations} declared from {@link officialDeclarations}
+ * @param {OfficialPackage[]} official the official list, for the order
+ * @returns {Array<InstalledPackage & {declaredOfficial?: true}>}
+ */
+export function withDeclaredOfficial(project: Project | undefined, installed: InstalledPackage[], catalog: CatalogResult, declared: OfficialDeclarations, official: OfficialPackage[]): Array<InstalledPackage & {
+    declaredOfficial?: true;
+}>;
 /**
  * Project a scanned or installed package into the discover list/detail entry
  * shape. Shared by the list and detail leaves so the entry keys (and their
@@ -104,11 +189,43 @@ export function loadValidatedDoc(result: ComponentResolution, { lang, zh }: {
     lang?: string | null;
     zh?: boolean;
 }): Promise<import("./discover.type.mjs").DiscoverDetailDocResponse["data"]>;
+/** The name the official list goes by, as a source and on each of its entries. */
+export const OFFICIAL_SOURCE_NAME: "Astryx";
+/** The official list, generated from the repository when the CLI is built. */
+export const OFFICIAL_LIST_FILE: string;
 /** The list and detail entry fields for each item kind, in display order. */
 export const KIND_FIELDS: readonly [readonly ["component", "components"], readonly ["template", "templates"], readonly ["doc", "docs"], readonly ["theme", "themes"], readonly ["codemod", "codemods"], readonly ["agent-doc", "agentDocs"]];
 export type ScannedPackage = import("./_package-scanner.mjs").ScannedPackage;
 export type DiscoverPackage = import("../../authoring/discover/type").DiscoverPackage;
 export type DiscoverSource = import("../../authoring/discover/type").DiscoverSource;
+/**
+ * An official package as this CLI lists it (spec:AST-051 FR11), with what its
+ * add command pins (FR2): the project's Core version, the Core range the
+ * project declares, or the latest release; with none, it pins nothing.
+ */
+export type OfficialPackage = DiscoverPackage & {
+    pin?: string;
+};
+/**
+ * The official packages the project's package.json declares: the real package
+ * name of each, mapped to the name it is installed under (an npm alias such as
+ * `"my-theme": "npm:@astryxdesign/theme-gothic@0.7.0"` installs under
+ * `my-theme`). `dependency` holds those declared in dependencies,
+ * devDependencies or optionalDependencies, which make a package the project's
+ * own; `any` adds peerDependencies, which only keep it from being offered.
+ */
+export type OfficialDeclarations = {
+    dependency: Map<string, string>;
+    any: Set<string>;
+};
+/**
+ * The official list as this CLI reads it. `error` says why the file could not
+ * be read; the list is then empty and discover reports it like a failed source.
+ */
+export type OfficialList = {
+    packages: OfficialPackage[];
+    error?: string;
+};
 /**
  * An installed integration with what it adds, per kind. `components` is the
  * scanned component list the discover leaves have always used.
@@ -129,7 +246,8 @@ export type SourceState = {
      */
     name: string;
     /**
-     * `astryx.config`, or the integration that exports it
+     * `astryx.config`, the integration that exports it, or
+     * `@astryxdesign/cli` for the official list
      */
     from: string;
     status: "fresh" | "saved" | "failed";
@@ -145,13 +263,15 @@ export type SourceState = {
     error?: string | undefined;
 };
 /**
- * Everything every source returned, merged. When two sources list the same
- * package, the earlier source's entry is kept.
+ * Everything every source returned, merged, the official list last. When two
+ * sources list the same package, the earlier source's entry is kept. `official`
+ * marks an entry the official list supplied.
  */
 export type CatalogResult = {
     sources: SourceState[];
     packages: Array<DiscoverPackage & {
         source: string;
+        official?: true;
     }>;
 };
 /**