@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/api/search/_adapter.d.mts

@@ -1,11 +1,75 @@
 // @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 Core a typed search reads: the project's, else the release's own,
- * installed into the per-user cache first when needed. Throws as
- * requireCoreDir does.
+ * installed into the per-user cache first when needed (a network install and
+ * an npm subprocess; spec AST-081 FR3). Throws as requireCoreDir does.
  * @param {string} cwd
  * @returns {string}
  */
 export function requireSearchCoreDir(cwd: string): string;
+/**
+ * Gathers every candidate the query's domains hold.
+ *
+ * @param {{cwd?: string, type?: string}} options
+ * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null}>}
+ */
+export function gatherCandidates(options: {
+    cwd?: string;
+    type?: string;
+}): Promise<{
+    all: Candidate[];
+    components: Candidate[];
+    searchedComponents: boolean;
+    outside: boolean;
+    coreSkipped: string | null;
+}>;
+/**
+ * The search tree's static data, read once: the entry cards and each node's
+ * weights file.
+ *
+ * These files are static, reviewed data that only order matches inside a score
+ * band; ORDERING.md beside them says what each holds and how
+ * they are refreshed.
+ * @returns {SearchData}
+ */
+export function loadSearchData(): SearchData;
+export { componentKeywords } from "./_gather-components.mjs";
+export type Candidate = import("./_lexical.mjs").Candidate;
+export type SearcherWeights = {
+    w: number[];
+    mu: number[];
+    sd: number[];
+};
+export type SearchData = {
+    /**
+     *  Each Core component's and hook's source-built card: what it is, the words
+     *  people type for it, its main props.
+     */
+    cards: Record<string, {
+        what?: string;
+        synonyms?: string[];
+        props?: string[];
+    }>;
+    /**
+     * The root classifier's weights.
+     */
+    router: import("../../foundation/route/route.mjs").ClassifierWeights;
+    /**
+     * The main searcher's weights.
+     */
+    main: SearcherWeights;
+    /**
+     * The doc searcher's weights.
+     */
+    doc: SearcherWeights;
+    /**
+     * The template searcher's weights.
+     */
+    template: SearcherWeights;
+};
+export type SearchCatalog = Awaited<ReturnType<typeof gatherCandidates>> & {
+    data: SearchData;
+};

package/api/search/_adapter.mjs

@@ -1,25 +1,133 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Environment adapter for search: locating the Core a search reads,
- * including the network install and npm subprocess that fetch a release's
- * own Core outside a project (spec AST-081 FR3; architecture:cli-surface
- * INV21).
- *
- * @input  the folder a search runs in
- * @output the Core folder a search reads
- * @position packages/cli/api/search — imported by search.mjs only
+ * @file Search's adapter: the only place search reads the environment. It
+ * gathers every candidate from the domains a query asks for (one file per
+ * domain, _gather-*.mjs) and loads the tree's static data before it runs.
  */
 
+import {readFileSync} from 'node:fs';
 import {requireCoreDir} from '../../foundation/fs/paths.mjs';
+import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
+import {coreDirOrThrow} from '../error.mjs';
+import {CORELESS_DOMAINS} from './_query.mjs';
+import {gatherComponents} from './_gather-components.mjs';
+import {gatherHooks} from './_gather-hooks.mjs';
+import {gatherDocs} from './_gather-docs.mjs';
+import {gatherTemplates, gatherThemes} from './_gather-templates.mjs';
+
+export {componentKeywords} from './_gather-components.mjs';
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
 
 /**
  * The Core a typed search reads: the project's, else the release's own,
- * installed into the per-user cache first when needed. Throws as
- * requireCoreDir does.
+ * installed into the per-user cache first when needed (a network install and
+ * an npm subprocess; spec AST-081 FR3). Throws as requireCoreDir does.
  * @param {string} cwd
  * @returns {string}
  */
 export function requireSearchCoreDir(cwd) {
   return requireCoreDir(cwd);
 }
+
+/**
+ * Gathers every candidate the query's domains hold.
+ *
+ * @param {{cwd?: string, type?: string}} options
+ * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null}>}
+ */
+export async function gatherCandidates(options) {
+  const {cwd = process.cwd(), type} = options;
+  // `astryx docs` reads docs without @astryxdesign/core, and `astryx theme
+  // list` reads themes without it (bundled themes need no project), so a
+  // search of either must too. Every other domain reads core: asked for by
+  // name, it is an error without core; an open search then covers the docs
+  // and themes alone.
+  const needsCore = !type || !CORELESS_DOMAINS.includes(type);
+  // A domain that reads Core gets it as `component` does: the project's, else
+  // the answering release's own, installed into the per-user cache on first
+  // need (spec AST-081 FR3). Asked for by name, a Core that cannot be had is
+  // the error; an open search answers from the rest and says what it skipped
+  // and why, never silently.
+  /** @type {string | null} */
+  let coreDir = null;
+  /** @type {string | null} */
+  let coreSkipped = null;
+  if (needsCore && type) {
+    coreDir = coreDirOrThrow(requireSearchCoreDir, cwd);
+  } else if (needsCore) {
+    try {
+      coreDir = requireSearchCoreDir(cwd);
+    } catch (error) {
+      coreSkipped = /** @type {Error} */ (error).message;
+    }
+  }
+
+  // Gather candidates from each requested domain in parallel.
+  /** @param {string} d */
+  const wants = d =>
+    (!type && (coreDir != null || CORELESS_DOMAINS.includes(d))) || type === d;
+  const [components, hooks, docTopics, templates, themes] = await Promise.all([
+    wants('component')
+      ? gatherComponents(/** @type {string} */ (coreDir), cwd)
+      : [],
+    wants('hook') ? gatherHooks(/** @type {string} */ (coreDir)) : [],
+    wants('doc') ? gatherDocs(cwd) : [],
+    wants('template') ? gatherTemplates(cwd) : [],
+    wants('theme') ? gatherThemes(cwd) : [],
+  ]);
+
+  const all = [...components, ...hooks, ...docTopics, ...templates, ...themes];
+  // Outside a project a theme cannot be added to an app, so its command forks
+  // the source instead (spec AST-081 FR3).
+  const outside = themes.length > 0 && isOutsideProject(cwd);
+  return {
+    all,
+    components,
+    searchedComponents: wants('component'),
+    outside,
+    coreSkipped,
+  };
+}
+
+/**
+ * @typedef {{w: number[], mu: number[], sd: number[]}} SearcherWeights
+ * @typedef {object} SearchData
+ * @property {Record<string, {what?: string, synonyms?: string[], props?: string[]}>} cards
+ *   Each Core component's and hook's source-built card: what it is, the words
+ *   people type for it, its main props.
+ * @property {import('../../foundation/route/route.mjs').ClassifierWeights} router The root classifier's weights.
+ * @property {SearcherWeights} main The main searcher's weights.
+ * @property {SearcherWeights} doc The doc searcher's weights.
+ * @property {SearcherWeights} template The template searcher's weights.
+ * @typedef {Awaited<ReturnType<typeof gatherCandidates>> & {data: SearchData}} SearchCatalog
+ */
+
+/** @type {SearchData | null} */
+let searchData = null;
+
+/**
+ * The search tree's static data, read once: the entry cards and each node's
+ * weights file.
+ *
+ * These files are static, reviewed data that only order matches inside a score
+ * band; ORDERING.md beside them says what each holds and how
+ * they are refreshed.
+ * @returns {SearchData}
+ */
+export function loadSearchData() {
+  if (!searchData) {
+    /** @param {string} file */
+    const read = file =>
+      JSON.parse(readFileSync(new URL(file, import.meta.url), 'utf8'));
+    searchData = {
+      cards: read('./_cards.json'),
+      router: read('./tree.weights.json'),
+      main: read('./_main-searcher.weights.json'),
+      doc: read('./_doc-searcher.weights.json'),
+      template: read('./_template-searcher.weights.json'),
+    };
+  }
+  return searchData;
+}

package/api/search/_candidate-score.d.mts

@@ -0,0 +1,40 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Score a single candidate against the search term across name, keywords,
+ * and prose signals. Returns the best (highest) score plus a human reason,
+ * or null if nothing matched above the floor.
+ *
+ * @param {string} term - Lowercased search term.
+ * @param {object} candidate
+ * @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
+ * @param {string[]} [candidate.aliases] - Other names, scored like the name (a theme's display name).
+ * @param {string} [candidate.domain] - A component, hook, or template name
+ *   also matches typed as words: `command palette` is CommandPalette.
+ * @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).
+ * @param {string[]} [candidate.weakKeywords] - Derived signal (components a page renders).
+ * @param {string} [candidate.description]
+ * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
+ * @param {string[]} [candidate.guidance] - Usage guidance (features, best practices) — scored a tier below description.
+ * @param {{fuzzy?: boolean, joins?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false. `joins`: read a spaced query joined into a name or keyword (default true); off when the query names an entry outright.
+ * @returns {{score: number, reason: string, alias?: 'partial' | 'keyword'} | null}
+ *   `alias` marks a hit that read the query's words joined.
+ */
+export function scoreCandidate(term: string, { name, aliases, domain, keywords, weakKeywords, description, prose, guidance, }: {
+    name: string;
+    aliases?: string[] | undefined;
+    domain?: string | undefined;
+    keywords?: string[] | undefined;
+    weakKeywords?: string[] | undefined;
+    description?: string | undefined;
+    prose?: string[] | undefined;
+    guidance?: string[] | undefined;
+}, { fuzzy, joins }?: {
+    fuzzy?: boolean;
+    joins?: boolean;
+}): {
+    score: number;
+    reason: string;
+    alias?: "partial" | "keyword";
+} | null;

package/api/search/_candidate-score.mjs

@@ -0,0 +1,238 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file One search term's score against one candidate: name, keyword, prose,
+ * and typo signals.
+ *
+ * Scoring is keyword + fuzzy ranking (NOT semantic / embeddings — that is a
+ * deliberate future follow-up). It reuses the same signal weighting as the
+ * component fuzzy resolver in lib/string-utils.mjs:
+ *
+ *   100  exact name match
+ *    95  name is the term's plural or stem form ("buttons" -> Button)
+ *    90  exact keyword match
+ *    88  keyword is the term's plural or stem form
+ *    80  name Levenshtein distance 1 (one-word lookups, words of 5+ letters)
+ *    70  keyword word prefix / distance 1 (distance: one-word lookups, 5+ letters)
+ *    60  name word prefix (>=4 chars, >=50% coverage)
+ *    60  exact weak-keyword match
+ *    50  description / prose mentions the term
+ *    45  usage guidance mentions the term
+ *    40  name Levenshtein distance 2 (one-word lookups, 8+ letters)
+ *    40  weak-keyword word prefix
+ *    30  keyword Levenshtein distance 2 (one-word lookups, 8+ letters)
+ *    20  name Levenshtein distance 3 (one-word lookups, 11+ letters)
+ *
+ * Name + keyword signals always outweigh description/prose, so an exact match
+ * sorts above an incidental mention.
+ *
+ * A term matches inside a name or keyword only at the start of one of its
+ * words: "dash" finds "dashboard" and "input" finds "TextInput", but "file"
+ * does not find "profile". Edit distance is typo tolerance, so it applies only
+ * to a one-word lookup, where a typo is the likely explanation, and only to
+ * words long enough that one edit rarely makes another real word. In a
+ * sentence, a near miss is usually a different word: "site" is not "side",
+ * "cable" is not "table".
+ */
+
+import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
+import {
+  stem,
+  wordForms,
+  sameWord,
+  startsAWordOf,
+  joined,
+  isTypo,
+} from './_words.mjs';
+import {pluralOf} from './_query.mjs';
+
+/**
+ * Score a single candidate against the search term across name, keywords,
+ * and prose signals. Returns the best (highest) score plus a human reason,
+ * or null if nothing matched above the floor.
+ *
+ * @param {string} term - Lowercased search term.
+ * @param {object} candidate
+ * @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
+ * @param {string[]} [candidate.aliases] - Other names, scored like the name (a theme's display name).
+ * @param {string} [candidate.domain] - A component, hook, or template name
+ *   also matches typed as words: `command palette` is CommandPalette.
+ * @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).
+ * @param {string[]} [candidate.weakKeywords] - Derived signal (components a page renders).
+ * @param {string} [candidate.description]
+ * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
+ * @param {string[]} [candidate.guidance] - Usage guidance (features, best practices) — scored a tier below description.
+ * @param {{fuzzy?: boolean, joins?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false. `joins`: read a spaced query joined into a name or keyword (default true); off when the query names an entry outright.
+ * @returns {{score: number, reason: string, alias?: 'partial' | 'keyword'} | null}
+ *   `alias` marks a hit that read the query's words joined.
+ */
+export function scoreCandidate(
+  term,
+  {
+    name,
+    aliases = [],
+    domain,
+    keywords = [],
+    weakKeywords = [],
+    description = '',
+    prose = [],
+    guidance = [],
+  },
+  {fuzzy = true, joins = true} = {},
+) {
+  let best = 0;
+  let reason = '';
+  /** @type {'partial' | 'keyword' | false} */
+  let alias = false;
+  /**
+   * @param {number} score
+   * @param {string} why
+   * @param {'partial' | 'keyword' | false} [byAlias] - the hit reads the
+   *   query's words joined, into part of a name or into a keyword
+   */
+  const consider = (score, why, byAlias = false) => {
+    if (score > best) {
+      best = score;
+      reason = why;
+      alias = byAlias;
+    }
+  };
+
+  // ── Name signals ────────────────────────────────────────────────
+  // An alias is a name too: a theme answers to its display name as well as
+  // its slug.
+  for (const candidateName of [name, ...aliases.filter(Boolean)]) {
+    const nameLower = candidateName.toLowerCase();
+    // A placed guide's name is its route, and the route's last segment is its
+    // name too, as a flat topic's is: `codemods` is cli/integrations/codemods.
+    const leafLower = nameLower.slice(nameLower.lastIndexOf('/') + 1);
+
+    // A plural of the name is the name: `integration` is the `integrations`
+    // guides, `tab` the `tabs` doc.
+    // A component, hook, or template name typed as words is its name:
+    // `command palette` is CommandPalette. A doc's name is a route or key,
+    // matched as written.
+    const spelled =
+      domain !== 'doc' &&
+      !/[\s_-]/.test(nameLower) &&
+      nameLower === term.replace(/\s+/g, '');
+    if (nameLower === term || leafLower === term || spelled) {
+      consider(100, 'exact name');
+    } else if (
+      joins &&
+      (domain === 'component' || domain === 'hook') &&
+      /\s/.test(term) &&
+      nameLower.startsWith(term.replace(/\s+/g, '')) &&
+      term.replace(/\s+/g, '').length / nameLower.length >= 0.75
+    ) {
+      // Most of the name typed as words, cut short: `complex select` is
+      // ComplexSelector, ahead of a one-word keyword elsewhere.
+      consider(95, `name "${candidateName}" spelled`, 'partial');
+    } else if (pluralOf(nameLower, term) || pluralOf(term, nameLower)) {
+      // One point under the exact spelling, so the doc named `tokens` still
+      // outranks the Token component for `tokens`.
+      consider(99, 'plural of the name');
+    } else {
+      if (sameWord(term, nameLower)) consider(95, `name "${candidateName}"`);
+      // The term is a word of the name, or starts one: "input" in TextInput.
+      else if (startsAWordOf(term, candidateName)) {
+        consider(60, `name contains "${term}"`);
+      }
+      if (fuzzy) {
+        const dist = levenshteinDistance(term, nameLower);
+        if (isTypo(term, nameLower, dist)) {
+          consider(
+            dist === 1 ? 80 : dist === 2 ? 40 : 20,
+            `similar name (distance ${dist})`,
+          );
+        }
+      }
+    }
+  }
+
+  // ── Keyword signals ─────────────────────────────────────────────
+  const termJoined = joined(term);
+  for (const kw of keywords) {
+    const kwLower = String(kw).toLowerCase();
+    // A one-word keyword typed as separate words is the keyword: `number
+    // field` is `numberfield`. Only a
+    // lowercase keyword, one an author declares for a reader to type: a
+    // capitalized one names another entry (a block's `componentsUsed`). A
+    // doc's keywords include code terms, matched as written.
+    if (kwLower === term) {
+      consider(90, `keyword "${kw}"`);
+      continue;
+    }
+    if (
+      joins &&
+      domain !== 'doc' &&
+      /\s/.test(term) &&
+      String(kw) === termJoined
+    ) {
+      consider(90, `keyword "${kw}"`, 'keyword');
+      continue;
+    }
+    if (sameWord(term, kwLower)) {
+      consider(88, `keyword "${kw}"`);
+      continue;
+    }
+    if (startsAWordOf(term, kw)) consider(70, `keyword "${kw}"`);
+    if (fuzzy) {
+      const dist = levenshteinDistance(term, kwLower);
+      if (isTypo(term, kwLower, dist) && dist <= 2) {
+        consider(dist === 1 ? 70 : 30, `keyword "${kw}" (distance ${dist})`);
+      }
+    }
+  }
+
+  // ── Weak keyword signals (derived, not authored) ─────────────────
+  // Capped at 60 so one incidental component match cannot clear the
+  // confident-match gate on its own; it still counts toward multi-term
+  // coverage, which is where "this page renders that" is real evidence.
+  // No Levenshtein tier — fuzzy matching a derived signal is pure noise.
+  for (const kw of weakKeywords) {
+    const kwLower = String(kw).toLowerCase();
+    if (kwLower === term || sameWord(term, kwLower)) {
+      consider(60, `renders ${kw}`);
+      continue;
+    }
+    if (startsAWordOf(term, kw)) consider(40, `renders ${kw}`);
+  }
+
+  // ── Prose / description / guidance signals (stem-tolerant whole word) ──
+  // Match the term's stem as a whole word, tolerating plural/gerund suffixes
+  // so "chart" matches "charts" and "filter" matches "filtering".
+  if (term.length >= 3) {
+    // Any form of the term, with any common suffix: `spacing` finds
+    // "space" and "spaces", `tables` finds "table".
+    const roots = [...new Set([stem(term), ...wordForms(term)])]
+      .filter(f => f.length >= 3)
+      .map(f => f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const re = new RegExp(`\\b(?:${roots.join('|')})(s|es|ing|ed|ies)?\\b`);
+    if (description && re.test(description.toLowerCase())) {
+      consider(50, `description mentions "${term}"`);
+    } else {
+      let matchedProse = false;
+      for (const blob of prose) {
+        if (blob && re.test(String(blob).toLowerCase())) {
+          consider(50, `docs mention "${term}"`);
+          matchedProse = true;
+          break;
+        }
+      }
+      // A tier below prose: guidance is what a component says about USING it,
+      // so the term appearing there is weaker evidence than the component's own
+      // summary. Only consulted when nothing stronger matched.
+      if (!matchedProse) {
+        for (const blob of guidance) {
+          if (blob && re.test(String(blob).toLowerCase())) {
+            consider(45, `guidance mentions "${term}"`);
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  return best > 0 ? {score: best, reason, ...(alias ? {alias} : {})} : null;
+}