docguard-cli 0.31.0 → 0.32.0

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/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.31.0"
+  version: "0.32.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.32.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.32.0 -->
 
 # DocGuard Sync Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {