@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src/lib → lib}/xle/splice.mjs

@@ -29,9 +29,12 @@ const IMPORT_RE =
  * default, namespace, and side-effect imports (incl. simple multiline named
  * lists). Returns {imports, rest} where rest is the source with those import
  * lines removed.
+ * @param {string} source
+ * @returns {{imports: import('./xle-ast').ParsedImport[], rest: string}}
  */
 export function parseImportStatements(source) {
   const lines = source.split('\n');
+  /** @type {import('./xle-ast').ParsedImport[]} */
   const imports = [];
   const kept = [];
   for (let i = 0; i < lines.length; i++) {
@@ -74,7 +77,7 @@ export function parseImportStatements(source) {
  *
  * @param {string} source - raw block TSX
  * @param {string} fallbackName - PascalCase name to use if no export name found
- * @returns {{componentName: string, imports: object[], body: string} | null}
+ * @returns {import('./xle-ast').PreparedSpliceModule | null}
  */
 export function prepareSpliceModule(source, fallbackName) {
   const {imports, rest} = parseImportStatements(source);
@@ -106,6 +109,8 @@ export function prepareSpliceModule(source, fallbackName) {
 /**
  * Merge a parsed import list into an emitter import map.
  * The map is Map<source, {named:Set, types:Set, default?:string, namespace?:string, sideEffect?:bool}>.
+ * @param {Map<string, import('./xle-ast').ImportEntry>} map
+ * @param {import('./xle-ast').ParsedImport[]} imports
  */
 export function mergeImports(map, imports) {
   for (const imp of imports) {
@@ -113,6 +118,7 @@ export function mergeImports(map, imports) {
       map.set(imp.source, {named: new Set(), types: new Set(), default: null, namespace: null, sideEffect: false});
     }
     const entry = map.get(imp.source);
+    if (!entry) continue;
     if (imp.sideEffect) entry.sideEffect = true;
     if (imp.default) entry.default = imp.default;
     if (imp.namespace) entry.namespace = imp.namespace;
@@ -120,7 +126,12 @@ export function mergeImports(map, imports) {
   }
 }
 
-/** Render one merged import entry to a statement string. */
+/**
+ * Render one merged import entry to a statement string.
+ * @param {string} source
+ * @param {import('./xle-ast').ImportEntry} entry
+ * @returns {string}
+ */
 export function renderImport(source, entry) {
   if (entry.sideEffect && !entry.default && !entry.namespace && entry.named.size === 0 && entry.types.size === 0) {
     return `import '${source}';`;

package/{src/lib → lib}/xle/validate.mjs

@@ -19,7 +19,10 @@ import {levenshteinDistance} from '../levenshtein.mjs';
 import {KEY_ALIASES} from './parse.mjs';
 import {resolveComponent} from './registry-core.mjs';
 
-/** Boolean flag synonyms — agent-frequency spellings of isX/hasX props. */
+/**
+ * Boolean flag synonyms — agent-frequency spellings of isX/hasX props.
+ * @type {Record<string, string>}
+ */
 const FLAG_SYNONYMS = {
   req: 'isRequired', opt: 'isOptional', dis: 'isDisabled',
   scroll: 'isScrollable', divider: 'hasDivider', dividers: 'hasDivider',
@@ -30,6 +33,12 @@ const FLAG_SYNONYMS = {
 /** Props the expander treats as the node's primary text payload, in order. */
 export const PAYLOAD_PROPS = ['label', 'title', 'heading'];
 
+/**
+ * @param {string} input
+ * @param {string[]} candidates
+ * @param {number} [max]
+ * @returns {string[]}
+ */
 function suggest(input, candidates, max = 4) {
   const lower = input.toLowerCase();
   return candidates
@@ -45,6 +54,7 @@ function suggest(input, candidates, max = 4) {
     .map(s => s.name);
 }
 
+/** @param {string} name */
 function normalizeBlockKey(name) {
   return name.toLowerCase().replace(/[^a-z0-9]/g, '');
 }
@@ -53,6 +63,9 @@ function normalizeBlockKey(name) {
  * Resolve a word to a prop assignment via, in order: synonym table,
  * exact boolean prop, is/has-prefixed boolean prop, unique enum value.
  * Returns {prop, value} or null.
+ * @param {import('./xle-ast').RegistryComponent} component
+ * @param {string} word
+ * @returns {{prop: string, value: string|boolean, ambiguous?: undefined} | {ambiguous: string[], prop?: undefined, value?: undefined} | null}
  */
 function resolveWord(component, word) {
   const synonym = FLAG_SYNONYMS[word];
@@ -67,6 +80,7 @@ function resolveWord(component, word) {
     if (pref && pref.isBoolean) return {prop: prefix + cap, value: true};
   }
   // Unique enum membership across all enum-typed props.
+  /** @type {string[]} */
   const hits = [];
   for (const prop of component.props.values()) {
     if (prop.enumValues && prop.enumValues.includes(word)) hits.push(prop.name);
@@ -76,7 +90,12 @@ function resolveWord(component, word) {
   return null;
 }
 
-/** Map axis-neutral j=/a= keys onto the component's real alignment props. */
+/**
+ * Map axis-neutral j=/a= keys onto the component's real alignment props.
+ * @param {import('./xle-ast').RegistryComponent} component
+ * @param {string} key
+ * @returns {string}
+ */
 function resolveAxisKey(component, key) {
   const main = key === '__mainAxis';
   if (component.name === 'VStack') return main ? 'vAlign' : 'hAlign';
@@ -87,9 +106,14 @@ function resolveAxisKey(component, key) {
   return generic;
 }
 
-/** Grid's `columns` object shorthand: {min,max,fit|fill} → real keys. */
+/**
+ * Grid's `columns` object shorthand: {min,max,fit|fill} → real keys.
+ * @param {import('./xle-ast').XLEValue} value
+ * @returns {import('./xle-ast').XLEValue}
+ */
 function normalizeColumnsObject(value) {
   if (typeof value !== 'object' || value == null || Array.isArray(value)) return value;
+  /** @type {Record<string, import('./xle-ast').XLEValue>} */
   const out = {};
   for (const [k, v] of Object.entries(value)) {
     if (k === 'min') out.minWidth = v;
@@ -100,19 +124,35 @@ function normalizeColumnsObject(value) {
 }
 
 export class Validation {
+  /**
+   * @param {import('./xle-ast').Registry} registry
+   * @param {import('./browser').XLEBlock[]} [blocks]
+   * @param {{loose?: boolean}} [options]
+   */
   constructor(registry, blocks, {loose = false} = {}) {
     this.registry = registry;
     this.blocks = blocks || [];
     this.blockIndex = new Map(this.blocks.map(b => [normalizeBlockKey(b.dirName), b]));
     this.loose = loose;
+    /** @type {import('./xle-ast').RawIssue[]} */
     this.errors = [];
+    /** @type {import('./xle-ast').RawIssue[]} */
     this.warnings = [];
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {string} message
+   * @param {string[]} [suggestions]
+   */
   error(node, message, suggestions = []) {
     this.errors.push({message, line: node.line, col: node.col, suggestions});
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {string} message
+   */
   warn(node, message) {
     this.warnings.push({message, line: node.line, col: node.col});
   }
@@ -121,6 +161,10 @@ export class Validation {
     return [...this.registry.aliases.keys(), ...this.registry.componentNames];
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {import('./xle-ast').XLENode | null} parent
+   */
   bindNode(node, parent) {
     // Anonymous block reference ({block} with no host element).
     if (!node.name && node.hint) {
@@ -134,7 +178,7 @@ export class Validation {
       this.error(
         node,
         `Unknown component or alias '${node.name}'`,
-        suggest(node.name, this.nameCandidates()),
+        suggest(node.name ?? '', this.nameCandidates()),
       );
       node.bound = null;
     } else {
@@ -148,6 +192,10 @@ export class Validation {
     for (const child of node.children) this.bindAny(child, node);
   }
 
+  /**
+   * @param {import('./xle-ast').XLEItem} item
+   * @param {import('./xle-ast').XLENode | null} parent
+   */
   bindAny(item, parent) {
     if (item.kind === 'group') {
       for (const child of item.children) this.bindAny(child, parent);
@@ -156,7 +204,12 @@ export class Validation {
     }
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {import('./xle-ast').RegistryComponent} component
+   */
   bindAttrs(node, component) {
+    if (!node.bound) return;
     if (component.undocumented) {
       // No prop metadata for this export — bind raw and tell the author
       // nothing was checked, rather than rejecting valid props.
@@ -200,7 +253,7 @@ export class Validation {
           this.error(
             node,
             `'!${attr.key}' does not match a boolean prop of ${component.name}`,
-            suggest(attr.key, [...component.props.keys()].filter(p => component.props.get(p).isBoolean)),
+            suggest(attr.key, [...component.props.keys()].filter(p => component.props.get(p)?.isBoolean)),
           );
         } else {
           node.bound.props.set(hit.prop, false);
@@ -209,7 +262,13 @@ export class Validation {
     }
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {import('./xle-ast').RegistryComponent} component
+   * @param {import('./xle-ast').KvAttr} attr
+   */
   bindKv(node, component, attr) {
+    if (!node.bound) return;
     let key = attr.key.split('.')[0];
     key = KEY_ALIASES[key] ?? key;
 
@@ -253,7 +312,12 @@ export class Validation {
     node.bound.props.set(key, value);
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {import('./xle-ast').RegistryComponent} component
+   */
   bindMods(node, component) {
+    if (!node.bound) return;
     for (const mod of node.enumMods) {
       const hit = resolveWord(component, mod);
       if (!hit || hit.ambiguous) {
@@ -273,33 +337,45 @@ export class Validation {
     }
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {import('./xle-ast').RegistryComponent} component
+   */
   bindSlots(node, component) {
+    if (!node.bound) return;
     for (const slot of node.slots) {
       const prop = component.props.get(slot.key);
       if (!prop) {
         this.error(
           node,
           `${component.name} has no slot prop '${slot.key}'`,
-          suggest(slot.key, [...component.props.keys()].filter(k => component.props.get(k).isNode)),
+          suggest(slot.key, [...component.props.keys()].filter(k => component.props.get(k)?.isNode)),
         );
         continue;
       }
       if (!prop.isNode && !prop.isFunction) {
         this.warn(node, `${component.name}.${slot.key} is typed '${prop.type}' — slot value may not fit`);
       }
-      if (slot.value && slot.value.subexpr) {
-        for (const sub of slot.value.subexpr) this.bindAny(sub, node);
+      const sv = slot.value;
+      if (sv && typeof sv === 'object' && 'subexpr' in sv) {
+        for (const sub of sv.subexpr) this.bindAny(sub, node);
       }
-      if (slot.value && slot.value.hint) this.bindHintRef(node, slot.value.hint);
+      if (sv && typeof sv === 'object' && 'hint' in sv) this.bindHintRef(node, sv.hint);
       node.bound.slots.push(slot);
     }
   }
 
+  /** @param {import('./xle-ast').XLENode} node */
   bindHint(node) {
     this.bindHintRef(node, node.hint);
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {import('./xle-ast').Hint | null} hint
+   */
   bindHintRef(node, hint) {
+    if (!hint) return;
     const block = this.blockIndex.get(normalizeBlockKey(hint.name));
     if (block) {
       hint.block = {name: block.dirName, description: block.description, category: block.category};
@@ -308,7 +384,7 @@ export class Validation {
     const nearest = suggest(
       normalizeBlockKey(hint.name),
       [...this.blockIndex.keys()],
-    ).map(k => this.blockIndex.get(k).dirName);
+    ).map(k => this.blockIndex.get(k)?.dirName).filter(/** @returns {d is string} */ (d) => d != null);
     if (this.loose) {
       this.warn(node, `Unknown block '{${hint.name}}' — emitting a TODO placeholder (running with --loose)`);
     } else {
@@ -320,6 +396,11 @@ export class Validation {
     }
   }
 
+  /**
+   * @param {import('./xle-ast').XLENode} node
+   * @param {import('./xle-ast').RegistryComponent} component
+   * @param {import('./xle-ast').XLENode | null} parent
+   */
   checkPairings(node, component, parent) {
     const parentName = parent?.bound?.component?.name ?? parent?.name;
     if (component.name === 'AppShell' && parent) {
@@ -337,11 +418,11 @@ export class Validation {
 /**
  * Validate (and bind) a parsed document in place.
  *
- * @param {{roots: any[], overlays: any[]}} doc
- * @param {object} registry - from buildRegistry()
- * @param {Array<object>} blocks - from template discovery (dirName et al)
+ * @param {import('./xle-ast').XLEDoc} doc
+ * @param {import('./xle-ast').Registry} registry - from buildRegistry()
+ * @param {import('./browser').XLEBlock[]} [blocks] - from template discovery (dirName et al)
  * @param {{loose?: boolean}} [options]
- * @returns {{errors: Array, warnings: Array}}
+ * @returns {{errors: import('./xle-ast').RawIssue[], warnings: import('./xle-ast').RawIssue[]}}
  */
 export function validate(doc, registry, blocks, options = {}) {
   const v = new Validation(registry, blocks, options);

package/lib/xle/xle-ast.d.ts

@@ -0,0 +1,214 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Shared XLE/XLO AST + registry type surface for the .mjs pipeline. */
+
+/** A key=value attribute token. */
+export interface KvAttr {
+  kind: 'kv';
+  key: string;
+  value: XLEValue;
+  raw?: string;
+  line: number;
+  col: number;
+}
+
+/** A bare flag attribute token (e.g. `scroll`). */
+export interface FlagAttr {
+  kind: 'flag';
+  key: string;
+  line: number;
+  col: number;
+}
+
+/** A negated flag attribute token (e.g. `!scroll`). */
+export interface NegAttr {
+  kind: 'neg';
+  key: string;
+  line: number;
+  col: number;
+}
+
+export type Attr = KvAttr | FlagAttr | NegAttr;
+
+/** Parsed `{name +flag :arg}` block hint body. */
+export interface Hint {
+  name: string;
+  flags: string[];
+  arg: string | null;
+  /** Set by the validator when the hint resolves to a known block. */
+  block?: {name: string; description?: string; category?: string};
+}
+
+/** An idref value like `#foo`. */
+export interface IdRef {
+  idref: string;
+}
+
+/** A sub-expression value carrying parsed items. */
+export interface SubExprValue {
+  subexpr: XLEItem[];
+}
+
+/** A hint value nested inside a slot. */
+export interface HintValue {
+  hint: Hint;
+}
+
+/** The value of a slot token. */
+export type SlotValue = string | IdRef | SubExprValue | HintValue | null;
+
+/** A slot token (`@key=...`). */
+export interface Slot {
+  kind: 'slot';
+  key: string;
+  value: SlotValue;
+  line: number;
+  col: number;
+}
+
+/** Any scalar/structured value an attribute or prop can hold. */
+export type XLEValue =
+  | string
+  | number
+  | boolean
+  | IdRef
+  | {subexpr: XLEItem[]}
+  | {hint: Hint}
+  | {__expr: string}
+  | XLEValue[]
+  | {[key: string]: XLEValue};
+
+/** A raw prop entry from a component's `.doc.mjs`. */
+export interface DocProp {
+  name: string;
+  type?: string;
+  required?: boolean;
+}
+
+/** Registry prop metadata. */
+export interface RegistryProp {
+  name: string;
+  type: string;
+  required: boolean;
+  enumValues: Array<string | number> | null;
+  isBoolean: boolean;
+  isFunction: boolean;
+  isNode: boolean;
+}
+
+/** A resolved registry component entry. */
+export interface RegistryComponent {
+  name: string;
+  exportName: string;
+  dirName: string;
+  importPath: string;
+  undocumented?: boolean;
+  props: Map<string, RegistryProp>;
+}
+
+/** The hydrated registry shape used by validate()/expand(). */
+export interface Registry {
+  components: Map<string, RegistryComponent>;
+  aliases: Map<string, string>;
+  componentNames: string[];
+}
+
+/** Binding info attached to a node by the validator. */
+export interface BoundInfo {
+  component: RegistryComponent;
+  props: Map<string, XLEValue>;
+  slots: Slot[];
+  stray: unknown[];
+}
+
+/** A parsed element node. */
+export interface XLENode {
+  kind: 'node';
+  name: string | null;
+  id: string | null;
+  enumMods: string[];
+  payload: string | null;
+  payload2: string | null;
+  attrs: Attr[];
+  slots: Slot[];
+  hint: Hint | null;
+  repeat: number | null;
+  selected: boolean;
+  children: XLEItem[];
+  line: number;
+  col: number;
+  /** Set by validate(); null when the name could not be resolved. */
+  bound?: BoundInfo | null;
+}
+
+/** A parenthesized grouping term. */
+export interface XLEGroup {
+  kind: 'group';
+  repeat: number | null;
+  children: XLEItem[];
+  line: number;
+  col: number;
+}
+
+/** Any AST item: an element node or a group. */
+export type XLEItem = XLENode | XLEGroup;
+
+/** The parsed document. */
+export interface XLEDoc {
+  roots: XLEItem[];
+  overlays: XLEItem[];
+  form: 'compact' | 'outline';
+}
+
+/** A parsed import statement (from splice.mjs). */
+export interface ParsedImport {
+  source: string;
+  isType: boolean;
+  default: string | null;
+  namespace: string | null;
+  named: string[];
+  sideEffect: boolean;
+}
+
+/** A merged import map entry (emitter imports). */
+export interface ImportEntry {
+  named: Set<string>;
+  types: Set<string>;
+  default: string | null;
+  namespace: string | null;
+  sideEffect: boolean;
+}
+
+/** A prepared block module for splicing. */
+export interface PreparedSpliceModule {
+  componentName: string;
+  imports: ParsedImport[];
+  body: string;
+}
+
+/** A prepared block module reference (import or splice mode). */
+export interface BlockModule {
+  mode: 'import' | 'splice';
+  componentName: string;
+  importPath: string;
+  source: string;
+}
+
+/** Emitter emission context. */ export interface EmitContext {
+  inStack?: boolean;
+}
+
+/** A scaffolded useState entry. */
+export interface StateEntry {
+  name: string;
+  setter: string;
+  initial: string;
+}
+
+/** Internal validation issue (pre-formatting). */
+export interface RawIssue {
+  message: string;
+  line?: number;
+  col?: number;
+  suggestions?: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.7",
+  "version": "0.1.8-canary.07362a9",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -32,57 +32,64 @@
   "exports": {
     ".": "./bin/astryx.mjs",
     "./json": {
-      "types": "./src/types/index.d.ts",
-      "import": "./src/lib/parse.mjs"
+      "types": "./types/index.d.ts",
+      "import": "./lib/parse.mjs"
     },
     "./api": {
-      "types": "./src/types/api.d.ts",
-      "import": "./src/api/index.mjs"
+      "types": "./types/api.d.ts",
+      "import": "./api/index.mjs"
     },
     "./config": {
-      "types": "./src/types/config.d.ts",
-      "import": "./src/config.mjs"
+      "types": "./types/config.d.ts",
+      "import": "./authoring/config.mjs"
     },
     "./integration": {
-      "types": "./src/types/integration.d.ts",
-      "import": "./src/integration.mjs"
+      "types": "./types/integration.d.ts",
+      "import": "./authoring/integration.mjs"
     },
     "./doc": {
-      "types": "./src/types/doc.d.ts",
-      "import": "./src/doc.mjs"
+      "types": "./types/doc.d.ts",
+      "import": "./authoring/doc.mjs"
     },
     "./template": {
-      "types": "./src/types/template-api.d.ts",
-      "import": "./src/template.mjs"
+      "types": "./types/template-api.d.ts",
+      "import": "./authoring/template.mjs"
     },
     "./codemod": {
-      "types": "./src/types/codemod.d.ts",
-      "import": "./src/codemod.mjs"
+      "types": "./types/codemod.d.ts",
+      "import": "./authoring/codemod.mjs"
     },
     "./xle": {
-      "types": "./src/lib/xle/browser.d.ts",
-      "import": "./src/lib/xle/browser.mjs"
+      "types": "./lib/xle/browser.d.ts",
+      "import": "./lib/xle/browser.mjs"
     }
   },
   "files": [
     "bin",
-    "src",
+    "api",
+    "cli",
+    "codemods",
+    "authoring",
+    "lib",
+    "utils",
+    "types",
+    "schemas",
+    "scripts/postinstall.mjs",
     "templates",
     "docs",
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
     "commander": "^12.1.0",
     "jiti": "^2.7.0",
     "jscodeshift": "^17.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.1.8-canary.07362a9",
+    "@astryxdesign/core": "0.1.8-canary.07362a9",
+    "@astryxdesign/lab": "0.1.8-canary.07362a9",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.07362a9",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,15 +107,17 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.1.8-canary.07362a9",
+    "@astryxdesign/core": "0.1.8-canary.07362a9",
+    "@astryxdesign/lab": "0.1.8-canary.07362a9",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.07362a9",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
     "typecheck:template-docs": "tsc --project tsconfig.template-docs.json",
-    "typecheck:json-api": "tsc --project tsconfig.json-api.json && tsc --project tsconfig.api-contract.json"
+    "typecheck:json-api": "tsc --project tsconfig.json-api.json && tsc --project tsconfig.api-contract.json",
+    "typecheck:strict": "tsc --project tsconfig.strict.json"
   }
 }