docguard-cli 0.28.0 → 0.29.0

package/cli/validators/api-surface.mjs

@@ -30,6 +30,7 @@ import { scanRoutesDeep } from '../scanners/routes.mjs';
 import { parseApiReferenceDoc, compareEndpoints, endpointKey } from '../scanners/api-doc.mjs';
 import { collectPackageJsons, getWorkspaceDirs } from '../shared-source.mjs';
 import { relPosix } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const MAX_REPORTED = 15;
 const API_DOC = 'docs-canonical/API-REFERENCE.md';
@@ -250,9 +251,12 @@ export function computeSpecVsRouteDrift(projectDir, config) {
   };
 }
 
+// v0.29: migrated to structured findings (API001–API005). Messages are
+// byte-identical to the legacy strings — resultFromFindings derives the
+// errors/warnings arrays from the same findings; `fixes` and
+// `authoritativeSpec` are preserved.
 export function validateApiSurface(projectDir, config) {
-  const errors = [];
-  const warnings = [];
+  const findings = [];
   const fixes = [];
   const trim = (arr) => {
     const shown = arr.slice(0, MAX_REPORTED);
@@ -268,7 +272,7 @@ export function validateApiSurface(projectDir, config) {
     const anyRouteFile = config.changedFiles.some(f => ROUTE_RE.test(f));
     if (!anyRouteFile) {
       return {
-        errors, warnings, passed: 0, total: 0, fixes,
+        errors: [], warnings: [], passed: 0, total: 0, fixes,
         applicable: false,
         note: 'no route/spec files in changed set',
       };
@@ -280,12 +284,17 @@ export function validateApiSurface(projectDir, config) {
   // choked on it. We fall back to code scanning (below), but the parse failure
   // is surfaced here rather than silently producing a clean "no surface" pass.
   for (const specPath of findUnparseableSpecs(projectDir, config)) {
-    warnings.push(
-      `OpenAPI spec ${specPath} declares paths but DocGuard parsed 0 endpoints from it ` +
-      `(likely an unsupported YAML feature — $ref, anchors, or folded scalars). ` +
-      `Falling back to code scanning; the spec's own endpoint list is unavailable. ` +
-      `Validate it with a full OpenAPI linter.`
-    );
+    findings.push(mkFinding({
+      code: 'API001',
+      validator: 'apiSurface',
+      severity: 'warn',
+      message: `OpenAPI spec ${specPath} declares paths but DocGuard parsed 0 endpoints from it ` +
+        `(likely an unsupported YAML feature — $ref, anchors, or folded scalars). ` +
+        `Falling back to code scanning; the spec's own endpoint list is unavailable. ` +
+        `Validate it with a full OpenAPI linter.`,
+      location: specPath,
+      suggestion: { kind: 'review', text: 'Validate the spec with a full OpenAPI linter (e.g. spectral) and simplify unsupported YAML features' },
+    }));
   }
 
   const drift = computeApiSurfaceDrift(projectDir, config);
@@ -296,10 +305,15 @@ export function validateApiSurface(projectDir, config) {
     const others = divergence.specs.slice(1).map(s => s.relPath).join(', ');
     const sample = divergence.divergent.slice(0, 8).join(', ');
     const more = divergence.divergent.length > 8 ? ` (+${divergence.divergent.length - 8} more)` : '';
-    warnings.push(
-      `Multiple OpenAPI specs disagree on ${divergence.divergent.length} endpoint(s): ` +
-      `${divergence.authoritative} (treated as authoritative) vs ${others}. Divergent: ${sample}${more}`
-    );
+    findings.push(mkFinding({
+      code: 'API002',
+      validator: 'apiSurface',
+      severity: 'warn',
+      message: `Multiple OpenAPI specs disagree on ${divergence.divergent.length} endpoint(s): ` +
+        `${divergence.authoritative} (treated as authoritative) vs ${others}. Divergent: ${sample}${more}`,
+      location: divergence.authoritative,
+      suggestion: { kind: 'review', text: 'Regenerate or delete the stale spec copy so every spec agrees on the endpoint set' },
+    }));
   }
 
   // ── #4: spec declares an endpoint with no registered route ──
@@ -314,12 +328,30 @@ export function validateApiSurface(projectDir, config) {
     if (specRoute.specDeclaredNoRoute.length) {
       const { shown, extra } = trim(specRoute.specDeclaredNoRoute);
       for (const e of shown) {
-        warnings.push(
-          `OpenAPI spec (${specRoute.specPath}) declares ${e.method} ${e.path} but no route registers it in code — ` +
-          `the spec may be wrong, and the API-REFERENCE doc reconciles clean against it, hiding the gap.`
-        );
+        findings.push(mkFinding({
+          code: 'API003',
+          validator: 'apiSurface',
+          severity: 'warn',
+          // "may be wrong" — the route scanner can be blind to dynamic
+          // registration, so this is a candidate false positive by design.
+          confidence: 'low',
+          message: `OpenAPI spec (${specRoute.specPath}) declares ${e.method} ${e.path} but no route registers it in code — ` +
+            `the spec may be wrong, and the API-REFERENCE doc reconciles clean against it, hiding the gap.`,
+          location: specRoute.specPath,
+          suggestion: { kind: 'review', text: 'Verify the endpoint: remove it from the spec if it no longer exists, or check whether the route is registered dynamically' },
+        }));
+      }
+      if (extra > 0) {
+        findings.push(mkFinding({
+          code: 'API003',
+          validator: 'apiSurface',
+          severity: 'warn',
+          confidence: 'low',
+          message: `…and ${extra} more spec-declared endpoint(s) with no registered route`,
+          location: specRoute.specPath,
+          suggestion: { kind: 'review', text: 'Verify each spec-declared endpoint against the registered routes' },
+        }));
       }
-      if (extra > 0) warnings.push(`…and ${extra} more spec-declared endpoint(s) with no registered route`);
     }
   }
 
@@ -327,7 +359,8 @@ export function validateApiSurface(projectDir, config) {
     // Nothing to validate against the API-REFERENCE doc — but the spec-vs-route
     // check above may still have produced findings.
     return {
-      errors, warnings, passed: specRoutePassed, total: specRouteTotal, fixes,
+      ...resultFromFindings(findings, { passed: specRoutePassed, total: specRouteTotal }),
+      fixes,
       authoritativeSpec: drift.source || specRoute.specPath,
     };
   }
@@ -341,13 +374,51 @@ export function validateApiSurface(projectDir, config) {
     const { shown, extra } = trim(documentedButAbsent);
     for (const e of shown) {
       const msg = `Documented endpoint not found in code: ${e.method} ${e.path} (${API_DOC})`;
-      if (confidence === 'spec') errors.push(msg);
-      else warnings.push(`${msg} [code-scan — verify]`);
+      if (confidence === 'spec') {
+        findings.push(mkFinding({
+          code: 'API004',
+          validator: 'apiSurface',
+          severity: 'error',
+          message: msg,
+          location: API_DOC,
+          suggestion: { kind: 'fix', text: 'Remove the dead endpoint from the doc', command: 'docguard fix --write' },
+        }));
+      } else {
+        findings.push(mkFinding({
+          code: 'API004',
+          validator: 'apiSurface',
+          severity: 'warn',
+          // The "[code-scan — verify]" suffix marks this as heuristic-only:
+          // the route scanner may simply not see the endpoint's registration.
+          confidence: 'low',
+          message: `${msg} [code-scan — verify]`,
+          location: API_DOC,
+          suggestion: { kind: 'review', text: 'Verify the endpoint really is gone from the code, then remove it from the doc' },
+        }));
+      }
     }
     if (extra > 0) {
       const tail = `…and ${extra} more documented endpoint(s) not found in code`;
-      if (confidence === 'spec') errors.push(tail);
-      else warnings.push(tail);
+      if (confidence === 'spec') {
+        findings.push(mkFinding({
+          code: 'API004',
+          validator: 'apiSurface',
+          severity: 'error',
+          message: tail,
+          location: API_DOC,
+          suggestion: { kind: 'fix', text: 'Remove the dead endpoints from the doc', command: 'docguard fix --write' },
+        }));
+      } else {
+        findings.push(mkFinding({
+          code: 'API004',
+          validator: 'apiSurface',
+          severity: 'warn',
+          confidence: 'low',
+          message: tail,
+          location: API_DOC,
+          suggestion: { kind: 'review', text: 'Verify each documented endpoint against the code, then prune the doc' },
+        }));
+      }
     }
     // Only spec-confirmed absences are safe to auto-remove.
     if (confidence === 'spec') {
@@ -361,10 +432,26 @@ export function validateApiSurface(projectDir, config) {
   if (presentButUndocumented.length) {
     const { shown, extra } = trim(presentButUndocumented);
     for (const e of shown) {
-      warnings.push(`Undocumented endpoint in code: ${e.method} ${e.path} — add it to ${API_DOC}`);
+      findings.push(mkFinding({
+        code: 'API005',
+        validator: 'apiSurface',
+        severity: 'warn',
+        message: `Undocumented endpoint in code: ${e.method} ${e.path} — add it to ${API_DOC}`,
+        location: API_DOC,
+        suggestion: { kind: 'fix', text: `Document the endpoint in ${API_DOC}` },
+      }));
+    }
+    if (extra > 0) {
+      findings.push(mkFinding({
+        code: 'API005',
+        validator: 'apiSurface',
+        severity: 'warn',
+        message: `…and ${extra} more undocumented endpoint(s) in code`,
+        location: API_DOC,
+        suggestion: { kind: 'fix', text: `Document the remaining endpoints in ${API_DOC}` },
+      }));
     }
-    if (extra > 0) warnings.push(`…and ${extra} more undocumented endpoint(s) in code`);
   }
 
-  return { errors, warnings, passed, total, fixes, authoritativeSpec: source };
+  return { ...resultFromFindings(findings, { passed, total }), fixes, authoritativeSpec: source };
 }

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) {
@@ -102,10 +122,18 @@ function validateConfigLayers(projectDir, config, layers, results) {
 
         for (const forbiddenDir of layer.forbidden) {
           if (spec.includes(forbiddenDir) || spec.includes(`/${forbiddenDir}/`)) {
-            results.total++;
-            results.errors.push(
-              `${relPath}: ${layer.name} layer imports from forbidden layer (${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)',
+              },
+            }));
           }
         }
       }
@@ -307,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) {
@@ -327,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++;
     }
   }
 }
@@ -376,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();
 }