@astryxdesign/cli 0.7.12-canary.ccb4a6d → 0.7.12-canary.da3dbdc

package/api/search/exportSearchIndex.doc.mjs

@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `exportSearchIndex()`. Colocated with the API function it
+ * documents; the shape source of truth stays in `search.type.mjs`.
+ * @position packages/cli/api/search — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'exportSearchIndex',
+  namespace: 'cli/api',
+  stability: 'experimental',
+  displayName: 'exportSearchIndex()',
+  summary:
+    'The candidates search ranks in a folder, as plain JSON to store and rank later with rankSearchIndex().',
+  description:
+    "Gathers what `search()` would rank in `cwd` and returns it as `{version, candidates}`. Gathering reads each installed package's docs and loads its integration manifest, which runs that package's code, so a catalog that lists packages it must not load makes the index where loading is safe (a folder with those packages installed), stores it, and ranks it with {@link function:rankSearchIndex}. With `package`, the index keeps only that package's candidates, for a catalog that stores one index per package. A component description's inline doc tokens are resolved where the index is made, as `search` prints them; when Core could not be had there, the index says why in `coreSkipped`. Fields that point into the folder are left out, so an index reads the same wherever it was made. The candidates are the ranker's input, not a stable shape: an index is ranked only by the CLI version that made it. Experimental: it may change or be removed in a patch release.",
+  importPath: '@astryxdesign/cli/api',
+  signature: 'exportSearchIndex(options?: {cwd?: string, package?: string}): Promise<SearchIndex>',
+  keywords: ['search index', 'stored search index'],
+  params: [
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description: 'The folder to gather from, read as `search()` reads it.',
+      default: 'process.cwd()',
+    },
+    {
+      name: 'options.package',
+      type: 'string',
+      description:
+        "Keep only the candidates this npm package owns: its components, templates, themes, and doc parts. Without it the index holds everything the folder's search ranks, Core's entries and the CLI's docs included.",
+    },
+  ],
+  returns: [
+    {
+      type: 'SearchIndex',
+      description:
+        '`version`, the CLI version that made it, and `candidates`, the gathered entries as plain JSON.',
+    },
+  ],
+  throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: '`package` is given and is not a non-empty string',
+    },
+  ],
+  examples: [
+    {
+      label: 'Index one installed integration',
+      code: "const index = await exportSearchIndex({cwd: '/tmp/harness', package: '@acme/ui'});",
+    },
+  ],
+  related: ['search', 'rankSearchIndex'],
+};

package/api/search/rankSearchIndex.doc.d.mts

@@ -0,0 +1,10 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `rankSearchIndex()`. Colocated with the API function it
+ * documents; the shape source of truth stays in `search.type.mjs`.
+ * @position packages/cli/api/search — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/search/rankSearchIndex.doc.mjs

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `rankSearchIndex()`. Colocated with the API function it
+ * documents; the shape source of truth stays in `search.type.mjs`.
+ * @position packages/cli/api/search — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'rankSearchIndex',
+  namespace: 'cli/api',
+  stability: 'experimental',
+  displayName: 'rankSearchIndex()',
+  summary:
+    "Ranks stored search indexes with search's own tree: an index made in one folder answers as search() does there.",
+  description:
+    "Ranks the candidates of every index together, with the same tree, weights, and order as {@link function:search}. An index made with `exportSearchIndex()` in one folder ranks exactly as `search(query)` does in that folder: the same results, order, and scores. Indexes made in separate folders are ranked together as one list; a doc that one package replaces or extends in another is not merged across them, so a project's own `search` can differ where that happens. A theme result's command is the in-project `theme add`. When every index was made where Core could not be had, an open rank (no `type`) carries `meta.partial`, as `search` does; a rank of `type` `component`, `hook`, or `template` throws the error `search` throws there. Every index must come from this CLI's version, because the candidates' shape is the ranker's input. Experimental: it may change or be removed in a patch release.",
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'rankSearchIndex(query: string, indexes: SearchIndex | SearchIndex[], options?: {type?: SearchDomain, limit?: number}): Promise<SearchResponse>',
+  keywords: ['search index', 'stored search index'],
+  params: [
+    {
+      name: 'query',
+      type: 'string',
+      description: 'Free-text search term.',
+      required: true,
+    },
+    {
+      name: 'indexes',
+      type: 'SearchIndex | SearchIndex[]',
+      description:
+        'Indexes made by `exportSearchIndex()` with this CLI version.',
+      required: true,
+    },
+    {
+      name: 'options.type',
+      type: "'component' | 'hook' | 'doc' | 'template' | 'theme'",
+      description: 'Restrict results to a single domain.',
+    },
+    {
+      name: 'options.limit',
+      type: 'number',
+      description: 'Maximum number of results.',
+      default: '20',
+    },
+  ],
+  returns: [
+    {
+      type: 'search',
+      description:
+        'The same response as `search()`: the query, `matchCount`, and the ranked results bounded by `limit`.',
+    },
+  ],
+  throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: 'the query is empty, `type` is unknown, `limit` is not a positive integer, an index is not `{version, candidates}`, or an index was made by another CLI version',
+    },
+    {
+      code: 'ERR_CORE_NOT_FOUND',
+      when: 'every index was made where @astryxdesign/core could not be found, and `type` names a domain that reads it: `component`, `hook`, or `template`',
+    },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: 'every index was made where the Core of the release that answers could not be installed into the per-user cache, and `type` names a domain that reads it: `component`, `hook`, or `template`; a rank with no `type` answers with `meta.partial` instead',
+    },
+  ],
+  examples: [
+    {
+      label: 'Rank stored indexes',
+      code: 'const r = await rankSearchIndex(text, [coreIndex, ...packageIndexes]);',
+    },
+  ],
+  related: ['search', 'exportSearchIndex'],
+};

package/api/search/search-index.d.mts

@@ -0,0 +1,44 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The candidates `search` ranks in a folder, as plain JSON: store it, and rank
+ * it later with {@link rankSearchIndex}.
+ *
+ * Experimental (spec:AST-017 FR27): may change or be removed in a patch
+ * release.
+ * @experimental
+ * @param {object} [options]
+ * @param {string} [options.cwd] - The folder to gather from, as `search` reads it.
+ * @param {string} [options.package] - Keep only the candidates this npm package
+ *   owns (its components, templates, themes, and doc parts).
+ * @returns {Promise<import('./search.type.mjs').SearchIndex>}
+ */
+export function exportSearchIndex(options?: {
+    cwd?: string | undefined;
+    package?: string | undefined;
+}): Promise<import("./search.type.mjs").SearchIndex>;
+/**
+ * Ranks stored indexes with search's tree. An index made in one folder answers
+ * as `search(query)` does there (a theme result's command is the in-project
+ * `theme add`). Indexes made in separate folders, such as one per package
+ * (made with `package`) and one for Core, are ranked together as one list; a
+ * doc that one package replaces or extends in another is not merged across
+ * them. Every index must come from this CLI's version, since the tree reads
+ * the candidates' shape. When every index was made where Core could not be
+ * had, the answer carries `meta.partial`, as `search` does.
+ *
+ * Experimental (spec:AST-017 FR27): may change or be removed in a patch
+ * release.
+ * @experimental
+ * @param {string} query - Free-text search term.
+ * @param {import('./search.type.mjs').SearchIndex | import('./search.type.mjs').SearchIndex[]} indexes
+ * @param {object} [options]
+ * @param {import('./search.type.mjs').SearchDomain} [options.type] - Restrict to one domain.
+ * @param {number} [options.limit] - Max results (default 20).
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
+ */
+export function rankSearchIndex(query: string, indexes: import("./search.type.mjs").SearchIndex | import("./search.type.mjs").SearchIndex[], options?: {
+    type?: import("./search.type.mjs").SearchDomain | undefined;
+    limit?: number | undefined;
+}): Promise<import("./search.type.mjs").SearchResponse>;

package/api/search/search-index.mjs

@@ -0,0 +1,270 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A stored search index: the candidates `search` gathers in a folder, as
+ * plain JSON, and the ranking of stored candidates with search's own tree.
+ *
+ * Gathering reads every package's docs and loads its manifest, which runs the
+ * package's code. A catalog that lists packages it must not load (a web page
+ * that lists every published integration) stores each package's index once,
+ * where loading is safe, and ranks the stored indexes per query.
+ * @position api/search; search.mjs is the folder-reading search.
+ */
+
+import {
+  docPackageManager,
+  runWithDocPackageManager,
+} from '../../foundation/env/package-manager.mjs';
+import {withListingCache} from '../../foundation/fs/listing-cache.mjs';
+import {cliVersion} from '../../foundation/release/run-context.mjs';
+import {runTree} from '../../foundation/route/route.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {linkSearchResponse} from '../component/_adapter.mjs';
+import {AstryxError} from '../error.mjs';
+import {
+  gatherCandidates,
+  loadSearchData,
+  resolveSearchCore,
+} from './_adapter.mjs';
+import {checkSearchArgs} from './_result.mjs';
+import {SEARCH_TREE} from './tree.mjs';
+
+/**
+ * Fields a gathered candidate holds that point into the folder it was read
+ * from. They decide ownership while gathering and never rank, so an index
+ * leaves them out and reads the same wherever it was made.
+ */
+const LOCAL_FIELDS = ['_docPath'];
+
+/**
+ * A component candidate's description as `search` prints it: its inline
+ * `{@link}`, `{@pm}` and `{@command}` tokens resolved in the folder the index
+ * is made in. The raw description stays the one that is scored.
+ */
+const DISPLAY_FIELD = '_displayDescription';
+
+/** Stands for the Core the indexes were made with, which ranking never reads. */
+const STORED_CORE = 'stored-index';
+
+/**
+ * @param {Record<string, unknown>} candidate
+ * @returns {Record<string, unknown>}
+ */
+function portable(candidate) {
+  /** @type {Record<string, unknown>} */
+  const out = JSON.parse(JSON.stringify(candidate));
+  for (const field of LOCAL_FIELDS) delete out[field];
+  return out;
+}
+
+/**
+ * The candidates `search` ranks in a folder, as plain JSON: store it, and rank
+ * it later with {@link rankSearchIndex}.
+ *
+ * Experimental (spec:AST-017 FR27): may change or be removed in a patch
+ * release.
+ * @experimental
+ * @param {object} [options]
+ * @param {string} [options.cwd] - The folder to gather from, as `search` reads it.
+ * @param {string} [options.package] - Keep only the candidates this npm package
+ *   owns (its components, templates, themes, and doc parts).
+ * @returns {Promise<import('./search.type.mjs').SearchIndex>}
+ */
+export async function exportSearchIndex(options = {}) {
+  const {cwd = process.cwd(), package: owner} = options;
+  if (owner != null && (typeof owner !== 'string' || owner.trim() === '')) {
+    throw new AstryxError(
+      `Invalid package "${owner}". Pass an npm package name.`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  return runWithDocPackageManager(docPackageManager(cwd), () =>
+    withListingCache(async () => {
+      const gathered = await gatherCandidates({cwd});
+      const kept =
+        owner == null
+          ? gathered.all
+          : gathered.all.filter(candidate => candidate._package === owner);
+      const candidates = kept.map(candidate =>
+        portable(/** @type {Record<string, unknown>} */ (candidate)),
+      );
+      await addDisplayDescriptions(candidates, cwd);
+      return {
+        version: cliVersion(),
+        candidates,
+        ...(gathered.coreSkipped == null
+          ? {}
+          : {
+              coreSkipped: gathered.coreSkipped,
+              ...(gathered.coreSkippedCode == null
+                ? {}
+                : {coreSkippedCode: gathered.coreSkippedCode}),
+            }),
+      };
+    }),
+  );
+}
+
+/**
+ * Resolves each component description's inline tokens as `search` does for
+ * the results it prints, and keeps the printed text beside the scored one.
+ * @param {Record<string, unknown>[]} candidates
+ * @param {string} cwd
+ */
+async function addDisplayDescriptions(candidates, cwd) {
+  const linkable = candidates.filter(
+    candidate =>
+      candidate.domain === 'component' &&
+      typeof candidate.description === 'string' &&
+      candidate.description.includes('{@'),
+  );
+  if (linkable.length === 0) return;
+  const response = await linkSearchResponse(
+    /** @type {any} */ ({
+      type: 'search',
+      data: {
+        results: linkable.map(candidate => ({
+          domain: 'component',
+          package: candidate._package,
+          description: candidate.description,
+        })),
+      },
+    }),
+    cwd,
+  );
+  response.data.results.forEach(
+    (/** @type {any} */ result, /** @type {number} */ i) => {
+      if (result.description !== linkable[i].description)
+        linkable[i][DISPLAY_FIELD] = result.description;
+    },
+  );
+}
+
+/**
+ * Ranks stored indexes with search's tree. An index made in one folder answers
+ * as `search(query)` does there (a theme result's command is the in-project
+ * `theme add`). Indexes made in separate folders, such as one per package
+ * (made with `package`) and one for Core, are ranked together as one list; a
+ * doc that one package replaces or extends in another is not merged across
+ * them. Every index must come from this CLI's version, since the tree reads
+ * the candidates' shape. When every index was made where Core could not be
+ * had, the answer carries `meta.partial`, as `search` does.
+ *
+ * Experimental (spec:AST-017 FR27): may change or be removed in a patch
+ * release.
+ * @experimental
+ * @param {string} query - Free-text search term.
+ * @param {import('./search.type.mjs').SearchIndex | import('./search.type.mjs').SearchIndex[]} indexes
+ * @param {object} [options]
+ * @param {import('./search.type.mjs').SearchDomain} [options.type] - Restrict to one domain.
+ * @param {number} [options.limit] - Max results (default 20).
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
+ */
+export async function rankSearchIndex(query, indexes, options = {}) {
+  checkSearchArgs(query, options);
+  const list = Array.isArray(indexes) ? indexes : [indexes];
+  const version = cliVersion();
+  /** @type {any[]} */
+  const all = [];
+  for (const index of list) {
+    if (index == null || !Array.isArray(index.candidates)) {
+      throw new AstryxError(
+        'A search index is {version, candidates}, as exportSearchIndex() returns it.',
+        undefined,
+        ERROR_CODES.ERR_INVALID_ARGUMENT,
+      );
+    }
+    if (index.version !== version) {
+      throw new AstryxError(
+        `This search index was made by CLI ${index.version}; this is CLI ${version}. Make it again with this version's exportSearchIndex().`,
+        undefined,
+        ERROR_CODES.ERR_INVALID_ARGUMENT,
+      );
+    }
+    all.push(...index.candidates);
+  }
+  const {type} = options;
+  const wanted =
+    type == null ? all : all.filter(candidate => candidate.domain === type);
+  const {searchedComponents, coreSkipped} = coreFlags(list, type);
+  const response = /** @type {import('./search.type.mjs').SearchResponse} */ (
+    await runTree(
+      SEARCH_TREE,
+      {query, options: {type, limit: options.limit}},
+      {
+        all: wanted,
+        components: wanted.filter(
+          candidate => candidate.domain === 'component',
+        ),
+        searchedComponents,
+        outside: false,
+        coreSkipped,
+        coreSkippedCode: null,
+        data: loadSearchData(),
+      },
+    )
+  );
+  return withDisplayDescriptions(response, wanted);
+}
+
+/**
+ * The catalog flags `search` derives from Core for a request of `type`, by
+ * search's own rule (`resolveSearchCore`). Core is missing only when no index
+ * had it. An open search then names what it skipped. A docs or themes search
+ * never reads Core. A Core domain asked for by name throws the error that
+ * `search` throws.
+ * @param {import('./search.type.mjs').SearchIndex[]} list
+ * @param {import('./search.type.mjs').SearchDomain | undefined} type
+ * @returns {{searchedComponents: boolean, coreSkipped: string | null}}
+ */
+function coreFlags(list, type) {
+  const missing =
+    list.length > 0 &&
+    list.every(index => typeof index.coreSkipped === 'string');
+  const lookup = () => {
+    if (!missing) return STORED_CORE;
+    throw Object.assign(
+      new Error(/** @type {string} */ (list[0].coreSkipped)),
+      {
+        code: list[0].coreSkippedCode ?? ERROR_CODES.ERR_CORE_NOT_FOUND,
+      },
+    );
+  };
+  const {coreSkipped, wants} = resolveSearchCore(type, lookup, STORED_CORE);
+  return {searchedComponents: wants('component'), coreSkipped};
+}
+
+/**
+ * The response with each component result's description as `search` prints
+ * it, from the text the index stored when it was made.
+ * @param {import('./search.type.mjs').SearchResponse} response
+ * @param {any[]} candidates
+ * @returns {import('./search.type.mjs').SearchResponse}
+ */
+function withDisplayDescriptions(response, candidates) {
+  /** @type {Map<string, string>} */
+  const display = new Map();
+  for (const candidate of candidates) {
+    if (
+      candidate.domain === 'component' &&
+      typeof candidate[DISPLAY_FIELD] === 'string'
+    )
+      display.set(
+        `${candidate._package}\u0000${candidate._resultName ?? candidate.name}`,
+        candidate[DISPLAY_FIELD],
+      );
+  }
+  if (display.size === 0) return response;
+  return {
+    ...response,
+    data: {
+      ...response.data,
+      results: response.data.results.map(result => {
+        if (result.domain !== 'component') return result;
+        const text = display.get(`${result.package}\u0000${result.name}`);
+        return text == null ? result : {...result, description: text};
+      }),
+    },
+  };
+}

package/api/search/search.type.d.mts

@@ -95,6 +95,34 @@ export type SearchResponse = {
         };
     } | undefined;
 };
+/**
+ * The candidates `search` ranks in a folder, as `exportSearchIndex()` returns them:
+ * plain JSON to store and rank later with `rankSearchIndex()`.
+ */
+export type SearchIndex = {
+    /**
+     * - The CLI version that made it. `rankSearchIndex()`
+     * ranks only indexes made by its own version.
+     */
+    version: string;
+    /**
+     * - The gathered candidates,
+     * each the entry search scores. Their fields are the ranker's input, not a
+     * contract: they may change in any release, which is why `version` must match.
+     */
+    candidates: Record<string, unknown>[];
+    /**
+     * - Why Core could not be had where the index
+     * was made, when it could not: its components, hooks and templates are then
+     * missing, and `rankSearchIndex()` answers as `search` does without Core
+     * (`meta.partial` for an open search; refused for a domain that reads Core).
+     */
+    coreSkipped?: string | undefined;
+    /**
+     * - The error code that Core lookup gave.
+     */
+    coreSkippedCode?: string | undefined;
+};
 /**
  * Options for `search()`.
  */

package/api/search/search.type.mjs

@@ -51,6 +51,23 @@
  *   The results are the docs and themes.
  */
 
+/**
+ * The candidates `search` ranks in a folder, as `exportSearchIndex()` returns them:
+ * plain JSON to store and rank later with `rankSearchIndex()`.
+ * @experimental May change or be removed in a patch release.
+ * @typedef {object} SearchIndex
+ * @property {string} version - The CLI version that made it. `rankSearchIndex()`
+ *   ranks only indexes made by its own version.
+ * @property {Record<string, unknown>[]} candidates - The gathered candidates,
+ *   each the entry search scores. Their fields are the ranker's input, not a
+ *   contract: they may change in any release, which is why `version` must match.
+ * @property {string} [coreSkipped] - Why Core could not be had where the index
+ *   was made, when it could not: its components, hooks and templates are then
+ *   missing, and `rankSearchIndex()` answers as `search` does without Core
+ *   (`meta.partial` for an open search; refused for a domain that reads Core).
+ * @property {string} [coreSkippedCode] - The error code that Core lookup gave.
+ */
+
 /**
  * Options for `search()`.
  * @typedef {object} SearchOptions

package/api/swizzle/_moduleGraph.d.mts

@@ -16,6 +16,8 @@
  *   file the copy holds (absolute source path), with the edits its imports need
  * @property {Map<string, Set<string>>} dependsOn file -> carried files its
  *   computed specifiers point at
+ * @property {Map<string, string>} otherPackages the source root of each other
+ *   Astryx package the copy carries modules from, with its package name
  * @property {Record<string, string>} dependencies each npm package the copied
  *   files import, other than the owner package and Node's built-in modules,
  *   with the range the owner package declares
@@ -162,6 +164,11 @@ export type CopyPlan = {
      * computed specifiers point at
      */
     dependsOn: Map<string, Set<string>>;
+    /**
+     * the source root of each other
+     * Astryx package the copy carries modules from, with its package name
+     */
+    otherPackages: Map<string, string>;
     /**
      * each npm package the copied
      * files import, other than the owner package and Node's built-in modules,