@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/lib/sidecars.js

@@ -17,6 +17,87 @@ const {
 
 const SCHEMA_VERSION = "1.0.0";
 
+function readJsonIfExists(targetPath) {
+  if (!targetPath || !pathExists(targetPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(targetPath, "utf8"));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function normalizeEvidenceText(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function resolveProjectRootFromChangeDir(changeDir) {
+  return path.resolve(changeDir || process.cwd(), "..", "..", "..");
+}
+
+function resolveSourceRefAbsolutePath(projectRoot, sourceRefPath) {
+  const sourcePath = String(sourceRefPath || "").trim();
+  if (!sourcePath) {
+    return null;
+  }
+  if (path.isAbsolute(sourcePath)) {
+    return sourcePath;
+  }
+  return path.join(projectRoot, sourcePath);
+}
+
+function evaluateSourceRefsFreshness(changeDir, payload) {
+  const sourceRefs = Array.isArray(payload && payload.sourceRefs) ? payload.sourceRefs : [];
+  if (sourceRefs.length === 0) {
+    return {
+      fresh: false,
+      checked: 0,
+      stale: ["missing_source_refs"]
+    };
+  }
+  const projectRoot = resolveProjectRootFromChangeDir(changeDir);
+  const stale = [];
+  for (const ref of sourceRefs) {
+    const absolutePath = resolveSourceRefAbsolutePath(projectRoot, ref && ref.path);
+    if (!absolutePath || !pathExists(absolutePath)) {
+      stale.push(`missing:${String((ref && ref.path) || "").trim() || "(unknown)"}`);
+      continue;
+    }
+    const expected = String((ref && ref.digest) || "").trim();
+    const actual = digestFile(absolutePath);
+    if (expected && actual && expected !== actual) {
+      stale.push(`digest_mismatch:${String(ref.path || absolutePath)}`);
+    }
+  }
+
+  return {
+    fresh: stale.length === 0,
+    checked: sourceRefs.length,
+    stale
+  };
+}
+
+function buildCollectionTextIdMap(items, idField = "id", textField = "text") {
+  const map = new Map();
+  for (const item of Array.isArray(items) ? items : []) {
+    const id = String(item && item[idField] ? item[idField] : "").trim();
+    const text = normalizeEvidenceText(item && item[textField]);
+    if (!id || !text) {
+      continue;
+    }
+    if (!map.has(text)) {
+      map.set(text, []);
+    }
+    map.get(text).push(id);
+  }
+  return map;
+}
+
 function buildEnvelope(projectRoot) {
   return {
     status: STATUS.PASS,
@@ -241,6 +322,316 @@ function writeSidecarFile(sidecarsDir, fileName, payload) {
   return absolutePath;
 }
 
+function loadPlanningAnchorIndex(changeDir) {
+  const sidecarsDir = path.join(changeDir, "sidecars");
+  const spec = readJsonIfExists(path.join(sidecarsDir, "spec.index.json"));
+  const bindings = readJsonIfExists(path.join(sidecarsDir, "bindings.index.json"));
+  const notes = [];
+  const warnings = [];
+
+  if (!pathExists(sidecarsDir)) {
+    notes.push("Planning sidecars are missing; anchor resolution will use artifact fallback.");
+    return {
+      sidecarsDir,
+      available: false,
+      index: {
+        behavior: new Set(),
+        acceptance: new Set(),
+        state: new Set(),
+        mapping: new Set()
+      },
+      notes,
+      warnings
+    };
+  }
+
+  if (!spec) {
+    warnings.push("Missing or unreadable `spec.index.json` in sidecars.");
+  }
+  if (!bindings) {
+    warnings.push("Missing or unreadable `bindings.index.json` in sidecars.");
+  }
+
+  const specFreshness = spec ? evaluateSourceRefsFreshness(changeDir, spec) : null;
+  const bindingsFreshness = bindings ? evaluateSourceRefsFreshness(changeDir, bindings) : null;
+  if (specFreshness && !specFreshness.fresh) {
+    warnings.push(
+      `spec.index.json appears stale (${specFreshness.stale.join(", ")}); anchor resolution will degrade.`
+    );
+  }
+  if (bindingsFreshness && !bindingsFreshness.fresh) {
+    warnings.push(
+      `bindings.index.json appears stale (${bindingsFreshness.stale.join(", ")}); anchor resolution will degrade.`
+    );
+  }
+
+  const behavior = new Set(
+    ((spec && spec.collections && spec.collections.behavior) || []).map((item) => item.id)
+  );
+  const acceptance = new Set(
+    ((spec && spec.collections && spec.collections.acceptance) || []).map((item) => item.id)
+  );
+  const state = new Set(
+    ((spec && spec.collections && spec.collections.states) || []).map((item) => item.id)
+  );
+  const mapping = new Set(((bindings && bindings.mappings) || []).map((item) => item.id));
+
+  const sourceFresh =
+    (!specFreshness || specFreshness.fresh) && (!bindingsFreshness || bindingsFreshness.fresh);
+  const available =
+    sourceFresh && (behavior.size > 0 || acceptance.size > 0 || state.size > 0 || mapping.size > 0);
+  if (!available) {
+    if (!sourceFresh) {
+      notes.push("Planning sidecars exist but are stale; anchor resolution falls back to artifact evidence.");
+    } else {
+      notes.push("Planning sidecars are present but empty for anchor id resolution.");
+    }
+  }
+
+  return {
+    sidecarsDir,
+    available,
+    fresh: sourceFresh,
+    freshness: {
+      spec: specFreshness,
+      bindings: bindingsFreshness
+    },
+    index: {
+      behavior,
+      acceptance,
+      state,
+      mapping
+    },
+    raw: {
+      spec,
+      bindings
+    },
+    notes,
+    warnings
+  };
+}
+
+function resolvePlanningAnchorRefs(anchorRefs, options = {}) {
+  const refs = Array.isArray(anchorRefs) ? anchorRefs : [];
+  const sidecarIndex = options.sidecarIndex || {
+    available: false,
+    index: {
+      behavior: new Set(),
+      acceptance: new Set(),
+      state: new Set(),
+      mapping: new Set()
+    }
+  };
+  const artifactResolver = typeof options.resolveArtifactRef === "function" ? options.resolveArtifactRef : null;
+  const anchorIdResolver = typeof options.resolveAnchorIdRef === "function" ? options.resolveAnchorIdRef : null;
+
+  const resolved = [];
+  const unresolved = [];
+  const notes = [];
+
+  for (const ref of refs) {
+    const normalized = String(ref || "").trim();
+    if (!normalized) {
+      continue;
+    }
+
+    const familyMatch = normalized.match(/^(behavior|acceptance|state|mapping)-/i);
+    if (familyMatch) {
+      const family = String(familyMatch[1] || "").toLowerCase();
+      if (sidecarIndex.available && sidecarIndex.index[family] && sidecarIndex.index[family].has(normalized)) {
+        resolved.push({
+          ref: normalized,
+          source: "sidecar",
+          family
+        });
+      } else {
+        let fallback = null;
+        if (anchorIdResolver) {
+          fallback = anchorIdResolver({
+            ref: normalized,
+            family,
+            sidecarAvailable: sidecarIndex.available,
+            sidecarFresh: sidecarIndex.fresh !== false
+          });
+          if (fallback && fallback.ok) {
+            resolved.push({
+              ref: normalized,
+              source: fallback.source || "artifact-parse",
+              family
+            });
+            if (fallback.note) {
+              notes.push(String(fallback.note));
+            }
+            continue;
+          }
+        }
+        const fallbackReason =
+          fallback && fallback.reason ? String(fallback.reason).trim() : "";
+        const fallbackClassification =
+          fallback && fallback.classification ? String(fallback.classification).trim() : "";
+        unresolved.push({
+          ref: normalized,
+          reason:
+            fallbackReason ||
+            (sidecarIndex.available ? "unknown_sidecar_id" : "sidecar_unavailable"),
+          family,
+          classification: fallbackClassification ||
+            (sidecarIndex.available || sidecarIndex.fresh === false || fallbackReason
+              ? "invalid_or_stale_sidecar_anchor"
+              : "sidecar_not_available")
+        });
+      }
+      continue;
+    }
+
+    const artifactMatch = normalized.match(/^artifact:([^#\s]+)(?:#(.+))?$/i);
+    if (artifactMatch && artifactResolver) {
+      const artifactPath = String(artifactMatch[1] || "").trim();
+      const artifactToken = String(artifactMatch[2] || "").trim();
+      const artifactResult = artifactResolver({
+        artifactPath,
+        artifactToken
+      });
+      if (artifactResult && artifactResult.ok) {
+        resolved.push({
+          ref: normalized,
+          source: "artifact",
+          artifactPath,
+          artifactToken
+        });
+      } else {
+        unresolved.push({
+          ref: normalized,
+          reason:
+            artifactResult && artifactResult.reason ? artifactResult.reason : "artifact_ref_unresolved"
+        });
+      }
+      continue;
+    }
+
+    unresolved.push({
+      ref: normalized,
+      reason: "unsupported_anchor_format",
+      classification: "malformed_anchor"
+    });
+  }
+
+  if (!sidecarIndex.available) {
+    notes.push("Anchor id resolution degraded: sidecars unavailable; artifact refs are preferred.");
+  }
+
+  return {
+    resolved,
+    unresolved,
+    notes
+  };
+}
+
+function loadAnalyzeEvidenceIndex(changeDir) {
+  const sidecarIndex = loadPlanningAnchorIndex(changeDir);
+  const sidecarsDir = sidecarIndex.sidecarsDir;
+  const spec = sidecarIndex.raw && sidecarIndex.raw.spec ? sidecarIndex.raw.spec : null;
+  const bindings = sidecarIndex.raw && sidecarIndex.raw.bindings ? sidecarIndex.raw.bindings : null;
+
+  const behaviorMap = buildCollectionTextIdMap(spec && spec.collections && spec.collections.behavior);
+  const acceptanceMap = buildCollectionTextIdMap(spec && spec.collections && spec.collections.acceptance);
+  const stateMap = buildCollectionTextIdMap(spec && spec.collections && spec.collections.states);
+  const mappingByImplementation = new Map();
+  for (const mapping of (bindings && bindings.mappings) || []) {
+    const implementation = String(mapping && mapping.implementation ? mapping.implementation : "").trim();
+    if (!implementation) {
+      continue;
+    }
+    const normalized = implementation.replace(/\\/g, "/");
+    if (!mappingByImplementation.has(normalized)) {
+      mappingByImplementation.set(normalized, []);
+    }
+    mappingByImplementation.get(normalized).push(String(mapping.id || "").trim());
+  }
+
+  return {
+    sidecarsDir,
+    available: sidecarIndex.available,
+    fresh: sidecarIndex.fresh === true,
+    notes: sidecarIndex.notes.slice(),
+    warnings: sidecarIndex.warnings.slice(),
+    maps: {
+      behavior: behaviorMap,
+      acceptance: acceptanceMap,
+      state: stateMap,
+      mappingByImplementation
+    }
+  };
+}
+
+function resolveAnalyzeEvidenceRefs(evidenceItems, options = {}) {
+  const items = Array.isArray(evidenceItems) ? evidenceItems : [];
+  const index = options.index || {
+    available: false,
+    maps: {
+      behavior: new Map(),
+      acceptance: new Map(),
+      state: new Map(),
+      mappingByImplementation: new Map()
+    }
+  };
+  const refs = [];
+  const notes = [];
+
+  for (const item of items) {
+    const artifactPath = String(item && item.artifactPath ? item.artifactPath : "").trim();
+    const itemText = String(item && item.itemText ? item.itemText : "").trim();
+    const kind = String(item && item.kind ? item.kind : "").trim().toLowerCase();
+    const implementationPath = String(item && item.implementationPath ? item.implementationPath : "").trim();
+    const normalizedText = normalizeEvidenceText(itemText);
+
+    if (index.available && normalizedText) {
+      const candidateIds = [];
+      if (kind === "behavior" && index.maps.behavior.has(normalizedText)) {
+        candidateIds.push(...index.maps.behavior.get(normalizedText));
+      }
+      if (kind === "acceptance" && index.maps.acceptance.has(normalizedText)) {
+        candidateIds.push(...index.maps.acceptance.get(normalizedText));
+      }
+      if (kind === "state" && index.maps.state.has(normalizedText)) {
+        candidateIds.push(...index.maps.state.get(normalizedText));
+      }
+      for (const id of candidateIds) {
+        refs.push(`sidecar:${id}`);
+      }
+    }
+
+    if (index.available && implementationPath) {
+      const normalizedImplementation = implementationPath.replace(/\\/g, "/");
+      const mappingIds = index.maps.mappingByImplementation.get(normalizedImplementation) || [];
+      for (const id of mappingIds) {
+        refs.push(`sidecar:${id}`);
+      }
+    }
+
+    if (artifactPath) {
+      const fallbackToken = itemText
+        ? itemText
+            .split(/\s+/)
+            .slice(0, 8)
+            .join(" ")
+        : "";
+      refs.push(
+        fallbackToken ? `artifact:${artifactPath}#${fallbackToken}` : `artifact:${artifactPath}`
+      );
+    }
+  }
+
+  if (!index.available) {
+    notes.push("Analyze evidence mapping degraded to artifact refs because sidecars are unavailable or stale.");
+  }
+
+  return {
+    refs: unique(refs),
+    notes
+  };
+}
+
 function generatePlanningSidecars(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const write = options.write !== false;
@@ -365,5 +756,9 @@ function formatGenerateSidecarsReport(result) {
 module.exports = {
   SCHEMA_VERSION,
   generatePlanningSidecars,
-  formatGenerateSidecarsReport
+  formatGenerateSidecarsReport,
+  loadPlanningAnchorIndex,
+  resolvePlanningAnchorRefs,
+  loadAnalyzeEvidenceIndex,
+  resolveAnalyzeEvidenceRefs
 };

package/lib/supervisor-review.js

@@ -1,7 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execFile } = require("child_process");
+const { spawn } = require("child_process");
 const {
   escapeRegExp,
   isPlainObject,
@@ -120,6 +120,19 @@ function truncateForError(value, maxLength = 240) {
   return `${text.slice(0, maxLength)}...`;
 }
 
+function buildReviewerExecutionDiagnostics(stdout, stderr) {
+  const diagnostics = [];
+  const normalizedStderr = truncateForError(stderr, 600);
+  const normalizedStdout = truncateForError(stdout, 600);
+  if (normalizedStderr) {
+    diagnostics.push(`stderr: ${normalizedStderr}`);
+  }
+  if (normalizedStdout) {
+    diagnostics.push(`stdout: ${normalizedStdout}`);
+  }
+  return diagnostics;
+}
+
 function parseReviewerPayload(rawText) {
   const payload = parseJsonText(String(rawText || "").trim(), "reviewer JSON payload");
   if (!isPlainObject(payload)) {
@@ -146,8 +159,97 @@ function parseReviewerPayload(rawText) {
 
 function execFileAsync(command, args, options = {}) {
   return new Promise((resolve, reject) => {
-    execFile(command, args, options, (error, stdout, stderr) => {
-      if (error) {
+    const encoding = options.encoding || "utf8";
+    const maxBuffer = Number.isFinite(options.maxBuffer) && options.maxBuffer > 0 ? options.maxBuffer : Infinity;
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    let finished = false;
+    let timedOut = false;
+    let overflowed = false;
+    let stdoutSize = 0;
+    let stderrSize = 0;
+    const stdoutChunks = [];
+    const stderrChunks = [];
+
+    function finalizeError(error) {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      error.stdout = Buffer.concat(stdoutChunks).toString(encoding);
+      error.stderr = Buffer.concat(stderrChunks).toString(encoding);
+      reject(error);
+    }
+
+    function pushChunk(target, chunk, currentSize) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk || ""), encoding);
+      const nextSize = currentSize + buffer.length;
+      target.push(buffer);
+      return nextSize;
+    }
+
+    const timeoutMs = Number.isFinite(options.timeout) && options.timeout > 0 ? options.timeout : 0;
+    const timeoutId =
+      timeoutMs > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            child.kill();
+          }, timeoutMs)
+        : null;
+
+    child.on("error", (error) => {
+      finalizeError(error);
+    });
+
+    child.stdout.on("data", (chunk) => {
+      stdoutSize = pushChunk(stdoutChunks, chunk, stdoutSize);
+      if (stdoutSize > maxBuffer && !overflowed) {
+        overflowed = true;
+        const error = new Error("stdout maxBuffer length exceeded");
+        error.code = "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+        child.kill();
+        finalizeError(error);
+      }
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderrSize = pushChunk(stderrChunks, chunk, stderrSize);
+      if (stderrSize > maxBuffer && !overflowed) {
+        overflowed = true;
+        const error = new Error("stderr maxBuffer length exceeded");
+        error.code = "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+        child.kill();
+        finalizeError(error);
+      }
+    });
+
+    child.on("close", (code, signal) => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      const stdout = Buffer.concat(stdoutChunks).toString(encoding);
+      const stderr = Buffer.concat(stderrChunks).toString(encoding);
+      if (timedOut || code !== 0) {
+        const error = new Error(
+          timedOut
+            ? `Process timed out after ${timeoutMs}ms`
+            : `Process exited with code ${code !== null ? code : "unknown"}`
+        );
+        error.code = code;
+        error.signal = signal;
+        error.killed = timedOut;
         error.stdout = stdout;
         error.stderr = stderr;
         reject(error);
@@ -241,11 +343,12 @@ async function runReviewerWithCodexOnce(options = {}) {
     for (const screenshotPath of screenshotPaths || []) {
       args.push("-i", screenshotPath);
     }
-    args.push(prompt);
+    args.push("--", prompt);
 
     const timeoutValue = normalizePositiveInt(timeoutMs, 0, 0, 30 * 60 * 1000);
+    let execResult = null;
     try {
-      await execFileAsync(codexBin, args, {
+      execResult = await execFileAsync(codexBin, args, {
         encoding: "utf8",
         maxBuffer: resolvedMaxBuffer,
         timeout: timeoutValue > 0 ? timeoutValue : undefined
@@ -272,7 +375,15 @@ async function runReviewerWithCodexOnce(options = {}) {
     }
 
     if (!pathExists(outputPath)) {
-      throw new Error(`Reviewer \`${reviewer}\` completed but produced no output JSON.`);
+      const diagnostics = buildReviewerExecutionDiagnostics(
+        execResult && execResult.stdout,
+        execResult && execResult.stderr
+      );
+      throw new Error(
+        `Reviewer \`${reviewer}\` completed but produced no output JSON.${
+          diagnostics.length > 0 ? ` ${diagnostics.join(" | ")}` : ""
+        }`
+      );
     }
 
     return parseReviewerPayload(fs.readFileSync(outputPath, "utf8"));