Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
55.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Hermetic integration authoring checks against the real Core catalogs.
 * @input Integration fixtures and the post-0.7 conflict projection.
 * @output Coverage for replacement validation and public diagnostics.
 * @position Unit coverage; the 0.6.x compatibility shape has its own fixture.
 */

import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {REPO_ROOT} from '../../test-utils/repo-root.mjs';

vi.mock('../../foundation/discovery/template-conflict-release.mjs', () => ({
  expandedTemplateConflictSchemaActive: () => true,
}));
import * as fs from 'node:fs';
import * as path from 'node:path';
import {validateIntegration} from './validate-integration.mjs';
import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
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,
  integrationTemplateConflicts,
} from './authoring-checks.mjs';
import {warmIntegrationChecks} from '../../test-utils/warm-integration-checks.mjs';

// The checks' one-time start in this file (TypeScript and its lib files) runs
// here, while the file is collected, so no test carries it.
await warmIntegrationChecks();

let tmpDir;

function writeIntegration({
  id,
  name,
  type = 'block',
  root = tmpDir,
  replacements,
  withSource = true,
}) {
  fs.mkdirSync(root, {recursive: true});
  fs.writeFileSync(
    path.join(root, 'package.json'),
    JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
  );
  fs.writeFileSync(
    path.join(root, 'astryx.integration.mjs'),
    `export default {templates: './templates'};\n`,
  );
  const stem = path.join(root, 'templates', id);
  fs.mkdirSync(path.dirname(stem), {recursive: true});
  fs.writeFileSync(
    `${stem}.doc.mjs`,
    `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'${replacements?.[id] == null ? '' : `, replaces: ${JSON.stringify(replacements[id])}`}};\n`,
  );
  if (!withSource) return;
  fs.writeFileSync(
    `${stem}.tsx`,
    'export default function Fixture() { return null; }\n',
  );
}

function writeComponentIntegration(componentName) {
  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 {components: './components'};\n`,
  );
  fs.mkdirSync(path.join(tmpDir, 'components'), {recursive: true});
  fs.writeFileSync(
    path.join(tmpDir, 'components', `${componentName}.doc.mjs`),
    `export default {type: 'component', name: ${JSON.stringify(componentName)}, displayName: ${JSON.stringify(componentName)}, description: 'Fixture component.', props: []};\n`,
  );
  fs.writeFileSync(
    path.join(tmpDir, 'components', `${componentName}.tsx`),
    'export default function Fixture() { return null; }\n',
  );
}

function writeDocIntegration({name, replaces, extendsTopic}) {
  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});
  const relationship =
    replaces != null
      ? `, replaces: ${JSON.stringify(replaces)}`
      : extendsTopic != null
        ? `, extends: ${JSON.stringify(extendsTopic)}`
        : '';
  fs.writeFileSync(
    path.join(tmpDir, 'docs', `${name}.doc.mjs`),
    `export default {type: 'generic', name: ${JSON.stringify(name)}, title: 'Fixture', description: 'Fixture topic.'${relationship}, sections: [{title: 'Overview', content: [{type: 'prose', text: 'Fixture.'}]}]};\n`,
  );
}

/**
 * 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(REPO_ROOT, '.astryx-template-conflicts-'),
  );
  // The fixture is a package with its own TypeScript config, scoped to its
  // own files. Without one, the prop check reads the repository's root
  // config, as `tsc` would for a folder inside it, and compiles every
  // declaration in the repository for each check.
  fs.writeFileSync(
    path.join(tmpDir, 'tsconfig.json'),
    `${JSON.stringify({extends: '../tsconfig.json', include: ['**/*']})}\n`,
  );
});

afterEach(() => {
  fs.rmSync(tmpDir, {recursive: true, force: true});
});

describe('integrationTemplateConflicts', () => {
  it('warns on an id shared with Core and gives the package-qualified command', async () => {
    const [core] = await discoverCoreTemplates();
    expect(core).toBeDefined();
    writeIntegration({
      id: core.dirName,
      name: 'Integration override',
      type: core.type,
    });

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});

    expect(result.type).toBe('integration.template-conflicts');
    expect(result.data.name).toBe('@acme/widgets');
    expect(result.data.issues).toEqual([]);
    expect(result.data.conflicts).toHaveLength(1);
    expect(result.data.conflicts[0]).toMatchObject({
      id: core.dirName,
      severity: 'warning',
      integrationPackage: '@acme/widgets',
      integrationName: 'Integration override',
    });
    expect(result.data.conflicts[0].message).toContain('Consider renaming');
    expect(result.data.conflicts[0].command).toContain(
      `template ${core.dirName} --package @acme/widgets`,
    );
  });

  it('does not flag a shared display name when the ids differ', async () => {
    const [core] = await discoverCoreTemplates();
    expect(core).toBeDefined();
    writeIntegration({
      id: 'integration-only-id',
      name: core.name,
      type: core.type,
    });

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});

    expect(result.data.conflicts).toEqual([]);
    expect(result.data.issues).toEqual([]);
  });

  it('loads an installed integration through the same conflict path', async () => {
    const [core] = await discoverCoreTemplates();
    expect(core).toBeDefined();
    const installed = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
    writeIntegration({
      id: core.dirName,
      name: 'Installed override',
      type: core.type,
      root: installed,
    });

    const result = await integrationTemplateConflicts('@acme/widgets', {
      cwd: tmpDir,
    });

    expect(result.data.name).toBe('@acme/widgets');
    expect(result.data.conflicts.map(conflict => conflict.id)).toContain(
      core.dirName,
    );
  });

  it('classifies a valid replacement and points to the Core original', async () => {
    const core = (await discoverCoreTemplates()).find(
      template => template.type === 'page',
    );
    expect(core).toBeDefined();
    writeIntegration({
      id: 'acme-app-shell',
      name: 'Acme app shell',
      type: core.type,
      replacements: {'acme-app-shell': core.dirName},
    });

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});

    expect(result.data.issues).toEqual([]);
    expect(result.data.conflicts).toEqual([
      expect.objectContaining({
        id: 'acme-app-shell',
        severity: 'info',
        relationship: 'replaces',
        replaces: core.dirName,
      }),
    ]);
    expect(result.data.conflicts[0].command).toContain(
      `template ${core.dirName} --package @astryxdesign/core`,
    );
  });

  it('reports a replacement target that Core does not provide', async () => {
    writeIntegration({
      id: 'acme-app-shell',
      name: 'Acme app shell',
      type: 'page',
      replacements: {'acme-app-shell': 'missing-core-shell'},
    });

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});

    expect(result.data.issues).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          code: 'missing_template_replacement_target',
          severity: 'error',
        }),
      ]),
    );
  });

  it('reports a replacement declared by a template that cannot be used', async () => {
    const [core] = await discoverCoreTemplates();
    expect(core).toBeDefined();
    writeIntegration({
      id: 'broken-template',
      name: 'Broken template',
      type: core.type,
      replacements: {'broken-template': core.dirName},
      withSource: false,
    });

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});

    expect(result.data.issues).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          code: 'invalid_template_replacement',
          severity: 'error',
          message: expect.stringContaining('cannot be used'),
        }),
      ]),
    );
  });

  it('reports two templates that replace the same Core target as ambiguous', async () => {
    const [core] = await discoverCoreTemplates();
    expect(core).toBeDefined();
    const replacements = {
      'acme-app-shell-a': core.dirName,
      'acme-app-shell-b': core.dirName,
    };
    writeIntegration({
      id: 'acme-app-shell-a',
      name: 'Acme app shell A',
      type: core.type,
      replacements,
    });
    writeIntegration({
      id: 'acme-app-shell-b',
      name: 'Acme app shell B',
      type: core.type,
      replacements,
    });

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});

    expect(result.data.issues).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          code: 'ambiguous_template_replacement',
          severity: 'error',
        }),
      ]),
    );
  });

  it('reports a replacement whose template kind differs from Core', async () => {
    const corePage = (await discoverCoreTemplates()).find(
      template => template.type === 'page',
    );
    expect(corePage).toBeDefined();
    writeIntegration({
      id: 'acme-app-shell',
      name: 'Acme app shell',
      type: 'block',
      replacements: {'acme-app-shell': corePage.dirName},
    });

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});

    expect(result.data.issues).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          code: 'invalid_template_replacement',
          severity: 'error',
          message: expect.stringContaining('same type'),
        }),
      ]),
    );
  });

  it('does not recommend an impossible replacement for a different Core kind', async () => {
    const corePage = (await discoverCoreTemplates()).find(
      template => template.type === 'page',
    );
    expect(corePage).toBeDefined();
    writeIntegration({
      id: corePage.dirName,
      name: 'Acme block with a page id',
      type: 'block',
    });

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
    const conflict = result.data.conflicts.find(
      item => item.id === corePage.dirName,
    );

    expect(conflict?.relationship).toBe('accidental');
    expect(conflict?.message).toContain(
      'cannot replace a different template kind',
    );
    expect(conflict?.message).toContain('Rename');
    expect(conflict?.message).not.toContain('set replaces');
  });

  it('returns a malformed template once as an invalid_template issue', async () => {
    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 {templates: './templates'};\n`,
    );
    fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
    fs.writeFileSync(
      path.join(tmpDir, 'templates', 'broken.doc.mjs'),
      `throw new Error('broken fixture');\n`,
    );
    fs.writeFileSync(
      path.join(tmpDir, 'templates', 'broken.tsx'),
      'export default function Broken() { return null; }\n',
    );

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
    const invalid = result.data.issues.filter(
      issue => issue.code === 'invalid_template',
    );

    expect(result.data.conflicts).toEqual([]);
    expect(invalid).toHaveLength(1);
    expect(invalid[0].message).toContain('broken fixture');
  });

  it('returns structural issues instead of claiming a broken integration is clean', async () => {
    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 {templates: './missing'};\n`,
    );

    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});

    expect(result.data.conflicts).toEqual([]);
    expect(
      result.data.issues.some(issue => issue.code === 'missing_root'),
    ).toBe(true);
  });
});

describe('integrationComponentConflicts', () => {
  it('warns on a Core component name and gives the package-qualified command', async () => {
    const coreDir = findCoreDir(tmpDir);
    expect(coreDir).not.toBeNull();
    const [core] = discoverOwnedComponents(coreDir, []);
    expect(core).toBeDefined();
    writeComponentIntegration(core.name);

    const result = await integrationComponentConflicts(undefined, {
      cwd: tmpDir,
    });

    expect(result.type).toBe('integration.component-conflicts');
    expect(result.data.issues).toEqual([]);
    expect(result.data.conflicts).toEqual([
      expect.objectContaining({
        name: core.name,
        severity: 'warning',
        integrationPackage: '@acme/widgets',
        command: expect.stringContaining(
          `component ${core.name} --package @acme/widgets`,
        ),
      }),
    ]);
  });

  it('does not flag an integration-only component name', async () => {
    writeComponentIntegration('AcmeOnlyWidget');

    const result = await integrationComponentConflicts(undefined, {
      cwd: tmpDir,
    });

    expect(result.data.conflicts).toEqual([]);
    expect(result.data.issues).toEqual([]);
  });

  it("compares each component doc's props with the component's TypeScript props, as warnings", async () => {
    writeComponentIntegration('AcmeBadge');
    fs.writeFileSync(
      path.join(tmpDir, 'components', 'AcmeBadge.doc.mjs'),
      `export default {type: 'component', name: 'AcmeBadge', displayName: 'AcmeBadge', description: 'Fixture component.', props: [{name: 'label', type: 'string', description: 'Text.', required: true}, {name: 'size', type: "'sm' | 'md'", description: 'Size.'}]};\n`,
    );
    fs.writeFileSync(
      path.join(tmpDir, 'components', 'AcmeBadge.tsx'),
      'export function AcmeBadge(props: {label: string; count?: number}) { return null; }\n',
    );

    const result = await integrationComponentConflicts(undefined, {
      cwd: tmpDir,
    });

    expect(result.data.issues).toEqual([]);
    expect(result.data.propDrift).toMatchObject({
      status: 'checked',
      components: 1,
      unchecked: [],
    });
    expect(
      result.data.propDrift?.findings.map(f => [f.prop, f.kind, f.severity]),
    ).toEqual([
      ['count', 'not_in_doc', 'warning'],
      ['size', 'not_in_code', 'warning'],
    ]);
  });

  it('leaves propDrift out when the package has no components root', async () => {
    writeDocIntegration({name: 'acme-setup'});

    const result = await integrationComponentConflicts(undefined, {
      cwd: tmpDir,
    });

    expect(result.data).not.toHaveProperty('propDrift');
  });
});

describe('integrationDocConflicts', () => {
  it('marks an explicit Core replacement as intentional', async () => {
    const [coreTopic] = Object.keys(discoverBuiltinTopics());
    expect(coreTopic).toBeDefined();
    writeDocIntegration({name: 'acme-setup', replaces: coreTopic});

    const result = await integrationDocConflicts(undefined, {cwd: tmpDir});

    expect(result.type).toBe('integration.doc-conflicts');
    expect(result.data.issues).toEqual([]);
    expect(result.data.findings).toEqual([
      expect.objectContaining({
        topic: 'acme-setup',
        severity: 'info',
        relationship: 'replaces',
        coreTopic,
      }),
    ]);
  });

  it('marks an explicit Core extension as intentional', async () => {
    const [coreTopic] = Object.keys(discoverBuiltinTopics());
    expect(coreTopic).toBeDefined();
    writeDocIntegration({name: 'acme-extra', extendsTopic: coreTopic});

    const result = await integrationDocConflicts(undefined, {cwd: tmpDir});

    expect(result.data.findings).toEqual([
      expect.objectContaining({
        topic: 'acme-extra',
        severity: 'info',
        relationship: 'extends',
        coreTopic,
      }),
    ]);
  });

  it('reports a same-name Core topic without a relationship as accidental', async () => {
    const [coreTopic] = Object.keys(discoverBuiltinTopics());
    expect(coreTopic).toBeDefined();
    writeDocIntegration({name: coreTopic});

    const result = await integrationDocConflicts(undefined, {cwd: tmpDir});

    expect(result.data.findings).toEqual([
      expect.objectContaining({
        topic: coreTopic,
        severity: 'error',
        relationship: 'accidental',
        coreTopic,
      }),
    ]);
    expect(result.data.findings[0].message).toContain(
      `replaces: '${coreTopic}'`,
    );
    expect(result.data.findings[0].message).toContain(
      `extends: '${coreTopic}'`,
    );
  });

  it('reports a Core name as accidental when replacing a different topic', async () => {
    const [replacedCore, nameCore] = Object.keys(discoverBuiltinTopics());
    expect(replacedCore).toBeDefined();
    expect(nameCore).toBeDefined();
    writeDocIntegration({name: nameCore, replaces: replacedCore});

    const result = await integrationDocConflicts(undefined, {cwd: tmpDir});

    expect(result.data.findings).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          topic: nameCore,
          severity: 'info',
          relationship: 'replaces',
          coreTopic: replacedCore,
        }),
        expect.objectContaining({
          topic: nameCore,
          severity: 'error',
          relationship: 'accidental',
          coreTopic: nameCore,
        }),
      ]),
    );
  });

  it('matches Core topic identity case-insensitively like docs lookup', async () => {
    const [coreTopic] = Object.keys(discoverBuiltinTopics());
    expect(coreTopic).toBeDefined();
    const mixedCase = coreTopic.toUpperCase();
    writeDocIntegration({name: mixedCase});

    const result = await integrationDocConflicts(undefined, {cwd: tmpDir});

    expect(result.data.findings).toEqual([
      expect.objectContaining({
        topic: mixedCase,
        severity: 'error',
        relationship: 'accidental',
        coreTopic,
      }),
    ]);
  });
});

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

describe('validateIntegration runner-command notes', () => {
  /** The runner-command notes, read back into their parts. */
  async function runnerNotes() {
    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
    const notes = (data.notes ?? [])
      .filter((/** @type {any} */ note) => note.code === 'runner_command')
      .map((/** @type {any} */ note) => {
        const m =
          /^(\S+): "([^"]+)"(?: \(section "([^"]+)"\))? writes `([^`]+)`(?: \(line (\d+)\))?\./.exec(
            note.message,
          );
        return {
          file: m?.[1],
          topic: m?.[2],
          section: m?.[3] ?? null,
          command: m?.[4],
          line: m?.[5] ? Number(m[5]) : null,
          message: note.message,
        };
      });
    return {data, notes};
  }

  function writeTopic(/** @type {string} */ text) {
    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});
    const doc = {
      type: 'generic',
      name: 'acme-setup',
      title: 'Fixture',
      description: 'Fixture topic.',
      sections: [
        {
          title: 'Overview',
          content: [
            {type: 'prose', text},
            {type: 'code', lang: 'bash', code: 'npx @astryxdesign/cli init'},
          ],
        },
      ],
    };
    fs.writeFileSync(
      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
      `export default ${JSON.stringify(doc)};\n`,
    );
  }

  it('lists a runner command with its line and fix, and raises no issue', async () => {
    writeTopic('Check it with `pnpm exec astryx doctor` first.');

    const {data, notes} = await runnerNotes();
    const [hit, ...rest] = notes;

    expect(rest).toEqual([]);
    expect(hit).toMatchObject({
      topic: 'acme-setup',
      section: 'Overview',
      file: 'docs/acme-setup.doc.mjs',
      line: 1,
      command: 'pnpm exec astryx doctor',
    });
    expect(hit.message).toContain('Write the token `{@command doctor}`');
    // A note only: no issue, so no exit changes on it.
    expect(
      data.issues.map((/** @type {any} */ issue) => issue.code),
    ).not.toContain('runner_command');
  });

  it('puts each copy of a repeated command on its own line', async () => {
    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});
    const doc = {
      type: 'generic',
      name: 'acme-setup',
      title: 'Fixture',
      description: 'Fixture topic.',
      sections: [
        {
          title: 'First',
          content: [{type: 'prose', text: 'Run `npx astryx doctor`.'}],
        },
        {
          title: 'Second',
          content: [{type: 'prose', text: 'Run `npx astryx doctor` again.'}],
        },
        {
          title: 'Third',
          content: [{type: 'prose', text: 'Or plain `npx astryx`.'}],
        },
      ],
    };
    fs.writeFileSync(
      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
      `export default ${JSON.stringify(doc, null, 2)};\n`,
    );
    const lines = fs
      .readFileSync(path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'), 'utf8')
      .split('\n');
    const lineHolding = (/** @type {string} */ text) =>
      lines.findIndex(line => line.includes(text)) + 1;

    const {notes} = await runnerNotes();

    expect(
      notes.map((/** @type {any} */ each) => [
        each.section,
        each.line,
        each.command,
      ]),
    ).toEqual([
      ['First', lineHolding('Run `npx astryx doctor`.'), 'npx astryx doctor'],
      ['Second', lineHolding('again.'), 'npx astryx doctor'],
      ['Third', lineHolding('Or plain'), 'npx astryx'],
    ]);
  });

  it('puts each copy of an identical one-line string on its own line', async () => {
    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});
    const block = {type: 'code', lang: 'bash', code: 'npx astryx doctor'};
    const doc = {
      type: 'generic',
      name: 'acme-setup',
      title: 'Fixture',
      description: 'Fixture topic.',
      sections: [
        {title: 'First', content: [block]},
        {title: 'Second', content: [block]},
      ],
    };
    fs.writeFileSync(
      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
      `export default ${JSON.stringify(doc, null, 2)};\n`,
    );
    const lines = fs
      .readFileSync(path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'), 'utf8')
      .split('\n');
    const copies = lines.flatMap((line, at) =>
      line.includes('"npx astryx doctor"') ? [at + 1] : [],
    );

    const {notes} = await runnerNotes();

    expect(copies).toHaveLength(2);
    expect(
      notes.map((/** @type {any} */ each) => [each.section, each.line]),
    ).toEqual([
      ['First', copies[0]],
      ['Second', copies[1]],
    ]);
  });

  it("places a section's command on its own line when the section sits in a constant above the doc", async () => {
    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});
    fs.writeFileSync(
      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
      [
        "const install = {title: 'Install', content: [{type: 'prose', text: 'Run `npx astryx doctor`.'}]};",
        '',
        'export default {',
        "  type: 'generic',",
        "  name: 'acme-setup',",
        "  title: 'Fixture',",
        "  description: 'Install first: `npx astryx doctor`.',",
        '  sections: [install],',
        '};',
        '',
      ].join('\n'),
    );

    const {notes} = await runnerNotes();

    expect(
      notes.map((/** @type {any} */ each) => [each.section, each.line]),
    ).toEqual(
      expect.arrayContaining([
        [null, 7],
        ['Install', 1],
      ]),
    );
  });

  it('lists package-manager commands, bare commands and broken tokens with the token to write, all for the next minor', async () => {
    writeTopic(
      'Add it with `npm install -D @acme/widgets`, run `astryx search acme`, then {@pm add x} and {@cmd docs}. Only npm: `npm pkg set name=x`.',
    );

    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
    const notes = (data.notes ?? []).filter(
      (/** @type {any} */ note) => note.code !== 'runner_command',
    );

    expect(
      notes.map((/** @type {any} */ note) => [note.code, note.next]),
    ).toEqual([
      ['package_manager_command', true],
      ['plain_command', true],
      ['doc_token', true],
      ['doc_token', true],
      ['package_manager_command', true],
      // The fixture's install step, in its bash block.
      ['package_manager_command', true],
    ]);
    const messages = notes.map((/** @type {any} */ note) => note.message);
    expect(messages[0]).toContain('{@pm install @acme/widgets --dev}');
    expect(messages[1]).toContain('{@command search acme}');
    expect(messages[2]).toContain('{@pm}` starts with a verb');
    expect(messages[3]).toContain('Doc tokens are');
    expect(messages[4]).toContain(
      '{@pm-only npm "<why only npm>" pkg set name=x}',
    );
    expect(messages[5]).toContain('{@pm dlx @astryxdesign/cli init}');
    expect(data.issues.map((/** @type {any} */ issue) => issue.code)).toEqual(
      [],
    );
  });

  it('reads a verb named alone as a mention, and TSDoc tags in a TypeScript sample as code', async () => {
    writeTopic(
      'Scripts run with `npm run`, `pnpm dlx` fetches a package, and `npm i -g`, `yarn global add` and `npm pkg set` each take one.',
    );
    const file = path.join(tmpDir, 'docs', 'acme-setup.doc.mjs');
    fs.writeFileSync(
      file,
      fs.readFileSync(file, 'utf8').replace(
        /\{"type":"code"[^}]*\}/,
        JSON.stringify({
          type: 'code',
          lang: 'ts',
          code: '/** {@inheritDoc Base.render} */\nexport const x = 1;',
        }),
      ),
    );

    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
    expect(
      (data.notes ?? []).filter((/** @type {any} */ note) =>
        ['package_manager_command', 'doc_token'].includes(note.code),
      ),
    ).toEqual([]);
  });

  it('lists a token that never closes, in prose and in any code block', async () => {
    writeTopic(
      'Install with {@pm install @acme/widgets --dev before you start.',
    );
    const file = path.join(tmpDir, 'docs', 'acme-setup.doc.mjs');
    fs.writeFileSync(
      file,
      fs.readFileSync(file, 'utf8').replace(
        /\{"type":"code"[^}]*\}/,
        JSON.stringify({
          type: 'code',
          lang: 'tsx',
          code: '// {@pm install @acme/widgets --dev\nexport const x = 1;',
        }),
      ),
    );

    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
    const tokens = (data.notes ?? []).filter(
      (/** @type {any} */ note) => note.code === 'doc_token',
    );
    expect(tokens).toHaveLength(2);
    expect(tokens[0].message).toContain('never closes');
  });

  it('lists a {@command} token that names no Astryx command', async () => {
    writeTopic('Run {@command dcotor} before you ship.');

    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
    const tokens = (data.notes ?? []).filter(
      (/** @type {any} */ note) => note.code === 'doc_token',
    );
    expect(tokens).toHaveLength(1);
    expect(tokens[0].message).toContain('`dcotor` is not an Astryx command');
  });

  it('reads the command after leading global flags in a {@command} token', async () => {
    writeTopic(
      'Read it as data with {@command --json component Button} or {@command --detail full docs acme}, not {@command --json dcotor}, {@command --json nosuch docs} or {@command --detail full nosuch}. Check the version with {@command --version}; {@command --json} alone names nothing.',
    );
    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
    const tokens = (data.notes ?? []).filter(
      (/** @type {any} */ note) => note.code === 'doc_token',
    );
    expect(
      tokens.map(note => note.message.match(/`(\w+)` is not/)?.[1]),
    ).toEqual(['dcotor', 'nosuch', 'nosuch', undefined]);
    expect(tokens[3].message).toContain('names no Astryx command');
  });

  it('lists nothing for a topic written in the doc syntax', async () => {
    writeTopic(
      'Add it with {@pm install @acme/widgets --dev}, run {@command docs acme}, and {@pm-only npm "only npm has pkg" pkg set name=x}. Show the syntax: {@@pm install x}.',
    );
    // The fixture's bash block holds a scoped install step; write it as a token.
    const file = path.join(tmpDir, 'docs', 'acme-setup.doc.mjs');
    fs.writeFileSync(
      file,
      fs
        .readFileSync(file, 'utf8')
        .replace(
          'npx @astryxdesign/cli init',
          '{@pm dlx @astryxdesign/cli init}',
        ),
    );

    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
    expect(data.notes ?? []).toEqual([]);
  });

  it('lists nothing for bare commands and the scoped install step', async () => {
    writeTopic('Check it with `astryx doctor` first.');

    const {notes} = await runnerNotes();
    expect((await runnerNotes()).notes).toEqual([]);
  });
});