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

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

@@ -10,9 +10,9 @@
  * blog's structure can change freely without touching the CLI.
  */
 
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {SITE_URL, SITE_ORIGIN} from '../lib/site.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {SITE_URL, SITE_ORIGIN} from '../../lib/site.mjs';
 
 /** Abort a feed/post fetch that hangs, and cap how much we'll read. */
 const FETCH_TIMEOUT_MS = 15000;
@@ -20,6 +20,10 @@ const MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a blog feed is never larger.
 
 const FEED_URL = new URL('/rss.xml', SITE_URL).toString();
 
+/**
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
 async function fetchText(url) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
@@ -31,7 +35,12 @@ async function fetchText(url) {
     });
   } catch (e) {
     clearTimeout(timer);
-    const reason = e.name === 'AbortError' ? 'timed out' : e.message;
+    const reason =
+      e instanceof Error
+        ? e.name === 'AbortError'
+          ? 'timed out'
+          : e.message
+        : String(e);
     throw new AstryxError(
       `Could not reach ${url}: ${reason}`,
       [],
@@ -61,6 +70,7 @@ async function fetchText(url) {
  * Defense in depth: a post's plaintext URL comes from feed content. Require it
  * to live on the canonical origin so even a tampered feed can't redirect the
  * CLI to another host.
+ * @param {string} target
  */
 function assertCanonicalOrigin(target) {
   let targetOrigin;
@@ -82,6 +92,10 @@ function assertCanonicalOrigin(target) {
   }
 }
 
+/**
+ * @param {string} value
+ * @returns {string}
+ */
 function unescapeXml(value) {
   return value
     .replace(/&lt;/g, '<')
@@ -91,12 +105,23 @@ function unescapeXml(value) {
     .replace(/&amp;/g, '&');
 }
 
+/**
+ * @param {string} item
+ * @param {string} name
+ * @returns {string}
+ */
 function tag(item, name) {
   const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
   return m ? unescapeXml(m[1].trim()) : '';
 }
 
+/**
+ * @param {string} item
+ * @param {string} name
+ * @returns {string[]}
+ */
 function tagAll(item, name) {
+  /** @type {string[]} */
   const out = [];
   const re = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, 'g');
   let m;
@@ -104,7 +129,11 @@ function tagAll(item, name) {
   return out;
 }
 
-/** Extract the plaintext alternate href from an <item>. */
+/**
+ * Extract the plaintext alternate href from an <item>.
+ * @param {string} item
+ * @returns {string | null}
+ */
 function textHref(item) {
   // Match the atom:link alternate regardless of attribute order/quoting; then
   // confirm it's the text/plain alternate before trusting the href.
@@ -121,7 +150,11 @@ function textHref(item) {
   return null;
 }
 
-/** Derive a slug from a post link (last path segment). */
+/**
+ * Derive a slug from a post link (last path segment).
+ * @param {string} link
+ * @returns {string}
+ */
 function slugFromLink(link) {
   try {
     const path = new URL(link).pathname.replace(/\/$/, '');
@@ -131,6 +164,9 @@ function slugFromLink(link) {
   }
 }
 
+/**
+ * @param {string} xml
+ */
 function parseFeed(xml) {
   const items = [];
   const re = /<item>([\s\S]*?)<\/item>/g;

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

@@ -9,8 +9,8 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {blog} from './blog.mjs';
-import {AstryxError} from './error.mjs';
-import {SITE_URL} from '../lib/site.mjs';
+import {AstryxError} from '../error.mjs';
+import {SITE_URL} from '../../lib/site.mjs';
 
 const FEED = `<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">

package/api/build/build.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build API — the "assemble a page" assistant, as data.
+ *
+ * `build()` with no query signals the workflow playbook (`build.help`). With a
+ * query it runs the unified search and groups the results into a composition
+ * KIT (`build.kit`): the closest page templates, the blocks that cover parts,
+ * and the domain components to fill gaps, plus the always-on frame + foundation.
+ *
+ * The kit carries RAW `SearchResultEntry` objects and static name arrays only —
+ * never pre-formatted command strings. All CLI prefixing (formatCliCommand /
+ * getCliInvocation) and the section prose live in the command renderer, so the
+ * JSON shape stays package-manager-agnostic and stable across environments.
+ */
+
+import {search} from '../search/search.mjs';
+
+/** A page at/above this score is a confident direct match. */
+const PAGE_DIRECT = 95;
+/** Below this a page is too weak to offer even as a layout reference. */
+const PAGE_FLOOR = 50;
+/** Below this a block/domain-component match is incidental noise. */
+const DOMAIN_FLOOR = 55;
+
+/**
+ * Always-surfaced primitives. Every page needs a shell + layout/typography/
+ * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
+ * so search alone never returns them. Kept here (not the renderer) because they
+ * are ALSO used to exclude these names from the idea-specific `domain` group.
+ */
+const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
+const FOUNDATION = [
+  'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
+  'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
+];
+const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+
+/**
+ * The page-building assistant. No query → the playbook signal; a query → the
+ * grouped composition kit.
+ *
+ * @param {string} [query] what you're building (e.g. "analytics dashboard")
+ * @param {{cwd?: string, type?: import('../../types/search').SearchDomain, limit?: number}} [options]
+ * @returns {Promise<import('../../types/build').BuildHelpResponse | import('../../types/build').BuildKitResponse>}
+ */
+export async function build(query, options = {}) {
+  if (!query || !String(query).trim()) {
+    return {type: 'build.help', data: {playbook: true}};
+  }
+
+  const {cwd = process.cwd(), type, limit = 60} = options;
+  // search()'s JSDoc @returns widens results to object[]; the SearchResponse
+  // shape is the contract (api.d.ts). Cast locally rather than tightening the
+  // search @returns (a separate follow-up).
+  const result = /** @type {import('../../types/search').SearchResponse} */ (
+    await search(query, {cwd, type, limit})
+  );
+  const results = result.data.results;
+
+  const pages = results
+    .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
+    .slice(0, 3);
+  const blocks = results
+    .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
+    .slice(0, 5);
+  const domain = results
+    .filter(
+      r =>
+        (r.domain === 'component' || r.domain === 'hook') &&
+        r.score >= DOMAIN_FLOOR &&
+        !ALWAYS.has(r.name),
+    )
+    .slice(0, 6);
+  const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
+
+  return {
+    type: 'build.kit',
+    data: {
+      query: result.data.query,
+      // Distinguishes "search found nothing" (renderer shows "No matches")
+      // from a weak-but-non-empty result set (renderer still shows the kit).
+      hasResults: results.length > 0,
+      directMatch,
+      pages,
+      blocks,
+      domain,
+      frame: FRAME,
+      foundation: FOUNDATION,
+    },
+  };
+}

package/api/build/build.test.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the build API (playbook signal + composition kit).
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {build} from './build.mjs';
+
+// api/build/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+// build() delegates to search(), whose first (cold) call is slow under vitest.
+vi.setConfig({testTimeout: 30000});
+
+describe('build API', () => {
+  it('no query → build.help playbook signal', async () => {
+    const r = await build();
+    expect(r.type).toBe('build.help');
+    expect(r.data).toEqual({playbook: true});
+  });
+
+  it('query → build.kit with raw entries + static frame/foundation', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.query).toBe('dashboard');
+    expect(r.data.hasResults).toBe(true);
+    expect(r.data.frame).toContain('AppShell');
+    expect(r.data.foundation).toContain('Button');
+    expect(Array.isArray(r.data.pages)).toBe(true);
+
+    // Entries are RAW SearchResultEntry objects — never package-manager-prefixed
+    // command strings (that formatting is the CLI renderer's job).
+    for (const e of [...r.data.pages, ...r.data.blocks, ...r.data.domain]) {
+      expect(typeof e.name).toBe('string');
+      expect(typeof e.score).toBe('number');
+      expect(e.command).not.toMatch(/^(pnpm|npm|yarn|bun|npx)\b/);
+    }
+  });
+
+  it('excludes always-on frame/foundation names from the domain group', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error('expected build.kit');
+    const names = r.data.domain.map(d => d.name);
+    expect(names).not.toContain('Button');
+    expect(names).not.toContain('AppShell');
+  });
+
+  it('applies grouping caps, score floors, and directMatch threshold', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error('expected build.kit');
+    const {pages, blocks, domain, directMatch} = r.data;
+
+    // Caps: pages ≤ 3, blocks ≤ 5, domain ≤ 6.
+    expect(pages.length).toBeLessThanOrEqual(3);
+    expect(blocks.length).toBeLessThanOrEqual(5);
+    expect(domain.length).toBeLessThanOrEqual(6);
+
+    // Score floors: pages ≥ PAGE_FLOOR(50); blocks/domain ≥ DOMAIN_FLOOR(55).
+    for (const p of pages) expect(p.score).toBeGreaterThanOrEqual(50);
+    for (const b of blocks) expect(b.score).toBeGreaterThanOrEqual(55);
+    for (const d of domain) expect(d.score).toBeGreaterThanOrEqual(55);
+
+    // directMatch iff the top page is a confident match (PAGE_DIRECT = 95).
+    expect(directMatch).toBe(pages.length > 0 && pages[0].score >= 95);
+
+    // Domain partitioning: pages = non-block templates, blocks = block templates,
+    // domain = components/hooks.
+    for (const p of pages) {
+      expect(p.domain).toBe('template');
+      expect(p.kind).not.toBe('block');
+    }
+    for (const b of blocks) {
+      expect(b.domain).toBe('template');
+      expect(b.kind).toBe('block');
+    }
+    for (const d of domain) expect(['component', 'hook']).toContain(d.domain);
+  });
+
+  it('no matches → build.kit with hasResults=false and empty groups', async () => {
+    const r = await build('zzznomatch99', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.hasResults).toBe(false);
+    expect(r.data.pages).toHaveLength(0);
+    expect(r.data.blocks).toHaveLength(0);
+    expect(r.data.domain).toHaveLength(0);
+  });
+});

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

@@ -9,8 +9,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {findCoreDir, discoverExternalPackages} from '../utils/paths.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {findCoreDir, discoverExternalPackages} from '../../utils/paths.mjs';
 import {
   CORE_PACKAGE,
   discoverComponents,
@@ -22,24 +22,46 @@ import {
   findIntegrationComponentDoc,
   findIntegrationComponentSource,
   resolveImportPath,
-} from '../lib/component-discovery.mjs';
-import {Project} from '../lib/project.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {searchComponents} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {findShowcase, findRelatedBlocks} from './template.mjs';
+} from '../../lib/component-discovery.mjs';
+import {Project} from '../../lib/project.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {searchComponents} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {findShowcase, findRelatedBlocks} from '../template/template.mjs';
+
+/**
+ * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
+ * which is either a single-component or multi-component doc; this loose view
+ * captures the fields the API reads across both forms.
+ * @typedef {object} LoadedComponentDoc
+ * @property {string} [name]
+ * @property {string} [description]
+ * @property {any[]} [props]
+ * @property {any[]} [components]
+ * @property {{description?: string}} [usage]
+ * @property {any} [theming]
+ */
+
+/**
+ * Options object for `loadDocs`, matching its declared parameter shape (used
+ * as a cast target so `lang` (which the API may hold as `string|null`) type
+ * checks against `loadDocs`'s `lang?: string`).
+ * @typedef {{zh?: boolean, dense?: boolean, lang?: string}} LoadDocsOpts
+ */
 
 /**
  * Load the configured integrations for `cwd`, swallowing any config errors so
  * component discovery never hard-fails on a malformed/absent integration. An
  * empty list means "core only".
  * @param {string} cwd
- * @returns {Promise<Array<{name: string, components?: string, issuesUrl?: string}>>}
+ * @returns {Promise<import('../../lib/integrations.mjs').LoadedIntegration[]>}
  */
 async function loadIntegrationsSafely(cwd) {
   try {
     const project = await Project.load(cwd);
-    return project.loadedIntegrations;
+    return /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
+      project.loadedIntegrations
+    );
   } catch {
     return [];
   }
@@ -47,7 +69,7 @@ async function loadIntegrationsSafely(cwd) {
 
 /**
  * Resolve a loaded integration by package name.
- * @param {Array<{name: string}>} loadedIntegrations
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration[]} loadedIntegrations
  * @param {string} packageName
  */
 function findLoadedIntegration(loadedIntegrations, packageName) {
@@ -133,7 +155,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              const docs = await loadDocs(readme, {zh, lang});
+              const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang})));
               entries.push({name: comp, description: docs.usage?.description || docs.description || '', import: resolveImportPath(coreDir, comp)});
             } catch {
               entries.push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});
@@ -151,7 +173,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              entries.push(await loadDocs(readme, {zh, lang, dense}));
+              entries.push(await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang, dense})));
             } catch {
               entries.push({name: `XDS${comp}`, description: ''});
             }
@@ -173,7 +195,7 @@ export async function component(name, options = {}) {
 
     // All components — merge core + external packages with grouped subcategories
     if (detail === 'compact') {
-      /** @type {Record<string, Array<import('../types/component').ComponentBriefEntry>>} */
+      /** @type {Record<string, Array<import('../../types/component').ComponentBriefEntry>>} */
       const result = {};
       for (const [cat, comps] of Object.entries(components)) {
         result[cat] = [];
@@ -181,7 +203,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              const docs = await loadDocs(readme, {zh, lang});
+              const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang})));
               result[cat].push({name: comp, description: docs.usage?.description || docs.description || '', import: resolveImportPath(coreDir, comp)});
             } catch {
               result[cat].push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});
@@ -203,7 +225,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              result[cat].push(await loadDocs(readme, {zh, lang, dense}));
+              result[cat].push(await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang, dense})));
             } catch {
               result[cat].push({name: `XDS${comp}`, description: ''});
             }
@@ -238,7 +260,7 @@ export async function component(name, options = {}) {
         const groupLabel = rec.group ?? integration.name;
         const key = `${groupLabel} (${integration.name})`;
         if (!byGroup.has(key)) byGroup.set(key, []);
-        byGroup.get(key).push({name: rec.name, package: integration.name});
+        byGroup.get(key)?.push({name: rec.name, package: integration.name});
       }
       for (const [key, members] of byGroup) {
         members.sort((a, b) => a.name.localeCompare(b.name));
@@ -334,14 +356,14 @@ export async function component(name, options = {}) {
    * `package`, the resolved `import` specifier, and `sourceAvailable` (whether
    * a swizzleable source file exists for the owner). Existing doc fields
    * (name, usage, props, …) are preserved.
-   * @param {object} docs
+   * @param {LoadedComponentDoc} docs
    * @param {{package: string, sourcePath: string|null}} owner
    * @param {string} componentName
    */
   function withOwnership(docs, owner, componentName) {
     const importSpec =
       owner.package === CORE_PACKAGE
-        ? resolveImportPath(coreDir, componentName)
+        ? resolveImportPath(/** @type {string} */ (coreDir), componentName)
         : `${owner.package}/${componentName}`;
     return {
       ...docs,
@@ -368,7 +390,7 @@ export async function component(name, options = {}) {
         }
         return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
       }
-      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
         return {type: 'component.detail.props', data: p};
@@ -389,7 +411,7 @@ export async function component(name, options = {}) {
         }
         return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
       }
-      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
         return {type: 'component.detail.props', data: p};
@@ -420,7 +442,7 @@ export async function component(name, options = {}) {
 
     const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);
     if (extDocPath && extDocPath.endsWith('.doc.mjs')) {
-      const docs = await loadDocs(extDocPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(extDocPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
 
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
@@ -461,7 +483,7 @@ export async function component(name, options = {}) {
     if (showcase) {
       throw new AstryxError(`No showcase found for "${name}"`, undefined, ERROR_CODES.ERR_NO_SHOWCASE);
     }
-    const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+    const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
     if (props) {
       const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
       return {type: 'component.detail.props', data: p};
@@ -546,12 +568,12 @@ export async function component(name, options = {}) {
     throw new AstryxError(`No .doc.mjs found for "${resolvedName}". The component needs a typed doc file.`, undefined, ERROR_CODES.ERR_NO_DOC);
   }
 
-  const docs = await loadDocs(readmePath, {zh, dense, lang});
+  const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readmePath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
 
   // ── Blocks mode ──────────────────────────────────────────────
   if (blocks) {
     const allBlocks = await findRelatedBlocks(dirName);
-    const toEntry = (b) => ({
+    const toEntry = (/** @type {any} */ b) => ({
       name: b.dirName,
       displayName: b.name,
       description: b.description,
@@ -561,7 +583,7 @@ export async function component(name, options = {}) {
 
     // Examples: blocks in the component's own directory, or
     // componentsUsed match for sub-components without a directory.
-    const ownDir = allBlocks.filter(b => path.basename(b.category) === dirName);
+    const ownDir = allBlocks.filter((/** @type {any} */ b) => path.basename(b.category) === dirName);
     const examples = ownDir.length > 0
       ? ownDir
       : allBlocks.filter(b => b.componentsUsed?.some(c => c === dirName));
@@ -595,6 +617,7 @@ export async function component(name, options = {}) {
     : null;
 
   if (matchingComponent) {
+    /** @type {LoadedComponentDoc & {parentDoc?: string, import?: string}} */
     const scoped = {
       name: dirName,
       description: matchingComponent.description,

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

@@ -4,28 +4,37 @@
  * @file Programmatic API for the discover command.
  */
 
-import {Project} from '../lib/project.mjs';
+import {Project} from '../../lib/project.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
-} from '../lib/package-scanner.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+} from '../../lib/package-scanner.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
+/**
+ * @typedef {import('../../lib/package-scanner.mjs').ScannedPackage} ScannedPackage
+ */
+
+/**
+ * @param {unknown} docs
+ * @returns {string | null}
+ */
 function validateDocs(docs) {
   if (!docs || typeof docs !== 'object')
     return 'docs export is missing or not an object';
-  if (typeof docs.name !== 'string' || !docs.name)
+  const d = /** @type {Record<string, any>} */ (docs);
+  if (typeof d.name !== 'string' || !d.name)
     return 'docs.name is missing or not a string';
-  if (!docs.usage || typeof docs.usage.description !== 'string')
+  if (!d.usage || typeof d.usage.description !== 'string')
     return 'docs.usage.description is missing or not a string';
-  if (docs.props && !Array.isArray(docs.props))
+  if (d.props && !Array.isArray(d.props))
     return 'docs.props must be an array';
-  if (docs.components && !Array.isArray(docs.components))
+  if (d.components && !Array.isArray(d.components))
     return 'docs.components must be an array';
-  if (docs.usage?.bestPractices && !Array.isArray(docs.usage.bestPractices))
+  if (d.usage?.bestPractices && !Array.isArray(d.usage.bestPractices))
     return 'docs.usage.bestPractices must be an array';
   return null;
 }
@@ -36,11 +45,21 @@ function validateDocs(docs) {
  * @param {boolean} [options.components]
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
- * @returns {Promise<{type: string, data: unknown}>}
+ * @returns {Promise<
+ *   import('../../types/discover').DiscoverListResponse |
+ *   import('../../types/discover').DiscoverDetailResponse |
+ *   import('../../types/discover').DiscoverDetailDocResponse |
+ *   import('../../types/discover').DiscoverSearchResponse
+ * >}
  */
 export async function discover(query, options = {}) {
   const {lang = null, zh = false} = options;
   const project = await Project.load();
+  const loadedIntegrations =
+    /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
+      project.loadedIntegrations
+    );
+  /** @param {ScannedPackage} pkg */
   const toEntry = pkg => ({
     name: pkg.name,
     category: pkg.category,
@@ -52,7 +71,7 @@ export async function discover(query, options = {}) {
 
   // External packages come from configured integrations that declare a
   // components root. Each becomes a scannable package keyed by its docsDir.
-  const explicitPackages = project.loadedIntegrations
+  const explicitPackages = loadedIntegrations
     .filter(integration => integration.components)
     .map(integration => ({
       name: integration.name,
@@ -64,7 +83,10 @@ export async function discover(query, options = {}) {
     return {type: 'discover.list', data: [], meta: {configured: false}};
   }
 
-  const packages = scanAllPackages([], explicitPackages);
+  const packages = scanAllPackages(
+    [],
+    /** @type {ScannedPackage[]} */ (/** @type {unknown} */ (explicitPackages)),
+  );
 
   if (packages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: true}};
@@ -105,7 +127,7 @@ export async function discover(query, options = {}) {
     return await loadAndValidate(exact, {lang, zh});
   }
 
-  const substringMatches = [];
+  const substringMatches = /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
   for (const pkg of packages) {
     for (const comp of pkg.components) {
       if (comp.toLowerCase().includes(lower)) {
@@ -134,7 +156,7 @@ export async function discover(query, options = {}) {
   }
 
   // Fuzzy fallback
-  const allComponents = [];
+  const allComponents = /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
   for (const pkg of packages) {
     for (const comp of pkg.components) {
       allComponents.push({pkg, comp});
@@ -167,6 +189,13 @@ export async function discover(query, options = {}) {
   );
 }
 
+/**
+ * @param {ScannedPackage[]} packages
+ * @param {string} compName
+ * @param {string} pkgName
+ * @param {{lang?: string|null, zh?: boolean}} opts
+ * @returns {Promise<import('../../types/discover').DiscoverDetailDocResponse>}
+ */
 async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   const pkg = packages.find(p => p.name === pkgName);
   if (!pkg)
@@ -202,13 +231,21 @@ async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   return await loadAndValidate(result, {lang, zh});
 }
 
+/**
+ * @param {{docPath: string, componentName: string, pkg: ScannedPackage}} result
+ * @param {{lang?: string|null, zh?: boolean}} opts
+ * @returns {Promise<import('../../types/discover').DiscoverDetailDocResponse>}
+ */
 async function loadAndValidate(result, {lang, zh}) {
   let docs;
   try {
-    docs = await loadDocs(result.docPath, {zh, lang});
+    docs = await loadDocs(
+      result.docPath,
+      /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}),
+    );
   } catch (e) {
     throw new AstryxError(
-      `Failed to load docs for ${result.componentName}: ${e.message}`,
+      `Failed to load docs for ${result.componentName}: ${/** @type {any} */ (e).message}`,
       undefined,
       ERROR_CODES.ERR_INVALID_DOC,
     );