Skip to content

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

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

/**
 * @file Knowledge-record validation.
 * @input Versioned schemas, records, and current ENGOWNERS/DESIGNOWNERS.
 * @output Structural, relationship, and approval-eligibility problems.
 * @position Repository knowledge guardrail; schemas do not grant approval rights.
 */

/* global console, process */
import fs from 'node:fs';
import path from 'node:path';
import {execFileSync} from 'node:child_process';
import {createHash} from 'node:crypto';
import {createRequire} from 'node:module';
import {fileURLToPath} from 'node:url';
import {collectThemingTargets} from '../packages/cli/foundation/discovery/theming-targets.mjs';
import {readObjects} from './lib/git-objects.mjs';

const require = createRequire(import.meta.url);
const {
  COMPONENT_PACKAGE_NAMES,
  packageHasPublicComponent,
} = require('./component-packages.cjs');
const {
  parseAuthority,
  parseOwnerFile,
} = require('../.github/scripts/knowledge-frontmatter.cjs');
const {
  parseDesignDecisionsBlock,
  validateDesignDecisionsBlock,
} = require('../.github/scripts/component-design-decisions.cjs');
const {
  COMPONENT_SPEC_ROOT,
  PLATFORM_SOURCE_ROOTS,
  classifyPackageArchitectureRecordPath,
  classifyPlatformComponentSpecPath,
  componentSpecPathForSource,
  isComponentSpecRecordPath,
  isIgnoredComponentKnowledgeSegment,
  isKnowledgeRecordPath,
  isPlatformComponentSpecPath,
  isValidatedRecordPath,
  locateComponentKnowledgePath,
} = require('../.github/scripts/knowledge-paths.cjs');

const HERE = path.dirname(fileURLToPath(import.meta.url));
const DEFAULT_ROOT = path.resolve(HERE, '..');
const MODULE_ID_PATTERN =
  /^module:([A-Z][A-Za-z0-9]*)\/([A-Za-z][A-Za-z0-9]*)$/;
const READER_FIRST_TEMPLATE_KINDS = new Set([
  'architecture',
  'component',
  'module',
]);
const CONTRACT_AT_A_GLANCE_SECTION = 'Contract at a glance';

export {parseDesignDecisionsBlock, validateDesignDecisionsBlock};

function expectedTemplateSections(kind, requiredSections) {
  return READER_FIRST_TEMPLATE_KINDS.has(kind)
    ? [CONTRACT_AT_A_GLANCE_SECTION, ...requiredSections]
    : requiredSections;
}

export function parseKnowledgeDocument(content, filePath = '<document>') {
  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
  if (!match) {
    return {
      frontmatter: new Map(),
      sections: [],
      problems: [`${filePath}: missing frontmatter.`],
    };
  }

  function parseScalar(raw) {
    let value = raw.trim();
    if (value === 'null' || value === '~') return null;
    if (/^\[.*\]$/.test(value)) {
      const inner = value.slice(1, -1).trim();
      return inner
        ? inner
            .split(',')
            .map(item => item.trim())
            .filter(Boolean)
            .map(item => item.replace(/^['"]|['"]$/g, ''))
        : [];
    }
    if (/^[0-9]+$/.test(value)) return Number(value);
    return value.replace(/^['"]|['"]$/g, '');
  }

  const frontmatter = new Map();
  const problems = [];
  const lines = match[1].split(/\r?\n/);
  for (let index = 0; index < lines.length; index += 1) {
    const line = lines[index];
    if (
      /^\s/.test(line) ||
      line.trim() === '' ||
      line.trimStart().startsWith('#')
    )
      continue;
    const field = line.match(/^([a-z][a-z0-9_]*):\s*(.*)$/);
    if (!field) continue;
    let raw = field[2].trim();
    if (raw === '') {
      const block = [];
      while (index + 1 < lines.length && /^\s/.test(lines[index + 1])) {
        block.push(lines[index + 1].trim());
        index += 1;
      }
      if (block.length === 1 && /^\[.*\]$/.test(block[0])) {
        raw = block[0];
      } else if (block[0] === '[' && block.at(-1) === ']') {
        raw = `[${block.slice(1, -1).join('')}]`;
      } else if (block.every(item => item.startsWith('- '))) {
        raw = `[${block.map(item => item.slice(2)).join(',')}]`;
      }
    }
    if (frontmatter.has(field[1])) {
      problems.push(`${filePath}: duplicate frontmatter field ${field[1]}.`);
      continue;
    }
    frontmatter.set(field[1], parseScalar(raw));
  }

  try {
    const authority = parseAuthority(content, filePath);
    if (authority !== frontmatter.get('authority')) {
      problems.push(`${filePath}: authority could not be parsed consistently.`);
    }
  } catch (error) {
    problems.push(error.message);
  }

  const sections = [...content.matchAll(/^## (.+?)\s*$/gm)].map(
    section => section[1],
  );
  return {frontmatter, sections, problems};
}

const REVIEW_APPLICABILITY_MARKER = 'review-applicability:v1';
const PATH_APPLICABILITY_MARKER = 'path-applicability:v1';
const PATH_PATTERN_CHARACTERS = /^[A-Za-z0-9_.@*?/-]+$/;
export const GLOBAL_REVIEW_TRIGGERS = new Set([
  'accessibility',
  'behavior',
  'compatibility',
  'component-slots',
  'docsite',
  'interaction',
  'layering',
  'layout',
  'motion',
  'navigation',
  'platform',
  'public-api',
  'react-runtime',
  'responsive',
  'scrolling',
  'specification',
  'styling',
  'testing',
  'theming',
  'tokens',
  'visual',
]);
const REVIEW_TRIGGER_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
const REVIEW_CLAIM_ID_PATTERN = /^[A-Z][A-Z0-9]*-?[0-9]+[a-z]?$/;

function exactKeys(value, expected) {
  return (
    value != null &&
    typeof value === 'object' &&
    !Array.isArray(value) &&
    Object.keys(value).sort().join('\0') === [...expected].sort().join('\0')
  );
}

export function extractKnowledgeClaims(content) {
  const claims = new Map();
  const definitions = [
    {
      pattern:
        /^\s*[-*]\s+\*\*([A-Z][A-Z0-9]*-?[0-9]+[a-z]?)\s+—\s+([\s\S]*?)\*\*/gm,
      title: match => match[2].replace(/\s+/g, ' ').trim(),
    },
    {
      pattern: /^#{2,6}\s+([A-Z][A-Z0-9]*-?[0-9]+[a-z]?)\s+—\s+(.+?)\s*$/gm,
      title: match => match[2].trim(),
    },
  ];
  for (const {pattern, title} of definitions) {
    for (const match of content.matchAll(pattern)) {
      if (!claims.has(match[1])) {
        claims.set(match[1], title(match));
      }
    }
  }

  let levelTwoSection = null;
  for (const line of content.split(/\r?\n/)) {
    const heading = /^##\s+(.+?)\s*$/.exec(line);
    if (heading) {
      levelTwoSection = heading[1];
      continue;
    }
    if (levelTwoSection !== 'Requirements') continue;
    const row =
      /^\|\s*([A-Z][A-Z0-9]*-?[0-9]+[a-z]?)\s*\|\s*([^|]+?)\s*\|/.exec(line);
    if (row && !claims.has(row[1])) {
      claims.set(row[1], row[2].replace(/\s+/g, ' ').trim());
    }
  }
  return claims;
}

function parseOverlayBlock(content, markerName, filePath) {
  const marker = new RegExp(
    `<!--\\s*${markerName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*-->`,
    'g',
  );
  const markers = [...content.matchAll(marker)];
  if (markers.length === 0) return {config: null, problems: []};
  if (markers.length > 1) {
    return {
      config: null,
      problems: [`${filePath}: duplicate ${markerName} blocks.`],
    };
  }

  const remainder = content.slice(markers[0].index + markers[0][0].length);
  const block = /^\s*```json\s*\n([\s\S]*?)\n```/.exec(remainder);
  if (!block) {
    return {
      config: null,
      problems: [
        `${filePath}: ${markerName} must be followed by one JSON code block.`,
      ],
    };
  }

  const duplicates = duplicateJsonKeys(block[1]);
  if (duplicates.length > 0) {
    return {
      config: null,
      problems: [
        `${filePath}: ${markerName} repeats JSON field ${JSON.stringify(duplicates[0])}.`,
      ],
    };
  }

  try {
    return {config: JSON.parse(block[1]), problems: []};
  } catch (error) {
    return {
      config: null,
      problems: [
        `${filePath}: ${markerName} is not valid JSON (${error.message}).`,
      ],
    };
  }
}

/**
 * Keys repeated within one JSON object. `JSON.parse` keeps the last value
 * silently, so a repeated key would hide an entry; the same key in two
 * different objects (two concerns that both list `names`) is not a repeat.
 */
function duplicateJsonKeys(text) {
  const duplicates = [];
  const objects = [];
  for (let index = 0; index < text.length; index += 1) {
    const character = text[index];
    if (character === '{') objects.push(new Set());
    else if (character === '}') objects.pop();
    else if (character === '"') {
      let end = index + 1;
      while (end < text.length && text[end] !== '"') {
        end += text[end] === '\\' ? 2 : 1;
      }
      const raw = text.slice(index, end + 1);
      index = end;
      if (!/^\s*:/.test(text.slice(end + 1))) continue;
      const keys = objects.at(-1);
      let key;
      try {
        key = JSON.parse(raw);
      } catch {
        continue;
      }
      if (keys == null) continue;
      if (keys.has(key)) duplicates.push(key);
      keys.add(key);
    }
  }
  return duplicates;
}

export function parseReviewApplicabilityBlock(
  content,
  filePath = '<knowledge record>',
) {
  return parseOverlayBlock(content, REVIEW_APPLICABILITY_MARKER, filePath);
}

export function validateReviewApplicability(
  config,
  content,
  filePath = '<knowledge record>',
) {
  if (config == null) return [];
  const problems = [];
  const keys =
    config != null && typeof config === 'object' && !Array.isArray(config)
      ? Object.keys(config)
      : [];
  if (
    !keys.includes('scope') ||
    keys.some(key => !['scope', 'triggers', 'concerns'].includes(key)) ||
    !(keys.includes('triggers') || keys.includes('concerns'))
  ) {
    return [
      `${filePath}: ${REVIEW_APPLICABILITY_MARKER} requires scope with triggers, concerns, or both, and nothing else.`,
    ];
  }
  if (config.scope !== 'global') {
    problems.push(
      `${filePath}: ${REVIEW_APPLICABILITY_MARKER} scope must be "global".`,
    );
  }
  if (keys.includes('concerns')) {
    problems.push(
      ...validateReviewConcerns(
        config.concerns,
        extractKnowledgeClaims(content),
        filePath,
      ),
    );
  }
  if (!keys.includes('triggers')) return problems;
  if (
    config.triggers == null ||
    typeof config.triggers !== 'object' ||
    Array.isArray(config.triggers) ||
    Object.keys(config.triggers).length === 0
  ) {
    problems.push(
      `${filePath}: ${REVIEW_APPLICABILITY_MARKER} requires at least one trigger with explicit claims.`,
    );
    return problems;
  }

  const knownClaims = extractKnowledgeClaims(content);
  const seenPairs = new Set();
  for (const [trigger, claims] of Object.entries(config.triggers)) {
    const where = `${filePath}: ${REVIEW_APPLICABILITY_MARKER} trigger ${JSON.stringify(trigger)}`;
    if (!REVIEW_TRIGGER_PATTERN.test(trigger)) {
      problems.push(`${where} must use lower-kebab-case.`);
    } else if (!GLOBAL_REVIEW_TRIGGERS.has(trigger)) {
      problems.push(`${where} is not a supported semantic trigger.`);
    }
    if (!Array.isArray(claims) || claims.length === 0) {
      problems.push(`${where} requires a non-empty claim list.`);
      continue;
    }
    for (const claimId of claims) {
      if (
        typeof claimId !== 'string' ||
        !REVIEW_CLAIM_ID_PATTERN.test(claimId)
      ) {
        problems.push(
          `${where} has malformed claim id ${JSON.stringify(claimId)}.`,
        );
        continue;
      }
      const pair = `${trigger}\0${claimId}`;
      if (seenPairs.has(pair)) {
        problems.push(`${where} repeats claim ${JSON.stringify(claimId)}.`);
        continue;
      }
      seenPairs.add(pair);
      if (!knownClaims.has(claimId)) {
        problems.push(
          `${where} references missing claim ${JSON.stringify(claimId)}.`,
        );
      }
    }
  }
  return problems;
}

function pathPatternExpression(pattern) {
  let expression = '';
  const segments = pattern.split('/');
  segments.forEach((segment, index) => {
    const last = index === segments.length - 1;
    if (segment === '**') {
      expression += last ? '.*' : '(?:[^/]+/)*';
      return;
    }
    expression += segment
      .split('')
      .map(character => {
        if (character === '*') return '[^/]*';
        if (character === '?') return '[^/]';
        return character.replace(/[.+^${}()|[\]\\]/g, '\\$&');
      })
      .join('');
    if (!last) expression += '/';
  });
  return new RegExp(`^${expression}$`);
}

/**
 * True when a repository-relative path matches a path-applicability pattern.
 * `**` spans any number of whole segments, `*` any run within one segment,
 * and `?` one character within a segment. Matching is case-sensitive.
 */
const pathPatternCache = new Map();

export function matchesPathPattern(pattern, filePath) {
  let expression = pathPatternCache.get(pattern);
  if (!expression) {
    expression = pathPatternExpression(pattern);
    pathPatternCache.set(pattern, expression);
  }
  return expression.test(filePath);
}

export function parsePathApplicabilityBlock(
  content,
  filePath = '<knowledge record>',
) {
  return parseOverlayBlock(content, PATH_APPLICABILITY_MARKER, filePath);
}

/**
 * Validate a `path-applicability:v1` block. When `repositoryFiles` is given,
 * every pattern must match at least one of them, so a pattern cannot go stale
 * silently after a move or rename.
 */
export function validatePathApplicability(
  config,
  filePath = '<knowledge record>',
  repositoryFiles = null,
) {
  if (config == null) return [];
  const where = `${filePath}: ${PATH_APPLICABILITY_MARKER}`;
  if (!exactKeys(config, ['paths'])) {
    return [`${where} requires exactly paths.`];
  }
  if (!Array.isArray(config.paths) || config.paths.length === 0) {
    return [`${where} requires a non-empty paths list.`];
  }
  const problems = [];
  const seen = new Set();
  for (const pattern of config.paths) {
    if (typeof pattern !== 'string' || pattern.length === 0) {
      problems.push(`${where} has a non-string or empty pattern.`);
      continue;
    }
    const label = `${where} pattern ${JSON.stringify(pattern)}`;
    if (seen.has(pattern)) {
      problems.push(`${label} is repeated.`);
      continue;
    }
    seen.add(pattern);
    if (!PATH_PATTERN_CHARACTERS.test(pattern)) {
      problems.push(
        `${label} may use only letters, digits, _ . @ - / and the wildcards * ** ?.`,
      );
      continue;
    }
    const segments = pattern.split('/');
    if (
      pattern.startsWith('/') ||
      segments.some(
        segment => segment === '' || segment === '.' || segment === '..',
      )
    ) {
      problems.push(
        `${label} must be repository-relative with no empty, "." or ".." segments.`,
      );
      continue;
    }
    if (segments.some(segment => segment.includes('**') && segment !== '**')) {
      problems.push(`${label} may use ** only as a whole segment.`);
      continue;
    }
    if (pattern === '**') {
      problems.push(`${label} covers the whole repository; name the paths.`);
      continue;
    }
    if (/[*?]/.test(segments[0])) {
      problems.push(
        `${label} must start with a literal path segment; a leading wildcard covers the whole repository.`,
      );
      continue;
    }
    if (
      repositoryFiles &&
      repositoryFiles.length > 1 &&
      repositoryFiles.every(candidate => matchesPathPattern(pattern, candidate))
    ) {
      problems.push(`${label} matches every repository file; name the paths.`);
      continue;
    }
    if (
      repositoryFiles &&
      !repositoryFiles.some(candidate => matchesPathPattern(pattern, candidate))
    ) {
      problems.push(`${label} matches no repository file.`);
    }
  }
  return problems;
}

function repositoryFileList(root) {
  try {
    return execFileSync('git', ['-C', root, 'ls-files', '-z'], {
      encoding: 'utf8',
      maxBuffer: 256 * 1024 * 1024,
      stdio: ['ignore', 'pipe', 'ignore'],
    })
      .split('\0')
      .filter(Boolean);
  } catch {
    return null;
  }
}

const REVIEW_CONCERN_NAME_PATTERN = REVIEW_TRIGGER_PATTERN;
const IDENTIFIER_PATTERN = /^[A-Za-z_$][\w$]*$/;

/**
 * A record's `concerns` map names the shared utilities it owns and the code
 * that re-implements them. Each entry lists identifiers (`names`), regular
 * expressions (`patterns`), or both, and the claims they route.
 */
function validateReviewConcerns(concerns, knownClaims, filePath) {
  const where = `${filePath}: ${REVIEW_APPLICABILITY_MARKER} concerns`;
  if (
    concerns == null ||
    typeof concerns !== 'object' ||
    Array.isArray(concerns) ||
    Object.keys(concerns).length === 0
  ) {
    return [`${where} must map at least one concern name to its entry.`];
  }
  const problems = [];
  for (const [name, entry] of Object.entries(concerns)) {
    const at = `${where} ${JSON.stringify(name)}`;
    if (!REVIEW_CONCERN_NAME_PATTERN.test(name)) {
      problems.push(`${at} must use lower-kebab-case.`);
    }
    const entryKeys =
      entry != null && typeof entry === 'object' && !Array.isArray(entry)
        ? Object.keys(entry)
        : null;
    if (
      entryKeys == null ||
      !entryKeys.includes('claims') ||
      entryKeys.some(key => !['names', 'patterns', 'claims'].includes(key))
    ) {
      problems.push(
        `${at} requires claims with names, patterns, or both, and nothing else.`,
      );
      continue;
    }
    const names = entry.names ?? [];
    const patterns = entry.patterns ?? [];
    if (!Array.isArray(names) || !Array.isArray(patterns)) {
      problems.push(`${at} names and patterns must be lists.`);
      continue;
    }
    if (names.length + patterns.length === 0) {
      problems.push(`${at} requires at least one name or pattern.`);
    }
    for (const value of names) {
      if (typeof value !== 'string' || !IDENTIFIER_PATTERN.test(value)) {
        problems.push(
          `${at} has a name that is not an identifier: ${JSON.stringify(value)}.`,
        );
      }
    }
    for (const value of patterns) {
      try {
        if (typeof value !== 'string' || value.length === 0) throw new Error();
        new RegExp(value);
      } catch {
        problems.push(`${at} has an invalid pattern ${JSON.stringify(value)}.`);
      }
    }
    if (!Array.isArray(entry.claims) || entry.claims.length === 0) {
      problems.push(`${at} requires a non-empty claim list.`);
      continue;
    }
    const seen = new Set();
    for (const claimId of entry.claims) {
      if (
        typeof claimId !== 'string' ||
        !REVIEW_CLAIM_ID_PATTERN.test(claimId)
      ) {
        problems.push(
          `${at} has malformed claim id ${JSON.stringify(claimId)}.`,
        );
      } else if (seen.has(claimId)) {
        problems.push(`${at} repeats claim ${JSON.stringify(claimId)}.`);
      } else if (!knownClaims.has(claimId)) {
        problems.push(
          `${at} references missing claim ${JSON.stringify(claimId)}.`,
        );
      }
      seen.add(claimId);
    }
  }
  return problems;
}

function concernMatchers(entry) {
  return [
    ...(entry.names ?? []).map(name => ({
      label: name,
      expression: new RegExp(
        `(?<![\\w$])${name.replace(/\$/g, '\\$')}(?![\\w$])`,
      ),
    })),
    ...(entry.patterns ?? []).map(pattern => ({
      label: pattern,
      expression: new RegExp(pattern),
    })),
  ];
}

/**
 * Route each claim whose owning record's concern matches an added line.
 * `addedLines` are `{file, line, text}` rows of shipped source a diff adds.
 * Every row names the record, concern, claim, and the first added lines that
 * matched it, so a reviewer sees why the claim applies.
 */
export function collectConcernMatches(records, addedLines, authorityCommit) {
  const matches = [];
  if (addedLines.length === 0) return matches;
  for (const record of records) {
    const parsed = parseReviewApplicabilityBlock(record.content, record.path);
    if (parsed.config?.concerns == null) continue;
    const document = parseKnowledgeDocument(record.content, record.path);
    const problems = [
      ...document.problems,
      ...parsed.problems,
      ...validateReviewApplicability(
        parsed.config,
        record.content,
        record.path,
      ),
    ];
    if (problems.length > 0) throw new Error(problems.join('\n'));
    if (document.frontmatter.get('authority') !== 'current') continue;
    const recordId = document.frontmatter.get('id');
    const claims = extractKnowledgeClaims(record.content);
    const recordDigest = createHash('sha256')
      .update(record.content)
      .digest('hex');
    for (const [concern, entry] of Object.entries(parsed.config.concerns)) {
      const matchers = concernMatchers(entry);
      const evidence = [];
      for (const added of addedLines) {
        for (const matcher of matchers) {
          const found = matcher.expression.exec(added.text);
          if (found) {
            evidence.push({...added, matched: found[0], by: matcher.label});
            break;
          }
        }
      }
      if (evidence.length === 0) continue;
      const first = evidence[0];
      for (const claimId of entry.claims) {
        matches.push({
          recordId,
          path: record.path,
          concern,
          claimId,
          claim: claims.get(claimId),
          utilities: entry.names ?? [],
          matchReason: `Added line ${first.file}:${first.line} matched ${JSON.stringify(first.matched)} in concern ${JSON.stringify(concern)}${entry.names?.length ? ` (shared: ${entry.names.join(', ')})` : ''}, which routes claim ${JSON.stringify(`${recordId}/${claimId}`)}.`,
          evidence: evidence.slice(0, 5),
          authorityCommit,
          recordDigest,
        });
      }
    }
  }
  return matches.sort((left, right) =>
    [left.recordId, left.concern, left.claimId]
      .join('\0')
      .localeCompare([right.recordId, right.concern, right.claimId].join('\0')),
  );
}

export function collectGlobalReviewMatches(
  records,
  requestedTriggers,
  authorityCommit,
) {
  const requested = [...new Set(requestedTriggers)].sort();
  for (const trigger of requested) {
    if (
      !REVIEW_TRIGGER_PATTERN.test(trigger) ||
      !GLOBAL_REVIEW_TRIGGERS.has(trigger)
    ) {
      throw new Error(`Invalid review trigger ${JSON.stringify(trigger)}.`);
    }
  }

  const matches = [];
  for (const record of records) {
    const document = parseKnowledgeDocument(record.content, record.path);
    const parsed = parseReviewApplicabilityBlock(record.content, record.path);
    const problems = [
      ...document.problems,
      ...parsed.problems,
      ...validateReviewApplicability(
        parsed.config,
        record.content,
        record.path,
      ),
    ];
    if (problems.length > 0) {
      throw new Error(problems.join('\n'));
    }
    if (
      document.frontmatter.get('authority') !== 'current' ||
      parsed.config?.scope !== 'global'
    ) {
      continue;
    }

    const recordId = document.frontmatter.get('id');
    if (typeof recordId !== 'string' || recordId.length === 0) {
      throw new Error(`${record.path}: a routed record requires an id.`);
    }
    const claims = extractKnowledgeClaims(record.content);
    const recordDigest = createHash('sha256')
      .update(record.content)
      .digest('hex');
    for (const trigger of requested) {
      for (const claimId of parsed.config.triggers?.[trigger] ?? []) {
        matches.push({
          recordId,
          path: record.path,
          trigger,
          claimId,
          claim: claims.get(claimId),
          matchReason: `Requested trigger ${JSON.stringify(trigger)} matched ${REVIEW_APPLICABILITY_MARKER} claim ${JSON.stringify(`${recordId}/${claimId}`)}.`,
          authorityCommit,
          recordDigest,
        });
      }
    }
  }
  return matches.sort((left, right) =>
    [left.recordId, left.path, left.trigger, left.claimId]
      .join('\0')
      .localeCompare(
        [right.recordId, right.path, right.trigger, right.claimId].join('\0'),
      ),
  );
}

export function routeGlobalReviewBaselinesAtRevision(
  root,
  authorityCommit,
  reviewHead,
  requestedTriggers,
) {
  const {records, authority} = readKnowledgeRecordsAtAuthority(
    root,
    authorityCommit,
    reviewHead,
  );
  return collectGlobalReviewMatches(records, requestedTriggers, authority);
}

/**
 * The knowledge records at a review's base authority commit, after checking
 * that commit is the full, resolved `origin/main` merge base of the reviewed
 * head, so a proposed head can never serve as its own authority.
 */
export function readKnowledgeRecordsAtAuthority(
  root,
  authorityCommit,
  reviewHead,
) {
  // One process resolves both commits, and fails when either does not.
  const resolved = execFileSync(
    'git',
    [
      '-C',
      root,
      'rev-parse',
      `${authorityCommit}^{commit}`,
      `${reviewHead}^{commit}`,
    ],
    {encoding: 'utf8'},
  )
    .trim()
    .split('\n');
  // Without --verify, rev-parse echoes an option and expands a range, so
  // only two object ids count as a resolution.
  if (
    resolved.length !== 2 ||
    !resolved.every(line => /^[0-9a-f]{40,64}$/.test(line))
  ) {
    throw new Error(
      `cannot resolve ${authorityCommit} and ${reviewHead} to two commits.`,
    );
  }
  const [resolvedCommit, resolvedHead] = resolved;
  if (resolvedCommit !== authorityCommit) {
    throw new Error(
      `authority commit must be the full resolved commit ${resolvedCommit}.`,
    );
  }
  if (resolvedHead !== reviewHead) {
    throw new Error(
      `review head must be the full resolved commit ${resolvedHead}.`,
    );
  }
  if (resolvedCommit === resolvedHead) {
    throw new Error('review head must differ from its base authority commit.');
  }
  const expectedBase = execFileSync(
    'git',
    ['-C', root, 'merge-base', 'origin/main', resolvedHead],
    {encoding: 'utf8'},
  ).trim();
  if (resolvedCommit !== expectedBase) {
    throw new Error(
      `authority commit must equal the review head's origin/main merge base ${expectedBase}.`,
    );
  }
  return {
    records: readKnowledgeRecordsAtRevision(root, resolvedCommit),
    authority: resolvedCommit,
  };
}

function readKnowledgeRecordsAtRevision(
  root,
  revision,
  isRecord = isKnowledgeRecordPath,
) {
  const paths = execFileSync(
    'git',
    [
      '-C',
      root,
      'ls-tree',
      '-r',
      '--name-only',
      revision,
      '--',
      'docs/architecture',
      'docs/design',
      'docs/families',
      'docs/specs',
      'packages',
    ],
    {encoding: 'utf8'},
  )
    .split(/\r?\n/)
    .filter(isRecord);
  const objects = readObjects(
    root,
    paths.map(filePath => `${revision}:${filePath}`),
  );
  return paths.map(filePath => {
    const content = objects.get(`${revision}:${filePath}`);
    if (!content) {
      throw new Error(`cannot read ${filePath} at ${revision}.`);
    }
    return {path: filePath, content: content.toString('utf8')};
  });
}

// A decision starts at a `DEC-n` or `Amendment` heading, or at a
// `- **DEC-n …**` list item. Its Decider line may share a line with its
// Reference, and may name several deciders.
const DECISION_HEADING = /^#{2,4} (DEC-[0-9]+[a-z]?)\b/;
const AMENDMENT_HEADING = /^#{2,4} (Amendment\b.*?)\s*$/;
const DECISION_ITEM = /^\s*[-*] \*\*(DEC-[0-9]+[a-z]?)\b/;
const ANY_HEADING = /^#{1,4} /;
// Any bold label that ends in "decider" or "deciders" (a decision may name
// several, such as a system-boundary and an adoption decider), except a
// proposed one, which approves nothing.
const DECIDER_LINE =
  /\*\*((?:[^*]*?\s)?[Dd]eciders?|Direction owners?):?\*\*:?\s*(.*)$/;
const PROPOSED_DECIDER = /^proposed\b/i;
const PLACEHOLDER_DECIDER = /pending|<[^>]*>/i;

function deciderLines(content) {
  const deciders = new Map();
  let decision = null;
  for (const line of content.split(/\r?\n/)) {
    const heading =
      line.match(DECISION_HEADING) ?? line.match(AMENDMENT_HEADING);
    if (heading || ANY_HEADING.test(line)) decision = heading?.[1] ?? null;
    const item = line.match(DECISION_ITEM);
    if (item) decision = item[1];
    const decider = decision && line.match(DECIDER_LINE);
    if (!decider || PROPOSED_DECIDER.test(decider[1])) continue;
    const label = decider[1].trim();
    const key = /^(deciders?|direction owners?)$/i.test(label)
      ? decision
      : `${decision} (${label})`;
    if (!deciders.has(key)) {
      deciders.set(key, decider[2].replace(/\s+/g, ' ').trim());
    }
  }
  return deciders;
}

function approvers(document) {
  const value = document.frontmatter.get('approved_by');
  if (value == null) return [];
  return Array.isArray(value) ? value.map(String) : [String(value)];
}

function originalDecider(line) {
  return line
    .split(';')[0]
    .split(',')
    .map(field => field.replace(/[`@]/g, '').replace(/\.$/, '').trim())
    .filter(field => field && !/^\d{4}-\d{2}-\d{2}/.test(field))
    .join(', ');
}

// Only the decider and date fields can hold a placeholder. The rest of the
// line is free text, such as a decision's subject.
function hasPlaceholderDecider(line) {
  const [decider = '', date = ''] = line.split(';')[0].split(',');
  return (
    PROPOSED_DECIDER.test(decider.replace(/[`@]/g, '').trim()) ||
    PLACEHOLDER_DECIDER.test(decider) ||
    PLACEHOLDER_DECIDER.test(date.split('(')[0])
  );
}

/**
 * The approval lines a pull request changes or removes, with the account whose
 * approval each change needs (INV31). Records pair by id, so a moved record or
 * a moved line is not a change.
 */
export function findApprovalLineRewrites(baseRecords, currentRecords) {
  const byId = records =>
    new Map(
      records.map(record => {
        const document = parseKnowledgeDocument(record.content, record.path);
        return [
          document.frontmatter.get('id') ?? record.path,
          {record, document},
        ];
      }),
    );
  const current = byId(currentRecords);
  const changes = [];
  for (const [id, base] of byId(baseRecords)) {
    const head = current.get(id);
    const headApprovers = head ? approvers(head.document) : [];
    const path = head?.record.path ?? base.record.path;
    const baseApprovers = approvers(base.document);
    for (const login of baseApprovers) {
      if (headApprovers.includes(login)) continue;
      const from = baseApprovers.join(', ');
      const to = headApprovers.join(', ') || null;
      changes.push({path, claim: 'approved_by', from, to, decider: login});
    }
    const headDeciders = head ? deciderLines(head.record.content) : new Map();
    for (const [decision, from] of deciderLines(base.record.content)) {
      if (hasPlaceholderDecider(from)) continue;
      const to = headDeciders.get(decision) ?? null;
      if (to?.startsWith(from)) continue;
      changes.push({
        path,
        claim: decision,
        from,
        to,
        decider: originalDecider(from),
      });
    }
  }
  return changes;
}

function currentValidatedRecords(root, repositoryFiles) {
  return repositoryFiles
    .filter(isValidatedRecordPath)
    .filter(filePath => fs.existsSync(path.join(root, filePath)))
    .map(filePath => ({
      path: filePath,
      content: fs.readFileSync(path.join(root, filePath), 'utf8'),
    }));
}

/**
 * The approval lines the working tree changes since `baseRevision`, in every
 * validated record: knowledge records and platform component records.
 */
export function approvalLineRewritesSince(root, baseRevision, repositoryFiles) {
  return findApprovalLineRewrites(
    readKnowledgeRecordsAtRevision(root, baseRevision, isValidatedRecordPath),
    currentValidatedRecords(root, repositoryFiles),
  );
}

function immediateDirectories(directory) {
  if (!fs.existsSync(directory)) return [];
  return fs
    .readdirSync(directory, {withFileTypes: true})
    .filter(entry => entry.isDirectory())
    .map(entry => path.join(directory, entry.name));
}

function matchingFiles(directory, predicate) {
  if (!fs.existsSync(directory)) return [];
  return fs
    .readdirSync(directory, {withFileTypes: true})
    .filter(entry => entry.isFile() && predicate(entry.name))
    .map(entry => path.join(directory, entry.name));
}

function matchingFilesRecursively(
  directory,
  predicate,
  {skipDirectory = () => false} = {},
) {
  if (!fs.existsSync(directory)) return [];
  const matches = [];
  const pending = [directory];
  while (pending.length > 0) {
    const current = pending.pop();
    for (const entry of fs.readdirSync(current, {withFileTypes: true})) {
      const candidate = path.join(current, entry.name);
      if (entry.isDirectory()) {
        if (skipDirectory(entry.name, candidate)) {
          continue;
        }
        pending.push(candidate);
      } else if (entry.isFile() && predicate(entry.name, candidate)) {
        matches.push(candidate);
      }
    }
  }
  return matches;
}

export function discoverThemeRecordCandidates(root = DEFAULT_ROOT) {
  const records = [];
  const problems = [];

  for (const filePath of matchingFiles(
    path.join(root, 'docs/themes'),
    name => name.endsWith('.md') && name !== 'README.md',
  )) {
    records.push(filePath);
    problems.push(
      `${path.relative(root, filePath)}: theme records must be placed at packages/themes/<theme>/<theme>.spec.md; docs/themes contains guidance only.`,
    );
  }

  for (const themeDirectory of immediateDirectories(
    path.join(root, 'packages/themes'),
  )) {
    const themeName = path.basename(themeDirectory);
    const expectedPath = path.join(themeDirectory, `${themeName}.spec.md`);
    for (const filePath of matchingFilesRecursively(themeDirectory, name =>
      name.endsWith('.spec.md'),
    )) {
      records.push(filePath);
      if (filePath !== expectedPath) {
        problems.push(
          `${path.relative(root, filePath)}: theme record must be placed exactly at packages/themes/${themeName}/${themeName}.spec.md.`,
        );
      }
    }
  }

  return {records: records.sort(), problems};
}

/**
 * Every package's own architecture records:
 * `packages/<package>/specs/…/<slug>.spec.md`.
 */
export function discoverPackageArchitectureRecords(root = DEFAULT_ROOT) {
  return immediateDirectories(path.join(root, 'packages'))
    .flatMap(packageDirectory =>
      matchingFilesRecursively(
        path.join(packageDirectory, 'specs'),
        (_name, candidate) =>
          classifyPackageArchitectureRecordPath(
            path.relative(root, candidate).split(path.sep).join('/'),
          ) !== null,
        {skipDirectory: isIgnoredComponentKnowledgeSegment},
      ),
    )
    .sort();
}

export function discoverKnowledgeRecords(root = DEFAULT_ROOT) {
  const records = [];

  for (const specDirectory of immediateDirectories(
    path.join(root, 'docs/specs'),
  )) {
    for (const name of ['spec.md', 'plan.md']) {
      const candidate = path.join(specDirectory, name);
      if (fs.existsSync(candidate)) records.push(candidate);
    }
  }

  records.push(
    ...matchingFiles(
      path.join(root, 'docs/families'),
      name => name.endsWith('.md') && name !== 'README.md',
    ),
    ...matchingFiles(
      path.join(root, 'docs/architecture'),
      name => name.endsWith('.md') && name !== 'README.md',
    ),
    ...matchingFiles(
      path.join(root, 'docs/design'),
      name => name.endsWith('.md') && name !== 'README.md',
    ),
  );

  records.push(...discoverThemeRecordCandidates(root).records);
  records.push(...discoverPackageArchitectureRecords(root));

  records.push(
    ...matchingFilesRecursively(
      path.join(root, COMPONENT_SPEC_ROOT),
      (_name, candidate) =>
        isComponentSpecRecordPath(
          path.relative(root, candidate).split(path.sep).join('/'),
        ),
      {skipDirectory: isIgnoredComponentKnowledgeSegment},
    ),
  );

  return records.sort();
}

/**
 * Platform implementation records:
 * `docs/specs/components/<ComponentRoot>/<PublicName>.<language>.spec.md`.
 */
export function discoverPlatformComponentRecords(root = DEFAULT_ROOT) {
  return matchingFilesRecursively(
    path.join(root, COMPONENT_SPEC_ROOT),
    (_name, candidate) =>
      isPlatformComponentSpecPath(
        path.relative(root, candidate).split(path.sep).join('/'),
      ),
    {skipDirectory: isIgnoredComponentKnowledgeSegment},
  ).sort();
}

/**
 * What only a platform record has, checked after the record loop has read every
 * id: `platform_of` names the core component, the core record beside it
 * declares that id, and its `verified_by` paths exist. `ids` maps every record
 * id to its path and authority.
 */
export function validatePlatformComponentRecords(root, {ids, repositoryFiles}) {
  const problems = [];
  const tracked = repositoryFiles ? new Set(repositoryFiles) : null;
  for (const absolutePath of discoverPlatformComponentRecords(root)) {
    const filePath = path
      .relative(root, absolutePath)
      .split(path.sep)
      .join('/');
    const {componentRoot, publicName} =
      classifyPlatformComponentSpecPath(filePath);
    const {frontmatter} = parseKnowledgeDocument(
      fs.readFileSync(absolutePath, 'utf8'),
      filePath,
    );
    if (frontmatter.get('kind') !== 'component') {
      problems.push(`${filePath}: a platform record must be kind: component.`);
    }
    const coreId = `component:${publicName}`;
    if (frontmatter.get('platform_of') !== coreId) {
      problems.push(
        `${filePath}: platform_of must name the core component, ${coreId}.`,
      );
    }
    const corePath = `${COMPONENT_SPEC_ROOT}/${componentRoot}/${publicName}.spec.md`;
    // Placed like the core record it implements, whether or not that record
    // exists yet.
    const location = componentRecordLocation(root, path.join(root, corePath));
    if (!location) {
      problems.push(
        `${filePath}: platform records must live at ${COMPONENT_SPEC_ROOT}/<ComponentRoot>/, where exactly one registered component package owns <ComponentRoot>.`,
      );
    } else {
      const placement = componentNamePlacement(root, location, publicName);
      if (placement.missingFlatExport) {
        problems.push(
          `${filePath}: platform record for ${publicName} must match a public named export and TSX module in packages/${location.packageName}/src.`,
        );
      }
      if (placement.outsideRoot) {
        problems.push(
          `${filePath}: platform record for ${publicName} must match component root ${JSON.stringify(componentRoot)} or an exact public component entry in that root's consumer docs.`,
        );
      }
    }
    if (fs.existsSync(path.join(root, corePath))) {
      const core = ids.get(coreId);
      if (!core || core.filePath.split(path.sep).join('/') !== corePath) {
        problems.push(
          `${filePath}: the core record beside it, ${corePath}, must declare id ${coreId}.`,
        );
      }
    }
    const verifiedBy = frontmatter.get('verified_by');
    for (const entry of Array.isArray(verifiedBy) ? verifiedBy : []) {
      const cited = String(entry).replace(/\/+$/, '');
      const exists = tracked
        ? tracked.has(cited) ||
          [...tracked].some(file => file.startsWith(`${cited}/`))
        : fs.existsSync(path.join(root, cited));
      if (!exists) {
        problems.push(
          `${filePath}: verified_by path ${entry} is not in the repository.`,
        );
      }
    }
  }
  return problems;
}

/**
 * Spec files outside the component record layout: a `*.spec.md` left in a
 * registered component package's source tree, and a `*.spec.md` under
 * `docs/specs/components/` that is neither a component or module record nor a
 * platform implementation's `<PublicName>.<language>.spec.md`.
 */
export function discoverMisplacedComponentSpecs(root = DEFAULT_ROOT) {
  const problems = [];
  const toPosix = candidate =>
    path.relative(root, candidate).split(path.sep).join('/');
  const isSpecFile = name =>
    name.endsWith('.spec.md') && !name.endsWith('.generated.spec.md');

  for (const packageName of COMPONENT_PACKAGE_NAMES) {
    const sourceRoot = path.join(root, `packages/${packageName}/src`);
    for (const candidate of matchingFilesRecursively(
      sourceRoot,
      name => isSpecFile(name) && !name.startsWith('.'),
      {skipDirectory: isIgnoredComponentKnowledgeSegment},
    )) {
      const relativeToSource = path
        .relative(sourceRoot, candidate)
        .split(path.sep)
        .join('/');
      problems.push(
        `${toPosix(candidate)}: component records live under ${COMPONENT_SPEC_ROOT}/; move this record to ${componentSpecPathForSource(packageName, relativeToSource)}.`,
      );
    }
  }

  const nativeSources = path.join(root, PLATFORM_SOURCE_ROOTS.swift);
  for (const candidate of matchingFilesRecursively(
    nativeSources,
    name => isSpecFile(name) && !name.startsWith('.'),
    {skipDirectory: isIgnoredComponentKnowledgeSegment},
  )) {
    const relative = path
      .relative(nativeSources, candidate)
      .split(path.sep)
      .join('/')
      .split('/');
    // Sources/<Module>/<ComponentRoot>/.../<Name>.spec.md
    const componentRoot =
      relative.length >= 3 ? relative[1] : '<ComponentRoot>';
    const name = relative.at(-1).slice(0, -'.spec.md'.length);
    problems.push(
      `${toPosix(candidate)}: Swift component records live beside the core record; move this record to ${COMPONENT_SPEC_ROOT}/${componentRoot}/${name}.swift.spec.md.`,
    );
  }

  for (const candidate of matchingFilesRecursively(
    path.join(root, COMPONENT_SPEC_ROOT),
    name => isSpecFile(name) && !name.startsWith('.'),
    {skipDirectory: isIgnoredComponentKnowledgeSegment},
  )) {
    const filePath = toPosix(candidate);
    if (isComponentSpecRecordPath(filePath)) continue;
    if (isPlatformComponentSpecPath(filePath)) continue;
    problems.push(
      `${filePath}: a file under ${COMPONENT_SPEC_ROOT}/ must be <ComponentRoot>/<PublicName>.spec.md, a module record nested below it, or a platform record <ComponentRoot>/<PublicName>.<language>.spec.md.`,
    );
  }

  return problems;
}

function componentRecordLocation(root, absolutePath) {
  const filePath = path.relative(root, absolutePath).split(path.sep).join('/');
  const location = locateComponentKnowledgePath(root, filePath);
  if (!location) return null;
  return {
    ...location,
    componentRootPath: path.join(root, location.componentRootDirectory),
    componentSourcePath: path.join(root, location.componentSourceDirectory),
  };
}

function isFullConsumerDocEntry(entry) {
  return (
    entry != null &&
    typeof entry === 'object' &&
    (typeof entry.description === 'string' ||
      Array.isArray(entry.props) ||
      Array.isArray(entry.params) ||
      Array.isArray(entry.returns) ||
      entry.usage != null)
  );
}

/**
 * Public names one consumer doc defines: its own `name` and its full
 * `components` entries, as `componentRootDefinesPublicComponent` reads them.
 * Anatomy parts and other nested `name` fields are not names.
 */
export function consumerDocPublicNames(docPath) {
  let mod;
  try {
    mod = require(docPath);
  } catch {
    return [];
  }
  const doc = mod.docs ?? mod.default;
  if (!doc) return [];
  const names = new Set();
  if (typeof doc.name === 'string') names.add(doc.name.replace(/^XDS/, ''));
  for (const entry of doc.components ?? []) {
    if (typeof entry?.name === 'string' && isFullConsumerDocEntry(entry)) {
      names.add(entry.name.replace(/^XDS/, ''));
    }
  }
  return [...names].sort();
}

/**
 * Whether a component record's public name fits where its folder places it: a
 * flat package exports it, and it is the component root or an exact public
 * component entry in that root's consumer docs.
 */
function componentNamePlacement(root, location, publicName) {
  return {
    missingFlatExport:
      location.layout === 'flat' &&
      !packageHasPublicComponent(root, location.packageName, publicName),
    outsideRoot:
      publicName !== location.componentRoot &&
      !componentRootDefinesPublicComponent(
        location.componentSourcePath,
        publicName,
      ),
  };
}

function componentRootDefinesPublicComponent(componentRootPath, publicName) {
  for (const docPath of matchingFilesRecursively(
    componentRootPath,
    name => name.endsWith('.doc.mjs'),
    {skipDirectory: isIgnoredComponentKnowledgeSegment},
  )) {
    let mod;
    try {
      mod = require(docPath);
    } catch {
      continue;
    }
    const doc = mod.docs ?? mod.default;
    if (!doc) continue;
    if (doc.name?.replace(/^XDS/, '') === publicName) return true;
    if (
      (doc.components ?? []).some(
        entry =>
          entry?.name?.replace(/^XDS/, '') === publicName &&
          isFullConsumerDocEntry(entry),
      )
    ) {
      return true;
    }
  }
  return false;
}

function activeRecord(record, activeAuthorities) {
  return activeAuthorities.includes(
    record.document.frontmatter.get('authority'),
  );
}

/**
 * Validate the explicit two-way ownership graph between component and module
 * records. This is structural metadata, not broad coverage enforcement: a
 * component with `modules: []` is valid, and private helpers need no record.
 */
export function validateComponentModuleRelationships(
  root,
  records,
  activeAuthorities = ['draft', 'current'],
) {
  const problems = [];
  const recordsById = new Map();

  for (const record of records) {
    const id = record.document.frontmatter.get('id');
    if (typeof id !== 'string') continue;
    const matches = recordsById.get(id) ?? [];
    matches.push(record);
    recordsById.set(id, matches);
  }

  for (const record of records) {
    const {frontmatter} = record.document;
    const kind = frontmatter.get('kind');
    if (kind !== 'component' && kind !== 'module') continue;

    const location = componentRecordLocation(root, record.absolutePath);
    if (!location) {
      problems.push(
        `${record.filePath}: ${kind} records must live at ${COMPONENT_SPEC_ROOT}/<ComponentRoot>/, where exactly one registered component package owns <ComponentRoot>.`,
      );
      continue;
    }

    const publicName = location.publicName;
    if (kind === 'component') {
      if (location.kind !== 'component') {
        problems.push(
          `${record.filePath}: component records must be direct children of their component root; nested records use kind: module.`,
        );
      }
      const expectedId = `component:${publicName}`;
      if (frontmatter.get('id') !== expectedId) {
        problems.push(
          `${record.filePath}: component record id must be ${expectedId} to match its filename.`,
        );
      }
      const placement = componentNamePlacement(root, location, publicName);
      if (placement.missingFlatExport) {
        problems.push(
          `${record.filePath}: flat-package component record ${expectedId} must match a public named export and TSX module in packages/${location.packageName}/src.`,
        );
      }
      if (placement.outsideRoot) {
        problems.push(
          `${record.filePath}: flat component record ${expectedId} must match component root ${JSON.stringify(location.componentRoot)} or an exact public component entry in that root's consumer docs.`,
        );
      }
      continue;
    }

    if (location.kind !== 'module') {
      problems.push(
        `${record.filePath}: module records must be nested beneath their component root; direct children are reserved for component records.`,
      );
    }
    const id = frontmatter.get('id');
    const idMatch = typeof id === 'string' ? MODULE_ID_PATTERN.exec(id) : null;
    if (!idMatch) continue;
    const expectedParent = `component:${idMatch[1]}`;
    if (location.layout === 'flat' && location.componentRoot !== idMatch[1]) {
      problems.push(
        `${record.filePath}: flat-package module ${id} must live under ${COMPONENT_SPEC_ROOT}/${idMatch[1]}/ to match its parent component.`,
      );
    }
    if (frontmatter.get('parent_component') !== expectedParent) {
      problems.push(
        `${record.filePath}: parent_component must be ${expectedParent} to match module id ${id}.`,
      );
    }
    if (publicName !== idMatch[2]) {
      problems.push(
        `${record.filePath}: module filename must be ${idMatch[2]}.spec.md to match id ${id}.`,
      );
    }
  }

  for (const record of records) {
    if (!activeRecord(record, activeAuthorities)) continue;
    const {frontmatter} = record.document;
    const kind = frontmatter.get('kind');
    const id = frontmatter.get('id');
    const location = componentRecordLocation(root, record.absolutePath);
    if (!location || typeof id !== 'string') continue;

    if (kind === 'component') {
      const modules = frontmatter.get('modules');
      if (!Array.isArray(modules)) continue;
      const seen = new Set();
      for (const moduleId of modules) {
        if (seen.has(moduleId)) {
          problems.push(
            `${record.filePath}: modules contains duplicate reference ${moduleId}.`,
          );
          continue;
        }
        seen.add(moduleId);

        const targets = recordsById.get(moduleId) ?? [];
        if (targets.length === 0) {
          problems.push(
            `${record.filePath}: modules reference ${moduleId} does not resolve to an active module record.`,
          );
          continue;
        }
        if (targets.length > 1) continue;
        const target = targets[0];
        if (target.document.frontmatter.get('kind') !== 'module') {
          problems.push(
            `${record.filePath}: modules reference ${moduleId} must resolve to a module record, not ${target.document.frontmatter.get('kind')}.`,
          );
          continue;
        }
        if (!activeRecord(target, activeAuthorities)) {
          problems.push(
            `${record.filePath}: modules reference ${moduleId} must resolve to an active module record.`,
          );
          continue;
        }
        if (target.document.frontmatter.get('parent_component') !== id) {
          problems.push(
            `${record.filePath}: modules reference ${moduleId}, but that module declares parent_component ${JSON.stringify(target.document.frontmatter.get('parent_component'))}.`,
          );
        }
        const targetLocation = componentRecordLocation(
          root,
          target.absolutePath,
        );
        if (
          targetLocation &&
          path.resolve(targetLocation.componentRootPath) !==
            path.resolve(location.componentRootPath)
        ) {
          problems.push(
            `${record.filePath}: module ${moduleId} must live in the same component root as its parent record (${target.filePath}).`,
          );
        }
      }
      continue;
    }

    if (kind !== 'module') continue;
    const parentId = frontmatter.get('parent_component');
    if (typeof parentId !== 'string') continue;
    const parents = recordsById.get(parentId) ?? [];
    if (parents.length === 0) {
      problems.push(
        `${record.filePath}: parent_component ${parentId} does not resolve to an active component record.`,
      );
      continue;
    }
    if (parents.length > 1) continue;
    const parent = parents[0];
    if (parent.document.frontmatter.get('kind') !== 'component') {
      problems.push(
        `${record.filePath}: parent_component ${parentId} must resolve to a component record, not ${parent.document.frontmatter.get('kind')}.`,
      );
      continue;
    }
    if (!activeRecord(parent, activeAuthorities)) {
      problems.push(
        `${record.filePath}: parent_component ${parentId} must resolve to an active component record.`,
      );
      continue;
    }

    const parentLocation = componentRecordLocation(root, parent.absolutePath);
    if (
      parentLocation &&
      path.resolve(parentLocation.componentRootPath) !==
        path.resolve(location.componentRootPath)
    ) {
      problems.push(
        `${record.filePath}: parent_component ${parentId} must be declared in the same component root (${parent.filePath}).`,
      );
    }

    const backlinks = Array.isArray(parent.document.frontmatter.get('modules'))
      ? parent.document.frontmatter
          .get('modules')
          .filter(moduleId => moduleId === id).length
      : 0;
    if (backlinks === 0) {
      problems.push(
        `${record.filePath}: module ${id} is orphaned; ${parent.filePath} must list it in modules.`,
      );
    } else if (backlinks > 1) {
      problems.push(
        `${record.filePath}: module ${id} is listed more than once by ${parent.filePath}.`,
      );
    }
  }

  return problems;
}

export function parseAnatomyThemingBlock(
  content,
  filePath = '<component spec>',
) {
  const heading = /^### Theming anatomy\s*$/gm;
  const headings = [...content.matchAll(heading)];
  if (headings.length === 0) return {mapping: null, problems: []};
  if (headings.length > 1) {
    return {
      mapping: null,
      problems: [`${filePath}: duplicate "Theming anatomy" subsection.`],
    };
  }

  const precedingSections = [
    ...content.slice(0, headings[0].index).matchAll(/^## (.+?)\s*$/gm),
  ];
  if (precedingSections.at(-1)?.[1] !== 'Design relationships') {
    return {
      mapping: null,
      problems: [
        `${filePath}: "Theming anatomy" must be a level-three subsection of "Design relationships".`,
      ],
    };
  }

  const start = headings[0].index + headings[0][0].length;
  const remainder = content.slice(start);
  const nextHeading = /^#{2,3} .+$/m.exec(remainder);
  const section =
    nextHeading == null ? remainder : remainder.slice(0, nextHeading.index);
  const blocks = [
    ...section.matchAll(
      /<!--\s*anatomy-theming:v1\s*-->\s*```json\s*\n([\s\S]*?)\n```/g,
    ),
  ];
  if (blocks.length !== 1) {
    return {
      mapping: null,
      problems: [
        `${filePath}: "Theming anatomy" must contain exactly one <!-- anatomy-theming:v1 --> JSON block.`,
      ],
    };
  }

  try {
    return {mapping: JSON.parse(blocks[0][1]), problems: []};
  } catch (error) {
    return {
      mapping: null,
      problems: [
        `${filePath}: anatomy-theming:v1 is not valid JSON (${error.message}).`,
      ],
    };
  }
}

const THEME_TARGET_NAME = /^(?!astryx-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
const THEMING_DISPOSITIONS = ['target', 'inherits', 'delegatesTo', 'none'];
const NONE_REASON_PREFIX = /^(?:intentional|reachability-gap|unsettled):\s+\S/;

function exactObjectKeys(value, expected) {
  return (
    value != null &&
    typeof value === 'object' &&
    !Array.isArray(value) &&
    Object.keys(value).sort().join('\0') === [...expected].sort().join('\0')
  );
}

function isNonEmptyString(value) {
  return typeof value === 'string' && value.trim().length > 0;
}

function validateTargetName(target, where, problems) {
  if (!isNonEmptyString(target)) {
    problems.push(`${where}: target is required.`);
  } else if (!THEME_TARGET_NAME.test(target)) {
    problems.push(
      `${where}: target must omit the "astryx-" prefix and use kebab-case.`,
    );
  }
}

/**
 * Validate one parsed anatomy-theming:v1 map against the component's public
 * anatomy and target inventory.
 */
export function validateAnatomyThemingMap(
  mapping,
  contract,
  filePath = '<component spec>',
) {
  const problems = [];
  if (
    mapping == null ||
    typeof mapping !== 'object' ||
    Array.isArray(mapping)
  ) {
    return [`${filePath}: anatomy-theming:v1 must be a JSON object.`];
  }

  const declaredParts = Object.keys(mapping).sort();
  const anatomyParts = [...contract.anatomy].sort();
  const missing = anatomyParts.filter(part => !declaredParts.includes(part));
  const extra = declaredParts.filter(part => !anatomyParts.includes(part));
  if (missing.length > 0) {
    problems.push(
      `${filePath}: theming anatomy is missing ${missing.join(', ')}.`,
    );
  }
  if (extra.length > 0) {
    problems.push(
      `${filePath}: theming anatomy has unknown ${extra.join(', ')}.`,
    );
  }

  const ownedTargets = new Set();
  for (const [part, disposition] of Object.entries(mapping)) {
    const where = `${filePath}: theming anatomy ${JSON.stringify(part)}`;
    if (
      disposition == null ||
      typeof disposition !== 'object' ||
      Array.isArray(disposition)
    ) {
      problems.push(`${where} must be an object.`);
      continue;
    }

    const keys = Object.keys(disposition);
    const selected = THEMING_DISPOSITIONS.filter(key => key in disposition);
    if (selected.length !== 1 || keys.length !== 1) {
      problems.push(
        `${where} must declare exactly one of target, inherits, delegatesTo, or none.`,
      );
      continue;
    }

    const kind = selected[0];
    if (kind === 'target' || kind === 'inherits') {
      const target = disposition[kind];
      validateTargetName(target, `${where}.${kind}`, problems);
      if (
        isNonEmptyString(target) &&
        THEME_TARGET_NAME.test(target) &&
        !contract.targets.includes(target)
      ) {
        problems.push(
          `${where}.${kind}: ${JSON.stringify(target)} is not a current target in the component doc.`,
        );
      }
      if (kind === 'target') ownedTargets.add(target);
      continue;
    }

    if (kind === 'delegatesTo') {
      const delegation = disposition.delegatesTo;
      if (!exactObjectKeys(delegation, ['owner', 'target'])) {
        problems.push(
          `${where}.delegatesTo requires exactly owner and target.`,
        );
        continue;
      }
      if (
        !isNonEmptyString(delegation.owner) ||
        !/^(component:[A-Z][A-Za-z0-9]*|family:[a-z0-9]+(?:-[a-z0-9]+)*)$/.test(
          delegation.owner,
        )
      ) {
        problems.push(
          `${where}.delegatesTo.owner must be component:<Name> or family:<id>.`,
        );
      }
      validateTargetName(
        delegation.target,
        `${where}.delegatesTo.target`,
        problems,
      );
      continue;
    }

    const none = disposition.none;
    if (!exactObjectKeys(none, ['reason']) || !isNonEmptyString(none.reason)) {
      problems.push(`${where}.none requires a non-empty reason.`);
    } else if (!NONE_REASON_PREFIX.test(none.reason)) {
      problems.push(
        `${where}.none.reason must start with intentional:, reachability-gap:, or unsettled:.`,
      );
    }
  }

  for (const target of contract.targets) {
    if (!ownedTargets.has(target)) {
      problems.push(
        `${filePath}: current target ${JSON.stringify(target)} has no anatomy entry with a target disposition.`,
      );
    }
  }

  return problems;
}

function collectDelegations(mapping, filePath) {
  const delegations = [];
  for (const [anatomy, disposition] of Object.entries(mapping)) {
    const delegation = disposition?.delegatesTo;
    if (!exactObjectKeys(delegation, ['owner', 'target'])) continue;
    if (
      !/^(component:[A-Z][A-Za-z0-9]*|family:[a-z0-9]+(?:-[a-z0-9]+)*)$/.test(
        delegation.owner,
      )
    )
      continue;
    if (!THEME_TARGET_NAME.test(delegation.target)) continue;
    delegations.push({
      filePath,
      anatomy,
      owner: delegation.owner,
      target: delegation.target,
    });
  }
  return delegations;
}

/**
 * Validate delegatesTo pairs against the CLI's canonical active owner/target
 * inventory and active knowledge-family membership.
 */
export function validateDelegations(
  delegations,
  canonicalTargets,
  activeFamilies = new Map(),
) {
  const targetsByOwner = new Map();
  const ownersByTarget = new Map();
  for (const {component, key} of canonicalTargets) {
    const owner = `component:${component.replace(/^XDS/, '')}`;
    const targets = targetsByOwner.get(owner) ?? new Set();
    targets.add(key);
    targetsByOwner.set(owner, targets);
    const owners = ownersByTarget.get(key) ?? new Set();
    owners.add(owner);
    ownersByTarget.set(key, owners);
  }

  function targetOwnership(target) {
    const owners = [...(ownersByTarget.get(target) ?? [])]
      .sort()
      .map(value => JSON.stringify(value));
    return owners.length > 0
      ? ` canonical owner${owners.length === 1 ? '' : 's'} for target ${JSON.stringify(target)}: ${owners.join(', ')}.`
      : ` no active canonical owner declares target ${JSON.stringify(target)}.`;
  }

  const problems = [];
  for (const {filePath, anatomy, owner, target} of delegations) {
    const where = `${filePath}: theming anatomy ${JSON.stringify(anatomy)}.delegatesTo`;

    if (owner.startsWith('family:')) {
      const family = activeFamilies.get(owner);
      if (!family) {
        problems.push(
          `${where}: owner ${JSON.stringify(owner)} does not resolve to an active family record (target ${JSON.stringify(target)}).`,
        );
        continue;
      }

      const memberOwners = new Set(family.members);
      const matchingMembers = [
        ...(ownersByTarget.get(target) ?? new Set()),
      ].filter(member => memberOwners.has(member));
      if (matchingMembers.length === 0) {
        problems.push(
          `${where}: target ${JSON.stringify(target)} is not an active canonical target of any component in ${JSON.stringify(owner)} members (${family.filePath});${targetOwnership(target)}`,
        );
      }
      continue;
    }

    const ownedTargets = targetsByOwner.get(owner);
    if (!ownedTargets) {
      problems.push(
        `${where}: owner ${JSON.stringify(owner)} does not exist in the canonical active component target inventory;${targetOwnership(target)}`,
      );
      continue;
    }
    if (!ownedTargets.has(target)) {
      const available = [...ownedTargets]
        .sort()
        .map(value => JSON.stringify(value))
        .join(', ');
      problems.push(
        `${where}: target ${JSON.stringify(target)} is not an active target owned by ${JSON.stringify(owner)}; active targets for that owner: ${available};${targetOwnership(target)}`,
      );
    }
  }
  return problems;
}

function loadComponentContract(root, specPath, componentName) {
  const location = componentRecordLocation(root, specPath);
  if (!location) {
    return {
      problem: `${path.relative(root, specPath)}: component record is outside a component root.`,
    };
  }
  const directory = path.join(root, location.codeDirectory);
  for (const docPath of matchingFiles(directory, name =>
    name.endsWith('.doc.mjs'),
  )) {
    let mod;
    try {
      mod = require(docPath);
    } catch (error) {
      return {
        problem: `${path.relative(root, docPath)}: could not load component doc (${error.message}).`,
      };
    }
    const doc = mod.docs ?? mod.default;
    if (!doc) continue;
    const candidates = [doc, ...(doc.components ?? [])];
    const candidate = candidates.find(
      entry => entry?.name?.replace(/^XDS/, '') === componentName,
    );
    if (!candidate) continue;
    const anatomy = candidate.usage?.anatomy ?? doc.usage?.anatomy;
    if (!Array.isArray(anatomy)) {
      return {
        problem: `${path.relative(root, docPath)}: ${componentName} has no canonical English usage.anatomy.`,
      };
    }
    const targets = (
      candidate.theming?.targets ??
      doc.theming?.targets ??
      []
    ).map(target => target.className.replace(/^astryx-/, ''));
    return {
      contract: {
        anatomy: anatomy.map(part => part.name),
        targets,
      },
    };
  }
  return {
    problem: `${path.relative(root, specPath)}: no component doc for ${componentName}.`,
  };
}

function loadModuleContract(root, specPath, moduleName) {
  const location = componentRecordLocation(root, specPath);
  if (!location) {
    return {
      problem: `${path.relative(root, specPath)}: module record is outside a component root.`,
    };
  }

  const candidates = [];
  for (const docPath of matchingFilesRecursively(
    location.componentSourcePath,
    name => name.endsWith('.doc.mjs'),
    {skipDirectory: isIgnoredComponentKnowledgeSegment},
  )) {
    let mod;
    try {
      mod = require(docPath);
    } catch (error) {
      return {
        problem: `${path.relative(root, docPath)}: could not load component doc (${error.message}).`,
      };
    }
    const doc = mod.docs ?? mod.default;
    if (!doc) continue;
    if (doc.name?.replace(/^XDS/, '') === moduleName) {
      candidates.push({docPath, doc});
    }
    for (const entry of doc.components ?? []) {
      if (
        entry?.name?.replace(/^XDS/, '') === moduleName &&
        isFullConsumerDocEntry(entry)
      ) {
        candidates.push({docPath, doc: entry});
      }
    }
  }

  if (candidates.length === 0) {
    return {
      problem: `${path.relative(root, specPath)}: no exact consumer doc entry for module ${moduleName}.`,
    };
  }
  if (candidates.length > 1) {
    return {
      problem: `${path.relative(root, specPath)}: module ${moduleName} has multiple consumer doc entries (${candidates.map(candidate => path.relative(root, candidate.docPath)).join(', ')}).`,
    };
  }

  const [{docPath, doc}] = candidates;
  if (!Array.isArray(doc.usage?.anatomy)) {
    return {
      problem: `${path.relative(root, docPath)}: ${moduleName} has no canonical English usage.anatomy; module records never inherit parent aggregate anatomy.`,
    };
  }
  const targets = (doc.theming?.targets ?? []).map(target =>
    target.className.replace(/^astryx-/, ''),
  );
  return {
    contract: {
      anatomy: doc.usage.anatomy.map(part => part.name),
      targets,
    },
  };
}

function validateAgainstSchema(
  document,
  schema,
  schemaPath,
  filePath,
  isTemplate,
  currentTemplateVersion,
  designApprovalOwners = [],
  engineeringApprovalOwners = [],
  {idPattern = null} = {},
) {
  const problems = [...document.problems];
  const {frontmatter, sections} = document;
  const kind = frontmatter.get('kind');
  const kindSchema = schema.kinds[kind];

  if (!kindSchema) {
    problems.push(
      `${filePath}: unknown knowledge kind ${JSON.stringify(kind)}.`,
    );
    return problems;
  }

  for (const field of kindSchema.requiredFrontmatter) {
    if (!frontmatter.has(field))
      problems.push(`${filePath}: missing frontmatter field ${field}.`);
  }
  for (const section of kindSchema.requiredSections) {
    if (!sections.includes(section))
      problems.push(`${filePath}: missing section "${section}".`);
  }

  const templateVersion = frontmatter.get('template_version');
  if (!Number.isInteger(templateVersion) || templateVersion < 1) {
    problems.push(`${filePath}: template_version must be a positive integer.`);
  } else if (templateVersion > currentTemplateVersion) {
    problems.push(
      `${filePath}: template_version ${templateVersion} is newer than ${currentTemplateVersion}.`,
    );
  }

  const schemaVersion = frontmatter.get('schema_version');
  if (schemaVersion !== schema.schemaVersion) {
    problems.push(
      `${filePath}: schema_version ${JSON.stringify(schemaVersion)} does not match ${schema.schemaVersion} from ${schemaPath}.`,
    );
  }

  for (const field of kindSchema.listFields ?? []) {
    if (!Array.isArray(frontmatter.get(field))) {
      problems.push(`${filePath}: ${field} must be a list.`);
    }
  }

  if (isTemplate) {
    if (templateVersion !== currentTemplateVersion) {
      problems.push(
        `${filePath}: template_version must equal ${currentTemplateVersion}.`,
      );
    }
    const extraFields = [...frontmatter.keys()].filter(
      field => !kindSchema.requiredFrontmatter.includes(field),
    );
    if (extraFields.length) {
      problems.push(
        `${filePath}: template fields are missing from the schema: ${extraFields.join(', ')}.`,
      );
    }
    const expectedSections = expectedTemplateSections(
      kind,
      kindSchema.requiredSections,
    );
    if (JSON.stringify(sections) !== JSON.stringify(expectedSections)) {
      problems.push(
        `${filePath}: template section order must exactly match the schema plus its allowed editorial sections; bump the schema and migrate active records for any other structural change.`,
      );
    }
    return problems;
  }

  for (const field of kindSchema.requiredNonEmptyStringFields ?? []) {
    const value = frontmatter.get(field);
    if (typeof value !== 'string' || value.trim().length === 0) {
      problems.push(`${filePath}: ${field} must be a non-empty string.`);
    }
  }

  const id = frontmatter.get('id');
  const expectedIdPattern = idPattern ?? kindSchema.idPattern;
  if (
    expectedIdPattern &&
    (typeof id !== 'string' || !new RegExp(expectedIdPattern).test(id))
  ) {
    problems.push(
      `${filePath}: id must match ${JSON.stringify(expectedIdPattern)}.`,
    );
  }

  if (kindSchema.requiredFrontmatter.includes('owners')) {
    const owners = frontmatter.get('owners');
    if (!Array.isArray(owners) || owners.length === 0) {
      problems.push(`${filePath}: owners must be a non-empty inline list.`);
    }
  }

  const authority = frontmatter.get('authority');
  if (!schema.authorities.includes(authority)) {
    problems.push(
      `${filePath}: authority must be ${schema.authorities.join(', ')}.`,
    );
  }
  if (authority === 'current') {
    for (const field of kindSchema.currentNonEmptyFields ?? []) {
      const value = frontmatter.get(field);
      if (!Array.isArray(value) || value.length === 0) {
        problems.push(
          `${filePath}: current records require non-empty ${field}.`,
        );
      }
    }
    const approvedBy = frontmatter.get('approved_by');
    const approvedAt = frontmatter.get('approved_at');
    const authorizedOwners =
      kind === 'design' || kind === 'theme'
        ? [...new Set([...engineeringApprovalOwners, ...designApprovalOwners])]
        : engineeringApprovalOwners;
    if (!authorizedOwners.includes(approvedBy)) {
      problems.push(
        `${filePath}: current records require approved_by to name an authorized owner.`,
      );
    }
    if (
      typeof approvedAt !== 'string' ||
      !/^\d{4}-\d{2}-\d{2}$/.test(approvedAt)
    ) {
      problems.push(
        `${filePath}: current records require approved_at as YYYY-MM-DD.`,
      );
    }
  }
  if (authority === 'archived') {
    const reason = frontmatter.get('archive_reason');
    if (!schema.archiveReasons.includes(reason)) {
      problems.push(
        `${filePath}: archived records require archive_reason (${schema.archiveReasons.join(', ')}).`,
      );
    }
    if (reason === 'superseded' && !frontmatter.get('superseded_by')) {
      problems.push(`${filePath}: superseded records require superseded_by.`);
    }
  }

  return problems;
}

export function validateSchemaEvolution(baseSchemas, currentSchemas) {
  const problems = [];
  let highestBaseVersion = -1;
  for (const [filePath, baseContent] of baseSchemas) {
    const match = filePath.match(/v([0-9]+)\.json$/);
    if (match)
      highestBaseVersion = Math.max(highestBaseVersion, Number(match[1]));
    if (!currentSchemas.has(filePath)) {
      problems.push(
        `${filePath}: versioned schemas are append-only and cannot be deleted.`,
      );
    } else if (currentSchemas.get(filePath) !== baseContent) {
      problems.push(
        `${filePath}: versioned schemas are immutable; add a new version and migrate active records.`,
      );
    }
  }
  for (const filePath of currentSchemas.keys()) {
    if (baseSchemas.has(filePath)) continue;
    const version = Number(filePath.match(/v([0-9]+)\.json$/)?.[1]);
    if (!Number.isInteger(version) || version <= highestBaseVersion) {
      problems.push(
        `${filePath}: new schema versions must be greater than ${highestBaseVersion}.`,
      );
    }
  }
  return problems;
}

function schemaFilesAtRevision(root, revision) {
  let output;
  try {
    output = execFileSync(
      'git',
      [
        '-C',
        root,
        'ls-tree',
        '-r',
        '--name-only',
        revision,
        '--',
        'docs/schemas/knowledge',
      ],
      {encoding: 'utf8'},
    );
  } catch (error) {
    throw new Error(`Could not read knowledge schemas at ${revision}.`, {
      cause: error,
    });
  }
  const schemas = new Map();
  for (const filePath of output
    .split(/\r?\n/)
    .filter(path => /^docs\/schemas\/knowledge\/v[0-9]+\.json$/.test(path))) {
    schemas.set(
      filePath,
      execFileSync('git', ['-C', root, 'show', `${revision}:${filePath}`], {
        encoding: 'utf8',
      }),
    );
  }
  return schemas;
}

function currentSchemaFiles(root) {
  return new Map(
    matchingFiles(path.join(root, 'docs/schemas/knowledge'), name =>
      /^v[0-9]+\.json$/.test(name),
    ).map(filePath => [
      path.relative(root, filePath),
      fs.readFileSync(filePath, 'utf8'),
    ]),
  );
}

export function composeKnowledgeSchemas(rawSchemas) {
  const composed = new Map();
  const latestKindVersions = new Map();

  function compose(version, stack = []) {
    if (composed.has(version)) return composed.get(version);
    const entry = rawSchemas.get(version);
    if (!entry) throw new Error(`Schema v${version} does not exist.`);
    if (stack.includes(version))
      throw new Error('Knowledge schema extends cycle.');
    const parentVersion = entry.schema.extends;
    const parent =
      parentVersion == null
        ? null
        : compose(parentVersion, [...stack, version]);
    const schema = parent
      ? {
          ...parent.schema,
          ...entry.schema,
          kinds: {...parent.schema.kinds, ...(entry.schema.kinds ?? {})},
        }
      : entry.schema;
    const result = {...entry, schema};
    composed.set(version, result);
    return result;
  }

  for (const version of [...rawSchemas.keys()].sort((a, b) => a - b)) {
    const entry = rawSchemas.get(version);
    compose(version);
    for (const kind of Object.keys(entry.schema.kinds ?? {})) {
      latestKindVersions.set(kind, version);
    }
  }
  return {schemas: composed, latestKindVersions};
}

export async function validateKnowledgeRoot(root = DEFAULT_ROOT) {
  const schemaDirectory = path.join(root, 'docs/schemas/knowledge');
  const rawSchemas = new Map(
    matchingFiles(schemaDirectory, name => /^v[0-9]+\.json$/.test(name)).map(
      schemaPath => {
        const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
        const fileVersion = Number(
          path.basename(schemaPath).match(/^v([0-9]+)\.json$/)[1],
        );
        if (schema.schemaVersion !== fileVersion) {
          throw new Error(
            `${path.relative(root, schemaPath)} declares schemaVersion ${schema.schemaVersion}; expected ${fileVersion}.`,
          );
        }
        return [schema.schemaVersion, {schema, schemaPath}];
      },
    ),
  );
  if (rawSchemas.size === 0)
    return ['docs/schemas/knowledge: no versioned schemas found.'];
  const {schemas, latestKindVersions} = composeKnowledgeSchemas(rawSchemas);
  const latestVersion = Math.max(...schemas.keys());
  const {schema} = schemas.get(latestVersion);
  const templateVersions = JSON.parse(
    fs.readFileSync(
      path.join(root, 'docs/templates/knowledge/versions.json'),
      'utf8',
    ),
  );
  const designOwnersPath = path.join(root, '.github/DESIGNOWNERS');
  const designApprovalOwners = fs.existsSync(designOwnersPath)
    ? parseOwnerFile(fs.readFileSync(designOwnersPath, 'utf8'))
    : [];
  const engineeringOwnersPath = path.join(root, '.github/ENGOWNERS');
  const engineeringApprovalOwners = fs.existsSync(engineeringOwnersPath)
    ? parseOwnerFile(fs.readFileSync(engineeringOwnersPath, 'utf8'))
    : [];
  const problems = [
    ...discoverThemeRecordCandidates(root).problems,
    ...discoverMisplacedComponentSpecs(root),
  ];
  const ids = new Map();
  const records = [];
  const delegations = [];
  const repositoryFiles = repositoryFileList(root);

  for (const [kind, kindSchema] of Object.entries(schema.kinds)) {
    const kindVersion = latestKindVersions.get(kind);
    const kindSchemaEntry = schemas.get(kindVersion);
    if (
      !Number.isInteger(templateVersions[kind]) ||
      templateVersions[kind] < 1
    ) {
      problems.push(
        `docs/templates/knowledge/versions.json: missing valid version for ${kind}.`,
      );
      continue;
    }
    const templatePath = path.join(root, kindSchema.template);
    if (!fs.existsSync(templatePath)) {
      problems.push(
        `${kindSchema.template}: template for ${kind} does not exist.`,
      );
      continue;
    }
    const templateContent = fs.readFileSync(templatePath, 'utf8');
    const template = parseKnowledgeDocument(
      templateContent,
      kindSchema.template,
    );
    problems.push(
      ...validateAgainstSchema(
        template,
        kindSchemaEntry.schema,
        path.relative(root, kindSchemaEntry.schemaPath),
        kindSchema.template,
        true,
        templateVersions[kind],
        designApprovalOwners,
        engineeringApprovalOwners,
      ),
    );
    if (template.frontmatter.get('kind') !== kind) {
      problems.push(`${kindSchema.template}: template kind must be ${kind}.`);
    }
    if (kind === 'component' || kind === 'module') {
      const designDecisions = parseDesignDecisionsBlock(
        templateContent,
        kindSchema.template,
      );
      problems.push(
        ...validateDesignDecisionsBlock(designDecisions, {
          allowHeaderOnly: true,
          filePath: kindSchema.template,
        }),
      );
    }
  }

  const platformRecordPaths = new Set(discoverPlatformComponentRecords(root));
  for (const absolutePath of [
    ...discoverKnowledgeRecords(root),
    ...platformRecordPaths,
  ]) {
    const filePath = path.relative(root, absolutePath);
    const content = fs.readFileSync(absolutePath, 'utf8');
    const document = parseKnowledgeDocument(content, filePath);
    // A platform record is checked like any record, with its
    // language-qualified id (`component:<language>/<PublicName>`).
    const platform = platformRecordPaths.has(absolutePath)
      ? classifyPlatformComponentSpecPath(filePath.split(path.sep).join('/'))
      : null;
    const pathApplicability = parsePathApplicabilityBlock(content, filePath);
    problems.push(
      ...pathApplicability.problems,
      ...validatePathApplicability(
        pathApplicability.config,
        filePath,
        repositoryFiles,
      ),
    );
    const reviewApplicability = parseReviewApplicabilityBlock(
      content,
      filePath,
    );
    problems.push(
      ...reviewApplicability.problems,
      ...validateReviewApplicability(
        reviewApplicability.config,
        content,
        filePath,
      ),
    );
    const recordVersion = document.frontmatter.get('schema_version');
    const versionedSchema = schemas.get(recordVersion);
    if (!versionedSchema) {
      problems.push(
        `${filePath}: schema_version ${JSON.stringify(recordVersion)} has no schema file.`,
      );
      continue;
    }
    problems.push(
      ...validateAgainstSchema(
        document,
        versionedSchema.schema,
        path.relative(root, versionedSchema.schemaPath),
        filePath,
        false,
        templateVersions[document.frontmatter.get('kind')],
        designApprovalOwners,
        engineeringApprovalOwners,
        platform
          ? {
              idPattern: `^component:${platform.language}/${platform.publicName}$`,
            }
          : {},
      ),
    );
    const authority = document.frontmatter.get('authority');
    const isActiveRecord =
      versionedSchema.schema.activeAuthorities.includes(authority);
    const kind = document.frontmatter.get('kind');
    const latestKindVersion = latestKindVersions.get(kind);
    if (isActiveRecord && recordVersion !== latestKindVersion) {
      problems.push(
        `${filePath}: active ${kind} records must use latest schema_version ${latestKindVersion} for that kind.`,
      );
    }
    const packageRecord = classifyPackageArchitectureRecordPath(
      filePath.split(path.sep).join('/'),
    );
    if (packageRecord) {
      if (kind !== 'architecture') {
        problems.push(
          `${filePath}: a record under packages/${packageRecord.packageName}/specs/ must be kind: architecture.`,
        );
      }
      if (document.frontmatter.get('id') !== packageRecord.id) {
        problems.push(
          `${filePath}: id must be ${packageRecord.id} to match its path.`,
        );
      }
    }
    if (kind === 'component' || kind === 'module') {
      const designDecisions = parseDesignDecisionsBlock(content, filePath);
      problems.push(
        ...validateDesignDecisionsBlock(designDecisions, {filePath}),
      );
      const parsed = parseAnatomyThemingBlock(content, filePath);
      problems.push(...parsed.problems);
      // Theme targets map a core component's anatomy; a platform record's
      // block is parsed but has no core contract to check against.
      if (parsed.mapping != null && !platform) {
        if (isActiveRecord) {
          delegations.push(...collectDelegations(parsed.mapping, filePath));
        }
        const recordName = String(document.frontmatter.get('id') ?? '')
          .replace(/^(?:component|module):/, '')
          .split('/')
          .at(-1);
        const loaded =
          kind === 'module'
            ? loadModuleContract(root, absolutePath, recordName)
            : loadComponentContract(root, absolutePath, recordName);
        if (loaded.problem) {
          problems.push(loaded.problem);
        } else {
          problems.push(
            ...validateAnatomyThemingMap(
              parsed.mapping,
              loaded.contract,
              filePath,
            ),
          );
        }
      }
    }
    const id = document.frontmatter.get('id');
    if (id) {
      if (ids.has(id))
        problems.push(
          `${filePath}: duplicate id ${id}; first declared in ${ids.get(id).filePath}.`,
        );
      else {
        ids.set(id, {
          filePath,
          authority: document.frontmatter.get('authority'),
        });
      }
    }
    if (!platform) records.push({filePath, absolutePath, document});
  }

  problems.push(
    ...validatePlatformComponentRecords(root, {ids, repositoryFiles}),
    ...validateComponentModuleRelationships(
      root,
      records,
      schema.activeAuthorities,
    ),
  );

  if (delegations.length > 0) {
    const activeFamilies = new Map();
    for (const {filePath, document} of records) {
      const authority = document.frontmatter.get('authority');
      if (
        document.frontmatter.get('kind') !== 'family' ||
        !schema.activeAuthorities.includes(authority)
      )
        continue;
      const id = document.frontmatter.get('id');
      const members = document.frontmatter.get('members');
      if (typeof id !== 'string' || !Array.isArray(members)) continue;
      if (!activeFamilies.has(id)) activeFamilies.set(id, {filePath, members});
    }

    const canonicalTargets = await collectThemingTargets(
      path.join(root, 'packages/core/src'),
    );
    problems.push(
      ...validateDelegations(delegations, canonicalTargets, activeFamilies),
    );
  }

  for (const {filePath, document} of records) {
    if (document.frontmatter.get('authority') !== 'current') continue;
    // An unknown kind is already reported above.
    const kindSchema = schema.kinds[document.frontmatter.get('kind')];
    for (const field of kindSchema?.referenceFields ?? []) {
      const references = document.frontmatter.get(field);
      if (!Array.isArray(references)) continue;
      for (const reference of references) {
        const targetId = reference.replace(/\/DEC-[0-9]+$/, '');
        const target = ids.get(targetId);
        if (!target) {
          problems.push(
            `${filePath}: ${field} reference ${reference} does not resolve.`,
          );
        } else if (target.authority !== 'current') {
          problems.push(
            `${filePath}: current records may not rely on non-current ${reference} (${target.filePath}).`,
          );
        }
      }
    }
  }

  if (repositoryFiles) {
    const {loadKnowledgeIndex, findUnreachedRecords} =
      await import('./specs-for-file.mjs');
    for (const record of findUnreachedRecords(
      loadKnowledgeIndex(root),
      repositoryFiles,
    )) {
      problems.push(
        `${record.path}: current record ${record.id} 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.`,
      );
    }
  }

  return problems;
}

async function main() {
  if (!repositoryFileList(DEFAULT_ROOT)) {
    console.warn(
      'Skipped the INV25 reachability and path-pattern match checks: `git ls-files` is unavailable here.',
    );
  }
  const problems = await validateKnowledgeRoot();
  const baseIndex = process.argv.indexOf('--base');
  if (baseIndex !== -1) {
    const baseRevision = process.argv[baseIndex + 1];
    if (!baseRevision) throw new Error('--base requires a revision.');
    problems.push(
      ...validateSchemaEvolution(
        schemaFilesAtRevision(DEFAULT_ROOT, baseRevision),
        currentSchemaFiles(DEFAULT_ROOT),
      ),
    );
    const repositoryFiles = repositoryFileList(DEFAULT_ROOT);
    const changes = repositoryFiles
      ? approvalLineRewritesSince(DEFAULT_ROOT, baseRevision, repositoryFiles)
      : [];
    for (const change of changes) {
      console.warn(
        `${change.path}: ${change.claim} changes from "${change.from}" to "${change.to ?? 'removed'}"; it needs ${change.decider}'s approval at the exact head (INV31).`,
      );
    }
  }
  if (problems.length) {
    console.error(`Knowledge validation failed (${problems.length}):\n`);
    for (const problem of problems) console.error(`- ${problem}`);
    process.exit(1);
  }
  console.log('Knowledge templates and records are aligned.');
}

// Not a top-level await: validation imports scripts/specs-for-file.mjs, which
// imports this module back, and that import must find it fully evaluated.
if (process.argv[1] === fileURLToPath(import.meta.url)) {
  main().catch(error => {
    console.error(error);
    process.exit(1);
  });
}