@picoai/tickets 0.2.0 → 0.4.0

package/src/lib/validation.js

@@ -3,7 +3,10 @@ import path from "node:path";
 
 import {
   ASSIGNMENT_MODE_VALUES,
+  CLAIM_ACTION_VALUES,
+  PLANNING_NODE_TYPES,
   PRIORITY_VALUES,
+  RESOLUTION_VALUES,
   STATUS_VALUES,
 } from "./constants.js";
 import {
@@ -211,6 +214,90 @@ export function validateTicket(ticketPath, allFields = false) {
     }
   }
 
+  if ("planning" in frontMatter) {
+    const planning = frontMatter.planning;
+    if (!planning || typeof planning !== "object" || Array.isArray(planning)) {
+      issues.push({
+        severity: "error",
+        code: "PLANNING_INVALID",
+        message: "planning must be mapping",
+        ticket_path: ticketPath,
+      });
+    } else {
+      if ("node_type" in planning && !PLANNING_NODE_TYPES.includes(planning.node_type)) {
+        issues.push({
+          severity: "error",
+          code: "PLANNING_NODE_TYPE_INVALID",
+          message: `planning.node_type must be one of ${PLANNING_NODE_TYPES.join("|")}`,
+          ticket_path: ticketPath,
+        });
+      }
+
+      for (const key of ["group_ids", "precedes"]) {
+        if (!(key in planning)) {
+          continue;
+        }
+        if (!Array.isArray(planning[key])) {
+          issues.push({
+            severity: "error",
+            code: "PLANNING_RELATIONSHIP_INVALID",
+            message: `planning.${key} must be list`,
+            ticket_path: ticketPath,
+          });
+          continue;
+        }
+        for (const relation of planning[key]) {
+          if (typeof relation !== "string" || !isUuidv7(relation)) {
+            issues.push({
+              severity: "error",
+              code: "PLANNING_RELATIONSHIP_ID_INVALID",
+              message: `planning.${key} entries must be UUIDv7`,
+              ticket_path: ticketPath,
+            });
+          }
+        }
+      }
+
+      for (const key of ["lane", "horizon"]) {
+        if (key in planning && planning[key] !== null && typeof planning[key] !== "string") {
+          issues.push({
+            severity: "error",
+            code: "PLANNING_SCALAR_INVALID",
+            message: `planning.${key} must be string or null`,
+            ticket_path: ticketPath,
+          });
+        }
+      }
+
+      if ("rank" in planning && planning.rank !== null && (!Number.isInteger(planning.rank) || planning.rank <= 0)) {
+        issues.push({
+          severity: "error",
+          code: "PLANNING_RANK_INVALID",
+          message: "planning.rank must be a positive integer or null",
+          ticket_path: ticketPath,
+        });
+      }
+    }
+  }
+
+  if ("resolution" in frontMatter) {
+    if (frontMatter.resolution !== null && !RESOLUTION_VALUES.includes(frontMatter.resolution)) {
+      issues.push({
+        severity: "error",
+        code: "RESOLUTION_INVALID",
+        message: `resolution must be one of ${RESOLUTION_VALUES.join("|")} or null`,
+        ticket_path: ticketPath,
+      });
+    } else if (frontMatter.resolution !== null && !["done", "canceled"].includes(frontMatter.status)) {
+      issues.push({
+        severity: "error",
+        code: "RESOLUTION_STATUS_INVALID",
+        message: "resolution requires terminal status done|canceled",
+        ticket_path: ticketPath,
+      });
+    }
+  }
+
   if ("agent_limits" in frontMatter) {
     if (!frontMatter.agent_limits || typeof frontMatter.agent_limits !== "object" || Array.isArray(frontMatter.agent_limits)) {
       issues.push({
@@ -345,6 +432,224 @@ export function validateTicket(ticketPath, allFields = false) {
   return [issues, frontMatter, body];
 }
 
+function loadPlanningRows(ticketPaths) {
+  const rows = [];
+
+  for (const ticketPath of ticketPaths) {
+    try {
+      const [frontMatter] = loadTicket(ticketPath);
+      rows.push({
+        ticket_path: ticketPath,
+        id: frontMatter.id ?? "",
+        status: frontMatter.status ?? "",
+        dependencies: Array.isArray(frontMatter.dependencies) ? frontMatter.dependencies : [],
+        blocks: Array.isArray(frontMatter.blocks) ? frontMatter.blocks : [],
+        related: Array.isArray(frontMatter.related) ? frontMatter.related : [],
+        planning: {
+          node_type: frontMatter.planning?.node_type ?? "work",
+          group_ids: Array.isArray(frontMatter.planning?.group_ids) ? frontMatter.planning.group_ids : [],
+          lane: frontMatter.planning?.lane ?? null,
+          rank: frontMatter.planning?.rank ?? null,
+          horizon: frontMatter.planning?.horizon ?? null,
+          precedes: Array.isArray(frontMatter.planning?.precedes) ? frontMatter.planning.precedes : [],
+        },
+      });
+    } catch {
+      // Ticket parsing errors are already surfaced by validateTicket.
+    }
+  }
+
+  return rows;
+}
+
+function relationshipIssue(ticketPath, code, message) {
+  return {
+    severity: "error",
+    code,
+    message,
+    ticket_path: ticketPath,
+  };
+}
+
+function collectCycleNodes(adjacency) {
+  const state = new Map();
+  const cycleNodes = new Set();
+  const stack = [];
+
+  function visit(nodeId) {
+    const status = state.get(nodeId) ?? 0;
+    if (status === 1) {
+      const startIndex = stack.indexOf(nodeId);
+      for (const entry of stack.slice(startIndex)) {
+        cycleNodes.add(entry);
+      }
+      cycleNodes.add(nodeId);
+      return;
+    }
+    if (status === 2) {
+      return;
+    }
+
+    state.set(nodeId, 1);
+    stack.push(nodeId);
+    for (const nextId of adjacency.get(nodeId) ?? []) {
+      visit(nextId);
+    }
+    stack.pop();
+    state.set(nodeId, 2);
+  }
+
+  for (const nodeId of adjacency.keys()) {
+    visit(nodeId);
+  }
+
+  return cycleNodes;
+}
+
+export function validatePlanningTopology(targetTicketPaths, allTicketPaths = targetTicketPaths) {
+  const issues = [];
+  const allRows = loadPlanningRows(allTicketPaths);
+  const rowsById = new Map(allRows.map((row) => [row.id, row]));
+  const targetPaths = new Set(targetTicketPaths);
+  const targetRows = allRows.filter((row) => targetPaths.has(row.ticket_path));
+
+  for (const row of targetRows) {
+    for (const [key, values] of [
+      ["dependencies", row.dependencies],
+      ["blocks", row.blocks],
+      ["related", row.related],
+    ]) {
+      for (const relationId of values) {
+        if (typeof relationId === "string" && isUuidv7(relationId) && !rowsById.has(relationId)) {
+          issues.push(
+            relationshipIssue(row.ticket_path, "RELATIONSHIP_TARGET_MISSING", `${key} references missing ticket ${relationId}`),
+          );
+        }
+      }
+    }
+
+    for (const relationId of row.planning.group_ids) {
+      if (typeof relationId === "string" && isUuidv7(relationId) && !rowsById.has(relationId)) {
+        issues.push(
+          relationshipIssue(
+            row.ticket_path,
+            "PLANNING_TARGET_MISSING",
+            `planning.group_ids references missing ticket ${relationId}`,
+          ),
+        );
+        continue;
+      }
+      const target = rowsById.get(relationId);
+      if (target && !["group", "checkpoint"].includes(target.planning.node_type)) {
+        issues.push(
+          relationshipIssue(
+            row.ticket_path,
+            "PLANNING_GROUP_TARGET_INVALID",
+            `planning.group_ids must reference a group or checkpoint ticket: ${relationId}`,
+          ),
+        );
+      }
+    }
+
+    for (const relationId of row.planning.precedes) {
+      if (typeof relationId === "string" && isUuidv7(relationId) && !rowsById.has(relationId)) {
+        issues.push(
+          relationshipIssue(
+            row.ticket_path,
+            "PLANNING_TARGET_MISSING",
+            `planning.precedes references missing ticket ${relationId}`,
+          ),
+        );
+        continue;
+      }
+      if (relationId === row.id) {
+        issues.push(
+          relationshipIssue(
+            row.ticket_path,
+            "PLANNING_PRECEDES_SELF_REFERENCE",
+            "planning.precedes must not contain the ticket's own id",
+          ),
+        );
+      }
+    }
+  }
+
+  const precedesAdjacency = new Map();
+  for (const row of allRows) {
+    precedesAdjacency.set(row.id, [...row.planning.precedes]);
+  }
+  const precedesCycles = collectCycleNodes(precedesAdjacency);
+  for (const row of targetRows) {
+    if (precedesCycles.has(row.id)) {
+      issues.push(
+        relationshipIssue(row.ticket_path, "PLANNING_PRECEDES_CYCLE", "planning.precedes contains a cycle"),
+      );
+    }
+  }
+
+  const groupAdjacency = new Map();
+  for (const row of allRows) {
+    if (!["group", "checkpoint"].includes(row.planning.node_type)) {
+      continue;
+    }
+    const edges = row.planning.group_ids.filter((groupId) => {
+      const target = rowsById.get(groupId);
+      return target && ["group", "checkpoint"].includes(target.planning.node_type);
+    });
+    groupAdjacency.set(row.id, edges);
+  }
+  const groupCycles = collectCycleNodes(groupAdjacency);
+  for (const row of targetRows) {
+    if (groupCycles.has(row.id)) {
+      issues.push(
+        relationshipIssue(
+          row.ticket_path,
+          "PLANNING_GROUP_CYCLE",
+          "group/checkpoint membership contains a cycle",
+        ),
+      );
+    }
+  }
+
+  const ranksByScope = new Map();
+  for (const row of allRows) {
+    if (!Number.isInteger(row.planning.rank)) {
+      continue;
+    }
+    const scopeKey = JSON.stringify({
+      node_type: row.planning.node_type,
+      group_ids: [...row.planning.group_ids].sort((a, b) => a.localeCompare(b)),
+      lane: row.planning.lane ?? null,
+      horizon: row.planning.horizon ?? null,
+      rank: row.planning.rank,
+    });
+    if (!ranksByScope.has(scopeKey)) {
+      ranksByScope.set(scopeKey, []);
+    }
+    ranksByScope.get(scopeKey).push(row);
+  }
+
+  for (const rows of ranksByScope.values()) {
+    if (rows.length < 2) {
+      continue;
+    }
+    for (const row of rows) {
+      if (!targetPaths.has(row.ticket_path)) {
+        continue;
+      }
+      issues.push(
+        relationshipIssue(
+          row.ticket_path,
+          "PLANNING_RANK_CONFLICT",
+          "planning.rank conflicts with another ticket in the same peer set",
+        ),
+      );
+    }
+  }
+
+  return issues;
+}
+
 export function validateRunLog(logPath, machineStrictDefault) {
   const issues = [];
   const filename = path.basename(logPath);
@@ -380,11 +685,11 @@ export function validateRunLog(logPath, machineStrictDefault) {
         message: "event_type missing",
         log: loc,
       });
-    } else if (!["status", "work"].includes(entry.event_type)) {
+    } else if (!["status", "work", "claim"].includes(entry.event_type)) {
       issues.push({
         severity: machineEntry ? "error" : "warning",
         code: "LOG_EVENT_TYPE_INVALID",
-        message: "event_type must be status|work",
+        message: "event_type must be status|work|claim",
         log: loc,
       });
     } else {
@@ -524,6 +829,79 @@ export function validateRunLog(logPath, machineStrictDefault) {
       });
     }
 
+    if (eventType === "claim") {
+      const claim = entry.claim;
+      if (!claim || typeof claim !== "object" || Array.isArray(claim)) {
+        issues.push({
+          severity: machineEntry ? "error" : "warning",
+          code: "CLAIM_INVALID",
+          message: "claim event must include claim mapping",
+          log: loc,
+        });
+      } else {
+        if (!CLAIM_ACTION_VALUES.includes(claim.action)) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "CLAIM_ACTION_INVALID",
+            message: `claim.action must be one of ${CLAIM_ACTION_VALUES.join("|")}`,
+            log: loc,
+          });
+        }
+        if (typeof claim.claim_id !== "string" || !isUuidv7(claim.claim_id)) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "CLAIM_ID_INVALID",
+            message: "claim.claim_id must be UUIDv7",
+            log: loc,
+          });
+        }
+        if (typeof claim.holder_id !== "string" || !claim.holder_id.trim()) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "CLAIM_HOLDER_ID_INVALID",
+            message: "claim.holder_id must be non-empty string",
+            log: loc,
+          });
+        }
+        if (!["human", "agent"].includes(claim.holder_type)) {
+          issues.push({
+            severity: machineEntry ? "error" : "warning",
+            code: "CLAIM_HOLDER_TYPE_INVALID",
+            message: "claim.holder_type must be human|agent",
+            log: loc,
+          });
+        }
+        if (claim.action !== "release") {
+          if (!Number.isInteger(claim.ttl_minutes) || claim.ttl_minutes <= 0) {
+            issues.push({
+              severity: machineEntry ? "error" : "warning",
+              code: "CLAIM_TTL_INVALID",
+              message: "claim.ttl_minutes must be a positive integer",
+              log: loc,
+            });
+          }
+          if (!parseIso(claim.expires_at)) {
+            issues.push({
+              severity: machineEntry ? "error" : "warning",
+              code: "CLAIM_EXPIRES_AT_INVALID",
+              message: "claim.expires_at must be ISO8601",
+              log: loc,
+            });
+          }
+        }
+        if ("supersedes_claim_id" in claim && claim.supersedes_claim_id !== null) {
+          if (typeof claim.supersedes_claim_id !== "string" || !isUuidv7(claim.supersedes_claim_id)) {
+            issues.push({
+              severity: machineEntry ? "error" : "warning",
+              code: "CLAIM_SUPERSEDES_INVALID",
+              message: "claim.supersedes_claim_id must be UUIDv7 or null",
+              log: loc,
+            });
+          }
+        }
+      }
+    }
+
     if ("custom" in entry && (typeof entry.custom !== "object" || !entry.custom || Array.isArray(entry.custom))) {
       issues.push({
         severity: machineEntry ? "error" : "warning",