@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.1

package/lib/lint-tasks.js

@@ -0,0 +1,176 @@
+const path = require("path");
+const { STATUS } = require("./workflow-contract");
+const {
+  normalizeText,
+  unique,
+  resolveChangeDir,
+  parseTasksArtifact,
+  parseRuntimeSpecs,
+  readChangeArtifacts,
+  readArtifactTexts
+} = require("./planning-parsers");
+
+function buildEnvelope(projectRoot, strict) {
+  return {
+    status: STATUS.PASS,
+    failures: [],
+    warnings: [],
+    notes: [],
+    projectRoot,
+    changeId: null,
+    strict,
+    summary: {
+      groups: 0,
+      checklistItems: 0
+    }
+  };
+}
+
+function finalize(result) {
+  result.failures = unique(result.failures);
+  result.warnings = unique(result.warnings);
+  result.notes = unique(result.notes);
+  const hasFindings = result.failures.length > 0 || result.warnings.length > 0;
+  if (!hasFindings) {
+    result.status = STATUS.PASS;
+    return result;
+  }
+  result.status = result.strict ? STATUS.BLOCK : STATUS.WARN;
+  return result;
+}
+
+function findMissingTaskGroupSequence(taskGroups) {
+  const numeric = taskGroups
+    .map((group) => Number.parseInt(String(group.id || "").split(".")[0], 10))
+    .filter(Number.isFinite)
+    .sort((a, b) => a - b);
+  if (numeric.length === 0) {
+    return [];
+  }
+  const missing = [];
+  for (let value = numeric[0]; value <= numeric[numeric.length - 1]; value += 1) {
+    if (!numeric.includes(value)) {
+      missing.push(value);
+    }
+  }
+  return missing;
+}
+
+function lintTasks(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const strict = options.strict === true;
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const result = buildEnvelope(projectRoot, strict);
+
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  result.failures.push(...resolved.failures);
+  result.notes.push(...resolved.notes);
+  if (!resolved.changeDir) {
+    result.notes.push("lint-tasks defaults to advisory mode; pass `--strict` to block on findings.");
+    return finalize(result);
+  }
+  result.changeId = resolved.changeId;
+
+  const artifactPaths = readChangeArtifacts(projectRoot, resolved.changeId);
+  const artifacts = readArtifactTexts(artifactPaths);
+  if (!artifacts.tasks) {
+    result.failures.push("Missing `tasks.md` for lint-tasks.");
+    result.notes.push("lint-tasks defaults to advisory mode; pass `--strict` to block on findings.");
+    return finalize(result);
+  }
+
+  const parsedTasks = parseTasksArtifact(artifacts.tasks);
+  const specRecords = parseRuntimeSpecs(resolved.changeDir, projectRoot);
+  const taskText = normalizeText(artifacts.tasks);
+
+  result.summary.groups = parsedTasks.taskGroups.length;
+  result.summary.checklistItems = parsedTasks.checklistItems.length;
+
+  if (parsedTasks.taskGroups.length === 0) {
+    result.failures.push("`tasks.md` is missing top-level numbered task groups (for example `## 1. Setup`).");
+  }
+
+  const missingSequence = findMissingTaskGroupSequence(parsedTasks.taskGroups);
+  if (missingSequence.length > 0) {
+    result.warnings.push(
+      `Task-group numbering is non-contiguous. Missing top-level groups: ${missingSequence.join(", ")}.`
+    );
+  }
+
+  const nonNumericGroups = parsedTasks.taskGroups.filter(
+    (group) => !/^\d+(?:\.\d+)*$/.test(String(group.id || ""))
+  );
+  if (nonNumericGroups.length > 0) {
+    result.warnings.push("Some task-group headings are not numeric and may be skipped by execution metadata.");
+  }
+
+  if (parsedTasks.checklistItems.length === 0) {
+    result.failures.push("`tasks.md` has no checklist items.");
+  }
+
+  const hasVerificationAction =
+    parsedTasks.taskGroups.some((group) => /verify|verification|coverage/i.test(group.title)) ||
+    parsedTasks.checklistItems.some((item) => /verify|verification|coverage/i.test(item.text));
+  if (!hasVerificationAction) {
+    result.warnings.push("Missing explicit verification actions in `tasks.md`.");
+  }
+
+  for (const specRecord of specRecords) {
+    const behaviorItems = specRecord.parsed.sections.behavior.items || [];
+    for (const behaviorItem of behaviorItems) {
+      const normalizedBehavior = normalizeText(behaviorItem)
+        .split(" ")
+        .filter((token) => token.length >= 4)
+        .slice(0, 6);
+      if (normalizedBehavior.length === 0) {
+        continue;
+      }
+      const covered = normalizedBehavior.some((token) => taskText.includes(token));
+      if (!covered) {
+        result.warnings.push(
+          `Planned behavior may be uncovered in tasks: "${behaviorItem}" (${specRecord.path}).`
+        );
+      }
+    }
+  }
+
+  result.notes.push("lint-tasks defaults to advisory mode; pass `--strict` to block on findings.");
+  return finalize(result);
+}
+
+function formatLintTasksReport(result) {
+  const lines = [
+    "Da Vinci lint-tasks",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Strict mode: ${result.strict ? "yes" : "no"}`,
+    `Status: ${result.status}`,
+    `Task groups: ${result.summary.groups}`,
+    `Checklist items: ${result.summary.checklistItems}`
+  ];
+
+  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}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  lintTasks,
+  formatLintTasksReport
+};