@attalabs/vinaya 0.9.0 → 0.12.0

package/dist/checks/bin/check-doc-coverage.js

@@ -2,9 +2,9 @@
 // @bun
 
 // src/checks/bin/check-doc-coverage.ts
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 import { existsSync, readFileSync } from "fs";
-// ../../packages/aeg-core/src/anchored-region.ts
+// ../../packages/aeg-forge-state/src/strip-code.ts
 function maskCode(body) {
   const fill = (line) => " ".repeat(line.length);
   return maskIndentedCode(maskFencedCode(body, fill), fill).replace(/(`+)[^\n]*?\1/g, (m) => " ".repeat(m.length));
@@ -21,29 +21,38 @@ function stripCode(body, options = {}) {
 var FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})([^\r\n]*)\r?$/;
 var FENCE_CLOSE = /^ {0,3}(`+|~+)[ \t]*\r?$/;
 function maskFencedCode(body, fill) {
+  const { lines } = scanFencedCode(body);
+  return lines.map(({ line, inCode }) => inCode ? fill(line) : line).join(`
+`);
+}
+function scanFencedCode(body) {
   let fenceChar = null;
   let fenceLen = 0;
-  return body.split(`
+  const lines = body.split(`
 `).map((line) => {
     if (fenceChar === null) {
       const open = line.match(FENCE_OPEN);
       if (!open)
-        return line;
+        return { line, inCode: false };
       const marker = open[1];
       if (marker[0] === "`" && open[2].includes("`"))
-        return line;
+        return { line, inCode: false };
       fenceChar = marker[0];
       fenceLen = marker.length;
-      return fill(line);
+      return { line, inCode: true };
     }
     const close = line.match(FENCE_CLOSE);
     if (close && close[1][0] === fenceChar && close[1].length >= fenceLen) {
       fenceChar = null;
       fenceLen = 0;
     }
-    return fill(line);
-  }).join(`
-`);
+    return { line, inCode: true };
+  });
+  return { lines, unterminated: fenceChar !== null };
+}
+function hasUnterminatedFence(body) {
+  return scanFencedCode(body.replace(/\r\n?/g, `
+`)).unterminated;
 }
 var LIST_MARKER = /^ {0,3}(?:[-*+]|\d{1,9}[.)])(?:\s|$)/;
 function indentWidth(line) {
@@ -86,88 +95,7 @@ function maskIndentedCode(body, fill) {
   return out.join(`
 `);
 }
-function anchoredRegion(body, field) {
-  const masked = maskCode(body);
-  const start = new RegExp(`<!--\\s*AEG:${field}:START\\s*-->`).exec(masked);
-  if (!start)
-    return null;
-  const afterStart = start.index + start[0].length;
-  const end = new RegExp(`<!--\\s*AEG:${field}:END\\s*-->`).exec(masked.slice(afterStart));
-  if (!end)
-    return null;
-  return body.slice(afterStart, afterStart + end.index);
-}
-// ../../packages/aeg-core/src/parse-registry.ts
-function parseRegistry(md) {
-  const rows = readMarkdownTable(md, /^##\s+Registry\b/i);
-  const projects = [];
-  for (const row of rows) {
-    if (row.length < 4)
-      continue;
-    const name = stripBackticks(row[0] ?? "").trim();
-    const path = stripBackticks(row[1] ?? "").trim();
-    const specsPath = stripBackticks(row[2] ?? "").trim();
-    const stateCell = (row[3] ?? "").trim();
-    if (!name || !path || !specsPath)
-      continue;
-    projects.push({
-      name,
-      path,
-      specsPath,
-      statePath: parseStateCell(stateCell)
-    });
-  }
-  return projects;
-}
-function parseStateCell(cell) {
-  if (!cell)
-    return null;
-  const stripped = stripBackticks(cell).trim();
-  if (/^[\w./@-]+\/?$/.test(stripped) && cell.includes("`")) {
-    return stripped;
-  }
-  return null;
-}
-function stripBackticks(s) {
-  return s.replace(/`/g, "");
-}
-function readMarkdownTable(md, headingMatcher) {
-  const lines = md.split(/\r?\n/);
-  let i = 0;
-  for (;i < lines.length; i++) {
-    if (headingMatcher.test(lines[i] ?? "")) {
-      i++;
-      break;
-    }
-  }
-  if (i >= lines.length)
-    return [];
-  for (;i < lines.length; i++) {
-    if ((lines[i] ?? "").trim().startsWith("|"))
-      break;
-  }
-  if (i + 1 >= lines.length)
-    return [];
-  i += 2;
-  const out = [];
-  for (;i < lines.length; i++) {
-    const trimmed = (lines[i] ?? "").trim();
-    if (!trimmed.startsWith("|"))
-      break;
-    out.push(splitTableRow(trimmed));
-  }
-  return out;
-}
-function splitTableRow(row) {
-  const PLACEHOLDER = "\x00PIPE\x00";
-  const escaped = row.replace(/\\\|/g, PLACEHOLDER);
-  const parts = escaped.split("|").map((s) => s.trim());
-  if (parts.length && parts[0] === "")
-    parts.shift();
-  if (parts.length && parts[parts.length - 1] === "")
-    parts.pop();
-  return parts.map((p) => p.split(PLACEHOLDER).join("|"));
-}
+
 // ../../packages/aeg-forge-state/src/parse-rationale-deps.ts
 var SECTION_HEADER = /\*\*Dependency rationale\*\*/i;
 var NEXT_HEADER = /\*\*[A-Z][^*]*\*\*/;
@@ -465,11 +393,37 @@ function findTrancheSlug(names) {
 var TITLE_PATTERN = /^\[([^\]]+)]\s*(\S+)\s*—\s*(.+)$/;
 var PROJECT_SLUG = /^[a-z0-9][a-z0-9-]*$/i;
 var PROJECT_FIELD = /^\s*(?:\*\*)?Project(?:\(s\))?(?:\*\*)?\s*:\s*(?:\*\*)?\s*(.+)$/im;
+var VALUE_EDGE_MARKUP = /^[`.;\s]+|[`.;\s]+$/g;
+function unwrapValue(raw) {
+  return raw.replace(/\*\*/g, "").replace(VALUE_EDGE_MARKUP, "");
+}
+function projectFieldFromBody(body) {
+  const m = stripCode(body, { inlineSpans: "keep" }).match(PROJECT_FIELD);
+  if (m)
+    return parseFieldValue(m[1] ?? "");
+  if (hasUnterminatedFence(body)) {
+    const raw = body.match(PROJECT_FIELD);
+    if (raw)
+      return { declared: true, names: [], unparsed: [(raw[1] ?? "").trim()], unreadable: true };
+  }
+  return { declared: false, names: [], unparsed: [], unreadable: false };
+}
+function parseFieldValue(value) {
+  const names = [];
+  const unparsed = [];
+  for (const raw of value.split(",")) {
+    const name = unwrapValue(raw);
+    if (name.length === 0)
+      continue;
+    if (PROJECT_SLUG.test(name))
+      names.push(name);
+    else
+      unparsed.push(raw.trim());
+  }
+  return { declared: true, names: [...new Set(names)], unparsed, unreadable: false };
+}
 function projectsFromBody(body) {
-  const m = body.match(PROJECT_FIELD);
-  if (!m)
-    return [];
-  return (m[1] ?? "").split(",").map((s) => s.trim()).filter((s) => PROJECT_SLUG.test(s));
+  return projectFieldFromBody(body).names;
 }
 function taskFromIssue(issue) {
   const m = issue.title.match(TITLE_PATTERN);
@@ -511,8 +465,8 @@ function tasksFromIssues(issues) {
   }
   return tasks.sort((a, b) => compareTaskIds(a.id, b.id));
 }
-async function listTasksForSlugAsync(owner, repo, slug) {
-  return tasksFromIssues(await ghIssueListByAnyLabelAsync(owner, repo, [trancheLabel(slug)]));
+async function fetchTrancheIssuesAsync(owner, repo, slug) {
+  return ghIssueListByAnyLabelAsync(owner, repo, [trancheLabel(slug)]);
 }
 function resolveTaskIssueRef(title, labels) {
   const m = title.match(TITLE_PATTERN);
@@ -528,17 +482,20 @@ function resolveTaskIssueRef(title, labels) {
 }
 
 // ../../packages/aeg-forge-state/src/derive-from-forge.ts
-async function deriveTrancheFromForge(owner, repo, slug, known) {
-  const milestone = known ?? findMilestoneForSlug(owner, repo, slug);
-  const tasks = await listTasksForSlugAsync(owner, repo, slug);
+function trancheFromIssues(slug, issues, known) {
   return {
     name: slug,
-    lifecycle: milestone?.lifecycle ?? "active",
-    goal: milestone?.goal ?? "",
-    tasks,
+    lifecycle: known?.lifecycle ?? "active",
+    goal: known?.goal ?? "",
+    tasks: tasksFromIssues(issues),
     backlog: []
   };
 }
+async function deriveTrancheFromForge(owner, repo, slug, known) {
+  const milestone = known ?? findMilestoneForSlug(owner, repo, slug);
+  const issues = await fetchTrancheIssuesAsync(owner, repo, slug);
+  return trancheFromIssues(slug, issues, milestone);
+}
 // ../../node_modules/universal-user-agent/index.js
 function getUserAgent() {
   if (typeof navigator === "object" && "userAgent" in navigator) {
@@ -1458,6 +1415,96 @@ var systemEnv3 = {
   ...process.env,
   PATH: [process.env.PATH, "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"].filter(Boolean).join(":")
 };
+// ../../packages/aeg-core/src/anchored-region.ts
+function anchoredRegionBounds(body, field) {
+  const masked = maskCode(body);
+  const start = new RegExp(`<!--\\s*AEG:${field}:START\\s*-->`).exec(masked);
+  if (!start)
+    return null;
+  const innerStart = start.index + start[0].length;
+  const end = new RegExp(`<!--\\s*AEG:${field}:END\\s*-->`).exec(masked.slice(innerStart));
+  if (!end)
+    return null;
+  const innerEnd = innerStart + end.index;
+  return { outerStart: start.index, outerEnd: innerEnd + end[0].length, innerStart, innerEnd };
+}
+function anchoredRegion(body, field) {
+  const bounds = anchoredRegionBounds(body, field);
+  if (!bounds)
+    return null;
+  return body.slice(bounds.innerStart, bounds.innerEnd);
+}
+// ../../packages/aeg-core/src/parse-registry.ts
+function parseRegistry(md) {
+  const rows = readMarkdownTable(md, /^##\s+Registry\b/i);
+  const projects = [];
+  for (const row of rows) {
+    if (row.length < 4)
+      continue;
+    const name = stripBackticks(row[0] ?? "").trim();
+    const path = stripBackticks(row[1] ?? "").trim();
+    const specsPath = stripBackticks(row[2] ?? "").trim();
+    const stateCell = (row[3] ?? "").trim();
+    if (!name || !path || !specsPath)
+      continue;
+    projects.push({
+      name,
+      path,
+      specsPath,
+      statePath: parseStateCell(stateCell)
+    });
+  }
+  return projects;
+}
+function parseStateCell(cell) {
+  if (!cell)
+    return null;
+  const stripped = stripBackticks(cell).trim();
+  if (/^[\w./@-]+\/?$/.test(stripped) && cell.includes("`")) {
+    return stripped;
+  }
+  return null;
+}
+function stripBackticks(s) {
+  return s.replace(/`/g, "");
+}
+function readMarkdownTable(md, headingMatcher) {
+  const lines = md.split(/\r?\n/);
+  let i = 0;
+  for (;i < lines.length; i++) {
+    if (headingMatcher.test(lines[i] ?? "")) {
+      i++;
+      break;
+    }
+  }
+  if (i >= lines.length)
+    return [];
+  for (;i < lines.length; i++) {
+    if ((lines[i] ?? "").trim().startsWith("|"))
+      break;
+  }
+  if (i + 1 >= lines.length)
+    return [];
+  i += 2;
+  const out = [];
+  for (;i < lines.length; i++) {
+    const trimmed = (lines[i] ?? "").trim();
+    if (!trimmed.startsWith("|"))
+      break;
+    out.push(splitTableRow(trimmed));
+  }
+  return out;
+}
+function splitTableRow(row) {
+  const PLACEHOLDER = "\x00PIPE\x00";
+  const escaped = row.replace(/\\\|/g, PLACEHOLDER);
+  const parts = escaped.split("|").map((s) => s.trim());
+  if (parts.length && parts[0] === "")
+    parts.shift();
+  if (parts.length && parts[parts.length - 1] === "")
+    parts.pop();
+  return parts.map((p) => p.split(PLACEHOLDER).join("|"));
+}
 // ../../packages/aeg-core/src/state-machine-model.ts
 var FORGE_FACT_INPUTS = [
   {
@@ -1961,23 +2008,65 @@ function checkIssueRationale(body) {
 function isTaskIssueLabelSet(labels) {
   return hasLabel("tranche", labels);
 }
+function isControlCodePoint(codePoint) {
+  return codePoint <= 31 || codePoint >= 127 && codePoint <= 159;
+}
+function isDisplayControlCodePoint(codePoint) {
+  return codePoint >= 8203 && codePoint <= 8207 || codePoint >= 8234 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297 || codePoint === 65279;
+}
+var MESSAGE_VALUE_COUNT_MAX = 5;
+function residueForMessage(values) {
+  const shown = values.slice(0, MESSAGE_VALUE_COUNT_MAX).map((v) => `\`${forMessage(v)}\``);
+  const rest = values.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")} and ${rest} more` : shown.join(", ");
+}
+var MESSAGE_VALUE_MAX = 64;
+function forMessage(value) {
+  const kept = [];
+  for (const ch of value.replace(/\s+/g, " ")) {
+    const codePoint = ch.codePointAt(0) ?? 0;
+    if (isControlCodePoint(codePoint) || isDisplayControlCodePoint(codePoint))
+      continue;
+    kept.push(ch);
+  }
+  const cleaned = kept.join("").trim();
+  if (cleaned.length === 0)
+    return "(unprintable)";
+  const points = Array.from(cleaned);
+  return points.length > MESSAGE_VALUE_MAX ? `${points.slice(0, MESSAGE_VALUE_MAX).join("")}…` : cleaned;
+}
 function checkProjectsRegistered(body, _labels, registeredNames) {
   if (registeredNames.length === 0)
     return { status: "pass", errors: [] };
-  const known = new Set(registeredNames.map((n) => n.trim()));
-  const unregistered = projectsFromBody(body).filter((p) => !known.has(p));
-  if (unregistered.length === 0)
+  const field = projectFieldFromBody(body);
+  if (!field.declared)
     return { status: "pass", errors: [] };
-  const caseHints = unregistered.map((p) => {
-    const row = [...known].find((k) => k.toLowerCase() === p.toLowerCase());
-    return row ? `\`${p}\` differs from the registered \`${row}\` only in case` : null;
-  }).filter((h) => h !== null);
-  return {
-    status: "fail",
-    errors: [
-      `issue-validation project registry: the \`**Project:**\` field declares ${unregistered.join(", ")} — no such row in \`.vinaya/projects.md\`, which is the authority for valid project names (registered: ${[...registeredNames].join(", ")}). Fix the name, or register the project with \`vinaya init product <name> --path <folder>\` first; an unregistered project has no specs to read and no per-project state to update.${caseHints.length > 0 ? ` Note: ${caseHints.join("; ")} — project names are matched exactly, because every downstream consumer compares them literally.` : ""} This reads the same field \`projectsFromBody\` derives the task's project from, so a name here that is not a row is a task that resolves to a project that does not exist.`
-    ]
-  };
+  const known = new Set(registeredNames.map((n) => n.trim()));
+  const registeredList = [...registeredNames].map(forMessage).join(", ");
+  const errors = [];
+  if (field.unreadable) {
+    return {
+      status: "fail",
+      errors: [
+        `issue-validation project registry: the body has an unterminated code fence, so its \`**Project:**\` field could not be read reliably — the fence runs to end of body (CommonMark, and how the forge renders it), swallowing everything after it including the foot field where the declaration lives by convention. Read from the raw body the field says ${residueForMessage(field.unparsed) || "(nothing)"}, but a line inside a swallowed region may be a quoted example rather than a real declaration, so this gate refuses rather than guessing which. Balance the fences — every opening run of backticks or tildes needs a closing run at least as long — and the field reads normally.`
+      ]
+    };
+  }
+  const unregistered = field.names.filter((p) => !known.has(p));
+  if (unregistered.length > 0) {
+    const caseHints = unregistered.map((p) => {
+      const row = [...known].find((k) => k.toLowerCase() === p.toLowerCase());
+      return row ? `\`${forMessage(p)}\` differs from the registered \`${forMessage(row)}\` only in case` : null;
+    }).filter((h) => h !== null);
+    errors.push(`issue-validation project registry: the \`**Project:**\` field declares ${unregistered.map(forMessage).join(", ")} — no such row in \`.vinaya/projects.md\`, which is the authority for valid project names (registered: ${registeredList}). Fix the name, or register the project with \`vinaya init product <name> --path <folder>\` first; an unregistered project has no specs to read and no per-project state to update.${caseHints.length > 0 ? ` Note: ${caseHints.join("; ")} — project names are matched exactly, because every downstream consumer compares them literally.` : ""} This reads the same field \`projectsFromBody\` derives the task's project from, so a name here that is not a row is a task that resolves to a project that does not exist.`);
+  }
+  if (field.names.length === 0) {
+    const residue = field.unparsed.length > 0 ? ` — ${residueForMessage(field.unparsed)}` : " — the field is empty";
+    errors.push(`issue-validation project registry: the \`**Project:**\` field is present but resolves to no project name${residue} (registered: ${registeredList}). A project name is a slug (\`[a-z0-9][a-z0-9-]*\`, matched exactly); prose, a parenthetical, or a sentence in this field resolves to no project at all, and this gate cannot check a name it never receives — which is how a declaration like this used to pass. Write the registered name on its own, or register the project with \`vinaya init product <name> --path <folder>\` first. If the task genuinely touches no registered project, omit the field rather than explaining its absence inside it — \`checkIssueRationale\` already requires the \`Project(s) + blast radius\` narrative field for that.`);
+  } else if (field.unparsed.length > 0) {
+    errors.push(`issue-validation project registry: the \`**Project:**\` field declares a value that is not a project name — ${residueForMessage(field.unparsed)} (registered: ${registeredList}). The rest of the field parsed, so this is a name the gate silently could not check rather than a field it could not read at all. A project name is a slug (\`[a-z0-9][a-z0-9-]*\`, matched exactly); write it on its own, or drop it if it names no project.`);
+  }
+  return errors.length > 0 ? { status: "fail", errors } : { status: "pass", errors: [] };
 }
 
 // ../../packages/aeg-core/src/coherence-checks.ts
@@ -2940,6 +3029,21 @@ function evaluateTestPlanGate(body, branch) {
   messages.push("All Test Plan items ticked — runtime verification complete.", "PASS.");
   return { verdict: "pass", messages };
 }
+// src/lib/diff-evidence.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
+function fileDiffAgainst(ref, path) {
+  let out;
+  try {
+    out = execFileSync2("git", ["diff", `${ref}...HEAD`, "--", path], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+  } catch {
+    return null;
+  }
+  return out === "" ? null : out;
+}
+
 // src/checks/contract.ts
 var CHECK_SCHEMA_VERSION = 1;
 function emitCheckError(error) {
@@ -2948,7 +3052,7 @@ function emitCheckError(error) {
 }
 
 // src/lib/config.ts
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { z } from "zod";
@@ -3063,7 +3167,7 @@ function trustAnchorRepo() {
       return validated;
   }
   try {
-    const url = execFileSync2("git", ["remote", "get-url", "origin"], {
+    const url = execFileSync3("git", ["remote", "get-url", "origin"], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"]
     }).trim();
@@ -3077,7 +3181,7 @@ function ghFetchTrustAnchorConfig() {
   const repo = trustAnchorRepo();
   if (!repo)
     throw new Error("could not resolve repo identity for the trust-anchor read");
-  return execFileSync2("gh", ["api", `repos/${repo}/contents/${LOCAL_CONFIG_FILENAME}`, "--jq", ".content"], {
+  return execFileSync3("gh", ["api", `repos/${repo}/contents/${LOCAL_CONFIG_FILENAME}`, "--jq", ".content"], {
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -3125,7 +3229,7 @@ function loadTrustAnchorConfig(fetcher = ghFetchTrustAnchorConfig) {
 var CHECK_NAME = "doc-coverage";
 function git(args) {
   try {
-    return execFileSync3("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    return execFileSync4("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
   } catch {
     return "";
   }
@@ -3148,7 +3252,7 @@ function resolvePrBody() {
 }
 function fetchPrLabels(prNumber) {
   try {
-    const out = execFileSync3("gh", ["pr", "view", String(prNumber), "--json", "labels"], {
+    const out = execFileSync4("gh", ["pr", "view", String(prNumber), "--json", "labels"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -3159,7 +3263,7 @@ function fetchPrLabels(prNumber) {
 }
 function fetchWaiverLabelActor(prNumber, label2) {
   try {
-    const out = execFileSync3("gh", ["api", `repos/{owner}/{repo}/issues/${prNumber}/timeline`, "--paginate"], {
+    const out = execFileSync4("gh", ["api", `repos/{owner}/{repo}/issues/${prNumber}/timeline`, "--paginate"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -3188,14 +3292,17 @@ function waiverActive() {
 }
 function main() {
   const base = process.env.BASE_SHA || "origin/main";
-  let changed = changedFiles(base);
-  if (changed.length === 0)
-    changed = changedFiles("main");
+  let ref = base;
+  let changed = changedFiles(ref);
+  if (changed.length === 0) {
+    ref = "main";
+    changed = changedFiles(ref);
+  }
   if (changed.length === 0) {
     process.exit(0);
   }
   const content = existsSync(DOC_OWNERS_PATH) ? readFileSync(DOC_OWNERS_PATH, "utf8") : null;
-  const result = evaluateC5(changed, content, resolvePrBody(), existsSync, waiverActive());
+  const result = evaluateC5(changed, content, resolvePrBody(), existsSync, waiverActive(), (p) => fileDiffAgainst(ref, p));
   if (result.errors.length > 0) {
     for (const message of result.errors) {
       emitCheckError({