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

package/api/search/_priority.mjs

@@ -0,0 +1,139 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Domain priority: when a component, hook, template, or theme ranks
+ * ahead of docs the reader did not ask for.
+ */
+
+import {sameWord} from './_words.mjs';
+import {phraseWords, samePhraseWord, samePhrase} from './_query.mjs';
+import {compoundHit, compoundOf} from './_compound.mjs';
+import {
+  bestForToken,
+  FULL_COVERAGE_SCORE,
+  STRONG_TOKEN_SCORE,
+} from './_score.mjs';
+import {TITLE_PHRASE_SCORE, TITLE_IN_QUERY_SCORE} from './_titles.mjs';
+import {scoreCandidate} from './_candidate-score.mjs';
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+
+/**
+ * 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,
+  tokens,
+  candidate,
+  hit,
+  queryWords = phraseWords(term),
+) {
+  const words = [term, ...tokens];
+  if (candidate.domain === 'doc') {
+    const topic = String(candidate._topic ?? candidate.name).toLowerCase();
+    // The whole query, read as words, is the topic's route, its last
+    // segment, or its own title, whatever the plural: `side panel` is
+    // layout/side-panels, and `header and footer` is "Headers and footers".
+    // A section's title is a heading inside a topic, not the topic's name.
+    const named = [topic, topic.slice(topic.lastIndexOf('/') + 1)];
+    if (candidate._section == null && candidate.titles?.[0]) {
+      named.push(candidate.titles[0]);
+    }
+    if (named.some(n => samePhrase(term, n))) {
+      return 2;
+    }
+    // A query of two or more words that is one of the doc's own declared
+    // keywords, read as words whatever the plural, is the author naming the
+    // doc for that phrase: `code review` on a guide that declares it. Only
+    // what the author declared counts: the code terms and table cells a
+    // doc's other keywords add (`missing_field`) name what it mentions, not
+    // what it is for. One word is left out too, and a section declares
+    // nothing.
+    if (
+      phraseWords(term).length >= 2 &&
+      candidate._section == null &&
+      (candidate._declared ?? []).some(k => samePhrase(term, String(k)))
+    ) {
+      return 1;
+    }
+    if (
+      words.some(
+        w =>
+          (scoreCandidate(w, {name: topic}, {fuzzy: false})?.score ?? 0) >= 95,
+      )
+    ) {
+      return 1;
+    }
+    // A whole title inside the query is the only path to 160-169.
+    if (hit.score >= TITLE_IN_QUERY_SCORE && hit.score < TITLE_PHRASE_SCORE) {
+      return 1;
+    }
+    // Every word matched, and one of them names the doc in its title.
+    if (
+      hit.score >= FULL_COVERAGE_SCORE &&
+      hit.score < TITLE_IN_QUERY_SCORE &&
+      hit.matched === hit.total
+    ) {
+      const titleWords = phraseWords(candidate.titles?.[0] ?? '');
+      if (
+        (tokens.length ? tokens : [term]).some(t =>
+          titleWords.some(w => samePhraseWord(t, w) || sameWord(t, w)),
+        )
+      ) {
+        return 1;
+      }
+    }
+    return 0;
+  }
+  if (hit.score >= FULL_COVERAGE_SCORE) return 1;
+  const compound = compoundOf.has(candidate)
+    ? compoundOf.get(candidate)
+    : compoundHit(queryWords, candidate);
+  if ((compound?.score ?? 0) >= STRONG_TOKEN_SCORE) {
+    return 1;
+  }
+  const fuzzy = tokens.length <= 1;
+  return words.some(
+    w =>
+      (bestForToken(w, candidate, {fuzzy})?.score ?? 0) >= STRONG_TOKEN_SCORE,
+  )
+    ? 1
+    : 0;
+}

package/api/search/_query-words.d.mts

@@ -0,0 +1,25 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** Plural folding: one fixed rule per suffix. @param {string} w */
+export function fold(w: string): string;
+/** A name's words: `DateRangeInput` is date, range, input. @param {string} name */
+export function nameWords(name: string): string[];
+/** @param {string} q @returns {string[]} unique words, then adjacent pairs */
+export function queryTokens(q: string): string[];
+/** The router's inputs: the query's tokens plus four shape flags. @param {string} q */
+export function routerTokens(q: string): string[];
+/**
+ * The router's probability for each class: the shared classifier over the
+ * query's tokens.
+ * @param {import('../../foundation/route/route.mjs').ClassifierWeights} weights
+ * @param {string} q
+ * @returns {number[]}
+ */
+export function routeProbs(weights: import("../../foundation/route/route.mjs").ClassifierWeights, q: string): number[];
+/** The domains, in the order the weights files index them. */
+export const DOMAINS: string[];
+/** The router's classes: the domain a query wants, or none. */
+export const ROUTES: string[];
+export function words(text: string): string[];
+export function queryWords(q: string): string[];

package/api/search/_query-words.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file How search's searchers and classifier read a query: its words,
+ * folded forms, word pairs, and the classifier's tokens and class
+ * probabilities.
+ */
+
+import {classify} from '../../foundation/route/route.mjs';
+
+/** The domains, in the order the weights files index them. */
+export const DOMAINS = ['component', 'hook', 'doc', 'template', 'theme'];
+
+/** The router's classes: the domain a query wants, or none. */
+export const ROUTES = [...DOMAINS, 'NONE'];
+
+const STOP = new Set(
+  'a an the of for to with and or in on by is it my me i we you this that be as at from use using how what which show make add create get set any can do does not no into via'.split(
+    ' ',
+  ),
+);
+
+const QUESTION = new Set([
+  'how',
+  'what',
+  'why',
+  'when',
+  'where',
+  'can',
+  'does',
+  'is',
+]);
+
+/** @param {string} text @returns {string[]} */
+export const words = text =>
+  (text || '').toLowerCase().match(/[a-z0-9]+/g) ?? [];
+
+/** Plural folding: one fixed rule per suffix. @param {string} w */
+export function fold(w) {
+  if (w.length > 4 && w.endsWith('ies')) return `${w.slice(0, -3)}y`;
+  if (w.length > 3 && w.endsWith('es') && 'sxz'.includes(w[w.length - 3])) {
+    return w.slice(0, -2);
+  }
+  if (w.length > 3 && w.endsWith('s') && !w.endsWith('ss'))
+    return w.slice(0, -1);
+  return w;
+}
+
+/** A name's words: `DateRangeInput` is date, range, input. @param {string} name */
+export function nameWords(name) {
+  const s = name
+    .replace(/[/-]/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2');
+  return words(s);
+}
+
+/** The query's content words, folded. @param {string} q */
+export const queryWords = q =>
+  words(q)
+    .filter(w => !STOP.has(w))
+    .map(fold);
+
+/** @param {string} q @returns {string[]} unique words, then adjacent pairs */
+export function queryTokens(q) {
+  const qw = queryWords(q);
+  const pairs = qw.slice(1).map((w, i) => `${qw[i]}_${w}`);
+  return [...new Set([...qw, ...pairs])];
+}
+
+/** The router's inputs: the query's tokens plus four shape flags. @param {string} q */
+export function routerTokens(q) {
+  const ws = words(q);
+  const flags = [`#n${Math.min(ws.length, 6)}`];
+  if (ws.length && QUESTION.has(ws[0])) flags.push('#question');
+  if (q.split(/\s+/).some(w => /^use[a-z]+/.test(w)) || /\buse[A-Z]/.test(q)) {
+    flags.push('#usehook');
+  }
+  if (/[A-Z][a-z]+[A-Z]/.test(q)) flags.push('#camel');
+  return [...queryTokens(q), ...flags, '#bias'];
+}
+
+/**
+ * The router's probability for each class: the shared classifier over the
+ * query's tokens.
+ * @param {import('../../foundation/route/route.mjs').ClassifierWeights} weights
+ * @param {string} q
+ * @returns {number[]}
+ */
+export function routeProbs(weights, q) {
+  return classify(weights, routerTokens(q));
+}

package/api/search/_query.d.mts

@@ -0,0 +1,65 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * 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[];
+/**
+ * Score a candidate against a query, handling multi-word natural language.
+ * Tries the whole phrase (so exact/near matches still win) AND a per-token
+ * pass (so "data table with filters" matches `table-page` via table+filter),
+ * and returns whichever is stronger.
+ *
+ * @param {string} term - Lowercased full query.
+ * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
+ * @param {object} candidate
+ * @returns {{score: number, reason: string} | null}
+ */
+/**
+ * The words of a title or query, lowercased, without punctuation or code ticks.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function phraseWords(text: string): string[];
+/**
+ * Whether two words are the same word, allowing a plural on either side, so
+ * `data attributes selector` still reads "Data attribute selectors".
+ * @param {string} a
+ * @param {string} b
+ */
+export function samePhraseWord(a: string, b: string): boolean;
+/**
+ * Whether two phrases are the same words, in order, ignoring case,
+ * punctuation, and a plural on any word: `side panel` is "Side panels", and
+ * `headers and footers` is `header-and-footer`.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function samePhrase(a: string, b: string): boolean;
+/**
+ * Whether `plural` is the plural of `word`: `integrations` of `integration`,
+ * `boxes` of `box`. `es` only follows s, x, z, ch, or sh, so `notes` is not a
+ * plural of `not`.
+ * @param {string} plural
+ * @param {string} word
+ */
+export function pluralOf(plural: string, word: string): boolean;
+/** Valid domain filters for `--type`. */
+export const SEARCH_DOMAINS: string[];
+/**
+ * The domains a search reads without @astryxdesign/core. An open search outside
+ * an app covers these alone.
+ */
+export const CORELESS_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>;

package/api/search/_query.mjs

@@ -0,0 +1,176 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Reading a search query: its domains, stopwords, content tokens, and
+ * phrase words.
+ */
+
+import {unlinkText} from '../../foundation/doc-compiler/links.mjs';
+import {sameWord} from './_words.mjs';
+
+/** Valid domain filters for `--type`. */
+export const SEARCH_DOMAINS = ['component', 'hook', 'doc', 'template', 'theme'];
+
+/**
+ * The domains a search reads without @astryxdesign/core. An open search outside
+ * an app covers these alone.
+ */
+export const CORELESS_DOMAINS = ['doc', 'theme'];
+
+/**
+ * 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 = new Set([
+  'a',
+  'an',
+  'the',
+  'of',
+  'for',
+  'to',
+  'with',
+  'and',
+  'or',
+  'in',
+  'on',
+  'at',
+  'by',
+  'that',
+  'this',
+  'my',
+  'your',
+  'our',
+  'their',
+  'is',
+  'are',
+  'be',
+  'it',
+  'its',
+  'as',
+  'from',
+  'page',
+  'screen',
+  'app',
+  'application',
+  'view',
+  'where',
+  'you',
+  'can',
+  'some',
+  'like',
+  'just',
+  'basically',
+  'kinda',
+  'want',
+  'wants',
+  'need',
+  'needs',
+  'something',
+  'thing',
+  'things',
+  'build',
+  'make',
+  'create',
+  'i',
+  'me',
+  'we',
+  'us',
+  'so',
+  'up',
+  'out',
+  'over',
+  'side',
+  'one',
+  'big',
+]);
+
+/**
+ * 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) {
+  return (
+    term
+      .split(/\s+/)
+      // Strip only leading/trailing punctuation; keep joined identifiers intact
+      // (e.g. "foo_bar" stays one token) so gibberish stays gibberish.
+      .map(t => t.replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, ''))
+      .filter(t => t.length >= 2 && !STOPWORDS.has(t))
+  );
+}
+
+/**
+ * Score a candidate against a query, handling multi-word natural language.
+ * Tries the whole phrase (so exact/near matches still win) AND a per-token
+ * pass (so "data table with filters" matches `table-page` via table+filter),
+ * and returns whichever is stronger.
+ *
+ * @param {string} term - Lowercased full query.
+ * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
+ * @param {object} candidate
+ * @returns {{score: number, reason: string} | null}
+ */
+
+/**
+ * The words of a title or query, lowercased, without punctuation or code ticks.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function phraseWords(text) {
+  return (
+    unlinkText(text)
+      .toLowerCase()
+      .match(/[a-z0-9]+/g) ?? []
+  );
+}
+
+/**
+ * Whether two words are the same word, allowing a plural on either side, so
+ * `data attributes selector` still reads "Data attribute selectors".
+ * @param {string} a
+ * @param {string} b
+ */
+export function samePhraseWord(a, b) {
+  return (
+    a === b ||
+    `${a}s` === b ||
+    `${b}s` === a ||
+    `${a}es` === b ||
+    `${b}es` === a
+  );
+}
+
+/**
+ * Whether two phrases are the same words, in order, ignoring case,
+ * punctuation, and a plural on any word: `side panel` is "Side panels", and
+ * `headers and footers` is `header-and-footer`.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function samePhrase(a, b) {
+  const x = phraseWords(a);
+  const y = phraseWords(b);
+  return (
+    x.length > 0 &&
+    x.length === y.length &&
+    x.every((w, k) => samePhraseWord(w, y[k]) || sameWord(w, y[k]))
+  );
+}
+
+/**
+ * Whether `plural` is the plural of `word`: `integrations` of `integration`,
+ * `boxes` of `box`. `es` only follows s, x, z, ch, or sh, so `notes` is not a
+ * plural of `not`.
+ * @param {string} plural
+ * @param {string} word
+ */
+export function pluralOf(plural, word) {
+  if (word.length < 3) return false;
+  if (plural === `${word}s`) return true;
+  return /(?:s|x|z|ch|sh)$/.test(word) && plural === `${word}es`;
+}

package/api/search/_result.d.mts

@@ -0,0 +1,97 @@
+// @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 */
+/**
+ * Map a scored candidate to its public, actionable result shape. Each result
+ * carries enough to act on it: the domain, name, a one-line description, and
+ * the follow-up command (and import path where relevant).
+ *
+ * @param {Candidate} c - candidate
+ * @param {number} score
+ * @param {string} reason
+ * @param {number} matchedTerms - Query concepts this result answered.
+ * @param {number} queryTerms - Query concepts there were to answer.
+  * @param {boolean} [outside] - The search runs outside a project, where a
+ *   theme cannot be added to an app, so its command forks the source instead
+ *   (spec AST-081 FR3).
+ */
+export function toResult(c: Candidate, score: number, reason: string, matchedTerms: number, queryTerms: number, outside?: boolean): {
+    domain: "component" | "hook" | "theme" | "doc" | "template";
+    name: string;
+    package: string | undefined;
+    score: number;
+    reason: string;
+    description: string;
+} | {
+    import: string | undefined;
+    command: string;
+    domain: "component" | "hook" | "theme" | "doc" | "template";
+    name: string;
+    package: string | undefined;
+    score: number;
+    reason: string;
+    description: string;
+} | {
+    parent?: string | undefined;
+    title: string | undefined;
+    command: string;
+    section?: string | undefined;
+    name: string;
+    domain: "component" | "hook" | "theme" | "doc" | "template";
+    package: string | undefined;
+    score: number;
+    reason: string;
+    description: string;
+} | {
+    displayName: string | undefined;
+    kind: "page" | "block" | undefined;
+    command: string;
+    domain: "component" | "hook" | "theme" | "doc" | "template";
+    name: string;
+    package: string | undefined;
+    score: number;
+    reason: string;
+    description: string;
+} | {
+    displayName: string | undefined;
+    command: string;
+    domain: "component" | "hook" | "theme" | "doc" | "template";
+    name: string;
+    package: string | undefined;
+    score: number;
+    reason: string;
+    description: string;
+};
+/**
+ * Throws the search argument errors: an empty query, an unknown type, a limit
+ * that is not a positive integer.
+ *
+ * @param {string} query
+ * @param {{type?: string, limit?: number}} options
+ */
+export function checkSearchArgs(query: string, options: {
+    type?: string;
+    limit?: number;
+}): void;
+/**
+ * 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;
+/**
+ * The components each search response was scored against, by response:
+ * `build` reads them to tell a part of a page from a page without gathering
+ * them again. Module-private, so they never enter search's JSON.
+ * @type {WeakMap<object, {name: string, keywords: string[]}[]>}
+ */
+export const searchedComponentsOf: WeakMap<object, {
+    name: string;
+    keywords: string[];
+}[]>;
+export type Candidate = import("./_lexical.mjs").Candidate;