@codedology/code-forge 0.1.0

package/src/worker/review-state.mjs

@@ -0,0 +1,145 @@
+/**
+ * The fix-loop state per `(run, block, file)` (plan §4.11; block B12c).
+ *
+ * B12b's `fixloop.mjs` is a state machine whose `FileState` (round, level, open findings,
+ * `reviewed_content`, …) must survive between two `review-file` calls on the same file: round 1
+ * is the first ticket, round 2 (the fix-hunk recheck) the next one, and so on. The worker keeps it
+ * in the run's temp root, OUTSIDE the workspace:
+ *
+ *   <run-root>/review-state/<block>/<sha256(file)[0:24]>.json
+ *
+ * Every state file is SIGNED with the run key (`{run, block, file, seq, state}` + `mac`) AND
+ * anchored in the run's append-only ledger: each save first writes a signed row
+ * `{event: 'review.state', block, file, seq, state_sha, l3_rung_used}`. A load matches the file
+ * against the LATEST verified anchor (highest `seq`) for the file: a missing file, an older signed
+ * file (rollback), a different sha, or a file with no anchor is `tampered` — the hook refuses the
+ * ticket, never a fresh round 1 that could clear a `review_cap` stop or an open finding. A
+ * `review.state` row of the run whose MAC does not verify is `tampered` for every block and file
+ * of it (`blockAnchors`). Whether the block's one L3 rung was used comes from the anchors, never
+ * from the state files.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { signRow, verifyRow } from '../state/signer.mjs';
+import { assertBlockId, assertRowPath } from './ticket.mjs';
+
+/** @typedef {import('../review/fixloop.mjs').FileState} FileState */
+/** @typedef {{runRootDir: string, runId: string, block: string, file: string, key: Buffer, rows: Array<Record<string, any>>}} Where */
+
+export const STATE_EVENT = 'review.state';
+
+/** @param {string} runRootDir @param {string} block @returns {string} */
+export const blockStateDir = (runRootDir, block) => path.join(runRootDir, 'review-state', assertBlockId(block));
+
+/**
+ * @param {string} runRootDir @param {string} block @param {string} file - repo-root-relative.
+ * @returns {string}
+ */
+export function statePath(runRootDir, block, file) {
+  const name = createHash('sha256').update(assertRowPath(file)).digest('hex').slice(0, 24);
+  return path.join(blockStateDir(runRootDir, block), `${name}.json`);
+}
+
+/** @param {string} text @returns {string} */
+const sha = (text) => createHash('sha256').update(text).digest('hex');
+
+/**
+ * The block's verified `review.state` anchors, or null when any anchor of the RUN fails: EVERY
+ * `review.state` row of the run is verified (MAC, integer `seq`, string `state_sha`) BEFORE the
+ * block filter, so an anchor whose `block` was edited does not silently drop out and let the
+ * previous seq's state file validate (a rollback) — it fails its MAC and the whole run is
+ * `tampered`. The run selector stays first because the ledger is per project: other runs' anchors
+ * are signed with their own keys and cannot verify with this one. (An anchor whose `run` was
+ * edited is, for this run, a deleted line: out of the MAC's reach, like any dropped ledger row.)
+ * @param {{runId: string, block: string, key: Buffer, rows: Array<Record<string, any>>}} opts
+ * @returns {Array<Record<string, any>> | null}
+ */
+export function blockAnchors({ runId, block, key, rows }) {
+  const ofRun = rows.filter((r) => r?.event === STATE_EVENT && r.run === runId);
+  if (ofRun.some((r) => !verifyRow(r, key).ok || !Number.isInteger(r.seq) || typeof r.state_sha !== 'string')) return null;
+  return ofRun.filter((r) => r.block === block);
+}
+
+/**
+ * @param {Array<Record<string, any>>} anchors @param {string} file
+ * @returns {Record<string, any> | null} the file's latest anchor.
+ */
+function latestAnchor(anchors, file) {
+  let best = null;
+  for (const a of anchors) if (a.file === file && (best === null || a.seq > best.seq)) best = a;
+  return best;
+}
+
+/**
+ * @param {Where} where
+ * @returns {{status: 'none' | 'ok' | 'tampered', state: FileState | null, seq: number}}
+ */
+export function loadState({ runRootDir, runId, block, file, key, rows }) {
+  const anchors = blockAnchors({ runId, block, key, rows });
+  if (anchors === null) return { status: 'tampered', state: null, seq: 0 };
+  const anchor = latestAnchor(anchors, file);
+  let text = null;
+  try {
+    text = readFileSync(statePath(runRootDir, block, file), 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code !== 'ENOENT') return { status: 'tampered', state: null, seq: 0 };
+  }
+  if (anchor === null) return text === null ? { status: 'none', state: null, seq: 0 } : { status: 'tampered', state: null, seq: 0 };
+  if (text === null || sha(text) !== anchor.state_sha) return { status: 'tampered', state: null, seq: anchor.seq };
+  let body = null;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = null;
+  }
+  const ok =
+    body &&
+    typeof body === 'object' &&
+    verifyRow(body, key).ok &&
+    body.run === runId &&
+    body.block === block &&
+    body.file === file &&
+    body.seq === anchor.seq &&
+    body.state &&
+    typeof body.state === 'object' &&
+    body.state.file === file;
+  if (!ok) return { status: 'tampered', state: null, seq: anchor.seq };
+  return { status: 'ok', state: /** @type {FileState} */ (body.state), seq: anchor.seq };
+}
+
+/**
+ * Anchor, then write: the signed `review.state` row goes to the ledger FIRST (a failed ledger write
+ * changes nothing and throws), then the state file is replaced atomically (mode 0600).
+ * @param {Where & {state: FileState, seq: number, writeRow: (row: Record<string, any>) => Promise<unknown>}} opts
+ *   `seq` - the loaded state's seq (0 for a new file); this save is `seq + 1`.
+ */
+export async function saveState({ runRootDir, runId, block, file, key, state, seq, writeRow }) {
+  const target = statePath(runRootDir, block, file);
+  const next = seq + 1;
+  const text = `${JSON.stringify(signRow({ run: runId, block, file, seq: next, state }, key))}\n`;
+  await writeRow({ event: STATE_EVENT, block, file, seq: next, state_sha: sha(text), l3_rung_used: state.l3_rung_used === true });
+  mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const tmp = `${target}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  try {
+    writeFileSync(tmp, text, { mode: 0o600 });
+    renameSync(tmp, target);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * Whether the block's one L3 rung (§3.6 rules 5/6) was already used on ANY of its files — the
+ * rung is once per block. Derived from the ledger anchors only; fails closed: a block anchor that
+ * does not verify is `tampered`.
+ * @param {{runId: string, block: string, key: Buffer, rows: Array<Record<string, any>>}} opts
+ * @returns {{status: 'ok' | 'tampered', used: boolean}}
+ */
+export function blockRungUsed(opts) {
+  const anchors = blockAnchors(opts);
+  if (anchors === null) return { status: 'tampered', used: true };
+  return { status: 'ok', used: anchors.some((a) => a.l3_rung_used === true) };
+}

package/src/worker/ticket.mjs

@@ -0,0 +1,195 @@
+/**
+ * Review tickets (plan §4.8, V4; block B11): repo-root-relative paths, content hashes and ticket
+ * ids. Pure functions plus the one `git rev-parse --show-toplevel` call.
+ *
+ * Path rule (V4): a ticket's `file` — and every `review.*` row the worker writes — is relative to
+ * the REPOSITORY ROOT (realpath'd `git rev-parse --show-toplevel`), whatever directory the coder
+ * called `review-file` from. A raw argument that is absolute or has a `..` segment is refused with
+ * `bad-path` before anything is written; so is a result outside the root or under `.git/` or
+ * `.code-forge/`. A stored value is re-checked by `assertRowPath` (tickets are coder-writable).
+ *
+ * Ticket id = the first 24 hex chars of `sha256(run \0 block \0 file \0 content_hash)`: the same
+ * content enqueued twice is the same ticket (idempotent), an edited file is a new one.
+ */
+
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { exec } from '../util/exec.mjs';
+
+/** A refusal with a stable machine-readable `code` (`bad-path`, `usage`, `no-repo`). */
+export class WorkerError extends Error {
+  /** @param {string} code @param {string} message */
+  constructor(code, message) {
+    super(message);
+    this.name = 'WorkerError';
+    this.code = code;
+  }
+}
+
+/** The content hash recorded for a file that no longer exists (a deletion is reviewable). */
+export const DELETED_HASH = 'deleted';
+
+const BLOCK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const TICKET_ID = /^[0-9a-f]{24}$/;
+
+/** @param {unknown} id @returns {string} */
+export function assertBlockId(id) {
+  if (typeof id !== 'string' || !BLOCK_ID.test(id)) throw new WorkerError('usage', `block id must match ${BLOCK_ID}`);
+  return id;
+}
+
+/** @param {unknown} id @returns {string} */
+export function assertTicketId(id) {
+  if (typeof id !== 'string' || !TICKET_ID.test(id)) throw new WorkerError('usage', 'a ticket id is 24 lowercase hex characters');
+  return id;
+}
+
+/**
+ * The env for a child `git`: no inherited repository-selecting `GIT_*` variable (a git hook
+ * exports `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, …), no system or global config.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function gitChildEnv(env = process.env) {
+  /** @type {NodeJS.ProcessEnv} */
+  const out = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (!name.startsWith('GIT_')) out[name] = value;
+  }
+  return { ...out, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_TERMINAL_PROMPT: '0' };
+}
+
+/**
+ * The repository root containing `cwd`, realpath'd.
+ * @param {string} cwd
+ * @returns {Promise<string>}
+ * @throws {WorkerError} `no-repo`
+ */
+export async function repoRootOf(cwd) {
+  const res = await exec(['git', 'rev-parse', '--show-toplevel'], { cwd, env: gitChildEnv(), timeoutMs: 10000 });
+  const top = res.stdout.trim();
+  if (res.result !== 'ok' || top.length === 0) throw new WorkerError('no-repo', 'not inside a git repository');
+  return realpathSync(top);
+}
+
+/**
+ * Refuse a stored row path that is not a plain repo-root-relative POSIX path (V4).
+ * @param {unknown} value
+ * @returns {string}
+ * @throws {WorkerError} `bad-path`
+ */
+export function assertRowPath(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 4096) throw new WorkerError('bad-path', 'file must be a non-empty relative path');
+  if (value.includes('\0') || value.includes('\\')) throw new WorkerError('bad-path', 'file must be a POSIX path');
+  if (path.posix.isAbsolute(value)) throw new WorkerError('bad-path', 'file must be relative to the repository root, not absolute');
+  const segments = value.split('/');
+  if (segments.some((s) => s === '' || s === '.' || s === '..')) throw new WorkerError('bad-path', 'file must not contain "", "." or ".." segments');
+  const top = segments[0].toLowerCase(); // case-insensitive file systems (macOS, Windows) alias `.GIT`
+  if (top === '.git' || top === '.code-forge') throw new WorkerError('bad-path', `file may not be under ${segments[0]}/`);
+  return value;
+}
+
+/**
+ * Turn a `review-file` argument, given relative to `cwd`, into the repo-root-relative path (V4).
+ * The file's directory is realpath'd when it exists, so a symlinked directory cannot point the
+ * result outside the root.
+ * @param {string} raw @param {string} cwd @param {string} repoRoot - realpath'd.
+ * @returns {string}
+ * @throws {WorkerError} `bad-path`
+ */
+export function normalizeRequestPath(raw, cwd, repoRoot) {
+  if (typeof raw !== 'string' || raw.length === 0) throw new WorkerError('bad-path', 'a path is required');
+  if (path.isAbsolute(raw)) throw new WorkerError('bad-path', 'give the path relative to the current directory, not absolute');
+  if (raw.split(/[/\\]/).includes('..')) throw new WorkerError('bad-path', 'the path may not contain a ".." segment');
+  const joined = path.resolve(realOrSelf(cwd), raw);
+  const real = path.join(realOrSelf(path.dirname(joined)), path.basename(joined));
+  const rel = path.relative(repoRoot, real);
+  if (!isInside(rel)) throw new WorkerError('bad-path', 'the path is outside the repository');
+  return assertInsideRoot(repoRoot, rel.split(path.sep).join('/'));
+}
+
+/** @param {string} rel @returns {boolean} whether a `path.relative` result stays inside. */
+function isInside(rel) {
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+
+/**
+ * Re-check a repo-root-relative path on disk: the file itself may not be a symlink (it could
+ * point anywhere), and its directory, realpath'd, must still be inside the root. A missing file
+ * passes (a deletion is reviewable); its existing parent is still checked.
+ * @param {string} repoRoot - realpath'd. @param {string} file
+ * @returns {string} `file`
+ * @throws {WorkerError} `bad-path`
+ */
+export function assertInsideRoot(repoRoot, file) {
+  const full = path.join(repoRoot, assertRowPath(file));
+  try {
+    if (lstatSync(full).isSymbolicLink()) throw new WorkerError('bad-path', 'the path is a symlink');
+  } catch (err) {
+    if (err instanceof WorkerError) throw err;
+  }
+  const rel = path.relative(realOrSelf(repoRoot), path.join(realOrSelf(path.dirname(full)), path.basename(full)));
+  if (!isInside(rel)) throw new WorkerError('bad-path', 'the path is outside the repository');
+  return file;
+}
+
+/** @param {string} p @returns {string} */
+function realOrSelf(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * sha256 of the file's bytes, or `DELETED_HASH` when it does not exist. Re-checks the path on
+ * disk first (`assertInsideRoot`: no symlinked file, no directory outside the root).
+ * @param {string} repoRoot @param {string} file - repo-root-relative.
+ * @returns {string}
+ */
+export function contentHash(repoRoot, file) {
+  const bytes = readRegularFileNoFollow(repoRoot, file);
+  if (bytes === null) return DELETED_HASH;
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+/**
+ * Read a repo file's bytes without ever following a symlink, closing the lstat→read race (a
+ * regular file swapped for a symlink after `assertInsideRoot` checked it): the file is opened
+ * with `O_NOFOLLOW` (a symlink fails with ELOOP ⇒ `bad-path`) and `O_NONBLOCK` (a FIFO never
+ * blocks the open), the OPEN descriptor must be a regular file (`fstat`), and the bytes come from
+ * that descriptor. The realpath'd parent is checked inside the root before and after the open.
+ * @param {string} repoRoot - realpath'd. @param {string} file - repo-root-relative.
+ * @returns {Buffer | null} the bytes, or null when the file does not exist.
+ * @throws {WorkerError} `bad-path`
+ */
+export function readRegularFileNoFollow(repoRoot, file) {
+  assertInsideRoot(repoRoot, file);
+  const full = path.join(repoRoot, file);
+  let fd;
+  try {
+    fd = openSync(full, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  } catch (err) {
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+    if (code === 'ENOENT') return null;
+    if (code === 'ELOOP' || code === 'EMLINK') throw new WorkerError('bad-path', 'the path is a symlink');
+    throw err;
+  }
+  try {
+    if (!fstatSync(fd).isFile()) throw new WorkerError('bad-path', 'not a regular file');
+    assertInsideRoot(repoRoot, file);
+    return readFileSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * @param {{run: string, block: string, file: string, content_hash: string}} t
+ * @returns {string} the ticket id.
+ */
+export function ticketId({ run, block, file, content_hash }) {
+  return createHash('sha256').update([run, block, file, content_hash].join('\0')).digest('hex').slice(0, 24);
+}