vibe-coding-master 0.8.13 → 0.9.0

package/scripts/harness-tools/check-durable-docs

@@ -1,298 +1,332 @@
-#!/usr/bin/env python3
-import argparse
-import json
-import re
-import subprocess
-import sys
-from dataclasses import asdict, dataclass
-from pathlib import Path
-
-
-EXCLUDED_PARTS = {".git", ".claude", ".ai", "target", "node_modules", "dist", "build"}
-KNOWN_ISSUE_FIELDS = (
-    "status",
-    "category",
-    "affected modules/surfaces",
-    "current gap",
-    "impact",
-    "mitigation or workaround",
-    "resolution condition",
-    "related issues",
-)
-TERMINAL_PLAN_WORDS = ("complete", "completed", "shipped", "delivered", "closed", "done", "superseded", "obsolete")
-
-
-@dataclass(frozen=True)
-class Finding:
-    code: str
-    path: str
-    line: int
-    message: str
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Check VCM durable project documentation contracts.")
-    parser.add_argument("--json", action="store_true", dest="json_output", help="Write machine-readable output.")
-    return parser.parse_args()
-
-
-def repository_root() -> Path:
-    try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--show-toplevel"],
-            check=False,
-            text=True,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.DEVNULL,
-        )
-    except FileNotFoundError:
-        return Path.cwd().resolve()
-    if result.returncode == 0 and result.stdout.strip():
-        return Path(result.stdout.strip()).resolve()
-    return Path.cwd().resolve()
-
-
-def relative(path: Path, root: Path) -> str:
-    return path.resolve().relative_to(root).as_posix()
-
-
-def read_text(path: Path) -> str:
-    return path.read_text(encoding="utf-8")
-
-
-def markdown_headings(lines: list[str], pattern: re.Pattern[str]) -> list[tuple[int, re.Match[str]]]:
-    headings: list[tuple[int, re.Match[str]]] = []
-    fenced = False
-    for index, line in enumerate(lines):
-        if re.match(r"^\s*(```|~~~)", line):
-            fenced = not fenced
-            continue
-        if fenced:
-            continue
-        match = pattern.match(line)
-        if match:
-            headings.append((index, match))
-    return headings
-
-
-def first_match_line(lines: list[str], pattern: re.Pattern[str], start: int = 0, end: int | None = None) -> int | None:
-    stop = len(lines) if end is None else min(end, len(lines))
-    for index in range(start, stop):
-        if pattern.search(lines[index]):
-            return index + 1
-    return None
-
-
-def check_known_issues(root: Path, findings: list[Finding]) -> None:
-    path = root / "docs/known-issues.md"
-    if not path.is_file():
-        return
-    lines = read_text(path).splitlines()
-    heading_pattern = re.compile(r"^##\s+(?:\[)?KI-(\d+)(?:\])?\b", re.IGNORECASE)
-    headings = markdown_headings(lines, heading_pattern)
-    for heading_index, (start, match) in enumerate(headings):
-        end = headings[heading_index + 1][0] if heading_index + 1 < len(headings) else len(lines)
-        body = "\n".join(lines[start + 1:end])
-        issue_id = f"KI-{match.group(1)}"
-        fields: dict[str, str] = {}
-        for line in lines[start + 1:end]:
-            field_match = re.match(r"^\s*-\s*([^:]+):\s*(.*)$", line)
-            if field_match:
-                fields[field_match.group(1).strip().lower()] = field_match.group(2).strip()
-        missing = [field for field in KNOWN_ISSUE_FIELDS if field not in fields]
-        if missing:
-            findings.append(Finding(
-                "DD_KI_FIELDS",
-                relative(path, root),
-                start + 1,
-                f"{issue_id} is missing required current-state fields: {', '.join(missing)}.",
-            ))
-        status = fields.get("status", "").lower()
-        if status and status not in {"open", "planned", "accepted"}:
-            findings.append(Finding(
-                "DD_KI_STATUS",
-                relative(path, root),
-                start + 1,
-                f"{issue_id} has non-current status '{fields['status']}'. Remove terminal issues instead of retaining history.",
-            ))
-        resolved_line = first_match_line(
-            lines,
-            re.compile(r"(?:\bRESOLVED\b|\bFIXED\b|\bCLOSED\b|\bOBSOLETE\b|nothing remains open)", re.IGNORECASE),
-            start,
-            end,
-        )
-        if resolved_line is not None:
-            findings.append(Finding(
-                "DD_KI_RESOLVED_HISTORY",
-                relative(path, root),
-                resolved_line,
-                f"{issue_id} retains resolved or terminal history. Rewrite the entry around only the current unresolved gap.",
-            ))
-        provenance_line = first_match_line(
-            lines,
-            re.compile(r"\bROUND-?\d+\b|\b(?:reviewer|tester)[ -]?(?:confirmed|approved|proven)|\bcommit\s+`?[0-9a-f]{7,40}\b", re.IGNORECASE),
-            start,
-            end,
-        )
-        if provenance_line is not None:
-            findings.append(Finding(
-                "DD_KI_TASK_HISTORY",
-                relative(path, root),
-                provenance_line,
-                f"{issue_id} contains task or validation provenance that belongs in Git, PR, or task evidence.",
-            ))
-
-
-def check_active_plans(root: Path, findings: list[Finding]) -> None:
-    plans_root = root / "docs/plans"
-    if not plans_root.is_dir():
-        return
-    terminal_pattern = re.compile(r"\b(?:" + "|".join(TERMINAL_PLAN_WORDS) + r")\b", re.IGNORECASE)
-    status_pattern = re.compile(r"^\s*(?:>\s*)?(?:\*\*)?(?:status|stability)(?:\*\*)?\s*[:\-\u2014]", re.IGNORECASE)
-    closed_doc_pattern = re.compile(r"\b(?:plan|task|document|doc|phase|work)\b.{0,40}\b(?:is\s+)?(?:closed|complete|completed|shipped|delivered|done)\b", re.IGNORECASE)
-    for path in sorted(plans_root.rglob("*.md")):
-        lines = read_text(path).splitlines()
-        for index, line in enumerate(lines[:60]):
-            if (status_pattern.search(line) and terminal_pattern.search(line)) or (index < 15 and closed_doc_pattern.search(line)):
-                findings.append(Finding(
-                    "DD_ACTIVE_PLAN_TERMINAL",
-                    relative(path, root),
-                    index + 1,
-                    "Completed or terminal plans must leave the active plans collection; Git and PR history preserve execution history.",
-                ))
-                break
-
-
-def architecture_docs(root: Path) -> list[Path]:
-    paths: list[Path] = []
-    project_doc = root / "docs/ARCHITECTURE.md"
-    if project_doc.is_file():
-        paths.append(project_doc)
-    for path in root.rglob("ARCHITECTURE.md"):
-        if path == project_doc or any(part in EXCLUDED_PARTS for part in path.relative_to(root).parts):
-            continue
-        paths.append(path)
-    return sorted(set(paths))
-
-
-def check_architecture_history(root: Path, findings: list[Finding]) -> None:
-    patterns = (
-        ("DD_ARCH_TASK_LABEL", re.compile(r"\bSCF-[A-Za-z0-9.-]+\b|\bROUND-?\d+\b", re.IGNORECASE), "task labels"),
-        ("DD_ARCH_COMMIT_HISTORY", re.compile(r"\bcommit\s+`?[0-9a-f]{7,40}\b", re.IGNORECASE), "commit history"),
-        ("DD_ARCH_VALIDATION_HISTORY", re.compile(r"\b(?:reviewer|tester).{0,40}(?:PASS|confirmed|approved|proven)\b", re.IGNORECASE), "role validation history"),
-    )
-    for path in architecture_docs(root):
-        lines = read_text(path).splitlines()
-        for code, pattern, label in patterns:
-            line = first_match_line(lines, pattern)
-            if line is not None:
-                findings.append(Finding(
-                    code,
-                    relative(path, root),
-                    line,
-                    f"Architecture documentation contains {label}; keep only current architecture and use Git, PR, or task evidence for history.",
-                ))
-
-
-def check_testing_history(root: Path, findings: list[Finding]) -> None:
-    path = root / "docs/TESTING.md"
-    if not path.is_file():
-        return
-    lines = read_text(path).splitlines()
-    patterns = (
-        ("DD_TEST_TASK_HISTORY", re.compile(r"\bROUND-?\d+\b|\bcommit\s+`?[0-9a-f]{7,40}\b", re.IGNORECASE), "task or commit history"),
-        ("DD_TEST_VERDICT_HISTORY", re.compile(r"\b(?:reviewer|tester)[ -]?(?:confirmed|approved|proven)|\bL[0-4]\s+(?:PASS|FAIL)\b", re.IGNORECASE), "past validation verdicts"),
-        ("DD_TEST_LEGACY_OWNER", re.compile(r"\breviewer-owned\b|\brun by the reviewer\b", re.IGNORECASE), "legacy Reviewer ownership"),
-    )
-    for code, pattern, label in patterns:
-        line = first_match_line(lines, pattern)
-        if line is not None:
-            findings.append(Finding(
-                code,
-                relative(path, root),
-                line,
-                f"Testing documentation contains {label}; keep current strategy, runnable commands, case definitions, and current gaps only.",
-            ))
-
-
-def load_module_index(root: Path) -> dict | None:
-    path = root / ".ai/generated/module-index.json"
-    if not path.is_file():
-        return None
-    try:
-        value = json.loads(read_text(path))
-    except (json.JSONDecodeError, OSError):
-        return None
-    return value if isinstance(value, dict) else None
-
-
-def check_generated_architecture_facts(root: Path, findings: list[Finding]) -> None:
-    index = load_module_index(root)
-    if index is None:
-        return
-    layers = index.get("layers")
-    if not isinstance(layers, list):
-        return
-    layer_counts: dict[str, int] = {}
-    for layer in layers:
-        if not isinstance(layer, dict) or not isinstance(layer.get("name"), str) or not isinstance(layer.get("modules"), list):
-            continue
-        name = layer["name"]
-        modules = layer["modules"]
-        layer_counts[name] = len(modules)
-        for module in modules:
-            if not isinstance(module, dict):
-                continue
-            architecture_doc = module.get("architectureDoc")
-            if isinstance(architecture_doc, str) and architecture_doc and not (root / architecture_doc).is_file():
-                findings.append(Finding(
-                    "DD_MODULE_ARCH_MISSING",
-                    architecture_doc,
-                    1,
-                    f"Module index names a missing architecture document for module '{module.get('name', 'unknown')}'.",
-                ))
-    project_doc = root / "docs/ARCHITECTURE.md"
-    if not project_doc.is_file():
-        return
-    row_pattern = re.compile(r"^\|\s*`?([^`|]+)`?\s*\|\s*(\d+)\s*\|")
-    for index_number, line in enumerate(read_text(project_doc).splitlines()):
-        match = row_pattern.match(line)
-        if not match:
-            continue
-        name = match.group(1).strip()
-        if name not in layer_counts:
-            continue
-        documented = int(match.group(2))
-        generated = layer_counts[name]
-        if documented != generated:
-            findings.append(Finding(
-                "DD_ARCH_GENERATED_COUNT",
-                relative(project_doc, root),
-                index_number + 1,
-                f"Layer '{name}' documents {documented} modules, but .ai/generated/module-index.json contains {generated}.",
-            ))
-
-
-def main() -> int:
-    args = parse_args()
-    root = repository_root()
-    findings: list[Finding] = []
-    check_known_issues(root, findings)
-    check_active_plans(root, findings)
-    check_architecture_history(root, findings)
-    check_testing_history(root, findings)
-    check_generated_architecture_facts(root, findings)
-    findings.sort(key=lambda item: (item.path, item.line, item.code))
-    if args.json_output:
-        print(json.dumps({"ok": not findings, "findings": [asdict(item) for item in findings]}, indent=2))
-    elif findings:
-        for item in findings:
-            print(f"{item.path}:{item.line}: [{item.code}] {item.message}")
-        print(f"Durable docs audit failed with {len(findings)} finding(s).")
-    else:
-        print("Durable docs audit passed.")
-    return 1 if findings else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+#!/usr/bin/env node
+"use strict";
+// Check VCM durable project documentation contracts.
+
+const childProcess = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const EXCLUDED_PARTS = new Set([".git", ".claude", ".ai", "target", "node_modules", "dist", "build"]);
+const KNOWN_ISSUE_FIELDS = [
+  "status",
+  "category",
+  "affected modules/surfaces",
+  "current gap",
+  "impact",
+  "mitigation or workaround",
+  "resolution condition",
+  "related issues"
+];
+const TERMINAL_PLAN_WORDS = ["complete", "completed", "shipped", "delivered", "closed", "done", "superseded", "obsolete"];
+
+function parseArgs(argv) {
+  const args = { jsonOutput: false };
+  for (const argument of argv) {
+    if (argument === "--json") {
+      args.jsonOutput = true;
+    } else if (argument === "-h" || argument === "--help") {
+      process.stdout.write("usage: check-durable-docs [-h] [--json]\n\nCheck VCM durable project documentation contracts.\n");
+      process.exit(0);
+    } else {
+      process.stderr.write("usage: check-durable-docs [-h] [--json]\ncheck-durable-docs: error: unrecognized arguments: " + argument + "\n");
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+function repositoryRoot() {
+  const result = childProcess.spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  if (!result.error && result.status === 0 && result.stdout.trim()) {
+    return fs.realpathSync(result.stdout.trim());
+  }
+  return fs.realpathSync(process.cwd());
+}
+
+function relative(target, root) {
+  return path.relative(root, fs.realpathSync(target)).split(path.sep).join("/");
+}
+
+function readLines(target) {
+  return fs.readFileSync(target, "utf8").split(/\r\n|\n|\r/).filter((line, index, all) => index < all.length - 1 || line !== "");
+}
+
+function isFile(target) {
+  try {
+    return fs.statSync(target).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function markdownHeadings(lines, pattern) {
+  const headings = [];
+  let fenced = false;
+  lines.forEach((line, index) => {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      return;
+    }
+    if (fenced) {
+      return;
+    }
+    const match = pattern.exec(line);
+    if (match) {
+      headings.push({ index, match });
+    }
+  });
+  return headings;
+}
+
+function firstMatchLine(lines, pattern, start = 0, end = undefined) {
+  const stop = end === undefined ? lines.length : Math.min(end, lines.length);
+  for (let index = start; index < stop; index += 1) {
+    if (pattern.test(lines[index])) {
+      return index + 1;
+    }
+  }
+  return null;
+}
+
+function finding(code, file, line, message) {
+  return { code, path: file, line, message };
+}
+
+function checkKnownIssues(root, findings) {
+  const file = path.join(root, "docs/known-issues.md");
+  if (!isFile(file)) {
+    return;
+  }
+  const lines = readLines(file);
+  const headings = markdownHeadings(lines, /^##\s+(?:\[)?KI-(\d+)(?:\])?\b/i);
+  headings.forEach(({ index: start, match }, headingIndex) => {
+    const end = headingIndex + 1 < headings.length ? headings[headingIndex + 1].index : lines.length;
+    const issueId = "KI-" + match[1];
+    const fields = {};
+    for (const line of lines.slice(start + 1, end)) {
+      const fieldMatch = /^\s*-\s*([^:]+):\s*(.*)$/.exec(line);
+      if (fieldMatch) {
+        fields[fieldMatch[1].trim().toLowerCase()] = fieldMatch[2].trim();
+      }
+    }
+    const missing = KNOWN_ISSUE_FIELDS.filter((field) => !(field in fields));
+    if (missing.length > 0) {
+      findings.push(finding("DD_KI_FIELDS", relative(file, root), start + 1,
+        issueId + " is missing required current-state fields: " + missing.join(", ") + "."));
+    }
+    const status = (fields.status || "").toLowerCase();
+    if (status && !["open", "planned", "accepted"].includes(status)) {
+      findings.push(finding("DD_KI_STATUS", relative(file, root), start + 1,
+        issueId + " has non-current status '" + fields.status + "'. Remove terminal issues instead of retaining history."));
+    }
+    const resolvedLine = firstMatchLine(lines, /(?:\bRESOLVED\b|\bFIXED\b|\bCLOSED\b|\bOBSOLETE\b|nothing remains open)/i, start, end);
+    if (resolvedLine !== null) {
+      findings.push(finding("DD_KI_RESOLVED_HISTORY", relative(file, root), resolvedLine,
+        issueId + " retains resolved or terminal history. Rewrite the entry around only the current unresolved gap."));
+    }
+    const provenanceLine = firstMatchLine(
+      lines,
+      /\bROUND-?\d+\b|\b(?:reviewer|tester)[ -]?(?:confirmed|approved|proven)|\bcommit\s+`?[0-9a-f]{7,40}\b/i,
+      start,
+      end
+    );
+    if (provenanceLine !== null) {
+      findings.push(finding("DD_KI_TASK_HISTORY", relative(file, root), provenanceLine,
+        issueId + " contains task or validation provenance that belongs in Git, PR, or task evidence."));
+    }
+  });
+}
+
+function walkFiles(directory, accept, results = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(target, accept, results);
+    } else if (entry.isFile() && accept(entry.name)) {
+      results.push(target);
+    }
+  }
+  return results;
+}
+
+function checkActivePlans(root, findings) {
+  const plansRoot = path.join(root, "docs/plans");
+  try {
+    if (!fs.statSync(plansRoot).isDirectory()) {
+      return;
+    }
+  } catch {
+    return;
+  }
+  const terminalPattern = new RegExp("\\b(?:" + TERMINAL_PLAN_WORDS.join("|") + ")\\b", "i");
+  const statusPattern = /^\s*(?:>\s*)?(?:\*\*)?(?:status|stability)(?:\*\*)?\s*[:\-—]/i;
+  const closedDocPattern = /\b(?:plan|task|document|doc|phase|work)\b.{0,40}\b(?:is\s+)?(?:closed|complete|completed|shipped|delivered|done)\b/i;
+  for (const file of walkFiles(plansRoot, (name) => name.endsWith(".md")).sort()) {
+    const lines = readLines(file);
+    for (const [index, line] of lines.slice(0, 60).entries()) {
+      if ((statusPattern.test(line) && terminalPattern.test(line)) || (index < 15 && closedDocPattern.test(line))) {
+        findings.push(finding("DD_ACTIVE_PLAN_TERMINAL", relative(file, root), index + 1,
+          "Completed or terminal plans must leave the active plans collection; Git and PR history preserve execution history."));
+        break;
+      }
+    }
+  }
+}
+
+function architectureDocs(root) {
+  const paths = new Set();
+  const projectDoc = path.join(root, "docs/ARCHITECTURE.md");
+  if (isFile(projectDoc)) {
+    paths.add(projectDoc);
+  }
+  const visit = (directory) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (EXCLUDED_PARTS.has(entry.name)) {
+        continue;
+      }
+      const target = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        visit(target);
+      } else if (entry.isFile() && entry.name === "ARCHITECTURE.md") {
+        paths.add(target);
+      }
+    }
+  };
+  visit(root);
+  return [...paths].sort();
+}
+
+function checkArchitectureHistory(root, findings) {
+  const patterns = [
+    ["DD_ARCH_TASK_LABEL", /\bSCF-[A-Za-z0-9.-]+\b|\bROUND-?\d+\b/i, "task labels"],
+    ["DD_ARCH_COMMIT_HISTORY", /\bcommit\s+`?[0-9a-f]{7,40}\b/i, "commit history"],
+    ["DD_ARCH_VALIDATION_HISTORY", /\b(?:reviewer|tester).{0,40}(?:PASS|confirmed|approved|proven)\b/i, "role validation history"]
+  ];
+  for (const file of architectureDocs(root)) {
+    const lines = readLines(file);
+    for (const [code, pattern, label] of patterns) {
+      const line = firstMatchLine(lines, pattern);
+      if (line !== null) {
+        findings.push(finding(code, relative(file, root), line,
+          "Architecture documentation contains " + label + "; keep only current architecture and use Git, PR, or task evidence for history."));
+      }
+    }
+  }
+}
+
+function checkTestingHistory(root, findings) {
+  const file = path.join(root, "docs/TESTING.md");
+  if (!isFile(file)) {
+    return;
+  }
+  const lines = readLines(file);
+  const patterns = [
+    ["DD_TEST_TASK_HISTORY", /\bROUND-?\d+\b|\bcommit\s+`?[0-9a-f]{7,40}\b/i, "task or commit history"],
+    ["DD_TEST_VERDICT_HISTORY", /\b(?:reviewer|tester)[ -]?(?:confirmed|approved|proven)|\bL[0-4]\s+(?:PASS|FAIL)\b/i, "past validation verdicts"],
+    ["DD_TEST_LEGACY_OWNER", /\breviewer-owned\b|\brun by the reviewer\b/i, "legacy Reviewer ownership"]
+  ];
+  for (const [code, pattern, label] of patterns) {
+    const line = firstMatchLine(lines, pattern);
+    if (line !== null) {
+      findings.push(finding(code, relative(file, root), line,
+        "Testing documentation contains " + label + "; keep current strategy, runnable commands, case definitions, and current gaps only."));
+    }
+  }
+}
+
+function loadModuleIndex(root) {
+  const file = path.join(root, ".ai/generated/module-index.json");
+  if (!isFile(file)) {
+    return null;
+  }
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function checkGeneratedArchitectureFacts(root, findings) {
+  const index = loadModuleIndex(root);
+  if (index === null || !Array.isArray(index.layers)) {
+    return;
+  }
+  const layerCounts = new Map();
+  for (const layer of index.layers) {
+    if (!layer || typeof layer !== "object" || typeof layer.name !== "string" || !Array.isArray(layer.modules)) {
+      continue;
+    }
+    layerCounts.set(layer.name, layer.modules.length);
+    for (const module of layer.modules) {
+      if (!module || typeof module !== "object") {
+        continue;
+      }
+      const architectureDoc = module.architectureDoc;
+      if (typeof architectureDoc === "string" && architectureDoc && !isFile(path.join(root, architectureDoc))) {
+        findings.push(finding("DD_MODULE_ARCH_MISSING", architectureDoc, 1,
+          "Module index names a missing architecture document for module '" + (module.name ?? "unknown") + "'."));
+      }
+    }
+  }
+  const projectDoc = path.join(root, "docs/ARCHITECTURE.md");
+  if (!isFile(projectDoc)) {
+    return;
+  }
+  readLines(projectDoc).forEach((line, lineIndex) => {
+    const match = /^\|\s*`?([^`|]+)`?\s*\|\s*(\d+)\s*\|/.exec(line);
+    if (!match) {
+      return;
+    }
+    const name = match[1].trim();
+    if (!layerCounts.has(name)) {
+      return;
+    }
+    const documented = Number(match[2]);
+    const generated = layerCounts.get(name);
+    if (documented !== generated) {
+      findings.push(finding("DD_ARCH_GENERATED_COUNT", relative(projectDoc, root), lineIndex + 1,
+        "Layer '" + name + "' documents " + documented + " modules, but .ai/generated/module-index.json contains " + generated + "."));
+    }
+  });
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const root = repositoryRoot();
+  const findings = [];
+  checkKnownIssues(root, findings);
+  checkActivePlans(root, findings);
+  checkArchitectureHistory(root, findings);
+  checkTestingHistory(root, findings);
+  checkGeneratedArchitectureFacts(root, findings);
+  findings.sort((left, right) =>
+    left.path < right.path ? -1 : left.path > right.path ? 1
+      : left.line !== right.line ? left.line - right.line
+        : left.code < right.code ? -1 : left.code > right.code ? 1 : 0);
+  if (args.jsonOutput) {
+    process.stdout.write(JSON.stringify({ ok: findings.length === 0, findings }, null, 2) + "\n");
+  } else if (findings.length > 0) {
+    for (const item of findings) {
+      process.stdout.write(item.path + ":" + item.line + ": [" + item.code + "] " + item.message + "\n");
+    }
+    process.stdout.write("Durable docs audit failed with " + findings.length + " finding(s).\n");
+  } else {
+    process.stdout.write("Durable docs audit passed.\n");
+  }
+  return findings.length > 0 ? 1 : 0;
+}
+
+process.exitCode = main(process.argv.slice(2));