@astryxdesign/cli 0.7.2-canary.db3a2e7 → 0.7.2-canary.e26723d

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

@@ -1,8 +1,20 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * 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 +115,99 @@ 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 `.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 +221,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 +239,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 +264,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 +389,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";