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

package/{src/lib → lib}/integration-warnings.mjs

@@ -19,7 +19,7 @@
  *     ADDS a one-line nudge.
  */
 
-import {validateLoadedIntegration} from '../api/validate-integration.mjs';
+import {validateLoadedIntegration} from '../api/integration/validate-integration.mjs';
 
 /**
  * For each configured (already-loaded) integration, compute its issues using
@@ -28,7 +28,7 @@ import {validateLoadedIntegration} from '../api/validate-integration.mjs';
  *
  *   Warning: <pkg> has N integration issue(s). Run: astryx validate-integration <pkg>
  *
- * @param {Array<object>} loadedIntegrations the Project's loaded integrations
+ * @param {Array<import('./integrations.mjs').LoadedIntegration>} loadedIntegrations the Project's loaded integrations
  * @param {{json?: boolean}} [options]
  * @returns {Promise<void>}
  */

package/{src/lib → lib}/integrations.mjs

@@ -15,6 +15,23 @@ import * as path from 'node:path';
 import {AstryxIntegrationSchema} from './config-schema.mjs';
 import {loadModuleWithSchema, findPresentFiles} from './module-loader.mjs';
 
+/**
+ * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
+ * the package's package.json; the `components`/`templates`/`codemods` roots are
+ * absolute paths resolved from the manifest. The `__`-prefixed fields are
+ * internal bookkeeping used by validate-integration and Project.
+ * @typedef {object} LoadedIntegration
+ * @property {string} name
+ * @property {string} [version]
+ * @property {string} [components]
+ * @property {string} [templates]
+ * @property {string} [codemods]
+ * @property {string} [issuesUrl]
+ * @property {string} __spec
+ * @property {string} __packageDir
+ * @property {string} __manifestFile
+ */
+
 /** Conventional manifest basenames, in load-precedence order. */
 export const MANIFEST_BASENAMES = [
   'astryx.integration.ts',
@@ -85,8 +102,10 @@ function resolveManifestPath(packageDir, spec) {
  *
  * @param {string[]} [specs] package names
  * @param {{cwd?: string}} [options]
+ * @returns {Promise<LoadedIntegration[]>}
  */
 export async function loadIntegrations(specs = [], {cwd = process.cwd()} = {}) {
+  /** @type {LoadedIntegration[]} */
   const integrations = [];
   const seen = new Set();
 
@@ -112,6 +131,7 @@ export async function loadIntegrations(specs = [], {cwd = process.cwd()} = {}) {
       {label: `Integration ${spec}`},
     );
 
+    /** @param {string | null | undefined} value */
     const resolveRoot = value =>
       value == null ? undefined : path.resolve(packageDir, value);
 

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

@@ -5,7 +5,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {Project} from './project.mjs';
 import {loadIntegrations} from './integrations.mjs';
-import {discover} from '../api/discover.mjs';
+import {discover} from '../api/discover/discover.mjs';
 
 let tmpDir;
 let originalCwd;

package/{src/lib → lib}/json-contract.test.mjs

@@ -27,7 +27,7 @@ import {
 } from './json.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI = path.resolve(__dirname, '..', '..', 'bin', 'astryx.mjs');
+const CLI = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
 
 function runCli(args) {
   return spawnSync(process.execPath, [CLI, ...args], {

package/{src/lib → lib}/json-shim.mjs

@@ -65,6 +65,7 @@ function jsonActive() {
 export function buildHelpEnvelope(cmd) {
   // Reconstruct the fully-qualified command name (e.g. "astryx theme build").
   const nameParts = [];
+  /** @type {import('commander').Command | null} */
   let c = cmd;
   while (c) {
     nameParts.unshift(c.name());
@@ -81,7 +82,7 @@ export function buildHelpEnvelope(cmd) {
   });
 
   const subcommands = cmd.commands
-    .filter((s) => !s._hidden)
+    .filter((s) => !(/** @type {any} */ (s))._hidden)
     .map((s) => ({name: s.name(), description: s.description() || ''}));
 
   return {
@@ -102,7 +103,7 @@ export function buildHelpEnvelope(cmd) {
  * for both success and error).
  *
  * @param {string} message
- * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {import('../types/base').Suggestion[]} [suggestions]
  * @param {string} [code] - Stable machine-readable error code (error-codes.mjs).
  */
 function emitJsonError(message, suggestions, code) {
@@ -227,10 +228,14 @@ let Command_outputHelp_patched = false;
  * @param {import('commander').Command} cmd
  */
 function patchOutputHelp(cmd) {
-  if (cmd.__xdsHelpPatched) return;
-  cmd.__xdsHelpPatched = true;
+  // Commander instances are monkeypatched at runtime with an internal
+  // `__xdsHelpPatched` marker and a replacement `outputHelp`, neither of which
+  // is in commander's public types — treat the instance as untyped here.
+  const anyCmd = /** @type {any} */ (cmd);
+  if (anyCmd.__xdsHelpPatched) return;
+  anyCmd.__xdsHelpPatched = true;
   const original = cmd.outputHelp.bind(cmd);
-  cmd.outputHelp = function patchedOutputHelp(contextOptions) {
+  anyCmd.outputHelp = function patchedOutputHelp(/** @type {any} */ contextOptions) {
     if (jsonActive()) {
       if (!process.__xdsJsonHandled) {
         process.__xdsJsonHandled = true;
@@ -254,7 +259,7 @@ function patchPrototype(CommandCtor) {
   if (proto.__xdsHelpPatched) return;
   proto.__xdsHelpPatched = true;
   const original = proto.outputHelp;
-  proto.outputHelp = function patchedProtoOutputHelp(contextOptions) {
+  proto.outputHelp = function patchedProtoOutputHelp(/** @type {any} */ contextOptions) {
     if (jsonActive()) {
       if (!process.__xdsJsonHandled) {
         process.__xdsJsonHandled = true;

package/{src/lib → lib}/json-shim.test.mjs

@@ -25,7 +25,7 @@ import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 
 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) {
   const res = spawnSync('node', [CLI_BIN, ...args], {

package/{src/lib → lib}/json.mjs

@@ -112,10 +112,10 @@ export function jsonOut(type, data, meta) {
  * consumers can branch on it unconditionally.
  *
  * @param {unknown} err
- * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {import('../types/base').Suggestion[]} [suggestions]
  * @param {string} [code] - Explicit stable error code. Overrides any code
  *   carried on a thrown Error.
- * @returns {{apiVersion: number, error: string, code: string, suggestions?: Array<{name: string, reason: string}>}}
+ * @returns {{apiVersion: number, error: string, code: string, suggestions?: import('../types/base').Suggestion[]}}
  */
 export function toErrorEnvelope(err, suggestions, code) {
   const message =
@@ -136,7 +136,7 @@ export function toErrorEnvelope(err, suggestions, code) {
 /**
  * Output a structured JSON error and exit.
  * @param {string} message
- * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {import('../types/base').Suggestion[]} [suggestions]
  * @param {string} [code] - Stable machine-readable error code (error-codes.mjs).
  */
 export function jsonError(message, suggestions, code) {

package/{src/lib → lib}/levenshtein.mjs

@@ -13,8 +13,14 @@
  * @position lib — shared by string-utils.mjs and lib/xle/validate.mjs
  */
 
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
 export function levenshteinDistance(a, b) {
   const m = a.length, n = b.length;
+  /** @type {number[][]} */
   const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
   for (let i = 0; i <= m; i++) dp[i][0] = i;
   for (let j = 0; j <= n; j++) dp[0][j] = j;

package/{src/lib → lib}/manifest.mjs

@@ -50,6 +50,7 @@ export const RESPONSE_TYPES = {
   docs: ['docs.list', 'docs.detail', 'docs.detail.section'],
   discover: ['discover.list', 'discover.detail', 'discover.detail.doc', 'discover.search'],
   search: ['search'],
+  build: ['build.help', 'build.kit'],
   swizzle: ['swizzle.list', 'swizzle.copy'],
   template: [
     'template.list',
@@ -79,6 +80,7 @@ const EXAMPLES = {
   docs: ['astryx docs', 'astryx docs spacing --json'],
   discover: ['astryx discover --json'],
   search: ['astryx search modal --json', 'astryx search button --type component --json'],
+  build: ['astryx build', 'astryx build "analytics dashboard" --json'],
   swizzle: ['astryx swizzle XDSButton'],
   template: ['astryx template --json', 'astryx template dashboard ./src/app'],
   hook: ['astryx hook', 'astryx hook useToggle --json'],
@@ -103,7 +105,7 @@ const EXAMPLES = {
  * option takes a value (boolean vs string), surfaces `choices` and `default`.
  *
  * @param {import('commander').Option} opt
- * @returns {{flag: string, description: string, type: string, choices?: string[], default?: unknown, negate?: boolean}}
+ * @returns {import('../types/manifest').ManifestOption}
  */
 function describeOption(opt) {
   const o = /** @type {any} */ (opt);
@@ -127,7 +129,7 @@ function describeOption(opt) {
 /**
  * Map a Commander positional argument to an arg descriptor.
  * @param {import('commander').Argument} arg
- * @returns {{name: string, required: boolean, variadic: boolean, description: string}}
+ * @returns {import('../types/manifest').ManifestArgument}
  */
 function describeArgument(arg) {
   const a = /** @type {any} */ (arg);
@@ -163,7 +165,7 @@ function fullName(cmd, root) {
  * @param {import('commander').Command} cmd
  * @param {import('commander').Command} root
  * @param {Set<string>} jsonSupported  fully-qualified names that support --json
- * @returns {object | null}  null for hidden/internal commands
+ * @returns {import('../types/manifest').ManifestCommand | null}  null for hidden/internal commands
  */
 function describeCommand(cmd, root, jsonSupported) {
   const name = fullName(cmd, root);
@@ -210,7 +212,7 @@ function describeCommand(cmd, root, jsonSupported) {
  * command entry doesn't repeat them.
  *
  * @param {import('commander').Command} program
- * @returns {Array<object>}
+ * @returns {import('../types/manifest').ManifestOption[]}
  */
 function describeGlobalOptions(program) {
   const opts = (program.options || []).map(describeOption);
@@ -233,7 +235,7 @@ function describeGlobalOptions(program) {
  * @param {object} [opts]
  * @param {Set<string>} [opts.jsonSupported]  the JSON_SUPPORTED allowlist
  * @param {string} [opts.version]  CLI version (defaults to program.version())
- * @returns {object}  the manifest `data` payload (sans envelope)
+ * @returns {import('../types/manifest').CLIManifest}  the manifest `data` payload (sans envelope)
  */
 export function buildManifest(program, opts = {}) {
   const jsonSupported = opts.jsonSupported || new Set();

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

@@ -18,11 +18,11 @@ import {describe, it, expect} from 'vitest';
 import {spawnSync} from 'node:child_process';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {program, JSON_SUPPORTED} from '../index.mjs';
+import {program, JSON_SUPPORTED} from '../cli/index.mjs';
 import {buildManifest, RESPONSE_TYPES} from './manifest.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');
 
 const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
 

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

@@ -21,6 +21,7 @@ import * as fs from 'node:fs';
 import {createJiti} from 'jiti';
 import {formatZodError} from './config-schema.mjs';
 
+/** @type {ReturnType<typeof createJiti> | undefined} */
 let jitiInstance;
 function getJiti() {
   if (!jitiInstance) {

package/{src/lib → lib}/package-scanner.mjs

@@ -6,9 +6,28 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+/**
+ * A discovered documentation package (its package.json declares `astryx.docs`).
+ * @typedef {object} ScannedPackage
+ * @property {string} name
+ * @property {string} [version]
+ * @property {string} [description]
+ * @property {string} [displayName]
+ * @property {string} dir
+ * @property {Record<string, any>} astryx
+ * @property {string} category
+ * @property {string} docsDir
+ * @property {string[]} components
+ */
+
+/**
+ * @param {string} scanDir
+ * @returns {ScannedPackage[]}
+ */
 export function scanDirectory(scanDir) {
   if (!fs.existsSync(scanDir)) return [];
   const entries = fs.readdirSync(scanDir, {withFileTypes: true});
+  /** @type {ScannedPackage[]} */
   const packages = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
@@ -40,7 +59,13 @@ export function scanDirectory(scanDir) {
   return packages;
 }
 
+/**
+ * @param {string[]} packageDirs
+ * @param {ScannedPackage[]} [explicitPackages]
+ * @returns {ScannedPackage[]}
+ */
 export function scanAllPackages(packageDirs, explicitPackages = []) {
+  /** @type {ScannedPackage[]} */
   const all = [];
   const seen = new Set();
 
@@ -62,10 +87,17 @@ export function scanAllPackages(packageDirs, explicitPackages = []) {
   return all;
 }
 
+/**
+ * @param {string} docsDir
+ * @returns {string[]}
+ */
 function discoverDocComponents(docsDir) {
   if (!fs.existsSync(docsDir)) return [];
+  /** @type {string[]} */
   const components = [];
+  /** @param {string} dir */
   function walk(dir) {
+    /** @type {import('node:fs').Dirent[]} */
     let entries;
     try {
       entries = fs.readdirSync(dir, {withFileTypes: true});
@@ -84,6 +116,11 @@ function discoverDocComponents(docsDir) {
   return components.sort();
 }
 
+/**
+ * @param {ScannedPackage[]} packages
+ * @param {string} name
+ * @returns {{pkg: ScannedPackage, docPath: string, componentName: string} | null}
+ */
 export function findComponentInPackages(packages, name) {
   const lower = name.toLowerCase();
   for (const pkg of packages) {
@@ -95,9 +132,19 @@ export function findComponentInPackages(packages, name) {
   return null;
 }
 
+/**
+ * @param {string} docsDir
+ * @param {string} name
+ * @returns {string | null}
+ */
 function findDocFile(docsDir, name) {
   const target = name + '.doc.mjs';
+  /**
+   * @param {string} dir
+   * @returns {string | null}
+   */
   function walk(dir) {
+    /** @type {import('node:fs').Dirent[]} */
     let entries;
     try {
       entries = fs.readdirSync(dir, {withFileTypes: true});

package/{src/lib → lib}/project.mjs

@@ -44,19 +44,42 @@ import {findCoreDir} from '../utils/paths.mjs';
 import {
   discoverTemplates,
   discoverIntegrationTemplatesForOne,
-} from '../api/template.mjs';
+} from '../api/template/template.mjs';
 import {getTransformsBetween} from '../codemods/registry.mjs';
 import {
   discoverIntegrationCodemods,
   selectIntegrationCodemods,
 } from '../codemods/integration-discovery.mjs';
-import {validateLoadedIntegration} from '../api/validate-integration.mjs';
+import {validateLoadedIntegration} from '../api/integration/validate-integration.mjs';
 import {
   InMemoryConfigCache,
   cacheKey,
   configContentHash,
 } from './config-cache.mjs';
 
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ * Reproduces the historical `err?.message ?? String(err)` behavior in a
+ * strict-checkJs-safe way: prefer a non-nullish `.message` (covers Error
+ * instances and error-like objects thrown by integration code), else `String()`.
+ * @param {unknown} err
+ * @returns {string}
+ */
+function errorMessage(err) {
+  const message =
+    err && typeof err === 'object' && 'message' in err
+      ? /** @type {{message: unknown}} */ (err).message
+      : undefined;
+  return message == null ? String(err) : String(message);
+}
+
+/**
+ * An integration issue tagged with the owner package. The base
+ * {@link import('../types/integration').AstryxIntegrationIssue} fields plus the
+ * `package` that produced it, which Project tracks for routing/dedup.
+ * @typedef {import('../types/integration').AstryxIntegrationIssue & {package: string}} ProjectIntegrationIssue
+ */
+
 /** Conventional config basenames, in load-precedence order. */
 export const CONFIG_BASENAMES = [
   'astryx.config.ts',
@@ -117,13 +140,13 @@ export class Project {
   #config;
   /** @type {string[]} */
   #integrations;
-  /** @type {Array<object>} */
+  /** @type {import('./integrations.mjs').LoadedIntegration[]} */
   #loadedIntegrations;
   /** @type {import('./config-cache.mjs').ConfigCache} */
   #cache;
   /** @type {string} */
   #hash;
-  /** @type {import('../types/integration').AstryxIntegrationIssue[]} */
+  /** @type {ProjectIntegrationIssue[]} */
   #issues = [];
   /**
    * Package names of integrations whose issues have already been collected
@@ -137,9 +160,9 @@ export class Project {
    * @param {object} init
    * @param {string} init.cwd
    * @param {string|null} init.configPath
-   * @param {object} init.config validated AstryxConfig surface
+   * @param {import('../types/config').AstryxConfig} init.config validated AstryxConfig surface
    * @param {string[]} init.integrations
-   * @param {Array<object>} init.loadedIntegrations
+   * @param {import('./integrations.mjs').LoadedIntegration[]} init.loadedIntegrations
    * @param {import('./config-cache.mjs').ConfigCache} init.cache
    * @param {string} init.hash config content hash
    */
@@ -175,8 +198,11 @@ export class Project {
     const configPath = findConfigPath(cwd);
     const hash = configContentHash(configPath);
 
+    /** @type {import('../types/config').AstryxConfig} */
     let config = {integrations: []};
+    /** @type {string[]} */
     let integrations = [];
+    /** @type {import('./integrations.mjs').LoadedIntegration[]} */
     let loadedIntegrations = [];
 
     if (configPath) {
@@ -204,7 +230,7 @@ export class Project {
   /**
    * The validated config surface (same data loadConfig returned, minus the
    * resolved `loadedIntegrations` which is exposed separately).
-   * @returns {{integrations?: string[], issuesUrl?: string, hooks?: object, experimental?: object}}
+   * @returns {import('../types/config').AstryxConfig}
    */
   get config() {
     return this.#config;
@@ -215,7 +241,7 @@ export class Project {
     return this.#integrations;
   }
 
-  /** Resolved loaded integrations (lib/integrations.mjs shape). @returns {Array<object>} */
+  /** Resolved loaded integrations (lib/integrations.mjs shape). @returns {import('./integrations.mjs').LoadedIntegration[]} */
   get loadedIntegrations() {
     return this.#loadedIntegrations;
   }
@@ -245,7 +271,7 @@ export class Project {
    */
   async #memo(kind, produce) {
     const key = cacheKey(this.#hash, this.#cwd, kind);
-    const hit = this.#cache.get(key);
+    const hit = /** @type {{value: T} | undefined} */ (this.#cache.get(key));
     if (hit !== undefined) return hit.value;
     const value = await produce();
     this.#cache.set(key, {value});
@@ -272,7 +298,10 @@ export class Project {
     });
   }
 
-  /** Package label for a loaded integration. */
+  /** Package label for a loaded integration.
+   * @param {import('./integrations.mjs').LoadedIntegration} integration
+   * @returns {string}
+   */
   #pkgLabel(integration) {
     return integration?.name ?? integration?.__spec ?? '(integration)';
   }
@@ -281,7 +310,7 @@ export class Project {
    * Validate one loaded integration and collect any issues. Marks the
    * integration visited so issues() won't redo the work. Best-effort: a
    * validator throwing is itself recorded as an issue, never propagated.
-   * @param {object} integration
+   * @param {import('./integrations.mjs').LoadedIntegration} integration
    */
   async #collectIssues(integration) {
     const pkg = this.#pkgLabel(integration);
@@ -294,7 +323,7 @@ export class Project {
       this.#pushIssue(pkg, {
         code: 'integration_error',
         severity: 'error',
-        message: err?.message ?? String(err),
+        message: errorMessage(err),
       });
     }
   }
@@ -311,7 +340,7 @@ export class Project {
   async components() {
     return this.#memo('components', async () => {
       const coreDir = findCoreDir(this.#cwd);
-      /** @type {Array<object>} */
+      /** @type {Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>} */
       const records = [];
 
       // Core records (no integrations) — never integration-broken.
@@ -343,7 +372,7 @@ export class Project {
           this.#pushIssue(pkg, {
             code: 'invalid_component',
             severity: 'error',
-            message: err?.message ?? String(err),
+            message: errorMessage(err),
           });
         }
       }
@@ -362,7 +391,7 @@ export class Project {
    */
   async templates() {
     return this.#memo('templates', async () => {
-      /** @type {Array<object>} */
+      /** @type {any[]} */
       const templates = [];
 
       // Core + external-package templates (discoverTemplates internally also
@@ -371,7 +400,7 @@ export class Project {
       // path so the skip+warn policy and issue collection apply, then dedupe).
       try {
         const core = await discoverTemplates(this.#cwd);
-        for (const t of core) {
+        for (const t of /** @type {any[]} */ (core)) {
           // Skip integration-owned templates here; they are re-added (and
           // issue-collected) per integration below to honor skip+warn.
           if (t.package && t.package !== CORE_PACKAGE) continue;
@@ -405,7 +434,7 @@ export class Project {
           this.#pushIssue(pkg, {
             code: 'invalid_template',
             severity: 'error',
-            message: err?.message ?? String(err),
+            message: errorMessage(err),
           });
         }
       }
@@ -431,6 +460,7 @@ export class Project {
 
       // Discover integration codemods per integration so a single broken
       // integration is skipped (issue collected) without losing the others.
+      /** @type {import('./integrations.mjs').LoadedIntegration[]} */
       const good = [];
       for (const integration of this.#loadedIntegrations) {
         await this.#collectIssues(integration);
@@ -449,7 +479,7 @@ export class Project {
           this.#pushIssue(pkg, {
             code: 'invalid_codemod',
             severity: 'error',
-            message: err?.message ?? String(err),
+            message: errorMessage(err),
           });
         }
       }

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

@@ -13,7 +13,7 @@ let originalCwd;
 
 const codemodModulePath = path.resolve(
   process.cwd(),
-  'packages/cli/src/codemod.mjs',
+  'packages/cli/authoring/codemod.mjs',
 );
 const codemodModuleUrl = pathToFileURL(codemodModulePath).href;
 

package/{src/lib → lib}/resolve-theme.mjs

@@ -25,6 +25,9 @@ const _require = createRequire(import.meta.url);
 /**
  * Try to load a module, returning the default export or the module itself.
  * Returns null if the module cannot be found.
+ * @param {string} specifier
+ * @param {string} cwd
+ * @returns {unknown}
  */
 function tryLoadModule(specifier, cwd) {
   // For relative/absolute paths, resolve against cwd
@@ -49,6 +52,8 @@ function tryLoadModule(specifier, cwd) {
  * Extract theme data from a loaded module.
  * Handles both `module.default` and direct `module` patterns,
  * as well as named exports like `module.theme` or `module.{name}Theme`.
+ * @param {any} mod
+ * @returns {any}
  */
 function extractTheme(mod) {
   if (!mod || typeof mod !== 'object') return null;

package/{src/lib → lib}/string-utils.mjs

@@ -13,6 +13,10 @@ export {levenshteinDistance} from './levenshtein.mjs';
 /**
  * Find the closest component names to a given (possibly misspelled) name.
  * Returns matches sorted by distance, filtered to maxDistance.
+ * @param {string} name
+ * @param {Record<string, string[]>} components
+ * @param {number} [maxDistance]
+ * @returns {{name: string, distance: number}[]}
  */
 export function findClosestComponents(name, components, maxDistance = 3) {
   const allNames = Object.values(components).flat();
@@ -45,6 +49,11 @@ export function findClosestComponents(name, components, maxDistance = 3) {
  *    20  name Levenshtein distance 3
  *
  * Each result: { name, score, reason }
+ *
+ * @param {string} needle
+ * @param {string} coreDir
+ * @param {Record<string, string[]>} components
+ * @returns {Promise<{name: string, score: number, reason: string}[]>}
  */
 export async function searchComponents(needle, coreDir, components) {
   const {pathToFileURL} = await import('node:url');
@@ -53,8 +62,14 @@ export async function searchComponents(needle, coreDir, components) {
 
   const term = needle.toLowerCase();
   const allNames = Object.values(components).flat();
+  /** @type {Map<string, {name: string, score: number, reason: string}>} */
   const scored = new Map();
 
+  /**
+   * @param {string} name
+   * @param {number} score
+   * @param {string} reason
+   */
   function addMatch(name, score, reason) {
     const existing = scored.get(name);
     if (!existing || score > existing.score) {