@mmerterden/multi-agent-pipeline 12.1.1 → 12.3.0

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

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// validate-analysis-doc.mjs  -  deterministic validator for an EMITTED
+// /multi-agent:analysis document (analysis/<feature>-<platform>.md).
+//
+// The analysis SKILL states many "fails the dispatch gate" invariants as prose
+// the model is asked to self-enforce. This turns the high-value, mechanically
+// checkable ones into a real gate so a malformed spec is caught before it is
+// handed to a human or to /multi-agent:dev.
+//
+// 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 (feature, platform, language, mode,
+//     template_version); mode in {full, lite}; platform in the known set.
+//   - Never-omitted sections present by title keyword (Locked 2): Summary,
+//     Goals, User Stories, API Contracts, Architecture, Files to Add, Risks,
+//     References.
+//   - Humanizer punctuation policy (Locked 7): no em-dash / en-dash / ellipsis /
+//     section-sign / curly quotes anywhere in the body.
+//   - Traceability (Full mode only, Locked 31): every BR-<slug>-NN id defined in
+//     the Business Rules area is referenced again later (test / acceptance /
+//     analytics). A define-only rule is a WARN (heuristic).
+//   - No whole-section "TBD" / "Not applicable" placeholder bodies (Locked 2);
+//     the inline "[label TBD - see Open Questions]" marker is allowed.
+//
+// Usage:
+//   node validate-analysis-doc.mjs analysis/UserProfile-ios.md
+//   cat doc.md | node validate-analysis-doc.mjs -
+//   node validate-analysis-doc.mjs doc.md --strict   # WARN also fails
+//
+// Exit: 0 valid, 1 invalid (or WARN under --strict), 64 usage error.
+
+import { readFileSync } from "node:fs";
+
+const KNOWN_PLATFORMS = new Set(["ios", "android", "backend", "frontend"]);
+const REQUIRED_FM = ["feature", "platform", "language", "mode", "template_version"];
+
+// Never-omitted sections (Locked 2), matched by bilingual title keyword so the
+// re-flowed section numbering does not matter.
+const REQUIRED_SECTIONS = [
+  { key: "summary", any: ["Summary", "Özet", "Ozet"] },
+  { key: "goals", any: ["Goals", "Hedefler"] },
+  { key: "user stories", any: ["User Stories", "Kullanıcı Hikayeleri", "Kullanici Hikayeleri"] },
+  { key: "api contracts", any: ["API Contracts", "API Kontratları", "API Kontratlari"] },
+  { key: "architecture", any: ["Architecture", "Mimari"] },
+  { key: "files to add", any: ["Files to Add", "Eklenecek Dosyalar"] },
+  { key: "risks", any: ["Risks", "Riskler"] },
+  { key: "references", any: ["References", "Referanslar"] },
+];
+
+// Humanizer punctuation policy (Locked 7) - banned codepoints.
+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" },
+];
+
+function readInput() {
+  const args = process.argv.slice(2).filter((a) => a !== "--strict");
+  const arg = args[0];
+  if (!arg) {
+    console.error("usage: validate-analysis-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 };
+}
+
+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 mode = parsed.fm.mode;
+    if (mode && mode !== "full" && mode !== "lite") {
+      errors.push(`front-matter mode must be full|lite, got: ${mode}`);
+    }
+    const plat = parsed.fm.platform;
+    if (plat && !KNOWN_PLATFORMS.has(plat)) {
+      errors.push(`front-matter platform not in known set: ${plat}`);
+    }
+  }
+  const mode = parsed?.fm?.mode || "full";
+
+  // 2. Never-omitted sections (by heading keyword)
+  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 (Locked 2): ${sec.key}`);
+    }
+  }
+
+  // 2b. Opt-in coverage sections must be present when the front-matter says so.
+  const uiTests = String(parsed?.fm?.ui_tests || "false").toLowerCase() === "true";
+  const a11yDepth = String(parsed?.fm?.a11y_depth || "basic").toLowerCase();
+  const headingBlobLower = headingBlob.toLowerCase();
+  if (uiTests) {
+    const hasUi =
+      headingBlob.includes("15.6") ||
+      headingBlobLower.includes("ui test") ||
+      headingBlobLower.includes("ui-test");
+    if (!hasUi) {
+      errors.push("front-matter ui_tests: true but no Section 15.6 UI test scenarios found (Locked 31)");
+    }
+  }
+  if (a11yDepth === "full") {
+    const hasWalkthrough =
+      headingBlob.includes("16.2") ||
+      headingBlobLower.includes("walkthrough") ||
+      headingBlobLower.includes("gezinme");
+    if (!hasWalkthrough) {
+      errors.push("front-matter a11y_depth: full but no Section 16.2 screen-reader walkthrough found");
+    }
+  }
+
+  // 3. 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} (Locked 7 humanizer policy)`);
+      }
+    }
+  }
+
+  // 4. Placeholder whole-section bodies (Locked 2)
+  if (/^\s*(TBD|Not applicable|N\/A)\s*$/im.test(text)) {
+    warns.push('a line is a bare "TBD"/"Not applicable"/"N/A" body; omit the section instead (Locked 2)');
+  }
+
+  // 5. Traceability (Full mode only, Locked 31)
+  if (mode === "full") {
+    const idRe = /BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/gi;
+    const all = text.match(idRe) || [];
+    const counts = new Map();
+    for (const id of all) {
+      const key = id.toUpperCase();
+      counts.set(key, (counts.get(key) || 0) + 1);
+    }
+    if (counts.size === 0) {
+      warns.push("Full mode but no BR-<slug>-NN business-rule ids found (Section 4.4 / Locked 31)");
+    }
+    for (const [id, n] of counts) {
+      if (n < 2) {
+        warns.push(`business rule ${id} is defined but never referenced downstream (test/acceptance/analytics) - Locked 31 traceability`);
+      }
+    }
+  }
+
+  // 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-analysis-doc: FAIL (${errors.length} error(s), ${warns.length} warning(s))`);
+    process.exit(1);
+  }
+  if (strict && warns.length > 0) {
+    console.error(`validate-analysis-doc: FAIL under --strict (${warns.length} warning(s))`);
+    process.exit(1);
+  }
+  console.log(`validate-analysis-doc: OK (mode=${mode}, ${warns.length} warning(s))`);
+  process.exit(0);
+}
+
+main();