@pareto4/pp-core 1.13.0 → 1.17.1

package/scripts/update-size-baseline.cjs

@@ -4,309 +4,65 @@
 /**
  * @file update-size-baseline.cjs
  *
- * Regenerates the committed per-file size baselines
- * (`tests/workflow-size-baseline.json`, `tests/agent-size-baseline.json`) from
- * the current files.
+ * Regenerates the committed per-file workflow size baseline
+ * (`tests/workflow-size-baseline.json`) from the current workflow files.
  *
- * Workflow size budget policy (2026-10-11; per commit since pack 9): the guards
- * allow each commit a small DELTA BUDGET (config size_budget.*, see
- * scripts/lib/size-budget.cjs), so plans never run this script. It runs once per
- * phase, in the phase's closing commit (`--reason "phase NN close"`, from
- * execute-phase), and otherwise only when one commit must grow past the budget.
- * Because a raise is the review record of growth, RAISING any entry requires a
- * reason:
+ * Run via `npm run size:baseline` whenever a workflow file legitimately grows
+ * or shrinks.  Growth must still be justified in the PR; this script only
+ * records the new reality so the CI guard (issue #1074) can diff against it.
  *
- *   npm run size:baseline                         # lower / add / remove only
- *   npm run size:baseline -- --reason "<why>"     # also allowed to raise
- *
- * Without `--reason`, a run that would raise any entry is REFUSED: it exits
- * non-zero and writes nothing (neither baseline). With a reason, every raise is
- * recorded in the baseline file's `_rebaselines` array (newest last) as
- * `{ date, reason, deltas: [{ file, from, to, delta }] }` — the committed
- * review record of a deliberate growth.
- *
- * Idempotent: running it twice with no file changes produces no diff (a run
- * with nothing to raise never appends a `_rebaselines` entry).
+ * Idempotent: running it twice with no file changes produces no diff.
  */
 
 const fs = require('fs');
 const path = require('path');
-const { measureMdFiles, measureMdTree, WORKFLOWS_DIR } = require('./workflow-size.cjs');
+const { measureMdFiles, WORKFLOWS_DIR } = require('./workflow-size.cjs');
 
 const BASELINE_PATH = path.join(__dirname, '..', 'tests', 'workflow-size-baseline.json');
 const AGENTS_DIR = path.join(__dirname, '..', 'agents');
 const AGENT_BASELINE_PATH = path.join(__dirname, '..', 'tests', 'agent-size-baseline.json');
-const isPpAgent = (f) => f.startsWith('pp-');
-
-/** Key of the raise log inside a baseline file. Never a measured filename. */
-const REBASELINES_KEY = '_rebaselines';
-
-/**
- * Split a parsed baseline file into its size entries and its raise log.
- * Size entries are the numeric values; metadata keys (`_rebaselines`) are not
- * sizes and must never reach a guard as one.
- *
- * @param {object|null} raw - Parsed baseline JSON (null when absent).
- * @returns {{ sizes: Object<string, number>, rebaselines: Array<object> }}
- */
-function splitBaseline(raw) {
-  const sizes = {};
-  let rebaselines = [];
-  if (raw && typeof raw === 'object') {
-    for (const [key, value] of Object.entries(raw)) {
-      if (key === REBASELINES_KEY) rebaselines = value;
-      else sizes[key] = value;
-    }
-  }
-  return { sizes, rebaselines };
-}
-
-/**
- * Read and parse a baseline file; `null` when it does not exist.
- *
- * @param {string} filePath
- * @returns {object|null}
- */
-function readBaseline(filePath) {
-  let text;
-  try {
-    text = fs.readFileSync(filePath, 'utf-8');
-  } catch (err) {
-    if (err.code === 'ENOENT') return null;
-    throw err;
-  }
-  return JSON.parse(text);
-}
+const isGsdAgent = (f) => f.startsWith('pp-');
 
 /**
- * Serialize to the on-disk baseline format: size keys sorted, then the
- * `_rebaselines` log last; 2-space indent, trailing newline (a stable,
- * minimal-diff artifact).
+ * Serialize a size map to the on-disk baseline format: keys sorted, 2-space
+ * indent, trailing newline (so the file is a stable, minimal-diff artifact).
  *
  * @param {Object<string, number>} sizes
- * @param {Array<object>} [rebaselines]
  * @returns {string}
  */
-function serializeBaseline(sizes, rebaselines = []) {
+function serializeBaseline(sizes) {
   const sorted = {};
   for (const key of Object.keys(sizes).sort()) sorted[key] = sizes[key];
-  sorted[REBASELINES_KEY] = rebaselines;
   return JSON.stringify(sorted, null, 2) + '\n';
 }
 
 /**
- * Classify the difference between an old and a new size map.
- *
- * @param {Object<string, number>} oldSizes
- * @param {Object<string, number>} newSizes
- * @returns {{ raised: Array<{file:string,from:number,to:number,delta:number}>,
- *             lowered: Array<{file:string,from:number,to:number,delta:number}>,
- *             added: string[], removed: string[] }}
- */
-function diffSizes(oldSizes, newSizes) {
-  const raised = [];
-  const lowered = [];
-  const added = [];
-  for (const file of Object.keys(newSizes).sort()) {
-    if (!(file in oldSizes)) {
-      added.push(file);
-      continue;
-    }
-    const from = oldSizes[file];
-    const to = newSizes[file];
-    if (to > from) raised.push({ file, from, to, delta: to - from });
-    else if (to < from) lowered.push({ file, from, to, delta: from - to });
-  }
-  const removed = Object.keys(oldSizes).filter((f) => !(f in newSizes)).sort();
-  return { raised, lowered, added, removed };
-}
-
-/**
- * Validate a `_rebaselines` log. Returns a list of problems (empty = valid).
- * Every entry must carry an ISO date, a non-empty reason and a non-empty list
- * of positive deltas whose arithmetic holds; dates must be non-decreasing
- * (newest last).
- *
- * @param {unknown} log
- * @returns {string[]}
- */
-function validateRebaselineLog(log) {
-  if (!Array.isArray(log)) return [`${REBASELINES_KEY} must be an array, got ${JSON.stringify(log)}`];
-  const problems = [];
-  const isSize = (n) => Number.isInteger(n) && n >= 0;
-  let prevDate = '';
-  log.forEach((entry, i) => {
-    const at = `${REBASELINES_KEY}[${i}]`;
-    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-      problems.push(`${at} must be an object`);
-      return;
-    }
-    if (typeof entry.date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(entry.date)) {
-      problems.push(`${at}.date must be YYYY-MM-DD, got ${JSON.stringify(entry.date)}`);
-    } else {
-      if (entry.date < prevDate) problems.push(`${at}.date ${entry.date} is older than the entry before it (newest must be last)`);
-      prevDate = entry.date;
-    }
-    if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
-      problems.push(`${at}.reason must be a non-empty string`);
-    }
-    if (!Array.isArray(entry.deltas) || entry.deltas.length === 0) {
-      problems.push(`${at}.deltas must be a non-empty array`);
-      return;
-    }
-    entry.deltas.forEach((d, j) => {
-      const dat = `${at}.deltas[${j}]`;
-      if (!d || typeof d.file !== 'string' || d.file === '') problems.push(`${dat}.file must be a non-empty string`);
-      if (!d || !isSize(d.from) || !isSize(d.to)) problems.push(`${dat}.from/.to must be non-negative integers`);
-      else if (!Number.isInteger(d.delta) || d.delta <= 0 || d.delta !== d.to - d.from) {
-        problems.push(`${dat}.delta must be the positive difference to - from (${d.to - d.from}), got ${JSON.stringify(d.delta)}`);
-      }
-    });
-  });
-  return problems;
-}
-
-/**
- * Compute (but do not write) a regenerated baseline.
+ * Write a baseline file from the measured `.md` sizes in a directory.
  *
  * @param {object} [opts]
  * @param {string} [opts.dir]       - Directory to measure (default: workflows).
- * @param {string} [opts.outPath]   - Baseline file (default: workflow baseline).
- * @param {function(string): boolean} [opts.predicate] - File filter.
- * @param {function(string, function): Object<string, number>} [opts.measure] -
- *        Measurer (default: recursive `measureMdTree`; agents pass `measureMdFiles`).
- * @param {string} [opts.reason]    - Justification; required to raise any entry.
- * @param {string} [opts.today]     - Date stamp for a raise (default: today, UTC).
- * @returns {{ outPath: string, refused: boolean, count: number, content: string|null,
- *             change: ReturnType<typeof diffSizes> }}
+ * @param {string} [opts.outPath]   - Baseline file to write (default: workflow).
+ * @param {function(string): boolean} [opts.predicate] - Filename filter.
+ * @returns {{ outPath: string, count: number, content: string }}
  */
-function planBaseline({
-  dir = WORKFLOWS_DIR,
-  outPath = BASELINE_PATH,
-  predicate,
-  measure = measureMdTree,
-  reason,
-  today = new Date().toISOString().slice(0, 10),
-} = {}) {
-  const sizes = measure(dir, predicate);
-  const { sizes: oldSizes, rebaselines: oldLog } = splitBaseline(readBaseline(outPath));
-  const change = diffSizes(oldSizes, sizes);
-  const count = Object.keys(sizes).length;
-  const hasReason = typeof reason === 'string' && reason.trim() !== '';
-  if (change.raised.length > 0 && !hasReason) {
-    return { outPath, refused: true, count, content: null, change };
-  }
-  const log = Array.isArray(oldLog) ? [...oldLog] : [];
-  if (change.raised.length > 0) {
-    log.push({ date: today, reason: reason.trim(), deltas: change.raised });
-  }
-  return { outPath, refused: false, count, content: serializeBaseline(sizes, log), change };
-}
-
-/**
- * Regenerate one baseline file. A refused plan (a raise without a reason)
- * writes nothing.
- *
- * @param {Parameters<typeof planBaseline>[0]} [opts]
- * @returns {ReturnType<typeof planBaseline>}
- */
-function generateBaseline(opts = {}) {
-  const plan = planBaseline(opts);
-  if (!plan.refused) fs.writeFileSync(plan.outPath, plan.content);
-  return plan;
-}
-
-/**
- * Parse CLI arguments: only `--reason <text>` / `--reason=<text>`.
- *
- * @param {string[]} argv
- * @returns {{ reason?: string }}
- */
-function parseArgs(argv) {
-  const out = {};
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === '--reason') {
-      out.reason = argv[++i];
-      if (out.reason === undefined) throw new Error('--reason needs a value');
-    } else if (arg.startsWith('--reason=')) {
-      out.reason = arg.slice('--reason='.length);
-    } else {
-      throw new Error(`unknown argument: ${arg} (only --reason "<text>" is accepted)`);
-    }
-  }
-  if (out.reason !== undefined && out.reason.trim() === '') throw new Error('--reason must not be empty');
-  return out;
+function generateBaseline({ dir = WORKFLOWS_DIR, outPath = BASELINE_PATH, predicate } = {}) {
+  const sizes = measureMdFiles(dir, predicate);
+  const content = serializeBaseline(sizes);
+  fs.writeFileSync(outPath, content);
+  return { outPath, count: Object.keys(sizes).length, content };
 }
 
-const TARGETS = [
-  { label: 'workflow', dir: WORKFLOWS_DIR, outPath: BASELINE_PATH, measure: measureMdTree },
-  { label: 'agent', dir: AGENTS_DIR, outPath: AGENT_BASELINE_PATH, predicate: isPpAgent, measure: measureMdFiles },
-];
-
-/**
- * CLI entry. Plans every target first and writes only when none is refused,
- * so a refusal leaves BOTH baselines untouched.
- *
- * @param {string[]} argv
- * @param {object} [io]
- * @param {Array<object>} [io.targets]
- * @param {string} [io.today]
- * @param {NodeJS.WritableStream} [io.stdout]
- * @param {NodeJS.WritableStream} [io.stderr]
- * @returns {number} exit code
- */
-function main(argv, { targets = TARGETS, today, stdout = process.stdout, stderr = process.stderr } = {}) {
-  let args;
-  try {
-    args = parseArgs(argv);
-  } catch (err) {
-    stderr.write(`size:baseline: ${err.message}\n`);
-    return 2;
-  }
-  const plans = targets.map((t) => ({ t, plan: planBaseline({ ...t, reason: args.reason, today }) }));
-  const refused = plans.filter((p) => p.plan.refused);
-  if (refused.length > 0) {
-    const lines = refused.flatMap(({ t, plan }) =>
-      plan.change.raised.map((r) => `  - ${t.label}: ${r.file}: ${r.from} → ${r.to} (+${r.delta})`)
-    );
-    stderr.write(
-      'size:baseline: REFUSED — this run would RAISE baseline entries, which needs a reason:\n' +
-        `${lines.join('\n')}\n` +
-        'Shrink the file(s), or re-run with: npm run size:baseline -- --reason "<why this growth is needed>"\n' +
-        'Nothing was written.\n'
-    );
-    return 1;
-  }
-  for (const { t, plan } of plans) {
-    fs.writeFileSync(plan.outPath, plan.content);
-    const c = plan.change;
-    stdout.write(
-      `Wrote ${plan.count} ${t.label} sizes to ${path.relative(process.cwd(), plan.outPath)} ` +
-        `(raised ${c.raised.length}, lowered ${c.lowered.length}, added ${c.added.length}, removed ${c.removed.length})\n`
+if (require.main === module) {
+  const targets = [
+    { label: 'workflow', dir: WORKFLOWS_DIR, outPath: BASELINE_PATH },
+    { label: 'agent', dir: AGENTS_DIR, outPath: AGENT_BASELINE_PATH, predicate: isGsdAgent },
+  ];
+  for (const t of targets) {
+    const { outPath, count } = generateBaseline(t);
+    process.stdout.write(
+      `Wrote ${count} ${t.label} sizes to ${path.relative(process.cwd(), outPath)}\n`
     );
   }
-  if (args.reason !== undefined && plans.every((p) => p.plan.change.raised.length === 0)) {
-    stdout.write('Note: nothing was raised, so --reason was not recorded.\n');
-  }
-  return 0;
-}
-
-if (require.main === module) {
-  process.exitCode = main(process.argv.slice(2));
 }
 
-module.exports = {
-  generateBaseline,
-  planBaseline,
-  serializeBaseline,
-  splitBaseline,
-  readBaseline,
-  diffSizes,
-  validateRebaselineLog,
-  parseArgs,
-  main,
-  REBASELINES_KEY,
-  BASELINE_PATH,
-  AGENT_BASELINE_PATH,
-};
+module.exports = { generateBaseline, serializeBaseline, BASELINE_PATH, AGENT_BASELINE_PATH };