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

package/api/docs/_adapter.mjs

@@ -17,8 +17,11 @@
  *   foundation/discovery/docs-discovery, which the catalog comes from.
  */
 
+import * as path from 'node:path';
 import {Project} from '../../foundation/config/project.mjs';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
+import {checkDocTypes} from '../../foundation/discovery/doc-types.mjs';
+import {integrationDocFiles} from '../../foundation/discovery/integration-doc-files.mjs';
 import {
   linkReferenceTopic,
   lowerReferenceTopic,
@@ -53,6 +56,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 +509,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 +908,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 +1002,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})),
@@ -1125,3 +1334,37 @@ export async function resolveTopicDocs(topic, options = {}) {
   const node = await lowerTopic(catalog, entry, effectiveLang);
   return {catalog, node, lang: effectiveLang, entry};
 }
+
+/**
+ * Each doc one integration package ships, checked against the published
+ * authoring type for its kind with the project's own TypeScript (spec:AST-039
+ * FR13). Without TypeScript the report says nothing was checked.
+ * @param {any} integration a loaded integration
+ * @param {string} cwd
+ * @returns {Promise<import('../../foundation/discovery/doc-types.mjs').DocTypesReport & {fixtures?: number}>}
+ */
+export async function integrationDocTypes(integration, cwd) {
+  const packageDir = /** @type {{__packageDir?: string}} */ (integration)
+    .__packageDir;
+  const {files, unread, fixtures} = await integrationDocFiles(integration);
+  const checked = await checkDocTypes(files, {
+    packageDir: packageDir ?? cwd,
+    resolveFrom: [cwd, packageDir],
+  });
+  // Test fixtures no reader serves don't ship as docs: only counted.
+  const report =
+    checked.status === 'checked' && fixtures > 0
+      ? {...checked, fixtures}
+      : checked;
+  if (report.status !== 'checked' || unread.length === 0) return report;
+  // A root its reader cannot read serves no doc; say so rather than skip it.
+  const rel = (/** @type {string} */ file) =>
+    path.relative(packageDir ?? cwd, file).split(path.sep).join('/') || '.';
+  return {
+    ...report,
+    unchecked: [
+      ...report.unchecked,
+      ...unread.map(entry => ({doc: rel(entry.path), reason: entry.reason})),
+    ].sort((a, b) => a.doc.localeCompare(b.doc)),
+  };
+}

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

@@ -24,6 +24,7 @@ import {
   findComponentReadme,
   findIntegrationComponent,
   integrationRecordHold,
+  isIntegrationMember,
   unscopedComponentOwners,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {legacyExternalKeeps} from '../component/_adapter.mjs';
@@ -197,7 +198,7 @@ async function selectTarget(project, component, packageName) {
     discoverIntegrationComponents(integration).flatMap(r =>
       r.name.toLowerCase() === wanted
         ? [{...r, hold: integrationRecordHold(r)}]
-        : docStem(r.docPath).toLowerCase() === wanted
+        : docStem(r.docPath).toLowerCase() === wanted && !isIntegrationMember(r)
           ? [{...r, hold: 'doc'}]
           : [],
     ),

package/api/index.d.mts

@@ -16,6 +16,7 @@ export { init } from "./init/init.mjs";
 export { doctor } from "./doctor/doctor.mjs";
 export { integrationAddTheme } from "./integration/add-theme.mjs";
 export { integrationPackCheck } from "./integration/pack-check.mjs";
+export { integrationCheck } from "./integration/check/check.mjs";
 export { AstryxError } from "./error.mjs";
 export { logger } from "./logger.mjs";
 export * from "../foundation/response/batch.type.mjs";
@@ -37,6 +38,7 @@ export * from "./integration/integration-authoring.type.mjs";
 export * from "./integration/pack-check.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export * from "./integration/authoring-checks.type.mjs";
+export * from "./integration/integration-check.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
 export { themeBuild, themeAdd, themeRemove, themeUse, themeEject, themeTemplate, themeList, themeListAvailable, themeListCopySources, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";

package/api/index.mjs

@@ -67,6 +67,7 @@ export {
   integrationComponentConflicts,
   integrationDocConflicts,
 } from './integration/authoring-checks.mjs';
+export {integrationCheck} from './integration/check/check.mjs';
 export {AstryxError} from './error.mjs';
 // The one shared logger: the `logger` instance side-effecting commands write
 // through, plus its generated `Logger` type. Part of the public surface so an
@@ -100,3 +101,4 @@ export * from './integration/integration-authoring.type.mjs';
 export * from './integration/pack-check.type.mjs';
 export * from './integration/validate-integration.type.mjs';
 export * from './integration/authoring-checks.type.mjs';
+export * from './integration/integration-check.type.mjs';

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],
+  });
+}

package/api/integration/add-contribution.component-names.test.mjs

@@ -98,6 +98,72 @@ describe('integrationAddComponent name collisions', () => {
     expect(snapshot()).toEqual(before);
   });
 
+  it('adds a name a family doc lists but the module it imports does not export', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist'], exports: {'./tabs': './components/tabs/index.ts'}}, null, 2)}\n`,
+    );
+    const tabs = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(tabs, {recursive: true});
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabExtra', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTabExtra() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'index.ts'),
+      "export {AcmeTabs} from './AcmeTabs';\n",
+    );
+
+    const result = await integrationAdd('component', 'AcmeTabExtra', {
+      cwd: tmpDir,
+      dryRun: true,
+    });
+    expect(result.data.files).toContain('components/AcmeTabExtra.doc.mjs');
+  });
+
+  it('refuses a member a family exports through built output', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist'], exports: {'./tabs': './dist/tabs/index.js'}}, null, 2)}\n`,
+    );
+    const tabs = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(tabs, {recursive: true});
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTab', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTab.tsx'),
+      'export function AcmeTab() { return null; }\n',
+    );
+    const dist = path.join(tmpDir, 'dist', 'tabs');
+    fs.mkdirSync(dist, {recursive: true});
+    fs.writeFileSync(
+      path.join(dist, 'index.js'),
+      "export {AcmeTabs} from './tabs.js';\nexport {AcmeTab} from './tab.js';\n",
+    );
+    fs.writeFileSync(
+      path.join(dist, 'tabs.js'),
+      'export function AcmeTabs() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(dist, 'tab.js'),
+      'export function AcmeTab() { return null; }\n',
+    );
+
+    await expect(
+      integrationAdd('component', 'AcmeTab', {cwd: tmpDir, dryRun: true}),
+    ).rejects.toThrow('Refusing to add component "AcmeTab"');
+  });
+
   it('still adds a component whose name is free', async () => {
     writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
 

package/api/integration/add-contribution.mjs

@@ -264,9 +264,13 @@ async function addComponent(name, options) {
       ERROR_CODES.ERR_FILE_EXISTS,
     );
   }
-  // Discovery keys components by doc stem anywhere under the root, so a second
-  // doc with this name would shadow one of the two.
-  const existingDoc = findIntegrationComponentDoc({components: root}, name);
+  // A second doc under a name discovery already records, by a doc's file name
+  // anywhere under the root or by a name a doc documents, would shadow one of
+  // the two.
+  const existingDoc = findIntegrationComponentDoc(
+    {name: owner, components: root, __packageDir: packageDir},
+    name,
+  );
   if (existingDoc != null) {
     throw new AstryxError(
       `Refusing to add component "${name}": ${projectPath(path.relative(packageDir, existingDoc))} already defines it.`,
@@ -691,7 +695,7 @@ async function addTemplate(name, options) {
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
   const blockFields = templateType === 'block' ? '\n  aspectRatio: 1,' : '';
-  const specContents = `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n  type: '${templateType}',\n  name: '${name}',\n  displayName: '${kebabToTitle(name)}',\n  description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;
+  const specContents = `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */\nexport default {\n  type: '${templateType}',\n  name: '${name}',\n  displayName: '${kebabToTitle(name)}',\n  description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;
   const sourceContents = `export default function ${pascalName}() {\n  return <div>${kebabToTitle(name)}</div>;\n}\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */