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

package/api/build/kit/signals.mjs

@@ -0,0 +1,284 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file What build weighs for one request, computed once: search's matches
+ * grouped into pages, blocks, and domain components; the page template to
+ * start from and its alternatives (start.mjs, rank.mjs); and search's whole
+ * block list with its scores, for the block picker. answer.mjs turns these and
+ * a block list into the build.kit response.
+ * @input A request and build's options; templates and components through the
+ *   adapter.
+ * @output {@link KitSignals}
+ * @position api/build/kit, beside kit.mjs and answer.mjs; the main searcher in
+ *   tree.mjs calls it.
+ */
+
+import {
+  searchCore as search,
+  searchedComponents,
+} from '../../search/search.mjs';
+import {coreDirOrThrow} from '../../error.mjs';
+import {getResultCoverage} from '../../search/coverage.mjs';
+import {CORE_PROVIDER_ID} from '../../../foundation/identity/providers.mjs';
+import {
+  loadComponents,
+  loadTemplates,
+  requireBuildCoreDir,
+  templateSetupNotes,
+} from '../_adapter.mjs';
+import {ideaKind} from './kind.mjs';
+import {pickAlternatives, rankPages} from './rank.mjs';
+import {asTemplate, chooseStart} from './start.mjs';
+
+/** A page at/above this score is a confident direct match. */
+const PAGE_DIRECT = 95;
+
+/** Below this a page is too weak to offer at all. */
+const PAGE_FLOOR = 50;
+
+/**
+ * Below this a block/domain-component match is incidental noise. A single
+ * description word in a multi-word idea scores 50 plus at most 7.5 of coverage
+ * garnish, so it stays below; a name or keyword hit clears it. `build "weekly
+ * brief"` used to offer Toast, Popover and TextInput because their
+ * descriptions say "brief".
+ */
+const DOMAIN_FLOOR = 60;
+
+/**
+ * How much of a multi-word query a page must cover to be offered on breadth.
+ *
+ * Score alone cannot carry this. A page's derived keywords include every
+ * component its source renders, so `build "actionable warning banner"` once
+ * scored `login`, `contact-form` and `documentation-design` at 95 apiece — an
+ * exact hit on "banner" alone, plus the coverage garnish. Matching one of
+ * three concepts is not the same claim as matching three.
+ */
+const PAGE_COVERAGE = 0.5;
+
+/**
+ * Always-surfaced primitives. Every page needs a shell + layout/typography/
+ * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
+ * so search alone never returns them. Kept here (not the renderer) because they
+ * are ALSO used to exclude these names from the idea-specific `domain` group.
+ * Every page template already uses them.
+ */
+export const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
+
+export const FOUNDATION = [
+  'VStack',
+  'HStack',
+  'Grid',
+  'StackItem',
+  'Card',
+  'Section',
+  'Text',
+  'Heading',
+  'Button',
+  'Icon',
+  'Badge',
+  'Divider',
+];
+
+const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+
+/**
+ * @typedef {import('../../search/search.type.mjs').SearchResultEntry} SearchResultEntry
+ * @typedef {import('../build.type.mjs').BuildStart} BuildStart
+ * @typedef {[name: string, score: number, matched: number | null, total: number | null]} BlockScore
+ */
+
+/**
+ * Everything build weighs for one request.
+ * @typedef {object} KitSignals
+ * @property {string} query search's echo of the query
+ * @property {number} matchCount
+ * @property {boolean} directMatch
+ * @property {BuildStart | null} start the start, its alternatives, and its notes
+ * @property {SearchResultEntry[]} pages
+ * @property {SearchResultEntry[]} blocks the blocks build names itself
+ * @property {SearchResultEntry[]} domain
+ * @property {string[]} kitBlocks the names of `blocks`
+ * @property {BlockScore[]} searched every block search returned, in its order
+ * @property {string[]} foreign the blocks, named, searched or scaffoldable, whose package is not Core's
+ */
+
+/**
+ * A block result's name, score, and how much of the query it matched.
+ * @param {SearchResultEntry} r
+ * @returns {BlockScore}
+ */
+function blockScore(r) {
+  const coverage = getResultCoverage(r);
+  return [r.name, r.score, coverage?.matched ?? null, coverage?.total ?? null];
+}
+
+/**
+ * Build's signals for one request (see {@link KitSignals}).
+ *
+ * @param {string} query what you're building (e.g. "analytics dashboard")
+ * @param {{cwd?: string, type?: import('../../search/search.type.mjs').SearchDomain, limit?: number}} [options]
+ * @returns {Promise<KitSignals>}
+ */
+export async function kitSignals(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') coreDirOrThrow(requireBuildCoreDir, cwd);
+  // 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,
+        // 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
+  // below is deliberately small (≤3 pages, ≤5 blocks, ≤6 components) and
+  // `results` is itself capped, so every other count here is a cap; this is the
+  // one field that says how much the query actually matched.
+  const matchCount = result.data.matchCount;
+
+  /**
+   * Did this result answer enough of the query to stand as a page on breadth?
+   * Single-concept queries have nothing to cover, so they always pass. Coverage
+   * stays in a module-private WeakMap and never enters public search/build JSON.
+   * @param {object} r
+   */
+  const covers = r => {
+    const coverage = getResultCoverage(r);
+    const total = coverage?.total ?? 1;
+    if (total <= 1) return true;
+    return (coverage?.matched ?? 0) / total >= PAGE_COVERAGE;
+  };
+
+  const matchedPages = results
+    .filter(
+      r =>
+        r.domain === 'template' &&
+        r.kind !== 'block' &&
+        r.score >= PAGE_FLOOR &&
+        covers(r),
+    )
+    .slice(0, 3);
+  const searchedBlocks = results.filter(
+    r => r.domain === 'template' && r.kind === 'block',
+  );
+  const blocks = searchedBlocks
+    .filter(r => r.score >= DOMAIN_FLOOR)
+    .slice(0, 5);
+  const domain = results
+    .filter(
+      r =>
+        (r.domain === 'component' || r.domain === 'hook') &&
+        r.score >= DOMAIN_FLOOR &&
+        !ALWAYS.has(r.name),
+    )
+    .slice(0, 6);
+  const directMatch =
+    matchedPages.length > 0 && matchedPages[0].score >= PAGE_DIRECT;
+
+  /**
+   * On a loose match, a page entry's `command` previews the layout rather
+   * than printing the whole template: `--skeleton` gives the shape without
+   * presenting the page as the thing to build. The recommendation itself is
+   * `start`, which always scaffolds. Copied rather than mutated: these entries
+   * come from `search()` and are not this function's to modify.
+   */
+  const pages = directMatch
+    ? matchedPages
+    : matchedPages.map(page => ({
+        ...page,
+        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 templates = wantsPages
+    ? await loadTemplates(cwd)
+    : {pages: [], blocks: []};
+  const catalog = templates.pages;
+  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, 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
+  // three far more often than it is the start alone.
+  /** @type {BuildStart | null} */
+  const start = chosen && {
+    ...chosen,
+    alternatives: pickAlternatives(ranked, chosen.name).flatMap(r => {
+      const t = catalog.find(c => c.name === r.name);
+      return t ? [asTemplate(t)] : [];
+    }),
+  };
+
+  // Analyze what the start template needs that the project lacks (external
+  // packages, StyleX compiler). Only the start — alternatives are suggestions,
+  // not commitments, so reporting their needs would be noise.
+  if (start) {
+    const startTemplate = catalog.find(t => t.name === start.name);
+    if (startTemplate) {
+      const notes = templateSetupNotes(startTemplate, cwd);
+      if (notes.length > 0) start.notes = notes;
+    }
+  }
+
+  return {
+    query: result.data.query,
+    matchCount,
+    directMatch,
+    start,
+    pages: pagesKept,
+    blocks: blocksKept,
+    domain: domainKept,
+    kitBlocks: blocksKept.map(r => r.name),
+    searched: searchedBlocks.map(blockScore),
+    foreign: [
+      ...new Set(
+        [...blocksKept, ...searchedBlocks, ...templates.blocks]
+          .filter(b => b.package !== CORE_PROVIDER_ID)
+          .map(b => b.name),
+      ),
+    ],
+  };
+}

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

@@ -0,0 +1,32 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * 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
+ * scaffold. Null only when the project has no page template to offer at all.
+ *
+ * `direct` means two independent signals agree: the ranker's pick is also
+ * search's direct match. The ranker sees only ready templates, so a template
+ * still marked not ready is never the start; when search matched one directly
+ * 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
+ * @param {string} idea
+ * @returns {Omit<BuildStart, 'alternatives'> | null}
+ */
+export function chooseStart(ranked: import("./rank.mjs").RankedPage[], kind: import("./rank.mjs").IdeaKind, pages: SearchResultEntry[], directMatch: boolean, catalog: PageTemplate[], idea: string): Omit<BuildStart, "alternatives"> | null;
+export function asTemplate(t: PageTemplate): {
+    name: string;
+    package: string;
+    displayName: string;
+    description: string;
+    command: string;
+};
+export type SearchResultEntry = import("../../search/search.type.mjs").SearchResultEntry;
+export type BuildStart = import("../build.type.mjs").BuildStart;
+export type PageTemplate = import("../_adapter.mjs").PageTemplate;

package/api/build/kit/start.mjs

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The page template a kit starts from: the page ranker's pick when it has
+ * the evidence to lead, the template a part lives in, else the app shell.
+ */
+
+import {loadWeights} from '../_adapter.mjs';
+import {asksForNewPage} from './kind.mjs';
+import {pickStart} from './rank.mjs';
+import {weighStart} from './weights.mjs';
+
+/**
+ * @typedef {import('../../search/search.type.mjs').SearchResultEntry} SearchResultEntry
+ * @typedef {import('../build.type.mjs').BuildStart} BuildStart
+ * @typedef {import('../_adapter.mjs').PageTemplate} PageTemplate
+ */
+
+/**
+ * Where a page starts when no page template matched: the first of these the
+ * project can scaffold. A top nav over empty, full-width content is the least
+ * opinionated frame that still has navigation; `blank` is the floor, with no
+ * chrome at all. Either one still hands the reader a page frame and its
+ * padding, which composing from components does not.
+ */
+const FALLBACK_STARTS = ['shell-top-nav', 'blank'];
+
+/**
+ * A page template as the kit names it: the command that selects exactly that
+ * template, scaffolding into `<path>`, a placeholder for the file or folder to
+ * write it to.
+ * @param {PageTemplate} t
+ */
+export const asTemplate = t => ({
+  name: t.name,
+  package: t.package,
+  displayName: t.displayName,
+  description: t.description,
+  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
+ * scaffold. Null only when the project has no page template to offer at all.
+ *
+ * `direct` means two independent signals agree: the ranker's pick is also
+ * search's direct match. The ranker sees only ready templates, so a template
+ * still marked not ready is never the start; when search matched one directly
+ * 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
+ * @param {string} idea
+ * @returns {Omit<BuildStart, 'alternatives'> | null}
+ */
+export 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;
+  // The reason never denies a match the same response reports: a direct
+  // 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(', ');
+  /**
+   * 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 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;
+    const place = placement(kind, pick.base && pick.familyNamed);
+    return {
+      ...asTemplate(closest),
+      basis: agrees ? 'direct' : 'closest',
+      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) {
+    const shell = catalog.find(t => t.name === id);
+    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) ||
+        (weighed === null && !!proposed && proposed.family !== 'Shell');
+      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.`
+          : place
+            ? placed(place, shell.name)
+            : direct
+              ? 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
+                  ? `Search matched ${loose} only loosely, so start from the app shell.`
+                  : 'No template matched, so start from the app shell.',
+      };
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,72 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Content terms of a text: lowercase alphanumeric words, stopwords removed,
+ * stemmed.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function terms(text: string): string[];
+/**
+ * The terms of an idea that only ever modify another word, each with the words
+ * it modifies: in each phrase the last content word is its head, and the ones
+ * before it describe the next.
+ * @param {string} query
+ * @returns {Map<string, Set<string>>}
+ */
+export function modifiersOf(query: string): Map<string, Set<string>>;
+/**
+ * Adjacent term pairs a text names, "a b", for telling a template that names
+ * a whole compound ("executive summary") from one that names only its parts.
+ * @param {string[]} texts
+ * @returns {Set<string>}
+ */
+export function pairsOf(texts: string[]): Set<string>;
+/**
+ * The terms of an idea that name its frame: "modal" in "in a modal". A card, a
+ * table or an existing page after "in a" is where a part goes, not a frame.
+ * @param {string} query
+ * @returns {Set<string>}
+ */
+export function containersOf(query: string): Set<string>;
+/**
+ * Family words, from the templates' own ids: a word in the ids of two or more
+ * templates of one family, plus the family's name when a template carries it.
+ * Each word maps to its family.
+ * @param {PageTemplate[]} pages
+ * @returns {Map<string, string>}
+ */
+export function familyWordsOf(pages: PageTemplate[]): Map<string, string>;
+/**
+ * Where an idea's head ends: its first clause, before the parts it lists.
+ */
+export const HEAD_END: RegExp;
+/**
+ * The family whose templates are app chrome rather than page content: the
+ * explicit `Shell -` category (architecture:template-authoring/INV7).
+ */
+export const SHELL_FAMILY: "Shell";
+/** A container phrase: "in a modal", "inside the side panel". */
+export const CONTAINER_PHRASE: RegExp;
+/**
+ * Where a phrase ends, for finding the word that heads it: punctuation and
+ * the words that join phrases.
+ */
+export const PHRASE_END: RegExp;
+export function normalized(text: string): string;
+/** Stemmed synonym lookup built from search's vocabulary, both directions. */
+export const SYNONYMS_OF: Map<string, Set<string>>;
+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";