@xenonbyte/da-vinci-workflow 0.2.3 → 0.2.5

package/lib/task-execution.js

@@ -0,0 +1,160 @@
+const path = require("path");
+const { resolveChangeDir, unique } = require("./planning-parsers");
+const { writeExecutionSignal } = require("./execution-signals");
+
+const VALID_IMPLEMENTER_STATUSES = new Set([
+  "DONE",
+  "DONE_WITH_CONCERNS",
+  "NEEDS_CONTEXT",
+  "BLOCKED"
+]);
+
+function normalizeStatus(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (!VALID_IMPLEMENTER_STATUSES.has(normalized)) {
+    throw new Error(
+      "`task-execution --status` must be one of DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED."
+    );
+  }
+  return normalized;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return unique(value.map((item) => String(item || "").trim()).filter(Boolean));
+  }
+  return unique(
+    String(value || "")
+      .split(/[,\n;]/)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  );
+}
+
+function normalizeTaskGroupId(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("`task-execution` requires `--task-group <id>`.");
+  }
+  return normalized;
+}
+
+function mapImplementerStatusToSignal(status) {
+  if (status === "DONE") {
+    return "PASS";
+  }
+  if (status === "DONE_WITH_CONCERNS" || status === "NEEDS_CONTEXT") {
+    return "WARN";
+  }
+  return "BLOCK";
+}
+
+function buildSurface(taskGroupId) {
+  const safeId = String(taskGroupId || "")
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "_");
+  return `task-execution.${safeId}`;
+}
+
+function normalizeTaskExecutionEnvelope(input = {}) {
+  const taskGroupId = normalizeTaskGroupId(input.taskGroupId);
+  const status = normalizeStatus(input.status);
+  const summary = String(input.summary || "").trim();
+  if (!summary) {
+    throw new Error("`task-execution` requires `--summary <text>`.");
+  }
+  const changedFiles = normalizeList(input.changedFiles);
+  const testEvidence = normalizeList(input.testEvidence);
+  const concerns = normalizeList(input.concerns);
+  const blockers = normalizeList(input.blockers);
+
+  return {
+    taskGroupId,
+    status,
+    summary,
+    changedFiles,
+    testEvidence,
+    concerns,
+    blockers,
+    recordedAt: new Date().toISOString()
+  };
+}
+
+function writeTaskExecutionEnvelope(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  if (!resolved.changeDir || !resolved.changeId) {
+    const resolveError =
+      Array.isArray(resolved.failures) && resolved.failures.length > 0
+        ? String(resolved.failures[0] || "").trim()
+        : "";
+    throw new Error(resolveError || "Unable to resolve active change for task-execution.");
+  }
+
+  const envelope = normalizeTaskExecutionEnvelope(options);
+  const signalPath = writeExecutionSignal(projectRoot, {
+    changeId: resolved.changeId,
+    surface: buildSurface(envelope.taskGroupId),
+    status: mapImplementerStatusToSignal(envelope.status),
+    advisory: false,
+    strict: true,
+    failures: envelope.status === "BLOCKED" ? envelope.blockers : [],
+    warnings:
+      envelope.status === "DONE_WITH_CONCERNS" || envelope.status === "NEEDS_CONTEXT"
+        ? envelope.concerns
+        : [],
+    notes: [envelope.summary, ...envelope.testEvidence.map((item) => `test: ${item}`)],
+    details: {
+      type: "task_execution",
+      envelope
+    }
+  });
+
+  return {
+    status: mapImplementerStatusToSignal(envelope.status),
+    projectRoot,
+    changeId: resolved.changeId,
+    taskGroupId: envelope.taskGroupId,
+    implementerStatus: envelope.status,
+    summary: envelope.summary,
+    changedFiles: envelope.changedFiles,
+    testEvidence: envelope.testEvidence,
+    concerns: envelope.concerns,
+    blockers: envelope.blockers,
+    signalPath
+  };
+}
+
+function formatTaskExecutionReport(result) {
+  const lines = [
+    "Task execution envelope",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId}`,
+    `Task group: ${result.taskGroupId}`,
+    `Implementer status: ${result.implementerStatus}`,
+    `Signal status: ${result.status}`,
+    `Summary: ${result.summary}`,
+    `Signal path: ${result.signalPath}`
+  ];
+  if (result.changedFiles.length > 0) {
+    lines.push(`Changed files: ${result.changedFiles.join(", ")}`);
+  }
+  if (result.testEvidence.length > 0) {
+    lines.push(`Test evidence: ${result.testEvidence.join(", ")}`);
+  }
+  if (result.concerns.length > 0) {
+    lines.push(`Concerns: ${result.concerns.join(", ")}`);
+  }
+  if (result.blockers.length > 0) {
+    lines.push(`Blockers: ${result.blockers.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  VALID_IMPLEMENTER_STATUSES,
+  normalizeTaskExecutionEnvelope,
+  writeTaskExecutionEnvelope,
+  formatTaskExecutionReport
+};

package/lib/task-review.js

@@ -0,0 +1,197 @@
+const fs = require("fs");
+const path = require("path");
+const { resolveChangeDir, unique } = require("./planning-parsers");
+const { readExecutionSignals, writeExecutionSignal } = require("./execution-signals");
+const { writeFileAtomic, readTextIfExists } = require("./utils");
+
+const VALID_REVIEW_STAGES = new Set(["spec", "quality"]);
+const VALID_REVIEW_STATUSES = new Set(["PASS", "WARN", "BLOCK"]);
+
+function normalizeReviewStage(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!VALID_REVIEW_STAGES.has(normalized)) {
+    throw new Error("`task-review --stage` must be `spec` or `quality`.");
+  }
+  return normalized;
+}
+
+function normalizeReviewStatus(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (!VALID_REVIEW_STATUSES.has(normalized)) {
+    throw new Error("`task-review --status` must be PASS, WARN, or BLOCK.");
+  }
+  return normalized;
+}
+
+function normalizeTaskGroupId(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("`task-review` requires `--task-group <id>`.");
+  }
+  return normalized;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return unique(value.map((item) => String(item || "").trim()).filter(Boolean));
+  }
+  return unique(
+    String(value || "")
+      .split(/[,\n;]/)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  );
+}
+
+function buildSafeTaskGroupId(taskGroupId) {
+  return String(taskGroupId || "")
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+
+function buildTaskReviewSurface(taskGroupId, stage) {
+  return `task-review.${buildSafeTaskGroupId(taskGroupId)}.${stage}`;
+}
+
+function mapReviewStatusToSignalStatus(status) {
+  return status;
+}
+
+function normalizeTaskReviewEnvelope(input = {}) {
+  const taskGroupId = normalizeTaskGroupId(input.taskGroupId);
+  const stage = normalizeReviewStage(input.stage);
+  const status = normalizeReviewStatus(input.status);
+  const summary = String(input.summary || "").trim();
+  if (!summary) {
+    throw new Error("`task-review` requires `--summary <text>`.");
+  }
+  const issues = normalizeList(input.issues);
+  const reviewer = String(input.reviewer || "").trim() || "unspecified";
+
+  return {
+    taskGroupId,
+    stage,
+    status,
+    summary,
+    issues,
+    reviewer,
+    recordedAt: new Date().toISOString()
+  };
+}
+
+function findLatestTaskReviewSignal(signals, taskGroupId, stage) {
+  const surface = buildTaskReviewSurface(taskGroupId, stage);
+  return (signals || [])
+    .filter((signal) => String(signal.surface || "") === surface)
+    .sort((left, right) => String(right.timestamp || "").localeCompare(String(left.timestamp || "")))[0] || null;
+}
+
+function appendTaskReviewEvidence(verificationText, envelope) {
+  const existing = String(verificationText || "").trim();
+  const section = [
+    `### Task Review ${envelope.taskGroupId} (${envelope.stage})`,
+    `- Status: ${envelope.status}`,
+    `- Reviewer: ${envelope.reviewer}`,
+    `- Summary: ${envelope.summary}`,
+    `- Issues: ${envelope.issues.length > 0 ? envelope.issues.join("; ") : "none"}`,
+    `- Recorded at: ${envelope.recordedAt}`
+  ].join("\n");
+
+  if (!existing) {
+    return `# Verification\n\n## Task Review Evidence\n\n${section}\n`;
+  }
+  if (!/^\s*##\s+Task Review Evidence\s*$/im.test(existing)) {
+    return `${existing}\n\n## Task Review Evidence\n\n${section}\n`;
+  }
+  return `${existing}\n\n${section}\n`;
+}
+
+function writeTaskReviewEnvelope(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  if (!resolved.changeDir || !resolved.changeId) {
+    const resolveError =
+      Array.isArray(resolved.failures) && resolved.failures.length > 0
+        ? String(resolved.failures[0] || "").trim()
+        : "";
+    throw new Error(resolveError || "Unable to resolve active change for task-review.");
+  }
+
+  const envelope = normalizeTaskReviewEnvelope(options);
+  const existingSignals = readExecutionSignals(projectRoot, { changeId: resolved.changeId });
+
+  if (envelope.stage === "quality") {
+    const specSignal = findLatestTaskReviewSignal(existingSignals, envelope.taskGroupId, "spec");
+    if (!specSignal || String(specSignal.status || "").toUpperCase() !== "PASS") {
+      throw new Error(
+        `Quality review for task group ${envelope.taskGroupId} requires a prior spec review PASS.`
+      );
+    }
+  }
+
+  const signalPath = writeExecutionSignal(projectRoot, {
+    changeId: resolved.changeId,
+    surface: buildTaskReviewSurface(envelope.taskGroupId, envelope.stage),
+    status: mapReviewStatusToSignalStatus(envelope.status),
+    advisory: false,
+    strict: true,
+    failures: envelope.status === "BLOCK" ? envelope.issues : [],
+    warnings: envelope.status === "WARN" ? envelope.issues : [],
+    notes: [envelope.summary, `reviewer: ${envelope.reviewer}`],
+    details: {
+      type: "task_review",
+      envelope
+    }
+  });
+
+  let verificationPath = null;
+  if (options.writeVerification === true) {
+    verificationPath = path.join(resolved.changeDir, "verification.md");
+    fs.mkdirSync(path.dirname(verificationPath), { recursive: true });
+    const nextVerification = appendTaskReviewEvidence(readTextIfExists(verificationPath), envelope);
+    writeFileAtomic(verificationPath, nextVerification);
+  }
+
+  return {
+    status: envelope.status,
+    projectRoot,
+    changeId: resolved.changeId,
+    taskGroupId: envelope.taskGroupId,
+    stage: envelope.stage,
+    summary: envelope.summary,
+    issues: envelope.issues,
+    reviewer: envelope.reviewer,
+    signalPath,
+    verificationPath
+  };
+}
+
+function formatTaskReviewReport(result) {
+  const lines = [
+    "Task review envelope",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId}`,
+    `Task group: ${result.taskGroupId}`,
+    `Stage: ${result.stage}`,
+    `Status: ${result.status}`,
+    `Reviewer: ${result.reviewer}`,
+    `Summary: ${result.summary}`,
+    `Signal path: ${result.signalPath}`
+  ];
+  if (result.issues.length > 0) {
+    lines.push(`Issues: ${result.issues.join("; ")}`);
+  }
+  if (result.verificationPath) {
+    lines.push(`Verification write-back: ${result.verificationPath}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  VALID_REVIEW_STAGES,
+  VALID_REVIEW_STATUSES,
+  normalizeTaskReviewEnvelope,
+  writeTaskReviewEnvelope,
+  formatTaskReviewReport
+};

package/lib/utils.js

@@ -28,6 +28,23 @@ function readTextIfExists(targetPath, options = {}) {
   return fs.readFileSync(targetPath, encoding);
 }
 
+function normalizeRelativePath(relativePath) {
+  return String(relativePath || "")
+    .split(path.sep)
+    .filter(Boolean)
+    .join("/");
+}
+
+function pathWithinRoot(projectRoot, candidatePath) {
+  const root = path.resolve(projectRoot);
+  const candidate = path.resolve(candidatePath);
+  if (candidate === root) {
+    return true;
+  }
+  const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+  return candidate.startsWith(prefix);
+}
+
 function uniqueValues(values) {
   return Array.from(new Set((values || []).filter(Boolean)));
 }
@@ -120,6 +137,8 @@ module.exports = {
   escapeRegExp,
   pathExists,
   readTextIfExists,
+  normalizeRelativePath,
+  pathWithinRoot,
   uniqueValues,
   parseJsonText,
   readJsonFile,