gstack/scripts/capture-baseline.ts

#!/usr/bin/env -S bun --no-env-file --config=/dev/null
/**
 * CLI for capturing a parity baseline snapshot.
 *
 * Usage:
 *   bun run scripts/capture-baseline.ts                            # default path
 *   bun run scripts/capture-baseline.ts --tag v1.44.1              # tag the snapshot
 *   bun run scripts/capture-baseline.ts --out path/to/baseline.json
 *
 * The default output path is test/fixtures/parity-baseline-<tag>.json,
 * or test/fixtures/parity-baseline-current.json when no tag is given.
 */

import * as fs from 'fs';
import * as path from 'path';
import { captureBaseline } from '../test/helpers/capture-parity-baseline';
import { PARITY_INVARIANTS } from '../test/helpers/parity-harness';

const ROOT = path.resolve(import.meta.dir, '..');

const USAGE = `Usage: bun run scripts/capture-baseline.ts [--tag <tag>] [--out <path>]

Captures a parity baseline snapshot of every SKILL.md and writes it to
test/fixtures/parity-baseline-<tag>.json (parity-baseline-current.json
without --tag), or to --out.`;

export type CaptureArgs = { help: true } | { help: false; tag?: string; out?: string };

export function parseCaptureArgs(argv: string[]): CaptureArgs {
  const parsed: { tag?: string; out?: string } = {};
  for (let i = 0; i < argv.length; i++) {
    const flag = argv[i]!;
    if (flag === '--help' || flag === '-h') return { help: true };
    if (flag !== '--tag' && flag !== '--out') throw new Error(`unknown argument "${flag}"`);
    const value = argv[++i];
    if (!value || value.startsWith('-')) throw new Error(`${flag} needs a value`);
    parsed[flag === '--tag' ? 'tag' : 'out'] = value;
  }
  return { help: false, ...parsed };
}

function main(): void {
  let args: CaptureArgs;
  try {
    args = parseCaptureArgs(process.argv.slice(2));
  } catch (err) {
    console.error(`capture-baseline: ${(err as Error).message}\n\n${USAGE}`);
    process.exit(2);
  }
  if (args.help) {
    console.log(USAGE);
    return;
  }
  const { tag } = args;
  const outPath = args.out
    ? path.resolve(args.out)
    : path.join(ROOT, 'test', 'fixtures', `parity-baseline-${tag ?? 'current'}.json`);

  const baseline = captureBaseline({
    repoRoot: ROOT,
    tag,
    // Carved skills record UNION bytes (skeleton + sections/*.md) so the
    // baseline measures the same thing parity-harness checks against.
    sectionedSkills: PARITY_INVARIANTS.filter(i => i.sectioned).map(i => i.skill),
  });

  fs.mkdirSync(path.dirname(outPath), { recursive: true });
  fs.writeFileSync(outPath, JSON.stringify(baseline, null, 2) + '\n');

  const totalKB = Math.round(baseline.totalCorpusBytes / 1024);
  const top3 = baseline.topHeaviest.slice(0, 3);
  console.log(`Parity baseline captured: ${outPath}`);
  console.log(`  tag:           ${baseline.tag}`);
  console.log(`  commit:        ${baseline.capturedFromCommit}`);
  console.log(`  branch:        ${baseline.capturedFromBranch}`);
  console.log(`  skills:        ${baseline.totalSkills}`);
  console.log(`  total corpus:  ${totalKB} KB`);
  console.log(`  catalog tokens: ~${baseline.estTotalCatalogTokens}`);
  console.log(`  top 3 heaviest:`);
  for (const s of top3) {
    const kb = Math.round(s.skillMdBytes / 1024);
    console.log(`    ${s.skill.padEnd(28)} ${kb} KB (${s.skillMdLines} lines, ~${s.estTokens} tokens)`);
  }
}

if (import.meta.main) main();