Skip to content

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

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

import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {execFileSync} from 'node:child_process';
import {createRequire} from 'node:module';
import {afterEach, describe, expect, it} from 'vitest';
import {
  createRepository,
  importCommits,
  workingTreeFiles,
} from './lib/git-fixture.mjs';
import {
  composeKnowledgeSchemas,
  collectConcernMatches,
  collectGlobalReviewMatches,
  discoverKnowledgeRecords,
  extractKnowledgeClaims,
  matchesPathPattern,
  parseAnatomyThemingBlock,
  parseDesignDecisionsBlock,
  parseKnowledgeDocument,
  parsePathApplicabilityBlock,
  parseReviewApplicabilityBlock,
  routeGlobalReviewBaselinesAtRevision,
  validateAnatomyThemingMap,
  validateDesignDecisionsBlock,
  validateDelegations,
  validateKnowledgeRoot,
  validatePathApplicability,
  validateReviewApplicability,
  validateSchemaEvolution,
  approvalLineRewritesSince,
  findApprovalLineRewrites,
} from './check-knowledge.mjs';

const repoRoot = path.resolve(import.meta.dirname, '..');
const roots = [];
const {componentSpecPathForSource} = createRequire(import.meta.url)(
  '../.github/scripts/knowledge-paths.cjs',
);

/**
 * Fixtures describe a record by the source path it governs; the record itself
 * lives under docs/specs/components/, mirroring that path.
 */
function recordPath(codeSidePath) {
  const match =
    /^(.*)[\\/]packages[\\/]([^\\/]+)[\\/]src[\\/](.+\.spec\.md)$/.exec(
      codeSidePath,
    );
  if (!match) return codeSidePath;
  const target = path.join(
    match[1],
    componentSpecPathForSource(match[2], match[3].split(path.sep).join('/')),
  );
  // The source directory the record mirrors exists, as it does beside real code.
  fs.mkdirSync(path.dirname(codeSidePath), {recursive: true});
  fs.mkdirSync(path.dirname(target), {recursive: true});
  return target;
}

function fixtureRoot() {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-knowledge-'));
  roots.push(root);
  fs.mkdirSync(path.join(root, 'docs/schemas/knowledge'), {recursive: true});
  fs.mkdirSync(path.join(root, 'docs/templates'), {recursive: true});
  fs.cpSync(
    path.join(repoRoot, 'docs/templates/knowledge'),
    path.join(root, 'docs/templates/knowledge'),
    {recursive: true},
  );
  for (const version of ['v1.json', 'v2.json', 'v3.json', 'v4.json']) {
    fs.copyFileSync(
      path.join(repoRoot, `docs/schemas/knowledge/${version}`),
      path.join(root, `docs/schemas/knowledge/${version}`),
    );
  }
  for (const relative of [
    'docs/specs',
    'docs/families',
    'docs/architecture',
    'docs/themes',
    'packages/core/src',
    'packages/lab/src',
    'packages/charts/src',
    'packages/richtext/src',
    'packages/vega/src',
  ]) {
    fs.mkdirSync(path.join(root, relative), {recursive: true});
  }
  for (const relative of [
    'packages/themes/neutral',
    'packages/themes/duplicate',
  ]) {
    fs.mkdirSync(path.join(root, relative), {recursive: true});
  }
  fs.mkdirSync(path.join(root, '.github'), {recursive: true});
  for (const ownerFile of ['DESIGNOWNERS', 'ENGOWNERS']) {
    fs.copyFileSync(
      path.join(repoRoot, `.github/${ownerFile}`),
      path.join(root, `.github/${ownerFile}`),
    );
  }
  return root;
}

function addSchemaVersion(root, version) {
  const latest = JSON.parse(
    fs.readFileSync(path.join(root, 'docs/schemas/knowledge/v1.json'), 'utf8'),
  );
  latest.schemaVersion = version;
  fs.writeFileSync(
    path.join(root, `docs/schemas/knowledge/v${version}.json`),
    `${JSON.stringify(latest, null, 2)}\n`,
  );
}

function componentRecord(overrides = {}) {
  const values = {
    schema_version: '3',
    template_version: '1',
    kind: 'component',
    id: 'component:Button',
    authority: 'draft',
    archive_reason: 'null',
    superseded_by: 'null',
    approved_by: 'null',
    approved_at: 'null',
    owners: '[owner]',
    review_triggers: '[behavior]',
    verified_by: '[Button.test.tsx]',
    modules: '[]',
    families: '[family:actions]',
    design_specs: '[design:actions]',
    architecture: '[architecture:components]',
    contributing: '[contributing:api]',
    system_specs: '[]',
    ...overrides,
  };
  const frontmatter = Object.entries(values)
    .map(([key, value]) => `${key}: ${value}`)
    .join('\n');
  const sections = [
    'Intent',
    'Compatibility and migration',
    'Ownership boundary',
    'Public concepts',
    'Behavioral and layout contract',
    'Accessibility contract',
    'Design relationships',
    'Family and system relationships',
    'Verification map',
    'Decision log',
    'Open questions',
    'Content boundary',
  ]
    .map(section => `## ${section}\n\nBody.`)
    .join('\n\n');
  return `---\n${frontmatter}\n---\n\n# Button component contract\n\n${sections}\n`;
}

function platformRecord(overrides = {}) {
  return componentRecord({
    id: 'component:swift/Button',
    platform_of: 'component:Button',
    verified_by: '[packages/native/apple/Tests/AstryxTests/ButtonTests.swift]',
    ...overrides,
  });
}

function writeSwiftTest(root) {
  const swiftTest = path.join(
    root,
    'packages/native/apple/Tests/AstryxTests/ButtonTests.swift',
  );
  fs.mkdirSync(path.dirname(swiftTest), {recursive: true});
  fs.writeFileSync(swiftTest, '');
}

function moduleRecord(overrides = {}) {
  const values = {
    schema_version: '3',
    template_version: '1',
    kind: 'module',
    id: 'module:Button/useButtonThing',
    authority: 'draft',
    archive_reason: 'null',
    superseded_by: 'null',
    approved_by: 'null',
    approved_at: 'null',
    owners: '[owner]',
    review_triggers: '[public-api,behavior,accessibility]',
    verified_by: '[useButtonThing.test.ts]',
    parent_component: 'component:Button',
    references: '[]',
    ...overrides,
  };
  const frontmatter = Object.entries(values)
    .map(([key, value]) => `${key}: ${value}`)
    .join('\n');
  const sections = [
    'Intent',
    'Compatibility and migration',
    'Ownership boundary',
    'Public API and concepts',
    'Behavioral contract',
    'Accessibility contract',
    'Design relationships',
    'Parent and system relationships',
    'Verification map',
    'Decision log',
    'Open questions',
    'Content boundary',
  ]
    .map(section => `## ${section}\n\nBody.`)
    .join('\n\n');
  return `---\n${frontmatter}\n---\n\n# Button module contract\n\n${sections}\n`;
}

function themeRecord(overrides = {}) {
  const values = {
    schema_version: '2',
    template_version: '1',
    kind: 'theme',
    id: 'theme:neutral',
    authority: 'draft',
    approved_by: 'null',
    approved_at: 'null',
    review_triggers: '[tokens]',
    verified_by: '[theme.test.ts]',
    package: "'@astryxdesign/theme-neutral'",
    source_theme: 'packages/themes/neutral/src/neutralTheme.ts',
    references: '[architecture:theme-test]',
    ...overrides,
  };
  const frontmatter = Object.entries(values)
    .map(([key, value]) => `${key}: ${value}`)
    .join('\n');
  const sections = [
    'Intent and audience',
    'Inheritance and base',
    'Portable token overrides',
    'Theme-local role definitions',
    'Tonal palette definitions',
    'Component and state mappings',
    'Compatibility and migration',
    'Accessibility and contrast evidence',
    'Build and artifact contract',
    'Verification map',
    'Decision log',
    'Open questions',
    'Content boundary',
  ]
    .map(section => `## ${section}\n\nBody.`)
    .join('\n\n');
  return `---\n${frontmatter}\n---\n\n# Neutral theme specification\n\n${sections}\n`;
}

function systemSpecRecord(overrides = {}) {
  const values = {
    schema_version: '4',
    template_version: '1',
    kind: 'system-spec',
    id: 'spec:AST-900',
    authority: 'current',
    archive_reason: 'null',
    superseded_by: 'null',
    approved_by: 'cixzhang',
    approved_at: '2026-08-31',
    phase: 'accepted',
    owners: '[cixzhang]',
    affects_architecture: '[]',
    affects_families: '[]',
    affects_contributing: '[]',
    affects_consumer_docs: '[]',
    ...overrides,
  };
  const frontmatter = Object.entries(values)
    .map(([key, value]) => `${key}: ${value}`)
    .join('\n');
  const sections = [
    'Intent',
    'Non-goals',
    'Requirements',
    'Current-state impact',
    'Verification',
    'Decision log',
    'Open questions',
  ]
    .map(section => `## ${section}\n\nBody.`)
    .join('\n\n');
  return `---\n${frontmatter}\n---\n\n# Fixture system spec\n\n${sections}\n`;
}

function writeSystemSpec(root, directoryName, record) {
  const directory = path.join(root, `docs/specs/${directoryName}`);
  fs.mkdirSync(directory);
  fs.writeFileSync(path.join(directory, 'spec.md'), record);
}

function writeCurrentArchitecture(root) {
  const template = fs.readFileSync(
    path.join(root, 'docs/templates/knowledge/architecture.md'),
    'utf8',
  );
  fs.writeFileSync(
    path.join(root, 'docs/architecture/theme-test.md'),
    template
      .replace('id: architecture:<surface>', 'id: architecture:theme-test')
      .replace('authority: draft', 'authority: current')
      .replace('approved_by: null', 'approved_by: cixzhang')
      .replace('approved_at: null', 'approved_at: 2026-08-31'),
  );
}

function anatomyThemingBlock(mapping) {
  return `### Theming anatomy\n\n<!-- anatomy-theming:v1 -->\n\`\`\`json\n${JSON.stringify(mapping, null, 2)}\n\`\`\``;
}

function withAnatomyTheming(record, mapping) {
  return record.replace(
    '## Design relationships\n\nBody.',
    `## Design relationships\n\nBody.\n\n${anatomyThemingBlock(mapping)}`,
  );
}

function writeButtonDoc(directory) {
  const content = `export const docs = {
  name: 'Button',
  displayName: 'Button',
  category: 'Actions',
  keywords: ['button'],
  props: [],
  usage: {
    anatomy: [
      {name: 'Root', required: true, description: 'Painted surface.'},
      {name: 'Label', required: true, description: 'Visible label.'},
      {name: 'Icon', required: false, description: 'Shared icon.'},
      {name: 'Content', required: false, description: 'Consumer content.'},
    ],
    description: 'A button triggers an action. Use it for a discrete action.',
    bestPractices: [],
  },
  theming: {
    targets: [{className: 'astryx-button'}],
  },
};\n`;
  fs.writeFileSync(path.join(directory, 'Button.doc.mjs'), content);
  return content;
}

function reviewApplicabilityBlock(triggers, scope = 'global') {
  return `<!-- review-applicability:v1 -->\n\`\`\`json\n${JSON.stringify(
    {scope, triggers},
    null,
    2,
  )}\n\`\`\``;
}

function withReviewApplicability(record, triggers, scope = 'global') {
  const lines = record.split('\n');
  const titleIndex = lines.findIndex(line => line.startsWith('# '));
  lines.splice(
    titleIndex + 1,
    0,
    '',
    reviewApplicabilityBlock(triggers, scope),
  );
  return lines.join('\n');
}

function withSystemClaims(record) {
  return record.replace(
    '## Requirements\n\nBody.',
    '## Requirements\n\n- **FR1 — Public API stays stable.** Callers keep the same contract.\n\n- **FR2 — Evidence stays scoped.** Tests prove only this claim.',
  );
}

/**
 * Commits the fixture's working tree as it stands on `main`, after the
 * commit there, or as the first commit of a new repository.
 */
function commitFixture(root, message, {create = false} = {}) {
  const commit = {
    ref: 'refs/heads/main',
    name: 'commit',
    message,
    snapshot: true,
    files: workingTreeFiles(root),
  };
  return create
    ? createRepository(root, [commit]).commit
    : importCommits(root, [{...commit, parent: 'refs/heads/main'}]).commit;
}

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

describe('global review applicability', () => {
  const currentRecord = withSystemClaims(systemSpecRecord());

  it('parses explicit trigger-to-claim routing', () => {
    const record = withReviewApplicability(currentRecord, {
      'public-api': ['FR1'],
      testing: ['FR2'],
    });
    const parsed = parseReviewApplicabilityBlock(record);
    expect(parsed.problems).toEqual([]);
    expect(parsed.config).toEqual({
      scope: 'global',
      triggers: {'public-api': ['FR1'], testing: ['FR2']},
    });
    expect(extractKnowledgeClaims(record)).toEqual(
      new Map([
        ['FR1', 'Public API stays stable.'],
        ['FR2', 'Evidence stays scoped.'],
      ]),
    );
    expect(validateReviewApplicability(parsed.config, record)).toEqual([]);
  });

  it.each([
    [
      'global routing without claims',
      {scope: 'global', triggers: {'public-api': []}},
      /non-empty claim list/,
    ],
    [
      'a stale claim reference',
      {scope: 'global', triggers: {'public-api': ['FR99']}},
      /references missing claim "FR99"/,
    ],
    [
      'a duplicate trigger and claim pair',
      {scope: 'global', triggers: {'public-api': ['FR1', 'FR1']}},
      /repeats claim "FR1"/,
    ],
    [
      'a malformed trigger',
      {scope: 'global', triggers: {'Public API': ['FR1']}},
      /must use lower-kebab-case/,
    ],
    [
      'an unsupported trigger',
      {scope: 'global', triggers: {'unknown-area': ['FR1']}},
      /is not a supported semantic trigger/,
    ],
    [
      'an unsupported scope',
      {scope: 'component', triggers: {'public-api': ['FR1']}},
      /scope must be "global"/,
    ],
  ])('rejects %s', (_name, config, expected) => {
    expect(
      validateReviewApplicability(config, currentRecord).join('\n'),
    ).toMatch(expected);
  });

  it('rejects duplicate JSON object keys before parsing can overwrite them', () => {
    const record = currentRecord.replace(
      '# Fixture system spec',
      '# Fixture system spec\n\n<!-- review-applicability:v1 -->\n```json\n{"scope":"global","triggers":{"public-api":["FR1"],"public-api":["FR2"]}}\n```',
    );
    expect(parseReviewApplicabilityBlock(record).problems.join('\n')).toMatch(
      /repeats JSON field "public-api"/,
    );
  });

  it('keeps the same key in two different objects', () => {
    const record = currentRecord.replace(
      '# Fixture system spec',
      '# Fixture system spec\n\n<!-- review-applicability:v1 -->\n```json\n{"scope":"global","concerns":{"a":{"names":["x"],"claims":["FR1"]},"b":{"names":["y"],"claims":["FR2"]}}}\n```',
    );
    const parsed = parseReviewApplicabilityBlock(record);
    expect(parsed.problems).toEqual([]);
    expect(validateReviewApplicability(parsed.config, record)).toEqual([]);
  });

  it('accepts a concerns map with or without triggers', () => {
    const concerns = {
      'slot-presence': {
        names: ['isRenderable'],
        patterns: ["typeof [\\w.]+ !== 'boolean'"],
        claims: ['FR1'],
      },
    };
    expect(
      validateReviewApplicability({scope: 'global', concerns}, currentRecord),
    ).toEqual([]);
    expect(
      validateReviewApplicability(
        {scope: 'global', triggers: {'public-api': ['FR2']}, concerns},
        currentRecord,
      ),
    ).toEqual([]);
  });

  it.each([
    [
      'neither triggers nor concerns',
      {scope: 'global'},
      /triggers, concerns, or both/,
    ],
    [
      'an unknown block key',
      {
        scope: 'global',
        concerns: {a: {names: ['x'], claims: ['FR1']}},
        extra: 1,
      },
      /and nothing else/,
    ],
    [
      'an empty concerns map',
      {scope: 'global', concerns: {}},
      /at least one concern/,
    ],
    [
      'a concern without names or patterns',
      {scope: 'global', concerns: {a: {claims: ['FR1']}}},
      /at least one name or pattern/,
    ],
    [
      'a concern name that is not an identifier',
      {
        scope: 'global',
        concerns: {a: {names: ['is renderable'], claims: ['FR1']}},
      },
      /not an identifier/,
    ],
    [
      'an invalid pattern',
      {scope: 'global', concerns: {a: {patterns: ['('], claims: ['FR1']}}},
      /invalid pattern/,
    ],
    [
      'a concern claim the record lacks',
      {scope: 'global', concerns: {a: {names: ['x'], claims: ['FR99']}}},
      /references missing claim "FR99"/,
    ],
    [
      'an unknown concern key',
      {
        scope: 'global',
        concerns: {a: {names: ['x'], claims: ['FR1'], owner: 'y'}},
      },
      /claims with names, patterns, or both/,
    ],
  ])('rejects concerns with %s', (_name, config, expected) => {
    expect(
      validateReviewApplicability(config, currentRecord).join('\n'),
    ).toMatch(expected);
  });

  it('routes each claim whose concern matches an added line, with the evidence', () => {
    const record = {
      path: 'docs/specs/AST-900/spec.md',
      content: currentRecord.replace(
        '# Fixture system spec',
        `# Fixture system spec\n\n<!-- review-applicability:v1 -->\n\n\`\`\`json\n${JSON.stringify(
          {
            scope: 'global',
            concerns: {
              'slot-presence': {
                names: ['isRenderable'],
                patterns: ["typeof [\\w.]+ !== 'boolean'"],
                claims: ['FR1'],
              },
              'unrelated-concern': {names: ['useScrollLock'], claims: ['FR2']},
            },
          },
        )}\n\`\`\`\n`,
      ),
    };
    const added = [
      {
        file: 'packages/core/src/Badge/Badge.tsx',
        line: 3,
        text: 'const x = 1;',
      },
      {
        file: 'packages/core/src/Badge/Badge.tsx',
        line: 4,
        text: "  const hasLabel = label !== '' && label != null && typeof label !== 'boolean';",
      },
      {
        file: 'packages/core/src/Badge/Badge.tsx',
        line: 5,
        text: 'isRenderableish(x);',
      },
    ];
    const matches = collectConcernMatches([record], added, null);
    expect(matches).toEqual([
      expect.objectContaining({
        recordId: 'spec:AST-900',
        concern: 'slot-presence',
        claimId: 'FR1',
        claim: 'Public API stays stable.',
        utilities: ['isRenderable'],
        evidence: [
          expect.objectContaining({
            line: 4,
            matched: "typeof label !== 'boolean'",
          }),
        ],
      }),
    ]);
    expect(matches[0].matchReason).toContain('(shared: isRenderable)');
    expect(collectConcernMatches([record], [], null)).toEqual([]);
  });

  it('keeps the canonical claim title when a verification table repeats its id', () => {
    const record = `${currentRecord}\n| Contract | Verification |\n| --- | --- |\n| FR1 | A test file, not the claim. |\n`;
    expect(extractKnowledgeClaims(record).get('FR1')).toBe(
      'Public API stays stable.',
    );
  });

  it('does not treat a verification-table reference as a claim definition', () => {
    const record = withReviewApplicability(
      `${currentRecord.replace(
        '- **FR1 — Public API stays stable.** Callers keep the same contract.\n\n',
        '',
      )}\n| Contract | Verification |\n| --- | --- |\n| FR1 | A test file, not the claim. |\n`,
      {'public-api': ['FR1']},
    );
    const parsed = parseReviewApplicabilityBlock(record);
    expect(
      validateReviewApplicability(parsed.config, record).join('\n'),
    ).toMatch(/references missing claim "FR1"/);
  });

  it('keeps legacy records with no applicability block valid', async () => {
    const root = fixtureRoot();
    writeSystemSpec(root, 'AST-900', currentRecord);
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('fails knowledge validation for malformed global routing', async () => {
    const root = fixtureRoot();
    writeSystemSpec(
      root,
      'AST-900',
      withReviewApplicability(currentRecord, {'public-api': ['FR99']}),
    );
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /references missing claim "FR99"/,
    );
  });

  it('routes only matching claims from current records', () => {
    const record = withReviewApplicability(currentRecord, {
      'public-api': ['FR1'],
      testing: ['FR2'],
    });
    const matches = collectGlobalReviewMatches(
      [{path: 'docs/specs/AST-900/spec.md', content: record}],
      ['public-api'],
      'a'.repeat(40),
    );
    expect(matches).toHaveLength(1);
    expect(matches[0]).toMatchObject({
      recordId: 'spec:AST-900',
      path: 'docs/specs/AST-900/spec.md',
      trigger: 'public-api',
      claimId: 'FR1',
      claim: 'Public API stays stable.',
      authorityCommit: 'a'.repeat(40),
    });
    expect(matches[0].matchReason).toContain('public-api');
    expect(matches[0].matchReason).toContain('spec:AST-900/FR1');
    expect(matches[0].recordDigest).toMatch(/^[0-9a-f]{64}$/);
  });

  it('omits nonmatching and draft records', () => {
    const current = withReviewApplicability(currentRecord, {
      'public-api': ['FR1'],
    });
    const draft = withReviewApplicability(
      currentRecord.replace('authority: current', 'authority: draft'),
      {testing: ['FR2']},
    );
    expect(
      collectGlobalReviewMatches(
        [
          {path: 'docs/specs/AST-900/spec.md', content: current},
          {path: 'docs/specs/AST-901/spec.md', content: draft},
        ],
        ['testing'],
        'b'.repeat(40),
      ),
    ).toEqual([]);
  });

  it('pins routing to the reviewed head base and rejects self-authorization', () => {
    const root = fixtureRoot();
    writeSystemSpec(root, 'AST-900', currentRecord);
    const baseWithoutRouting = commitFixture(
      root,
      'base without global routing',
      {create: true},
    );
    execFileSync(
      'git',
      ['update-ref', 'refs/remotes/origin/main', baseWithoutRouting],
      {cwd: root},
    );

    fs.writeFileSync(
      path.join(root, 'docs/specs/AST-900/spec.md'),
      withReviewApplicability(currentRecord, {'public-api': ['FR1']}),
    );
    const proposedHead = commitFixture(root, 'head adds global routing');

    expect(
      routeGlobalReviewBaselinesAtRevision(
        root,
        baseWithoutRouting,
        proposedHead,
        ['public-api'],
      ),
    ).toEqual([]);
    expect(() =>
      routeGlobalReviewBaselinesAtRevision(root, proposedHead, proposedHead, [
        'public-api',
      ]),
    ).toThrow(/review head must differ/);

    execFileSync(
      'git',
      ['update-ref', 'refs/remotes/origin/main', proposedHead],
      {
        cwd: root,
      },
    );
    expect(() =>
      routeGlobalReviewBaselinesAtRevision(root, proposedHead, proposedHead, [
        'public-api',
      ]),
    ).toThrow(/review head must differ/);

    fs.writeFileSync(path.join(root, 'README.md'), '# Reviewed change\n');
    const laterHead = commitFixture(root, 'later review head');
    expect(
      routeGlobalReviewBaselinesAtRevision(root, proposedHead, laterHead, [
        'public-api',
      ]),
    ).toHaveLength(1);
    expect(() =>
      routeGlobalReviewBaselinesAtRevision(
        root,
        baseWithoutRouting,
        laterHead,
        ['public-api'],
      ),
    ).toThrow(/origin\/main merge base/);
  });

  it('sorts multiple matches deterministically', () => {
    const first = withReviewApplicability(
      withSystemClaims(systemSpecRecord({id: 'spec:AST-902'})),
      {testing: ['FR2'], 'public-api': ['FR1']},
    );
    const second = withReviewApplicability(
      withSystemClaims(systemSpecRecord({id: 'spec:AST-901'})),
      {'public-api': ['FR1']},
    );
    const matches = collectGlobalReviewMatches(
      [
        {path: 'docs/specs/AST-902/spec.md', content: first},
        {path: 'docs/specs/AST-901/spec.md', content: second},
      ],
      ['testing', 'public-api'],
      'c'.repeat(40),
    );
    expect(
      matches.map(row => `${row.recordId}:${row.trigger}:${row.claimId}`),
    ).toEqual([
      'spec:AST-901:public-api:FR1',
      'spec:AST-902:public-api:FR1',
      'spec:AST-902:testing:FR2',
    ]);
  });
});

describe('schema evolution', () => {
  it('tracks latest schema versions per kind', () => {
    const raw = new Map([
      [
        1,
        {
          schema: {schemaVersion: 1, kinds: {component: {marker: 'v1'}}},
          schemaPath: 'v1.json',
        },
      ],
      [
        2,
        {
          schema: {
            schemaVersion: 2,
            extends: 1,
            kinds: {theme: {marker: 'v2'}},
          },
          schemaPath: 'v2.json',
        },
      ],
      [
        3,
        {
          schema: {
            schemaVersion: 3,
            extends: 2,
            kinds: {component: {marker: 'v3'}},
          },
          schemaPath: 'v3.json',
        },
      ],
    ]);
    const {schemas, latestKindVersions} = composeKnowledgeSchemas(raw);
    expect(schemas.get(2).schema.kinds.component.marker).toBe('v1');
    expect(schemas.get(2).schema.kinds.theme.marker).toBe('v2');
    expect(latestKindVersions.get('theme')).toBe(2);
    expect(latestKindVersions.get('component')).toBe(3);
  });

  it('allows appending a higher schema version', () => {
    expect(
      validateSchemaEvolution(
        new Map([['docs/schemas/knowledge/v1.json', 'one']]),
        new Map([
          ['docs/schemas/knowledge/v1.json', 'one'],
          ['docs/schemas/knowledge/v2.json', 'two'],
        ]),
      ),
    ).toEqual([]);
  });

  it('rejects rewriting or deleting a published schema version', () => {
    expect(
      validateSchemaEvolution(
        new Map([
          ['docs/schemas/knowledge/v1.json', 'one'],
          ['docs/schemas/knowledge/v2.json', 'two'],
        ]),
        new Map([['docs/schemas/knowledge/v1.json', 'changed']]),
      ).join('\n'),
    ).toMatch(/immutable.*append-only/s);
  });
});

describe('approval line history', () => {
  function record({approvedBy = 'owner-a', decisions = []} = {}) {
    return {
      path: 'docs/architecture/example.md',
      content: [
        '---',
        'id: architecture:example',
        'authority: current',
        `approved_by: ${approvedBy}`,
        '---',
        '',
        '## Deciding specs',
        '',
        ...decisions.flatMap(([id, decider]) => [
          `### ${id} — A decision`,
          '',
          `**Decider:** ${decider}`,
          '',
          'The decision text.',
          '',
        ]),
      ].join('\n'),
    };
  }
  const base = record({
    decisions: [['DEC-1', '`owner-a`, `2026-11-01`']],
  });

  it('reports a rewritten Decider and approved_by with the original decider', () => {
    const head = record({
      approvedBy: 'owner-b',
      decisions: [['DEC-1', '`owner-b`, `2026-11-01`']],
    });
    expect(findApprovalLineRewrites([base], [head])).toEqual([
      {
        path: 'docs/architecture/example.md',
        claim: 'approved_by',
        from: 'owner-a',
        to: 'owner-b',
        decider: 'owner-a',
      },
      {
        path: 'docs/architecture/example.md',
        claim: 'DEC-1',
        from: '`owner-a`, `2026-11-01`',
        to: '`owner-b`, `2026-11-01`',
        decider: 'owner-a',
      },
    ]);
  });

  it('reports a removed decision', () => {
    expect(findApprovalLineRewrites([base], [record()])).toEqual([
      expect.objectContaining({claim: 'DEC-1', to: null, decider: 'owner-a'}),
    ]);
  });

  it('allows a new decision, an added approver, an amendment, and a filled placeholder', () => {
    const pendingBase = record({
      decisions: [
        ['DEC-1', '`owner-a`, `2026-11-01`'],
        ['DEC-2', '`owner-a`, `<pending>`'],
      ],
    });
    const head = record({
      approvedBy: '[owner-a, owner-b]',
      decisions: [
        ['DEC-2', '`owner-a`, `2026-11-08`'],
        ['DEC-1', '`owner-a`, `2026-11-01`; amended `2026-11-08`'],
        ['DEC-3', '`owner-b`, `2026-11-08`'],
      ],
    });
    expect(findApprovalLineRewrites([pendingBase], [head])).toEqual([]);
  });

  it('reads a placeholder only in the decider and date fields', () => {
    const decided =
      '`owner-a`, `2026-11-01`; pending-search Enter, a quiet send';
    const rewritten = findApprovalLineRewrites(
      [record({decisions: [['DEC-1', decided]]})],
      [
        record({
          decisions: [
            [
              'DEC-1',
              '`owner-b`, `2026-11-01`; pending-search Enter, a quiet send',
            ],
          ],
        }),
      ],
    );
    expect(rewritten).toEqual([
      expect.objectContaining({
        claim: 'DEC-1',
        from: decided,
        decider: 'owner-a',
      }),
    ]);
    // A placeholder date, with or without a note, is still a placeholder.
    for (const placeholder of [
      '`owner-a`, `<pending>`',
      '`owner-a`, pending (awaiting the owner)',
      'proposed by `owner-a`, `2026-09-27`; pending owner review',
    ]) {
      expect(
        findApprovalLineRewrites(
          [record({decisions: [['DEC-1', placeholder]]})],
          [record({decisions: [['DEC-1', '`owner-a`, `2026-11-08`']]})],
        ),
        placeholder,
      ).toEqual([]);
    }
  });

  it('reads every decided-line shape the records use', () => {
    const doc = lines => ({
      path: 'docs/specs/AST-900/spec.md',
      content: [
        '---',
        'id: spec:AST-900',
        'authority: current',
        'approved_by: owner-a',
        '---',
        '',
        ...lines,
      ].join('\n'),
    });
    const shapes = [
      // Reference and Decider on one line.
      [
        '### DEC-1 — One line',
        '',
        '**Reference:** `spec:AST-900/DEC-1` · **Decider:** `owner-a`, `2026-08-31`',
      ],
      // Several deciders.
      [
        '### DEC-2 — Two owners',
        '',
        '**Deciders:** `owner-a`, `owner-c`, `2026-09-03`',
      ],
      // A list-item decision with an indented Decider line.
      [
        '- **DEC-3 — A list item.**',
        '',
        '  **Decider:** `owner-a`, 2026-10-24',
      ],
      // An amendment heading.
      [
        '### Amendment — Narrow the name',
        '',
        '**Decider:** `owner-a`, `2026-09-12`',
      ],
      // A direction owner names who decided.
      [
        '### DEC-4 — Owner label',
        '',
        '**Direction owner:** `owner-a`, `2026-10-02`',
      ],
    ];
    const expected = [
      {claim: 'DEC-1', decider: 'owner-a'},
      {claim: 'DEC-2', decider: 'owner-a, owner-c'},
      {claim: 'DEC-3', decider: 'owner-a'},
      {claim: 'Amendment — Narrow the name', decider: 'owner-a'},
      {claim: 'DEC-4', decider: 'owner-a'},
    ];
    shapes.forEach((shape, i) => {
      const rewritten = shape.map(line => line.replace('owner-a', 'owner-b'));
      expect(
        findApprovalLineRewrites([doc(shape)], [doc(rewritten)]),
        shape[0],
      ).toEqual([expect.objectContaining(expected[i])]);
      expect(
        findApprovalLineRewrites([doc(shape)], [doc(['## Notes'])]),
        `${shape[0]} removed`,
      ).toEqual([expect.objectContaining({...expected[i], to: null})]);
      expect(findApprovalLineRewrites([doc(shape)], [doc(shape)])).toEqual([]);
    });
  });

  it('reads each labelled decider of a decision, and no proposed one', () => {
    const doc = lines => ({
      path: 'packages/themes/example/example.spec.md',
      content: [
        '---',
        'id: theme:example',
        'authority: current',
        'approved_by: owner-a',
        '---',
        '',
        '### DEC-1 — Two deciders',
        '',
        ...lines,
      ].join('\n'),
    });
    const base = [
      '**System-boundary decider:** `owner-a`, `2026-08-31`',
      '**Final adoption decider:** `owner-c`, `2026-10-17`',
      '**Proposed decider:** `owner-d`',
    ];
    const adoption = base.map(line => line.replace('owner-c', 'owner-b'));
    expect(findApprovalLineRewrites([doc(base)], [doc(adoption)])).toEqual([
      expect.objectContaining({
        claim: 'DEC-1 (Final adoption decider)',
        decider: 'owner-c',
      }),
    ]);
    const boundary = base.map(line => line.replace('owner-a', 'owner-b'));
    expect(findApprovalLineRewrites([doc(base)], [doc(boundary)])).toEqual([
      expect.objectContaining({
        claim: 'DEC-1 (System-boundary decider)',
        decider: 'owner-a',
      }),
    ]);
    const proposal = base.map(line => line.replace('owner-d', 'owner-e'));
    expect(findApprovalLineRewrites([doc(base)], [doc(proposal)])).toEqual([]);
  });

  it('warns for a platform component record too', () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'approval-lines-'));
    try {
      const file = 'docs/specs/components/TextInput/TextInput.swift.spec.md';
      const git = (...args) =>
        execFileSync('git', ['-C', dir, ...args], {
          encoding: 'utf8',
          env: {
            ...process.env,
            GIT_AUTHOR_NAME: 't',
            GIT_AUTHOR_EMAIL: '[email protected]',
            GIT_COMMITTER_NAME: 't',
            GIT_COMMITTER_EMAIL: '[email protected]',
          },
        });
      const write = approvedBy => {
        fs.mkdirSync(path.join(dir, path.dirname(file)), {recursive: true});
        fs.writeFileSync(
          path.join(dir, file),
          [
            '---',
            'id: component:TextInput/swift',
            'authority: current',
            `approved_by: ${approvedBy}`,
            '---',
            '',
            '# TextInput (Swift)',
            '',
          ].join('\n'),
        );
      };
      git('init', '-q');
      write('owner-a');
      git('add', '-A');
      git('commit', '-q', '-m', 'base');
      const base = git('rev-parse', 'HEAD').trim();
      write('owner-b');
      expect(approvalLineRewritesSince(dir, base, [file])).toEqual([
        {
          path: file,
          claim: 'approved_by',
          from: 'owner-a',
          to: 'owner-b',
          decider: 'owner-a',
        },
      ]);
    } finally {
      fs.rmSync(dir, {recursive: true, force: true});
    }
  });
});

describe('component-local design decisions', () => {
  const row =
    '| DD1 | Keep the label visually quiet. | Preserve primary-action emphasis. | Default label | Theme token substitutions may preserve contrast. |';
  const block = `${[
    '### Design decisions',
    '',
    '<!-- design-decisions:v1 -->',
    '',
    '| ID | Decision | Intent or reason | Applies to | Allowed variation |',
    '| --- | --- | --- | --- | --- |',
    row,
  ].join('\n')}\n`;

  it('parses a valid optional table under Design relationships', () => {
    const parsed = parseDesignDecisionsBlock(
      `## Design relationships\n\nBody.\n\n${block}\n### Theming anatomy\n`,
    );
    expect(parsed.rows).toHaveLength(1);
    expect(parsed.rows[0].id).toBe('DD1');
    expect(validateDesignDecisionsBlock(parsed)).toEqual([]);
  });

  it('keeps absence valid and permits header-only template guidance', () => {
    expect(
      validateDesignDecisionsBlock(
        parseDesignDecisionsBlock('## Design relationships\n\nBody.\n'),
      ),
    ).toEqual([]);
    const headerOnly = parseDesignDecisionsBlock(
      `## Design relationships\n\n${block.replace(`\n${row}`, '')}`,
    );
    expect(
      validateDesignDecisionsBlock(headerOnly, {allowHeaderOnly: true}),
    ).toEqual([]);
  });

  it('keeps the optional header-only table in component and module templates', () => {
    for (const template of ['component-spec.md', 'module-spec.md']) {
      const parsed = parseDesignDecisionsBlock(
        fs.readFileSync(
          path.join(repoRoot, 'docs/templates/knowledge', template),
          'utf8',
        ),
        template,
      );
      expect(parsed.present, template).toBe(true);
      expect(parsed.rows, template).toEqual([]);
      expect(
        validateDesignDecisionsBlock(parsed, {allowHeaderOnly: true}),
        template,
      ).toEqual([]);
    }
  });

  it('rejects malformed, empty, and duplicate authored rows', () => {
    const malformed = block
      .replace('Intent or reason', 'Rationale')
      .replace(row, `${row}\n${row.replace('DD1', 'bad')}`);
    const parsed = parseDesignDecisionsBlock(
      `## Design relationships\n\n${malformed}`,
      'Button.spec.md',
    );
    expect(validateDesignDecisionsBlock(parsed).join('\n')).toMatch(
      /columns must be exactly.*must match DD1/s,
    );
  });
});

describe('component theming anatomy metadata', () => {
  const contract = {
    anatomy: ['Root', 'Label', 'Icon', 'Content'],
    targets: ['button'],
  };
  const valid = {
    Root: {target: 'button'},
    Label: {inherits: 'button'},
    Icon: {delegatesTo: {owner: 'component:Icon', target: 'icon'}},
    Content: {
      none: {reason: 'intentional: The consumer owns this content.'},
    },
  };

  it('parses the optional versioned JSON block under Design relationships', () => {
    expect(
      parseAnatomyThemingBlock(
        `## Design relationships\n\n${anatomyThemingBlock(valid)}`,
      ).mapping,
    ).toEqual(valid);
    expect(parseAnatomyThemingBlock('## Design relationships\n').mapping).toBe(
      null,
    );
  });

  it('rejects the structured block outside its existing level-two section', () => {
    expect(
      parseAnatomyThemingBlock(
        `## Public concepts\n\n${anatomyThemingBlock(valid)}`,
      ).problems.join('\n'),
    ).toMatch(/subsection of "Design relationships"/);
  });

  it('accepts exactly one complete disposition per documented anatomy part', () => {
    expect(validateAnatomyThemingMap(valid, contract)).toEqual([]);
  });

  it('accepts every classified none reason', () => {
    for (const classification of [
      'intentional',
      'reachability-gap',
      'unsettled',
    ]) {
      expect(
        validateAnatomyThemingMap(
          {
            ...valid,
            Content: {
              none: {reason: `${classification}: Current factual state.`},
            },
          },
          contract,
        ),
      ).toEqual([]);
    }
  });

  it.each([
    [
      'multiple dispositions',
      {...valid, Root: {target: 'button', inherits: 'button'}},
      /exactly one/,
    ],
    [
      'missing delegated owner',
      {...valid, Icon: {delegatesTo: {target: 'icon'}}},
      /requires exactly owner and target/,
    ],
    [
      'missing delegated target',
      {...valid, Icon: {delegatesTo: {owner: 'component:Icon'}}},
      /requires exactly owner and target/,
    ],
    [
      'missing none reason',
      {...valid, Content: {none: {}}},
      /requires a non-empty reason/,
    ],
    [
      'unclassified none reason',
      {...valid, Content: {none: {reason: 'The consumer owns this content.'}}},
      /must start with intentional:, reachability-gap:, or unsettled:/,
    ],
    [
      'prefixed target',
      {...valid, Root: {target: 'astryx-button'}},
      /omit the "astryx-" prefix/,
    ],
    [
      'non-kebab target',
      {...valid, Root: {target: 'Button_Root'}},
      /use kebab-case/,
    ],
  ])('rejects %s', (_name, mapping, expected) => {
    expect(validateAnatomyThemingMap(mapping, contract).join('\n')).toMatch(
      expected,
    );
  });

  it('requires exact anatomy names and coverage of current local targets', () => {
    const result = validateAnatomyThemingMap(
      {
        Label: {inherits: 'button'},
        Icon: {delegatesTo: {owner: 'component:Icon', target: 'icon'}},
        Content: {none: {reason: 'intentional: Consumer owned.'}},
        Unknown: {none: {reason: 'unsettled: Not real.'}},
      },
      contract,
    ).join('\n');
    expect(result).toMatch(/missing Root/);
    expect(result).toMatch(/unknown Unknown/);
    expect(result).toMatch(/current target "button" has no anatomy entry/);
  });

  it('validates an opted-in spec without changing consumer doc bytes', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    const consumerDoc = writeButtonDoc(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      withAnatomyTheming(componentRecord(), {
        ...valid,
        Icon: {none: {reason: 'intentional: Fixture-owned icon.'}},
      }),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
    expect(
      fs.readFileSync(path.join(directory, 'Button.doc.mjs'), 'utf8'),
    ).toBe(consumerDoc);
  });

  it('keeps the block optional while existing specs migrate', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord(),
    );
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });
});

describe('component delegation ownership', () => {
  const canonicalTargets = [
    {component: 'Button', key: 'button'},
    {component: 'Icon', key: 'icon'},
    {component: 'Indicator', key: 'radio'},
    {component: 'RadioList', key: 'radio'},
    {component: 'Table', key: 'table-header'},
  ];
  const valid = {
    filePath: 'packages/core/src/Example/Example.spec.md',
    anatomy: 'Icon',
    owner: 'component:Icon',
    target: 'icon',
  };

  it('rejects an unknown owner with the complete delegation location', () => {
    const problems = validateDelegations(
      [{...valid, owner: 'component:Missing'}],
      canonicalTargets,
    ).join('\n');
    expect(problems).toContain(valid.filePath);
    expect(problems).toContain('theming anatomy "Icon".delegatesTo');
    expect(problems).toContain('owner "component:Missing"');
    expect(problems).toContain('target "icon"');
  });

  it('rejects a missing active target under an existing owner', () => {
    const problems = validateDelegations(
      [{...valid, target: 'glyph'}],
      canonicalTargets,
    ).join('\n');
    expect(problems).toContain('target "glyph"');
    expect(problems).toContain('owned by "component:Icon"');
    expect(problems).toContain('active targets for that owner: "icon"');
  });

  it('accepts a parent-owned member target only under its canonical owner', () => {
    expect(
      validateDelegations(
        [
          {
            ...valid,
            anatomy: 'Header',
            owner: 'component:Table',
            target: 'table-header',
          },
        ],
        canonicalTargets,
      ),
    ).toEqual([]);
    const problems = validateDelegations(
      [
        {
          ...valid,
          anatomy: 'Header',
          owner: 'component:TableHeader',
          target: 'table-header',
        },
      ],
      canonicalTargets,
    ).join('\n');
    expect(problems).toContain('"component:TableHeader"');
    expect(problems).toContain('target "table-header"');
    expect(problems).toContain(
      'canonical owner for target "table-header": "component:Table"',
    );
  });

  it('does not accept a target merely because unrelated owners share its name', () => {
    expect(
      validateDelegations(
        [
          {...valid, owner: 'component:Indicator', target: 'radio'},
          {...valid, owner: 'component:RadioList', target: 'radio'},
        ],
        canonicalTargets,
      ),
    ).toEqual([]);
    expect(
      validateDelegations(
        [{...valid, owner: 'component:Button', target: 'radio'}],
        canonicalTargets,
      ).join('\n'),
    ).toMatch(
      /radio.*component:Button.*button.*component:Indicator.*component:RadioList/,
    );
  });

  it('accepts a target owned by a member of an active family', () => {
    const families = new Map([
      [
        'family:actions',
        {
          filePath: 'docs/families/actions.md',
          members: ['component:Button', 'component:Icon'],
        },
      ],
    ]);
    expect(
      validateDelegations(
        [{...valid, owner: 'family:actions'}],
        canonicalTargets,
        families,
      ),
    ).toEqual([]);
  });

  it('rejects an unknown or inactive family owner', () => {
    const problems = validateDelegations(
      [{...valid, owner: 'family:missing'}],
      canonicalTargets,
      new Map(),
    ).join('\n');
    expect(problems).toContain('owner "family:missing"');
    expect(problems).toContain('active family record');
    expect(problems).toContain('target "icon"');
  });

  it('rejects a family target that none of its members owns', () => {
    const families = new Map([
      [
        'family:actions',
        {
          filePath: 'docs/families/actions.md',
          members: ['component:Button'],
        },
      ],
    ]);
    const problems = validateDelegations(
      [{...valid, owner: 'family:actions'}],
      canonicalTargets,
      families,
    ).join('\n');
    expect(problems).toContain('target "icon"');
    expect(problems).toContain('family:actions');
    expect(problems).toContain('docs/families/actions.md');
    expect(problems).toContain(
      'canonical owner for target "icon": "component:Icon"',
    );
  });

  it('matches shared target names only to members of the named family', () => {
    const families = new Map([
      [
        'family:selection',
        {
          filePath: 'docs/families/selection.md',
          members: ['component:Indicator'],
        },
      ],
      [
        'family:actions',
        {
          filePath: 'docs/families/actions.md',
          members: ['component:Button'],
        },
      ],
    ]);
    expect(
      validateDelegations(
        [{...valid, owner: 'family:selection', target: 'radio'}],
        canonicalTargets,
        families,
      ),
    ).toEqual([]);
    const problems = validateDelegations(
      [{...valid, owner: 'family:actions', target: 'radio'}],
      canonicalTargets,
      families,
    ).join('\n');
    expect(problems).toContain('family:actions');
    expect(problems).toContain('"component:Indicator", "component:RadioList"');
  });

  it.each([
    ['draft', {}],
    [
      'current',
      {
        authority: 'current',
        approved_by: 'cixzhang',
        approved_at: '2026-08-30',
      },
    ],
  ])(
    'rejects an invalid delegation from an active %s record end to end',
    async (authority, overrides) => {
      const root = fixtureRoot();
      const directory = path.join(root, 'packages/core/src/Button');
      fs.mkdirSync(directory);
      writeButtonDoc(directory);
      fs.writeFileSync(
        recordPath(path.join(directory, 'Button.spec.md')),
        withAnatomyTheming(componentRecord(overrides), {
          Root: {target: 'button'},
          Label: {inherits: 'button'},
          Icon: {
            delegatesTo: {
              owner:
                authority === 'draft' ? 'component:Missing' : 'family:missing',
              target: 'icon',
            },
          },
          Content: {
            none: {reason: 'intentional: Consumer-owned content.'},
          },
        }),
      );

      const problems = (await validateKnowledgeRoot(root)).join('\n');
      expect(problems).toContain('theming anatomy "Icon".delegatesTo');
      expect(problems).toContain(
        authority === 'draft' ? 'component:Missing' : 'family:missing',
      );
    },
  );

  it('does not validate delegations from archived records', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    writeButtonDoc(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      withAnatomyTheming(
        componentRecord({
          authority: 'archived',
          archive_reason: 'historical',
        }),
        {
          Root: {target: 'button'},
          Label: {inherits: 'button'},
          Icon: {
            delegatesTo: {owner: 'family:missing', target: 'icon'},
          },
          Content: {
            none: {reason: 'intentional: Consumer-owned content.'},
          },
        },
      ),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('accepts every authored delegation in the existing records', async () => {
    expect(await validateKnowledgeRoot(repoRoot)).toEqual([]);
  }, 60_000);
});

describe('knowledge validation', () => {
  it('parses only top-level frontmatter and level-two sections', () => {
    const document = parseKnowledgeDocument(
      '---\nschema_version: 1\nowners:\n  [\n    one,\n    two,\n  ]\n---\n\n## Intent\n',
    );
    expect(document.frontmatter.get('schema_version')).toBe(1);
    expect(document.frontmatter.get('owners')).toEqual(['one', 'two']);
    expect(document.sections).toEqual(['Intent']);
  });

  it('accepts aligned templates with no records', async () => {
    expect(await validateKnowledgeRoot(fixtureRoot())).toEqual([]);
  });

  it('uses the reader-first projection only in architecture, component, and module templates', () => {
    const readerFirstTemplates = new Map([
      [
        'architecture.md',
        [
          'Governing contract',
          'System behavior',
          'End-user impact',
          'Builder impact',
          'Compatibility/readiness',
          'Review checks',
          'Governing rules',
        ],
      ],
      [
        'component-spec.md',
        [
          'Public contract',
          'Behavior',
          'End-user impact',
          'Builder impact',
          'Compatibility/readiness',
          'Review checks',
          'Governing rules',
        ],
      ],
      [
        'module-spec.md',
        [
          'Public contract',
          'Behavior',
          'End-user impact',
          'Builder impact',
          'Compatibility/readiness',
          'Review checks',
          'Governing rules',
        ],
      ],
    ]);

    for (const [fileName, projectionRows] of readerFirstTemplates) {
      const content = fs.readFileSync(
        path.join(repoRoot, 'docs/templates/knowledge', fileName),
        'utf8',
      );
      expect(parseKnowledgeDocument(content).sections[0]).toBe(
        'Contract at a glance',
      );
      for (const row of projectionRows) {
        expect(
          content
            .split('\n')
            .some(line => line.trimStart().startsWith(`| ${row} `)),
        ).toBe(true);
      }
      expect(content).toContain(
        'This table is a review projection; the body below is authoritative.',
      );
    }

    for (const fileName of [
      'design-spec.md',
      'family-contract.md',
      'implementation-plan.md',
      'system-spec.md',
      'theme-spec.md',
    ]) {
      const content = fs.readFileSync(
        path.join(repoRoot, 'docs/templates/knowledge', fileName),
        'utf8',
      );
      expect(parseKnowledgeDocument(content).sections).not.toContain(
        'Contract at a glance',
      );
    }
  });

  it('accepts an optional reader-first projection in an older record', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord().replace(
        '## Intent',
        '## Contract at a glance\n\nProjection.\n\n## Intent',
      ),
    );
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('rejects a structural template change without a schema update', async () => {
    const root = fixtureRoot();
    const template = path.join(
      root,
      'docs/templates/knowledge/component-spec.md',
    );
    fs.appendFileSync(template, '\n## Undeclared section\n');
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /template section order must exactly match the schema plus its allowed editorial sections/,
    );
  });

  it('rejects a schema whose filename and declared version disagree', async () => {
    const root = fixtureRoot();
    const schemaPath = path.join(root, 'docs/schemas/knowledge/v1.json');
    const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
    schema.schemaVersion = 2;
    fs.writeFileSync(schemaPath, `${JSON.stringify(schema)}\n`);
    await expect(validateKnowledgeRoot(root)).rejects.toThrow(
      /declares schemaVersion 2/,
    );
  });

  it('accepts a draft component record on the current schema', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord(),
    );
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('accepts a draft component record in a flat component package', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/vega/src');
    fs.writeFileSync(
      path.join(directory, 'index.ts'),
      "export {VegaChart} from './VegaChart';\n",
    );
    fs.writeFileSync(
      path.join(directory, 'VegaChart.tsx'),
      'export function VegaChart() {}\n',
    );
    fs.writeFileSync(
      recordPath(path.join(directory, 'VegaChart.spec.md')),
      componentRecord({id: 'component:VegaChart'}),
    );
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('rejects a flat-package spec with no matching public component', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/charts/src');
    fs.writeFileSync(
      path.join(directory, 'index.ts'),
      "export {Chart} from './Chart';\n",
    );
    fs.writeFileSync(
      path.join(directory, 'Chart.tsx'),
      'export function Chart() {}\n',
    );
    // Ghost.tsx exists but the package barrel does not export it.
    fs.writeFileSync(
      path.join(directory, 'Ghost.tsx'),
      'export function Ghost() {}\n',
    );
    fs.writeFileSync(
      recordPath(path.join(directory, 'Ghost.spec.md')),
      componentRecord({id: 'component:Ghost'}),
    );
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /must match a public named export and TSX module/,
    );
  });

  it('accepts a flat-package module beneath its declared parent component', async () => {
    const root = fixtureRoot();
    const source = path.join(root, 'packages/charts/src');
    const modulePath = recordPath(
      path.join(source, 'Chart/plugins/useChartThing.spec.md'),
    );
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    fs.writeFileSync(
      path.join(source, 'index.ts'),
      "export {Chart} from './Chart';\n",
    );
    fs.writeFileSync(
      path.join(source, 'Chart.tsx'),
      'export function Chart() {}\n',
    );
    fs.writeFileSync(
      recordPath(path.join(source, 'Chart.spec.md')),
      componentRecord({
        id: 'component:Chart',
        modules: '[module:Chart/useChartThing]',
      }),
    );
    fs.writeFileSync(
      modulePath,
      moduleRecord({
        id: 'module:Chart/useChartThing',
        parent_component: 'component:Chart',
      }),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('rejects a flat-package module beneath a different path root', async () => {
    const root = fixtureRoot();
    const source = path.join(root, 'packages/charts/src');
    const modulePath = recordPath(
      path.join(source, 'Ghost/plugins/useChartThing.spec.md'),
    );
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    fs.writeFileSync(
      path.join(source, 'index.ts'),
      "export {Chart} from './Chart';\n",
    );
    fs.writeFileSync(
      path.join(source, 'Chart.tsx'),
      'export function Chart() {}\n',
    );
    fs.writeFileSync(
      recordPath(path.join(source, 'Chart.spec.md')),
      componentRecord({
        id: 'component:Chart',
        modules: '[module:Chart/useChartThing]',
      }),
    );
    fs.writeFileSync(
      modulePath,
      moduleRecord({
        id: 'module:Chart/useChartThing',
        parent_component: 'component:Chart',
      }),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /flat-package module module:Chart\/useChartThing must live under docs\/specs\/components\/Chart\//,
    );
  });

  it('accepts a flat public member record backed by the root consumer doc', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/NavMenu');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      path.join(directory, 'NavMenu.doc.mjs'),
      "export const docs = {name: 'NavHeadingMenu'};\n",
    );
    fs.writeFileSync(
      recordPath(path.join(directory, 'NavHeadingMenu.spec.md')),
      componentRecord({id: 'component:NavHeadingMenu'}),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('accepts a flat public member record backed by a full inline consumer entry', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Table');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      path.join(directory, 'Table.doc.mjs'),
      `export const docs = {
  name: 'Table',
  components: [{name: 'TableRow', description: 'A public row.', props: []}],
};\n`,
    );
    fs.writeFileSync(
      recordPath(path.join(directory, 'TableRow.spec.md')),
      componentRecord({id: 'component:TableRow'}),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('rejects a flat component record unrelated to its component root', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    const parentDoc = writeButtonDoc(directory).replace(
      '  usage: {',
      "  components: [{name: 'Wrong', projection: {anatomy: []}}],\n  usage: {",
    );
    fs.writeFileSync(path.join(directory, 'Button.doc.mjs'), parentDoc);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Wrong.spec.md')),
      componentRecord({id: 'component:Wrong'}),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /flat component record component:Wrong must match component root "Button" or an exact public component entry/,
    );
  });

  it('discovers a nested module beside its flat parent and ignores non-record trees', async () => {
    const root = fixtureRoot();
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    const modulePath = recordPath(
      path.join(componentDirectory, 'plugins/thing/useButtonThing.spec.md'),
    );
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord({modules: '[module:Button/useButtonThing]'}),
    );
    fs.writeFileSync(modulePath, moduleRecord());

    const ignored = [
      '__fixtures__/fixture.spec.md',
      '__generated__/generated.spec.md',
      '__tests__/test.spec.md',
      '.hidden/hidden.spec.md',
      '.hidden.spec.md',
      'fixtures/fixture.spec.md',
      'generated/generated.spec.md',
      'node_modules/dependency.spec.md',
      'plugins/thing/snapshot.generated.spec.md',
    ];
    for (const relative of ignored) {
      const ignoredPath = recordPath(path.join(componentDirectory, relative));
      fs.mkdirSync(path.dirname(ignoredPath), {recursive: true});
      fs.writeFileSync(ignoredPath, moduleRecord());
    }
    const topLevelIgnored = path.join(
      root,
      'docs/specs/components/__tests__/TopLevel.spec.md',
    );
    fs.mkdirSync(path.dirname(topLevelIgnored), {recursive: true});
    fs.writeFileSync(topLevelIgnored, moduleRecord());

    const discovered = discoverKnowledgeRecords(root).map(filePath =>
      path.relative(root, filePath).split(path.sep).join('/'),
    );
    expect(discovered).toContain('docs/specs/components/Button/Button.spec.md');
    expect(discovered).toContain(
      'docs/specs/components/Button/plugins/thing/useButtonThing.spec.md',
    );
    for (const relative of ignored) {
      expect(discovered).not.toContain(
        `docs/specs/components/Button/${relative}`,
      );
    }
    expect(discovered).not.toContain(
      'docs/specs/components/__tests__/TopLevel.spec.md',
    );
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('rejects a component spec left beside its code and names where it belongs', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(path.join(directory, 'Button.spec.md'), componentRecord());
    fs.writeFileSync(
      path.join(root, 'packages/charts/src/Chart.spec.md'),
      componentRecord({id: 'component:Chart'}),
    );
    const problems = (await validateKnowledgeRoot(root)).join('\n');
    expect(problems).toContain(
      'packages/core/src/Button/Button.spec.md: component records live under docs/specs/components/; move this record to docs/specs/components/Button/Button.spec.md.',
    );
    expect(problems).toContain(
      'packages/charts/src/Chart.spec.md: component records live under docs/specs/components/; move this record to docs/specs/components/Chart/Chart.spec.md.',
    );
  });

  it('rejects a Swift spec left beside its view and names its place beside the core record', async () => {
    const root = fixtureRoot();
    const view = path.join(
      root,
      'packages/native/apple/Sources/Astryx/Avatar/AvatarStatusDot.spec.md',
    );
    fs.mkdirSync(path.dirname(view), {recursive: true});
    fs.writeFileSync(view, '# Swift\n');
    expect((await validateKnowledgeRoot(root)).join('\n')).toContain(
      'packages/native/apple/Sources/Astryx/Avatar/AvatarStatusDot.spec.md: Swift component records live beside the core record; move this record to docs/specs/components/Avatar/AvatarStatusDot.swift.spec.md.',
    );
  });

  it('accepts a platform record beside the core record and rejects other stray files', async () => {
    const root = fixtureRoot();
    fs.mkdirSync(path.join(root, 'packages/core/src/Button'));
    fs.writeFileSync(
      recordPath(path.join(root, 'packages/core/src/Button/Button.spec.md')),
      componentRecord(),
    );
    const folder = path.join(root, 'docs/specs/components/Button');
    writeSwiftTest(root);
    fs.writeFileSync(
      path.join(folder, 'Button.swift.spec.md'),
      platformRecord(),
    );
    fs.writeFileSync(path.join(folder, 'Button.klingon.spec.md'), '# ?\n');
    fs.writeFileSync(
      path.join(root, 'docs/specs/components/Loose.spec.md'),
      '# ?\n',
    );
    const problems = await validateKnowledgeRoot(root);
    expect(problems.join('\n')).not.toContain('Button.swift.spec.md');
    expect(
      problems.filter(problem => problem.includes('must be <ComponentRoot>')),
    ).toHaveLength(2);
  });

  it('checks a platform record with the shared validator and against its core component', async () => {
    const root = fixtureRoot();
    fs.mkdirSync(path.join(root, 'packages/core/src/Button'));
    fs.writeFileSync(
      recordPath(path.join(root, 'packages/core/src/Button/Button.spec.md')),
      componentRecord(),
    );
    writeSwiftTest(root);
    const swift = path.join(
      root,
      'docs/specs/components/Button/Button.swift.spec.md',
    );
    const swiftProblems = async overrides => {
      fs.writeFileSync(swift, platformRecord(overrides));
      return (await validateKnowledgeRoot(root)).filter(problem =>
        problem.startsWith('docs/specs/components/Button/Button.swift.spec.md'),
      );
    };

    expect(await swiftProblems()).toEqual([]);
    expect(
      await swiftProblems({
        id: 'component:Button',
        platform_of: 'component:Card',
        owners: '[]',
        verified_by: '[packages/native/apple/Tests/Missing.swift]',
      }),
    ).toEqual([
      'docs/specs/components/Button/Button.swift.spec.md: id must match "^component:swift/Button$".',
      'docs/specs/components/Button/Button.swift.spec.md: owners must be a non-empty inline list.',
      'docs/specs/components/Button/Button.swift.spec.md: duplicate id component:Button; first declared in docs/specs/components/Button/Button.spec.md.',
      'docs/specs/components/Button/Button.swift.spec.md: platform_of must name the core component, component:Button.',
      'docs/specs/components/Button/Button.swift.spec.md: verified_by path packages/native/apple/Tests/Missing.swift is not in the repository.',
    ]);
    // It is placed like the core record it implements.
    for (const [misplaced, message] of [
      [
        'docs/specs/components/Buton/Button.swift.spec.md',
        'platform records must live at docs/specs/components/<ComponentRoot>/',
      ],
      [
        'docs/specs/components/Button/Banana.swift.spec.md',
        'platform record for Banana must match component root "Button"',
      ],
    ]) {
      const misplacedPath = path.join(root, misplaced);
      fs.mkdirSync(path.dirname(misplacedPath), {recursive: true});
      const name = path.basename(misplaced, '.swift.spec.md');
      fs.writeFileSync(
        misplacedPath,
        platformRecord({
          id: `component:swift/${name}`,
          platform_of: `component:${name}`,
        }),
      );
      const misplacedProblems = (await validateKnowledgeRoot(root)).filter(
        problem => problem.startsWith(misplaced),
      );
      expect(misplacedProblems.join('\n')).toContain(message);
      fs.rmSync(misplacedPath);
    }
    // Its applicability blocks are validated, since specs:for reads them.
    fs.writeFileSync(
      swift,
      withReviewApplicability(platformRecord(), {'not-a-trigger': ['INV1']}) +
        '\n<!-- path-applicability:v1 -->\n\n```json\n{"paths": []}\n```\n',
    );
    const blockProblems = (await validateKnowledgeRoot(root)).filter(problem =>
      problem.startsWith('docs/specs/components/Button/Button.swift.spec.md'),
    );
    expect(
      blockProblems.some(problem => problem.includes('review-applicability')),
    ).toBe(true);
    expect(blockProblems).toContain(
      'docs/specs/components/Button/Button.swift.spec.md: path-applicability:v1 requires a non-empty paths list.',
    );
    // The shared validator's current-record rules apply, verified_by included.
    expect(
      await swiftProblems({authority: 'current', verified_by: '[]'}),
    ).toEqual(
      expect.arrayContaining([
        'docs/specs/components/Button/Button.swift.spec.md: current records require non-empty verified_by.',
        'docs/specs/components/Button/Button.swift.spec.md: current records require approved_by to name an authorized owner.',
        'docs/specs/components/Button/Button.swift.spec.md: current records require approved_at as YYYY-MM-DD.',
      ]),
    );
    expect(
      await swiftProblems({
        authority: 'current',
        approved_by: 'cixzhang',
        approved_at: '2026-11-01',
      }),
    ).toEqual([]);
  });

  it('places a flat-package platform record by the same rules as its core record', async () => {
    const root = fixtureRoot();
    const source = path.join(root, 'packages/charts/src');
    fs.writeFileSync(
      path.join(source, 'index.ts'),
      "export {Chart} from './Chart';\nexport {Ghost} from './Ghost';\n",
    );
    fs.writeFileSync(
      path.join(source, 'Chart.tsx'),
      'export function Chart() {}\n',
    );
    fs.writeFileSync(
      path.join(source, 'Ghost.tsx'),
      'export function Ghost() {}\n',
    );
    writeSwiftTest(root);
    const swiftRecord = (folder, name) => {
      const filePath = path.join(
        root,
        `docs/specs/components/${folder}/${name}.swift.spec.md`,
      );
      fs.mkdirSync(path.dirname(filePath), {recursive: true});
      fs.writeFileSync(
        filePath,
        platformRecord({
          id: `component:swift/${name}`,
          platform_of: `component:${name}`,
        }),
      );
    };
    swiftRecord('Chart', 'Chart');
    swiftRecord('Chart', 'Ghost');

    const problems = (await validateKnowledgeRoot(root)).join('\n');
    expect(problems).not.toContain('Chart/Chart.swift.spec.md');
    expect(problems).toContain(
      'docs/specs/components/Chart/Ghost.swift.spec.md: platform record for Ghost must match component root "Chart"',
    );
  });

  it('checks a package architecture record under packages/<package>/specs/', async () => {
    const root = fixtureRoot();
    const template = fs.readFileSync(
      path.join(root, 'docs/templates/knowledge/architecture.md'),
      'utf8',
    );
    const slots = path.join(root, 'packages/native/specs/swift/slots.spec.md');
    const writeSlots = (id, kind = 'architecture') => {
      fs.mkdirSync(path.dirname(slots), {recursive: true});
      fs.writeFileSync(
        slots,
        template
          .replace('id: architecture:<surface>', `id: ${id}`)
          .replace('kind: architecture', `kind: ${kind}`),
      );
    };
    const packageProblems = async () =>
      (await validateKnowledgeRoot(root)).filter(problem =>
        problem.startsWith('packages/native/specs/'),
      );
    // Guidance Markdown that is not a `<slug>.spec.md` is not a candidate.
    fs.mkdirSync(path.join(root, 'packages/native/specs'), {recursive: true});
    fs.writeFileSync(
      path.join(root, 'packages/native/specs/README.md'),
      '# Native specs\n',
    );

    writeSlots('architecture:native-swift-slots');
    expect(await packageProblems()).toEqual([]);

    writeSlots('architecture:swift-slots');
    expect(await packageProblems()).toEqual([
      'packages/native/specs/swift/slots.spec.md: id must be architecture:native-swift-slots to match its path.',
    ]);

    writeSlots('architecture:native-swift-slots', 'bogus');
    expect(await packageProblems()).toContain(
      'packages/native/specs/swift/slots.spec.md: a record under packages/native/specs/ must be kind: architecture.',
    );
  });

  it('rejects a nested component record instead of treating it as a module', async () => {
    const root = fixtureRoot();
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    const nestedPath = recordPath(
      path.join(componentDirectory, 'notes/Extra.spec.md'),
    );
    fs.mkdirSync(path.dirname(nestedPath), {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord(),
    );
    fs.writeFileSync(nestedPath, componentRecord({id: 'component:Extra'}));

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /nested records use kind: module/,
    );
  });

  it('rejects a direct-child module record', async () => {
    const root = fixtureRoot();
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(componentDirectory, {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord({modules: '[module:Button/useButtonThing]'}),
    );
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'useButtonThing.spec.md')),
      moduleRecord(),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /module records must be nested beneath their component root/,
    );
  });

  it('rejects missing parent links and orphan module records', async () => {
    const root = fixtureRoot();
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    const modulePath = recordPath(
      path.join(componentDirectory, 'plugins/orphan/useOrphan.spec.md'),
    );
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord({modules: '[module:Button/useMissing]'}),
    );
    fs.writeFileSync(
      modulePath,
      moduleRecord({
        id: 'module:Button/useOrphan',
        parent_component: 'component:Button',
      }),
    );

    const problems = (await validateKnowledgeRoot(root)).join('\n');
    expect(problems).toMatch(
      /modules reference module:Button\/useMissing does not resolve/,
    );
    expect(problems).toMatch(/module module:Button\/useOrphan is orphaned/);
  });

  it('rejects mismatched parent declarations and component roots', async () => {
    const root = fixtureRoot();
    const buttonDirectory = path.join(root, 'packages/core/src/Button');
    const otherDirectory = path.join(root, 'packages/core/src/Other');
    const modulePath = recordPath(
      path.join(otherDirectory, 'plugins/thing/useButtonThing.spec.md'),
    );
    fs.mkdirSync(buttonDirectory, {recursive: true});
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(buttonDirectory, 'Button.spec.md')),
      componentRecord({modules: '[module:Other/useButtonThing]'}),
    );
    fs.writeFileSync(
      recordPath(path.join(otherDirectory, 'Other.spec.md')),
      componentRecord({
        id: 'component:Other',
        modules: '[module:Other/useButtonThing]',
      }),
    );
    fs.writeFileSync(
      modulePath,
      moduleRecord({
        id: 'module:Other/useButtonThing',
        parent_component: 'component:Other',
      }),
    );

    const problems = (await validateKnowledgeRoot(root)).join('\n');
    expect(problems).toMatch(
      /Button\.spec\.md: modules reference module:Other\/useButtonThing, but that module declares parent_component "component:Other"/,
    );
    expect(problems).toMatch(/must live in the same component root/);
  });

  it('requires parent_component to resolve to a component record', async () => {
    const root = fixtureRoot();
    const familyTemplate = fs.readFileSync(
      path.join(root, 'docs/templates/knowledge/family-contract.md'),
      'utf8',
    );
    fs.writeFileSync(
      path.join(root, 'docs/families/not-a-component.md'),
      familyTemplate.replace(
        'id: family:<family-name>',
        'id: component:Button',
      ),
    );
    fs.mkdirSync(path.join(root, 'packages/core/src/Button'));
    const modulePath = path.join(
      root,
      'docs/specs/components/Button/plugins/thing/useButtonThing.spec.md',
    );
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    fs.writeFileSync(modulePath, moduleRecord());

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /parent_component component:Button must resolve to a component record, not family/,
    );
  });

  it('requires parent module links to resolve to module records', async () => {
    const root = fixtureRoot();
    const familyTemplate = fs.readFileSync(
      path.join(root, 'docs/templates/knowledge/family-contract.md'),
      'utf8',
    );
    fs.writeFileSync(
      path.join(root, 'docs/families/actions.md'),
      familyTemplate.replace('family:<family-name>', 'family:actions'),
    );
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(componentDirectory, {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord({modules: '[family:actions]'}),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /modules reference family:actions must resolve to a module record, not family/,
    );
  });

  it('rejects duplicate module links and duplicate module ids', async () => {
    const root = fixtureRoot();
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(componentDirectory, {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord({
        modules: '[module:Button/useButtonThing,module:Button/useButtonThing]',
      }),
    );
    for (const owner of ['first', 'second']) {
      const modulePath = recordPath(
        path.join(
          componentDirectory,
          `plugins/${owner}/useButtonThing.spec.md`,
        ),
      );
      fs.mkdirSync(path.dirname(modulePath), {recursive: true});
      fs.writeFileSync(modulePath, moduleRecord());
    }

    const problems = (await validateKnowledgeRoot(root)).join('\n');
    expect(problems).toMatch(/duplicate id module:Button\/useButtonThing/);
    expect(problems).toMatch(
      /modules contains duplicate reference module:Button\/useButtonThing/,
    );
  });

  it('requires module ids and filenames to encode the same public name', async () => {
    const root = fixtureRoot();
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    const modulePath = recordPath(
      path.join(componentDirectory, 'plugins/thing/WrongName.spec.md'),
    );
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord({modules: '[module:Button/useButtonThing]'}),
    );
    fs.writeFileSync(modulePath, moduleRecord());

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /module filename must be useButtonThing\.spec\.md/,
    );
  });

  it('validates module anatomy only against the module consumer doc', async () => {
    const root = fixtureRoot();
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    const modulePath = recordPath(
      path.join(componentDirectory, 'plugins/thing/useButtonThing.spec.md'),
    );
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord({modules: '[module:Button/useButtonThing]'}),
    );
    fs.writeFileSync(
      path.join(componentDirectory, 'useButtonThing.doc.mjs'),
      `export const docs = {
  name: 'useButtonThing',
  usage: {
    anatomy: [
      {name: 'Generated control', required: true, description: 'Generated UI.'},
    ],
  },
  theming: {
    targets: [{className: 'astryx-button-thing'}],
  },
};\n`,
    );
    fs.writeFileSync(
      modulePath,
      withAnatomyTheming(moduleRecord(), {
        'Generated control': {target: 'button-thing'},
      }),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('never validates a module map against parent aggregate anatomy', async () => {
    const root = fixtureRoot();
    const componentDirectory = path.join(root, 'packages/core/src/Button');
    const modulePath = recordPath(
      path.join(componentDirectory, 'plugins/thing/useButtonThing.spec.md'),
    );
    fs.mkdirSync(path.dirname(modulePath), {recursive: true});
    const parentDoc = writeButtonDoc(componentDirectory).replace(
      '  usage: {',
      "  components: [{name: 'useButtonThing'}],\n  usage: {",
    );
    fs.writeFileSync(
      path.join(componentDirectory, 'Button.doc.mjs'),
      parentDoc,
    );
    fs.writeFileSync(
      recordPath(path.join(componentDirectory, 'Button.spec.md')),
      componentRecord({modules: '[module:Button/useButtonThing]'}),
    );
    fs.writeFileSync(
      modulePath,
      withAnatomyTheming(moduleRecord(), {Root: {target: 'button'}}),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /no exact consumer doc entry for module useButtonThing/,
    );
  });

  it('discovers only the exact canonical package-local theme record without placement errors', async () => {
    const root = fixtureRoot();
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord(),
    );
    fs.writeFileSync(
      path.join(root, 'docs/themes/README.md'),
      '# Guidance only\n',
    );

    const discovered = discoverKnowledgeRecords(root).map(filePath =>
      path.relative(root, filePath),
    );
    expect(discovered).toContain('packages/themes/neutral/neutral.spec.md');
    expect(discovered).not.toContain('docs/themes/README.md');
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it.each([
    [
      'docs guidance directory',
      'docs/themes/neutral.md',
      /theme records must be placed at packages\/themes\/<theme>\/<theme>\.spec\.md/,
    ],
    [
      'wrong package filename',
      'packages/themes/neutral/Theme.spec.md',
      /theme record must be placed exactly at packages\/themes\/neutral\/neutral\.spec\.md/,
    ],
    [
      'nested package path',
      'packages/themes/neutral/subdir/neutral.spec.md',
      /theme record must be placed exactly at packages\/themes\/neutral\/neutral\.spec\.md/,
    ],
  ])(
    'rejects a theme-shaped record in the %s',
    async (_name, relative, error) => {
      const root = fixtureRoot();
      const absolute = path.join(root, relative);
      fs.mkdirSync(path.dirname(absolute), {recursive: true});
      fs.writeFileSync(absolute, themeRecord());

      const discovered = discoverKnowledgeRecords(root).map(filePath =>
        path.relative(root, filePath),
      );
      expect(discovered).toContain(relative);
      expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(error);
    },
  );

  it('accepts derived repo-owner approval on a current theme record', async () => {
    const root = fixtureRoot();
    writeCurrentArchitecture(root);
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        approved_by: 'rubyycheung',
        approved_at: '2026-08-31',
      }),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('does not inherit v1 approvalOwners for theme approval', async () => {
    const root = fixtureRoot();
    writeCurrentArchitecture(root);
    for (const ownerFile of ['ENGOWNERS', 'DESIGNOWNERS']) {
      const filePath = path.join(root, `.github/${ownerFile}`);
      fs.writeFileSync(
        filePath,
        fs.readFileSync(filePath, 'utf8').replace(/@cixzhang\b/g, ''),
      );
    }
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        approved_by: 'cixzhang',
        approved_at: '2026-08-31',
      }),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /approved_by to name an authorized owner/,
    );
  });

  it('accepts an ENGOWNER approval on a current theme record', async () => {
    const root = fixtureRoot();
    writeCurrentArchitecture(root);
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        approved_by: 'czarandy',
        approved_at: '2026-08-31',
      }),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('rejects a scalar references field on a current theme', async () => {
    const root = fixtureRoot();
    writeCurrentArchitecture(root);
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        approved_by: 'rubyycheung',
        approved_at: '2026-08-31',
        references: 'spec:AST-006',
      }),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /references must be a list/,
    );
  });

  it('does not let a self-declared theme owner approve a current record', async () => {
    const root = fixtureRoot();
    writeCurrentArchitecture(root);
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        additional_owners: '[self-declared-owner]',
        approved_by: 'self-declared-owner',
        approved_at: '2026-08-31',
      }),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /approved_by to name an authorized owner/,
    );
  });

  it('rejects an unresolved reference from a current theme record', async () => {
    const root = fixtureRoot();
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        approved_by: 'rubyycheung',
        approved_at: '2026-08-31',
        references: '[architecture:missing]',
      }),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /references reference architecture:missing does not resolve/,
    );
  });

  it('rejects an unresolved typed reference list from a current theme', async () => {
    const root = fixtureRoot();
    writeCurrentArchitecture(root);
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        approved_by: 'rubyycheung',
        approved_at: '2026-08-31',
        references: '[spec:missing]',
      }),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /references reference spec:missing does not resolve/,
    );
  });

  it('rejects a current theme that relies on a draft deciding spec', async () => {
    const root = fixtureRoot();
    writeCurrentArchitecture(root);
    const specDirectory = path.join(root, 'docs/specs/AST-006');
    fs.mkdirSync(specDirectory);
    const systemTemplate = fs.readFileSync(
      path.join(root, 'docs/templates/knowledge/system-spec.md'),
      'utf8',
    );
    fs.writeFileSync(
      path.join(specDirectory, 'spec.md'),
      systemTemplate.replace('id: spec:AST-000', 'id: spec:AST-006'),
    );
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        approved_by: 'rubyycheung',
        approved_at: '2026-08-31',
        references: '[spec:AST-006]',
      }),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /current records may not rely on non-current spec:AST-006/,
    );
  });

  it('accepts a current theme list reference to a current deciding spec', async () => {
    const root = fixtureRoot();
    writeCurrentArchitecture(root);
    writeSystemSpec(root, 'AST-006', systemSpecRecord({id: 'spec:AST-006'}));
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({
        authority: 'current',
        approved_by: 'rubyycheung',
        approved_at: '2026-08-31',
        references: '[spec:AST-006]',
      }),
    );

    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('rejects duplicate theme ids', async () => {
    const root = fixtureRoot();
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord(),
    );
    fs.writeFileSync(
      path.join(root, 'packages/themes/duplicate/duplicate.spec.md'),
      themeRecord(),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /duplicate id theme:neutral/,
    );
  });

  it('rejects a theme id outside the package-theme-name format', async () => {
    const root = fixtureRoot();
    fs.writeFileSync(
      path.join(root, 'packages/themes/neutral/neutral.spec.md'),
      themeRecord({id: 'theme:Neutral Theme'}),
    );

    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /id must match/,
    );
  });

  it('rejects duplicate authority fields', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord().replace(
        'authority: draft',
        'authority: draft\nauthority: "current"',
      ),
    );
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /duplicate authority fields|duplicate frontmatter field authority/,
    );
  });

  describe('repository owner eligibility', () => {
    const records = [
      ['architecture', 'architecture.md', 'docs/architecture/approval.md'],
      [
        'component',
        'component-spec.md',
        'docs/specs/components/Button/Button.spec.md',
      ],
      [
        'module',
        'module-spec.md',
        'docs/specs/components/Button/hooks/useButtonThing.spec.md',
      ],
      ['family', 'family-contract.md', 'docs/families/approval.md'],
      ['system-spec', 'system-spec.md', 'docs/specs/AST-900/spec.md'],
      ['design', 'design-spec.md', 'docs/design/approval.md'],
      ['theme', 'theme-spec.md', 'packages/themes/neutral/neutral.spec.md'],
    ];

    function writeApprovalRecord(root, templateName, filePath, approvedBy) {
      const template = fs.readFileSync(
        path.join(root, 'docs/templates/knowledge', templateName),
        'utf8',
      );
      const content = template
        .replace('authority: draft', 'authority: current')
        .replace('approved_by: null', `approved_by: ${approvedBy}`)
        .replace('approved_at: null', 'approved_at: 2026-10-13');
      fs.mkdirSync(path.dirname(path.join(root, filePath)), {recursive: true});
      fs.writeFileSync(path.join(root, filePath), content);
    }

    function approvalProblems(problems, filePath) {
      return problems.filter(problem =>
        problem.startsWith(`${filePath}: current records require approved_by`),
      );
    }

    it.each(records)(
      'accepts an ENGOWNER for %s records',
      async (_kind, templateName, filePath) => {
        const root = fixtureRoot();
        writeApprovalRecord(root, templateName, filePath, 'nynexman4464');
        expect(
          approvalProblems(await validateKnowledgeRoot(root), filePath),
        ).toEqual([]);
      },
    );

    it.each(records)(
      'does not inherit the legacy schema approver list for %s',
      async (_kind, templateName, filePath) => {
        const root = fixtureRoot();
        for (const ownerFile of ['ENGOWNERS', 'DESIGNOWNERS']) {
          const ownerPath = path.join(root, '.github', ownerFile);
          fs.writeFileSync(
            ownerPath,
            fs.readFileSync(ownerPath, 'utf8').replace(/@cixzhang\b/g, ''),
          );
        }
        writeApprovalRecord(root, templateName, filePath, 'cixzhang');
        expect(
          approvalProblems(await validateKnowledgeRoot(root), filePath),
        ).toHaveLength(1);
      },
    );

    it.each(records)(
      'limits DESIGNOWNER eligibility to design/theme for %s',
      async (kind, templateName, filePath) => {
        const root = fixtureRoot();
        writeApprovalRecord(root, templateName, filePath, 'rubyycheung');
        expect(
          approvalProblems(await validateKnowledgeRoot(root), filePath),
        ).toHaveLength(kind === 'design' || kind === 'theme' ? 0 : 1);
      },
    );
  });

  it('requires explicit approval for a current record', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord({authority: 'current'}),
    );
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /require approved_by/,
    );
  });

  it('rejects an unauthorized current approval claim', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord({
        authority: 'current',
        approved_by: 'someone-else',
        approved_at: '2026-08-30',
      }),
    );
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /authorized owner/,
    );
  });

  it('accepts a current record with an authorized dated approval', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord({
        authority: 'current',
        approved_by: 'cixzhang',
        approved_at: '2026-08-30',
      }),
    );
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('requires a replacement for a superseded archive', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord({authority: 'archived', archive_reason: 'superseded'}),
    );
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /require superseded_by/,
    );
  });

  it('rejects a record claiming a future template version', async () => {
    const root = fixtureRoot();
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord({template_version: '8'}),
    );
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /template_version 8 is newer than 7/,
    );
  });

  it('rejects active records on an old schema', async () => {
    const root = fixtureRoot();
    addSchemaVersion(root, 0);
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord({schema_version: '0'}),
    );
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /active component records must use latest schema_version 3 for that kind/,
    );
  });

  it('allows archived records to retain an older available schema', async () => {
    const root = fixtureRoot();
    addSchemaVersion(root, 0);
    const directory = path.join(root, 'packages/core/src/Button');
    fs.mkdirSync(directory);
    fs.writeFileSync(
      recordPath(path.join(directory, 'Button.spec.md')),
      componentRecord({
        schema_version: '0',
        authority: 'archived',
        archive_reason: 'historical',
      }),
    );
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('accepts a DESIGNOWNER approval claim on a current design record', async () => {
    const root = fixtureRoot();
    const template = fs.readFileSync(
      path.join(root, 'docs/templates/knowledge/design-spec.md'),
      'utf8',
    );
    const record = template
      .replace('id: design:<surface>', 'id: design:button')
      .replace('authority: draft', 'authority: current')
      .replace('approved_by: null', 'approved_by: rubyycheung')
      .replace('approved_at: null', 'approved_at: 2026-08-30');
    fs.mkdirSync(path.join(root, 'docs/design'), {recursive: true});
    fs.writeFileSync(path.join(root, 'docs/design/button.md'), record);
    expect((await validateKnowledgeRoot(root)).join('\n')).not.toMatch(
      /approved_by to name an authorized owner/,
    );
  });

  it('requires current design records to reference current architecture', async () => {
    const root = fixtureRoot();
    const template = fs.readFileSync(
      path.join(root, 'docs/templates/knowledge/design-spec.md'),
      'utf8',
    );
    const record = template
      .replace('id: design:<surface>', 'id: design:button')
      .replace('authority: draft', 'authority: current')
      .replace('approved_by: null', 'approved_by: cixzhang')
      .replace('approved_at: null', 'approved_at: 2026-08-30')
      .replace(
        'architecture: [architecture:<surface>]',
        'architecture: [architecture:missing]',
      );
    fs.mkdirSync(path.join(root, 'docs/design'), {recursive: true});
    fs.writeFileSync(path.join(root, 'docs/design/button.md'), record);
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /architecture reference architecture:missing does not resolve/,
    );
  });

  it('rejects duplicate logical ids', async () => {
    const root = fixtureRoot();
    for (const name of ['Button', 'Action']) {
      const directory = path.join(root, `packages/core/src/${name}`);
      fs.mkdirSync(directory);
      fs.writeFileSync(
        recordPath(path.join(directory, `${name}.spec.md`)),
        componentRecord(),
      );
    }
    expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
      /duplicate id component:Button/,
    );
  });
});

describe('path-applicability:v1', () => {
  it('matches ** across whole segments, * and ? within one segment', () => {
    const cases = [
      ['apps/docsite/**', 'apps/docsite/src/a.ts', true],
      ['apps/docsite/**', 'apps/docsite', false],
      ['apps/docsite/**', 'apps/docsite-old/a.ts', false],
      [
        'packages/**/*.doc.mjs',
        'packages/core/src/Button/Button.doc.mjs',
        true,
      ],
      ['packages/**/*.doc.mjs', 'packages/Button.doc.mjs', true],
      [
        'packages/**/*.doc.mjs',
        'packages/core/src/Button/Button.doc.zh.mjs',
        false,
      ],
      ['packages/*/src/index.ts', 'packages/core/src/index.ts', true],
      ['packages/*/src/index.ts', 'packages/core/nested/src/index.ts', false],
      ['scripts/check-?.mjs', 'scripts/check-a.mjs', true],
      ['scripts/check-?.mjs', 'scripts/check-ab.mjs', false],
      ['docs/a.b.md', 'docs/aXb.md', false],
      ['README.md', 'README.md', true],
      ['README.md', 'packages/core/README.md', false],
    ];
    for (const [pattern, filePath, expected] of cases) {
      expect([
        pattern,
        filePath,
        matchesPathPattern(pattern, filePath),
      ]).toEqual([pattern, filePath, expected]);
    }
  });

  it('accepts a valid block and rejects malformed, unsafe, repeated, or stale patterns', () => {
    const files = ['apps/docsite/src/a.ts', 'README.md'];
    const content = [
      '# Record',
      '',
      '<!-- path-applicability:v1 -->',
      '',
      '```json',
      '{"paths": ["apps/docsite/**", "README.md"]}',
      '```',
    ].join('\n');
    const parsed = parsePathApplicabilityBlock(content, 'r.md');
    expect(parsed.problems).toEqual([]);
    expect(validatePathApplicability(parsed.config, 'r.md', files)).toEqual([]);

    const problems = config => validatePathApplicability(config, 'r.md', files);
    expect(problems({paths: []})).toEqual([
      'r.md: path-applicability:v1 requires a non-empty paths list.',
    ]);
    expect(problems({paths: ['README.md'], scope: 'global'})).toEqual([
      'r.md: path-applicability:v1 requires exactly paths.',
    ]);
    expect(
      problems({
        paths: [
          'README.md',
          'README.md',
          '/abs/**',
          'a/../b',
          'a/b**',
          '**',
          'docs/{a,b}.md',
          'apps/missing/**',
          '**/*',
          '**/**',
          '**/?*',
          '*/src/a.ts',
        ],
      }),
    ).toEqual([
      'r.md: path-applicability:v1 pattern "README.md" is repeated.',
      'r.md: path-applicability:v1 pattern "/abs/**" must be repository-relative with no empty, "." or ".." segments.',
      'r.md: path-applicability:v1 pattern "a/../b" must be repository-relative with no empty, "." or ".." segments.',
      'r.md: path-applicability:v1 pattern "a/b**" may use ** only as a whole segment.',
      'r.md: path-applicability:v1 pattern "**" covers the whole repository; name the paths.',
      'r.md: path-applicability:v1 pattern "docs/{a,b}.md" may use only letters, digits, _ . @ - / and the wildcards * ** ?.',
      'r.md: path-applicability:v1 pattern "apps/missing/**" matches no repository file.',
      'r.md: path-applicability:v1 pattern "**/*" must start with a literal path segment; a leading wildcard covers the whole repository.',
      'r.md: path-applicability:v1 pattern "**/**" must start with a literal path segment; a leading wildcard covers the whole repository.',
      'r.md: path-applicability:v1 pattern "**/?*" must start with a literal path segment; a leading wildcard covers the whole repository.',
      'r.md: path-applicability:v1 pattern "*/src/a.ts" must start with a literal path segment; a leading wildcard covers the whole repository.',
    ]);
    expect(
      validatePathApplicability({paths: ['apps/**']}, 'r.md', [
        'apps/a.ts',
        'apps/b/c.ts',
      ]),
    ).toEqual([
      'r.md: path-applicability:v1 pattern "apps/**" matches every repository file; name the paths.',
    ]);
    expect(
      validatePathApplicability({paths: ['apps/missing/**']}, 'r.md', null),
    ).toEqual([]);
  });

  it('reports duplicate blocks through the shared overlay parser', () => {
    const block =
      '<!-- path-applicability:v1 -->\n```json\n{"paths": ["README.md"]}\n```\n';
    expect(
      parsePathApplicabilityBlock(`${block}\n${block}`, 'r.md').problems,
    ).toEqual(['r.md: duplicate path-applicability:v1 blocks.']);
  });
});

describe('INV25 record reachability', () => {
  function gitFixture(root) {
    execFileSync('git', ['init', '-q'], {cwd: root});
    execFileSync('git', ['add', '-A'], {cwd: root});
  }

  it('fails a current record no tracked non-record path reaches, and passes once a pattern reaches it', async () => {
    const root = fixtureRoot();
    writeSystemSpec(root, 'AST-900', systemSpecRecord());
    fs.mkdirSync(path.join(root, 'apps/site'), {recursive: true});
    fs.writeFileSync(path.join(root, 'apps/site/index.md'), '# Site\n');
    gitFixture(root);
    expect(await validateKnowledgeRoot(root)).toEqual([
      'docs/specs/AST-900/spec.md: current record spec:AST-900 is not reached from any repository path that is not itself a record (INV25). Link it through placement, applies_to, verified_by, a membership or consumer-doc id, a cited spec number, or a path-applicability:v1 block.',
    ]);

    fs.writeFileSync(
      path.join(root, 'docs/specs/AST-900/spec.md'),
      systemSpecRecord().replace(
        '# Fixture system spec\n',
        '# Fixture system spec\n\n<!-- path-applicability:v1 -->\n\n```json\n{"paths": ["apps/site/**"]}\n```\n',
      ),
    );
    gitFixture(root);
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('skips reachability when the root has no tracked file list', async () => {
    const root = fixtureRoot();
    writeSystemSpec(root, 'AST-900', systemSpecRecord());
    expect(await validateKnowledgeRoot(root)).toEqual([]);
  });

  it('runs from the command line without deadlocking on its own import', () => {
    const output = execFileSync(
      process.execPath,
      [path.join(repoRoot, 'scripts/check-knowledge.mjs')],
      {cwd: repoRoot, encoding: 'utf8'},
    );
    expect(output).toContain('Knowledge templates and records are aligned.');
  });
});