@xenonbyte/da-vinci-workflow 0.1.24 → 0.1.26

package/lib/audit.js

@@ -1,8 +1,16 @@
 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 {
   normalizeCheckpointLabel,
   parseCheckpointStatusMap,
@@ -31,17 +39,6 @@ const EXPORT_SCAN_LIMITS = Object.freeze({
   maxEntries: 1200
 });
 
-function pathExists(targetPath) {
-  return fs.existsSync(targetPath);
-}
-
-function readTextIfExists(targetPath) {
-  if (!pathExists(targetPath)) {
-    return "";
-  }
-  return fs.readFileSync(targetPath, "utf8");
-}
-
 function listFilesRecursive(rootDir, limits = {}) {
   return listFilesRecursiveSafe(rootDir, {
     includeDotfiles: true,
@@ -200,6 +197,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 +253,9 @@ function auditProject(projectPathInput, options = {}) {
 
   if (!pathExists(daVinciDir)) {
     failures.push("Missing `.da-vinci/` directory.");
+    notes.push(
+      `Hint: scaffold the required workflow files with \`${buildBootstrapCommand(projectRoot, mode, options.changeId || null)}\`.`
+    );
     return {
       projectRoot,
       mode,
@@ -274,6 +284,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 +381,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 +420,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)}.`
+            );
+          }
         }
       }
     }
@@ -474,12 +530,19 @@ function auditProject(projectPathInput, options = {}) {
       const enforceAsFailure =
         mode === "completion" && scopedChangeDirs.includes(changeDir) && designSupervisorRequired;
 
+      if (review.usedStructuredSectionFallback) {
+        warnings.push(
+          `Latest design-supervisor review entry in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+            `is a legacy/non-structured format; gate evaluation used ${review.selectedSectionHeading}.`
+        );
+      }
+
       let reviewRecordValid = true;
 
       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 {
@@ -636,7 +699,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}.`);
@@ -764,6 +827,10 @@ function auditProject(projectPathInput, options = {}) {
   };
 }
 
+function auditProjectAsync(projectPathInput, options = {}) {
+  return runModuleExportInWorker(__filename, "auditProject", [projectPathInput, options]);
+}
+
 function formatAuditReport(result) {
   const lines = [
     "Da Vinci audit",
@@ -802,5 +869,6 @@ function formatAuditReport(result) {
 
 module.exports = {
   auditProject,
+  auditProjectAsync,
   formatAuditReport
 };