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

package/api/search/search.test.mjs

@@ -117,16 +117,16 @@ describe('search leaf — docs at the grain a reader reads them', () => {
         .find(result => result.section === 'which-codemods-run');
       expect(hit).toMatchObject({
         domain: 'doc',
-        name: expect.stringMatching(/^cli\/integrations\/(?:.+\/)?codemods$/),
+        name: expect.stringMatching(/^authoring\/(?:.+\/)?codemods$/),
         title: expect.stringMatching(/ › Codemods › Choose when a codemod runs$/),
       });
       expect(hit.parent).toBe(`astryx docs ${hit.name} --index`);
       expect(hit.command).toBe(`astryx docs ${hit.name} which-codemods-run`);
       const block = await search('token-ref', {cwd});
       expect(block.data.results[0]).toMatchObject({
-        name: 'authoring',
+        name: 'authoring/field-reference',
         section: 'reference-doc',
-        command: 'astryx docs authoring reference-doc',
+        command: 'astryx docs authoring/field-reference reference-doc',
       });
       const fn = await search('assertResponse', {cwd, type: 'doc'});
       expect(fn.data.results[0]).toMatchObject({
@@ -148,13 +148,13 @@ describe('search leaf — docs at the grain a reader reads them', () => {
       // keywords and the title the guides declare. A namespace's own
       // keywords count, and a plural name is the name.
       for (const [query, route] of [
-        ['make an integration', /^cli\/integrations$/],
-        ['build an integration', /^cli\/integrations$/],
-        ['create an integration', /^cli\/integrations$/],
-        ['integration', /^cli\/integrations$/],
-        ['publish an integration', /^cli\/integrations$/],
+        ['make an integration', /^authoring$/],
+        ['build an integration', /^authoring$/],
+        ['create an integration', /^authoring$/],
+        ['integration', /^authoring$/],
+        ['publish an integration', /^authoring$/],
         // The troubleshooting guide, wherever the tree places it.
-        ['troubleshoot integration', /^cli\/integrations\/(?:.+\/)?troubleshooting$/],
+        ['troubleshoot integration', /^authoring\/(?:.+\/)?troubleshooting$/],
       ]) {
         const r = await search(query, {cwd, type: 'doc'});
         const names = r.data.results.slice(0, 3).map(result => result.name);
@@ -167,7 +167,7 @@ describe('search leaf — docs at the grain a reader reads them', () => {
   it(
     'gives a top-level namespace hit the topic list as its parent',
     async () => {
-      for (const [query, route] of [['unorganized', 'unorganized'], ['Astryx CLI', 'cli']]) {
+      for (const [query, route] of [['foundations', 'foundations'], ['Astryx CLI', 'cli']]) {
         const r = await search(query, {cwd, type: 'doc'});
         expect(r.data.results).toContainEqual(
           expect.objectContaining({
@@ -185,7 +185,7 @@ describe('search leaf — docs at the grain a reader reads them', () => {
     'points a topic hit at its index, never a whole-topic read',
     async () => {
       // A guide the tree places, read from the tree rather than named.
-      const {data: integrations} = await docs('cli/integrations');
+      const {data: integrations} = await docs('authoring');
       const guide = integrations.slots
         .flatMap(slot => slot.children)
         .find(child => child.kind === 'generic').route;
@@ -440,9 +440,9 @@ describe('search leaf — a candidate that matches every word outranks a partial
     const tokens = await search('tokens', {cwd});
     expect(tokens.data.results[0]).toMatchObject({domain: 'doc', name: 'tokens'});
     for (const [query, route] of [
-      ['codemods', /^cli\/integrations\/(?:.+\/)?codemods$/],
-      ['quick start', /^cli\/integrations\/(?:.+\/)?quick-start$/],
-      ['test in an app', /^cli\/integrations\/(?:.+\/)?test-in-an-app$/],
+      ['codemods', /^authoring\/(?:.+\/)?codemods$/],
+      ['quick start', /^authoring\/(?:.+\/)?quick-start$/],
+      ['test in an app', /^authoring\/(?:.+\/)?test-in-an-app$/],
     ]) {
       const r = await search(query, {cwd, type: 'doc'});
       // The guide is among the hits that share the top score: two guides

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);
+  });
+});