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

package/{src/lib → lib}/component-format.mjs

@@ -6,6 +6,7 @@
 
 import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 
 /**
  * Derive the `defineTheme` component-override key from a theming target.
@@ -18,15 +19,19 @@ import {loadDocs} from './component-loader.mjs';
  * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
  * (NAMESPACE / classPrefix), the same way build-theme.mjs mirrors it.
  * <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->
+ * @param {import('../../core/src/docs-types').ThemingTarget} target
+ * @returns {string}
  */
 function targetKey(target) {
   return target.className.replace(/^astryx-/, '');
 }
 
+/** @param {string} name @returns {string} */
 function dataAttrForName(name) {
   return `data-${name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`;
 }
 
+/** @param {import('../../core/src/docs-types').ThemingTarget} target @returns {string[]} */
 function getTargetDataAttributes(target) {
   return [
     ...(target.visualProps || []).map(dataAttrForName),
@@ -42,13 +47,17 @@ function getTargetDataAttributes(target) {
  * than the header has columns gets the excess *discarded*, so an unescaped
  * `gap: 0 | 0.5 | ...` silently eats its own Default and Description columns.
  * <!-- SYNC: packages/core/src/Markdown/parser.ts (splits on unescaped pipes) -->
+ * @param {unknown} value
+ * @returns {string}
  */
 export function mdCell(value) {
   return String(value ?? '').replace(/\|/g, '\\|');
 }
 
+/** @param {import('../../core/src/docs-types').PropDoc[]} [props] @returns {string} */
 function formatPropsTable(props) {
   if (!props || props.length === 0) return '';
+  /** @type {string[]} */
   const lines = [];
   lines.push('| Prop | Type | Default | Description |');
   lines.push('|------|------|---------|-------------|');
@@ -71,6 +80,8 @@ function formatPropsTable(props) {
  * and was being printed literally as the string "undefined". Emit the
  * description only when present, and when there are no inline props point the
  * reader at the sub-component's own docs instead of a blank/`undefined` block.
+ * @param {any} comp
+ * @returns {string[]}
  */
 function formatSubComponent(comp) {
   const out = [`### ${comp.name}\n`];
@@ -81,7 +92,7 @@ function formatSubComponent(comp) {
   if (table) {
     out.push(table + '\n');
   } else {
-    out.push(`See \`astryx component ${comp.name}\` for props and usage.\n`);
+    out.push(`See \`${getCliInvocation()} component ${comp.name}\` for props and usage.\n`);
   }
   return out;
 }
@@ -91,6 +102,9 @@ function formatSubComponent(comp) {
  * the visualProps and the variant prop in the component's props list.
  * Returns an array of variant strings from the `variant` prop type,
  * or the variants from target visualProps.
+ * @param {import('../../core/src/docs-types').ThemingTarget} target
+ * @param {any} docs
+ * @returns {string[]}
  */
 function getTargetVariants(target, docs) {
   if (!target.visualProps?.length) return [];
@@ -98,12 +112,12 @@ function getTargetVariants(target, docs) {
   // If variant is a visualProp, try to resolve the actual variant values from props
   if (target.visualProps.includes('variant')) {
     const allProps = docs.props || (docs.components?.[0]?.props) || [];
-    const variantProp = allProps.find(p => p.name === 'variant');
+    const variantProp = allProps.find((/** @type {any} */ p) => p.name === 'variant');
     if (variantProp && variantProp.type.includes('|')) {
       return variantProp.type
         .replace(/['"]/g, '')
         .split('|')
-        .map(v => v.trim())
+        .map((/** @type {string} */ v) => v.trim())
         .filter(Boolean);
     }
   }
@@ -114,6 +128,8 @@ function getTargetVariants(target, docs) {
 
 /**
  * Get the state classes for a theming target from the states field.
+ * @param {import('../../core/src/docs-types').ThemingTarget} target
+ * @returns {string[]}
  */
 function getTargetStates(target) {
   return target.states || [];
@@ -122,13 +138,14 @@ function getTargetStates(target) {
 /**
  * Format the theming targets table, merging in theme variants if available.
  *
- * @param {object} docs - Component doc object
- * @param {object|null} themeData - Resolved theme data with variants
+ * @param {any} docs - Component doc object
+ * @param {any} themeData - Resolved theme data with variants
  * @returns {string} Markdown table
  */
 function formatTargetsTable(docs, themeData) {
   if (!docs.theming?.targets?.length) return '';
 
+  /** @type {string[]} */
   const lines = [];
   lines.push('| Component class | Preferred data attributes | Props | States |');
   lines.push('|-----------------|---------------------------|-------|--------|');
@@ -145,7 +162,7 @@ function formatTargetsTable(docs, themeData) {
     // Build variant display: core variants plain, theme variants with * suffix
     const variantParts = [
       ...coreVariants,
-      ...themeVariants.map(v => `${v}*`),
+      ...themeVariants.map((/** @type {string} */ v) => `${v}*`),
     ];
 
     const variantsStr = variantParts.length > 0 ? variantParts.join(', ') : '—';
@@ -165,12 +182,13 @@ function formatTargetsTable(docs, themeData) {
 /**
  * Format full component docs (default mode, replaces cleanReadme).
  *
- * @param {object} docs - Component doc object
+ * @param {any} docs - Component doc object
  * @param {object} [options] - Options
- * @param {object|null} [options.themeData] - Resolved theme data
+ * @param {any} [options.themeData] - Resolved theme data
  * @param {string|null} [options.importHint] - Import path hint (e.g. '@astryxdesign/core/Button')
  */
 export function formatFull(docs, options = {}) {
+  /** @type {string[]} */
   const sections = [];
 
   sections.push(`# ${docs.name}\n`);
@@ -244,8 +262,8 @@ export function formatFull(docs, options = {}) {
 
       // Note about theme variants if any are present
       if (themeData?.variants) {
-        const componentKeys = docs.theming.targets.map(t => targetKey(t));
-        const hasThemeVariants = componentKeys.some(k => themeData.variants[k]?.length > 0);
+        const componentKeys = docs.theming.targets.map((/** @type {any} */ t) => targetKey(t));
+        const hasThemeVariants = componentKeys.some((/** @type {any} */ k) => themeData.variants[k]?.length > 0);
         if (hasThemeVariants) {
           sections.push(`_\\* = custom variant from ${themeData.name || 'active'} theme_\n`);
         }
@@ -289,7 +307,7 @@ export function formatFull(docs, options = {}) {
 
     // Component CSS vars — split into public (directly settable) and private (set via derived)
     if (docs.theming?.vars?.length) {
-      const publicVars = docs.theming.vars.filter(v => !v.private && !v.derived);
+      const publicVars = docs.theming.vars.filter((/** @type {any} */ v) => !v.private && !v.derived);
 
       if (publicVars.length > 0) {
         sections.push('**Themeable CSS variables** — additional properties that can be overridden in `defineTheme` component overrides.\n');
@@ -308,12 +326,12 @@ export function formatFull(docs, options = {}) {
       if (docs.theming?.derived?.length) {
         const varsKey = docs.theming.targets?.length ? targetKey(docs.theming.targets[0]) : docs.theming.componentKey || '';
         const derivedExamples = docs.theming.derived
-          .filter(d => d.vars?.length)
-          .map(d => `      ${d.property}: '...',`)
+          .filter((/** @type {any} */ d) => d.vars?.length)
+          .map((/** @type {any} */ d) => `      ${d.property}: '...',`)
           .join('\n');
         const expandExamples = docs.theming.derived
-          .filter(d => d.expand === 'container')
-          .map(d => `      ${d.property}: '...',  // expands to container layout tokens`)
+          .filter((/** @type {any} */ d) => d.expand === 'container')
+          .map((/** @type {any} */ d) => `      ${d.property}: '...',  // expands to container layout tokens`)
           .join('\n');
         const allExamples = [derivedExamples, expandExamples].filter(Boolean).join('\n');
         if (allExamples) {
@@ -330,6 +348,10 @@ export function formatFull(docs, options = {}) {
 /**
  * Format compact docs for LLM consumption (replaces extractCompact + ensureImportStatement).
  * Includes: import, best practices, props, theming.
+ * @param {any} docs
+ * @param {string} componentName
+ * @param {string} [importHint]
+ * @returns {string}
  */
 export function formatCompact(docs, componentName, importHint) {
   // Bare name (un-prefix migration P5a): the CLI now presents component names
@@ -338,6 +360,7 @@ export function formatCompact(docs, componentName, importHint) {
     ? componentName.slice(3)
     : componentName;
 
+  /** @type {string[]} */
   const sections = [];
 
   sections.push(`# ${docs.name}\n`);
@@ -345,7 +368,7 @@ export function formatCompact(docs, componentName, importHint) {
   sections.push(desc + '\n');
 
   if (docs.usage?.anatomy?.length) {
-    sections.push('Anatomy: ' + docs.usage.anatomy.map(el => {
+    sections.push('Anatomy: ' + docs.usage.anatomy.map((/** @type {any} */ el) => {
       const req = el.required ? '' : ' (optional)';
       return `${el.name}${req}`;
     }).join(', ') + '\n');
@@ -395,7 +418,7 @@ export function formatCompact(docs, componentName, importHint) {
     propLines.push('| CSS Property | Sets |');
     propLines.push('|-------------|------|');
     for (const d of docs.theming.derived) {
-      const target = d.expand === 'container' ? 'container layout tokens' : (d.vars || []).map(v => `\`${mdCell(v)}\``).join(', ');
+      const target = d.expand === 'container' ? 'container layout tokens' : (d.vars || []).map((/** @type {any} */ v) => `\`${mdCell(v)}\``).join(', ');
       propLines.push(`| \`${mdCell(d.property)}\` | ${target} |`);
     }
     sections.push(propLines.join('\n') + '\n');
@@ -425,12 +448,20 @@ export function formatCompact(docs, componentName, importHint) {
  */
 const SIGNATURE_UNION_MAX_MEMBERS = 8;
 
+/**
+ * @param {any} docs
+ * @param {string} componentName
+ * @param {string} [importHint]
+ * @param {{themeData?: any}} [options]
+ * @returns {string}
+ */
 export function formatBrief(docs, componentName, importHint, options = {}) {
   const displayName = componentName.startsWith('XDS')
     ? componentName.slice(3)
     : componentName;
 
   // Find the right props and examples for this component
+  /** @type {any[]} */
   let props = [];
   let description = docs.usage?.description || docs.description || '';
   let examples = docs.examples || [];
@@ -438,7 +469,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   if ('props' in docs) {
     props = docs.props;
   } else if ('components' in docs) {
-    const entry = docs.components.find(c => c.name === displayName);
+    const entry = docs.components.find((/** @type {any} */ c) => c.name === displayName);
     if (entry) {
       props = entry.props;
       description = entry.description;
@@ -447,7 +478,9 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   }
 
   // Build signature from union-type props
+  /** @type {string[]} */
   const signatureProps = [];
+  /** @type {string[]} */
   const otherProps = [];
 
   for (const prop of props) {
@@ -456,7 +489,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
         ? prop.type
             .replace(/['"]/g, '')
             .split('|')
-            .map(v => v.trim())
+            .map((/** @type {string} */ v) => v.trim())
         : null;
     if (values && values.length <= SIGNATURE_UNION_MAX_MEMBERS) {
       signatureProps.push(`${prop.name}: ${values.join('|')}`);
@@ -468,6 +501,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   }
 
   // Build output
+  /** @type {string[]} */
   const output = [];
 
   // Signature line
@@ -489,8 +523,8 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   // Component vars (if any — only show public vars)
   if (docs.theming?.vars?.length) {
     const varNames = docs.theming.vars
-      .filter(v => !v.derived && !v.private)
-      .map(v => `${v.name} (${v.default})`)
+      .filter((/** @type {any} */ v) => !v.derived && !v.private)
+      .map((/** @type {any} */ v) => `${v.name} (${v.default})`)
       .join(', ');
     if (varNames) {
       output.push(`  Vars: ${varNames}`);
@@ -500,7 +534,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   // Derived properties (if any)
   if (docs.theming?.derived?.length) {
     const derivedNames = docs.theming.derived
-      .map(d => d.expand === 'container' ? `${d.property} → container tokens` : `${d.property} → ${(d.vars || []).join(', ')}`)
+      .map((/** @type {any} */ d) => d.expand === 'container' ? `${d.property} → container tokens` : `${d.property} → ${(d.vars || []).join(', ')}`)
       .join('; ');
     output.push(`  Derived: ${derivedNames}`);
   }
@@ -508,7 +542,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
 // Theme targets (component class, preferred data attrs, props, states) with theme variant merging
   if (docs.theming?.targets?.length) {
     const { themeData = null } = options;
-    const targetParts = docs.theming.targets.map(t => {
+    const targetParts = docs.theming.targets.map((/** @type {any} */ t) => {
       const parts = [t.className];
       const dataAttrs = getTargetDataAttributes(t);
       if (dataAttrs.length) parts.push(`preferred attrs: ${dataAttrs.join(', ')}`);
@@ -517,7 +551,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
       // Merge theme variants
       const componentKey = targetKey(t);
       const themeVars = themeData?.variants?.[componentKey];
-      if (themeVars?.length) parts.push(`theme: ${themeVars.map(v => v + '*').join(', ')}`);
+      if (themeVars?.length) parts.push(`theme: ${themeVars.map((/** @type {any} */ v) => v + '*').join(', ')}`);
       return parts.join(' ');
     });
     output.push(`  Targets: ${targetParts.join(' | ')}`);
@@ -532,7 +566,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   if (examples.length > 0) {
     const code = examples[0].code;
     const codeLine =
-      code.split('\n').find(l => l.trim().startsWith('<XDS')) ||
+      code.split('\n').find((/** @type {string} */ l) => l.trim().startsWith('<XDS')) ||
       code.split('\n')[0];
     output.push(`  ${codeLine.trim()}`);
   }
@@ -542,6 +576,9 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
 
 /**
  * Format only the props tables (replaces extractProps).
+ * @param {any} docs
+ * @param {string} componentName
+ * @returns {string}
  */
 export function formatProps(docs, componentName) {
   if ('props' in docs) {
@@ -549,6 +586,7 @@ export function formatProps(docs, componentName) {
   }
 
   if ('components' in docs) {
+    /** @type {string[]} */
     const sections = [];
     for (const comp of docs.components) {
       sections.push(`### ${comp.name} Props\n`);
@@ -562,9 +600,13 @@ export function formatProps(docs, componentName) {
 
 /**
  * Format brief summaries for ALL components in one output.
+ * @param {string} coreDir
+ * @param {{zh?: boolean, lang?: string, themeData?: any}} [options]
+ * @returns {Promise<string>}
  */
 export async function formatBriefAll(coreDir, {zh = false, lang, themeData = null} = {}) {
   const components = discoverComponents(coreDir);
+  /** @type {string[]} */
   const output = [];
 
   for (const [key, comps] of Object.entries(components)) {

package/{src/lib → lib}/component-loader.mjs

@@ -37,6 +37,7 @@ export async function loadComponentDoc(
   {zh = false, dense = false, lang} = {},
 ) {
   const mod = await importUserModule(docPath);
+  /** @type {any} */
   const authored = mod?.default ?? mod?.docs;
 
   const result = ComponentDocSchema.safeParse(authored);
@@ -52,16 +53,23 @@ export async function loadComponentDoc(
     locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
   if (!translationKey || !mod[translationKey]) return docs;
 
+  /** @type {any} */
   const translation = mod[translationKey];
-  if (translation.props || translation.components?.some(c => c.props)) {
+  if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
     return translation;
   }
   return mergeTranslation(docs, translation);
 }
 
+/**
+ * @param {any} docs
+ * @param {any} translation
+ * @returns {any}
+ */
 export function mergeTranslation(docs, translation) {
   if (!translation) return docs;
 
+  /** @type {any} */
   const merged = {...docs};
 
   // Merge prose into usage
@@ -77,7 +85,7 @@ export function mergeTranslation(docs, translation) {
 
   // Merge prop descriptions for single-component docs
   if (translation.propDescriptions && merged.props) {
-    merged.props = merged.props.map(prop => {
+    merged.props = merged.props.map((/** @type {any} */ prop) => {
       const desc = translation.propDescriptions[prop.name];
       return desc != null ? {...prop, description: desc} : prop;
     });
@@ -88,7 +96,7 @@ export function mergeTranslation(docs, translation) {
   // translation has an entry. Names may include dots (e.g. 'options.isActive');
   // the lookup is keyed by the exact param name.
   if (translation.paramDescriptions && merged.params) {
-    merged.params = merged.params.map(param => {
+    merged.params = merged.params.map((/** @type {any} */ param) => {
       const desc = translation.paramDescriptions[param.name];
       return desc != null ? {...param, description: desc} : param;
     });
@@ -97,7 +105,7 @@ export function mergeTranslation(docs, translation) {
   // Merge hook return descriptions (HookTranslationDoc). Returns are an array
   // of {name, type, description}; override description by name where present.
   if (translation.returnDescriptions && merged.returns) {
-    merged.returns = merged.returns.map(ret => {
+    merged.returns = merged.returns.map((/** @type {any} */ ret) => {
       const desc = translation.returnDescriptions[ret.name];
       return desc != null ? {...ret, description: desc} : ret;
     });
@@ -105,15 +113,15 @@ export function mergeTranslation(docs, translation) {
 
   // Merge sub-component translations
   if (translation.components && merged.components) {
-    merged.components = merged.components.map((comp, i) => {
-      const trans = translation.components.find(t => t.name === comp.name)
+    merged.components = merged.components.map((/** @type {any} */ comp, /** @type {any} */ i) => {
+      const trans = translation.components.find((/** @type {any} */ t) => t.name === comp.name)
         || translation.components[i];
       if (!trans) return comp;
 
       const mergedComp = {...comp};
       if (trans.description) mergedComp.description = trans.description;
       if (trans.propDescriptions && comp.props) {
-        mergedComp.props = comp.props.map(prop => {
+        mergedComp.props = comp.props.map((/** @type {any} */ prop) => {
           const desc = trans.propDescriptions[prop.name];
           return desc != null ? {...prop, description: desc} : prop;
         });
@@ -130,6 +138,9 @@ export function mergeTranslation(docs, translation) {
  * Supports --lang flag: 'zh' for Chinese, 'dense' for compressed format.
  * Also supports legacy --zh and --dense flags.
  * Translations are merged onto the base docs, keeping structure intact.
+ * @param {string} readmePath
+ * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
+ * @returns {Promise<any>}
  */
 export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {}) {
   const mod = await import(pathToFileURL(readmePath).href);
@@ -151,7 +162,7 @@ export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {
   // `isIconOnly`. A reader of the translated docs cannot discover a prop that
   // is not there. Overlay it instead, so an untranslated prop falls back to
   // its English entry. (Same principle as the reference-doc overlays, #2182.)
-  if (translation.props || translation.components?.some(c => c.props)) {
+  if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
     return overlayComponentDoc(docs, translation);
   }
 
@@ -172,11 +183,14 @@ export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {
  * @returns {any} Merged doc with every base prop present.
  */
 function overlayComponentDoc(docs, translation) {
-  /** Merge one prop list: keep base entries and order, translate what's covered. */
+  /** Merge one prop list: keep base entries and order, translate what's covered.
+   * @param {any[] | undefined} baseProps
+   * @param {any[] | undefined} tProps
+   */
   const overlayProps = (baseProps, tProps) => {
     if (!baseProps) return baseProps;
-    const byName = new Map((tProps ?? []).map(p => [p.name, p]));
-    return baseProps.map(prop => {
+    const byName = new Map((tProps ?? []).map((/** @type {any} */ p) => [p.name, p]));
+    return baseProps.map((/** @type {any} */ prop) => {
       const t = byName.get(prop.name);
       // Take the translated text, but never let it drop the prop's contract
       // (type/default/required stay authoritative from the English doc).
@@ -190,9 +204,9 @@ function overlayComponentDoc(docs, translation) {
 
   if (docs.components) {
     const tByName = new Map(
-      (translation.components ?? []).map(c => [c.name, c]),
+      (translation.components ?? []).map((/** @type {any} */ c) => [c.name, c]),
     );
-    merged.components = docs.components.map(base => {
+    merged.components = docs.components.map((/** @type {any} */ base) => {
       const t = tByName.get(base.name);
       if (!t) return base;
       return {...base, ...t, props: overlayProps(base.props, t.props)};

package/{src/lib → lib}/componentDocOverlay.test.mjs

@@ -29,7 +29,6 @@ const CORE_SRC = path.join(
   import.meta.dirname,
   '..',
   '..',
-  '..',
   'core',
   'src',
 );

package/{src/lib → lib}/error-codes.test.mjs

@@ -21,7 +21,7 @@ import {fileURLToPath} from 'node:url';
 import {ERROR_CODES, isErrorCode, allErrorCodes} from './error-codes.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');
 
 function runCli(args, {cwd} = {}) {
   const res = spawnSync('node', [CLI_BIN, ...args], {

package/{src/lib → lib}/hook-discovery.mjs

@@ -15,6 +15,8 @@ const CATEGORY_RE = /(?:^|\n) {0,4}category:\s*['"]([^'"]+)['"]/;
 
 /**
  * Read the `category` field from a hook's .doc.mjs file (synchronous).
+ * @param {string} docPath
+ * @returns {{category: string | null}}
  */
 function readHookMeta(docPath) {
   try {
@@ -31,6 +33,8 @@ function readHookMeta(docPath) {
 /**
  * Extract the hook name from a doc filename.
  * e.g. 'useFocusTrap.doc.mjs' → 'useFocusTrap'
+ * @param {string} fileName
+ * @returns {string}
  */
 function hookNameFromFile(fileName) {
   return fileName.replace('.doc.mjs', '');
@@ -41,6 +45,8 @@ function hookNameFromFile(fileName) {
  * Returns Record<category, hookName[]> similar to discoverComponents.
  * Categories from HookDoc.category: focus, layout, animation, interaction, data, media, streaming
  * Hooks without a category go in 'Other'.
+ * @param {string} coreDir
+ * @returns {Record<string, string[]>}
  */
 export function discoverHooks(coreDir) {
   const srcDir = path.join(coreDir, 'src');
@@ -77,7 +83,7 @@ export function discoverHooks(coreDir) {
   const groups = new Map();
   for (const [hookName, category] of hookCategories) {
     if (!groups.has(category)) groups.set(category, []);
-    groups.get(category).push(hookName);
+    groups.get(category)?.push(hookName);
   }
 
   // Sort members within each group
@@ -103,6 +109,8 @@ export function discoverHooks(coreDir) {
 
 /**
  * Recursively scan a directory for use*.doc.mjs files.
+ * @param {string} dirPath
+ * @param {Map<string, string>} hookCategories
  */
 function scanDirForHookDocs(dirPath, hookCategories) {
   if (!fs.existsSync(dirPath)) return;
@@ -199,6 +207,9 @@ export function findHookDoc(coreDir, name) {
 
 /**
  * Recursively search a directory for a hook doc matching any of the candidate names.
+ * @param {string} dirPath
+ * @param {string[]} candidates
+ * @returns {string | null}
  */
 function searchDirForHookDoc(dirPath, candidates) {
   if (!fs.existsSync(dirPath)) return null;
@@ -221,6 +232,8 @@ function searchDirForHookDoc(dirPath, candidates) {
 
 /**
  * Get all discovered hook names as a flat array (for fuzzy matching).
+ * @param {string} coreDir
+ * @returns {string[]}
  */
 export function getAllHookNames(coreDir) {
   const hooks = discoverHooks(coreDir);

package/{src/lib → lib}/hook-format.mjs

@@ -16,14 +16,16 @@ import {mdCell} from './component-format.mjs';
 /**
  * Build a signature string from hook docs.
  * e.g. 'useFocusTrap(options: UseFocusTrapOptions): { containerRef, focusFirst }'
+ * @param {any} docs
+ * @returns {string}
  */
 function buildSignature(docs) {
   const name = docs.name;
 
   // Build params string — only top-level params (skip options.foo nested params)
-  const topParams = (docs.params || []).filter(p => !p.name.includes('.'));
+  const topParams = (docs.params || []).filter((/** @type {any} */ p) => !p.name.includes('.'));
   const paramStr = topParams
-    .map(p => {
+    .map((/** @type {any} */ p) => {
       const opt = p.required ? '' : '?';
       return `${p.name}${opt}: ${p.type}`;
     })
@@ -37,7 +39,7 @@ function buildSignature(docs) {
   } else if (returns.length === 1 && returns[0].name === 'value') {
     returnStr = returns[0].type;
   } else {
-    returnStr = `{ ${returns.map(r => r.name).join(', ')} }`;
+    returnStr = `{ ${returns.map((/** @type {any} */ r) => r.name).join(', ')} }`;
   }
 
   return `${name}(${paramStr}): ${returnStr}`;
@@ -45,9 +47,12 @@ function buildSignature(docs) {
 
 /**
  * Format a parameters table (matches component props table style).
+ * @param {any[]} [params]
+ * @returns {string}
  */
 function formatParamsTable(params) {
   if (!params || params.length === 0) return '';
+  /** @type {string[]} */
   const lines = [];
   lines.push('| Param | Type | Default | Description |');
   lines.push('|-------|------|---------|-------------|');
@@ -63,9 +68,12 @@ function formatParamsTable(params) {
 
 /**
  * Format a returns table.
+ * @param {any[]} [returns]
+ * @returns {string}
  */
 function formatReturnsTable(returns) {
   if (!returns || returns.length === 0) return '';
+  /** @type {string[]} */
   const lines = [];
   lines.push('| Field | Type | Description |');
   lines.push('|-------|------|-------------|');
@@ -81,8 +89,11 @@ function formatReturnsTable(returns) {
  * Format full hook docs (default mode).
  * Matches component formatFull structure:
  *   # Name, description, anatomy→params, best practices, props→params+returns, theming→related
+ * @param {any} docs
+ * @returns {string}
  */
 export function formatHookFull(docs) {
+  /** @type {string[]} */
   const sections = [];
 
   sections.push(`# ${docs.name}\n`);
@@ -119,8 +130,12 @@ export function formatHookFull(docs) {
  * Format compact hook docs for LLM consumption.
  * Matches component formatCompact structure:
  *   # Name, description, ## Import, ## Best Practices, ## Parameters, ## Returns
+ * @param {any} docs
+ * @param {string} [importPath]
+ * @returns {string}
  */
 export function formatHookCompact(docs, importPath) {
+  /** @type {string[]} */
   const sections = [];
 
   sections.push(`# ${docs.name}\n`);
@@ -159,6 +174,7 @@ export function formatHookCompact(docs, importPath) {
   }
 
   // Related components (compact footer)
+  /** @type {string[]} */
   const relatedParts = [];
   if (docs.relatedComponents?.length) {
     relatedParts.push(`Components: ${docs.relatedComponents.join(', ')}`);
@@ -181,8 +197,11 @@ export function formatHookCompact(docs, importPath) {
  *   signature  ← from 'import/path'
  *   description
  *   key params
+ * @param {any} docs
+ * @returns {string}
  */
 export function formatHookBrief(docs) {
+  /** @type {string[]} */
   const output = [];
 
   // Signature line with import hint (matches component brief)
@@ -204,8 +223,8 @@ export function formatHookBrief(docs) {
 
   // Key params (matches component brief 'prop · prop' line)
   const paramNames = (docs.params || [])
-    .filter(p => !p.name.includes('.'))
-    .map(p => p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name);
+    .filter((/** @type {any} */ p) => !p.name.includes('.'))
+    .map((/** @type {any} */ p) => p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name);
   if (paramNames.length > 0) {
     output.push(`  ${paramNames.join(' \u00b7 ')}`);
   }
@@ -216,9 +235,12 @@ export function formatHookBrief(docs) {
 /**
  * Format brief summaries for ALL hooks in one output.
  * Matches component formatBriefAll: group headers with ##.
+ * @param {string} coreDir
+ * @returns {Promise<string>}
  */
 export async function formatHookBriefAll(coreDir) {
   const hooks = discoverHooks(coreDir);
+  /** @type {string[]} */
   const output = [];
 
   for (const [category, hookNames] of Object.entries(hooks)) {
@@ -243,6 +265,8 @@ export async function formatHookBriefAll(coreDir) {
 
 /**
  * Format only the parameters table (matches component formatProps).
+ * @param {any} docs
+ * @returns {string}
  */
 export function formatHookParams(docs) {
   if (docs.params?.length) {