@astryxdesign/cli 0.6.3-canary.7ada42e → 0.6.3-canary.7ec7be0

package/foundation/integrations/cli-requirement.mjs

@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The CLI an integration's namespace docs need (spec:AST-046 FR11).
+ *
+ * @input A package.json object.
+ * @output Whether its `peerDependencies` range for `@astryxdesign/cli` admits
+ *   only CLIs that read namespace docs, and the package.json that declares it.
+ * @position foundation/integrations; read by `integration add doc --parent`,
+ *   which declares the peer, and `integration pack --check`, which requires it.
+ */
+
+import {semverCompare} from '../env/semver.mjs';
+
+export const CLI_PACKAGE = '@astryxdesign/cli';
+
+/**
+ * The first CLI release that reads an integration's docs tree (namespace docs
+ * and placed guides) and its templates' `replaces`. A release before it can
+ * hide every doc topic a package with a namespace doc or a placed guide
+ * ships, with no warning, and it rejects `replaces` and withholds the
+ * package's templates and doc topics.
+ */
+export const DOCS_TREE_CLI = '0.7.0';
+
+const VERSION_RE = /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/**
+ * A version or partial version as MAJOR.MINOR.PATCH, a wildcard part as 0.
+ * @param {string} text
+ * @returns {string | null}
+ */
+function lowerVersion(text) {
+  const m = VERSION_RE.exec(text.trim());
+  if (!m) return null;
+  return [m[1], m[2], m[3]]
+    .map(part => (part == null || /^[xX*]$/.test(part) ? '0' : part))
+    .join('.');
+}
+
+/**
+ * The lowest version one space-joined comparator set admits, or null when it
+ * has no lower bound this can read.
+ * @param {string} set
+ * @returns {string | null}
+ */
+function lowestOfSet(set) {
+  if (set === '' || set === '*' || /^[xX]$/.test(set)) return null;
+  const hyphen = /^(\S+)\s+-\s+\S+$/.exec(set);
+  if (hyphen) return lowerVersion(hyphen[1]);
+  /** @type {string | null} */
+  let lowest = null;
+  for (const comparator of set.split(/\s+/)) {
+    const m = /^(>=|<=|>|<|=|\^|~)?(.+)$/.exec(comparator);
+    if (!m) return null;
+    if (m[1] === '<' || m[1] === '<=') continue;
+    const version = lowerVersion(m[2]);
+    if (version == null) return null;
+    if (lowest == null || semverCompare(version, lowest) > 0) lowest = version;
+  }
+  return lowest;
+}
+
+/**
+ * The lowest version a semver range admits: the least of its `||`
+ * alternatives. Null when an alternative has no lower bound, or the range is
+ * not one this can read, so the caller treats it as admitting every version.
+ * @param {unknown} range
+ * @returns {string | null}
+ */
+export function lowestAdmitted(range) {
+  if (typeof range !== 'string') return null;
+  /** @type {string | null} */
+  let lowest = null;
+  for (const alternative of range.split('||')) {
+    const low = lowestOfSet(alternative.trim());
+    if (low == null) return null;
+    if (lowest == null || semverCompare(low, lowest) < 0) lowest = low;
+  }
+  return lowest;
+}
+
+/**
+ * Why a package that uses a feature an older CLI cannot read would lose it,
+ * or null when its declared CLI range admits only CLIs that read it.
+ * @param {any} pkg package.json
+ * @param {string} feature what the package does, e.g. "ships a namespace doc"
+ * @param {string} loss what an older CLI does with it
+ * @returns {string | null}
+ */
+function cliRangeProblem(pkg, feature, loss) {
+  const range = pkg?.peerDependencies?.[CLI_PACKAGE];
+  const fix = `"${CLI_PACKAGE}": ">=${DOCS_TREE_CLI}" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required)`;
+  if (typeof range !== 'string') {
+    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A CLI older than ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
+  }
+  const lowest = lowestAdmitted(range);
+  if (lowest == null || semverCompare(lowest, DOCS_TREE_CLI) < 0) {
+    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a CLI older than ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
+  }
+  return null;
+}
+
+/**
+ * Why a package that ships a namespace doc or a placed guide would lose its
+ * docs on an older CLI, or null when its declared CLI range admits only CLIs
+ * that read the docs tree. Published 0.6.3 hides every topic of a package
+ * with a namespace doc; builds of main before the docs tree also do so for a
+ * placed guide.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function docsTreeCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'ships a namespace doc or a placed guide',
+    'does not read the docs tree, and can hide every doc topic the package ships',
+  );
+}
+
+/**
+ * Why a package with a template that sets `replaces` would lose its templates
+ * and doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * range admits only CLIs that read the field.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function replacesCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'has a template that sets `replaces`',
+    "rejects the field, and withholds the package's templates and doc topics",
+  );
+}
+
+/**
+ * The package.json with a CLI peer that reads namespace docs: optional, unless
+ * the package already says otherwise.
+ * @param {any} pkg package.json
+ * @returns {any}
+ */
+export function withDocsTreeCli(pkg) {
+  const meta = pkg.peerDependenciesMeta ?? {};
+  return {
+    ...pkg,
+    peerDependencies: {
+      ...(pkg.peerDependencies ?? {}),
+      [CLI_PACKAGE]: `>=${DOCS_TREE_CLI}`,
+    },
+    peerDependenciesMeta: meta[CLI_PACKAGE]
+      ? meta
+      : {...meta, [CLI_PACKAGE]: {optional: true}},
+  };
+}

package/foundation/integrations/cli-requirement.test.mjs

@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+  DOCS_TREE_CLI,
+  lowestAdmitted,
+  docsTreeCliProblem,
+  replacesCliProblem,
+  withDocsTreeCli,
+} from './cli-requirement.mjs';
+
+describe('lowestAdmitted', () => {
+  it.each([
+    ['>=0.7.0', '0.7.0'],
+    ['^0.6.0', '0.6.0'],
+    ['~0.7.1', '0.7.1'],
+    ['0.7.x', '0.7.0'],
+    ['>=0.7.0 <0.8.0', '0.7.0'],
+    ['^0.6.0 || >=0.7.0', '0.6.0'],
+    ['0.8.0 - 0.9.0', '0.8.0'],
+    ['*', null],
+    ['<1.0.0', null],
+    ['latest', null],
+    ['workspace:*', null],
+  ])('%s admits %s at the lowest', (range, lowest) => {
+    expect(lowestAdmitted(range)).toBe(lowest);
+  });
+});
+
+describe('docsTreeCliProblem', () => {
+  it('asks for a CLI peer when there is none', () => {
+    expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
+      'declares no @astryxdesign/cli peer',
+    );
+  });
+
+  it.each(['^0.6.0', '^0.6.0 || >=0.7.0', '*', '>=0.6.3'])(
+    'refuses %s, which admits a CLI that cannot read a namespace doc',
+    range => {
+      expect(
+        docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
+      ).toContain('admits a CLI older than');
+    },
+  );
+
+  it.each(['>=0.7.0', '^0.7.2', '>=0.7.0 <2'])('accepts %s', range => {
+    expect(
+      docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
+    ).toBeNull();
+  });
+
+  it('declares the peer as optional, and keeps what the package says of it', () => {
+    const declared = withDocsTreeCli({name: '@acme/kit'});
+    expect(declared.peerDependencies).toEqual({
+      '@astryxdesign/cli': `>=${DOCS_TREE_CLI}`,
+    });
+    expect(declared.peerDependenciesMeta).toEqual({
+      '@astryxdesign/cli': {optional: true},
+    });
+    expect(docsTreeCliProblem(declared)).toBeNull();
+    const required = withDocsTreeCli({
+      peerDependencies: {react: '^19.0.0', '@astryxdesign/cli': '^0.6.0'},
+      peerDependenciesMeta: {'@astryxdesign/cli': {optional: false}},
+    });
+    expect(required.peerDependencies.react).toBe('^19.0.0');
+    expect(required.peerDependenciesMeta['@astryxdesign/cli']).toEqual({
+      optional: false,
+    });
+  });
+});
+
+describe('replacesCliProblem', () => {
+  it('asks a package that sets replaces for a CLI that reads the field', () => {
+    expect(replacesCliProblem({name: '@acme/kit'})).toContain(
+      'sets `replaces`',
+    );
+    expect(
+      replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '^0.6.0'}}),
+    ).toContain('admits a CLI older than');
+    expect(
+      replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
+    ).toBeNull();
+  });
+});

package/foundation/integrations/contribution-inventory.d.mts

@@ -26,7 +26,7 @@ export function computeRequiredFiles(loaded: import("./integrations.mjs").Loaded
  * @typedef {object} ContributionIdentities
  * @property {{slug: string, exportName: string}[]} themes
  * @property {string[]} components
- * @property {{id: string, type: string, name: string}[]} templates
+ * @property {{id: string, type: string, name: string, replaces?: string}[]} templates
  * @property {{version: string, id: string}[]} codemods
  * @property {string[]} docs
  * @property {string[]} agentDocsAppend
@@ -127,6 +127,7 @@ export type ContributionIdentities = {
         id: string;
         type: string;
         name: string;
+        replaces?: string;
     }[];
     codemods: {
         version: string;

package/foundation/integrations/contribution-inventory.mjs

@@ -189,7 +189,7 @@ export function computeRequiredFiles(loaded) {
  * @typedef {object} ContributionIdentities
  * @property {{slug: string, exportName: string}[]} themes
  * @property {string[]} components
- * @property {{id: string, type: string, name: string}[]} templates
+ * @property {{id: string, type: string, name: string, replaces?: string}[]} templates
  * @property {{version: string, id: string}[]} codemods
  * @property {string[]} docs
  * @property {string[]} agentDocsAppend
@@ -278,7 +278,12 @@ export async function collectIdentities(loaded) {
         errors.push({kind: 'templates', message: templateError.message});
       }
       identities.templates = templates
-        .map(t => ({id: t.dirName, type: t.type, name: t.name}))
+        .map(t => ({
+          id: t.dirName,
+          type: t.type,
+          name: t.name,
+          ...(t.replaces == null ? {} : {replaces: t.replaces}),
+        }))
         .sort((a, b) => a.id.localeCompare(b.id));
     } catch (err) {
       errors.push({
@@ -309,12 +314,13 @@ export async function collectIdentities(loaded) {
 
   if (loaded.docs && fs.existsSync(loaded.docs)) {
     try {
-      const {records, errors: docErrors} =
+      const {records, guides, errors: docErrors} =
         await discoverIntegrationDocs(loaded);
       for (const docError of docErrors) {
         errors.push({kind: 'docs', message: docError.message});
       }
-      identities.docs = records.map(r => r.name).sort();
+      // A guide placed in the docs tree is a doc contribution too.
+      identities.docs = [...records, ...guides].map(r => r.name).sort();
     } catch (err) {
       errors.push({kind: 'docs', message: /** @type {Error} */ (err).message});
     }

package/foundation/integrations/contribution-inventory.test.mjs

@@ -304,6 +304,25 @@ describe('compareIdentities', () => {
     expect(issues[0].message).toContain('dash');
   });
 
+  it('errors when a packed template replaces a different target', () => {
+    const template = {id: 'acme-shell', type: 'page', name: 'Acme shell'};
+    const local = {
+      ...base(),
+      templates: [{...template, replaces: 'shell-side-nav'}],
+    };
+    const packed = {
+      ...base(),
+      templates: [{...template, replaces: 'shell-top-nav'}],
+    };
+
+    expect(compareIdentities(local, packed)).toEqual([
+      expect.objectContaining({
+        code: 'identity_mismatch',
+        message: expect.stringContaining('acme-shell'),
+      }),
+    ]);
+  });
+
   it('errors when a codemod is missing from packed', () => {
     const local = {
       ...base(),

package/foundation/integrations/integration-warnings.d.mts

@@ -8,10 +8,17 @@
  *
  *   Warning: <pkg> has N integration issue(s). Run: astryx doctor integration validate <pkg>
  *
- * @param {Array<import('./integrations.mjs').LoadedIntegration>} loadedIntegrations the Project's loaded integrations
+ * @param {Array<import('./integrations.mjs').LoadedIntegration> | {issues: () => Promise<Array<{package: string, code: string, severity: string, message: string}>>}} source loaded integrations or their Project owner
  * @param {{json?: boolean}} [options]
  * @returns {Promise<void>}
  */
-export function warnOnIntegrationIssues(loadedIntegrations: Array<import("./integrations.mjs").LoadedIntegration>, { json }?: {
+export function warnOnIntegrationIssues(source: Array<import("./integrations.mjs").LoadedIntegration> | {
+    issues: () => Promise<Array<{
+        package: string;
+        code: string;
+        severity: string;
+        message: string;
+    }>>;
+}, { json }?: {
     json?: boolean;
 }): Promise<void>;

package/foundation/integrations/integration-warnings.mjs

@@ -10,8 +10,9 @@
  * contributions or spamming per-contribution diagnostics.
  *
  * Design constraints (all enforced here):
- *   - Reuses the Doctor integration validators (validateLoadedIntegration);
- *     no validation logic is duplicated.
+ *   - Reuses Project.issues() when a Project is available, so cross-package
+ *     replacement warnings are visible; accepts loaded integrations for legacy
+ *     internal callers and tests.
  *   - Writes to STDERR only, so it never corrupts a --json stdout envelope.
  *   - Suppressed entirely in --json mode.
  *   - Best-effort: never throws, never changes the exit code. Broken
@@ -28,38 +29,62 @@ import {validateLoadedIntegration} from './validate-contributions.mjs';
  *
  *   Warning: <pkg> has N integration issue(s). Run: astryx doctor integration validate <pkg>
  *
- * @param {Array<import('./integrations.mjs').LoadedIntegration>} loadedIntegrations the Project's loaded integrations
+ * @param {Array<import('./integrations.mjs').LoadedIntegration> | {issues: () => Promise<Array<{package: string, code: string, severity: string, message: string}>>}} source loaded integrations or their Project owner
  * @param {{json?: boolean}} [options]
  * @returns {Promise<void>}
  */
-export async function warnOnIntegrationIssues(loadedIntegrations, {json = false} = {}) {
+export async function warnOnIntegrationIssues(source, {json = false} = {}) {
   try {
-    // Cheap guard: only do work when integrations are actually configured.
     if (json) return;
-    if (!Array.isArray(loadedIntegrations) || loadedIntegrations.length === 0) {
-      return;
-    }
-    for (const integration of loadedIntegrations) {
-      if (!integration || typeof integration !== 'object') continue;
-      // A package set aside for a provider-ID conflict is fine in isolation,
-      // so `doctor integration validate` would not explain it. Say it here.
-      if (integration.__providerConflict) {
-        console.error(`Warning: ${integration.__providerConflict.message}`);
-        continue;
+
+    /** @type {Map<string, number>} */
+    const issueCounts = new Map();
+    const fromProject =
+      source != null &&
+      !Array.isArray(source) &&
+      typeof source.issues === 'function';
+
+    if (fromProject) {
+      const issues = await source.issues();
+      for (const issue of issues) {
+        // A provider-conflict issue carries the specific message that
+        // `doctor integration validate` would not explain. Print it directly.
+        if (issue.code === 'duplicate_provider') {
+          console.error(`Warning: ${issue.message}`);
+          continue;
+        }
+        issueCounts.set(
+          issue.package,
+          (issueCounts.get(issue.package) ?? 0) + 1,
+        );
       }
-      let issues;
-      try {
-        issues = await validateLoadedIntegration(integration);
-      } catch {
-        // Best-effort: a validator throwing must not break the host command.
-        continue;
+    } else if (Array.isArray(source)) {
+      for (const integration of source) {
+        if (!integration || typeof integration !== 'object') continue;
+        // A package set aside for a provider-ID conflict is fine in isolation,
+        // so `doctor integration validate` would not explain it. Say it here.
+        if (integration.__providerConflict) {
+          console.error(`Warning: ${integration.__providerConflict.message}`);
+          continue;
+        }
+        let issues;
+        try {
+          issues = await validateLoadedIntegration(integration);
+        } catch {
+          continue;
+        }
+        if (!Array.isArray(issues) || issues.length === 0) continue;
+        const pkg = integration.name ?? integration.__spec ?? '(integration)';
+        issueCounts.set(pkg, issues.length);
       }
-      if (!Array.isArray(issues) || issues.length === 0) continue;
-      const pkg = integration.name ?? integration.__spec ?? '(integration)';
-      // Stderr only — keeps stdout (and any --json envelope) clean.
+    }
+
+    for (const [pkg, count] of issueCounts) {
+      const command = fromProject
+        ? 'astryx doctor'
+        : `astryx doctor integration validate ${pkg}`;
       console.error(
-        `Warning: ${pkg} has ${issues.length} integration issue(s). ` +
-          `Run: astryx doctor integration validate ${pkg}`,
+        `Warning: ${pkg} has ${count} integration issue(s). Run: ${command}`,
       );
     }
   } catch {

package/foundation/integrations/integration-warnings.test.mjs

@@ -37,7 +37,12 @@ afterEach(() => {
  * Build a loaded-integration-shaped object. Roots are absolute (mirrors
  * loadIntegrations' resolveRoot).
  */
-function loaded({name = '@acme/widgets', components, templates, codemods} = {}) {
+function loaded({
+  name = '@acme/widgets',
+  components,
+  templates,
+  codemods,
+} = {}) {
   return {
     name,
     version: '1.0.0',
@@ -62,6 +67,25 @@ describe('warnOnIntegrationIssues', () => {
     );
   });
 
+  it('surfaces cross-package issues collected by Project', async () => {
+    const project = {
+      issues: async () => [
+        {
+          package: '@acme/later',
+          code: 'ambiguous_template_replacement',
+          severity: 'warning',
+          message: 'Later configured replacement wins.',
+        },
+      ],
+    };
+
+    await warnOnIntegrationIssues(project, {json: false});
+
+    expect(errLines).toEqual([
+      'Warning: @acme/later has 1 integration issue(s). Run: astryx doctor',
+    ]);
+  });
+
   it('emits nothing in --json mode (keeps stdout/JSON clean)', async () => {
     const integration = loaded({components: 'does-not-exist'});
     await warnOnIntegrationIssues([integration], {json: true});
@@ -116,4 +140,53 @@ describe('warnOnIntegrationIssues', () => {
     ).resolves.toBeUndefined();
     expect(errLines).toHaveLength(0);
   });
+
+  it('prints the specific provider-conflict message via the array path', async () => {
+    const conflict = {
+      name: '@acme/charts',
+      version: '2.0.0',
+      __spec: '@acme/charts',
+      __packageDir: tmpDir,
+      __providerConflict: {
+        providerId: '@acme/lab',
+        claimedBy: '@acme/lab',
+        message:
+          '@acme/charts@2.0.0 and @acme/lab@1.0.0 both claim provider ID ' +
+          '"@acme/lab". @acme/lab@1.0.0 loads first and is used; ' +
+          '@acme/charts@2.0.0 contributes nothing until one package changes ' +
+          'its providerId.',
+      },
+    };
+    await warnOnIntegrationIssues([conflict], {json: false});
+
+    expect(errLines).toHaveLength(1);
+    expect(errLines[0]).toBe(`Warning: ${conflict.__providerConflict.message}`);
+    // Must NOT print the generic validate pointer for a provider conflict.
+    expect(errLines[0]).not.toContain('integration issue(s)');
+  });
+
+  it('prints the specific provider-conflict message via the Project path', async () => {
+    const conflictMessage =
+      '@acme/charts@2.0.0 and @acme/lab@1.0.0 both claim provider ID ' +
+      '"@acme/lab". @acme/lab@1.0.0 loads first and is used; ' +
+      '@acme/charts@2.0.0 contributes nothing until one package changes ' +
+      'its providerId.';
+    const project = {
+      issues: async () => [
+        {
+          package: '@acme/charts@2.0.0',
+          code: 'duplicate_provider',
+          severity: 'warning',
+          message: conflictMessage,
+        },
+      ],
+    };
+
+    await warnOnIntegrationIssues(project, {json: false});
+
+    expect(errLines).toHaveLength(1);
+    expect(errLines[0]).toBe(`Warning: ${conflictMessage}`);
+    // Must NOT print the generic validate pointer for a provider conflict.
+    expect(errLines[0]).not.toContain('integration issue(s)');
+  });
 });

package/foundation/integrations/validate-contributions.mjs

@@ -236,7 +236,11 @@ async function checkTemplates(integration, issues) {
   try {
     const {errors} = await discoverIntegrationTemplatesForOne(integration);
     for (const e of errors) {
-      issues.push(issueError('invalid_template', e.message));
+      issues.push({
+        code: e.code ?? 'invalid_template',
+        severity: e.severity ?? 'error',
+        message: e.message,
+      });
     }
   } catch (err) {
     issues.push(
@@ -246,41 +250,35 @@ async function checkTemplates(integration, issues) {
 }
 
 /**
- * Validate the integration's components via the landed ownership discovery.
- * Feature-detected: if the component-ownership export isn't present in this
- * build (sibling PR not yet merged), component validation is skipped rather
- * than hard-failing.
- *
- * `discoverIntegrationComponents` returns ownership records and does not throw
- * on a missing same-stem source — it records `sourcePath: null`. We surface
- * each such record as an `invalid_component` error.
+ * Validate the integration's components through the same load-and-parse boundary
+ * that component detail uses. Missing source and invalid metadata are reported
+ * per component so valid siblings remain available.
  * @param {LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkComponents(integration, issues) {
   if (!integration.components || !fs.existsSync(integration.components)) return;
-  const discover = componentDiscovery.discoverIntegrationComponents;
+  const discover = componentDiscovery.discoverValidIntegrationComponents;
   if (typeof discover !== 'function') return; // feature not present yet
   try {
-    const records = (await discover(integration)) ?? [];
+    const {discovered, errors} = await discover(integration);
     /** @type {import('./contribution-fixes.mjs').FixContext | undefined} */
     let context;
-    for (const record of records) {
-      if (record?.sourcePath == null) {
-        const docPath = record?.docPath;
-        let fix = `Fix: add ${record?.name}.tsx beside ${docPath ? path.basename(docPath) : `${record?.name}.doc.mjs`}.`;
-        const stamp = docPath ? readContributionStamp(docPath, false) : null;
-        if (stamp && stamp.type !== 'component' && integration.__packageDir) {
-          context ??= createFixContext(integration.__packageDir, integration);
-          fix = notAComponentFix(context, docPath, stamp);
-        }
-        issues.push(
-          issueError(
-            'invalid_component',
-            `Component "${record?.name}" is missing its same-stem source file ${record?.name}.tsx. ${fix}`,
-          ),
-        );
+    const byName = new Map(discovered.map(record => [record.name, record]));
+    for (const error of errors) {
+      const record = byName.get(error.name);
+      if (record == null || record.sourcePath != null) {
+        issues.push(issueError('invalid_component', error.message));
+        continue;
+      }
+      const docPath = record.docPath;
+      let fix = `Fix: add ${record.name}.tsx beside ${docPath ? path.basename(docPath) : `${record.name}.doc.mjs`}.`;
+      const stamp = docPath ? readContributionStamp(docPath, false) : null;
+      if (stamp && stamp.type !== 'component' && integration.__packageDir) {
+        context ??= createFixContext(integration.__packageDir, integration);
+        fix = notAComponentFix(context, docPath, stamp);
       }
+      issues.push(issueError('invalid_component', `${error.message} ${fix}`));
     }
     const overlap = integration.__packageDir
       ? newComponentDocNote(
@@ -289,7 +287,7 @@ async function checkComponents(integration, issues) {
       : '';
     for (const name of findSourceOnlyCandidates(
       integration.components,
-      records.map(record => record.name),
+      discovered.map(record => record.name),
     )) {
       // A hidden doc still pairs with its source; discovery just skips it.
       if (

package/foundation/response/response-types.doc.d.mts

@@ -5,7 +5,11 @@
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
  * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload.
+ * switches on `type` to narrow the `data` payload. Descriptions follow the
+ * currently published response projection, not a future package-version boundary.
+ *
+ * @input Public response discriminants and their currently released payloads.
+ * @output Generated consumer reference for every typed JSON success response.
  * @position packages/cli/foundation/response — enum documentation
  */
 /** @type {import('@astryxdesign/cli/authoring').EnumDoc} */