docverity 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devesh Agarwal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# Docverity
+
+**Catch documentation that lies about your code.**
+
+Docverity reads your docs, extracts the concrete claims they make about your
+codebase, and checks each one against the actual source. When a documented flag
+gets renamed, a config default changes, or a referenced file is deleted, your
+docs silently start lying. Docverity turns that into a failing check, in CI,
+before your users hit it.
+
+Existing tools run the code blocks in your docs (`doctest`, `mdbook test`) or
+help you author and host docs. None of them verify that the *prose* still tells
+the truth about the code. That is the gap Docverity fills.
+
+## Two engines
+
+Docverity ships with two complementary engines:
+
+- **Reference checker** — deterministic, no API key, instant. Catches docs that
+  mention files, CLI flags, environment variables, or symbols that no longer
+  exist anywhere in the source.
+- **Claim verifier** — LLM-backed, catches prose-level semantic drift: "the
+  default timeout is 30s", "this returns a list", "set `FOO=bar` to enable X".
+  Runs when `ANTHROPIC_API_KEY` (or `ANTHROPIC_AUTH_TOKEN`) is set.
+
+Works free out of the box. Gets smarter with a key.
+
+## Install
+
+```bash
+npm install -g docverity
+```
+
+Or run without installing:
+
+```bash
+npx docverity
+```
+
+## Usage
+
+From your repo root:
+
+```bash
+docverity
+```
+
+By default it checks `README.md` and every `.md` file under `docs/`. Pass files
+explicitly to narrow the scope, and use `-C` to point at another root:
+
+```bash
+docverity -C path/to/repo
+```
+
+Skip the LLM engine for a fast, deterministic-only run:
+
+```bash
+docverity --no-llm
+```
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `--no-llm` | Deterministic checks only; no API calls. |
+| `--model <id>` | Model for the LLM engine (default `claude-opus-4-8`). |
+| `--fail-confidence <n>` | Minimum confidence (0..1) to fail the build on. Default `0.7`. |
+| `--strict` | Also fail on unverifiable claims. |
+| `--format <fmt>` | `pretty` (default), `json`, or `github`. |
+
+Docverity exits non-zero when it finds drift above the confidence threshold, so
+it fails CI the way a linter would.
+
+## In CI (GitHub Actions)
+
+```yaml
+name: docs
+on: [pull_request]
+jobs:
+  docverity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx docverity --format github
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+With `--format github`, drifted claims appear as inline annotations on the
+changed lines of the pull request.
+
+## Use it from an agent (MCP)
+
+Docverity ships an MCP server so a coding agent can check docs as a tool and fix
+drift in the same turn it changed the code. Add it to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "docverity": {
+      "command": "npx",
+      "args": ["docverity", "mcp"]
+    }
+  }
+}
+```
+
+This exposes one tool, `check_docs`, which returns each drifted claim with its
+file, line, the stale text, code evidence, a confidence score, and a suggested
+fix the agent can apply directly. It runs the deterministic engine by default
+(fast, free, no key); pass `llm: true` to also verify prose claims.
+
+A [`SKILL.md`](SKILL.md) is included so the agent knows when to reach for it
+(after editing code, before a release, when asked whether the docs are correct).
+
+## How it works
+
+1. **Extract** — parse each doc into atomic claims (a flag, a path, an env var,
+   a symbol, or a prose assertion).
+2. **Locate** — search the source tree (via ripgrep when available) for evidence
+   of each claim. Documentation files are excluded from evidence: a claim must
+   be backed by code, not by the docs restating it.
+3. **Verify** — the reference engine checks for hard evidence; the LLM engine
+   judges prose claims against the located evidence and returns
+   ok / drifted / unverifiable with a specific reason.
+4. **Report** — pretty output, machine-readable JSON, or GitHub annotations.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import path from "node:path";
+import kleur from "kleur";
+import { extractClaims } from "./extract.js";
+import { verifyReference } from "./verify-reference.js";
+import { verifyLlm } from "./verify-llm.js";
+import { hasApiKey } from "./llm.js";
+import { printReport, printGithubAnnotations, toJson, summarize } from "./report.js";
+import { discoverDocs } from "./discover.js";
+import { runMcpServer } from "./mcp.js";
+const program = new Command();
+program
+    .name("docverity")
+    .description("Catch documentation that lies about your code.")
+    .version("0.1.0");
+program
+    .command("check", { isDefault: true })
+    .description("Check docs for claims that no longer match the code.")
+    .argument("[docs...]", "doc files to check (default: README + docs/**/*.md)")
+    .option("-C, --root <dir>", "repo root", process.cwd())
+    .option("--no-llm", "skip the LLM claim verifier (deterministic checks only)")
+    .option("--model <id>", "model for the LLM engine", "claude-opus-4-8")
+    .option("--fail-confidence <n>", "min confidence to fail on (0..1)", "0.7")
+    .option("--strict", "also fail on unverifiable claims", false)
+    .option("--format <fmt>", "output format: pretty | json | github", "pretty")
+    .action(async (docs, rawOpts) => {
+    const root = path.resolve(rawOpts.root);
+    const docFiles = docs.length ? docs : discoverDocs(root);
+    if (!docFiles.length) {
+        console.error(kleur.yellow("No documentation files found."));
+        process.exit(0);
+    }
+    const useLlm = rawOpts.llm && hasApiKey();
+    if (rawOpts.llm && !hasApiKey() && rawOpts.format === "pretty") {
+        console.error(kleur.dim("No ANTHROPIC_API_KEY set — running deterministic checks only. Set a key to verify prose claims."));
+    }
+    const opts = {
+        root,
+        docFiles,
+        useLlm,
+        model: rawOpts.model,
+        failConfidence: Number(rawOpts.failConfidence),
+        strict: Boolean(rawOpts.strict),
+    };
+    const verdicts = [];
+    for (const doc of docFiles) {
+        const claims = extractClaims(root, doc);
+        verdicts.push(...(await verifyReference(root, claims)));
+        if (useLlm) {
+            try {
+                verdicts.push(...(await verifyLlm(root, doc, opts.model)));
+            }
+            catch (err) {
+                console.error(kleur.yellow(`LLM engine failed on ${doc}: ${err?.message ?? err}`));
+            }
+        }
+    }
+    let shouldFail;
+    if (rawOpts.format === "json") {
+        console.log(toJson(verdicts, opts));
+        shouldFail = summarize(verdicts, opts).failures.length > 0;
+    }
+    else if (rawOpts.format === "github") {
+        printGithubAnnotations(verdicts, opts);
+        shouldFail = summarize(verdicts, opts).failures.length > 0;
+    }
+    else {
+        shouldFail = printReport(verdicts, opts);
+    }
+    process.exit(shouldFail ? 1 : 0);
+});
+program
+    .command("mcp")
+    .description("Run as an MCP server (stdio) so agents can check docs as a tool.")
+    .action(async () => {
+    await runMcpServer();
+});
+program.parseAsync();

package/dist/discover.js

@@ -0,0 +1,27 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+/** Default doc discovery: README at root plus markdown under docs/. */
+export function discoverDocs(root) {
+    const found = [];
+    for (const name of ["README.md", "README.markdown", "readme.md"]) {
+        if (existsSync(path.join(root, name))) {
+            found.push(name);
+            break;
+        }
+    }
+    const docsDir = path.join(root, "docs");
+    if (existsSync(docsDir) && statSync(docsDir).isDirectory()) {
+        walkMarkdown(docsDir, root, found);
+    }
+    return found;
+}
+function walkMarkdown(dir, root, out) {
+    for (const entry of readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        const st = statSync(full);
+        if (st.isDirectory())
+            walkMarkdown(full, root, out);
+        else if (entry.endsWith(".md"))
+            out.push(path.relative(root, full));
+    }
+}

package/dist/extract.js

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+// Patterns for the kinds of token a doc can reference that we can check
+// deterministically against the source tree.
+const FLAG_RE = /(^|[\s(`"'])(--[a-zA-Z][a-zA-Z0-9-]+)/g;
+const ENV_RE = /\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+){1,})\b/g;
+const PATH_RE = /([\w./-]+\/[\w./-]+\.[a-zA-Z0-9]+|[\w-]+\.[a-zA-Z]{2,4})/g;
+// Common English ALL_CAPS that are not env vars.
+const ENV_STOPWORDS = new Set([
+    "NOTE",
+    "TODO",
+    "FIXME",
+    "WARNING",
+    "JSON",
+    "HTTP",
+    "HTTPS",
+    "API",
+    "URL",
+    "CLI",
+    "MIT",
+    "README",
+]);
+// File-ish tokens that are usually prose, not real paths.
+const PATH_STOPWORDS = new Set(["e.g.", "i.e.", "etc.", "vs.", "a.k.a."]);
+/** Extract deterministically-checkable claims from a single doc file. */
+export function extractClaims(root, docFile) {
+    const abs = path.isAbsolute(docFile) ? docFile : path.join(root, docFile);
+    const rel = path.relative(root, abs);
+    const text = readFileSync(abs, "utf8");
+    const lines = text.split("\n");
+    const claims = [];
+    let inFence = false;
+    let fenceLang = "";
+    let counter = 0;
+    const seen = new Set();
+    const push = (kind, line, tok, assertion, hints) => {
+        const key = `${kind}:${tok}`;
+        if (seen.has(key))
+            return; // one claim per distinct token keeps noise down
+        seen.add(key);
+        claims.push({
+            id: `${rel}#${++counter}`,
+            docFile: rel,
+            line,
+            kind,
+            text: tok,
+            assertion,
+            searchHints: hints,
+        });
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNo = i + 1;
+        const fenceMatch = line.match(/^\s*```(\w+)?/);
+        if (fenceMatch) {
+            if (!inFence) {
+                inFence = true;
+                fenceLang = (fenceMatch[1] ?? "").toLowerCase();
+            }
+            else {
+                inFence = false;
+                fenceLang = "";
+            }
+            continue;
+        }
+        // Inside a shell code block, capture commands as claims.
+        if (inFence) {
+            if (["bash", "sh", "shell", "console", "zsh"].includes(fenceLang)) {
+                const cmd = line.replace(/^\s*\$\s?/, "").trim();
+                if (cmd && !cmd.startsWith("#")) {
+                    extractFromCommand(cmd, lineNo, push);
+                }
+            }
+            continue;
+        }
+        // Outside code: scan inline code spans plus the raw line for tokens.
+        const inlineSpans = [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+        const scanText = line;
+        for (const m of scanText.matchAll(FLAG_RE)) {
+            const flag = m[2];
+            push("flag", lineNo, flag, `the CLI flag ${flag} exists`, [flag]);
+        }
+        for (const m of scanText.matchAll(ENV_RE)) {
+            const env = m[1];
+            if (ENV_STOPWORDS.has(env))
+                continue;
+            push("env", lineNo, env, `the environment variable ${env} is used`, [env]);
+        }
+        // Only treat path-looking tokens inside inline code as path claims, to
+        // avoid matching ordinary prose words with dots.
+        for (const span of inlineSpans) {
+            for (const m of span.matchAll(PATH_RE)) {
+                const p = m[1];
+                if (PATH_STOPWORDS.has(p))
+                    continue;
+                if (p.startsWith("--"))
+                    continue;
+                push("file", lineNo, p, `the path ${p} exists`, [p]);
+            }
+            // A bare identifier in backticks used like a function call.
+            const callMatch = span.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\(\)?$/);
+            if (callMatch) {
+                const sym = callMatch[1];
+                if (sym.length > 2) {
+                    push("symbol", lineNo, sym, `the symbol ${sym} exists in the code`, [sym]);
+                }
+            }
+        }
+    }
+    return claims;
+}
+function extractFromCommand(cmd, lineNo, push) {
+    for (const m of cmd.matchAll(FLAG_RE)) {
+        const flag = m[2];
+        push("flag", lineNo, flag, `the CLI flag ${flag} exists`, [flag]);
+    }
+    for (const m of cmd.matchAll(ENV_RE)) {
+        const env = m[1];
+        if (ENV_STOPWORDS.has(env))
+            continue;
+        push("env", lineNo, env, `the environment variable ${env} is used`, [env]);
+    }
+}

package/dist/llm.js

@@ -0,0 +1,42 @@
+import Anthropic from "@anthropic-ai/sdk";
+let client = null;
+export function hasApiKey() {
+    return Boolean(process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN);
+}
+function getClient() {
+    if (client)
+        return client;
+    // Prefer an API key; otherwise fall back to a Bearer/OAuth token (e.g. from
+    // `ant auth login`), which needs the oauth beta header on every request.
+    if (!process.env.ANTHROPIC_API_KEY && process.env.ANTHROPIC_AUTH_TOKEN) {
+        client = new Anthropic({
+            authToken: process.env.ANTHROPIC_AUTH_TOKEN,
+            defaultHeaders: { "anthropic-beta": "oauth-2025-04-20" },
+        });
+    }
+    else {
+        client = new Anthropic();
+    }
+    return client;
+}
+/**
+ * Call the model with a forced JSON schema and return the parsed object.
+ * Uses output_config.format so the first text block is guaranteed valid JSON.
+ */
+export async function structuredCall(model, system, user, schema) {
+    // Built as an untyped param: `adaptive` thinking and `output_config` are
+    // supported by the API but newer than this SDK version's type definitions.
+    const params = {
+        model,
+        max_tokens: 8000,
+        thinking: { type: "adaptive" },
+        system,
+        messages: [{ role: "user", content: user }],
+        output_config: { format: { type: "json_schema", schema } },
+    };
+    const res = await getClient().messages.create(params);
+    const block = res.content.find((b) => b.type === "text");
+    if (!block)
+        throw new Error("Model returned no text content.");
+    return JSON.parse(block.text);
+}

package/dist/mcp.js

@@ -0,0 +1,144 @@
+import path from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { extractClaims } from "./extract.js";
+import { verifyReference } from "./verify-reference.js";
+import { verifyLlm } from "./verify-llm.js";
+import { hasApiKey } from "./llm.js";
+import { discoverDocs } from "./discover.js";
+// The description is the agent's selection signal: it must say *when* to call
+// the tool, not just what it does. Recent models under-reach for tools, so the
+// trigger conditions are load-bearing.
+const CHECK_DESCRIPTION = `Check whether a project's documentation still matches its source code, and report the claims that have drifted (gone stale or wrong).
+
+Call this AFTER you edit, rename, move, or delete source files, CLI flags, environment variables, or functions — to catch documentation you may have just made inaccurate. Also call it when the user asks whether the README or docs are still correct, before cutting a release, or when reviewing a pull request that changes code.
+
+Returns each drifted documentation claim with its file and line, the exact stale text, supporting code evidence, a confidence score, and a suggested fix you can apply directly with an edit. Fast and free by default (deterministic checks, no API key required); pass llm=true to additionally verify prose-level claims such as default values, return types, and described behavior.`;
+const CHECK_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        root: {
+            type: "string",
+            description: "Repository root to check. Defaults to the current working directory.",
+        },
+        docs: {
+            type: "array",
+            items: { type: "string" },
+            description: "Specific doc files to check, relative to root. Defaults to README plus docs/**/*.md.",
+        },
+        llm: {
+            type: "boolean",
+            description: "Also run the LLM prose verifier (needs ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN). Default false.",
+        },
+        failConfidence: {
+            type: "number",
+            description: "Minimum confidence (0..1) for a drift to be reported. Default 0.7.",
+        },
+    },
+};
+const MAX_FINDINGS = 50;
+async function runCheck(args) {
+    const root = path.resolve(args.root ?? process.cwd());
+    const docFiles = args.docs?.length ? args.docs : discoverDocs(root);
+    const failConfidence = args.failConfidence ?? 0.7;
+    const wantLlm = Boolean(args.llm);
+    const useLlm = wantLlm && hasApiKey();
+    const verdicts = [];
+    for (const doc of docFiles) {
+        verdicts.push(...(await verifyReference(root, extractClaims(root, doc))));
+        if (useLlm) {
+            try {
+                verdicts.push(...(await verifyLlm(root, doc, "claude-opus-4-8")));
+            }
+            catch {
+                // Surface as a note rather than failing the whole call.
+            }
+        }
+    }
+    let ok = 0;
+    let drifted = 0;
+    let unverifiable = 0;
+    const findings = [];
+    for (const v of verdicts) {
+        if (v.status === "ok")
+            ok++;
+        else if (v.status === "drifted")
+            drifted++;
+        else
+            unverifiable++;
+        const include = (v.status === "drifted" && v.confidence >= failConfidence) ||
+            v.status === "unverifiable";
+        if (!include || v.status === "ok")
+            continue;
+        findings.push({
+            doc: v.claim.docFile,
+            line: v.claim.line,
+            kind: v.claim.kind,
+            text: v.claim.text,
+            status: v.status,
+            confidence: Number(v.confidence.toFixed(2)),
+            engine: v.engine,
+            explanation: v.explanation,
+            suggestedFix: v.suggestedFix,
+            evidence: v.evidence[0] ? `${v.evidence[0].file}:${v.evidence[0].line}` : undefined,
+        });
+    }
+    // Drifted first, then by confidence — the agent should act on these top-down.
+    findings.sort((a, b) => {
+        if (a.status !== b.status)
+            return a.status === "drifted" ? -1 : 1;
+        return b.confidence - a.confidence;
+    });
+    const truncated = findings.length > MAX_FINDINGS;
+    const shown = findings.slice(0, MAX_FINDINGS);
+    let note;
+    if (wantLlm && !hasApiKey()) {
+        note = "llm=true was requested but no ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN is set; ran deterministic checks only.";
+    }
+    if (truncated) {
+        note = `${note ? note + " " : ""}Showing ${MAX_FINDINGS} of ${findings.length} findings.`;
+    }
+    return {
+        summary: {
+            docsChecked: docFiles,
+            ok,
+            drifted,
+            unverifiable,
+            engine: useLlm ? "reference+llm" : "reference",
+        },
+        findings: shown,
+        note,
+    };
+}
+/** Start the stdio MCP server. Only protocol messages go to stdout. */
+export async function runMcpServer() {
+    const server = new Server({ name: "docverity", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "check_docs",
+                description: CHECK_DESCRIPTION,
+                inputSchema: CHECK_INPUT_SCHEMA,
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        if (req.params.name !== "check_docs") {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+            };
+        }
+        const result = await runCheck((req.params.arguments ?? {}));
+        const headline = result.findings.length === 0
+            ? "No doc drift detected."
+            : `${result.findings.length} documentation claim(s) need attention.`;
+        return {
+            content: [
+                { type: "text", text: `${headline}\n\n${JSON.stringify(result, null, 2)}` },
+            ],
+        };
+    });
+    await server.connect(new StdioServerTransport());
+}

package/dist/report.js

@@ -0,0 +1,84 @@
+import kleur from "kleur";
+export function summarize(verdicts, opts) {
+    let ok = 0;
+    let drifted = 0;
+    let unverifiable = 0;
+    const failures = [];
+    for (const v of verdicts) {
+        if (v.status === "ok")
+            ok++;
+        else if (v.status === "drifted") {
+            drifted++;
+            if (v.confidence >= opts.failConfidence)
+                failures.push(v);
+        }
+        else {
+            unverifiable++;
+            if (opts.strict)
+                failures.push(v);
+        }
+    }
+    return { ok, drifted, unverifiable, failures };
+}
+/** Pretty terminal report. Returns true if the check should fail the build. */
+export function printReport(verdicts, opts) {
+    const summary = summarize(verdicts, opts);
+    const drifts = verdicts
+        .filter((v) => v.status === "drifted" && v.confidence >= opts.failConfidence)
+        .sort((a, b) => b.confidence - a.confidence);
+    if (drifts.length === 0) {
+        console.log(kleur.green(`\n✓ No doc drift detected.`) +
+            kleur.dim(` (${summary.ok} claims verified, ${summary.unverifiable} unverifiable)\n`));
+        return opts.strict && summary.failures.length > 0;
+    }
+    console.log(kleur.bold().red(`\n✗ ${drifts.length} doc claim(s) drifted from the code:\n`));
+    for (const v of drifts) {
+        const loc = kleur.cyan(`${v.claim.docFile}:${v.claim.line}`);
+        const tag = kleur.dim(`[${v.engine}]`);
+        const conf = kleur.dim(`${Math.round(v.confidence * 100)}%`);
+        console.log(`  ${kleur.red("●")} ${loc} ${tag} ${conf}`);
+        console.log(`    ${kleur.bold(v.claim.text)}`);
+        console.log(`    ${v.explanation}`);
+        if (v.suggestedFix) {
+            console.log(`    ${kleur.yellow("fix:")} ${kleur.dim(v.suggestedFix)}`);
+        }
+        if (v.evidence.length) {
+            const e = v.evidence[0];
+            console.log(kleur.dim(`    seen: ${e.file}:${e.line}  ${e.snippet}`));
+        }
+        console.log();
+    }
+    console.log(kleur.dim(`${summary.ok} ok · ${summary.drifted} drifted · ${summary.unverifiable} unverifiable\n`));
+    return true;
+}
+/** GitHub Actions workflow-command annotations. */
+export function printGithubAnnotations(verdicts, opts) {
+    for (const v of verdicts) {
+        if (v.status !== "drifted" || v.confidence < opts.failConfidence)
+            continue;
+        const msg = `${v.claim.text} — ${v.explanation}`.replace(/\n/g, " ");
+        console.log(`::error file=${v.claim.docFile},line=${v.claim.line}::doc drift: ${msg}`);
+    }
+}
+export function toJson(verdicts, opts) {
+    const summary = summarize(verdicts, opts);
+    return JSON.stringify({
+        summary: {
+            ok: summary.ok,
+            drifted: summary.drifted,
+            unverifiable: summary.unverifiable,
+            failed: summary.failures.length,
+        },
+        verdicts: verdicts.map((v) => ({
+            doc: v.claim.docFile,
+            line: v.claim.line,
+            kind: v.claim.kind,
+            text: v.claim.text,
+            status: v.status,
+            confidence: v.confidence,
+            engine: v.engine,
+            explanation: v.explanation,
+            suggestedFix: v.suggestedFix,
+        })),
+    }, null, 2);
+}

package/dist/search.js

@@ -0,0 +1,157 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync } from "node:fs";
+import path from "node:path";
+const execFileAsync = promisify(execFile);
+// Directories never worth searching for evidence of documented behavior.
+const IGNORE_DIRS = [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".next",
+    ".venv",
+    "vendor",
+];
+// Documentation file types are excluded from evidence: a claim in the docs
+// must be backed by the *code*, not by the docs restating it (otherwise a
+// README that mentions a removed flag would cite itself as proof).
+const DOC_EXTENSIONS = [".md", ".markdown", ".mdx", ".rst", ".txt", ".adoc"];
+function isDocFile(file) {
+    const lower = file.toLowerCase();
+    return DOC_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+let rgChecked = false;
+let rgAvailable = false;
+async function hasRipgrep() {
+    if (rgChecked)
+        return rgAvailable;
+    rgChecked = true;
+    try {
+        await execFileAsync("rg", ["--version"]);
+        rgAvailable = true;
+    }
+    catch {
+        rgAvailable = false;
+    }
+    return rgAvailable;
+}
+/**
+ * Search the repo for a literal string. Returns up to `limit` evidence hits.
+ * Uses ripgrep when available, falling back to a Node-based walk otherwise.
+ */
+export async function searchLiteral(root, needle, limit = 8) {
+    if (!needle.trim())
+        return [];
+    if (await hasRipgrep()) {
+        const args = [
+            "--fixed-strings",
+            "--line-number",
+            "--no-heading",
+            "--color",
+            "never",
+            "--max-count",
+            String(limit),
+        ];
+        for (const dir of IGNORE_DIRS)
+            args.push("--glob", `!${dir}/`);
+        for (const ext of DOC_EXTENSIONS)
+            args.push("--glob", `!*${ext}`);
+        args.push("--", needle, ".");
+        try {
+            const { stdout } = await execFileAsync("rg", args, {
+                cwd: root,
+                maxBuffer: 8 * 1024 * 1024,
+            });
+            return parseRgOutput(stdout, limit);
+        }
+        catch (err) {
+            // rg exits 1 when there are no matches; that is not an error for us.
+            if (err?.code === 1)
+                return [];
+            throw err;
+        }
+    }
+    return fallbackSearch(root, needle, limit);
+}
+function parseRgOutput(stdout, limit) {
+    const out = [];
+    for (const raw of stdout.split("\n")) {
+        if (!raw)
+            continue;
+        // format: path:line:content
+        const first = raw.indexOf(":");
+        const second = raw.indexOf(":", first + 1);
+        if (first < 0 || second < 0)
+            continue;
+        const file = raw.slice(0, first);
+        const line = Number(raw.slice(first + 1, second));
+        const snippet = raw.slice(second + 1).trim();
+        out.push({ file, line, snippet: snippet.slice(0, 200) });
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+import { readdirSync, readFileSync, statSync } from "node:fs";
+function fallbackSearch(root, needle, limit) {
+    const out = [];
+    const walk = (dir) => {
+        if (out.length >= limit)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.length >= limit)
+                return;
+            if (IGNORE_DIRS.includes(entry))
+                continue;
+            const full = path.join(dir, entry);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                walk(full);
+            }
+            else if (st.isFile() && st.size < 2 * 1024 * 1024 && !isDocFile(full)) {
+                let content;
+                try {
+                    content = readFileSync(full, "utf8");
+                }
+                catch {
+                    continue;
+                }
+                const lines = content.split("\n");
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].includes(needle)) {
+                        out.push({
+                            file: path.relative(root, full),
+                            line: i + 1,
+                            snippet: lines[i].trim().slice(0, 200),
+                        });
+                        if (out.length >= limit)
+                            return;
+                    }
+                }
+            }
+        }
+    };
+    walk(root);
+    return out;
+}
+/** Resolve a documented path claim against the filesystem. */
+export function fileExists(root, relPath) {
+    const clean = relPath.replace(/^\.\//, "").replace(/[`*]/g, "");
+    return existsSync(path.join(root, clean));
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+// Core data model for DocDrift.
+//
+// A "claim" is one checkable assertion that a documentation file makes about
+// the codebase. The pipeline is: extract claims -> locate evidence in the
+// repo -> verify each claim against that evidence -> report.
+export {};

package/dist/verify-llm.js

@@ -0,0 +1,127 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { searchLiteral } from "./search.js";
+import { structuredCall } from "./llm.js";
+const EXTRACT_SYSTEM = `You extract verifiable factual claims that a documentation file makes about a software codebase.
+
+A claim is a specific, checkable assertion: a default value, a return type, a parameter name, a config key, an install step, a behavior ("by default X happens"), an output shape. Ignore marketing copy, aspirational statements, and anything not checkable against source code.
+
+For each claim, provide search terms (identifiers, strings, file names) that would help locate the relevant code. Be precise; prefer fewer high-quality claims over many vague ones.`;
+const VERIFY_SYSTEM = `You verify whether documentation claims still match the codebase, given source-code evidence.
+
+For each claim, decide:
+- "ok": the evidence confirms the claim is still true.
+- "drifted": the evidence contradicts the claim (the docs are now wrong).
+- "unverifiable": the evidence is insufficient to decide.
+
+Be conservative. Only mark "drifted" when the evidence clearly contradicts the claim. When unsure, choose "unverifiable". A false "drifted" verdict is worse than a missed one. Give the specific contradiction and, when drifted, a concrete suggested doc fix.`;
+const EXTRACT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        claims: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    line: { type: "integer" },
+                    text: { type: "string" },
+                    assertion: { type: "string" },
+                    searchHints: { type: "array", items: { type: "string" } },
+                },
+                required: ["line", "text", "assertion", "searchHints"],
+            },
+        },
+    },
+    required: ["claims"],
+};
+const VERIFY_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        verdicts: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    id: { type: "string" },
+                    status: { type: "string", enum: ["ok", "drifted", "unverifiable"] },
+                    confidence: { type: "number" },
+                    explanation: { type: "string" },
+                    suggestedFix: { type: "string" },
+                },
+                required: ["id", "status", "confidence", "explanation"],
+            },
+        },
+    },
+    required: ["verdicts"],
+};
+/** LLM engine: extract prose claims from a doc and verify them against the code. */
+export async function verifyLlm(root, docFile, model) {
+    const abs = path.isAbsolute(docFile) ? docFile : path.join(root, docFile);
+    const rel = path.relative(root, abs);
+    const docText = readFileSync(abs, "utf8");
+    const numbered = docText
+        .split("\n")
+        .map((l, i) => `${i + 1}: ${l}`)
+        .join("\n");
+    const { claims: raw } = await structuredCall(model, EXTRACT_SYSTEM, `Documentation file: ${rel}\n\n${numbered}`, EXTRACT_SCHEMA);
+    if (!raw.length)
+        return [];
+    const claims = raw.map((c, i) => ({
+        id: `${rel}~${i + 1}`,
+        docFile: rel,
+        line: c.line,
+        kind: "prose",
+        text: c.text,
+        assertion: c.assertion,
+        searchHints: c.searchHints,
+    }));
+    // Gather evidence for each claim from the source tree.
+    const evidenceByClaim = new Map();
+    for (const claim of claims) {
+        const found = [];
+        for (const hint of claim.searchHints.slice(0, 4)) {
+            found.push(...(await searchLiteral(root, hint, 4)));
+        }
+        evidenceByClaim.set(claim.id, dedupeEvidence(found).slice(0, 8));
+    }
+    const verifyPayload = claims.map((c) => ({
+        id: c.id,
+        claim: c.assertion,
+        docText: c.text,
+        evidence: evidenceByClaim.get(c.id) ?? [],
+    }));
+    const { verdicts: rawVerdicts } = await structuredCall(model, VERIFY_SYSTEM, `Verify these claims against the evidence:\n\n${JSON.stringify(verifyPayload, null, 2)}`, VERIFY_SCHEMA);
+    const byId = new Map(claims.map((c) => [c.id, c]));
+    const out = [];
+    for (const v of rawVerdicts) {
+        const claim = byId.get(v.id);
+        if (!claim)
+            continue;
+        out.push({
+            claim,
+            status: v.status,
+            confidence: v.confidence,
+            explanation: v.explanation,
+            suggestedFix: v.suggestedFix,
+            evidence: evidenceByClaim.get(v.id) ?? [],
+            engine: "llm",
+        });
+    }
+    return out;
+}
+function dedupeEvidence(items) {
+    const seen = new Set();
+    const out = [];
+    for (const e of items) {
+        const key = `${e.file}:${e.line}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(e);
+    }
+    return out;
+}

package/dist/verify-reference.js

@@ -0,0 +1,68 @@
+import { searchLiteral, fileExists } from "./search.js";
+/**
+ * The deterministic engine: verify each claim by looking for hard evidence in
+ * the source tree. No model, no API key. High precision by design — when in
+ * doubt it returns "unverifiable" rather than "drifted".
+ */
+export async function verifyReference(root, claims) {
+    const verdicts = [];
+    for (const claim of claims) {
+        verdicts.push(await verifyOne(root, claim));
+    }
+    return verdicts;
+}
+async function verifyOne(root, claim) {
+    const base = { claim, evidence: [], engine: "reference" };
+    switch (claim.kind) {
+        case "file": {
+            const exists = fileExists(root, claim.text);
+            return exists
+                ? {
+                    ...base,
+                    status: "ok",
+                    confidence: 0.95,
+                    explanation: `${claim.text} exists on disk.`,
+                }
+                : {
+                    ...base,
+                    status: "drifted",
+                    confidence: 0.9,
+                    explanation: `The docs reference ${claim.text}, but no such file or directory exists.`,
+                    suggestedFix: `Update or remove the reference to ${claim.text}.`,
+                };
+        }
+        case "flag":
+        case "env":
+        case "symbol": {
+            const hits = await searchLiteral(root, claim.text);
+            if (hits.length > 0) {
+                return {
+                    ...base,
+                    status: "ok",
+                    confidence: 0.8,
+                    explanation: `Found ${hits.length} occurrence(s) of ${claim.text} in the source.`,
+                    evidence: hits.slice(0, 3),
+                };
+            }
+            const noun = claim.kind === "flag"
+                ? "CLI flag"
+                : claim.kind === "env"
+                    ? "environment variable"
+                    : "symbol";
+            return {
+                ...base,
+                status: "drifted",
+                confidence: claim.kind === "symbol" ? 0.6 : 0.8,
+                explanation: `The docs mention the ${noun} ${claim.text}, but it does not appear anywhere in the source.`,
+                suggestedFix: `Verify ${claim.text} still exists; it may have been renamed or removed.`,
+            };
+        }
+        default:
+            return {
+                ...base,
+                status: "unverifiable",
+                confidence: 0.3,
+                explanation: `Prose claim — needs the LLM engine to verify.`,
+            };
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "docverity",
+  "version": "0.1.0",
+  "description": "Catch documentation that lies about your code. Verify that your docs' claims still match the source, in CI.",
+  "type": "module",
+  "bin": {
+    "docverity": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "documentation",
+    "docs",
+    "drift",
+    "ci",
+    "readme",
+    "doc-rot",
+    "lint",
+    "ai",
+    "claude",
+    "mcp",
+    "model-context-protocol",
+    "agent"
+  ],
+  "author": "Devesh Agarwal",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deveshagarwal/docverity.git"
+  },
+  "homepage": "https://github.com/deveshagarwal/docverity#readme",
+  "bugs": {
+    "url": "https://github.com/deveshagarwal/docverity/issues"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.70.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^12.1.0",
+    "kleur": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}