@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/build/_adapter.mjs

@@ -2,20 +2,23 @@
 
 /**
  * @file The build subject's environment access: the page templates a project
- * can scaffold.
+ * can scaffold, and the components it can use.
  *
- * @input Template discovery for `cwd` — the CLI's own templates plus any that
- *   the project's configured integrations contribute.
+ * @input Template and component discovery for `cwd` — the CLI's own templates
+ *   and Core's components, plus any that the project's configured integrations
+ *   contribute.
  * @output Ready page templates as `{name, displayName, description, category,
- *   command}`, where `command` is the `astryx template` command that selects
- *   exactly that template.
- * @position Beside build.mjs (api/build/). The kit leaf reads templates only
- *   through here, because a subject's `_adapter.mjs` is its only environment
- *   access. Search keeps its own discovery; this adds none of its own, it
- *   reuses the template subject's.
+ *   keywords, command}`, where `command` is the `astryx template` command that
+ *   selects exactly that template; components as `{name, keywords}`.
+ * @position Beside build.mjs (api/build/). The kit leaf reads templates and
+ *   components only through here, because a subject's `_adapter.mjs` is its
+ *   only environment access. This adds no discovery of its own: templates come
+ *   from the template subject's, components from search's.
  */
 
 import {discoverTemplates} from '../template/template.mjs';
+import {componentKeywords} from '../search/search.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 
 /**
  * A page template the kit can recommend starting from.
@@ -23,8 +26,16 @@ import {discoverTemplates} from '../template/template.mjs';
  * @property {string} name The template's own id, as search reports it.
  * @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
  * @property {string} displayName Human-facing name.
- * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} description What the page is and how it is laid out.
  * @property {string} category The template's own `Family - Variant` label; empty when it declares none.
+ * @property {string[]} keywords The ideas the page serves, as its own descriptor names them; empty when it declares none.
+ */
+
+/**
+ * A component the project can use, as the ranker reads it.
+ * @typedef {object} ComponentWords
+ * @property {string} name The component's name, e.g. `DateRangeInput`.
+ * @property {string[]} keywords The keywords its own doc declares.
  */
 
 /**
@@ -53,8 +64,28 @@ export async function loadPageTemplates(cwd) {
       displayName: t.displayName || t.name,
       description: t.description || '',
       category: t.category || '',
+      keywords: t.keywords ?? [],
       // The id `template()` resolves back to this entry: an active replacement
       // owns the Core id it names, so that id selects it, not its own.
       command: `astryx template ${t.replaces ?? t.dirName} --type page`,
     }));
 }
+
+/**
+ * The components the project can use, Core's and its integrations', each with
+ * the keywords its own doc declares: what the ranker reads to tell a part of a
+ * page from a page. Search's own discovery, so both agree on what exists; empty
+ * when Core cannot be found.
+ *
+ * @param {string} cwd
+ * @returns {Promise<ComponentWords[]>}
+ */
+export async function loadComponents(cwd) {
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) return [];
+  try {
+    return await componentKeywords(coreDir, cwd);
+  } catch {
+    return [];
+  }
+}

package/api/build/build.doc.mjs

@@ -19,8 +19,8 @@ export const doc = {
     'The "build a page" entry point. Called with no query it returns the ' +
     'how-to-build-a-page playbook as data: the workflow steps with their ' +
     'commands, the on-system rules, and related lookups. Called with a query it names the page template to ' +
-    'START from (always one: the page template a ranker built for long descriptions puts first, else the app ' +
-    'shell) and the next two templates, ' +
+    'START from (always one: the page template a ranker built for long descriptions puts first; for a part ' +
+    'of a page, the page it names; else the app shell) and the next two templates, ' +
     'and the unified search grouped around it: the other close page templates, drop-in blocks, and ' +
     'idea-specific components/hooks, plus the always-on frame + foundation. A template carries the page ' +
     'frame and spacing, so the kit never recommends composing a page from components.',
@@ -40,6 +40,7 @@ export const doc = {
       type: 'string',
       description:
         'Directory to resolve @astryxdesign/core and templates from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.type',
@@ -69,7 +70,11 @@ export const doc = {
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'options.type is not a known domain, or options.limit is not a positive integer',
+      when: 'a query is given and options.type is not a known domain, or options.limit is not a positive integer',
+    },
+    {
+      code: 'ERR_CORE_NOT_FOUND',
+      when: 'a query is given and @astryxdesign/core cannot be found from cwd',
     },
   ],
   examples: [

package/api/build/build.test.mjs

@@ -8,7 +8,7 @@ import {describe, it, expect, vi} from 'vitest';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {build} from './build.mjs';
-import {search} from '../search/search.mjs';
+import {search, searchedComponents} from '../search/search.mjs';
 
 // api/build/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
 const REPO = path.resolve(
@@ -152,6 +152,16 @@ describe('build API', () => {
   });
 });
 
+describe('build kit — reuses the components its search gathered', () => {
+  it('keeps them beside the search response, out of its JSON', async () => {
+    const all = await search('date picker', {cwd: REPO});
+    expect(searchedComponents(all)?.map(c => c.name)).toContain('DateRangeInput');
+    expect(JSON.stringify(all)).not.toContain('"keywords"');
+    const pagesOnly = await search('date picker', {cwd: REPO, type: 'template'});
+    expect(searchedComponents(pagesOnly)).toBeNull();
+  }, 60_000);
+});
+
 describe('build kit — coverage gates the pages group', () => {
   it('does not call a one-word coincidence a direct match', async () => {
     // A page's keywords include every component its source renders, so any
@@ -179,6 +189,28 @@ describe('build kit — coverage gates the pages group', () => {
     }
   });
 
+  it('does not call a page that only mentions every word a direct match', async () => {
+    // `empty state` and `command palette` name components. A page whose text
+    // mentions both words, or that renders the component, is a layout
+    // reference, not the page the reader asked for.
+    for (const query of ['empty state', 'command palette']) {
+      const r = await build(query, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error('expected build.kit');
+      expect(r.data.directMatch, query).toBe(false);
+    }
+  });
+
+  it('keeps the page and component a query names first', async () => {
+    const pageOf = async (/** @type {string} */ query) => {
+      const r = await build(query, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error('expected build.kit');
+      return r.data;
+    };
+    expect((await pageOf('checkout flow')).pages[0]).toMatchObject({name: 'checkout-wizard'});
+    expect((await pageOf('sign in with sso')).pages[0]).toMatchObject({name: 'login-sso'});
+    expect((await pageOf('search results')).domain.map(e => e.name)).toContain('PowerSearch');
+  });
+
   it('leaves single-concept queries alone (nothing to cover)', async () => {
     const r = await build('dashboard', {cwd: REPO});
     expect(r.type).toBe('build.kit');
@@ -237,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('executive summary', {cwd: REPO});
+    const r = await build('quarterly business review', {cwd: REPO});
     expect(r.type).toBe('build.kit');
     if (r.type !== 'build.kit') return;
     expect(r.data.directMatch).toBe(false);
@@ -335,9 +367,35 @@ describe('build kit — every page starts from a template', () => {
     const placed = await build('an empty state for a settings page', {cwd: REPO});
     if (placed.type !== 'build.kit') throw new Error(placed.type);
     expect(placed.data.start).toMatchObject({name: 'settings', basis: 'closest'});
+    expect(placed.data.start?.reason).toMatch(/part of a page, so it starts from the page it names/);
     const loose = await build('a date range picker', {cwd: REPO});
     if (loose.type !== 'build.kit') throw new Error(loose.type);
     expect(loose.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+    expect(loose.data.start?.reason).toMatch(/part of a page and names no page, so it starts from the app shell/);
+  });
+
+  it('starts a change to an existing page from the app shell', async () => {
+    // The page is the builder's to keep; no template scaffolds it.
+    const r = await build('add a sort toggle to the existing reports dashboard', {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(/changes a page you already have, so keep it/);
+    expect(r.data.start?.reason).not.toMatch(/too little of the idea fits/);
+    // A direct match the response reports is still named.
+    if (r.data.directMatch) expect(r.data.start?.reason).toContain(`\`${r.data.pages[0].name}\``);
+  });
+
+  it('does not call a new page that mentions something existing a change', async () => {
+    for (const idea of [
+      'a new dashboard inspired by the existing one',
+      'a new dashboard based on the existing dashboard',
+      'clone the existing dashboard as a new page',
+    ]) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.start?.name).toBe('dashboard');
+      expect(r.data.start?.reason).not.toMatch(/already have/);
+    }
   });
 
   it('names a direct match the ranker outweighed in the reason', async () => {

package/api/build/kit/kit.mjs

@@ -27,10 +27,13 @@
  * the invocation stays the renderer's job.
  */
 
-import {search} from '../../search/search.mjs';
+import {search, searchedComponents} from '../../search/search.mjs';
+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 {loadPageTemplates} from '../_adapter.mjs';
-import {pickAlternatives, pickStart, rankPages} from './rank.mjs';
+import {loadComponents, loadPageTemplates} from '../_adapter.mjs';
+import {ideaKind, pickAlternatives, pickStart, rankPages} from './rank.mjs';
 
 /** A page at/above this score is a confident direct match. */
 const PAGE_DIRECT = 95;
@@ -115,6 +118,24 @@ const asTemplate = t => ({
   command: `${t.command} <path>`,
 });
 
+/**
+ * Why a part of a page, or a change to a page the builder already has, starts
+ * where it does (spec:AST-048/FR3, FR9): the rest of the start's reason, or
+ * null for a whole page.
+ * @param {import('./rank.mjs').IdeaKind} kind
+ * @param {boolean} inPage whether the start is the page the idea names
+ * @returns {string | null}
+ */
+function placement(kind, inPage) {
+  if (kind === 'edit')
+    return 'the idea changes a page you already have, so keep it and add blocks to it; a new page starts from the app shell.';
+  if (kind === 'part')
+    return inPage
+      ? 'the idea is a part of a page, so it starts from the page it names.'
+      : 'the idea is a part of a page and names no page, so it starts from the app shell.';
+  return null;
+}
+
 /**
  * The template to start from: the ready page the ranker puts first when it
  * has the evidence to lead, else the first fallback shell the project can
@@ -126,12 +147,13 @@ const asTemplate = t => ({
  * the reason names it, so the reader knows why the kit starts elsewhere.
  *
  * @param {import('./rank.mjs').RankedPage[]} ranked
+ * @param {import('./rank.mjs').IdeaKind} kind
  * @param {SearchResultEntry[]} pages
  * @param {boolean} directMatch
  * @param {PageTemplate[]} catalog
  * @returns {Omit<BuildStart, 'alternatives'> | null}
  */
-function chooseStart(ranked, pages, directMatch, catalog) {
+function chooseStart(ranked, kind, pages, directMatch, catalog) {
   const direct = directMatch ? pages[0].name : null;
   const unready =
     direct && !catalog.some(t => t.name === direct) ? direct : null;
@@ -139,20 +161,32 @@ function chooseStart(ranked, pages, directMatch, catalog) {
   // match the ranker outweighed is named, and so are the loose page matches
   // search listed when the kit falls back to the shell.
   const loose = pages.map(p => `\`${p.name}\``).join(', ');
-  const pick = pickStart(ranked);
+  /**
+   * A part's or an edit's reason, naming a direct match that is not the start.
+   * @param {string} place
+   * @param {string} startName
+   */
+  const placed = (place, startName) =>
+    direct && direct !== startName
+      ? `Search matched \`${direct}\` by name, but ${place}`
+      : place[0].toUpperCase() + place.slice(1);
+  const pick = pickStart(ranked, kind);
   const closest = pick && catalog.find(t => t.name === pick.name);
-  if (closest) {
+  if (pick && closest) {
     const agrees = closest.name === direct;
+    const place = placement(kind, pick.base && pick.familyNamed);
     return {
       ...asTemplate(closest),
       basis: agrees ? 'direct' : 'closest',
-      reason: agrees
-        ? 'Matches the idea.'
-        : unready
-          ? `\`${unready}\` matches but is not ready yet; this is the closest ready template.`
-          : direct
-            ? `Search matched \`${direct}\` by name, but this template fits more of the idea.`
-            : 'The closest template; none is exactly this page.',
+      reason: unready
+        ? `\`${unready}\` matches but is not ready yet; this is the closest ready template.`
+        : place
+          ? placed(place, closest.name)
+          : agrees
+            ? 'Matches the idea.'
+            : direct
+              ? `Search matched \`${direct}\` by name, but this template fits more of the idea.`
+              : 'The closest template; none is exactly this page.',
     };
   }
   for (const id of FALLBACK_STARTS) {
@@ -161,18 +195,21 @@ function chooseStart(ranked, pages, directMatch, catalog) {
       // 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 place = placement(kind, false);
       return {
         ...asTemplate(shell),
         basis: 'fallback',
         reason: unready
           ? `\`${unready}\` matches but is not ready yet, so start from the app shell.`
-          : direct
-            ? `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
-                ? `Search matched ${loose} only loosely, so start from the app shell.`
-                : 'No template matched, so start from the app shell.',
+          : 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.`
+              : nearest
+                ? 'No template is a clear match; the app shell is the closest.'
+                : loose
+                  ? `Search matched ${loose} only loosely, so start from the app shell.`
+                  : 'No template matched, so start from the app shell.',
       };
     }
   }
@@ -188,12 +225,30 @@ function chooseStart(ranked, pages, directMatch, catalog) {
  */
 export async function buildKit(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 60} = options;
+  // A kit is built from Core's components, hooks, and templates. An open
+  // search without core covers the docs alone, so the kit asks for core here.
+  if (type !== 'doc' && !findCoreDir(cwd)) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
   // search()'s JSDoc @returns widens results to object[]; the SearchResponse
   // shape is the contract (api/search/search.type.mjs). Cast locally rather than
   // tightening the search @returns (a separate follow-up).
   const result =
     /** @type {import('../../search/search.type.mjs').SearchResponse} */ (
-      await search(query, {cwd, type, limit})
+      await search(query, {
+        cwd,
+        type,
+        // Search wider than the surfaced kit so a flood of doc matches cannot
+        // bury the page templates past the cutoff; the caller's `limit` still
+        // caps the kit below. A non-positive or non-integer limit is passed
+        // through unchanged so search rejects it (ERR_INVALID_ARGUMENT).
+        limit:
+          Number.isInteger(limit) && limit > 0 ? Math.max(limit, 200) : limit,
+      })
     );
   const results = result.data.results;
   // The TOTAL number of matches, not the number that survived `limit`. The kit
@@ -257,13 +312,41 @@ export async function buildKit(query, options = {}) {
         command: `${page.command} --skeleton`,
       }));
 
+  // The caller's `limit` caps the surfaced kit, even though the search above
+  // ran wider to find templates that a flood of doc matches would otherwise
+  // bury past the cutoff. Keep pages first, then blocks, then components.
+  let budget = limit;
+  /**
+   * @template T
+   * @param {T[]} arr
+   * @returns {T[]}
+   */
+  const toLimit = arr => {
+    const out = arr.slice(0, Math.max(0, budget));
+    budget -= out.length;
+    return out;
+  };
+  const pagesKept = toLimit(pages);
+  const blocksKept = toLimit(blocks);
+  const domainKept = toLimit(domain);
+
   // A kit narrowed to components or hooks has no page to start from; every
   // other kit does, so the reader is never left to compose a page from scratch.
   const wantsPages = !type || type === 'template';
   const catalog = wantsPages ? await loadPageTemplates(cwd) : [];
   const ranked = wantsPages ? rankPages(query, catalog) : [];
+  // A part of a page starts where it lives (spec:AST-048/FR3); the project's
+  // own components say what a part is. The search above already gathered them
+  // unless it was narrowed to templates.
+  const kind = wantsPages
+    ? ideaKind(
+        query,
+        catalog,
+        searchedComponents(result) ?? (await loadComponents(cwd)),
+      )
+    : 'page';
   const chosen = wantsPages
-    ? chooseStart(ranked, matchedPages, directMatch, catalog)
+    ? chooseStart(ranked, kind, matchedPages, directMatch, catalog)
     : 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
@@ -288,7 +371,7 @@ export async function buildKit(query, options = {}) {
   // not resolve — the same defect `getCliInvocation` exists to prevent, and
   // the renderer applies it. A JSON caller gets the parts, not a sentence.
   const hint =
-    pages.length + blocks.length + domain.length < THIN_KIT
+    pagesKept.length + blocksKept.length + domainKept.length < THIN_KIT
       ? {
           reason:
             'Few matches. This is keyword search, not semantic — try other wordings.',
@@ -306,9 +389,9 @@ export async function buildKit(query, options = {}) {
       matchCount,
       directMatch,
       start,
-      pages,
-      blocks,
-      domain,
+      pages: pagesKept,
+      blocks: blocksKept,
+      domain: domainKept,
       frame: FRAME,
       foundation: FOUNDATION,
       hint,

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

@@ -1,10 +1,6 @@
 // @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('../_adapter.mjs').PageTemplate} PageTemplate
- * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, containerMatched: boolean}} RankedPage
- */
 /**
  * Rank page templates against an idea, best first. Ties go to the template
  * with the shorter id (the family's broader page), then by name.
@@ -14,6 +10,17 @@
  * @returns {RankedPage[]}
  */
 export function rankPages(query: string, pages: PageTemplate[]): RankedPage[];
+/**
+ * What an idea asks for (spec:AST-048/FR3): a whole `page`; a `part` of one,
+ * when its head noun names one of the system's components and it lists fewer
+ * than PAGE_PIECES pieces; or an `edit` of a page the builder already has.
+ *
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @param {ComponentWords[]} components
+ * @returns {IdeaKind}
+ */
+export function ideaKind(query: string, pages: PageTemplate[], components: ComponentWords[]): IdeaKind;
 /**
  * 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
@@ -26,19 +33,28 @@ export function rankPages(query: string, pages: PageTemplate[]): RankedPage[];
  */
 export function pickAlternatives(ranked: RankedPage[], startName: string, count?: number): RankedPage[];
 /**
- * The template to start from, or null when the best one has too little
- * evidence to lead and the page should start from the app shell. Evidence is
- * two matched terms, the idea naming the template's family, or its container.
+ * The template to start from, or null for the kit's neutral app shell. A page
+ * needs evidence to lead: two matched terms, the idea naming the template's
+ * family, or its container. A part starts from the base template of the family
+ * the idea places it in, else from the app shell (spec:AST-048/FR3); an edit of
+ * a page the builder already has starts from the app shell (FR9). Either way,
+ * the app shell is the shell template the idea describes when one leads.
  *
  * @param {RankedPage[]} ranked
+ * @param {IdeaKind} [kind]
  * @returns {RankedPage | null}
  */
-export function pickStart(ranked: RankedPage[]): RankedPage | null;
+export function pickStart(ranked: RankedPage[], kind?: IdeaKind): RankedPage | null;
 export type PageTemplate = import("../_adapter.mjs").PageTemplate;
+export type ComponentWords = import("../_adapter.mjs").ComponentWords;
 export type RankedPage = {
     name: string;
     score: number;
     hits: number;
     familyNamed: boolean;
     containerMatched: boolean;
+    family: string;
+    base: boolean;
+    matched: Set<string>;
 };
+export type IdeaKind = "page" | "part" | "edit";