@boyingliu01/xp-gate 0.31.4 → 0.32.1

package/hooks/lib/validate-code-walkthrough.cjs

@@ -3,6 +3,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const os = require('node:os');
 
 const REQUIRED_ROLES = ['architecture', 'technical', 'feasibility'];
 const VALIDITY_MS = 60 * 60 * 1000;
@@ -45,25 +46,31 @@ function parseTimestamp(value, field) {
     : null;
   if (!match) fail(`${field} must be a canonical UTC ISO-8601 timestamp.`);
 
-  const [, yearText, monthText, dayText, hourText, minuteText, secondText, fractionText] = match;
-  const year = Number(yearText);
-  const month = Number(monthText);
-  const day = Number(dayText);
-  const hour = Number(hourText);
-  const minute = Number(minuteText);
-  const second = Number(secondText);
-  const milliseconds = Number((fractionText || '').padEnd(3, '0') || 0);
+  // Groups 1..6 are year, month, day, hour, minute, second; group 7 is the
+  // optional millisecond fraction. Keeping them as arrays means the "build the
+  // date" and "verify round-trip" steps share one ordered definition instead of
+  // repeating seven hand-numbered comparisons.
+  const parts = match.slice(1, 7).map(Number);
+  const [year, month, day, hour, minute, second] = parts;
+  const milliseconds = Number((match[7] || '').padEnd(3, '0') || 0);
   const date = new Date(0);
   date.setUTCFullYear(year, month - 1, day);
   date.setUTCHours(hour, minute, second, milliseconds);
 
-  if (date.getUTCFullYear() !== year
-      || date.getUTCMonth() !== month - 1
-      || date.getUTCDate() !== day
-      || date.getUTCHours() !== hour
-      || date.getUTCMinutes() !== minute
-      || date.getUTCSeconds() !== second
-      || date.getUTCMilliseconds() !== milliseconds) {
+  // A date silently rolls over ("2026-02-30" becomes March 2), so the only way
+  // to know the input was a real calendar instant is to read it back and compare
+  // every field.
+  const expected = [...parts, milliseconds];
+  const readBack = [
+    date.getUTCFullYear(),
+    date.getUTCMonth() + 1,
+    date.getUTCDate(),
+    date.getUTCHours(),
+    date.getUTCMinutes(),
+    date.getUTCSeconds(),
+    date.getUTCMilliseconds(),
+  ];
+  if (!readBack.every((actual, i) => actual === expected[i])) {
     fail(`${field} must contain a valid UTC calendar date and time.`);
   }
   return date.getTime();
@@ -142,6 +149,19 @@ function resolveBindingSeats(config) {
   return seatsFromExperts(profiles[active].experts);
 }
 
+/**
+ * Machine-wide Delphi config path: `$XDG_CONFIG_HOME/xp-gate/` or
+ * `~/.config/xp-gate/`. Mirrors `defaultGlobalConfigPath()` in
+ * `plugins/dsh/src/delphi-config.ts` so the gate and the tool that produces the
+ * evidence agree on where seats come from. XDG_CONFIG_HOME is honoured because
+ * the plugin honours it — a gate reading a different file than the reviewer
+ * used would bind against seats nobody actually ran.
+ */
+function globalConfigPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'xp-gate', DELPHI_CONFIG_FILE);
+}
+
 /**
  * Read the binding seats for the project rooted at `projectRoot`.
  *
@@ -152,23 +172,88 @@ function resolveBindingSeats(config) {
  * fixture to xp-gate's seats. The gate's subject is the repository being
  * pushed, so that is what must be named.
  *
+ * ## Global fallback (2026-10-27)
+ *
+ * A project file still WINS, so a repo can override seats deliberately. When
+ * the project has none, the machine-wide config is used instead of returning
+ * null — and this is load-bearing, not a convenience:
+ *
+ * Before this fallback existed, DELETING a project-level config silently
+ * disabled the entire #574 seat check, because `bindingSeats === null`
+ * short-circuits `validateRequestedModel`. The gate kept reporting PASS while
+ * any three distinct gateway models — including the expensive overseas ones
+ * #574 exists to catch — could satisfy it, with no message anywhere. A user
+ * consolidating onto one global config to stop maintaining a copy per repo
+ * would have unknowingly traded that protection away.
+ *
+ * Only ENOENT triggers the fallback: an unreadable project config
+ * (EACCES/EISDIR) must surface rather than silently routing this run to a
+ * different file. Same semantics as `loadDelphiConfig()` in the DSH plugin.
+ *
+ * ## No config anywhere is now FAIL-CLOSED (2026-10-27)
+ *
+ * Returning null when both locations are absent re-opened the exact hole #574
+ * closed: measured, `b-claude-4.8-opus` / `gpt-5.5` / `gemini-3-pro` pass the
+ * validator when no config exists. That was tolerable while a config shipped
+ * inside every repo (deleting one looked like opting out); once the machine-wide
+ * file is the single source of truth, "no config" becomes the normal state of a
+ * fresh machine or a bare CI runner — i.e. the bypass is the default path.
+ *
+ * The caller distinguishes two cases it already knows:
+ *   - no project context at all (no root argument) -> unbound, #423 behaviour;
+ *   - a real repo with evidence but no config anywhere -> refuse.
+ * This function therefore throws rather than returning null for the second
+ * case; `main()` only reaches it when a project root was named.
+ *
  * @param {string} projectRoot repository root whose config binds the evidence
- * @returns {Map<string, string> | null} seats, or null when no config exists
+ * @param {NodeJS.ProcessEnv} env environment for the global-path lookup
+ * @returns {Map<string, string>} seats; never null
+ * @throws exits via fail() when neither location has a config
  */
-function loadBindingSeats(projectRoot) {
-  const configPath = path.join(projectRoot, DELPHI_CONFIG_FILE);
+function loadBindingSeats(projectRoot, env = process.env) {
+  const projectPath = path.join(projectRoot, DELPHI_CONFIG_FILE);
+  const fallbackPath = globalConfigPath(env);
+
   let raw;
+  let source = projectPath;
+  let projectMissing = false;
   try {
-    raw = fs.readFileSync(configPath, 'utf8');
-  } catch (error) {
-    if (error && error.code === 'ENOENT') return null;
-    fail(`cannot read ${DELPHI_CONFIG_FILE}: ${error && error.message ? error.message : String(error)}`);
+    raw = fs.readFileSync(projectPath, 'utf8');
+  } catch (projectError) {
+    if (projectError && projectError.code === 'ENOENT') {
+      projectMissing = true;
+      try {
+        raw = fs.readFileSync(fallbackPath, 'utf8');
+        source = fallbackPath;
+      } catch (globalError) {
+        if (globalError && globalError.code === 'ENOENT') {
+          // Both absent: this repo has walkthrough evidence but nothing binds
+          // it to seats. Fail closed and say exactly where we looked.
+          fail(
+            `no ${DELPHI_CONFIG_FILE} found, so the reviewer seats cannot be verified. `
+              + `Looked in: ${projectPath}, ${fallbackPath}. `
+              + `Create the machine-wide config or add one to the repository.`
+          );
+        }
+        fail(
+          `cannot read ${DELPHI_CONFIG_FILE}: ${globalError && globalError.message
+            ? globalError.message
+            : String(globalError)}`
+        );
+      }
+    } else {
+      fail(
+        `cannot read ${DELPHI_CONFIG_FILE}: ${projectError && projectError.message
+          ? projectError.message
+          : String(projectError)}`
+      );
+    }
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (error) {
-    fail(`${DELPHI_CONFIG_FILE} is not valid JSON: ${error.message}`);
+    fail(`${source} is not valid JSON: ${error.message}`);
   }
   const seats = resolveBindingSeats(parsed);
   for (const role of REQUIRED_ROLES) {
@@ -176,9 +261,60 @@ function loadBindingSeats(projectRoot) {
       fail(`${DELPHI_CONFIG_FILE} declares no seat for the ${role} role; all three roles must be configured.`);
     }
   }
+  // A repo-local copy that disagrees with the machine-wide one is exactly how
+  // the 2026-10-27 incident happened: a stale per-repo file silently won and the
+  // review kept using a seat that had been retired. Winning is still allowed
+  // (deliberate overrides exist), but it must never be silent.
+  if (!projectMissing) {
+    warnOnSeatDrift(projectPath, fallbackPath, seats);
+  }
   return seats;
 }
 
+/**
+ * Warn (never block) when a repository-local config disagrees with the
+ * machine-wide one.
+ *
+ * 2026-10-27 incident: the machine-wide config had been updated to replace a
+ * flaky seat, but an older copy survived in the repo root. The project file
+ * won, the review kept calling the retired seat, and nothing anywhere said so —
+ * the only symptom was intermittent HTTP 500s that looked like a gateway
+ * problem. Silence is what made it expensive.
+ *
+ * Deliberate per-repo overrides are legitimate, so this is a WARN on stderr and
+ * never changes the exit code. Absence of either file is not drift.
+ *
+ * @param {string} projectPath repository config path
+ * @param {string} fallbackPath machine-wide config path
+ * @param {Map<string, string>} projectSeats seats actually in effect
+ */
+function warnOnSeatDrift(projectPath, fallbackPath, projectSeats) {
+  let machineRaw;
+  try {
+    machineRaw = fs.readFileSync(fallbackPath, 'utf8');
+  } catch {
+    return; // no machine-wide config -> nothing to disagree with
+  }
+  let machineSeats;
+  try {
+    machineSeats = resolveBindingSeats(JSON.parse(machineRaw));
+  } catch {
+    return; // a malformed machine config is reported by its own path when used
+  }
+  const drift = REQUIRED_ROLES.filter(
+    (role) => machineSeats.has(role) && projectSeats.get(role) !== machineSeats.get(role)
+  );
+  if (drift.length === 0) return;
+  const detail = drift
+    .map((role) => `${role}: repo=${projectSeats.get(role)} machine=${machineSeats.get(role)}`)
+    .join('; ');
+  process.stderr.write(
+    `⚠️  ${DELPHI_CONFIG_FILE} in this repository overrides the machine-wide seats `
+      + `(${detail}). The repository copy wins. If the machine-wide config was updated `
+      + `to retire a seat, this repo is still calling the old one.\n`
+  );
+}
+
 /**
  * Validate an expert's identity fields: shape, role, approval status, and
  * channel provenance. Split out of `validateExpert`, which exceeded the
@@ -284,10 +420,24 @@ function validateExpert(expert, index, roles, models, resolvedModels, bindingSea
 
 function validateEvidence(evidence, expectedCommit, expectedBranch, now, bindingSeats) {
   if (!isPlainObject(evidence)) fail('top level must be a plain object.');
+  validateEvidenceIdentity(evidence, expectedCommit, expectedBranch);
+  validateEvidenceTimestamps(evidence, now);
+  validateConsensusRatio(evidence.consensus_ratio);
+  validateExperts(evidence.experts, bindingSeats);
+}
+
+/** The document must describe this exact push, and must approve it. */
+function validateEvidenceIdentity(evidence, expectedCommit, expectedBranch) {
   if (evidence.commit !== expectedCommit) fail('commit does not match HEAD.');
   if (evidence.branch !== expectedBranch) fail('branch does not match the current branch.');
   if (evidence.verdict !== 'APPROVED') fail('top-level verdict must be APPROVED.');
+}
 
+/**
+ * The evidence must be recent and self-consistent: not from the future, not
+ * expired, and valid for exactly one hour from its own timestamp.
+ */
+function validateEvidenceTimestamps(evidence, now) {
   const timestamp = parseTimestamp(evidence.timestamp, 'timestamp');
   const expires = parseTimestamp(evidence.expires, 'expires');
   if (timestamp > now) fail('timestamp is in the future.');
@@ -295,15 +445,22 @@ function validateEvidence(evidence, expectedCommit, expectedBranch, now, binding
   if (expires - timestamp !== VALIDITY_MS) {
     fail('expires must be exactly one hour after timestamp.');
   }
+}
 
-  if (typeof evidence.consensus_ratio !== 'number'
-      || !Number.isFinite(evidence.consensus_ratio)
-      || evidence.consensus_ratio < 0.90
-      || evidence.consensus_ratio > 1) {
+/** The three experts must have agreed at 90% or better. */
+function validateConsensusRatio(ratio) {
+  if (typeof ratio !== 'number' || !Number.isFinite(ratio) || ratio < 0.90 || ratio > 1) {
     fail('consensus_ratio must be a finite number from 0.90 through 1.');
   }
+}
 
-  if (!Array.isArray(evidence.experts) || evidence.experts.length !== 3) {
+/**
+ * Validate each of the three expert records, then confirm every required role
+ * appeared. `roles` accumulates across the records, so it is checked once after
+ * the loop rather than per expert.
+ */
+function validateExperts(experts, bindingSeats) {
+  if (!Array.isArray(experts) || experts.length !== 3) {
     fail('experts must contain exactly three records.');
   }
   const roles = new Set();
@@ -311,7 +468,7 @@ function validateEvidence(evidence, expectedCommit, expectedBranch, now, binding
   // Scoped to this validation run, so one document's models cannot leak into the
   // next (a long-lived process validating several pushes).
   const resolvedModels = new Set();
-  evidence.experts.forEach((expert, index) => {
+  experts.forEach((expert, index) => {
     validateExpert(expert, index, roles, models, resolvedModels, bindingSeats);
   });
   if (roles.size !== REQUIRED_ROLES.length) fail('all required expert roles must be present.');