daftari 1.12.6 → 1.13.1

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.13.1] - 2026-05-30
+
+### Changed
+
+- Expanded README `Coherence audit` section: multi-repo case promoted to the
+  headline, sample output added, transitive staleness defined in plain
+  language, GitHub Actions CI snippet added, exit-code table added, CLI flags
+  documented separately from `audit.yaml`. No code changes — docs only.
+
+## [1.13.0] - 2026-05-30
+
+### Added
+
+- `daftari audit` CLI subcommand. Scans N markdown repos and reports broken
+  cross-repo references and link-graph transitive staleness. Outputs markdown
+  (default: stdout) and optional JSON. Exit code 1 if `fail_on.broken_refs` or
+  `fail_on.transitive_staleness` thresholds are exceeded. Anonymous repos passed
+  via `--repo` get no URL patterns — URL-based cross-refs into them aren't
+  detected; use `--config` with an `urls:` block to enable them. See issue #85.
+
 ## [1.12.6] - 2026-05-27
 
 ### Changed

package/README.md

@@ -164,6 +164,165 @@ Deliberately deferred to keep the surface tight:
 
 Each is a clean increment on a surface that already works.
 
+## Coherence audit
+
+`daftari audit` is a read-only, deterministic check across one or more
+markdown repos for **broken cross-repo references** and **link-graph
+transitive staleness**. It works against any markdown tree — daftari-managed
+or not. The audit creates no `.daftari/` directory and writes nothing to the
+audited repos.
+
+### Multi-repo (the headline use case)
+
+When two or more repos link to each other, the audit detects broken
+references that neither repo's own lint could see — because each repo only
+knows about itself.
+
+```bash
+daftari audit \
+  --repo ~/repos/service-a \
+  --repo ~/repos/service-b
+```
+
+That works for relative-path links (`../service-b/docs/api.md`). For
+GitHub-style URL links between repos (`https://github.com/org/service-b/...`),
+declare each repo's URL patterns in an `audit.yaml` so the resolver can map
+them back to the local repo:
+
+```yaml
+# audit.yaml
+repos:
+  - name: service-a
+    path: ~/repos/service-a
+    urls: ["github.com/org/service-a"]
+  - name: service-b
+    path: ~/repos/service-b
+    urls: ["github.com/org/service-b"]
+```
+
+```bash
+daftari audit --config audit.yaml
+```
+
+### Single repo
+
+The same command, one `--repo`:
+
+```bash
+daftari audit --repo ./docs
+```
+
+In single-repo mode the cross-repo check trivially has no work, but the
+staleness check still runs over the in-repo link graph.
+
+### What gets detected
+
+- **Missing files.** A link from `service-a/intro.md` to `../service-b/api.md`
+  or `https://github.com/org/service-b/blob/main/api.md` — flagged if `api.md`
+  doesn't exist in `service-b`.
+- **Missing anchors.** Same link with `#run` — flagged if `api.md` has no
+  `## Run` heading.
+- **Direct staleness.** Any doc whose git mtime is older than
+  `staleness.threshold_days` (default 540, ~18 months).
+- **Transitive staleness.** A fresh doc that links — directly or through a
+  chain — to a stale doc is itself flagged, with the shortest chain reported.
+  Catches the case where you keep touching an index page while the docs it
+  links to are rotting.
+
+### Sample output
+
+```markdown
+# Coherence Audit Report
+
+## Totals
+- repos scanned: **2**
+- docs scanned: **47**
+- broken cross-repo refs: **2**
+- directly stale docs: **3**
+- transitively stale docs: **5**
+
+## Broken cross-repo references
+| kind           | source                    | target                  | href |
+|----------------|---------------------------|-------------------------|------|
+| missing_anchor | service-a/intro.md        | service-b/api.md#run    | `https://github.com/org/service-b/blob/main/api.md#run` |
+| missing_file   | service-a/architecture.md | service-b/deleted.md    | `../service-b/deleted.md` |
+
+## Staleness
+| kind       | doc                      | mtime      | chain |
+|------------|--------------------------|------------|-------|
+| transitive | service-a/onboarding.md  | 2026-04-01 | service-a/onboarding.md → service-b/legacy-flow.md |
+```
+
+JSON output (`--output-json` or `output.json` in config) carries the same
+structure with full detail in `brokenRefs[]` and `staleness[]` arrays plus a
+`totals` summary block for compact downstream rendering.
+
+### CI integration
+
+The audit's exit code is designed to gate CI:
+
+```yaml
+# .github/workflows/docs-audit.yml
+name: Docs audit
+on: [pull_request]
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }   # full history so git mtime works
+      - run: npx daftari@latest audit --config audit.yaml
+```
+
+Exit codes:
+
+| code | meaning |
+|------|---------|
+| `0`  | clean run, all findings within `fail_on` thresholds |
+| `1`  | clean run but a threshold was exceeded — CI fails |
+| `2`  | config error (missing required fields, bad paths, malformed YAML) |
+| `3`  | runtime error (IO failure during collection) |
+
+### CLI flags
+
+`audit.yaml` and CLI flags overlap; CLI wins. A warning is printed to stderr
+when `--output` or `--output-json` displaces a value from the config.
+
+- `--repo <path>` — add a repo. May be repeated. Anonymous CLI repos get no
+  URL patterns; URL-based cross-refs into them won't be detected. Use
+  `--config` for URL-aware repos.
+- `--config <path>` — load an `audit.yaml`.
+- `--output <md>` — markdown report destination (default: stdout).
+- `--output-json <json>` — JSON report destination (default: not written).
+- `--help` — full help text.
+
+### Full `audit.yaml` schema
+
+```yaml
+repos:
+  - name: service-a
+    path: ~/repos/service-a
+    docs_glob: "docs/**/*.md"       # default: "**/*.md"
+    urls:                            # optional; enables URL-pattern matching
+      - "github.com/org/service-a"
+
+  - name: service-b
+    path: ~/repos/service-b
+    urls:
+      - "github.com/org/service-b"
+
+output:
+  markdown: coherence-report.md      # default: stdout
+  json: coherence-report.json        # default: not emitted
+
+staleness:
+  threshold_days: 540                # default: 540 (18 months)
+
+fail_on:
+  broken_refs: 1                     # default: fail on any broken ref
+  transitive_staleness: 100          # default: generous; teams tune
+```
+
 ## Development
 
 ```
@@ -181,6 +340,13 @@ Design tenets: functions and types, no classes; tool handlers return
 - <docs/architecture.md> — layered design, request path, accumulation vs. generative domains
 - <docs/file-format.md> — complete frontmatter reference
 
+## Integrations
+
+- [`integrations/langchain/`](integrations/langchain/) — `langchain-daftari`, a
+  Python package that exposes the 14 daftari tools as LangChain `BaseTool`s
+  for use with LangGraph / `create_react_agent`. Sync + async, schemas pulled
+  live from `tools/list`.
+
 ## Privacy
 
 Daftari is a local MCP server. It runs on your machine, against vault files on

package/dist/audit/checks/broken_refs.d.ts

@@ -0,0 +1,3 @@
+import type { BrokenRefFinding, LinkEdge, RepoSnapshot } from "../types.js";
+export declare function checkBrokenRefs(snapshots: RepoSnapshot[], edges: LinkEdge[]): BrokenRefFinding[];
+//# sourceMappingURL=broken_refs.d.ts.map

package/dist/audit/checks/broken_refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broken_refs.d.ts","sourceRoot":"","sources":["../../../src/audit/checks/broken_refs.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,gBAAgB,EAAE,CA0DhG"}

package/dist/audit/checks/broken_refs.js

@@ -0,0 +1,67 @@
+// src/audit/checks/broken_refs.ts
+// Pure function: given snapshots and classified edges, return every broken
+// reference as a BrokenRefFinding. No throws. No classes.
+//
+// Resolution logic:
+//   1. Look up target repo by name; if not found → missing_file.
+//   2. Look up targetPath in that repo's docs Map.
+//   3. If not found and targetPath lacks a ".md" extension, try targetPath +
+//      ".md" (spec §7 bare-path fallback).
+//   4. If still not found → missing_file.
+//   5. If found and targetAnchor is set: check DocSnapshot.headings. If absent
+//      → missing_anchor.
+export function checkBrokenRefs(snapshots, edges) {
+    // Index snapshots by repo name for O(1) lookup.
+    const byRepo = new Map();
+    for (const snap of snapshots) {
+        byRepo.set(snap.config.name, snap);
+    }
+    const findings = [];
+    for (const edge of edges) {
+        const targetSnap = byRepo.get(edge.targetRepo);
+        if (!targetSnap) {
+            // Target repo itself is unknown — treat as missing file.
+            findings.push({
+                kind: "missing_file",
+                source: { repo: edge.sourceRepo, path: edge.sourcePath },
+                target: { repo: edge.targetRepo, path: edge.targetPath, anchor: edge.targetAnchor },
+                rawHref: edge.rawHref,
+            });
+            continue;
+        }
+        // Resolve the target doc: exact match, then .md fallback.
+        let resolvedPath = null;
+        if (targetSnap.docs.has(edge.targetPath)) {
+            resolvedPath = edge.targetPath;
+        }
+        else if (!edge.targetPath.endsWith(".md")) {
+            const withMd = `${edge.targetPath}.md`;
+            if (targetSnap.docs.has(withMd)) {
+                resolvedPath = withMd;
+            }
+        }
+        if (resolvedPath === null) {
+            findings.push({
+                kind: "missing_file",
+                source: { repo: edge.sourceRepo, path: edge.sourcePath },
+                target: { repo: edge.targetRepo, path: edge.targetPath, anchor: edge.targetAnchor },
+                rawHref: edge.rawHref,
+            });
+            continue;
+        }
+        // File found. Check anchor if present.
+        if (edge.targetAnchor !== null) {
+            const doc = targetSnap.docs.get(resolvedPath);
+            if (doc && !doc.headings.has(edge.targetAnchor)) {
+                findings.push({
+                    kind: "missing_anchor",
+                    source: { repo: edge.sourceRepo, path: edge.sourcePath },
+                    target: { repo: edge.targetRepo, path: resolvedPath, anchor: edge.targetAnchor },
+                    rawHref: edge.rawHref,
+                });
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=broken_refs.js.map

package/dist/audit/checks/broken_refs.js.map

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

package/dist/audit/checks/staleness.d.ts

@@ -0,0 +1,3 @@
+import type { LinkEdge, RepoSnapshot, StalenessFinding } from "../types.js";
+export declare function checkStaleness(snapshots: RepoSnapshot[], edges: LinkEdge[], thresholdDays: number, now: Date): StalenessFinding[];
+//# sourceMappingURL=staleness.d.ts.map

package/dist/audit/checks/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../../../src/audit/checks/staleness.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAY5E,wBAAgB,cAAc,CAC5B,SAAS,EAAE,YAAY,EAAE,EACzB,KAAK,EAAE,QAAQ,EAAE,EACjB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,IAAI,GACR,gBAAgB,EAAE,CAsGpB"}

package/dist/audit/checks/staleness.js

@@ -0,0 +1,114 @@
+// src/audit/checks/staleness.ts
+// Memoized BFS from each fresh doc to the nearest directly-stale leaf. BFS
+// (not DFS) so the recorded chain is the shortest path. Cycles handled by
+// the BFS visited set; verdicts memoized across roots.
+const key = (repo, path) => `${repo} ${path}`;
+function isDirectlyStale(mtimeIso, now, thresholdDays) {
+    const ms = now.getTime() - new Date(mtimeIso).getTime();
+    return ms > thresholdDays * 86_400_000;
+}
+export function checkStaleness(snapshots, edges, thresholdDays, now) {
+    const nodes = new Map();
+    for (const snap of snapshots) {
+        for (const d of snap.docs.values()) {
+            nodes.set(key(snap.config.name, d.relPath), {
+                repo: snap.config.name,
+                path: d.relPath,
+                mtime: d.mtime,
+            });
+        }
+    }
+    const adj = new Map();
+    for (const edge of edges) {
+        const src = key(edge.sourceRepo, edge.sourcePath);
+        const dst = key(edge.targetRepo, edge.targetPath);
+        // Resolve the dst against the .md-extension fallback so transitive edges
+        // see the same node identity broken-refs check does.
+        let dstKey = dst;
+        if (!nodes.has(dstKey)) {
+            const alt = key(edge.targetRepo, `${edge.targetPath}.md`);
+            if (nodes.has(alt))
+                dstKey = alt;
+        }
+        if (!nodes.has(dstKey))
+            continue; // dangling edge — broken_refs handles it
+        if (!nodes.has(src))
+            continue;
+        const list = adj.get(src) ?? [];
+        list.push(dstKey);
+        adj.set(src, list);
+    }
+    // Classify directly stale leaves.
+    const direct = new Set();
+    for (const [k, info] of nodes) {
+        if (isDirectlyStale(info.mtime, now, thresholdDays))
+            direct.add(k);
+    }
+    // BFS from each fresh root to find shortest path to a stale node.
+    // Memoize the shortest chain per node so a second root reaching it
+    // doesn't recompute.
+    const shortestChain = new Map(); // null = no stale path
+    function chainFor(root) {
+        if (direct.has(root))
+            return null; // direct, not transitive
+        if (shortestChain.has(root))
+            return shortestChain.get(root) ?? null;
+        const prev = new Map();
+        prev.set(root, null);
+        const queue = [root];
+        let target = null;
+        while (queue.length > 0) {
+            const cur = queue.shift();
+            if (cur !== root && direct.has(cur)) {
+                target = cur;
+                break;
+            }
+            for (const next of adj.get(cur) ?? []) {
+                if (prev.has(next))
+                    continue;
+                prev.set(next, cur);
+                queue.push(next);
+            }
+        }
+        if (!target) {
+            shortestChain.set(root, null);
+            return null;
+        }
+        const path = [];
+        let n = target;
+        while (n) {
+            path.unshift(n);
+            n = prev.get(n) ?? null;
+        }
+        const chain = path.map((k) => {
+            const info = nodes.get(k);
+            return { repo: info.repo, path: info.path, mtime: info.mtime };
+        });
+        shortestChain.set(root, chain);
+        return chain;
+    }
+    const findings = [];
+    for (const [k, info] of nodes) {
+        if (direct.has(k)) {
+            findings.push({
+                kind: "direct",
+                repo: info.repo,
+                path: info.path,
+                mtime: info.mtime,
+            });
+            continue;
+        }
+        const chain = chainFor(k);
+        if (chain) {
+            findings.push({
+                kind: "transitive",
+                repo: info.repo,
+                path: info.path,
+                mtime: info.mtime,
+                staleChain: chain,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/audit/checks/staleness.js.map

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

package/dist/audit/collect.d.ts

@@ -0,0 +1,4 @@
+import { type Result } from "../frontmatter/types.js";
+import type { AuditConfig, AuditError, RepoSnapshot } from "./types.js";
+export declare function collectRepos(config: AuditConfig): Promise<Result<RepoSnapshot[], AuditError>>;
+//# sourceMappingURL=collect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/audit/collect.ts"],"names":[],"mappings":"AAWA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAA2B,YAAY,EAAE,MAAM,YAAY,CAAC;AAoHjG,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,UAAU,CAAC,CAAC,CAa7C"}

package/dist/audit/collect.js

@@ -0,0 +1,134 @@
+// src/audit/collect.ts
+// The only IO stage of the audit pipeline. Per repo: glob docs, strip
+// frontmatter, extract headings (GitHub-slugged) and links, then batch
+// git log to populate mtimes; on any git failure, fall back to fs mtime.
+import { execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve as nodeResolve } from "node:path";
+import { glob } from "glob";
+import matter from "gray-matter";
+import { err, ok } from "../frontmatter/types.js";
+import { extractLinksFromBody } from "./links.js";
+import { runtimeError } from "./types.js";
+function slugify(heading) {
+    // GitHub slug: lowercase, strip non-alphanumeric (keep `-_`), whitespace -> `-`.
+    return heading
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9\-_]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function extractHeadings(body) {
+    const out = new Set();
+    for (const line of body.split(/\r?\n/)) {
+        const m = line.match(/^#{1,6}\s+(.+?)\s*#*\s*$/);
+        if (m)
+            out.add(slugify(m[1]));
+    }
+    return out;
+}
+function gitMtimes(repoPath, docsGlob) {
+    const opts = {
+        cwd: repoPath,
+        maxBuffer: 256 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+    };
+    try {
+        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], opts);
+    }
+    catch {
+        return null;
+    }
+    let out;
+    try {
+        // Use the :(glob) pathspec magic so git's internal glob matcher handles
+        // "**/*.md" correctly on all platforms and git configurations, including
+        // matching top-level files (bare "**/*.md" without the magic prefix skips
+        // files at depth 0 on some git versions).
+        const pathspec = docsGlob.startsWith(":(") ? docsGlob : `:(glob)${docsGlob}`;
+        out = execFileSync("git", ["log", "--all", "--name-only", `--pretty=format:COMMIT %aI`, "--", pathspec], opts).toString();
+    }
+    catch {
+        return null;
+    }
+    const mtimes = new Map();
+    let currentIso = null;
+    for (const line of out.split("\n")) {
+        if (line.startsWith("COMMIT ")) {
+            currentIso = line.slice("COMMIT ".length).trim() || null;
+            continue;
+        }
+        const path = line.trim();
+        if (!path || !currentIso)
+            continue;
+        // First time we see a path is its newest commit (git log is newest-first).
+        if (!mtimes.has(path))
+            mtimes.set(path, currentIso);
+    }
+    return mtimes;
+}
+async function loadDoc(repoPath, relPath, mtimeFromGit) {
+    const absPath = nodeResolve(repoPath, relPath);
+    const text = await readFile(absPath, "utf-8");
+    const parsed = matter(text);
+    const body = parsed.content;
+    let mtime;
+    let mtimeSource;
+    if (mtimeFromGit) {
+        mtime = mtimeFromGit;
+        mtimeSource = "git";
+    }
+    else {
+        mtime = statSync(absPath).mtime.toISOString();
+        mtimeSource = "fs";
+    }
+    return {
+        relPath: relPath.split(/[\\/]/).join("/"),
+        absPath,
+        mtime,
+        mtimeSource,
+        headings: extractHeadings(body),
+        links: extractLinksFromBody(body),
+    };
+}
+async function collectOne(config) {
+    const files = await glob(config.docsGlob, {
+        cwd: config.path,
+        nodir: true,
+        posix: true,
+        dot: false,
+    });
+    const onlyMd = files.filter((f) => /\.(md|markdown)$/i.test(f));
+    const mtimes = gitMtimes(config.path, config.docsGlob);
+    const docs = new Map();
+    for (const rel of onlyMd) {
+        const posixRel = rel.split(/[\\/]/).join("/");
+        try {
+            const snap = await loadDoc(config.path, posixRel, mtimes?.get(posixRel));
+            docs.set(posixRel, snap);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`daftari audit: warning: unreadable doc ${posixRel}: ${msg}\n`);
+        }
+    }
+    return { config, docs };
+}
+export async function collectRepos(config) {
+    // Sequential per-repo; concurrency would help but is out of scope until the
+    // 30s budget gets squeezed (see plan §perf).
+    const out = [];
+    for (const r of config.repos) {
+        try {
+            out.push(await collectOne(r));
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            return err(runtimeError(`collect failed for repo ${r.name}: ${reason}`));
+        }
+    }
+    return ok(out);
+}
+//# sourceMappingURL=collect.js.map

package/dist/audit/collect.js.map

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

package/dist/audit/config.d.ts

@@ -0,0 +1,4 @@
+import { type Result } from "../frontmatter/types.js";
+import { type AuditConfig, type AuditError } from "./types.js";
+export declare function parseAuditConfig(argv: string[], yamlLoader?: (path: string) => string): Result<AuditConfig, AuditError>;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/audit/config.ts"],"names":[],"mappings":"AAQA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAgC,MAAM,YAAY,CAAC;AAsG7F,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACpC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAwFjC"}