@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/api/search/search.d.mts

@@ -9,6 +9,13 @@
  * @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;
 /**
  * Split a query into meaningful content tokens (lowercased, stopwords + very
  * short words removed). Empty for single-word queries (callers fall back to
@@ -47,6 +54,7 @@ export function scoreQuery(term: string, tokens: string[], candidate: Candidate)
  * @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}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
  * @returns {{score: number, reason: string} | null}
  */
 export function scoreCandidate(term: string, { name, keywords, weakKeywords, description, prose, guidance, }: {
@@ -56,6 +64,8 @@ export function scoreCandidate(term: string, { name, keywords, weakKeywords, des
     description?: string | undefined;
     prose?: string[] | undefined;
     guidance?: string[] | undefined;
+}, { fuzzy }?: {
+    fuzzy?: boolean;
 }): {
     score: number;
     reason: string;
@@ -72,11 +82,34 @@ export function scoreCandidate(term: string, { name, keywords, weakKeywords, des
  */
 export function search(query: string, options?: {
     cwd?: string | undefined;
-    type?: "component" | "hook" | "doc" | "template" | undefined;
+    type?: "component" | "hook" | "template" | "doc" | 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}.
@@ -91,6 +124,31 @@ export type Candidate = {
     guidance?: 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 authored a docs-tree
+     * doc part. Flat topics carry none: an extension's sections can come from
+     * another package.
+     */
+    _package?: string | undefined;
     _displayName?: string | undefined;
     _kind?: "page" | "block" | undefined;
+    _resultName?: string | undefined;
+    _commandName?: string | undefined;
 };

package/api/search/search.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'search',
+  namespace: 'cli/api',
   displayName: 'search()',
   summary:
     'Unified ranked search across components, hooks, docs, and templates.',
@@ -46,14 +47,15 @@ export const doc = {
     {
       name: 'options.cwd',
       type: 'string',
-      description: 'Directory to resolve @astryxdesign/core from.',
+      description:
+        "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it.",
     },
   ],
   returns: [
     {
       type: 'search',
       description:
-        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, and `displayName` and `kind` for templates.',
+        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, and `displayName` and `kind` for templates. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the Unorganized level for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from).',
     },
   ],
   throws: [
@@ -63,7 +65,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
-      when: '@astryxdesign/core cannot be found from the cwd',
+      when: '@astryxdesign/core cannot be found from the cwd, and the search reads it: every `type` but `doc`',
     },
   ],
   examples: [