@xenonbyte/da-vinci-workflow 0.1.18 → 0.1.20

package/lib/audit.js

@@ -45,6 +45,10 @@ function relativeTo(projectRoot, targetPath) {
   return path.relative(projectRoot, targetPath) || ".";
 }
 
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function collectRegisteredPenPaths(projectRoot, designRegistryPath) {
   const registryText = readTextIfExists(designRegistryPath);
   const matches = registryText.match(/\.da-vinci\/designs\/[^\s`]+\.pen/g) || [];
@@ -117,6 +121,448 @@ function addMissingArtifacts(projectRoot, artifactPaths, targetList) {
   }
 }
 
+function pushUnique(targetList, message) {
+  if (!targetList.includes(message)) {
+    targetList.push(message);
+  }
+}
+
+function getMarkdownSection(text, heading) {
+  if (!text) {
+    return "";
+  }
+
+  const escapedHeading = escapeRegExp(heading);
+  const headingPattern = new RegExp(`^##\\s+${escapedHeading}\\s*$`, "i");
+  const anyHeadingPattern = /^##\s+/;
+  const lines = String(text).replace(/\r\n?/g, "\n").split("\n");
+  const sectionLines = [];
+  let capturing = false;
+
+  for (const line of lines) {
+    if (capturing && anyHeadingPattern.test(line)) {
+      break;
+    }
+
+    if (!capturing && headingPattern.test(line)) {
+      capturing = true;
+      continue;
+    }
+
+    if (capturing) {
+      sectionLines.push(line);
+    }
+  }
+
+  return sectionLines.join("\n").trim();
+}
+
+function normalizeCheckpointLabel(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/`/g, "")
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function parseCheckpointStatusMap(markdownText) {
+  const section = getMarkdownSection(markdownText, "Checkpoint Status");
+  if (!section) {
+    return {};
+  }
+
+  const statuses = {};
+  const matches = section.matchAll(/(?:^|\n)\s*-\s*`?([^`:\n]+?)`?\s*:\s*(PASS|WARN|BLOCK)\b/gi);
+  for (const match of matches) {
+    const label = normalizeCheckpointLabel(match[1]);
+    if (!label) {
+      continue;
+    }
+    statuses[label] = String(match[2]).toUpperCase();
+  }
+
+  return statuses;
+}
+
+function hasContextDeltaExpectationSignals(markdownText) {
+  const text = String(markdownText || "");
+  return (
+    /##\s+(Checkpoint Status|MCP Runtime Gate)\b/i.test(text) ||
+    /(?:^|\n)\s*(?:[-*]\s*)?`?Context Delta Required`?\s*:\s*(?:true|yes|on|1)\b/i.test(text)
+  );
+}
+
+function parseSupersedesTokens(value) {
+  return String(value || "")
+    .split(/[,\n;]/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+}
+
+function normalizeTimeToken(value) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    return "";
+  }
+
+  const parseCandidates = [];
+  const rawWithT = raw.includes(" ") ? raw.replace(/\s+/, "T") : raw;
+  const hasExplicitTimezone = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(rawWithT);
+
+  if (!hasExplicitTimezone && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(rawWithT)) {
+    parseCandidates.push(`${rawWithT}Z`);
+  }
+
+  parseCandidates.push(rawWithT);
+  parseCandidates.push(raw);
+
+  for (const candidate of parseCandidates) {
+    const timestamp = Date.parse(candidate);
+    if (!Number.isFinite(timestamp)) {
+      continue;
+    }
+    return new Date(timestamp).toISOString();
+  }
+
+  return "";
+}
+
+function getTimeReferenceKeys(value) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    return [];
+  }
+
+  const keys = new Set([raw]);
+
+  if (raw.includes(" ")) {
+    keys.add(raw.replace(/\s+/, "T"));
+  }
+
+  if (raw.endsWith(".000Z")) {
+    keys.add(raw.replace(".000Z", "Z"));
+  }
+
+  const normalized = normalizeTimeToken(raw);
+  if (normalized) {
+    keys.add(normalized);
+    if (normalized.endsWith(".000Z")) {
+      keys.add(normalized.replace(".000Z", "Z"));
+    }
+  }
+
+  return [...keys];
+}
+
+function buildContextDeltaReferenceIndex(entries) {
+  const referenceIndex = new Map();
+
+  function addReference(key, entryIndex) {
+    const normalizedKey = String(key || "").trim();
+    if (!normalizedKey) {
+      return;
+    }
+
+    const existing = referenceIndex.get(normalizedKey) || [];
+    existing.push(entryIndex);
+    referenceIndex.set(normalizedKey, existing);
+  }
+
+  entries.forEach((entry, entryIndex) => {
+    if (entry.time) {
+      for (const timeKey of getTimeReferenceKeys(entry.time)) {
+        addReference(timeKey, entryIndex);
+        addReference(`time:${timeKey}`, entryIndex);
+      }
+    }
+
+    if (entry.checkpointType && entry.time) {
+      const normalizedCheckpointType = normalizeCheckpointLabel(entry.checkpointType);
+      for (const timeKey of getTimeReferenceKeys(entry.time)) {
+        addReference(`${entry.checkpointType}@${timeKey}`, entryIndex);
+        addReference(`${normalizedCheckpointType}@${timeKey}`, entryIndex);
+      }
+    }
+  });
+
+  return referenceIndex;
+}
+
+function getSupersedesCandidateKeys(token) {
+  const trimmed = String(token || "").trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  const keys = new Set([trimmed]);
+  const prefixedTimeMatch = trimmed.match(/^time\s*:\s*(.+)$/i);
+  if (prefixedTimeMatch) {
+    for (const timeKey of getTimeReferenceKeys(prefixedTimeMatch[1])) {
+      keys.add(timeKey);
+      keys.add(`time:${timeKey}`);
+    }
+  } else {
+    keys.add(`time:${trimmed}`);
+    for (const timeKey of getTimeReferenceKeys(trimmed)) {
+      keys.add(timeKey);
+      keys.add(`time:${timeKey}`);
+    }
+  }
+
+  const atIndex = trimmed.indexOf("@");
+  if (atIndex > 0 && atIndex < trimmed.length - 1) {
+    const checkpointType = trimmed.slice(0, atIndex).trim();
+    const time = trimmed.slice(atIndex + 1).trim();
+    if (checkpointType && time) {
+      const normalizedCheckpointType = normalizeCheckpointLabel(checkpointType);
+      for (const timeKey of getTimeReferenceKeys(time)) {
+        keys.add(`${checkpointType}@${timeKey}`);
+        keys.add(`${normalizedCheckpointType}@${timeKey}`);
+      }
+    }
+  }
+
+  return [...keys];
+}
+
+function resolveSupersedesReferenceIndices(token, referenceIndex) {
+  const indices = new Set();
+  for (const key of getSupersedesCandidateKeys(token)) {
+    const matches = referenceIndex.get(key);
+    if (!matches) {
+      continue;
+    }
+    for (const entryIndex of matches) {
+      indices.add(entryIndex);
+    }
+  }
+  return [...indices].sort((a, b) => a - b);
+}
+
+function inspectContextDelta(markdownText) {
+  const section = getMarkdownSection(markdownText, "Context Delta");
+  if (!section) {
+    return {
+      found: false,
+      hasConcreteEntry: false,
+      entries: [],
+      incompleteEntryCount: 0
+    };
+  }
+
+  const lines = String(section).replace(/\r\n?/g, "\n").split("\n");
+  const entries = [];
+  let current = null;
+
+  function ensureCurrent() {
+    if (!current) {
+      current = {};
+    }
+  }
+
+  function flushCurrent() {
+    if (!current) {
+      return;
+    }
+
+    const hasAnyValue = [
+      current.time,
+      current.checkpointType,
+      current.goal,
+      current.decision,
+      current.constraints,
+      current.impact,
+      current.status,
+      current.nextAction,
+      current.supersedes
+    ].some((value) => Boolean(value));
+
+    if (hasAnyValue) {
+      entries.push(current);
+    }
+    current = null;
+  }
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (!line) {
+      continue;
+    }
+
+    const timeMatch = line.match(/^-+\s*`?time`?\s*:\s*(.+)$/i);
+    if (timeMatch) {
+      flushCurrent();
+      current = {
+        time: timeMatch[1].trim()
+      };
+      continue;
+    }
+
+    const checkpointTypeMatch = line.match(/^-+\s*`?checkpoint(?:[_ -]?type)?`?\s*:\s*(.+)$/i);
+    if (checkpointTypeMatch) {
+      ensureCurrent();
+      current.checkpointType = checkpointTypeMatch[1].trim();
+      continue;
+    }
+
+    const goalMatch = line.match(/^-+\s*`?goal`?\s*:\s*(.+)$/i);
+    if (goalMatch) {
+      ensureCurrent();
+      current.goal = goalMatch[1].trim();
+      continue;
+    }
+
+    const decisionMatch = line.match(/^-+\s*`?decision`?\s*:\s*(.+)$/i);
+    if (decisionMatch) {
+      ensureCurrent();
+      current.decision = decisionMatch[1].trim();
+      continue;
+    }
+
+    const constraintsMatch = line.match(/^-+\s*`?constraints`?\s*:\s*(.+)$/i);
+    if (constraintsMatch) {
+      ensureCurrent();
+      current.constraints = constraintsMatch[1].trim();
+      continue;
+    }
+
+    const impactMatch = line.match(/^-+\s*`?impact`?\s*:\s*(.+)$/i);
+    if (impactMatch) {
+      ensureCurrent();
+      current.impact = impactMatch[1].trim();
+      continue;
+    }
+
+    const statusMatch = line.match(/^-+\s*`?status`?\s*:\s*(PASS|WARN|BLOCK)\b/i);
+    if (statusMatch) {
+      ensureCurrent();
+      current.status = String(statusMatch[1]).toUpperCase();
+      continue;
+    }
+
+    const nextActionMatch = line.match(/^-+\s*`?next(?:[_ -]?action)?`?\s*:\s*(.+)$/i);
+    if (nextActionMatch) {
+      ensureCurrent();
+      current.nextAction = nextActionMatch[1].trim();
+      continue;
+    }
+
+    const supersedesMatch = line.match(/^-+\s*`?supersedes`?\s*:\s*(.+)$/i);
+    if (supersedesMatch) {
+      ensureCurrent();
+      current.supersedes = supersedesMatch[1].trim();
+      continue;
+    }
+  }
+
+  flushCurrent();
+
+  const hasConcreteEntry = entries.some(
+    (entry) => entry.time || entry.checkpointType || entry.status || entry.decision || entry.nextAction
+  );
+  const incompleteEntryCount = entries.filter(
+    (entry) => !entry.time || !entry.checkpointType || !entry.status
+  ).length;
+
+  return {
+    found: true,
+    hasConcreteEntry,
+    entries,
+    incompleteEntryCount
+  };
+}
+
+function getVisualAssistFieldValues(daVinciText, fieldName) {
+  const section = getMarkdownSection(daVinciText, "Visual Assist");
+  if (!section) {
+    return [];
+  }
+
+  const fieldPattern = new RegExp(`^\\s*-\\s*${escapeRegExp(fieldName)}\\s*:\\s*(.*)$`, "i");
+  const nestedValuePattern = /^\s{2,}-\s*(.+?)\s*$/;
+  const nextFieldPattern = /^\s*-\s+[^:]+:\s*.*$/;
+  const values = [];
+  let capturing = false;
+
+  for (const rawLine of String(section).replace(/\r\n?/g, "\n").split("\n")) {
+    const fieldMatch = rawLine.match(fieldPattern);
+    if (!capturing && fieldMatch) {
+      capturing = true;
+      const inlineValue = (fieldMatch[1] || "").trim();
+      if (inlineValue) {
+        values.push(inlineValue);
+      }
+      continue;
+    }
+
+    if (capturing && nextFieldPattern.test(rawLine)) {
+      break;
+    }
+
+    if (capturing) {
+      const nestedMatch = rawLine.match(nestedValuePattern);
+      if (nestedMatch) {
+        const value = nestedMatch[1].trim();
+        if (value) {
+          values.push(value);
+        }
+      } else if (rawLine.trim() === "") {
+        continue;
+      } else {
+        break;
+      }
+    }
+  }
+
+  return values;
+}
+
+function hasConfiguredDesignSupervisorReview(daVinciText) {
+  return getVisualAssistFieldValues(daVinciText, "Design-supervisor reviewers").length > 0;
+}
+
+function isDesignSupervisorReviewRequired(daVinciText) {
+  return getVisualAssistFieldValues(daVinciText, "Require Supervisor Review").some((value) =>
+    /^true$/i.test(String(value).trim())
+  );
+}
+
+function inspectDesignSupervisorReview(pencilDesignText) {
+  const section = getMarkdownSection(pencilDesignText, "Design-Supervisor Review");
+  if (!section) {
+    return {
+      found: false,
+      status: null,
+      acceptedWarn: false,
+      hasIssueList: false,
+      hasRevisionOutcome: false
+    };
+  }
+
+  const statusMatch = section.match(/(?:^|\n)\s*-\s*(?:Status|状态)\s*:\s*(PASS|WARN|BLOCK)\b/i);
+  const status = statusMatch ? statusMatch[1].toUpperCase() : null;
+  const issueListMatch = section.match(/(?:^|\n)\s*-\s*(?:Issue list|问题列表)\s*:\s*(.+)$/im);
+  const revisionOutcomeMatch = section.match(
+    /(?:^|\n)\s*-\s*(?:Revision outcome|修订结果)\s*:\s*(.+)$/im
+  );
+  const revisionOutcome = revisionOutcomeMatch ? revisionOutcomeMatch[1].trim() : "";
+  const acceptedWarn =
+    status === "WARN" &&
+    /(accepted|accepted with follow-up|accepted warning|warn accepted|接受|已接受|接受警告)/i.test(
+      revisionOutcome
+    );
+
+  return {
+    found: true,
+    status,
+    acceptedWarn,
+    hasIssueList: Boolean(issueListMatch && issueListMatch[1].trim()),
+    hasRevisionOutcome: Boolean(revisionOutcome)
+  };
+}
+
 function auditProject(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const mode = options.mode || "integrity";
@@ -125,6 +571,9 @@ function auditProject(projectPathInput, options = {}) {
   const changesDir = path.join(daVinciDir, "changes");
   const designRegistryPath = path.join(daVinciDir, "design-registry.md");
   const pencilSessionPath = getSessionStatePath(projectRoot);
+  const daVinciText = readTextIfExists(path.join(projectRoot, "DA-VINCI.md"));
+  const designSupervisorConfigured = hasConfiguredDesignSupervisorReview(daVinciText);
+  const designSupervisorRequired = isDesignSupervisorReviewRequired(daVinciText);
 
   const failures = [];
   const warnings = [];
@@ -186,6 +635,16 @@ function auditProject(projectPathInput, options = {}) {
     addMissingArtifacts(projectRoot, completionRequiredArtifacts.slice(1, 4), warnings);
   }
 
+  if (designSupervisorRequired && !designSupervisorConfigured) {
+    const message =
+      "DA-VINCI.md sets `Require Supervisor Review: true` but no `Design-supervisor reviewers` are configured.";
+    if (mode === "completion") {
+      failures.push(message);
+    } else {
+      warnings.push(message);
+    }
+  }
+
   const daVinciFiles = listFilesRecursive(daVinciDir);
   const misplacedExports = daVinciFiles.filter(
     (filePath) => IMAGE_EXPORT_PATTERN.test(filePath) && !isAllowedExportPath(projectRoot, filePath)
@@ -348,6 +807,201 @@ function auditProject(projectPathInput, options = {}) {
       );
     }
 
+    const pencilDesignPath = path.join(changeDir, "pencil-design.md");
+    if (designSupervisorConfigured && pathExists(pencilDesignPath)) {
+      const review = inspectDesignSupervisorReview(readTextIfExists(pencilDesignPath));
+      const enforceAsFailure =
+        mode === "completion" && scopedChangeDirs.includes(changeDir) && designSupervisorRequired;
+
+      if (!review.found) {
+        const message =
+          `DA-VINCI.md configures Design-supervisor reviewers, but ${relativeTo(projectRoot, pencilDesignPath)} ` +
+          "does not record a `## Design-Supervisor Review` section.";
+        if (enforceAsFailure) {
+          failures.push(message);
+        } else {
+          warnings.push(message);
+        }
+      } else if (!review.status) {
+        const message =
+          `Design-supervisor review is recorded in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+          "but no PASS/WARN/BLOCK status was found.";
+        if (enforceAsFailure) {
+          failures.push(message);
+        } else {
+          warnings.push(message);
+        }
+      } else if (!review.hasIssueList || !review.hasRevisionOutcome) {
+        const missingFields = [
+          !review.hasIssueList ? "Issue list" : null,
+          !review.hasRevisionOutcome ? "Revision outcome" : null
+        ]
+          .filter(Boolean)
+          .join(" and ");
+        const message =
+          `Design-supervisor review in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+          `is missing required field(s): ${missingFields}.`;
+        if (enforceAsFailure) {
+          failures.push(message);
+        } else {
+          warnings.push(message);
+        }
+      } else if (review.status === "BLOCK") {
+        const message =
+          `Design-supervisor review is still BLOCK in ${relativeTo(projectRoot, pencilDesignPath)}.`;
+        if (enforceAsFailure) {
+          failures.push(message);
+        } else {
+          warnings.push(message);
+        }
+      } else if (review.status === "WARN" && !review.acceptedWarn) {
+        const message =
+          `Design-supervisor review is WARN in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+          "but the warning was not explicitly accepted.";
+        if (enforceAsFailure) {
+          failures.push(message);
+        } else {
+          warnings.push(message);
+        }
+      } else {
+        notes.push(
+          `Detected design-supervisor review status ${review.status} in ${relativeTo(projectRoot, pencilDesignPath)}.`
+        );
+      }
+    }
+
+    const tasksPath = path.join(changeDir, "tasks.md");
+    const verificationPath = path.join(changeDir, "verification.md");
+    const contextArtifacts = [pencilDesignPath, tasksPath, verificationPath]
+      .filter((artifactPath) => pathExists(artifactPath))
+      .map((artifactPath) => ({
+        path: artifactPath,
+        text: readTextIfExists(artifactPath)
+      }));
+    const contextCandidates = contextArtifacts.filter((artifact) =>
+      hasContextDeltaExpectationSignals(artifact.text)
+    );
+
+    if (contextCandidates.length > 0) {
+      const contextInspections = contextCandidates.map((artifact) => ({
+        path: artifact.path,
+        inspection: inspectContextDelta(artifact.text),
+        checkpointStatuses: parseCheckpointStatusMap(artifact.text)
+      }));
+
+      const hasAnyConcreteContextDelta = contextInspections.some(
+        (item) => item.inspection.hasConcreteEntry
+      );
+
+      if (!hasAnyConcreteContextDelta) {
+        pushUnique(
+          warnings,
+          `Checkpoint-bearing artifacts in ${changeRel} do not record any concrete \`## Context Delta\` entries.`
+        );
+      } else {
+        notes.push(`Detected context-delta recovery notes in ${changeRel}.`);
+      }
+
+      for (const item of contextInspections) {
+        if (!item.inspection.found || item.inspection.incompleteEntryCount === 0) {
+          continue;
+        }
+
+        pushUnique(
+          warnings,
+          `${relativeTo(projectRoot, item.path)} has ${item.inspection.incompleteEntryCount} context-delta entr` +
+            `${item.inspection.incompleteEntryCount === 1 ? "y" : "ies"} missing one of: time/checkpoint_type/status.`
+        );
+      }
+
+      for (const item of contextInspections) {
+        if (!item.inspection.found || item.inspection.entries.length === 0) {
+          continue;
+        }
+
+        const referenceIndex = buildContextDeltaReferenceIndex(item.inspection.entries);
+
+        item.inspection.entries.forEach((entry, entryIndex) => {
+          if (!entry.supersedes) {
+            return;
+          }
+
+          const entryLabel = entry.time ? `time \`${entry.time}\`` : `entry #${entryIndex + 1}`;
+          const supersedesTokens = parseSupersedesTokens(entry.supersedes);
+
+          if (supersedesTokens.length === 0) {
+            pushUnique(
+              warnings,
+              `${relativeTo(projectRoot, item.path)} has ${entryLabel} with an empty \`supersedes\` reference.`
+            );
+            return;
+          }
+
+          for (const token of supersedesTokens) {
+            const resolvedIndices = resolveSupersedesReferenceIndices(token, referenceIndex);
+
+            if (resolvedIndices.length === 0) {
+              pushUnique(
+                warnings,
+                `${relativeTo(projectRoot, item.path)} has ${entryLabel} superseding \`${token}\`, ` +
+                  "but no referenced context-delta entry exists in the same artifact."
+              );
+              continue;
+            }
+
+            const hasOlderMatch = resolvedIndices.some((resolvedIndex) => resolvedIndex < entryIndex);
+            if (!hasOlderMatch) {
+              pushUnique(
+                warnings,
+                `${relativeTo(projectRoot, item.path)} has ${entryLabel} superseding \`${token}\`, ` +
+                  "but the reference does not point to an earlier context-delta entry."
+              );
+            }
+          }
+        });
+      }
+
+      if (mode === "completion" && scopedChangeDirs.includes(changeDir)) {
+        for (const item of contextInspections) {
+          if (!item.inspection.hasConcreteEntry || Object.keys(item.checkpointStatuses).length === 0) {
+            continue;
+          }
+
+          const entriesByType = new Map();
+          for (const entry of item.inspection.entries) {
+            if (!entry.checkpointType || !entry.status) {
+              continue;
+            }
+            const checkpointType = normalizeCheckpointLabel(entry.checkpointType);
+            const existing = entriesByType.get(checkpointType) || [];
+            existing.push(entry);
+            entriesByType.set(checkpointType, existing);
+          }
+
+          for (const [checkpointType, entries] of entriesByType.entries()) {
+            const currentStatus = item.checkpointStatuses[checkpointType];
+            if (!currentStatus || entries.length === 0) {
+              continue;
+            }
+
+            const latestEntry = entries[entries.length - 1];
+            if (currentStatus === latestEntry.status) {
+              continue;
+            }
+
+            const statusHistory = entries.map((entry) => entry.status).join(" -> ");
+            pushUnique(
+              warnings,
+              `Context-delta/checkpoint status mismatch in ${relativeTo(projectRoot, item.path)} for ` +
+                `\`${latestEntry.checkpointType}\`: latest context-delta status is ${latestEntry.status}, ` +
+                `current checkpoint status is ${currentStatus} (history: ${statusHistory}). ` +
+                "This may indicate stale checkpoint status or stale context-delta notes."
+            );
+          }
+        }
+      }
+    }
+
     const specDirs = listChildDirs(path.join(changeDir, "specs"));
     for (const specDir of specDirs) {
       const specFile = path.join(specDir, "spec.md");