@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

package/api/layout/layout.test.mjs

@@ -0,0 +1,297 @@
+// 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 '../../foundation/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/),
+    });
+  });
+
+  it('maps pathologically deep nesting to a coded parse error, not ERR_UNKNOWN', async () => {
+    await expect(layoutCheck('V > '.repeat(2000) + 'C')).rejects.toMatchObject({
+      code: 'ERR_LAYOUT_PARSE',
+    });
+  });
+
+  it('wraps top-level repeats and groups in a fragment (valid JSX)', async () => {
+    for (const expr of ['B"Sign in"*3', '(B"a" + B"b")', '(B"a" + B"b")*2']) {
+      const {data} = await layoutExpand(expr);
+      expectValidTsx(data.code);
+      expect(data.code).toContain('<>');
+    }
+  }, SLOW);
+
+  it('wraps a top-level outline repeat block in a fragment', async () => {
+    const {data} = await layoutExpand('repeat 3:\n  B "x"', {form: 'outline'});
+    expectValidTsx(data.code);
+  }, SLOW);
+
+  it('emits JSX-safe TSX for text payloads containing < and >', async () => {
+    const result = await layoutExpand('Text"5 < 3 and 3 > 1"');
+    expectValidTsx(result.data.code);
+  }, SLOW);
+
+  it('emits JSX-safe TSX for text payloads containing { and }', async () => {
+    const result = await layoutExpand('Text"cost is {price}"');
+    expectValidTsx(result.data.code);
+  }, SLOW);
+
+  it('emits JSX-safe TSX when a text payload looks like a closing tag', async () => {
+    const result = await layoutExpand('Text"end</Text><img/>"');
+    expectValidTsx(result.data.code);
+  }, SLOW);
+
+  it('emits JSX-safe TSX for JSX-special chars in outline form', async () => {
+    const result = await layoutExpand('VStack\n  Text "a < b"', {form: 'outline'});
+    expectValidTsx(result.data.code);
+  }, SLOW);
+});
+
+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.
+    // A package.json beside the config makes Project.load resolve it as the
+    // sibling-of-nearest-package.json (the standard config resolution).
+    const cwd = mkdtempSync(join(process.cwd(), '.xle-imp-test-'));
+    try {
+      writeFileSync(join(cwd, 'package.json'), '{"name": "xle-imp-fixture"}\n');
+      writeFileSync(
+        join(cwd, 'astryx.config.mjs'),
+        `export default {experimental: {xle: {components: {KpiCard: {from: '@/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);
+  });
+});
+
+
+describe('layout — input validation (API matches CLI)', () => {
+  it('rejects an invalid --form value instead of silently parsing as compact', async () => {
+    await expect(layoutCheck('V > C', {form: /** @type {any} */ ('xml')})).rejects.toMatchObject({
+      code: 'ERR_INVALID_OPTION',
+    });
+    await expect(layoutExpand('V > C', {form: /** @type {any} */ ('nonsense')})).rejects.toMatchObject({
+      code: 'ERR_INVALID_OPTION',
+    });
+  });
+
+  it('rejects an empty expression at the API layer', async () => {
+    await expect(layoutCheck('')).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+    await expect(layoutExpand('   ')).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+  });
+});

package/api/layout/layout.type.d.mts

@@ -0,0 +1,89 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The input surface an expression was parsed as.
+ */
+export type LayoutForm = "compact" | "outline" | "auto";
+/**
+ * A validation issue with its formatted, human-readable rendering.
+ */
+export type LayoutIssue = {
+    line?: number | undefined;
+    col?: number | undefined;
+    message: string;
+    formatted: string;
+    suggestions?: string[] | undefined;
+};
+/**
+ * A block referenced by a layout expression and how it was spliced in.
+ */
+export type LayoutBlockReference = {
+    name: string;
+    mode: string;
+};
+/**
+ * astryx --json layout expand "<expr>" [path]
+ */
+export type LayoutExpandResponse = {
+    type: "layout.expand";
+    data: {
+        form: LayoutForm;
+        code: string;
+        componentsUsed: string[];
+        states: number;
+        todos: string[];
+        blocksReferenced: LayoutBlockReference[];
+        warnings: string[];
+        written: string | null;
+    };
+};
+/**
+ * astryx --json layout check "<expr>"
+ */
+export type LayoutCheckResponse = {
+    type: "layout.check";
+    data: {
+        valid: boolean;
+        form: LayoutForm;
+        errors: LayoutIssue[];
+        warnings: string[];
+        compact: string;
+        outline: string;
+    };
+};
+/**
+ * astryx --json layout grammar
+ */
+export type LayoutGrammarResponse = {
+    type: "layout.grammar";
+    data: {
+        text: string;
+        aliases: Record<string, string>;
+    };
+};
+export type LayoutResponse = LayoutExpandResponse | LayoutCheckResponse | LayoutGrammarResponse;
+/**
+ * Options for `layoutExpand()`.
+ */
+export type LayoutExpandOptions = {
+    targetPath?: string | undefined;
+    form?: LayoutForm | undefined;
+    loose?: boolean | undefined;
+    name?: string | undefined;
+    cwd?: string | undefined;
+};
+/**
+ * Options for `layoutCheck()`.
+ */
+export type LayoutCheckOptions = {
+    form?: LayoutForm | undefined;
+    loose?: boolean | undefined;
+    cwd?: string | undefined;
+};
+/**
+ * Options for `layoutGrammar()`.
+ */
+export type LayoutGrammarOptions = {
+    cwd?: string | undefined;
+};

package/api/layout/layout.type.mjs

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated types for the `layout` command — source of truth for its JSON
+ * responses. `astryx layout expand|check|grammar` turn compressed XLE/XLO
+ * expressions into validated XDS TSX (or echo canonical surfaces / a grammar
+ * cheatsheet). The `types/layout.d.ts` barrel re-exports from here.
+ *
+ * Invocation                                 -> type discriminator
+ * -----------------------------------------------------------------
+ * astryx --json layout expand "<expr>"       -> layout.expand
+ * astryx --json layout check "<expr>"        -> layout.check
+ * astryx --json layout grammar               -> layout.grammar
+ */
+
+/**
+ * The input surface an expression was parsed as.
+ * @typedef {'compact' | 'outline' | 'auto'} LayoutForm
+ */
+
+/**
+ * A validation issue with its formatted, human-readable rendering.
+ * @typedef {object} LayoutIssue
+ * @property {number} [line]
+ * @property {number} [col]
+ * @property {string} message
+ * @property {string} formatted
+ * @property {string[]} [suggestions]
+ */
+
+/**
+ * A block referenced by a layout expression and how it was spliced in.
+ * @typedef {object} LayoutBlockReference
+ * @property {string} name
+ * @property {string} mode
+ */
+
+/**
+ * astryx --json layout expand "<expr>" [path]
+ * @typedef {object} LayoutExpandResponse
+ * @property {'layout.expand'} type
+ * @property {object} data
+ * @property {LayoutForm} data.form
+ * @property {string} data.code
+ * @property {string[]} data.componentsUsed
+ * @property {number} data.states Number of useState hooks the expansion scaffolded.
+ * @property {string[]} data.todos
+ * @property {LayoutBlockReference[]} data.blocksReferenced
+ * @property {string[]} data.warnings
+ * @property {string | null} data.written
+ */
+
+/**
+ * astryx --json layout check "<expr>"
+ * @typedef {object} LayoutCheckResponse
+ * @property {'layout.check'} type
+ * @property {object} data
+ * @property {boolean} data.valid
+ * @property {LayoutForm} data.form
+ * @property {LayoutIssue[]} data.errors
+ * @property {string[]} data.warnings
+ * @property {string} data.compact
+ * @property {string} data.outline
+ */
+
+/**
+ * astryx --json layout grammar
+ * @typedef {object} LayoutGrammarResponse
+ * @property {'layout.grammar'} type
+ * @property {object} data
+ * @property {string} data.text
+ * @property {Record<string, string>} data.aliases Alias table (short name -> canonical component), from the registry.
+ */
+
+/**
+ * @typedef {LayoutExpandResponse | LayoutCheckResponse | LayoutGrammarResponse} LayoutResponse
+ */
+
+/**
+ * Options for `layoutExpand()`.
+ * @typedef {object} LayoutExpandOptions
+ * @property {string} [targetPath]
+ * @property {LayoutForm} [form]
+ * @property {boolean} [loose]
+ * @property {string} [name]
+ * @property {string} [cwd]
+ */
+
+/**
+ * Options for `layoutCheck()`.
+ * @typedef {object} LayoutCheckOptions
+ * @property {LayoutForm} [form]
+ * @property {boolean} [loose]
+ * @property {string} [cwd]
+ */
+
+/**
+ * Options for `layoutGrammar()`.
+ * @typedef {object} LayoutGrammarOptions
+ * @property {string} [cwd]
+ */
+
+export {};

package/api/layout/layoutCheck.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `layoutCheck()` / `astryx layout check`. Colocated with
+ * the API function it documents; the response-shape source of truth stays in
+ * `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/layout/layoutCheck.doc.mjs

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `layoutCheck()` / `astryx layout check`. Colocated with
+ * the API function it documents; the response-shape source of truth stays in
+ * `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'layoutCheck',
+  namespace: 'cli/api',
+  displayName: 'layoutCheck()',
+  summary: 'Validate a layout expression without expanding it.',
+  description:
+    'The validator behind `astryx layout check`. Parses and validates a compressed XLE/XLO ' +
+    'expression without generating any TSX, and echoes it back in both canonical surfaces ' +
+    '(compact and outline). Validation failures are reported in the layout.check envelope ' +
+    '(valid: false) with line/col and suggestions (not thrown) so callers can lint an ' +
+    'expression and surface fixes.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'layoutCheck(expression: string, options?: LayoutCheckOptions): Promise<LayoutCheckResponse>',
+  keywords: ['layout', 'check', 'validate', 'xle', 'xlo', 'lint'],
+  params: [
+    {
+      name: 'expression',
+      type: 'string',
+      description: 'The layout expression to validate.',
+      required: true,
+    },
+    {
+      name: 'options.form',
+      type: "'compact' | 'outline' | 'auto'",
+      description:
+        'Force which input surface the expression is parsed as, or auto-detect it.',
+      default: "'auto'",
+    },
+    {
+      name: 'options.loose',
+      type: 'boolean',
+      description:
+        'Treat unknown {hint} references as warnings instead of errors.',
+      default: 'false',
+    },
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description: 'Directory the block catalog and registry resolve against.',
+    },
+  ],
+  returns: [
+    {
+      type: 'layout.check',
+      description:
+        'The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).',
+    },
+  ],
+  throws: [
+    {code: 'ERR_INVALID_ARGUMENT', when: 'the expression is empty'},
+    {
+      code: 'ERR_INVALID_OPTION',
+      when: 'form is not one of "compact", "outline", or "auto"',
+    },
+    {
+      code: 'ERR_LAYOUT_PARSE',
+      when: 'the expression has a syntax error (reported with line/col)',
+    },
+  ],
+  examples: [
+    {
+      label: 'Validate an expression',
+      code: 'const r = await layoutCheck(\'VStack[g4] > Text"Hi"\');',
+    },
+    {
+      label: 'Read the canonical forms',
+      code: 'const {data} = await layoutCheck(\'Card > Text"Hi"\');',
+    },
+  ],
+  command: 'layout check',
+  related: ['layoutExpand', 'layoutGrammar'],
+};

package/api/layout/layoutExpand.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `layoutExpand()` / `astryx layout expand`. Colocated
+ * with the API function it documents; the response-shape source of truth stays
+ * in `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;