jules-orchestrator-kit 0.42.0 → 0.52.0

package/src/coverage.mjs

@@ -0,0 +1,328 @@
+import { readFileSync, readdirSync, mkdtempSync, rmSync, existsSync, realpathSync } from "node:fs";
+import { join, resolve, relative, isAbsolute } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+import { resolveVerify } from "./config.mjs";
+
+/**
+ * Checks if a file path should be excluded from diff coverage enforcement.
+ * Excludes test files, configs, documentation, and agent rules.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isExcludedFromCoverage(filePath = "") {
+  if (!filePath) return true;
+  const norm = filePath.replace(/\\/g, "/").toLowerCase();
+  if (
+    norm.startsWith(".agent/") ||
+    norm.startsWith(".github/") ||
+    norm.startsWith(".git/") ||
+    norm.startsWith("test/") ||
+    norm.startsWith("tests/") ||
+    norm.includes("/__tests__/") ||
+    norm.includes(".test.") ||
+    norm.includes(".spec.") ||
+    norm.includes("_test.") ||
+    norm.endsWith(".md") ||
+    norm.endsWith(".json") ||
+    norm.endsWith(".yml") ||
+    norm.endsWith(".yaml") ||
+    norm.endsWith(".lock")
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Maps V8 function range offsets to 1-indexed line hit counts.
+ * @param {string} sourceContent - Full text of source file
+ * @param {Array<object>} v8Functions - Functions array from V8 coverage JSON
+ * @returns {Map<number, number>} Map of lineNo -> hitCount
+ */
+export function mapV8RangesToLines(sourceContent = "", v8Functions = []) {
+  if (!sourceContent || !Array.isArray(v8Functions) || v8Functions.length === 0) {
+    return new Map();
+  }
+
+  const lines = sourceContent.split("\n");
+  const lineRanges = [];
+  let currentOffset = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const start = currentOffset;
+    const end = currentOffset + lines[i].length;
+    lineRanges.push({ lineNo: i + 1, start, end, text: lines[i] });
+    currentOffset = end + 1;
+  }
+
+  const allRanges = [];
+  for (const fn of v8Functions) {
+    if (Array.isArray(fn.ranges)) {
+      for (const r of fn.ranges) {
+        allRanges.push(r);
+      }
+    }
+  }
+
+  // Sort ranges: broader outer ranges first
+  allRanges.sort((a, b) => {
+    if (a.startOffset !== b.startOffset) return a.startOffset - b.startOffset;
+    return b.endOffset - a.endOffset;
+  });
+
+  const lineHits = new Map();
+
+  for (const { lineNo, start, text } of lineRanges) {
+    const trimmed = text.trim();
+    if (
+      !trimmed ||
+      trimmed.startsWith("//") ||
+      trimmed.startsWith("/*") ||
+      trimmed.startsWith("*") ||
+      trimmed.startsWith("import ") ||
+      trimmed.startsWith("export default {") ||
+      trimmed === "};" ||
+      trimmed === "}"
+    ) {
+      continue;
+    }
+
+    const nonWsStart = start + text.search(/\S/);
+    const nonWsEnd = start + text.trimEnd().length;
+
+    let count = 0;
+    let matched = false;
+
+    for (const r of allRanges) {
+      if (r.startOffset <= nonWsStart && nonWsEnd <= r.endOffset) {
+        count = r.count;
+        matched = true;
+      }
+    }
+
+    if (matched) {
+      lineHits.set(lineNo, count);
+    }
+  }
+
+  return lineHits;
+}
+
+/**
+ * Spawns the verification test command with NODE_V8_COVERAGE and collects raw coverage maps.
+ * @param {string} [testCmd] - Command to execute (defaults to package test cmd)
+ * @param {object} [options]
+ * @param {string} [options.root=process.cwd()]
+ * @param {number} [options.timeoutMs=60000]
+ * @returns {object} { ok, coverageFiles, coverageByFile, stdout, stderr, exitCode }
+ */
+export function runV8Coverage(testCmd, options = {}) {
+  const root = options.root || process.cwd();
+  const cmd = testCmd || resolveVerify(root).testCmd || "npm test";
+  const timeoutMs = options.timeoutMs || 60000;
+
+  const tempCoverageDir = mkdtempSync(join(tmpdir(), "jules-v8-cov-"));
+
+  try {
+    const env = {
+      ...process.env,
+      NODE_V8_COVERAGE: tempCoverageDir,
+    };
+    // Strip child test runner flags to avoid collisions
+    for (const k of Object.keys(env)) {
+      if (k.startsWith("NODE_TEST_") || k.startsWith("NODE_CHANNEL_")) {
+        delete env[k];
+      }
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+
+    try {
+      stdout = execSync(cmd, {
+        cwd: root,
+        env,
+        timeout: timeoutMs,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      });
+    } catch (err) {
+      exitCode = err.status || 1;
+      stdout = err.stdout ? String(err.stdout) : "";
+      stderr = err.stderr ? String(err.stderr) : err.message;
+    }
+
+    const coverageByFile = new Map();
+    const files = existsSync(tempCoverageDir) ? readdirSync(tempCoverageDir) : [];
+
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const fullPath = join(tempCoverageDir, file);
+      try {
+        const content = readFileSync(fullPath, "utf-8");
+        const parsed = JSON.parse(content);
+        if (Array.isArray(parsed.result)) {
+          for (const item of parsed.result) {
+            if (!item.url || item.url.startsWith("node:")) continue;
+            let relPath = item.url;
+            if (relPath.startsWith("file://")) {
+              try {
+                relPath = fileURLToPath(item.url);
+              } catch (_) {
+                relPath = relPath.replace(/^file:\/\//, "");
+              }
+            }
+
+            let resolvedRoot = root;
+            try {
+              if (existsSync(root)) resolvedRoot = realpathSync(root);
+            } catch (_) {}
+
+            try {
+              if (existsSync(relPath)) relPath = realpathSync(relPath);
+            } catch (_) {}
+
+            if (isAbsolute(relPath)) {
+              relPath = relative(resolvedRoot, relPath);
+            }
+            relPath = relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+
+            if (!isExcludedFromCoverage(relPath)) {
+              if (!coverageByFile.has(relPath)) {
+                coverageByFile.set(relPath, []);
+              }
+              coverageByFile.get(relPath).push(...(item.functions || []));
+            }
+          }
+        }
+      } catch (_) {}
+    }
+
+    return {
+      ok: exitCode === 0,
+      exitCode,
+      stdout,
+      stderr,
+      coverageFiles: files.length,
+      coverageByFile,
+    };
+  } finally {
+    try {
+      rmSync(tempCoverageDir, { recursive: true, force: true });
+    } catch (_) {}
+  }
+}
+
+/**
+ * Parses diff text to extract added line numbers for each modified file.
+ * @param {string} diffStr
+ * @returns {Map<string, number[]>} Map of filePath -> added line numbers
+ */
+export function extractAddedLinesFromDiff(diffStr = "") {
+  const fileAddedLines = new Map();
+  if (!diffStr) return fileAddedLines;
+
+  let currentFile = null;
+  let currentLineNo = null;
+
+  const lines = diffStr.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if ((line.startsWith("+++ ") || line.startsWith("+++ b/") || line.startsWith("+++ /dev/null")) && !line.startsWith("++++")) {
+      const target = line.slice(3).split("\t")[0].trim().replace(/^b\//, "");
+      currentFile = target && target !== "/dev/null" ? target : null;
+      currentLineNo = null;
+      continue;
+    }
+
+    const hunkMatch = /^@@ -\d+(?:,\d+)? \+(\d+)/.exec(line);
+    if (hunkMatch) {
+      currentLineNo = parseInt(hunkMatch[1], 10);
+      continue;
+    }
+
+    if (currentLineNo === null || !currentFile) continue;
+
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      if (!isExcludedFromCoverage(currentFile)) {
+        if (!fileAddedLines.has(currentFile)) {
+          fileAddedLines.set(currentFile, []);
+        }
+        fileAddedLines.get(currentFile).push(currentLineNo);
+      }
+      currentLineNo++;
+    } else if (!line.startsWith("-") && !line.startsWith("\\")) {
+      currentLineNo++;
+    }
+  }
+
+  return fileAddedLines;
+}
+
+/**
+ * Calculates diff coverage percentage by cross-referencing V8 coverage against added lines in the git diff.
+ * @param {Map<string, Array<object>>} coverageByFile - Map of relative file path -> V8 function arrays
+ * @param {string} diffStr - Unified git diff
+ * @param {object} [options]
+ * @param {string} [options.root=process.cwd()]
+ * @param {number} [options.minCoverage=100] - Expected minimum coverage percentage (0-100)
+ * @returns {object} { ok, score, totalLines, coveredLines, missedLines, missedByFile, summary }
+ */
+export function calculateDiffCoverage(coverageByFile, diffStr = "", options = {}) {
+  const root = options.root || process.cwd();
+  const minCoverage = typeof options.minCoverage === "number" ? options.minCoverage : 100;
+  const addedLinesMap = extractAddedLinesFromDiff(diffStr);
+
+  let totalLines = 0;
+  let coveredLines = 0;
+  const missedByFile = {};
+
+  for (const [file, addedLines] of addedLinesMap.entries()) {
+    const absPath = resolve(root, file);
+    if (!existsSync(absPath)) continue;
+
+    let sourceContent = "";
+    try {
+      sourceContent = readFileSync(absPath, "utf-8");
+    } catch (_) {
+      continue;
+    }
+
+    const v8Functions = coverageByFile.get(file) || [];
+    const lineHits = mapV8RangesToLines(sourceContent, v8Functions);
+
+    const missed = [];
+    for (const lineNo of addedLines) {
+      if (lineHits.has(lineNo)) {
+        totalLines++;
+        const count = lineHits.get(lineNo);
+        if (count > 0) {
+          coveredLines++;
+        } else {
+          missed.push(lineNo);
+        }
+      }
+    }
+
+    if (missed.length > 0) {
+      missedByFile[file] = missed;
+    }
+  }
+
+  const score = totalLines > 0 ? Math.round((coveredLines / totalLines) * 10000) / 100 : 100;
+  const ok = score >= minCoverage;
+
+  return {
+    ok,
+    score,
+    minCoverage,
+    totalLines,
+    coveredLines,
+    missedLines: totalLines - coveredLines,
+    missedByFile,
+    summary: `Diff Coverage: ${score}% (${coveredLines}/${totalLines} added executable lines covered, min: ${minCoverage}%)`,
+  };
+}

package/src/engine.mjs

@@ -14,7 +14,7 @@ import { appendTelemetry as appendTelemetryUnsafe } from "./telemetry.mjs";
 
 import { spawn } from "node:child_process";
 import { resolveAffectedTests, executeQueueDag } from "./dag-engine.mjs";
-import { recordRemediation, queryRemediations, harvestFailureRecord, hydrateMemory } from "./remediation.mjs";
+import { recordRemediation, queryRemediations, harvestFailureRecord, hydrateMemory, createWhackAMoleDetector } from "./remediation.mjs";
 import { hydratePrompt, harvestFailure } from "./memory.mjs";
 import { resolveRolePrompt } from "./role-resolver.mjs";
 
@@ -593,17 +593,23 @@ export async function repair(failure, opts = {}) {
     threshold: 2,
     cooldownMs: 60000,
   });
+  const whackAMole = createWhackAMoleDetector({
+    maxHistory: Math.max(maxRetries + 2, 8),
+    threshold: 2,
+  });
 
   let currentFailure = failure;
   const initialFingerprint = fingerprintFailureState(currentFailure, root);
   breaker.observe(initialFingerprint);
+  whackAMole.recordTestOutcome(currentFailure.stderr || currentFailure.message);
+  let extraPromptDirective = null;
 
   for (let n = 1; n <= maxRetries; n++) {
     if (progressBus && progressToken) {
       progressBus.reportProgress(progressToken, Math.round((n / maxRetries) * 100), 100, `OODA Repair attempt ${n}/${maxRetries}`);
     }
 
-    const repairPrompt = buildRepairPrompt(currentFailure, n, config);
+    const repairPrompt = buildRepairPrompt(currentFailure, n, config, extraPromptDirective);
     let session;
     try {
       session = await withBudget(
@@ -657,6 +663,7 @@ export async function repair(failure, opts = {}) {
     const gateRes = await gate({ root, config, fix: false, progressBus, progressToken });
     if (gateRes.ok) {
       breaker.reset();
+      whackAMole.reset();
       recordRemediation(root, {
         fingerprint: initialFingerprint,
         symptom: currentFailure.stderr || currentFailure.message || "Failure resolved by OODA repair",
@@ -669,6 +676,12 @@ export async function repair(failure, opts = {}) {
     currentFailure = gateRes.phases.find((p) => p.phase === "verify")?.testResult || failure;
     const currentFingerprint = fingerprintFailureState(currentFailure, root);
 
+    // Whack-a-Mole test-oscillation check
+    const whackCheck = whackAMole.recordTestOutcome(currentFailure.stderr || currentFailure.message);
+    if (whackCheck.whackAMole) {
+      extraPromptDirective = whackCheck.promptDirective;
+    }
+
     const check = breaker.observe(currentFingerprint);
     if (check.tripped) {
       harvestFailureRecord(root, {
@@ -800,13 +813,16 @@ export async function pollSessionState(provider, session, opts = {}) {
   return { ...session, status: String(session.status || "COMPLETED").toUpperCase() };
 }
 
-function buildRepairPrompt(failure, attempt, _config) {
+function buildRepairPrompt(failure, attempt, _config, extraPromptDirective = null) {
   const cleanStderr = redactSecrets(failure.stderr || failure.stdout || "Unknown Error");
 
   let escalationStrategy = "DIRECT_REPAIR";
   let escalationDirective = "1. Ground your fix strictly in the error log below. Do NOT guess file contents or function signatures.";
 
-  if (attempt === 2) {
+  if (extraPromptDirective) {
+    escalationStrategy = "WHACK_A_MOLE_PIVOT";
+    escalationDirective = `1. ARCHITECTURAL PIVOT: ${extraPromptDirective}`;
+  } else if (attempt === 2) {
     escalationStrategy = "DIAGNOSTIC_ANALYSIS";
     escalationDirective = "1. DIAGNOSE FIRST: Two attempts have failed. Analyze if the root cause is in a different file or component than where the previous patch was applied.";
   } else if (attempt >= 3) {

package/src/git.mjs

@@ -1,6 +1,6 @@
 import { execFileSync, execSync } from "node:child_process";
 import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, delimiter } from "node:path";
 import { normalizePath } from "./config.mjs";
 
 
@@ -18,6 +18,118 @@ export class GateError extends Error {
 const DEFAULT_TIMEOUT = 10 * 60 * 1000; // 10 minutes
 const DEFAULT_MAX_BUFFER = 10 * 1024 * 1024; // 10 MB
 
+// Windows cmd.exe quoting. `.cmd`/`.bat` shims (npm.cmd, claude.cmd, …) cannot
+// be spawned by CreateProcess, so they must run through cmd.exe, and the
+// command line cmd.exe sees must round-trip every argv element exactly. The
+// rules below follow the C runtime's argument parser and cmd.exe's meta-char
+// escaping — the same algorithm cross-spawn uses — reimplemented here so the
+// kit stays dependency-free.
+
+// Characters cmd.exe treats specially outside double quotes.
+const WINDOWS_META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+// A real Windows executable, which CreateProcess can start without a shell.
+const WINDOWS_NATIVE_EXE = /\.(?:com|exe)$/i;
+// An npm-style cmd shim, which re-parses its own arguments and therefore needs
+// its meta chars double-escaped.
+const WINDOWS_CMD_SHIM = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i;
+
+/** Escapes cmd.exe meta characters in a command *name*. */
+export function windowsEscapeCommand(command) {
+  return String(command).replace(WINDOWS_META_CHARS, "^$1");
+}
+
+/**
+ * Quotes a single argv element for cmd.exe.
+ *
+ * @param {string} arg
+ * @param {boolean} [doubleEscapeMetaChars] true when the command is a cmd-shim
+ *   that will re-parse its own arguments (node_modules/.bin/*.cmd).
+ * @returns {string}
+ */
+export function windowsEscapeArgument(arg, doubleEscapeMetaChars = false) {
+  let ret = String(arg);
+  // Backslash runs immediately before a double quote: double the backslashes
+  // and escape the quote.
+  ret = ret.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+  // A backslash run at the very end will sit in front of the closing quote we
+  // add next: double it so it stays literal.
+  ret = ret.replace(/(?=(\\+?)?)\1$/, "$1$1");
+  ret = `"${ret}"`;
+  ret = ret.replace(WINDOWS_META_CHARS, "^$1");
+  if (doubleEscapeMetaChars) ret = ret.replace(WINDOWS_META_CHARS, "^$1");
+  return ret;
+}
+
+/**
+ * Resolves `binary` against PATH + PATHEXT on Windows.
+ *
+ * @param {string} binary
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string | null}
+ */
+function resolveWindowsCommand(binary, env) {
+  const pathExt = (env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.trim()).filter(Boolean);
+  const hasSeparator = /[\\/]/.test(binary) || /^[A-Za-z]:/.test(binary);
+
+  const candidates = [];
+  if (hasSeparator) {
+    candidates.push(binary);
+    for (const ext of pathExt) candidates.push(binary + ext);
+  } else {
+    const dirs = (env.PATH || "").split(delimiter).filter(Boolean);
+    for (const dir of dirs) {
+      for (const ext of pathExt) candidates.push(join(dir, binary + ext));
+      candidates.push(join(dir, binary));
+    }
+  }
+
+  for (const candidate of candidates) {
+    try {
+      if (existsSync(candidate)) return candidate;
+    } catch (_) {}
+  }
+  return null;
+}
+
+/**
+ * Builds the spawn arguments that correctly execute `binary` with `args` on
+ * Windows, handling the `.cmd`/`.bat` shims package managers and CLI providers
+ * install. Returns null on non-Windows so callers keep spawning the binary
+ * directly (`P-07`).
+ *
+ * @param {string} binary
+ * @param {string[]} args
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {NodeJS.Platform} [platform]
+ * @returns {{ file: string, args: string[], verbatim: boolean } | null}
+ */
+export function resolveWindowsSpawn(binary, args, env = process.env, platform = process.platform) {
+  if (platform !== "win32") return null;
+
+  const argArray = (args || []).map((a) => String(a));
+  const resolved = resolveWindowsCommand(binary, env);
+
+  // A native executable is spawned directly — its argv needs no quoting.
+  if (resolved && WINDOWS_NATIVE_EXE.test(resolved)) {
+    return { file: resolved, args: argArray, verbatim: false };
+  }
+
+  // Everything else (`.cmd`, `.bat`, or an unresolved name) goes through
+  // cmd.exe. The `/s /c` invocation plus one outer quote pair is the shape
+  // cmd.exe expects so the pre-quoted argv parses back into the same elements.
+  const commandName = resolved || binary;
+  const doubleEscape = WINDOWS_CMD_SHIM.test(resolved || commandName);
+  const shellCommand = [windowsEscapeCommand(commandName)]
+    .concat(argArray.map((a) => windowsEscapeArgument(a, doubleEscape)))
+    .join(" ");
+
+  return {
+    file: (env && env.ComSpec) || "cmd.exe",
+    args: ["/d", "/s", "/c", `"${shellCommand}"`],
+    verbatim: true,
+  };
+}
+
 export function runCmd(command, opts = {}) {
   const cwd = opts.cwd || process.cwd();
   const timeout = opts.timeout || DEFAULT_TIMEOUT;
@@ -53,14 +165,23 @@ export function runCmd(command, opts = {}) {
   // Windows install, and the gate reported it as a plain non-zero verification
   // rather than as an environment problem.
   //
-  // Node's `shell: true` rebuilds the command line as `[file, ...args].join(" ")`
-  // and passes it to cmd.exe verbatim. That reconstruction is normally lossy —
-  // it does not quote an argument containing a space — but it is exact here,
-  // because these tokens were produced by splitting on whitespace in the first
-  // place. It is also only reached when the command contains no shell
-  // metacharacter, since those take the execSync branch above. An array command
-  // is excluded: its elements may legitimately contain spaces.
+  // A whitespace-split string command is re-run under `shell: true`: Node
+  // rebuilds the command line as `[file, ...args].join(" ")` and passes it to
+  // cmd.exe verbatim. That reconstruction is normally lossy — it does not quote
+  // an argument containing a space — but it is exact here, because these tokens
+  // were produced by splitting on whitespace in the first place, and none of
+  // them can contain a shell metacharacter (those took the execSync branch).
+  //
+  // An *array* command cannot use that trick: its elements may legitimately
+  // contain spaces, so the same join would corrupt argv. Arrays are therefore
+  // wrapped in cmd.exe with every element quoted per the C-runtime + cmd.exe
+  // rules, which preserves argv exactly while still letting the shell resolve
+  // the `.cmd` shim (P-07).
   const winShim = tokenized && process.platform === "win32";
+  const winSpawn =
+    !useShell && !winShim && process.platform === "win32"
+      ? resolveWindowsSpawn(binary, args, opts.env || process.env)
+      : null;
 
   if (!binary && !useShell) {
     if (opts.ignoreError) return { status: 0, stdout: "", stderr: "" };
@@ -77,10 +198,11 @@ export function runCmd(command, opts = {}) {
           timeout,
           maxBuffer,
         })
-      : execFileSync(binary, args, {
+      : execFileSync(winSpawn ? winSpawn.file : binary, winSpawn ? winSpawn.args : args, {
           cwd,
           encoding: "utf-8",
           shell: winShim,
+          windowsVerbatimArguments: Boolean(winSpawn && winSpawn.verbatim),
           stdio: ["ignore", "pipe", "pipe"],
           env: opts.env || process.env,
           timeout,