@xenonbyte/da-vinci-workflow 0.1.25 → 0.2.1

package/lib/audit.js

@@ -1,8 +1,17 @@
 const fs = require("fs");
 const path = require("path");
-const { getStandardPenStatePath, readPenState, hashPenDocument, readPenDocument } = require("./pen-persistence");
+const {
+  getStandardPenStatePath,
+  readPenState,
+  hashPenDocument,
+  readPenDocument,
+  assertPenDocumentShape
+} = require("./pen-persistence");
 const { getSessionStatePath, readSessionState } = require("./pencil-session");
 const { isPathInside, listFilesRecursiveSafe } = require("./fs-safety");
+const { pathExists, readTextIfExists } = require("./utils");
+const { runModuleExportInWorker } = require("./async-offload");
+const { readExecutionSignals, summarizeSignalsBySurface } = require("./execution-signals");
 const {
   normalizeCheckpointLabel,
   parseCheckpointStatusMap,
@@ -30,17 +39,13 @@ const EXPORT_SCAN_LIMITS = Object.freeze({
   maxDepth: 4,
   maxEntries: 1200
 });
-
-function pathExists(targetPath) {
-  return fs.existsSync(targetPath);
-}
-
-function readTextIfExists(targetPath) {
-  if (!pathExists(targetPath)) {
-    return "";
-  }
-  return fs.readFileSync(targetPath, "utf8");
-}
+const PLANNING_SIGNAL_SURFACES = new Set(["lint-spec", "scope-check", "lint-tasks", "lint-bindings"]);
+const VERIFICATION_SIGNAL_SURFACES = new Set([
+  "verify-bindings",
+  "verify-implementation",
+  "verify-structure",
+  "verify-coverage"
+]);
 
 function listFilesRecursive(rootDir, limits = {}) {
   return listFilesRecursiveSafe(rootDir, {
@@ -200,6 +205,16 @@ function normalizeReviewerToken(value) {
   return String(value || "").trim().toLowerCase();
 }
 
+function buildBootstrapCommand(projectRoot, mode, changeId = null) {
+  const parts = ["da-vinci", "bootstrap-project", "--project", projectRoot];
+  if (changeId) {
+    parts.push("--change", changeId);
+  } else if (mode === "completion") {
+    parts.push("--change", "<change-id>");
+  }
+  return parts.join(" ");
+}
+
 function auditProject(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const mode = options.mode || "integrity";
@@ -246,6 +261,20 @@ function auditProject(projectPathInput, options = {}) {
 
   if (!pathExists(daVinciDir)) {
     failures.push("Missing `.da-vinci/` directory.");
+    addMissingArtifacts(projectRoot, [path.join(projectRoot, "DA-VINCI.md"), designsDir], failures);
+    const missingWorkflowArtifacts = [
+      path.join(daVinciDir, "project-inventory.md"),
+      path.join(daVinciDir, "page-map.md"),
+      designRegistryPath
+    ];
+    if (mode === "completion") {
+      addMissingArtifacts(projectRoot, missingWorkflowArtifacts, failures);
+    } else {
+      addMissingArtifacts(projectRoot, missingWorkflowArtifacts, warnings);
+    }
+    notes.push(
+      `Hint: scaffold the required workflow files with \`${buildBootstrapCommand(projectRoot, mode, options.changeId || null)}\`.`
+    );
     return {
       projectRoot,
       mode,
@@ -274,6 +303,12 @@ function auditProject(projectPathInput, options = {}) {
     addMissingArtifacts(projectRoot, completionRequiredArtifacts.slice(1, 4), warnings);
   }
 
+  if (failures.some((message) => message.startsWith("Missing required artifact: "))) {
+    notes.push(
+      `Hint: scaffold missing workflow artifacts with \`${buildBootstrapCommand(projectRoot, mode, options.changeId || null)}\`.`
+    );
+  }
+
   if (designSupervisorRequired && !designSupervisorConfigured) {
     const message =
       "DA-VINCI.md sets `Require Supervisor Review: true` but no `Design-supervisor reviewers` are configured.";
@@ -365,7 +400,15 @@ function auditProject(projectPathInput, options = {}) {
       continue;
     }
 
-    const persistedDocument = readPenDocument(registeredPenPath);
+    let persistedDocument;
+    try {
+      persistedDocument = assertPenDocumentShape(readPenDocument(registeredPenPath), registeredPenPath);
+    } catch (error) {
+      failures.push(
+        `Registered design source is not a valid .pen document: ${relativeTo(projectRoot, registeredPenPath)}`
+      );
+      continue;
+    }
     const currentHash = hashPenDocument(persistedDocument);
     if (state.snapshotHash !== currentHash) {
       failures.push(
@@ -396,16 +439,48 @@ function auditProject(projectPathInput, options = {}) {
         failures.push("Completion audit requires the Pencil session to be ended and recorded as `closed`.");
       }
 
+      if (sessionState.forceWithoutSync === true) {
+        const message =
+          "Pencil session was force-closed without a final live MCP sync verification. " +
+          "Run a fresh session persist/end cycle before completion.";
+        if (mode === "completion") {
+          failures.push(message);
+        } else {
+          warnings.push(message);
+        }
+      }
+
       if (sessionState.penPath && pathExists(sessionState.penPath)) {
-        const penState = readPenState(sessionState.penPath);
-        const persistedHash = penState && penState.snapshotHash ? String(penState.snapshotHash) : "";
-
-        if (sessionState.lastPersistedHash && persistedHash && sessionState.lastPersistedHash !== persistedHash) {
-          failures.push("Pencil session state hash does not match the current persisted `.pen` state hash.");
-        } else if (persistedHash) {
-          notes.push(
-            `Detected Pencil session state for ${relativeTo(projectRoot, sessionState.penPath)}.`
+        let sessionPenValid = true;
+        let currentPenDocument = null;
+        try {
+          currentPenDocument = assertPenDocumentShape(
+            readPenDocument(sessionState.penPath),
+            sessionState.penPath
+          );
+        } catch (error) {
+          failures.push(
+            `Session-bound .pen is not a valid document: ${relativeTo(projectRoot, sessionState.penPath)}`
           );
+          sessionPenValid = false;
+        }
+        if (sessionPenValid) {
+          const currentHash = hashPenDocument(currentPenDocument);
+          const penState = readPenState(sessionState.penPath);
+          const persistedHash = penState && penState.snapshotHash ? String(penState.snapshotHash) : "";
+
+          if (persistedHash && persistedHash !== currentHash) {
+            failures.push("Pencil session state metadata hash does not match the current `.pen` document on disk.");
+          } else if (
+            sessionState.lastPersistedHash &&
+            sessionState.lastPersistedHash !== currentHash
+          ) {
+            failures.push("Pencil session state hash does not match the current persisted `.pen` state hash.");
+          } else if (persistedHash) {
+            notes.push(
+              `Detected Pencil session state for ${relativeTo(projectRoot, sessionState.penPath)}.`
+            );
+          }
         }
       }
     }
@@ -486,7 +561,7 @@ function auditProject(projectPathInput, options = {}) {
       if (!review.found) {
         const message =
           `DA-VINCI.md configures Design-supervisor reviewers, but ${relativeTo(projectRoot, pencilDesignPath)} ` +
-          "does not record a `## Design-Supervisor Review` section.";
+          "does not record a `Design-Supervisor Review` section.";
         if (enforceAsFailure) {
           failures.push(message);
         } else {
@@ -643,7 +718,7 @@ function auditProject(projectPathInput, options = {}) {
       if (!hasAnyConcreteContextDelta) {
         pushUnique(
           warnings,
-          `Checkpoint-bearing artifacts in ${changeRel} do not record any concrete \`## Context Delta\` entries.`
+          `Checkpoint-bearing artifacts in ${changeRel} do not record any concrete \`Context Delta\` entries.`
         );
       } else {
         notes.push(`Detected context-delta recovery notes in ${changeRel}.`);
@@ -758,6 +833,48 @@ function auditProject(projectPathInput, options = {}) {
     }
   }
 
+  const signalSummary =
+    options && options.preloadedSignalSummary && typeof options.preloadedSignalSummary === "object"
+      ? options.preloadedSignalSummary
+      : summarizeSignalsBySurface(
+          readExecutionSignals(projectRoot, {
+            changeId: options.changeId || ""
+          })
+        );
+  for (const [surface, signal] of Object.entries(signalSummary)) {
+    if (surface === "signal-file-parse") {
+      const warningMessage =
+        Array.isArray(signal.warnings) && signal.warnings[0]
+          ? String(signal.warnings[0])
+          : "Malformed execution signal files were detected.";
+      pushUnique(warnings, warningMessage);
+      continue;
+    }
+
+    if (mode === "integrity" && PLANNING_SIGNAL_SURFACES.has(surface)) {
+      if (signal.status === "BLOCK") {
+        pushUnique(warnings, `Planning signal ${surface} is BLOCK (advisory in integrity mode).`);
+      } else if (signal.status === "WARN") {
+        pushUnique(notes, `Planning signal ${surface} is WARN.`);
+      }
+    }
+
+    if (mode === "completion" && VERIFICATION_SIGNAL_SURFACES.has(surface)) {
+      if (signal.status === "BLOCK") {
+        failures.push(`Verification signal ${surface} is BLOCK.`);
+      } else if (signal.status === "WARN") {
+        pushUnique(warnings, `Verification signal ${surface} is WARN.`);
+      }
+    }
+
+    if (surface === "diff-spec" && signal.status !== "PASS") {
+      pushUnique(warnings, `Planning diff signal ${surface} reports ${signal.status}.`);
+    }
+  }
+  notes.push(
+    "Execution-chain signal integration uses advisory planning semantics in integrity mode and blocking verification semantics in completion mode."
+  );
+
   const status = failures.length > 0 ? "FAIL" : warnings.length > 0 ? "WARN" : "PASS";
 
   return {
@@ -771,6 +888,10 @@ function auditProject(projectPathInput, options = {}) {
   };
 }
 
+function auditProjectAsync(projectPathInput, options = {}) {
+  return runModuleExportInWorker(__filename, "auditProject", [projectPathInput, options]);
+}
+
 function formatAuditReport(result) {
   const lines = [
     "Da Vinci audit",
@@ -809,5 +930,6 @@ function formatAuditReport(result) {
 
 module.exports = {
   auditProject,
+  auditProjectAsync,
   formatAuditReport
 };