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

package/api/swizzle/swizzle.mjs

@@ -0,0 +1,283 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file swizzle API — copy a component's source into the consumer project for
+ * customization, rewriting escaping relative imports to the OWNER package's
+ * subpaths.
+ *
+ * Side-effecting: `swizzle(name, ...)` writes files and returns a
+ * `swizzle.copy` receipt describing what it did; with no name (or `list`) it
+ * returns `swizzle.list`. Errors throw AstryxError (stable code + suggestions).
+ * All human prose / package-manager prefixing lives in the CLI renderer.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {findCoreDir, listComponents} from '../../utils/paths.mjs';
+import {assertWithin, PathSafetyError} from '../../utils/path-safety.mjs';
+import {checkGhCli} from '../../utils/github.mjs';
+import {Project} from '../../lib/project.mjs';
+import {
+  CORE_PACKAGE,
+  findIntegrationComponentDoc,
+  findIntegrationComponentSource,
+} from '../../lib/component-discovery.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {AstryxError} from '../error.mjs';
+
+/** Default issue tracker for maintainer feedback after swizzling. */
+const DEFAULT_ISSUES_URL = 'https://github.com/facebook/astryx/issues/new';
+
+/**
+ * Rewrite relative imports that point outside the component directory to use
+ * the OWNER package's subpaths. Imports within the copied directory (./x) are
+ * left untouched.
+ *
+ * e.g. with ownerPackage '@astryxdesign/core':
+ *      '../theme/tokens.stylex' -> '@astryxdesign/core/theme'
+ *      '../utils/mergeProps'     -> '@astryxdesign/core/utils'
+ *
+ * @param {string} content
+ * @param {string} [ownerPackage]
+ */
+export function rewriteImports(content, ownerPackage = CORE_PACKAGE) {
+  return content.replace(
+    /(from\s+['"])(\.\.\/.+?)(['"])/g,
+    (match, prefix, importPath, suffix) => {
+      const parts = importPath.replace(/^\.\.\//, '').split('/');
+      const topDir = parts[0];
+      return `${prefix}${ownerPackage}/${topDir}${suffix}`;
+    },
+  );
+}
+
+/**
+ * Build the maintainer feedback note for a swizzled component.
+ * @param {string} component
+ * @param {string|undefined} issuesUrl
+ * @returns {{issuesUrl: string, ghCommand?: string} | null}
+ */
+function buildFeedback(component, issuesUrl) {
+  if (!issuesUrl) return null;
+  /** @type {{issuesUrl: string, ghCommand?: string}} */
+  const feedback = {issuesUrl};
+  const match = issuesUrl.match(
+    /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/issues(?:\/new)?\/?$/,
+  );
+  if (match && checkGhCli()) {
+    const [, owner, repo] = match;
+    feedback.ghCommand = `gh issue create --repo ${owner}/${repo} --title "[${component}] Swizzle feedback"`;
+  }
+  return feedback;
+}
+
+/**
+ * Load the configured integrations + core issues URL for `cwd`, swallowing any
+ * config errors so swizzle never hard-fails on a malformed/absent config.
+ * @param {string} cwd
+ * @returns {Promise<{loadedIntegrations: import('../../lib/integrations.mjs').LoadedIntegration[], issuesUrl: string|undefined, project: Project|null}>}
+ */
+async function loadConfigSafely(cwd) {
+  try {
+    const project = await Project.load(cwd);
+    return {
+      loadedIntegrations: project.loadedIntegrations,
+      issuesUrl: project.config.issuesUrl,
+      project,
+    };
+  } catch {
+    return {loadedIntegrations: [], issuesUrl: undefined, project: null};
+  }
+}
+
+/**
+ * Build the set of OWNER packages that provide a component named `name` across
+ * core + every loaded integration.
+ * @param {string} coreDir
+ * @param {Array<{name: string, components?: string, issuesUrl?: string}>} loadedIntegrations
+ * @param {string} name
+ * @param {string|undefined} coreIssuesUrl
+ * @returns {Array<{package: string, sourceDir: string|null, ownerPackage: string, issuesUrl: string|undefined}>}
+ */
+function resolveOwners(coreDir, loadedIntegrations, name, coreIssuesUrl) {
+  const owners = [];
+  const coreComponentDir = path.join(coreDir, 'src', name);
+  if (fs.existsSync(coreComponentDir)) {
+    owners.push({
+      package: CORE_PACKAGE,
+      sourceDir: coreComponentDir,
+      ownerPackage: CORE_PACKAGE,
+      issuesUrl: coreIssuesUrl || DEFAULT_ISSUES_URL,
+    });
+  }
+  for (const integration of loadedIntegrations) {
+    const docPath = findIntegrationComponentDoc(integration, name);
+    if (!docPath) continue;
+    const sourcePath = findIntegrationComponentSource(integration, name);
+    owners.push({
+      package: integration.name,
+      sourceDir: sourcePath ? path.dirname(sourcePath) : null,
+      ownerPackage: integration.name,
+      issuesUrl: integration.issuesUrl,
+    });
+  }
+  return owners;
+}
+
+/** @param {string} file */
+function isExcludedFromCopy(file) {
+  return (
+    file.includes('.test.') || file.includes('.doc.') || file === 'README.md'
+  );
+}
+
+/**
+ * List swizzlable components, or copy one component's source for customization.
+ *
+ * @param {string} [component] bare or XDS-prefixed component name; omit to list
+ * @param {{cwd?: string, output?: string, package?: string, list?: boolean, overwrite?: boolean}} [options]
+ * @returns {Promise<import('../../types/swizzle').SwizzleListResponse | import('../../types/swizzle').SwizzleCopyResponse>}
+ */
+export async function swizzle(component, options = {}) {
+  const {
+    cwd = process.cwd(),
+    output = './components/astryx',
+    package: pkg,
+    list = false,
+    overwrite = false,
+  } = options;
+
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package. Make sure you are inside the design system monorepo or have @astryxdesign/core installed.',
+      [],
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
+
+  const components = listComponents(coreDir);
+
+  if (list || !component) {
+    return {type: 'swizzle.list', data: components};
+  }
+
+  const dirName = component.replace(/^XDS/, '');
+
+  const {loadedIntegrations, project} = await loadConfigSafely(cwd);
+  const coreIssuesUrl = project
+    ? project.issuesUrl({package: CORE_PACKAGE})
+    : undefined;
+  const allOwners = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+
+  if (allOwners.length === 0) {
+    throw new AstryxError(
+      `Component "${component}" not found.`,
+      components.slice(0, 10).map(n => ({name: n})),
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  let owner;
+  if (pkg) {
+    owner = allOwners.find(o => o.package === pkg);
+    if (!owner) {
+      throw new AstryxError(
+        `Component "${dirName}" is not provided by package "${pkg}".`,
+        allOwners.map(o => ({name: o.package, reason: 'provides this component'})),
+        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+      );
+    }
+  } else if (allOwners.length > 1) {
+    throw new AstryxError(
+      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
+      allOwners.map(o => ({name: o.package, reason: 'provides this component'})),
+      ERROR_CODES.ERR_AMBIGUOUS_COMPONENT,
+    );
+  } else {
+    owner = allOwners[0];
+  }
+
+  if (!owner.sourceDir || !fs.existsSync(owner.sourceDir)) {
+    throw new AstryxError(
+      `No source found for "${dirName}" in package "${owner.package}".`,
+      [],
+      ERROR_CODES.ERR_NO_SOURCE,
+    );
+  }
+
+  const componentDir = owner.sourceDir;
+
+  // Path-safety: --output must resolve inside cwd.
+  let outputBase;
+  try {
+    outputBase = assertWithin(output, cwd, {label: 'output directory'});
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, [], ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+  const outputDir = path.join(outputBase, dirName);
+
+  // Pre-flight overwrite check before any mkdir/writeFile.
+  const sourceFiles = fs.readdirSync(componentDir).filter(file => {
+    if (isExcludedFromCopy(file)) return false;
+    return fs.statSync(path.join(componentDir, file)).isFile();
+  });
+  const existingFiles = sourceFiles.filter(f =>
+    fs.existsSync(path.join(outputDir, f)),
+  );
+  if (existingFiles.length > 0 && !overwrite) {
+    const relOutputForMsg = path.relative(cwd, outputDir) || '.';
+    throw new AstryxError(
+      `Refusing to overwrite ${existingFiles.length} existing file(s) in ${relOutputForMsg}/. ` +
+        `Re-run with --overwrite (or -f) to replace them.`,
+      [],
+      ERROR_CODES.ERR_FILE_EXISTS,
+    );
+  }
+
+  fs.mkdirSync(outputDir, {recursive: true});
+
+  const files = fs.readdirSync(componentDir);
+  let copied = 0;
+  let usesStyleX = false;
+  for (const file of files) {
+    if (isExcludedFromCopy(file)) continue;
+    const srcPath = path.join(componentDir, file);
+    if (!fs.statSync(srcPath).isFile()) continue;
+    let content = fs.readFileSync(srcPath, 'utf-8');
+    if (file.endsWith('.ts') || file.endsWith('.tsx')) {
+      content = rewriteImports(content, owner.ownerPackage);
+    }
+    if (
+      (file.endsWith('.ts') || file.endsWith('.tsx')) &&
+      content.includes('@stylexjs/stylex')
+    ) {
+      usesStyleX = true;
+    }
+    fs.writeFileSync(path.join(outputDir, file), content);
+    copied++;
+  }
+
+  const relOutput = path.relative(cwd, outputDir);
+  const copiedFiles = files.filter(
+    f =>
+      !isExcludedFromCopy(f) &&
+      fs.statSync(path.join(componentDir, f)).isFile(),
+  );
+  const feedback = buildFeedback(dirName, owner.issuesUrl);
+
+  /** @type {import('../../types/swizzle').SwizzleCopyResponse['data']} */
+  const data = {
+    component: dirName,
+    package: owner.package,
+    outputDir: relOutput,
+    filesCopied: copied,
+    files: copiedFiles.map(f => f),
+    usesStyleX,
+  };
+  if (feedback) data.feedback = feedback;
+  return {type: 'swizzle.copy', data};
+}

package/{src/commands → api/swizzle}/swizzle.test.mjs

@@ -1,7 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {rewriteImports} from './swizzle.mjs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {rewriteImports, swizzle} from './swizzle.mjs';
+
+// api/swizzle/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
 
 describe('rewriteImports', () => {
   it('rewrites ../theme/tokens to @astryxdesign/core/theme', () => {
@@ -51,3 +56,23 @@ describe('rewriteImports', () => {
     );
   });
 });
+
+describe('swizzle() API', () => {
+  it('no component → swizzle.list of core components', async () => {
+    const r = await swizzle(undefined, {cwd: REPO});
+    expect(r.type).toBe('swizzle.list');
+    expect(Array.isArray(r.data)).toBe(true);
+    expect(r.data).toContain('Button');
+  });
+
+  it('--list → swizzle.list even with a component arg', async () => {
+    const r = await swizzle('Button', {cwd: REPO, list: true});
+    expect(r.type).toBe('swizzle.list');
+  });
+
+  it('unknown component → AstryxError ERR_UNKNOWN_COMPONENT with suggestions', async () => {
+    await expect(swizzle('NotARealComponent99', {cwd: REPO})).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_COMPONENT',
+    });
+  });
+});

package/{src/api → api/template}/template-integration.test.mjs

@@ -62,7 +62,7 @@ function writeTemplate(pkgDir, id, {kind, body, withSource = true}) {
   fs.writeFileSync(
     docPath,
     body ??
-      `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
+      `import {${create}} from '${CLI_PKG}/authoring/template.mjs';\n` +
         `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
   );
   if (withSource) {
@@ -166,7 +166,7 @@ describe('integration template discovery', () => {
     );
     fs.writeFileSync(
       path.join(pkg2, 'templates', 'hero.doc.mjs'),
-      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
+      `import {createBlockTemplate} from '${CLI_PKG}/authoring/template.mjs';\n` +
         `export default createBlockTemplate({name: 'Hero block', description: 'b'});\n`,
     );
     fs.writeFileSync(

package/{src/api → api/template}/template-suffix.test.mjs

@@ -21,7 +21,7 @@ import {
   findRelatedBlocks,
 } from './template.mjs';
 
-/** Absolute path to the CLI package so fixtures can import /src/template.mjs. */
+/** Absolute path to the CLI package so fixtures can import /authoring/template.mjs. */
 const CLI_PKG = path.resolve(import.meta.dirname, '..', '..');
 
 let tmpDir;
@@ -68,7 +68,7 @@ function writeTemplate(pkgDir, id, {kind, suffix}) {
     kind === 'page' ? 'createPageTemplate' : 'createBlockTemplate';
   fs.writeFileSync(
     docPath,
-    `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
+    `import {${create}} from '${CLI_PKG}/authoring/template.mjs';\n` +
       `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
   );
   fs.writeFileSync(
@@ -177,7 +177,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
     fs.mkdirSync(fooDir, {recursive: true});
     fs.writeFileSync(
       path.join(fooDir, 'FooShowcase.template.ts'),
-      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
+      `import {createBlockTemplate} from '${CLI_PKG}/authoring/template.mjs';\n` +
         `export default createBlockTemplate({\n` +
         `  name: 'Foo — Showcase',\n` +
         `  description: 'Foo showcase.',\n` +

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

@@ -7,21 +7,54 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {createJiti} from 'jiti';
-import {loadModuleWithSchema} from '../lib/module-loader.mjs';
-import {TemplateEnvelopeSchema} from '../schemas/template-schema.mjs';
-import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
+import {loadModuleWithSchema} from '../../lib/module-loader.mjs';
+import {TemplateEnvelopeSchema} from '../../schemas/template-schema.mjs';
+import {CLI_ROOT, discoverExternalPackages} from '../../utils/paths.mjs';
 import {
   assertWithin,
   isFilePathArg,
   PathSafetyError,
-} from '../utils/path-safety.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {Project} from '../lib/project.mjs';
+} from '../../utils/path-safety.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {Project} from '../../lib/project.mjs';
 
 /** Identity used for core (built-in) templates in package-scoped listings. */
 const CORE_PACKAGE = '@astryxdesign/core';
 
+/**
+ * A discovered template (page or block), normalized across core, external, and
+ * integration sources. Not every source populates every field, so
+ * source-specific extras (`aspectRatio`, `isShowcase`, `package`) are optional.
+ * @typedef {object} DiscoveredTemplate
+ * @property {'page'|'block'} type
+ * @property {string} dirName
+ * @property {string} name
+ * @property {string} description
+ * @property {string} [category]
+ * @property {boolean} [isReady]
+ * @property {boolean} [scaffold]
+ * @property {number} [aspectRatio]
+ * @property {string[]} [componentsUsed]
+ * @property {boolean} [isShowcase]
+ * @property {string} filePath
+ * @property {string} docPath
+ * @property {string} [package]
+ */
+
+/**
+ * An integration-template discovery error.
+ * @typedef {object} TemplateDiscoveryError
+ * @property {string} package
+ * @property {string} [template]
+ * @property {string} message
+ */
+
+/**
+ * The loaded metadata object from a template spec (loose — authored shape).
+ * @typedef {Record<string, any> | undefined | null} TemplateDocModule
+ */
+
 /**
  * Canonical basename suffixes for template-spec files, in precedence order.
  * A template spec exports a `createBlockTemplate`/`createPageTemplate` result
@@ -60,6 +93,7 @@ function matchedTemplateSuffix(file) {
  */
 const TEMPLATE_SUFFIX_RE = /\.(template|doc)\.(ts|mjs|js)$/;
 
+/** @type {ReturnType<typeof createJiti> | undefined} */
 let jitiInstance;
 /** Lazily-created jiti for loading `.ts` template specs (JSX-capable). */
 function getJiti() {
@@ -69,7 +103,6 @@ function getJiti() {
   return jitiInstance;
 }
 
-
 /**
  * Load an integration template doc module and validate it against the template
  * envelope at the load boundary. Default export only — `.ts` via jiti,
@@ -145,7 +178,7 @@ export function stripTemplateAssetRefs(source) {
  * native dynamic import. Returns null if the file does not exist.
  *
  * @param {string} docPath absolute path to the spec file
- * @returns {Promise<Record<string, unknown> | undefined | null>}
+ * @returns {Promise<TemplateDocModule>}
  */
 async function loadDocModule(docPath) {
   if (!fs.existsSync(docPath)) return null;
@@ -159,6 +192,7 @@ async function loadDocModule(docPath) {
 export {discoverAll as discoverTemplates};
 
 export function listTemplates() {
+  /** @type {string[]} */
   const all = [];
   if (fs.existsSync(PAGES_DIR)) {
     all.push(
@@ -171,7 +205,13 @@ export function listTemplates() {
   return all.sort();
 }
 
+/**
+ * @param {string} dir
+ * @param {RegExp} pattern
+ * @returns {string[]}
+ */
 function findDocFiles(dir, pattern) {
+  /** @type {string[]} */
   const results = [];
   if (!fs.existsSync(dir)) return results;
   for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
@@ -205,6 +245,7 @@ async function discoverPages() {
     .readdirSync(PAGES_DIR, {withFileTypes: true})
     .filter(e => e.isDirectory());
 
+  /** @type {DiscoveredTemplate[]} */
   const templates = [];
   for (const dir of dirs) {
     const dirPath = path.join(PAGES_DIR, dir.name);
@@ -228,9 +269,11 @@ async function discoverPages() {
 
 async function discoverBlocks() {
   const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);
+  /** @type {DiscoveredTemplate[]} */
   const blocks = [];
   for (const docPath of docFiles) {
     const suffix = matchedTemplateSuffix(docPath);
+    if (!suffix) continue;
     const basename = path.basename(docPath, suffix);
     const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
     if (!fs.existsSync(tsxPath)) continue;
@@ -262,6 +305,7 @@ async function discoverBlocks() {
  */
 async function discoverExternalBlocks(cwd = process.cwd()) {
   const externals = discoverExternalPackages(cwd);
+  /** @type {DiscoveredTemplate[]} */
   const blocks = [];
 
   for (const ext of externals) {
@@ -269,6 +313,7 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
     const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);
     for (const docPath of docFiles) {
       const suffix = matchedTemplateSuffix(docPath);
+      if (!suffix) continue;
       const basename = path.basename(docPath, suffix);
       const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
       if (!fs.existsSync(tsxPath)) continue;
@@ -297,6 +342,7 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
 /**
  * Discover all blocks — core + external packages.
  * @param {string} [cwd]
+ * @returns {Promise<DiscoveredTemplate[]>}
  */
 async function discoverAllBlocks(cwd = process.cwd()) {
   const [core, external] = await Promise.all([
@@ -306,6 +352,10 @@ async function discoverAllBlocks(cwd = process.cwd()) {
   return [...core, ...external];
 }
 
+/**
+ * @param {string} [cwd]
+ * @returns {Promise<DiscoveredTemplate[]>}
+ */
 async function discoverAll(cwd = process.cwd()) {
   const [pages, blocks, integration] = await Promise.all([
     discoverPages(),
@@ -323,7 +373,7 @@ async function discoverAll(cwd = process.cwd()) {
  * when the caller wants to warn about malformed integration templates.
  *
  * @param {string} [cwd]
- * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
 async function discoverAllWithErrors(cwd = process.cwd()) {
   const [pages, blocks, integration] = await Promise.all([
@@ -348,8 +398,10 @@ export {discoverAllWithErrors};
  * @returns {string[]}
  */
 function findIntegrationDocFiles(root) {
+  /** @type {string[]} */
   const results = [];
   if (!fs.existsSync(root)) return results;
+  /** @param {string} dir */
   const walk = dir => {
     for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
       const full = path.join(dir, entry.name);
@@ -377,16 +429,21 @@ function findIntegrationDocFiles(root) {
  * template is skipped (recorded in `errors`).
  *
  * @param {string} [cwd]
- * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
 async function discoverIntegrationTemplates(cwd = process.cwd()) {
+  /** @type {DiscoveredTemplate[]} */
   const templates = [];
+  /** @type {TemplateDiscoveryError[]} */
   const errors = [];
 
   let loadedIntegrations;
   try {
     const project = await Project.load(cwd);
-    loadedIntegrations = project.loadedIntegrations;
+    loadedIntegrations =
+      /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
+        project.loadedIntegrations
+      );
   } catch {
     // Config load failures are surfaced elsewhere (discover/doctor); here we
     // simply contribute no integration templates.
@@ -409,10 +466,12 @@ async function discoverIntegrationTemplates(cwd = process.cwd()) {
  * than thrown. Exposed for `validate-integration`.
  *
  * @param {{name?: string, __spec?: string, templates?: string}} integration
- * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
 export async function discoverIntegrationTemplatesForOne(integration) {
+  /** @type {DiscoveredTemplate[]} */
   const templates = [];
+  /** @type {TemplateDiscoveryError[]} */
   const errors = [];
 
   const root = integration?.templates;
@@ -421,6 +480,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
 
   for (const docPath of findIntegrationDocFiles(root)) {
     const suffix = matchedTemplateSuffix(docPath);
+    if (!suffix) continue;
     const id = path
       .relative(root, docPath)
       .slice(0, -suffix.length)
@@ -444,7 +504,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
       errors.push({
         package: pkgLabel,
         template: id,
-        message: `Template "${id}" failed to load: ${err.message}`,
+        message: `Template "${id}" failed to load: ${/** @type {any} */ (err).message}`,
       });
       continue;
     }
@@ -480,10 +540,15 @@ export async function discoverIntegrationTemplatesForOne(integration) {
   return {templates, errors};
 }
 
+/**
+ * @param {string} componentName
+ * @param {string} [cwd]
+ * @returns {Promise<DiscoveredTemplate[]>}
+ */
 export async function findRelatedBlocks(componentName, cwd) {
   const blocks = await discoverAllBlocks(cwd);
   return blocks.filter(b =>
-    b.componentsUsed.some(c => c.toLowerCase() === componentName.toLowerCase()),
+    (b.componentsUsed ?? []).some(c => c.toLowerCase() === componentName.toLowerCase()),
   );
 }
 
@@ -506,7 +571,7 @@ export async function findShowcase(componentName, cwd, options) {
     return true;
   });
 
-  const toResult = b => ({
+  const toResult = (/** @type {DiscoveredTemplate} */ b) => ({
     name: b.name,
     aspectRatio: b.aspectRatio,
     filePath: b.filePath,
@@ -515,14 +580,14 @@ export async function findShowcase(componentName, cwd, options) {
 
   // Priority 1: own directory (components/Badge/ for "Badge")
   const dirMatch = showcases.find(b => {
-    const catDir = path.basename(b.category).toLowerCase();
+    const catDir = path.basename(b.category ?? '').toLowerCase();
     return catDir === lc;
   });
   if (dirMatch) return toResult(dirMatch);
 
   // Priority 2: componentsUsed in any directory (ClickableCard in Card/)
   const usedMatch = showcases.find(b =>
-    b.componentsUsed.some(c => c.toLowerCase() === lc),
+    (b.componentsUsed ?? []).some(c => c.toLowerCase() === lc),
   );
   if (usedMatch) return toResult(usedMatch);
 
@@ -540,6 +605,10 @@ const UBIQUITOUS = new Set([
   'Icon',
 ]);
 
+/**
+ * @param {string} pagePath
+ * @returns {string[]}
+ */
 export function extractComponents(pagePath) {
   const src = fs.readFileSync(pagePath, 'utf-8');
   // Match JSX opening tags, e.g. `<Section` or the legacy `<XDSSection`.
@@ -548,6 +617,7 @@ export function extractComponents(pagePath) {
   // JSX-tag boundary keeps this precise (avoids matching imports/comments/
   // identifiers) while remaining prefix-agnostic.
   const tagRegex = /<(XDS)?([A-Z]\w+)/g;
+  /** @type {string[]} */
   const matches = [];
   let m;
   while ((m = tagRegex.exec(src)) !== null) {
@@ -617,10 +687,11 @@ const SPATIAL_PROPS = [
  * @returns {string[]}
  */
 function extractSpatialAttrs(tagText) {
+  /** @type {string[]} */
   const attrs = [];
   for (const name of SPATIAL_PROPS) {
     const eqMatch = tagText.match(new RegExp(`\\b${name}\\s*=\\s*`));
-    if (eqMatch) {
+    if (eqMatch && eqMatch.index != null) {
       const start = eqMatch.index;
       let i = eqMatch.index + eqMatch[0].length;
       const rest = tagText.slice(i);
@@ -662,13 +733,19 @@ function extractSpatialAttrs(tagText) {
   return attrs;
 }
 
+/**
+ * @param {string} source
+ * @returns {string}
+ */
 function extractSkeleton(source) {
   const lines = source.split('\n');
+  /** @type {string[]} */
   const out = [];
   let depth = 0;
   let capturing = false;
   let inDefaultExport = false;
   const MAX_LINES = 35;
+  /** @type {string[]} */
   const depthStack = [];
 
   for (let i = 0; i < lines.length; i++) {