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

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;

package/api/search/_result.mjs

@@ -0,0 +1,150 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Search's arguments and results: argument checks, the result each
+ * candidate becomes, and the components a search read.
+ */
+
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {setResultCoverage} from './coverage.mjs';
+import {SEARCH_DOMAINS} from './_query.mjs';
+
+/** @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,
+  score,
+  reason,
+  matchedTerms,
+  queryTerms,
+  outside = false,
+) {
+  const base = {
+    domain: c.domain,
+    name: c._resultName ?? c.name,
+    package: c._package,
+    score,
+    reason,
+    description: c.description || '',
+  };
+  let result;
+  switch (c.domain) {
+    case 'component':
+      result = {
+        ...base,
+        import: c._import,
+        command: c._command ?? `astryx component ${c.name}`,
+      };
+      break;
+    case 'hook':
+      result = {
+        ...base,
+        import: c._import,
+        command: `astryx hook ${c.name}`,
+      };
+      break;
+    case 'doc':
+      // A doc result names its topic or route, plus the section when the
+      // hit is one section; its command reads exactly that part.
+      result = {
+        ...base,
+        name: c._topic ?? c.name,
+        ...(c._section ? {section: c._section} : {}),
+        title: c._title,
+        command: c._command ?? `astryx docs ${c.name}`,
+        ...(c._parent ? {parent: c._parent} : {}),
+      };
+      break;
+    case 'template':
+      result = {
+        ...base,
+        displayName: c._displayName,
+        kind: c._kind,
+        command: `astryx template ${c._commandName ?? c.name} --type ${c._kind}`,
+      };
+      break;
+    case 'theme':
+      result = {
+        ...base,
+        displayName: c._displayName,
+        command: outside
+          ? `astryx theme eject ${c.name}`
+          : `astryx theme add ${c.name}`,
+      };
+      break;
+    default:
+      result = base;
+  }
+  return setResultCoverage(result, matchedTerms, queryTerms);
+}
+
+/**
+ * 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, options) {
+  const {type, limit = 20} = options;
+
+  if (!query || !String(query).trim()) {
+    throw new AstryxError(
+      'A search query is required',
+      [{name: 'astryx search button', reason: 'example'}],
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+
+  if (type && !SEARCH_DOMAINS.includes(type)) {
+    throw new AstryxError(
+      `Unknown --type "${type}"`,
+      SEARCH_DOMAINS.map(d => ({name: d, reason: 'valid type'})),
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+
+  // Validate limit here (not just in the CLI) so direct API callers get the same
+  // contract: a non-positive or non-integer limit is an error, never a silent
+  // "return everything". (Previously `limit <= 0` fell through to the full set.)
+  if (limit != null && (!Number.isInteger(limit) || limit <= 0)) {
+    throw new AstryxError(
+      `Invalid limit "${limit}". Must be a positive integer.`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+}
+
+/**
+ * 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 = new WeakMap();
+
+/**
+ * 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) {
+  return searchedComponentsOf.get(response) ?? null;
+}

package/api/search/_score.d.mts

@@ -0,0 +1,60 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Best score for a token against a candidate, fanning out through synonyms
+ * (synonym hits are discounted so a direct hit always wins).
+ * @param {string} tok
+ * @param {Candidate} candidate
+ * @param {{fuzzy?: boolean}} [opts]
+ * @returns {{score: number, reason: string} | null}
+ */
+export function bestForToken(tok: string, candidate: Candidate, opts?: {
+    fuzzy?: boolean;
+}): {
+    score: number;
+    reason: 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;
+/**
+ * The score of a candidate that matches every content word of a multi-word
+ * query, before a bonus of up to 8 for how strong its strongest match is: just
+ * above anything that matches only some of the words. The token-sum path tops
+ * out near 150 for a partial match (a 100 on one word, the per-word bonus, and
+ * the coverage term), so an AND-match with one keyword-strength hit (see
+ * {@link STRONG_TOKEN_SCORE}) always outranks an OR-match, and stays below the
+ * title tiers.
+ */
+export const FULL_COVERAGE_SCORE: 151;
+/**
+ * The strongest single-word hit an every-word match needs to take that tier: a
+ * keyword substring. Two passing mentions in prose, or the components a page
+ * happens to render, are breadth, not relevance; they stay on the token sum,
+ * below an exact name or keyword hit on one of the words.
+ */
+export const STRONG_TOKEN_SCORE: 70;
+export type Candidate = import("./_lexical.mjs").Candidate;