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

package/api/component/list/list.mjs

@@ -16,6 +16,7 @@ import {
   discoverComponents,
   discoverExternalComponentsGrouped,
   discoverValidIntegrationComponents,
+  familyMember,
   findComponentReadme,
   findExternalComponentDoc,
   resolveImportPath,
@@ -66,6 +67,33 @@ async function legacyImport(ext, name, coreDir, docOpts) {
  */
 const coreEntry = doc => ({name: doc.name, package: CORE_PACKAGE, ...doc});
 
+/**
+ * The full-level entry for a component documented as a member of its family's
+ * doc (VStack in Stack's doc): a component doc built from the member's own
+ * entry, under its own name, display name and import, shaped like every other
+ * full entry. Null when the doc is the component's own.
+ * @param {any} docs
+ * @param {string} name
+ * @param {string} coreDir
+ * @returns {any}
+ */
+function memberEntry(docs, name, coreDir) {
+  const member = familyMember(docs, name);
+  if (!member) return null;
+  return {
+    name,
+    package: CORE_PACKAGE,
+    displayName: member.displayName ?? name,
+    ...(docs.group ? {group: docs.group} : {}),
+    ...(docs.category ? {category: docs.category} : {}),
+    usage: member.usage ?? {description: member.description ?? ''},
+    props: member.props ?? [],
+    ...(member.examples ? {examples: member.examples} : {}),
+    ...(docs.theming ? {theming: docs.theming} : {}),
+    import: resolveImportPath(coreDir, name),
+  };
+}
+
 /**
  * The entry for a Core slot an integration component replaces
  * (spec:AST-035 FR11), at the list's detail level: the replacement's own name,
@@ -177,7 +205,11 @@ export async function componentList(
             entries.push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -215,7 +247,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            entries.push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            entries.push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             entries.push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }
@@ -269,7 +302,11 @@ export async function componentList(
             result[cat].push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -310,7 +347,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            result[cat].push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            result[cat].push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             result[cat].push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }

package/api/docs/_adapter.mjs

@@ -53,6 +53,17 @@ import {
   selfDocSection,
 } from '../../foundation/discovery/authoring-self-docs.mjs';
 import {CLI_PROVIDER_ID} from '../../foundation/identity/providers.mjs';
+import {
+  CORE_PACKAGE,
+  discoverOwnedComponents,
+  discoverValidIntegrationComponents,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {loadComponentDoc} from '../../foundation/discovery/component-loader.mjs';
+import {
+  discoverCoreTemplates,
+  discoverIntegrationTemplatesForOne,
+} from '../../foundation/discovery/template-adapter.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
@@ -495,12 +506,205 @@ async function docFinder(catalog, fromProvider) {
         };
       }
     }
+    if (CONTRIBUTED_KINDS.has(parsed.kind)) {
+      const link = await contributedDocLink(
+        catalog,
+        provider,
+        parsed.kind,
+        parsed.name,
+      );
+      if (link)
+        return {link: {target, ...link}, kind: parsed.kind, typed: null};
+    }
+    const searchType =
+      parsed.kind === 'component'
+        ? 'component'
+        : parsed.kind === 'page' || parsed.kind === 'block'
+          ? 'template'
+          : 'doc';
     return {
-      problem: `"${target}" names no doc. Find it with \`astryx search ${parsed.name} --type doc\`, then name it as \`[<provider>:]<kind>:<name>\`.`,
+      problem: `"${target}" names no doc. Find it with \`astryx search ${parsed.name} --type ${searchType}\`, then name it as \`[<provider>:]<kind>:<name>\`.`,
     };
   };
 }
 
+/** The doc kinds no docs tree holds: components and templates. */
+const CONTRIBUTED_KINDS = new Set(['component', 'page', 'block']);
+
+/**
+ * The link to a component, page, or block doc (spec:AST-047 FR9). No docs tree
+ * holds these, so a link finds them among the component and template records
+ * the catalog carries, the ones `astryx component` and `astryx template` open,
+ * and reads as that command. A component is named by its export name, a
+ * template by its id; anything but Core's names its package.
+ * @param {DocsCatalog} catalog
+ * @param {string} provider normalized provider id
+ * @param {string} kind `component`, `page`, or `block`
+ * @param {string} name
+ * @returns {Promise<Omit<import('../../foundation/doc-compiler/links.mjs').DocLink, 'target'> | null>}
+ */
+async function contributedDocLink(catalog, provider, kind, name) {
+  const contributions = await catalog.contributions();
+  if (!contributions) return null;
+  const sameProvider = (/** @type {string} */ providerId) => {
+    try {
+      return normalizeProviderId(providerId) === provider;
+    } catch {
+      return false;
+    }
+  };
+  if (kind === 'component') {
+    const record = contributions.components.find(
+      component =>
+        component.name === name && sameProvider(component.providerId),
+    );
+    if (!record) return null;
+    /** @type {any} */
+    let doc = null;
+    try {
+      doc = record.docPath ? await loadComponentDoc(record.docPath) : null;
+    } catch {
+      // The component checks report a doc that does not load; the link
+      // still opens the component.
+    }
+    const entry =
+      doc?.name === name
+        ? doc
+        : doc?.components?.find(
+            (/** @type {any} */ each) => each.name === name,
+          );
+    // Bare, Core's name opens Core's component unless another package ships
+    // the same name or replaces it (spec:AST-035 FR11); then the link selects
+    // Core, as it always selects any other package.
+    const selectPackage =
+      record.package !== CORE_PACKAGE ||
+      contributions.components.some(
+        other =>
+          other.package !== CORE_PACKAGE &&
+          (other.name === name || other.replaces === name),
+      );
+    return {
+      id: createDocId(provider, 'component', name),
+      route: null,
+      title: entry?.displayName ?? name,
+      summary: entry?.description ?? doc?.description ?? '',
+      command: `astryx component ${name}${selectPackage ? ` --package ${record.package}` : ''}`,
+    };
+  }
+  const template = contributions.templates.find(
+    each =>
+      each.type === kind && each.id === name && sameProvider(each.providerId),
+  );
+  if (!template) return null;
+  // The same for a Core template: another package's template of its kind
+  // with its id, or one that replaces it, takes the bare id.
+  const selectPackage =
+    template.package !== CORE_PACKAGE ||
+    contributions.templates.some(
+      other =>
+        other.package !== CORE_PACKAGE &&
+        other.type === template.type &&
+        (other.id === name || other.replaces === name),
+    );
+  return {
+    id: createDocId(provider, template.type, name),
+    route: null,
+    title: template.displayName ?? template.name,
+    summary: template.description ?? '',
+    command: `astryx template ${name} --type ${template.type}${selectPackage ? ` --package ${template.package}` : ''}`,
+  };
+}
+
+/**
+ * The component and template docs one integration package's links can name:
+ * Core's and its own, as `doctor integration docs` checks it before any app
+ * configures it.
+ * @param {any} integration a loaded integration: its name, provider id, roots,
+ *   and package directory
+ * @returns {Promise<import('../../foundation/discovery/docs-discovery.mjs').LinkableContributions>}
+ */
+async function packageContributions(integration) {
+  const own = integration.providerId ?? integration.name;
+  /** @type {import('../../foundation/discovery/docs-discovery.mjs').LinkableComponent[]} */
+  const components = [];
+  const coreDir = findCoreDir(integration.__packageDir ?? process.cwd());
+  if (coreDir) {
+    try {
+      for (const record of discoverOwnedComponents(coreDir, [])) {
+        components.push({
+          providerId: CORE_PACKAGE,
+          package: CORE_PACKAGE,
+          name: record.name,
+          docPath: record.docPath,
+        });
+      }
+    } catch {
+      // The components check reports a Core it cannot read.
+    }
+  }
+  if (integration.components) {
+    try {
+      const {components: records} =
+        await discoverValidIntegrationComponents(integration);
+      for (const record of records) {
+        components.push({
+          providerId: own,
+          package: integration.name,
+          name: record.name,
+          docPath: record.docPath,
+          // Declared: this package alone cannot tell whether an app applies
+          // it, so a link to the Core name it names selects Core.
+          ...(typeof record.replaces === 'string'
+            ? {replaces: record.replaces}
+            : {}),
+        });
+      }
+    } catch {
+      // `validate` reports components that do not load.
+    }
+  }
+  /** @type {import('../../foundation/discovery/docs-discovery.mjs').LinkableTemplate[]} */
+  const templates = [];
+  /** @param {any} template @param {string} providerId @param {string} pkg */
+  const addTemplate = (template, providerId, pkg) => {
+    if (template.type !== 'page' && template.type !== 'block') return;
+    templates.push({
+      providerId,
+      package: pkg,
+      type: template.type,
+      id: template.dirName,
+      name: template.name,
+      ...(template.displayName == null
+        ? {}
+        : {displayName: template.displayName}),
+      ...(template.description == null
+        ? {}
+        : {description: template.description}),
+      ...(typeof template.replaces === 'string'
+        ? {replaces: template.replaces}
+        : {}),
+    });
+  };
+  try {
+    for (const template of await discoverCoreTemplates()) {
+      addTemplate(template, CORE_PACKAGE, CORE_PACKAGE);
+    }
+  } catch {
+    // Core templates that do not load leave nothing to link to.
+  }
+  if (integration.templates) {
+    try {
+      const {templates: records} =
+        await discoverIntegrationTemplatesForOne(integration);
+      for (const template of records)
+        addTemplate(template, own, integration.name);
+    } catch {
+      // `validate` reports templates that do not load.
+    }
+  }
+  return {components, templates};
+}
+
 /**
  * How a doc's links find their targets (spec:AST-047 FR9), as
  * {@link docFinder} finds them: each resolves to the link a read shows.
@@ -701,6 +905,7 @@ export async function docsLinkProblems(
  */
 export async function packageDocsProblems(integration, discovered) {
   const catalog = DocsCatalog.fromBuiltins();
+  catalog.setContributions(() => packageContributions(integration));
   for (const record of discovered.records) catalog.add(record);
   catalog.addTreeInputs({
     namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),
@@ -794,6 +999,7 @@ async function namespaceReferenceTarget(catalog, route, lang) {
  */
 export async function packageReferenceProblems(integration, discovered) {
   const catalog = DocsCatalog.fromBuiltins();
+  catalog.setContributions(() => packageContributions(integration));
   for (const record of discovered.records) catalog.add(record);
   catalog.addTreeInputs({
     namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),

package/api/docs/integrationDocs.test.mjs

@@ -22,6 +22,7 @@ import {docs} from './docs.mjs';
 import {search} from '../search/search.mjs';
 import {loadDocsCatalog} from './_adapter.mjs';
 import {AstryxError} from '../error.mjs';
+import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -110,6 +111,129 @@ describe('integration-contributed topics', () => {
     expect(section.data.title).toBe('Overview');
   }, SLOW);
 
+  it('reads a link to a component or a template as the command that opens it', async () => {
+    scaffold({
+      'using-widgets.doc.mjs': topic({
+        name: 'using-widgets',
+        title: 'Using widgets',
+        sections: [
+          {
+            title: 'Overview',
+            content: [
+              {
+                type: 'prose',
+                text: 'Start with {@link component:AcmeButton} or {@link block:acme-card}, built on {@link @astryxdesign/core:component:Button}.',
+              },
+            ],
+          },
+        ],
+      }),
+    });
+    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.mjs'),
+      "export default {components: './components', templates: './templates', docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(pkgDir, 'components'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+      'export function AcmeButton() { return null; }\n',
+    );
+    fs.mkdirSync(path.join(pkgDir, 'templates'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'acme-card.doc.mjs'),
+      "export default {type: 'block', name: 'Acme card', description: 'A card.'};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'acme-card.tsx'),
+      'export default function Fixture() { return null; }\n',
+    );
+
+    const detail = await docs('using-widgets', undefined, {cwd: tmpDir, full: true});
+
+    const prose = JSON.stringify(detail.data.sections);
+    expect(prose).toContain('`astryx component AcmeButton --package @acme/widgets`');
+    expect(prose).toContain(
+      '`astryx template acme-card --type block --package @acme/widgets`',
+    );
+    expect(prose).toContain('`astryx component Button`');
+    expect(prose).not.toContain('{@link');
+  }, SLOW);
+
+  it('selects Core in a link only where the bare name would open something else', async () => {
+    const core = await discoverCoreTemplates();
+    const page = core.find(template => template.type === 'page')?.dirName;
+    const block = core.find(template => template.type === 'block')?.dirName;
+    scaffold({
+      'using-widgets.doc.mjs': topic({
+        name: 'using-widgets',
+        title: 'Using widgets',
+        sections: [
+          {
+            title: 'Overview',
+            content: [
+              {
+                type: 'prose',
+                text:
+                  'Core: {@link @astryxdesign/core:component:Button}, {@link @astryxdesign/core:component:Badge}, ' +
+                  `{@link @astryxdesign/core:page:${page}}, {@link @astryxdesign/core:block:${block}}.`,
+              },
+            ],
+          },
+        ],
+      }),
+    });
+    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+    // The CLI range that turns component replacement on.
+    fs.writeFileSync(
+      path.join(pkgDir, 'package.json'),
+      JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        peerDependencies: {'@astryxdesign/cli': '>=0.6.7'},
+        peerDependenciesMeta: {'@astryxdesign/cli': {optional: true}},
+      }),
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.mjs'),
+      "export default {components: './components', templates: './templates', docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(pkgDir, 'components'));
+    // AcmeButton replaces Core's Button, so bare `Button` opens AcmeButton.
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', replaces: 'Button', props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+      'export function AcmeButton() { return null; }\n',
+    );
+    // A page template with a Core page's id makes the bare id ambiguous.
+    fs.mkdirSync(path.join(pkgDir, 'templates'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', `${page}.doc.mjs`),
+      "export default {type: 'page', name: 'Acme page', displayName: 'Acme page', description: 'A page.'};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', `${page}.tsx`),
+      'export default function Fixture() { return null; }\n',
+    );
+
+    const detail = await docs('using-widgets', undefined, {cwd: tmpDir, full: true});
+
+    const prose = JSON.stringify(detail.data.sections);
+    expect(prose).toContain('`astryx component Button --package @astryxdesign/core`');
+    expect(prose).toContain('`astryx component Badge`');
+    expect(prose).toContain(
+      `\`astryx template ${page} --type page --package @astryxdesign/core\``,
+    );
+    expect(prose).toContain(`\`astryx template ${block} --type block\``);
+  }, SLOW);
+
   it('is invisible to a project that does not configure the integration', async () => {
     scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {};\n'});
     const listed = await docs(undefined, undefined, {cwd: tmpDir});

package/api/doctor/theme-checks.mjs

@@ -736,7 +736,7 @@ export async function checkAppThemes(cwd) {
       label: 'App imports the theme module',
       status: 'warn',
       message: `Could not prove that project source imports ${state.module.path}${importEvidence.parseFailures ? `; ${importEvidence.parseFailures} source file(s) could not be parsed` : ''}.`,
-      fix: `Import {themes, defaultThemeSlug} from the generated module and {Theme} from '@astryxdesign/core', then render <Theme theme={themes[defaultThemeSlug]}>.`,
+      fix: `Import {themes, defaultThemeSlug} from the generated module and {Theme} from '@astryxdesign/core/theme', then render <Theme theme={themes[defaultThemeSlug]}>.`,
     });
   }
 

package/api/gap-report/gap-report.mjs

@@ -17,7 +17,18 @@
 import {Worker} from 'node:worker_threads';
 import {AstryxError} from '../error.mjs';
 import {Project} from '../../foundation/config/project.mjs';
-import {CORE_PACKAGE} from '../../foundation/discovery/component-discovery.mjs';
+import {
+  CORE_PACKAGE,
+  discoverIntegrationComponents,
+  docStem,
+  findComponentReadme,
+  findIntegrationComponent,
+  integrationRecordHold,
+  isIntegrationMember,
+  unscopedComponentOwners,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {legacyExternalKeeps} from '../component/_adapter.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {captureEnv} from '../../foundation/debug/event.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {parseGapReportReceipt} from '../../authoring/gap-report/parse.mjs';
@@ -178,13 +189,65 @@ async function selectTarget(project, component, packageName) {
     coreName,
   );
   if (replacement) return targetForPackage(project, replacement.package);
+  // The owner rule runs over every owner discovery finds, loadable or not
+  // (a doc recorded under another export still answers to its file's name);
+  // then only owners whose docs load route a report.
+  const wanted = bareComponent.toLowerCase();
+  const loads = new Set(records.map(r => `${r.package}\0${r.docPath}`));
+  const recorded = project.loadedIntegrations.flatMap(integration =>
+    discoverIntegrationComponents(integration).flatMap(r =>
+      r.name.toLowerCase() === wanted
+        ? [{...r, hold: integrationRecordHold(r)}]
+        : docStem(r.docPath).toLowerCase() === wanted && !isIntegrationMember(r)
+          ? [{...r, hold: 'doc'}]
+          : [],
+    ),
+  );
+  // The checks below find files by name, so they run on every spelling the
+  // case-blind match above found, as well as the one typed.
+  const spellings = new Set([
+    bareComponent,
+    ...recorded.flatMap(r =>
+      [r.name, docStem(r.docPath)].filter(n => n.toLowerCase() === wanted),
+    ),
+  ]);
+  // Core also holds a name only its doc lookup finds, as in detail: a name a
+  // doc records yields to it, though it routes no report itself.
+  const coreDir = findCoreDir(project.cwd);
+  const coreDocs =
+    coreDir != null &&
+    [...spellings].some(name => findComponentReadme(coreDir, name) != null);
+  const ruled = unscopedComponentOwners([
+    ...records
+      .filter(
+        r => r.package === CORE_PACKAGE && r.name.toLowerCase() === wanted,
+      )
+      .map(r => ({...r, hold: 'core'})),
+    ...recorded,
+    // A hidden doc named after its file still holds that name, as the
+    // component lookup finds it; it routes no report.
+    ...project.loadedIntegrations.flatMap(integration =>
+      [...spellings].flatMap(spelling => {
+        const found = findIntegrationComponent(integration, spelling);
+        return found?.hold === 'file'
+          ? [{...found, package: integration.name}]
+          : [];
+      }),
+    ),
+  ]).filter(r => !coreDocs || r.hold !== 'doc');
+  // A legacy docs package keeps an export name a doc records, as in detail.
   const owners = [
     ...new Set(
-      records
+      ([...spellings].some(name =>
+        legacyExternalKeeps(project.cwd, name, ruled),
+      )
+        ? []
+        : ruled
+      )
         .filter(
-          record => record.name.toLowerCase() === bareComponent.toLowerCase(),
+          r => r.hold === 'core' || loads.has(`${r.package}\0${r.docPath}`),
         )
-        .map(record => record.package),
+        .map(r => r.package),
     ),
   ];
 

package/api/init/run/run.mjs

@@ -50,11 +50,11 @@ export function getNextSteps(invocation) {
     `       (run \`${invocation} doctor\` to verify)`,
     "    2. Import base styles: import '@astryxdesign/core/reset.css'",
     "       and import '@astryxdesign/core/astryx.css'",
-    "    3. Import components: import { Button } from '@astryxdesign/core'",
+    "    3. Import components: import { Button } from '@astryxdesign/core/Button'",
     '    4. Add and wire a theme:',
     '       npm install @astryxdesign/theme-neutral',
     `       ${invocation} theme add neutral`,
-    "       import { Theme } from '@astryxdesign/core'",
+    "       import { Theme } from '@astryxdesign/core/theme'",
     "       import { themes, defaultThemeSlug } from './astryx-themes'",
     '       <Theme theme={themes[defaultThemeSlug]}>...</Theme>',
     `       Extend an imported theme to customize it. Run \`${invocation} theme eject <slug>\` only to fork source.`,

package/api/integration/_adapter.d.mts

@@ -0,0 +1,12 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Each component doc's props compared with the component's TypeScript props,
+ * read with the project's own compiler (spec:AST-039 FR12). Without one, the
+ * report says the comparison was skipped.
+ * @param {any} integration a loaded integration
+ * @param {string} cwd
+ * @returns {Promise<import('../../foundation/discovery/prop-drift.mjs').PropDriftReport>}
+ */
+export function integrationPropDrift(integration: any, cwd: string): Promise<import("../../foundation/discovery/prop-drift.mjs").PropDriftReport>;

package/api/integration/_adapter.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The integration subject's access to the environment (INV21): reading
+ * one package's component docs and sources with the project's own TypeScript.
+ *
+ * @input a loaded integration and the directory the command runs in
+ * @output the reports the integration checks attach to their results
+ * @position api/integration (internal; not exported from ./api)
+ */
+
+import {
+  discoverValidIntegrationComponents,
+  forEachIntegrationDoc,
+  integrationSourceForDoc,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {comparePropDocs} from '../../foundation/discovery/prop-drift.mjs';
+
+/**
+ * Each component doc's props compared with the component's TypeScript props,
+ * read with the project's own compiler (spec:AST-039 FR12). Without one, the
+ * report says the comparison was skipped.
+ * @param {any} integration a loaded integration
+ * @param {string} cwd
+ * @returns {Promise<import('../../foundation/discovery/prop-drift.mjs').PropDriftReport>}
+ */
+export async function integrationPropDrift(integration, cwd) {
+  const packageDir = /** @type {{__packageDir?: string}} */ (integration)
+    .__packageDir;
+  const {components} = await discoverValidIntegrationComponents(integration);
+  // Every doc the package ships has its prop tables compared or listed as not
+  // compared. A doc discovery leaves out (a hidden one, a second doc for one
+  // name, or one whose source or own file doesn't load) gets a record under
+  // its file name.
+  const recorded = new Set(components.map(c => c.docPath));
+  /** @type {typeof components} */
+  const left = [];
+  forEachIntegrationDoc(integration?.components, (docPath, stem) => {
+    if (recorded.has(docPath)) return;
+    recorded.add(docPath);
+    left.push({
+      name: stem,
+      package: integration.name,
+      docPath,
+      sourcePath: integrationSourceForDoc(docPath),
+      issuesUrl: integration.issuesUrl,
+      group: null,
+    });
+  });
+  return comparePropDocs([...components, ...left], {
+    packageDir: packageDir ?? cwd,
+    resolveFrom: [cwd, packageDir],
+  });
+}