@astryxdesign/cli 0.1.0 → 0.1.1-canary.080d887

package/src/api/layout.test.mjs

@@ -0,0 +1,238 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration tests for the layout API against the real @astryxdesign/core
+ * registry and real template blocks. Every expansion is additionally
+ * checked for TSX syntactic validity with the TypeScript parser, so the
+ * "expansion emits compilable JSX" contract is enforced, not assumed.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import {mkdtempSync, writeFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import ts from 'typescript';
+import {layoutExpand, layoutCheck, layoutGrammar} from './layout.mjs';
+import {buildRegistry} from '../lib/xle/registry.mjs';
+
+// The registry imports ~140 .doc.mjs modules on first use; under full-suite
+// parallel load that can exceed the default 5s test timeout. Warm it once.
+beforeAll(async () => {
+  await buildRegistry();
+}, 120_000);
+
+const SLOW = 30_000;
+
+/** Assert TSX parses cleanly; returns the source file for inspection. */
+function expectValidTsx(code) {
+  const sourceFile = ts.createSourceFile('generated.tsx', code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const diagnostics = sourceFile.parseDiagnostics || [];
+  const messages = diagnostics.map(d => ts.flattenDiagnosticMessageText(d.messageText, ' '));
+  expect(messages).toEqual([]);
+  return sourceFile;
+}
+
+const LOGIN_COMPACT =
+  'Ctr[h="100dvh"] > C[w=400 p8] > V[g6] > ' +
+  '(V[g1] > Tx"Welcome back" + Tx[t=supporting]"Sign in to your account") + ' +
+  '(F > TI"Email"[t=email req] + TI"Password"[t=password req]) + ' +
+  '(H[j=between a=center] > CB"Remember me" + Lk[href="/forgot"]"Forgot password?") + ' +
+  'B.primary"Sign in"';
+
+const CHAT_OUTLINE = `
+AppShell
+  topNav: TN
+  Layout > LC !scroll
+    ChL
+      composer:
+        ChC
+      ChML
+        ChS "Today"
+        repeat 2:
+          ChM
+            ChB "Reply $"
+    Tbar "Actions"
+      B "Delete" opens=#confirm
+
+overlays:
+  AD#confirm "Delete item?"
+`;
+
+const DASHBOARD_COMPACT =
+  'A[@topNav=TN @sideNav=SN] > L > V[g6] > ' +
+  '(G[c4 g4] > C{card-callout}*4) + ' +
+  '(C[p0] > T[striped] > (TR > THC"Name" + THC"Amount") + (TR > TC"Order $" + TC"\\$12.00")*3)';
+
+describe('layoutExpand', () => {
+  it('expands the login card with typed state scaffolds', async () => {
+    const result = await layoutExpand(LOGIN_COMPACT);
+    expect(result.type).toBe('layout.expand');
+    const {code} = result.data;
+    expectValidTsx(code);
+
+    expect(code).toContain(`const [email, setEmail] = useState('');`);
+    expect(code).toContain(`const [rememberMe, setRememberMe] = useState(false);`);
+    expect(code).toContain('<XDSCenter height="100dvh">');
+    expect(code).toContain('variant="primary"');
+    // axis-neutral j/a resolved onto the HStack's real props
+    expect(code).toContain('hAlign="between"');
+    expect(code).toContain('vAlign="center"');
+    // payload routed to label props, not duplicated as children
+    expect(code).not.toMatch(/label="Forgot password\?"[\s\S]{0,80}Forgot password\?/);
+  }, SLOW);
+
+  it('expands the outline chat page: slots, repeat blocks, overlays, triggers', async () => {
+    const result = await layoutExpand(CHAT_OUTLINE);
+    const {code, form} = result.data;
+    expect(form).toBe('outline');
+    expectValidTsx(code);
+
+    expect(code).toContain('composer={');
+    // slot satisfied required prop — no double assignment, no TODO for it
+    expect(code.match(/composer=/g)).toHaveLength(1);
+    expect(code).toContain('TODO(xle): open #confirm');
+    expect(code).toContain('overlays — wire open state');
+    expect((code.match(/<XDSChatMessage\b/g) || [])).toHaveLength(2);
+  }, SLOW);
+
+  it('expands the dashboard: table partition, repeats with $ counter and \\$ escape', async () => {
+    const result = await layoutExpand(DASHBOARD_COMPACT);
+    const {code} = result.data;
+    expectValidTsx(code);
+
+    expect(code).toContain('<XDSTableHeader>');
+    expect(code).toContain('<XDSTableBody>');
+    expect(code).toContain('Order 1');
+    expect(code).toContain('Order 3');
+    expect(code).toContain('$12.00');
+    expect(code).not.toContain('112.00');
+    // {card-callout} now splices: the block is co-defined once and referenced
+    // four times — no TODO marker.
+    expect((code.match(/^function CardCallout\(\)/gm) || [])).toHaveLength(1);
+    expect((code.match(/<CardCallout \/>/g) || [])).toHaveLength(4);
+    expect(code).not.toContain("TODO(xle): content block 'CardCallout'");
+  }, SLOW);
+
+  it('compact and outline surfaces expand to identical TSX', async () => {
+    const check = await layoutCheck(LOGIN_COMPACT);
+    const fromCompact = await layoutExpand(LOGIN_COMPACT);
+    const fromOutline = await layoutExpand(check.data.outline, {form: 'outline'});
+    expect(fromOutline.data.code).toEqual(fromCompact.data.code);
+  }, SLOW);
+
+  it('expansion is deterministic', async () => {
+    const a = await layoutExpand(DASHBOARD_COMPACT);
+    const b = await layoutExpand(DASHBOARD_COMPACT);
+    expect(a.data.code).toEqual(b.data.code);
+  }, SLOW);
+
+  it('throws structured errors with suggestions on invalid expressions', async () => {
+    await expect(layoutExpand('A[p6] > Grdi')).rejects.toMatchObject({
+      code: 'ERR_LAYOUT_INVALID',
+      message: expect.stringMatching(/AppShell has no prop 'padding'/),
+    });
+  });
+
+  it('rejects non-PascalCase --name', async () => {
+    await expect(layoutExpand('V > C', {name: 'not pascal'})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+  });
+
+  it('surfaces parse errors with positions', async () => {
+    await expect(layoutExpand('V > > C')).rejects.toMatchObject({
+      code: 'ERR_LAYOUT_PARSE',
+      message: expect.stringMatching(/line 1/),
+    });
+  });
+});
+
+describe('layoutCheck', () => {
+  it('returns both canonical surfaces for valid input', async () => {
+    const result = await layoutCheck('V[g6] > C{card-callout}*2');
+    expect(result.data.valid).toBe(true);
+    expect(result.data.compact).toContain('{card-callout}');
+    expect(result.data.outline).toContain('C {card-callout} x2');
+  });
+
+  it('collects all errors instead of stopping at the first', async () => {
+    const result = await layoutCheck('A[p6] > V[g7] > Bd.sucess"x" + C{not-a-block}');
+    expect(result.data.valid).toBe(false);
+    expect(result.data.errors.length).toBeGreaterThanOrEqual(4);
+    const all = result.data.errors.map(e => e.message).join('\n');
+    expect(all).toMatch(/no prop 'padding'/);
+    expect(all).toMatch(/must be one of/);
+    expect(all).toMatch(/Unknown block/);
+  });
+});
+
+describe('template referencing', () => {
+  it('splices a template block: co-defined once, referenced, imports merged', async () => {
+    const result = await layoutExpand('S[p6] > C{card-callout}*3', {name: 'Demo'});
+    const {code} = result.data;
+    expectValidTsx(code);
+    // co-defined exactly once, referenced three times, no TODO
+    expect((code.match(/^function CardCallout\(\)/gm) || [])).toHaveLength(1);
+    expect((code.match(/<CardCallout \/>/g) || [])).toHaveLength(3);
+    expect(code).not.toContain('TODO(xle)');
+    // the block's own import is hoisted, and shared specifiers dedupe
+    expect((code.match(/from '@astryxdesign\/core\/Card'/g) || [])).toHaveLength(1);
+    // the block lost its export — it's a local declaration now
+    expect(code).not.toContain('export default function CardCallout');
+    expect(result.data.blocksReferenced).toEqual([{name: 'CardCallout', mode: 'splice'}]);
+  }, SLOW);
+
+  it('merges a stateful block useState into a single react import', async () => {
+    const result = await layoutExpand(
+      'V > TI"Search"[t=text] + {table-column-settings-table}',
+      {name: 'Demo'},
+    );
+    const {code} = result.data;
+    expectValidTsx(code);
+    // page TextInput scaffolds useState; block also uses useState → one import
+    expect((code.match(/^import \{useState\} from 'react';$/gm) || [])).toHaveLength(1);
+    expect(code).toContain('function TableColumnSettingsTable()');
+  }, SLOW);
+
+  it('imports app-registered local components (the local-component bridge)', async () => {
+    // Inside the workspace so @astryxdesign/core resolves; cleaned up after.
+    const cwd = mkdtempSync(join(process.cwd(), '.xle-imp-test-'));
+    try {
+      writeFileSync(
+        join(cwd, 'astryx.config.mjs'),
+        `export default {layout: {components: {KpiCard: '@/components/KpiCard', TimeRangePicker: {from: '@/components/TimeRangePicker'}}}};\n`,
+      );
+      const result = await layoutExpand('S[p6] > (G[c4 g4] > {kpi-card}*4) + {time-range-picker}', {
+        name: 'Demo',
+        cwd,
+      });
+      const {code} = result.data;
+      expectValidTsx(code);
+      expect(code).toContain("import {KpiCard} from '@/components/KpiCard';");
+      expect(code).toContain("import {TimeRangePicker} from '@/components/TimeRangePicker';");
+      expect((code.match(/<KpiCard \/>/g) || [])).toHaveLength(4);
+      expect(code).toContain('<TimeRangePicker />');
+      expect(result.data.blocksReferenced).toContainEqual({name: 'KpiCard', mode: 'import'});
+    } finally {
+      rmSync(cwd, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('parses a standalone {block} in both surfaces', async () => {
+    const check = await layoutCheck('G[c4 g4] > {card-callout}*2');
+    expect(check.data.valid).toBe(true);
+    expect(check.data.compact).toContain('{card-callout}*2');
+    expect(check.data.outline).toMatch(/\{card-callout\} x2/);
+  });
+});
+
+describe('layoutGrammar', () => {
+  it('emits the cheatsheet with branch-generated aliases', async () => {
+    const result = await layoutGrammar();
+    expect(result.data.text).toContain('TWO SURFACES');
+    expect(result.data.aliases.V).toBe('VStack');
+    expect(result.data.aliases.TB).toBe('TableBody');
+    // every alias target must exist — the table is registry-filtered
+    expect(Object.values(result.data.aliases)).not.toContain(undefined);
+  });
+});

package/src/api/search.mjs

@@ -41,14 +41,184 @@ import {
 } from '../lib/component-discovery.mjs';
 import {discoverHooks, findHookDoc} from '../lib/hook-discovery.mjs';
 import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {discoverTemplates} from './template.mjs';
+import {discoverTemplates, extractComponents} from './template.mjs';
 import {AstryxError} from './error.mjs';
 
 const DOCS_DIR = path.join(CLI_ROOT, 'docs');
 
+/**
+ * Synonym / intent map: product-language terms an agent is likely to type,
+ * expanded to the catalog's vocabulary so oblique queries still rank. Keys and
+ * values are matched bidirectionally (typing any value also pulls in the key
+ * and its siblings). Lowercase, single words or short phrases.
+ */
+const SYNONYMS = {
+  dashboard: ['overview', 'analytics', 'kpi', 'kpis', 'metrics', 'stats', 'reporting', 'insights', 'control'],
+  login: ['signin', 'auth', 'authentication', 'sso', 'credentials', 'account'],
+  signup: ['register', 'registration', 'onboarding'],
+  payment: ['checkout', 'billing', 'card', 'pay', 'purchase', 'order'],
+  pricing: ['plans', 'plan', 'tiers', 'tier', 'subscription', 'subscriptions'],
+  chat: ['messaging', 'message', 'messages', 'conversation', 'inbox', 'dm'],
+  settings: ['preferences', 'config', 'configuration', 'account'],
+  calendar: ['schedule', 'scheduling', 'events', 'event', 'month', 'agenda'],
+  table: ['list', 'rows', 'records', 'grid', 'spreadsheet', 'datatable'],
+  gallery: ['photos', 'photo', 'images', 'image', 'pictures'],
+  hero: ['banner', 'splash', 'headline', 'landing'],
+  form: ['fields', 'input', 'inputs', 'survey'],
+  profile: ['bio', 'avatar', 'user'],
+  documentation: ['docs', 'reference', 'guide', 'api'],
+  navigation: ['nav', 'menu', 'sidebar'],
+};
+
+// Flatten into a token -> Set(expansions) lookup (bidirectional).
+const SYNONYM_INDEX = (() => {
+  const idx = new Map();
+  const add = (a, b) => {
+    if (!idx.has(a)) idx.set(a, new Set());
+    idx.get(a).add(b);
+  };
+  for (const [key, vals] of Object.entries(SYNONYMS)) {
+    for (const v of vals) {
+      add(key, v);
+      add(v, key);
+      for (const v2 of vals) if (v2 !== v) add(v, v2);
+    }
+  }
+  return idx;
+})();
+
+/**
+ * Light stemmer: strips common English suffixes so "charts"/"charting" and
+ * "chart" share a root. Deliberately crude (no Porter) — good enough to bridge
+ * plural/gerund gaps without a dependency.
+ * @param {string} w
+ * @returns {string}
+ */
+export function stem(w) {
+  let s = w;
+  for (const suf of ['ing', 'ed', 'ies', 'es', 's']) {
+    if (s.length > suf.length + 2 && s.endsWith(suf)) {
+      s = suf === 'ies' ? s.slice(0, -3) + 'y' : s.slice(0, -suf.length);
+      break;
+    }
+  }
+  return s;
+}
+
+
 /** Valid domain filters for `--type`. */
 export const SEARCH_DOMAINS = ['component', 'hook', 'doc', 'template'];
 
+/**
+ * Filler words stripped from multi-word queries so natural-language phrasing
+ * ("a page where you can see business stats") ranks on its content words.
+ */
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'of', 'for', 'to', 'with', 'and', 'or', 'in', 'on', 'at',
+  'by', 'that', 'this', 'my', 'your', 'our', 'their', 'is', 'are', 'be', 'it',
+  'its', 'as', 'from', 'page', 'screen', 'app', 'application', 'view', 'where',
+  'you', 'can', 'some', 'like', 'just', 'basically', 'kinda', 'want', 'wants',
+  'need', 'needs', 'something', 'thing', 'things', 'build', 'make', 'create',
+  'i', 'me', 'we', 'us', 'so', 'up', 'out', 'over', 'side', 'one', 'big',
+]);
+
+/**
+ * Split a query into meaningful content tokens (lowercased, stopwords + very
+ * short words removed). Empty for single-word queries (callers fall back to
+ * whole-phrase scoring).
+ * @param {string} term - Already-lowercased query.
+ * @returns {string[]}
+ */
+export function tokenizeQuery(term) {
+  return term
+    .split(/\s+/)
+    // Strip only leading/trailing punctuation; keep joined identifiers intact
+    // (e.g. "foo_bar" stays one token) so gibberish stays gibberish.
+    .map(t => t.replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, ''))
+    .filter(t => t.length >= 2 && !STOPWORDS.has(t));
+}
+
+/**
+ * Score a candidate against a query, handling multi-word natural language.
+ * Tries the whole phrase (so exact/near matches still win) AND a per-token
+ * pass (so "data table with filters" matches `table-page` via table+filter),
+ * and returns whichever is stronger.
+ *
+ * @param {string} term - Lowercased full query.
+ * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
+ * @param {object} candidate
+ * @returns {{score: number, reason: string} | null}
+ */
+/**
+ * Minimum per-token score (in the multi-word pass) to count as a real match.
+ * 50 = a genuine name/keyword/description hit; below that is loose Levenshtein
+ * fuzz that would otherwise turn gibberish queries into noise.
+ */
+const MIN_TOKEN_SCORE = 50;
+
+/**
+ * Best score for a token against a candidate, fanning out through synonyms
+ * (synonym hits are discounted so a direct hit always wins).
+ * @returns {{score: number, reason: string} | null}
+ */
+function bestForToken(tok, candidate) {
+  let best = scoreCandidate(tok, candidate);
+  const syns = SYNONYM_INDEX.get(tok);
+  if (syns) {
+    for (const s of syns) {
+      const h = scoreCandidate(s, candidate);
+      if (h) {
+        const score = Math.round(h.score * 0.85);
+        if (!best || score > best.score) best = {score, reason: `${h.reason} (~${tok})`};
+      }
+    }
+  }
+  return best;
+}
+
+export function scoreQuery(term, tokens, candidate) {
+  const full = scoreCandidate(term, candidate);
+
+  // 0–1 content tokens: keep whole-phrase fuzzy matching (typo tolerance for
+  // single words), but if stopwords left exactly one DIFFERENT token (e.g.
+  // "pricing page" → "pricing"), score that token too and take the stronger.
+  if (tokens.length <= 1) {
+    const single = tokens.length === 1 ? bestForToken(tokens[0], candidate) : null;
+    if (full && (!single || full.score >= single.score)) return full;
+    return single;
+  }
+
+  // Multi-word natural language: score each content token, counting only
+  // strong hits, then reward coverage so candidates matching more terms win.
+  let sum = 0;
+  let matched = 0;
+  const hitTerms = [];
+  for (const tok of tokens) {
+    const h = bestForToken(tok, candidate);
+    if (h && h.score >= MIN_TOKEN_SCORE) {
+      sum += h.score;
+      matched++;
+      hitTerms.push(tok);
+    }
+  }
+  if (matched === 0) return full;
+
+  // Reward the AVERAGE strength of the concepts that matched (not divided by
+  // total query length — that penalizes verbose / low-fidelity prompts), plus
+  // a bonus per additional matched concept and a coverage term. A candidate
+  // that matches several of the query's concepts beats one matching a single
+  // incidental word.
+  const avgMatched = sum / matched;
+  const coverage = matched / tokens.length;
+  const tokenScore = Math.round(avgMatched + Math.min(matched - 1, 3) * 12 + coverage * 15);
+
+  if (full && full.score >= tokenScore) return full;
+  return {
+    score: tokenScore,
+    reason: `matches ${matched}/${tokens.length} terms: ${hitTerms.join(', ')}`,
+  };
+}
+
 /**
  * Score a single candidate against the search term across name, keywords,
  * and prose signals. Returns the best (highest) score plus a human reason,
@@ -107,10 +277,13 @@ export function scoreCandidate(term, {name, keywords = [], description = '', pro
     else if (dist === 2) consider(30, `keyword "${kw}" (distance ${dist})`);
   }
 
-  // ── Prose / description signals (whole-word boundary) ───────────
+  // ── Prose / description signals (stem-tolerant whole word) ──────
+  // Match the term's stem as a whole word, tolerating plural/gerund suffixes
+  // so "chart" matches "charts" and "filter" matches "filtering".
   if (term.length >= 3) {
-    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const re = new RegExp(`\\b${escaped}\\b`);
+    const root = stem(term);
+    const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`\\b${escaped}(s|es|ing|ed|ies)?\\b`);
     if (description && re.test(description.toLowerCase())) {
       consider(50, `description mentions "${term}"`);
     } else {
@@ -240,14 +413,30 @@ async function gatherTemplates(cwd) {
   } catch {
     return [];
   }
-  return templates.map(t => ({
-    domain: 'template',
-    name: t.dirName,
-    keywords: Array.isArray(t.componentsUsed) ? t.componentsUsed : [],
-    description: t.description || '',
-    _displayName: t.name,
-    _kind: t.type, // 'page' | 'block'
-  }));
+  return templates.map(t => {
+    // Blocks ship componentsUsed; page templates don't, so derive them from the
+    // source. Category words (e.g. "Dashboard - Analytics") are strong intent
+    // signal for pages, which otherwise only index on name + description.
+    let keywords = Array.isArray(t.componentsUsed) ? [...t.componentsUsed] : [];
+    if (t.type === 'page') {
+      if (t.filePath) {
+        try {
+          keywords = keywords.concat(extractComponents(t.filePath));
+        } catch {
+          // Best-effort: skip keyword enrichment if the source can't be read.
+        }
+      }
+      if (t.category) keywords = keywords.concat(t.category.split(/[^A-Za-z0-9]+/).filter(Boolean));
+    }
+    return {
+      domain: 'template',
+      name: t.dirName,
+      keywords,
+      description: t.description || '',
+      _displayName: t.name,
+      _kind: t.type, // 'page' | 'block'
+    };
+  });
 }
 
 /**
@@ -325,6 +514,7 @@ export async function search(query, options = {}) {
   }
 
   const term = String(query).trim().toLowerCase();
+  const tokens = tokenizeQuery(term);
 
   const coreDir = findCoreDir(cwd);
   if (!coreDir) {
@@ -342,9 +532,13 @@ export async function search(query, options = {}) {
 
   const all = [...components, ...hooks, ...docTopics, ...templates];
 
+  // Score every candidate on its own merits. The consumer groups results by
+  // role (page / block / component) and takes the top of each, so there's no
+  // cross-role competition to engineer — a target page only needs to be the
+  // strongest PAGE, not outrank every component.
   const scored = [];
   for (const candidate of all) {
-    const hit = scoreCandidate(term, candidate);
+    const hit = scoreQuery(term, tokens, candidate);
     if (hit) scored.push(toResult(candidate, hit.score, hit.reason));
   }