@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/foundation/config/theme-state.mjs

@@ -16,6 +16,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 export const LOCAL_THEME_ROOT = './src/themes';
 export const THEME_MODULE_BASENAME = 'astryx-themes';
@@ -106,7 +107,7 @@ export function themeModuleCandidates(projectDir) {
 function validThemeRecord(value, label) {
   if (!isRecord(value) || !isRecord(value.themes)) {
     throw new ThemeStateError(
-      `${label} must carry a static ${THEME_RECORD_MARKER} header. Regenerate it with \`astryx theme add <slug>\`.`,
+      `${label} must carry a static ${THEME_RECORD_MARKER} header. Regenerate it with \`${formatCliCommand('theme add <slug>')}\`.`,
     );
   }
   const keys = Object.keys(value);
@@ -139,7 +140,7 @@ function validThemeRecord(value, label) {
     !THEME_SLUG_RE.test(value.defaultThemeSlug)
   ) {
     throw new ThemeStateError(
-      `${label} defaultThemeSlug must be a lowercase kebab-case slug. Regenerate it with \`astryx theme use <slug>\`.`,
+      `${label} defaultThemeSlug must be a lowercase kebab-case slug. Regenerate it with \`${formatCliCommand('theme use <slug>')}\`.`,
     );
   }
   return {themes, defaultSlug: value.defaultThemeSlug};
@@ -159,7 +160,7 @@ export function parseThemeModuleRecord(source, label = 'theme module') {
     .filter(line => /^\s*\*\s*@astryx-theme-record\s+/u.test(line));
   if (recordLines.length !== 1) {
     throw new ThemeStateError(
-      `${label} must carry exactly one static ${THEME_RECORD_MARKER} header. Regenerate it with \`astryx theme add <slug>\`.`,
+      `${label} must carry exactly one static ${THEME_RECORD_MARKER} header. Regenerate it with \`${formatCliCommand('theme add <slug>')}\`.`,
     );
   }
   const payload = recordLines[0].replace(
@@ -318,7 +319,7 @@ export function readThemeState(cwd = process.cwd()) {
 export function renderThemeModule(themes, defaultSlug, typescript) {
   if (!themes.some(theme => theme.slug === defaultSlug)) {
     throw new ThemeStateError(
-      `Default theme "${defaultSlug}" is not added. Run \`astryx theme add ${defaultSlug}\` first.`,
+      `Default theme "${defaultSlug}" is not added. Run \`${formatCliCommand(`theme add ${defaultSlug}`)}\` first.`,
     );
   }
   /** @type {string[]} */

package/foundation/discovery/authoring-self-docs.d.mts

@@ -83,5 +83,12 @@ export function auditAuthoringSelfDocs({ root, sources, budget, }?: {
 }>;
 /** The directory the self-docs live under. */
 export const AUTHORING_ROOT: string;
+/** The guide that holds every authoring schema, one section each. */
+export const AUTHORING_REFERENCE_NAME: "field-reference";
+/**
+ * Its route. `astryx docs authoring <name>` reads one of its sections through
+ * the authoring namespace (spec:AST-046 FR6).
+ */
+export const AUTHORING_REFERENCE_ROUTE: "authoring/field-reference";
 /** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
 export const AUTHORING_SELF_DOCS: string[];

package/foundation/discovery/authoring-self-docs.mjs

@@ -9,7 +9,7 @@
  *   `authoring` reference topic with one section per self-doc, and an audit
  *   naming any self-doc the topic cannot reach, any that fails to load, and any
  *   section over the docs output budget.
- * @position Read by assets/docs/authoring.doc.mjs (the topic) and by Doctor
+ * @position Read by assets/docs/tree/field-reference.doc.mjs (the guide) and by Doctor
  *   (the audit). Lives in foundation because authoring/ holds only contracts.
  *   A new `*.doc.mjs` under authoring/ must be added to the list, or Doctor and
  *   the self-doc tests fail.
@@ -27,6 +27,15 @@ import {
 /** The directory the self-docs live under. */
 export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
 
+/** The guide that holds every authoring schema, one section each. */
+export const AUTHORING_REFERENCE_NAME = 'field-reference';
+
+/**
+ * Its route. `astryx docs authoring <name>` reads one of its sections through
+ * the authoring namespace (spec:AST-046 FR6).
+ */
+export const AUTHORING_REFERENCE_ROUTE = `authoring/${AUTHORING_REFERENCE_NAME}`;
+
 /** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
 export const AUTHORING_SELF_DOCS = [
   'integration/integration.doc.mjs',
@@ -46,6 +55,7 @@ export const AUTHORING_SELF_DOCS = [
   'doctypes/reference/reference.doc.mjs',
   'doctypes/schema/schema.doc.mjs',
   'doctypes/template/template.doc.mjs',
+  'doctypes/template/integration-template.doc.mjs',
   'doctypes/theme/theme.doc.mjs',
 ];
 
@@ -188,11 +198,14 @@ export function selfDocSection(doc) {
  */
 export function buildAuthoringReferenceDoc(docs) {
   return /** @type {any} */ ({
-    name: 'authoring',
-    title: 'Authoring Reference',
+    type: 'generic',
+    name: AUTHORING_REFERENCE_NAME,
+    placement: {parent: 'namespace:authoring', slot: 'reference', order: 10},
+    title: 'Field reference',
     category: 'guide',
+    keywords: ['authoring reference', 'field reference', 'every field'],
     description:
-      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
+      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The guides that use them are the rest of {@link namespace:authoring}.',
     sections: docs.map(selfDocSection),
   });
 }

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -38,20 +38,32 @@ describe('authoring self-docs', () => {
     });
   });
 
-  it('builds a valid topic with one section per self-doc', async () => {
-    const topic = await buildAuthoringTopic();
+  it('builds a valid guide with one section per self-doc, placed under authoring', async () => {
+    const {placement, ...topic} = await buildAuthoringTopic();
     expect(problemsInTopic(topic)).toEqual([]);
     expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
+    expect(placement).toEqual({
+      parent: 'namespace:authoring',
+      slot: 'reference',
+      order: 10,
+    });
   });
 
   it(
     'is readable progressively through the docs API',
     async () => {
-      const index = await docs('authoring', undefined, {index: true});
+      const index = await docs('authoring/field-reference', undefined, {
+        index: true,
+      });
       expect(index.type).toBe('docs.index');
       expect(index.data.sections.map(s => s.id)).toContain('integration');
+      // The namespace answers a section read from the field reference, as
+      // `astryx docs authoring <name>` always has.
       const section = await docs('authoring', 'integration');
       expect(section.data.title).toBe('Astryx Integration');
+      expect(
+        (await docs('authoring/field-reference', 'integration')).data,
+      ).toEqual(section.data);
       expect(section.data.content.some(block => block.type === 'table')).toBe(
         true,
       );

package/foundation/discovery/authoring-surface.d.mts

@@ -30,7 +30,7 @@ export function tracePublicAuthoringTypes(root?: string): {
  * document something public: a public type declared beside it, and, when its
  * title is the name of a type declared beside it, that type.
  * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
- *   `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ *   `topicKeys` are the keys `astryx docs authoring/field-reference --index` lists; null skips
  *   that comparison.
  * @returns {Promise<{
  *   types: number,

package/foundation/discovery/authoring-surface.mjs

@@ -7,7 +7,7 @@
  * @input authoring/index.d.ts and the type modules it re-exports, parsed with
  *   jscodeshift and never imported or type-checked (consumer installs have no
  *   TypeScript); the self-docs on disk and in AUTHORING_SELF_DOCS; and the
- *   section keys `astryx docs authoring --index` lists.
+ *   section keys `astryx docs authoring/field-reference --index` lists.
  * @output {@link tracePublicAuthoringTypes}: each exported type and the module
  *   that declares it. {@link auditAuthoringSurface}: each module whose exported
  *   types a reader cannot reach and why, each export that cannot be traced,
@@ -424,7 +424,7 @@ function declaredIn(t, folder, name) {
  * document something public: a public type declared beside it, and, when its
  * title is the name of a type declared beside it, that type.
  * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
- *   `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ *   `topicKeys` are the keys `astryx docs authoring/field-reference --index` lists; null skips
  *   that comparison.
  * @returns {Promise<{
  *   types: number,

package/foundation/discovery/authoring-surface.test.mjs

@@ -86,7 +86,7 @@ describe('the public authoring surface of this repo', () => {
   it(
     'audits clean: every exported type has a readable doc and every self-doc documents one',
     async () => {
-      const index = await docs('authoring', undefined, {index: true});
+      const index = await docs('authoring/field-reference', undefined, {index: true});
       const topicKeys = new Set(
         index.data.sections.map((/** @type {any} */ s) => s.id),
       );

package/foundation/discovery/cli-self-docs.d.mts

@@ -102,7 +102,8 @@ export const CLI_SELF_DOC_DIRS: string[];
 /**
  * Every namespace a CLI doc may declare, and what reads it. The docs tree
  * adopts `cli/commands` (under `cli/commands`) and `cli/api` (under
- * `cli/api/<kind>s`); `astryx docs authoring` reads `authoring` from its list.
+ * `cli/api/<kind>s`); the field reference (`astryx docs authoring/field-reference`)
+ * reads `authoring` from its list.
  * @type {Record<string, {reader: 'tree' | 'authoring'}>}
  */
 export const CLI_DOC_NAMESPACES: Record<string, {

package/foundation/discovery/cli-self-docs.mjs

@@ -25,6 +25,7 @@ import {
   oversizedDocSections,
 } from './docs-output-budget.mjs';
 import {routeSegment} from './docs-section-key.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 /** The directories, relative to the CLI root, that hold the CLI's own docs. */
 export const CLI_SELF_DOC_DIRS = [
@@ -40,7 +41,8 @@ const NAMESPACED_KINDS = new Set(['command', 'function', 'schema', 'enum']);
 /**
  * Every namespace a CLI doc may declare, and what reads it. The docs tree
  * adopts `cli/commands` (under `cli/commands`) and `cli/api` (under
- * `cli/api/<kind>s`); `astryx docs authoring` reads `authoring` from its list.
+ * `cli/api/<kind>s`); the field reference (`astryx docs authoring/field-reference`)
+ * reads `authoring` from its list.
  * @type {Record<string, {reader: 'tree' | 'authoring'}>}
  */
 export const CLI_DOC_NAMESPACES = {
@@ -187,6 +189,19 @@ function sentence(text, more) {
   return more && text !== '' && !/[.!?:]$/.test(text) ? `${text}.` : text;
 }
 
+/**
+ * The line a command doc prints for what it does outside a project (spec
+ * AST-081 FR4). A group that only holds subcommands declares nothing and
+ * prints nothing.
+ * @type {Record<string, string>}
+ */
+const OUTSIDE_PROJECT_TEXT = {
+  same: "Outside a project (`same`): it answers as it would in a new project on this release, reading this release's Core, as it does in a project with nothing installed: the one installed beside the CLI, else one in the per-user cache, which a global install downloads in the background after a command run online (in CI, the first command that needs it downloads it).",
+  refuse:
+    'Outside a project (`refuse`): it writes nothing and fails, naming the app project or integration package it needs.',
+  own: 'Outside a project (`own`): it does what the description above says it does outside a project.',
+};
+
 /** @param {any[]} notes */
 function noteBlocks(notes) {
   return (notes ?? []).filter(note => TOPIC_BLOCKS.has(note?.type));
@@ -251,6 +266,8 @@ function commandSection(cmd, index) {
       rows: exitCodes.map((/** @type {any} */ e) => [String(e.code), e.when]),
     });
   }
+  const outside = OUTSIDE_PROJECT_TEXT[cmd.outsideProject];
+  if (outside) content.push({type: 'prose', text: outside});
   // Links name docs by identity; the route in each command is derived when
   // the doc is read (spec:AST-047 FR9).
   const subcommands = (cmd.subcommands ?? []).filter(
@@ -318,7 +335,8 @@ function functionSection(fn, index) {
     // A Default column only when some parameter declares a default, so a
     // function with none keeps a three-column table.
     const defaults = params.some(
-      (/** @type {any} */ p) => typeof p.default === 'string' && p.default !== '',
+      (/** @type {any} */ p) =>
+        typeof p.default === 'string' && p.default !== '',
     );
     content.push({
       type: 'table',
@@ -475,13 +493,13 @@ export async function auditCliSelfDocs({
       else {
         misfiled.push({
           source,
-          message: `${source} has namespace "authoring", but \`astryx docs authoring\` does not list it`,
+          message: `${source} has namespace "authoring", but \`${formatCliCommand('docs authoring/field-reference')}\` does not list it`,
         });
       }
     } else if (inAuthoring) {
       misfiled.push({
         source,
-        message: `${source} is read in \`astryx docs authoring\`, but its namespace is "${namespace}"`,
+        message: `${source} is read in \`${formatCliCommand('docs authoring/field-reference')}\`, but its namespace is "${namespace}"`,
       });
     } else {
       treeDocs.push(doc);

package/foundation/discovery/cli-self-docs.test.mjs

@@ -25,6 +25,7 @@ import {
   discoverCliSelfDocSources,
 } from './cli-self-docs.mjs';
 import {routeSegment} from './docs-section-key.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 const SLOW = 60_000;
 
@@ -145,8 +146,8 @@ describe('auditCliSelfDocs', () => {
     });
     const result = await audit(root, ['y/y.doc.mjs', 'z/z.doc.mjs']);
     expect(result.misfiled.map(entry => entry.message)).toEqual([
-      'authoring/x/x.doc.mjs has namespace "authoring", but `astryx docs authoring` does not list it',
-      'authoring/y/y.doc.mjs is read in `astryx docs authoring`, but its namespace is "cli/api"',
+      `authoring/x/x.doc.mjs has namespace "authoring", but \`${formatCliCommand('docs authoring/field-reference')}\` does not list it`,
+      `authoring/y/y.doc.mjs is read in \`${formatCliCommand('docs authoring/field-reference')}\`, but its namespace is "cli/api"`,
     ]);
     expect(result.authoring).toBe(1);
     expect(result.tree).toBe(0);

package/foundation/discovery/component-discovery.d.mts

@@ -1,8 +1,27 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * 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: string): boolean;
+/**
+ * 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: any, name: string): any;
 /**
  * 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']`
@@ -103,19 +122,129 @@ export function discoverExternalComponentsGrouped(docsDir: string): Record<strin
  * @returns {string | null}
  */
 export function findExternalComponentDoc(docsDir: string, name: string): string | null;
+/** @param {string} docPath */
+export function docStem(docPath: string): string;
+/**
+ * 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}
+ */
+export function importedModule(integration: {
+    name?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, docPath: string, doc: Record<string, any> | null): string | null | undefined;
+/**
+ * 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: {
+    name?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, specifier: string): string | null;
+/**
+ * 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: string, name: string): string | null;
+/**
+ * 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: {
+    name: string;
+    components?: string;
+    issuesUrl?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}): Array<{
+    docPath: string;
+    module: string | null;
+}>;
+/**
+ * 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: {
+    name: string;
+    docPath: string | null;
+}): boolean;
+/**
+ * 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: any, record: {
+    name: string;
+    docPath: string | null;
+}): any;
+/**
+ * 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: string | undefined, visit: (docPath: string, stem: string) => void): void;
+/**
+ * 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: string): string | 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.
+ * 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: {
     name: string;
     components?: string;
     issuesUrl?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, { documentedNames }?: {
+    documentedNames?: boolean;
 }): Array<{
     name: string;
     package: string;
@@ -129,11 +258,16 @@ 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}>,
  * }>}
@@ -142,12 +276,14 @@ export function discoverValidIntegrationComponents(integration: {
     name: string;
     components?: string;
     issuesUrl?: string;
+}, options?: {
+    documentedNames?: boolean;
 }): Promise<{
     components: Array<{
         name: string;
         package: string;
         docPath: string;
-        sourcePath: string;
+        sourcePath: string | null;
         issuesUrl: string | undefined;
         group: string | null;
         replaces?: unknown;
@@ -165,30 +301,103 @@ export function discoverValidIntegrationComponents(integration: {
         message: string;
     }>;
 }>;
+/**
+ * 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: {
+    name: string;
+    docPath: string | null;
+}): "file" | "doc";
+/**
+ * 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?: string;
+    components?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, name: string): {
+    docPath: string;
+    sourcePath: string | null;
+    hold: "file" | "doc";
+} | null;
+/**
+ * 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: {
+    name?: string;
+    components?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, docPath: string): string;
 /**
  * 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?: string;
     components?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
 }, name: string): string | null;
 /**
- * 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?: string;
     components?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
 }, name: string): string | 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<T extends {
+    hold?: string;
+}>(owners: T[]): T[];
 /**
  * Build a flat list of ownership records for ALL discoverable components —
  * core (built-in) plus every loaded integration. This is the authoritative
@@ -217,3 +426,11 @@ export function discoverOwnedComponents(coreDir: string, loadedIntegrations?: Ar
 }>;
 /** The owner package name for built-in (core) components. */
 export const CORE_PACKAGE: import("../../authoring/index.js").ProviderId;
+/**
+ * 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.
+ */
+export type NameHold = "core" | "file" | "doc";