@xenonbyte/da-vinci-workflow 0.2.4 → 0.2.6

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/task-review.js

@@ -123,7 +123,8 @@ function writeTaskReviewEnvelope(projectPathInput, options = {}) {
 
   if (envelope.stage === "quality") {
     const specSignal = findLatestTaskReviewSignal(existingSignals, envelope.taskGroupId, "spec");
-    if (!specSignal || String(specSignal.status || "").toUpperCase() !== "PASS") {
+    const specStatus = specSignal ? String(specSignal.status || "").toUpperCase() : "";
+    if (!specSignal || specStatus !== "PASS") {
       throw new Error(
         `Quality review for task group ${envelope.taskGroupId} requires a prior spec review PASS.`
       );

package/lib/utils.js

@@ -28,10 +28,41 @@ function readTextIfExists(targetPath, options = {}) {
   return fs.readFileSync(targetPath, encoding);
 }
 
+function normalizeRelativePath(relativePath) {
+  return String(relativePath || "")
+    .split(path.sep)
+    .filter(Boolean)
+    .join("/");
+}
+
+function pathWithinRoot(projectRoot, candidatePath) {
+  const root = path.resolve(projectRoot);
+  const candidate = path.resolve(candidatePath);
+  if (candidate === root) {
+    return true;
+  }
+  const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+  return candidate.startsWith(prefix);
+}
+
 function uniqueValues(values) {
   return Array.from(new Set((values || []).filter(Boolean)));
 }
 
+function dedupeMessages(items, options = {}) {
+  const normalize =
+    typeof options.normalize === "function"
+      ? options.normalize
+      : (value) => value;
+  return Array.from(
+    new Set(
+      (Array.isArray(items) ? items : [])
+        .map((item) => normalize(item))
+        .filter(Boolean)
+    )
+  );
+}
+
 function parseJsonText(raw, context = "JSON payload") {
   try {
     return JSON.parse(String(raw));
@@ -120,7 +151,10 @@ module.exports = {
   escapeRegExp,
   pathExists,
   readTextIfExists,
+  normalizeRelativePath,
+  pathWithinRoot,
   uniqueValues,
+  dedupeMessages,
   parseJsonText,
   readJsonFile,
   sleepSync,