Skip to content

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

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

import fs from 'node:fs';
import {execFileSync} from 'node:child_process';
import os from 'node:os';
import path from 'node:path';
import {afterEach, describe, expect, it} from 'vitest';
import {
  GLOBAL_REVIEW_TRIGGERS,
  collectGlobalReviewMatches,
} from './check-knowledge.mjs';
import {
  findUnreachedRecords,
  findUnroutedFiles,
  loadKnowledgeIndex,
  resolveSpecsForFile,
  formatResult,
} from './specs-for-file.mjs';

const repoRoot = path.resolve(import.meta.dirname, '..');
const roots = [];

afterEach(() => {
  for (const root of roots.splice(0)) {
    fs.rmSync(root, {recursive: true, force: true});
  }
});

function fixtureRoot() {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-specs-for-'));
  roots.push(root);
  return root;
}

function write(root, relative, content = '') {
  const absolute = path.join(root, relative);
  fs.mkdirSync(path.dirname(absolute), {recursive: true});
  fs.writeFileSync(absolute, content);
}

function frontmatterValue(value) {
  return Array.isArray(value) ? `[${value.join(', ')}]` : String(value);
}

function writeRecord(root, relative, fields, body = '') {
  const lines = Object.entries({authority: 'current', ...fields}).map(
    ([key, value]) => `${key}: ${frontmatterValue(value)}`,
  );
  write(root, relative, `---\n${lines.join('\n')}\n---\n\n# Record\n${body}`);
}

function globalBlock(triggers) {
  return [
    '',
    '<!-- review-applicability:v1 -->',
    '',
    '```json',
    JSON.stringify({scope: 'global', triggers}),
    '```',
    '',
    '## Requirements',
    '',
    ...Object.values(triggers)
      .flat()
      .map(id => `- **${id} — Claim ${id}.** Detail.`),
    '',
  ].join('\n');
}

/**
 * A small repository: Popover (component + family + architecture + deciding
 * spec), a Dialog module directory, a tooling architecture, and a docs topic.
 */
function popoverFixture() {
  const root = fixtureRoot();
  write(root, 'packages/core/src/Popover/Popover.tsx');
  write(root, 'packages/core/src/Popover/Popover.test.tsx');
  write(
    root,
    'packages/core/src/Popover/Popover.doc.mjs',
    "export const docs = {name: 'Popover', usage: {anatomy: [{name: 'Table'}]}, components: [{name: 'PopoverTrigger', description: 'Opens it.'}, {name: 'Item'}]};\n",
  );
  writeRecord(root, 'docs/specs/components/Popover/Popover.spec.md', {
    kind: 'component',
    id: 'component:Popover',
    review_triggers: ['behavior', 'layering'],
    verified_by: ['packages/core/src/Popover/Popover.test.tsx'],
    families: ['family:overlay-dismissal'],
    architecture: ['architecture:layer-runtime'],
    modules: [],
  });
  writeRecord(root, 'docs/families/overlay-dismissal.md', {
    kind: 'family',
    id: 'family:overlay-dismissal',
    members: ['component:Popover', 'component:Tooltip'],
    architecture: [],
    deciding_specs: ['spec:AST-003'],
  });
  writeRecord(root, 'docs/architecture/layer-runtime.md', {
    kind: 'architecture',
    id: 'architecture:layer-runtime',
    applies_to: ['packages/core/src/Layer/'],
    verified_by: ['scripts/layer-check.mjs'],
    deciding_specs: [],
  });
  writeRecord(root, 'docs/specs/AST-003/spec.md', {
    kind: 'system-spec',
    id: 'spec:AST-003',
    affects_architecture: ['architecture:layer-runtime'],
    affects_families: [],
    affects_consumer_docs: [],
  });
  writeRecord(root, 'docs/specs/AST-013/spec.md', {
    kind: 'system-spec',
    id: 'spec:AST-013',
    affects_architecture: [],
    affects_families: [],
    affects_consumer_docs: ['Tooltip', 'browser-support'],
  });
  writeRecord(
    root,
    'docs/specs/AST-020/spec.md',
    {
      kind: 'system-spec',
      id: 'spec:AST-020',
      affects_architecture: [],
      affects_families: [],
      affects_consumer_docs: [],
    },
    globalBlock({behavior: ['FR1'], testing: ['FR2']}),
  );
  writeRecord(root, 'docs/specs/AST-090/spec.md', {
    kind: 'system-spec',
    id: 'spec:AST-090',
    authority: 'draft',
    affects_architecture: [],
    affects_families: ['family:overlay-dismissal'],
    affects_consumer_docs: [],
  });

  write(root, 'packages/core/src/Dialog/Dialog.tsx');
  write(root, 'packages/core/src/Dialog/modules/DialogHeader.tsx');
  write(root, 'packages/core/src/Dialog/modules/DialogHeader.test.tsx');
  write(root, 'packages/core/src/Dialog/modules/DialogFooter.tsx');
  writeRecord(
    root,
    'docs/specs/components/Dialog/modules/DialogHeader.spec.md',
    {
      kind: 'module',
      id: 'module:Dialog/DialogHeader',
      parent_component: 'component:Dialog',
      references: [],
    },
  );
  writeRecord(root, 'docs/specs/components/Dialog/modules/DialogBody.spec.md', {
    kind: 'module',
    id: 'module:Dialog/DialogBody',
    parent_component: 'component:Dialog',
    references: [],
  });
  write(root, 'packages/core/src/Table/plugins/activation/useActivation.ts');
  write(root, 'packages/core/src/Table/plugins/activation/helpers/key.ts');
  writeRecord(
    root,
    'docs/specs/components/Table/plugins/activation/useTableActivation.spec.md',
    {
      kind: 'module',
      id: 'module:Table/useTableActivation',
      parent_component: 'component:Table',
      references: [],
    },
  );

  write(root, 'packages/core/src/Layer/Layer.tsx');
  write(root, 'packages/core/src/LayerProvider/LayerProvider.tsx');
  write(root, 'scripts/layer-check.mjs');
  write(root, 'packages/cli/assets/docs/browser-support.doc.mjs');
  write(root, 'packages/cli/assets/docs/tree/browser-support.doc.mjs');
  write(root, 'apps/docsite/src/content/blog/posts/release.md');
  writeRecord(root, 'docs/families/data-display.md', {
    kind: 'family',
    id: 'family:data-display',
    members: ['component:Table', 'component:Item', 'component:ChatHeadingItem'],
    architecture: [],
    deciding_specs: [],
  });
  write(root, 'packages/core/src/Drawer/Drawer.tsx');
  writeRecord(root, 'docs/specs/components/Drawer/Drawer.spec.md', {
    kind: 'component',
    id: 'component:Drawer',
    authority: 'draft',
    review_triggers: ['motion'],
    verified_by: [],
    families: [],
    architecture: ['architecture:container-padding'],
    system_specs: ['spec:AST-017/DEC-1'],
    modules: [],
  });
  writeRecord(root, 'docs/architecture/container-padding.md', {
    kind: 'architecture',
    id: 'architecture:container-padding',
    applies_to: ['packages/core/src/Layout/'],
    verified_by: [],
    deciding_specs: [],
  });
  write(
    root,
    'packages/core/src/Chat/Chat.doc.mjs',
    "export const docs = {name: 'Chat'};\n",
  );
  write(root, 'packages/core/src/Chat/ChatMessageList.tsx');
  write(root, 'packages/core/src/Chat/ChatComposerDrawer.tsx');
  write(root, 'packages/core/src/Chat/ChatComposerDrawer.test.tsx');
  write(
    root,
    'packages/core/src/Chat/__tests__/ChatComposerDrawer.a11y.states.ts',
  );
  write(root, 'packages/core/src/Chat/ChatHeadingItem.tsx');
  writeRecord(root, 'docs/specs/components/Chat/ChatComposerDrawer.spec.md', {
    kind: 'component',
    id: 'component:ChatComposerDrawer',
    review_triggers: ['motion'],
    verified_by: [],
    families: [],
    architecture: [],
    modules: [],
  });
  write(root, 'packages/core/src/Markdown/Markdown.tsx');
  write(root, 'packages/core/src/Markdown/plugins/headingLinks.ts');
  write(root, 'packages/core/src/Markdown/plugins/softBreaks.ts');
  writeRecord(
    root,
    'docs/specs/components/Markdown/modules/headingLinks.spec.md',
    {
      kind: 'module',
      id: 'module:Markdown/headingLinks',
      parent_component: 'component:Markdown',
      references: [],
    },
  );
  writeRecord(
    root,
    'docs/specs/components/Markdown/modules/softBreaks.spec.md',
    {
      kind: 'module',
      id: 'module:Markdown/softBreaks',
      parent_component: 'component:Markdown',
      references: [],
    },
  );
  write(root, 'packages/core/src/hooks/useMenuPress.ts');
  write(root, 'packages/core/src/hooks/useMenuPress.test.tsx');
  write(root, 'packages/core/src/hooks/useEntryAnimation.ts');
  write(
    root,
    'packages/core/src/hooks/useMenuPress.doc.mjs',
    "export const docs = {name: 'useMenuPress'};\n",
  );
  write(
    root,
    'packages/core/src/hooks/useEntryAnimation.doc.mjs',
    "export const docs = {name: 'useEntryAnimation'};\n",
  );
  writeRecord(
    root,
    'docs/specs/components/DropdownMenu/modules/useMenuPress.spec.md',
    {
      kind: 'module',
      id: 'module:DropdownMenu/useMenuPress',
      parent_component: 'component:DropdownMenu',
      verified_by: ['packages/core/src/hooks/useMenuPress.test.tsx'],
      references: [],
    },
  );
  writeRecord(root, 'docs/specs/AST-014/spec.md', {
    kind: 'system-spec',
    id: 'spec:AST-014',
    affects_architecture: [],
    affects_families: [],
    affects_consumer_docs: ['useEntryAnimation'],
  });
  write(root, 'apps/sandbox/src/app/(fullscreen)/pages/perf/benchmark.test.ts');
  writeRecord(root, 'docs/specs/components/Markdown/Markdown.spec.md', {
    kind: 'component',
    id: 'component:Markdown',
    review_triggers: ['behavior'],
    verified_by: [
      'apps/sandbox/src/app/(fullscreen)/pages/perf/benchmark.test.ts',
      'browser check of the rendered page',
    ],
    families: [],
    architecture: [],
    system_specs: ['spec:AST-017/FR3'],
    modules: [],
  });
  write(root, 'packages/cli/assets/docs/color.doc.mjs');
  write(root, 'packages/core/src/utils/color.ts');
  writeRecord(root, 'docs/specs/AST-008/spec.md', {
    kind: 'system-spec',
    id: 'spec:AST-008',
    affects_architecture: [],
    affects_families: [],
    affects_consumer_docs: ['color'],
  });
  write(root, 'packages/core/src/TabList/TabList.tsx');
  writeRecord(root, 'docs/specs/components/TabList/TabList.spec.md', {
    kind: 'component',
    id: 'component:TabList',
    review_triggers: ['behavior'],
    verified_by: [],
    families: [],
    architecture: [],
    system_specs: ['spec:AST-017/DEC-1'],
    modules: [],
  });
  writeRecord(root, 'docs/specs/AST-017/spec.md', {
    kind: 'system-spec',
    id: 'spec:AST-017',
    affects_architecture: [],
    affects_families: [],
    affects_consumer_docs: [],
  });
  write(
    root,
    'scripts/fixture-heavy.test.mjs',
    "const record = 'docs/specs/AST-013/spec.md';\nconst link = '../AST-013/spec.md';\n",
  );
  write(
    root,
    'packages/core/src/utils/plainDate.ts',
    '// Resolves wall time per AST-013 and docs/architecture/layer-runtime.md.\n// Day boundaries follow AST-017/DEC-1 and AST-020/FR15 (see AST-020 FR9). Not AST-0130 or XAST-020.\n',
  );
  return root;
}

function ids(entries) {
  return entries.map(entry => entry.id).sort();
}

describe('resolveSpecsForFile', () => {
  it('routes a component file to its record, family, inherited architecture, and deciding specs', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(
      index,
      'packages/core/src/Popover/Popover.tsx',
    );
    expect(ids(result.records)).toEqual([
      'architecture:layer-runtime',
      'component:Popover',
      'family:overlay-dismissal',
    ]);
    const family = result.records.find(
      record => record.id === 'family:overlay-dismissal',
    );
    expect(family.routes).toEqual([
      {via: 'members', detail: 'component:Popover'},
      {via: 'inherited:families', detail: 'component:Popover'},
    ]);
    expect(ids(result.decidingSpecs)).toEqual(['spec:AST-003']);
    expect(result.component).toEqual({
      package: 'core',
      root: 'Popover',
      names: ['Popover', 'PopoverTrigger'],
    });
    expect(result.source).toBe('working-tree');
  });

  it('keeps draft records out unless asked', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const file = 'packages/core/src/Popover/Popover.tsx';
    expect(ids(resolveSpecsForFile(index, file).decidingSpecs)).not.toContain(
      'spec:AST-090',
    );
    expect(
      ids(resolveSpecsForFile(index, file, {includeDraft: true}).decidingSpecs),
    ).toContain('spec:AST-090');
  });

  it('routes a module by its same-stem sources and a dedicated module directory by subtree', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const header = resolveSpecsForFile(
      index,
      'packages/core/src/Dialog/modules/DialogHeader.test.tsx',
    );
    expect(ids(header.records)).toEqual(['module:Dialog/DialogHeader']);
    const footer = resolveSpecsForFile(
      index,
      'packages/core/src/Dialog/modules/DialogFooter.tsx',
    );
    expect(footer.records).toEqual([]);
    const plugin = resolveSpecsForFile(
      index,
      'packages/core/src/Table/plugins/activation/helpers/key.ts',
    );
    expect(ids(plugin.records)).toEqual([
      'family:data-display',
      'module:Table/useTableActivation',
    ]);
  });

  it('matches applies_to by path segment, never by string prefix', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    expect(
      ids(
        resolveSpecsForFile(index, 'packages/core/src/Layer/Layer.tsx').records,
      ),
    ).toContain('architecture:layer-runtime');
    expect(
      resolveSpecsForFile(
        index,
        'packages/core/src/LayerProvider/LayerProvider.tsx',
      ).records,
    ).toEqual([]);
  });

  it('routes verified_by evidence to the record it verifies', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(index, 'scripts/layer-check.mjs');
    expect(result.records[0]).toMatchObject({
      id: 'architecture:layer-runtime',
      routes: [{via: 'verified_by', detail: 'scripts/layer-check.mjs'}],
    });
  });

  it('routes consumer-doc ids to their topic files', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    for (const file of [
      'packages/cli/assets/docs/browser-support.doc.mjs',
      'packages/cli/assets/docs/tree/browser-support.doc.mjs',
    ]) {
      expect(ids(resolveSpecsForFile(index, file).records)).toEqual([
        'spec:AST-013',
      ]);
    }
  });

  it('takes component names from docs and full component entries, never anatomy parts or partial entries', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(
      index,
      'packages/core/src/Popover/Popover.tsx',
    );
    expect(ids(result.records)).not.toContain('family:data-display');
  });

  it('never lets a draft record steer the result unless drafts are asked for', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const file = 'packages/core/src/Drawer/Drawer.tsx';
    const current = resolveSpecsForFile(index, file);
    expect(current.records).toEqual([]);
    expect(current.decisions).toEqual([]);
    expect(current.triggers).not.toEqual(['motion']);
    const withDrafts = resolveSpecsForFile(index, file, {includeDraft: true});
    expect(ids(withDrafts.records)).toEqual([
      'architecture:container-padding',
      'component:Drawer',
    ]);
    expect(withDrafts.triggers).toEqual(['motion']);
  });

  it('lists a decision-scoped citation as that decision, not the whole record', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(
      index,
      'packages/core/src/TabList/TabList.tsx',
    );
    expect(ids(result.records)).toEqual(['component:TabList']);
    expect(result.decisions).toEqual([
      expect.objectContaining({
        id: 'spec:AST-017/DEC-1',
        recordId: 'spec:AST-017',
        decision: 'DEC-1',
        routes: [{via: 'inherited:system_specs', detail: 'component:TabList'}],
      }),
    ]);
  });

  it('places a member component record only over its same-stem files', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const unrelated = resolveSpecsForFile(
      index,
      'packages/core/src/Chat/ChatMessageList.tsx',
    );
    expect(ids(unrelated.records)).toEqual([]);
    expect(unrelated.triggers).not.toEqual(['motion']);
    const own = resolveSpecsForFile(
      index,
      'packages/core/src/Chat/ChatComposerDrawer.test.tsx',
    );
    expect(ids(own.records)).toEqual(['component:ChatComposerDrawer']);
    expect(own.triggers).toEqual(['motion']);
    expect(
      ids(
        resolveSpecsForFile(
          index,
          'packages/core/src/Chat/__tests__/ChatComposerDrawer.a11y.states.ts',
        ).records,
      ),
    ).toEqual(['component:ChatComposerDrawer']);
  });

  it("places a platform record over its language's code and brings in the core record", () => {
    const root = fixtureRoot();
    write(root, 'packages/core/src/Avatar/Avatar.tsx');
    write(root, 'packages/native/apple/Sources/Astryx/Avatar/Avatar.swift');
    write(
      root,
      'packages/native/apple/Sources/Astryx/Avatar/AvatarStatusDot.swift',
    );
    write(root, 'packages/native/apple/Sources/Astryx/Button/Button.swift');
    writeRecord(root, 'docs/specs/components/Avatar/Avatar.spec.md', {
      kind: 'component',
      id: 'component:Avatar',
    });
    writeRecord(root, 'docs/specs/components/Avatar/Avatar.swift.spec.md', {
      kind: 'component',
      id: 'component:swift/Avatar',
      platform_of: 'component:Avatar',
    });
    writeRecord(
      root,
      'docs/specs/components/Avatar/AvatarStatusDot.swift.spec.md',
      {
        kind: 'component',
        id: 'component:swift/AvatarStatusDot',
        platform_of: 'component:AvatarStatusDot',
      },
    );
    const index = loadKnowledgeIndex(root);
    const lookup = file => ids(resolveSpecsForFile(index, file).records);

    expect(
      lookup('packages/native/apple/Sources/Astryx/Avatar/Avatar.swift'),
    ).toEqual(['component:Avatar', 'component:swift/Avatar']);
    expect(
      lookup(
        'packages/native/apple/Sources/Astryx/Avatar/AvatarStatusDot.swift',
      ),
    ).toEqual([
      'component:Avatar',
      'component:swift/Avatar',
      'component:swift/AvatarStatusDot',
    ]);
    expect(lookup('packages/core/src/Avatar/Avatar.tsx')).toEqual([
      'component:Avatar',
    ]);
    expect(
      lookup('packages/native/apple/Sources/Astryx/Button/Button.swift'),
    ).toEqual([]);
    expect(
      lookup('docs/specs/components/Avatar/AvatarStatusDot.swift.spec.md'),
    ).toEqual(['component:swift/AvatarStatusDot']);
    expect(
      findUnreachedRecords(index, [
        'packages/core/src/Avatar/Avatar.tsx',
        'packages/native/apple/Sources/Astryx/Avatar/AvatarStatusDot.swift',
      ]).map(record => record.id),
    ).toEqual([]);
  });

  it('names a member without its own consumer doc by its file stem', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    expect(
      ids(
        resolveSpecsForFile(index, 'packages/core/src/Chat/ChatHeadingItem.tsx')
          .records,
      ),
    ).toEqual(['family:data-display']);
  });

  it('places a module record over its same-stem sources anywhere in its component root', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    expect(
      ids(
        resolveSpecsForFile(
          index,
          'packages/core/src/Markdown/plugins/headingLinks.ts',
        ).records,
      ),
    ).toEqual(['component:Markdown', 'module:Markdown/headingLinks']);
    expect(
      ids(
        resolveSpecsForFile(index, 'packages/core/src/Markdown/Markdown.tsx')
          .records,
      ),
    ).toEqual(['component:Markdown']);
  });

  it('places a module record beside the same-stem verified_by evidence outside its root', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const source = resolveSpecsForFile(
      index,
      'packages/core/src/hooks/useMenuPress.ts',
    );
    expect(ids(source.records)).toEqual(['module:DropdownMenu/useMenuPress']);
    expect(source.records[0].routes[0].via).toBe('placement');
    expect(
      ids(
        resolveSpecsForFile(
          index,
          'packages/core/src/hooks/useEntryAnimation.ts',
        ).records,
      ),
    ).toEqual(['spec:AST-014']);
  });

  it('names a file in a shared directory by its own same-stem doc', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(
      index,
      'packages/core/src/hooks/useMenuPress.ts',
    );
    expect(result.component.names).toEqual(['useMenuPress']);
    expect(
      resolveSpecsForFile(index, 'packages/core/src/Chat/ChatMessageList.tsx')
        .component.names,
    ).toEqual(['Chat', 'ChatMessageList']);
    expect(ids(result.records)).not.toContain('spec:AST-014');
  });

  it('matches declared paths with route-group segments, and skips prose entries', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(
      index,
      'apps/sandbox/src/app/(fullscreen)/pages/perf/benchmark.test.ts',
    );
    expect(result.records[0]).toMatchObject({
      id: 'component:Markdown',
      routes: [
        {
          via: 'verified_by',
          detail:
            'apps/sandbox/src/app/(fullscreen)/pages/perf/benchmark.test.ts',
        },
      ],
    });
  });

  it('lists a claim-scoped reference as that claim, not the whole record', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(
      index,
      'packages/core/src/Markdown/Markdown.tsx',
    );
    expect(ids(result.records)).toEqual(['component:Markdown']);
    expect(result.decisions).toEqual([
      expect.objectContaining({
        id: 'spec:AST-017/FR3',
        decision: 'FR3',
        routes: [{via: 'inherited:system_specs', detail: 'component:Markdown'}],
      }),
    ]);
  });

  it('keeps a consumer-doc topic id on its topic file, not on files sharing its stem', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    expect(
      resolveSpecsForFile(index, 'packages/core/src/utils/color.ts').records,
    ).toEqual([]);
    expect(
      ids(
        resolveSpecsForFile(index, 'packages/cli/assets/docs/color.doc.mjs')
          .records,
      ),
    ).toEqual(['spec:AST-008']);
  });

  it('ignores spec numbers inside record paths', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(index, 'scripts/fixture-heavy.test.mjs');
    expect(result.records).toEqual([]);
    expect(result.decisions).toEqual([]);
  });

  it('routes a file to the system specs it cites by number', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(
      index,
      'packages/core/src/utils/plainDate.ts',
    );
    expect(
      result.records.map(record => [
        record.id,
        record.routes[0].via,
        record.routes[0].detail,
      ]),
    ).toEqual([['spec:AST-013', 'mentioned', 'AST-013']]);
    expect(result.decisions.map(decision => decision.id)).toEqual([
      'spec:AST-017/DEC-1',
      'spec:AST-020/FR15',
      'spec:AST-020/FR9',
    ]);
    expect(ids(result.records)).not.toContain('spec:AST-020');
  });

  it("routes a path matched by a record's path-applicability pattern", () => {
    const root = popoverFixture();
    writeRecord(
      root,
      'docs/specs/AST-033/spec.md',
      {
        kind: 'system-spec',
        id: 'spec:AST-033',
        affects_architecture: [],
        affects_families: [],
        affects_consumer_docs: [],
      },
      '\n<!-- path-applicability:v1 -->\n\n```json\n{"paths": ["apps/docsite/**"]}\n```\n',
    );
    const index = loadKnowledgeIndex(root);
    const result = resolveSpecsForFile(
      index,
      'apps/docsite/src/content/blog/posts/release.md',
    );
    expect(result.records).toEqual([
      expect.objectContaining({
        id: 'spec:AST-033',
        routes: [{via: 'path-applicability', detail: 'apps/docsite/**'}],
      }),
    ]);
    expect(
      resolveSpecsForFile(index, 'apps/docsite-legacy/index.md').records,
    ).toEqual([]);
  });

  it('reports a path no record reaches instead of guessing', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    const result = resolveSpecsForFile(
      index,
      'apps/docsite/src/content/blog/posts/release.md',
    );
    expect(result.records).toEqual([]);
    expect(result.decidingSpecs).toEqual([]);
  });

  it('selects global claims exactly as the review baseline router does', () => {
    const root = popoverFixture();
    const index = loadKnowledgeIndex(root);
    const records = index.records.map(record => ({
      path: record.path,
      content: record.content,
    }));
    const project = matches =>
      matches.map(({recordId, path: recordPath, trigger, claimId, claim}) => ({
        recordId,
        path: recordPath,
        trigger,
        claimId,
        claim,
      }));

    const local = resolveSpecsForFile(
      index,
      'packages/core/src/Popover/Popover.tsx',
    );
    expect(local.triggers).toEqual(['behavior', 'layering']);
    expect(local.globalClaims).toEqual(
      project(collectGlobalReviewMatches(records, local.triggers, null)),
    );
    expect(local.globalClaims.map(claim => claim.claimId)).toEqual(['FR1']);

    const requested = resolveSpecsForFile(index, 'scripts/layer-check.mjs', {
      triggers: ['testing'],
    });
    expect(requested.globalClaims.map(claim => claim.claimId)).toEqual(['FR2']);

    const none = resolveSpecsForFile(
      index,
      'apps/docsite/src/content/blog/posts/release.md',
    );
    expect(none.triggers).toEqual([...GLOBAL_REVIEW_TRIGGERS].sort());
  });
});

describe('concern routing', () => {
  function concernFixture() {
    const root = popoverFixture();
    writeRecord(
      root,
      'docs/architecture/react-component-runtime.md',
      {kind: 'architecture', id: 'architecture:react-component-runtime'},
      [
        '',
        '<!-- review-applicability:v1 -->',
        '',
        '```json',
        JSON.stringify({
          scope: 'global',
          concerns: {
            'slot-presence': {
              names: ['isRenderable'],
              patterns: ["typeof [\\w.]+ !== 'boolean'"],
              claims: ['INV16'],
            },
          },
        }),
        '```',
        '',
        '## Requirements',
        '',
        '- **INV16 — A shared concern is extended in its owner.** Detail.',
        '',
      ].join('\n'),
    );
    return loadKnowledgeIndex(root);
  }
  const file = 'packages/core/src/Popover/Popover.tsx';
  const addedLines = [
    {
      file,
      line: 7,
      text: "  if (label != null && typeof label !== 'boolean') {",
    },
    {
      file: 'packages/core/src/Other/Other.tsx',
      line: 1,
      text: 'isRenderable(x)',
    },
  ];

  it("lists the claims a concern routes from the file's own added lines", () => {
    const result = resolveSpecsForFile(concernFixture(), file, {addedLines});
    expect(result.concernClaims).toEqual([
      {
        recordId: 'architecture:react-component-runtime',
        path: 'docs/architecture/react-component-runtime.md',
        concern: 'slot-presence',
        claimId: 'INV16',
        claim: 'A shared concern is extended in its owner.',
        utilities: ['isRenderable'],
        evidence: [
          {
            file,
            line: 7,
            text: "  if (label != null && typeof label !== 'boolean') {",
            matched: "typeof label !== 'boolean'",
            by: "typeof [\\w.]+ !== 'boolean'",
          },
        ],
      },
    ]);
    expect(resolveSpecsForFile(concernFixture(), file).concernClaims).toEqual(
      [],
    );
  });

  it('prints the concern claims first and lists the linked records by id', () => {
    const result = resolveSpecsForFile(concernFixture(), file, {addedLines});
    const short = formatResult(result).split('\n');
    expect(short[1]).toBe(
      '  Follow first (the change touches a shared concern):',
    );
    expect(short[2]).toBe(
      "    architecture:react-component-runtime  INV16  ← slot-presence (line 7: typeof label !== 'boolean'; shared: isRenderable)",
    );
    // Every linked record is still listed, by id (INV26).
    expect(
      short.some(line => /^ {2}Records: .*component:Popover/.test(line)),
    ).toBe(true);
    expect(short.join('\n')).not.toContain('via ');
    const long = formatResult(result, {records: true}).split('\n');
    expect(long.join('\n')).toContain('via ');
    // --records prints the same concern claims first.
    expect(long.slice(1, 3)).toEqual(short.slice(1, 3));
  });
});

describe('coverage audits', () => {
  it('lists current records only their own file reaches', () => {
    const root = popoverFixture();
    const index = loadKnowledgeIndex(root);
    const files = [
      'packages/core/src/Popover/Popover.tsx',
      'docs/specs/AST-020/spec.md',
      'docs/specs/AST-013/spec.md',
    ];
    expect(ids(findUnreachedRecords(index, files))).toEqual([
      'architecture:container-padding',
      'component:ChatComposerDrawer',
      'component:Markdown',
      'component:TabList',
      'family:data-display',
      'module:Dialog/DialogBody',
      'module:Dialog/DialogHeader',
      'module:DropdownMenu/useMenuPress',
      'module:Markdown/headingLinks',
      'module:Markdown/softBreaks',
      'module:Table/useTableActivation',
      'spec:AST-008',
      'spec:AST-013',
      'spec:AST-014',
      'spec:AST-017',
      'spec:AST-020',
    ]);
    expect(
      ids(
        findUnreachedRecords(index, [
          ...files,
          'packages/core/src/TabList/TabList.tsx',
        ]),
      ),
    ).not.toContain('spec:AST-017');
  });

  it('lists tracked files without a governing record', () => {
    const index = loadKnowledgeIndex(popoverFixture());
    expect(
      findUnroutedFiles(index, [
        'packages/core/src/Popover/Popover.tsx',
        'apps/docsite/src/content/blog/posts/release.md',
      ]),
    ).toEqual(['apps/docsite/src/content/blog/posts/release.md']);
  });
});

describe('repository records', () => {
  const index = loadKnowledgeIndex(repoRoot);

  it('routes every current component and module record from each same-stem source', () => {
    const tracked = execFileSync('git', ['-C', repoRoot, 'ls-files'], {
      encoding: 'utf8',
      maxBuffer: 256 * 1024 * 1024,
    })
      .split('\n')
      .filter(Boolean);
    // A record with no same-stem source is not placed from any file. That is
    // allowed here: reachability of every current record is a separate check.
    const missing = [];
    for (const record of index.records) {
      if (record.authority !== 'current' || !record.classified) continue;
      const {packageName, componentRoot, publicName, layout} =
        record.classified;
      const root =
        layout === 'flat'
          ? `packages/${packageName}/src/`
          : `packages/${packageName}/src/${componentRoot}/`;
      const evidenceDirectories = new Set(
        (record.frontmatter.get('verified_by') ?? [])
          .filter(
            entry => path.posix.basename(entry).split('.')[0] === publicName,
          )
          .map(entry => `${path.posix.dirname(entry)}/`),
      );
      const candidates = tracked.filter(
        file =>
          !file.endsWith('.spec.md') &&
          path.posix.basename(file).split('.')[0] === publicName &&
          (file.startsWith(root) ||
            (record.kind === 'module' &&
              evidenceDirectories.has(`${path.posix.dirname(file)}/`))),
      );
      for (const file of candidates) {
        if (
          !ids(
            resolveSpecsForFile(index, file, {triggers: []}).records,
          ).includes(record.id)
        ) {
          missing.push(`${record.id} from ${file}`);
        }
      }
    }
    expect(missing).toEqual([]);
  });

  it('routes every current architecture record from each applies_to path', () => {
    const missing = [];
    for (const record of index.records) {
      if (record.authority !== 'current' || record.kind !== 'architecture') {
        continue;
      }
      for (const entry of record.frontmatter.get('applies_to') ?? []) {
        const target = path.join(repoRoot, entry);
        if (!fs.existsSync(target)) continue;
        const file = fs.statSync(target).isDirectory()
          ? path.posix.join(entry.replace(/\/+$/, ''), '__probe__.ts')
          : entry;
        if (
          !ids(
            resolveSpecsForFile(index, file, {triggers: []}).records,
          ).includes(record.id)
        ) {
          missing.push(`${record.id} from ${file}`);
        }
      }
    }
    expect(missing).toEqual([]);
  });
});