@namewta/speculo 1.0.13 → 1.0.14

package/template/workflows/specdev/common/tools/validate-specdev.mjs

@@ -66,6 +66,43 @@ const VALID_TICKET_STATUS = new Set([
   "deviated",
   "cancelled",
 ]);
+const VALID_TICKET_KIND = new Set([
+  "bug",
+  "feature",
+  "refactor",
+  "investigation",
+  "operations",
+  "documentation",
+  "review",
+]);
+const VALID_TRIAGE_MODE = new Set(["intake", "reconcile", "publish"]);
+const VALID_PUBLISH_ACTION = new Set([
+  "not-requested",
+  "pending",
+  "published",
+  "publish-failed",
+  "waived",
+]);
+const VALID_PUBLISH_ROW_STATE = new Set([
+  "planned",
+  "created",
+  "commented",
+  "closed",
+  "skipped:cancelled",
+  "skipped:excluded",
+  "failed",
+]);
+const FORBIDDEN_PUBLISH_LABELS = new Set([
+  "needs-triage",
+  "needs-info",
+  "ready-for-agent",
+  "ready-for-human",
+  "wontfix",
+  "duplicate",
+  "invalid",
+  "stale",
+]);
+const COUNTED_PUBLISH_STATES = new Set(["closed", "created", "commented"]);
 const VALID_DEPTH = new Set(["lite", "standard", "deep"]);
 const VALID_RISK = new Set(["low", "medium", "high", "critical"]);
 const VALID_PLAN_MODES = new Set([
@@ -175,6 +212,7 @@ const STATE_ARTIFACT_BASENAMES = new Set([
   "status.json",
   ".status.json",
   "triage.md",
+  "publish.md",
   "diagnosis.md",
   "source.md",
   "architecture-review.md",
@@ -973,7 +1011,7 @@ function capabilityChecks(root) {
       "triage",
       [
         join(root, "T-triage", "T-triage.md"),
-        ["source.md", "intake", "reconcile", "唯一权威", "远程写入为零"],
+        ["source.md", "intake", "reconcile", "publish", "publish.md", "specdev:published", "唯一权威", "远程写入为零"],
       ],
     ],
     [
@@ -1061,7 +1099,7 @@ function capabilityChecks(root) {
       "archive",
       [
         join(root, "A-archive-and-consolidate", "A-archive-and-consolidate.md"),
-        ["archive-single", "dry-run", "external_action", "consolidate-from-code", "archive-and-consolidate"],
+        ["archive-single", "dry-run", "external_action", "publish_action", "consolidate-from-code", "archive-and-consolidate"],
       ],
     ],
     [
@@ -1327,7 +1365,7 @@ function validateTriage(path, expectedChange, errors) {
     errors.push("triage.md: artifact/schema_version must be triage/1");
   }
   if (meta.change !== expectedChange) errors.push("triage.md: change must equal directory name");
-  if (!new Set(["intake", "reconcile"]).has(meta.mode)) errors.push(`triage.md: invalid mode ${meta.mode}`);
+  if (!VALID_TRIAGE_MODE.has(meta.mode)) errors.push(`triage.md: invalid mode ${meta.mode}`);
   if (!VALID_RISK.has(meta.risk)) errors.push(`triage.md: invalid risk ${meta.risk}`);
   if (typeof meta.route !== "string" || !meta.route.startsWith("specdev/")) {
     errors.push("triage.md: route must be a specdev work id");
@@ -1338,15 +1376,130 @@ function validateTriage(path, expectedChange, errors) {
   if (!new Set(["not-applicable", "pending-close", "closed", "close-failed", "waived"]).has(meta.external_action)) {
     errors.push(`triage.md: invalid external_action ${meta.external_action}`);
   }
+  const publishAction = meta.publish_action == null || meta.publish_action === ""
+    ? "not-requested"
+    : meta.publish_action;
+  if (!VALID_PUBLISH_ACTION.has(publishAction)) {
+    errors.push(`triage.md: invalid publish_action ${meta.publish_action}`);
+  }
+  meta.publish_action = publishAction;
   if (!String(meta.source ?? "").includes("/source.md</Path>")) {
     errors.push("triage.md: source must reference the local source.md artifact");
   }
   for (const heading of ["## 当前判定", "## 未知项", "## 路由", "## 外部动作"]) {
     if (!body.includes(heading)) errors.push(`triage.md: missing '${heading}'`);
   }
+  if (publishAction !== "not-requested" && !body.includes("## 发布投影")) {
+    errors.push("triage.md: missing '## 发布投影'");
+  }
   return { path, meta, body };
 }
 
+function parsePublishLedger(body) {
+  const rows = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (!/^\|/.test(line) || /^\|\s*-+/.test(line) || /^\|\s*ticket\s*\|/i.test(line)) continue;
+    const cells = line.split("|").map((cell) => cell.trim());
+    const inner = cells.slice(1, cells.length - 1);
+    if (inner.length < 8) continue;
+    rows.push({
+      ticket: inner[0],
+      kind: inner[1],
+      labels: inner[2],
+      number: inner[3],
+      url: inner[4],
+      marker: inner[5],
+      sha256: inner[6],
+      state: inner[7],
+    });
+  }
+  return rows;
+}
+
+function validatePublish(path, expectedChange, triage, errors) {
+  if (!isFile(path)) {
+    errors.push("missing publish.md ledger");
+    return null;
+  }
+  const { meta, body } = parseFrontmatter(path);
+  const required = [
+    "schema_version",
+    "artifact",
+    "change",
+    "mode",
+    "repo",
+    "publish_action",
+    "include_cancelled",
+    "origin",
+    "updated_at",
+  ];
+  const missing = required.filter((key) => !(key in meta));
+  if (missing.length) errors.push(`publish.md: missing keys ${JSON.stringify(missing)}`);
+  if (meta.schema_version !== 1 || meta.artifact !== "publish") {
+    errors.push("publish.md: artifact/schema_version must be publish/1");
+  }
+  if (meta.change !== expectedChange) errors.push("publish.md: change must equal directory name");
+  if (meta.mode !== "publish") errors.push(`publish.md: invalid mode ${meta.mode}`);
+  if (!new Set(["pending", "published", "publish-failed", "waived"]).has(meta.publish_action)) {
+    errors.push(`publish.md: invalid publish_action ${meta.publish_action}`);
+  }
+  if (!new Set(["local", "intake"]).has(meta.origin)) {
+    errors.push(`publish.md: invalid origin ${meta.origin}`);
+  }
+  if (typeof meta.repo !== "string" || !/.+\/.+/.test(meta.repo)) {
+    errors.push("publish.md: repo must be owner/repo");
+  }
+  for (const heading of ["## 发布计划", "## 账本", "## 计数", "## 重试"]) {
+    if (!body.includes(heading)) errors.push(`publish.md: missing '${heading}'`);
+  }
+  const rows = parsePublishLedger(body);
+  if (!rows.length) errors.push("publish.md: ledger table has no ticket rows");
+  const mixed = triage && triage.meta.classification === "mixed";
+  for (const row of rows) {
+    if (!/^T-\d{2,}$/.test(row.ticket)) {
+      errors.push(`publish.md: invalid ticket id ${row.ticket}`);
+    }
+    if (!VALID_PUBLISH_ROW_STATE.has(row.state)) {
+      errors.push(`publish.md: ${row.ticket}: invalid state ${row.state}`);
+    }
+    const labels = row.labels.split(",").map((item) => item.trim()).filter(Boolean);
+    for (const label of labels) {
+      if (FORBIDDEN_PUBLISH_LABELS.has(label)) {
+        errors.push(`publish.md: ${row.ticket}: forbidden label ${label}`);
+      }
+    }
+    const skipped = row.state.startsWith("skipped:");
+    if (!skipped && !VALID_TICKET_KIND.has(row.kind)) {
+      errors.push(`publish.md: ${row.ticket}: invalid kind ${row.kind}`);
+    }
+    if (mixed && !skipped && !VALID_TICKET_KIND.has(row.kind)) {
+      errors.push(`publish.md: mixed change requires kind on ${row.ticket}`);
+    }
+    if (COUNTED_PUBLISH_STATES.has(row.state) || row.state === "closed") {
+      if (!/^\d+$/.test(row.number)) {
+        errors.push(`publish.md: ${row.ticket}: ${row.state} row requires issue number`);
+      }
+      if (!String(row.url).startsWith("https://github.com/")) {
+        errors.push(`publish.md: ${row.ticket}: ${row.state} row requires GitHub url`);
+      }
+      const expectedMarker = `specdev:${expectedChange}:${row.ticket}:published`;
+      if (row.marker !== expectedMarker) {
+        errors.push(`publish.md: ${row.ticket}: marker must be ${expectedMarker}`);
+      }
+    }
+    if (row.state === "closed" || row.state === "created" || row.state === "commented") {
+      if (!labels.includes("specdev:published")) {
+        errors.push(`publish.md: ${row.ticket}: missing specdev:published`);
+      }
+      const originLabel = meta.origin === "intake" ? "origin:intake" : "origin:local";
+      if (!labels.includes(originLabel)) {
+        errors.push(`publish.md: ${row.ticket}: missing ${originLabel}`);
+      }
+    }
+  }
+  return { path, meta, body, rows };
+}
+
 function validateDiagnosis(path, expectedChange, errors) {
   if (!isFile(path)) {
     errors.push("missing diagnosis artifact");
@@ -2048,6 +2201,9 @@ function validateTicket(path, errors) {
   const ticketId = String(meta.id);
   if (!/^T-\d{2,}$/.test(ticketId)) errors.push(`${basename(path)}: invalid Ticket id ${ticketId}`);
   if (!VALID_TICKET_STATUS.has(meta.status)) errors.push(`${basename(path)}: invalid status ${meta.status}`);
+  if (meta.kind != null && meta.kind !== "" && !VALID_TICKET_KIND.has(meta.kind)) {
+    errors.push(`${basename(path)}: invalid kind ${meta.kind}`);
+  }
   if (!VALID_DEPTH.has(meta.planning_depth)) {
     errors.push(`${basename(path)}: invalid planning_depth ${meta.planning_depth}`);
   }
@@ -3010,6 +3166,13 @@ function validateChange(change, stage = null, repoRoot = null) {
   const triage = isFile(triagePath) || sourceRequired
     ? validateTriage(triagePath, basename(change), errors)
     : null;
+  const publishPath = join(change, "publish.md");
+  const publishRequired = Boolean(
+    triage && new Set(["pending", "published", "publish-failed", "waived"]).has(triage.meta.publish_action),
+  );
+  if (isFile(publishPath) || publishRequired) {
+    validatePublish(publishPath, basename(change), triage, errors);
+  }
   const diagnosisPath = join(change, "diagnosis.md");
   if (isFile(diagnosisPath) || stage === "diagnosis") {
     validateDiagnosis(diagnosisPath, basename(change), errors);
@@ -3298,6 +3461,13 @@ function validateChange(change, stage = null, repoRoot = null) {
   ) {
     errors.push(`complete stage cannot archive external_action=${triage.meta.external_action}`);
   }
+  if (
+    stage === "complete" &&
+    triage &&
+    new Set(["pending", "publish-failed"]).has(triage.meta.publish_action)
+  ) {
+    errors.push(`complete stage cannot archive publish_action=${triage.meta.publish_action}`);
+  }
 
   for (const path of walk(change).filter((item) => isFile(item) && extname(item) === ".md")) {
     const text = readText(path);