@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/api/json/envelope-types.test.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The published `@astryxdesign/cli/json` envelope types carry
+ * `apiVersion`, the field every `--json` envelope has. Type-checks a consumer
+ * fixture that reads it from each envelope shape.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+
+const INDEX = fileURLToPath(new URL('./index.ts', import.meta.url));
+const TSC = createRequire(import.meta.url).resolve('typescript/bin/tsc');
+
+const FIXTURE = `
+import type {
+  assertResponse,
+  CLIError,
+  CLIUnsupportedError,
+  parseResponse,
+} from ${JSON.stringify(INDEX)};
+
+declare const error: CLIError;
+declare const unsupported: CLIUnsupportedError;
+declare const parsed: Exclude<ReturnType<typeof parseResponse>, CLIError | CLIUnsupportedError>;
+declare const asserted: ReturnType<typeof assertResponse<'manifest'>>;
+
+export const versions: number[] = [
+  error.apiVersion,
+  unsupported.apiVersion,
+  parsed.apiVersion,
+  asserted.apiVersion,
+];
+`;
+
+describe('@astryxdesign/cli/json envelope types', () => {
+  it('declare apiVersion on the success and error envelopes', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-envelope-types-'));
+    try {
+      fs.writeFileSync(path.join(dir, 'fixture.ts'), FIXTURE);
+      fs.writeFileSync(
+        path.join(dir, 'tsconfig.json'),
+        JSON.stringify({
+          compilerOptions: {
+            target: 'ES2022',
+            module: 'ESNext',
+            moduleResolution: 'bundler',
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            allowImportingTsExtensions: true,
+            // index.ts re-exports JSDoc types from .type.mjs files; read them
+            // from source, as tsconfig.json-api.json does, not from generated
+            // declarations that exist only after a build.
+            allowJs: true,
+            types: [],
+          },
+          files: ['fixture.ts'],
+        }),
+      );
+      const res = spawnSync(process.execPath, [TSC, '-p', dir], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+      });
+      expect(res.stdout + res.stderr).toBe('');
+      expect(res.status).toBe(0);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+});

package/api/json/index.ts

@@ -28,6 +28,8 @@ export type * from '../init/init.type.mjs';
 export type * from '../doctor/doctor.type.mjs';
 export type * from '../layout/layout.type.mjs';
 export type * from '../integration/validate-integration.type.mjs';
+export type * from '../integration/authoring-checks.type.mjs';
+export type * from '../integration/pack-check.type.mjs';
 export type * from '../../foundation/response/base';
 export type * from '../../foundation/response/error-codes';
 export type * from '../../clients/cli/lib/manifest';

package/api/json/isError.doc.mjs

@@ -11,10 +11,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'isError',
+  namespace: 'cli/api',
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:
-    'Tests a parsed response for an `error` key. Branch on this before touching `data`: ' +
+    'Tests a parsed response for an `error` key. Branch on this before touching `data`, ' +
     'and prefer the stable `code` field over matching the human-readable message, which is ' +
     'not a contract. Note this returns a plain boolean, not a TypeScript type predicate, so ' +
     'it does not narrow on its own: cast to the matching *Response type to get typed access.',

package/api/json/parseResponse.doc.mjs

@@ -11,12 +11,13 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'parseResponse',
+  namespace: 'cli/api',
   displayName: 'parseResponse()',
   summary: 'Parse `astryx --json` stdout into the structural response envelope.',
   description:
     'The entry point for consuming the CLI as a subprocess. A JSON string is parsed; ' +
     'an already-parsed object is passed through unchanged, so it is safe to call on ' +
-    'either. It returns the structural { type, data, meta? } envelope without narrowing: ' +
+    'either. It returns the structural { apiVersion, type, data, meta? } envelope without narrowing: ' +
     '`data` stays unknown until you discriminate on `type` (or use assertResponse).',
   importPath: '@astryxdesign/cli/json',
   signature: 'parseResponse(raw: unknown): any',
@@ -34,7 +35,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
+        'The { apiVersion, type, data, meta? } envelope, or a CLIError envelope ({ apiVersion, error, code, suggestions? }). The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
     },
   ],
   throws: [

package/api/layout/_adapter.mjs

@@ -50,7 +50,18 @@ async function loadBlocks(cwd) {
   const blocks = [];
   try {
     const all = await discoverTemplates(cwd);
-    for (const t of all) if (t.type === 'block') blocks.push({...t, kind: 'template'});
+    const templates = all.filter(template => template.type === 'block');
+    /** @type {Map<string, import('../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate>} */
+    const byId = new Map();
+    // Exact ids are the fallback. Active replacement aliases override them in a
+    // second pass, matching template() regardless of discovery/display order.
+    for (const template of templates) byId.set(template.dirName, template);
+    for (const template of templates) {
+      if (template.replaces != null) byId.set(template.replaces, template);
+    }
+    for (const [id, template] of byId) {
+      blocks.push({...template, dirName: id, kind: 'template'});
+    }
   } catch {
     // discovery is best-effort
   }
@@ -91,7 +102,10 @@ export function formatIssue(issue) {
  * @param {string} expression
  * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
  */
-export async function analyze(expression, {form = 'auto', loose = false, cwd = process.cwd()} = {}) {
+export async function analyze(
+  expression,
+  {form = 'auto', loose = false, cwd = process.cwd()} = {},
+) {
   // Validate inputs in the API (not just the CLI): an empty expression or an
   // unknown --form must error, not silently parse as an empty/compact layout.
   if (typeof expression !== 'string' || expression.trim() === '') {
@@ -108,9 +122,10 @@ export async function analyze(expression, {form = 'auto', loose = false, cwd = p
       ERROR_CODES.ERR_INVALID_OPTION,
     );
   }
-  const registry = /** @type {import('../../foundation/xle/xle-ast').Registry} */ (
-    /** @type {unknown} */ (await buildRegistry({cwd}))
-  );
+  const registry =
+    /** @type {import('../../foundation/xle/xle-ast').Registry} */ (
+      /** @type {unknown} */ (await buildRegistry({cwd}))
+    );
   const blocks = await loadBlocks(cwd);
 
   /** @type {import('../../foundation/xle/xle-ast').XLEDoc} */

package/api/layout/expand/expand.mjs

@@ -120,18 +120,20 @@ export async function layoutExpand(expression, options = {}) {
 
   let written = null;
   if (targetPath) {
-    let resolved;
+    // The guard sees the file that will be written, not only its directory:
+    // a symlink at that name would otherwise carry the write outside the root.
+    const fileTarget = isFilePathArg(targetPath)
+      ? targetPath
+      : path.join(targetPath, `${componentName}.tsx`);
+    let filePath;
     try {
-      resolved = assertWithin(targetPath, cwd, {label: 'layout target path'});
+      filePath = assertWithin(fileTarget, cwd, {label: 'layout target path'});
     } catch (err) {
       if (err instanceof PathSafetyError) {
         throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
       }
       throw err;
     }
-    const filePath = isFilePathArg(targetPath)
-      ? resolved
-      : path.join(resolved, `${componentName}.tsx`);
     fs.mkdirSync(path.dirname(filePath), {recursive: true});
     fs.writeFileSync(filePath, result.code);
     written = path.relative(cwd, filePath);

package/api/layout/expand/expand.path-safety.test.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path-safety tests for the `layout.expand` write. The file written, not
+ * only the directory it lands in, must stay inside the project root.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {layoutExpand} from '../layout.mjs';
+import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+
+const SLOW = 30_000;
+
+// The registry imports every component doc on first use; warm it once.
+beforeAll(async () => {
+  await buildRegistry();
+}, 120_000);
+
+describe('layout.expand — write confinement', () => {
+  it('rejects a directory target whose generated file is a symlink leading outside cwd', async () => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'xle-confine-outside-'));
+    try {
+      const victim = path.join(outside, 'victim.tsx');
+      fs.writeFileSync(victim, 'OUTSIDE');
+      fs.mkdirSync(path.join(cwd, 'out'));
+      fs.symlinkSync(victim, path.join(cwd, 'out', 'GeneratedLayout.tsx'));
+
+      await expect(
+        layoutExpand('V > B', {targetPath: './out', cwd}),
+      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(victim, 'utf-8')).toBe('OUTSIDE');
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('still writes <Name>.tsx into a plain directory target', async () => {
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    try {
+      const result = await layoutExpand('V > B', {targetPath: './out', name: 'Demo', cwd});
+      expect(result.data.written).toBe(path.join('out', 'Demo.tsx'));
+      expect(fs.existsSync(path.join(cwd, 'out', 'Demo.tsx'))).toBe(true);
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  }, SLOW);
+});

package/api/layout/grammar/grammar.mjs

@@ -10,6 +10,7 @@
  */
 
 import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+import {MAX_REPEAT} from '../../../foundation/xle/expand.mjs';
 
 /**
  * `astryx layout grammar` — the agent cheatsheet, with the alias table
@@ -50,7 +51,7 @@ NODE ANATOMY   Name#id.enum"payload"[attrs]{hint}*N > children
   .enum        unique enum value of any prop:  Bd.success  Tx.lg  B.primary
   "payload"    primary text prop (label/title/heading) or text child:  TI"Email"  B"Save"
   {hint}       kebab-case template/component reference (see TEMPLATE REFERENCING) — NEVER text
-  *N / xN      repeat (use $ for the counter:  Tk"item-$"*3)
+  *N / xN      repeat, at most ${MAX_REPEAT} copies (use $ for the counter:  Tk"item-$"*3)
   trailing !   initial selection for scaffolded state:  Tab"Overview"!
 
 ATTRS [...] (outline: bare tokens after the name, no brackets)

package/api/layout/layoutCheck.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'layoutCheck',
+  namespace: 'cli/api',
   displayName: 'layoutCheck()',
   summary: 'Validate a layout expression without expanding it.',
   description:

package/api/layout/layoutExpand.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'layoutExpand',
+  namespace: 'cli/api',
   displayName: 'layoutExpand()',
   summary: 'Expand a validated layout expression into XDS TSX.',
   description:
@@ -36,7 +37,7 @@ export const doc = {
       name: 'options.targetPath',
       type: 'string',
       description:
-        'Write the generated TSX here (validated to stay within cwd). A directory gets <name>.tsx; a file path is used as-is. Omit to return the code without writing.',
+        'Write the generated TSX here (validated to stay within cwd). A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is used as-is; any other path is a directory that gets <name>.tsx. An existing file is replaced. Omit to return the code without writing.',
     },
     {
       name: 'options.form',

package/api/layout/layoutGrammar.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'layoutGrammar',
+  namespace: 'cli/api',
   displayName: 'layoutGrammar()',
   summary: 'Return the XLE/XLO grammar cheatsheet for this install.',
   description:

package/api/search/search-return-type.test.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The declared return type of `search()` is the canonical SearchResponse.
+ * Consumers of `@astryxdesign/cli/api` type-check against it; an `object` entry
+ * type erases every result field from their view.
+ */
+
+import {createRequire} from 'node:module';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+
+const require = createRequire(import.meta.url);
+const ts = require('typescript');
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SEARCH = path.join(HERE, 'search.mjs');
+const TYPES = path.join(HERE, 'search.type.mjs');
+
+describe('search() declared return type', () => {
+  it('types each result as the canonical SearchResultEntry', () => {
+    const program = ts.createProgram([SEARCH, TYPES], {
+      allowJs: true,
+      noEmit: true,
+      skipLibCheck: true,
+      types: [],
+      module: ts.ModuleKind.NodeNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      target: ts.ScriptTarget.ES2022,
+    });
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(SEARCH);
+    /** @param {string} file @param {string} name */
+    const exportOf = (file, name) =>
+      checker
+        .getExportsOfModule(checker.getSymbolAtLocation(program.getSourceFile(file)))
+        .find((/** @type {any} */ s) => s.name === name);
+    /** @param {any} type @param {string} name */
+    const prop = (type, name) =>
+      checker.getTypeOfSymbolAtLocation(type.getProperty(name), source);
+    /** @param {any} type */
+    const names = type => type.getProperties().map((/** @type {any} */ p) => p.name).sort();
+
+    const fn = checker.getTypeOfSymbolAtLocation(exportOf(SEARCH, 'search'), source);
+    const response = checker.getAwaitedType(fn.getCallSignatures()[0].getReturnType());
+    const data = prop(response, 'data');
+    expect(names(data)).toEqual(['matchCount', 'query', 'results']);
+    const entry = checker.getIndexTypeOfType(prop(data, 'results'), ts.IndexKind.Number);
+    const canonical = checker.getDeclaredTypeOfSymbol(exportOf(TYPES, 'SearchResultEntry'));
+    expect(names(canonical)).toContain('command');
+    expect(names(entry)).toEqual(names(canonical));
+  }, 30_000);
+});

package/api/search/search.d.mts

@@ -9,6 +9,13 @@
  * @returns {string}
  */
 export function stem(w: string): string;
+/**
+ * Whether two lowercase words are the same word, up to plural and stem form.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function sameWord(a: string, b: string): boolean;
 /**
  * Split a query into meaningful content tokens (lowercased, stopwords + very
  * short words removed). Empty for single-word queries (callers fall back to
@@ -17,6 +24,23 @@ export function stem(w: string): string;
  * @returns {string[]}
  */
 export function tokenizeQuery(term: string): string[];
+/**
+ * The first title or heading that holds every word of the query, in order and
+ * side by side, or null.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function headingWithPhrase(term: string, titles: string[] | undefined): string | null;
+/**
+ * The first title or heading of two words or more that the query holds whole,
+ * in order and side by side, or null. A question such as "how do I add dark
+ * mode" names the "Dark mode" section outright, around words no title has.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function titleInQuery(term: string, titles: string[] | undefined): string | null;
 /**
  * @param {string} term - Lowercased full query.
  * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
@@ -42,20 +66,26 @@ export function scoreQuery(term: string, tokens: string[], candidate: Candidate)
  * @param {string} term - Lowercased search term.
  * @param {object} candidate
  * @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
+ * @param {string} [candidate.domain] - A component, hook, or template name
+ *   also matches typed as words: `command palette` is CommandPalette.
  * @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).
  * @param {string[]} [candidate.weakKeywords] - Derived signal (components a page renders).
  * @param {string} [candidate.description]
  * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
  * @param {string[]} [candidate.guidance] - Usage guidance (features, best practices) — scored a tier below description.
+ * @param {{fuzzy?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
  * @returns {{score: number, reason: string} | null}
  */
-export function scoreCandidate(term: string, { name, keywords, weakKeywords, description, prose, guidance, }: {
+export function scoreCandidate(term: string, { name, domain, keywords, weakKeywords, description, prose, guidance, }: {
     name: string;
+    domain?: string | undefined;
     keywords?: string[] | undefined;
     weakKeywords?: string[] | undefined;
     description?: string | undefined;
     prose?: string[] | undefined;
     guidance?: string[] | undefined;
+}, { fuzzy }?: {
+    fuzzy?: boolean;
 }): {
     score: number;
     reason: string;
@@ -68,22 +98,38 @@ export function scoreCandidate(term: string, { name, keywords, weakKeywords, des
  * @param {string} [options.cwd]
  * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
  * @param {number} [options.limit] - Max results (default 20).
- * @returns {Promise<{type: 'search', data: {query: string, matchCount: number, results: Array<object>}}>}
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
 export function search(query: string, options?: {
     cwd?: string | undefined;
-    type?: "component" | "hook" | "doc" | "template" | undefined;
+    type?: "component" | "hook" | "template" | "doc" | undefined;
     limit?: number | undefined;
-}): Promise<{
-    type: "search";
-    data: {
-        query: string;
-        matchCount: number;
-        results: Array<object>;
-    };
-}>;
+}): Promise<import("./search.type.mjs").SearchResponse>;
+export namespace SYNONYMS {
+    let dashboard: string[];
+    let login: string[];
+    let signup: string[];
+    let payment: string[];
+    let pricing: string[];
+    let chat: string[];
+    let settings: string[];
+    let calendar: string[];
+    let table: string[];
+    let gallery: string[];
+    let hero: string[];
+    let form: string[];
+    let profile: string[];
+    let documentation: string[];
+    let navigation: string[];
+}
 /** Valid domain filters for `--type`. */
 export const SEARCH_DOMAINS: string[];
+/**
+ * Filler words stripped from multi-word queries so natural-language phrasing
+ * ("a page where you can see business stats") ranks on its content words.
+ * Exported for `build`, whose page ranker strips the same words.
+ */
+export const STOPWORDS: Set<string>;
 /**
  * A search candidate gathered from one content domain. Extra underscore-
  * prefixed fields carry domain-specific payload used only by {@link toResult}.
@@ -96,8 +142,39 @@ export type Candidate = {
     description?: string | undefined;
     prose?: string[] | undefined;
     guidance?: string[] | undefined;
+    /**
+     * - A doc's title and the headings inside it:
+     * the lines a reader scans to pick it. The whole query standing in one of
+     * them, or one of them standing whole in the query, is a top-tier match.
+     */
+    titles?: string[] | undefined;
     _import?: string | undefined;
     _title?: string | undefined;
+    /**
+     * - A doc result's topic or docs-tree route.
+     */
+    _topic?: string | undefined;
+    /**
+     * - A doc result's section key, when it is one section.
+     */
+    _section?: string | undefined;
+    /**
+     * - The command that reads exactly this doc part.
+     */
+    _command?: string | undefined;
+    /**
+     * - The command that opens the level above a doc
+     * part: its topic's section list, or the docs-tree namespace it sits in.
+     */
+    _parent?: string | undefined;
+    /**
+     * - The npm package that authored a docs-tree
+     * doc part. Flat topics carry none: an extension's sections can come from
+     * another package.
+     */
+    _package?: string | undefined;
     _displayName?: string | undefined;
-    _kind?: "block" | "page" | undefined;
+    _kind?: "page" | "block" | undefined;
+    _resultName?: string | undefined;
+    _commandName?: string | undefined;
 };

package/api/search/search.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'search',
+  namespace: 'cli/api',
   displayName: 'search()',
   summary:
     'Unified ranked search across components, hooks, docs, and templates.',
@@ -46,14 +47,15 @@ export const doc = {
     {
       name: 'options.cwd',
       type: 'string',
-      description: 'Directory to resolve @astryxdesign/core from.',
+      description:
+        "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it, and a search with no `type` covers the docs alone when core is missing.",
     },
   ],
   returns: [
     {
       type: 'search',
       description:
-        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
+        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, and `displayName` and `kind` for templates. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the Unorganized level for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from).',
     },
   ],
   throws: [
@@ -61,6 +63,10 @@ export const doc = {
       code: 'ERR_INVALID_ARGUMENT',
       when: 'the query is empty, --type is unknown, or --limit is not a positive integer',
     },
+    {
+      code: 'ERR_CORE_NOT_FOUND',
+      when: '@astryxdesign/core cannot be found from the cwd, and `type` names a domain that reads it: `component`, `hook`, or `template`',
+    },
   ],
   examples: [
     {label: 'Find a component', code: "const r = await search('button');"},