@codedology/code-forge 0.1.0

package/src/proof/tiers.mjs

@@ -0,0 +1,62 @@
+/**
+ * Proof tiers (plan §7.1, D14): two tiers, decided per file at `review-file` time and enforced
+ * by the block gate as the UNION of its files' tiers.
+ *
+ *   high  ⇐ risk ≥ 2, or the path matches `proof.tiers.high.paths`, or `security_sensitive`
+ *   light ⇐ everything else (the review-depth band `1 ≤ risk < 2` does NOT raise the proof tier)
+ *
+ * The light tier's proof is red→green (B10b). The high tier's extra proof — tool-made mutants on
+ * changed lines — is held on Q16 (block B10c), so `proofRequirements('high')` reports it as
+ * `held` and the gate enforces red→green only until Ricardo answers. Pure: no I/O.
+ */
+
+import { ownsFile } from '../state/registry.mjs';
+
+/** @typedef {'light' | 'high'} Tier */
+/** @typedef {'risk' | 'path' | 'security' | 'default'} TierReason */
+
+export const TIERS = Object.freeze(/** @type {const} */ (['light', 'high']));
+
+/** `risk ≥ HIGH_RISK` ⇒ high tier (§7.1). */
+export const HIGH_RISK = 2;
+
+/**
+ * @param {{file: string, risk: number, securitySensitive?: boolean, highPaths?: ReadonlyArray<string>}} input
+ *   `risk` is the S1 `risk` answer (0–3); `highPaths` is `proof.tiers.high.paths` (exact paths or
+ *   globs in the registry's syntax: `*`, `?`, `**`, `{a,b}`).
+ * @returns {{tier: Tier, reason: TierReason}} the FIRST reason that applies, in the order
+ *   security, risk, path — every one of them yields `high`, so the order only picks the label.
+ * @throws {TypeError} on a non-string file, a risk outside 0–3, or a non-array `highPaths`.
+ */
+export function tierFor({ file, risk, securitySensitive = false, highPaths = [] }) {
+  if (typeof file !== 'string' || file.length === 0) throw new TypeError('tierFor: file must be a non-empty repo-relative path');
+  if (typeof risk !== 'number' || !Number.isFinite(risk) || risk < 0 || risk > 3) {
+    throw new TypeError('tierFor: risk must be a number from 0 to 3');
+  }
+  if (!Array.isArray(highPaths)) throw new TypeError('tierFor: proof.tiers.high.paths must be an array');
+  if (securitySensitive === true) return { tier: 'high', reason: 'security' };
+  if (risk >= HIGH_RISK) return { tier: 'high', reason: 'risk' };
+  if (highPaths.length > 0 && ownsFile(highPaths, file)) return { tier: 'high', reason: 'path' };
+  return { tier: 'light', reason: 'default' };
+}
+
+/**
+ * The block's tier: the union of its files' tiers (`high` when any file is `high`).
+ * @param {ReadonlyArray<{tier: Tier}>} fileTiers
+ * @returns {Tier}
+ */
+export function blockTier(fileTiers) {
+  if (!Array.isArray(fileTiers)) throw new TypeError('blockTier: fileTiers must be an array');
+  return fileTiers.some((t) => t?.tier === 'high') ? 'high' : 'light';
+}
+
+/**
+ * What the gate requires for a tier. `mutants: 'held'` = the high tier's mutation proof is
+ * specified but not enforced until Q16 is answered (B10c).
+ * @param {Tier} tier
+ * @returns {{red_green: true, mutants: 'none' | 'held'}}
+ */
+export function proofRequirements(tier) {
+  if (!TIERS.includes(tier)) throw new TypeError(`proofRequirements: tier must be one of ${TIERS.join(', ')}`);
+  return { red_green: true, mutants: tier === 'high' ? 'held' : 'none' };
+}

package/src/review/budget.mjs

@@ -0,0 +1,241 @@
+/**
+ * Review budget per block (plan §4.10, R4, O19; block B12b) — the middle point.
+ *
+ * Budget = `review.block_budget_tokens` (150 000) + whatever the orchestrator raised for the run
+ * (`raised`). The forecast is the 0.1 static table (all `estimated`, [A31] for the recheck):
+ *   quick 7k · full 13k · A+B+judge 34k (26k for the two lenses + 8k judge) · consensus 30k ·
+ *   recheck 5k.
+ * Unconstrained depth per file: tier `light` ⇒ quick, `standard` ⇒ full, `high` ⇒ A+B+judge
+ * (`consensus` for every file under `review.multimodel: true`).
+ *
+ * Degrade order when the forecast exceeds the budget — one step at a time, cheapest first,
+ * re-forecasting after each, stopping at the first step that fits:
+ *   1. batch small files of the same tier into one packet (≤ `full_in`; one row per file;
+ *      `review.batch_small_files: false` skips it) — a file is small when its estimated packet
+ *      is ≤ `full_in / 3`;
+ *   2. high tier: the judge runs once per BLOCK instead of per file (lens A + B still per file);
+ *   3. standard band: `full` ⇒ `quick`;
+ *   4. high tier: `A + B + judge` ⇒ one `full` L2 + judge — the FLOOR for the high tier
+ *      (consensus floor = the full consensus: steps 2–4 never touch it);
+ *   (5. light: `quick` stays `quick` — a no-op, never counted.)
+ * Still over after step 4 ⇒ `over_budget`: the orchestrator raises the budget once per run or
+ * splits the block. Never silently, never below the floors. RECHECKS ARE NEVER DEGRADED: a
+ * round ≥ 2 packet is already the minimum (§4.11); they are never batched either.
+ *
+ * Rows (R4 dataset): per file `review.plan {file, tier, depth_unconstrained, depth_chosen,
+ * degrade_step, forecast_tokens, context_mode}` and per block `review.budget {budget,
+ * forecast_unconstrained, forecast_chosen, actual, raised, over_budget}`.
+ */
+
+import { budgetFor } from './packet.mjs';
+
+export const SESSION_COST = Object.freeze({ quick: 7000, full: 13000, dual: 34000, consensus: 30000, recheck: 5000 });
+
+/** The judge's share of `dual` (A + B = 2 × 13k; the judge reads two reports). */
+export const JUDGE_COST = SESSION_COST.dual - 2 * SESSION_COST.full;
+
+export const DEFAULT_BLOCK_BUDGET = 150000;
+
+/** Per-file cost of each depth when the judge is billed separately (per block). */
+const PER_FILE = Object.freeze({
+  quick: SESSION_COST.quick,
+  full: SESSION_COST.full,
+  dual: SESSION_COST.dual,
+  'dual-block-judge': 2 * SESSION_COST.full,
+  'full+judge': SESSION_COST.full + JUDGE_COST,
+  'full+block-judge': SESSION_COST.full,
+  consensus: SESSION_COST.consensus,
+  recheck: SESSION_COST.recheck,
+});
+
+/**
+ * Tier per file (§7.1): `high` when risk ≥ 2, a high path, or security-sensitive; `standard` for
+ * 1 ≤ risk < 2; else `light`.
+ * @param {{risk: number, highPath?: boolean, securitySensitive?: boolean}} opts
+ * @returns {'light' | 'standard' | 'high'}
+ */
+export function tierOf({ risk, highPath = false, securitySensitive = false }) {
+  if (highPath || securitySensitive || risk >= 2) return 'high';
+  return risk >= 1 ? 'standard' : 'light';
+}
+
+/**
+ * @typedef {object} BudgetFile
+ * @property {string} file
+ * @property {'light' | 'standard' | 'high'} tier
+ * @property {number} [tokens] - the estimated packet size (for batching); absent ⇒ not small.
+ * @property {boolean} [recheck] - a round ≥ 2 packet: forecast at `recheck`, never degraded.
+ */
+
+/**
+ * @typedef {object} PlanEntry
+ * @property {string} file @property {string} tier
+ * @property {string} depth_unconstrained @property {string} depth_chosen
+ * @property {number} degrade_step @property {number} forecast_tokens
+ * @property {string | null} context_mode @property {number | null} batch
+ */
+
+/**
+ * @typedef {object} BudgetPlan
+ * @property {number} budget @property {number} raised
+ * @property {number} forecast_unconstrained @property {number} forecast_chosen
+ * @property {number} degrade_step - the last step applied (0 = none).
+ * @property {boolean} over_budget
+ * @property {boolean} judge_per_block
+ * @property {PlanEntry[]} plan
+ */
+
+/** @param {'light' | 'standard' | 'high'} tier @param {boolean} consensus */
+const unconstrainedDepth = (tier, consensus) => (consensus ? 'consensus' : tier === 'high' ? 'dual' : tier === 'standard' ? 'full' : 'quick');
+
+/**
+ * Forecast the plan: per-file costs, batches billed once per batch, the block judge once.
+ * @param {PlanEntry[]} entries @param {boolean} judgePerBlock @returns {number}
+ */
+function forecast(entries, judgePerBlock) {
+  let total = 0;
+  /** @type {Map<number, number>} */
+  const batches = new Map();
+  for (const e of entries) {
+    const cost = PER_FILE[/** @type {keyof typeof PER_FILE} */ (e.depth_chosen)];
+    if (e.batch === null) {
+      e.forecast_tokens = cost;
+      total += cost;
+    } else {
+      batches.set(e.batch, Math.max(batches.get(e.batch) ?? 0, cost));
+    }
+  }
+  for (const [id, cost] of batches) {
+    const members = entries.filter((e) => e.batch === id);
+    for (const e of members) e.forecast_tokens = Math.ceil(cost / members.length);
+    total += cost;
+  }
+  const blockJudge = judgePerBlock && entries.some((e) => e.depth_chosen === 'dual-block-judge' || e.depth_chosen === 'full+block-judge');
+  return total + (blockJudge ? JUDGE_COST : 0);
+}
+
+/**
+ * Plan the block's review depth under its budget.
+ * @param {{files: BudgetFile[], cfg?: Record<string, any>, raised?: number}} opts
+ * @returns {BudgetPlan}
+ */
+export function planBudget({ files, cfg = {}, raised = 0 }) {
+  if (!Array.isArray(files)) throw new TypeError('planBudget: files must be an array');
+  const base = Number.isInteger(cfg?.review?.block_budget_tokens) && cfg.review.block_budget_tokens > 0 ? cfg.review.block_budget_tokens : DEFAULT_BLOCK_BUDGET;
+  if (!Number.isInteger(raised) || raised < 0) throw new TypeError('planBudget: raised must be an integer >= 0');
+  const budget = base + raised;
+  const consensus = cfg?.review?.multimodel === true;
+  const fullIn = budgetFor(cfg, 'full_in');
+
+  /** @type {PlanEntry[]} */
+  const plan = files.map((f) => {
+    const depth = f.recheck === true ? 'recheck' : unconstrainedDepth(f.tier, consensus);
+    return { file: f.file, tier: f.tier, depth_unconstrained: depth, depth_chosen: depth, degrade_step: 0, forecast_tokens: 0, context_mode: f.recheck === true ? 'recheck' : null, batch: null };
+  });
+  let judgePerBlock = false;
+  const unconstrained = forecast(plan, false);
+  let chosen = unconstrained;
+  let step = 0;
+
+  /** @type {Array<() => void>} */
+  const steps = [
+    // 1. batch small files of the same tier
+    () => {
+      if (cfg?.review?.batch_small_files === false) return;
+      let next = 0;
+      for (const tier of ['light', 'standard', 'high']) {
+        let load = 0;
+        let current = -1;
+        files.forEach((f, i) => {
+          const e = plan[i];
+          if (f.recheck === true || f.tier !== tier || !(typeof f.tokens === 'number' && f.tokens <= fullIn / 3)) return;
+          if (current < 0 || load + f.tokens > fullIn) {
+            current = next++;
+            load = 0;
+          }
+          load += f.tokens;
+          e.batch = current;
+          e.degrade_step = 1;
+        });
+      }
+      // a "batch" of one file is no batch
+      for (let id = 0; id < next; id += 1) {
+        const members = plan.filter((e) => e.batch === id);
+        if (members.length === 1) Object.assign(members[0], { batch: null, degrade_step: 0 });
+      }
+    },
+    // 2. judge per block for high-tier files
+    () => {
+      judgePerBlock = true;
+      for (const e of plan) if (e.depth_chosen === 'dual') Object.assign(e, { depth_chosen: 'dual-block-judge', degrade_step: 2 });
+    },
+    // 3. standard: full ⇒ quick
+    () => {
+      for (const e of plan) if (e.depth_chosen === 'full' && e.tier === 'standard') Object.assign(e, { depth_chosen: 'quick', degrade_step: 3 });
+    },
+    // 4. high: A + B (+ judge) ⇒ one full + judge — the floor
+    () => {
+      for (const e of plan) {
+        if (e.depth_chosen === 'dual-block-judge') Object.assign(e, { depth_chosen: 'full+block-judge', degrade_step: 4 });
+        else if (e.depth_chosen === 'dual') Object.assign(e, { depth_chosen: 'full+judge', degrade_step: 4 });
+      }
+    },
+  ];
+  while (chosen > budget && step < steps.length) {
+    steps[step]();
+    step += 1;
+    chosen = forecast(plan, judgePerBlock);
+  }
+  return { budget, raised, forecast_unconstrained: unconstrained, forecast_chosen: chosen, degrade_step: step, over_budget: chosen > budget, judge_per_block: judgePerBlock, plan };
+}
+
+/**
+ * The ledger rows of a plan: one `review.plan` per file, then one `review.budget` for the block.
+ * @param {BudgetPlan} result @param {{block: string, actual?: number | null}} opts
+ * @returns {Array<Record<string, any>>}
+ */
+export function budgetRows(result, { block, actual = null }) {
+  /** @type {Array<Record<string, any>>} */
+  const rows = result.plan.map((e) => ({
+    event: 'review.plan',
+    block,
+    file: e.file,
+    tier: e.tier,
+    depth_unconstrained: e.depth_unconstrained,
+    depth_chosen: e.depth_chosen,
+    degrade_step: e.degrade_step,
+    forecast_tokens: e.forecast_tokens,
+    context_mode: e.context_mode,
+    tokens_source: 'estimated',
+  }));
+  rows.push({
+    event: 'review.budget',
+    block,
+    budget: result.budget,
+    forecast_unconstrained: result.forecast_unconstrained,
+    forecast_chosen: result.forecast_chosen,
+    actual,
+    raised: result.raised,
+    over_budget: result.over_budget,
+    degrade_step: result.degrade_step,
+  });
+  if (result.over_budget) rows.push({ event: 'review.over_budget', block, budget: result.budget, forecast_chosen: result.forecast_chosen });
+  return rows;
+}
+
+/**
+ * Plan and write the rows (the ledger writer signs/stamps them). `blockOnly` writes the per-block
+ * rows only (`review.budget`, `review.over_budget`): the live path (B19, the worker's first ticket
+ * of a block) already gets one `review.plan` per reviewed file from the review engine, and a second
+ * set of forecast `review.plan` rows would double the report's planned-file count.
+ * @param {{files: BudgetFile[], cfg?: Record<string, any>, raised?: number, block: string, blockOnly?: boolean, writeRow: (row: Record<string, any>) => Promise<unknown>}} opts
+ * @returns {Promise<BudgetPlan>}
+ */
+export async function planAndRecord({ files, cfg, raised, block, blockOnly = false, writeRow }) {
+  const result = planBudget({ files, cfg, raised });
+  for (const row of budgetRows(result, { block })) {
+    if (blockOnly && row.event === 'review.plan') continue;
+    await writeRow(row);
+  }
+  return result;
+}

package/src/review/context.mjs

@@ -0,0 +1,156 @@
+/**
+ * Packet context (plan §4.3, C10; block B12a).
+ *
+ * A reviewer sees the current file around the diff, never the project. The rule:
+ *  - `whole`: the file at its current content has ≤ `review.context.whole_file_max_lines` (400)
+ *    lines ⇒ the whole file, every line numbered;
+ *  - `hunks`: otherwise each hunk with ± `review.context.hunk_context_lines` (40) lines of the
+ *    current file (overlapping windows merge);
+ *  - `minimal`: the budget fallback ⇒ each hunk with ± `review.context.min_context_lines` (10);
+ *  - `recheck`: a round ≥ 2 packet (§4.11) ⇒ always the hunk form on the fix hunks, never the
+ *    whole file.
+ * Lines are numbered with their line number in the CURRENT file, so a finding's `line_start`
+ * points at a real line. Pure functions: no I/O.
+ */
+
+export const CONTEXT_MODES = Object.freeze(['whole', 'hunks', 'minimal', 'recheck']);
+
+export const DEFAULT_CONTEXT = Object.freeze({ whole_file_max_lines: 400, hunk_context_lines: 40, min_context_lines: 10 });
+
+/** `@@ -a[,b] +c[,d] @@` — the part of a hunk header a reviewer must echo (no function context). */
+const HUNK_RE = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+
+/**
+ * @typedef {{header: string, oldStart: number, oldLines: number, newStart: number, newLines: number}} Hunk
+ */
+
+/**
+ * Parse a unified diff of ONE file. The file header (`diff --git`, `index`, `---`, `+++`) is
+ * skipped by position — everything before the first `@@` — so a content line that starts with
+ * `++` or `--` is never mistaken for a header.
+ * @param {string} text
+ * @returns {{hunks: Hunk[], plusCount: number, minusCount: number}}
+ */
+export function parseDiff(text) {
+  const lines = typeof text === 'string' ? text.split('\n') : [];
+  const first = lines.findIndex((line) => line.startsWith('@@'));
+  /** @type {Hunk[]} */
+  const hunks = [];
+  let plusCount = 0;
+  let minusCount = 0;
+  if (first < 0) return { hunks, plusCount, minusCount };
+  for (const line of lines.slice(first)) {
+    if (line.startsWith('@@')) {
+      const m = HUNK_RE.exec(line);
+      if (!m) continue;
+      hunks.push({
+        header: m[0],
+        oldStart: Number(m[1]),
+        oldLines: m[2] === undefined ? 1 : Number(m[2]),
+        newStart: Number(m[3]),
+        newLines: m[4] === undefined ? 1 : Number(m[4]),
+      });
+    } else if (line.startsWith('+')) {
+      plusCount += 1;
+    } else if (line.startsWith('-')) {
+      minusCount += 1;
+    }
+  }
+  return { hunks, plusCount, minusCount };
+}
+
+/**
+ * The file's lines (a final newline does not make an extra empty line).
+ * @param {string | null} content
+ * @returns {string[]}
+ */
+export function splitLines(content) {
+  if (typeof content !== 'string' || content.length === 0) return [];
+  const lines = content.split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  return lines;
+}
+
+/**
+ * One window per hunk over the CURRENT file: `[newStart − radius, newStart + max(newLines, 1) − 1
+ * + radius]`, clipped to the file; overlapping or touching windows merge.
+ * @param {ReadonlyArray<Hunk>} hunks @param {number} totalLines @param {number} radius
+ * @returns {Array<{start: number, end: number}>} 1-based, inclusive.
+ */
+export function hunkWindows(hunks, totalLines, radius) {
+  if (totalLines === 0) return [];
+  const raw = hunks
+    .map((h) => {
+      const anchor = Math.max(1, h.newStart);
+      const last = anchor + Math.max(h.newLines, 1) - 1;
+      return { start: Math.max(1, anchor - radius), end: Math.min(totalLines, last + radius) };
+    })
+    .filter((w) => w.start <= w.end)
+    .sort((a, b) => a.start - b.start);
+  /** @type {Array<{start: number, end: number}>} */
+  const merged = [];
+  for (const w of raw) {
+    const prev = merged.at(-1);
+    if (prev && w.start <= prev.end + 1) prev.end = Math.max(prev.end, w.end);
+    else merged.push({ ...w });
+  }
+  return merged;
+}
+
+/** @param {Record<string, any> | undefined} cfg */
+export function contextSettings(cfg) {
+  const c = cfg?.review?.context ?? {};
+  const pick = (/** @type {string} */ key) => (Number.isInteger(c[key]) && c[key] >= 0 ? c[key] : DEFAULT_CONTEXT[/** @type {keyof typeof DEFAULT_CONTEXT} */ (key)]);
+  return { whole_file_max_lines: pick('whole_file_max_lines'), hunk_context_lines: pick('hunk_context_lines'), min_context_lines: pick('min_context_lines') };
+}
+
+/**
+ * @typedef {object} Context
+ * @property {'whole' | 'hunks' | 'minimal' | 'recheck'} mode
+ * @property {string} text - the rendered context section body.
+ * @property {Array<{start: number, end: number}>} windows
+ * @property {number} lineCount - how many file lines the context carries.
+ */
+
+/**
+ * Build the context for one file.
+ * @param {{file: string, content: string | null, hunks: ReadonlyArray<Hunk>, cfg?: Record<string, any>, mode?: 'auto' | 'minimal' | 'recheck'}} opts
+ *   `mode: 'auto'` (default) applies the whole-file threshold; `minimal` and `recheck` force the
+ *   hunk form with their radius.
+ * @returns {Context}
+ */
+export function buildContext({ file, content, hunks, cfg, mode = 'auto' }) {
+  const settings = contextSettings(cfg);
+  const lines = splitLines(content);
+  /** @type {Context['mode']} */
+  let chosen;
+  if (mode === 'minimal') chosen = 'minimal';
+  else if (mode === 'recheck') chosen = 'recheck';
+  else chosen = lines.length <= settings.whole_file_max_lines ? 'whole' : 'hunks';
+
+  if (chosen === 'whole') {
+    const windows = lines.length > 0 ? [{ start: 1, end: lines.length }] : [];
+    const head = `### ${file} (whole file, ${lines.length} lines)`;
+    return { mode: chosen, windows, lineCount: lines.length, text: [head, ...numbered(lines, 1, lines.length)].join('\n') };
+  }
+  const radius = chosen === 'minimal' ? settings.min_context_lines : settings.hunk_context_lines;
+  const windows = hunkWindows(hunks, lines.length, radius);
+  const parts = [];
+  let lineCount = 0;
+  for (const w of windows) {
+    parts.push(`### ${file} lines ${w.start}-${w.end}`, ...numbered(lines, w.start, w.end));
+    lineCount += w.end - w.start + 1;
+  }
+  if (windows.length === 0) parts.push(`### ${file} (no current content)`);
+  return { mode: chosen, windows, lineCount, text: parts.join('\n') };
+}
+
+/**
+ * @param {string[]} lines @param {number} start @param {number} end - 1-based, inclusive.
+ * @returns {string[]}
+ */
+function numbered(lines, start, end) {
+  const out = [];
+  for (let n = start; n <= end; n += 1) out.push(`${n}| ${lines[n - 1]}`);
+  return out;
+}