daftari 1.17.1 → 1.19.0

package/dist/audit/index.js

@@ -7,13 +7,48 @@
 //   3 — runtime error
 import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { createAnthropicClient } from "../eval/llm.js";
 import { checkBrokenRefs } from "./checks/broken_refs.js";
+import { checkDescribesRefs } from "./checks/describes_refs.js";
 import { checkStaleness } from "./checks/staleness.js";
 import { collectRepos } from "./collect.js";
 import { parseAuditConfig } from "./config.js";
+import { classifyDescribesEdges } from "./describes.js";
 import { computeExitCode } from "./exit.js";
 import { classifyEdges } from "./links.js";
 import { renderJson, renderMarkdown } from "./report.js";
+import { logSemanticTensions, runSemanticCheck } from "./semantic.js";
+// Latest Sonnet — capable for doc/code comparison, cheaper than Opus for a
+// per-binding classification. Override with --semantic-model.
+const DEFAULT_SEMANTIC_MODEL = "claude-sonnet-4-6";
+function readNumberArg(argv, flag) {
+    const raw = argv.find((a) => a === flag || a.startsWith(`${flag}=`));
+    if (raw === undefined)
+        return undefined;
+    const idx = argv.indexOf(raw);
+    const value = raw.includes("=") ? raw.slice(raw.indexOf("=") + 1) : argv[idx + 1];
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+function readStringArg(argv, flag) {
+    const raw = argv.find((a) => a === flag || a.startsWith(`${flag}=`));
+    if (raw === undefined)
+        return undefined;
+    const idx = argv.indexOf(raw);
+    return raw.includes("=") ? raw.slice(raw.indexOf("=") + 1) : argv[idx + 1];
+}
+// The single docs repo that --auto-tension logs into. Tension entries live in a
+// vault's .daftari/tensions.md, so the target vault must be unambiguous.
+function resolveTensionVault(config) {
+    const docsRepos = config.repos.filter((r) => r.type !== "code");
+    if (docsRepos.length !== 1) {
+        return {
+            error: "--auto-tension requires exactly one docs repo to log tensions into; " +
+                `found ${docsRepos.length}`,
+        };
+    }
+    return docsRepos[0].path;
+}
 const HELP = `daftari audit — coherence checks across markdown repos.
 
 Usage:
@@ -22,14 +57,27 @@ Usage:
   daftari audit --help
 
 Flags:
-  --repo <path>          Add a repo to the audit. May be repeated. Anonymous
-                         CLI repos get no URL patterns — URL-based cross-repo
-                         references to them will not be detected. Use --config
-                         to declare urls explicitly.
+  --repo <path>          Add a docs repo to the audit. May be repeated.
+                         Anonymous CLI repos get no URL patterns — URL-based
+                         cross-repo references to them will not be detected.
+                         Use --config to declare urls explicitly.
+  --code-repo <path>     Add a code repo: a raw reference target indexed by
+                         path only (no frontmatter parsing). May be repeated.
+                         Doc-to-code \`describes\` bindings resolve against it.
   --config <path>        Load an audit.yaml. CLI flags override its values for
                          output paths (a warning is printed to stderr).
   --output <md>          Markdown report destination (default: stdout).
   --output-json <json>   JSON report destination (default: not written).
+  --semantic             Opt-in LLM check: for each doc-to-code binding whose
+                         target exists, ask whether the doc still accurately
+                         describes the code. Slow and token-costly; off by
+                         default. Requires ANTHROPIC_API_KEY.
+  --semantic-model <id>  Model for --semantic (default: ${DEFAULT_SEMANTIC_MODEL}).
+  --max-semantic <n>     Cap on semantic LLM calls (default: 200). Excess
+                         bindings are skipped with a logged count.
+  --auto-tension         With --semantic: log drifted/contradicted bindings as
+                         tensions in the docs vault. Requires exactly one docs
+                         repo. Never edits a doc.
 
 Exit codes:
   0  — run succeeded, all findings under configured thresholds
@@ -37,7 +85,7 @@ Exit codes:
   2  — config error (missing fields, bad paths, malformed YAML)
   3  — runtime error (IO failure during collection)
 `;
-export async function runAudit(argv) {
+export async function runAudit(argv, overrides = {}) {
     if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
         process.stdout.write(HELP);
         return 0;
@@ -48,6 +96,38 @@ export async function runAudit(argv) {
         return parsed.error.kind === "config" ? 2 : 3;
     }
     const config = parsed.value;
+    const semantic = argv.includes("--semantic");
+    const autoTension = argv.includes("--auto-tension");
+    // --auto-tension only acts on semantic findings; without --semantic there are
+    // none, so it would be a silent no-op. Warn rather than do nothing quietly.
+    if (autoTension && !semantic) {
+        process.stderr.write("daftari audit: --auto-tension has no effect without --semantic (no findings to log)\n");
+    }
+    // Fail fast on semantic preconditions, before any collection work.
+    let tensionVault = null;
+    if (autoTension) {
+        const resolved = resolveTensionVault(config);
+        if (typeof resolved !== "string") {
+            process.stderr.write(`daftari audit: ${resolved.error}\n`);
+            return 2;
+        }
+        tensionVault = resolved;
+    }
+    let llm = null;
+    if (semantic) {
+        if (overrides.llm) {
+            llm = overrides.llm;
+        }
+        else {
+            try {
+                llm = createAnthropicClient();
+            }
+            catch (e) {
+                process.stderr.write(`daftari audit: ${e instanceof Error ? e.message : String(e)}\n`);
+                return 2;
+            }
+        }
+    }
     const collected = await collectRepos(config);
     if (!collected.ok) {
         process.stderr.write(`daftari audit: ${collected.error.message}\n`);
@@ -57,12 +137,36 @@ export async function runAudit(argv) {
     const edges = classifyEdges(snapshots);
     const brokenRefs = checkBrokenRefs(snapshots, edges);
     const staleness = checkStaleness(snapshots, edges, config.staleness.thresholdDays, new Date());
+    const describesEdges = classifyDescribesEdges(snapshots);
+    const describesRefs = checkDescribesRefs(snapshots, describesEdges);
+    let semanticFindings = [];
+    if (semantic && llm) {
+        semanticFindings = await runSemanticCheck(describesEdges, snapshots, {
+            llm,
+            model: readStringArg(argv, "--semantic-model") ?? DEFAULT_SEMANTIC_MODEL,
+            maxSemantic: readNumberArg(argv, "--max-semantic"),
+            onCap: (dropped) => process.stderr.write(`daftari audit: --semantic capped; ${dropped} binding(s) not checked ` +
+                `(raise --max-semantic to include them)\n`),
+        });
+        if (autoTension && tensionVault) {
+            const { logged, errors } = await logSemanticTensions(semanticFindings, tensionVault, "agent:daftari-audit");
+            if (logged > 0)
+                process.stderr.write(`daftari audit: logged ${logged} tension(s)\n`);
+            for (const err of errors)
+                process.stderr.write(`daftari audit: tension log: ${err}\n`);
+        }
+    }
     const totals = {
         reposScanned: snapshots.length,
-        docsScanned: snapshots.reduce((n, s) => n + s.docs.size, 0),
+        // Only docs repos hold managed documents; code repos are reference targets.
+        docsScanned: snapshots
+            .filter((s) => s.config.type !== "code")
+            .reduce((n, s) => n + s.docs.size, 0),
         brokenRefs: brokenRefs.length,
         directlyStale: staleness.filter((f) => f.kind === "direct").length,
         transitivelyStale: staleness.filter((f) => f.kind === "transitive").length,
+        brokenDescribes: describesRefs.length,
+        semanticDrifted: semanticFindings.filter((f) => f.verdict === "drifted" || f.verdict === "contradicted").length,
     };
     const report = {
         generatedAt: new Date().toISOString(),
@@ -70,6 +174,8 @@ export async function runAudit(argv) {
         totals,
         brokenRefs,
         staleness,
+        describesRefs,
+        semantic: semanticFindings,
     };
     const md = renderMarkdown(report);
     try {

package/dist/audit/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"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"}

package/dist/audit/readtext.d.ts

@@ -0,0 +1,16 @@
+import { type Result } from "../frontmatter/types.js";
+export declare const DEFAULT_MAX_BYTES: number;
+export interface ReadTextOk {
+    text: string;
+    bytes: number;
+}
+export type ReadTextReason = "too_large" | "binary" | "encoding" | "unreadable";
+export interface ReadTextError {
+    reason: ReadTextReason;
+    message: string;
+}
+export interface ReadTextOptions {
+    maxBytes?: number;
+}
+export declare function readTextFile(absPath: string, opts?: ReadTextOptions): Promise<Result<ReadTextOk, ReadTextError>>;
+//# sourceMappingURL=readtext.d.ts.map

package/dist/audit/readtext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readtext.d.ts","sourceRoot":"","sources":["../../src/audit/readtext.ts"],"names":[],"mappings":"AAcA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE/D,eAAO,MAAM,iBAAiB,QAAa,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC,CAmC5C"}

package/dist/audit/readtext.js

@@ -0,0 +1,50 @@
+// src/audit/readtext.ts
+// Guarded text-file reader for non-markdown reference targets. The audit reads
+// arbitrary code files (semantic.ts; the eval subgraph loader in #121) and hands
+// their contents to an LLM. Those files carry none of the guarantees the
+// markdown path enjoys, so every read is bounded:
+//
+//   - size-capped (default 256 KiB) — checked via stat BEFORE reading, so a
+//     huge generated/vendored file is never pulled into memory;
+//   - binary-sniffed (a NUL byte → not text) — never send raw bytes to a model;
+//   - strict UTF-8 — undecodable input is rejected rather than mojibake'd.
+//
+// Content is never stored, indexed, or embedded — it is read ephemerally.
+import { readFile, stat } from "node:fs/promises";
+import { err, ok } from "../frontmatter/types.js";
+export const DEFAULT_MAX_BYTES = 256 * 1024;
+export async function readTextFile(absPath, opts = {}) {
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    let size;
+    try {
+        const st = await stat(absPath);
+        if (!st.isFile()) {
+            return err({ reason: "unreadable", message: `not a regular file: ${absPath}` });
+        }
+        size = st.size;
+    }
+    catch (e) {
+        return err({ reason: "unreadable", message: e instanceof Error ? e.message : String(e) });
+    }
+    if (size > maxBytes) {
+        return err({ reason: "too_large", message: `${size} bytes exceeds cap of ${maxBytes}` });
+    }
+    let buf;
+    try {
+        buf = await readFile(absPath);
+    }
+    catch (e) {
+        return err({ reason: "unreadable", message: e instanceof Error ? e.message : String(e) });
+    }
+    if (buf.includes(0)) {
+        return err({ reason: "binary", message: "contains NUL byte" });
+    }
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(buf);
+        return ok({ text, bytes: buf.length });
+    }
+    catch {
+        return err({ reason: "encoding", message: "not valid UTF-8" });
+    }
+}
+//# sourceMappingURL=readtext.js.map

package/dist/audit/readtext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readtext.js","sourceRoot":"","sources":["../../src/audit/readtext.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,+EAA+E;AAC/E,iFAAiF;AACjF,yEAAyE;AACzE,kDAAkD;AAClD,EAAE;AACF,4EAA4E;AAC5E,gEAAgE;AAChE,gFAAgF;AAChF,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAE1E,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,yBAAyB,CAAC;AAE/D,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,GAAG,IAAI,CAAC;AAkB5C,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,OAAwB,EAAE;IAE1B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IAEpD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC;YACjB,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,uBAAuB,OAAO,EAAE,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;IACjB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;QACpB,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,IAAI,yBAAyB,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC,CAAC;IACjE,CAAC;AACH,CAAC"}

package/dist/audit/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/audit/report.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAsC,MAAM,YAAY,CAAC;AAyBlF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CA8B1D;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEtD"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/audit/report.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,YAAY,CAAC;AAuDpB,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CA2C1D;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEtD"}

package/dist/audit/report.js

@@ -21,9 +21,38 @@ function renderStaleness(rows) {
     }
     return `${lines.join("\n")}\n`;
 }
+function renderDescribesRefs(rows) {
+    if (rows.length === 0)
+        return "_no broken doc-to-code bindings._\n";
+    const lines = ["| source | target | binding |", "|---|---|---|"];
+    for (const r of rows) {
+        const sym = r.target.symbol ? `::${r.target.symbol}` : "";
+        lines.push(`| ${r.source.repo}/${r.source.path} | ${r.target.repo}/${r.target.path}${sym} | \`${r.raw}\` |`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderSemantic(rows) {
+    // Only non-coherent verdicts are worth surfacing (drifted, contradicted, skipped).
+    const notable = rows.filter((r) => r.verdict !== "coherent");
+    if (notable.length === 0)
+        return "_all checked bindings are coherent._\n";
+    const lines = ["| verdict | source | target | detail |", "|---|---|---|---|"];
+    for (const r of notable) {
+        const sym = r.target.symbol ? `::${r.target.symbol}` : "";
+        const detail = r.verdict === "skipped"
+            ? (r.reason ?? "skipped")
+            : r.contradictions.join("; ") || "(no detail)";
+        lines.push(`| ${r.verdict} | ${r.source.repo}/${r.source.path} | ${r.target.repo}/${r.target.path}${sym} | ${detail} |`);
+    }
+    return `${lines.join("\n")}\n`;
+}
 export function renderMarkdown(report) {
     const t = report.totals;
-    const empty = t.brokenRefs === 0 && t.directlyStale === 0 && t.transitivelyStale === 0;
+    const empty = t.brokenRefs === 0 &&
+        t.directlyStale === 0 &&
+        t.transitivelyStale === 0 &&
+        t.brokenDescribes === 0 &&
+        report.semantic.length === 0;
     const head = [
         "# Coherence Audit Report",
         "",
@@ -36,6 +65,8 @@ export function renderMarkdown(report) {
         `- broken cross-repo refs: **${t.brokenRefs}**`,
         `- directly stale docs: **${t.directlyStale}**`,
         `- transitively stale docs: **${t.transitivelyStale}**`,
+        `- broken doc-to-code bindings: **${t.brokenDescribes}**`,
+        `- doc-to-code semantic drift: **${t.semanticDrifted}**`,
         "",
     ];
     if (empty) {
@@ -50,6 +81,12 @@ export function renderMarkdown(report) {
         "## Staleness",
         "",
         renderStaleness(report.staleness),
+        "## Broken doc-to-code bindings",
+        "",
+        renderDescribesRefs(report.describesRefs),
+        ...(report.semantic.length > 0
+            ? ["## Semantic coherence", "", renderSemantic(report.semantic)]
+            : []),
     ].join("\n");
 }
 export function renderJson(report) {

package/dist/audit/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/audit/report.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/audit/report.ts"],"names":[],"mappings":"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"}

package/dist/audit/semantic.d.ts

@@ -0,0 +1,35 @@
+import type { LlmClient } from "../eval/llm.js";
+import { readTextFile } from "./readtext.js";
+import type { DescribesEdge, RepoSnapshot } from "./types.js";
+export declare const SEMANTIC_VERDICTS: readonly ["coherent", "drifted", "contradicted", "skipped"];
+export type SemanticVerdict = (typeof SEMANTIC_VERDICTS)[number];
+export interface SemanticFinding {
+    source: {
+        repo: string;
+        path: string;
+    };
+    target: {
+        repo: string;
+        path: string;
+        symbol: string | null;
+    };
+    raw: string;
+    verdict: SemanticVerdict;
+    contradictions: string[];
+    reason?: string;
+}
+export interface SemanticDeps {
+    llm: LlmClient;
+    model: string;
+    maxBytes?: number;
+    maxSemantic?: number;
+    readText?: typeof readTextFile;
+    onCap?: (dropped: number) => void;
+}
+export declare const DEFAULT_MAX_SEMANTIC = 200;
+export declare function runSemanticCheck(edges: DescribesEdge[], snapshots: RepoSnapshot[], deps: SemanticDeps): Promise<SemanticFinding[]>;
+export declare function logSemanticTensions(findings: SemanticFinding[], vaultRoot: string, loggedBy: string): Promise<{
+    logged: number;
+    errors: string[];
+}>;
+//# sourceMappingURL=semantic.d.ts.map

package/dist/audit/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/audit/semantic.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,eAAO,MAAM,iBAAiB,6DAA8D,CAAC;AAC7F,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,eAAe,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,YAAY,CAAC;IAC/B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAmDxC,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,aAAa,EAAE,EACtB,SAAS,EAAE,YAAY,EAAE,EACzB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,eAAe,EAAE,CAAC,CAmE5B;AAMD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsB/C"}

package/dist/audit/semantic.js

@@ -0,0 +1,151 @@
+// src/audit/semantic.ts
+// Opt-in (--semantic) LLM drift check for doc-to-code bindings. For each
+// resolvable `describes` edge it reads the declaring doc and the described code
+// file (guarded by readtext.ts) and asks the model whether the doc still
+// accurately describes the code. Reference integrity (checks/describes_refs.ts)
+// already covers missing files; this catches the harder case — the file exists
+// but the doc lies about it.
+//
+// The module never imports the Anthropic SDK: the LlmClient and the reader are
+// injected, so it is fully unit-testable and the default (non-semantic) audit
+// never pulls in the SDK.
+import { addTension } from "../curation/tension.js";
+import { readTextFile } from "./readtext.js";
+export const SEMANTIC_VERDICTS = ["coherent", "drifted", "contradicted", "skipped"];
+export const DEFAULT_MAX_SEMANTIC = 200;
+const SYSTEM_PROMPT = `You audit whether a documentation file accurately describes a source code
+file. You are given the documentation and the code it claims to describe.
+Compare the doc's specific claims (function names, signatures, parameters,
+behavior, error handling) against the code.
+
+Return a verdict:
+  coherent     — the doc accurately describes the code
+  drifted      — the doc is partially out of date; some claims no longer match
+  contradicted — the doc makes claims the code directly contradicts
+
+List the specific claims in the doc that no longer hold (empty when coherent).`;
+// Verdict shape the model is asked to return.
+const VERDICT_SCHEMA = {
+    type: "object",
+    required: ["verdict", "contradictions"],
+    properties: {
+        verdict: { enum: ["coherent", "drifted", "contradicted"] },
+        contradictions: { type: "array", items: { type: "string" } },
+    },
+};
+function buildUser(docPath, docText, codePath, codeText) {
+    return [
+        `Documentation file: ${docPath}`,
+        "```markdown",
+        docText,
+        "```",
+        "",
+        `Source code file: ${codePath}`,
+        "```",
+        codeText,
+        "```",
+    ].join("\n");
+}
+function parseVerdict(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const v = parsed.verdict;
+    const c = parsed.contradictions;
+    if (v !== "coherent" && v !== "drifted" && v !== "contradicted")
+        return null;
+    const contradictions = Array.isArray(c)
+        ? c.filter((x) => typeof x === "string")
+        : [];
+    return { verdict: v, contradictions };
+}
+export async function runSemanticCheck(edges, snapshots, deps) {
+    const readText = deps.readText ?? readTextFile;
+    const maxSemantic = deps.maxSemantic ?? DEFAULT_MAX_SEMANTIC;
+    const byRepo = new Map();
+    for (const snap of snapshots)
+        byRepo.set(snap.config.name, snap);
+    // Only edges whose target file actually exists are semantic candidates —
+    // missing targets are reference-integrity findings (#119), not drift.
+    const resolvable = edges.filter((e) => byRepo.get(e.targetRepo)?.docs.has(e.targetPath));
+    const toProcess = resolvable.slice(0, maxSemantic);
+    if (resolvable.length > toProcess.length) {
+        deps.onCap?.(resolvable.length - toProcess.length);
+    }
+    const findings = [];
+    for (const e of toProcess) {
+        const sourceDoc = byRepo.get(e.sourceRepo)?.docs.get(e.sourcePath);
+        const targetFile = byRepo.get(e.targetRepo)?.docs.get(e.targetPath);
+        const base = {
+            source: { repo: e.sourceRepo, path: e.sourcePath },
+            target: { repo: e.targetRepo, path: e.targetPath, symbol: e.symbol },
+            raw: e.raw,
+        };
+        const skip = (reason) => ({
+            ...base,
+            verdict: "skipped",
+            contradictions: [],
+            reason,
+        });
+        if (!sourceDoc || !targetFile) {
+            findings.push(skip("source or target snapshot unavailable"));
+            continue;
+        }
+        const codeRead = await readText(targetFile.absPath, { maxBytes: deps.maxBytes });
+        if (!codeRead.ok) {
+            findings.push(skip(`code unreadable: ${codeRead.error.reason}`));
+            continue;
+        }
+        const docRead = await readText(sourceDoc.absPath, { maxBytes: deps.maxBytes });
+        if (!docRead.ok) {
+            findings.push(skip(`doc unreadable: ${docRead.error.reason}`));
+            continue;
+        }
+        const res = await deps.llm.completeJson({
+            model: deps.model,
+            system: SYSTEM_PROMPT,
+            user: buildUser(e.sourcePath, docRead.value.text, e.targetPath, codeRead.value.text),
+            schema: VERDICT_SCHEMA,
+        });
+        if (!res.ok) {
+            findings.push(skip(`llm error: ${res.error.message}`));
+            continue;
+        }
+        const verdict = parseVerdict(res.value.parsed);
+        if (!verdict) {
+            findings.push(skip("llm returned an unparseable verdict"));
+            continue;
+        }
+        findings.push({ ...base, verdict: verdict.verdict, contradictions: verdict.contradictions });
+    }
+    return findings;
+}
+// --auto-tension: record drift/contradiction verdicts in the vault's tension
+// log (the same store backing vault_tension_log). Coherent and skipped verdicts
+// are not tensions. Logging is advisory and never edits a doc; a failed append
+// is collected, not thrown.
+export async function logSemanticTensions(findings, vaultRoot, loggedBy) {
+    let logged = 0;
+    const errors = [];
+    for (const f of findings) {
+        if (f.verdict !== "drifted" && f.verdict !== "contradicted")
+            continue;
+        const target = `${f.target.repo}/${f.target.path}`;
+        const res = await addTension(vaultRoot, {
+            title: `Doc-code ${f.verdict}: ${f.source.path} ↔ ${target}`,
+            kind: "factual",
+            sourceA: f.source.path,
+            claimA: f.contradictions.length > 0
+                ? f.contradictions.join("; ")
+                : "doc may no longer match the code it describes",
+            sourceB: target,
+            claimB: `current implementation (audit verdict: ${f.verdict})`,
+            loggedBy,
+        });
+        if (res.ok)
+            logged++;
+        else
+            errors.push(res.error.message);
+    }
+    return { logged, errors };
+}
+//# sourceMappingURL=semantic.js.map

package/dist/audit/semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../../src/audit/semantic.ts"],"names":[],"mappings":"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"}

package/dist/audit/types.d.ts

@@ -1,3 +1,4 @@
+import type { SemanticFinding } from "./semantic.js";
 export type AuditConfig = {
     repos: RepoConfig[];
     output: {
@@ -10,13 +11,17 @@ export type AuditConfig = {
     failOn: {
         brokenRefs: number;
         transitiveStaleness: number;
+        brokenDescribes: number;
     };
 };
+export declare const REPO_TYPES: readonly ["docs", "code"];
+export type RepoType = (typeof REPO_TYPES)[number];
 export type RepoConfig = {
     name: string;
     path: string;
     docsGlob: string;
     urls: string[];
+    type: RepoType;
 };
 export type DocSnapshot = {
     relPath: string;
@@ -25,6 +30,7 @@ export type DocSnapshot = {
     mtimeSource: "git" | "fs";
     headings: Set<string>;
     links: LinkRef[];
+    describes: string[];
 };
 export type LinkRef = {
     rawHref: string;
@@ -45,6 +51,26 @@ export type LinkEdge = {
     targetAnchor: string | null;
     rawHref: string;
 };
+export type DescribesEdge = {
+    sourceRepo: string;
+    sourcePath: string;
+    targetRepo: string;
+    targetPath: string;
+    symbol: string | null;
+    raw: string;
+};
+export type DescribesRefFinding = {
+    source: {
+        repo: string;
+        path: string;
+    };
+    target: {
+        repo: string;
+        path: string;
+        symbol: string | null;
+    };
+    raw: string;
+};
 export type BrokenRefFinding = {
     kind: "missing_file" | "missing_anchor";
     source: {
@@ -78,9 +104,13 @@ export type AuditReport = {
         brokenRefs: number;
         directlyStale: number;
         transitivelyStale: number;
+        brokenDescribes: number;
+        semanticDrifted: number;
     };
     brokenRefs: BrokenRefFinding[];
     staleness: StalenessFinding[];
+    describesRefs: DescribesRefFinding[];
+    semantic: SemanticFinding[];
 };
 export type AuditError = {
     kind: "config";

package/dist/audit/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/audit/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/audit/types.ts"],"names":[],"mappings":"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"}