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

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) {

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 {
@@ -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}/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});