docverity 0.1.0 → 0.2.0

package/README.md

@@ -69,7 +69,9 @@ docverity --no-llm
 | `--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.
+it fails CI the way a linter would. Exit codes: `0` clean, `1` drift found,
+`2` a configuration error (e.g. an invalid `--fail-confidence` or a missing doc
+file) so a typo can never mask real drift with a green build.
 
 ## In CI (GitHub Actions)
 

package/dist/cli.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import path from "node:path";
+import { existsSync } from "node:fs";
 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";
+// verify-llm and mcp pull in heavy SDKs; they are imported lazily, only when used.
 const program = new Command();
 program
     .name("docverity")
     .description("Catch documentation that lies about your code.")
-    .version("0.1.0");
+    .version("0.2.0");
 program
     .command("check", { isDefault: true })
     .description("Check docs for claims that no longer match the code.")
@@ -26,7 +26,26 @@ program
     .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);
+    // A non-numeric threshold must never silently pass CI. Exit 2 = config error
+    // (distinct from 1 = drift found).
+    const failConfidence = Number(rawOpts.failConfidence);
+    if (!Number.isFinite(failConfidence) || failConfidence < 0 || failConfidence > 1) {
+        console.error(kleur.red(`Invalid --fail-confidence: ${rawOpts.failConfidence} (expected a number between 0 and 1).`));
+        process.exit(2);
+    }
+    // Resolve explicit doc args relative to root (path.resolve handles
+    // absolute/cwd-relative); path.relative makes them root-relative for the
+    // extractor and verifier, fixing the old root+arg double-join.
+    const docFiles = docs.length
+        ? docs.map((d) => path.relative(root, path.resolve(d)))
+        : discoverDocs(root);
+    if (docs.length) {
+        const missing = docFiles.filter((d) => !existsSync(path.join(root, d)));
+        if (missing.length) {
+            console.error(kleur.red(`Doc file(s) not found: ${missing.join(", ")}`));
+            process.exit(2);
+        }
+    }
     if (!docFiles.length) {
         console.error(kleur.yellow("No documentation files found."));
         process.exit(0);
@@ -40,14 +59,21 @@ program
         docFiles,
         useLlm,
         model: rawOpts.model,
-        failConfidence: Number(rawOpts.failConfidence),
+        failConfidence,
         strict: Boolean(rawOpts.strict),
     };
+    // Lazy-load the LLM engine (and its SDK) only when actually used.
+    const verifyLlm = useLlm ? (await import("./verify-llm.js")).verifyLlm : null;
     const verdicts = [];
     for (const doc of docFiles) {
-        const claims = extractClaims(root, doc);
-        verdicts.push(...(await verifyReference(root, claims)));
-        if (useLlm) {
+        try {
+            verdicts.push(...(await verifyReference(root, extractClaims(root, doc))));
+        }
+        catch (err) {
+            console.error(kleur.yellow(`Cannot check ${doc}: ${err?.message ?? err}`));
+            continue;
+        }
+        if (verifyLlm) {
             try {
                 verdicts.push(...(await verifyLlm(root, doc, opts.model)));
             }
@@ -74,6 +100,7 @@ program
     .command("mcp")
     .description("Run as an MCP server (stdio) so agents can check docs as a tool.")
     .action(async () => {
+    const { runMcpServer } = await import("./mcp.js");
     await runMcpServer();
 });
 program.parseAsync();

package/dist/extract.js

@@ -4,7 +4,9 @@ import path from "node:path";
 // 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;
+// Either a slash path (a/b.ext) or a (possibly multi-dot) filename (app.config.ts).
+// The multi-dot form keeps whole filenames intact instead of fragmenting them.
+const PATH_RE = /([\w./-]+\/[\w./-]+\.[a-zA-Z0-9]+|[\w-]+(?:\.[\w-]+)*\.[a-zA-Z][a-zA-Z0-9]{0,8})\b/g;
 // Common English ALL_CAPS that are not env vars.
 const ENV_STOPWORDS = new Set([
     "NOTE",
@@ -20,8 +22,19 @@ const ENV_STOPWORDS = new Set([
     "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."]);
+// File-ish tokens that are usually prose, not real paths. Both the
+// trailing-dot and bare forms, since PATH_RE can match either.
+const PATH_STOPWORDS = new Set([
+    "e.g.",
+    "i.e.",
+    "etc.",
+    "vs.",
+    "a.k.a.",
+    "e.g",
+    "i.e",
+    "a.k.a",
+    "vs",
+]);
 /** Extract deterministically-checkable claims from a single doc file. */
 export function extractClaims(root, docFile) {
     const abs = path.isAbsolute(docFile) ? docFile : path.join(root, docFile);
@@ -73,28 +86,29 @@ export function extractClaims(root, docFile) {
             }
             continue;
         }
-        // Outside code: scan inline code spans plus the raw line for tokens.
+        // Flags are distinctive (the -- prefix), so they can be claimed from prose.
+        // Env vars, paths, and symbols only count inside inline code spans — raw
+        // prose has too many ALL_CAPS words and dotted phrases to scan safely.
         const inlineSpans = [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
-        const scanText = line;
-        for (const m of scanText.matchAll(FLAG_RE)) {
+        for (const m of line.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(ENV_RE)) {
+                const env = m[1];
+                if (ENV_STOPWORDS.has(env))
+                    continue;
+                push("env", lineNo, env, `the environment variable ${env} is used`, [env]);
+            }
             for (const m of span.matchAll(PATH_RE)) {
                 const p = m[1];
                 if (PATH_STOPWORDS.has(p))
                     continue;
                 if (p.startsWith("--"))
                     continue;
+                if (p.startsWith("/"))
+                    continue; // absolute/home path, not a repo file
                 push("file", lineNo, p, `the path ${p} exists`, [p]);
             }
             // A bare identifier in backticks used like a function call.

package/dist/llm.js

@@ -1,11 +1,13 @@
-import Anthropic from "@anthropic-ai/sdk";
+// The Anthropic SDK is imported lazily so the default deterministic path (and
+// `npx docverity` cold start) never pays to load it.
 let client = null;
 export function hasApiKey() {
     return Boolean(process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN);
 }
-function getClient() {
+async function getClient() {
     if (client)
         return client;
+    const { default: Anthropic } = await import("@anthropic-ai/sdk");
     // 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) {
@@ -21,11 +23,9 @@ function getClient() {
 }
 /**
  * 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.
+ * output_config.format guarantees the first text block is 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,
@@ -34,9 +34,15 @@ export async function structuredCall(model, system, user, schema) {
         messages: [{ role: "user", content: user }],
         output_config: { format: { type: "json_schema", schema } },
     };
-    const res = await getClient().messages.create(params);
+    const c = await getClient();
+    const res = await c.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);
+    try {
+        return JSON.parse(block.text);
+    }
+    catch {
+        throw new Error("LLM returned truncated or non-JSON output (may have exceeded max_tokens).");
+    }
 }

package/dist/mcp.js

@@ -45,14 +45,19 @@ async function runCheck(args) {
     const wantLlm = Boolean(args.llm);
     const useLlm = wantLlm && hasApiKey();
     const verdicts = [];
+    let llmRan = false;
+    let llmError;
     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")));
+                llmRan = true;
             }
-            catch {
-                // Surface as a note rather than failing the whole call.
+            catch (err) {
+                // Don't fail the whole tool call; surface it as a note so the agent
+                // knows it got deterministic-only results, not a clean pass.
+                llmError = err?.message ?? String(err);
             }
         }
     }
@@ -67,9 +72,9 @@ async function runCheck(args) {
             drifted++;
         else
             unverifiable++;
-        const include = (v.status === "drifted" && v.confidence >= failConfidence) ||
-            v.status === "unverifiable";
-        if (!include || v.status === "ok")
+        // Only surface actionable drift; unverifiable claims stay in the counts but
+        // would be noise for an agent to act on.
+        if (!(v.status === "drifted" && v.confidence >= failConfidence))
             continue;
         findings.push({
             doc: v.claim.docFile,
@@ -93,11 +98,17 @@ async function runCheck(args) {
     const truncated = findings.length > MAX_FINDINGS;
     const shown = findings.slice(0, MAX_FINDINGS);
     let note;
+    const addNote = (s) => {
+        note = note ? `${note} ${s}` : s;
+    };
     if (wantLlm && !hasApiKey()) {
-        note = "llm=true was requested but no ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN is set; ran deterministic checks only.";
+        addNote("llm=true was requested but no ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN is set; ran deterministic checks only.");
+    }
+    if (llmError) {
+        addNote(`LLM prose verifier failed: ${llmError}; reported deterministic results only.`);
     }
     if (truncated) {
-        note = `${note ? note + " " : ""}Showing ${MAX_FINDINGS} of ${findings.length} findings.`;
+        addNote(`Showing ${MAX_FINDINGS} of ${findings.length} findings.`);
     }
     return {
         summary: {
@@ -105,7 +116,7 @@ async function runCheck(args) {
             ok,
             drifted,
             unverifiable,
-            engine: useLlm ? "reference+llm" : "reference",
+            engine: useLlm && llmRan ? "reference+llm" : "reference",
         },
         findings: shown,
         note,
@@ -113,7 +124,7 @@ async function runCheck(args) {
 }
 /** 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: {} } });
+    const server = new Server({ name: "docverity", version: "0.2.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
             {
@@ -130,15 +141,25 @@ export async function runMcpServer() {
                 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)}` },
-            ],
-        };
+        try {
+            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)}` },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    { type: "text", text: `docverity check failed: ${err?.message ?? err}` },
+                ],
+            };
+        }
     });
     await server.connect(new StdioServerTransport());
 }

package/dist/report.js

@@ -1,5 +1,10 @@
 import kleur from "kleur";
+/** A non-finite threshold must never silently pass all drift; fall back to 0.7. */
+export function effectiveFailConfidence(opts) {
+    return Number.isFinite(opts.failConfidence) ? opts.failConfidence : 0.7;
+}
 export function summarize(verdicts, opts) {
+    const failConfidence = effectiveFailConfidence(opts);
     let ok = 0;
     let drifted = 0;
     let unverifiable = 0;
@@ -9,7 +14,7 @@ export function summarize(verdicts, opts) {
             ok++;
         else if (v.status === "drifted") {
             drifted++;
-            if (v.confidence >= opts.failConfidence)
+            if (v.confidence >= failConfidence)
                 failures.push(v);
         }
         else {
@@ -23,8 +28,9 @@ export function summarize(verdicts, opts) {
 /** Pretty terminal report. Returns true if the check should fail the build. */
 export function printReport(verdicts, opts) {
     const summary = summarize(verdicts, opts);
+    const failConfidence = effectiveFailConfidence(opts);
     const drifts = verdicts
-        .filter((v) => v.status === "drifted" && v.confidence >= opts.failConfidence)
+        .filter((v) => v.status === "drifted" && v.confidence >= failConfidence)
         .sort((a, b) => b.confidence - a.confidence);
     if (drifts.length === 0) {
         console.log(kleur.green(`\n✓ No doc drift detected.`) +
@@ -51,13 +57,18 @@ export function printReport(verdicts, opts) {
     console.log(kleur.dim(`${summary.ok} ok · ${summary.drifted} drifted · ${summary.unverifiable} unverifiable\n`));
     return true;
 }
+// GitHub workflow commands need %/CR/LF escaped in data, and additionally
+// :/, escaped in property values, or the annotation truncates or mis-targets.
+const escData = (s) => s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+const escProp = (s) => escData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
 /** GitHub Actions workflow-command annotations. */
 export function printGithubAnnotations(verdicts, opts) {
+    const failConfidence = effectiveFailConfidence(opts);
     for (const v of verdicts) {
-        if (v.status !== "drifted" || v.confidence < opts.failConfidence)
+        if (v.status !== "drifted" || v.confidence < 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}`);
+        const msg = `doc drift: ${v.claim.text} — ${v.explanation}`;
+        console.log(`::error file=${escProp(v.claim.docFile)},line=${v.claim.line},title=docverity::${escData(msg)}`);
     }
 }
 export function toJson(verdicts, opts) {

package/dist/search.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 const execFileAsync = promisify(execFile);
 // Directories never worth searching for evidence of documented behavior.
@@ -23,6 +23,12 @@ function isDocFile(file) {
     const lower = file.toLowerCase();
     return DOC_EXTENSIONS.some((ext) => lower.endsWith(ext));
 }
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function flagPattern(token) {
+    return `(^|[^A-Za-z0-9-])${escapeRegex(token)}([^A-Za-z0-9-]|$)`;
+}
 let rgChecked = false;
 let rgAvailable = false;
 async function hasRipgrep() {
@@ -38,43 +44,57 @@ async function hasRipgrep() {
     }
     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) {
+/** Plain substring search. Used to gather evidence for the LLM engine. */
+export function searchLiteral(root, needle, limit = 8) {
+    return runSearch(root, needle, "literal", limit);
+}
+/** Boundary-aware search used by the deterministic verifier. */
+export function searchToken(root, token, mode, limit = 8) {
+    return runSearch(root, token, mode, limit);
+}
+async function runSearch(root, needle, mode, limit) {
     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;
-        }
+    if (await hasRipgrep())
+        return rgSearch(root, needle, mode, limit);
+    return fallbackSearch(root, needle, mode, limit);
+}
+async function rgSearch(root, needle, mode, limit) {
+    const args = [
+        "--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}`);
+    if (mode === "flag") {
+        args.push("--regexp", flagPattern(needle));
+    }
+    else if (mode === "word") {
+        args.push("--fixed-strings", "--word-regexp", "--regexp", needle);
+    }
+    else {
+        args.push("--fixed-strings", "--regexp", needle);
+    }
+    args.push("--", ".");
+    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 = [];
@@ -86,7 +106,7 @@ function parseRgOutput(stdout, limit) {
         const second = raw.indexOf(":", first + 1);
         if (first < 0 || second < 0)
             continue;
-        const file = raw.slice(0, first);
+        const file = raw.slice(0, first).replace(/^\.\//, "");
         const line = Number(raw.slice(first + 1, second));
         const snippet = raw.slice(second + 1).trim();
         out.push({ file, line, snippet: snippet.slice(0, 200) });
@@ -95,8 +115,16 @@ function parseRgOutput(stdout, limit) {
     }
     return out;
 }
-import { readdirSync, readFileSync, statSync } from "node:fs";
-function fallbackSearch(root, needle, limit) {
+function matcherFor(needle, mode) {
+    if (mode === "literal")
+        return (line) => line.includes(needle);
+    const re = mode === "flag"
+        ? new RegExp(flagPattern(needle))
+        : new RegExp(`\\b${escapeRegex(needle)}\\b`);
+    return (line) => re.test(line);
+}
+function fallbackSearch(root, needle, mode, limit) {
+    const matches = matcherFor(needle, mode);
     const out = [];
     const walk = (dir) => {
         if (out.length >= limit)
@@ -134,7 +162,7 @@ function fallbackSearch(root, needle, limit) {
                 }
                 const lines = content.split("\n");
                 for (let i = 0; i < lines.length; i++) {
-                    if (lines[i].includes(needle)) {
+                    if (matches(lines[i])) {
                         out.push({
                             file: path.relative(root, full),
                             line: i + 1,
@@ -150,8 +178,13 @@ function fallbackSearch(root, needle, limit) {
     walk(root);
     return out;
 }
-/** Resolve a documented path claim against the filesystem. */
+/** Resolve a documented path claim against the filesystem, contained to the repo. */
 export function fileExists(root, relPath) {
     const clean = relPath.replace(/^\.\//, "").replace(/[`*]/g, "");
-    return existsSync(path.join(root, clean));
+    const base = path.resolve(root);
+    const target = path.resolve(base, clean);
+    // Don't let "../../etc/passwd" style references probe outside the repo.
+    if (target !== base && !target.startsWith(base + path.sep))
+        return false;
+    return existsSync(target);
 }

package/dist/verify-llm.js

@@ -6,6 +6,8 @@ const EXTRACT_SYSTEM = `You extract verifiable factual claims that a documentati
 
 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.
 
+Do NOT emit bare flag/env-var/file-path/function-name existence claims (e.g. "the --json flag exists", "see src/foo.ts") — a separate deterministic engine already checks those, and re-reporting them causes duplicates. Focus on semantic prose claims: values, behaviors, types, defaults.
+
 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.
 
@@ -14,7 +16,7 @@ For each claim, decide:
 - "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.`;
+Be conservative. Only mark "drifted" when the evidence affirmatively shows a DIFFERENT value or behavior than the claim states. Absence of evidence is NEVER drift: if the evidence array is empty, or does not actually mention the claim's subject, you MUST return "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,
@@ -88,15 +90,36 @@ export async function verifyLlm(root, docFile, model) {
         }
         evidenceByClaim.set(claim.id, dedupeEvidence(found).slice(0, 8));
     }
-    const verifyPayload = claims.map((c) => ({
+    const out = [];
+    // Claims with no located evidence are NOT sent to the model: handing it an
+    // empty evidence array invites "absent, therefore drifted" hallucinations.
+    // Without evidence the claim is unverifiable by definition.
+    const grounded = [];
+    for (const claim of claims) {
+        if ((evidenceByClaim.get(claim.id) ?? []).length === 0) {
+            out.push({
+                claim,
+                status: "unverifiable",
+                confidence: 0.3,
+                explanation: "No code evidence located for this claim.",
+                evidence: [],
+                engine: "llm",
+            });
+        }
+        else {
+            grounded.push(claim);
+        }
+    }
+    if (grounded.length === 0)
+        return out;
+    const verifyPayload = grounded.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 = [];
+    const byId = new Map(grounded.map((c) => [c.id, c]));
     for (const v of rawVerdicts) {
         const claim = byId.get(v.id);
         if (!claim)

package/dist/verify-reference.js

@@ -1,4 +1,4 @@
-import { searchLiteral, fileExists } from "./search.js";
+import { searchToken, 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
@@ -15,26 +15,38 @@ async function verifyOne(root, claim) {
     const base = { claim, evidence: [], engine: "reference" };
     switch (claim.kind) {
         case "file": {
-            const exists = fileExists(root, claim.text);
-            return exists
-                ? {
+            if (fileExists(root, claim.text)) {
+                return {
                     ...base,
                     status: "ok",
                     confidence: 0.95,
                     explanation: `${claim.text} exists on disk.`,
-                }
-                : {
+                };
+            }
+            // A bare filename with no path separator is often a library or framework
+            // name in code formatting (Node.js, config.js), not a repo file. Don't
+            // assert drift on those; downgrade to unverifiable.
+            if (!claim.text.includes("/")) {
+                return {
                     ...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}.`,
+                    status: "unverifiable",
+                    confidence: 0.3,
+                    explanation: `${claim.text} is not a file in the repo; it may be a library or framework name rather than a path.`,
                 };
+            }
+            return {
+                ...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);
+            const mode = claim.kind === "flag" ? "flag" : "word";
+            const hits = await searchToken(root, claim.text, mode);
             if (hits.length > 0) {
                 return {
                     ...base,
@@ -49,10 +61,12 @@ async function verifyOne(root, claim) {
                 : claim.kind === "env"
                     ? "environment variable"
                     : "symbol";
+            // Boundary-aware search (below) means a hit is a real, whole-token match,
+            // so a miss is trustworthy enough to fail CI on, symbols included.
             return {
                 ...base,
                 status: "drifted",
-                confidence: claim.kind === "symbol" ? 0.6 : 0.8,
+                confidence: 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.`,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docverity",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Catch documentation that lies about your code. Verify that your docs' claims still match the source, in CI.",
   "type": "module",
   "bin": {
@@ -44,7 +44,7 @@
     "url": "https://github.com/deveshagarwal/docverity/issues"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.70.0",
+    "@anthropic-ai/sdk": "^0.106.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^12.1.0",
     "kleur": "^4.1.5"