@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/integration/authoring-checks.test.mjs

@@ -18,6 +18,11 @@ import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter
 import {discoverOwnedComponents} from '../../foundation/discovery/component-discovery.mjs';
 import {discoverBuiltinTopics} from '../../foundation/discovery/docs-discovery.mjs';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {
+  builtinGuideFiles,
+  loadTopicModule,
+} from '../../foundation/discovery/docs-discovery.mjs';
+import {proseWords} from '../../foundation/discovery/copied-passages.mjs';
 import {
   integrationComponentConflicts,
   integrationDocConflicts,
@@ -99,6 +104,44 @@ function writeDocIntegration({name, replaces, extendsTopic}) {
   );
 }
 
+/**
+ * A docs-only package with one generic topic per entry: its prose, and
+ * optionally a code block and the Core topic it replaces.
+ * @param {{name: string, text: string, code?: string, replaces?: string}[]} topics
+ */
+function writeTopics(topics) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    `export default {docs: './docs'};\n`,
+  );
+  fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+  for (const {name, text, code, replaces, extendsTopic} of topics) {
+    const blocks = [{type: 'prose', text}];
+    if (code != null) blocks.push({type: 'code', lang: 'text', code});
+    const doc = {
+      type: 'generic',
+      name,
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      ...(replaces == null ? {} : {replaces}),
+      ...(extendsTopic == null ? {} : {extends: extendsTopic}),
+      sections: [{title: 'Overview', content: blocks}],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', `${name}.doc.mjs`),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+  }
+}
+
+const PASSAGE =
+  'Themes cannot style the layer that holds a menu or a popover, so a menu ' +
+  'keeps the default surface color until the next release adds a token for it.';
+
 beforeEach(() => {
   tmpDir = fs.mkdtempSync(
     path.join(process.cwd(), '.astryx-template-conflicts-'),
@@ -562,3 +605,729 @@ describe('integrationDocConflicts', () => {
     ]);
   });
 });
+
+describe('integrationDocConflicts copied passages', () => {
+  const copied = (/** @type {any} */ result) => result.data.copiedPassages;
+
+  it('lists a passage two of the package topics repeat, and warns about it', async () => {
+    writeTopics([
+      {name: 'acme-setup', text: `Read this first. ${PASSAGE}`},
+      {name: 'acme-menus', text: `${PASSAGE} See the theme guide.`},
+    ]);
+
+    const result = await integrationDocConflicts(undefined, {cwd: tmpDir});
+    const [issue, ...rest] = copied(result);
+    expect(result.data.issues).toEqual([
+      {code: 'copied_passage', severity: 'warning', message: issue.message},
+    ]);
+
+    expect(rest).toEqual([]);
+    // The passage is about menus, so "acme-menus" keeps it.
+    expect(issue).toMatchObject({
+      topic: 'acme-setup',
+      otherTopic: 'acme-menus',
+      otherOwner: 'package',
+      owner: 'acme-menus',
+      section: 'Overview',
+      line: 1,
+      words: PASSAGE.split(' ').length,
+      passages: 1,
+    });
+    expect(issue.message).toContain(`${PASSAGE.split(' ').length} words`);
+    expect(issue.text).toBe(PASSAGE);
+    expect(issue.message).toContain(`"${PASSAGE}"`);
+    expect(issue.message).toContain(
+      '"acme-menus" keeps it: its name, title or section fits the passage.',
+    );
+    expect(issue.message).toContain(
+      'In "acme-setup", replace that whole passage, from its first word to its last, code ticks included, with {@link generic:acme-menus}.',
+    );
+  });
+
+  it('reports a passage copied from a Core topic, except into the topic that replaces it', async () => {
+    const [file] = builtinGuideFiles();
+    const coreDoc = /** @type {any} */ (await loadTopicModule(file));
+    const coreText = proseWords(coreDoc)
+      .slice(0, 30)
+      .map(each => each.word)
+      .join(' ');
+
+    writeTopics([{name: 'acme-copy', text: coreText}]);
+    const [issue] = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+    expect(issue.otherOwner).toBe('core');
+    expect(issue.message).toContain(`the Core topic "${coreDoc.name}"`);
+    expect(issue.owner).toBe(coreDoc.name);
+    expect(issue.message).toContain(
+      `code ticks included, with {@link @astryxdesign/cli:generic:${coreDoc.name}}.`,
+    );
+
+    fs.rmSync(path.join(tmpDir, 'docs'), {recursive: true, force: true});
+    writeTopics([{name: 'acme-own', text: coreText, replaces: coreDoc.name}]);
+    expect(
+      copied(await integrationDocConflicts(undefined, {cwd: tmpDir})).filter(
+        (/** @type {any} */ each) => each.message.includes(`"${coreDoc.name}"`),
+      ),
+    ).toEqual([]);
+  });
+
+  it('leaves out boilerplate that three topics share', async () => {
+    writeTopics([
+      {name: 'acme-fonts', text: PASSAGE},
+      {name: 'acme-icons', text: PASSAGE},
+      {name: 'acme-media', text: PASSAGE},
+    ]);
+
+    expect(
+      copied(await integrationDocConflicts(undefined, {cwd: tmpDir})),
+    ).toEqual([]);
+  });
+
+  it('leaves out a run of function words, which states no fact', async () => {
+    const glue = 'and it is in the way that you can do it for them';
+    writeTopics([
+      {name: 'acme-a', text: `Start here. ${glue} first.`},
+      {name: 'acme-b', text: `Then ${glue} again.`},
+    ]);
+
+    expect(
+      copied(await integrationDocConflicts(undefined, {cwd: tmpDir})),
+    ).toEqual([]);
+  });
+
+  it('leaves out a shared phrase under 10 words, and code', async () => {
+    const short = PASSAGE.split(' ').slice(0, 9).join(' ');
+    writeTopics([
+      {name: 'acme-a', text: PASSAGE},
+      {name: 'acme-b', text: short},
+      {name: 'acme-c', text: 'Run it.', code: PASSAGE},
+    ]);
+
+    expect(
+      copied(await integrationDocConflicts(undefined, {cwd: tmpDir})),
+    ).toEqual([]);
+  });
+});
+
+describe('integrationDocConflicts copied passages and extensions', () => {
+  const copied = (/** @type {any} */ result) => result.data.copiedPassages;
+
+  it('links to the page an extension shows on, not to the extension', async () => {
+    writeTopics([
+      {name: 'acme-menus', text: PASSAGE, extendsTopic: 'theme'},
+      {name: 'acme-setup', text: `${PASSAGE} Then run setup.`},
+    ]);
+
+    const [issue] = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(issue).toMatchObject({topic: 'acme-setup', owner: 'acme-menus'});
+    expect(issue.message).toContain(
+      'with {@link @astryxdesign/cli:generic:theme}.',
+    );
+  });
+
+  it('says to delete a copy in a topic that extends its owner', async () => {
+    writeTopics([
+      {name: 'acme-base', text: PASSAGE},
+      {name: 'acme-more', text: PASSAGE, extendsTopic: 'acme-base'},
+    ]);
+
+    const [issue] = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(issue).toMatchObject({topic: 'acme-more', owner: 'acme-base'});
+    expect(issue.message).toContain(
+      '"acme-more" and "acme-base" show on the same page ("acme-base"): delete the passage from "acme-more"',
+    );
+    expect(issue.message).not.toContain('{@link');
+  });
+
+  it('compares pages without regard to case, and for two extensions of one page', async () => {
+    writeTopics([
+      {name: 'acme-colors', text: PASSAGE, extendsTopic: 'Theme'},
+      {name: 'acme-menus', text: PASSAGE, extendsTopic: 'theme'},
+    ]);
+
+    const [issue] = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(issue.message).toContain('show on the same page ("theme")');
+    expect(issue.message).not.toContain('{@link');
+  });
+
+  it('finds the line of the string that holds the copy, whatever it opens with', async () => {
+    writeTopics([{name: 'acme-menus', text: PASSAGE}]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      [
+        'export default {',
+        "  type: 'generic',",
+        "  name: 'acme-setup',",
+        "  title: 'Fixture',",
+        "  description: 'Fixture topic.',",
+        "  sections: [{title: 'Overview', content: [",
+        "    {type: 'prose', text: '`acme` (the CLI) opens here, as {@link generic:acme-menus} says.'},",
+        `    {type: 'prose', text: '\`acme\` (the CLI) opens here: ${PASSAGE}'},`,
+        '  ]}],',
+        '};',
+        '',
+      ].join('\n'),
+    );
+
+    const [issue] = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(issue).toMatchObject({topic: 'acme-setup', line: 8});
+  });
+
+  it('does not list a 9-word sentence that ends in a link', async () => {
+    const sentence =
+      'Theme tokens control every surface color, as explained in {@link generic:acme-theme}.';
+    writeTopics([
+      {name: 'acme-colors', text: `Colors first. ${sentence}`},
+      {name: 'acme-menus', text: `Menus next. ${sentence}`},
+    ]);
+
+    expect(
+      copied(await integrationDocConflicts(undefined, {cwd: tmpDir})),
+    ).toEqual([]);
+  });
+
+  it('counts no function word toward which topic a passage fits', async () => {
+    writeTopics([
+      {name: 'acme-getting-started', text: `${PASSAGE} Then run setup.`},
+      {name: 'acme-menus', text: PASSAGE},
+    ]);
+    // Titles that share only function words with the passage.
+    for (const [name, title] of [
+      ['acme-getting-started', 'Get started with the widgets'],
+      ['acme-menus', 'Menus'],
+    ]) {
+      const file = path.join(tmpDir, 'docs', `${name}.doc.mjs`);
+      fs.writeFileSync(
+        file,
+        fs
+          .readFileSync(file, 'utf8')
+          .replace('"title":"Fixture"', `"title":"${title}"`),
+      );
+    }
+
+    const [issue] = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(issue).toMatchObject({
+      owner: 'acme-menus',
+      topic: 'acme-getting-started',
+    });
+  });
+
+  it('finds a copy after a lead-in three topics share', async () => {
+    const lead =
+      'Every package ships its integration docs as plain modules the CLI reads';
+    writeTopics([
+      {name: 'acme-menus', text: `${lead}. ${PASSAGE}`},
+      {name: 'acme-setup', text: `${lead}. ${PASSAGE} Then run setup.`},
+      {name: 'acme-other', text: `${lead}. Nothing else here is shared.`},
+    ]);
+
+    const found = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(found).toHaveLength(1);
+    expect(found[0].text).toBe(PASSAGE);
+  });
+
+  it("links to a package topic that replaces Core's by its own name", async () => {
+    writeTopics([
+      {name: 'theme', text: PASSAGE, replaces: 'theme'},
+      {name: 'acme-setup', text: `${PASSAGE} Then run setup.`},
+    ]);
+
+    const found = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    for (const each of found) {
+      expect(each.message).not.toContain('@astryxdesign/cli:generic:theme');
+    }
+    expect(
+      found.some((/** @type {any} */ each) =>
+        each.message.includes('with {@link generic:theme}.'),
+      ),
+    ).toBe(true);
+  });
+
+  it('prints no link to a Core topic one of the package topics replaces', async () => {
+    const [file] = builtinGuideFiles();
+    const coreDoc = /** @type {any} */ (await loadTopicModule(file));
+    const coreText = proseWords(coreDoc)
+      .slice(0, 30)
+      .map(each => each.word)
+      .join(' ');
+    writeTopics([
+      {name: 'acme-own', text: 'Our version.', replaces: coreDoc.name},
+      {name: 'acme-copy', text: coreText},
+    ]);
+
+    const found = copied(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    ).filter((/** @type {any} */ each) => each.owner === coreDoc.name);
+
+    expect(found).toHaveLength(1);
+    expect(found[0].message).toContain(
+      `"acme-own" replaces the Core topic "${coreDoc.name}"`,
+    );
+    expect(found[0].message).not.toContain('{@link');
+  });
+});
+
+describe('integrationDocConflicts fluff', () => {
+  const fluff = (/** @type {any} */ result) => result.data.fluff;
+
+  it('lists each padding phrase with its line and what to write instead', async () => {
+    writeTopics([
+      {
+        name: 'acme-setup',
+        text: 'In order to start, run the setup command once.',
+      },
+    ]);
+
+    const result = await integrationDocConflicts(undefined, {cwd: tmpDir});
+    const [hit, ...rest] = fluff(result);
+
+    expect(rest).toEqual([]);
+    expect(result.data.issues).toEqual([
+      {code: 'doc_fluff', severity: 'warning', message: hit.message},
+    ]);
+    expect(hit).toMatchObject({
+      topic: 'acme-setup',
+      kind: 'phrase',
+      phrase: 'in order to',
+      section: 'Overview',
+      file: 'docs/acme-setup.doc.mjs',
+      line: 1,
+      density: null,
+    });
+    expect(hit.message).toContain('Write "to" instead.');
+  });
+
+  it('finds each line within its own string, not in code or another field', async () => {
+    writeTopics([]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-lines.doc.mjs'),
+      [
+        'export default {',
+        "  type: 'generic',",
+        "  name: 'acme-lines',",
+        "  title: 'Fixture',",
+        "  description: 'Build the package in order to publish it.',",
+        "  sections: [{title: 'Overview', content: [",
+        "    {type: 'code', lang: 'text', code: 'in order to build'},",
+        "    {type: 'prose', text: 'Note that the build runs once per package and writes its output.'},",
+        "    {type: 'prose', text: 'Run the build in order to refresh the generated files for the docs.'},",
+        '  ]}],',
+        '};',
+        '',
+      ].join('\n'),
+    );
+
+    const found = fluff(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    ).map((/** @type {any} */ each) => [each.phrase, each.line]);
+
+    expect(found).toEqual([
+      ['in order to', 5],
+      ['note that', 8],
+      ['in order to', 9],
+    ]);
+  });
+
+  it('gives each use its own line in multi-line and concatenated strings', async () => {
+    writeTopics([]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-multi.doc.mjs'),
+      [
+        'export default {',
+        "  type: 'generic',",
+        "  name: 'acme-multi',",
+        "  title: 'Fixture',",
+        "  description: 'Fixture topic.',",
+        "  sections: [{title: 'Overview', content: [",
+        "    {type: 'prose', text: `Build the package first.",
+        'Run the build in order to refresh the files.',
+        'Run it again in order to check them.`},',
+        "    {type: 'prose', text: 'Publishing reads the built files ' +",
+        "      'in order to ship them, so build before you publish.'},",
+        '  ]}],',
+        '};',
+        '',
+      ].join('\n'),
+    );
+
+    const found = fluff(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    ).map((/** @type {any} */ each) => each.line);
+
+    expect(found).toEqual([8, 9, 11]);
+  });
+
+  it('finds the line of strings that open or end with code, links, quotes or escapes', async () => {
+    writeTopics([]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-shapes.doc.mjs'),
+      [
+        'export default {',
+        "  type: 'generic',",
+        "  name: 'acme-shapes',",
+        "  title: 'Fixture',",
+        "  description: 'Fixture topic.',",
+        "  sections: [{title: 'Overview', content: [",
+        "    {type: 'prose', text: '`build` runs first, in order to check it.'},",
+        "    {type: 'prose', text: '{@link generic:acme-shapes} runs it in order to ship.'},",
+        "    {type: 'prose', text: '\"Build\" is a step you run in order to test (and ship).'},",
+        "    {type: 'prose', text: '(Build) runs it once in order to publish the app\\'s files.'},",
+        "    {type: 'prose', text: 'Run the build in order to check the files.'},",
+        "    {type: 'prose', text: 'Run the build in order to publish the files.'},",
+        '  ]}],',
+        '};',
+        '',
+      ].join('\n'),
+    );
+
+    const found = fluff(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    ).map((/** @type {any} */ each) => each.line);
+
+    expect(found).toEqual([7, 8, 9, 10, 11, 12]);
+  });
+
+  it('lists a long topic that is mostly glue, and not a dense one', async () => {
+    const glue = Array.from(
+      {length: 12},
+      () =>
+        'So that is why it is the one that you would want to use if you can.',
+    ).join(' ');
+    const dense = Array.from(
+      {length: 8},
+      (_, i) =>
+        `Name codemod folder ${i} after the Core version whose upgrade runs it.`,
+    ).join(' ');
+    writeTopics([
+      {name: 'acme-glue', text: glue},
+      {name: 'acme-dense', text: dense},
+    ]);
+
+    const found = fluff(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(found.map((/** @type {any} */ each) => each.topic)).toEqual([
+      'acme-glue',
+    ]);
+    expect(found[0]).toMatchObject({kind: 'density', phrase: null});
+    expect(found[0].density).toBeLessThan(0.5);
+    expect(found[0].message).toContain("Core's guides have a median of");
+    expect(found[0].message).toContain('under the 50% floor');
+  });
+});
+
+describe('integrationDocConflicts stray doc pointers', () => {
+  const stray = (/** @type {any} */ result) => result.data.strayPointers;
+
+  it('lists a pointer to a topic whose name holds an underscore or capitals', async () => {
+    writeTopics([
+      {name: 'acme_setup', text: 'Install it first.'},
+      {name: 'AcmeGuide', text: 'Read on.'},
+      {
+        name: 'acme-menus',
+        text: 'Set it up as `astryx docs acme_setup` says, then `astryx docs AcmeGuide`; flags such as `astryx docs -h` are not pointers.',
+      },
+    ]);
+
+    const found = stray(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(found.map((/** @type {any} */ each) => each.link)).toEqual([
+      '{@link generic:acme_setup}',
+      '{@link generic:AcmeGuide}',
+    ]);
+  });
+
+  it('links a pointer to an extension topic to the page it extends', async () => {
+    writeTopics([
+      {name: 'acme-theme', text: 'Acme colors.', extendsTopic: 'theme'},
+      {name: 'acme-menus', text: 'Colors are in `astryx docs acme-theme`.'},
+    ]);
+
+    const [hit, ...rest] = stray(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(rest).toEqual([]);
+    expect(hit).toMatchObject({
+      topic: 'acme-menus',
+      link: '{@link @astryxdesign/cli:generic:theme}',
+    });
+  });
+
+  it('places a pointer-only list item on its own line, not an earlier summary or code block', async () => {
+    writeTopics([{name: 'acme-menus', text: 'Menus.'}]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      [
+        'export default {',
+        "  type: 'generic',",
+        "  name: 'acme-setup',",
+        "  title: 'Fixture',",
+        "  summary: 'See `astryx docs acme-menus`.',",
+        "  description: 'Fixture topic.',",
+        "  sections: [{title: 'Overview', content: [",
+        "    {type: 'code', lang: 'bash', code: 'astryx docs acme-menus'},",
+        "    {type: 'list', style: 'unordered', items: ['`astryx docs acme-menus`']},",
+        '  ]}],',
+        '};',
+        '',
+      ].join('\n'),
+    );
+
+    const found = stray(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    ).filter((/** @type {any} */ each) => each.topic === 'acme-setup');
+
+    // The summary's own pointer is listed too, at its line.
+    expect(found.map((/** @type {any} */ each) => each.line)).toEqual([5, 9]);
+  });
+
+  it('lists a written pointer to a doc with the link that replaces it, and warns', async () => {
+    writeTopics([
+      {name: 'acme-setup', text: 'Install it first.'},
+      {
+        name: 'acme-menus',
+        text: 'Set it up as `astryx docs acme-setup` says; the theme is in `astryx docs theme`.',
+      },
+    ]);
+
+    const result = await integrationDocConflicts(undefined, {cwd: tmpDir});
+    const [own, core, ...rest] = stray(result);
+
+    expect(rest).toEqual([]);
+    expect(own).toMatchObject({
+      topic: 'acme-menus',
+      section: 'Overview',
+      file: 'docs/acme-menus.doc.mjs',
+      line: 1,
+      pointer: 'astryx docs acme-setup',
+      link: '{@link generic:acme-setup}',
+    });
+    expect(own.message).toContain(
+      'Replace `astryx docs acme-setup`, code ticks included, with {@link generic:acme-setup}',
+    );
+    expect(core.link).toBe('{@link @astryxdesign/cli:generic:theme}');
+    expect(result.data.issues).toEqual([
+      {code: 'stray_doc_pointer', severity: 'warning', message: own.message},
+      {code: 'stray_doc_pointer', severity: 'warning', message: core.message},
+    ]);
+  });
+
+  it('names a namespace doc by its kind', async () => {
+    writeTopics([
+      {name: 'acme-setup', text: 'Lay it out as `astryx docs layout` says.'},
+    ]);
+
+    const [hit] = stray(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    expect(hit.link).toBe('{@link @astryxdesign/cli:namespace:layout}');
+  });
+
+  it('finds each line in the string that holds the pointer, not in code', async () => {
+    writeTopics([]);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-lines.doc.mjs'),
+      [
+        'export default {',
+        "  type: 'generic',",
+        "  name: 'acme-lines',",
+        "  title: 'Fixture',",
+        "  description: 'Read `astryx docs theme` first.',",
+        "  sections: [{title: 'Overview', content: [",
+        "    {type: 'code', lang: 'bash', code: 'astryx docs theme'},",
+        "    {type: 'prose', text: 'The colors your package sets show up in `astryx docs theme` for every app.'},",
+        '  ]}],',
+        '};',
+        '',
+      ].join('\n'),
+    );
+
+    const found = stray(
+      await integrationDocConflicts(undefined, {cwd: tmpDir}),
+    );
+
+    // The description resolves links too, so its pointer is its own finding.
+    expect(found.map((/** @type {any} */ each) => each.line)).toEqual([5, 8]);
+  });
+
+  it('leaves a command for a doc that does not exist, and a walkthrough', async () => {
+    writeTopics([
+      {
+        name: 'acme-setup',
+        text: 'Run `astryx docs acme-nothing`, or `astryx docs acme-setup overview`.',
+      },
+    ]);
+
+    expect(
+      stray(await integrationDocConflicts(undefined, {cwd: tmpDir})),
+    ).toEqual([]);
+  });
+});
+
+/**
+ * A package with one component doc and, optionally, one topic.
+ * @param {{usage: string, topicDescription?: string}} fixture
+ */
+function writeLinkedComponent({usage, topicDescription}) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    topicDescription == null
+      ? `export default {components: './components'};\n`
+      : `export default {components: './components', docs: './docs'};\n`,
+  );
+  fs.mkdirSync(path.join(tmpDir, 'components'), {recursive: true});
+  const doc = {
+    type: 'component',
+    name: 'AcmeButton',
+    displayName: 'Acme Button',
+    usage: {description: usage},
+    props: [],
+  };
+  fs.writeFileSync(
+    path.join(tmpDir, 'components', 'AcmeButton.doc.mjs'),
+    `export default ${JSON.stringify(doc, null, 2)};\n`,
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'components', 'AcmeButton.tsx'),
+    'export function AcmeButton() { return null; }\n',
+  );
+  if (topicDescription == null) return;
+  fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+  const topic = {
+    type: 'generic',
+    name: 'acme-setup',
+    title: 'Fixture',
+    description: topicDescription,
+    sections: [
+      {title: 'Overview', content: [{type: 'prose', text: 'Install it.'}]},
+    ],
+  };
+  fs.writeFileSync(
+    path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+    `export default ${JSON.stringify(topic, null, 2)};\n`,
+  );
+}
+
+describe('links in component docs and topic descriptions', () => {
+  it("warns on a component doc's link that names no doc, and passes one to its own topic", async () => {
+    writeLinkedComponent({
+      usage:
+        'Set it up as {@link generic:acme-setup} says, theme it with {@link @astryxdesign/cli:generic:theme}, then {@link generic:acme-nothing}.',
+      topicDescription: 'Install Acme.',
+    });
+
+    const {data} = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
+    const links = data.issues.filter(
+      (/** @type {any} */ issue) => issue.code === 'invalid_doc_graph',
+    );
+    expect(links).toEqual([
+      {
+        code: 'invalid_doc_graph',
+        severity: 'warning',
+        message: expect.stringMatching(
+          /^component AcmeButton \(usage\.description\): "generic:acme-nothing" names no doc\./,
+        ),
+      },
+    ]);
+  });
+
+  it("warns on a topic description's link that names no doc", async () => {
+    writeLinkedComponent({
+      usage: 'A button.',
+      topicDescription: 'Install Acme; see {@link generic:acme-nothing}.',
+    });
+
+    const {data} = await integrationDocConflicts(undefined, {cwd: tmpDir});
+    const links = data.issues.filter(
+      (/** @type {any} */ issue) => issue.code === 'invalid_doc_graph',
+    );
+    expect(links).toEqual([
+      {
+        code: 'invalid_doc_graph',
+        severity: 'warning',
+        message: expect.stringMatching(
+          /^acme-setup \(description\): "generic:acme-nothing" names no doc\./,
+        ),
+      },
+    ]);
+  });
+
+  it('lists a written pointer in a component doc, with the link that replaces it', async () => {
+    writeLinkedComponent({usage: 'Theme it as `astryx docs theme` says.'});
+
+    const {data} = await integrationDocConflicts(undefined, {cwd: tmpDir});
+    const [pointer, ...rest] = data.strayPointers;
+
+    expect(rest).toEqual([]);
+    expect(pointer).toMatchObject({
+      topic: 'AcmeButton',
+      kind: 'component',
+      section: null,
+      field: 'usage.description',
+      file: 'components/AcmeButton.doc.mjs',
+      pointer: 'astryx docs theme',
+      link: '{@link @astryxdesign/cli:generic:theme}',
+    });
+    expect(pointer.line).toEqual(expect.any(Number));
+    expect(pointer.message).toBe(
+      `component "AcmeButton" (field usage.description, line ${pointer.line}) points at a doc with the written command \`astryx docs theme\`. ` +
+        'Replace `astryx docs theme`, code ticks included, with {@link @astryxdesign/cli:generic:theme}: the CLI prints the command that opens the doc, and doctor checks the link.',
+    );
+    expect(data.issues).toContainEqual({
+      code: 'stray_doc_pointer',
+      severity: 'warning',
+      message: pointer.message,
+    });
+  });
+
+  it("lists a written pointer in a topic's description", async () => {
+    writeLinkedComponent({
+      usage: 'A button.',
+      topicDescription: 'Install Acme; theme it as `astryx docs theme` says.',
+    });
+
+    const {data} = await integrationDocConflicts(undefined, {cwd: tmpDir});
+
+    expect(data.strayPointers).toEqual([
+      expect.objectContaining({
+        topic: 'acme-setup',
+        kind: 'topic',
+        field: 'description',
+        link: '{@link @astryxdesign/cli:generic:theme}',
+      }),
+    ]);
+  });
+});