adversarial-review-gate 2.0.0

package/src/cli/run.js

@@ -0,0 +1,178 @@
+// `adversarial-review run` — wrap a host tool command and gate after it exits.
+//
+//   adversarial-review run --host <host> -- <command> [args...]
+//
+// Captures a baseline BEFORE running, spawns the command with inherited stdio,
+// waits for it to exit, waits a quiescence interval, then recaptures the review
+// scope. If files are STILL changing across two snapshots (the diff hash keeps
+// moving), in enforced/strict we BLOCK (files are still being written). Otherwise
+// we run evaluateGate. The original command's exit code is returned ONLY when the
+// gate allows; on block we exit non-zero (2) and print the reason to stderr.
+//
+// HARDENING #1: user-level stateDir. HARDENING #2: fail-closed try/catch.
+
+import { evaluateGate } from "../core/gate.js";
+import { captureBaseline, buildReviewDiff } from "../core/diff.js";
+import { loadEffectiveConfig, resolveStateDir } from "../core/load-config.js";
+import { isStrict } from "../core/policy.js";
+import { resolveExecutable, spawnResolved } from "../core/process.js";
+import { buildHostRouting } from "./host-map.js";
+import { failClosedDecision } from "./fail-closed.js";
+import { sessionStateKey } from "./hook.js";
+
+const DEFAULT_QUIESCENCE_MS = 750;
+const BLOCK_EXIT_CODE = 2;
+
+/**
+ * @param {string[]} argv
+ * @param {object} io  - { stdin, stdout, stderr, env, cwd }
+ */
+export async function runCommand(argv, io) {
+  const { host, command } = parseArgs(argv);
+  const env = io.env || process.env;
+  const cwd = io.cwd;
+
+  if (command.length === 0) {
+    io.stderr.write("usage: adversarial-review run --host <host> -- <command> [args...]\n");
+    process.exitCode = 2;
+    return;
+  }
+
+  const config = await loadEffectiveConfig(cwd, io);
+  const enforced = config.policy.mode === "enforced" || isStrict(config);
+  const stateDir = resolveStateDir(env);
+  const quiescenceMs = config.runtime?.quiescenceMs ?? DEFAULT_QUIESCENCE_MS;
+
+  // Capture baseline BEFORE running so post-run diff reflects only the wrapped
+  // command's changes.
+  const baseline = await captureBaseline(cwd);
+
+  // Run the wrapped command with inherited stdio.
+  const exitCode = await runWrapped(command, { cwd, env, io });
+
+  // Wait for filesystem quiescence, then confirm the workspace has settled.
+  await sleep(quiescenceMs);
+  const stillChanging = await stillChangingScope(cwd, baseline, quiescenceMs);
+  if (stillChanging && enforced) {
+    io.stderr.write(
+      "BLOCK: workspace is still being written after the command exited; cannot review a " +
+        "moving target. Re-run once the tool has finished.\n"
+    );
+    process.exitCode = BLOCK_EXIT_CODE;
+    return { action: "block", reason: "files_still_changing" };
+  }
+
+  const { hostDescriptor, reviewerRunner } = buildHostRouting(host, config, env);
+
+  let decision;
+  try {
+    decision = await evaluateGate({
+      config,
+      cwd,
+      baseline,
+      transcript: "",
+      transcriptPath: "",
+      host: hostDescriptor,
+      reviewerRunner,
+      // Compose the synthetic session id with the canonical workspace root so the
+      // gate's block-counter/cache are keyed per-workspace, consistent with the
+      // hook's composite keying (distinct workspaces never share state).
+      sessionId: sessionStateKey(`run-${host}`, cwd),
+      stateDir,
+    });
+  } catch (err) {
+    decision = await failClosedDecision({ config, cwd, baseline, err, io });
+  }
+
+  if (decision.action === "block") {
+    io.stderr.write(`BLOCK: ${decision.reason || "review required"}\n`);
+    process.exitCode = BLOCK_EXIT_CODE;
+    return decision;
+  }
+
+  if (decision.systemMessage) {
+    io.stderr.write(`${decision.systemMessage}\n`);
+  }
+  // Gate allowed: surface the wrapped command's own exit code.
+  process.exitCode = exitCode;
+  return decision;
+}
+
+// ---------------------------------------------------------------------------
+// Wrapped command execution
+// ---------------------------------------------------------------------------
+
+// Resolve and spawn the wrapped command with inherited stdio; resolve with its
+// exit code. A missing executable resolves to 127 (shell "command not found").
+async function runWrapped(command, { cwd, env, io }) {
+  const [exe, ...args] = command;
+  const resolved = await resolveExecutable(exe, env);
+  if (!resolved) {
+    io.stderr.write(`adversarial-review run: command not found: ${exe}\n`);
+    return 127;
+  }
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnResolved(resolved, args, { cwd, env, stdio: "inherit" });
+    } catch (err) {
+      io.stderr.write(`adversarial-review run: failed to spawn ${exe}: ${err.message}\n`);
+      resolve(126);
+      return;
+    }
+    child.on("error", (err) => {
+      io.stderr.write(`adversarial-review run: ${exe} error: ${err.message}\n`);
+      resolve(127);
+    });
+    child.on("close", (code) => resolve(code == null ? 0 : code));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Quiescence detection
+// ---------------------------------------------------------------------------
+
+// Take two review-scope snapshots `quiescenceMs` apart. If the diff hash changes
+// between them, files are still being written (not quiescent). Tolerant: a
+// build failure returns false (do not wedge on a diff error — the gate's own
+// internal-error handling covers an unbuildable diff).
+async function stillChangingScope(cwd, baseline, quiescenceMs) {
+  let first;
+  try {
+    first = await buildReviewDiff(cwd, baseline);
+  } catch {
+    return false;
+  }
+  await sleep(quiescenceMs);
+  let second;
+  try {
+    second = await buildReviewDiff(cwd, baseline);
+  } catch {
+    return false;
+  }
+  return first.diffHash !== second.diffHash;
+}
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+// Parse `--host <host> -- <command...>`. Everything after the first `--` is the
+// command. `--host` defaults to "wrapper".
+function parseArgs(argv) {
+  let host = "wrapper";
+  const sep = argv.indexOf("--");
+  const head = sep >= 0 ? argv.slice(0, sep) : argv;
+  const command = sep >= 0 ? argv.slice(sep + 1) : [];
+  for (let i = 0; i < head.length; i += 1) {
+    if (head[i] === "--host" && head[i + 1]) {
+      host = head[i + 1];
+      i += 1;
+    }
+  }
+  return { host, command };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/core/classify.js

@@ -0,0 +1,65 @@
+// File classification: determines whether a changed file is reviewable,
+// sensitive, or docs-only. Used by the gate to decide which files to send
+// to external reviewers and which require extra scrutiny.
+
+const CODE_EXTS = new Set([
+  ".py", ".pyi", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".go", ".rs",
+  ".c", ".h", ".cc", ".cpp", ".hpp", ".cs", ".java", ".kt", ".kts", ".rb",
+  ".php", ".swift", ".scala", ".sh", ".bash", ".zsh", ".sql", ".vue",
+  ".svelte", ".dart", ".lua", ".ex", ".exs", ".clj", ".erl", ".pl", ".r",
+  ".jl", ".groovy", ".gradle", ".tf", ".yaml", ".yml", ".json", ".toml",
+  // Windows scripts
+  ".bat", ".cmd", ".ps1", ".psm1",
+  // Terraform/HCL variable and config files
+  ".tfvars", ".hcl",
+  // Jupyter notebooks — committed executable code
+  ".ipynb",
+]);
+
+const DOC_EXTS = new Set([".md", ".txt", ".rst", ".adoc"]);
+
+// Matches sensitive path segments. Includes SSH/TLS key file names and
+// extensions so that private-key files are classified sensitive=true.
+const SENSITIVE_RE = /auth|login|password|passwd|secret|credential|token|crypto|payment|billing|migration|\.env|security|permission|access[_-]?control|deploy|infra|terraform|k8s|kube|dockerfile|workflow|github\/workflows|id_rsa|id_dsa|id_ecdsa|id_ed25519|\.pem|\.pfx|\.p12|\.key|\.keystore|\.jks/i;
+
+// Exact lowercase base-name matches for well-known build/manifest/lockfiles.
+// IMPORTANT: `base` is derived from the lowercased file path, so every entry
+// here MUST be lowercase — a capitalised entry would be dead code.
+const REVIEWABLE_NAMES = new Set([
+  "package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+  // Dockerfile — lowercase because `base` is always lowercased
+  "dockerfile", "docker-compose.yml", "compose.yml", "tsconfig.json",
+  // Build automation
+  "makefile", "gnumakefile", "justfile", "rakefile",
+  // Ruby / Bundler
+  "gemfile", "gemfile.lock",
+  // Rust / Cargo
+  "cargo.toml", "cargo.lock",
+  // Go modules
+  "go.mod", "go.sum",
+  // Python packaging
+  "poetry.lock", "pyproject.toml", "requirements.txt",
+  // PHP / Composer
+  "composer.json", "composer.lock",
+]);
+
+/**
+ * Classify a file path into reviewable/sensitive/docsOnly categories.
+ *
+ * @param {string} filePath - The path to classify (may use backslashes on Windows).
+ * @param {object} [config={}] - Optional merged config with sensitivity overrides.
+ * @returns {{ reviewable: boolean, sensitive: boolean, docsOnly: boolean, ext: string, base: string }}
+ */
+export function classifyPath(filePath, config = {}) {
+  // Normalize Windows backslashes so SENSITIVE_RE and path logic work uniformly.
+  const normalized = filePath.replace(/\\/g, "/");
+  const lower = normalized.toLowerCase();
+  const base = lower.split("/").at(-1);
+  const ext = base.includes(".") ? `.${base.split(".").at(-1)}` : "";
+  const extraExts = new Set(config.sensitivity?.extraCodeExts || []);
+  const extraSensitive = (config.sensitivity?.extraSensitive || []).map(String);
+  const sensitive = SENSITIVE_RE.test(normalized) || extraSensitive.some((part) => normalized.includes(part));
+  const reviewable = sensitive || CODE_EXTS.has(ext) || extraExts.has(ext) || REVIEWABLE_NAMES.has(base);
+  const docsOnly = DOC_EXTS.has(ext) && !sensitive && !reviewable;
+  return { reviewable, sensitive, docsOnly, ext, base };
+}

package/src/core/config.js

@@ -0,0 +1,158 @@
+// Default configuration for adversarial-review.
+// All sub-objects are frozen shallowly; consumers receive a deep clone via mergeConfig.
+
+export const DEFAULT_CONFIG = Object.freeze({
+  version: 2,
+  policy: {
+    mode: "enforced",
+    reviewScope: "all-code",
+    onReviewerError: "block",
+    onInternalError: "block",
+    onBlockCap: "block",
+    allowSkip: false,
+    allowAdvisoryHosts: false,
+  },
+  thresholds: {
+    bigDiffLines: 80,
+    bigFileCount: 5,
+    debateDiffLines: 250,
+    debateFileCount: 12,
+    debateOnSensitive: true,
+  },
+  sensitivity: {
+    extraSensitive: [],
+    extraCodeExts: [],
+  },
+  runtime: {
+    blockCap: 4,
+    stateTtlDays: 14,
+    timeoutSec: 180,
+    baselineRef: "auto",
+  },
+  privacy: {
+    externalReview: "allow",
+    secretScan: "block-external",
+    tempFileMode: "0600",
+  },
+  hosts: {},
+  reviewers: {},
+});
+
+// Known top-level config keys; unknown keys are stripped by sanitizeProjectConfig.
+const TOP_LEVEL_KEYS = new Set([
+  "version",
+  "policy",
+  "thresholds",
+  "sensitivity",
+  "runtime",
+  "privacy",
+  "hosts",
+  "reviewers",
+]);
+
+/**
+ * Strip unknown top-level keys from a raw project config object.
+ * Does not validate nested keys — that is intentionally left loose so
+ * future sub-keys added to DEFAULT_CONFIG work without updating this list.
+ *
+ * @param {object} raw
+ * @returns {object}
+ */
+export function sanitizeProjectConfig(raw) {
+  const clean = {};
+  for (const [key, value] of Object.entries(raw || {})) {
+    if (TOP_LEVEL_KEYS.has(key)) clean[key] = value;
+  }
+  return clean;
+}
+
+/**
+ * Recursively assign source properties onto target.
+ * Arrays are treated as scalars (replaced, not merged).
+ *
+ * @param {object} target
+ * @param {object} source
+ * @returns {object} target
+ */
+export function deepAssign(target, source) {
+  for (const [key, value] of Object.entries(source || {})) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      if (!target[key] || typeof target[key] !== "object" || Array.isArray(target[key])) {
+        target[key] = {};
+      }
+      deepAssign(target[key], value);
+    } else {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+// Ordering for mode strictness — higher index means stricter.
+const MODE_RANK = new Map([
+  ["soft", 0],
+  ["enforced", 1],
+  ["strict-ci", 2],
+]);
+
+/**
+ * Apply a user-level policy floor to a fully-merged config object so that
+ * a project config can never loosen what the user has set as a minimum.
+ *
+ * Floor rules (all one-directional — can only tighten, never loosen):
+ *  - mode: ratchets to whichever rank is higher
+ *  - allowSkip / allowAdvisoryHosts: floor=false forces false
+ *  - onReviewerError / onInternalError / onBlockCap: floor="block" forces "block"
+ *  - reviewScope: floor="all-code" forces "all-code"
+ *  - privacy.externalReview: floor="deny" forces "deny"
+ *  - privacy.secretScan: floor="block-all" forces "block-all"
+ *
+ * @param {object} config  - already deep-cloned merged config (mutated in place)
+ * @param {object} floor   - user policy floor (may have .policy sub-object or be flat)
+ * @returns {object} config
+ */
+export function applyPolicyFloor(config, floor = {}) {
+  const floorPolicy = floor.policy || floor;
+
+  if (floorPolicy.mode && MODE_RANK.has(floorPolicy.mode)) {
+    const currentRank = MODE_RANK.get(config.policy.mode) ?? 1;
+    const floorRank = MODE_RANK.get(floorPolicy.mode);
+    if (currentRank < floorRank) config.policy.mode = floorPolicy.mode;
+  }
+
+  for (const key of ["allowSkip", "allowAdvisoryHosts"]) {
+    if (floorPolicy[key] === false) config.policy[key] = false;
+  }
+
+  for (const key of ["onReviewerError", "onInternalError", "onBlockCap"]) {
+    if (floorPolicy[key] === "block") config.policy[key] = "block";
+  }
+
+  if (floorPolicy.reviewScope === "all-code") {
+    config.policy.reviewScope = "all-code";
+  }
+
+  if (floor.privacy?.externalReview === "deny") {
+    config.privacy.externalReview = "deny";
+  }
+  if (floor.privacy?.secretScan === "block-all") {
+    config.privacy.secretScan = "block-all";
+  }
+
+  return config;
+}
+
+/**
+ * Produce the final resolved config by merging project config on top of
+ * DEFAULT_CONFIG and then enforcing the user's policy floor.
+ *
+ * @param {object} [projectConfig={}]    - raw config loaded from project
+ * @param {object} [userPolicyFloor={}]  - user-level floor settings
+ * @returns {object} resolved config
+ */
+export function mergeConfig(projectConfig = {}, userPolicyFloor = {}) {
+  const merged = structuredClone(DEFAULT_CONFIG);
+  deepAssign(merged, sanitizeProjectConfig(projectConfig));
+  return applyPolicyFloor(merged, userPolicyFloor);
+}