@pareto4/pp-core 1.11.0 → 1.12.0

package/scripts/lib/size-budget.cjs

@@ -0,0 +1,311 @@
+'use strict';
+
+/**
+ * @file size-budget.cjs
+ *
+ * The per-commit size budget for workflow and agent markdown (pack 9, item 4).
+ *
+ * ## What is measured
+ *
+ * Every CHANGE since the baseline file was last committed, one at a time:
+ *   - each commit in `<last baseline commit>..HEAD` (at most MAX_COMMITS), against
+ *     its parent — for a merge commit, against the larger of each file's sizes in
+ *     its parents, so a merge adds nothing of its own and each plan commit is
+ *     judged on its own branch;
+ *   - the uncommitted edits under the guarded directory, against HEAD.
+ * A file's allowance base is the LARGER of its size before the change and its
+ * size in the committed baseline file. A change may grow one file by at most
+ * `per_file_bytes` and all files together by at most `per_commit_bytes`. So:
+ *   - a plan that grows a few files a little passes without touching the
+ *     baseline, however much the phase has grown in earlier plans;
+ *   - growth already recorded in the baseline (a justified re-baseline) passes;
+ *   - one change growing past the budget fails, by file and by total, and stays
+ *     red until it is shrunk or recorded — a later commit does not hide it.
+ * A file that is in neither the baseline nor the parent (a new file) is not
+ * budgeted; the tier, nested and new-file hard caps in the guard tests bound it.
+ *
+ * The cumulative growth of a phase is recorded once, at phase close:
+ * `npm run size:baseline -- --reason "phase NN close"` in the phase's closing
+ * commit, which also starts the next window. The tier hard caps stay absolute
+ * red lines.
+ *
+ * ## Why per commit, not against the baseline alone
+ *
+ * Measured against the committed baseline alone, the slack is spent cumulatively:
+ * a long phase whose plans each grow a different file by a few hundred bytes goes
+ * red part-way through, and from then on every plan re-baselines — the baseline
+ * becomes a file every plan touches, which serialises plans that are otherwise
+ * independent.
+ *
+ * ## Fallback
+ *
+ * Not a git checkout, or no HEAD: the check is the previous one — growth
+ * against the committed baseline with the same two numbers (`assertDeltaBudget`),
+ * new and removed files included. In a shallow clone, commits whose parent is
+ * missing are skipped (CI's `test` job clones with GitLab's default depth).
+ *
+ * ## The numbers
+ *
+ * `size_budget.per_file_bytes` (default 1024) and `size_budget.per_commit_bytes`
+ * (default 4096) — the schema defaults in
+ * `pp-core/bin/shared/config-defaults.manifest.json`, overridable in the
+ * repository's `.planning/config.json`. Nothing else holds them.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { assertDeltaBudget } = require('./allowlist-ratchet.cjs');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const DEFAULTS_MANIFEST = path.join(REPO_ROOT, 'pp-core', 'bin', 'shared', 'config-defaults.manifest.json');
+
+function isPositiveInt(v) {
+  return Number.isInteger(v) && v > 0;
+}
+
+/**
+ * The budget numbers: project `.planning/config.json` `size_budget.*` when set to
+ * positive integers, else the schema defaults from the manifest.
+ *
+ * @param {{ repoRoot?: string, manifestPath?: string }} [opts]
+ * @returns {{ perFileBytes: number, perCommitBytes: number, source: { perFileBytes: string, perCommitBytes: string } }}
+ */
+function readSizeBudget({ repoRoot = REPO_ROOT, manifestPath = DEFAULTS_MANIFEST } = {}) {
+  const defaults = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')).size_budget;
+  if (!defaults || !isPositiveInt(defaults.per_file_bytes) || !isPositiveInt(defaults.per_commit_bytes)) {
+    throw new Error(`${manifestPath} must define size_budget.per_file_bytes and size_budget.per_commit_bytes as positive integers`);
+  }
+  let project = {};
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(repoRoot, '.planning', 'config.json'), 'utf-8'));
+    if (cfg && typeof cfg.size_budget === 'object' && cfg.size_budget !== null) project = cfg.size_budget;
+  } catch {
+    // no project config: schema defaults apply
+  }
+  const pick = (key) =>
+    isPositiveInt(project[key])
+      ? { value: project[key], source: '.planning/config.json' }
+      : { value: defaults[key], source: 'schema default' };
+  const perFile = pick('per_file_bytes');
+  const perCommit = pick('per_commit_bytes');
+  return {
+    perFileBytes: perFile.value,
+    perCommitBytes: perCommit.value,
+    source: { perFileBytes: perFile.source, perCommitBytes: perCommit.source },
+  };
+}
+
+// A GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE inherited from a hook would point git at
+// another repository; the guarded directory decides which repository is meant.
+function git(cwd, args) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_')));
+  return execFileSync('git', args, { cwd, env, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+/** Cap on how many commits back the guard looks (a re-baseline resets the window). */
+const MAX_COMMITS = 300;
+
+/**
+ * The changes to judge, oldest first, or null when git cannot provide them (see
+ * the Fallback section above). A change is one commit since the baseline file
+ * was last committed — `before` is, per file, the larger of its sizes in the
+ * commit's parents (so a merge commit adds nothing of its own) — plus the
+ * uncommitted edits under `dir` against HEAD.
+ *
+ * @param {{ dir: string, include: (rel: string) => boolean, baselinePath?: string }} opts
+ *   `dir` the guarded directory; `include` filters POSIX paths relative to it
+ *   (the same keys the measurer produces); `baselinePath` the committed baseline
+ *   (its last commit starts the window; untracked → the last MAX_COMMITS commits).
+ * @returns {{ commits: Array<{ label: string, before: Object<string, number>, after: Object<string, number> }>,
+ *             head: Object<string, number>, dirty: boolean, since: string | null } | null}
+ */
+function commitChanges({ dir, include, baselinePath }) {
+  let top;
+  try {
+    top = git(dir, ['rev-parse', '--show-toplevel']).trim();
+    git(top, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
+  } catch {
+    return null;
+  }
+  const realTop = fs.realpathSync(top);
+  const rel = path.relative(realTop, fs.realpathSync(dir)).split(path.sep).join('/');
+  const pathspec = rel === '' ? '.' : rel;
+  const prefix = rel === '' ? '' : `${rel}/`;
+
+  const cache = new Map();
+  const sizesAt = (rev) => {
+    if (cache.has(rev)) return cache.get(rev);
+    let listing = null;
+    try {
+      listing = git(top, ['ls-tree', '-r', '-l', '--full-tree', rev, '--', pathspec]);
+    } catch {
+      listing = null; // object missing (shallow boundary)
+    }
+    let sizes = null;
+    if (listing !== null) {
+      sizes = {};
+      for (const line of listing.split('\n')) {
+        const m = /^\d+ blob [0-9a-f]+\s+(\d+)\t(.+)$/.exec(line);
+        if (!m || !m[2].startsWith(prefix)) continue;
+        const key = m[2].slice(prefix.length);
+        if (include(key)) sizes[key] = Number(m[1]);
+      }
+    }
+    cache.set(rev, sizes);
+    return sizes;
+  };
+
+  let since = null;
+  if (baselinePath) {
+    try {
+      const relBaseline = path.relative(realTop, fs.realpathSync(baselinePath)).split(path.sep).join('/');
+      since = git(top, ['log', '-1', '--format=%H', 'HEAD', '--', relBaseline]).trim() || null;
+    } catch {
+      since = null; // baseline outside the repository or not there
+    }
+  }
+  const range = since ? [`${since}..HEAD`] : ['HEAD'];
+  // No pathspec here: path-limited rev-list rewrites parents and prunes merges.
+  const lines = git(top, ['rev-list', '--reverse', `--max-count=${MAX_COMMITS}`, '--parents', ...range])
+    .split('\n')
+    .filter(Boolean);
+  const commits = [];
+  for (const line of lines) {
+    const [sha, ...parents] = line.split(' ');
+    const after = sizesAt(sha);
+    const parentSizes = parents.map(sizesAt);
+    if (after === null || parents.length === 0 || parentSizes.some((p) => p === null)) continue;
+    const before = {};
+    for (const p of parentSizes) {
+      for (const [k, v] of Object.entries(p)) before[k] = Math.max(before[k] ?? -1, v);
+    }
+    const subject = git(top, ['log', '-1', '--format=%s', sha]).trim();
+    commits.push({ label: `commit ${sha.slice(0, 9)} "${subject}"`, before, after });
+  }
+  const dirty = git(top, ['status', '--porcelain', '--untracked-files=all', '--', pathspec]).trim() !== '';
+  return { commits, head: sizesAt('HEAD') ?? {}, dirty, since };
+}
+
+/**
+ * The per-commit budget check. Reports through `fail`; returns the measurement.
+ *
+ * @param {object} o
+ * @param {string} o.label - prefix for messages, e.g. 'workflow-size'
+ * @param {Object<string, number>} o.current - sizes now (working tree)
+ * @param {Object<string, number>} o.baseline - committed baseline sizes
+ * @param {ReturnType<typeof commitChanges>} o.changes - from `commitChanges`; null → baseline-only fallback
+ * @param {{ perFileBytes: number, perCommitBytes: number }} o.budget - from `readSizeBudget`
+ * @param {(msg: string) => void} o.fail
+ * @param {string} [o.updateHint]
+ */
+function assertCommitDeltaBudget({ label, current, baseline, changes, budget, fail, updateHint }) {
+  const hint = updateHint ? `\n${updateHint}` : '';
+  if (changes === null) {
+    return {
+      mode: 'baseline',
+      ...assertDeltaBudget({
+        label,
+        current,
+        baseline,
+        perFileSlack: budget.perFileBytes,
+        totalSlack: budget.perCommitBytes,
+        fail,
+        updateHint: `(No git history available: measured against the committed baseline only.)${hint}`,
+      }),
+    };
+  }
+
+  if (Object.keys(baseline).length === 0) {
+    fail(
+      `[${label}] the committed baseline has no size entries — an empty baseline would make ` +
+        `every growth check pass vacuously. Regenerate it with \`npm run size:baseline\`.`
+    );
+  }
+  for (const [name, v] of Object.entries(baseline)) {
+    if (!Number.isInteger(v) || v < 0) fail(`[${label}] baseline entry ${name} is not a non-negative integer byte size: ${JSON.stringify(v)}`);
+  }
+  const base = (name) => (Number.isInteger(baseline[name]) && baseline[name] >= 0 ? baseline[name] : -1);
+  const todo =
+    `Shrink it — move content into a lazily-read steps/ or references/ file — or, if the growth is needed, ` +
+    `record it: npm run size:baseline -- --reason "<why this growth is needed>" and commit the baseline. ` +
+    `Growth within the budget needs no baseline commit: the phase's closing commit re-baselines once ` +
+    `with --reason "phase NN close".`;
+  const fmt = (o) => `  - ${o.name}: ${o.from} → ${o.to} (+${o.delta})`;
+
+  const judged = [...changes.commits];
+  if (changes.dirty) judged.push({ label: 'the uncommitted changes', before: changes.head, after: current });
+  const results = [];
+  for (const change of judged) {
+    const overages = [];
+    for (const name of Object.keys(change.after).sort()) {
+      const from = Math.max(base(name), change.before[name] ?? -1);
+      if (from < 0) continue; // new file: bounded by the hard caps, recorded at phase close
+      const to = change.after[name];
+      if (to > from) overages.push({ name, from, to, delta: to - from });
+    }
+    const totalOverage = overages.reduce((sum, o) => sum + o.delta, 0);
+    const where = `in ${change.label} (measured against its parent, or the committed baseline when larger)`;
+    const overFile = overages.filter((o) => o.delta > budget.perFileBytes);
+    if (overFile.length > 0) {
+      fail(
+        `[${label}] ${overFile.length} file(s) grew more than the per-file slack of ${budget.perFileBytes} bytes ` +
+          `(size_budget.per_file_bytes) ${where}. ${todo}\n${overFile.map(fmt).join('\n')}${hint}`
+      );
+    }
+    if (totalOverage > budget.perCommitBytes) {
+      fail(
+        `[${label}] total growth ${where} is ${totalOverage} bytes, over the total slack of ` +
+          `${budget.perCommitBytes} bytes (size_budget.per_commit_bytes). ${todo}\n${overages.map(fmt).join('\n')}${hint}`
+      );
+    }
+    results.push({ change: change.label, overages, totalOverage });
+  }
+  const unrecorded = Object.keys(current).filter((n) => base(n) < 0).sort();
+  const removed = Object.keys(baseline).filter((n) => !Object.prototype.hasOwnProperty.call(current, n)).sort();
+  return { mode: 'commit', since: changes.since, results, unrecorded, removed };
+}
+
+/**
+ * The whole guard for one tree, as the size-budget tests run it: read the
+ * committed baseline, measure, list the changes, check the budget and the
+ * `_rebaselines` log. Returns failure messages (empty = green).
+ *
+ * @param {object} o
+ * @param {string} o.label - 'workflow-size' / 'agent-size'
+ * @param {string} o.dir - guarded directory
+ * @param {string} o.baselinePath - committed baseline JSON
+ * @param {(dir: string) => Object<string, number>} o.measure - the measurer
+ * @param {(rel: string) => boolean} o.include - which repository paths (relative to dir) the measurer covers
+ * @param {{ perFileBytes: number, perCommitBytes: number }} [o.budget] - default: readSizeBudget()
+ * @param {object|null} [o.changes] - default: commitChanges({ dir, include, baselinePath }); null = baseline-only
+ * @param {string} [o.updateHint]
+ * @returns {string[]}
+ */
+function checkSizeBudget({ label, dir, baselinePath, measure, include, budget, changes, updateHint }) {
+  // Lazy: update-size-baseline.cjs is the baseline file format's owner.
+  const { readBaseline, splitBaseline, validateRebaselineLog, REBASELINES_KEY } = require('../update-size-baseline.cjs');
+  const failures = [];
+  const raw = readBaseline(baselinePath);
+  if (raw === null) {
+    failures.push(`baseline ${baselinePath} does not exist — run \`npm run size:baseline\``);
+  } else if (!(REBASELINES_KEY in raw)) {
+    failures.push(`baseline ${baselinePath} has no ${REBASELINES_KEY} log — run \`npm run size:baseline\``);
+  }
+  const { sizes, rebaselines } = splitBaseline(raw);
+  assertCommitDeltaBudget({
+    label,
+    current: measure(dir),
+    baseline: sizes,
+    changes: changes === undefined ? commitChanges({ dir, include, baselinePath }) : changes,
+    budget: budget ?? readSizeBudget(),
+    fail: (m) => failures.push(m),
+    updateHint,
+  });
+  for (const problem of validateRebaselineLog(rebaselines)) {
+    failures.push(`[${label}] invalid ${REBASELINES_KEY} log: ${problem}`);
+  }
+  return failures;
+}
+
+module.exports = { readSizeBudget, commitChanges, assertCommitDeltaBudget, checkSizeBudget, DEFAULTS_MANIFEST, MAX_COMMITS };