An open source design system that's fully customizable and agent ready
TypeScript
refactor(cli): split layout into api/layout leaf shape (#4478)
Joey08c99b8f01db
diff --git a/.changeset/cli-layout-leaves.md b/.changeset/cli-layout-leaves.mdnew file mode 100644index 0000000000..6fa66b1751--- /dev/null+++ b/.changeset/cli-layout-leaves.md@@ -0,0 +1,6 @@+---+'@astryxdesign/cli': patch+---++[refactor] CLI: layout reorganized into the api/layout leaf shape — a shared `_adapter.mjs` (`analyze`/`loadBlocks`/`formatIssue` over `lib/xle`) with thin `expand/`, `check/`, and `grammar/` leaves, plus a `layout.mjs` barrel. `api/index.mjs` and the CLI are unchanged (they import via the barrel). Pure reorg: `layout expand`/`check`/`grammar` `--json` envelopes and human output are byte-identical.+@josephfarinadiff --git a/.github/scripts/api-cli-parity-test.mjs b/.github/scripts/api-cli-parity-test.mjsindex f3f12f82bf..f147cc5351 100644--- a/.github/scripts/api-cli-parity-test.mjs+++ b/.github/scripts/api-cli-parity-test.mjs@@ -200,11 +200,14 @@ if (firstTemplate) {add('template nonexistent', ['template', 'nonexistent99'],() => apiCall(api.template, 'nonexistent99'));-// Theme add — list + error paths (read-only; never scaffolds files here).+// Theme list + add error path (read-only; never scaffolds files here).+// `theme list` / `theme add --list` are served by the dedicated themeList()+// leaf (the CLI routes the --list affordance there); themeAdd() now only+// scaffolds a named slug and throws on a missing/unknown one.add('theme list', ['theme', 'list'],- () => apiCall(api.themeAdd, undefined, {list: true, cwd: ROOT}));+ () => apiCall(api.themeList));add('theme add --list', ['theme', 'add', '--list'],- () => apiCall(api.themeAdd, undefined, {list: true, cwd: ROOT}));+ () => apiCall(api.themeList));add('theme add nonexistent', ['theme', 'add', 'nonexistent99'],() => apiCall(api.themeAdd, 'nonexistent99', {cwd: ROOT}));diff --git a/packages/cli/api/layout/_adapter.mjs b/packages/cli/api/layout/_adapter.mjsnew file mode 100644index 0000000000..4f670530dd--- /dev/null+++ b/packages/cli/api/layout/_adapter.mjs@@ -0,0 +1,117 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Shared analysis layer for the `layout` command's expand/check leaves.+ *+ * Loads the block catalog (template blocks + app-registered components), builds+ * the branch registry, and parses+validates a layout expression into a doc ++ * issues. Both the expand and check leaves sit on `analyze`; neither parses or+ * validates directly. (The grammar leaf needs none of this — it only reads the+ * registry alias table.)+ *+ * @input expression string (+ options)+ * @output analyze() -> {doc, registry, blocks, errors, warnings}; formatIssue()+ * @position api — shared core over lib/xle; leaves in expand/ + check/ project it+ */++import {AstryxError} from '../error.mjs';+import {ERROR_CODES} from '../../lib/error-codes.mjs';+import {parse, XLEParseError} from '../../lib/xle/parse.mjs';+import {validate} from '../../lib/xle/validate.mjs';+import {buildRegistry} from '../../lib/xle/registry.mjs';+import {discoverTemplates} from '../template/template.mjs';+import {Project} from '../../lib/project.mjs';++/**+ * @typedef {object} LayoutBlock+ * @property {string} dirName+ * @property {string} name+ * @property {'template'|'component'} kind+ * @property {string} [type]+ * @property {string} [description]+ * @property {string} [category]+ * @property {string} [importPath]+ * @property {string} [filePath]+ * @property {boolean} [isDefault]+ */++/**+ * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus+ * any app-registered local components from astryx.config.mjs+ * `experimental.xle.components` (imported by name). App components are how XLE+ * reaches domain pieces — the KpiCard/chart/drawer set that the+ * @astryxdesign/core registry can't see.+ *+ * @param {string} cwd+ * @returns {Promise<LayoutBlock[]>}+ */+async function loadBlocks(cwd) {+ /** @type {LayoutBlock[]} */+ const blocks = [];+ try {+ const all = await discoverTemplates(cwd);+ for (const t of all) if (t.type === 'block') blocks.push({...t, kind: 'template'});+ } catch {+ // discovery is best-effort+ }+ try {+ const project = await Project.load(cwd);+ /** @type {Record<string, {from?: string, description?: string, default?: boolean}>} */+ const components = project.config.experimental?.xle?.components ?? {};+ for (const [name, spec] of Object.entries(components)) {+ const importPath = spec.from;+ if (!importPath) continue;+ blocks.push({+ type: 'block',+ kind: 'component',+ dirName: name,+ name,+ description: spec.description ?? '',+ category: 'app',+ importPath,+ isDefault: Boolean(spec.default),+ });+ }+ } catch {+ // config is optional+ }+ return blocks;+}++/** @param {import('../../lib/xle/xle-ast').RawIssue} issue */+export function formatIssue(issue) {+ const where = issue.line != null ? `line ${issue.line}: ` : '';+ return `${where}${issue.message}`;+}++/**+ * Parse + validate, throwing structured XDSErrors on failure.+ * Returns {doc, registry, blocks, warnings}.+ *+ * @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()} = {}) {+ const registry = /** @type {import('../../lib/xle/xle-ast').Registry} */ (+ /** @type {unknown} */ (await buildRegistry({cwd}))+ );+ const blocks = await loadBlocks(cwd);++ /** @type {import('../../lib/xle/xle-ast').XLEDoc} */+ let doc;+ try {+ doc = parse(expression, {form});+ } catch (e) {+ if (e instanceof XLEParseError) {+ throw new AstryxError(+ `Layout expression syntax error at line ${e.line}, col ${e.col}: ${e.message}`,+ undefined,+ ERROR_CODES.ERR_LAYOUT_PARSE,+ );+ }+ throw e;+ }++ const {errors, warnings} = validate(doc, registry, blocks, {loose});+ return {doc, registry, blocks, errors, warnings};+}diff --git a/packages/cli/api/layout/check/check.mjs b/packages/cli/api/layout/check/check.mjsnew file mode 100644index 0000000000..5fa0bd7133--- /dev/null+++ b/packages/cli/api/layout/check/check.mjs@@ -0,0 +1,40 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx layout check` leaf — validate a layout expression without+ * expanding, echoing both canonical surfaces (compact + outline). Resolution ++ * validation come from ../_adapter.mjs (analyze); this leaf projects the+ * `layout.check` envelope.+ *+ * @input expression string (+ options)+ * @output {type:'layout.check', data}+ * @position api — leaf over ../_adapter.mjs + lib/xle/print+ */++import {toCompact, toOutline} from '../../../lib/xle/print.mjs';+import {analyze, formatIssue} from '../_adapter.mjs';++/**+ * `astryx layout check "<expr>" [--form compact|outline]`+ * Validates without expanding; echoes both canonical surfaces.+ *+ * @param {string} expression+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]+ * @returns {Promise<import('../../../types/layout').LayoutCheckResponse>}+ */+export async function layoutCheck(expression, options = {}) {+ const {form = 'auto', loose = false, cwd = process.cwd()} = options;+ const {doc, errors, warnings} = await analyze(expression, {form, loose, cwd});++ return {+ type: 'layout.check',+ data: {+ valid: errors.length === 0,+ form: doc.form,+ errors: errors.map(e => ({...e, formatted: formatIssue(e)})),+ warnings: warnings.map(formatIssue),+ compact: toCompact(doc),+ outline: toOutline(doc),+ },+ };+}diff --git a/packages/cli/api/layout/expand/expand.mjs b/packages/cli/api/layout/expand/expand.mjsnew file mode 100644index 0000000000..16d854db2f--- /dev/null+++ b/packages/cli/api/layout/expand/expand.mjs@@ -0,0 +1,153 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx layout expand` leaf — expand a validated layout expression into+ * XDS TSX (optionally written to disk). Resolution + validation come from+ * ../_adapter.mjs (analyze); this leaf owns block-module assembly, code+ * generation, and the path-safe write, and projects the `layout.expand` envelope.+ *+ * @input expression string (+ options)+ * @output {type:'layout.expand', data}+ * @position api — leaf over ../_adapter.mjs + lib/xle/expand+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {AstryxError} from '../../error.mjs';+import {ERROR_CODES} from '../../../lib/error-codes.mjs';+import {assertWithin, isFilePathArg, PathSafetyError} from '../../../utils/path-safety.mjs';+import {detectForm} from '../../../lib/xle/parse.mjs';+import {expand} from '../../../lib/xle/expand.mjs';+import {stripTemplateAssetRefs} from '../../template/template.mjs';+import {analyze, formatIssue} from '../_adapter.mjs';++/** @param {string} name */+const normKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');++/**+ * Collect the block names referenced by {hints} anywhere in the doc.+ * @param {import('../../../lib/xle/xle-ast').XLEDoc} doc+ */+function collectHintNames(doc) {+ /** @type {Set<string>} */+ const names = new Set();+ /** @param {import('../../../lib/xle/xle-ast').XLEItem} node */+ const visitNode = (node) => {+ if (!node || node.kind === 'group') {+ (node?.children || []).forEach(visit);+ return;+ }+ if (node.hint?.block) names.add(node.hint.block.name);+ for (const slot of node.slots || []) {+ const value = slot.value;+ if (value && typeof value === 'object' && 'hint' in value && value.hint?.block) {+ names.add(value.hint.block.name);+ }+ if (value && typeof value === 'object' && 'subexpr' in value) {+ (value.subexpr || []).forEach(visit);+ }+ }+ (node.children || []).forEach(visit);+ };+ /** @param {import('../../../lib/xle/xle-ast').XLEItem} item */+ const visit = (item) => (item?.kind === 'group' ? item.children.forEach(visit) : visitNode(item));+ doc.roots.forEach(visit);+ doc.overlays.forEach(visit);+ return names;+}++/**+ * Build the blockModules map expand() needs: import-mode for app components,+ * splice-mode (reading + asset-stripping the block source) for template blocks.+ * Only blocks actually referenced are read.+ *+ * @param {import('../../../lib/xle/xle-ast').XLEDoc} doc+ * @param {import('../_adapter.mjs').LayoutBlock[]} blocks+ * @returns {Map<string, import('../../../lib/xle/xle-ast').BlockModule>}+ */+function buildBlockModules(doc, blocks) {+ const referenced = collectHintNames(doc);+ if (referenced.size === 0) return new Map();+ const byKey = new Map(blocks.map(b => [normKey(b.dirName), b]));+ /** @type {Map<string, import('../../../lib/xle/xle-ast').BlockModule>} */+ const modules = new Map();+ for (const name of referenced) {+ const block = byKey.get(normKey(name));+ if (!block) continue;+ if (block.kind === 'component') {+ modules.set(name, /** @type {import('../../../lib/xle/xle-ast').BlockModule} */ (/** @type {unknown} */ ({mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault})));+ } else if (block.filePath && fs.existsSync(block.filePath)) {+ modules.set(name, /** @type {import('../../../lib/xle/xle-ast').BlockModule} */ ({mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))}));+ }+ }+ return modules;+}++/**+ * `astryx layout expand "<expr>" [path]`+ *+ * @param {string} expression+ * @param {object} [options]+ * @param {string} [options.targetPath] - write TSX here (validated against cwd)+ * @param {'compact'|'outline'|'auto'} [options.form]+ * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings+ * @param {string} [options.name] - generated component name+ * @param {string} [options.cwd]+ * @returns {Promise<import('../../../types/layout').LayoutExpandResponse>}+ */+export async function layoutExpand(expression, options = {}) {+ const {targetPath, form = 'auto', loose = false, name, cwd = process.cwd()} = options;+ const {doc, registry, blocks, errors, warnings} = await analyze(expression, {form, loose, cwd});++ if (errors.length > 0) {+ throw new AstryxError(+ `Layout expression is invalid:\n` + errors.map(e => ` - ${formatIssue(e)}`).join('\n'),+ errors.flatMap(e => (e.suggestions || []).map(s => ({name: s, reason: 'did you mean this?'}))),+ ERROR_CODES.ERR_LAYOUT_INVALID,+ );+ }++ const componentName = name || 'GeneratedLayout';+ if (!/^[A-Z][A-Za-z0-9]*$/.test(componentName)) {+ throw new AstryxError(+ `--name must be a PascalCase component name, got '${componentName}'`,+ undefined,+ ERROR_CODES.ERR_INVALID_ARGUMENT,+ );+ }+ const blockModules = buildBlockModules(doc, blocks);+ const result = expand(doc, registry, {componentName, blockModules});++ let written = null;+ if (targetPath) {+ let resolved;+ try {+ resolved = assertWithin(targetPath, 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);+ }++ return {+ type: 'layout.expand',+ data: {+ form: form === 'auto' ? detectForm(expression) : form,+ code: result.code,+ componentsUsed: result.componentsUsed,+ states: result.states,+ todos: result.todos,+ blocksReferenced: [...blockModules.entries()].map(([name, m]) => ({name, mode: m.mode})),+ warnings: warnings.map(formatIssue),+ written,+ },+ };+}diff --git a/packages/cli/api/layout/grammar/grammar.mjs b/packages/cli/api/layout/grammar/grammar.mjsnew file mode 100644index 0000000000..fe8bb17a63--- /dev/null+++ b/packages/cli/api/layout/grammar/grammar.mjs@@ -0,0 +1,88 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx layout grammar` leaf — the agent cheatsheet, with the alias+ * table generated from this branch's registry (never hand-maintained). Reads+ * only the registry; shares nothing with expand/check, so it has no adapter.+ *+ * @output {type:'layout.grammar', data}+ * @position api — leaf over lib/xle/registry+ */++import {buildRegistry, ALIAS_TABLE} from '../../../lib/xle/registry.mjs';++/**+ * `astryx layout grammar` — the agent cheatsheet, with the alias table+ * generated from this branch's registry (never hand-maintained).+ *+ * @param {{cwd?: string}} [options]+ * @returns {Promise<import('../../../types/layout').LayoutGrammarResponse>}+ */+export async function layoutGrammar(options = {}) {+ const {cwd = process.cwd()} = options;+ const registry = await buildRegistry({cwd});++ /** @type {string[]} */+ const aliasLines = [];+ /** @type {Map<string, string[]>} */+ const byTarget = new Map();+ for (const [alias, target] of registry.aliases) {+ if (!byTarget.has(target)) byTarget.set(target, []);+ byTarget.get(target)?.push(alias);+ }+ for (const [target, aliases] of [...byTarget.entries()].sort(([a], [b]) => a.localeCompare(b))) {+ aliasLines.push(`${aliases.join('/')}=${target}`);+ }++ const text = `XLE/XLO — XDS layout expressions (branch-generated; aliases reflect this install)++WORKFLOW+ astryx layout check "<expr>" validate; echoes canonical compact + outline forms+ astryx layout expand "<expr>" [path] emit validated TSX (path optional; --name <Pascal>)+ Errors carry line/col + suggestions. Fix and resubmit; nothing is guessed.++TWO SURFACES, ONE LANGUAGE (autodetected; --form to force)+ compact: A[cp6 @topNav=TN] > L > LC > S[p6] > (C{card-callout}*4) + T+ outline: indentation = nesting · same-indent = siblings · "repeat N:" block = (...)*N+ slot lines: topNav: TN (or a block: topNav:\\n TN ...)++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)+ trailing ! initial selection for scaffolded state: Tab"Overview"!++ATTRS [...] (outline: bare tokens after the name, no brackets)+ fused p6 g4 c4 w240 h2 cp2 mw960 rg2 cg2 (per-component: padding lives on Card/Section/AppShell.cp — p6 on AppShell/Layout/VStack errors with a correction)+ key=value t=email href='/x' c{min:340} dv=[top,bottom] — keys validated per component+ flags req opt dis striped hover divider … (isX/hasX props) · negate: !scroll+ align j= main axis, a= cross axis — expander picks hAlign/vAlign per stack direction+ slots @slotName=Node | @slotName=(sub > expr) | @slotName='text' | @slotName=#id+ trigger opens=#id (a plain attr, no @ — binds an onClick that opens the overlay)+ fill on a stack child → wraps in <StackItem size="fill">++TEMPLATE REFERENCING ({hint} pulls in real content — this is how XLE reaches past the @astryxdesign/core shell)+ C{card-callout} splice a template block (astryx template --list --type block):+ the block is co-defined once in the file, referenced, imports merged+ {kpi-card} standalone reference (no wrapper element) — place a component directly+ {kpi-card}*4 repeat a reference; the definition/import is emitted once+ app components register local ones in astryx.config.mjs to import them by name:+ export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}}}}}+ then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)++STRUCTURE THE EXPANDER HANDLES+ Layout > LH + LC + LF + LP children auto-route into header/content/footer/start slots+ T > (TR>THC*4) + (TR>TC*4)*6 rows partition into TableHeader/TableBody automatically+ TabList/inputs required value+onChange scaffold typed useState automatically+ overlays compact: tree ;; Dlg#confirm[...] · outline: overlays: section+ trigger: B"Delete"[opens=#confirm]++ALIASES (full component names always valid; XDS prefix optional)+ ${aliasLines.join(' ')}+`;++ return {type: 'layout.grammar', data: {text, aliases: Object.fromEntries(registry.aliases)}};+}++export {ALIAS_TABLE};diff --git a/packages/cli/api/layout/layout.mjs b/packages/cli/api/layout/layout.mjsindex bf0b8074ba..cbc291cead 100644--- a/packages/cli/api/layout/layout.mjs+++ b/packages/cli/api/layout/layout.mjs@@ -1,351 +1,17 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Programmatic API for the layout command (XLE/XLO).+ * @file `layout` command barrel — re-exports the expand/check/grammar leaves so+ * the CLI (cli/commands/layout.mjs) and scripted callers import from one place.+ * Each leaf is also importable directly (e.g. api/layout/expand/expand.mjs). The+ * shared analysis core lives in ./_adapter.mjs. `layout` has real subcommands,+ * so there is no flag-dispatch here — the CLI calls the leaf it wants.*- * `astryx layout` turns token-compressed layout expressions into validated- * XDS TSX. Two input surfaces — compact (Emmet-derived XLE) and outline- * (indentation-based XLO) — share one AST, one validator, and one- * expander. See the research: pastes P2376666892 (spec) and P2376717669- * (outline surface).- *- * @input expression string (+ options)+ * @input layout expressions (+ options), per leaf* @output {type, data} envelopes: layout.expand / layout.check / layout.grammar- * @position api — pure orchestration over lib/xle; command wrapper in commands/layout.mjs- */--import * as fs from 'node:fs';-import * as path from 'node:path';-import {AstryxError} from '../error.mjs';-import {ERROR_CODES} from '../../lib/error-codes.mjs';-import {assertWithin, isFilePathArg, PathSafetyError} from '../../utils/path-safety.mjs';-import {parse, detectForm, XLEParseError} from '../../lib/xle/parse.mjs';-import {validate} from '../../lib/xle/validate.mjs';-import {expand} from '../../lib/xle/expand.mjs';-import {toCompact, toOutline} from '../../lib/xle/print.mjs';-import {buildRegistry, ALIAS_TABLE} from '../../lib/xle/registry.mjs';-import {discoverTemplates, stripTemplateAssetRefs} from '../template/template.mjs';-import {Project} from '../../lib/project.mjs';--/**- * @typedef {object} LayoutBlock- * @property {string} dirName- * @property {string} name- * @property {'template'|'component'} kind- * @property {string} [type]- * @property {string} [description]- * @property {string} [category]- * @property {string} [importPath]- * @property {string} [filePath]- * @property {boolean} [isDefault]- */--/**- * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus- * any app-registered local components from astryx.config.mjs- * `experimental.xle.components` (imported by name). App components are how XLE- * reaches domain pieces — the KpiCard/chart/drawer set that the- * @astryxdesign/core registry can't see.- *- * @param {string} cwd- * @returns {Promise<LayoutBlock[]>}- */-async function loadBlocks(cwd) {- /** @type {LayoutBlock[]} */- const blocks = [];- try {- const all = await discoverTemplates(cwd);- for (const t of all) if (t.type === 'block') blocks.push({...t, kind: 'template'});- } catch {- // discovery is best-effort- }- try {- const project = await Project.load(cwd);- /** @type {Record<string, {from?: string, description?: string, default?: boolean}>} */- const components = project.config.experimental?.xle?.components ?? {};- for (const [name, spec] of Object.entries(components)) {- const importPath = spec.from;- if (!importPath) continue;- blocks.push({- type: 'block',- kind: 'component',- dirName: name,- name,- description: spec.description ?? '',- category: 'app',- importPath,- isDefault: Boolean(spec.default),- });- }- } catch {- // config is optional- }- return blocks;-}--/** @param {string} name */-const normKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');--/**- * Collect the block names referenced by {hints} anywhere in the doc.- * @param {import('../../lib/xle/xle-ast').XLEDoc} doc+ * @position api — command barrel over the expand/check/grammar leaves*/-function collectHintNames(doc) {- /** @type {Set<string>} */- const names = new Set();- /** @param {import('../../lib/xle/xle-ast').XLEItem} node */- const visitNode = (node) => {- if (!node || node.kind === 'group') {- (node?.children || []).forEach(visit);- return;- }- if (node.hint?.block) names.add(node.hint.block.name);- for (const slot of node.slots || []) {- const value = slot.value;- if (value && typeof value === 'object' && 'hint' in value && value.hint?.block) {- names.add(value.hint.block.name);- }- if (value && typeof value === 'object' && 'subexpr' in value) {- (value.subexpr || []).forEach(visit);- }- }- (node.children || []).forEach(visit);- };- /** @param {import('../../lib/xle/xle-ast').XLEItem} item */- const visit = (item) => (item?.kind === 'group' ? item.children.forEach(visit) : visitNode(item));- doc.roots.forEach(visit);- doc.overlays.forEach(visit);- return names;-}--/**- * Build the blockModules map expand() needs: import-mode for app components,- * splice-mode (reading + asset-stripping the block source) for template blocks.- * Only blocks actually referenced are read.- *- * @param {import('../../lib/xle/xle-ast').XLEDoc} doc- * @param {LayoutBlock[]} blocks- * @returns {Map<string, import('../../lib/xle/xle-ast').BlockModule>}- */-function buildBlockModules(doc, blocks) {- const referenced = collectHintNames(doc);- if (referenced.size === 0) return new Map();- const byKey = new Map(blocks.map(b => [normKey(b.dirName), b]));- /** @type {Map<string, import('../../lib/xle/xle-ast').BlockModule>} */- const modules = new Map();- for (const name of referenced) {- const block = byKey.get(normKey(name));- if (!block) continue;- if (block.kind === 'component') {- modules.set(name, /** @type {import('../../lib/xle/xle-ast').BlockModule} */ (/** @type {unknown} */ ({mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault})));- } else if (block.filePath && fs.existsSync(block.filePath)) {- modules.set(name, /** @type {import('../../lib/xle/xle-ast').BlockModule} */ ({mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))}));- }- }- return modules;-}--/** @param {import('../../lib/xle/xle-ast').RawIssue} issue */-function formatIssue(issue) {- const where = issue.line != null ? `line ${issue.line}: ` : '';- return `${where}${issue.message}`;-}--/**- * Parse + validate, throwing structured XDSErrors on failure.- * Returns {doc, registry, blocks, warnings}.- *- * @param {string} expression- * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]- */-async function analyze(expression, {form = 'auto', loose = false, cwd = process.cwd()} = {}) {- const registry = /** @type {import('../../lib/xle/xle-ast').Registry} */ (- /** @type {unknown} */ (await buildRegistry({cwd}))- );- const blocks = await loadBlocks(cwd);-- /** @type {import('../../lib/xle/xle-ast').XLEDoc} */- let doc;- try {- doc = parse(expression, {form});- } catch (e) {- if (e instanceof XLEParseError) {- throw new AstryxError(- `Layout expression syntax error at line ${e.line}, col ${e.col}: ${e.message}`,- undefined,- ERROR_CODES.ERR_LAYOUT_PARSE,- );- }- throw e;- }-- const {errors, warnings} = validate(doc, registry, blocks, {loose});- return {doc, registry, blocks, errors, warnings};-}--/**- * `astryx layout expand "<expr>" [path]`- *- * @param {string} expression- * @param {object} [options]- * @param {string} [options.targetPath] - write TSX here (validated against cwd)- * @param {'compact'|'outline'|'auto'} [options.form]- * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings- * @param {string} [options.name] - generated component name- * @param {string} [options.cwd]- */-export async function layoutExpand(expression, options = {}) {- const {targetPath, form = 'auto', loose = false, name, cwd = process.cwd()} = options;- const {doc, registry, blocks, errors, warnings} = await analyze(expression, {form, loose, cwd});-- if (errors.length > 0) {- throw new AstryxError(- `Layout expression is invalid:\n` + errors.map(e => ` - ${formatIssue(e)}`).join('\n'),- errors.flatMap(e => (e.suggestions || []).map(s => ({name: s, reason: 'did you mean this?'}))),- ERROR_CODES.ERR_LAYOUT_INVALID,- );- }-- const componentName = name || 'GeneratedLayout';- if (!/^[A-Z][A-Za-z0-9]*$/.test(componentName)) {- throw new AstryxError(- `--name must be a PascalCase component name, got '${componentName}'`,- undefined,- ERROR_CODES.ERR_INVALID_ARGUMENT,- );- }- const blockModules = buildBlockModules(doc, blocks);- const result = expand(doc, registry, {componentName, blockModules});-- let written = null;- if (targetPath) {- let resolved;- try {- resolved = assertWithin(targetPath, 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);- }-- return {- type: 'layout.expand',- data: {- form: form === 'auto' ? detectForm(expression) : form,- code: result.code,- componentsUsed: result.componentsUsed,- states: result.states,- todos: result.todos,- blocksReferenced: [...blockModules.entries()].map(([name, m]) => ({name, mode: m.mode})),- warnings: warnings.map(formatIssue),- written,- },- };-}--/**- * `astryx layout check "<expr>" [--form compact|outline]`- * Validates without expanding; echoes both canonical surfaces.- *- * @param {string} expression- * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]- */-export async function layoutCheck(expression, options = {}) {- const {form = 'auto', loose = false, cwd = process.cwd()} = options;- const {doc, errors, warnings} = await analyze(expression, {form, loose, cwd});-- return {- type: 'layout.check',- data: {- valid: errors.length === 0,- form: doc.form,- errors: errors.map(e => ({...e, formatted: formatIssue(e)})),- warnings: warnings.map(formatIssue),- compact: toCompact(doc),- outline: toOutline(doc),- },- };-}--/**- * `astryx layout grammar` — the agent cheatsheet, with the alias table- * generated from this branch's registry (never hand-maintained).- *- * @param {{cwd?: string}} [options]- */-export async function layoutGrammar(options = {}) {- const {cwd = process.cwd()} = options;- const registry = await buildRegistry({cwd});-- /** @type {string[]} */- const aliasLines = [];- /** @type {Map<string, string[]>} */- const byTarget = new Map();- for (const [alias, target] of registry.aliases) {- if (!byTarget.has(target)) byTarget.set(target, []);- byTarget.get(target)?.push(alias);- }- for (const [target, aliases] of [...byTarget.entries()].sort(([a], [b]) => a.localeCompare(b))) {- aliasLines.push(`${aliases.join('/')}=${target}`);- }-- const text = `XLE/XLO — XDS layout expressions (branch-generated; aliases reflect this install)--WORKFLOW- astryx layout check "<expr>" validate; echoes canonical compact + outline forms- astryx layout expand "<expr>" [path] emit validated TSX (path optional; --name <Pascal>)- Errors carry line/col + suggestions. Fix and resubmit; nothing is guessed.--TWO SURFACES, ONE LANGUAGE (autodetected; --form to force)- compact: A[cp6 @topNav=TN] > L > LC > S[p6] > (C{card-callout}*4) + T- outline: indentation = nesting · same-indent = siblings · "repeat N:" block = (...)*N- slot lines: topNav: TN (or a block: topNav:\\n TN ...)--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)- trailing ! initial selection for scaffolded state: Tab"Overview"!--ATTRS [...] (outline: bare tokens after the name, no brackets)- fused p6 g4 c4 w240 h2 cp2 mw960 rg2 cg2 (per-component: padding lives on Card/Section/AppShell.cp — p6 on AppShell/Layout/VStack errors with a correction)- key=value t=email href='/x' c{min:340} dv=[top,bottom] — keys validated per component- flags req opt dis striped hover divider … (isX/hasX props) · negate: !scroll- align j= main axis, a= cross axis — expander picks hAlign/vAlign per stack direction- slots @slotName=Node | @slotName=(sub > expr) | @slotName='text' | @slotName=#id- trigger opens=#id (a plain attr, no @ — binds an onClick that opens the overlay)- fill on a stack child → wraps in <StackItem size="fill">--TEMPLATE REFERENCING ({hint} pulls in real content — this is how XLE reaches past the @astryxdesign/core shell)- C{card-callout} splice a template block (astryx template --list --type block):- the block is co-defined once in the file, referenced, imports merged- {kpi-card} standalone reference (no wrapper element) — place a component directly- {kpi-card}*4 repeat a reference; the definition/import is emitted once- app components register local ones in astryx.config.mjs to import them by name:- export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}}}}}- then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)--STRUCTURE THE EXPANDER HANDLES- Layout > LH + LC + LF + LP children auto-route into header/content/footer/start slots- T > (TR>THC*4) + (TR>TC*4)*6 rows partition into TableHeader/TableBody automatically- TabList/inputs required value+onChange scaffold typed useState automatically- overlays compact: tree ;; Dlg#confirm[...] · outline: overlays: section- trigger: B"Delete"[opens=#confirm]--ALIASES (full component names always valid; XDS prefix optional)- ${aliasLines.join(' ')}-`;-- return {type: 'layout.grammar', data: {text, aliases: Object.fromEntries(registry.aliases)}};-}-export {ALIAS_TABLE};+export {layoutExpand} from './expand/expand.mjs';+export {layoutCheck} from './check/check.mjs';+export {layoutGrammar, ALIAS_TABLE} from './grammar/grammar.mjs';