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

package/api/search/_compound.d.mts

@@ -0,0 +1,50 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+/**
+ * The strongest hit a run of two or more adjacent query words has when it is
+ * read as one joined word, and the query words it covers. Readers type a
+ * compound name as separate words (`table header cell` is TableHeaderCell,
+ * `number field` the keyword `numberfield`), and no single word of the run
+ * matches on its own.
+ *
+ * - 100: the run joins to a component, hook, or template name, or its plural
+ *   (`table header cells` is TableHeaderCell), or a hook name without its
+ *   `use` prefix (`table sticky columns` is useTableStickyColumns).
+ * - 90: the run joins to a one-word keyword (`number field` is
+ *   `numberfield`).
+ * - 95: the run joins to most of a name, cut short (`dropdown menu radio` is
+ *   DropdownMenuRadioItem); 92: it is a name's leading words, covering at least half
+ *   of it (`top nav mega` is TopNavMegaMenu); 70: it is two or more adjacent
+ *   words of a name that cover at least half of it (`header cell` in
+ *   TableHeaderCell), the same coverage a word prefix needs. These three
+ *   are for components and hooks only.
+ *
+ * A doc's name is a route or key, so docs are left out.
+ * @param {string[]} words - The query's words, stopwords included.
+ * @param {Candidate} candidate
+ * @returns {{score: number, reason: string, covered: Set<string>, alias?: 'partial' | 'keyword', aliasWords?: number} | null}
+ *   `covered` holds the run's words and every stretch of them joined. `alias`
+ *   marks a hit on part of a name or on a keyword, not on the whole name.
+ */
+export function compoundHit(words: string[], candidate: Candidate): {
+    score: number;
+    reason: string;
+    covered: Set<string>;
+    alias?: "partial" | "keyword";
+    aliasWords?: number;
+} | null;
+/**
+ * The longest run of adjacent query words read as one name. Core's longest
+ * names run to six words; a longer run is a sentence, not a name, and reading
+ * every run of a long build idea costs time on every candidate.
+ */
+export const MAX_RUN_WORDS: 6;
+/**
+ * Each candidate's compound hit from its last scoreQuery, so domainPriority
+ * reads it without walking the query's runs again.
+ * @type {WeakMap<object, ReturnType<typeof compoundHit>>}
+ */
+export const compoundOf: WeakMap<object, ReturnType<typeof compoundHit>>;
+export type Candidate = import("./_lexical.mjs").Candidate;

package/api/search/_compound.mjs

@@ -0,0 +1,170 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Compound names: adjacent query words joined into a candidate's name
+ * or keyword (`icon button` and IconButton).
+ */
+
+import {wordsOf, joined} from './_words.mjs';
+import {pluralOf} from './_query.mjs';
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+
+/**
+ * The strongest hit a run of two or more adjacent query words has when it is
+ * read as one joined word, and the query words it covers. Readers type a
+ * compound name as separate words (`table header cell` is TableHeaderCell,
+ * `number field` the keyword `numberfield`), and no single word of the run
+ * matches on its own.
+ *
+ * - 100: the run joins to a component, hook, or template name, or its plural
+ *   (`table header cells` is TableHeaderCell), or a hook name without its
+ *   `use` prefix (`table sticky columns` is useTableStickyColumns).
+ * - 90: the run joins to a one-word keyword (`number field` is
+ *   `numberfield`).
+ * - 95: the run joins to most of a name, cut short (`dropdown menu radio` is
+ *   DropdownMenuRadioItem); 92: it is a name's leading words, covering at least half
+ *   of it (`top nav mega` is TopNavMegaMenu); 70: it is two or more adjacent
+ *   words of a name that cover at least half of it (`header cell` in
+ *   TableHeaderCell), the same coverage a word prefix needs. These three
+ *   are for components and hooks only.
+ *
+ * A doc's name is a route or key, so docs are left out.
+ * @param {string[]} words - The query's words, stopwords included.
+ * @param {Candidate} candidate
+ * @returns {{score: number, reason: string, covered: Set<string>, alias?: 'partial' | 'keyword', aliasWords?: number} | null}
+ *   `covered` holds the run's words and every stretch of them joined. `alias`
+ *   marks a hit on part of a name or on a keyword, not on the whole name.
+ */
+export function compoundHit(words, candidate) {
+  if (candidate.domain === 'doc' || words.length < 2) return null;
+  const names = [candidate.name, ...(candidate.aliases ?? [])]
+    .filter(Boolean)
+    .map(name => ({name, nameJoined: joined(name), nameWords: wordsOf(name)}));
+  // Part of a name counts only for a component or hook. A template's name
+  // starts with the component it shows (`ProgressBarShowcase`), so part of it
+  // names the component, not the template.
+  const partial =
+    candidate.domain === 'component' || candidate.domain === 'hook';
+  // One-word lowercase keywords: a keyword an author declares for a reader
+  // to type, joined (`numberfield`). A capitalized one names another entry (a
+  // block's `componentsUsed`), which matches by its own name, and a keyword of
+  // several words is a phrase, matched as one.
+  const keywords = (candidate.keywords ?? []).filter(k =>
+    /^[a-z0-9]+$/.test(String(k)),
+  );
+  /** @type {{score: number, reason: string, covered: Set<string>, alias?: 'partial' | 'keyword', aliasWords?: number} | null} */
+  let best = null;
+  for (const {run, word} of queryRuns(words)) {
+    let score = 0;
+    let reason = '';
+    /** @type {'partial' | 'keyword' | null} */
+    let kind = null;
+    for (const {name, nameJoined, nameWords} of names) {
+      if (
+        nameJoined === word ||
+        pluralOf(word, nameJoined) ||
+        (candidate.domain === 'hook' && nameJoined === `use${word}`)
+      ) {
+        if (score < 100)
+          [score, reason, kind] = [100, `name ${name} spelled`, null];
+      } else if (!partial) {
+        continue;
+      } else if (
+        nameJoined.startsWith(word) &&
+        word.length / nameJoined.length >= 0.75
+      ) {
+        // Most of the name, cut short: `dropdown menu radio` is
+        // DropdownMenuRadioItem.
+        if (score < 95)
+          [score, reason, kind] = [95, `name ${name} spelled`, 'partial'];
+      } else if (
+        word.length / nameJoined.length >= 0.5 &&
+        run.every(
+          (w, j) => nameWords[j + (nameWords[0] === 'use' ? 1 : 0)] === w,
+        )
+      ) {
+        // The name's leading words: `top nav mega` is TopNavMegaMenu.
+        if (score < 92)
+          [score, reason, kind] = [
+            92,
+            `name ${name} starts "${run.join(' ')}"`,
+            'partial',
+          ];
+      } else if (
+        word.length / nameJoined.length >= 0.5 &&
+        nameWords.some((_, k) => run.every((w, j) => nameWords[k + j] === w))
+      ) {
+        if (score < 70)
+          [score, reason, kind] = [
+            70,
+            `name ${name} holds "${run.join(' ')}"`,
+            'partial',
+          ];
+      }
+    }
+    if (score < 90 && keywords.includes(word)) {
+      [score, reason, kind] = [
+        90,
+        `keyword "${run.join(' ')}" spelled`,
+        'keyword',
+      ];
+    }
+    if (score > (best?.score ?? 0)) {
+      // Each word of the run, and each identifier typed as several of its
+      // words joined (`dropdownMenu` in `dropdownMenu checkbox`).
+      const covered = new Set();
+      for (let a = 0; a < run.length; a++) {
+        for (let b = a + 1; b <= run.length; b++) {
+          covered.add(run.slice(a, b).join(''));
+        }
+      }
+      best = {
+        score,
+        reason,
+        covered,
+        ...(kind ? {alias: kind, aliasWords: run.length} : {}),
+      };
+    }
+  }
+  return best;
+}
+
+/**
+ * The longest run of adjacent query words read as one name. Core's longest
+ * names run to six words; a longer run is a sentence, not a name, and reading
+ * every run of a long build idea costs time on every candidate.
+ */
+export const MAX_RUN_WORDS = 6;
+
+/**
+ * Each run of two to {@link MAX_RUN_WORDS} adjacent query words, longest
+ * first, with the run joined into one word. Computed once per query.
+ * @type {WeakMap<string[], {run: string[], word: string}[]>}
+ */
+const runsOf = new WeakMap();
+
+/**
+ * @param {string[]} words
+ * @returns {{run: string[], word: string}[]}
+ */
+function queryRuns(words) {
+  let runs = runsOf.get(words);
+  if (runs) return runs;
+  runs = [];
+  for (let len = Math.min(words.length, MAX_RUN_WORDS); len >= 2; len--) {
+    for (let i = 0; i + len <= words.length; i++) {
+      const run = words.slice(i, i + len);
+      runs.push({run, word: run.join('')});
+    }
+  }
+  runsOf.set(words, runs);
+  return runs;
+}
+
+/**
+ * Each candidate's compound hit from its last scoreQuery, so domainPriority
+ * reads it without walking the query's runs again.
+ * @type {WeakMap<object, ReturnType<typeof compoundHit>>}
+ */
+export const compoundOf = new WeakMap();

package/api/search/_doc-searcher.d.mts

@@ -0,0 +1,4 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export const doc: import("../../foundation/route/route.mjs").Searcher<import("./tree.mjs").SearchRequest, import("./_adapter.mjs").SearchCatalog, import("./search.type.mjs").SearchResponse>;

package/api/search/_doc-searcher.mjs

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The doc searcher: the main searcher's signals with its own weights,
+ * in _doc-searcher.weights.json.
+ * @input {query, options} and the gathered catalog with its static data
+ * @output the search response, the lexical response's shape and size
+ * @position api/search; a topic child of the root dispatcher in tree.mjs
+ */
+
+import {routeKit} from '../../foundation/route/route.mjs';
+import {asWeights, rankWith} from './_main-searcher.mjs';
+
+/** @type {import('./tree.mjs').SearchKit} */
+const {defineSearcher} = routeKit;
+
+export const doc = defineSearcher({
+  id: 'doc',
+  summary:
+    'Ranks entries for queries that ask for a doc, with weights of its own.',
+  run: (request, catalog, weights) =>
+    rankWith(request, catalog, asWeights(weights) ?? catalog.data.doc),
+});

package/api/search/_doc-searcher.test.mjs

@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the doc searcher (_doc-searcher.mjs): with its own weights
+ * it ranks a doc first for a query that asks for one. Run against the real
+ * @astryxdesign/core.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {gatherCandidates, loadSearchData} from './_adapter.mjs';
+import {doc} from './_doc-searcher.mjs';
+
+const REPO = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+
+describe('doc searcher', () => {
+  it('ranks a doc first for a doc query', async () => {
+    const catalog = {
+      ...(await gatherCandidates({cwd: REPO})),
+      data: loadSearchData(),
+    };
+    const answer = /** @type {any} */ (
+      await doc.run(
+        {query: 'how do I install a theme', options: {cwd: REPO}},
+        catalog,
+        null,
+      )
+    );
+    expect(answer.data.results[0].domain).toBe('doc');
+    expect(answer.data.results.length).toBeLessThanOrEqual(20);
+  });
+});

package/api/search/_doc-searcher.weights.json

@@ -0,0 +1 @@
+{"w":[0.255034,-0.032567,0.309242,0.050403,-0.358275,0.280939,0.461358,-0.613439,0.397626,0.070136,0.168831,0.032204,0.147137,-0.010509,-0.139086,0.247925,0.0,-0.013425,0.0,0.271127,-0.15666,0.161205,0.275391,-0.017229,-0.003888,0.018954,0.006559,0.010396,-0.003214,0.027251,-0.005917,0.093235,0.101059,0.006095,-0.013116,-0.036481,0.209443,0.12958,0.032606,0.036493,0.082651,0.0,0.0,0.0,0.067563,0.110925,0.145737,0.046132,-0.014063,0.127665,0.014997,0.180173,0.312727,0.079946,0.015853,-0.006495,0.009776,0.005509,0.006095],"mu":[0.122953,0.004932,0.176043,0.017021,0.147234,0.050213,0.178723,0.617872,0.005957,0.170087,0.638276,0.058177,0.049519,0.001321,0.051274,0.176439,0.061188,0.001341,0.0,0.009766,0.004823,0.073882,0.034193,0.000289,0.000827,0.000398,0.002652,0.001028,2.6e-05,0.008501,0.002364,0.111253,0.047342,0.000627,0.073136,0.02573,0.390793,0.145756,0.002861,0.044053,0.014124,0.0,0.0,0.0,0.007995,0.002104,0.029954,0.009344,0.000122,0.021697,0.001864,0.11116,0.041329,0.00039,0.000531,1e-06,0.000703,4.6e-05,6e-05],"sd":[0.272558,0.037015,0.37131,0.129352,0.35434,0.218385,0.383122,0.485909,0.076955,0.825557,1.798503,0.476936,0.124531,0.036157,0.2159,0.232289,1e-06,0.036574,1e-06,0.079222,0.057495,0.229243,0.146561,0.014114,0.017094,0.010761,0.028927,0.011091,0.003965,0.198705,0.104828,0.662804,0.448885,0.080939,0.547129,0.361981,1.544968,0.799909,0.170388,0.407639,0.250897,1e-06,1e-06,1e-06,0.048112,0.025129,0.109037,0.046651,0.006134,0.063975,0.011564,0.248543,0.049449,0.008334,0.023035,0.001195,0.026489,0.006758,0.007742]}

package/api/search/_doc-text.d.mts

@@ -0,0 +1,30 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The words one section says: its prose, headings, and list items.
+ * @param {any} section
+ * @returns {string[]}
+ */
+export function sectionProse(section: any): string[];
+/**
+ * The identifiers a doc part names in code ticks (`token-ref`,
+ * `ERR_UNKNOWN_SECTION`). Each is a keyword: a reader who types one exactly
+ * wants the part that defines or explains it.
+ * @param {any} part - a section, or `{content}` of a typed doc
+ * @returns {string[]}
+ */
+export function codeTerms(part: any): string[];
+/**
+ * The headings inside a section. Each names a subsection, so a query that
+ * names one should find the section as surely as one that names its title.
+ * @param {any} section
+ * @returns {string[]}
+ */
+export function headings(section: any): string[];
+/**
+ * A table cell as plain words, without its code ticks.
+ * @param {unknown} cell
+ * @returns {string}
+ */
+export function plain(cell: unknown): string;

package/api/search/_doc-text.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The text search reads from a doc section: its prose, code terms,
+ * headings, and table cells as plain words. Imported only by the adapter's
+ * gatherers.
+ */
+
+import {unlinkText} from '../../foundation/doc-compiler/links.mjs';
+
+/**
+ * The words one section says: its prose, headings, and list items.
+ * @param {any} section
+ * @returns {string[]}
+ */
+export function sectionProse(section) {
+  /** @type {string[]} */
+  const prose = [];
+  if (section?.title) prose.push(section.title);
+  for (const block of section?.content || []) {
+    if ((block.type === 'prose' || block.type === 'heading') && block.text) {
+      prose.push(block.text);
+    } else if (block.type === 'list' && Array.isArray(block.items)) {
+      for (const item of block.items) {
+        const text = typeof item === 'string' ? item : item?.text;
+        if (typeof text === 'string') prose.push(text);
+      }
+    } else if (block.type === 'table' && Array.isArray(block.rows)) {
+      for (const row of block.rows) prose.push(row.map(plain).join(' '));
+    } else if (block.type === 'code' && typeof block.code === 'string') {
+      prose.push([block.label, block.code].filter(Boolean).join(' '));
+    }
+  }
+  return prose;
+}
+
+/**
+ * The identifiers a doc part names in code ticks (`token-ref`,
+ * `ERR_UNKNOWN_SECTION`). Each is a keyword: a reader who types one exactly
+ * wants the part that defines or explains it.
+ * @param {any} part - a section, or `{content}` of a typed doc
+ * @returns {string[]}
+ */
+export function codeTerms(part) {
+  /** @type {Set<string>} */
+  const terms = new Set();
+  /** @param {unknown} text */
+  const scan = text => {
+    for (const m of String(text ?? '').matchAll(/`([^`\s]{2,40})`/g)) {
+      terms.add(m[1]);
+    }
+  };
+  for (const block of part?.content || []) {
+    if (block.type === 'prose') scan(block.text);
+    else if (block.type === 'list' && Array.isArray(block.items)) {
+      for (const item of block.items) {
+        scan(typeof item === 'string' ? item : item?.text);
+      }
+    } else if (block.type === 'table' && Array.isArray(block.rows)) {
+      for (const row of block.rows) for (const cell of row) scan(cell);
+    }
+  }
+  return [...terms];
+}
+
+/**
+ * The headings inside a section. Each names a subsection, so a query that
+ * names one should find the section as surely as one that names its title.
+ * @param {any} section
+ * @returns {string[]}
+ */
+export function headings(section) {
+  return (section?.content || [])
+    .filter(
+      (/** @type {any} */ block) => block.type === 'heading' && block.text,
+    )
+    .map((/** @type {any} */ block) => String(block.text));
+}
+
+/**
+ * A table cell as plain words, without its code ticks.
+ * @param {unknown} cell
+ * @returns {string}
+ */
+export function plain(cell) {
+  return unlinkText(String(cell ?? '')).replaceAll('`', '');
+}

package/api/search/_entries.d.mts

@@ -0,0 +1,63 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The entries search can answer with and their text, by field. Each doc
+ * section is its own entry. Built once per gathered catalog.
+ * @param {any[]} all the gathered candidates
+ * @param {Record<string, {what?: string, synonyms?: string[], props?: string[]}>} cards
+ * @returns {EntryTable}
+ */
+export function entryTable(all: any[], cards: Record<string, {
+    what?: string;
+    synonyms?: string[];
+    props?: string[];
+}>): EntryTable;
+/**
+ * @param {any[]} all
+ * @param {Record<string, {what?: string, synonyms?: string[], props?: string[]}>} cards
+ * @returns {EntryTable}
+ */
+export function buildTable(all: any[], cards: Record<string, {
+    what?: string;
+    synonyms?: string[];
+    props?: string[];
+}>): EntryTable;
+export function entryOf(table: {
+    index: Map<string, number>;
+}, res: {
+    domain: string;
+    name: string;
+    package?: string;
+    section?: string;
+}): number | undefined;
+export function entryId(c: any): string;
+export const HASHED_FIELDS: readonly string[];
+export type EntryTable = {
+    /**
+     * every returnable `<domain>:<name>`, in code-point order
+     */
+    ids: string[];
+    /**
+     * id -> position
+     */
+    index: Map<string, number>;
+    /**
+     * one candidate per id, for its result
+     */
+    candidate: any[];
+    /**
+     * domain index per id
+     */
+    domain: number[];
+    /**
+     * each id's name words
+     */
+    name: string[][];
+    fields: Record<"name" | "desc" | "card", {
+        post: Map<string, [number, number][]>;
+        idf: Map<string, number>;
+        len: number[];
+        avg: number;
+    }>;
+};