@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/layout/layout.test.mjs

@@ -1,297 +0,0 @@
-// 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

@@ -1,89 +0,0 @@
-// @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

@@ -1,103 +0,0 @@
-// 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

@@ -1,11 +0,0 @@
-// @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

@@ -1,84 +0,0 @@
-// 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',
-  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

@@ -1,11 +0,0 @@
-// @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;