docguard-cli 0.31.0 → 0.33.0

package/cli/validators/cross-reference.mjs

@@ -8,6 +8,13 @@
  *   - Markdown relative links:        [text](./OTHER.md)
  *                                     [text](./OTHER.md#anchor)
  *                                     [text](#anchor-in-same-doc)
+ *                                     [text](<path with spaces.md>)
+ *   - Obsidian wikilinks:             [[OTHER]]  [[OTHER#Heading]]  [[OTHER|alias]]
+ *     Validated only when the repo shows wikilinks-are-files evidence
+ *     (`.obsidian/` exists, or at least one wikilink target resolves) — some
+ *     repos use [[name]] as a non-file convention (template placeholders,
+ *     memory links) and must not be flagged. Image embeds `![[x.png]]` are
+ *     never treated as doc links.
  *   - Bare anchor refs:               see §3.2 ARCHITECTURE.md
  *                                     (Section 3.2 in DATA-MODEL.md)
  *   - Bracketed section refs:         [Section X.Y]
@@ -29,6 +36,8 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname, basename, relative } from 'node:path';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { resolveDocDirs } from '../shared.mjs';
+import { walkFiles } from '../shared-ignore.mjs';
 
 /**
  * Slugify a heading the way GitHub's markdown anchors work.
@@ -112,8 +121,13 @@ export function extractRefs(content, sourcePath) {
   //   ./RELATIVE.md
   //   ../OTHER.md#anchor
   //   #intra-doc-anchor
+  //   <path with spaces.md>   (CommonMark angle-bracket form)
   // We DON'T match http(s) targets here.
   const markdownLinkRe = /\[([^\]]+)\]\(((?!https?:|mailto:)[^)]+)\)/g;
+  // [[Target]] / [[Target#Heading]] / [[Target|alias]]. The (?<!!) guard
+  // excludes Obsidian image embeds ![[img.png]] — an embed is content, not a
+  // doc cross-reference.
+  const wikiLinkRe = /(?<!!)\[\[([^\]|#\n]+)(?:#([^\]|\n]*))?(?:\|[^\]\n]*)?\]\]/g;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -130,8 +144,14 @@ export function extractRefs(content, sourcePath) {
     markdownLinkRe.lastIndex = 0;
     while ((m = markdownLinkRe.exec(stripped)) !== null) {
       const target = m[2].trim();
-      // Drop any title text: [foo](bar "title") → bar
-      const cleanTarget = target.split(/\s+/)[0];
+      let cleanTarget;
+      if (target.startsWith('<') && target.includes('>')) {
+        // Angle-bracket form: the target is everything inside <…>, spaces allowed.
+        cleanTarget = target.slice(1, target.indexOf('>'));
+      } else {
+        // Drop any title text: [foo](bar "title") → bar
+        cleanTarget = target.split(/\s+/)[0];
+      }
       const hashIdx = cleanTarget.indexOf('#');
       let file, anchor;
       if (hashIdx === 0) {
@@ -145,13 +165,55 @@ export function extractRefs(content, sourcePath) {
         file = cleanTarget;
         anchor = null;
       }
+      // `./repo.md?x=1#setup` targets repo.md — the query never names a file.
+      if (file) file = file.split('?')[0];
       refs.push({ source: sourcePath, file, anchor, raw: m[0], line: i + 1 });
     }
+
+    wikiLinkRe.lastIndex = 0;
+    while ((m = wikiLinkRe.exec(stripped)) !== null) {
+      const target = m[1].trim();
+      if (!target) continue;
+      const anchor = m[2] !== undefined ? m[2].trim() : null;
+      refs.push({ source: sourcePath, file: target, anchor: anchor || null, raw: m[0], line: i + 1, wiki: true });
+    }
   }
 
   return refs;
 }
 
+/**
+ * Basename-stem → path index of every markdown file in the project's doc
+ * homes plus the already-collected canonical docs. Obsidian resolves
+ * wikilinks vault-wide by basename; this is the named-doc-dirs equivalent
+ * (never an arbitrary-subdir walk).
+ */
+function buildWikiIndex(projectDir, config, docs) {
+  const idx = new Map();
+  const add = (p) => {
+    const stem = basename(p).replace(/\.mdx?$/i, '').toLowerCase();
+    if (!idx.has(stem)) idx.set(stem, p);
+  };
+  for (const d of docs) add(d);
+  for (const d of resolveDocDirs(projectDir, config)) {
+    const abs = resolve(projectDir, d);
+    if (!existsSync(abs)) continue;
+    walkFiles(abs, (full) => { if (/\.mdx?$/i.test(full)) add(full); });
+  }
+  return idx;
+}
+
+/** Resolve a wikilink target: sibling path, project root, then vault index. */
+function resolveWikiTarget(sourcePath, target, projectDir, wikiIndex) {
+  const withExt = /\.mdx?$/i.test(target) ? target : `${target}.md`;
+  for (const base of [dirname(sourcePath), projectDir]) {
+    const p = resolve(base, withExt);
+    if (existsSync(p)) return p;
+  }
+  const stem = basename(withExt).replace(/\.mdx?$/i, '').toLowerCase();
+  return wikiIndex.get(stem) || null;
+}
+
 /**
  * Resolve a target file path relative to a source markdown file.
  * Returns the absolute path or null if the file doesn't exist.
@@ -297,9 +359,10 @@ function collectCanonicalDocs(projectDir) {
  * errors/warnings arrays from the same findings, so counts, exit codes, and
  * existing tests are unaffected; guard just renders richer output.
  */
-export function validateCrossReferences(projectDir, _config = {}) {
+export function validateCrossReferences(projectDir, config = {}) {
   const findings = [];
   const fixes = [];
+  const wikiRefs = []; // validated in a second pass — evidence gate needs the full set
   let passed = 0;
   let total = 0;
 
@@ -328,6 +391,10 @@ export function validateCrossReferences(projectDir, _config = {}) {
     const docName = basename(docPath);
 
     for (const ref of refs) {
+      if (ref.wiki) {
+        wikiRefs.push({ ...ref, docPath, docName });
+        continue;
+      }
       total++;
 
       // Resolve the target file (if any)
@@ -411,6 +478,60 @@ export function validateCrossReferences(projectDir, _config = {}) {
     }
   }
 
+  // ── Wikilink pass — only when the repo demonstrably uses [[x]] as FILE
+  // links: `.obsidian/` exists, or at least one wikilink target resolves.
+  // Repos using [[name]] as a non-file convention are skipped silently.
+  if (wikiRefs.length > 0) {
+    const wikiIndex = buildWikiIndex(projectDir, config, docs);
+    const resolved = wikiRefs.map(r => ({
+      r,
+      path: resolveWikiTarget(r.docPath, r.file, projectDir, wikiIndex),
+    }));
+    const evidence = existsSync(resolve(projectDir, '.obsidian')) || resolved.some(x => x.path);
+    if (evidence) {
+      for (const { r, path } of resolved) {
+        total++;
+        if (!path) {
+          findings.push(mkFinding({
+            code: 'XRF001',
+            validator: 'crossReference',
+            severity: 'warn',
+            message: `${r.docName}:${r.line} — broken wikilink: target "[[${r.file}]]" not found`,
+            location: `${relative(projectDir, r.docPath)}:${r.line}`,
+            suggestion: { kind: 'fix', text: 'Fix the wikilink target (or remove the dead link)' },
+          }));
+          continue;
+        }
+        if (r.anchor) {
+          let anchors = anchorIndex.get(path);
+          if (!anchors) {
+            try {
+              anchors = new Set(extractHeadings(readFileSync(path, 'utf-8')).map(h => h.anchor));
+            } catch { anchors = new Set(); }
+            anchorIndex.set(path, anchors);
+          }
+          // Obsidian anchors are heading TEXT ([[Doc#Quick Start]]); compare
+          // through the same slug pipeline as inline links.
+          const normalized = slugifyHeading(r.anchor);
+          if (!anchors.has(normalized) && !anchors.has(r.anchor)) {
+            const suggestion = suggestAnchor(normalized, anchors);
+            const hint = suggestion ? ` (did you mean #${suggestion}?)` : '';
+            findings.push(mkFinding({
+              code: 'XRF002',
+              validator: 'crossReference',
+              severity: 'warn',
+              message: `${r.docName}:${r.line} — broken anchor: "[[${r.file}#${r.anchor}]]" doesn't match any heading in ${basename(path)}${hint}`,
+              location: `${relative(projectDir, r.docPath)}:${r.line}`,
+              suggestion: { kind: 'review', text: 'Update the wikilink heading to match a real heading in the target doc' },
+            }));
+            continue;
+          }
+        }
+        passed++;
+      }
+    }
+  }
+
   return { ...resultFromFindings(findings, { passed, total }), fixes };
 }
 

package/cli/validators/docs-coverage.mjs

@@ -43,6 +43,11 @@ const COMMON_DOTFILES = new Set([
   '.babelrc', '.browserslistrc', '.stylelintrc',
   '.dockerignore', '.python-version', '.tool-versions', '.ruby-version',
   '.gitkeep', '.keep',
+  // DocGuard's own files — self-explanatory (embedded _comment / schema),
+  // and flagging them creates a warning the moment a team adopts the tool
+  // (e.g. `guard --update-baseline` writing the baseline instantly produced
+  // a DCV001 about the baseline file itself).
+  '.docguard.json', '.docguardignore', '.docguard.baseline.json',
 ]);
 
 // Generated tool artifacts (caches, coverage data, lock-data) that land at the

package/cli/validators/reference-existence.mjs

@@ -27,14 +27,24 @@
  *     mode (b) ("literal deleted but logic remains") is bounded by compound
  *     shape + the two-revision gate.
  * All findings are confidence:'low' / soft — "verify", never a hard failure.
+ *
+ * REF002 (ADR citations, the code→doc direction): a code comment citing
+ * `ADR-NNN` is a reference into the docs — if no ADR document defines that
+ * number, the citation is stale (renumbered, removed, or never written).
+ * ADRs have no external registry, so a missing number is a real signal.
+ * RFC citations are deliberately OUT of scope: `RFC 793` in a comment almost
+ * always cites the IETF registry (external, unverifiable) and would
+ * false-positive on every network stack. Numbers compare as integers, so
+ * `ADR-00NN` in code matches `ADR-NN` in docs.
  */
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { resolve, extname } from 'node:path';
+import { resolve, extname, relative, basename } from 'node:path';
 import { isGitRepo, lastCommitHash, symbolExistsAtRev } from '../shared-git.mjs';
-import { walkFiles } from '../shared-ignore.mjs';
+import { walkFiles, isNonProductPath } from '../shared-ignore.mjs';
 import { readScannable } from '../shared-source.mjs';
-import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { resolveDocDirs } from '../shared.mjs';
+import { mkFinding, resultFromFindings, lineSuppresses } from '../findings.mjs';
 
 const CODE_EXT = new Set([
   '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java',
@@ -51,17 +61,93 @@ function isCodeIdentifier(s) {
   return COMPOUND.test(s);
 }
 
-// One pass over the current source tree → Set of every whole identifier present.
-function buildHeadIdentifierSet(projectDir) {
-  const set = new Set();
-  walkFiles(projectDir, (full) => {
-    if (!CODE_EXT.has(extname(full))) return;
-    const content = readScannable(full);
-    if (!content) return;
-    const m = content.match(IDENT);
-    if (m) for (const id of m) set.add(id);
-  });
-  return set;
+// ── REF002 helpers ──────────────────────────────────────────────────────────
+
+// Uppercase-only by design: teams cite decision records as "ADR-NNN" / "ADR NN";
+// lowercase "adr" is too often an abbreviation for something else.
+const ADR_CITE_SRC = String.raw`\bADR[- ]?(\d{1,5})\b`;
+
+/**
+ * Index of the comment portion of a code line, or -1 when the line has no
+ * comment. A citation only counts when it sits inside a comment — `ADR-NN`
+ * in a string literal or identifier is data, not a citation. Whole-line
+ * comments (incl. `*` block-comment continuations) count from column 0;
+ * trailing comments are recognised by their marker. ` # ` requires spacing so
+ * `"#fff"`-style literals don't read as Python/shell comments.
+ */
+function commentIndex(line) {
+  const t = line.trimStart();
+  if (/^(\/\/|\/\*|\*|#|--|<!--)/.test(t)) return 0;
+  let idx = -1;
+  for (const marker of ['//', '/*', '<!--', ' # ', ' -- ']) {
+    const i = line.indexOf(marker);
+    if (i >= 0 && (idx < 0 || i < idx)) idx = i;
+  }
+  return idx;
+}
+
+/** Collect ADR citations found in comments of one source file. */
+function collectAdrCitations(content, relPath, out) {
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.includes('ADR')) continue;
+    const ci = commentIndex(line);
+    if (ci < 0) continue;
+    const re = new RegExp(ADR_CITE_SRC, 'g'); // local: shared stateful g-regexes are a footgun
+    let m;
+    while ((m = re.exec(line)) !== null) {
+      if (m.index < ci) continue;
+      if (lineSuppresses('REF002', line, lines[i - 1] || '')) continue;
+      out.push({ num: parseInt(m[1], 10), raw: m[0], file: relPath, line: i + 1 });
+    }
+  }
+}
+
+/**
+ * Discover which ADR numbers the project's docs actually define.
+ * Sources, in decreasing specificity:
+ *   - files/dirs named after ADRs (`ADR.md`, `docs/adr/`, `docs/decisions/`):
+ *     every ADR-NNN mention counts, plus madr-style numeric filenames
+ *     (`0001-use-postgres.md`);
+ *   - any other markdown in a doc home: heading lines only (`## ADR-NNN: …`),
+ *     so a prose mention ("see ADR-NN") never counts as a definition.
+ */
+function collectAdrNumbers(projectDir, config) {
+  const nums = new Set();
+  const addAll = (text) => {
+    for (const m of text.matchAll(new RegExp(ADR_CITE_SRC, 'g'))) nums.add(parseInt(m[1], 10));
+  };
+  const files = new Set();
+  try {
+    for (const f of readdirSync(projectDir)) {
+      if (f.endsWith('.md')) files.add(resolve(projectDir, f));
+    }
+  } catch { /* unreadable root */ }
+  for (const d of resolveDocDirs(projectDir, config)) {
+    const abs = resolve(projectDir, d);
+    if (!existsSync(abs)) continue;
+    walkFiles(abs, (full) => { if (full.endsWith('.md')) files.add(full); });
+  }
+  for (const full of files) {
+    let content;
+    try { content = readFileSync(full, 'utf-8'); } catch { continue; }
+    const base = basename(full);
+    const norm = full.replace(/\\/g, '/');
+    const isAdrHome = /adr/i.test(base) || /\/(adrs?|decisions?)\//i.test(norm);
+    const numericName = base.match(/^(\d{1,5})[-_.]/);
+    if (isAdrHome && numericName) nums.add(parseInt(numericName[1], 10));
+    const adrInName = base.match(/adr[-_ ]?(\d{1,5})/i);
+    if (adrInName) nums.add(parseInt(adrInName[1], 10));
+    if (isAdrHome) {
+      addAll(content);
+    } else {
+      for (const line of content.split('\n')) {
+        if (/^#{1,6}\s/.test(line)) addAll(line);
+      }
+    }
+  }
+  return nums;
 }
 
 function extractRefs(content) {
@@ -100,16 +186,44 @@ function indexDocs(projectDir) {
 export function validateReferenceExistence(projectDir, config = {}) {
   const cfg = config.referenceExistence || {};
   const maxRefsPerDoc = cfg.maxRefsPerDoc || 80;
+  const adrEnabled = cfg.adrCitations !== false;
 
   if (!isGitRepo(projectDir)) {
     return resultFromFindings([], { passed: 0, total: 0, applicable: false });
   }
   const docs = indexDocs(projectDir);
-  if (docs.length === 0 || docs.every(d => d.refs.length === 0)) {
+  const needIds = docs.some(d => d.refs.length > 0);
+  if (!needIds && !adrEnabled) {
+    return resultFromFindings([], { passed: 0, total: 0, applicable: false });
+  }
+
+  // ONE walk over the source tree serves both checks: the REF001 identifier
+  // set and the REF002 ADR-citation scan. Each part is skipped when its check
+  // has nothing to do, so the walk stays as cheap as before for either alone.
+  const headIds = new Set();
+  const citations = [];
+  walkFiles(projectDir, (full) => {
+    if (!CODE_EXT.has(extname(full))) return;
+    const content = readScannable(full);
+    if (!content) return;
+    if (needIds) {
+      const m = content.match(IDENT);
+      if (m) for (const id of m) headIds.add(id);
+    }
+    if (adrEnabled && content.includes('ADR')) {
+      // Tests/fixtures/examples cite ADRs as fixture data, not as real
+      // citations — same non-product scoping the surface scanners use.
+      const rel = relative(projectDir, full);
+      if (!isNonProductPath(rel.replace(/\\/g, '/'), config)) {
+        collectAdrCitations(content, rel, citations);
+      }
+    }
+  });
+
+  if (!needIds && citations.length === 0) {
     return resultFromFindings([], { passed: 0, total: 0, applicable: false });
   }
 
-  const headIds = buildHeadIdentifierSet(projectDir); // cheap gate, built once
   const revPresence = new Map(); // `${sym}\0${rev}` → bool
   // Authoritative HEAD absence (covers dot-dirs the walk skipped). Cached.
   const headAbsent = new Map();
@@ -147,9 +261,49 @@ export function validateReferenceExistence(projectDir, config = {}) {
     }
   }
 
+  // ── REF002: every distinct cited ADR number is one check ──
+  const MAX_ADR_FINDINGS = 10; // calm cap — a flood means a systemic numbering change, not 40 separate problems
+  let adrDistinct = 0;
+  let adrMissing = 0;
+  if (adrEnabled && citations.length > 0) {
+    const known = collectAdrNumbers(projectDir, config);
+    const byNum = new Map(); // num → [{raw, file, line}]
+    for (const c of citations) {
+      if (!byNum.has(c.num)) byNum.set(c.num, []);
+      byNum.get(c.num).push(c);
+    }
+    adrDistinct = byNum.size;
+    for (const [num, locs] of byNum) {
+      if (known.has(num)) continue;
+      adrMissing++;
+      if (adrMissing > MAX_ADR_FINDINGS) continue;
+      const first = locs[0];
+      const where = `${first.file}:${first.line}${locs.length > 1 ? ` (+${locs.length - 1} more)` : ''}`;
+      const message = known.size > 0
+        ? `Code cites ${first.raw} (${where}) but no ADR document defines that number — renumbered, removed, or never written.`
+        : `Code cites ${first.raw} (${where}) but the repo has no ADR documents — the decision record it points to is missing.`;
+      findings.push(mkFinding({
+        code: 'REF002',
+        validator: 'reference-existence',
+        severity: 'warn',
+        confidence: 'low',
+        message,
+        location: { file: first.file, line: first.line },
+        suggestion: {
+          summary: known.size > 0
+            ? `Fix the number or write the missing ADR entry (or suppress with // docguard:ignore REF002 on the citation line).`
+            : `Create an ADR doc (docguard init writes templates/ADR.md) or suppress with // docguard:ignore REF002.`,
+        },
+      }));
+    }
+  }
+
+  // A missing number beyond the finding cap is still a failed check.
+  const total = totalChecked + adrDistinct;
+  const overCap = Math.max(0, adrMissing - MAX_ADR_FINDINGS);
   const res = resultFromFindings(findings, {
-    passed: totalChecked - findings.length,
-    total: totalChecked,
+    passed: total - findings.length - overCap,
+    total,
     applicable: true,
   });
   res.absentAtHead = absentAtHead; // instrumentation: proves the pipeline reaches the rev check

package/cli/validators/traceability.mjs

@@ -21,6 +21,56 @@ import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { tokenize } from '../shared-diff.mjs';
 import { rankBySimilarity } from '../shared-ir.mjs';
 
+/**
+ * Optional graphify interop (github.com/Graphify-Labs/graphify, MIT).
+ * Teams that commit `graphify-out/graph.json` already carry a knowledge graph
+ * whose CODE side is deterministic tree-sitter extraction. If it's there, its
+ * doc↔code edges are one more linkage-evidence source for traceability.
+ *
+ * Trust rules (the determinism anchor):
+ *   - ONLY edges tagged confidence:"EXTRACTED" count — INFERRED/AMBIGUOUS
+ *     edges can come from graphify's LLM pass and must not vouch for a doc.
+ *   - Evidence-only: this can turn a would-be "unlinked doc" into a pass;
+ *     it never produces a finding.
+ *   - Zero-dep: one JSON read. Any parse/shape mismatch → null (no evidence).
+ *
+ * @returns {Map<string, Set<string>>|null} doc basename → linked code files
+ */
+function loadGraphifyDocLinks(projectDir) {
+  const p = resolve(projectDir, 'graphify-out', 'graph.json');
+  if (!existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf-8'));
+    const nodes = Array.isArray(raw.nodes) ? raw.nodes : [];
+    // networkx serializes edges as "links"; older graphify exports used "edges".
+    const links = Array.isArray(raw.links) ? raw.links
+      : Array.isArray(raw.edges) ? raw.edges : [];
+    const nodeFile = new Map(); // node id → source_file
+    for (const n of nodes) {
+      if (n && n.id !== undefined && typeof n.source_file === 'string') {
+        nodeFile.set(n.id, n.source_file);
+      }
+    }
+    const docLinks = new Map();
+    for (const l of links) {
+      if (!l || l.confidence !== 'EXTRACTED') continue;
+      const sf = nodeFile.get(l.source);
+      const tf = nodeFile.get(l.target);
+      if (!sf || !tf) continue;
+      for (const [a, b] of [[sf, tf], [tf, sf]]) {
+        if (a.endsWith('.md') && !b.endsWith('.md') && isTraceableSource(b)) {
+          const doc = basename(a);
+          if (!docLinks.has(doc)) docLinks.set(doc, new Set());
+          docLinks.get(doc).add(b);
+        }
+      }
+    }
+    return docLinks.size > 0 ? docLinks : null;
+  } catch {
+    return null; // malformed graph = no evidence, never a finding
+  }
+}
+
 // IR soft-link recovery (feat 5): tokenize test files once so an untraced
 // requirement can be matched to the test that most likely already covers it
 // (TF-IDF cosine, VSM). Capped so a huge test suite can't blow up guard.
@@ -98,6 +148,10 @@ export function validateTraceability(projectDir, config) {
   const projectFiles = [];
   scanDir(projectDir, projectDir, projectFiles);
 
+  // Optional graphify interop: a committed knowledge graph is one more
+  // deterministic evidence source for doc↔code linkage.
+  const graphifyLinks = loadGraphifyDocLinks(projectDir);
+
   // Scan source files for `// @doc <filename>.md` annotations. An annotation
   // is an explicit author signal that a source file documents (or is
   // documented by) a canonical doc. It is the user-facing escape hatch when
@@ -149,6 +203,15 @@ export function validateTraceability(projectDir, config) {
       }
     }
 
+    // Graphify interop: an EXTRACTED doc↔code edge in a committed
+    // graphify-out/graph.json is author-grade linkage evidence (the graph's
+    // code side is deterministic AST extraction). Only trusted when at least
+    // one linked code file still exists — a stale graph must not vouch.
+    if (!hasSource && graphifyLinks && graphifyLinks.has(docName)) {
+      hasSource = [...graphifyLinks.get(docName)]
+        .some(f => existsSync(resolve(projectDir, f)) || existsSync(f));
+    }
+
     if (hasSource) {
       passed++;
     } else {

package/cli/writers/baseline.mjs

@@ -0,0 +1,84 @@
+/**
+ * Adoption Baseline — `.docguard.baseline.json` (repo root, COMMITTED).
+ *
+ * The brownfield-adoption pattern (ESLint/semgrep-style): a legacy repo
+ * freezes its existing findings once (`guard --update-baseline`), commits the
+ * file, and from then on guard/ci gate only NEW drift. Suppressed findings
+ * are counted and displayed — never silently hidden — and the baseline is a
+ * reviewable diff in every PR that updates it.
+ *
+ * Root, not `.docguard/`: the state dir is gitignored, and a baseline only
+ * works if the whole team and CI share it.
+ *
+ * Fingerprints are content-addressed, not line-addressed: `code | location
+ * path (line numbers stripped) | message with digit-runs normalized to #`.
+ * Line numbers churn on every edit and messages embed volatile counts
+ * ("21 commits since…") — both would rot the baseline in a week.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const BASELINE_FILE = '.docguard.baseline.json';
+
+/** Stable fingerprint for one finding. */
+export function fingerprintFinding(f) {
+  const code = f.code || 'UNCODED';
+  const path = typeof f.location === 'string' ? f.location.replace(/:\d+$/, '') : '';
+  const msg = String(f.message || '').replace(/\d+/g, '#').replace(/\s+/g, ' ').trim();
+  return createHash('sha256').update(`${code}|${path}|${msg}`).digest('hex').slice(0, 16);
+}
+
+/**
+ * Load the committed baseline as a Map of fingerprint → allowed occurrence
+ * count, or null when the project has none (the common case — zero overhead).
+ *
+ * Occurrence counts matter (review finding H2): two findings with the same
+ * code + file + message shape — e.g. two hardcoded passwords in one file —
+ * share a fingerprint. A count-less set would let one frozen instance
+ * suppress every FUTURE instance of that class in that file, a
+ * security-relevant false negative. With counts, freezing 1 suppresses 1;
+ * a second appearance surfaces and gates.
+ */
+export function loadBaseline(projectDir) {
+  const p = resolve(projectDir, BASELINE_FILE);
+  if (!existsSync(p)) return null;
+  try {
+    const data = JSON.parse(readFileSync(p, 'utf-8'));
+    if (!data || typeof data.fingerprints !== 'object' || data.fingerprints === null) return null;
+    const map = new Map();
+    for (const [fp, n] of Object.entries(data.fingerprints)) {
+      const count = Number.isInteger(n) && n > 0 ? n : 0;
+      if (count > 0) map.set(fp, count);
+    }
+    return map.size > 0 ? map : null;
+  } catch {
+    // A malformed baseline must not silently un-gate CI: treat as absent so
+    // every finding surfaces (fail-open on visibility, fail-closed on hiding).
+    return null;
+  }
+}
+
+/**
+ * Write the baseline from the current findings: fingerprint → occurrence
+ * count, keys sorted so the committed file diffs cleanly. Returns the number
+ * of distinct fingerprints.
+ */
+export function saveBaseline(projectDir, findings) {
+  const counts = {};
+  for (const f of findings) {
+    const fp = fingerprintFinding(f);
+    counts[fp] = (counts[fp] || 0) + 1;
+  }
+  const fingerprints = Object.fromEntries(Object.keys(counts).sort().map(k => [k, counts[k]]));
+  const doc = {
+    _comment: 'DocGuard adoption baseline — existing findings frozen at adoption time (fingerprint → occurrence count). Guard suppresses up to that many instances of each and gates everything new. Regenerate with: docguard guard --update-baseline',
+    version: 2,
+    generatedAt: new Date().toISOString(),
+    count: Object.keys(fingerprints).length,
+    fingerprints,
+  };
+  writeFileSync(resolve(projectDir, BASELINE_FILE), JSON.stringify(doc, null, 2) + '\n');
+  return Object.keys(fingerprints).length;
+}