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

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.

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

@@ -33,19 +33,34 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
+import {findCoreDir, CLI_ROOT} from '../../utils/paths.mjs';
 import {
   discoverComponents,
   findComponentReadme,
   resolveImportPath,
-} from '../lib/component-discovery.mjs';
-import {discoverHooks, findHookDoc} from '../lib/hook-discovery.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {discoverTemplates, extractComponents} from './template.mjs';
-import {AstryxError} from './error.mjs';
+} from '../../lib/component-discovery.mjs';
+import {discoverHooks, findHookDoc} from '../../lib/hook-discovery.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {discoverTemplates, extractComponents} from '../template/template.mjs';
+import {AstryxError} from '../error.mjs';
 
 const DOCS_DIR = path.join(CLI_ROOT, 'docs');
 
+/**
+ * A search candidate gathered from one content domain. Extra underscore-
+ * prefixed fields carry domain-specific payload used only by {@link toResult}.
+ * @typedef {object} Candidate
+ * @property {'component'|'hook'|'doc'|'template'} domain
+ * @property {string} name
+ * @property {string[]} [keywords]
+ * @property {string} [description]
+ * @property {string[]} [prose]
+ * @property {string} [_import]
+ * @property {string} [_title]
+ * @property {string} [_displayName]
+ * @property {'page'|'block'} [_kind]
+ */
+
 /**
  * Synonym / intent map: product-language terms an agent is likely to type,
  * expanded to the catalog's vocabulary so oblique queries still rank. Keys and
@@ -72,10 +87,19 @@ const SYNONYMS = {
 
 // Flatten into a token -> Set(expansions) lookup (bidirectional).
 const SYNONYM_INDEX = (() => {
+  /** @type {Map<string, Set<string>>} */
   const idx = new Map();
+  /**
+   * @param {string} a
+   * @param {string} b
+   */
   const add = (a, b) => {
-    if (!idx.has(a)) idx.set(a, new Set());
-    idx.get(a).add(b);
+    let set = idx.get(a);
+    if (!set) {
+      set = new Set();
+      idx.set(a, set);
+    }
+    set.add(b);
   };
   for (const [key, vals] of Object.entries(SYNONYMS)) {
     for (const v of vals) {
@@ -159,6 +183,8 @@ const MIN_TOKEN_SCORE = 50;
 /**
  * Best score for a token against a candidate, fanning out through synonyms
  * (synonym hits are discounted so a direct hit always wins).
+ * @param {string} tok
+ * @param {Candidate} candidate
  * @returns {{score: number, reason: string} | null}
  */
 function bestForToken(tok, candidate) {
@@ -176,6 +202,12 @@ function bestForToken(tok, candidate) {
   return best;
 }
 
+/**
+ * @param {string} term - Lowercased full query.
+ * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
+ * @param {Candidate} candidate
+ * @returns {{score: number, reason: string} | null}
+ */
 export function scoreQuery(term, tokens, candidate) {
   const full = scoreCandidate(term, candidate);
 
@@ -192,6 +224,7 @@ export function scoreQuery(term, tokens, candidate) {
   // strong hits, then reward coverage so candidates matching more terms win.
   let sum = 0;
   let matched = 0;
+  /** @type {string[]} */
   const hitTerms = [];
   for (const tok of tokens) {
     const h = bestForToken(tok, candidate);
@@ -235,6 +268,10 @@ export function scoreQuery(term, tokens, candidate) {
 export function scoreCandidate(term, {name, keywords = [], description = '', prose = []}) {
   let best = 0;
   let reason = '';
+  /**
+   * @param {number} score
+   * @param {string} why
+   */
   const consider = (score, why) => {
     if (score > best) {
       best = score;
@@ -299,7 +336,12 @@ export function scoreCandidate(term, {name, keywords = [], description = '', pro
   return best > 0 ? {score: best, reason} : null;
 }
 
-/** Load a doc module's `docs`/`doc` export, swallowing errors. */
+/**
+ * Load a doc module's `docs`/`doc` export, swallowing errors.
+ * @param {string} docPath
+ * @param {string} [exportName]
+ * @returns {Promise<any>}
+ */
 async function loadModuleDoc(docPath, exportName = 'docs') {
   try {
     const mod = await import(pathToFileURL(docPath).href);
@@ -313,13 +355,16 @@ async function loadModuleDoc(docPath, exportName = 'docs') {
  * Build component candidates: name + keywords + usage/description from the
  * component's .doc.mjs.
  * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
  */
 async function gatherComponents(coreDir) {
   const grouped = discoverComponents(coreDir);
   const names = Object.values(grouped).flat();
+  /** @type {Candidate[]} */
   const candidates = [];
   for (const comp of names) {
     const readme = findComponentReadme(coreDir, comp);
+    /** @type {string[]} */
     let keywords = [];
     let description = '';
     if (readme && readme.endsWith('.doc.mjs')) {
@@ -344,13 +389,16 @@ async function gatherComponents(coreDir) {
  * Build hook candidates: name + keywords + usage/description from the hook's
  * .doc.mjs.
  * @param {string} coreDir
+ * @returns {Promise<Candidate[]>}
  */
 async function gatherHooks(coreDir) {
   const grouped = discoverHooks(coreDir);
   const names = Object.values(grouped).flat();
+  /** @type {Candidate[]} */
   const candidates = [];
   for (const hookName of names) {
     const docPath = findHookDoc(coreDir, hookName);
+    /** @type {string[]} */
     let keywords = [];
     let description = '';
     let importPath = '@astryxdesign/core/hooks';
@@ -373,9 +421,13 @@ async function gatherHooks(coreDir) {
   return candidates;
 }
 
-/** Build doc-topic candidates: topic name + description + section prose. */
+/**
+ * Build doc-topic candidates: topic name + description + section prose.
+ * @returns {Promise<Candidate[]>}
+ */
 async function gatherDocs() {
   if (!fs.existsSync(DOCS_DIR)) return [];
+  /** @type {Candidate[]} */
   const candidates = [];
   for (const file of fs.readdirSync(DOCS_DIR)) {
     const match = file.match(/^([\w-]+)\.doc\.mjs$/);
@@ -383,6 +435,7 @@ async function gatherDocs() {
     const topic = match[1];
     const doc = await loadModuleDoc(path.join(DOCS_DIR, file));
     let description = '';
+    /** @type {string[]} */
     const prose = [];
     if (doc) {
       description = doc.description || '';
@@ -405,7 +458,11 @@ async function gatherDocs() {
   return candidates;
 }
 
-/** Build template candidates (page + block) from the template discovery API. */
+/**
+ * Build template candidates (page + block) from the template discovery API.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
 async function gatherTemplates(cwd) {
   let templates;
   try {
@@ -444,7 +501,7 @@ async function gatherTemplates(cwd) {
  * carries enough to act on it: the domain, name, a one-line description, and
  * the follow-up command (and import path where relevant).
  *
- * @param {object} c - candidate
+ * @param {Candidate} c - candidate
  * @param {number} score
  * @param {string} reason
  */
@@ -522,6 +579,7 @@ export async function search(query, options = {}) {
   }
 
   // Gather candidates from each requested domain in parallel.
+  /** @param {string} d */
   const wants = d => !type || type === d;
   const [components, hooks, docTopics, templates] = await Promise.all([
     wants('component') ? gatherComponents(coreDir) : [],
@@ -543,6 +601,7 @@ export async function search(query, options = {}) {
   }
 
   // Sort by score desc, then domain (stable order), then name.
+  /** @type {Record<string, number>} */
   const domainOrder = {component: 0, hook: 1, doc: 2, template: 3};
   scored.sort(
     (a, b) =>