ms-ai-architect/scripts/kb-update/audit-corpus-headers.mjs

#!/usr/bin/env node
// audit-corpus-headers.mjs — Spor 1 Step 1: read-only audit of the corpus header state.
//
// Measures, per non-advisor reference file and in aggregate, the empirical ground
// truth the migration plan rests on: header-region **Verified:** values (clean date
// vs stale "MCP <date>"), body-duplicates and pipe-delimited meta rows inside the
// 500-byte header window, base-field presence (English **Last updated:**, **Status:**,
// title) and the header dialect (**Category:** / **Kategori:** / pipe). Mutates nothing.
//
// Usage:
//   node scripts/kb-update/audit-corpus-headers.mjs           # human summary
//   node scripts/kb-update/audit-corpus-headers.mjs --json    # full report to stdout
//   node scripts/kb-update/audit-corpus-headers.mjs --write   # persist data/corpus-header-audit.json

import { readdirSync, readFileSync, existsSync, realpathSync } from 'node:fs';
import { join, relative, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { atomicWriteJson } from './lib/atomic-write.mjs';

const __dirname = dirname(fileURLToPath(import.meta.url));
const PLUGIN_ROOT = join(__dirname, '..', '..');
const SKILLS_DIR = join(PLUGIN_ROOT, 'skills');
const OUT_PATH = join(__dirname, 'data', 'corpus-header-audit.json');

// The four non-advisor skills — advisor is out of audit scope (S-Cosmo: never mutated,
// and its header state is irrelevant to the Step-5/9 blast radius this audit pins).
const NON_ADVISOR_SKILLS = [
  'ms-ai-engineering',
  'ms-ai-governance',
  'ms-ai-infrastructure',
  'ms-ai-security',
];

// Mirrors kb-headers.mjs — the Port-1 contract reads only the top 500 bytes.
const HEADER_REGION_BYTES = 500;

// Base-field regexes mirror transform.mjs validateKbFile (RE_LAST_UPDATED:261 is not
// exported; replicated verbatim so the audit measures exactly what the guard reads).
const RE_TITLE = /^#\s+\S/m;
const RE_LAST_UPDATED = /\*\*Last updated:\*\*\s*[\d-]+/i;
const RE_STATUS = /\*\*Status:\*\*\s*\S/i;

// Verified value = everything after the label up to a pipe separator or line end,
// so "MCP 2026-06" survives intact while a pipe row stops at its sibling token.
const RE_VERIFIED = /\*\*Verified:\*\*\s*([^|\n]*)/;
const RE_CLEAN_DATE = /^\d{4}-\d{2}(-\d{2})?$/;

/** Audit a single file's content. Pure. */
function auditContent(content) {
  const head = content.slice(0, HEADER_REGION_BYTES);

  const verifiedMatches = [...head.matchAll(new RegExp(RE_VERIFIED.source, 'g'))];
  let verified = null;
  if (verifiedMatches.length > 0) {
    const value = verifiedMatches[0][1].trim();
    const line = head.slice(0, verifiedMatches[0].index).split('\n').length - 1;
    const lineText = head.split('\n')[line] ?? '';
    verified = {
      value,
      isDate: RE_CLEAN_DATE.test(value),
      pipe: lineText.includes(' | '),
      duplicateWithinHeaderRegion: verifiedMatches.length > 1,
    };
  }

  let dialect = 'none';
  if (/\*\*[^*\n]+:\*\*[^\n]* \| \*\*/.test(head)) dialect = 'pipe';
  else if (/\*\*Category:\*\*/i.test(head)) dialect = 'category';
  else if (/\*\*Kategori:\*\*/i.test(head)) dialect = 'kategori';

  return {
    title: RE_TITLE.test(content),
    status: RE_STATUS.test(content),
    lastUpdatedEnglish: RE_LAST_UPDATED.test(content),
    dialect,
    verified,
  };
}

/**
 * Audit a batch of files. Pure + dependency-injected reader (validate-kb-file.mjs
 * pattern) so tests never touch disk. An unreadable file is reported, not thrown.
 *
 * @param {string[]} paths
 * @param {(p: string) => string} [readFile]
 * @returns {{files: Record<string, object>, aggregate: object}}
 */
export function auditHeaders(paths, readFile = (p) => readFileSync(p, 'utf8')) {
  const files = {};
  const aggregate = {
    files: 0,
    readErrors: 0,
    verifiedPresent: 0,
    verifiedDate: 0,
    verifiedNonDate: 0,
    verifiedPipe: 0,
    verifiedDuplicate: 0,
    missingTitle: 0,
    missingStatus: 0,
    missingEnglishLastUpdated: 0,
    dialects: { category: 0, kategori: 0, pipe: 0, none: 0 },
  };

  for (const path of paths ?? []) {
    aggregate.files++;
    let content;
    try {
      content = readFile(path);
    } catch (err) {
      files[path] = { error: err.message };
      aggregate.readErrors++;
      continue;
    }
    const r = auditContent(content);
    files[path] = r;
    if (r.verified) {
      aggregate.verifiedPresent++;
      if (r.verified.isDate) aggregate.verifiedDate++;
      else aggregate.verifiedNonDate++;
      if (r.verified.pipe) aggregate.verifiedPipe++;
      if (r.verified.duplicateWithinHeaderRegion) aggregate.verifiedDuplicate++;
    }
    if (!r.title) aggregate.missingTitle++;
    if (!r.status) aggregate.missingStatus++;
    if (!r.lastUpdatedEnglish) aggregate.missingEnglishLastUpdated++;
    aggregate.dialects[r.dialect]++;
  }

  return { files, aggregate };
}

// Walk directory recursively for .md files (build-registry.mjs shape).
function walkMd(dir) {
  const results = [];
  if (!existsSync(dir)) return results;
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) {
      results.push(...walkMd(full));
    } else if (entry.name.endsWith('.md') && entry.name !== 'SKILL.md') {
      results.push(full);
    }
  }
  return results;
}

function main(argv) {
  const json = argv.includes('--json');
  const write = argv.includes('--write');

  const paths = NON_ADVISOR_SKILLS
    .flatMap((skill) => walkMd(join(SKILLS_DIR, skill, 'references')))
    .sort();
  const report = auditHeaders(paths);

  // Re-key on plugin-relative paths for a stable, machine-diffable artifact.
  const relFiles = {};
  for (const [abs, r] of Object.entries(report.files)) {
    relFiles[relative(PLUGIN_ROOT, abs)] = r;
  }
  const out = { generated_by: 'audit-corpus-headers.mjs', files: relFiles, aggregate: report.aggregate };

  if (write) {
    atomicWriteJson(OUT_PATH, out);
    console.log(`Wrote ${relative(PLUGIN_ROOT, OUT_PATH)}`);
  }
  if (json) {
    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
  }
  if (!json) {
    const a = report.aggregate;
    console.log(`Corpus header audit — ${a.files} non-advisor reference files`);
    console.log(`  Verified header present: ${a.verifiedPresent} (date: ${a.verifiedDate}, stale non-date: ${a.verifiedNonDate})`);
    console.log(`  Verified pipe rows: ${a.verifiedPipe}, duplicates within 500B: ${a.verifiedDuplicate}`);
    console.log(`  Missing English Last updated: ${a.missingEnglishLastUpdated}`);
    console.log(`  Missing Status: ${a.missingStatus}`);
    console.log(`  Missing title: ${a.missingTitle}`);
    console.log(`  Dialects: category=${a.dialects.category} kategori=${a.dialects.kategori} pipe=${a.dialects.pipe} none=${a.dialects.none}`);
  }
}

const isMain = (() => {
  try {
    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
  } catch {
    return false;
  }
})();
if (isMain) main(process.argv.slice(2));