import fs from "node:fs/promises";
import path from "node:path";

import { describe, it } from "node:test";
import { expect } from "expect";

import { runInit } from "../../src/init/init.js";
import { runCheck } from "../../src/checks/check.js";
import type { TruthHealthScorecard } from "../../src/checks/scorecard.js";
import { writeTruthmarkConfig } from "../helpers/truthmark-config.js";
import { createTempRepo } from "../helpers/temp-repo.js";

const initializeRepo = async (rootDir: string): Promise<void> => {
  await writeTruthmarkConfig(rootDir);
  const configPath = path.join(rootDir, ".truthmark/config.yml");
  const configFile = await fs.readFile(configPath, "utf8");
  await fs.writeFile(
    configPath,
    configFile.replace(
      "version: 2\n",
      [
        "version: 2",
        "platforms:",
        "  - codex",
        "  - opencode",
        "  - claude-code",
        "  - github-copilot",
        "  - antigravity",
        "  - cursor",
        "",
      ].join("\n"),
    ),
  );
  await runInit(rootDir);
};

const scorecardFrom = (
  result: Awaited<ReturnType<typeof runCheck>>,
): TruthHealthScorecard => {
  const scorecard = result.data?.scorecard;
  expect(scorecard).toBeDefined();
  return scorecard as TruthHealthScorecard;
};

const scorecardDimension = (
  scorecard: TruthHealthScorecard,
  id: TruthHealthScorecard["dimensions"][number]["id"],
) => {
  const dimension = scorecard.dimensions.find(
    (candidate) => candidate.id === id,
  );
  expect(dimension).toBeDefined();
  return dimension!;
};

describe("runCheck", () => {
  it("returns no error diagnostics for a healthy initialized repository", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile("src/index.ts", "export const value = true;\n");

      const result = await runCheck(repo.rootDir);

      expect(result.command).toBe("check");
      expect(
        result.diagnostics.filter(
          (diagnostic) => diagnostic.severity === "error",
        ),
      ).toEqual([]);

      const scorecard = scorecardFrom(result);
      expect(scorecard.schemaVersion).toBe("truthmark-scorecard/v0");
      expect(scorecard.dimensions).toHaveLength(7);
      expect(scorecardDimension(scorecard, "routing-coverage").status).toBe(
        "pass",
      );
      expect(scorecardDimension(scorecard, "branch-freshness").status).toBe(
        "not-run",
      );
      expect(result.data).toHaveProperty("truthVisibility");
    } finally {
      await repo.cleanup();
    }
  });

  it("resolves the repository root when check runs from a subdirectory", async () => {
    const repo = await createTempRepo();

    try {
      await writeTruthmarkConfig(repo.rootDir);
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "src/auth/session.ts",
        "export const session = true;\n",
      );

      const result = await runCheck(path.join(repo.rootDir, "src"));

      expect(
        result.diagnostics.some(
          (diagnostic) => diagnostic.category === "config",
        ),
      ).toBe(false);
    } finally {
      await repo.cleanup();
    }
  });

  it("reports missing host skill package support files", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await fs.rm(
        `${repo.rootDir}/.agents/skills/truthmark-sync/support/procedure.md`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "generated-surface" &&
            diagnostic.file ===
              ".agents/skills/truthmark-sync/support/procedure.md" &&
            diagnostic.message.includes("is missing"),
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("reports stale host skill package entrypoints", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        ".agents/skills/truthmark-sync/SKILL.md",
        `${await repo.readFile(".agents/skills/truthmark-sync/SKILL.md")}
Local stale edit.
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "generated-surface" &&
            diagnostic.file === ".agents/skills/truthmark-sync/SKILL.md" &&
            diagnostic.message.includes("is stale"),
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("reports stale host skill package support files", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        ".claude/skills/truthmark-sync/support/procedure.md",
        `${await repo.readFile(
          ".claude/skills/truthmark-sync/support/procedure.md",
        )}
Local stale edit.
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "generated-surface" &&
            diagnostic.file ===
              ".claude/skills/truthmark-sync/support/procedure.md" &&
            diagnostic.message.includes("is stale"),
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("reports obsolete generated workflow surfaces from retired renderer packages", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        ".agents/skills/truthmark-preview/SKILL.md",
        "# Legacy preview entrypoint\n",
      );
      await repo.writeFile("GEMINI.md", "# Legacy Gemini instructions\n");
      await repo.writeFile(
        ".gemini/skills/truthmark-sync/SKILL.md",
        "# Legacy Gemini sync skill\n",
      );
      await repo.writeFile(
        ".gemini/agents/truth-doc-writer.md",
        "# Legacy Gemini doc writer\n",
      );
      await repo.writeFile(
        ".gemini/commands/truthmark/sync.toml",
        'description = "Legacy Gemini sync command"\n',
      );
      await repo.writeFile(
        ".agents/skills/truthmark-sync/helper-manifest.yml",
        "id: truthmark-sync\n",
      );
      await repo.writeFile(
        ".opencode/skills/truthmark-check/support/helper-policy.md",
        "Legacy helper policy.\n",
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.filter(
          (diagnostic) =>
            diagnostic.category === "generated-surface" &&
            diagnostic.file === ".agents/skills/truthmark-preview/SKILL.md" &&
            diagnostic.message.includes("obsolete"),
        ),
      ).toHaveLength(1);
      for (const retiredPath of [
        "GEMINI.md",
        ".gemini/skills/truthmark-sync/SKILL.md",
        ".gemini/agents/truth-doc-writer.md",
        ".gemini/commands/truthmark/sync.toml",
      ]) {
        const obsoleteDiagnostics = result.diagnostics.filter(
          (diagnostic) =>
            diagnostic.category === "generated-surface" &&
            diagnostic.file === retiredPath &&
            diagnostic.message.includes("obsolete"),
        );
        expect(obsoleteDiagnostics).toHaveLength(1);
      }
      expect(
        result.diagnostics.filter(
          (diagnostic) =>
            diagnostic.category === "generated-surface" &&
            diagnostic.file ===
              ".agents/skills/truthmark-sync/helper-manifest.yml" &&
            diagnostic.message.includes("obsolete"),
        ),
      ).toHaveLength(1);
      expect(
        result.diagnostics.filter(
          (diagnostic) =>
            diagnostic.category === "generated-surface" &&
            diagnostic.file ===
              ".opencode/skills/truthmark-check/support/helper-policy.md" &&
            diagnostic.message.includes("obsolete"),
        ),
      ).toHaveLength(1);
    } finally {
      await repo.cleanup();
    }
  });

  it("returns links diagnostics for broken internal markdown links", async () => {
    const repo = await createTempRepo();

    try {
      await writeTruthmarkConfig(repo.rootDir);
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/engineering/repository/bootstrap-routing.md",
        `${await repo.readFile("docs/truthmark/engineering/repository/bootstrap-routing.md")}\nSee [Missing](docs/missing.md).\n`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) => diagnostic.category === "links",
        ),
      ).toBe(true);
      expect(
        scorecardDimension(scorecardFrom(result), "truth-doc-structure").status,
      ).toBe("fail");
    } finally {
      await repo.cleanup();
    }
  });

  it("returns links diagnostics instead of accepting links that escape the repo", async () => {
    const repo = await createTempRepo();

    try {
      await writeTruthmarkConfig(repo.rootDir);
      await initializeRepo(repo.rootDir);
      await fs.writeFile(
        path.resolve(repo.rootDir, "..", "truthmark-outside-link.md"),
        "# Outside Link\n",
        "utf8",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/repository/bootstrap-routing.md",
        `${await repo.readFile("docs/truthmark/engineering/repository/bootstrap-routing.md")}\nSee [Outside](../truthmark-outside-link.md).\n`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "links" &&
            diagnostic.file ===
              "docs/truthmark/engineering/repository/bootstrap-routing.md",
        ),
      ).toBe(true);
    } finally {
      await fs.rm(
        path.resolve(repo.rootDir, "..", "truthmark-outside-link.md"),
        {
          force: true,
        },
      );
      await repo.cleanup();
    }
  });

  it("returns links diagnostics for symlink targets that resolve outside the repo", async () => {
    const repo = await createTempRepo();

    try {
      await writeTruthmarkConfig(repo.rootDir);
      await initializeRepo(repo.rootDir);
      await fs.writeFile(
        path.resolve(repo.rootDir, "..", "truthmark-symlink-link-target.md"),
        "# Outside Link\n",
        "utf8",
      );
      await fs.mkdir(path.resolve(repo.rootDir, "docs"), { recursive: true });
      await fs.symlink(
        path.resolve(repo.rootDir, "..", "truthmark-symlink-link-target.md"),
        path.resolve(repo.rootDir, "docs", "linked-outside.md"),
      );
      await repo.writeFile(
        "docs/truthmark/engineering/repository/bootstrap-routing.md",
        `${await repo.readFile("docs/truthmark/engineering/repository/bootstrap-routing.md")}\nSee [Outside](docs/linked-outside.md).\n`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "links" &&
            diagnostic.file ===
              "docs/truthmark/engineering/repository/bootstrap-routing.md",
        ),
      ).toBe(true);
    } finally {
      await fs.rm(
        path.resolve(repo.rootDir, "..", "truthmark-symlink-link-target.md"),
        {
          force: true,
        },
      );
      await repo.cleanup();
    }
  });

  it("returns authority errors for missing literal authority files", async () => {
    const repo = await createTempRepo();

    try {
      await writeTruthmarkConfig(repo.rootDir);
      await initializeRepo(repo.rootDir);
      await fs.rm(`${repo.rootDir}/docs/truthmark/routes/areas.md`);

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "authority" &&
            diagnostic.severity === "error",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("returns config diagnostics instead of loading legacy authority entries that escape the repo", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await fs.writeFile(
        path.resolve(repo.rootDir, "..", "truthmark-outside-authority.md"),
        "# Outside Authority\n",
        "utf8",
      );
      await repo.writeFile(
        ".truthmark/config.yml",
        `version: 1
authority:
  - ../truthmark-outside-authority.md
  - ../truthmark-outside-*.md
instruction_targets:
  - AGENTS.md
frontmatter:
  required: []
  recommended:
    - status
ignore: []
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "config" &&
            diagnostic.severity === "error" &&
            diagnostic.message.includes("Unsupported Truthmark config shape"),
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) => diagnostic.category === "authority",
        ),
      ).toBe(false);

      const scorecard = scorecardFrom(result);
      expect(scorecardDimension(scorecard, "routing-coverage").status).toBe(
        "fail",
      );
      expect(scorecardDimension(scorecard, "branch-freshness").status).toBe(
        "not-run",
      );
    } finally {
      await fs.rm(
        path.resolve(repo.rootDir, "..", "truthmark-outside-authority.md"),
        {
          force: true,
        },
      );
      await repo.cleanup();
    }
  });

  it("returns config diagnostics for legacy symlinked authority docs", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await fs.writeFile(
        path.resolve(
          repo.rootDir,
          "..",
          "truthmark-symlink-authority-target.md",
        ),
        "# Outside Authority\n",
        "utf8",
      );
      await fs.mkdir(path.resolve(repo.rootDir, "docs", "custom"), {
        recursive: true,
      });
      await fs.symlink(
        path.resolve(
          repo.rootDir,
          "..",
          "truthmark-symlink-authority-target.md",
        ),
        path.resolve(repo.rootDir, "docs", "custom", "outside-authority.md"),
      );
      await repo.writeFile(
        ".truthmark/config.yml",
        `version: 1
authority:
  - docs/custom/outside-authority.md
instruction_targets:
  - AGENTS.md
frontmatter:
  required: []
  recommended:
    - status
ignore: []
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "config" &&
            diagnostic.severity === "error" &&
            diagnostic.message.includes("Unsupported Truthmark config shape"),
        ),
      ).toBe(true);
    } finally {
      await fs.rm(
        path.resolve(
          repo.rootDir,
          "..",
          "truthmark-symlink-authority-target.md",
        ),
        {
          force: true,
        },
      );
      await repo.cleanup();
    }
  });

  it("rejects legacy optional authority globs instead of checking them", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        ".truthmark/config.yml",
        `version: 1
authority:
  - docs/truthmark/routes/areas.md
  - docs/truthmark/engineering/**/*.md
  - docs/optional/**/*.md
instruction_targets:
  - AGENTS.md
frontmatter:
  required: []
  recommended: []
ignore: []
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "config" &&
            diagnostic.severity === "error" &&
            diagnostic.message.includes("Unsupported Truthmark config shape"),
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) => diagnostic.category === "authority",
        ),
      ).toBe(false);
    } finally {
      await repo.cleanup();
    }
  });

  it("returns area-index diagnostics for malformed areas and coverage diagnostics for unmapped code", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "src/auth/session.ts",
        "export const session = true;\n",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/authentication.md",
        "---\nstatus: active\n---\n\n# Authentication\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Authentication

Truth documents:
- docs/truthmark/engineering/authentication.md
`,
      );

      const malformedResult = await runCheck(repo.rootDir);

      expect(
        malformedResult.diagnostics.some(
          (diagnostic) => diagnostic.category === "area-index",
        ),
      ).toBe(true);

      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Authentication

Truth documents:
- docs/truthmark/engineering/authentication.md

Code surface:
- src/billing/**

Update truth when:
- authentication behavior changes
`,
      );

      const weakResult = await runCheck(repo.rootDir);

      expect(
        weakResult.diagnostics.some(
          (diagnostic) => diagnostic.category === "coverage",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("reports coverage diagnostics for unmapped Go, Python, C#, and Java code", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/engineering/platform.md",
        "---\nstatus: active\n---\n\n# Platform\n",
      );
      await repo.writeFile(
        "cmd/server/main.go",
        "package main\n\nfunc main() {}\n",
      );
      await repo.writeFile("scripts/task.py", "print('task')\n");
      await repo.writeFile(
        "src/App/Program.cs",
        "namespace App;\n\npublic class Program {}\n",
      );
      await repo.writeFile(
        "src/main/java/com/example/App.java",
        "package com.example;\n\npublic class App {}\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Platform

Truth documents:
- docs/truthmark/engineering/platform.md

Code surface:
- web/**

Update truth when:
- platform behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);
      const coverageFiles = result.diagnostics
        .filter((diagnostic) => diagnostic.category === "coverage")
        .map((diagnostic) => diagnostic.file);

      expect(coverageFiles).toEqual(
        expect.arrayContaining([
          "cmd/server/main.go",
          "scripts/task.py",
          "src/App/Program.cs",
          "src/main/java/com/example/App.java",
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("reports coverage diagnostics for unmapped IaC, API schema, frontend, workflow, and monorepo code", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/engineering/platform.md",
        "---\nstatus: active\n---\n\n# Platform\n",
      );
      await repo.writeFile(
        "infra/main.tf",
        'resource "null_resource" "example" {}\n',
      );
      await repo.writeFile(
        "k8s/deployment.yaml",
        "apiVersion: apps/v1\nkind: Deployment\n",
      );
      await repo.writeFile(
        "api/openapi.yaml",
        "openapi: 3.1.0\ninfo:\n  title: API\n",
      );
      await repo.writeFile("schema/user.graphql", "type User { id: ID! }\n");
      await repo.writeFile(
        "proto/user.proto",
        'syntax = "proto3";\nmessage User {}\n',
      );
      await repo.writeFile(
        "frontend/components/Login.tsx",
        "export const Login = () => null;\n",
      );
      await repo.writeFile(
        ".github/workflows/ci.yml",
        "name: CI\non: [push]\n",
      );
      await repo.writeFile(
        "apps/web/src/App.tsx",
        "export const App = () => null;\n",
      );
      await repo.writeFile(
        "packages/auth/src/session.ts",
        "export const session = true;\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Platform

Truth documents:
- docs/truthmark/engineering/platform.md

Code surface:
- src/**

Update truth when:
- platform behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);
      const coverageFiles = result.diagnostics
        .filter((diagnostic) => diagnostic.category === "coverage")
        .map((diagnostic) => diagnostic.file);

      expect(coverageFiles).toEqual(
        expect.arrayContaining([
          "infra/main.tf",
          "k8s/deployment.yaml",
          "api/openapi.yaml",
          "schema/user.graphql",
          "proto/user.proto",
          "frontend/components/Login.tsx",
          ".github/workflows/ci.yml",
          "apps/web/src/App.tsx",
          "packages/auth/src/session.ts",
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("uses delegated route files when checking coverage", async () => {
    const repo = await createTempRepo();

    try {
      await repo.writeFile(
        ".truthmark/config.yml",
        `version: 2
truthmark:
  workspace: docs/truthmark
  generated:
    portal:
      enabled: false
frontmatter:
  required: []
  recommended: []
ignore: []
`,
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Payments

Area files:
- docs/truthmark/routes/areas/payments.md

Code surface:
- services/payments/**

Update truth when:
- payment behavior changes
`,
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas/payments.md",
        `# Payments Areas

## Checkout

Truth documents:
- docs/truthmark/engineering/payments/checkout.md

Code surface:
- services/payments/checkout/**

Update truth when:
- checkout behavior changes
`,
      );
      await repo.writeFile(
        "docs/truthmark/engineering/payments/checkout.md",
        "# Checkout\n",
      );
      await repo.writeFile(
        "services/payments/checkout/handler.ts",
        "export const handler = () => 'ok';\n",
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "config" && diagnostic.severity === "error",
        ),
      ).toBe(false);
      expect(result.diagnostics).not.toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            category: "coverage",
            file: "services/payments/checkout/handler.ts",
          }),
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("reports stale generated workflow surfaces by comparing rendered content", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        ".agents/skills/truthmark-sync/SKILL.md",
        `${(
          await repo.readFile(".agents/skills/truthmark-sync/SKILL.md")
        ).replace(
          "Truthmark-managed generated file.",
          "Locally edited generated file.",
        )}\n`,
      );
      const result = await runCheck(repo.rootDir);

      expect(result.diagnostics).toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            category: "generated-surface",
            severity: "review",
            file: ".agents/skills/truthmark-sync/SKILL.md",
            message: expect.stringContaining("stale"),
          }),
        ]),
      );
      expect(result.diagnostics).not.toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            category: "generated-surface",
            file: ".agents/skills/truthmark-sync/SKILL.md",
            message: expect.stringContaining("version"),
          }),
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("reports stale Claude Code generated skill surfaces", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        ".claude/skills/truthmark-sync/SKILL.md",
        `${await repo.readFile(".claude/skills/truthmark-sync/SKILL.md")}\nmanual drift\n`,
      );

      const result = await runCheck(repo.rootDir);

      expect(result.diagnostics).toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            category: "generated-surface",
            severity: "review",
            file: ".claude/skills/truthmark-sync/SKILL.md",
            message: expect.stringContaining("stale"),
          }),
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("reports stale GitHub Copilot generated prompt surfaces", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        ".github/prompts/truthmark-sync.prompt.md",
        `${await repo.readFile(".github/prompts/truthmark-sync.prompt.md")}\nmanual drift\n`,
      );

      const result = await runCheck(repo.rootDir);

      expect(result.diagnostics).toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            category: "generated-surface",
            severity: "review",
            file: ".github/prompts/truthmark-sync.prompt.md",
            message: expect.stringContaining("stale"),
          }),
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("ignores manual version notes outside managed instruction blocks", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "AGENTS.md",
        `${await repo.readFile("AGENTS.md")}\n\nManual notes:\n- Keep legacy host bridge pinned at version: "0.9.0"\n`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.filter(
          (diagnostic) =>
            diagnostic.category === "generated-surface" &&
            diagnostic.file === "AGENTS.md",
        ),
      ).toEqual([]);
    } finally {
      await repo.cleanup();
    }
  });

  it("reports stale generated Cursor skill surfaces when configured", async () => {
    const repo = await createTempRepo();

    try {
      await repo.writeFile(
        ".truthmark/config.yml",
        `version: 2
platforms:
  - cursor
truthmark:
  workspace: docs/truthmark
  generated:
    portal:
      enabled: false
instruction_targets:
  - AGENTS.md
frontmatter:
  required: []
  recommended: []
ignore: []
`,
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        "# Truthmark Areas\n",
      );
      await runInit(repo.rootDir);
      await repo.writeFile(
        ".cursor/skills/truthmark-sync/SKILL.md",
        `${await repo.readFile(".cursor/skills/truthmark-sync/SKILL.md")}\n# stale\n`,
      );

      const result = await runCheck(repo.rootDir);

      expect(result.diagnostics).toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            category: "generated-surface",
            severity: "review",
            file: ".cursor/skills/truthmark-sync/SKILL.md",
            message: expect.stringContaining("stale"),
          }),
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("returns truth visibility quality metrics in JSON data", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "apps/web/src/unmapped.ts",
        "export const unmapped = true;\n",
      );
      const result = await runCheck(repo.rootDir);

      expect(result.data?.truthVisibility).toEqual(
        expect.objectContaining({
          routePrecision: expect.objectContaining({
            leafAreaCount: expect.any(Number),
            broadAreaCount: expect.any(Number),
          }),
          unmappedSurfaceCount: expect.any(Number),
          staleGeneratedSurfaceCount: expect.any(Number),
          syncCompletenessIssueCount: expect.any(Number),
          topologyPressureCount: expect.any(Number),
        }),
      );
      expect(
        (
          result.data?.truthVisibility as {
            unmappedSurfaceCount?: number;
          }
        ).unmappedSurfaceCount,
      ).toBeGreaterThan(0);
    } finally {
      await repo.cleanup();
    }
  });

  it("returns area-index diagnostics for missing truth documents referenced by areas", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Authentication

Truth documents:
- docs/truthmark/engineering/missing-authentication.md

Code surface:
- src/auth/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "area-index" &&
            diagnostic.message.includes("missing-authentication.md"),
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("returns area-index diagnostics for unmatched code surface globs", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Authentication

Truth documents:
- docs/truthmark/engineering/authentication.md

Code surface:
- src/typo/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "area-index" &&
            diagnostic.file === "src/typo/**",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("keeps valid code-surface entries active when a sibling code-surface glob is stale", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "src/auth/session.ts",
        "export const session = true;\n",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/authentication.md",
        "---\nstatus: active\n---\n\n# Authentication\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Authentication

Truth documents:
- docs/truthmark/engineering/authentication.md

Code surface:
- src/auth/**
- src/stale/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "area-index" &&
            diagnostic.file === "src/stale/**",
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "coverage" &&
            diagnostic.file === "src/auth/session.ts",
        ),
      ).toBe(false);
    } finally {
      await repo.cleanup();
    }
  });

  it("reports missing recommended frontmatter as review and missing required frontmatter as error", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/engineering/authentication.md",
        "# Authentication\n",
      );

      const recommendedResult = await runCheck(repo.rootDir);

      expect(
        recommendedResult.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "frontmatter" &&
            diagnostic.severity === "review",
        ),
      ).toBe(true);

      await repo.writeFile(
        ".truthmark/config.yml",
        `version: 2
truthmark:
  workspace: docs/truthmark
  generated:
    portal:
      enabled: false
instruction_targets:
  - AGENTS.md
frontmatter:
  required:
    - status
  recommended: []
ignore: []
`,
      );

      const requiredResult = await runCheck(repo.rootDir);

      expect(
        requiredResult.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "frontmatter" &&
            diagnostic.severity === "error",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("runs frontmatter and link checks across routed truth docs that are outside authority globs", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/custom/auth-guidance.md",
        "# Auth Guidance\n\nSee [Missing](missing.md).\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Authentication

Truth documents:
- docs/custom/auth-guidance.md

Code surface:
- src/auth/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "frontmatter" &&
            diagnostic.file === "docs/custom/auth-guidance.md",
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "links" &&
            diagnostic.file === "docs/custom/auth-guidance.md",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("returns diagnostics instead of throwing when a routed markdown doc has invalid frontmatter", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/custom/broken-frontmatter.md",
        "---\nstatus: [broken\n---\n# Broken\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Custom

Truth documents:
- docs/custom/broken-frontmatter.md

Code surface:
- src/custom/**

Update truth when:
- custom behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "frontmatter" &&
            diagnostic.severity === "error" &&
            diagnostic.file === "docs/custom/broken-frontmatter.md",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("still checks valid routed docs when another area is malformed", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/custom/auth-guidance.md",
        "# Auth Guidance\n\nSee [Missing](missing.md).\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Broken Area

Truth documents:
- docs/truthmark/engineering/authentication.md

## Valid Area

Truth documents:
- docs/custom/auth-guidance.md

Code surface:
- src/auth/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) => diagnostic.category === "area-index",
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "links" &&
            diagnostic.file === "docs/custom/auth-guidance.md",
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "frontmatter" &&
            diagnostic.file === "docs/custom/auth-guidance.md",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("returns diagnostics instead of throwing when an area truth document path escapes the repo", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Unsafe Area

Truth documents:
- ../outside.md

Code surface:
- src/auth/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "area-index" &&
            diagnostic.file === "../outside.md",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("returns area-index diagnostics for symlinked truth docs that resolve outside the repo", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await fs.writeFile(
        path.resolve(repo.rootDir, "..", "truthmark-symlink-area-target.md"),
        "---\nstatus: active\n---\n\n# Outside Area Doc\n",
        "utf8",
      );
      await fs.mkdir(path.resolve(repo.rootDir, "docs", "custom"), {
        recursive: true,
      });
      await fs.symlink(
        path.resolve(repo.rootDir, "..", "truthmark-symlink-area-target.md"),
        path.resolve(repo.rootDir, "docs", "custom", "outside-area-doc.md"),
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Unsafe Area

Truth documents:
- docs/custom/outside-area-doc.md

Code surface:
- src/auth/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "area-index" &&
            diagnostic.file === "docs/custom/outside-area-doc.md",
        ),
      ).toBe(true);
    } finally {
      await fs.rm(
        path.resolve(repo.rootDir, "..", "truthmark-symlink-area-target.md"),
        {
          force: true,
        },
      );
      await repo.cleanup();
    }
  });

  it("does not report missing product links for engineering-only route areas", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/engineering/contracts/internal-cache.md",
        "# Internal Cache\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Internal Cache

Truth documents:
\`\`\`yaml
truth_documents:
  - path: docs/truthmark/engineering/contracts/internal-cache.md
    kind: engineering-contract
\`\`\`

Code surface:
- src/cache/**

Update truth when:
- internal cache contracts change
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.filter(
          (diagnostic) =>
            diagnostic.category === "traceability" &&
            diagnostic.severity === "review" &&
            diagnostic.file ===
              "docs/truthmark/engineering/contracts/internal-cache.md" &&
            diagnostic.message.includes(
              "User-visible engineering truth document",
            ),
        ),
      ).toEqual([]);
    } finally {
      await repo.cleanup();
    }
  });

  it("reports missing product links when an engineering doc shares an area with product truth", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/product/payments/checkout.md",
        "# Checkout Capability\n",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/behaviors/checkout.md",
        "# Checkout Behavior\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Checkout

Truth documents:
\`\`\`yaml
truth_documents:
  - path: docs/truthmark/product/payments/checkout.md
    kind: product-capability
  - path: docs/truthmark/engineering/behaviors/checkout.md
    kind: engineering-behavior
\`\`\`

Code surface:
- src/checkout/**

Update truth when:
- checkout behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(result.diagnostics).toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            category: "traceability",
            severity: "review",
            file: "docs/truthmark/engineering/behaviors/checkout.md",
            message: expect.stringContaining(
              "User-visible engineering truth document",
            ),
          }),
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("allows product realized_by links without reciprocal engineering realizes links", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/product/payments/checkout.md",
        "# Checkout Capability\n",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/behaviors/checkout.md",
        "# Checkout Behavior\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Checkout

Truth documents:
\`\`\`yaml
truth_documents:
  - path: docs/truthmark/product/payments/checkout.md
    kind: product-capability
    realized_by:
      - docs/truthmark/engineering/behaviors/checkout.md
  - path: docs/truthmark/engineering/behaviors/checkout.md
    kind: engineering-behavior
\`\`\`

Code surface:
- src/checkout/**

Update truth when:
- checkout behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);
      const traceabilityErrors = result.diagnostics.filter(
        (diagnostic) =>
          diagnostic.category === "traceability" &&
          diagnostic.severity === "error" &&
          diagnostic.file === "docs/truthmark/product/payments/checkout.md",
      );

      expect(traceabilityErrors).toEqual([]);
    } finally {
      await repo.cleanup();
    }
  });

  it("allows engineering realizes links without reciprocal product realized_by links", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/product/payments/checkout.md",
        "# Checkout Capability\n",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/behaviors/checkout.md",
        "# Checkout Behavior\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Checkout

Truth documents:
\`\`\`yaml
truth_documents:
  - path: docs/truthmark/product/payments/checkout.md
    kind: product-capability
  - path: docs/truthmark/engineering/behaviors/checkout.md
    kind: engineering-behavior
    realizes:
      - docs/truthmark/product/payments/checkout.md
\`\`\`

Code surface:
- src/checkout/**

Update truth when:
- checkout behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);
      const traceabilityErrors = result.diagnostics.filter(
        (diagnostic) =>
          diagnostic.category === "traceability" &&
          diagnostic.severity === "error" &&
          diagnostic.file ===
            "docs/truthmark/engineering/behaviors/checkout.md",
      );

      expect(traceabilityErrors).toEqual([]);
    } finally {
      await repo.cleanup();
    }
  });

  it("merges duplicate route entries with divergent relationship metadata", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/product/payments/checkout.md",
        "# Checkout Capability\n",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/behaviors/checkout.md",
        "# Checkout Behavior\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Checkout

Truth documents:
\`\`\`yaml
truth_documents:
  - path: docs/truthmark/product/payments/checkout.md
    kind: product-capability
    realized_by:
      - docs/truthmark/engineering/behaviors/checkout.md
  - path: docs/truthmark/engineering/behaviors/checkout.md
    kind: engineering-behavior
    realizes:
      - docs/truthmark/product/payments/checkout.md
  - path: docs/truthmark/engineering/behaviors/checkout.md
    kind: engineering-behavior
\`\`\`

Code surface:
- src/checkout/**

Update truth when:
- checkout behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);
      const duplicateDiagnostics = result.diagnostics.filter(
        (diagnostic) =>
          diagnostic.category === "area-index" &&
          diagnostic.severity === "error" &&
          diagnostic.file ===
            "docs/truthmark/engineering/behaviors/checkout.md" &&
          diagnostic.message.includes("conflicting relationship metadata"),
      );
      const traceabilityErrors = result.diagnostics.filter(
        (diagnostic) =>
          diagnostic.category === "traceability" &&
          diagnostic.severity === "error" &&
          diagnostic.file === "docs/truthmark/product/payments/checkout.md",
      );

      expect(duplicateDiagnostics).toEqual([]);
      expect(traceabilityErrors).toEqual([]);
    } finally {
      await repo.cleanup();
    }
  });

  it("merges duplicate route relationship metadata before validating targets", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/product/payments/checkout.md",
        "# Checkout Capability\n",
      );
      await repo.writeFile(
        "docs/truthmark/product/payments/refunds.md",
        "# Refunds Capability\n",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/behaviors/checkout.md",
        "# Checkout Behavior\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Checkout

Truth documents:
\`\`\`yaml
truth_documents:
  - path: docs/truthmark/product/payments/checkout.md
    kind: product-capability
    realized_by:
      - docs/truthmark/engineering/behaviors/checkout.md
  - path: docs/truthmark/product/payments/refunds.md
    kind: product-capability
    realized_by:
      - docs/truthmark/engineering/behaviors/checkout.md
  - path: docs/truthmark/engineering/behaviors/checkout.md
    kind: engineering-behavior
    realizes:
      - docs/truthmark/product/payments/checkout.md
  - path: docs/truthmark/engineering/behaviors/checkout.md
    kind: engineering-behavior
    realizes:
      - docs/truthmark/product/payments/refunds.md
\`\`\`

Code surface:
- src/checkout/**

Update truth when:
- checkout behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.filter(
          (diagnostic) =>
            diagnostic.category === "area-index" &&
            diagnostic.file ===
              "docs/truthmark/engineering/behaviors/checkout.md" &&
            diagnostic.message.includes("conflicting relationship metadata"),
        ),
      ).toEqual([]);
      expect(
        result.diagnostics.filter(
          (diagnostic) =>
            diagnostic.category === "traceability" &&
            diagnostic.severity === "error" &&
            diagnostic.file === "docs/truthmark/product/payments/refunds.md",
        ),
      ).toEqual([]);
    } finally {
      await repo.cleanup();
    }
  });

  it("propagates explicit truth kind metadata from glob routes to matched docs", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile("src/api.ts", "export const api = true;\n");
      await repo.writeFile(
        "docs/truthmark/engineering/api.md",
        `---
status: active
doc_type: behavior
truth_kind: engineering-behavior
last_reviewed: 2026-05-14
source_of_truth:
  - docs/truthmark/routes/areas.md
---

# API

## Scope

API truth.

## Current Implementation Behavior

API behavior.

## Engineering Decisions

- Decision (2026-05-14): Test glob kind propagation.

## Rationale

This doc intentionally disagrees with the routed glob kind.
`,
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## API

Truth documents:
\`\`\`yaml
truth_documents:
  - path: docs/truthmark/engineering/**/*.md
    kind: engineering-contract
\`\`\`

Code surface:
- src/**

Update truth when:
- API behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(result.diagnostics).toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            category: "frontmatter",
            severity: "error",
            file: "docs/truthmark/engineering/api.md",
            message: expect.stringContaining(
              "routed truth kind engineering-contract",
            ),
          }),
        ]),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("returns diagnostics instead of throwing when an area truth document glob escapes the repo", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await fs.writeFile(
        path.resolve(repo.rootDir, "..", "truthmark-outside-shared.md"),
        "---\ntitle: Shared\nstatus: active\n---\n\n# Shared\n",
        "utf8",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Unsafe Area

Truth documents:
- ../truthmark-outside-*.md

Code surface:
- src/auth/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "area-index" &&
            diagnostic.file === "../truthmark-outside-shared.md",
        ),
      ).toBe(true);
    } finally {
      await fs.rm(
        path.resolve(repo.rootDir, "..", "truthmark-outside-shared.md"),
        {
          force: true,
        },
      );
      await repo.cleanup();
    }
  });

  it("still validates truth docs referenced by a malformed area", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/custom/malformed-area-doc.md",
        "# Custom Guidance\n\nSee [Missing](missing.md).\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Broken Area

Truth documents:
- docs/custom/malformed-area-doc.md
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) => diagnostic.category === "area-index",
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "frontmatter" &&
            diagnostic.file === "docs/custom/malformed-area-doc.md",
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "links" &&
            diagnostic.file === "docs/custom/malformed-area-doc.md",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("does not count an area with broken truth documents toward code coverage", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "src/auth/session.ts",
        "export const session = true;\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Broken Area

Truth documents:
- docs/truthmark/missing.md

Code surface:
- src/auth/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "coverage" &&
            diagnostic.file === "src/auth/session.ts",
        ),
      ).toBe(true);
    } finally {
      await repo.cleanup();
    }
  });

  it("keeps colliding area slugs from corrupting coverage state", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "src/auth/session.ts",
        "export const session = true;\n",
      );
      await repo.writeFile(
        "docs/truthmark/engineering/authentication.md",
        "---\nstatus: active\n---\n\n# Authentication\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Auth API

Truth documents:
- docs/truthmark/engineering/authentication.md

Code surface:
- src/auth/**

Update truth when:
- authentication behavior changes

## Auth/API

Truth documents:
- docs/truthmark/engineering/missing-authentication.md

Code surface:
- src/billing/**

Update truth when:
- billing behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "coverage" &&
            diagnostic.file === "src/auth/session.ts",
        ),
      ).toBe(false);
    } finally {
      await repo.cleanup();
    }
  });

  it("does not report coverage for files matched by ignore globs", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/engineering/authentication.md",
        "---\nstatus: active\n---\n\n# Authentication\n",
      );
      await repo.writeFile(
        "src/auth/session.ts",
        "export const session = true;\n",
      );
      await repo.writeFile(
        "src/generated/out.ts",
        "export const generated = true;\n",
      );
      await repo.writeFile(
        "src/unmapped/manual.ts",
        "export const manual = true;\n",
      );
      await repo.writeFile(
        ".truthmark/config.yml",
        `version: 2
truthmark:
  workspace: docs/truthmark
  generated:
    portal:
      enabled: false
instruction_targets:
  - AGENTS.md
frontmatter:
  required: []
  recommended:
    - status
ignore:
  - src/generated/**
`,
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

  ## Authentication

  Truth documents:
  - docs/truthmark/engineering/authentication.md

  Code surface:
  - src/auth/**

  Update truth when:
  - authentication behavior changes
  `,
      );

      const result = await runCheck(repo.rootDir);
      const coverageFiles = result.diagnostics
        .filter((diagnostic) => diagnostic.category === "coverage")
        .map((diagnostic) => diagnostic.file);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "config" && diagnostic.severity === "error",
        ),
      ).toBe(false);
      expect(coverageFiles).toContain("src/unmapped/manual.ts");
      expect(coverageFiles).not.toContain("src/generated/out.ts");
    } finally {
      await repo.cleanup();
    }
  });

  it("reports unmapped functional code under an unknown root in coverage and scorecard output", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "backend/auth/session.ts",
        "export const session = true;\n",
      );

      const result = await runCheck(repo.rootDir);
      const coverageDiagnostics = result.diagnostics.filter(
        (diagnostic) => diagnostic.category === "coverage",
      );
      const scorecard = scorecardFrom(result);

      expect(coverageDiagnostics).toEqual([
        expect.objectContaining({
          category: "coverage",
          severity: "review",
          message:
            "Code file backend/auth/session.ts is not covered by any Truthmark area mapping.",
          file: "backend/auth/session.ts",
        }),
      ]);
      expect(
        (result.data?.truthVisibility as { unmappedSurfaceCount: number })
          .unmappedSurfaceCount,
      ).toBe(1);
      expect(scorecardDimension(scorecard, "routing-coverage").status).toBe(
        "warn",
      );
      expect(scorecardDimension(scorecard, "ownership-clarity").status).toBe(
        "warn",
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("recognizes a mapped functional source file under an unknown root", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile("engine/runtime/main.rs", "fn main() {}\n");
      await repo.writeFile(
        "docs/truthmark/engineering/runtime.md",
        "---\nstatus: active\n---\n\n# Runtime\n",
      );
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Runtime

Truth documents:
- docs/truthmark/engineering/runtime.md

Code surface:
- engine/runtime/**

Update truth when:
- runtime behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(result.diagnostics).not.toContainEqual(
        expect.objectContaining({
          category: "coverage",
          file: "engine/runtime/main.rs",
        }),
      );
    } finally {
      await repo.cleanup();
    }
  });

  it("limits coverage diagnostics to ordinary non-test functional code", async () => {
    const repo = await createTempRepo();

    try {
      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "backend/service.ts",
        "export const service = true;\n",
      );
      await repo.writeFile("README.md", "# Read me\n");
      await repo.writeFile("assets/logo.png", "not a source file\n");
      await repo.writeFile("tests/service.test.ts", "void 0;\n");
      await repo.writeFile("backend/service.test.ts", "void 0;\n");
      await repo.writeFile("backend/service.spec.ts", "void 0;\n");

      const result = await runCheck(repo.rootDir);
      const coverageFiles = result.diagnostics
        .filter((diagnostic) => diagnostic.category === "coverage")
        .map((diagnostic) => diagnostic.file);

      expect(coverageFiles).toEqual(["backend/service.ts"]);
    } finally {
      await repo.cleanup();
    }
  });

  it("limits coverage diagnostics for mixed-surface repositories to ordinary functional source only", async () => {
    const repo = await createTempRepo();

    try {
      await writeTruthmarkConfig(repo.rootDir);
      const configPath = path.join(repo.rootDir, ".truthmark/config.yml");
      const configFile = await fs.readFile(configPath, "utf8");
      await fs.writeFile(
        configPath,
        configFile.replace(
          "version: 2\n",
          [
            "version: 2",
            "platforms:",
            "  - codex",
            "",
          ].join("\n"),
        ),
      );
      await runInit(repo.rootDir);

      await repo.writeFile("backend/service.ts", "export const service = true;\n");
      await repo.writeFile("README.md", "# Read me\n");
      await repo.writeFile("assets/logo.png", "pretend-png\n");
      await repo.writeFile("tests/service.test.ts", "void 0;\n");
      await repo.writeFile("backend/service.spec.ts", "void 0;\n");
      await repo.writeFile("backend/service.test.ts", "void 0;\n");
      await repo.writeFile("docs/truthmark/engineering/overview.md", "# Overview\n");
      await repo.writeFile(
        "tests/nested/nested.unit.spec.ts",
        "void 0;\n",
      );

      const result = await runCheck(repo.rootDir);
      const coverageFiles = result.diagnostics
        .filter((diagnostic) => diagnostic.category === "coverage")
        .map((diagnostic) => diagnostic.file);

      expect(coverageFiles).toEqual(["backend/service.ts"]);
    } finally {
      await repo.cleanup();
    }
  });

  it("does not treat symlinked source directories outside the repo as live code coverage", async () => {
    const repo = await createTempRepo();

    try {
      const outsideDir = path.resolve(
        repo.rootDir,
        "..",
        "truthmark-coverage-outside-dir",
      );

      await initializeRepo(repo.rootDir);
      await repo.writeFile(
        "docs/truthmark/engineering/authentication.md",
        "---\nstatus: active\n---\n\n# Authentication\n",
      );
      await fs.mkdir(outsideDir, { recursive: true });
      await fs.writeFile(
        path.join(outsideDir, "outside.ts"),
        "export const outside = true;\n",
        "utf8",
      );
      await fs.mkdir(path.join(repo.rootDir, "src"), { recursive: true });
      await fs.symlink(outsideDir, path.join(repo.rootDir, "src", "external"));
      await repo.writeFile(
        "docs/truthmark/routes/areas.md",
        `# Truthmark Areas

## Authentication

Truth documents:
- docs/truthmark/engineering/authentication.md

Code surface:
- src/external/**

Update truth when:
- authentication behavior changes
`,
      );

      const result = await runCheck(repo.rootDir);

      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "area-index" &&
            diagnostic.file === "src/external/**",
        ),
      ).toBe(true);
      expect(
        result.diagnostics.some(
          (diagnostic) =>
            diagnostic.category === "coverage" &&
            diagnostic.file === "src/external/outside.ts",
        ),
      ).toBe(false);
    } finally {
      await fs.rm(
        path.resolve(repo.rootDir, "..", "truthmark-coverage-outside-dir"),
        {
          force: true,
          recursive: true,
        },
      );
      await repo.cleanup();
    }
  });
});