@astryxdesign/cli 0.7.12-canary.f543ec7 → 0.7.12

package/api/search/_fit-order.d.mts

@@ -0,0 +1,47 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The results with the first kept. Entries #2 to #10 split into runs of one
+ * band and kind. Inside a run, the entries that fit the query under FIT_BAR
+ * times the run's median fit move, in order, after the others, unless their
+ * name spells NAME_WORDS or more of the query's words. A run whose
+ * median fit is zero or less keeps its order. Nothing crosses a run, and
+ * nothing is added or dropped.
+ * @param {any[]} results
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ *   the block picker's weights, or a function that reads them; the function
+ *   runs only when a run can change. Without weights the order stays
+ * @returns {any[]}
+ */
+export function orderByFit(results: any[], candidates: any[], query: string, weights: Weights | (() => Weights | null | undefined) | null | undefined): any[];
+/**
+ * The search response with its results ordered by fit (`orderByFit`). Any
+ * other response passes through.
+ * @template T
+ * @param {T} response
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ * @returns {T}
+ */
+export function withFitOrder<T>(response: T, candidates: any[], query: string, weights: Weights | (() => Weights | null | undefined) | null | undefined): T;
+/**
+ * The search response with at most `limit` results.
+ * @template T
+ * @param {T} response
+ * @param {number} limit
+ * @returns {T}
+ */
+export function withLimit<T>(response: T, limit: number): T;
+/** An entry stays in place when its fit is at least this times the median. */
+export const FIT_BAR: 1.7;
+/** The first result stays; the pass orders the places after it up to here. */
+export const FIT_PLACES: 10;
+export type Weights = import("../build/blocks/blocks.mjs").BlockPickerWeights;
+export type Side = {
+    vector: Map<number, number>;
+    projected: Float64Array;
+};

package/api/search/_fit-order.mjs

@@ -0,0 +1,257 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A last pass over a searcher's answer: inside each run of one score
+ * band and kind, the entries from #2 to #10 that fit the whole query much
+ * worse than the others in their run move, in order, after them.
+ * @input the ordered response, the gathered candidates, and the query
+ * @output the same response with the same results, maybe in a new order
+ * @position api/search; rankWith (_main-searcher.mjs) runs it after
+ * orderMatches, with the weights the adapter loads (loadSearchData) through
+ * build's own loader. The fit is build's block-picker match
+ * (build/blocks/blocks.mjs) with its shipped weights, so an entry the weights
+ * never saw is scored from its own docs the same way. Without readable
+ * weights the order stays.
+ */
+
+import {
+  docSideOf,
+  matchOf,
+  requestSideOf,
+  stemOf,
+  termsOf,
+  wordsOf,
+} from '../build/blocks/blocks.mjs';
+import {bandOf} from './_order.mjs';
+import {searchedComponentsOf} from './_result.mjs';
+
+/** An entry stays in place when its fit is at least this times the median. */
+export const FIT_BAR = 1.7;
+
+/** An entry whose name spells at least this many query words never moves. */
+const NAME_WORDS = 2;
+
+/** The first result stays; the pass orders the places after it up to here. */
+export const FIT_PLACES = 10;
+
+/** @typedef {import('../build/blocks/blocks.mjs').BlockPickerWeights} Weights */
+/** @typedef {{vector: Map<number, number>, projected: Float64Array}} Side */
+
+/**
+ * Each candidate by `domain:name`; a doc also by its topic and by
+ * `topic#section`. The first candidate with a key owns it.
+ * @type {WeakMap<any[], Map<string, any>>}
+ */
+const keyed = new WeakMap();
+
+/**
+ * Each candidate's docs side, computed when a result first needs it.
+ * @type {WeakMap<Weights, WeakMap<any, Side>>}
+ */
+const sides = new WeakMap();
+
+/**
+ * An entry's docs text: its name words, display name or first title,
+ * description, and keywords.
+ * @param {any} c
+ */
+const docText = c =>
+  [
+    wordsOf(c.name).join(' '),
+    c._displayName ?? (Array.isArray(c.titles) ? c.titles[0] : '') ?? '',
+    c.description ?? '',
+    (Array.isArray(c.keywords) ? c.keywords : []).join(' '),
+  ].join(' ');
+
+/**
+ * @param {any[]} candidates
+ * @returns {Map<string, any>}
+ */
+function keysOf(candidates) {
+  let byKey = keyed.get(candidates);
+  if (!byKey) {
+    byKey = new Map();
+    for (const c of candidates) {
+      const keys = [`${c.domain}:${c._resultName ?? c.name}`];
+      if (c.domain === 'doc' && c._topic)
+        keys.push(
+          c._section ? `doc:${c._topic}#${c._section}` : `doc:${c._topic}`,
+        );
+      for (const k of keys) if (!byKey.has(k)) byKey.set(k, c);
+    }
+    keyed.set(candidates, byKey);
+  }
+  return byKey;
+}
+
+/**
+ * @param {any} c
+ * @param {Weights} weights
+ * @returns {Side}
+ */
+function candidateSide(c, weights) {
+  let byCandidate = sides.get(weights);
+  if (!byCandidate) {
+    byCandidate = new WeakMap();
+    sides.set(weights, byCandidate);
+  }
+  let side = byCandidate.get(c);
+  if (!side) {
+    side = docSideOf(docText(c), weights);
+    byCandidate.set(c, side);
+  }
+  return side;
+}
+
+/**
+ * A result's docs side: its candidate's, else one from the result's own name,
+ * display name and description.
+ * @param {any} r
+ * @param {any[]} candidates
+ * @param {Weights} weights
+ * @returns {Side}
+ */
+function resultSideOf(r, candidates, weights) {
+  const byKey = keysOf(candidates);
+  if (r.domain === 'doc' && r.section) {
+    const c = byKey.get(`doc:${r.name}#${r.section}`);
+    if (c) return candidateSide(c, weights);
+  }
+  const c = byKey.get(`${r.domain}:${r.name}`);
+  return c
+    ? candidateSide(c, weights)
+    : docSideOf(
+        `${wordsOf(r.name).join(' ')} ${r.displayName ?? ''} ${r.description ?? ''}`,
+        weights,
+      );
+}
+
+/**
+ * A result's run: its score band and kind (doc or not), as orderMatches reads
+ * them.
+ * @param {any} r
+ */
+const runOf = r => `${bandOf(r.score ?? 0)}:${r.domain === 'doc'}`;
+
+/**
+ * The results with the first kept. Entries #2 to #10 split into runs of one
+ * band and kind. Inside a run, the entries that fit the query under FIT_BAR
+ * times the run's median fit move, in order, after the others, unless their
+ * name spells NAME_WORDS or more of the query's words. A run whose
+ * median fit is zero or less keeps its order. Nothing crosses a run, and
+ * nothing is added or dropped.
+ * @param {any[]} results
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ *   the block picker's weights, or a function that reads them; the function
+ *   runs only when a run can change. Without weights the order stays
+ * @returns {any[]}
+ */
+export function orderByFit(results, candidates, query, weights) {
+  if (!weights || results.length < 3) return results;
+  const end = Math.min(FIT_PLACES, results.length);
+  /** @type {[number, number][]} */
+  const runs = [];
+  for (let i = 1; i < end;) {
+    let j = i;
+    while (j < end && runOf(results[j]) === runOf(results[i])) j++;
+    runs.push([i, j]);
+    i = j;
+  }
+  // Only a run of two or more can change, so the weights stay unread when
+  // there is none.
+  if (!runs.some(([i, j]) => j - i > 1)) return results;
+  const w = typeof weights === 'function' ? weights() : weights;
+  if (!w) return results;
+  const request = requestSideOf(query, w);
+  const queryWords = new Set(termsOf(query).filter(t => !t.includes('_')));
+  /** @param {any} r */
+  const named = r =>
+    new Set(
+      wordsOf(r.name)
+        .map(stemOf)
+        .filter(word => queryWords.has(word)),
+    ).size >= NAME_WORDS;
+  const out = results.slice();
+  let changed = false;
+  for (const [i, j] of runs) {
+    if (j - i < 2) continue;
+    const moved = demoteWeak(
+      results.slice(i, j),
+      request,
+      candidates,
+      w,
+      named,
+    );
+    moved.forEach((r, k) => {
+      if (r !== out[i + k]) changed = true;
+      out[i + k] = r;
+    });
+  }
+  return changed ? out : results;
+}
+
+/**
+ * One run, with the entries under FIT_BAR times its median fit moved, in
+ * order, after the others. An entry whose name spells NAME_WORDS or more of
+ * the query's words stays with the others: its name is strong evidence.
+ * @param {any[]} run
+ * @param {Side} request
+ * @param {any[]} candidates
+ * @param {Weights} weights
+ * @param {(r: any) => boolean} named
+ * @returns {any[]}
+ */
+function demoteWeak(run, request, candidates, weights, named) {
+  const fits = run.map(
+    r => matchOf(request, resultSideOf(r, candidates, weights), weights).match,
+  );
+  const sorted = [...fits].sort((a, b) => a - b);
+  const n = sorted.length;
+  const median =
+    n % 2 ? sorted[(n - 1) / 2] : (sorted[n / 2 - 1] + sorted[n / 2]) / 2;
+  if (!(median > 0)) return run;
+  const bar = FIT_BAR * median;
+  const kept = run.map((r, k) => fits[k] >= bar || named(r));
+  return [...run.filter((_, k) => kept[k]), ...run.filter((_, k) => !kept[k])];
+}
+
+/**
+ * The search response with its results ordered by fit (`orderByFit`). Any
+ * other response passes through.
+ * @template T
+ * @param {T} response
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ * @returns {T}
+ */
+export function withFitOrder(response, candidates, query, weights) {
+  const r = /** @type {any} */ (response);
+  const results = r?.data?.results;
+  if (!Array.isArray(results)) return response;
+  const ordered = orderByFit(results, candidates, query, weights);
+  if (ordered === results) return response;
+  const out = {...r, data: {...r.data, results: ordered}};
+  const searched = searchedComponentsOf.get(r);
+  if (searched) searchedComponentsOf.set(out, searched);
+  return /** @type {T} */ (out);
+}
+
+/**
+ * The search response with at most `limit` results.
+ * @template T
+ * @param {T} response
+ * @param {number} limit
+ * @returns {T}
+ */
+export function withLimit(response, limit) {
+  const r = /** @type {any} */ (response);
+  const results = r?.data?.results;
+  if (!Array.isArray(results) || results.length <= limit) return response;
+  const out = {...r, data: {...r.data, results: results.slice(0, limit)}};
+  const searched = searchedComponentsOf.get(r);
+  if (searched) searchedComponentsOf.set(out, searched);
+  return /** @type {T} */ (out);
+}

package/api/search/_main-searcher.mjs

@@ -15,6 +15,7 @@
 import {routeKit} from '../../foundation/route/route.mjs';
 import {rank, signals} from './_features.mjs';
 import {entryTable} from './_entries.mjs';
+import {FIT_PLACES, withFitOrder, withLimit} from './_fit-order.mjs';
 import {orderMatches} from './_order.mjs';
 import {routeProbs} from './_query-words.mjs';
 import {namesWhole, rankLexical} from './_lexical.mjs';
@@ -94,13 +95,22 @@ export function rankWith(request, catalog, weights) {
   );
   const route = routeProbs(catalog.data.router, query);
   const rows = signals(table, query, lexical.data.results, route);
-  return orderMatches(
-    table,
-    rank(table, rows, weights),
-    lexical,
+  const limit = options.limit ?? 20;
+  // The fit pass reads the first FIT_PLACES results at every limit, so a
+  // smaller limit shows the top of that order.
+  const ordered = withFitOrder(
+    orderMatches(
+      table,
+      rank(table, rows, weights),
+      lexical,
+      query,
+      Math.max(limit, FIT_PLACES),
+    ),
+    catalog.all,
     query,
-    options.limit ?? 20,
+    () => catalog.data.picker,
   );
+  return withLimit(ordered, limit);
 }
 
 /** @type {import('./tree.mjs').SearchKit} */

package/api/search/exportSearchIndex.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 `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: import("@astryxdesign/cli/authoring").FunctionDoc;

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>;