@astryxdesign/cli 0.7.12-canary.f543ec7 → 0.7.12

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,