@mmerterden/multi-agent-pipeline 14.2.2 → 15.1.0

package/pipeline/scripts/validate-complaint-doc.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// validate-complaint-doc.mjs  -  deterministic validator for an EMITTED
+// /multi-agent:complaint-analysis report (complaints/<run-name>.md).
+//
+// The complaint-analysis SKILL states its "fails the dispatch gate" invariants
+// as prose; this turns the mechanically checkable ones into a real gate so a
+// malformed or PII-leaking report is caught before it reaches Confluence,
+// Jira, or a repo working tree.
+//
+// Zero deps. Reads one markdown file (path arg or STDIN).
+//
+// Checks (ERROR = blocking exit 1; WARN = advisory, still exit 0 unless --strict):
+//   - Front-matter block with required keys (run_name, generated_at, language,
+//     complaint_count, graylog_degraded); language in {tr, en}.
+//   - Required sections present by bilingual title keyword: Summary, Triage,
+//     Complaint Details, Open Questions, Methodology, References.
+//   - Every triage-table row (a row in the Triage section whose FIRST cell is
+//     a C-NN id) has a valid verdict token in a cell of its own:
+//     client:<layer> | bff:<layer> | core | insufficient-evidence.
+//     Verdict tokens stay English in both languages (payload vocabulary).
+//     Scoping matters: the Section 1 coverage table cites C-NN ids in its
+//     "Verdicts attributed" column and must not be read as triage rows, and a
+//     summary cell mentioning "core" must not classify the row as core.
+//   - Every core verdict has a matching entry in the routing section
+//     (Yönlendirme / Routing), and that section exists when any core row does.
+//   - Every client/bff verdict has a fix-plan marker (Fix plan / Geliştirme
+//     planı) in the complaint-details section (development handoff, Locked 13).
+//   - Humanizer punctuation policy: no em-dash / en-dash / ellipsis /
+//     section-sign / curly quotes anywhere.
+//   - Redaction leak scan: an email address or a 13-19 digit card-like run is
+//     an ERROR; a bare 11-digit run is a WARN (could be a numeric trx id); a
+//     PNR-shaped token (6-char uppercase letter+digit mix, or 6 uppercase
+//     letters right after a "PNR" keyword) is a WARN.
+//
+// Usage:
+//   node validate-complaint-doc.mjs complaints/complaints-20260810.md
+//   cat report.md | node validate-complaint-doc.mjs -
+//   node validate-complaint-doc.mjs report.md --strict   # WARN also fails
+//
+// Exit: 0 valid, 1 invalid (or WARN under --strict), 64 usage error.
+
+import { readFileSync } from "node:fs";
+
+const REQUIRED_FM = ["run_name", "generated_at", "language", "complaint_count", "graylog_degraded"];
+
+const REQUIRED_SECTIONS = [
+  { key: "summary", any: ["Summary", "Özet", "Ozet"] },
+  { key: "triage table", any: ["Triage"] },
+  { key: "complaint details", any: ["Complaint Details", "Şikayet Detayları", "Sikayet Detaylari", "Detay"] },
+  { key: "open questions", any: ["Open Questions", "Açık Sorular", "Acik Sorular"] },
+  { key: "methodology", any: ["Methodology", "Metodoloji"] },
+  { key: "references", any: ["References", "Referanslar"] },
+];
+
+const ROUTING_KEYWORDS = ["Routing", "Yönlendirme", "Yonlendirme"];
+const FIX_PLAN_RE = /(Fix plan|Fix Plan|Geliştirme planı|Geliştirme Planı|Gelistirme plani|Gelistirme Plani)/;
+
+// Cell-exact on purpose: a substring match would classify a row as `core`
+// because its summary says "core-data" or "core team" before the verdict column.
+const VERDICT_CELL_RE =
+  /^(client:(ios|android|web)|bff:(mobile-bff|web-bff)|core|insufficient-evidence)$/;
+
+const BANNED_PUNCT = [
+  { ch: "—", name: "em-dash" },
+  { ch: "–", name: "en-dash" },
+  { ch: "…", name: "ellipsis" },
+  { ch: "§", name: "section-sign" },
+  { ch: "“", name: "curly-double-open" },
+  { ch: "”", name: "curly-double-close" },
+  { ch: "‘", name: "curly-single-open" },
+  { ch: "’", name: "curly-single-close" },
+];
+
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/;
+const CARD_RE = /\b\d(?:[ -]?\d){12,18}\b/;
+const NATIONAL_ID_RE = /\b\d{11}\b/;
+// Same shape parse-complaints.sh redacts (6-char uppercase alnum with at least
+// one letter AND one digit), so a leak the parser should have caught fails
+// loudly here too. All-letter PNRs are only flaggable with context: a bare
+// 6-letter word is far too common, so those warn only right after "PNR".
+const PNR_MIXED_RE = /\b(?=[A-Z0-9]{6}\b)(?=[A-Z0-9]*\d)(?=\d*[A-Z])[A-Z0-9]{6}\b/;
+const PNR_CONTEXT_RE = /\bPNR\b[^A-Za-z0-9\n]{0,3}[A-Z]{6}\b/;
+
+function readInput() {
+  const args = process.argv.slice(2).filter((a) => a !== "--strict");
+  const arg = args[0];
+  if (!arg) {
+    console.error("usage: validate-complaint-doc.mjs <path|-> [--strict]");
+    process.exit(64);
+  }
+  if (arg === "-") return readFileSync(0, "utf-8");
+  return readFileSync(arg, "utf-8");
+}
+
+function parseFrontMatter(text) {
+  const lines = text.split("\n");
+  if (lines[0].trim() !== "---") return null;
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return null;
+  const fm = {};
+  for (let i = 1; i < end; i++) {
+    const m = lines[i].match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+    if (m) fm[m[1]] = m[2].trim();
+  }
+  return { fm, bodyStart: end + 1 };
+}
+
+// The routing section body: from the heading whose title contains a routing
+// keyword to the next heading of the same or shallower depth.
+function sectionBody(text, keywords) {
+  const lines = text.split("\n");
+  let start = -1;
+  let depth = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{1,3})\s+(.*)$/);
+    if (!m) continue;
+    if (start < 0 && keywords.some((kw) => m[2].includes(kw))) {
+      start = i;
+      depth = m[1].length;
+      continue;
+    }
+    if (start >= 0 && m[1].length <= depth) {
+      return lines.slice(start, i).join("\n");
+    }
+  }
+  return start >= 0 ? lines.slice(start).join("\n") : null;
+}
+
+function main() {
+  const text = readInput();
+  const strict = process.argv.includes("--strict");
+  const errors = [];
+  const warns = [];
+
+  // 1. Front-matter
+  const parsed = parseFrontMatter(text);
+  if (!parsed) {
+    errors.push("missing YAML front-matter block (--- ... ---) at the top");
+  } else {
+    for (const k of REQUIRED_FM) {
+      if (!parsed.fm[k]) errors.push(`front-matter missing required key: ${k}`);
+    }
+    const lang = parsed.fm.language;
+    if (lang && lang !== "tr" && lang !== "en") {
+      errors.push(`front-matter language must be tr|en, got: ${lang}`);
+    }
+  }
+
+  // 2. Required sections (by heading keyword, bilingual)
+  const headings = text
+    .split("\n")
+    .filter((l) => /^#{1,3}\s/.test(l))
+    .map((l) => l.replace(/^#{1,3}\s/, "").trim());
+  const headingBlob = headings.join("\n");
+  for (const sec of REQUIRED_SECTIONS) {
+    if (!sec.any.some((kw) => headingBlob.includes(kw))) {
+      errors.push(`missing required section: ${sec.key}`);
+    }
+  }
+
+  // 3. Triage rows: scoped to the Triage section (the Section 1 coverage table
+  // also cites C-NN ids, in its "Verdicts attributed" column), and a triage row
+  // carries the id in its FIRST cell. Every such row needs a verdict cell.
+  const triageScope = sectionBody(text, ["Triage"]) ?? text;
+  const rows = triageScope.split("\n").filter((l) => /^\s*\|\s*C-\d{2,}\s*\|/.test(l));
+  if (rows.length === 0) {
+    errors.push("no triage rows found (expected Triage-section rows with a C-NN id in the first cell)");
+  }
+  const coreIds = [];
+  const handoffIds = [];
+  for (const row of rows) {
+    const id = (row.match(/\bC-\d{2,}\b/) || [])[0];
+    const cells = row.split("|").map((c) => c.trim());
+    const verdict = cells.find((c) => VERDICT_CELL_RE.test(c));
+    if (!verdict) {
+      errors.push(`triage row ${id} has no valid verdict token (client:<layer> | bff:<layer> | core | insufficient-evidence)`);
+    } else if (verdict === "core" && !coreIds.includes(id)) {
+      coreIds.push(id);
+    } else if (/^(client|bff):/.test(verdict) && !handoffIds.includes(id)) {
+      handoffIds.push(id);
+    }
+  }
+
+  // 4. Core verdicts require the routing section, one entry per complaint.
+  if (coreIds.length > 0) {
+    const routing = sectionBody(text, ROUTING_KEYWORDS);
+    if (!routing) {
+      errors.push(`core verdict(s) ${coreIds.join(", ")} but no routing section (Yönlendirme / Routing)`);
+    } else {
+      for (const id of coreIds) {
+        if (!routing.includes(id)) {
+          errors.push(`core verdict ${id} has no entry in the routing section`);
+        }
+      }
+    }
+  }
+
+  // 4b. Client/bff verdicts require a fix-plan block under their C-NN detail
+  // subsection (development handoff, Locked 13).
+  for (const id of handoffIds) {
+    const detail = sectionBody(text, [id]);
+    if (!detail || !FIX_PLAN_RE.test(detail)) {
+      errors.push(`client/bff verdict ${id} has no fix-plan block (Fix plan / Geliştirme planı) in its detail section`);
+    }
+  }
+
+  // 5. Humanizer punctuation
+  const bodyLines = text.split("\n");
+  for (let i = 0; i < bodyLines.length; i++) {
+    for (const b of BANNED_PUNCT) {
+      if (bodyLines[i].includes(b.ch)) {
+        errors.push(`banned punctuation ${b.name} at line ${i + 1} (humanizer policy)`);
+      }
+    }
+  }
+
+  // 6. Redaction leak scan
+  for (let i = 0; i < bodyLines.length; i++) {
+    if (EMAIL_RE.test(bodyLines[i])) {
+      errors.push(`redaction leak: email address at line ${i + 1}`);
+    }
+    if (CARD_RE.test(bodyLines[i])) {
+      errors.push(`redaction leak: card-like digit run at line ${i + 1}`);
+    }
+    if (NATIONAL_ID_RE.test(bodyLines[i]) && !CARD_RE.test(bodyLines[i])) {
+      warns.push(`possible redaction leak: bare 11-digit run at line ${i + 1} (national-id-like; ignore if it is a numeric trx id)`);
+    }
+    if (PNR_MIXED_RE.test(bodyLines[i]) || PNR_CONTEXT_RE.test(bodyLines[i])) {
+      warns.push(`possible redaction leak: PNR-shaped token at line ${i + 1} (parse-complaints.sh should have redacted it)`);
+    }
+  }
+
+  // Report
+  for (const w of warns) console.error(`WARN: ${w}`);
+  for (const e of errors) console.error(`ERROR: ${e}`);
+  if (errors.length > 0) {
+    console.error(
+      `validate-complaint-doc: FAIL (${errors.length} error(s), ${warns.length} warning(s))`,
+    );
+    process.exit(1);
+  }
+  if (strict && warns.length > 0) {
+    console.error(`validate-complaint-doc: FAIL under --strict (${warns.length} warning(s))`);
+    process.exit(1);
+  }
+  console.log(`validate-complaint-doc: OK (${warns.length} warning(s))`);
+  process.exit(0);
+}
+
+main();

package/pipeline/scripts/validate-reviewer.mjs

@@ -127,8 +127,13 @@ function validateConformance(parsed, selectedIds, errors) {
         `${label} (${id}): verdict "conformant" needs the file it was checked in  -  a verdict with no evidence is an assertion`,
       );
     }
-    if (row.verdict === "not-applicable" && (typeof row.reason !== "string" || row.reason.length < 4)) {
-      errors.push(`${label} (${id}): verdict "not-applicable" needs a reason naming why the rule cannot bind`);
+    if (
+      row.verdict === "not-applicable" &&
+      (typeof row.reason !== "string" || row.reason.length < 4)
+    ) {
+      errors.push(
+        `${label} (${id}): verdict "not-applicable" needs a reason naming why the rule cannot bind`,
+      );
     }
     if (row.verdict === "violated") {
       const matched = (parsed.findings ?? []).some((f) => f?.ruleId === id);
@@ -141,7 +146,8 @@ function validateConformance(parsed, selectedIds, errors) {
   });
 
   for (const [id, count] of seen) {
-    if (count > 1) errors.push(`conformance: ruleId "${id}" appears ${count} times (expected exactly once)`);
+    if (count > 1)
+      errors.push(`conformance: ruleId "${id}" appears ${count} times (expected exactly once)`);
   }
   const missing = [...selectedIds].filter((id) => !seen.has(id));
   if (missing.length > 0) {