Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
67.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Component discovery — find, list, and resolve Astryx components
 */

import * as fs from 'node:fs';
import {createRequire} from 'node:module';
import * as path from 'node:path';
import {DOC_EXPORTS} from '../doc-compiler/read.mjs';
import {
  listDir,
  listDirEntries,
  listingCacheActive,
  oncePerListing,
  pathExists,
  withListingCache,
} from '../fs/listing-cache.mjs';
import {existsCaseExact} from '../fs/paths.mjs';
import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
import {loadComponentDoc} from './component-loader.mjs';
import {
  HAS_COMPUTED,
  moduleExportSource,
  moduleExportsName,
  staticExportObject,
} from './module-exports.mjs';
import {
  inspectPackageExport,
  sourceExportTarget,
} from './package-exports.mjs';

const require = createRequire(import.meta.url);

const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);

/** The owner package name for built-in (core) components. */
export const CORE_PACKAGE = CORE_PROVIDER_ID;

/** Conventional doc-file suffixes for integration components (same-stem). */
const INTEGRATION_DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];

// Component source files are named `XDS{Name}.tsx` today. The XDS-prefix
// migration (P2380608025, P4) renames them to the bare `{Name}.tsx` form, so
// discovery must recognize BOTH. The `XDS` prefix has historically doubled as
// a "this is a top-level component" marker, so naively matching all PascalCase
// `.tsx` files would surface internal helpers that happen to be PascalCase
// (`OverlayScrim.tsx`, `PowerSearchEditPopover.tsx`, ...). To avoid that
// regression, a BARE-named file is only treated as a component when a matching
// doc file exists for it (`{Name}.doc.mjs` or `XDS{Name}.doc.mjs` in the same
// directory). Prefixed `XDS{Name}.tsx` files keep their existing behavior.
const PREFIXED_COMPONENT_FILE_RE = /^XDS[A-Z]\w+\.tsx$/;
const BARE_COMPONENT_FILE_RE = /^[A-Z]\w+\.tsx$/;

/**
 * Whether a filename looks like a component source file, excluding tests,
 * Context files, and (implicitly, via the uppercase-first match) `use*` hooks.
 *
 * Recognizes both the current `XDSButton.tsx` form and the post-migration
 * bare `Button.tsx` form. Bare matches additionally require a sibling doc file
 * so internal PascalCase helpers are not misclassified as components.
 *
 * @param {string} fileName
 * @param {string} dirPath — directory containing the file (for the bare-name doc check)
 * @returns {boolean}
 */
function isComponentSourceFile(fileName, dirPath) {
  if (fileName.includes('.test.') || fileName.includes('Context.')) {
    return false;
  }
  if (PREFIXED_COMPONENT_FILE_RE.test(fileName)) {
    return true;
  }
  if (BARE_COMPONENT_FILE_RE.test(fileName)) {
    const base = fileName.replace(/\.tsx$/, '');
    return (
      pathExists(path.join(dirPath, `${base}.doc.mjs`)) ||
      pathExists(path.join(dirPath, `XDS${base}.doc.mjs`))
    );
  }
  return false;
}

/**
 * Strip the optional `XDS` prefix and `.tsx` suffix to get the bare component
 * name. Works for both `XDSButton.tsx` and `Button.tsx`.
 *
 * @param {string} fileName
 * @returns {string}
 */
function componentNameFromFile(fileName) {
  return fileName.replace(/^XDS/, '').replace(/\.tsx$/, '');
}

// Matches the top-level `group: 'GroupName'` field in a .doc.mjs file.
// Only matches at ≤2 spaces (top-level object fields). Deeper indentation is a
// nested field — e.g. a `group:` entry inside a `propDescriptions:` block of a
// docsZh/docsDense translation export — which must NOT be read as the
// component's group (that leaked a translated prop description as a group key).
const GROUP_RE = /(?:^|\n) {0,2}group:\s*['"]([^'"]+)['"]/;
const HIDDEN_COMPONENTS_RE = /(?:^|\n) {0,2}hiddenComponents:\s*\[([^\]]*)\]/;
const HIDDEN_RE = /(?:^|\n) {0,2}hidden:\s*true/;
// Every top-level `name: '...'` (or `"name": "..."`) in the file: a quick check
// that a doc is named after its file before anything parses it.
const NAME_FIELD_RE = /(?:^|\n) {0,2}['"]?name['"]?\s*:\s*['"]([^'"\n]+)['"]/g;
// A `components` field anywhere in the file, written out or as a shorthand: the
// quick check for a family doc, before anything parses it. A false match only
// costs the parse.
const MEMBERS_FIELD_RE = /\bcomponents\b/;
// A top-level `replaces: '...'`: the Core name a doc claims for its package.
const REPLACES_FIELD_RE =
  /(?:^|\n) {0,2}['"]?replaces['"]?\s*:\s*['"]([^'"\n]+)['"]/;

/**
 * What a quick scan of a doc's text finds before anything parses it: the
 * top-level `name` values it writes (none when a spread could set the name),
 * whether it may list family members, and the Core name it replaces.
 * @param {string} text
 * @returns {{names: string[], hasMembers: boolean, replaces: string | null}}
 */
function scanDocText(text) {
  return {
    names: text.includes('...')
      ? []
      : [...text.matchAll(NAME_FIELD_RE)].map(match => match[1]),
    hasMembers: MEMBERS_FIELD_RE.test(text),
    replaces: REPLACES_FIELD_RE.exec(text)?.[1] ?? null,
  };
}

/**
 * Whether a component doc is hidden (`hidden: true`), read as discovery
 * reads it: discovery skips a hidden doc.
 * @param {string} docPath
 * @returns {boolean}
 */
export function isHiddenComponentDoc(docPath) {
  return readDocMeta(docPath).hidden;
}

/**
 * Read the `group`, `hiddenComponents`, and `hidden` fields from a
 * component's .doc.mjs file (synchronous), with what {@link scanDocText}
 * finds in it.
 * @param {string} docPath
 * @returns {{group: string | null, hiddenComponents: Set<string>, hidden: boolean, names: string[], hasMembers: boolean, replaces: string | null}}
 */
function readDocMeta(docPath) {
  try {
    const content = fs.readFileSync(docPath, 'utf-8');
    const groupMatch = GROUP_RE.exec(content);
    const hiddenCompsMatch = HIDDEN_COMPONENTS_RE.exec(content);
    /** @type {Set<string>} */
    const hiddenSet = new Set();
    if (hiddenCompsMatch) {
      for (const m of hiddenCompsMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {
        hiddenSet.add(m[1]);
      }
    }
    const hidden = HIDDEN_RE.test(content);
    return {
      group: groupMatch ? groupMatch[1] : null,
      hiddenComponents: hiddenSet,
      hidden,
      ...scanDocText(content),
    };
  } catch {
    return {
      group: null,
      hiddenComponents: new Set(),
      hidden: false,
      names: [],
      hasMembers: false,
      replaces: null,
    };
  }
}

/** @type {typeof import('@babel/parser') | undefined} */
let babelParser;

/**
 * A property of an object literal, by its plain key.
 * @param {any} object - an ObjectExpression node
 * @param {string} key
 * @returns {any}
 */
function propertyValue(object, key) {
  for (const property of object.properties) {
    if (property.type !== 'ObjectProperty' || property.computed) continue;
    const name =
      property.key.type === 'Identifier'
        ? property.key.name
        : property.key.type === 'StringLiteral'
          ? property.key.value
          : null;
    if (name === key) return property.value;
  }
  return null;
}

/**
 * The names a component doc lists as `components` members, read from its
 * source without running it. Only a static `{name: '<Name>'}` entry in the doc
 * object the loader reads (the `default` export, else `docs`) counts: a name in
 * prose, an example, or `relatedComponents` is not a member.
 * @param {string} source - the doc file's text
 * @returns {string[]}
 */
function docMemberNames(source) {
  /** @type {any} */
  let ast;
  try {
    babelParser ??= require('@babel/parser');
    ast = /** @type {typeof import('@babel/parser')} */ (babelParser).parse(
      source,
      {
        sourceType: 'module',
      },
    );
  } catch {
    return [];
  }
  /** @type {Map<string, any>} */
  const constants = new Map();
  let defaultExport = null;
  let docsExport = null;
  for (const node of ast.program.body) {
    const declaration =
      node.type === 'ExportNamedDeclaration' ? node.declaration : node;
    if (declaration?.type === 'VariableDeclaration') {
      for (const declarator of declaration.declarations) {
        if (declarator.id.type !== 'Identifier' || !declarator.init) continue;
        constants.set(declarator.id.name, declarator.init);
        if (
          node.type === 'ExportNamedDeclaration' &&
          declarator.id.name === 'docs'
        ) {
          docsExport = declarator.init;
        }
      }
    }
    if (node.type === 'ExportDefaultDeclaration')
      defaultExport = node.declaration;
  }
  let doc = defaultExport ?? docsExport;
  if (doc?.type === 'Identifier') doc = constants.get(doc.name);
  if (doc?.type !== 'ObjectExpression') return [];
  const members = propertyValue(doc, 'components');
  if (members?.type !== 'ArrayExpression') return [];
  return members.elements.flatMap((/** @type {any} */ element) => {
    if (element?.type !== 'ObjectExpression') return [];
    const name = propertyValue(element, 'name');
    return name?.type === 'StringLiteral' ? [name.value] : [];
  });
}

/**
 * Whether `name` has its own component folder in Core: `src/<Name>/<Name>.tsx`
 * (or the `XDS`-prefixed form).
 * @param {string} srcDir
 * @param {string} name
 * @returns {boolean}
 */
function hasOwnFolder(srcDir, name) {
  return [`${name}.tsx`, `XDS${name}.tsx`].some(file =>
    existsCaseExact(path.join(srcDir, name, file), srcDir),
  );
}

/**
 * Member names read in this process, by doc path, reused while the file keeps
 * its size and mtime.
 * @type {Map<string, {size: number, mtimeMs: number, members: string[]}>}
 */
const memberReads = new Map();

/**
 * The names a doc lists as `components` members (see docMemberNames).
 * @param {string} docPath
 * @returns {string[]}
 */
function readDocMembers(docPath) {
  let stat;
  try {
    stat = fs.statSync(docPath);
  } catch {
    return [];
  }
  const cached = memberReads.get(docPath);
  if (cached && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) {
    return cached.members;
  }
  /** @type {string[]} */
  let members;
  try {
    members = docMemberNames(fs.readFileSync(docPath, 'utf-8'));
  } catch {
    members = [];
  }
  memberReads.set(docPath, {size: stat.size, mtimeMs: stat.mtimeMs, members});
  return members;
}

// A sibling component folder named by a relative import or re-export.
const SIBLING_IMPORT_RE =
  /(?:\bfrom|\bimport\s*\()\s*['"]\.\.\/([A-Za-z0-9_-]+)(?:\/[^'"]*)?['"]/g;

/**
 * The Core doc that documents `name` as one of its `components` members: the
 * doc of a component it builds on. HStack and VStack import Stack, and Stack's
 * doc lists them, so each has its own folder and import path but no doc of its
 * own. Only the folders the component's own source imports from are read.
 * @param {string} srcDir
 * @param {string} name
 * @returns {string | null}
 */
function findFamilyDoc(srcDir, name) {
  const sourcePath = [`${name}.tsx`, `XDS${name}.tsx`]
    .map(file => path.join(srcDir, name, file))
    .find(file => existsCaseExact(file, srcDir));
  if (!sourcePath) return null;
  let source;
  try {
    source = fs.readFileSync(sourcePath, 'utf-8');
  } catch {
    return null;
  }
  const families = [
    ...new Set([...source.matchAll(SIBLING_IMPORT_RE)].map(match => match[1])),
  ]
    .filter(dir => dir !== name && !SKIP_DIRS.has(dir))
    .sort();
  for (const dir of families) {
    const dirPath = path.join(srcDir, dir);
    if (!existsCaseExact(dirPath, srcDir)) continue;
    for (const file of [...listDir(dirPath)].sort()) {
      if (!file.endsWith('.doc.mjs')) continue;
      const docPath = path.join(dirPath, file);
      const members = readDocMembers(docPath);
      if (members.includes(name) || members.includes(`XDS${name}`)) {
        return docPath;
      }
    }
  }
  return null;
}

/**
 * The entry a family doc gives `name` in its `components`, when the doc is not
 * the component's own (Stack's doc for VStack); null otherwise.
 * @param {any} docs - a loaded component doc
 * @param {string} name - bare component name
 * @returns {any}
 */
export function familyMember(docs, name) {
  if (!docs || docs.name === name || docs.name === `XDS${name}`) return null;
  const members = Array.isArray(docs.components) ? docs.components : [];
  return (
    members.find(
      (/** @type {any} */ member) =>
        member?.name === name || member?.name === `XDS${name}`,
    ) ?? null
  );
}

/**
 * Auto-discover components by scanning for Astryx*.tsx files in core/src/.
 * A component is listed when a doc documents it: a doc in its folder, or, for a
 * component folder with no doc of its own, the doc `findComponentReadme` finds
 * elsewhere (Heading's doc in the Text folder; HStack and VStack as members of
 * Stack's doc).
 *
 * Returns an ordered Record where:
 * - Grouped components use the group name as key: `'Buttons': ['Button', 'IconButton']`
 * - Ungrouped components use their own name as key: `'Avatar': ['Avatar']`
 *
 * Keys are sorted alphabetically (groups and ungrouped components interleaved).
 * Components within each group are also sorted alphabetically.
 * @param {string} coreDir
 * @returns {Record<string, string[]>}
 */
export function discoverComponents(coreDir) {
  // The component matcher calls this for each name it resolves, so one
  // operation reads the docs once. Each caller gets its own copy to change.
  const found = oncePerListing(`components\0${coreDir}`, () =>
    readComponentGroups(coreDir),
  );
  return Object.fromEntries(
    Object.entries(found).map(([key, names]) => [key, [...names]]),
  );
}

/**
 * The component groups under `coreDir`, read from disk.
 * @param {string} coreDir
 * @returns {Record<string, string[]>}
 */
function readComponentGroups(coreDir) {
  const srcDir = path.join(coreDir, 'src');
  /** @type {Map<string, string|null>} componentName → group */
  const componentGroups = new Map();

  /**
   * @param {string} dirPath
   * @returns {string[]}
   */
  function collectXDSFiles(dirPath) {
    /** @type {string[]} */
    const results = [];
    if (!pathExists(dirPath)) return results;
    const entries = listDirEntries(dirPath);
    for (const entry of entries) {
      if (entry.isDirectory()) {
        results.push(...collectXDSFiles(path.join(dirPath, entry.name)));
      } else if (isComponentSourceFile(entry.name, dirPath)) {
        results.push(entry.name);
      }
    }
    return results;
  }

  const topEntries = listDirEntries(srcDir);
  for (const entry of topEntries) {
    if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;

    const dirPath = path.join(srcDir, entry.name);
    const xdsFiles = collectXDSFiles(dirPath);

    // Read the group from the directory's .doc.mjs file (if it exists)
    // Check both {Name}.doc.mjs and Astryx{Name}.doc.mjs naming conventions
    let docFile = path.join(dirPath, `${entry.name}.doc.mjs`);
    if (!pathExists(docFile)) {
      docFile = path.join(dirPath, `XDS${entry.name}.doc.mjs`);
    }
    const {group, hiddenComponents, hidden} = pathExists(docFile)
      ? readDocMeta(docFile)
      : {group: null, hiddenComponents: new Set(), hidden: false};

    // Skip entire directory if the doc is marked hidden
    if (hidden) continue;

    for (const fileName of xdsFiles) {
      const componentName = componentNameFromFile(fileName);
      if (hiddenComponents.has(componentName)) continue;

      // Check for a per-component doc file that overrides the directory group
      let compGroup = group;
      let compDoc = path.join(dirPath, `${componentName}.doc.mjs`);
      if (!pathExists(compDoc)) {
        compDoc = path.join(dirPath, `XDS${componentName}.doc.mjs`);
      }
      const hasComponentDoc = pathExists(compDoc);
      if (hasComponentDoc) {
        const compMeta = readDocMeta(compDoc);
        if (compMeta.group) compGroup = compMeta.group;
      }

      // Skip components without any .doc.mjs file (directory-level or
      // component-level). They can't be documented, so surfacing them in
      // the component list leads to broken docs-site links.
      if (!pathExists(docFile) && !hasComponentDoc) continue;

      if (!componentGroups.has(componentName)) {
        componentGroups.set(componentName, compGroup);
      }
    }
  }

  // A component folder with no doc in it is still listed when a doc elsewhere
  // documents it, the doc `component <Name>` opens: its own same-stem doc in a
  // family folder (Text/Heading.doc.mjs), or a member entry in the family's doc
  // (HStack and VStack in Stack's doc).
  for (const entry of topEntries) {
    if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
    const name = entry.name;
    if (componentGroups.has(name) || name.endsWith('Context')) continue;
    if (
      listDir(path.join(srcDir, name)).some(file => file.endsWith('.doc.mjs'))
    ) {
      continue;
    }
    if (!hasOwnFolder(srcDir, name)) continue;
    const docPath = findComponentReadme(coreDir, name);
    if (!docPath?.endsWith('.doc.mjs')) continue;
    const meta = readDocMeta(docPath);
    if (meta.hidden || meta.hiddenComponents.has(name)) continue;
    componentGroups.set(name, meta.group);
  }

  // Build the result: group name → sorted members, or component name → [self]
  /** @type {Map<string, string[]>} */
  const groups = new Map();
  /** @type {string[]} ungrouped component names */
  const ungrouped = [];

  for (const [name, group] of componentGroups) {
    if (group) {
      if (!groups.has(group)) groups.set(group, []);
      groups.get(group)?.push(name);
    } else {
      ungrouped.push(name);
    }
  }

  // Sort members within each group
  for (const members of groups.values()) {
    members.sort();
  }

  // Merge groups and ungrouped into a single alphabetically-ordered record
  /** @type {Array<{key: string, values: string[]}>} */
  const entries = [];
  for (const [groupName, members] of groups) {
    entries.push({key: groupName, values: members});
  }
  for (const name of ungrouped) {
    entries.push({key: name, values: [name]});
  }
  entries.sort((a, b) => a.key.localeCompare(b.key));

  /** @type {Record<string, string[]>} */
  const ordered = {};
  for (const {key, values} of entries) {
    ordered[key] = values;
  }

  return ordered;
}

/**
 * The folders of `srcDir`, in listing order, whose own listing holds one of
 * `names`: the only folders a probe for `<folder>/<name>` can find. Inside an
 * operation each listing is read once, for every name. Outside one, every
 * folder is returned, so each probe reads the disk.
 * @param {string} srcDir
 * @param {fs.Dirent[]} entries `srcDir`'s listing
 * @param {string[]} names
 * @returns {fs.Dirent[]}
 */
function foldersHolding(srcDir, entries, names) {
  const folders = entries.filter(entry => entry.isDirectory());
  if (!listingCacheActive()) return folders;
  const byName = oncePerListing(`folder-names\0${srcDir}`, () => {
    /** @type {Map<string, Set<string>>} */
    const index = new Map();
    for (const folder of folders) {
      let listed;
      try {
        listed = listDir(path.join(srcDir, folder.name));
      } catch {
        continue;
      }
      for (const name of listed) {
        let holders = index.get(name);
        if (!holders) index.set(name, (holders = new Set()));
        holders.add(folder.name);
      }
    }
    return index;
  });
  return folders.filter(folder =>
    names.some(name => byName.get(name)?.has(folder.name)),
  );
}

/**
 * Find the .doc.mjs file for a component.
 * For sub-components (e.g. StackItem), returns the parent's .doc.mjs
 * if the sub-component is documented there.
 * @param {string} coreDir
 * @param {string} name
 * @returns {string | null}
 */
export function findComponentReadme(coreDir, name) {
  const srcDir = path.join(coreDir, 'src');
  const exactDoc = `${name}.doc.mjs`;
  const xdsDoc = `XDS${name}.doc.mjs`;

  // Direct match: src/{name}/{Name}.doc.mjs or src/{name}/Astryx{Name}.doc.mjs
  const direct = path.join(srcDir, name, exactDoc);
  if (existsCaseExact(direct, srcDir)) return direct;
  const directXds = path.join(srcDir, name, xdsDoc);
  if (existsCaseExact(directXds, srcDir)) return directXds;

  // Nested match: src/*/{name}/{Name}.doc.mjs or src/*/{name}/Astryx{Name}.doc.mjs
  const entries = listDirEntries(srcDir);
  for (const entry of foldersHolding(srcDir, entries, [name])) {
    const nested = path.join(srcDir, entry.name, name, exactDoc);
    if (existsCaseExact(nested, srcDir)) return nested;
    const nestedXds = path.join(srcDir, entry.name, name, xdsDoc);
    if (existsCaseExact(nestedXds, srcDir)) return nestedXds;
  }

  // Per-component doc in a parent directory: src/*/{Name}.doc.mjs or src/*/Astryx{Name}.doc.mjs
  for (const entry of foldersHolding(srcDir, entries, [exactDoc, xdsDoc])) {
    const perComp = path.join(srcDir, entry.name, exactDoc);
    if (existsCaseExact(perComp, srcDir)) return perComp;
    const perCompXds = path.join(srcDir, entry.name, xdsDoc);
    if (existsCaseExact(perCompXds, srcDir)) return perCompXds;
  }

  // Sub-component fallback: find the source file, then walk up
  // looking for any .doc.mjs in the same or parent directories
  const sourcePath = findComponentSource(coreDir, name);
  if (sourcePath) {
    let dir = path.dirname(sourcePath);
    while (dir.startsWith(srcDir)) {
      const dirEntries = listDir(dir);
      for (const f of dirEntries) {
        if (f.endsWith('.doc.mjs')) return path.join(dir, f);
      }
      dir = path.dirname(dir);
    }
  }

  // A component with its own folder, documented as a member of its family's
  // doc (HStack and VStack in Stack's doc).
  if (hasOwnFolder(srcDir, name)) return findFamilyDoc(srcDir, name);

  return null;
}

/**
 * Find the main source file for a component (Astryx*.tsx, excluding tests).
 * For "Button" finds src/Button/XDSButton.tsx
 * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx
 * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)
 *
 * Hooks and other functions are authored as `.ts` (e.g. `useMediaQuery.ts`,
 * `useResizable.ts`), so `.ts` candidates are searched alongside `.tsx`. Without
 * this, deriving the import path for a `.ts`-authored function falls back to the
 * bare `@astryxdesign/core` root instead of its tree-shakeable subpath.
 * @param {string} coreDir
 * @param {string} name
 * @returns {string | null}
 */
export function findComponentSource(coreDir, name) {
  const found = ownSourceFile(coreDir, name);
  if (found == null) return null;
  // A component's exact name in another case (`tokenizer` for Tokenizer) is
  // that component's. A module that only shares the spelling, such as
  // `CodeBlock/tokenizer.ts`, never stands for it.
  return caseSpelledComponentSource(path.join(coreDir, 'src'), name) == null
    ? found
    : null;
}

/**
 * The file named for `name` in `src/`, found as {@link findComponentSource}
 * describes, before the case-spelling check.
 * @param {string} coreDir
 * @param {string} name
 * @returns {string | null}
 */
function ownSourceFile(coreDir, name) {
  const srcDir = path.join(coreDir, 'src');
  const candidateFiles = ownFileNames(name);

  /**
   * @param {string} dirPath
   * @returns {string | null}
   */
  function searchDir(dirPath, listed = false) {
    // A folder from its parent's listing exists; only a starting folder
    // needs the check.
    if (!listed && !pathExists(dirPath)) return null;
    const entries = listDirEntries(dirPath);

    // Check for an exact match (prefixed or bare) first. The listing in hand
    // holds every name in the folder, so no name is probed on disk.
    for (const candidate of candidateFiles) {
      const entry = entries.find(e => e.name === candidate);
      if (!entry) continue;
      const exact = path.join(dirPath, candidate);
      if (!entry.isSymbolicLink() || pathExists(exact)) return exact;
    }

    // Recurse into subdirectories
    for (const entry of entries) {
      if (entry.isDirectory()) {
        const found = searchDir(path.join(dirPath, entry.name), true);
        if (found) return found;
      }
    }
    return null;
  }

  // Search in the component's directory
  const directDir = path.join(srcDir, name);
  if (existsCaseExact(directDir, srcDir)) {
    const found = searchDir(directDir);
    if (found) return found;
  }

  // Search nested (component might be under a parent dir)
  const entries = listDirEntries(srcDir);
  for (const entry of entries) {
    if (!entry.isDirectory()) continue;
    const nestedDir = path.join(srcDir, entry.name, name);
    if (existsCaseExact(nestedDir, srcDir)) {
      const found = searchDir(nestedDir);
      if (found) return found;
    }
  }

  // Fallback: search entire src tree for the file
  return searchDir(srcDir);
}

/**
 * The file names a component's own source can have. The `XDS` forms come
 * first, so an older prefixed file wins over a bare one. `.tsx` comes before
 * `.ts`, so a component wins over a same-named helper. `.ts` covers hooks and
 * functions.
 * @param {string} name
 * @returns {string[]}
 */
function ownFileNames(name) {
  return [`XDS${name}.tsx`, `${name}.tsx`, `XDS${name}.ts`, `${name}.ts`];
}

// A component's name (PascalCase) or a hook's (`use` followed by PascalCase).
const COMPONENT_OR_HOOK_NAME_RE = /^(?:use)?[A-Z][A-Za-z0-9]*$/;

/**
 * Every component or hook file in `src/`, by its stem in lower case: its
 * stem (without an `XDS` prefix) and its path. Built once per operation.
 * @param {string} srcDir
 * @returns {Map<string, Array<{stem: string, file: string}>>}
 */
function caseStemIndex(srcDir) {
  return oncePerListing(`case-stems\0${srcDir}`, () => {
    /** @type {Map<string, Array<{stem: string, file: string}>>} */
    const index = new Map();
    /** @param {string} dirPath */
    const visit = dirPath => {
      for (const entry of listDirEntries(dirPath)) {
        const entryPath = path.join(dirPath, entry.name);
        if (entry.isDirectory()) {
          if (entry.name !== '__tests__') visit(entryPath);
          continue;
        }
        const stem = /^(?:XDS)?(.+)\.tsx?$/.exec(entry.name)?.[1];
        if (stem == null || !COMPONENT_OR_HOOK_NAME_RE.test(stem)) continue;
        const key = stem.toLowerCase();
        index.set(key, [...(index.get(key) ?? []), {stem, file: entryPath}]);
      }
    };
    if (pathExists(srcDir)) visit(srcDir);
    return index;
  });
}

/**
 * The source of the component or hook whose exact name `name` spells in
 * another case. A file named for it, anywhere in `src/`, exports it, as
 * `TabList/Tab.tsx` exports Tab for `tab`. Null when no such file exists.
 * @param {string} srcDir
 * @param {string} name
 * @returns {string | null}
 */
function caseSpelledComponentSource(srcDir, name) {
  for (const {stem, file} of caseStemIndex(srcDir).get(name.toLowerCase()) ??
    []) {
    if (
      stem !== name &&
      (moduleExportsName(file, stem) || moduleExportsName(file, `XDS${stem}`))
    ) {
      return file;
    }
  }
  return null;
}

/**
 * Compute the Levenshtein (edit) distance between two strings.
 * Used for fuzzy-matching component names. Dependency-free.
 * @param {string} coreDir
 * @param {string} componentName
 * @returns {string}
 */
export function resolveImportPath(coreDir, componentName) {
  const srcDir = path.join(coreDir, 'src');
  const exportKeys = exportKeysOf(coreDir);

  // Priority 1: exact subpath export matching the component name (e.g. ./Heading)
  // This allows convenience re-export directories to win over the source directory.
  const exactMatch = exportKeys.find(
    k => k.toLowerCase() === `./${componentName}`.toLowerCase(),
  );
  if (exactMatch) {
    return `@astryxdesign/core/${exactMatch.slice(2)}`;
  }

  const sourcePath = findComponentSource(coreDir, componentName);
  if (!sourcePath) return '@astryxdesign/core';

  // Priority 2: subpath export matching the top-level source directory
  const relToSrc = path.relative(srcDir, sourcePath);
  const topDir = relToSrc.split(path.sep)[0];

  const topMatch = exportKeys.find(
    k => k.toLowerCase() === `./${topDir}`.toLowerCase(),
  );
  if (topMatch) {
    return `@astryxdesign/core/${topMatch.slice(2)}`;
  }

  return '@astryxdesign/core';
}

/**
 * The subpaths the package's `exports` map names, read once per operation:
 * a search resolves the import of every component.
 * @param {string} coreDir
 * @returns {string[]}
 */
function exportKeysOf(coreDir) {
  const pkgPath = path.join(coreDir, 'package.json');
  return oncePerListing(`export-keys\0${pkgPath}`, () => {
    const pkg = pathExists(pkgPath)
      ? JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
      : null;
    return Object.keys(pkg?.exports || {});
  });
}

/**
 * Does a package's `exports` map publish this subpath?
 *
 * Node matches a subpath either by an exact key or by a PATTERN key holding a
 * single `*`, which stands for any (possibly empty) run of characters — so
 * `./*` publishes `./Carousel` just as surely as a literal `./Carousel` key
 * does. A key whose target is `null` blocks the subpath instead of publishing
 * it, and a package with no map at all publishes nothing by subpath.
 *
 * Exact-key-only matching is why this is a function rather than a lookup: it
 * reported the bare package for every wildcard package, which is a specifier
 * that need not resolve at all when the package has no `.` export.
 *
 * @param {Record<string, unknown>|null|undefined} exportsMap
 * @param {string} subpath e.g. `./Carousel`
 * @returns {boolean}
 */
function exportsPublish(exportsMap, subpath) {
  if (!exportsMap || typeof exportsMap !== 'object') return false;
  if (subpath in exportsMap) return exportsMap[subpath] != null;
  for (const [key, target] of Object.entries(exportsMap)) {
    const star = key.indexOf('*');
    if (star === -1) continue;
    // One `*` per key, per the spec; a second is not a pattern.
    if (key.indexOf('*', star + 1) !== -1) continue;
    const prefix = key.slice(0, star);
    const suffix = key.slice(star + 1);
    if (
      subpath.length >= prefix.length + suffix.length &&
      subpath.startsWith(prefix) &&
      subpath.endsWith(suffix)
    ) {
      return target != null;
    }
  }
  return false;
}

/**
 * Resolve the specifier an integration component is imported from. An authored
 * doc import is canonical; otherwise resolve against the owning package's
 * `exports` map.
 *
 * A component lives in a directory that need not share its name — several
 * components can be exported from one entry point — so the specifier has to
 * come from the directory the doc file sits in, checked against `exports`,
 * rather than from the component name. Falls back to the package root when the
 * package does not publish that subpath, matching what a consumer would have
 * to write by hand.
 *
 * Lives here, beside {@link resolveImportPath}, because more than one surface
 * answers "where is this imported from" and they have to agree: `component`
 * reports it as ownership metadata and `search` reports it on every hit. When
 * each resolved it for itself the two disagreed, and an import specifier that
 * does not resolve is worse than no answer.
 *
 * `exportsMap` is the map `loadIntegrations` already parsed onto the loaded
 * integration, so the common path reads no manifest at all. `undefined` means
 * the caller has no parsed map — a record built by hand rather than by the
 * loader — and only then is the manifest read here. `null` means the loader
 * looked and the package has no `exports`, which is an answer, not a gap: it
 * must not trigger a read. Resolution that depended on every producer of a
 * record remembering to populate a field would degrade silently, and silently
 * is how this bug got here.
 *
 * @param {{exportsMap?: Record<string, unknown>|null, packageDir?: string, docPath?: string|null, packageName: string}} owner
 * @param {string} componentName
 * @param {string|null} [authoredImport]
 * @returns {string}
 */
export function resolveIntegrationImportPath(
  owner,
  componentName,
  authoredImport,
) {
  if (authoredImport) return authoredImport;
  const {exportsMap, packageDir, docPath, packageName} = owner;
  const map =
    exportsMap === undefined ? readPackageExports(packageDir) : exportsMap;
  const directory = docPath
    ? path.basename(path.dirname(docPath))
    : componentName;
  return exportsPublish(map, `./${directory}`)
    ? `${packageName}/${directory}`
    : packageName;
}

/**
 * Read a package's `exports` map from disk. The fallback for a loaded-
 * integration record that carries no parsed map; {@link loadIntegrations}
 * populates one for every integration it loads.
 *
 * @param {string|undefined} packageDir
 * @returns {Record<string, unknown>|null}
 */
function readPackageExports(packageDir) {
  if (!packageDir) return null;
  try {
    const manifest = JSON.parse(
      fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),
    );
    return manifest.exports ?? null;
  } catch {
    // An unreadable or malformed manifest is not worth failing a lookup over.
    return null;
  }
}

// ── External package discovery ───────────────────────────────────────

/**
 * Discover components from an external package's docs directory,
 * reading `group:` fields from each .doc.mjs for subcategories.
 *
 * Returns a Record<string, string[]> matching the shape of discoverComponents():
 * - Grouped components: `{ 'App Chrome': ['AppShell', 'SideNav', 'TopNav'] }`
 * - Ungrouped components: `{ 'Diff': ['Diff'] }`
 * @param {string} docsDir
 * @returns {Record<string, string[]>}
 */
export function discoverExternalComponentsGrouped(docsDir) {
  if (!pathExists(docsDir)) return {};

  /** @type {Map<string, string|null>} componentName → group */
  const componentGroups = new Map();

  /** @param {string} dirPath */
  function scanDir(dirPath) {
    const entries = listDirEntries(dirPath);
    for (const entry of entries) {
      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
      const fullPath = path.join(dirPath, entry.name);
      if (entry.isDirectory()) {
        scanDir(fullPath);
      } else if (entry.name.endsWith('.doc.mjs')) {
        const name = entry.name.replace('.doc.mjs', '');
        const {group, hidden} = readDocMeta(fullPath);
        if (!hidden) {
          componentGroups.set(name, group);
        }
      }
    }
  }

  scanDir(docsDir);

  // Build grouped result (same algorithm as discoverComponents)
  /** @type {Map<string, string[]>} */
  const groups = new Map();
  /** @type {string[]} */
  const ungrouped = [];

  for (const [name, group] of componentGroups) {
    if (group) {
      if (!groups.has(group)) groups.set(group, []);
      groups.get(group)?.push(name);
    } else {
      ungrouped.push(name);
    }
  }

  for (const members of groups.values()) {
    members.sort();
  }

  /** @type {Array<{key: string, values: string[]}>} */
  const entries = [];
  for (const [groupName, members] of groups) {
    entries.push({key: groupName, values: members});
  }
  for (const name of ungrouped) {
    entries.push({key: name, values: [name]});
  }
  entries.sort((a, b) => a.key.localeCompare(b.key));

  /** @type {Record<string, string[]>} */
  const ordered = {};
  for (const {key, values} of entries) {
    ordered[key] = values;
  }

  return ordered;
}

/**
 * Find a component's doc file in an external package's docs directory.
 * Returns the path to {Name}.doc.mjs or null.
 * @param {string} docsDir
 * @param {string} name
 * @returns {string | null}
 */
export function findExternalComponentDoc(docsDir, name) {
  if (!pathExists(docsDir)) return null;
  const target = `${name}.doc.mjs`;

  /**
   * @param {string} dirPath
   * @returns {string | null}
   */
  function scanDir(dirPath) {
    const entries = listDirEntries(dirPath);
    for (const entry of entries) {
      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
      const fullPath = path.join(dirPath, entry.name);
      if (entry.isDirectory()) {
        const found = scanDir(fullPath);
        if (found) return found;
      } else if (entry.name === target) {
        return fullPath;
      }
    }
    return null;
  }

  return scanDir(docsDir);
}

// ── Integration component discovery (ownership-aware) ────────────────
//
// Integration packages contribute a `components` root (resolved absolute path
// in `loadedIntegrations`, see lib/integrations.mjs). Each component uses a
// same-stem source/doc convention — e.g. `MetaAppShell.tsx` next to
// `MetaAppShell.doc.{ts,mjs,js}`. The doc file is authoritative for discovery;
// the sibling `.tsx` (if present) is the swizzleable source.
//
// Each discovered component is recorded with its OWNER package (the
// integration's package name) and the owner's `issuesUrl` so downstream
// commands — and the future integration-component swizzle — can disambiguate
// by package and route source/issues correctly.

// A doc's `name` can name another export of its file, and a family doc's full
// entries are components under their own names; every other doc reads as before.
const COMPONENT_NAME_RE = /^[A-Z][\w$]*$/;

/** @type {Map<string, {stamp: string, value: Record<string, any> | null}>} doc reads, reused while the doc file is unchanged */
const docReads = new Map();

/**
 * A file's identity for a cache: ctime and inode change on a rewrite even when
 * npm stamps the same size and mtime.
 * @param {string} file
 */
function fileStamp(file) {
  try {
    const {size, mtimeMs, ctimeMs, ino} = fs.statSync(file);
    return `${size}:${mtimeMs}:${ctimeMs}:${ino}`;
  } catch {
    return 'missing';
  }
}

/** UTF-16 code-unit order, the same in every locale. @param {string} a @param {string} b */
function byCodeUnit(a, b) {
  return a < b ? -1 : a > b ? 1 : 0;
}

/**
 * A component doc's exported object as plain data, read without running it.
 * @param {string} docPath
 * @returns {Record<string, any> | null}
 */
function docObject(docPath) {
  const stamp = fileStamp(docPath);
  const cached = docReads.get(docPath);
  if (cached?.stamp === stamp) return cached.value;
  const value = staticExportObject(docPath, DOC_EXPORTS.components);
  docReads.set(docPath, {stamp, value});
  return value;
}

/** @param {string} docPath */
export function docStem(docPath) {
  return path.basename(docPath).replace(/\.doc\.(ts|mjs|js)$/, '');
}

/**
 * The export a component doc names when its same-stem source is not named
 * after an export, or null to keep the stem.
 * @param {{docPath: string, sourcePath: string|null, stem: string, names: string[]}} doc
 *   `names`: top-level names a quick scan found (none: the doc is read)
 * @returns {string | null}
 */
function otherExportName({docPath, sourcePath, stem, names}) {
  if (sourcePath == null) return null;
  if (names.length > 0 && names.every(name => name === stem)) return null;
  const name = docObject(docPath)?.name;
  return typeof name === 'string' &&
    name !== stem &&
    COMPONENT_NAME_RE.test(name) &&
    moduleExportsName(sourcePath, name) &&
    !moduleExportsName(sourcePath, stem)
    ? name
    : null;
}

/**
 * The file Node loads for a package without `exports`: its `main`, else its
 * `index` file.
 * @param {string} packageDir
 * @returns {string | null}
 */
function packageMain(packageDir) {
  let main;
  try {
    main = JSON.parse(
      fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),
    ).main;
  } catch {
    return null;
  }
  const entry =
    typeof main === 'string' && main !== ''
      ? `./${path.posix.normalize(main).replace(/^\.\//, '')}`
      : './index';
  return inspectPackageExport({}, packageDir, entry).target;
}

/**
 * The local module a doc's import names: the doc's own `import`, else the
 * subpath its directory publishes, read through the package's `exports` (its
 * `main` when it has none). A subpath's `source` condition wins when its file
 * is in the package, so the answer does not depend on a build. Undefined when the package directory is unknown;
 * null when the import names another package or resolves to no file.
 *
 * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 * @param {string} docPath
 * @param {Record<string, any> | null} doc
 * @returns {string | null | undefined}
 */
export function importedModule(integration, docPath, doc) {
  const packageName = integration?.name;
  const packageDir = integration?.__packageDir;
  if (!packageName || !packageDir) return undefined;
  const exportsMap =
    integration.__packageExports === undefined
      ? readPackageExports(packageDir)
      : integration.__packageExports;
  const specifier = resolveIntegrationImportPath(
    {exportsMap, packageDir, docPath, packageName},
    docStem(docPath),
    typeof doc?.import === 'string' ? doc.import : null,
  );
  if (specifier !== packageName && !specifier.startsWith(`${packageName}/`)) {
    return null;
  }
  if (specifier === packageName && exportsMap == null) {
    return packageMain(packageDir);
  }
  const subpath =
    specifier === packageName
      ? '.'
      : `./${specifier.slice(packageName.length + 1)}`;
  const pkg = {name: packageName, exports: exportsMap ?? undefined};
  // The `source` condition first, when its file is there, so a family lists
  // the same members whether or not the package has been built.
  return (
    sourceExportTarget(pkg, packageDir, subpath) ??
    inspectPackageExport(pkg, packageDir, subpath).target
  );
}

/**
 * The file an import of the package's own name resolves to, through its
 * package.json `exports` (or `main` when it has none): `@acme/kit` or
 * `@acme/kit/widget`. Null when the specifier names another package, or the
 * package publishes nothing at it.
 * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown> | null}} integration
 * @param {string} specifier
 * @returns {string | null}
 */
export function ownPackageModule(integration, specifier) {
  const packageName = integration?.name;
  const packageDir = integration?.__packageDir;
  if (!packageName || !packageDir) return null;
  if (specifier !== packageName && !specifier.startsWith(`${packageName}/`)) {
    return null;
  }
  const exportsMap =
    integration.__packageExports === undefined
      ? readPackageExports(packageDir)
      : integration.__packageExports;
  if (specifier === packageName && exportsMap == null) {
    return packageMain(packageDir) ?? null;
  }
  const subpath =
    specifier === packageName
      ? '.'
      : `./${specifier.slice(packageName.length + 1)}`;
  return (
    inspectPackageExport(
      {name: packageName, exports: exportsMap ?? undefined},
      packageDir,
      subpath,
    ).target ?? null
  );
}

/**
 * Whether `file` sits in `folder` or below it.
 * @param {string} folder
 * @param {string} file
 */
function isWithin(folder, file) {
  const relative = path.relative(folder, file);
  return (
    relative !== '' &&
    !path.isAbsolute(relative) &&
    relative.split(path.sep)[0] !== '..'
  );
}

/**
 * The `.tsx` file in `folder`, or below it, that declares `name`, taking files
 * in path order: the source of a member whose import never reaches a `.tsx`
 * file, as when the import names built output.
 *
 * @param {string} folder
 * @param {string} name
 * @returns {string | null}
 */
export function folderSourceFor(folder, name) {
  /** @type {string[]} */
  const files = [];
  /** @param {string} dirPath */
  const scan = dirPath => {
    for (const entry of listDirEntries(dirPath)) {
      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
      if (entry.name.startsWith('.')) continue;
      const fullPath = path.join(dirPath, entry.name);
      if (entry.isDirectory()) scan(fullPath);
      else if (
        entry.name.endsWith('.tsx') &&
        !/\.(?:test|spec|stories)\.tsx$/.test(entry.name)
      ) {
        files.push(fullPath);
      }
    }
  };
  scan(folder);
  for (const file of files.sort(byCodeUnit)) {
    const declared = moduleExportSource(file, name);
    if (
      declared != null &&
      declared.endsWith('.tsx') &&
      isWithin(folder, declared)
    ) {
      return declared;
    }
  }
  return null;
}

/**
 * The full entries a family doc lists in `components` that the module its
 * import names exports, each with its source. An entry is full when it says
 * more than its `name`; the name must be static PascalCase, not hidden, and
 * neither the doc's stem nor the export the doc is recorded under. A member's
 * source is the `.tsx` file in the family doc's folder, or below it, that
 * declares it: the one the family's own source or the imported module reaches,
 * else the one in that folder that declares the name, as when the import names
 * built output. A member that only a bundle or a file outside the folder
 * declares has no source.
 *
 * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 * @param {{docPath: string, sourcePath: string|null}} record the doc's own
 * @param {string | null | undefined} ownName the export the doc is recorded
 *   under, when it names one
 * @param {string} [only] look for this member alone
 * @returns {Array<{name: string, sourcePath: string | null}>}
 */
function familyMembers(integration, record, ownName, only) {
  const familySource = record.sourcePath;
  const doc = docObject(record.docPath);
  const entries = Array.isArray(doc?.components) ? doc.components : [];
  const hidden = new Set(
    Array.isArray(doc?.hiddenComponents) ? doc.hiddenComponents : [],
  );
  const stem = docStem(record.docPath);
  /** @type {string[]} */
  const names = [];
  for (const entry of entries) {
    if (entry == null || typeof entry !== 'object') continue;
    const name = entry.name;
    const full = Object.keys(entry).length > 1 || entry[HAS_COMPUTED] === true;
    if (typeof name !== 'string' || !full) continue;
    if (!COMPONENT_NAME_RE.test(name) || hidden.has(name)) continue;
    if (name === stem || name === ownName) continue;
    if (only != null && name !== only) continue;
    names.push(name);
  }
  if (names.length === 0) return [];
  const imported = importedModule(integration, record.docPath, doc);
  const module = imported === undefined ? familySource : imported;
  if (module == null) return [];
  const folder = path.dirname(record.docPath);
  /** @param {string | null} file */
  const inFolder = file =>
    file != null && file.endsWith('.tsx') && isWithin(folder, file);
  return names.flatMap(name => {
    const exported = moduleExportSource(module, name);
    if (exported == null) return [];
    // A member's source is a `.tsx` file in the family's folder, as a doc's own
    // is: never a bundle, even one under a family at the package root.
    const reached = [
      familySource == null ? null : moduleExportSource(familySource, name),
      exported,
    ].find(inFolder);
    return [{name, sourcePath: reached ?? folderSourceFor(folder, name)}];
  });
}

/**
 * Each family doc under an integration's components root that names an
 * import, with the file the import resolves to: null when it resolves to none,
 * such as build output that does not exist yet.
 *
 * @param {{name: string, components?: string, issuesUrl?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 * @returns {Array<{docPath: string, module: string | null}>}
 */
export function familyImports(integration) {
  return discoverIntegrationComponents(integration).flatMap(record => {
    if (record.docPath == null || !isOwnRecord(record)) return [];
    const doc = docObject(record.docPath);
    if (!Array.isArray(doc?.components) || doc.components.length === 0) {
      return [];
    }
    const module = importedModule(integration, record.docPath, doc);
    return module === undefined ? [] : [{docPath: record.docPath, module}];
  });
}

/**
 * Whether `record` is its doc's own component (under the doc's stem or the
 * export its `name` documents) rather than a member the doc lists.
 *
 * @param {{name: string, docPath: string|null}} record
 * @returns {boolean}
 */
function isOwnRecord(record) {
  if (record.docPath == null) return true;
  const stem = docStem(record.docPath);
  if (stem === record.name) return true;
  return (
    otherExportName({
      docPath: record.docPath,
      sourcePath: integrationSourceForDoc(record.docPath),
      stem,
      names: [],
    }) === record.name
  );
}

/**
 * Whether a discovered integration record is a member its family doc lists,
 * decided from the files, not from whether the doc loads.
 *
 * @param {{name: string, docPath: string|null}} record
 * @returns {boolean}
 */
export function isIntegrationMember(record) {
  return !isOwnRecord(record);
}

/**
 * The entry a family doc gives a member that discovery lists under its own
 * name, or null when the record is the doc's own component or the loaded doc
 * has no entry for it.
 *
 * @param {any} doc the doc loaded from `record.docPath`
 * @param {{name: string, docPath: string|null}} record
 * @returns {any}
 */
export function integrationMemberEntry(doc, record) {
  if (doc == null || typeof doc !== 'object' || isOwnRecord(record)) {
    return null;
  }
  if (!Array.isArray(doc.components)) return null;
  return (
    doc.components.find(
      (/** @type {any} */ entry) => entry?.name === record.name,
    ) ?? null
  );
}

/**
 * Whether `dir` is a folder to list. A declared root that is a file is
 * reported by the root check; discovery finds nothing in it.
 * @param {string} dir
 */
function isFolder(dir) {
  try {
    return fs.statSync(dir).isDirectory();
  } catch {
    return false;
  }
}

/**
 * Visit every component doc under an integration's components root, hidden
 * ones included, in discovery order, with its stem.
 * @param {string | undefined} componentsDir
 * @param {(docPath: string, stem: string) => void} visit
 */
export function forEachIntegrationDoc(componentsDir, visit) {
  if (!componentsDir || !isFolder(componentsDir)) return;
  /** @param {string} name */
  const key = name => {
    const rank = INTEGRATION_DOC_SUFFIXES.findIndex(s => name.endsWith(s));
    return rank < 0
      ? {stem: name, rank}
      : {stem: name.slice(0, -INTEGRATION_DOC_SUFFIXES[rank].length), rank};
  };
  /** @param {string} dirPath */
  function scanDir(dirPath) {
    // Name order, and for two docs of one stem the suffix precedence, so the
    // doc a stem records is the one a lookup by name finds, on every disk.
    const entries = listDirEntries(dirPath).sort((a, b) => {
      const left = key(a.name);
      const right = key(b.name);
      return left.stem === right.stem
        ? left.rank - right.rank
        : byCodeUnit(left.stem, right.stem);
    });
    for (const entry of entries) {
      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
      const fullPath = path.join(dirPath, entry.name);
      if (entry.isDirectory()) {
        scanDir(fullPath);
        continue;
      }
      const suffix = INTEGRATION_DOC_SUFFIXES.find(s => entry.name.endsWith(s));
      if (suffix) visit(fullPath, entry.name.slice(0, -suffix.length));
    }
  }
  scanDir(componentsDir);
}

/**
 * Given an integration component doc path, return the sibling component source
 * (`{Name}.tsx`) if one exists, else null.
 *
 * @param {string} docPath absolute path to a `{Name}.doc.{ts,mjs,js}` file
 * @returns {string|null}
 */
export function integrationSourceForDoc(docPath) {
  const dir = path.dirname(docPath);
  const base = path.basename(docPath).replace(/\.doc\.(ts|mjs|js)$/, '');
  const candidate = path.join(dir, `${base}.tsx`);
  return pathExists(candidate) ? candidate : null;
}

/**
 * Discover ownership records for the components contributed by a single loaded
 * integration. Scans the integration's resolved `components` dir for same-stem
 * doc files and records each with owner package + issuesUrl + sourcePath. A doc
 * that names a differently named export of its file is recorded under that
 * export, and each family member it lists, under the member's name, unless the
 * name is taken: every doc's file name (a hidden doc's too), a Core name a doc
 * in the package replaces, and a name an earlier doc records.
 *
 * @param {{name: string, components?: string, issuesUrl?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 *   a single entry from `loadedIntegrations` (lib/integrations.mjs)
 * @param {{documentedNames?: boolean}} [options] `documentedNames: false`
 *   records each doc under its file name alone, without reading the names
 *   docs document: for a caller that needs only what each doc says
 * @returns {Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>}
 */
export function discoverIntegrationComponents(
  integration,
  {documentedNames = true} = {},
) {
  const componentsDir = integration?.components;
  if (!componentsDir || !isFolder(componentsDir)) return [];

  /** @type {Map<string, {name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>} */
  const byName = new Map();
  /** @type {Map<string, {names: string[], hasMembers: boolean, replaces: string | null}>} stem → quick scan */
  const scans = new Map();
  /** @type {Set<string>} names no doc can record under another name */
  const taken = new Set();

  forEachIntegrationDoc(componentsDir, (fullPath, name) => {
    taken.add(name);
    const {group, hidden, names, hasMembers, replaces} = readDocMeta(fullPath);
    if (hidden) return;
    // First doc wins per name (precedence matches INTEGRATION_DOC_SUFFIXES).
    if (byName.has(name)) return;
    byName.set(name, {
      name,
      package: integration.name,
      docPath: fullPath,
      sourcePath: integrationSourceForDoc(fullPath),
      issuesUrl: integration.issuesUrl,
      group: group ?? null,
    });
    scans.set(name, {names, hasMembers, replaces});
  });
  if (!documentedNames) return [...byName.values()];

  // A doc that names a differently named export of its file is listed under
  // that export, and each member a family doc lists under the member's name,
  // unless the name is taken.
  for (const {replaces} of scans.values()) if (replaces) taken.add(replaces);
  const records = [...byName.values()];
  const byPath = [...records].sort((a, b) => byCodeUnit(a.docPath, b.docPath));
  /** @type {Map<string, string>} stem → export name */
  const exportNames = new Map();
  for (const record of byPath) {
    const exportName = otherExportName({
      ...record,
      stem: record.name,
      names: scans.get(record.name)?.names ?? [],
    });
    if (exportName == null || taken.has(exportName)) continue;
    taken.add(exportName);
    exportNames.set(record.name, exportName);
  }
  /** @type {typeof records} */
  const members = [];
  for (const record of byPath) {
    if (!scans.get(record.name)?.hasMembers) continue;
    const ownName = exportNames.get(record.name);
    for (const member of familyMembers(integration, record, ownName)) {
      if (taken.has(member.name)) continue;
      taken.add(member.name);
      members.push({...record, ...member});
    }
  }
  const named = records.map(record => {
    const name = exportNames.get(record.name);
    return name ? {...record, name} : record;
  });
  return [...named, ...members];
}

/**
 * Load and validate every discovered integration component independently.
 * Invalid metadata or a missing same-stem source removes only that component;
 * callers can report the returned errors while retaining valid siblings. A
 * component whose doc sets `replaces` carries the value as written; the
 * component replacement resolver decides what it means. A family member is
 * read through its family's doc: it never carries the family's `replaces`, and
 * a family doc that fails to load is reported once. A doc that fails to load
 * is reported under its file name: what it says cannot be trusted.
 *
 * @param {{name: string, components?: string, issuesUrl?: string}} integration
 * @param {{documentedNames?: boolean}} [options] as for
 *   {@link discoverIntegrationComponents}
 * @returns {Promise<{
 *   components: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>,
 *   discovered: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>,
 *   errors: Array<{name: string, message: string}>,
 * }>}
 */
export async function discoverValidIntegrationComponents(integration, options) {
  const discovered = discoverIntegrationComponents(integration, options);
  /** @type {Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>} */
  const components = [];
  /** @type {Array<{name: string, message: string}>} */
  const errors = [];
  /** @type {Set<string>} docs that failed to load */
  const failedDocs = new Set();

  for (const record of discovered) {
    // A doc's own component needs its same-stem source. A member has none when
    // only a bundle or a file outside its family's folder declares it.
    if (record.sourcePath == null && isOwnRecord(record)) {
      errors.push({
        name: record.name,
        message: `Component "${record.name}" is missing its same-stem source file ${record.name}.tsx.`,
      });
      continue;
    }
    try {
      const doc = await loadComponentDoc(record.docPath);
      const valid =
        /** @type {{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}} */ (
          record
        );
      components.push(
        isOwnRecord(record) &&
          doc != null &&
          typeof doc === 'object' &&
          doc.replaces !== undefined
          ? {...valid, replaces: doc.replaces}
          : valid,
      );
    } catch (err) {
      if (failedDocs.has(record.docPath)) continue;
      failedDocs.add(record.docPath);
      const name = docStem(record.docPath);
      errors.push({
        name,
        message: `Component "${name}" has invalid metadata: ${
          err instanceof Error ? err.message : String(err)
        }`,
      });
    }
  }

  return {components, discovered, errors};
}

/**
 * How an owner holds a component name, which the owner rule
 * ({@link unscopedComponentOwners}) reads: `core` when Core documents it;
 * `file` when an integration doc named after its file is recorded under it;
 * `doc` when only a doc records it: an export name, a member, or the file name
 * of a doc recorded under another export.
 * @typedef {'core' | 'file' | 'doc'} NameHold
 */

/**
 * How a discovered integration record holds its name.
 * @param {{name: string, docPath: string|null}} record
 * @returns {'file' | 'doc'}
 */
export function integrationRecordHold(record) {
  return record.docPath == null || docStem(record.docPath) === record.name
    ? 'file'
    : 'doc';
}

/**
 * The doc that records `name` as its export or a member though its file is
 * named otherwise, with the source, reading only docs that write the name.
 *
 * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 * @param {string} componentsDir
 * @param {string} name
 * @returns {{docPath: string, sourcePath: string|null} | null}
 */
function findDocumentedComponent(integration, componentsDir, name) {
  if (!COMPONENT_NAME_RE.test(name)) return null;
  const literals = [`'${name}'`, `"${name}"`, `\`${name}\``];
  /** @type {Set<string>} */
  const stems = new Set();
  /** @type {Array<{docPath: string, stem: string, names: string[], hasMembers: boolean, replaces: string | null, sourcePath: string|null}>} */
  const candidates = [];
  forEachIntegrationDoc(componentsDir, (docPath, stem) => {
    let text;
    try {
      text = fs.readFileSync(docPath, 'utf-8');
    } catch {
      return;
    }
    // The docs discovery records: the first visible doc for each stem.
    if (HIDDEN_RE.test(text) || stems.has(stem)) return;
    stems.add(stem);
    if (!literals.some(literal => text.includes(literal))) return;
    candidates.push({
      docPath,
      stem,
      ...scanDocText(text),
      sourcePath: integrationSourceForDoc(docPath),
    });
  });
  // A Core name a doc in the package replaces is the replacement's to answer.
  if (candidates.some(candidate => candidate.replaces === name)) return null;
  candidates.sort((a, b) => byCodeUnit(a.docPath, b.docPath));
  for (const candidate of candidates) {
    if (otherExportName(candidate) === name) {
      return {docPath: candidate.docPath, sourcePath: candidate.sourcePath};
    }
  }
  for (const candidate of candidates) {
    if (!candidate.hasMembers) continue;
    const ownName = otherExportName(candidate);
    const [member] = familyMembers(integration, candidate, ownName, name);
    if (member) {
      return {docPath: candidate.docPath, sourcePath: member.sourcePath};
    }
  }
  return null;
}

/**
 * The integration component a name finds, as discovery records it, and its
 * hold: the same-stem doc first, then a doc that records the name as an export
 * or a member.
 *
 * @param {{name?: string, components?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 * @param {string} name
 * @returns {{docPath: string, sourcePath: string|null, hold: 'file' | 'doc'} | null}
 */
export function findIntegrationComponent(integration, name) {
  const componentsDir = integration?.components;
  if (!componentsDir || !isFolder(componentsDir)) return null;
  const sameStem = findSameStemDoc(componentsDir, name);
  if (sameStem) {
    const exportName = otherExportName({
      docPath: sameStem,
      sourcePath: integrationSourceForDoc(sameStem),
      stem: name,
      names: readDocMeta(sameStem).names,
    });
    const renamed =
      exportName != null &&
      findSameStemDoc(componentsDir, exportName) == null &&
      findDocumentedComponent(integration, componentsDir, exportName)
        ?.docPath === sameStem;
    return {
      docPath: sameStem,
      sourcePath: integrationSourceForDoc(sameStem),
      hold: renamed ? 'doc' : 'file',
    };
  }
  const found = findDocumentedComponent(integration, componentsDir, name);
  return found && {...found, hold: 'doc'};
}

/**
 * The name discovery records a component doc under: the export its `name`
 * documents when the doc is recorded under it, else the doc's file name.
 *
 * @param {{name?: string, components?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 * @param {string} docPath
 * @returns {string}
 */
export function recordedDocName(integration, docPath) {
  const stem = docStem(docPath);
  const found = findIntegrationComponent(integration, stem);
  if (found?.docPath !== docPath || found.hold !== 'doc') return stem;
  return (
    otherExportName({
      docPath,
      sourcePath: integrationSourceForDoc(docPath),
      stem,
      names: readDocMeta(docPath).names,
    }) ?? stem
  );
}

/**
 * Find an integration component's doc file by name within a loaded
 * integration's resolved `components` dir. Honors the same-stem convention
 * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`, and finds a
 * doc that records the component under another name: a differently named
 * export of its file, or a member its family doc lists.
 *
 * @param {{name?: string, components?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 * @param {string} name bare component name (no `XDS`/`Astryx` prefix)
 * @returns {string|null}
 */
export function findIntegrationComponentDoc(integration, name) {
  return findIntegrationComponent(integration, name)?.docPath ?? null;
}

/**
 * The first `{Name}.doc.{ts,mjs,js}` under `componentsDir`, shallowest first.
 * @param {string} componentsDir
 * @param {string} name
 * @returns {string|null}
 */
function findSameStemDoc(componentsDir, name) {
  /**
   * @param {string} dirPath
   * @returns {string | null}
   */
  function scanDir(dirPath) {
    const entries = listDirEntries(dirPath);
    // Exact same-stem match (precedence order) first in this dir.
    for (const suffix of INTEGRATION_DOC_SUFFIXES) {
      const candidate = path.join(dirPath, `${name}${suffix}`);
      if (pathExists(candidate)) return candidate;
    }
    for (const entry of entries) {
      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
      if (entry.isDirectory()) {
        const found = scanDir(path.join(dirPath, entry.name));
        if (found) return found;
      }
    }
    return null;
  }

  return scanDir(componentsDir);
}

/**
 * Find an integration component's swizzleable source file by name within a
 * loaded integration's resolved `components` dir: the same-stem `{Name}.tsx`
 * of its doc, or, for a family member, the file that declares it. Returns null
 * when the integration ships docs without source.
 *
 * @param {{name?: string, components?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
 * @param {string} name bare component name
 * @returns {string|null}
 */
export function findIntegrationComponentSource(integration, name) {
  return findIntegrationComponent(integration, name)?.sourcePath ?? null;
}

/**
 * The owner rule: an owner that holds a name only because a doc records it
 * (`hold: 'doc'`) yields to Core and to every file-named owner; `--package`
 * still reaches it. Surfaces resolve a replacement first, then this rule, then
 * which docs load.
 *
 * @template {{hold?: string}} T
 * @param {T[]} owners each with its {@link NameHold}; an owner without one
 *   counts as Core's or file-named
 * @returns {T[]}
 */
export function unscopedComponentOwners(owners) {
  const primary = owners.filter(owner => owner.hold !== 'doc');
  return primary.length > 0 ? primary : owners;
}

/**
 * Build a flat list of ownership records for ALL discoverable components —
 * core (built-in) plus every loaded integration. This is the authoritative
 * source for package-aware listing and disambiguation.
 *
 * Core records carry `package: '@astryxdesign/core'`, `issuesUrl: undefined`
 * (the default core issues URL), and the resolved `.tsx` source via
 * findComponentSource(). Integration records carry their owner package name,
 * the manifest `issuesUrl`, and the same-stem `.tsx` source if present.
 *
 * @param {string} coreDir
 * @param {Array<{name: string, components?: string, issuesUrl?: string}>} [loadedIntegrations]
 * @returns {Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>}
 */
export function discoverOwnedComponents(coreDir, loadedIntegrations = []) {
  // Read-only: one listing of each folder serves the whole discovery.
  return withListingCache(() => ownedComponents(coreDir, loadedIntegrations));
}

/**
 * @param {string} coreDir
 * @param {Array<{name: string, components?: string, issuesUrl?: string}>} loadedIntegrations
 * @returns {Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>}
 */
function ownedComponents(coreDir, loadedIntegrations) {
  /** @type {Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>} */
  const records = [];

  // Core components — derive group from discoverComponents (grouped record).
  const grouped = discoverComponents(coreDir);
  /** @type {Map<string, string|null>} name → group */
  const coreGroup = new Map();
  for (const [key, members] of Object.entries(grouped)) {
    const isUngrouped = members.length === 1 && members[0] === key;
    for (const name of members) {
      coreGroup.set(name, isUngrouped ? null : key);
    }
  }
  for (const [name, group] of coreGroup) {
    records.push({
      name,
      package: CORE_PACKAGE,
      group,
      docPath: findComponentReadme(coreDir, name),
      sourcePath: findComponentSource(coreDir, name),
      issuesUrl: undefined,
    });
  }

  // Integration components.
  for (const integration of loadedIntegrations) {
    for (const rec of discoverIntegrationComponents(integration)) {
      records.push(rec);
    }
  }

  return records;
}

// ── Legacy markdown-parsing functions ────────────────────────────────
// These are kept for backward compatibility with existing tests.
// The CLI action handler uses the new format functions below instead.

/**
 * Minimal cleanup for full docs (default mode).
 * Strips SYNC comments, rewrites title, collapses blank lines.
 */