@astryxdesign/cli 0.7.2-canary.e2909cf → 0.7.2-canary.e4bdd70

package/foundation/discovery/component-discovery.mjs

@@ -7,10 +7,18 @@
 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, pathExists} 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} from './package-exports.mjs';
 
 const require = createRequire(import.meta.url);
 
@@ -82,12 +90,40 @@ function componentNameFromFile(fileName) {
 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,
+  };
+}
 
 /**
  * Read the `group`, `hiddenComponents`, and `hidden` fields from a
- * component's .doc.mjs file (synchronous).
+ * 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}}
+ * @returns {{group: string | null, hiddenComponents: Set<string>, hidden: boolean, names: string[], hasMembers: boolean, replaces: string | null}}
  */
 function readDocMeta(docPath) {
   try {
@@ -106,9 +142,17 @@ function readDocMeta(docPath) {
       group: groupMatch ? groupMatch[1] : null,
       hiddenComponents: hiddenSet,
       hidden,
+      ...scanDocText(content),
     };
   } catch {
-    return {group: null, hiddenComponents: new Set(), hidden: false};
+    return {
+      group: null,
+      hiddenComponents: new Set(),
+      hidden: false,
+      names: [],
+      hasMembers: false,
+      replaces: null,
+    };
   }
 }
 
@@ -148,9 +192,12 @@ function docMemberNames(source) {
   let ast;
   try {
     babelParser ??= require('@babel/parser');
-    ast = /** @type {typeof import('@babel/parser')} */ (babelParser).parse(source, {
-      sourceType: 'module',
-    });
+    ast = /** @type {typeof import('@babel/parser')} */ (babelParser).parse(
+      source,
+      {
+        sourceType: 'module',
+      },
+    );
   } catch {
     return [];
   }
@@ -165,12 +212,16 @@ function docMemberNames(source) {
       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') {
+        if (
+          node.type === 'ExportNamedDeclaration' &&
+          declarator.id.name === 'docs'
+        ) {
           docsExport = declarator.init;
         }
       }
     }
-    if (node.type === 'ExportDefaultDeclaration') defaultExport = node.declaration;
+    if (node.type === 'ExportDefaultDeclaration')
+      defaultExport = node.declaration;
   }
   let doc = defaultExport ?? docsExport;
   if (doc?.type === 'Identifier') doc = constants.get(doc.name);
@@ -388,7 +439,9 @@ export function discoverComponents(coreDir) {
     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'))) {
+    if (
+      listDir(path.join(srcDir, name)).some(file => file.endsWith('.doc.mjs'))
+    ) {
       continue;
     }
     if (!hasOwnFolder(srcDir, name)) continue;
@@ -843,6 +896,345 @@ export function findExternalComponentDoc(docsDir, name) {
 // 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). 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}
+ */
+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)}`;
+  return inspectPackageExport(
+    {name: packageName, exports: exportsMap ?? undefined},
+    packageDir,
+    subpath,
+  ).target;
+}
+
+/**
+ * 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
+  );
+}
+
+/**
+ * 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 || !pathExists(componentsDir)) return;
+  /** @param {string} dirPath */
+  function scanDir(dirPath) {
+    for (const entry of listDirEntries(dirPath)) {
+      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.
@@ -850,7 +1242,7 @@ export function findExternalComponentDoc(docsDir, name) {
  * @param {string} docPath absolute path to a `{Name}.doc.{ts,mjs,js}` file
  * @returns {string|null}
  */
-function integrationSourceForDoc(docPath) {
+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`);
@@ -860,49 +1252,85 @@ function integrationSourceForDoc(docPath) {
 /**
  * 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.
+ * 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}} integration
+ * @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) {
+export function discoverIntegrationComponents(
+  integration,
+  {documentedNames = true} = {},
+) {
   const componentsDir = integration?.components;
   if (!componentsDir || !pathExists(componentsDir)) return [];
 
   /** @type {Map<string, {name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>} */
   const byName = 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);
-        continue;
-      }
-      const suffix = INTEGRATION_DOC_SUFFIXES.find(s => entry.name.endsWith(s));
-      if (!suffix) continue;
-      const name = entry.name.slice(0, -suffix.length);
-      const {group, hidden} = readDocMeta(fullPath);
-      if (hidden) continue;
-      // First doc wins per name (precedence matches INTEGRATION_DOC_SUFFIXES).
-      if (byName.has(name)) continue;
-      byName.set(name, {
-        name,
-        package: integration.name,
-        docPath: fullPath,
-        sourcePath: integrationSourceForDoc(fullPath),
-        issuesUrl: integration.issuesUrl,
-        group: group ?? null,
-      });
+  /** @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});
     }
   }
-
-  scanDir(componentsDir);
-  return [...byName.values()];
+  const named = records.map(record => {
+    const name = exportNames.get(record.name);
+    return name ? {...record, name} : record;
+  });
+  return [...named, ...members];
 }
 
 /**
@@ -910,24 +1338,33 @@ export function discoverIntegrationComponents(integration) {
  * 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.
+ * 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, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>,
+ *   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) {
-  const discovered = discoverIntegrationComponents(integration);
-  /** @type {Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>} */
+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) {
-    if (record.sourcePath == null) {
+    // 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.`,
@@ -937,18 +1374,24 @@ export async function discoverValidIntegrationComponents(integration) {
     try {
       const doc = await loadComponentDoc(record.docPath);
       const valid =
-        /** @type {{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null}} */ (
+        /** @type {{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}} */ (
           record
         );
       components.push(
-        doc != null && typeof doc === 'object' && doc.replaces !== undefined
+        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: record.name,
-        message: `Component "${record.name}" has invalid metadata: ${
+        name,
+        message: `Component "${name}" has invalid metadata: ${
           err instanceof Error ? err.message : String(err)
         }`,
       });
@@ -958,19 +1401,158 @@ export async function discoverValidIntegrationComponents(integration) {
   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 || !pathExists(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`.
+ * (`{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 {{components?: string}} integration
+ * @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) {
-  const componentsDir = integration?.components;
-  if (!componentsDir || !pathExists(componentsDir)) return null;
+  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}
@@ -996,18 +1578,33 @@ export function findIntegrationComponentDoc(integration, name) {
 }
 
 /**
- * Find an integration component's swizzleable source file (`{Name}.tsx`) by
- * name within a loaded integration's resolved `components` dir. Returns null
+ * 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 {{components?: string}} integration
+ * @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) {
-  const docPath = findIntegrationComponentDoc(integration, name);
-  if (!docPath) return null;
-  return integrationSourceForDoc(docPath);
+  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;
 }
 
 /**