feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

2026-05-03 20:14:44 -05:00
parent 0443381aa0
commit be993429c1
59 changed files with 1898 additions and 385 deletions
@@ -0,0 +1,71 @@
+/**
+ * verify-docs-flow.test.mjs — unit tests for the docs-flow verifier (M2, S-206)
+ *
+ * Tests the exported functions from scripts/verify-docs-flow.mjs.
+ * Each test is structured as a RED → GREEN cycle: we first verify the function
+ * exists and behaves correctly; any structural violation surfaces as a clear
+ * test failure rather than a cryptic runtime error.
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "../..");
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Import the verifier lazily so missing-module errors surface as test
+ * failures rather than crashing the whole suite.
+ */
+async function loadVerifier() {
+  const verifierPath = path.join(REPO_ROOT, "scripts", "verify-docs-flow.mjs");
+  return import(verifierPath);
+}
+
+// ── S-206 acceptance checks ────────────────────────────────────────────────
+
+describe("verify-docs-flow.mjs", () => {
+  test("module exists and exports required functions", async () => {
+    const mod = await loadVerifier();
+    assert.equal(typeof mod.checkDocsIndexCoverage, "function",
+      "must export checkDocsIndexCoverage");
+    assert.equal(typeof mod.checkReviewerMatrixConsistency, "function",
+      "must export checkReviewerMatrixConsistency");
+    assert.equal(typeof mod.checkTelegramAgentCoverage, "function",
+      "must export checkTelegramAgentCoverage");
+    assert.equal(typeof mod.checkRepoPathsExist, "function",
+      "must export checkRepoPathsExist");
+  });
+
+  test("checkDocsIndexCoverage: every docs/*.md is linked from docs/README.md", async () => {
+    const { checkDocsIndexCoverage } = await loadVerifier();
+    const errors = await checkDocsIndexCoverage(REPO_ROOT);
+    assert.deepEqual(errors, [],
+      `docs/README.md coverage errors:\n${errors.join("\n")}`);
+  });
+
+  test("checkReviewerMatrixConsistency: reviewer tables consistent across canonical sources", async () => {
+    const { checkReviewerMatrixConsistency } = await loadVerifier();
+    const errors = await checkReviewerMatrixConsistency(REPO_ROOT);
+    assert.deepEqual(errors, [],
+      `Reviewer matrix inconsistency errors:\n${errors.join("\n")}`);
+  });
+
+  test("checkTelegramAgentCoverage: Telegram doc lists all agents with Pi helpers", async () => {
+    const { checkTelegramAgentCoverage } = await loadVerifier();
+    const errors = await checkTelegramAgentCoverage(REPO_ROOT);
+    assert.deepEqual(errors, [],
+      `Telegram coverage errors:\n${errors.join("\n")}`);
+  });
+
+  test("checkRepoPathsExist: all repo-relative paths in README.md and docs/ exist", async () => {
+    const { checkRepoPathsExist } = await loadVerifier();
+    const errors = await checkRepoPathsExist(REPO_ROOT);
+    assert.deepEqual(errors, [],
+      `Broken repo-relative path references:\n${errors.join("\n")}`);
+  });
+});