@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/api/integration/_adapter.d.mts

@@ -0,0 +1,53 @@
+// @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>;
+/**
+ * The passages two of a package's topics, or one of them and a Core topic,
+ * repeat word for word (architecture:cli-surface DEC-8). Reads the package's
+ * topics and Core's guides.
+ *
+ * @param {Parameters<typeof findCopiedPassages>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ */
+export function integrationCopiedPassages(discovered: Parameters<typeof findCopiedPassages>[0]): Promise<import("./authoring-checks.type.mjs").CopiedPassage[]>;
+/**
+ * Padding phrases and low-density topics in a package's prose
+ * (architecture:cli-surface DEC-8). Reads the package's topics, and Core's
+ * guides for the density median a finding names.
+ *
+ * @param {Parameters<typeof findFluff>[0]} discovered the package's docs, as
+ *   discoverIntegrationDocs returns them
+ */
+export function integrationFluff(discovered: Parameters<typeof findFluff>[0]): Promise<import("./authoring-checks.type.mjs").DocFluff[]>;
+/**
+ * Code spans in a package's prose that write `astryx docs <name>` for a doc
+ * that exists, where `{@link generic:<name>}` would be checked
+ * (architecture:cli-surface DEC-8). Reads the package's topics, its own
+ * component docs, and the names of Core's docs.
+ *
+ * @param {Parameters<typeof findStrayPointers>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ * @param {any} [integration] the loaded integration, whose component docs are
+ *   read too
+ */
+export function integrationStrayPointers(discovered: Parameters<typeof findStrayPointers>[0], integration?: any): Promise<import("./authoring-checks.type.mjs").StrayPointer[]>;
+/**
+ * Each Astryx command a package's topics write with a package runner. A
+ * package whose topics cannot be discovered has none here: the other checks
+ * report topics that do not load.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<import('../../foundation/discovery/runner-commands.mjs').RunnerCommand[]>}
+ */
+export function integrationRunnerCommands(integration: any): Promise<import("../../foundation/discovery/runner-commands.mjs").RunnerCommand[]>;
+import { findCopiedPassages } from '../../foundation/discovery/copied-passages.mjs';
+import { findFluff } from '../../foundation/discovery/doc-fluff.mjs';
+import { findStrayPointers } from '../../foundation/discovery/stray-pointers.mjs';

package/api/integration/_adapter.mjs

@@ -0,0 +1,132 @@
+// 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,
+ * and its topics.
+ *
+ * @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 {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
+import {comparePropDocs} from '../../foundation/discovery/prop-drift.mjs';
+import {findCopiedPassages} from '../../foundation/discovery/copied-passages.mjs';
+import {findFluff} from '../../foundation/discovery/doc-fluff.mjs';
+import {findRunnerCommands} from '../../foundation/discovery/runner-commands.mjs';
+import {findStrayPointers} from '../../foundation/discovery/stray-pointers.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],
+  });
+}
+
+/**
+ * The passages two of a package's topics, or one of them and a Core topic,
+ * repeat word for word (architecture:cli-surface DEC-8). Reads the package's
+ * topics and Core's guides.
+ *
+ * @param {Parameters<typeof findCopiedPassages>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ */
+export function integrationCopiedPassages(discovered) {
+  return findCopiedPassages(discovered);
+}
+
+/**
+ * Padding phrases and low-density topics in a package's prose
+ * (architecture:cli-surface DEC-8). Reads the package's topics, and Core's
+ * guides for the density median a finding names.
+ *
+ * @param {Parameters<typeof findFluff>[0]} discovered the package's docs, as
+ *   discoverIntegrationDocs returns them
+ */
+export function integrationFluff(discovered) {
+  return findFluff(discovered);
+}
+
+/**
+ * Code spans in a package's prose that write `astryx docs <name>` for a doc
+ * that exists, where `{@link generic:<name>}` would be checked
+ * (architecture:cli-surface DEC-8). Reads the package's topics, its own
+ * component docs, and the names of Core's docs.
+ *
+ * @param {Parameters<typeof findStrayPointers>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ * @param {any} [integration] the loaded integration, whose component docs are
+ *   read too
+ */
+export async function integrationStrayPointers(discovered, integration) {
+  /** @type {{name: string, file: string}[]} */
+  const components = [];
+  if (integration?.components) {
+    const seen = new Set();
+    try {
+      const {components: records} =
+        await discoverValidIntegrationComponents(integration);
+      for (const record of records) {
+        if (!record.docPath || seen.has(record.docPath)) continue;
+        seen.add(record.docPath);
+        components.push({name: record.name, file: record.docPath});
+      }
+    } catch {
+      // `validate` reports component docs that do not load.
+    }
+  }
+  return findStrayPointers({...discovered, components});
+}
+
+/**
+ * Each Astryx command a package's topics write with a package runner. A
+ * package whose topics cannot be discovered has none here: the other checks
+ * report topics that do not load.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<import('../../foundation/discovery/runner-commands.mjs').RunnerCommand[]>}
+ */
+export async function integrationRunnerCommands(integration) {
+  let discovered;
+  try {
+    discovered = await discoverIntegrationDocs(integration);
+  } catch {
+    return [];
+  }
+  return findRunnerCommands(discovered);
+}

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[]} */

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

@@ -536,7 +536,9 @@ describe('integrationAdd template', () => {
       path.join(tmpDir, 'templates/my-widget.doc.mjs'),
       'utf-8',
     );
-    expect(spec).toContain("@astryxdesign/cli/authoring').TemplateDoc");
+    expect(spec).toContain(
+      "@astryxdesign/cli/authoring').IntegrationTemplateDoc",
+    );
     expect(spec).toContain("type: 'page'");
     expect(spec).toContain("name: 'my-widget'");
 
@@ -830,7 +832,7 @@ describe('typed descriptor conformance', () => {
     for (const [relativePath, type] of [
       ['components/MyWidget.doc.mjs', 'ComponentDoc'],
       ['docs/my-guide.doc.mjs', 'ReferenceDoc'],
-      ['templates/my-page.doc.mjs', 'TemplateDoc'],
+      ['templates/my-page.doc.mjs', 'IntegrationTemplateDoc'],
       ['themes/ocean/oceanTheme.doc.mjs', 'ThemeDoc'],
     ]) {
       const source = fs.readFileSync(path.join(tmpDir, relativePath), 'utf-8');

package/api/integration/authoring-checks.mjs

@@ -3,6 +3,10 @@
 /**
  * @file Integration authoring diagnostics against the built-in Core catalog.
  *
+ * The components check also compares each component doc's props with the
+ * component's TypeScript props (foundation/discovery/prop-drift.mjs); those
+ * findings are warnings under `propDrift`.
+ *
  * Templates may intentionally replace Core identities; undeclared same-id
  * overlaps stay fail-closed and require package selection. The CLI package
  * version gates replacement-specific fields so 0.6.x keeps its released shape.
@@ -14,17 +18,25 @@
  * @position Public integration-authoring API over private discovery adapters.
  */
 
+import path from 'node:path';
 import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {
+  packageComponentLinkProblems,
   packageDocsProblems,
   packageReferenceProblems,
 } from '../docs/_adapter.mjs';
-import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {findProjectCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverIntegrationComponents,
   discoverOwnedComponents,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {loadComponentReplacements} from '../component/_adapter.mjs';
+import {
+  integrationCopiedPassages,
+  integrationFluff,
+  integrationPropDrift,
+  integrationStrayPointers,
+} from './_adapter.mjs';
 import {
   discoverBuiltinTopics,
   discoverIntegrationDocs,
@@ -39,6 +51,8 @@ import {
   validateInstalledIntegration,
   validateLocalIntegration,
 } from './validate-integration.mjs';
+import {rootProblem} from '../../foundation/integrations/validate-contributions.mjs';
+import {normalizeProviderId} from '../../foundation/identity/provider-identity.mjs';
 
 /** @param {string} value */
 export function shellArg(value) {
@@ -46,15 +60,61 @@ export function shellArg(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * The provider ID a package without a name is checked under: a valid bare
+ * package name no published package can hold (npm names are lowercase).
+ */
+const UNNAMED_PROVIDER = 'astryx-unnamed-local-package';
+
+/**
+ * A message as the package sees it: the stand-in provider ID gone, its docs
+ * named by their path in the package.
+ * @param {string} message
+ */
+function unnamedShown(message) {
+  return message
+    .split(`${UNNAMED_PROVIDER}/`)
+    .join('')
+    .split(UNNAMED_PROVIDER)
+    .join('this package');
+}
+
 /**
  * Resolve one local or installed integration for an authoring check.
  * @param {string | undefined} pkg
  * @param {string} cwd
  */
 async function resolveIntegration(pkg, cwd) {
-  return pkg
-    ? validateInstalledIntegration(pkg, cwd)
-    : validateLocalIntegration(cwd);
+  const resolved = pkg
+    ? await validateInstalledIntegration(pkg, cwd)
+    : await validateLocalIntegration(cwd);
+  const integration = resolved.found ? resolved.integration : undefined;
+  if (!integration) return resolved;
+  // A root that is not a readable folder is reported in the issues; the
+  // checks read nothing from it rather than fail on it.
+  /** @type {typeof integration & {__unnamed?: boolean}} */
+  const usable = {...integration};
+  // The provider ID readers key the package on: the manifest's providerId,
+  // else its name. A package with neither (validate warned about it) is
+  // still checked; the docs check names its docs under a stand-in ID.
+  try {
+    usable.providerId = normalizeProviderId(
+      integration.__declaredProviderId ?? integration.name,
+    );
+  } catch {
+    usable.__unnamed = true;
+  }
+  for (const kind of /** @type {const} */ ([
+    'components',
+    'templates',
+    'codemods',
+    'docs',
+    'themes',
+  ])) {
+    const root = usable[kind];
+    if (root != null && rootProblem(root)) usable[kind] = undefined;
+  }
+  return {...resolved, integration: usable};
 }
 
 /**
@@ -242,7 +302,24 @@ export async function integrationComponentConflicts(pkg, options = {}) {
     };
   }
 
-  const coreDir = findCoreDir(cwd);
+  // Each documented prop against the component's TypeScript props, read with
+  // the project's own compiler; without one the report says it was skipped.
+  const propDrift = await integrationPropDrift(resolved.integration, cwd);
+
+  // A link in a component doc's text reads as the command that opens its doc,
+  // as one in a topic does; one that names no doc prints as written, so it is
+  // a warning (spec:AST-047 FR9). The package's own topics are linkable.
+  const ownDocs = resolved.integration.docs
+    ? await discoverIntegrationDocs(resolved.integration)
+    : null;
+  for (const {severity, message} of await packageComponentLinkProblems(
+    resolved.integration,
+    ownDocs,
+  )) {
+    issues.push({code: 'invalid_doc_graph', severity, message});
+  }
+
+  const coreDir = findProjectCoreDir(cwd);
   if (!coreDir) {
     issues.push({
       code: 'core_not_found',
@@ -252,7 +329,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
     });
     return {
       type: 'integration.component-conflicts',
-      data: {validated, name, version, conflicts: [], issues},
+      data: {validated, name, version, conflicts: [], issues, propDrift},
     };
   }
 
@@ -296,7 +373,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
 
   return {
     type: 'integration.component-conflicts',
-    data: {validated, name, version, conflicts, issues},
+    data: {validated, name, version, conflicts, issues, propDrift},
   };
 }
 
@@ -314,15 +391,64 @@ export async function integrationDocConflicts(pkg, options = {}) {
   const version = resolved.found ? (resolved.version ?? null) : null;
   const issues = [...resolved.issues];
 
+  /** @type {import('./authoring-checks.type.mjs').CopiedPassage[]} */
+  const copiedPassages = [];
+  /** @type {import('./authoring-checks.type.mjs').DocFluff[]} */
+  const fluff = [];
+  /** @type {import('./authoring-checks.type.mjs').StrayPointer[]} */
+  const strayPointers = [];
+  // Like the other findings' `doc`, a fluff or stray-pointer `file` is
+  // relative to the package root.
+  const packageDir = /** @type {any} */ (resolved.integration)?.__packageDir;
+  const fromPackage = (/** @type {string} */ file) =>
+    typeof packageDir === 'string'
+      ? path.relative(packageDir, file).split(path.sep).join('/')
+      : file;
   if (!resolved.integration?.docs || name == null) {
+    // A package that ships components and no topics still has component docs
+    // a written pointer can sit in.
+    if (name != null && resolved.integration?.components) {
+      strayPointers.push(
+        ...(
+          await integrationStrayPointers(
+            {records: [], guides: []},
+            resolved.integration,
+          )
+        ).map(each => ({...each, file: fromPackage(each.file)})),
+      );
+      for (const {message} of strayPointers) {
+        issues.push({code: 'stray_doc_pointer', severity: 'warning', message});
+      }
+    }
     return {
       type: 'integration.doc-conflicts',
-      data: {validated, name, version, findings: [], issues},
+      data: {
+        validated,
+        name,
+        version,
+        findings: [],
+        copiedPassages,
+        fluff,
+        strayPointers,
+        issues,
+      },
     };
   }
 
+  // The docs tree names a package's docs by its provider ID, which a
+  // package.json without a name does not give: its docs are checked under a
+  // stand-in ID, which no message names.
+  const unnamed = /** @type {{__unnamed?: boolean}} */ (resolved.integration)
+    .__unnamed;
+  const docsIntegration = unnamed
+    ? {
+        ...resolved.integration,
+        name: UNNAMED_PROVIDER,
+        providerId: UNNAMED_PROVIDER,
+      }
+    : resolved.integration;
   const [discovered, builtinTopics] = await Promise.all([
-    discoverIntegrationDocs(resolved.integration),
+    discoverIntegrationDocs(docsIntegration),
     Promise.resolve(discoverBuiltinTopics()),
   ]);
   const {records, errors} = discovered;
@@ -392,25 +518,77 @@ export async function integrationDocConflicts(pkg, options = {}) {
   // its docs (spec:AST-046, spec:AST-047).
   if (errors.length === 0) {
     for (const {severity, message} of await packageDocsProblems(
-      /** @type {{name: string}} */ (resolved.integration),
+      /** @type {{name: string}} */ (docsIntegration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_graph', severity, message});
+      issues.push({
+        code: 'invalid_doc_graph',
+        severity,
+        message: unnamedShown(message),
+      });
     }
 
     // A reference block includes content rather than linking to it, so one
     // that cannot include what it names loses that content for every reader:
     // an error, where a link that names no doc still prints as written.
     for (const message of await packageReferenceProblems(
-      /** @type {{name: string}} */ (resolved.integration),
+      /** @type {{name: string}} */ (docsIntegration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_reference', severity: 'error', message});
+      issues.push({
+        code: 'invalid_doc_reference',
+        severity: 'error',
+        message: unnamedShown(message),
+      });
+    }
+
+    // One fact has one owner: a passage two topics repeat goes stale in one
+    // of them. Each is listed and is a warning (architecture:cli-surface
+    // DEC-8), so `integration check --strict` fails until it is fixed;
+    // `doctor integration docs` keeps its exit code, as it fails on errors.
+    copiedPassages.push(
+      ...(await integrationCopiedPassages(discovered)).map(passage => ({
+        ...passage,
+        message: unnamedShown(passage.message),
+      })),
+    );
+    for (const {message} of copiedPassages) {
+      issues.push({code: 'copied_passage', severity: 'warning', message});
+    }
+    // Docs should be dense: padding phrases and mostly-glue topics, listed
+    // and warned about the same way (DEC-8).
+    fluff.push(
+      ...(await integrationFluff(discovered)).map(each => ({
+        ...each,
+        file: fromPackage(each.file),
+        message: unnamedShown(each.message),
+      })),
+    );
+    for (const {message} of fluff) {
+      issues.push({code: 'doc_fluff', severity: 'warning', message});
+    }
+    // A pointer to a doc is a link, so doctor checks it (DEC-8).
+    strayPointers.push(
+      ...(await integrationStrayPointers(discovered, resolved.integration)).map(
+        each => ({...each, file: fromPackage(each.file)}),
+      ),
+    );
+    for (const {message} of strayPointers) {
+      issues.push({code: 'stray_doc_pointer', severity: 'warning', message});
     }
   }
 
   return {
     type: 'integration.doc-conflicts',
-    data: {validated, name, version, findings, issues},
+    data: {
+      validated,
+      name,
+      version,
+      findings,
+      copiedPassages,
+      fluff,
+      strayPointers,
+      issues,
+    },
   };
 }