ms-ai-architect/scripts/kb-update/backfill-category.mjs

#!/usr/bin/env node
// Backfill **Category:** on the reference files that carry NO category label (R20).
//
// Deterministic folder→category rule (operator-approved taxonomy 2026-07-06): insert-only
// via the tested `insertMetaField` primitive, with a hard per-file invariant asserted BEFORE
// any write — exactly one line is inserted, it is the Category line, and the body is
// byte-identical. If any target falls outside the approved folder rule, or any file would
// change by more than that single line, the run aborts and writes nothing. Idempotent:
// files that already carry **Category:**/**Kategori:** are skipped, so a re-run is a no-op.
//
// The planning is factored into pure/importable pieces (categoryForFile + planCategoryBackfill)
// behind an isMain guard, so the frozen taxonomy and the plan can be tested without executing
// the corpus scan as an import side effect.
//
// Recovery contract: writes are crash-safe (atomicWriteSync tmp+rename — a reader sees the old
// file or the new one, never a partial); an interrupted run is recovered by re-running (idempotent).
//
// Usage:  node scripts/kb-update/backfill-category.mjs [--dry]
import { readFileSync, realpathSync } from 'node:fs';
import { execSync } from 'node:child_process';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { insertMetaField } from './lib/transform.mjs';
import { atomicWriteSync } from './lib/atomic-write.mjs';

const __dirname = dirname(fileURLToPath(import.meta.url));
const PLUGIN_ROOT = join(__dirname, '..', '..');

// Immediate-parent-directory basename → Category. Operator-approved 2026-07-06 (frozen).
export const FOLDER_CATEGORY = {
  architecture: 'Solution Architecture & Advisory',
  platforms: 'Microsoft AI Platforms',
  development: 'Microsoft AI Platforms',
  'responsible-ai': 'Responsible AI & Governance',
  'mlops-genaiops': 'MLOps & GenAIOps',
};

const RE_CAT = /^\s*\*\*(Category|Kategori):\*\*/im;

/**
 * The Category for a reference file, keyed on its immediate-parent folder. Pure.
 * @param {string} rel — plugin-relative path
 * @returns {string|null} the approved Category, or null when the folder is outside the rule
 */
export function categoryForFile(rel) {
  const folder = String(rel ?? '').split('/').slice(-2, -1)[0];
  return FOLDER_CATEGORY[folder] ?? null;
}

/**
 * Plan the Category backfill under `root` (reads files; performs NO writes). Discovers every
 * reference file, keeps only those missing a Category, and for each in an approved folder builds
 * the insert-only mutation behind the one-line/byte-identical invariant. Files outside the
 * approved folder rule are collected as `unmatched` (never planned for a write).
 * @param {string} root — corpus root (contains skills/…)
 * @returns {{files: string[], targets: string[], planned: {rel:string,cat:string,out:string}[], unmatched: string[]}}
 */
export function planCategoryBackfill(root) {
  const files = execSync("find skills/*/references -name '*.md'", { cwd: root, encoding: 'utf8' })
    .trim()
    .split('\n')
    .filter(Boolean);

  const targets = files.filter((rel) => !RE_CAT.test(readFileSync(join(root, rel), 'utf8')));

  const planned = [];
  const unmatched = [];
  for (const rel of targets) {
    const cat = categoryForFile(rel);
    if (!cat) {
      const folder = String(rel).split('/').slice(-2, -1)[0];
      unmatched.push(`${rel} (folder=${folder})`);
      continue;
    }
    const old = readFileSync(join(root, rel), 'utf8');
    const out = insertMetaField(old, 'Category', cat);
    // Hard invariant: exactly one line inserted (the Category line), body byte-identical.
    const o = old.split('\n');
    const n = out.split('\n');
    if (n.length !== o.length + 1) throw new Error(`ABORT ${rel}: not exactly one line inserted`);
    let d = 0;
    while (d < o.length && o[d] === n[d]) d++;
    if (n[d] !== `**Category:** ${cat}`) {
      throw new Error(`ABORT ${rel}: inserted line mismatch → ${JSON.stringify(n[d])}`);
    }
    if (o.slice(d).join('\n') !== n.slice(d + 1).join('\n')) {
      throw new Error(`ABORT ${rel}: body not byte-identical below the insertion`);
    }
    planned.push({ rel, cat, out });
  }
  return { files, targets, planned, unmatched };
}

function run({ root = PLUGIN_ROOT, dry }) {
  const { files, targets, planned, unmatched } = planCategoryBackfill(root);

  if (unmatched.length) {
    console.error(`ABORT — ${unmatched.length} target(s) outside the approved folder rule:`);
    unmatched.forEach((u) => console.error('  ' + u));
    process.exit(1);
  }

  const byCat = {};
  for (const p of planned) byCat[p.cat] = (byCat[p.cat] || 0) + 1;
  console.log(`Reference files: ${files.length} | without a category: ${targets.length} | planned: ${planned.length}`);
  console.log('By category:');
  for (const [c, n] of Object.entries(byCat).sort()) console.log(`  ${n}  ${c}`);

  if (dry) {
    console.log('\n(dry run — no writes)');
    return;
  }
  for (const p of planned) atomicWriteSync(join(root, p.rel), p.out);
  console.log(`\nWrote ${planned.length} files.`);
}

const isMain = (() => {
  try {
    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
  } catch {
    return false;
  }
})();
if (isMain) run({ dry: process.argv.includes('--dry') });