ms-ai-architect/scripts/kb-update/lib/taxonomy.mjs

// taxonomy.mjs — Loader + accessors for data/domain-taxonomy.json (lag 0).
// Zero dependencies. The taxonomy is the single source of truth for in-domain
// classification: which sitemaps to poll, which URLs are relevant, which
// skill/category owns content, and update priority. poll-sitemaps,
// discover-new-urls and report-changes READ this instead of embedding copies.

import { readFileSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

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

/**
 * Load the domain taxonomy from disk.
 * @param {string} [dataDir] — defaults to ../data/ relative to lib/
 * @returns {object} parsed taxonomy
 */
export function loadTaxonomy(dataDir = DEFAULT_DATA_DIR) {
  const path = join(dataDir, 'domain-taxonomy.json');
  return JSON.parse(readFileSync(path, 'utf8'));
}

/**
 * Target sitemap child-name prefixes to scan/poll.
 * @param {object} tax
 * @returns {string[]}
 */
export function getSitemapPrefixes(tax) {
  return tax.sitemap_prefixes;
}

/**
 * Canonical owning skill for a KB category (physical-disk truth).
 * @param {object} tax
 * @param {string} category
 * @returns {string|null} skill directory name, or null if unknown
 */
export function getCategorySkill(tax, category) {
  return tax.category_skill[category] ?? null;
}

/**
 * Build a URL classifier mirroring discover-new-urls semantics:
 * exclude wins; first include match → { skill, category } with skill DERIVED
 * from the canonical category_skill map (no embedded skill assignments).
 * @param {object} tax
 * @returns {(url: string) => ({skill: string|null, category: string}|null)}
 */
export function makeClassifier(tax) {
  const include = tax.relevance.include.map((r) => ({
    re: new RegExp(r.pattern),
    category: r.category,
  }));
  const exclude = tax.relevance.exclude.map((p) => new RegExp(p));

  return function classifyUrl(url) {
    if (exclude.some((re) => re.test(url))) return null;
    for (const rule of include) {
      if (rule.re.test(url)) {
        return { skill: tax.category_skill[rule.category] ?? null, category: rule.category };
      }
    }
    return null;
  };
}

/**
 * Build a file-priority function mirroring report-changes getFilePriority:
 * ordered regex rules over the lowercased path; first match wins; else default.
 *
 * A file with NO "Last updated:" header (hasDate=false) cannot have its currency
 * verified, so it lands in the dedicated `dateless` tier ('unverified') instead
 * of inheriting a path-based priority — otherwise dateless files flood the
 * critical bucket and drown the genuinely-stale critical files (carry-forward B).
 * hasDate defaults to true so existing single-arg callers keep path-based scoring.
 * @param {object} tax
 * @returns {(filePath: string, hasDate?: boolean) => string}
 */
export function makePriorityFn(tax) {
  const rules = tax.priority.rules.map((r) => ({ re: new RegExp(r.match), priority: r.priority }));
  const fallback = tax.priority.default;
  const datelessTier = tax.priority.dateless ?? fallback;

  return function getFilePriority(filePath, hasDate = true) {
    if (!hasDate) return datelessTier;
    const lower = filePath.toLowerCase();
    for (const r of rules) {
      if (r.re.test(lower)) return r.priority;
    }
    return fallback;
  };
}