@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f2b60a0

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

@@ -117,6 +117,58 @@ export function discoverExternalComponentsGrouped(docsDir: string): Record<strin
 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.
@@ -124,15 +176,24 @@ export function docStem(docPath: string): string;
  * @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. A doc
  * that names a differently named export of its file is recorded under that
- * export 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.
+ * 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
@@ -143,6 +204,8 @@ export function discoverIntegrationComponents(integration: {
     name: string;
     components?: string;
     issuesUrl?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
 }, { documentedNames }?: {
     documentedNames?: boolean;
 }): Array<{
@@ -158,14 +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. A doc that fails to
- * load is reported under its file name: what it says cannot be trusted.
+ * 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}>,
  * }>}
@@ -181,7 +246,7 @@ export function discoverValidIntegrationComponents(integration: {
         name: string;
         package: string;
         docPath: string;
-        sourcePath: string;
+        sourcePath: string | null;
         issuesUrl: string | undefined;
         group: string | null;
         replaces?: unknown;
@@ -203,8 +268,8 @@ export function discoverValidIntegrationComponents(integration: {
  * 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, or the file name of a doc
- * recorded under another export.
+ * `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
  */
 /**
@@ -218,43 +283,69 @@ export function integrationRecordHold(record: {
 }): "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.
+ * hold: the same-stem doc first, then a doc that records the name as an export
+ * or a member.
  *
- * @param {{components?: string}} integration
+ * @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`, and finds a
- * doc that records the component under a differently named export of its file.
+ * 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 by name within a
  * loaded integration's resolved `components` dir: the same-stem `{Name}.tsx`
- * of its doc. Returns null when the integration ships docs without source.
+ * 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
@@ -302,7 +393,7 @@ 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, or the file name of a doc
- * recorded under another export.
+ * `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";