@astryxdesign/cli 0.1.8-canary.0c4d8d7 → 0.1.8-canary.0db5dfd

package/{src/api → api/docs}/docs.mjs

@@ -7,13 +7,17 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {CLI_ROOT} from '../utils/paths.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const DOCS_DIR = path.join(CLI_ROOT, 'docs');
 
+/**
+ * @returns {Record<string, string>}
+ */
 function discoverTopics() {
+  /** @type {Record<string, string>} */
   const topics = {};
   if (!fs.existsSync(DOCS_DIR)) return topics;
   for (const file of fs.readdirSync(DOCS_DIR)) {
@@ -23,6 +27,11 @@ function discoverTopics() {
   return topics;
 }
 
+/**
+ * @param {string} docPath
+ * @param {{lang?: string|null}} [opts]
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
+ */
 async function loadReferenceDocs(docPath, {lang} = {}) {
   const mod = await import(pathToFileURL(docPath).href);
   const docs = mod.docs;
@@ -45,6 +54,7 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   // printed the colour table under a "Spacing" heading (#2182). An overlay may
   // now cover any subset of sections, in any order; sections it does not name
   // keep their base content.
+  /** @type {Map<string, any>} */
   const bySection = new Map();
   for (const ts of translation.sections ?? []) {
     if (ts?.section != null) bySection.set(ts.section, ts);
@@ -53,32 +63,43 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   return {
     ...docs,
     description: translation.description || docs.description,
-    sections: docs.sections.map(section => {
-      const ts = bySection.get(section.title);
-      if (!ts) return section;
-      return {
-        ...section,
-        title: ts.title || section.title,
-        content: section.content.map((block, bi) => {
-          const tb = ts.content?.[bi];
-          if (!tb) return block;
-          if (tb.type === 'prose' && block.type === 'prose') return {...block, text: tb.text};
-          if (tb.type === 'list' && block.type === 'list') return {...block, items: tb.items};
-          return block;
-        }),
-      };
-    }),
+    sections: docs.sections.map(
+      (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ section) => {
+        const ts = bySection.get(section.title);
+        if (!ts) return section;
+        return {
+          ...section,
+          title: ts.title || section.title,
+          content: section.content.map(
+            (
+              /** @type {import('../../../core/src/docs-types').ContentBlock} */ block,
+              /** @type {number} */ bi,
+            ) => {
+              const tb = ts.content?.[bi];
+              if (!tb) return block;
+              if (tb.type === 'prose' && block.type === 'prose') return {...block, text: tb.text};
+              if (tb.type === 'list' && block.type === 'list') return {...block, items: tb.items};
+              return block;
+            },
+          ),
+        };
+      },
+    ),
   };
 }
 
 /**
  * Resolve token-ref blocks by inlining the referenced section's table.
  * This allows section docs to reference token tables without duplicating data.
+ * @param {import('../../types/docs').DocsDetailResponse['data']} docsData
+ * @param {Record<string, string>} topics
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
  */
 async function resolveTokenRefs(docsData, topics) {
   const resolved = {...docsData, sections: [...docsData.sections]};
   for (let si = 0; si < resolved.sections.length; si++) {
     const section = resolved.sections[si];
+    /** @type {import('../../../core/src/docs-types').ContentBlock[]} */
     const newContent = [];
     for (const block of section.content) {
       if (block.type === 'token-ref') {
@@ -90,7 +111,8 @@ async function resolveTokenRefs(docsData, topics) {
         const refMod = await import(pathToFileURL(refPath).href);
         const refDocs = refMod.docs;
         const refSection = refDocs.sections.find(
-          s => s.title.toLowerCase() === block.section.toLowerCase(),
+          (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ s) =>
+            s.title.toLowerCase() === block.section.toLowerCase(),
         );
         if (!refSection) {
           newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});
@@ -125,7 +147,11 @@ async function resolveTokenRefs(docsData, topics) {
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
- * @returns {Promise<{type: string, data: unknown}>}
+ * @returns {Promise<
+ *   import('../../types/docs').DocsListResponse |
+ *   import('../../types/docs').DocsDetailResponse |
+ *   import('../../types/docs').DocsDetailSectionResponse
+ * >}
  */
 export async function docs(topic, section, options = {}) {
   const {lang = null, zh = false, dense = false} = options;
@@ -133,7 +159,7 @@ export async function docs(topic, section, options = {}) {
   const topics = discoverTopics();
 
   if (!topic) {
-    /** @type {Array<import('../types/docs').DocsListEntry>} */
+    /** @type {Array<import('../../types/docs').DocsListEntry>} */
     const entries = [];
     for (const [name, docPath] of Object.entries(topics)) {
       try {

package/{src/api → api/doctor}/doctor.mjs

@@ -24,11 +24,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {createRequire} from 'node:module';
 
-import {MIN_NODE_VERSION, isNodeVersionSupported} from '../lib/node-version.mjs';
-import {CLI_ROOT, findCoreDir} from '../utils/paths.mjs';
-import {detectPackageManager, getCliInvocation} from '../utils/package-manager.mjs';
-import {findConfigPath, Project} from '../lib/project.mjs';
-import {semverCompare} from '../utils/semver.mjs';
+import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../lib/node-version.mjs';
+import {CLI_ROOT, findCoreDir} from '../../utils/paths.mjs';
+import {detectPackageManager, getCliInvocation} from '../../utils/package-manager.mjs';
+import {findConfigPath, Project} from '../../lib/project.mjs';
+import {semverCompare} from '../../utils/semver.mjs';
 
 const _require = createRequire(import.meta.url);
 
@@ -49,7 +49,7 @@ const _require = createRequire(import.meta.url);
  * @typedef {object} DoctorContext
  * @property {string} cwd - Directory to diagnose.
  * @property {string} nodeVersion - Running Node version.
- * @property {string|null} coreDir - Resolved @astryxdesign/core directory, or null.
+ * @property {string|null} coreDir - Resolved core package directory, or null.
  * @property {string|null} configPath - Resolved astryx.config.mjs path, or null.
  * @property {string|null} configTheme - theme value read from config, or null.
  */
@@ -104,6 +104,7 @@ function findNodeModules(startDir) {
  */
 function findThemePackages(cwd) {
   const nm = findNodeModules(cwd);
+  /** @type {Array<{name: string, version: string|null}>} */
   const found = [];
   if (!nm) return found;
   const scopeDir = path.join(nm, '@astryxdesign');
@@ -317,7 +318,7 @@ export async function checkConfig(ctx) {
       id: 'config',
       label: 'astryx.config.mjs',
       status: 'fail',
-      message: `astryx.config.mjs failed to load: ${err.message}`,
+      message: `astryx.config.mjs failed to load: ${/** @type {any} */ (err).message}`,
       fix: 'Fix the syntax/runtime error in astryx.config.mjs so it imports cleanly.',
     };
   }
@@ -490,7 +491,8 @@ export async function runChecks(options = {}) {
   let configTheme = null;
   try {
     const project = await Project.load(cwd);
-    configTheme = project.config?.theme ?? null;
+    configTheme =
+      /** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
   } catch {
     // Best-effort: a missing/invalid config leaves configTheme null.
   }
@@ -504,6 +506,7 @@ export async function runChecks(options = {}) {
     configTheme,
   };
 
+  /** @type {DoctorCheck[]} */
   const checks = [];
   // checkConfig is async; run it in its declared slot (after themes).
   for (const fn of SYNC_CHECKS) {

package/{src/api → api/hook}/hook.mjs

@@ -7,12 +7,12 @@
  * The CLI command handler is a thin wrapper around this function.
  */
 
-import {findCoreDir} from '../utils/paths.mjs';
-import {discoverHooks, findHookDoc, getAllHookNames} from '../lib/hook-discovery.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {findCoreDir} from '../../utils/paths.mjs';
+import {discoverHooks, findHookDoc, getAllHookNames} from '../../lib/hook-discovery.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 /**
  * @param {string} [name]
@@ -72,7 +72,7 @@ export async function hook(name, options = {}) {
           const docPath = findHookDoc(coreDir, hookName);
           if (docPath) {
             try {
-              const docs = await loadDocs(docPath, {zh, lang});
+              const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
               entries.push({
                 name: hookName,
                 description: docs.usage?.description || '',
@@ -94,7 +94,7 @@ export async function hook(name, options = {}) {
           const docPath = findHookDoc(coreDir, hookName);
           if (docPath) {
             try {
-              entries.push(await loadDocs(docPath, {zh, lang}));
+              entries.push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
             } catch {
               entries.push({name: hookName});
             }
@@ -119,7 +119,7 @@ export async function hook(name, options = {}) {
           const docPath = findHookDoc(coreDir, hookName);
           if (docPath) {
             try {
-              const docs = await loadDocs(docPath, {zh, lang});
+              const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
               result[cat].push({
                 name: hookName,
                 description: docs.usage?.description || '',
@@ -145,7 +145,7 @@ export async function hook(name, options = {}) {
           const docPath = findHookDoc(coreDir, hookName);
           if (docPath) {
             try {
-              result[cat].push(await loadDocs(docPath, {zh, lang}));
+              result[cat].push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
             } catch {
               result[cat].push({name: hookName});
             }
@@ -186,7 +186,7 @@ export async function hook(name, options = {}) {
     );
   }
 
-  const docs = await loadDocs(docPath, {zh, lang});
+  const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
 
   if (params) {
     return {type: 'hook.detail.params', data: docs.params || []};

package/{src/api → api}/index.mjs

@@ -19,13 +19,20 @@
  * // { type: 'hook.detail', data: { name: 'useMediaQuery', ... } }
  */
 
-export {component} from './component.mjs';
-export {docs} from './docs.mjs';
-export {blog} from './blog.mjs';
-export {discover} from './discover.mjs';
-export {template} from './template.mjs';
-export {themeAdd, listThemes} from './theme-add.mjs';
-export {hook} from './hook.mjs';
-export {search} from './search.mjs';
-export {doctor} from './doctor.mjs';
+export {component} from './component/component.mjs';
+export {docs} from './docs/docs.mjs';
+export {blog} from './blog/blog.mjs';
+export {discover} from './discover/discover.mjs';
+export {template} from './template/template.mjs';
+export {themeAdd, listThemes} from './theme/theme-add.mjs';
+export {hook} from './hook/hook.mjs';
+export {search} from './search/search.mjs';
+export {build} from './build/build.mjs';
+export {swizzle} from './swizzle/swizzle.mjs';
+export {doctor} from './doctor/doctor.mjs';
+export {layoutExpand, layoutCheck, layoutGrammar} from './layout/layout.mjs';
+export {
+  validateIntegration,
+  summarizeIssues,
+} from './integration/validate-integration.mjs';
 export {AstryxError} from './error.mjs';

package/{src/api → api/integration}/validate-integration.mjs

@@ -28,13 +28,13 @@ import {
   findManifestPaths,
   loadManifestObject,
   resolvePackageDir,
-} from '../lib/integrations.mjs';
-import {discoverIntegrationCodemods} from '../codemods/integration-discovery.mjs';
-import {discoverIntegrationTemplatesForOne} from './template.mjs';
-import * as componentDiscovery from '../lib/component-discovery.mjs';
+} from '../../lib/integrations.mjs';
+import {discoverIntegrationCodemods} from '../../codemods/integration-discovery.mjs';
+import {discoverIntegrationTemplatesForOne} from '../template/template.mjs';
+import * as componentDiscovery from '../../lib/component-discovery.mjs';
 
 /**
- * @typedef {import('../types/integration').AstryxIntegrationIssue} Issue
+ * @typedef {import('../../types/integration').AstryxIntegrationIssue} Issue
  */
 
 /**
@@ -75,7 +75,8 @@ function error(code, message) {
  * @param {Issue[]} issues
  */
 function checkRoots(resolved, issues) {
-  for (const kind of ['components', 'templates', 'codemods']) {
+  const kinds = /** @type {const} */ (['components', 'templates', 'codemods']);
+  for (const kind of kinds) {
     const root = resolved[kind];
     if (root == null) continue;
     if (!fs.existsSync(root)) {
@@ -93,7 +94,7 @@ function checkRoots(resolved, issues) {
  * Validate the integration's codemods via the landed discovery. Discovery is
  * strict (throws on bad export / duplicate id); we convert any throw into an
  * `invalid_codemod` error.
- * @param {object} integration loaded-integration-shaped object
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkCodemods(integration, issues) {
@@ -101,14 +102,14 @@ async function checkCodemods(integration, issues) {
   try {
     await discoverIntegrationCodemods([integration]);
   } catch (err) {
-    issues.push(error('invalid_codemod', err.message));
+    issues.push(error('invalid_codemod', /** @type {any} */ (err).message));
   }
 }
 
 /**
  * Validate the integration's templates via the landed discovery. Per-template
  * problems are reported as `invalid_template` errors.
- * @param {object} integration loaded-integration-shaped object
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkTemplates(integration, issues) {
@@ -119,7 +120,7 @@ async function checkTemplates(integration, issues) {
       issues.push(error('invalid_template', e.message));
     }
   } catch (err) {
-    issues.push(error('invalid_template', err.message));
+    issues.push(error('invalid_template', /** @type {any} */ (err).message));
   }
 }
 
@@ -132,7 +133,7 @@ async function checkTemplates(integration, issues) {
  * `discoverIntegrationComponents` returns ownership records and does not throw
  * on a missing same-stem source — it records `sourcePath: null`. We surface
  * each such record as an `invalid_component` error.
- * @param {object} integration loaded-integration-shaped object
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkComponents(integration, issues) {
@@ -152,13 +153,13 @@ async function checkComponents(integration, issues) {
       }
     }
   } catch (err) {
-    issues.push(error('invalid_component', err.message));
+    issues.push(error('invalid_component', /** @type {any} */ (err).message));
   }
 }
 
 /**
  * Run every contribution validator against a loaded-integration-shaped object.
- * @param {object} integration
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration} integration
  * @param {Issue[]} issues
  */
 async function runContributionChecks(integration, issues) {
@@ -181,7 +182,7 @@ async function runContributionChecks(integration, issues) {
  * contribution checks (roots + codemods/templates/components) because those can
  * regress independently of the manifest (a deleted directory, a broken template).
  *
- * @param {object} loaded loaded-integration-shaped object
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration} loaded loaded-integration-shaped object
  * @returns {Promise<Issue[]>}
  */
 export async function validateLoadedIntegration(loaded) {
@@ -210,6 +211,7 @@ export async function validateLoadedIntegration(loaded) {
 async function validateAtPackageDir(packageDir, identity) {
   /** @type {Issue[]} */
   const issues = [];
+  /** @type {ValidateResult} */
   const result = {
     found: true,
     name: identity.name,
@@ -254,10 +256,11 @@ async function validateAtPackageDir(packageDir, identity) {
       `Integration manifest (${path.basename(manifestFile)})`,
     );
   } catch (err) {
-    issues.push(error('invalid_manifest', err.message));
+    issues.push(error('invalid_manifest', /** @type {any} */ (err).message));
     return result;
   }
 
+  /** @param {string | null | undefined} value */
   const resolveRoot = value =>
     value == null ? undefined : path.resolve(packageDir, value);
 
@@ -300,6 +303,7 @@ export async function validateLocalIntegration(cwd = process.cwd()) {
     return {found: false, issues: []};
   }
 
+  /** @type {{name?: string, version?: string}} */
   let pkg = {};
   try {
     pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
@@ -323,6 +327,7 @@ export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
   const packageDir = resolvePackageDir(spec, cwd);
   const pkgJsonPath = path.join(packageDir, 'package.json');
 
+  /** @type {{name?: string, version?: string}} */
   let pkg;
   try {
     pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
@@ -346,6 +351,34 @@ export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
   });
 }
 
+/**
+ * Unified entry: validate the LOCAL integration (no `pkg`) or an INSTALLED one
+ * (`pkg` given) and return the `integration.validate` envelope. The no-manifest
+ * local case is guidance, not an error — it comes back with `name: null` and no
+ * issues so the CLI can print a hint and stay exit-0.
+ *
+ * This is the seam that keeps the CLI a thin wrapper: the command handler calls
+ * this and only chooses how to render (human vs --json) + the exit code.
+ *
+ * @param {string} [pkg] installed package name; omit to validate the cwd package
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('../../types/validate-integration').ValidateIntegrationResponse>}
+ */
+export async function validateIntegration(pkg, options = {}) {
+  const {cwd = process.cwd()} = options;
+  const result = pkg
+    ? await validateInstalledIntegration(pkg, cwd)
+    : await validateLocalIntegration(cwd);
+  return {
+    type: 'integration.validate',
+    data: {
+      name: result.found ? result.name ?? null : null,
+      version: result.found ? result.version ?? null : null,
+      issues: result.issues,
+    },
+  };
+}
+
 /**
  * Summarize issues by severity.
  * @param {Issue[]} issues

package/{src/api → api/integration}/validate-integration.test.mjs

@@ -24,7 +24,7 @@ let tmpDir;
 // Absolute file:// URL to the codemod helper so codemod modules in the temp
 // package can import createCodemod without node_modules wiring.
 const codemodModuleUrl = pathToFileURL(
-  path.resolve(process.cwd(), 'packages/cli/src/codemod.mjs'),
+  path.resolve(process.cwd(), 'packages/cli/authoring/codemod.mjs'),
 ).href;
 
 beforeEach(() => {

package/{src/api → api/layout}/layout.mjs

@@ -16,16 +16,29 @@
 
 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.mjs';
-import {Project} from '../lib/project.mjs';
+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
@@ -33,8 +46,12 @@ import {Project} from '../lib/project.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);
@@ -44,6 +61,7 @@ async function loadBlocks(cwd) {
   }
   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;
@@ -65,11 +83,17 @@ async function loadBlocks(cwd) {
   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. */
+/**
+ * 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);
@@ -77,11 +101,17 @@ function collectHintNames(doc) {
     }
     if (node.hint?.block) names.add(node.hint.block.name);
     for (const slot of node.slots || []) {
-      if (slot.value?.hint?.block) names.add(slot.value.hint.block.name);
-      (slot.value?.subexpr || []).forEach(visit);
+      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);
@@ -92,24 +122,30 @@ function collectHintNames(doc) {
  * 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, {mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault});
+      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, {mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))});
+      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}`;
@@ -118,11 +154,17 @@ function formatIssue(issue) {
 /**
  * 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 = await buildRegistry({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});
@@ -212,6 +254,9 @@ export async function layoutExpand(expression, options = {}) {
 /**
  * `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;
@@ -233,16 +278,20 @@ export async function layoutCheck(expression, options = {}) {
 /**
  * `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);
+    byTarget.get(target)?.push(alias);
   }
   for (const [target, aliases] of [...byTarget.entries()].sort(([a], [b]) => a.localeCompare(b))) {
     aliasLines.push(`${aliases.join('/')}=${target}`);

package/{src/api → api/layout}/layout.test.mjs

@@ -13,7 +13,7 @@ import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import ts from 'typescript';
 import {layoutExpand, layoutCheck, layoutGrammar} from './layout.mjs';
-import {buildRegistry} from '../lib/xle/registry.mjs';
+import {buildRegistry} from '../../lib/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.