@astryxdesign/cli 0.6.5-canary.01972bc → 0.6.5-canary.01fb22f

package/README.md

@@ -69,7 +69,7 @@ Results for "button" (20 of 239):
 
 Options:
 
-- `--type <component|hook|doc|template>`: restrict to a single domain
+- `--type <component|hook|doc|template|theme>`: restrict to a single domain (`doc` and `theme` work outside an app too)
 - `--limit <n>`: cap the number of results (default 20)
 - `--verbose`: also print each result's match score and reason
 - `--json`: typed `{ apiVersion, type: 'search', data: { query, matchCount, results } }` envelope — `matchCount` is how many candidates matched in total, `results` the slice `--limit` allowed
@@ -91,7 +91,7 @@ Options:
 | `init`        | Initialize the design system in your project                                                  |
 | `integration` | Author and verify an Astryx integration package                                               |
 | `layout`      | Generate XDS layouts from compressed expressions (XLE/XLO)                                    |
-| `search`      | Search components, hooks, docs, and templates in one ranked list                              |
+| `search`      | Search components, hooks, docs, templates, and themes in one ranked list                      |
 | `swizzle`     | Copy component source for customization                                                       |
 | `template`    | List, show, or scaffold page and block templates                                              |
 | `theme`       | Create and build themes: add a shipped one, compile to CSS, or list what a theme can override |

package/api/build/_adapter.d.mts

@@ -40,6 +40,20 @@ export function loadPageTemplates(cwd: string): Promise<PageTemplate[]>;
  * @returns {Promise<ComponentWords[]>}
  */
 export function loadComponents(cwd: string): Promise<ComponentWords[]>;
+/**
+ * The matcher weights checked in beside the kit (`kit/weights.json`), read
+ * once; null when the file is absent or unreadable.
+ * @returns {import('./kit/weights.mjs').WeightsFile | null}
+ */
+export function loadWeights(): import("./kit/weights.mjs").WeightsFile | null;
+/**
+ * Whether a parsed weights file has the shape the kit reads: every row has a
+ * weight per candidate, every bias a number per candidate, and three blend
+ * numbers per member (the tables plus the ranker) and one for the shell.
+ * @param {any} file
+ * @returns {file is import('./kit/weights.mjs').WeightsFile}
+ */
+export function isWeightsFile(file: any): file is import("./kit/weights.mjs").WeightsFile;
 /**
  * A page template the kit can recommend starting from.
  */

package/api/build/_adapter.mjs

@@ -2,7 +2,7 @@
 
 /**
  * @file The build subject's environment access: the page templates a project
- * can scaffold, and the components it can use.
+ * can scaffold, the components it can use, and the checked-in matcher weights.
  *
  * @input Template and component discovery for `cwd` — the CLI's own templates
  *   and Core's components, plus any that the project's configured integrations
@@ -16,6 +16,8 @@
  *   from the template subject's, components from search's.
  */
 
+import fs from 'node:fs';
+
 import {discoverTemplates} from '../template/template.mjs';
 import {componentKeywords} from '../search/search.mjs';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
@@ -89,3 +91,58 @@ export async function loadComponents(cwd) {
     return [];
   }
 }
+
+/** @type {import('./kit/weights.mjs').WeightsFile | null | undefined} */
+let weights;
+
+/**
+ * The matcher weights checked in beside the kit (`kit/weights.json`), read
+ * once; null when the file is absent or unreadable.
+ * @returns {import('./kit/weights.mjs').WeightsFile | null}
+ */
+export function loadWeights() {
+  if (weights === undefined) {
+    try {
+      const file = JSON.parse(
+        fs.readFileSync(new URL('./kit/weights.json', import.meta.url), 'utf8'),
+      );
+      weights = isWeightsFile(file) ? file : null;
+    } catch {
+      weights = null;
+    }
+  }
+  return weights ?? null;
+}
+
+/**
+ * Whether a parsed weights file has the shape the kit reads: every row has a
+ * weight per candidate, every bias a number per candidate, and three blend
+ * numbers per member (the tables plus the ranker) and one for the shell.
+ * @param {any} file
+ * @returns {file is import('./kit/weights.mjs').WeightsFile}
+ */
+export function isWeightsFile(file) {
+  const n = Array.isArray(file?.candidates) ? file.candidates.length : 0;
+  return (
+    n > 0 &&
+    Array.isArray(file.tables) &&
+    file.tables.length > 0 &&
+    file.tables.every(
+      (/** @type {any} */ t) =>
+        Array.isArray(t?.words) &&
+        Array.isArray(t.rows) &&
+        t.rows.length === t.words.length &&
+        t.rows.every(
+          (/** @type {any} */ r) => typeof r === 'string' && r.length === n,
+        ) &&
+        Array.isArray(t.bias) &&
+        t.bias.length === n &&
+        t.bias.every((/** @type {any} */ b) => Number.isFinite(b)) &&
+        Number.isFinite(t.clip) &&
+        Number.isFinite(t.step),
+    ) &&
+    Array.isArray(file.blend) &&
+    file.blend.length === 3 * (file.tables.length + 1) + 1 &&
+    file.blend.every((/** @type {any} */ x) => Number.isFinite(x))
+  );
+}

package/api/build/build.test.mjs

@@ -269,7 +269,7 @@ describe('build kit — a thin kit says what to try next', () => {
     // A skeleton is a 35-line excerpt: a reader who studies it and composes
     // the rest loses the spacing the template exists to carry. A loose match
     // is still the best start there is, so `start` scaffolds it.
-    const r = await build('quarterly business review', {cwd: REPO});
+    const r = await build('weekly business review with targets', {cwd: REPO});
     expect(r.type).toBe('build.kit');
     if (r.type !== 'build.kit') return;
     expect(r.data.directMatch).toBe(false);
@@ -477,6 +477,79 @@ describe('build kit — every page starts from a template', () => {
     expect(r.data.pages.map(p => p.name)).not.toContain('side-gallery');
   });
 
+  it('names a direct match the start does not use, and calls the start direct only when it is', async () => {
+    for (const idea of ['a login form', 'a docs site for our API', 'contact form']) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.directMatch).toBe(true);
+      const match = r.data.pages[0].name;
+      if (r.data.start?.name === match) {
+        expect(r.data.start?.basis).toBe('direct');
+      } else {
+        expect(['closest', 'fallback']).toContain(r.data.start?.basis);
+        expect(r.data.start?.reason).toContain(`\`${match}\``);
+      }
+    }
+  });
+
+  it('keeps a template search matched directly rather than the app shell', async () => {
+    for (const [idea, name] of [
+      ['a login screen', 'login'],
+      ['a checkout wizard', 'checkout-wizard'],
+    ]) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.directMatch).toBe(true);
+      expect(r.data.start?.name).toBe(name);
+    }
+  });
+
+  it('lets the weights choose another template over a direct match', async () => {
+    const r = await build('a login form', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.directMatch).toBe(true);
+    const match = r.data.pages[0].name;
+    expect(r.data.start?.name).not.toBe('shell-top-nav');
+    expect(r.data.start?.name).not.toBe(match);
+    expect(r.data.start?.reason).toContain(`\`${match}\``);
+  });
+
+  it('starts a part that names no page from the app shell', async () => {
+    for (const idea of ['a kanban card', 'a date range picker']) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+      expect(r.data.start?.reason).toMatch(/part of a page/);
+    }
+  });
+
+  it('does not keep a loose match over the app shell', async () => {
+    // Search matches no template directly, so the ranker's closest page does
+    // not override the shell the weights choose.
+    const r = await build('quarterly business review', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.directMatch).toBe(false);
+    expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+    expect(r.data.start?.reason).toMatch(/closest/);
+  });
+
+  it('starts a new page with no matching template from the app shell', async () => {
+    const r = await build('a new page', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.start?.name).toBe('shell-top-nav');
+  });
+
+  it('starts a page the words describe from its template', async () => {
+    for (const [idea, name] of [
+      ['a weekly report of sales by region', 'dashboard-scorecard'],
+      ['a pricing page with three plans and a comparison table', 'table-page'],
+    ]) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.start?.name).toBe(name);
+    }
+  });
+
   it('starts a component in a container from a template with that frame', async () => {
     // "in a modal": the modal is the frame, so the dialog template leads
     // instead of the app shell.

package/api/build/kit/kit.mjs

@@ -32,8 +32,15 @@ import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {getResultCoverage} from '../../search/coverage.mjs';
-import {loadComponents, loadPageTemplates} from '../_adapter.mjs';
-import {ideaKind, pickAlternatives, pickStart, rankPages} from './rank.mjs';
+import {loadComponents, loadPageTemplates, loadWeights} from '../_adapter.mjs';
+import {
+  asksForNewPage,
+  ideaKind,
+  pickAlternatives,
+  pickStart,
+  rankPages,
+} from './rank.mjs';
+import {weighStart} from './weights.mjs';
 
 /** A page at/above this score is a confident direct match. */
 const PAGE_DIRECT = 95;
@@ -151,9 +158,10 @@ function placement(kind, inPage) {
  * @param {SearchResultEntry[]} pages
  * @param {boolean} directMatch
  * @param {PageTemplate[]} catalog
+ * @param {string} idea
  * @returns {Omit<BuildStart, 'alternatives'> | null}
  */
-function chooseStart(ranked, kind, pages, directMatch, catalog) {
+function chooseStart(ranked, kind, pages, directMatch, catalog, idea) {
   const direct = directMatch ? pages[0].name : null;
   const unready =
     direct && !catalog.some(t => t.name === direct) ? direct : null;
@@ -170,7 +178,27 @@ function chooseStart(ranked, kind, pages, directMatch, catalog) {
     direct && direct !== startName
       ? `Search matched \`${direct}\` by name, but ${place}`
       : place[0].toUpperCase() + place.slice(1);
-  const pick = pickStart(ranked, kind);
+  const proposed = pickStart(ranked, kind);
+  // The checked-in word weights (weights.mjs), blended with the ranker's
+  // scores, decide the start of a whole page. A part or an edit starts where
+  // the ranker's placement rules put it (spec:AST-048/FR3).
+  const weighed =
+    kind === 'page'
+      ? weighStart(idea, ranked, proposed, catalog, {
+          weights: loadWeights(),
+          newPage: asksForNewPage(idea, catalog),
+        })
+      : undefined;
+  // A shell start keeps the shell the ranker named, if any, and never replaces
+  // the template the ranker chose for a page search matched directly.
+  const pick =
+    weighed === undefined
+      ? proposed
+      : weighed === null
+        ? proposed?.family === 'Shell' || (proposed && direct && !unready)
+          ? proposed
+          : null
+        : (ranked.find(r => r.name === weighed) ?? proposed);
   const closest = pick && catalog.find(t => t.name === pick.name);
   if (pick && closest) {
     const agrees = closest.name === direct;
@@ -194,7 +222,9 @@ function chooseStart(ranked, kind, pages, directMatch, catalog) {
     if (shell) {
       // The shell can also be the ranker's best guess without the evidence to
       // lead ("horizontal site navigation"); say so rather than "no match".
-      const nearest = ranked[0]?.name === shell.name && ranked[0].hits > 0;
+      const nearest =
+        (ranked[0]?.name === shell.name && ranked[0].hits > 0) ||
+        (weighed === null && !!proposed && proposed.family !== 'Shell');
       const place = placement(kind, false);
       return {
         ...asTemplate(shell),
@@ -204,7 +234,9 @@ function chooseStart(ranked, kind, pages, directMatch, catalog) {
           : place
             ? placed(place, shell.name)
             : direct
-              ? `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
+              ? weighed === null
+                ? `Search matched \`${direct}\` by name, but the app shell is the closer start.`
+                : `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
               : nearest
                 ? 'No template is a clear match; the app shell is the closest.'
                 : loose
@@ -346,7 +378,7 @@ export async function buildKit(query, options = {}) {
       )
     : 'page';
   const chosen = wantsPages
-    ? chooseStart(ranked, kind, matchedPages, directMatch, catalog)
+    ? chooseStart(ranked, kind, matchedPages, directMatch, catalog, query)
     : null;
   // Name the ranker's next two templates beside the start: the reader judges
   // meaning better than keywords do, and an acceptable template is in these

package/api/build/kit/rank.d.mts

@@ -21,6 +21,14 @@ export function rankPages(query: string, pages: PageTemplate[]): RankedPage[];
  * @returns {IdeaKind}
  */
 export function ideaKind(query: string, pages: PageTemplate[], components: ComponentWords[]): IdeaKind;
+/**
+ * Whether an idea asks for a new page (see `asksNewPage`), from the idea and
+ * the project's page templates.
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @returns {boolean}
+ */
+export function asksForNewPage(query: string, pages: PageTemplate[]): boolean;
 /**
  * The next closest templates after the start, best first: the ones a reader
  * should check the idea against when the start's shape is wrong. Each matched

package/api/build/kit/rank.mjs

@@ -543,6 +543,20 @@ function asksNewPage(phrases, familyWords) {
   });
 }
 
+/**
+ * Whether an idea asks for a new page (see `asksNewPage`), from the idea and
+ * the project's page templates.
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @returns {boolean}
+ */
+export function asksForNewPage(query, pages) {
+  return asksNewPage(
+    String(query).toLowerCase().split(PHRASE_END),
+    familyWordsOf(pages),
+  );
+}
+
 /**
  * The words of a component's name: "DateRangeInput" is date, range, input.
  * @param {ComponentWords} component

package/api/build/kit/weights.d.mts

@@ -0,0 +1,82 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The Porter stem of a lowercase word.
+ * @param {string} word
+ * @returns {string}
+ */
+export function stem(word: string): string;
+/**
+ * Lowercase words of an idea that can carry weight: letters only, two or more.
+ * @param {string} idea
+ * @returns {string[]}
+ */
+export function weightWords(idea: string): string[];
+/**
+ * Where an idea starts, by the blended weights.
+ * @param {string} idea
+ * @param {import('./rank.mjs').RankedPage[]} ranked the ranker's output for the idea
+ * @param {import('./rank.mjs').RankedPage | null} pick the ranker's own start
+ * @param {{name: string}[]} catalog the project's ready page templates
+ * @param {{weights?: WeightsFile | null, newPage?: boolean}} [options]
+ *   `newPage`: the idea asks for a new page (rank.mjs `asksForNewPage`)
+ * @returns {string | null | undefined} a template id, null for the app shell,
+ *   undefined without weights
+ */
+export function weighStart(idea: string, ranked: import("./rank.mjs").RankedPage[], pick: import("./rank.mjs").RankedPage | null, catalog: {
+    name: string;
+}[], { weights, newPage }?: {
+    weights?: WeightsFile | null;
+    newPage?: boolean;
+}): string | null | undefined;
+/**
+ * @file Word weights for `build`'s START (spec:AST-048): a checked-in table of
+ * per-template word weights, blended with the page ranker's own scores, picks
+ * the template an idea starts from.
+ *
+ * @input An idea, the ranker's output for it (`rankPages`, `pickStart`), the
+ *   project's ready page templates, and the weights (`weights.json` beside this
+ *   file, read by the adapter): the candidates (the app shell as `SHELL`, then page template ids), one or more
+ *   word tables (stemmed words, a bias per candidate, and one row of weights
+ *   per word, a character per candidate) and the blend numbers.
+ * @output `weighStart(idea, ranked, pick, catalog)`: the template id to start
+ *   from, null for the app shell, or undefined when no table is available, in
+ *   which case the ranker's own pick stands.
+ * @position Beside rank.mjs (api/build/kit/); kit.mjs calls it for every
+ *   whole page (a part or an edit follows the ranker's placement rules). The
+ *   ranker's pick of a template the tables do not list stands, so a new
+ *   template can start a build.
+ */
+/** The app shell, as one candidate. */
+export const SHELL: "SHELL";
+export type WeightTable = {
+    /**
+     * stemmed words
+     */
+    words: string[];
+    /**
+     * one per candidate
+     */
+    bias: number[];
+    clip: number;
+    step: number;
+    /**
+     * one per word: a character per candidate,
+     * weight = (charCode - 97) * step - clip
+     */
+    rows: string[];
+};
+export type WeightsFile = {
+    version: number;
+    /**
+     * `SHELL`, then page template ids
+     */
+    candidates: string[];
+    tables: WeightTable[];
+    /**
+     * three numbers per member (the tables, in order,
+     * with the ranker second), then one for `SHELL`
+     */
+    blend: number[];
+};