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

package/api/build/build.mjs

@@ -4,20 +4,27 @@
  * @file build API — dispatcher + barrel for the "assemble a page" assistant.
  *
  * `build()` with no query signals the workflow playbook (`build.help`). With a
- * query it runs the unified search and groups the results into a composition
- * KIT (`build.kit`). Each shape is projected by its own leaf; this file only
+ * query it runs build's tree (tree.mjs), whose searchers answer with a
+ * composition KIT (`build.kit`). Each shape is projected by its own leaf; this file only
  * routes to the leaves and re-exports them, keeping the SAME `build` export so
  * api/index.mjs and the CLI consumer stay unchanged.
  *
  *   no query  → build.help  (api/build/help/help.mjs)
- *   a query   → build.kit   (api/build/kit/kit.mjs)
+ *   a query   → build.kit   (api/build/tree.mjs: kit/signals.mjs, the block
+ *               picker in blocks/blocks.mjs, then kit/answer.mjs)
  */
 
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {buildHelp} from './help/help.mjs';
 import {buildKit} from './kit/kit.mjs';
-import {withListingCache} from './_adapter.mjs';
+import {
+  loadBlockPicker,
+  loadTreeWeights,
+  withListingCache,
+} from './_adapter.mjs';
+import {runTree} from '../../foundation/route/route.mjs';
+import {BUILD_TREE} from './tree.mjs';
 
 // Barrel: surface the leaves alongside the dispatcher for the fractal shape.
 export {buildHelp, buildKit};
@@ -34,7 +41,10 @@ export async function build(query, options = {}) {
   if (!query || !String(query).trim()) {
     return buildHelp();
   }
-  if (options.limit != null && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+  if (
+    options.limit != null &&
+    (!Number.isInteger(options.limit) || options.limit <= 0)
+  ) {
     throw new AstryxError(
       `Invalid limit "${options.limit}". Must be a positive integer.`,
       undefined,
@@ -43,5 +53,14 @@ export async function build(query, options = {}) {
   }
   // The kit resolves every candidate's source and docs by walking the same
   // tree; read each directory once for this call.
-  return withListingCache(() => buildKit(query, options));
+  return withListingCache(
+    async () =>
+      /** @type {import('./build.type.mjs').BuildKitResponse} */ (
+        await runTree(
+          BUILD_TREE,
+          {query, options},
+          {weights: loadTreeWeights(), blocks: loadBlockPicker()},
+        )
+      ),
+  );
 }

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

@@ -0,0 +1,14 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The kit for a request. `blocks` re-orders the blocks build names itself:
+ * each keeps build's own entry (its score and reason), and a name build did
+ * not give is dropped, so the kit never lists more blocks than build's own.
+ * Blocks of the same name from two packages are both kept.
+ *
+ * @param {import('./signals.mjs').KitSignals} signals
+ * @param {string[]} [blocks] block names; build's own when omitted
+ * @returns {import('../build.type.mjs').BuildKitResponse}
+ */
+export function kitAnswer(signals: import("./signals.mjs").KitSignals, blocks?: string[]): import("../build.type.mjs").BuildKitResponse;

package/api/build/kit/answer.mjs

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The build.kit response, from a request's signals (signals.mjs) and the
+ * blocks to name. With build's own blocks it is the kit build has always
+ * given; another list changes only the blocks, never their count.
+ * @input {@link import('./signals.mjs').KitSignals} and block names
+ * @output the build.kit response
+ * @position api/build/kit, beside signals.mjs; the main searcher in tree.mjs
+ *   calls it with the block picker's list.
+ */
+
+import {FOUNDATION, FRAME} from './signals.mjs';
+
+/**
+ * Fewer offerable results than this and the kit says how to look further.
+ *
+ * Three is the point below which a kit stops being a starting point. An agent
+ * that reads a near-empty kit does not conclude "my wording was wrong" — it
+ * concludes the package has nothing and falls back on its own memory of what
+ * Astryx contains, which is exactly the failure `build` exists to prevent.
+ */
+const THIN_KIT = 3;
+
+/**
+ * The kit for a request. `blocks` re-orders the blocks build names itself:
+ * each keeps build's own entry (its score and reason), and a name build did
+ * not give is dropped, so the kit never lists more blocks than build's own.
+ * Blocks of the same name from two packages are both kept.
+ *
+ * @param {import('./signals.mjs').KitSignals} signals
+ * @param {string[]} [blocks] block names; build's own when omitted
+ * @returns {import('../build.type.mjs').BuildKitResponse}
+ */
+export function kitAnswer(signals, blocks = signals.kitBlocks) {
+  // Entries by name, in build's order: two packages can ship a block with the
+  // same name, and each name in `blocks` takes the next entry of that name, so
+  // both stay listed.
+  /** @type {Map<string, import('../build.type.mjs').BuildKitResponse['data']['blocks']>} */
+  const own = new Map();
+  for (const b of signals.blocks)
+    own.set(b.name, [...(own.get(b.name) ?? []), b]);
+  const named = blocks.flatMap(name => {
+    const entry = own.get(name)?.shift();
+    return entry ? [entry] : [];
+  });
+
+  // What to try when the kit comes back thin. Keyword search over a design
+  // system misses in a predictable way — the reader's words and the package's
+  // often do not overlap — so name the two commands that browse rather than
+  // search, and say plainly that this is not semantic matching.
+  //
+  // STRUCTURED, not prose: `commands` are bare subcommands, because the API
+  // cannot know how the caller invokes the CLI. Baking `astryx component
+  // --list` into the text hands a pnpm-workspace reader a command that does
+  // 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 =
+    signals.pages.length + named.length + signals.domain.length < THIN_KIT
+      ? {
+          reason:
+            'Few matches. This is keyword search, not semantic — try other wordings.',
+          commands: ['component --list', 'template --list'],
+        }
+      : undefined;
+
+  return {
+    type: 'build.kit',
+    data: {
+      query: signals.query,
+      // Distinguishes "search found nothing" from a weak-but-non-empty result
+      // set. Either way the kit still names a template to start from.
+      hasResults: signals.matchCount > 0,
+      matchCount: signals.matchCount,
+      directMatch: signals.directMatch,
+      start: signals.start,
+      pages: signals.pages,
+      blocks: named,
+      domain: signals.domain,
+      frame: FRAME,
+      foundation: FOUNDATION,
+      hint,
+    },
+  };
+}

package/api/build/kit/answer.test.mjs

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {kitAnswer} from './answer.mjs';
+
+/** @param {any[]} blocks */
+const signals = blocks =>
+  /** @type {any} */ ({
+    query: 'q',
+    matchCount: blocks.length,
+    directMatch: false,
+    start: null,
+    pages: [],
+    blocks,
+    kitBlocks: blocks.map(b => b.name),
+    domain: [],
+  });
+
+describe('kitAnswer', () => {
+  const a = {name: 'Hero', package: '@a/one', score: 90, reason: 'name'};
+  const b = {name: 'Hero', package: '@b/two', score: 80, reason: 'name'};
+  const c = {name: 'Footer', package: '@a/one', score: 70, reason: 'keyword'};
+
+  it('keeps blocks of the same name from two packages', () => {
+    const kit = kitAnswer(signals([a, b, c]));
+    expect(kit.data.blocks).toEqual([a, b, c]);
+  });
+
+  it('keeps both when the picker re-orders them', () => {
+    const kit = kitAnswer(signals([a, b, c]), ['Footer', 'Hero', 'Hero']);
+    expect(kit.data.blocks).toEqual([c, a, b]);
+  });
+
+  it('never lists a block build did not give, or more than it gave', () => {
+    const kit = kitAnswer(signals([a, c]), ['Hero', 'Hero', 'Nav', 'Footer']);
+    expect(kit.data.blocks).toEqual([a, c]);
+  });
+});

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

@@ -0,0 +1,25 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * 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;
+/**
+ * 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;
+export type PageTemplate = import("./words.mjs").PageTemplate;
+export type ComponentWords = import("./words.mjs").ComponentWords;
+export type IdeaKind = import("./words.mjs").IdeaKind;

package/api/build/kit/kind.mjs

@@ -0,0 +1,170 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Whether a build idea asks for a page, a part of a page, or a change to
+ * a page the builder already has.
+ *
+ * Parts (spec:AST-048/FR3). "A date range picker" asks for a part of a page,
+ * not a page, and the system's own components say what a part is: an idea
+ * whose head noun is a word of a component's name or keywords, Core's or an
+ * integration's, asks for that part, unless the noun is a family word ("a data
+ * table") or the idea lists a page's worth of pieces. Words search drops as
+ * stopwords ("page", "screen", "app", "view") name no component, so "a calendar
+ * page" asks for a page and "a calendar" for a part. A part starts from the
+ * base template of the family the idea names ("an empty state for a settings
+ * page"), else from the app shell. An idea that changes a page or part the
+ * builder already has starts from the app shell too: that page is the
+ * builder's to keep (FR9), and no template scaffolds it. "Existing" marks one
+ * when its phrase names a page family or a component ("add a column to the
+ * existing table"), unless the idea asks for a new page ("a new dashboard like
+ * the existing dashboard", "clone the existing dashboard as a new page"). A
+ * bare "existing" phrase that names a page ("existing reports dashboard with a
+ * date filter") reads as the builder's own page.
+ */
+
+import {stem} from '../../search/search.mjs';
+import {
+  HEAD_END,
+  CONTAINER_PHRASE,
+  PHRASE_END,
+  terms,
+  containersOf,
+  familyWordsOf,
+} from './words.mjs';
+
+/**
+ * @typedef {import('./words.mjs').PageTemplate} PageTemplate
+ * @typedef {import('./words.mjs').ComponentWords} ComponentWords
+ * @typedef {import('./words.mjs').IdeaKind} IdeaKind
+ */
+
+/**
+ * How many listed pieces make an idea a page: a part is one thing with a detail
+ * or two ("a status pill with a tooltip"), while three pieces, two commas
+ * apart, describe a page.
+ */
+const PAGE_PIECES = 3;
+
+/**
+ * The word that marks a page or part the builder already has, when its phrase
+ * names one (see `changesExistingPage`).
+ */
+const EXISTING = /\bexisting\b/i;
+
+/**
+ * The word that marks an idea asking for a new page ("a new dashboard", "as a
+ * new page"), which is never a change to one the builder has.
+ */
+const NEW = /\bnew\b/;
+
+/**
+ * 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, pages, components) {
+  const text = String(query);
+  const familyWords = familyWordsOf(pages);
+  if (changesExistingPage(text, familyWords, components)) return 'edit';
+  // The head's last word, page words included: "calendar" is the noun of "a
+  // calendar", "page" the noun of "a calendar page". An overlay frame names
+  // where the thing lives, not the thing: "drafts" is the noun of "drafts in
+  // a modal".
+  const head = (text.split(HEAD_END)[0] ?? '').replace(CONTAINER_PHRASE, m =>
+    containersOf(m).size > 0 ? ' ' : m,
+  );
+  const words = (head.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter(
+    w => w.length >= 2,
+  );
+  const noun = stem(words[words.length - 1] ?? '');
+  if (familyWords.has(noun)) return 'page';
+  const pieces = (text.match(/,/g) ?? []).length + 1;
+  if (pieces >= PAGE_PIECES) return 'page';
+  return components.some(c => componentTerms(c).includes(noun))
+    ? 'part'
+    : 'page';
+}
+
+/**
+ * Whether an idea changes a page or part the builder already has: "existing"
+ * in the same phrase as a word that names a family of page templates or one of
+ * the system's components ("the existing incidents table", "the existing
+ * banner"). A new page "inspired by the existing one", or "existing users" on a
+ * new page, names neither, and an idea that asks for a new page is no change
+ * whatever it names.
+ * @param {string} text
+ * @param {Map<string, string>} familyWords
+ * @param {ComponentWords[]} components
+ * @returns {boolean}
+ */
+function changesExistingPage(text, familyWords, components) {
+  const componentWords = new Set(components.flatMap(nameTerms));
+  const phrases = text.toLowerCase().split(PHRASE_END);
+  if (asksNewPage(phrases, familyWords)) return false;
+  return phrases.some(phrase => {
+    const at = phrase.search(EXISTING);
+    return (
+      at >= 0 &&
+      terms(phrase.slice(at)).some(
+        t => familyWords.has(t) || componentWords.has(t),
+      )
+    );
+  });
+}
+
+/**
+ * Whether an idea asks for a new page: "new" before a word that names a family
+ * of page templates ("a new dashboard"), or before only words search drops,
+ * such as "page" ("as a new page"). "A new column" asks for a part.
+ * @param {string[]} phrases
+ * @param {Map<string, string>} familyWords
+ * @returns {boolean}
+ */
+function asksNewPage(phrases, familyWords) {
+  return phrases.some(phrase => {
+    const at = phrase.search(NEW);
+    if (at < 0) return false;
+    const after = terms(phrase.slice(at + 'new'.length));
+    return after.length === 0 || familyWords.has(after[0]);
+  });
+}
+
+/**
+ * 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
+ * @returns {string[]}
+ */
+function nameTerms(component) {
+  return terms(component.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2'));
+}
+
+/**
+ * The terms a component answers to: the words of its name and of its keywords.
+ * @param {ComponentWords} component
+ * @returns {string[]}
+ */
+function componentTerms(component) {
+  return [
+    ...nameTerms(component),
+    ...component.keywords.flatMap(keyword => terms(keyword)),
+  ];
+}

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

@@ -2,7 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * The page template to start from, and the kit around it.
+ * The page template to start from, and the kit around it, with the blocks
+ * build names itself.
  *
  * @param {string} query what you're building (e.g. "analytics dashboard")
  * @param {{cwd?: string, type?: import('../../search/search.type.mjs').SearchDomain, limit?: number}} [options]
@@ -13,6 +14,3 @@ export function buildKit(query: string, options?: {
     type?: import("../../search/search.type.mjs").SearchDomain;
     limit?: number;
 }): Promise<import("../build.type.mjs").BuildKitResponse>;
-export type SearchResultEntry = import("../../search/search.type.mjs").SearchResultEntry;
-export type BuildStart = import("../build.type.mjs").BuildStart;
-export type PageTemplate = import("../_adapter.mjs").PageTemplate;