@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/lib/verify.js

@@ -0,0 +1,652 @@
+const fs = require("fs");
+const path = require("path");
+const { STATUS } = require("./workflow-contract");
+const {
+  normalizeText,
+  unique,
+  resolveImplementationLanding,
+  resolveChangeDir,
+  parseBindingsArtifact,
+  parseTasksArtifact,
+  parseVerificationArtifact,
+  parseRuntimeSpecs,
+  readChangeArtifacts,
+  readArtifactTexts
+} = require("./planning-parsers");
+
+const CODE_FILE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".html", ".css", ".scss"]);
+const NON_IMPLEMENTATION_DIR_NAMES = new Set([
+  ".git",
+  ".da-vinci",
+  "node_modules",
+  "test",
+  "tests",
+  "__tests__",
+  "__mocks__",
+  "fixtures",
+  "__fixtures__",
+  "scripts",
+  "coverage",
+  "dist",
+  "build",
+  ".next",
+  ".nuxt",
+  ".storybook",
+  "storybook-static",
+  "cypress",
+  "playwright-report",
+  "e2e"
+]);
+const NON_IMPLEMENTATION_FILE_PATTERNS = [
+  /\.test\.[a-z0-9]+$/i,
+  /\.spec\.[a-z0-9]+$/i,
+  /\.stories\.[a-z0-9]+$/i,
+  /\.story\.[a-z0-9]+$/i
+];
+const MAX_SCANNED_FILES = 2000;
+const MAX_SCANNED_BYTES_PER_FILE = 512 * 1024;
+const MAX_SCANNED_DIRECTORIES = 10000;
+const MAX_SCAN_DEPTH = 32;
+
+function buildEnvelope(name, projectRoot, strict) {
+  return {
+    status: STATUS.PASS,
+    failures: [],
+    warnings: [],
+    notes: [],
+    projectRoot,
+    changeId: null,
+    strict,
+    surface: name
+  };
+}
+
+function finalize(result, options = {}) {
+  result.failures = unique(result.failures);
+  result.warnings = unique(result.warnings);
+  result.notes = unique(result.notes);
+
+  if (result.failures.length > 0) {
+    result.status = STATUS.BLOCK;
+    return result;
+  }
+  if (result.warnings.length > 0) {
+    result.status = result.strict || options.strictWarnings ? STATUS.BLOCK : STATUS.WARN;
+    return result;
+  }
+  result.status = STATUS.PASS;
+  return result;
+}
+
+function isNonImplementationDirName(name) {
+  return NON_IMPLEMENTATION_DIR_NAMES.has(String(name || "").toLowerCase());
+}
+
+function isNonImplementationFileName(name) {
+  const normalized = String(name || "").trim();
+  if (!normalized) {
+    return false;
+  }
+  return NON_IMPLEMENTATION_FILE_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+function collectCodeFiles(projectRoot) {
+  const files = [];
+  const scan = {
+    truncatedByFileLimit: false,
+    truncatedByDirectoryLimit: false,
+    depthLimitHits: 0,
+    skippedSymlinks: 0,
+    readErrors: 0,
+    scannedDirectories: 0
+  };
+  const queue = [{ dir: projectRoot, depth: 0 }];
+  const visited = new Set();
+  while (queue.length > 0 && files.length < MAX_SCANNED_FILES) {
+    const current = queue.pop();
+    if (current.depth > MAX_SCAN_DEPTH) {
+      scan.depthLimitHits += 1;
+      continue;
+    }
+
+    let resolvedCurrent;
+    try {
+      resolvedCurrent = fs.realpathSync(current.dir);
+    } catch (_error) {
+      scan.readErrors += 1;
+      continue;
+    }
+    if (visited.has(resolvedCurrent)) {
+      continue;
+    }
+    visited.add(resolvedCurrent);
+    scan.scannedDirectories += 1;
+    if (scan.scannedDirectories > MAX_SCANNED_DIRECTORIES) {
+      scan.truncatedByDirectoryLimit = true;
+      break;
+    }
+
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current.dir, { withFileTypes: true });
+    } catch (_error) {
+      scan.readErrors += 1;
+      continue;
+    }
+    for (const entry of entries) {
+      if (files.length >= MAX_SCANNED_FILES) {
+        scan.truncatedByFileLimit = true;
+        break;
+      }
+      if (entry.isDirectory() && isNonImplementationDirName(entry.name)) {
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        scan.skippedSymlinks += 1;
+        continue;
+      }
+      const absolutePath = path.join(current.dir, entry.name);
+      if (entry.isDirectory()) {
+        if (current.depth >= MAX_SCAN_DEPTH) {
+          scan.depthLimitHits += 1;
+          continue;
+        }
+        queue.push({
+          dir: absolutePath,
+          depth: current.depth + 1
+        });
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (!CODE_FILE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        continue;
+      }
+      if (isNonImplementationFileName(entry.name)) {
+        continue;
+      }
+      files.push(absolutePath);
+    }
+  }
+  if (files.length >= MAX_SCANNED_FILES) {
+    scan.truncatedByFileLimit = true;
+  }
+  return {
+    files: files.sort(),
+    scan
+  };
+}
+
+function safeReadFile(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size > MAX_SCANNED_BYTES_PER_FILE) {
+      return "";
+    }
+    return fs.readFileSync(filePath, "utf8");
+  } catch (_error) {
+    return "";
+  }
+}
+
+function readCodeFileForScan(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size > MAX_SCANNED_BYTES_PER_FILE) {
+      return {
+        text: "",
+        bytesRead: 0,
+        skippedLarge: true,
+        readError: false
+      };
+    }
+    return {
+      text: fs.readFileSync(filePath, "utf8"),
+      bytesRead: stat.size,
+      skippedLarge: false,
+      readError: false
+    };
+  } catch (_error) {
+    return {
+      text: "",
+      bytesRead: 0,
+      skippedLarge: false,
+      readError: true
+    };
+  }
+}
+
+function allCovered(checks) {
+  for (const check of checks) {
+    if (!check.covered) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function createSharedSetup(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const strict = options && options.strict === true;
+  const requestedChangeId = options && options.changeId ? String(options.changeId).trim() : "";
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+
+  let artifactPaths = null;
+  let artifacts = null;
+  if (resolved.changeDir) {
+    artifactPaths = readChangeArtifacts(projectRoot, resolved.changeId);
+    artifacts = readArtifactTexts(artifactPaths);
+  }
+
+  return {
+    projectRoot,
+    strict,
+    requestedChangeId,
+    resolved,
+    artifactPaths,
+    artifacts
+  };
+}
+
+function commonSetup(surface, projectPathInput, options) {
+  const sharedSetup =
+    options && options.sharedSetup
+      ? options.sharedSetup
+      : createSharedSetup(projectPathInput, options || {});
+  const strict =
+    (options && options.strict === true) || (sharedSetup && sharedSetup.strict === true);
+  const result = buildEnvelope(surface, sharedSetup.projectRoot, strict);
+
+  result.failures.push(...sharedSetup.resolved.failures);
+  result.notes.push(...sharedSetup.resolved.notes);
+  if (!sharedSetup.resolved.changeDir) {
+    return {
+      result: finalize(result),
+      resolved: sharedSetup.resolved,
+      artifacts: sharedSetup.artifacts,
+      artifactPaths: sharedSetup.artifactPaths,
+      sharedSetup
+    };
+  }
+  result.changeId = sharedSetup.resolved.changeId;
+
+  return {
+    result,
+    resolved: sharedSetup.resolved,
+    artifacts: sharedSetup.artifacts,
+    artifactPaths: sharedSetup.artifactPaths,
+    sharedSetup
+  };
+}
+
+function verifyBindings(projectPathInput, options = {}) {
+  const setup = commonSetup("verify-bindings", projectPathInput, options);
+  const { result, artifacts } = setup;
+  if (!artifacts) {
+    return result;
+  }
+
+  if (!artifacts.bindings) {
+    result.failures.push("Missing `pencil-bindings.md` for verify-bindings.");
+    return finalize(result);
+  }
+
+  const parsed = parseBindingsArtifact(artifacts.bindings);
+  if (parsed.mappings.length === 0) {
+    result.failures.push("No implementation mappings found in `pencil-bindings.md`.");
+    return finalize(result);
+  }
+
+  for (const mapping of parsed.mappings) {
+    const landing = resolveImplementationLanding(result.projectRoot, mapping.implementation);
+    if (!landing) {
+      result.failures.push(
+        `Missing implementation landing for binding "${mapping.implementation}" -> "${mapping.designPage}".`
+      );
+    }
+  }
+
+  if (parsed.malformed.length > 0) {
+    for (const malformed of parsed.malformed) {
+      result.warnings.push(`Malformed binding mapping entry: "${malformed}".`);
+    }
+  }
+
+  return finalize(result);
+}
+
+function verifyImplementation(projectPathInput, options = {}) {
+  const setup = commonSetup("verify-implementation", projectPathInput, options);
+  const { result, resolved, artifacts } = setup;
+  if (!artifacts) {
+    return result;
+  }
+
+  const codeScan = collectCodeFiles(result.projectRoot);
+  const codeFiles = codeScan.files;
+  if (codeFiles.length === 0) {
+    result.failures.push("No implementation files were found for verify-implementation.");
+    return finalize(result);
+  }
+
+  const specRecords = parseRuntimeSpecs(resolved.changeDir, result.projectRoot);
+  const tasksArtifact = parseTasksArtifact(artifacts.tasks || "");
+
+  if (specRecords.length === 0) {
+    result.failures.push("Missing runtime specs for verify-implementation.");
+    return finalize(result);
+  }
+
+  const stateChecks = [];
+  for (const record of specRecords) {
+    const states = record.parsed.sections.states.items || [];
+    for (const stateItem of states) {
+      const state = normalizeText(String(stateItem || "").split(":")[0]);
+      if (!state) {
+        continue;
+      }
+      const stateTokens = state.split(" ").filter((token) => token.length >= 3);
+      if (stateTokens.length === 0) {
+        continue;
+      }
+      stateChecks.push({
+        recordPath: record.path,
+        stateItem,
+        tokens: stateTokens,
+        covered: false
+      });
+    }
+  }
+
+  const taskGroupChecks = [];
+  for (const group of tasksArtifact.taskGroups) {
+    const titleTokens = normalizeText(group.title)
+      .split(" ")
+      .filter((token) => token.length >= 4);
+    if (titleTokens.length === 0) {
+      continue;
+    }
+
+    taskGroupChecks.push({
+      group,
+      tokens: titleTokens,
+      covered: false
+    });
+  }
+
+  let scannedBytes = 0;
+  let skippedLargeFiles = 0;
+  let readErrors = 0;
+  for (const codeFile of codeFiles) {
+    const read = readCodeFileForScan(codeFile);
+    scannedBytes += read.bytesRead;
+    if (read.skippedLarge) {
+      skippedLargeFiles += 1;
+      continue;
+    }
+    if (read.readError) {
+      readErrors += 1;
+      continue;
+    }
+
+    const lower = String(read.text || "").toLowerCase();
+    if (!lower) {
+      continue;
+    }
+
+    for (const check of stateChecks) {
+      if (check.covered) {
+        continue;
+      }
+      check.covered = check.tokens.some((token) => lower.includes(token));
+    }
+    for (const check of taskGroupChecks) {
+      if (check.covered) {
+        continue;
+      }
+      check.covered = check.tokens.some((token) => lower.includes(token));
+    }
+
+    if (allCovered(stateChecks) && allCovered(taskGroupChecks)) {
+      break;
+    }
+  }
+
+  for (const check of stateChecks) {
+    if (!check.covered) {
+      result.warnings.push(
+        `State coverage may be missing in implementation: "${check.stateItem}" (${check.recordPath}).`
+      );
+    }
+  }
+  for (const check of taskGroupChecks) {
+    if (!check.covered) {
+      result.warnings.push(
+        `Task-group intent may be missing in implementation: "${check.group.id}. ${check.group.title}".`
+      );
+    }
+  }
+
+  if (codeScan.scan.truncatedByFileLimit) {
+    result.warnings.push(
+      `verify-implementation hit file scan limit (${MAX_SCANNED_FILES}); deep coverage may be incomplete.`
+    );
+  }
+  if (codeScan.scan.truncatedByDirectoryLimit) {
+    result.warnings.push(
+      `verify-implementation hit directory scan limit (${MAX_SCANNED_DIRECTORIES}); coverage may be incomplete.`
+    );
+  }
+  if (codeScan.scan.readErrors + readErrors > 0) {
+    result.warnings.push(
+      `verify-implementation skipped unreadable files/directories (${codeScan.scan.readErrors + readErrors}).`
+    );
+  }
+  if (codeScan.scan.depthLimitHits > 0) {
+    result.notes.push(
+      `verify-implementation enforced max scan depth (${MAX_SCAN_DEPTH}); skipped deeper paths: ${codeScan.scan.depthLimitHits}.`
+    );
+  }
+  if (codeScan.scan.skippedSymlinks > 0) {
+    result.notes.push(
+      `verify-implementation skipped symlink entries during scan: ${codeScan.scan.skippedSymlinks}.`
+    );
+  }
+  if (skippedLargeFiles > 0) {
+    result.notes.push(
+      `verify-implementation skipped files larger than ${MAX_SCANNED_BYTES_PER_FILE} bytes: ${skippedLargeFiles}.`
+    );
+  }
+
+  result.summary = {
+    codeFiles: codeFiles.length,
+    specFiles: specRecords.length,
+    taskGroups: tasksArtifact.taskGroups.length,
+    scannedBytes
+  };
+  return finalize(result);
+}
+
+function verifyStructure(projectPathInput, options = {}) {
+  const setup = commonSetup("verify-structure", projectPathInput, options);
+  const { result, artifacts } = setup;
+  if (!artifacts) {
+    return result;
+  }
+
+  if (!artifacts.bindings) {
+    result.failures.push("Missing `pencil-bindings.md` for verify-structure.");
+    return finalize(result);
+  }
+
+  const bindings = parseBindingsArtifact(artifacts.bindings);
+  const confidence = [];
+
+  if (bindings.mappings.length === 0) {
+    result.failures.push("No binding mappings available for structural comparison.");
+    return finalize(result);
+  }
+
+  for (const mapping of bindings.mappings) {
+    const landing = resolveImplementationLanding(result.projectRoot, mapping.implementation);
+    if (!landing) {
+      result.failures.push(`Structural check missing implementation file for "${mapping.implementation}".`);
+      continue;
+    }
+
+    const ext = path.extname(landing).toLowerCase();
+    const source = safeReadFile(landing);
+    const normalizedSource = normalizeText(source);
+    const pageTokens = normalizeText(mapping.designPage)
+      .split(" ")
+      .filter((token) => token.length >= 3);
+
+    if (ext === ".html" || ext === ".tsx" || ext === ".jsx" || ext === ".js") {
+      const hasMarkupIndicators = /<section|<main|<header|<footer|<div/.test(source);
+      if (hasMarkupIndicators) {
+        confidence.push({ mapping: mapping.implementation, mode: "markup", confidence: "high" });
+      } else {
+        confidence.push({ mapping: mapping.implementation, mode: "heuristic", confidence: "medium" });
+        result.warnings.push(
+          `verify-structure used heuristic mode for "${mapping.implementation}" because markup structure was limited.`
+        );
+      }
+    } else {
+      confidence.push({ mapping: mapping.implementation, mode: "heuristic", confidence: "low" });
+      result.warnings.push(
+        `verify-structure used heuristic mode for "${mapping.implementation}" due to unsupported file type ${ext || "(none)"}.`
+      );
+    }
+
+    if (pageTokens.length > 0) {
+      const covered = pageTokens.some((token) => normalizedSource.includes(token));
+      if (!covered) {
+        result.warnings.push(
+          `Structural drift suspected: design page "${mapping.designPage}" tokens not found in "${mapping.implementation}".`
+        );
+      }
+    }
+  }
+
+  result.structure = {
+    confidence
+  };
+  return finalize(result);
+}
+
+function verifyCoverage(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const strict = options.strict === true;
+  const changeId = options.changeId ? String(options.changeId).trim() : "";
+  const sharedSetup = createSharedSetup(projectRoot, { changeId, strict });
+  const sharedOptions = { changeId, strict, sharedSetup };
+  const bindingsResult = verifyBindings(projectRoot, sharedOptions);
+  const implementationResult = verifyImplementation(projectRoot, sharedOptions);
+  const structureResult = verifyStructure(projectRoot, sharedOptions);
+
+  const result = buildEnvelope("verify-coverage", projectRoot, strict);
+  result.changeId = bindingsResult.changeId || implementationResult.changeId || structureResult.changeId || null;
+  result.notes.push("verify-coverage aggregates requirement, design, binding, code, and test coverage signals.");
+
+  if (bindingsResult.status === STATUS.BLOCK) {
+    result.failures.push("verify-bindings reported BLOCK.");
+  } else if (bindingsResult.status === STATUS.WARN) {
+    result.warnings.push("verify-bindings reported WARN.");
+  }
+  if (implementationResult.status === STATUS.BLOCK) {
+    result.failures.push("verify-implementation reported BLOCK.");
+  } else if (implementationResult.status === STATUS.WARN) {
+    result.warnings.push("verify-implementation reported WARN.");
+  }
+  if (structureResult.status === STATUS.BLOCK) {
+    result.failures.push("verify-structure reported BLOCK.");
+  } else if (structureResult.status === STATUS.WARN) {
+    result.warnings.push("verify-structure reported WARN.");
+  }
+
+  if (sharedSetup.artifacts && sharedSetup.artifacts.verification) {
+    const verificationArtifact = parseVerificationArtifact(sharedSetup.artifacts.verification);
+    if (verificationArtifact.requirementCoverage.length === 0) {
+      result.warnings.push("`verification.md` is missing requirement-coverage evidence.");
+    }
+    if (verificationArtifact.designCoverage.length === 0) {
+      result.warnings.push("`verification.md` is missing design-coverage evidence.");
+    }
+    const hasTestEvidence = verificationArtifact.outcome.some((item) => /test|coverage|verify/i.test(item));
+    if (!hasTestEvidence) {
+      result.warnings.push("`verification.md` outcome lacks explicit test evidence.");
+    }
+  } else {
+    result.warnings.push("Missing `verification.md`; coverage evidence is incomplete.");
+  }
+
+  result.components = {
+    bindings: {
+      status: bindingsResult.status,
+      failures: bindingsResult.failures,
+      warnings: bindingsResult.warnings
+    },
+    implementation: {
+      status: implementationResult.status,
+      failures: implementationResult.failures,
+      warnings: implementationResult.warnings
+    },
+    structure: {
+      status: structureResult.status,
+      failures: structureResult.failures,
+      warnings: structureResult.warnings,
+      confidence: structureResult.structure ? structureResult.structure.confidence : []
+    }
+  };
+
+  return finalize(result);
+}
+
+function formatVerifyReport(result, title = "Da Vinci verify") {
+  const lines = [
+    title,
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Strict mode: ${result.strict ? "yes" : "no"}`,
+    `Status: ${result.status}`
+  ];
+  if (result.summary) {
+    for (const [key, value] of Object.entries(result.summary)) {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+  if (result.failures.length > 0) {
+    lines.push("", "Failures:");
+    for (const failure of result.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+  if (result.notes.length > 0) {
+    lines.push("", "Notes:");
+    for (const note of result.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+  if (result.structure && Array.isArray(result.structure.confidence) && result.structure.confidence.length > 0) {
+    lines.push("", "Structure confidence:");
+    for (const item of result.structure.confidence) {
+      lines.push(`- ${item.mapping}: ${item.mode} (${item.confidence})`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  verifyBindings,
+  verifyImplementation,
+  verifyStructure,
+  verifyCoverage,
+  formatVerifyReport
+};