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

package/api/search/_words.mjs

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Word matching for search: stems and word forms, word starts,
+ * identifier spelling, joined names, and typo tolerance.
+ */
+
+/**
+ * Light stemmer: strips common English suffixes so "charts"/"charting" and
+ * "chart" share a root. Deliberately crude (no Porter) — good enough to bridge
+ * plural/gerund gaps without a dependency.
+ * @param {string} w
+ * @returns {string}
+ */
+export function stem(w) {
+  let s = w;
+  for (const suf of ['ing', 'ed', 'ies', 'es', 's']) {
+    if (s.length > suf.length + 2 && s.endsWith(suf)) {
+      s = suf === 'ies' ? s.slice(0, -3) + 'y' : s.slice(0, -suf.length);
+      break;
+    }
+  }
+  return s;
+}
+
+/**
+ * The forms of a word that count as the same word: itself, its stem, and its
+ * singular when it ends in a plural suffix — so "tables" is "table",
+ * "statuses" is "status", and "filtering" is "filter".
+ * @param {string} w - Lowercase word.
+ * @returns {Set<string>}
+ */
+export function wordForms(w) {
+  const forms = new Set([w, stem(w)]);
+  if (w.length > 3 && w.endsWith('s')) forms.add(w.slice(0, -1));
+  if (w.length > 4 && w.endsWith('es')) forms.add(w.slice(0, -2));
+  if (w.length > 4 && w.endsWith('ies')) forms.add(w.slice(0, -3) + 'y');
+  // A gerund keeps its verb: "spacing" lost a final e ("space"), and
+  // "dragging" doubled a consonant ("drag"). A past participle does not: it
+  // usually describes a state ("archived notes"), not the action a catalog
+  // word names.
+  if (w.length >= 6 && w.endsWith('ing')) {
+    const base = w.slice(0, -3);
+    forms.add(base);
+    forms.add(`${base}e`);
+    if (/([b-df-hj-np-tv-z])\1$/.test(base)) forms.add(base.slice(0, -1));
+  }
+  return forms;
+}
+
+/**
+ * The singulars a lowercase word may have when it ends in a plural suffix:
+ * "tokens" is "token", "boxes" is "box", "entries" is "entry".
+ * @param {string} w
+ * @returns {string[]}
+ */
+function singulars(w) {
+  /** @type {string[]} */
+  const out = [];
+  if (w.length > 3 && w.endsWith('s')) out.push(w.slice(0, -1));
+  if (w.length > 4 && w.endsWith('es')) out.push(w.slice(0, -2));
+  if (w.length > 4 && w.endsWith('ies')) out.push(w.slice(0, -3) + 'y');
+  return out;
+}
+
+/**
+ * Whether two lowercase words are the same word, up to plural and stem form.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function sameWord(a, b) {
+  if (a === b) return true;
+  const forms = wordForms(a);
+  for (const f of wordForms(b)) if (forms.has(f)) return true;
+  return false;
+}
+
+/**
+ * The lowercase words of a name or keyword: split at non-alphanumerics and at
+ * camelCase boundaries, so "TextInput" is ["text", "input"] and
+ * "Dashboard - Analytics" is ["dashboard", "analytics"].
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function wordsOf(text) {
+  return String(text)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+}
+
+/**
+ * Whether a term is found inside a name or keyword: it is one of its words, or
+ * the start of one (a truncation), and covers at least half of the whole
+ * string. Four letters minimum, so a short term never matches by accident.
+ * @param {string} term - Lowercase term.
+ * @param {string} text - The name or keyword as authored.
+ * @returns {boolean}
+ */
+export function startsAWordOf(term, text) {
+  if (term.length < 4) return false;
+  if (term.length / String(text).length < 0.5) return false;
+  // The term or its singular may start the word: "tokens" starts
+  // "tokenizer" through "token". A singular needs five letters, so "stats"
+  // does not start "status".
+  const starts = [term, ...singulars(term).filter(f => f.length >= 5)];
+  return wordsOf(text).some(
+    w => starts.some(f => w.startsWith(f)) || sameWord(term, w),
+  );
+}
+
+/**
+ * A query with its camelCase and PascalCase identifiers spelled as words, so
+ * `SidebarToggle` reads "sidebar toggle" and `useTablePaginationState` "use
+ * table pagination state". Plain words, and identifiers joined with `_` or `-`, are
+ * unchanged: a joined token that matches nothing stays unmatched.
+ * @param {string} query - The query as typed, before lowercasing.
+ * @returns {string} Lowercased.
+ */
+export function spellIdentifiers(query) {
+  return String(query)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase();
+}
+
+/**
+ * A name or keyword with its separators removed, lowercased: `Side Nav`,
+ * `side-nav`, and `SideNav` all join to `sidenav`.
+ * @param {string} text
+ * @returns {string}
+ */
+export function joined(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '');
+}
+
+/**
+ * The fewest letters both words need before an edit distance counts as a
+ * typo, by distance. Below them, one edit usually makes a different word.
+ */
+const TYPO_MIN_LENGTH = {1: 5, 2: 8, 3: 11};
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @param {number} dist
+ */
+export const isTypo = (a, b, dist) =>
+  dist > 0 &&
+  dist <= 3 &&
+  Math.min(a.length, b.length) >=
+    TYPO_MIN_LENGTH[/** @type {1 | 2 | 3} */ (dist)];

package/api/search/search.d.mts

@@ -1,219 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * Light stemmer: strips common English suffixes so "charts"/"charting" and
- * "chart" share a root. Deliberately crude (no Porter) — good enough to bridge
- * plural/gerund gaps without a dependency.
- * @param {string} w
- * @returns {string}
- */
-export function stem(w: string): string;
-/**
- * Whether two lowercase words are the same word, up to plural and stem form.
- * @param {string} a
- * @param {string} b
- * @returns {boolean}
- */
-export function sameWord(a: string, b: string): boolean;
-/**
- * A query with its camelCase and PascalCase identifiers spelled as words, so
- * `SidebarToggle` reads "sidebar toggle" and `useTablePaginationState` "use
- * table pagination state". Plain words, and identifiers joined with `_` or `-`, are
- * unchanged: a joined token that matches nothing stays unmatched.
- * @param {string} query - The query as typed, before lowercasing.
- * @returns {string} Lowercased.
- */
-export function spellIdentifiers(query: string): string;
-/**
- * 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;
-/**
- * Split a query into meaningful content tokens (lowercased, stopwords + very
- * short words removed). Empty for single-word queries (callers fall back to
- * whole-phrase scoring).
- * @param {string} term - Already-lowercased query.
- * @returns {string[]}
- */
-export function tokenizeQuery(term: string): string[];
-/**
- * A match's domain priority: 0 (none), 1, or 2 (a doc the whole query names).
- * A component, hook, template, or theme with priority ranks ahead of any doc
- * without it, whatever the two scores are. Docs among themselves rank by
- * priority, then score; everything else ranks among itself by score.
- *
- * A component, hook, template, or theme has priority (1) when one of the
- * query's words, or the whole query, hits its name or an authored keyword at
- * {@link STRONG_TOKEN_SCORE} or above, or when it matches every word.
- *
- * A doc has priority when the reader asked for that doc:
- * - 2: the whole query is the topic's name, its last route segment, or its
- *   own title, as words and whatever the plural (`font setup` is
- *   typography/font-setup, `side panel` is "Side panels");
- * - 1: a word of the query is the topic's name (`illustration` in a longer
- *   question is the illustrations guide);
- * - 1: a query of two or more words is one of the topic's own declared
- *   keywords, whatever the plural (`code review` on a guide that declares it);
- * - 1: the query holds one of the doc's titles whole (`resizable side panels`
- *   names "Side panels"; `light dark mode button` names "Light/Dark Mode");
- * - 1: the doc matches every word of the query and one of them is a word of
- *   its title (`switch to a dark theme` and "Use a theme").
- * A section answers to its topic's name.
- *
- * A doc that matched only by a heading holding the query, by one word, or by
- * words spread through its text has no priority. Docs are split into many
- * small topics, each with its own headings, so a common phrase such as
- * `font size` hits a heading exactly (170) while the component the reader is
- * after matches one word by keyword (`Text`, 98). Ranked on text alone, every
- * split adds another doc above the component. Broad reference pages match every word of many queries
- * in their text the same way. The score stays the text-match strength the
- * result reports, so callers that gate on it (`build`) see the same numbers.
- *
- * @param {string} term - Lowercased search term.
- * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
- * @param {Candidate} candidate
- * @param {{score: number, matched: number, total: number}} hit - The
- *   candidate's scoreQuery result.
- * @returns {0 | 1 | 2}
- */
-export function domainPriority(term: string, tokens: string[], candidate: Candidate, hit: {
-    score: number;
-    matched: number;
-    total: number;
-}, queryWords?: string[]): 0 | 1 | 2;
-/**
- * The first title or heading that holds every word of the query, in order and
- * side by side, or null.
- * @param {string} term - Lowercased full query.
- * @param {string[] | undefined} titles
- * @returns {string | null}
- */
-export function headingWithPhrase(term: string, titles: string[] | undefined): string | null;
-/**
- * The first title or heading of two words or more that the query holds whole,
- * in order and side by side, or null. A question such as "how do I add dark
- * mode" names the "Dark mode" section outright, around words no title has.
- * @param {string} term - Lowercased full query.
- * @param {string[] | undefined} titles
- * @returns {string | null}
- */
-export function titleInQuery(term: string, titles: string[] | undefined): string | null;
-/**
- * @param {string} term - Lowercased full query.
- * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
- * @param {Candidate} candidate
- * @param {string[]} [words] - The query's words for compound names (see
- *   compoundHit); empty when the query names an entry outright.
- * @param {{plain?: boolean}} [opts] - `plain`: score without matches on part
- *   of a name or a joined keyword.
- * @returns {{score: number, reason: string, matched: number, total: number, alias?: 'partial' | 'keyword', aliasWords?: number} | null}
- *   `matched`/`total` are the query concepts this candidate answered, out of
- *   the concepts the query had. Callers that must distinguish "matched one word
- *   of three" from "matched all three" — `build`, which gates its pages group
- *   on coverage — cannot recover that from the score, because a single strong
- *   hit and a broad weak one land on the same number.
- */
-export function scoreQuery(term: string, tokens: string[], candidate: Candidate, words?: string[], { plain }?: {
-    plain?: boolean;
-}): {
-    score: number;
-    reason: string;
-    matched: number;
-    total: number;
-    alias?: "partial" | "keyword";
-    aliasWords?: number;
-} | null;
-/**
- * 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;
-/**
- * The components (name and keywords) a search response was scored against, or
- * null when that search was narrowed away from components.
- * @param {object} response
- * @returns {{name: string, keywords: string[]}[] | null}
- */
-export function searchedComponents(response: object): {
-    name: string;
-    keywords: string[];
-}[] | null;
-/**
- * Every component the project can use, Core's and its integrations', with the
- * keywords its own doc declares: the discovery and doc reads search's own
- * candidates use, without the import paths and prose a result carries. `build`
- * reads it to tell a part of a page from a page when its search was narrowed
- * away from components.
- * @param {string} coreDir
- * @param {string} cwd
- * @returns {Promise<{name: string, keywords: string[]}[]>}
- */
-export function componentKeywords(coreDir: string, cwd: string): Promise<{
-    name: string;
-    keywords: string[];
-}[]>;
 /**
  * Unified ranked search across components, hooks, docs, templates, and themes.
  *
@@ -226,99 +13,29 @@ export function componentKeywords(coreDir: string, cwd: string): Promise<{
  */
 export function search(query: string, options?: {
     cwd?: string | undefined;
-    type?: "component" | "hook" | "doc" | "template" | "theme" | undefined;
+    type?: "component" | "hook" | "theme" | "doc" | "template" | undefined;
     limit?: number | undefined;
 }): Promise<import("./search.type.mjs").SearchResponse>;
-export namespace SYNONYMS {
-    let dashboard: string[];
-    let login: string[];
-    let signup: string[];
-    let payment: string[];
-    let pricing: string[];
-    let chat: string[];
-    let settings: string[];
-    let calendar: string[];
-    let table: string[];
-    let gallery: string[];
-    let hero: string[];
-    let form: string[];
-    let profile: string[];
-    let documentation: string[];
-    let navigation: string[];
-}
-/** Valid domain filters for `--type`. */
-export const SEARCH_DOMAINS: string[];
 /**
- * Filler words stripped from multi-word queries so natural-language phrasing
- * ("a page where you can see business stats") ranks on its content words.
- * Exported for `build`, whose page ranker strips the same words.
- */
-export const STOPWORDS: Set<string>;
-/**
- * A search candidate gathered from one content domain. Extra underscore-
- * prefixed fields carry domain-specific payload used only by {@link toResult}.
+ * The lexical ranker alone: keyword and fuzzy scoring of every candidate.
+ * `build` ranks from it.
+ *
+ * @param {string} query
+ * @param {{cwd?: string, type?: 'component'|'hook'|'doc'|'template'|'theme', limit?: number}} [options]
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
-export type Candidate = {
-    domain: "component" | "hook" | "doc" | "template" | "theme";
-    name: string;
-    /**
-     * - Other names the candidate answers to, scored
-     * with the same name signals: a theme's display name.
-     */
-    aliases?: string[] | undefined;
-    keywords?: string[] | undefined;
-    /**
-     * - A doc's own declared keywords: what its
-     * author lists in `keywords`, without the code terms and table cells its
-     * other keywords add.
-     */
-    _declared?: string[] | undefined;
-    weakKeywords?: string[] | undefined;
-    description?: string | undefined;
-    prose?: string[] | undefined;
-    guidance?: string[] | undefined;
-    /**
-     * - A doc's title and the headings inside it:
-     * the lines a reader scans to pick it. The whole query standing in one of
-     * them, or one of them standing whole in the query, is a top-tier match.
-     */
-    titles?: string[] | undefined;
-    _import?: string | undefined;
-    _title?: string | undefined;
-    /**
-     * - A doc result's topic or docs-tree route.
-     */
-    _topic?: string | undefined;
-    /**
-     * - A doc result's section key, when it is one section.
-     */
-    _section?: string | undefined;
-    /**
-     * - The command that reads exactly this doc part.
-     */
-    _command?: string | undefined;
-    /**
-     * - The command that opens the level above a doc
-     * part: its topic's section list, or the docs-tree namespace it sits in.
-     */
-    _parent?: string | undefined;
-    /**
-     * - The npm package that owns the candidate:
-     * Core's package for its components, hooks, and templates, the integration's
-     * for what it contributed, and for a doc part the package that wrote it.
-     */
-    _package?: string | undefined;
-    _displayName?: string | undefined;
-    _kind?: "page" | "block" | undefined;
-    _resultName?: string | undefined;
-    _commandName?: string | undefined;
-    /**
-     * - How an integration component holds its
-     * name, for the owner rule.
-     */
-    _hold?: "file" | "doc" | undefined;
-    /**
-     * - An integration component's doc.
-     */
-    _docPath?: string | undefined;
-};
+export function searchCore(query: string, options?: {
+    cwd?: string;
+    type?: "component" | "hook" | "doc" | "template" | "theme";
+    limit?: number;
+}): Promise<import("./search.type.mjs").SearchResponse>;
+export { scoreCandidate } from "./_candidate-score.mjs";
+export { scoreQuery } from "./_score.mjs";
+export { domainPriority } from "./_priority.mjs";
+export { compoundHit } from "./_compound.mjs";
+export { SYNONYMS } from "./_synonyms.mjs";
+export { searchedComponents } from "./_result.mjs";
+export { componentKeywords } from "./_adapter.mjs";
+export { SEARCH_DOMAINS, STOPWORDS, tokenizeQuery } from "./_query.mjs";
+export { headingWithPhrase, titleInQuery } from "./_titles.mjs";
+export { sameWord, spellIdentifiers, stem } from "./_words.mjs";

package/api/search/search.doc.mjs

@@ -17,11 +17,13 @@ export const doc = {
     'Unified ranked search across components, hooks, docs, templates, and themes.',
   description:
     'The single "I\'m looking for X" entry point across every content domain. ' +
-    'Ranking is keyword + fuzzy (not embeddings); name and keyword signals outrank ' +
-    'incidental prose mentions, so an exact match always sorts first. A component\'s ' +
-    'usage guidance (its best practices) is indexed one tier below its description, ' +
-    'so the words a reader types still find it — but a component that IS the answer ' +
-    'always outranks one whose advice merely mentions the term.' +
+    'Matching and scores are keyword + fuzzy (not embeddings). Between score bands ' +
+    'results keep the lexical order, whose domain priority can put a weaker ' +
+    'component, hook, template, or theme above a stronger doc, and a query that is an entry\'s exact name answers ' +
+    'with that entry first. Inside a band, fixed weights order the matches, so a ' +
+    'description match can lead a keyword match in the same band (55–99 holds both). ' +
+    'A component\'s usage guidance (its best practices) is indexed one tier below ' +
+    'its description, so the words a reader types still find it.' +
     " In global mode: with `cwd` outside a project, items from integrations installed next to this CLI package globally are searched too, and theme results name no step that adds a theme to an app; inside a project, only the project's own integrations count. See {@link namespace:global} and {@link generic:computer-integrations}.",
   importPath: '@astryxdesign/cli/api',
   signature: