Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.7 KB
Raw Blame
/**
 * Shared runner for per-file count ratchets (D6 of docs/designs/RUST_ENGINE.md):
 * scripts/check-engine-raw-sql-ratchet.ts and scripts/check-engine-kind-branches.ts.
 *
 * A guard supplies a scanner that returns `path<TAB>metric -> count` for the
 * tree. The baseline holds rows `path<TAB>metric<TAB>count[<TAB>note]`. Counts
 * fall by default:
 *   1. a count above its row (no row = 0)            -> FAIL
 *   2. a count below its row (stale)                 -> FAIL
 *   3. a duplicate or malformed row                  -> FAIL
 * A row goes up only by a reviewer-visible edit in the same PR that raises the
 * count and writes the reason in the note column (as
 * scripts/module-size-limits.tsv does). `--prune` lowers stale rows to the
 * actual count, keeps their notes and drops rows at zero; it never raises a row
 * or adds one. `--print` writes the current counts as rows to stdout (used to
 * generate a baseline from the tree at its commit).
 */
import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';

export interface CountRatchet {
  /** Guard name used in output, e.g. `check-engine-raw-sql-ratchet`. */
  name: string;
  /** Script path for fix hints, e.g. `scripts/check-engine-raw-sql-ratchet.ts`. */
  script: string;
  baselineRel: string;
  anchor: string;
  metrics: readonly string[];
  /** One line: why the counts only fall. */
  why: string;
  /** What to do instead of adding a new site. */
  riseFix: string;
  scan(root: string): Map<string, number>;
}

export function tsFiles(dir: string): string[] {
  if (!existsSync(dir)) return [];
  const out: string[] = [];
  for (const entry of readdirSync(dir).sort()) {
    const full = join(dir, entry);
    if (statSync(full).isDirectory()) out.push(...tsFiles(full));
    else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts')) out.push(full);
  }
  return out;
}

interface Row { lineNo: number; key: string; count: number; note: string | undefined; malformed: string | null }

function parseBaseline(text: string, metrics: readonly string[]): Row[] {
  const rows: Row[] = [];
  text.split('\n').forEach((raw, i) => {
    if (raw.trim() === '' || raw.startsWith('#')) return;
    const cols = raw.split('\t');
    const [path, metric, count, note] = cols;
    let malformed: string | null = null;
    if (cols.length < 3 || cols.length > 4 || !path) malformed = "want 'path<TAB>metric<TAB>count' with an optional '<TAB>note'";
    else if (cols.length === 4 && note.trim() === '') malformed = 'the note column is empty (drop it, or say why the row was raised)';
    else if (!metrics.includes(metric)) malformed = 'unknown metric ' + JSON.stringify(metric) + ' (one of ' + metrics.join(', ') + ')';
    else if (!/^[1-9]\d*$/.test(count)) malformed = 'count must be a positive integer';
    rows.push({ lineNo: i + 1, key: path + '\t' + metric, count: Number(count), note, malformed });
  });
  return rows;
}

export function totals(actual: Map<string, number>, metrics: readonly string[]): { byMetric: Record<string, number>; all: number; files: number } {
  const byMetric = Object.fromEntries(metrics.map((m) => [m, 0])) as Record<string, number>;
  const files = new Set<string>();
  let all = 0;
  for (const [key, n] of actual) {
    const [path, metric] = key.split('\t');
    byMetric[metric] += n;
    all += n;
    files.add(path);
  }
  return { byMetric, all, files: files.size };
}

const RAISE_HINT = '\n      If the site must stay until its area is converted: raise the row (or add it) in this PR with a note column saying why.';

export function runCountRatchet(guard: CountRatchet, root: string, argv: string[]): never {
  const actual = guard.scan(root);
  if (argv.includes('--print')) {
    const keys = [...actual.keys()].sort();
    for (const key of keys) console.log(key + '\t' + actual.get(key));
    process.exit(0);
  }
  const prune = argv.includes('--prune');
  const baselinePath = join(root, guard.baselineRel);
  if (!existsSync(baselinePath)) {
    console.error('FAIL: ' + guard.baselineRel + ':1 baseline file missing');
    console.error('Fix:  git checkout ' + guard.baselineRel);
    console.error('See:  ' + guard.anchor);
    process.exit(1);
  }
  const baselineText = readFileSync(baselinePath, 'utf8');
  const rows = parseBaseline(baselineText, guard.metrics);
  const violations: string[] = [];
  const rewrite = new Map<number, string | null>();
  const seen = new Set<string>();
  const pruneHint = '(or: bun ' + guard.script + ' --prune)';

  for (const row of rows) {
    const where = guard.baselineRel + ':' + row.lineNo;
    if (row.malformed) {
      violations.push('FAIL: ' + where + ' malformed row: ' + row.malformed);
      continue;
    }
    const [path, metric] = row.key.split('\t');
    if (seen.has(row.key)) {
      rewrite.set(row.lineNo, null);
      violations.push('FAIL: ' + where + ' duplicate row for ' + path + ' ' + metric + '\n      Fix:  delete this line ' + pruneHint);
      continue;
    }
    seen.add(row.key);
    const now = actual.get(row.key) ?? 0;
    if (now > row.count) {
      violations.push('FAIL: ' + path + ' ' + metric + ': baseline ' + row.count + ', actual ' + now + '\n      Fix:  ' + guard.riseFix + RAISE_HINT);
    } else if (now < row.count) {
      rewrite.set(row.lineNo, now === 0 ? null : [path, metric, String(now), ...(row.note === undefined ? [] : [row.note])].join('\t'));
      violations.push('FAIL: ' + where + ' stale row: ' + path + ' ' + metric + ': baseline ' + row.count + ', actual ' + now
        + '\n      Fix:  lower the row to ' + now + (now === 0 ? ' (delete it)' : '') + '; counts only fall ' + pruneHint);
    }
  }
  for (const [key, now] of actual) {
    if (seen.has(key)) continue;
    const [path, metric] = key.split('\t');
    violations.push('FAIL: ' + path + ' ' + metric + ': baseline 0, actual ' + now + '\n      Fix:  ' + guard.riseFix + RAISE_HINT);
  }

  if (prune) {
    const kept: string[] = [];
    baselineText.split('\n').forEach((line, i) => {
      if (!rewrite.has(i + 1)) kept.push(line);
      else if (rewrite.get(i + 1) !== null) kept.push(rewrite.get(i + 1)!);
    });
    writeFileSync(baselinePath, kept.join('\n'));
    console.log(guard.name + ': pruned ' + rewrite.size + ' row(s) in ' + guard.baselineRel);
    process.exit(0);
  }
  if (violations.length) {
    for (const v of violations) console.error(v);
    console.error('Why:  ' + guard.why);
    console.error('See:  ' + guard.anchor);
    console.error(guard.name + ': ' + violations.length + ' violation(s)');
    process.exit(1);
  }
  const t = totals(actual, guard.metrics);
  console.log(guard.name + ': ok (' + t.all + ' sites in ' + t.files + ' files: ' + guard.metrics.map((m) => m + ' ' + t.byMetric[m]).join(', ') + ')');
  process.exit(0);
}