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

package/api/search/search.type.d.mts

@@ -18,7 +18,12 @@ export type SearchResultEntry = {
      */
     name: string;
     /**
-     * - Relevance score (higher is better).
+     * - How strongly the query matched this entry (higher is
+     * stronger). Search keeps the lexical ranker's order between score bands,
+     * including its domain priority, which can place a weaker non-doc match above
+     * a stronger doc; within a run of one score band and kind it orders matches
+     * by its static ordering weights, so a lower score can lead inside a band.
+     * Build's `blocks` use their own order.
      */
     score: number;
     /**

package/api/search/search.type.mjs

@@ -17,7 +17,12 @@
  * @typedef {object} SearchResultEntry
  * @property {SearchDomain} domain - Which content domain this result came from.
  * @property {string} name - Primary identifier (component/hook name, doc topic or docs-tree route, template dir, theme slug).
- * @property {number} score - Relevance score (higher is better).
+ * @property {number} score - How strongly the query matched this entry (higher is
+ *   stronger). Search keeps the lexical ranker's order between score bands,
+ *   including its domain priority, which can place a weaker non-doc match above
+ *   a stronger doc; within a run of one score band and kind it orders matches
+ *   by its static ordering weights, so a lower score can lead inside a band.
+ *   Build's `blocks` use their own order.
  * @property {string} reason - Human-readable reason the candidate matched (e.g. `keyword "button"`).
  * @property {string} description - One-line description, when available.
  * @property {string} command - Follow-up command to act on this result (e.g. `astryx component Button`, or `astryx theme add neutral` for a theme; `astryx theme eject neutral` outside a project).

package/api/search/tree.d.mts

@@ -0,0 +1,15 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export const SEARCH_TREE: import("../../foundation/route/route.mjs").Tree<SearchRequest, import("./_adapter.mjs").SearchCatalog, import("./search.type.mjs").SearchResponse>;
+export type SearchRequest = {
+    query: string;
+    options: {
+        cwd?: string;
+        type?: import("./search.type.mjs").SearchDomain;
+        limit?: number;
+    };
+};
+export type SearchCatalog = import("./_adapter.mjs").SearchCatalog;
+export type SearchAnswer = import("./search.type.mjs").SearchResponse;
+export type SearchKit = import("../../foundation/route/route.mjs").RouteKit<SearchRequest, SearchCatalog, SearchAnswer>;

package/api/search/tree.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file How search answers: a root classifier reads the query's words and
+ * guesses the domain it wants (tree.weights.json), and hands it to that
+ * domain's topic searcher when it is sure enough; otherwise the main searcher
+ * keeps it. Adding a topic searcher is one file and one line here.
+ * @input {query, options} and the gathered catalog with its static data
+ * @output the search response
+ * @position api/search; search.mjs runs it with the shared route helper
+ */
+
+import {routeKit} from '../../foundation/route/route.mjs';
+import {routerTokens} from './_query-words.mjs';
+import {doc} from './_doc-searcher.mjs';
+import {main} from './_main-searcher.mjs';
+import {template} from './_template-searcher.mjs';
+
+/**
+ * @typedef {{query: string, options: {cwd?: string, type?: import('./search.type.mjs').SearchDomain, limit?: number}}} SearchRequest
+ * @typedef {import('./_adapter.mjs').SearchCatalog} SearchCatalog
+ * @typedef {import('./search.type.mjs').SearchResponse} SearchAnswer
+ * @typedef {import('../../foundation/route/route.mjs').RouteKit<SearchRequest, SearchCatalog, SearchAnswer>} SearchKit
+ */
+
+/** @type {SearchKit} */
+const {defineClassifier, defineTree} = routeKit;
+
+const root = defineClassifier({
+  id: 'root',
+  summary:
+    'Guesses the domain a query wants from its words and hands it to that topic searcher, else to the main searcher.',
+  searchers: {doc: doc.id, template: template.id},
+  fallback: main.id,
+  floor: 0.4,
+  features: request => routerTokens(request.query),
+  weights: catalog => catalog.data.router,
+});
+
+export const SEARCH_TREE = defineTree('root', [root, main, doc, template]);

package/api/search/tree.test.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the search tree's root dispatcher (tree.mjs): the router
+ * sends a query to the topic searcher of the domain it wants, and every other
+ * query to the main searcher. Run against the real @astryxdesign/core.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {runTree} from '../../foundation/route/route.mjs';
+import {gatherCandidates, loadSearchData} from './_adapter.mjs';
+import {routeProbs, ROUTES} from './_query-words.mjs';
+import {SEARCH_TREE} from './tree.mjs';
+
+const REPO = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+
+/** @param {string} query */
+async function route(query) {
+  const catalog = {
+    ...(await gatherCandidates({cwd: REPO})),
+    data: loadSearchData(),
+  };
+  /** @type {string[]} */
+  const steps = [];
+  const answer = await runTree(
+    SEARCH_TREE,
+    {query, options: {cwd: REPO}},
+    catalog,
+    {
+      tuning: {onTrace: e => steps.push(e.id)},
+    },
+  );
+  return {steps, answer: /** @type {any} */ (answer)};
+}
+
+describe('search tree', () => {
+  it('sends a doc question to the doc searcher', async () => {
+    const {steps, answer} = await route('how do I install a theme');
+    expect(steps).toEqual(['root', 'doc']);
+    expect(answer.data.results[0].domain).toBe('doc');
+  });
+
+  it('sends a page request to the template searcher', async () => {
+    const {steps, answer} = await route('page of settings with a side menu');
+    expect(steps).toEqual(['root', 'template']);
+    expect(
+      answer.data.results.slice(0, 3).map((/** @type {any} */ r) => r.name),
+    ).toContain('settings');
+  });
+
+  it('sends a component query to the main searcher', async () => {
+    const {steps} = await route('date chooser');
+    expect(steps).toEqual(['root', 'main']);
+  });
+
+  it('gives one probability per class that sums to one', () => {
+    const p = routeProbs(loadSearchData().router, 'toast notice');
+    expect(p).toHaveLength(ROUTES.length);
+    expect(p.reduce((a, b) => a + b, 0)).toBeCloseTo(1, 12);
+  });
+});