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

package/api/build/kit/words.mjs

@@ -0,0 +1,202 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The words build's page ranker reads: a template's terms and families,
+ * an idea's modifiers, containers and phrase pairs, and search's synonyms.
+ *
+ * Family words come 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 — never from a list kept here or from synonyms, so an integration's
+ * templates join the vocabulary by being named like their family, and "a
+ * landing page" is not a hero because "landing" is a synonym of "hero".
+ */
+
+import {stem, STOPWORDS, SYNONYMS} from '../../search/search.mjs';
+
+/**
+ * Words search drops that name layout: "side navigation", "side by side".
+ */
+const LAYOUT_WORDS = new Set(['side']);
+
+/**
+ * Where an idea's head ends: its first clause, before the parts it lists.
+ */
+export const HEAD_END =
+  /:|,|;|\(|\s[-\u2013\u2014]\s|\b(?:with|showing|listing|for|that|where|plus|including|containing|featuring|which|to|from|of)\b/i;
+
+/**
+ * Frames a page can live in, above whatever is underneath. A container phrase
+ * counts only when it names one of these.
+ */
+const OVERLAY_FRAMES = new Set([
+  'modal',
+  'dialog',
+  'drawer',
+  'sheet',
+  'popup',
+  'overlay',
+]);
+
+/**
+ * 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 =
+  /\b(?:in|inside|within)\s+(?:a|an|the)\s+([a-z-]+)(?:\s+([a-z-]+))?/gi;
+
+/**
+ * Where a phrase ends, for finding the word that heads it: punctuation and
+ * the words that join phrases.
+ */
+export const PHRASE_END =
+  /[^a-z0-9\s-]+|\s(?:and|or|with|for|of|to|in|on|at|by|from|the|a|an|plus)\s/;
+
+/** @param {string} t */
+const isContentWord = t =>
+  t.length >= 2 && (LAYOUT_WORDS.has(t) || !STOPWORDS.has(t));
+
+/**
+ * Content terms of a text: lowercase alphanumeric words, stopwords removed,
+ * stemmed.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function terms(text) {
+  return (
+    String(text)
+      .toLowerCase()
+      .match(/[a-z0-9]+/g) ?? []
+  )
+    .filter(isContentWord)
+    .map(stem);
+}
+
+/**
+ * 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) {
+  const heads = new Set();
+  /** @type {Map<string, Set<string>>} */
+  const modifiers = new Map();
+  for (const phrase of String(query).toLowerCase().split(PHRASE_END)) {
+    const words = terms(phrase);
+    words.forEach((w, i) => {
+      if (i === words.length - 1) heads.add(w);
+      else modifiers.set(w, (modifiers.get(w) ?? new Set()).add(words[i + 1]));
+    });
+  }
+  for (const h of heads) modifiers.delete(h);
+  return modifiers;
+}
+
+/**
+ * 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) {
+  const pairs = new Set();
+  for (const text of texts) {
+    for (const phrase of String(text).toLowerCase().split(PHRASE_END)) {
+      const words = terms(phrase);
+      for (let i = 1; i < words.length; i++)
+        pairs.add(`${words[i - 1]} ${words[i]}`);
+    }
+  }
+  return pairs;
+}
+
+/**
+ * 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) {
+  const found = new Set();
+  for (const m of String(query).matchAll(CONTAINER_PHRASE)) {
+    for (const t of terms(`${m[1]} ${m[2] ?? ''}`)) {
+      if (OVERLAY_FRAMES.has(t)) found.add(t);
+    }
+  }
+  return found;
+}
+
+/** @param {string} text */
+export const normalized = text =>
+  (
+    String(text)
+      .toLowerCase()
+      .match(/[a-z0-9]+/g) ?? []
+  ).join(' ');
+
+/** Stemmed synonym lookup built from search's vocabulary, both directions. */
+export const SYNONYMS_OF = (() => {
+  /** @type {Map<string, Set<string>>} */
+  const index = new Map();
+  /** @param {string} a @param {string} b */
+  const add = (a, b) => {
+    const set = index.get(a) ?? new Set();
+    set.add(b);
+    index.set(a, set);
+  };
+  for (const [key, values] of Object.entries(SYNONYMS)) {
+    const k = stem(key);
+    for (const value of values) {
+      const v = stem(value);
+      add(k, v);
+      add(v, k);
+      for (const other of values) if (other !== value) add(v, stem(other));
+    }
+  }
+  return index;
+})();
+
+/**
+ * @typedef {import('../_adapter.mjs').PageTemplate} PageTemplate
+ * @typedef {import('../_adapter.mjs').ComponentWords} ComponentWords
+ * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, containerMatched: boolean, family: string, base: boolean, matched: Set<string>}} RankedPage
+ * @typedef {'page' | 'part' | 'edit'} IdeaKind
+ */
+
+/** @param {PageTemplate} page */
+const familyOf = page => (page.category.split(' - ')[0] ?? '').trim();
+
+/**
+ * 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) {
+  /** @type {Map<string, Map<string, number>>} */
+  const idWords = new Map();
+  for (const page of pages) {
+    const family = familyOf(page);
+    const counts = idWords.get(family) ?? new Map();
+    for (const w of new Set(page.name.split('-'))) {
+      if (w.length >= 3) counts.set(stem(w), (counts.get(stem(w)) ?? 0) + 1);
+    }
+    idWords.set(family, counts);
+  }
+  /** @type {Map<string, string>} */
+  const familyOfWord = new Map();
+  for (const [family, counts] of idWords) {
+    const heads = [...counts].filter(([, c]) => c >= 2).map(([w]) => w);
+    const name = normalized(family).split(' ').pop() ?? '';
+    if (name.length >= 3 && counts.has(stem(name))) heads.push(stem(name));
+    for (const head of heads) {
+      if (!familyOfWord.has(head)) familyOfWord.set(head, family);
+    }
+  }
+  return familyOfWord;
+}

package/api/build/tree.d.mts

@@ -0,0 +1,20 @@
+// @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 BUILD_TREE: import("../../foundation/route/route.mjs").Tree<BuildRequest, BuildContext, import("./build.type.mjs").BuildKitResponse>;
+export type BuildRequest = {
+    query: string;
+    options: NonNullable<Parameters<typeof kitSignals>[1]>;
+};
+export type BuildContext = {
+    /**
+     * the root's weights
+     */
+    weights: import("../../foundation/route/route.mjs").ClassifierWeights;
+    /**
+     * the block picker's weights; null: build names its own blocks
+     */
+    blocks: import("./blocks/blocks.mjs").BlockPickerWeights | null;
+};
+export type BuildAnswer = import("./build.type.mjs").BuildKitResponse;
+import { kitSignals } from './kit/signals.mjs';

package/api/build/tree.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file How build answers: a root classifier sends each request to the
+ * searcher that should answer it. Its weights (tree.weights.json) have one
+ * class today, so every request goes to the main searcher: the kit's signals
+ * (kit/signals.mjs), the block picker's blocks (blocks/blocks.mjs), and the
+ * kit around them (kit/answer.mjs).
+ * @input {query, options} and the data build's adapter gathered: the root's
+ *   weights and the block picker's
+ * @output the build.kit response
+ * @position api/build; build.mjs runs it with the shared route helper
+ */
+
+import {routeKit} from '../../foundation/route/route.mjs';
+import {kitAnswer} from './kit/answer.mjs';
+import {kitSignals} from './kit/signals.mjs';
+import {pickBlocks} from './blocks/blocks.mjs';
+
+/**
+ * @typedef {{query: string, options: NonNullable<Parameters<typeof kitSignals>[1]>}} BuildRequest
+ * @typedef {object} BuildContext
+ * @property {import('../../foundation/route/route.mjs').ClassifierWeights} weights the root's weights
+ * @property {import('./blocks/blocks.mjs').BlockPickerWeights | null} blocks the block picker's weights; null: build names its own blocks
+ * @typedef {import('./build.type.mjs').BuildKitResponse} BuildAnswer
+ */
+
+/** @type {import('../../foundation/route/route.mjs').RouteKit<BuildRequest, BuildContext, BuildAnswer>} */
+const {defineSearcher, defineClassifier, defineTree} = routeKit;
+
+const main = defineSearcher({
+  id: 'main',
+  summary:
+    'Ranks page templates, blocks, and components by the words of the request, starts from the best page template, and lists its blocks in the order the block picker ranks them.',
+  run: async (request, ctx) => {
+    const signals = await kitSignals(request.query, request.options);
+    if (!ctx.blocks) return kitAnswer(signals);
+    const picked = pickBlocks(request.query, signals, ctx.blocks);
+    return kitAnswer(signals, picked.names, picked.entries);
+  },
+});
+
+const root = defineClassifier({
+  id: 'root',
+  summary: 'Classifies the request and hands it to the searcher for its class.',
+  searchers: {},
+  fallback: 'main',
+  floor: 1,
+  features: () => ['#bias'],
+  weights: ctx => ctx.weights,
+});
+
+export const BUILD_TREE = defineTree('root', [root, main]);

package/api/build/tree.test.mjs

@@ -0,0 +1,185 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build's tree end to end, offline: the network and subprocesses throw,
+ * and build still answers. The block picker changes only the kit's blocks:
+ * the start, its alternatives, and every other field stay build's own, the
+ * block count is build's own, and the blocks it names are pinned per phrase.
+ */
+
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {afterAll, beforeAll, describe, expect, it, vi} from 'vitest';
+
+// vi.mock calls are hoisted above the imports; the stub maker is hoisted with them.
+const {blocked} = vi.hoisted(() => ({
+  /** @param {string} name */
+  blocked: name => async (/** @type {() => Promise<any>} */ load) => {
+    const real = await load();
+    /** @type {Record<string, unknown>} */
+    const stub = {};
+    for (const [key, value] of Object.entries(real)) {
+      stub[key] =
+        typeof value === 'function'
+          ? () => {
+              throw new Error(`build reached ${name}.${key}`);
+            }
+          : value;
+    }
+    return {...stub, default: stub};
+  },
+}));
+vi.mock('node:http', blocked('http'));
+vi.mock('node:https', blocked('https'));
+vi.mock('node:net', blocked('net'));
+vi.mock('node:dns', blocked('dns'));
+vi.mock('node:child_process', blocked('child_process'));
+vi.mock('http', blocked('http'));
+vi.mock('https', blocked('https'));
+vi.mock('net', blocked('net'));
+vi.mock('dns', blocked('dns'));
+vi.mock('child_process', blocked('child_process'));
+
+const {build} = await import('./build.mjs');
+const {buildKit} = await import('./kit/kit.mjs');
+const {loadBlockPicker, withListingCache} = await import('./_adapter.mjs');
+
+const REPO = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+
+/**
+ * Hand-written phrases and the blocks the picker names for each. The rest of
+ * the answer carries search results, which change whenever the docs do, so it
+ * is compared with build's own kit rather than pinned.
+ * @type {[string, string[]][]}
+ */
+const PINNED = [
+  [
+    'analytics dashboard with a KPI row and a sortable table',
+    [
+      'TableSortableTable',
+      'TableGridDividersTable',
+      'TableShowcase',
+      'TableGroupedRowsTable',
+      'TableStripedTable',
+    ],
+  ],
+  [
+    'settings page with notification toggles and a save bar',
+    [
+      'SwitchShowcase',
+      'SwitchSettingsPanel',
+      'ToggleButtonShowcase',
+      'ToggleButtonStates',
+      'SwitchWithDescription',
+    ],
+  ],
+  [
+    'empty state for a question bank with an import button',
+    [
+      'EmptyStateContainer',
+      'EmptyStateShowcase',
+      'EmptyStateCompact',
+      'EmptyStateActions',
+      'CommandPaletteEmptyShowcase',
+    ],
+  ],
+  [
+    'login form with single sign-on buttons',
+    [
+      'ButtonWithIcon',
+      'CardWithInnerLayout',
+      'ButtonVariants',
+      'FormLayoutShowcase',
+      'FormLayoutMixedControls',
+    ],
+  ],
+  [
+    'calendar for booking appointments',
+    [
+      'CalendarSingle',
+      'CalendarShowcase',
+      'CalendarConstraints',
+      'CalendarRangeWithValue',
+      'CalendarTwoMonths',
+    ],
+  ],
+  [
+    'kanban board for sprint tasks with a filter bar',
+    ['ToolbarTableFilter', 'PowerSearchShowcase'],
+  ],
+];
+
+/** @type {typeof globalThis.fetch} */
+let realFetch;
+beforeAll(() => {
+  realFetch = globalThis.fetch;
+  globalThis.fetch = () => {
+    throw new Error('build reached fetch');
+  };
+});
+afterAll(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('build tree', () => {
+  it('keeps a block the request names by its exact name in build’s slot', async () => {
+    const phrase = 'calendar for booking appointments with CalendarTwoMonths';
+    const answer = await build(phrase, {cwd: REPO});
+    const own = await withListingCache(() => buildKit(phrase, {cwd: REPO}));
+    if (answer?.type !== 'build.kit' || own.type !== 'build.kit')
+      throw new Error('expected a kit');
+    const k = own.data.blocks.findIndex(b => b.name === 'CalendarTwoMonths');
+    expect(k).toBeGreaterThanOrEqual(0);
+    expect(answer.data.blocks[k].name).toBe('CalendarTwoMonths');
+  });
+
+  it('runs with the network and subprocesses blocked', async () => {
+    const cp = await import('node:child_process');
+    const https = await import('node:https');
+    expect(() => cp.execFileSync('true')).toThrow(/build reached/);
+    expect(() => https.request('https://example.com')).toThrow(/build reached/);
+    expect(() => globalThis.fetch('https://example.com')).toThrow(
+      /build reached/,
+    );
+  });
+
+  it('loads the block picker weights as plain numbers', () => {
+    expect(loadBlockPicker()).not.toBeNull();
+  });
+
+  for (const [phrase, blocks] of PINNED) {
+    it(`answers "${phrase}" offline with the picker's blocks`, async () => {
+      const answer = await build(phrase, {cwd: REPO});
+      const own = await withListingCache(() => buildKit(phrase, {cwd: REPO}));
+      if (answer?.type !== 'build.kit' || own.type !== 'build.kit')
+        throw new Error('expected a kit');
+      // Only the blocks move: the start, its alternatives, and every other
+      // field are build's own.
+      expect({...answer.data, blocks: null}).toEqual({
+        ...own.data,
+        blocks: null,
+      });
+      expect(answer.data.start?.alternatives).toEqual(
+        own.data.start?.alternatives,
+      );
+      // Every block is build's own entry, one search returned, or the picker's
+      // own, each with its real score and reason; never more blocks than
+      // build's own.
+      expect(answer.data.blocks.length).toBe(own.data.blocks.length);
+      for (const b of answer.data.blocks) {
+        expect(b.score).toBeGreaterThan(0);
+        expect(typeof b.reason).toBe('string');
+        const mine = own.data.blocks.find(o => o.name === b.name);
+        if (mine) expect(mine).toEqual(b);
+      }
+      expect(answer.data.blocks.map(b => b.name)).toEqual(blocks);
+      // Never longer than build's own answer for the same request.
+      expect(Buffer.byteLength(JSON.stringify(answer))).toBeLessThanOrEqual(
+        Buffer.byteLength(JSON.stringify(own)),
+      );
+    });
+  }
+});

package/api/build/tree.weights.json

@@ -0,0 +1 @@
+{"classes": ["main"], "tokens": {"#bias": [0]}}

package/api/component/_adapter.mjs

@@ -44,6 +44,10 @@ import {Project} from '../../foundation/config/project.mjs';
 import {loadComponentDoc as loadValidatedComponentDoc} from '../../foundation/discovery/component-loader.mjs';
 import {resolveComponentReplacements} from '../../foundation/discovery/component-replacement.mjs';
 import {searchComponents} from '../../foundation/text/string-utils.mjs';
+import {
+  rankComponentSuggestions,
+  synonymMatches,
+} from '../../foundation/text/suggest-order.mjs';
 import {AstryxError, coreDirOrThrow} from '../error.mjs';
 import {
   componentLinkProvider,
@@ -51,6 +55,28 @@ import {
   loadDocsCatalog,
 } from '../docs/_adapter.mjs';
 
+/** @type {Record<string, {synonyms?: string[]}> | undefined} */
+let cards;
+/**
+ * Search's component cards (each component's other names), read once.
+ * @returns {Record<string, {synonyms?: string[]}>}
+ */
+function searchCards() {
+  if (!cards) {
+    try {
+      cards = JSON.parse(
+        fs.readFileSync(
+          new URL('../search/_cards.json', import.meta.url),
+          'utf8',
+        ),
+      );
+    } catch {
+      cards = {};
+    }
+  }
+  return /** @type {Record<string, {synonyms?: string[]}>} */ (cards);
+}
+
 export {CORE_PACKAGE, unscopedComponentOwners};
 
 /**
@@ -463,12 +489,20 @@ export async function resolveUnscopedDoc(dirName, {coreDir, cwd, name}) {
         resolvedOwnerPackage = CORE_PACKAGE;
         resolvedSourcePath = findComponentSource(coreDir, resolvedName);
       } else {
+        // How many to suggest: the near-top results, at most five and at
+        // least two. Which ones, and in what order, is the suggestion
+        // ranking's call.
         const threshold = Math.max(topScore - 20, 1);
-        const candidates = results
-          .filter(r => r.score >= threshold)
-          .slice(0, 5);
-        if (candidates.length < 2)
-          candidates.push(...results.slice(candidates.length, 2));
+        const count = Math.max(
+          results.filter(r => r.score >= threshold).slice(0, 5).length,
+          Math.min(2, results.length),
+        );
+        const candidates = rankComponentSuggestions(
+          dirName,
+          results,
+          Object.values(components).flat(),
+          synonymMatches(dirName, searchCards()),
+        ).slice(0, count);
         throw new AstryxError(
           `No component named "${name}"`,
           candidates.map(c => ({name: c.name, reason: c.reason})),

package/api/component/component-replacement.test.mjs

@@ -64,6 +64,7 @@ function writeIntegration(name, components, peers) {
         type: 'component',
         name: componentName,
         displayName: componentName,
+        import: `${name}/components/${componentName}`,
         ...(replaces ? {replaces} : {}),
         keywords: ['acme'],
         usage: {description: `${componentName} for Acme apps.`},

package/api/component/component.mjs

@@ -293,7 +293,7 @@ async function componentRead(name, options = {}) {
   const selectorList = Array.isArray(name) ? name : null;
   const noName = selectorList == null && !name;
 
-  // Default detail level mirrors the CLI (see commands/component/index.mjs):
+  // Default detail level mirrors the CLI (see commands/component.mjs):
   // single-component views default to 'full', list-style views (--list,
   // --category, or no name) default to 'brief' (scannable name lists).
   // An explicit array remains a batch even when it is empty or a caller also
@@ -461,8 +461,22 @@ async function componentRead(name, options = {}) {
         return componentDetailBlocks(dirName, cwd, owner.package);
       }
       const loaded = await loadComponentDoc(owner.docPath, docOpts);
-      // A family member an integration lists under its own name reads as that
-      // member, the way a Core sub-component does below.
+      // A family member reads as that member, scoped the way the unscoped
+      // lookup scopes it: an integration member by its own entry, a Core
+      // sub-component (HStack in the Stack doc) by scopeSubComponent.
+      const sub =
+        scoped.kind === 'core'
+          ? scopeSubComponent(loaded, dirName, coreDir)
+          : null;
+      if (sub) {
+        if (props) {
+          return componentDetailProps(
+            {props: sub.matchingComponent.props},
+            owner.package,
+          );
+        }
+        return componentDetail(sub.scoped, owner, dirName, coreDir);
+      }
       const docs =
         scoped.kind === 'integration'
           ? scopeIntegrationMember(loaded, owner, dirName)

package/api/component/component.test.mjs

@@ -135,6 +135,21 @@ describe('component list — components whose docs live in a family folder', ()
     });
   }, SLOW);
 
+  it('answers a Core-scoped lookup of a member with that member, as the unscoped lookup does', async () => {
+    for (const name of ['HStack', 'VStack']) {
+      const unscoped = await component(name, {cwd});
+      const scoped = await component(name, {
+        cwd,
+        package: '@astryxdesign/core',
+      });
+      expect(scoped.data.name).toBe(name);
+      expect(scoped.data.parentDoc).toBe('Stack');
+      expect(scoped.data.import).toBe(`@astryxdesign/core/${name}`);
+      expect(scoped.data.props).toEqual(unscoped.data.props);
+      expect(scoped.data.props.length).toBeGreaterThan(0);
+    }
+  }, SLOW);
+
   it('prints each one\'s own import path in the list, the detail, and search', async () => {
     // The path `component <Name>` prints is the one docs and examples teach:
     // the component's own entry point, never its family's (/Stack, /Text) or

package/api/component/doc-links.test.mjs

@@ -250,14 +250,14 @@ describe("a link in a guide's description, as the docs tree shows it", () => {
         'Document a theme by extending the core theme topic, so an app reads it in `astryx docs theme`.';
       const guide = /** @type {any} */ (
         await docs(
-          'cli/integrations/building-blocks/themes/document-the-theme',
+          'authoring/building-blocks/themes/document-the-theme',
           undefined,
           {cwd: tmpDir, full: true},
         )
       );
       expect(guide.data.description).toBe(expected);
       const namespace = /** @type {any} */ (
-        await docs('cli/integrations/building-blocks/themes', undefined, {
+        await docs('authoring/building-blocks/themes', undefined, {
           cwd: tmpDir,
         })
       );

package/api/discover/_adapter.d.mts

@@ -43,12 +43,11 @@ export function hasSources(project: Project | undefined): boolean;
  * @param {Project | undefined} project
  * @param {Array<{name: string}>} installed
  * @param {Set<string>} declared
- * @param {(name: string, version?: string) => string} add
  * @returns {Promise<import('./discover.type.mjs').DiscoverAvailableEntry[]>}
  */
 export function computerAvailableEntries(project: Project | undefined, installed: Array<{
     name: string;
-}>, declared: Set<string>, add: (name: string, version?: string) => string): Promise<import("./discover.type.mjs").DiscoverAvailableEntry[]>;
+}>, declared: Set<string>): Promise<import("./discover.type.mjs").DiscoverAvailableEntry[]>;
 /**
  * Package names the project's package.json declares in any dependency field.
  * @param {Project | undefined} project