Skip to content

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

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

/**
 * @file An integration's flat topic replaces or extends a guide the docs tree
 * places, by its route, and an extension places its sections with `before` or
 * `after`. Every read names the package of the guide and of each section, in
 * text and JSON (architecture:cli-surface INV28). A route that holds no guide,
 * and a `before`/`after` that names no section, fail nothing: they are listed
 * notes (INV35).
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {docs} from './docs.mjs';
import {integrationDocConflicts} from '../integration/authoring-checks.mjs';
import {validateIntegration} from '../integration/validate-integration.mjs';
import {integrationCheck} from '../integration/check/check.mjs';
import {runCli} from '../../test-utils/run-cli.mjs';
import {search} from '../search/search.mjs';
import {sectionPositionCliProblem} from '../../foundation/integrations/cli-requirement.mjs';
import {
  DocsCatalog,
  mergeTopic,
} from '../../foundation/discovery/docs-discovery.mjs';
import {REPO_ROOT} from '../../test-utils/repo-root.mjs';

const SLOW = 60_000;
const CLI = '@astryxdesign/cli';
const KIT = '@acme/kit';
const GUIDE = 'authoring/quick-start';

/** @type {string} */
let tmpDir;

/**
 * A flat topic of the kit.
 * @param {string} name
 * @param {object} fields
 */
function topic(name, fields) {
  return {
    type: 'generic',
    name,
    title: `Acme ${name}`,
    description: `The Acme ${name}.`,
    sections: [
      {
        id: `acme-${name}`,
        title: `Acme ${name}`,
        content: [{type: 'prose', text: `Acme ${name}.`}],
      },
    ],
    ...fields,
  };
}

/**
 * One section of an extension.
 * @param {string} id
 * @param {object} [fields]
 */
function section(id, fields = {}) {
  return {
    id,
    title: id.replace(/-/g, ' '),
    content: [{type: 'prose', text: `Acme ${id}.`}],
    ...fields,
  };
}

/** The installed kit's folder. */
const kitDir = () => path.join(tmpDir, 'node_modules', '@acme', 'kit');

/**
 * A project that configures `@acme/kit`, which ships these docs.
 * @param {Record<string, object>} files
 */
function scaffold(files) {
  fs.writeFileSync(
    path.join(tmpDir, 'package.json'),
    JSON.stringify({name: 'consumer'}),
  );
  fs.writeFileSync(
    path.join(tmpDir, 'astryx.config.mjs'),
    `export default {integrations: ['${KIT}']};\n`,
  );
  fs.mkdirSync(path.join(kitDir(), 'docs'), {recursive: true});
  fs.writeFileSync(
    path.join(kitDir(), 'package.json'),
    JSON.stringify({name: KIT, version: '1.0.0', type: 'module'}),
  );
  fs.writeFileSync(
    path.join(kitDir(), 'astryx.integration.mjs'),
    "export default {docs: './docs'};\n",
  );
  for (const [file, doc] of Object.entries(files)) {
    fs.writeFileSync(
      path.join(kitDir(), 'docs', file),
      `export default ${JSON.stringify(doc, null, 2)};\n`,
    );
  }
}

/** @param {string[]} args */
async function cliText(args) {
  const {status, stdout} = await runCli(args, tmpDir);
  return {status, stdout};
}

/** @param {string[]} args */
async function cliJson(args) {
  const {status, stdout} = await runCli(['--json', ...args], tmpDir);
  return {status, json: JSON.parse(stdout)};
}

beforeEach(() => {
  tmpDir = fs.mkdtempSync(
    path.join(REPO_ROOT, '.astryx-guide-route-targets-'),
  );
});

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

describe('a flat topic that replaces a placed guide by its route', () => {
  beforeEach(() => {
    scaffold({
      'quick-start.doc.mjs': topic('quick-start', {replaces: GUIDE}),
    });
  });

  it(
    'is read at the route, naming its package and the one it replaced',
    async () => {
      const read = await docs(GUIDE, undefined, {cwd: tmpDir});
      expect(Object.keys(read).slice(0, 2)).toEqual(['type', 'package']);
      expect(read).toMatchObject({type: 'docs.detail', package: KIT});
      expect(read.data).toMatchObject({
        name: GUIDE,
        title: 'Acme quick-start',
        replaces: GUIDE,
        replacedPackage: CLI,
      });
      expect(read.data.sections.map(s => [s.id, s.package])).toEqual([
        ['acme-quick-start', KIT],
      ]);

      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(index).toMatchObject({type: 'docs.index', package: KIT});
      expect(index.data).toMatchObject({replaces: GUIDE, replacedPackage: CLI});
      expect(index.data.sections.every(s => s.package === KIT)).toBe(true);
    },
    SLOW,
  );

  it(
    'lists under its own package where the topic list names the guide',
    async () => {
      const list = await docs(undefined, undefined, {cwd: tmpDir, depth: 'all'});
      if (list.type !== 'docs.list') return;
      /** @param {any[]} rows */
      const flat = rows =>
        rows.flatMap((/** @type {any} */ row) => [
          row,
          ...flat(row.children ?? []),
        ]);
      const child = flat(list.meta?.namespaces ?? []).find(
        (/** @type {any} */ row) => row.topic === GUIDE,
      );
      // The same attribution the namespace read gives it, not the package
      // whose route it took.
      expect(child).toMatchObject({
        package: KIT,
        replaces: GUIDE,
        replacedPackage: CLI,
        title: 'Acme quick-start',
      });
      const text = await cliText(['docs', '--depth', 'all']);
      expect(text.stdout).toContain(GUIDE);
    },
    SLOW,
  );

  it(
    'lists under its own package where its namespace lists the guide',
    async () => {
      const parent = await docs('authoring', undefined, {cwd: tmpDir});
      const child = parent.data.slots
        .flatMap(slot => slot.children)
        .find(each => each.route === GUIDE);
      expect(child).toMatchObject({
        package: KIT,
        replaces: GUIDE,
        replacedPackage: CLI,
        title: 'Acme quick-start',
      });
      const text = await cliText(['docs', 'authoring']);
      expect(text.stdout).toContain(`quick-start (${KIT})`);
    },
    SLOW,
  );

  it(
    'names both packages in text, the replaced one right after package:',
    async () => {
      for (const args of [
        ['docs', GUIDE],
        ['docs', GUIDE, '--full'],
      ]) {
        const {status, stdout} = await cliText(args);
        expect(status).toBe(0);
        expect(stdout).toMatch(
          new RegExp(
            `package: +${KIT.replace('/', '\\/')}\\s*\\n+replaces ${CLI.replace('/', '\\/')}'s ${GUIDE.replace('/', '\\/')}`,
          ),
        );
      }
      const {json} = await cliJson(['docs', GUIDE, '--full']);
      expect(json).toMatchObject({package: KIT, data: {replacedPackage: CLI}});
    },
    SLOW,
  );

  it(
    'is an intentional override to doctor integration docs, with no issue',
    async () => {
      const result = await integrationDocConflicts(KIT, {cwd: tmpDir});
      expect(result.data.findings).toContainEqual(
        expect.objectContaining({
          topic: 'quick-start',
          severity: 'info',
          relationship: 'replaces',
          coreTopic: GUIDE,
        }),
      );
      expect(result.data.issues).toEqual([]);
    },
    SLOW,
  );
});

describe('a flat topic that extends a placed guide by its route', () => {
  /** @param {object[]} sections */
  const extend = sections =>
    scaffold({
      'quick-start-acme.doc.mjs': topic('quick-start-acme', {
        extends: GUIDE,
        sections,
      }),
    });

  it(
    'places each section before or after a key, or at the end, naming its package',
    async () => {
      extend([
        section('acme-registry', {before: 'fill-in-package-json'}),
        section('acme-login', {after: 'quick-start'}),
        section('acme-support'),
        // Replaces the guide's section in place, by its key.
        {...section('global-mode'), title: 'In global mode, at Acme'},
      ]);
      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(index.package).toBe(CLI);
      expect(index.data.replaces).toBeUndefined();
      expect(index.data.sections.map(s => [s.id, s.package])).toEqual([
        ['quick-start', CLI],
        ['acme-login', KIT],
        ['acme-registry', KIT],
        ['fill-in-package-json', CLI],
        ['the-integration-file', CLI],
        ['global-mode', KIT],
        ['acme-support', KIT],
      ]);

      const read = await docs(GUIDE, undefined, {cwd: tmpDir});
      expect(read.package).toBe(CLI);
      expect(read.data.replacedPackage).toBeUndefined();
      // Readers never see the placing fields.
      for (const each of read.data.sections) {
        expect(each).not.toHaveProperty('before');
        expect(each).not.toHaveProperty('after');
      }
      expect(read.data.sections.find(s => s.id === 'acme-login').package).toBe(
        KIT,
      );
    },
    SLOW,
  );

  it(
    'labels each section it adds once, in text',
    async () => {
      extend([
        section('acme-login', {after: 'quick-start', title: `Log in (${KIT})`}),
        section('acme-support', {title: 'Acme support'}),
      ]);
      const index = await cliText(['docs', GUIDE]);
      expect(index.stdout).toContain(`package: ${CLI}`);
      expect(index.stdout).not.toContain(`replaces ${CLI}`);
      expect(index.stdout).toContain(`Acme support (${KIT})`);
      expect(index.stdout).toContain(`Log in (${KIT})`);
      expect(index.stdout).not.toContain(`(${KIT}) (${KIT})`);
      const full = await cliText(['docs', GUIDE, '--full']);
      expect(full.stdout).toContain(`Acme support (${KIT})`);
      expect(full.stdout).not.toContain(`(${KIT}) (${KIT})`);
      const one = await cliJson(['docs', GUIDE, 'acme-support']);
      expect(one.json).toMatchObject({package: KIT});
    },
    SLOW,
  );

  it(
    'adds a section whose key names no section at the end, as a listed note',
    async () => {
      extend([section('acme-registry', {before: 'no-such-section'})]);
      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(index.data.sections.at(-1)).toMatchObject({
        id: 'acme-registry',
        package: KIT,
      });
      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      expect(validated.data.issues).toEqual([]);
      expect(validated.data.notes).toContainEqual({
        code: 'doc_section_unplaced',
        message: expect.stringContaining('"no-such-section"'),
        next: true,
      });
      const docsCheck = await integrationDocConflicts(KIT, {cwd: tmpDir});
      expect(docsCheck.data.issues).toEqual([]);
      expect(docsCheck.data.findings).toContainEqual(
        expect.objectContaining({relationship: 'extends', coreTopic: GUIDE}),
      );
    },
    SLOW,
  );

  it(
    'places sections in a flat topic it extends the same way',
    async () => {
      scaffold({
        'theme-acme.doc.mjs': topic('theme-acme', {
          extends: 'theme',
          sections: [
            section('acme-theme', {before: 'creating-a-custom-theme'}),
          ],
        }),
      });
      const index = await docs('theme', undefined, {cwd: tmpDir, index: true});
      const ids = index.data.sections.map(s => s.id);
      expect(ids.indexOf('acme-theme')).toBe(
        ids.indexOf('creating-a-custom-theme') - 1,
      );
      expect(index.data.sections.find(s => s.id === 'acme-theme').package).toBe(
        KIT,
      );
    },
    SLOW,
  );

  it(
    'refuses a section that sets both before and after, as before',
    async () => {
      extend([
        section('acme-x', {before: 'quick-start', after: 'quick-start'}),
      ]);
      const result = await integrationDocConflicts(KIT, {cwd: tmpDir});
      expect(result.data.issues).toContainEqual(
        expect.objectContaining({code: 'invalid_doc', severity: 'error'}),
      );
    },
    SLOW,
  );
});

describe('a route that holds no guide', () => {
  it(
    'changes nothing and fails nothing, as a listed note',
    async () => {
      scaffold({
        'quick-start.doc.mjs': topic('quick-start', {
          replaces: 'authoring/no-such-guide',
        }),
      });
      const read = await docs(GUIDE, undefined, {cwd: tmpDir});
      expect(read.package).toBe(CLI);

      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      expect(validated.data.issues).toEqual([]);
      expect(validated.data.notes).toContainEqual({
        code: 'doc_target_not_found',
        message: expect.stringContaining('"authoring/no-such-guide"'),
        next: true,
      });
      const docsCheck = await integrationDocConflicts(KIT, {cwd: tmpDir});
      expect(docsCheck.data.issues).toEqual([]);

      const check = await integrationCheck({cwd: kitDir(), strict: true});
      expect(check.data.failed).toBe(false);
    },
    SLOW,
  );
});

describe('a flat topic that replaces a flat topic', () => {
  it(
    'names the package it replaced in the list, the index, and text',
    async () => {
      scaffold({
        'acme-start.doc.mjs': topic('acme-start', {
          replaces: 'getting-started',
        }),
      });
      const listed = await docs(undefined, undefined, {cwd: tmpDir});
      expect(listed.data.find(t => t.topic === 'acme-start')).toMatchObject({
        package: KIT,
        replaces: 'getting-started',
        replacedPackage: CLI,
      });
      const index = await docs('acme-start', undefined, {
        cwd: tmpDir,
        index: true,
      });
      expect(index.data).toMatchObject({
        replaces: 'getting-started',
        replacedPackage: CLI,
      });
      const {stdout} = await cliText(['docs', 'getting-started']);
      expect(stdout).toContain(`replaces ${CLI}'s getting-started`);
    },
    SLOW,
  );
});

describe('a doc that names a namespace instead of a guide', () => {
  it.each(['extends', 'replaces'])(
    'changes nothing with %s, as a note naming the guides below it',
    async relationship => {
      scaffold({
        'authoring-acme.doc.mjs': topic('authoring-acme', {
          [relationship]: 'authoring',
          sections: [section('make-it-at-acme')],
        }),
      });
      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      expect(validated.data.issues).toEqual([]);
      const note = validated.data.notes?.find(
        each => each.code === 'doc_target_not_found',
      );
      expect(note?.message).toContain('"authoring", which is a namespace');
      expect(note?.message).toContain('authoring/field-reference');
      const check = await integrationCheck({cwd: kitDir(), strict: true});
      expect(check.data.failed).toBe(false);
    },
    SLOW,
  );

  it(
    'extends a guide below it by its route, labeled with its package',
    async () => {
      scaffold({
        'authoring-acme.doc.mjs': topic('authoring-acme', {
          extends: 'authoring/field-reference',
          sections: [
            section('make-it-at-acme', {title: 'At Acme: make it in the kit'}),
          ],
        }),
      });
      const read = await docs('authoring/field-reference', 'make-it-at-acme', {
        cwd: tmpDir,
      });
      expect(read).toMatchObject({type: 'docs.detail.section', package: KIT});
      const {stdout} = await cliText(['docs', 'authoring/field-reference']);
      expect(stdout).toContain(`At Acme: make it in the kit (${KIT})`);
      const docsCheck = await integrationDocConflicts(KIT, {cwd: tmpDir});
      expect(docsCheck.data.findings).toContainEqual(
        expect.objectContaining({
          relationship: 'extends',
          coreTopic: 'authoring/field-reference',
        }),
      );
    },
    SLOW,
  );
});

describe('a route that moved', () => {
  it(
    'applies to the guide at the route it moved to',
    async () => {
      scaffold({
        'quick-start.doc.mjs': topic('quick-start', {
          replaces: 'cli/integrations/quick-start',
        }),
      });
      const read = await docs(GUIDE, undefined, {cwd: tmpDir});
      expect(read).toMatchObject({
        package: KIT,
        data: {replaces: GUIDE, replacedPackage: CLI},
      });
      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(index.data.replaces).toBe(GUIDE);
      const {stdout} = await cliText(['docs', GUIDE, '--full']);
      expect(stdout).toContain(`replaces ${CLI}'s ${GUIDE}`);
      expect(stdout).not.toContain('cli/integrations');
      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      expect(
        (validated.data.notes ?? []).filter(n => n.code.startsWith('doc_')),
      ).toEqual([]);
    },
    SLOW,
  );
});

describe('review follow-ups', () => {
  it('keeps the authored order of sections placed after one key', () => {
    const merged = mergeTopic(
      {
        sections: [
          {id: 'a', title: 'A', content: []},
          {id: 'b', title: 'B', content: []},
        ],
      },
      {
        sections: [
          {id: 'first', title: 'First', after: 'a', content: []},
          {id: 'second', title: 'Second', after: 'a', content: []},
          {id: 'zero', title: 'Zero', before: 'b', content: []},
        ],
      },
    );
    expect(merged.sections.map(each => each.id)).toEqual([
      'a',
      'first',
      'second',
      'zero',
      'b',
    ]);
  });

  it(
    'never reads back before or after, on a doc that extends nothing',
    async () => {
      scaffold({
        'plain.doc.mjs': topic('plain', {
          sections: [section('only', {after: 'nothing'})],
        }),
      });
      const read = await docs('plain', undefined, {cwd: tmpDir});
      expect(read.data.sections[0]).not.toHaveProperty('after');
    },
    SLOW,
  );

  it(
    'names the replacing and extending packages in search, as reads do',
    async () => {
      scaffold({
        'quick-start.doc.mjs': topic('quick-start', {
          replaces: GUIDE,
          sections: [section('acme-zebra-registry')],
        }),
        'field-ref.doc.mjs': topic('field-ref', {
          extends: 'authoring/field-reference',
          sections: [section('acme-walrus-login')],
        }),
      });
      for (const [query, route] of [
        ['acme zebra registry', GUIDE],
        ['acme walrus login', 'authoring/field-reference'],
      ]) {
        const found = await search(query, {cwd: tmpDir, type: 'doc'});
        // The best hit is the integration's text, at the guide's route.
        expect(found.data.results[0]).toMatchObject({
          name: route,
          package: KIT,
        });
      }
    },
    SLOW,
  );

  it(
    'checks the links in a doc that targets a guide by its route',
    async () => {
      scaffold({
        'field-ref.doc.mjs': topic('field-ref', {
          extends: 'authoring/field-reference',
          sections: [
            {
              id: 'acme-link',
              title: 'Acme link',
              content: [
                {type: 'prose', text: 'See {@link generic:no-such-acme-doc}.'},
              ],
            },
          ],
        }),
      });
      const result = await integrationDocConflicts(KIT, {cwd: tmpDir});
      expect(result.data.issues).toContainEqual(
        expect.objectContaining({
          code: 'invalid_doc_graph',
          message: expect.stringContaining('no-such-acme-doc'),
        }),
      );
    },
    SLOW,
  );

  it(
    'lets the later of two replacements of one guide win, failing nothing',
    async () => {
      const catalog = DocsCatalog.fromBuiltins();
      const record = (/** @type {string} */ pkg) => ({
        name: `${pkg.split('/')[1]}-start`,
        package: pkg,
        path: `/x/${pkg}.doc.mjs`,
        replaces: GUIDE,
      });
      expect(catalog.add(record('@acme/one'))).toBeNull();
      expect(catalog.add(record('@acme/two'))).toBeNull();
      expect(catalog.guideOverlay(GUIDE)).toMatchObject({
        replacement: {package: '@acme/two'},
        replacedPackage: '@acme/one',
      });

      scaffold({
        'a.doc.mjs': topic('acme-a', {replaces: GUIDE}),
        'b.doc.mjs': topic('acme-b', {replaces: GUIDE}),
      });
      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      expect(validated.data.issues).toEqual([]);
      expect(validated.data.notes).toContainEqual({
        code: 'duplicate_guide_replacement',
        message: expect.stringContaining('"acme-b", is read'),
        next: true,
      });
      const check = await integrationCheck({cwd: kitDir(), strict: true});
      expect(check.data.failed).toBe(false);
    },
    SLOW,
  );
});

describe('second review follow-ups', () => {
  it(
    'names the earlier replacer in the namespace listing too',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {replaces: GUIDE}),
        'b.doc.mjs': topic('acme-b', {replaces: GUIDE}),
      });
      const parent = await docs('authoring', undefined, {cwd: tmpDir});
      const child = parent.data.slots
        .flatMap(slot => slot.children)
        .find(each => each.route === GUIDE);
      const read = await docs(GUIDE, undefined, {cwd: tmpDir});
      expect(child?.replacedPackage).toBe(read.data.replacedPackage);
      expect(child?.title).toBe('Acme acme-b');
    },
    SLOW,
  );

  it(
    'stacks docs that name a guide by its old and its new route, in order',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {
          replaces: 'cli/integrations/quick-start',
        }),
        'b.doc.mjs': topic('acme-b', {
          extends: GUIDE,
          sections: [section('acme-extra')],
        }),
      });
      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(index.data.sections.map(each => each.id)).toEqual([
        'acme-acme-a',
        'acme-extra',
      ]);
    },
    SLOW,
  );

  it(
    'lets a later replacement by the old route drop an earlier extension',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {
          extends: GUIDE,
          sections: [section('acme-extra')],
        }),
        'b.doc.mjs': topic('acme-b', {
          replaces: 'cli/integrations/quick-start',
        }),
      });
      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(index.data.sections.map(each => each.id)).toEqual(['acme-acme-b']);
    },
    SLOW,
  );

  it('asks a package that places sections for a CLI that reads before and after', () => {
    expect(
      sectionPositionCliProblem({
        peerDependencies: {'@astryxdesign/cli': '>=0.6.0'},
      }),
    ).toContain('`before` or `after`');
    expect(
      sectionPositionCliProblem({
        peerDependencies: {'@astryxdesign/cli': '>=0.7.4'},
      }),
    ).toBeNull();
  });
});

describe('third review follow-ups', () => {
  /**
   * A project that configures two kits, each with these docs.
   * @param {Record<string, object>} one
   * @param {Record<string, object>} two
   */
  function scaffoldTwo(one, two) {
    scaffold(one);
    fs.writeFileSync(
      path.join(tmpDir, 'astryx.config.mjs'),
      `export default {integrations: ['${KIT}', '@acme/more']};\n`,
    );
    const dir = path.join(tmpDir, 'node_modules', '@acme', 'more');
    fs.mkdirSync(path.join(dir, 'docs'), {recursive: true});
    fs.writeFileSync(
      path.join(dir, 'package.json'),
      JSON.stringify({name: '@acme/more', version: '1.0.0', type: 'module'}),
    );
    fs.writeFileSync(
      path.join(dir, 'astryx.integration.mjs'),
      "export default {docs: './docs'};\n",
    );
    for (const [file, doc] of Object.entries(two)) {
      fs.writeFileSync(
        path.join(dir, 'docs', file),
        `export default ${JSON.stringify(doc, null, 2)};\n`,
      );
    }
  }

  it(
    'keeps configured order for sections two packages place after one key',
    async () => {
      scaffoldTwo(
        {
          'a.doc.mjs': topic('acme-a', {
            extends: GUIDE,
            sections: [section('acme-first', {after: 'quick-start'})],
          }),
        },
        {
          'b.doc.mjs': topic('acme-b', {
            extends: GUIDE,
            sections: [section('acme-second', {after: 'quick-start'})],
          }),
        },
      );
      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(
        index.data.sections.slice(0, 3).map(s => [s.id, s.package]),
      ).toEqual([
        ['quick-start', CLI],
        ['acme-first', KIT],
        ['acme-second', '@acme/more'],
      ]);
    },
    SLOW,
  );

  it(
    'notes one package replacing a guide by its old and its new route',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {
          replaces: 'cli/integrations/quick-start',
        }),
        'b.doc.mjs': topic('acme-b', {replaces: GUIDE}),
      });
      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      expect(validated.data.notes).toContainEqual({
        code: 'duplicate_guide_replacement',
        message: expect.stringContaining('"acme-b", is read'),
        next: true,
      });
    },
    SLOW,
  );
});

describe('fourth review follow-ups', () => {
  /**
   * Add another configured package that ships these docs.
   * @param {string} pkg
   * @param {Record<string, object>} files
   */
  function addPackage(pkg, files) {
    const config = path.join(tmpDir, 'astryx.config.mjs');
    const listed = fs.readFileSync(config, 'utf8').match(/\[(.*)\]/)?.[1] ?? '';
    fs.writeFileSync(
      config,
      `export default {integrations: [${listed}, '${pkg}']};\n`,
    );
    const dir = path.join(tmpDir, 'node_modules', ...pkg.split('/'));
    fs.mkdirSync(path.join(dir, 'docs'), {recursive: true});
    fs.writeFileSync(
      path.join(dir, 'package.json'),
      JSON.stringify({name: pkg, version: '1.0.0', type: 'module'}),
    );
    fs.writeFileSync(
      path.join(dir, 'astryx.integration.mjs'),
      "export default {docs: './docs'};\n",
    );
    for (const [file, doc] of Object.entries(files)) {
      fs.writeFileSync(
        path.join(dir, 'docs', file),
        `export default ${JSON.stringify(doc, null, 2)};\n`,
      );
    }
  }

  it(
    'keeps the place of a placed section that a later package replaces',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {
          extends: GUIDE,
          sections: [section('acme-first', {after: 'quick-start'})],
        }),
      });
      addPackage('@acme/two', {
        'b.doc.mjs': topic('acme-b', {
          extends: GUIDE,
          sections: [{...section('acme-first'), title: 'First, revised'}],
        }),
      });
      addPackage('@acme/three', {
        'c.doc.mjs': topic('acme-c', {
          extends: GUIDE,
          sections: [section('acme-third', {after: 'quick-start'})],
        }),
      });
      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(
        index.data.sections.slice(0, 3).map(s => [s.id, s.package]),
      ).toEqual([
        ['quick-start', CLI],
        ['acme-first', '@acme/two'],
        ['acme-third', '@acme/three'],
      ]);
    },
    SLOW,
  );
});

describe('fifth review follow-ups', () => {
  it(
    'does not call a route replacement named like a CLI topic an accidental conflict',
    async () => {
      scaffold({
        'getting-started.doc.mjs': topic('getting-started', {replaces: GUIDE}),
      });
      const result = await integrationDocConflicts(KIT, {cwd: tmpDir});
      expect(result.data.issues).toEqual([]);
      expect(
        result.data.findings.filter(each => each.relationship === 'accidental'),
      ).toEqual([]);
      const listed = await docs(undefined, undefined, {cwd: tmpDir});
      expect(
        listed.data.find(each => each.topic === 'getting-started')?.package,
      ).toBe(CLI);
    },
    SLOW,
  );

  it(
    'names what a topic replaced twice took over the same way in every read',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {replaces: 'getting-started'}),
        'b.doc.mjs': topic('acme-b', {replaces: 'getting-started'}),
      });
      const listed = await docs(undefined, undefined, {cwd: tmpDir});
      const item = listed.data.find(each => each.topic === 'acme-b');
      const index = await docs('acme-b', undefined, {cwd: tmpDir, index: true});
      const read = await docs('acme-b', undefined, {cwd: tmpDir});
      expect(index.data.replaces).toBe(item?.replaces);
      expect(read.data.replaces).toBe(item?.replaces);
      expect(read.data.replacedPackage).toBe(item?.replacedPackage);
    },
    SLOW,
  );
});

describe('whole-diff self-review', () => {
  it('keeps a chain of after placements in order across packages', () => {
    let doc = {
      sections: [
        {id: 'x', title: 'X', content: []},
        {id: 'y', title: 'Y', content: []},
      ],
    };
    for (const overlay of [
      {sections: [{id: 'first', title: 'First', after: 'x', content: []}]},
      {sections: [{id: 'second', title: 'Second', after: 'x', content: []}]},
      {
        sections: [
          {
            id: 'under-first',
            title: 'Under first',
            after: 'first',
            content: [],
          },
        ],
      },
      {
        sections: [
          {
            id: 'before-second',
            title: 'Before second',
            before: 'second',
            content: [],
          },
        ],
      },
      {sections: [{id: 'last', title: 'Last', after: 'x', content: []}]},
    ]) {
      doc = mergeTopic(doc, overlay);
    }
    expect(doc.sections.map((/** @type {any} */ each) => each.id)).toEqual([
      'x',
      'first',
      'under-first',
      'before-second',
      'second',
      'last',
      'y',
    ]);
  });

  it(
    'counts a key an earlier doc of the package adds as a section of the guide',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {
          extends: GUIDE,
          sections: [section('acme-x', {after: 'quick-start'})],
        }),
        'b.doc.mjs': topic('acme-b', {
          extends: GUIDE,
          sections: [section('acme-y', {after: 'acme-x'})],
        }),
      });
      const index = await docs(GUIDE, undefined, {cwd: tmpDir, index: true});
      expect(index.data.sections.slice(0, 3).map(s => s.id)).toEqual([
        'quick-start',
        'acme-x',
        'acme-y',
      ]);
      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      expect(
        (validated.data.notes ?? []).filter(
          n => n.code === 'doc_section_unplaced',
        ),
      ).toEqual([]);
    },
    SLOW,
  );

  it(
    'still notes a key no doc of the target adds, with earlier extensions merged',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {
          extends: GUIDE,
          sections: [section('acme-x', {after: 'quick-start'})],
        }),
        'b.doc.mjs': topic('acme-b', {
          extends: GUIDE,
          sections: [section('acme-y', {after: 'acme-nope'})],
        }),
      });
      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      expect(
        (validated.data.notes ?? []).filter(
          n => n.code === 'doc_section_unplaced',
        ),
      ).toEqual([
        expect.objectContaining({
          message: expect.stringContaining('"acme-nope"'),
        }),
      ]);
    },
    SLOW,
  );
});

describe('old routes in messages', () => {
  it(
    'names the guide at its route now in notes and doctor findings',
    async () => {
      scaffold({
        'a.doc.mjs': topic('acme-a', {
          extends: 'cli/integrations/quick-start',
          sections: [section('acme-x', {after: 'acme-nope'})],
        }),
      });
      const validated = await validateIntegration(KIT, {cwd: tmpDir});
      const note = (validated.data.notes ?? []).find(
        n => n.code === 'doc_section_unplaced',
      );
      expect(note?.message).toContain(`docs ${GUIDE} --index`);
      expect(note?.message).not.toContain('cli/integrations');
      const result = await integrationDocConflicts(KIT, {cwd: tmpDir});
      const finding = result.data.findings.find(f => f.topic === 'acme-a');
      expect(finding).toMatchObject({
        relationship: 'extends',
        coreTopic: GUIDE,
      });
      expect(finding?.message).not.toContain('cli/integrations');
    },
    SLOW,
  );
});