@codedology/code-forge 0.8.0 → 0.9.0

package/src/review/deletion.mjs

@@ -0,0 +1,106 @@
+/**
+ * The deletion note (block B74, issue #8): a packet for a pure deletion (the file is gone from the
+ * reviewed tree, its diff is all `-` lines) gets a `## deleted file` section before the diff. It
+ * says the file is deleted and lists the tree paths that still name the file's basename, so the
+ * reviewer checks for dangling references.
+ *
+ * The reviewed tree is the working tree the review engine diffs (`reviewFile`'s `repoRoot`: the
+ * block's worktree, or the main tree), never a commit: the paths come from ONE
+ * `git grep -l -z --untracked -F -e <basename> -- .` run with that tree as cwd (argv only, the
+ * review git env `reviewGitEnv`: no inherited `GIT_*` variable, `GIT_CONFIG_NOSYSTEM=1`,
+ * `GIT_CONFIG_GLOBAL` the null device, `GIT_LITERAL_PATHSPECS=1`). `--untracked` adds the files a
+ * block created and has not committed yet (never ignored ones). The list is sorted, never names the
+ * deleted path itself or a secret-like path (`isSecretLike`), and stops at {@link MAX_REFERENCES}
+ * paths; a path with a control character (it could break the packet layout) is never printed, only
+ * counted with the paths past the cap (`(<n> more not listed)`). No match ⇒ `no references found`.
+ * A basename shorter than {@link MIN_BASENAME} characters is not grepped, nor is a deleted path
+ * with a control character (it is printed JSON-escaped), and a grep that fails (or times out) is
+ * not trusted: all say `references not checked`. The note is a hint, never an exemption: a
+ * deletion is reviewed and needs a signed approval like any other change (a grep cannot prove that
+ * nothing depends on a file).
+ */
+
+import path from 'node:path';
+import { exec } from '../util/exec.mjs';
+import { isSecretLike, reviewGitEnv } from './packet.mjs';
+
+/** At most this many referencing paths are listed. */
+export const MAX_REFERENCES = 20;
+
+/** A basename shorter than this matches too much to be a useful hint: it is not grepped. */
+export const MIN_BASENAME = 3;
+
+export const NO_REFERENCES = 'no references found';
+export const NOT_CHECKED = 'references not checked';
+
+const GREP_TIMEOUT_MS = 30000;
+
+const CONTROL = /[\x00-\x1f\x7f]/;
+
+/** @param {string} p @returns {boolean} whether `p` has a control character. */
+const hasControl = (p) => CONTROL.test(p);
+
+/**
+ * @typedef {object} References
+ * @property {'found' | 'none' | 'not_checked'} status
+ * @property {string[]} paths - sorted, at most {@link MAX_REFERENCES}.
+ * @property {number} more - matching paths not listed: past the cap, or with a control character.
+ */
+
+/** @type {References} */
+const NOT_CHECKED_REFS = Object.freeze({ status: 'not_checked', paths: [], more: 0 });
+
+/**
+ * The paths of the reviewed tree (`repoRoot`, the grep's cwd) that still name `file`'s basename.
+ * @param {{repoRoot: string, file: string, run?: typeof exec}} opts - `run`: the child runner
+ *   (default `exec`; a test seam).
+ * @returns {Promise<References>}
+ */
+export async function findReferences({ repoRoot, file, run = exec }) {
+  const base = path.posix.basename(file);
+  if (base.length < MIN_BASENAME || hasControl(file)) return { ...NOT_CHECKED_REFS, paths: [] };
+  let res;
+  try {
+    res = await run(['git', 'grep', '-l', '-z', '--untracked', '-F', '-e', base, '--', '.'], { cwd: repoRoot, env: reviewGitEnv(), timeoutMs: GREP_TIMEOUT_MS, okExitCodes: [0, 1] });
+  } catch {
+    return { ...NOT_CHECKED_REFS, paths: [] };
+  }
+  if (res?.result !== 'ok' || (res.code !== 0 && res.code !== 1) || typeof res.stdout !== 'string') return { ...NOT_CHECKED_REFS, paths: [] };
+  const matched = [...new Set(res.stdout.split('\0').filter((p) => p.length > 0 && p !== file && !isSecretLike(p)))];
+  const unsafe = matched.filter(hasControl).length;
+  const clean = matched.filter((p) => !hasControl(p)).sort();
+  if (clean.length === 0 && unsafe === 0) return { status: 'none', paths: [], more: 0 };
+  return { status: 'found', paths: clean.slice(0, MAX_REFERENCES), more: Math.max(0, clean.length - MAX_REFERENCES) + unsafe };
+}
+
+/**
+ * The `## deleted file` section (heading included) for a deleted `file`. A name with a control
+ * character is printed JSON-escaped, never raw.
+ * @param {string} file @param {References} refs @returns {string}
+ */
+export function renderDeletionNote(file, refs) {
+  const shown = hasControl(file) ? JSON.stringify(file) : file;
+  const out = ['## deleted file', `this file is deleted: ${shown}`, `check that nothing still depends on it. tree paths that still name ${JSON.stringify(path.posix.basename(file))}:`];
+  if (refs.status === 'not_checked') out.push(NOT_CHECKED);
+  else if (refs.status === 'none') out.push(NO_REFERENCES);
+  else {
+    out.push(...refs.paths.map((p) => `- ${p}`));
+    if (refs.more > 0) out.push(`(${refs.more} more not listed)`);
+  }
+  return out.join('\n');
+}
+
+/**
+ * The deletion note for `file`, its references read in `repoRoot` (the reviewed tree). Never
+ * rejects: anything that fails is `references not checked`.
+ * @param {{repoRoot: string, file: string, run?: typeof exec}} opts @returns {Promise<string>}
+ */
+export async function deletionNote(opts) {
+  let refs;
+  try {
+    refs = await findReferences(opts);
+  } catch {
+    refs = NOT_CHECKED_REFS;
+  }
+  return renderDeletionNote(opts.file, refs);
+}

package/src/review/engine.mjs

@@ -40,12 +40,15 @@
  *     (`moved.mjs`, B56). The peers' diffs are read once per review (`input.peerDiffs`, or a
  *     reader built from `input.peers`). It is extra text: every hunk still goes to the reviewer,
  *     and it counts toward the budget in the same measure.
+ *  9. a pure deletion (the file is gone from the reviewed tree) gets a `## deleted file` note in
+ *     every packet — reviewers and judge — naming up to 20 tree paths that still name its basename
+ *     (`deletion.mjs`, B74). It is a hint, never an exemption: the deletion still needs approval.
  * Approval (until B12b's triage lands) = the final answer (the judge's in dual/consensus mode, else
  * the single reviewer's) passed the guard, says `passed: true`, and carries no `critical` or
  * `warning` finding.
  */
 
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import { resolveLevel } from '../config/known-ids.mjs';
@@ -55,6 +58,7 @@ import { isMigrationPath, isPolicyPath } from '../decide/lane-facts.mjs';
 import { tierFor } from '../proof/tiers.mjs';
 import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, diffOnlyTokens, readFileDiff } from './packet.mjs';
 import { movedText, movesFor, peerDiffReader } from './moved.mjs';
+import { deletionNote, renderDeletionNote } from './deletion.mjs';
 import { isMarkdownFile, packSections, sectionFindings, sectionGroups } from './sections.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
 import { spawnWithTimeoutRetry } from './session-retry.mjs';
@@ -182,6 +186,8 @@ export function rulesRisk({ file, plusCount, cfg }) {
  * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow] - ledger rows
  *   (`review.plan`, `review.unavailable`, `review.schema_invalid`, `review.schema_fallback`); a
  *   failed write never fails the review (a failed `review.schema_fallback` write means no try).
+ * @property {(opts: {repoRoot: string, file: string}) => Promise<string>} [deletionNote] - B74: the
+ *   deletion note reader (default `deletionNote`, `deletion.mjs`); a throw gives `references not checked`.
  * @property {import('./schema-fallback.mjs').SchemaHistory} [schemaHistory] - B55: the packet's
  *   signed schema-miss history (the worker's); absent ⇒ no second-level try.
  */
@@ -233,8 +239,22 @@ export async function reviewFile(input, deps) {
   } catch {
     moves = null; // no hint; the review goes on
   }
+  // B74: a pure deletion gets the `## deleted file` note in every packet, read once; it is extra
+  // text like the moved code, counted in the same measure. "Deleted" is explicit: the diff is not
+  // empty (checked above), the reader found no content (`readFileDiff` gives null ONLY for a path
+  // not on disk: a binary file is decoded text, an unreadable one throws) AND the path is absent
+  // from the reviewed tree now. The references are read in that same tree (`repoRoot`).
+  let deleted = '';
+  if (diff.content === null && isAbsent(repoRoot, diff.file)) {
+    const note = deps.deletionNote ?? deletionNote;
+    try {
+      deleted = await note({ repoRoot, file: diff.file });
+    } catch {
+      deleted = renderDeletionNote(diff.file, { status: 'not_checked', paths: [], more: 0 }); // the review goes on
+    }
+  }
   /** @param {ReadonlyArray<number> | null} keys - a Markdown section's group keys; null ⇒ the whole file. */
-  const movedOf = (keys) => movedText(moves, diff.content, keys);
+  const movedOf = (keys) => [deleted, movedText(moves, diff.content, keys)].filter((t) => typeof t === 'string' && t.length > 0).join('\n');
   const min = minTokensOut(cfg);
   // B55: never in consensus mode — its providers (two reviewers, the judge) are the check itself
   const schemaFallback = plan.mode !== 'consensus';
@@ -466,6 +486,20 @@ async function runOne(spec, text, packet, { deps, workDir, min, cfg, schemaFallb
   return { ...meta, status: 'ok', reason: null, review: verdict.review };
 }
 
+/**
+ * B74: whether `file` is absent from the tree at `repoRoot` (lstat says ENOENT or ENOTDIR).
+ * @param {string} repoRoot @param {string} file @returns {boolean}
+ */
+function isAbsent(repoRoot, file) {
+  try {
+    lstatSync(path.join(repoRoot, file));
+    return false;
+  } catch (err) {
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+  }
+}
+
 /**
  * Two token counts added; a missing one (not a number) adds nothing, both missing ⇒ null.
  * @param {unknown} a @param {unknown} b @returns {number | null}

package/src/review/fixloop.mjs

@@ -24,11 +24,15 @@
  *     a coding level, R1) takes it, so for an L2 block the rung IS the +1 at round 2. After the
  *     patch the block continues at L2 (§3.6, Fable ruling A): `l3_rung_used = true`,
  *     `rounds_at_level = 0`, and the `patch_check` goes through `decideNext` like any recheck —
- *     clean ⇒ complete; open set not smaller than before the patch ⇒ `stopped: l3_patch_exhausted`
- *     (`trigger: review_stall`); round ≥ cap ⇒ `stopped: review_cap`; else `fix` at L2 with
- *     `l3_patch: true` in the brief. A later stall ⇒ `l3_patch_exhausted`; round 4 still open ⇒
- *     `review_cap` (the rung is spent). Either way the ledger `review.cap` row lists the open
- *     ids — the human decides (fix by hand, `block waive`, or re-decompose).
+ *     clean ⇒ complete; the patch closed NO finding that was open before it (ids compared, not
+ *     counts) ⇒ `stopped: l3_patch_exhausted` (`trigger: review_stall`); round ≥ cap ⇒
+ *     `stopped: review_cap`; else `fix` at L2 with `l3_patch: true` in the brief. B73 (issue #12):
+ *     a patch that closed ≥ 1 old id below the cap is progress, not a stall, even when new findings
+ *     in its fix hunks keep the open set from shrinking. A later stall at L2 ⇒ `l3_patch_exhausted`
+ *     (the rung is spent, never a second one); round 4 still open ⇒ `review_cap`. Either way the
+ *     ledger `review.cap` row lists the open ids — the human decides (`STOP_EXITS`,
+ *     `stop-exits.mjs`): `block reopen` after a fix, `block waive` per open finding,
+ *     `review-file --answers` for a fix in another owned file, or re-decompose.
  *  6. Ledger per round: `review.round {file, round, level, kind, open_before, closed,
  *     new_in_hunks, late, open_after, tokens_in, tokens_out}`; a converged file gets
  *     `review.approved {file, content_hash, round}` (the worker signs every row it writes).
@@ -497,17 +501,20 @@ async function recheckSession(packet, deps) {
 /**
  * After a counted round with open findings: cap first (rule 6), else stall / ladder (2b, 2).
  * @param {FileState} state @param {number} openBefore @param {ReturnType<typeof settings>} s
- * @param {'full' | 'recheck' | 'patch_check'} kind - a `patch_check` compares against the open
- *   set before the patch (the rung's own shrink test), whatever the round number.
+ * @param {'full' | 'recheck' | 'patch_check'} kind - a `patch_check` is judged by `closedIds`
+ *   (B73), whatever the round number.
+ * @param {number} closedIds - how many ids open before the round are not open after it.
  * @returns {NextStep}
  */
-function decideNext(state, openBefore, s, kind) {
+function decideNext(state, openBefore, s, kind, closedIds) {
   if (state.open.length === 0) return { action: 'complete' };
   if (kind === 'patch_check') {
-    // the block's one rung is spent: a patch that did not shrink the set stops FIRST — even when
-    // the rung was taken at the cap — then the cap; else the block continues at L2 below
-    if (reviewRoundStalled(openBefore, state.open.length)) return { action: 'stop', reason: 'l3_patch_exhausted', trigger: 'review_stall' };
+    // the block's one rung is spent: a patch that closed no old finding stops FIRST — even when
+    // the rung was taken at the cap — then the cap; else (B73: ≥ 1 old id closed is progress,
+    // whatever new findings its fix hunks brought) the block continues at L2: a fix, no stall
+    if (closedIds === 0) return { action: 'stop', reason: 'l3_patch_exhausted', trigger: 'review_stall' };
     if (state.round >= s.maxRounds) return { action: 'stop', reason: 'review_cap', trigger: 'review_cap' };
+    return { action: 'fix', level: state.level, trigger: null };
   }
   if (state.round >= s.maxRounds) {
     const esc = escalationAfterAttempt({ currentLevel: state.level, roundsAtFile: state.round, maxRoundsPerFile: s.maxRounds, openFixNowFinding: true, l3RungAlreadyUsed: state.l3_rung_used });
@@ -515,7 +522,7 @@ function decideNext(state, openBefore, s, kind) {
   }
   const esc = escalationAfterAttempt({
     currentLevel: state.level,
-    reviewStall: (kind === 'patch_check' || state.round >= 2) && reviewRoundStalled(openBefore, state.open.length),
+    reviewStall: state.round >= 2 && reviewRoundStalled(openBefore, state.open.length),
     openFixNowFinding: true,
     reviewRoundsAtLevel: state.rounds_at_level,
     reviewRoundsPerLevel: s.perLevel,
@@ -740,9 +747,12 @@ export async function runRound(state, deps, opts = {}) {
     draft.status = 'complete';
     draft.next = { action: 'complete' };
   } else {
-    // after a patch_check the block continues at L2 (§3.6): the rung is spent, so a stall now
-    // stops (`l3_patch_exhausted`) and the cap stops (`review_cap`); a shrunk set is fixed at L2
-    draft.next = decideNext(draft, openBefore, s, kind);
+    // after a patch_check the block continues at L2 (§3.6): the rung is spent, so a patch that
+    // closed no old id stops (`l3_patch_exhausted`) and the cap stops (`review_cap`); a patch that
+    // closed one is fixed at L2 (B73). Closed = an id open before the round, not open after it.
+    const after = new Set(draft.open.map((f) => f.id));
+    const closedIds = new Set(state.open.map((f) => f.id).filter((id) => !after.has(id))).size;
+    draft.next = decideNext(draft, openBefore, s, kind, closedIds);
     if (draft.next.action === 'stop') draft.status = 'stopped';
   }
   const rows = [...lateRows, roundRow];