@picoai/tickets 0.1.0

package/src/lib/validation.js

@@ -0,0 +1,482 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  ASSIGNMENT_MODE_VALUES,
+  PRIORITY_VALUES,
+  STATUS_VALUES,
+} from "./constants.js";
+import {
+  isUuidv7,
+  listTicketDirs,
+  loadTicket,
+  parseIso,
+  readJsonl,
+  repoRoot,
+} from "./util.js";
+
+function parseVersion(value) {
+  if (typeof value === "number" && Number.isInteger(value)) {
+    return value;
+  }
+  if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+    return Number.parseInt(value.trim(), 10);
+  }
+  return null;
+}
+
+export function collectTicketPaths(target) {
+  if (target) {
+    const resolved = path.resolve(repoRoot(), target);
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+      return [path.join(resolved, "ticket.md")];
+    }
+    return [resolved];
+  }
+
+  return listTicketDirs()
+    .map((ticketDir) => path.join(ticketDir, "ticket.md"))
+    .filter((ticketPath) => fs.existsSync(ticketPath));
+}
+
+export function validateTicket(ticketPath, allFields = false) {
+  const issues = [];
+  let frontMatter;
+  let body;
+
+  try {
+    [frontMatter, body] = loadTicket(ticketPath);
+  } catch (error) {
+    issues.push({
+      severity: "error",
+      code: "TICKET_FRONT_MATTER_INVALID",
+      message: String(error.message ?? error),
+      ticket_path: ticketPath,
+    });
+    return [issues, {}, ""];
+  }
+
+  const requiredFields = ["id", "title", "status", "created_at"];
+  for (const field of requiredFields) {
+    if (!(field in frontMatter)) {
+      issues.push({
+        severity: "error",
+        code: `MISSING_${field.toUpperCase()}`,
+        message: `Missing ${field}`,
+        ticket_path: ticketPath,
+      });
+    }
+  }
+
+  if (!("version" in frontMatter)) {
+    issues.push({
+      severity: "warning",
+      code: "VERSION_MISSING",
+      message: "Missing version (assume 1 for legacy tickets)",
+      ticket_path: ticketPath,
+    });
+  } else {
+    const version = parseVersion(frontMatter.version);
+    if (version === null || version <= 0) {
+      issues.push({
+        severity: "error",
+        code: "VERSION_INVALID",
+        message: "version must be a positive integer",
+        ticket_path: ticketPath,
+      });
+    }
+
+    if (!("version_url" in frontMatter)) {
+      issues.push({
+        severity: "error",
+        code: "VERSION_URL_MISSING",
+        message: "version_url required when version is present",
+        ticket_path: ticketPath,
+      });
+    } else if (typeof frontMatter.version_url !== "string" || !frontMatter.version_url.trim()) {
+      issues.push({
+        severity: "error",
+        code: "VERSION_URL_INVALID",
+        message: "version_url must be a non-empty string",
+        ticket_path: ticketPath,
+      });
+    }
+  }
+
+  if ("version_url" in frontMatter && !("version" in frontMatter)) {
+    issues.push({
+      severity: "warning",
+      code: "VERSION_URL_WITHOUT_VERSION",
+      message: "version_url present without version",
+      ticket_path: ticketPath,
+    });
+  }
+
+  if ("id" in frontMatter && (!isUuidv7(frontMatter.id) || typeof frontMatter.id !== "string")) {
+    issues.push({
+      severity: "error",
+      code: "ID_NOT_UUIDV7",
+      message: "id must be UUIDv7",
+      ticket_path: ticketPath,
+    });
+  }
+
+  if ("created_at" in frontMatter) {
+    if (typeof frontMatter.created_at !== "string" || !parseIso(frontMatter.created_at)) {
+      issues.push({
+        severity: "error",
+        code: "CREATED_AT_INVALID",
+        message: "created_at must be ISO8601 UTC",
+        ticket_path: ticketPath,
+      });
+    }
+  }
+
+  if ("status" in frontMatter && !STATUS_VALUES.includes(frontMatter.status)) {
+    issues.push({
+      severity: "error",
+      code: "STATUS_INVALID",
+      message: "status invalid",
+      ticket_path: ticketPath,
+    });
+  }
+
+  if ("assignment" in frontMatter) {
+    if (!frontMatter.assignment || typeof frontMatter.assignment !== "object" || Array.isArray(frontMatter.assignment)) {
+      issues.push({
+        severity: "error",
+        code: "ASSIGNMENT_INVALID",
+        message: "assignment must be mapping",
+        ticket_path: ticketPath,
+      });
+    } else {
+      const mode = frontMatter.assignment.mode;
+      if (mode && !ASSIGNMENT_MODE_VALUES.includes(mode)) {
+        issues.push({
+          severity: "error",
+          code: "ASSIGNMENT_MODE_INVALID",
+          message: "assignment.mode invalid",
+          ticket_path: ticketPath,
+        });
+      }
+    }
+  }
+
+  if ("custom" in frontMatter && (typeof frontMatter.custom !== "object" || !frontMatter.custom || Array.isArray(frontMatter.custom))) {
+    issues.push({
+      severity: "error",
+      code: "CUSTOM_INVALID",
+      message: "custom must be mapping",
+      ticket_path: ticketPath,
+    });
+  }
+
+  const relationshipKeys = ["dependencies", "blocks", "related"];
+  for (const relationshipKey of relationshipKeys) {
+    if (!(relationshipKey in frontMatter)) {
+      continue;
+    }
+
+    const value = frontMatter[relationshipKey];
+    if (!Array.isArray(value)) {
+      issues.push({
+        severity: "error",
+        code: "RELATIONSHIP_TYPE_INVALID",
+        message: `${relationshipKey} must be list`,
+        ticket_path: ticketPath,
+      });
+      continue;
+    }
+
+    for (const relationship of value) {
+      if (typeof relationship !== "string" || !isUuidv7(relationship)) {
+        issues.push({
+          severity: "error",
+          code: "RELATIONSHIP_ID_INVALID",
+          message: `${relationshipKey} entries must be UUIDv7`,
+          ticket_path: ticketPath,
+        });
+      }
+    }
+  }
+
+  for (const forbidden of ["parent", "subtickets", "supersedes", "duplicate_of"]) {
+    if (forbidden in frontMatter) {
+      issues.push({
+        severity: "error",
+        code: "RELATIONSHIP_KEY_FORBIDDEN",
+        message: `${forbidden} not allowed in ticket.md`,
+        ticket_path: ticketPath,
+      });
+    }
+  }
+
+  if ("agent_limits" in frontMatter) {
+    if (!frontMatter.agent_limits || typeof frontMatter.agent_limits !== "object" || Array.isArray(frontMatter.agent_limits)) {
+      issues.push({
+        severity: "error",
+        code: "AGENT_LIMITS_INVALID",
+        message: "agent_limits must be mapping",
+        ticket_path: ticketPath,
+      });
+    } else {
+      for (const key of [
+        "iteration_timebox_minutes",
+        "max_iterations",
+        "max_tool_calls",
+        "checkpoint_every_minutes",
+      ]) {
+        if (!(key in frontMatter.agent_limits)) {
+          continue;
+        }
+        const value = frontMatter.agent_limits[key];
+        if (!Number.isInteger(value) || value <= 0) {
+          issues.push({
+            severity: "error",
+            code: "AGENT_LIMIT_VALUE_INVALID",
+            message: `${key} must be positive int`,
+            ticket_path: ticketPath,
+          });
+        }
+      }
+    }
+  }
+
+  if (allFields) {
+    if ("priority" in frontMatter && !PRIORITY_VALUES.includes(frontMatter.priority)) {
+      issues.push({
+        severity: "error",
+        code: "PRIORITY_INVALID",
+        message: "priority must be low|medium|high|critical",
+        ticket_path: ticketPath,
+        optional: true,
+      });
+    }
+
+    if ("labels" in frontMatter) {
+      if (!Array.isArray(frontMatter.labels)) {
+        issues.push({
+          severity: "error",
+          code: "LABELS_NOT_LIST",
+          message: "labels must be list of strings",
+          ticket_path: ticketPath,
+          optional: true,
+        });
+      } else {
+        for (const label of frontMatter.labels) {
+          if (typeof label !== "string") {
+            issues.push({
+              severity: "error",
+              code: "LABEL_INVALID_ENTRY",
+              message: "labels entries must be strings",
+              ticket_path: ticketPath,
+              optional: true,
+            });
+          }
+        }
+      }
+    }
+
+    if (
+      frontMatter.assignment &&
+      typeof frontMatter.assignment === "object" &&
+      !Array.isArray(frontMatter.assignment)
+    ) {
+      const owner = frontMatter.assignment.owner;
+      if (owner !== undefined && owner !== null && typeof owner !== "string") {
+        issues.push({
+          severity: "error",
+          code: "ASSIGNMENT_OWNER_INVALID",
+          message: "assignment.owner must be string",
+          ticket_path: ticketPath,
+          optional: true,
+        });
+      }
+    }
+
+    if ("verification" in frontMatter) {
+      const verification = frontMatter.verification;
+      if (!verification || typeof verification !== "object" || Array.isArray(verification)) {
+        issues.push({
+          severity: "error",
+          code: "VERIFICATION_INVALID",
+          message: "verification must be mapping",
+          ticket_path: ticketPath,
+          optional: true,
+        });
+      } else {
+        const commands = verification.commands;
+        if (commands !== undefined && !Array.isArray(commands)) {
+          issues.push({
+            severity: "error",
+            code: "VERIFICATION_COMMANDS_INVALID",
+            message: "verification.commands must be list of strings",
+            ticket_path: ticketPath,
+            optional: true,
+          });
+        } else if (Array.isArray(commands)) {
+          for (const command of commands) {
+            if (typeof command !== "string") {
+              issues.push({
+                severity: "error",
+                code: "VERIFICATION_COMMAND_INVALID",
+                message: "verification.commands entries must be strings",
+                ticket_path: ticketPath,
+                optional: true,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  for (const heading of ["# Ticket", "## Description", "## Acceptance Criteria", "## Verification"]) {
+    if (!body.includes(heading)) {
+      issues.push({
+        severity: "error",
+        code: "MISSING_SECTION",
+        message: `Missing section ${heading}`,
+        ticket_path: ticketPath,
+      });
+    }
+  }
+
+  return [issues, frontMatter, body];
+}
+
+export function validateRunLog(logPath, machineStrictDefault) {
+  const issues = [];
+  const filename = path.basename(logPath);
+  let expectedPrefix = null;
+  if (filename.includes("-")) {
+    expectedPrefix = filename.replace(/\.jsonl$/, "").split("-", 1)[0];
+  }
+
+  const entries = readJsonl(logPath);
+  let runStartedValue = null;
+
+  entries.forEach((entry, idx) => {
+    const loc = `${logPath}:${idx + 1}`;
+    const machineEntry =
+      machineStrictDefault || entry.written_by === "tickets" || entry.machine === true;
+
+    for (const required of ["ts", "run_started", "actor_type", "actor_id", "summary"]) {
+      if (!(required in entry)) {
+        issues.push({
+          severity: machineEntry ? "error" : "warning",
+          code: "LOG_FIELD_MISSING",
+          message: `${required} missing`,
+          log: loc,
+        });
+      }
+    }
+
+    if (!("version" in entry)) {
+      issues.push({
+        severity: machineEntry ? "error" : "warning",
+        code: "LOG_VERSION_MISSING",
+        message: "version missing (assume 1 for legacy logs)",
+        log: loc,
+      });
+    } else {
+      const version = parseVersion(entry.version);
+      if (version === null || version <= 0) {
+        issues.push({
+          severity: machineEntry ? "error" : "warning",
+          code: "LOG_VERSION_INVALID",
+          message: "version must be a positive integer",
+          log: loc,
+        });
+      }
+
+      if (!("version_url" in entry)) {
+        issues.push({
+          severity: machineEntry ? "error" : "warning",
+          code: "LOG_VERSION_URL_MISSING",
+          message: "version_url required when version is present",
+          log: loc,
+        });
+      } else if (typeof entry.version_url !== "string" || !entry.version_url.trim()) {
+        issues.push({
+          severity: machineEntry ? "error" : "warning",
+          code: "LOG_VERSION_URL_INVALID",
+          message: "version_url must be a non-empty string",
+          log: loc,
+        });
+      }
+    }
+
+    if ("ts" in entry && !parseIso(entry.ts)) {
+      issues.push({
+        severity: machineEntry ? "error" : "warning",
+        code: "TS_INVALID",
+        message: "ts not ISO8601",
+        log: loc,
+      });
+    }
+
+    if ("run_started" in entry) {
+      if (!parseIso(entry.run_started)) {
+        issues.push({
+          severity: machineEntry ? "error" : "warning",
+          code: "RUN_STARTED_INVALID",
+          message: "run_started not ISO8601",
+          log: loc,
+        });
+      } else {
+        if (!runStartedValue) {
+          runStartedValue = entry.run_started;
+        } else if (runStartedValue !== entry.run_started) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "RUN_STARTED_INCONSISTENT",
+            message: "run_started differs within file",
+            log: loc,
+          });
+        }
+
+        if (
+          expectedPrefix &&
+          !entry.run_started.replaceAll(":", "").startsWith(expectedPrefix.replaceAll(":", ""))
+        ) {
+          issues.push({
+            severity: "warning",
+            code: "RUN_STARTED_FILENAME_MISMATCH",
+            message: "run_started mismatch filename prefix",
+            log: loc,
+          });
+        }
+      }
+    }
+
+    if ("actor_type" in entry && !["human", "agent"].includes(entry.actor_type)) {
+      issues.push({
+        severity: machineEntry ? "error" : "warning",
+        code: "ACTOR_TYPE_INVALID",
+        message: "actor_type must be human|agent",
+        log: loc,
+      });
+    }
+
+    if (machineEntry && entry.written_by !== "tickets" && entry.machine !== true) {
+      issues.push({
+        severity: "error",
+        code: "MACHINE_MARKER_MISSING",
+        message: "machine marker required",
+        log: loc,
+      });
+    }
+
+    if ("custom" in entry && (typeof entry.custom !== "object" || !entry.custom || Array.isArray(entry.custom))) {
+      issues.push({
+        severity: machineEntry ? "error" : "warning",
+        code: "LOG_CUSTOM_INVALID",
+        message: "custom must be mapping",
+        log: loc,
+      });
+    }
+  });
+
+  return issues;
+}