@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.6

package/lib/planning-signal-freshness.js

@@ -0,0 +1,205 @@
+const fs = require("fs");
+const path = require("path");
+const { pathExists } = require("./utils");
+
+function normalizeSurface(surface) {
+  return String(surface || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function collectMarkdownFilesRecursive(rootPath) {
+  if (!rootPath || !pathExists(rootPath)) {
+    return [];
+  }
+
+  const pending = [rootPath];
+  const seenDirs = new Set();
+  const files = [];
+
+  while (pending.length > 0) {
+    const current = pending.pop();
+    let realDir = null;
+    try {
+      realDir = fs.realpathSync(current);
+    } catch (_error) {
+      continue;
+    }
+    if (seenDirs.has(realDir)) {
+      continue;
+    }
+    seenDirs.add(realDir);
+
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch (_error) {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(absolutePath);
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        let stat = null;
+        try {
+          stat = fs.statSync(absolutePath);
+        } catch (_error) {
+          continue;
+        }
+        if (stat.isDirectory()) {
+          pending.push(absolutePath);
+          continue;
+        }
+        if (stat.isFile() && /\.md$/i.test(entry.name)) {
+          files.push(absolutePath);
+        }
+        continue;
+      }
+      if (entry.isFile() && /\.md$/i.test(entry.name)) {
+        files.push(absolutePath);
+      }
+    }
+  }
+
+  return files;
+}
+
+function collectSurfaceArtifacts(projectRoot, changeId, surface) {
+  const workflowRoot = path.join(projectRoot, ".da-vinci");
+  const changeDir = path.join(workflowRoot, "changes", String(changeId || "").trim());
+  const normalizedSurface = normalizeSurface(surface);
+  if (!normalizedSurface || !pathExists(changeDir)) {
+    return [];
+  }
+
+  const artifactPaths = new Set();
+  const addIfExists = (targetPath) => {
+    if (targetPath && pathExists(targetPath)) {
+      artifactPaths.add(path.resolve(targetPath));
+    }
+  };
+
+  const addCommonSpecArtifacts = () => {
+    const specsRoot = path.join(changeDir, "specs");
+    for (const filePath of collectMarkdownFilesRecursive(specsRoot)) {
+      addIfExists(filePath);
+    }
+  };
+
+  if (normalizedSurface === "lint-spec") {
+    addCommonSpecArtifacts();
+    addIfExists(path.join(changeDir, "proposal.md"));
+    addIfExists(path.join(changeDir, "design-brief.md"));
+    addIfExists(path.join(changeDir, "design.md"));
+    addIfExists(path.join(changeDir, "tasks.md"));
+    addIfExists(path.join(changeDir, "verification.md"));
+    addIfExists(path.join(changeDir, "pencil-design.md"));
+    addIfExists(path.join(changeDir, "pencil-bindings.md"));
+    addIfExists(path.join(projectRoot, "DA-VINCI.md"));
+    addIfExists(path.join(projectRoot, "openspec", "config.yaml"));
+    return Array.from(artifactPaths);
+  }
+
+  if (normalizedSurface === "scope-check") {
+    addCommonSpecArtifacts();
+    addIfExists(path.join(changeDir, "proposal.md"));
+    addIfExists(path.join(changeDir, "tasks.md"));
+    addIfExists(path.join(changeDir, "verification.md"));
+    addIfExists(path.join(changeDir, "pencil-design.md"));
+    addIfExists(path.join(changeDir, "pencil-bindings.md"));
+    addIfExists(path.join(workflowRoot, "page-map.md"));
+    addIfExists(path.join(changeDir, "page-map.md"));
+    return Array.from(artifactPaths);
+  }
+
+  if (normalizedSurface === "lint-tasks") {
+    addCommonSpecArtifacts();
+    addIfExists(path.join(changeDir, "proposal.md"));
+    addIfExists(path.join(changeDir, "design-brief.md"));
+    addIfExists(path.join(changeDir, "design.md"));
+    addIfExists(path.join(changeDir, "tasks.md"));
+    addIfExists(path.join(changeDir, "pencil-bindings.md"));
+    addIfExists(path.join(changeDir, "pencil-design.md"));
+    addIfExists(path.join(changeDir, "verification.md"));
+    addIfExists(path.join(workflowRoot, "page-map.md"));
+    addIfExists(path.join(changeDir, "page-map.md"));
+    return Array.from(artifactPaths);
+  }
+
+  return [];
+}
+
+function latestMtimeMs(paths) {
+  let latest = 0;
+  for (const targetPath of Array.isArray(paths) ? paths : []) {
+    let stat = null;
+    try {
+      stat = fs.statSync(targetPath);
+    } catch (_error) {
+      continue;
+    }
+    if (Number.isFinite(stat.mtimeMs) && stat.mtimeMs > latest) {
+      latest = stat.mtimeMs;
+    }
+  }
+  return latest;
+}
+
+function evaluatePlanningSignalFreshness(projectRoot, options = {}) {
+  const changeId = String(options.changeId || "").trim();
+  const surface = normalizeSurface(options.surface);
+  const signal = options.signal || null;
+  const artifactPaths = collectSurfaceArtifacts(projectRoot, changeId, surface);
+  const latestArtifactMtime = latestMtimeMs(artifactPaths);
+  const toleranceMs = Number.isFinite(Number(options.toleranceMs))
+    ? Math.max(0, Number(options.toleranceMs))
+    : 1000;
+
+  if (!changeId || !surface) {
+    return {
+      applicable: false,
+      fresh: true,
+      reasons: [],
+      artifactCount: artifactPaths.length,
+      latestArtifactMtimeMs: latestArtifactMtime,
+      signalTimestampMs: 0,
+      staleByMs: 0
+    };
+  }
+
+  const signalTimestampMs = Date.parse(String(signal && signal.timestamp ? signal.timestamp : ""));
+  const reasons = [];
+  if (!Number.isFinite(signalTimestampMs)) {
+    reasons.push("missing_or_invalid_signal_timestamp");
+  }
+  if (
+    latestArtifactMtime > 0 &&
+    Number.isFinite(signalTimestampMs) &&
+    signalTimestampMs + toleranceMs < latestArtifactMtime
+  ) {
+    reasons.push("artifact_newer_than_signal");
+  }
+
+  return {
+    applicable: true,
+    fresh: reasons.length === 0,
+    reasons,
+    artifactCount: artifactPaths.length,
+    latestArtifactMtimeMs: latestArtifactMtime,
+    signalTimestampMs: Number.isFinite(signalTimestampMs) ? signalTimestampMs : 0,
+    staleByMs:
+      Number.isFinite(signalTimestampMs) && latestArtifactMtime > signalTimestampMs + toleranceMs
+        ? latestArtifactMtime - (signalTimestampMs + toleranceMs)
+        : 0
+  };
+}
+
+module.exports = {
+  evaluatePlanningSignalFreshness
+};