HiveGrid-Wireframes/hivegrid-cloud/scripts/verify-docs-inventory-baseline.test.mjs

import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it } from "vitest";

import {
  docsInventoryInventoryScanRoots,
  docsInventoryStatusAuthorityContracts,
  failureCount,
  gates,
  renderReport,
  reportPath,
  runDocsInventoryInventory,
  runDocsInventoryStatusAuthorityGuard,
} from "./verify-docs-inventory-baseline.mjs";

const focusedSmokeTargets = ["scripts/check-api-inventory.test.ts", "apps/web/app/application/featureManifests.test.ts"];

describe("Docs Inventory baseline runner configuration", () => {
  it("defines the required non-E2E gates and report path", () => {
    expect(reportPath).toMatch(/\.tc\/baselines\/docs-inventory\/baseline-health\.md$/);
    expect(gates.map((gate) => gate.id)).toEqual(["typecheck", "lint", "vitest-docsInventory-smoke", "docsInventory-status-authority-guard", "docsInventory-docs-inventory"]);
    expect(gates.some((gate) => gate.args?.some((arg) => /playwright|cypress|browser|e2e/i.test(arg)))).toBe(false);
    expect(docsInventoryInventoryScanRoots).toEqual(["docs/feature-inventory.md", "docs/env-access-inventory.md", "docs/deployment.md"]);
  });

  it("keeps focused smoke tests in the Vitest gate", () => {
    const vitestGate = gates.find((gate) => gate.id === "vitest-docsInventory-smoke");

    expect(vitestGate?.args).toEqual(["exec", "vitest", "run", ...focusedSmokeTargets]);
  });
});

describe("Docs Inventory baseline runner failure counting", () => {
  it("counts failed typecheck diagnostics conservatively", () => {
    expect(failureCount("typecheck", "src/a.ts(1,1): error TS2307: Cannot find module\nsrc/b.ts(2,2): error TS2322: Type mismatch", "", 1)).toBe(2);
    expect(failureCount("typecheck", "Build failed", "", 1)).toBe(1);
  });

  it("counts failed ESLint diagnostics conservatively", () => {
    expect(failureCount("lint", "✖ 4 problems (3 errors, 1 warning)", "", 1)).toBe(3);
    expect(failureCount("lint", "2 errors and 0 warnings", "", 1)).toBe(2);
    expect(failureCount("lint", "Lint crashed", "", 1)).toBe(1);
  });

  it("counts failed Vitest diagnostics conservatively", () => {
    expect(failureCount("vitest-docsInventory-smoke", "Tests 2 failed | 8 passed", "", 1)).toBe(2);
    expect(failureCount("vitest-docsInventory-smoke", "Test Files 1 failed | 2 passed", "", 1)).toBe(1);
    expect(failureCount("vitest-docsInventory-smoke", "Vitest crashed", "", 1)).toBe(1);
  });

  it("returns zero for clean exits and read-only inventory gates", () => {
    expect(failureCount("lint", "warning only", "", 0)).toBe(0);
    expect(failureCount("docsInventory-docs-inventory", "total matches: 12", "", 1)).toBe(0);
  });
});

describe("Docs Inventory status authority guard", () => {
  it("requires current-status routing markers on historical and canonical docs", async () => {
    const root = await mkdtemp(join(tmpdir(), "docsInventory-status-authority-"));

    for (const contract of docsInventoryStatusAuthorityContracts) {
      const absolutePath = join(root, contract.path);
      await mkdir(join(absolutePath, ".."), { recursive: true });
      await writeFile(absolutePath, contract.requiredMarkers.join("\n\n"), "utf8");
    }

    const guard = await runDocsInventoryStatusAuthorityGuard(root);

    expect(guard.checked).toEqual(docsInventoryStatusAuthorityContracts.map((contract) => contract.path));
    expect(guard.failures).toEqual([]);
  });

  it("fails when old handoff/status docs can look authoritative again", async () => {
    const root = await mkdtemp(join(tmpdir(), "docsInventory-status-authority-fail-"));
    await mkdir(join(root, "docs", "improvement-plan"), { recursive: true });
    await writeFile(join(root, "docs", "improvement-plan", "README.md"), "die jeweils neueste Session-Zusammenfassung", "utf8");

    const guard = await runDocsInventoryStatusAuthorityGuard(root);

    expect(guard.failures).toContain("docs/agent-entrypoints.md: missing status-authority-controlled document");
    expect(guard.failures).toContain('docs/improvement-plan/README.md: missing marker "Historical plan archive"');
    expect(guard.failures).toContain('docs/improvement-plan/README.md: forbidden stale marker "die jeweils neueste Session-Zusammenfassung"');
    expect(guard.failures).toContain("docs/improvement-plan/CURRENT-STATUS.md: missing status-authority-controlled document");
    expect(guard.failures).toContain("docs/improvement-plan/archive/handoffs/README.md: missing status-authority-controlled document");
  });
});

describe("Docs Inventory docs inventory scan", () => {
  it("scans configured docs, counts baseline terms, and ignores dependency and TC paths", async () => {
    const root = await mkdtemp(join(tmpdir(), "docsInventory-baseline-inventory-"));
    await mkdir(join(root, "docs"), { recursive: true });
    await mkdir(join(root, "docs", "node_modules", "ignored"), { recursive: true });
    await mkdir(join(root, "docs", ".tc"), { recursive: true });
    await mkdir(join(root, "docs", "generated"), { recursive: true });

    await writeFile(join(root, "docs", "feature-inventory.md"), "Feature manifest core plugin remove inventory", "utf8");
    await writeFile(join(root, "docs", "env-access-inventory.md"), "Environment secret DATABASE_URL REDIS_URL API_KEY TOKEN access required", "utf8");
    await writeFile(join(root, "docs", "deployment.md"), "Deploy Docker Coolify Gitea registry workflow CI production TODO", "utf8");
    await writeFile(join(root, "docs", "node_modules", "ignored", "ignored.md"), "feature secret deploy TODO", "utf8");
    await writeFile(join(root, "docs", ".tc", "ignored.md"), "feature secret deploy TODO", "utf8");
    await writeFile(join(root, "docs", "generated", "ignored.md"), "feature secret deploy TODO", "utf8");

    const inventory = await runDocsInventoryInventory(root);
    const allMatches = inventory.matches.join("\n");

    expect(inventory.roots).toEqual(["docs/feature-inventory.md", "docs/env-access-inventory.md", "docs/deployment.md"]);
    expect(inventory.missingRoots).toEqual([]);
    expect(inventory.filesScanned).toBe(3);
    expect(inventory.counts).toMatchObject({
      "feature-inventory-signal": 6,
      "env-access-signal": 7,
      "deployment-signal": 8,
      "risk-marker": 2,
    });
    expect(allMatches).toContain("docs/feature-inventory.md");
    expect(allMatches).toContain("docs/env-access-inventory.md");
    expect(allMatches).toContain("docs/deployment.md");
    expect(allMatches).not.toContain("node_modules/ignored/ignored.md");
    expect(allMatches).not.toContain(".tc/ignored.md");
    expect(allMatches).not.toContain("generated/ignored.md");
  });

  it("records absent docs roots without failing the read-only inventory gate", async () => {
    const root = await mkdtemp(join(tmpdir(), "docsInventory-baseline-missing-"));
    const inventory = await runDocsInventoryInventory(root);

    expect(inventory.roots).toEqual([]);
    expect(inventory.missingRoots).toEqual(docsInventoryInventoryScanRoots);
    expect(inventory.filesScanned).toBe(0);
    expect(inventory.totalMatches).toBe(0);
  });
});

describe("Docs Inventory report rendering", () => {
  it("renders gate metadata, fingerprints, and inventory counts", () => {
    const report = renderReport([
      { id: "typecheck", command: "pnpm run typecheck", exitCode: 2, durationMs: 1500, failureCount: 7, fingerprint: { hash: "abc123def456", excerpt: "error TS2322" } },
      {
        id: "docsInventory-docs-inventory",
        command: "read-only Docs Inventory docs inventory",
        exitCode: 0,
        durationMs: 42,
        failureCount: 0,
        inventory: {
          roots: ["docs/feature-inventory.md"],
          missingRoots: ["docs/deployment.md"],
          filesScanned: 1,
          counts: { "feature-inventory-signal": 1, "deployment-signal": 2 },
          totalMatches: 3,
          matches: [],
        },
        fingerprint: { hash: "fed456abc123", excerpt: "feature-inventory-signal: 1" },
      },
      {
        id: "docsInventory-status-authority-guard",
        command: "static Docs Inventory status authority guard",
        exitCode: 1,
        durationMs: 20,
        failureCount: 1,
        statusAuthorityGuard: {
          checked: ["docs/improvement-plan/README.md"],
          failures: ["docs/improvement-plan/README.md: missing marker"],
        },
        fingerprint: { hash: "abc456abc456", excerpt: "failures: 1" },
      },
    ]);

    expect(report).toContain("# Docs Inventory Baseline Health");
    expect(report).toContain("non-E2E baseline gates for Docs Inventory baseline");
    expect(report).toContain("feature, environment access, deployment, and risk markers");
    expect(report).toContain("## typecheck");
    expect(report).toContain("## docsInventory-docs-inventory");
    expect(report).toContain("- Exitcode: 2");
    expect(report).toContain("- Failure Count: 7");
    expect(report).toContain("- Output Fingerprint: abc123def456");
    expect(report).toContain("- Status Authority Docs Checked: docs/improvement-plan/README.md");
    expect(report).toContain("- Status Authority Guard Failures: 1");
    expect(report).toContain("- Inventory Roots: docs/feature-inventory.md");
    expect(report).toContain("- Missing Roots Skipped: docs/deployment.md");
    expect(report).toContain("  - feature-inventory-signal: 1");
    expect(report).toContain("- Total Inventory Matches: 3");
  });
});