docguard-cli 0.27.0 → 0.29.0

package/cli/validators/architecture.mjs

@@ -17,7 +17,8 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, relative, dirname, basename } from 'node:path';
-import { shouldIgnore } from '../shared-ignore.mjs';
+import { shouldIgnore, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -27,24 +28,42 @@ const IGNORE_DIRS = new Set([
 
 const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.jsx']);
 
+// v0.29: migrated to structured findings (ARC001–ARC003). Messages are
+// byte-identical to the legacy strings — resultFromFindings derives the
+// errors/warnings arrays from the same findings array (acc), which the
+// helpers below mutate in place.
 export function validateArchitecture(projectDir, config) {
-  const results = { name: 'architecture', errors: [], warnings: [], passed: 0, total: 0 };
+  const acc = { findings: [], passed: 0, total: 0 };
+  const compose = () => ({
+    name: 'architecture',
+    ...resultFromFindings(acc.findings, { passed: acc.passed, total: acc.total }),
+  });
 
   // ── 1. Config-driven layer validation ──
   const layers = config.layers;
   if (layers && Object.keys(layers).length > 0) {
-    validateConfigLayers(projectDir, config, layers, results);
+    validateConfigLayers(projectDir, config, layers, acc);
   }
 
   // ── 2. Auto-detect import graph ──
   const importGraph = buildImportGraph(projectDir, config);
-  if (importGraph.files.length === 0) return results;
+  if (importGraph.files.length === 0) return compose();
 
   // ── 3. Detect circular dependencies ──
   const circles = detectCircularDeps(importGraph);
   for (const circle of circles) {
-    results.total++;
-    results.warnings.push(`Circular dependency: ${circle.join(' → ')}`);
+    acc.total++;
+    acc.findings.push(mkFinding({
+      code: 'ARC002',
+      validator: 'architecture',
+      severity: 'warn',
+      message: `Circular dependency: ${circle.join(' → ')}`,
+      location: circle[0],
+      suggestion: {
+        kind: 'fix',
+        text: 'Break the cycle — convert one edge to a dynamic import() or extract the shared code into a third module',
+      },
+    }));
   }
 
   // ── 4. Check layer boundaries from ARCHITECTURE.md ──
@@ -54,13 +73,14 @@ export function validateArchitecture(projectDir, config) {
     const declaredLayers = parseLayerBoundaries(archContent);
 
     if (declaredLayers.length > 0) {
-      validateLayerBoundaries(projectDir, importGraph, declaredLayers, results);
+      validateLayerBoundaries(projectDir, importGraph, declaredLayers, acc);
     }
   }
 
   // ── 5. No boundaries declared and no circular deps to check → not applicable.
   // (Previously this returned a fake 1/1 pass, rendering a confident green ✅
   // for projects that declared no layer boundaries — it validated nothing.)
+  const results = compose();
   if (results.total === 0) {
     results.note = 'no layer boundaries declared in ARCHITECTURE.md';
   }
@@ -70,7 +90,7 @@ export function validateArchitecture(projectDir, config) {
 
 // ── Config-driven validation (existing behavior) ────────────────────────────
 
-function validateConfigLayers(projectDir, config, layers, results) {
+function validateConfigLayers(projectDir, config, layers, acc) {
   const layerMap = {};
   for (const [layerName, layerConfig] of Object.entries(layers)) {
     if (layerConfig.dir && layerConfig.canImport) {
@@ -97,15 +117,23 @@ function validateConfigLayers(projectDir, config, layers, results) {
       const relPath = relative(projectDir, file);
       const imports = extractImports(content);
 
-      for (const imp of imports) {
-        if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+      for (const { spec } of imports) {
+        if (!spec.startsWith('.') && !spec.startsWith('/')) continue;
 
         for (const forbiddenDir of layer.forbidden) {
-          if (imp.includes(forbiddenDir) || imp.includes(`/${forbiddenDir}/`)) {
-            results.total++;
-            results.errors.push(
-              `${relPath}: ${layer.name} layer imports from forbidden layer (${forbiddenDir})`
-            );
+          if (spec.includes(forbiddenDir) || spec.includes(`/${forbiddenDir}/`)) {
+            acc.total++;
+            acc.findings.push(mkFinding({
+              code: 'ARC001',
+              validator: 'architecture',
+              severity: 'error',
+              message: `${relPath}: ${layer.name} layer imports from forbidden layer (${forbiddenDir})`,
+              location: relPath,
+              suggestion: {
+                kind: 'fix',
+                text: 'Remove the import or route it through an allowed layer (see the layers config in .docguard.json)',
+              },
+            }));
           }
         }
       }
@@ -135,14 +163,19 @@ function buildImportGraph(projectDir, config) {
 
       const resolvedImports = [];
       for (const imp of imports) {
-        if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+        if (!imp.spec.startsWith('.') && !imp.spec.startsWith('/')) continue;
 
         // Resolve relative imports
         const fromDir = dirname(file);
-        const resolved = resolveImport(fromDir, imp, projectDir);
+        const resolved = resolveImport(fromDir, imp.spec, projectDir);
         if (resolved) {
-          resolvedImports.push(resolved);
-          graph.edges.push({ from: relPath, to: resolved });
+          graph.edges.push({ from: relPath, to: resolved, dynamic: imp.dynamic });
+          // v0.28 (field report #2): a dynamic `await import()` does NOT create a
+          // load-time edge — it's the canonical way to BREAK an import cycle. So
+          // it's excluded from the cycle-detection adjacency (fileMap) while still
+          // recorded in graph.edges for layer-boundary checks (an import is still
+          // an import for layering).
+          if (!imp.dynamic) resolvedImports.push(resolved);
         }
       }
 
@@ -153,26 +186,33 @@ function buildImportGraph(projectDir, config) {
   return graph;
 }
 
+/**
+ * Extract a file's imports as `{ spec, dynamic }`. `dynamic:true` marks a
+ * runtime `import('…')` — which does NOT create a load-time dependency edge and
+ * is the canonical way to break an import cycle (field report #2). ES `import …
+ * from` and CommonJS `require()` are load-time (static).
+ */
 function extractImports(content) {
   const imports = [];
 
-  // ES module imports
+  // ES module imports (static, load-time). `import\s+` requires whitespace after
+  // `import`, so it never matches a dynamic `import(` call.
   const esImportRegex = /import\s+(?:.*?\s+from\s+)?['"]([^'"]+)['"]/g;
   let match;
   while ((match = esImportRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: false });
   }
 
-  // Dynamic imports
+  // Dynamic imports (runtime — NOT a load-time cycle edge)
   const dynamicRegex = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
   while ((match = dynamicRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: true });
   }
 
-  // CommonJS require
+  // CommonJS require (static, load-time)
   const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
   while ((match = requireRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: false });
   }
 
   return imports;
@@ -295,7 +335,7 @@ function parseLayerBoundaries(archContent) {
   return layers;
 }
 
-function validateLayerBoundaries(projectDir, graph, declaredLayers, results) {
+function validateLayerBoundaries(projectDir, graph, declaredLayers, acc) {
   // Map directory patterns to layer names
   const layerDirMap = new Map();
   for (const layer of declaredLayers) {
@@ -315,13 +355,21 @@ function validateLayerBoundaries(projectDir, graph, declaredLayers, results) {
 
     // Check if this import is forbidden
     if (fromLayer.cannotImport.some(l => l.includes(toLayer.name) || toLayer.name.includes(l))) {
-      results.total++;
-      results.errors.push(
-        `${edge.from}: ${fromLayer.name} → ${toLayer.name} (forbidden by ARCHITECTURE.md)`
-      );
+      acc.total++;
+      acc.findings.push(mkFinding({
+        code: 'ARC003',
+        validator: 'architecture',
+        severity: 'error',
+        message: `${edge.from}: ${fromLayer.name} → ${toLayer.name} (forbidden by ARCHITECTURE.md)`,
+        location: edge.from,
+        suggestion: {
+          kind: 'review',
+          text: 'Remove or invert the import — or update the Layer Boundaries table in ARCHITECTURE.md if the rule changed',
+        },
+      }));
     } else {
-      results.total++;
-      results.passed++;
+      acc.total++;
+      acc.passed++;
     }
   }
 }
@@ -364,33 +412,20 @@ function getFileLayer(filePath, layerDirMap) {
 
 // ── Utilities ───────────────────────────────────────────────────────────────
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker.
+// The old version pruned config-ignored DIRECTORIES before descending; the
+// per-file check below yields the same result set (ignore-glob semantics match
+// any path under the dir — see globToRegex's `^pattern/` alternation), at the
+// cost of descending then filtering. Correctness-equivalent, verified by the
+// ignore-validator specs.
 function getFilesRecursive(dir, config, projectDir) {
   const results = [];
-  if (!existsSync(dir)) return results;
-
-  let entries;
-  try {
-    entries = readdirSync(dir);
-  } catch { return results; }
-
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
-
-    // Check config.ignore for this directory
+  sharedWalkFiles(dir, (fullPath) => {
     if (config && projectDir) {
-      const relPath = relative(projectDir, join(dir, entry));
-      if (shouldIgnore(relPath, config)) continue;
+      const relPath = relative(projectDir, fullPath);
+      if (shouldIgnore(relPath, config)) return;
     }
-
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        results.push(...getFilesRecursive(fullPath, config, projectDir));
-      } else {
-        results.push(fullPath);
-      }
-    } catch { /* skip */ }
-  }
+    results.push(fullPath);
+  }, { ignoreDirs: IGNORE_DIRS });
   return results;
 }

package/cli/validators/canonical-sync.mjs

@@ -40,6 +40,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * Validate that README count claims about DocGuard's surface match code-truth.
@@ -48,30 +49,38 @@ import { resolve, join } from 'node:path';
  * @param {string} projectDir - Project root directory
  * @param {object} config - DocGuard config (unused but required by validator interface)
  * @param {Array} [guardResults] - Results array from runGuardInternal (optional but recommended)
+ *
+ * v0.29: migrated to structured findings (CSY001–CSY004). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings array at every return point.
  * @returns {{ errors: string[], warnings: string[], fixes: object[], passed: number, total: number, na?: boolean, naReason?: string }}
  */
 export function validateCanonicalSync(projectDir, config, guardResults) {
-  const result = { errors: [], warnings: [], fixes: [], passed: 0, total: 0 };
+  const findings = [];
+  const fixes = [];
+  let passed = 0;
+  let total = 0;
+  // Compose the legacy result shape (plus findings) at every return point.
+  const compose = (extra) => ({ ...resultFromFindings(findings, { passed, total }), fixes, ...extra });
 
   // ── Gate: only run in DocGuard's own repo ─────────────────────────────
   const pkgPath = resolve(projectDir, 'package.json');
   if (!existsSync(pkgPath)) {
-    return { ...result, na: true, naReason: 'no package.json' };
+    return compose({ na: true, naReason: 'no package.json' });
   }
 
   let pkg;
   try {
     pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
   } catch {
-    return { ...result, na: true, naReason: 'unreadable package.json' };
+    return compose({ na: true, naReason: 'unreadable package.json' });
   }
 
   if (pkg.name !== 'docguard-cli') {
-    return {
-      ...result,
+    return compose({
       na: true,
       naReason: 'canonical-sync only runs in the docguard-cli repo (it polices DocGuard\'s own surface)',
-    };
+    });
   }
 
   // ── Gather code-truth ────────────────────────────────────────────────
@@ -80,7 +89,7 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
   const validatorsDir = resolve(cliDir, 'validators');
 
   if (!existsSync(commandsDir) || !existsSync(validatorsDir)) {
-    return { ...result, na: true, naReason: 'cli/commands or cli/validators not found' };
+    return compose({ na: true, naReason: 'cli/commands or cli/validators not found' });
   }
 
   const commandFiles = readdirSync(commandsDir).filter(f => f.endsWith('.mjs'));
@@ -137,60 +146,77 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
     try { readme += readFileSync(p, 'utf-8') + '\n'; readAny = true; } catch { /* skip unreadable */ }
   }
   if (!readAny) {
-    result.warnings.push('canonical-sync: no README.md or AGENTS.md found — cannot check surface claims');
-    result.total = 1;
-    return result;
+    findings.push(mkFinding({
+      code: 'CSY001',
+      validator: 'canonicalSync',
+      severity: 'warn',
+      message: 'canonical-sync: no README.md or AGENTS.md found — cannot check surface claims',
+      location: 'README.md',
+      suggestion: { kind: 'review', text: 'Add a README.md (or AGENTS.md) so DocGuard can police its own surface claims' },
+    }));
+    total = 1;
+    return compose();
   }
 
   // ── Check 1: "ships N commands" ─────────────────────────────────────
   // Check ALL claims (matchAll), not just the first: with README + AGENTS.md
   // concatenated, a correct claim in one file must not mask a stale claim in
   // the other (the same first-match-masking trap the secret scanner had).
-  result.total++;
+  total++;
   const cmdMatches = [...readme.matchAll(/ships\s+\*{0,2}(\d+)\s+commands?\*{0,2}/gi)];
   if (cmdMatches.length > 0) {
     const wrong = [...new Set(cmdMatches.map(m => Number(m[1])).filter(n => n !== actualCommandCount))];
     if (wrong.length === 0) {
-      result.passed++;
+      passed++;
     } else {
       const detail = actualUserFacingCount !== actualCommandFileCount
         ? `${actualCommandCount} user-facing commands in --help (${actualCommandFileCount} files including deprecation aliases)`
         : `${actualCommandCount} command file(s)`;
-      result.warnings.push(
-        `A surface doc (README.md/AGENTS.md) claims ${wrong.map(n => `"ships ${n} commands"`).join(' / ')} but the real count is ${detail}. Update it.`
-      );
+      findings.push(mkFinding({
+        code: 'CSY002',
+        validator: 'canonicalSync',
+        severity: 'warn',
+        message: `A surface doc (README.md/AGENTS.md) claims ${wrong.map(n => `"ships ${n} commands"`).join(' / ')} but the real count is ${detail}. Update it.`,
+        location: null,
+        suggestion: { kind: 'fix', text: 'Update the "ships N commands" claim in README.md/AGENTS.md to the real count' },
+      }));
     }
   } else {
     // No claim found — that's OK, just don't check this one
-    result.passed++;
+    passed++;
   }
 
   // ── Check 2: "N validators" in surface context ──────────────────────
   // Match phrases like "22 validators", "all 22 validators", "the 22 validators"
   // but NOT phase-log entries like "Built with 9 validators" (those are
   // historical, and ROADMAP.md/CHANGELOG.md are skipped at the file level).
-  result.total++;
+  total++;
   const validatorMatches = [...readme.matchAll(/(?:all|the|with|across|ships?)\s+\*{0,2}(\d+)\s+validators?\*{0,2}/gi)];
   if (validatorMatches.length > 0) {
     const wrongClaims = validatorMatches
       .map(m => Number(m[1]))
       .filter(n => n !== actualValidatorCount);
     if (wrongClaims.length === 0) {
-      result.passed++;
+      passed++;
     } else {
       const uniqueWrong = [...new Set(wrongClaims)];
-      result.warnings.push(
-        `A surface doc (README.md/AGENTS.md) claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update it.`
-      );
+      findings.push(mkFinding({
+        code: 'CSY003',
+        validator: 'canonicalSync',
+        severity: 'warn',
+        message: `A surface doc (README.md/AGENTS.md) claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update it.`,
+        location: null,
+        suggestion: { kind: 'fix', text: 'Update the "N validators" claim in README.md/AGENTS.md to match guard\'s count' },
+      }));
     }
   } else {
-    result.passed++;
+    passed++;
   }
 
   // ── Check 3: architecture-diagram counts ────────────────────────────
   // Catches the specific "Commands (N)" and "Validators (N)" patterns in
   // the mermaid block that drifted across 5 releases.
-  result.total++;
+  total++;
   const archMatches = [
     { re: /Commands\s*\((\d+)\)/, label: 'Commands', expected: actualCommandCount },
     { re: /Validators\s*\((\d+)\)/, label: 'Validators', expected: actualValidatorCount },
@@ -203,12 +229,17 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
     }
   }
   if (archWrong.length === 0) {
-    result.passed++;
+    passed++;
   } else {
-    result.warnings.push(
-      `README.md architecture diagram has stale counts: ${archWrong.join('; ')}. Update the mermaid block.`
-    );
+    findings.push(mkFinding({
+      code: 'CSY004',
+      validator: 'canonicalSync',
+      severity: 'warn',
+      message: `README.md architecture diagram has stale counts: ${archWrong.join('; ')}. Update the mermaid block.`,
+      location: 'README.md',
+      suggestion: { kind: 'fix', text: 'Update the Commands (N) / Validators (N) labels in the README mermaid block' },
+    }));
   }
 
-  return result;
+  return compose();
 }

package/cli/validators/changelog.mjs

@@ -7,6 +7,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const CODE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|cs|kt|swift)$/;
 
@@ -24,35 +25,53 @@ function getStagedFiles(projectDir) {
   }
 }
 
+// v0.29: migrated to structured findings (CHG001–CHG003). Messages are
+// byte-identical to the legacy strings; the `fixes` array is preserved for
+// the fix applier.
 export function validateChangelog(projectDir, config) {
-  const results = { name: 'changelog', errors: [], warnings: [], passed: 0, total: 0, fixes: [] };
+  const findings = [];
+  const fixes = [];
+  let passed = 0;
+  let total = 0;
 
   const changelogPath = resolve(projectDir, config.requiredFiles.changelog);
   if (!existsSync(changelogPath)) {
     // Structure validator catches missing files
-    return results;
+    return { name: 'changelog', ...resultFromFindings([], { passed: 0, total: 0 }), fixes };
   }
 
   const content = readFileSync(changelogPath, 'utf-8');
 
   // Check for [Unreleased] section
-  results.total++;
+  total++;
   if (content.includes('[Unreleased]') || content.includes('[unreleased]')) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push('CHANGELOG.md: missing [Unreleased] section — fix with `docguard fix --write`');
-    results.fixes.push({ type: 'insert-changelog-unreleased', file: config.requiredFiles.changelog });
+    findings.push(mkFinding({
+      code: 'CHG001',
+      validator: 'changelog',
+      severity: 'warn',
+      message: 'CHANGELOG.md: missing [Unreleased] section — fix with `docguard fix --write`',
+      location: config.requiredFiles.changelog,
+      suggestion: { kind: 'fix', text: 'Insert an [Unreleased] section', command: 'docguard fix --write' },
+    }));
+    fixes.push({ type: 'insert-changelog-unreleased', file: config.requiredFiles.changelog });
   }
 
   // Check it follows Keep a Changelog format (at least has ## headers)
-  results.total++;
+  total++;
   const hasVersionHeaders = /^## \[/m.test(content);
   if (hasVersionHeaders) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push(
-      'CHANGELOG.md: no version sections found (expected ## [version] format)'
-    );
+    findings.push(mkFinding({
+      code: 'CHG002',
+      validator: 'changelog',
+      severity: 'warn',
+      message: 'CHANGELOG.md: no version sections found (expected ## [version] format)',
+      location: config.requiredFiles.changelog,
+      suggestion: { kind: 'review', text: 'Adopt Keep a Changelog format: ## [version] - YYYY-MM-DD headers' },
+    }));
   }
 
   // Per STANDARD.md: if there are staged CODE changes, CHANGELOG.md should be
@@ -65,16 +84,21 @@ export function validateChangelog(projectDir, config) {
     const changelogStaged = staged.some(f => basename(f) === changelogName);
 
     if (stagedCode.length > 0) {
-      results.total++;
+      total++;
       if (changelogStaged) {
-        results.passed++;
+        passed++;
       } else {
-        results.warnings.push(
-          `${stagedCode.length} code file(s) staged but ${changelogName} is not — add a CHANGELOG entry for this change`
-        );
+        findings.push(mkFinding({
+          code: 'CHG003',
+          validator: 'changelog',
+          severity: 'warn',
+          message: `${stagedCode.length} code file(s) staged but ${changelogName} is not — add a CHANGELOG entry for this change`,
+          location: config.requiredFiles.changelog,
+          suggestion: { kind: 'fix', text: `Describe the staged change under [Unreleased] in ${changelogName}, then stage it` },
+        }));
       }
     }
   }
 
-  return results;
+  return { name: 'changelog', ...resultFromFindings(findings, { passed, total }), fixes };
 }

package/cli/validators/cross-reference.mjs

@@ -28,6 +28,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname, basename, relative } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * Slugify a heading the way GitHub's markdown anchors work.
@@ -290,17 +291,21 @@ function collectCanonicalDocs(projectDir) {
 /**
  * Validator entrypoint — matches the standard signature returning
  * { errors, warnings, passed, total }.
+ *
+ * v0.29: migrated to structured findings (XRF001–XRF002). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * 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 = {}) {
-  const errors = [];
-  const warnings = [];
+  const findings = [];
   const fixes = [];
   let passed = 0;
   let total = 0;
 
   const docs = collectCanonicalDocs(projectDir);
   if (docs.length === 0) {
-    return { errors, warnings, passed, total, applicable: false };
+    return resultFromFindings([], { passed, total, applicable: false });
   }
 
   // Build a map of doc path → anchor set for fast lookups during ref resolution.
@@ -336,9 +341,14 @@ export function validateCrossReferences(projectDir, _config = {}) {
         }
         targetPath = resolveTarget(docPath, ref.file, projectDir);
         if (!targetPath) {
-          warnings.push(
-            `${docName}:${ref.line} — broken link: target file "${ref.file}" not found`
-          );
+          findings.push(mkFinding({
+            code: 'XRF001',
+            validator: 'crossReference',
+            severity: 'warn',
+            message: `${docName}:${ref.line} — broken link: target file "${ref.file}" not found`,
+            location: `${relative(projectDir, docPath)}:${ref.line}`,
+            suggestion: { kind: 'fix', text: 'Fix the link target path (or remove the dead link)' },
+          }));
           continue;
         }
       } else {
@@ -372,10 +382,17 @@ export function validateCrossReferences(projectDir, _config = {}) {
           // `docguard fix --write` resolves it without AI. Other near-misses
           // still get the hint but no fix (the user needs to verify intent).
           const isHighConfidence = suggestion && isUnambiguousSuggestion(normalizedAnchor, suggestion, anchors);
-          warnings.push(
-            `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading${hint}` +
-            (isHighConfidence ? ' [auto-fixable]' : '')
-          );
+          findings.push(mkFinding({
+            code: 'XRF002',
+            validator: 'crossReference',
+            severity: 'warn',
+            message: `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading${hint}` +
+              (isHighConfidence ? ' [auto-fixable]' : ''),
+            location: `${relative(projectDir, docPath)}:${ref.line}`,
+            suggestion: isHighConfidence
+              ? { kind: 'fix', text: `Replace #${ref.anchor} with #${suggestion}`, command: 'docguard fix --write' }
+              : { kind: 'review', text: 'Update the anchor to match a real heading in the target doc' },
+          }));
           if (isHighConfidence) {
             fixes.push({
               type: 'replace-anchor',
@@ -394,7 +411,7 @@ export function validateCrossReferences(projectDir, _config = {}) {
     }
   }
 
-  return { errors, warnings, passed, total, fixes };
+  return { ...resultFromFindings(findings, { passed, total }), fixes };
 }
 
 /**