docguard-cli 0.28.0 → 0.29.0

package/cli/validators/metrics-consistency.mjs

@@ -8,12 +8,11 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative } from 'node:path';
-import { loadIgnorePatterns, c } from '../shared.mjs';
-
-const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
-]);
+import { loadIgnorePatterns, resolveDocDirs } from '../shared.mjs';
+// v0.29 consolidation: walker + glob counting live in shared-ignore.mjs (the
+// single implementations) — this file previously carried private copies.
+import { walkFiles, countGlobFiles } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * Validate metrics consistency across documentation.
@@ -22,8 +21,11 @@ const IGNORE_DIRS = new Set([
  * @param {object} [guardResults] - Results from runGuardInternal (optional)
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
  */
+// v0.29: migrated to structured findings (MET001 built-in meta-counts, MET002
+// declared collections). Messages are byte-identical to the legacy strings;
+// the `fixes` array is preserved for the fix applier.
 export function validateMetricsConsistency(projectDir, config, guardResults) {
-  const warnings = [];
+  const findings = [];
   const fixes = [];
   let passed = 0;
   let total = 0;
@@ -52,18 +54,56 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
 
   // If no actuals to compare, skip
   if (Object.keys(actuals).length === 0) {
-    return { errors: [], warnings, passed: 0, total: 0 };
+    return resultFromFindings([], { passed: 0, total: 0 });
   }
 
   // ── Scan markdown files for hardcoded numbers ──
   const isIgnored = loadIgnorePatterns(projectDir);
   const mdFiles = findMarkdownFiles(projectDir, config);
-  // Patterns must match standalone number references, not ratio-style "8/8 checks"
+  // Patterns must match standalone number references, not ratio-style "8/8 checks".
+  // `requireBind`: built-in DocGuard meta-counts (checks/validators) describe a
+  // generic noun, so they only fire when the line is bound to "docguard" (Bug #2).
+  // `subject`: human phrasing for the warning. `actualSource`: records WHAT the
+  // actual count describes so the fix applier can confirm both sides are the same
+  // subject before overwriting.
   const patterns = [
-    { key: 'checks', regex: /(?<!\d\/)\b(\d{2,})\s+(?:automated\s+)?checks?\b/gi, label: 'checks' },
-    { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators' },
+    { key: 'checks', regex: /(?<!\d\/)\b(\d{2,})\s+(?:automated\s+)?checks?\b/gi, label: 'checks', requireBind: true, subject: "DocGuard's own", actualSource: 'docguard.guard.checks' },
+    { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators', requireBind: true, subject: "DocGuard's own", actualSource: 'docguard.guard.validators' },
   ];
 
+  // v0.29 (field report #6): project-declared collections. `config.collections`
+  // maps a documentation noun (e.g. "extractors") to a glob whose matching-file
+  // count is the source of truth. This catches the exact class that shipped a
+  // wrong "16 extractors" past a green guard — deterministically, in `guard`, with
+  // no LLM. A declared collection IS the opt-in binding (the user named this noun),
+  // so unlike the built-ins it does NOT require "docguard" on the line. Fail-safe:
+  // an unresolved glob (0 matches) never asserts "0", so a misconfigured pattern
+  // can't manufacture a false drift. Reserved nouns keep the built-in count.
+  const RESERVED = new Set(['checks', 'validators', 'tests']);
+  const escapeRegExp = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // noun stems, not globs
+  const collections = (config && config.collections && typeof config.collections === 'object') ? config.collections : {};
+  for (const [noun, glob] of Object.entries(collections)) {
+    const key = String(noun).toLowerCase();
+    if (RESERVED.has(key) || typeof glob !== 'string' || !glob.trim()) continue;
+    const count = countGlobFiles(projectDir, glob);
+    // <= 0 covers BOTH "unresolved/empty glob" (0) and "walk incomplete" (-1,
+    // e.g. permission-denied subtree). Either way: never assert a count we
+    // can't stand behind — a partial count auto-"fixing" a correct doc number
+    // is the tool's worst failure mode.
+    if (count <= 0) continue;
+    actuals[key] = count;
+    const stem = escapeRegExp(String(noun).replace(/s$/i, ''));
+    patterns.push({
+      key,
+      regex: new RegExp(`(?<!\\d\\/)\\b(\\d+)\\s+${stem}s?\\b`, 'gi'),
+      label: String(noun),
+      requireBind: false,
+      isCollection: true,
+      glob,
+      actualSource: `docguard.collections.${key}`,
+    });
+  }
+
   // v0.14.1-N1: dedup by (file, label, found) — a file that mentions the
   // stale number multiple times produces ONE warning, not one per occurrence.
   // The replace-count applier already uses replace-all semantics, so a single
@@ -82,7 +122,7 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
     let content;
     try { content = readFileSync(mdFile, 'utf-8'); } catch { continue; }
 
-    for (const { key, regex, label } of patterns) {
+    for (const { key, regex, label, requireBind, subject, actualSource, isCollection, glob } of patterns) {
       if (actuals[key] === undefined) continue;
 
       regex.lastIndex = 0;
@@ -93,11 +133,13 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
       // "19" on line 50 are two distinct drifts.
       const distinctFoundInFile = new Set();
       while ((match = regex.exec(content)) !== null) {
-        // Bug #2 (subject-binding): only validate a number BOUND to DocGuard.
-        // An unbound "N checks" (a proof harness, a CI job, a third-party tool)
-        // describes a DIFFERENT subject — comparing it to DocGuard's own count
-        // is a false positive, and auto-fixing it overwrites a correct number.
-        if (!isDocguardBound(content, match.index)) continue;
+        // Bug #2 (subject-binding): for the built-in meta-counts, only validate a
+        // number BOUND to DocGuard. An unbound "N checks" (a proof harness, a CI
+        // job, a third-party tool) describes a DIFFERENT subject — comparing it to
+        // DocGuard's own count is a false positive, and auto-fixing it overwrites a
+        // correct number. Project-declared collections (requireBind:false) skip
+        // this: naming the noun in `config.collections` IS the explicit binding.
+        if (requireBind && !isDocguardBound(content, match.index)) continue;
         distinctFoundInFile.add(parseInt(match[1], 10));
       }
       if (distinctFoundInFile.size === 0) continue;
@@ -108,13 +150,27 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
           if (reportedDrift.has(driftKey)) continue;
           reportedDrift.add(driftKey);
           total++;
-          warnings.push(
-            `${relPath} says "${found} ${label}" but DocGuard's own ${label} count is ${actuals[key]}. Fix with \`docguard fix --write\``
-          );
+          const phrase = isCollection
+            ? `the code has ${actuals[key]} (${glob})`
+            : `${subject} ${label} count is ${actuals[key]}`;
+          findings.push(mkFinding({
+            code: isCollection ? 'MET002' : 'MET001',
+            validator: 'metricsConsistency',
+            severity: 'warn',
+            message: `${relPath} says "${found} ${label}" but ${phrase}. Fix with \`docguard fix --write\``,
+            location: relPath,
+            suggestion: {
+              kind: 'fix',
+              text: isCollection
+                ? `Confirm which side is right, then rewrite the stale count (${found} → ${actuals[key]})`
+                : `Rewrite the stale docguard-bound count (${found} → ${actuals[key]})`,
+              command: 'docguard fix --write',
+            },
+          }));
           // actualSource records WHAT the actual count describes, so the applier
           // (and a human) can confirm both sides are the same subject before any
           // overwrite. Without it the fix is refused (fail-closed). See Bug #2.
-          fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key], actualSource: `docguard.guard.${key}` });
+          fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key], actualSource });
         } else {
           // Matches the actual count — one pass per (file, label), not per occurrence.
           const passKey = `${relPath}|${label}`;
@@ -127,7 +183,7 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
     }
   }
 
-  return { errors: [], warnings, passed, total, fixes };
+  return { ...resultFromFindings(findings, { passed, total }), fixes };
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -208,17 +264,20 @@ function findMarkdownFiles(dir, config = {}) {
     }
   } catch { /* unreadable root */ }
 
-  // Configured canonical docs (wherever they live), plus the conventional
-  // doc homes (docs/, docs-canonical/, extensions/) — scanned in full
-  // (recursive). Code/tooling dirs (security/, backend/, src/, …) are NOT doc
-  // homes and are deliberately excluded.
+  // Configured canonical docs (wherever they live), plus every resolved doc
+  // home — scanned in full (recursive). v0.29 (field report #6, follow-up): the
+  // doc-home set is no longer the hardcoded trio; resolveDocDirs auto-detects
+  // conventional doc dirs (docs/, documentation/, guides/, …) or honors an
+  // explicit config.docs.dirs. NAMED dirs only — code/tooling dirs (security/,
+  // backend/, src/, …) and arbitrary subdirs are still NEVER walked (the
+  // wu-whatsappinbox false-positive flood the scoping fix removed).
   const canonical = config && config.requiredFiles && Array.isArray(config.requiredFiles.canonical)
     ? config.requiredFiles.canonical : [];
   for (const rel of canonical) {
     const full = resolve(dir, rel);
     if (existsSync(full)) { try { if (statSync(full).isFile()) add(full); } catch { /* skip */ } }
   }
-  for (const sub of ['docs', 'docs-canonical', 'extensions']) {
+  for (const sub of resolveDocDirs(dir, config)) {
     const searchDir = resolve(dir, sub);
     if (existsSync(searchDir)) walkFiles(searchDir, add);
   }
@@ -226,23 +285,6 @@ function findMarkdownFiles(dir, config = {}) {
   return mdFiles;
 }
 
-function walkFiles(dir, callback) {
-  if (!existsSync(dir)) return;
-  let entries;
-  try { entries = readdirSync(dir); } catch { return; }
-
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        walkFiles(fullPath, callback);
-      } else if (stat.isFile()) {
-        callback(fullPath);
-      }
-    } catch (err) {
-      console.error(`${c.red}Error reading file or directory: ${err.message}${c.reset}`);
-    }
-  }
-}
+// Local walker + glob→count helpers were removed in the v0.29 consolidation —
+// `walkFiles` / `countGlobFiles` are imported from ../shared-ignore.mjs, the
+// single canonical implementations.

package/cli/validators/schema-sync.mjs

@@ -12,6 +12,8 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname, basename } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
+import { walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -77,9 +79,15 @@ const SCHEMA_DETECTORS = [
 
 /**
  * Main validator entry point.
+ *
+ * v0.29: migrated to structured findings (SCH001–SCH002). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings array.
  */
 export function validateSchemaSync(projectDir, config) {
-  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
 
   // Check if DATA-MODEL.md exists
   const dataModelPath = resolve(projectDir, 'docs-canonical', 'DATA-MODEL.md');
@@ -88,13 +96,18 @@ export function validateSchemaSync(projectDir, config) {
     // Only warn if we detect schema files
     const detectedModels = detectAllModels(projectDir, config);
     if (detectedModels.length > 0) {
-      results.total++;
-      results.warnings.push(
-        `Found ${detectedModels.length} database model(s) (${detectedModels.map(m => m.name).slice(0, 5).join(', ')}${detectedModels.length > 5 ? '...' : ''}) ` +
-        `but no DATA-MODEL.md exists. Run \`docguard init\` to create one, then document your schema`
-      );
+      total++;
+      findings.push(mkFinding({
+        code: 'SCH001',
+        validator: 'schemaSync',
+        severity: 'warn',
+        message: `Found ${detectedModels.length} database model(s) (${detectedModels.map(m => m.name).slice(0, 5).join(', ')}${detectedModels.length > 5 ? '...' : ''}) ` +
+          `but no DATA-MODEL.md exists. Run \`docguard init\` to create one, then document your schema`,
+        location: 'docs-canonical/DATA-MODEL.md',
+        suggestion: { kind: 'fix', text: 'Create DATA-MODEL.md, then document the detected models in it', command: 'docguard init' },
+      }));
     }
-    return results;
+    return resultFromFindings(findings, { passed, total });
   }
 
   const dataModelContent = readFileSync(dataModelPath, 'utf-8').toLowerCase();
@@ -104,12 +117,12 @@ export function validateSchemaSync(projectDir, config) {
 
   if (detectedModels.length === 0) {
     // No schema files found — silently pass
-    return results;
+    return resultFromFindings(findings, { passed, total });
   }
 
   // Check each model appears in DATA-MODEL.md
   for (const model of detectedModels) {
-    results.total++;
+    total++;
 
     // Check if model name appears in DATA-MODEL.md (case-insensitive)
     const modelLower = model.name.toLowerCase();
@@ -120,16 +133,21 @@ export function validateSchemaSync(projectDir, config) {
       (modelLower.endsWith('s') && dataModelContent.includes(modelLower.slice(0, -1)));
 
     if (found) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
-        `${model.framework} model "${model.name}" (${model.file}) not documented in DATA-MODEL.md. ` +
-        `Add it to the Entity Definitions section`
-      );
+      findings.push(mkFinding({
+        code: 'SCH002',
+        validator: 'schemaSync',
+        severity: 'warn',
+        message: `${model.framework} model "${model.name}" (${model.file}) not documented in DATA-MODEL.md. ` +
+          `Add it to the Entity Definitions section`,
+        location: model.file,
+        suggestion: { kind: 'fix', text: 'Document the model in the Entity Definitions section of docs-canonical/DATA-MODEL.md' },
+      }));
     }
   }
 
-  return results;
+  return resultFromFindings(findings, { passed, total });
 }
 
 // ──── Model Detection ──────────────────────────────────────────────────────
@@ -193,24 +211,11 @@ function findSchemaFiles(projectDir, detector, config = {}) {
   return files;
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker.
 function scanSchemaDir(dir, filePattern, files) {
-  let entries;
-  try { entries = readdirSync(dir); } catch { return; }
-
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry)) continue;
-    if (entry.startsWith('.')) continue;
-
-    const full = join(dir, entry);
-    let stat;
-    try { stat = statSync(full); } catch { continue; }
-
-    if (stat.isDirectory()) {
-      scanSchemaDir(full, filePattern, files);
-    } else if (filePattern.test(entry)) {
-      files.push(full);
-    }
-  }
+  sharedWalkFiles(dir, (full) => {
+    if (filePattern.test(basename(full))) files.push(full);
+  }, { ignoreDirs: IGNORE_DIRS });
 }
 
 /**

package/cli/validators/security.mjs

@@ -7,7 +7,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { shouldIgnore, relPosix } from '../shared-ignore.mjs';
+import { shouldIgnore, relPosix, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings, lineSuppresses } from '../findings.mjs';
 
 // Each secret pattern maps to a stable finding code (see cli/findings.mjs CODES)
@@ -233,24 +233,11 @@ export function validateSecurity(projectDir, config) {
   return resultFromFindings(findings, { passed, total });
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker.
+// keepDot('.env') is LOAD-BEARING — a secrets validator must scan dotenv files.
 function walkDir(dir, callback) {
-  if (!existsSync(dir)) return;
-
-  const entries = readdirSync(dir);
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry)) continue;
-    if (entry.startsWith('.') && entry !== '.env') continue;
-
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        walkDir(fullPath, callback);
-      } else if (stat.isFile()) {
-        callback(fullPath);
-      }
-    } catch {
-      // Skip unreadable files
-    }
-  }
+  sharedWalkFiles(dir, callback, {
+    ignoreDirs: IGNORE_DIRS,
+    keepDot: (entry) => entry === '.env',
+  });
 }

package/cli/validators/spec-kit.mjs

@@ -9,6 +9,9 @@
  *
  * Re-exports `validateSpecKitIntegration` from the scanner. Importers should
  * use this path (`validators/spec-kit.mjs`) going forward.
+ *
+ * v0.29: the validator emits structured findings (SPK001–SPK007); the
+ * migration lives in `scanners/speckit.mjs` alongside the validation logic.
  */
 
 export { validateSpecKitIntegration } from '../scanners/speckit.mjs';

package/cli/validators/structure.mjs

@@ -1,22 +1,39 @@
 /**
  * Structure Validator — Checks that all required CDD files exist
+ *
+ * v0.29: migrated to structured findings (STR001–STR003). 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.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { docHasSection } from '../shared.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 export function validateStructure(projectDir, config) {
-  const results = { name: 'structure', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
+
+  const missingFile = (file) => mkFinding({
+    code: 'STR001',
+    validator: 'structure',
+    severity: 'error',
+    message: `Missing required file: ${file}`,
+    location: file,
+    suggestion: { kind: 'fix', text: 'Create it from the professional template', command: 'docguard init' },
+  });
 
   // Check canonical docs
   for (const file of config.requiredFiles.canonical) {
-    results.total++;
+    total++;
     const fullPath = resolve(projectDir, file);
     if (existsSync(fullPath)) {
-      results.passed++;
+      passed++;
     } else {
-      results.errors.push(`Missing required file: ${file}`);
+      findings.push(missingFile(file));
     }
   }
 
@@ -27,44 +44,53 @@ export function validateStructure(projectDir, config) {
     ? config.requiredFiles.agentFile
     : (typeof config.requiredFiles?.agentFile === 'string' ? [config.requiredFiles.agentFile] : []);
   if (agentFiles.length > 0) {
-    results.total++;
+    total++;
     const agentFileFound = agentFiles.some(f =>
       existsSync(resolve(projectDir, f))
     );
     if (agentFileFound) {
-      results.passed++;
+      passed++;
     } else {
-      results.errors.push(`Missing agent file: ${agentFiles.join(' or ')}`);
+      findings.push(mkFinding({
+        code: 'STR002',
+        validator: 'structure',
+        severity: 'error',
+        message: `Missing agent file: ${agentFiles.join(' or ')}`,
+        location: agentFiles[0],
+        suggestion: { kind: 'fix', text: 'Create the agent instructions file', command: 'docguard init' },
+      }));
     }
   }
 
   // Check changelog — same defensive pattern.
   const changelogPath = config.requiredFiles?.changelog;
   if (changelogPath) {
-    results.total++;
+    total++;
     if (existsSync(resolve(projectDir, changelogPath))) {
-      results.passed++;
+      passed++;
     } else {
-      results.errors.push(`Missing required file: ${changelogPath}`);
+      findings.push(missingFile(changelogPath));
     }
   }
 
   // Check drift log
-  results.total++;
+  total++;
   if (existsSync(resolve(projectDir, config.requiredFiles.driftLog))) {
-    results.passed++;
+    passed++;
   } else {
-    results.errors.push(`Missing required file: ${config.requiredFiles.driftLog}`);
+    findings.push(missingFile(config.requiredFiles.driftLog));
   }
 
-  return results;
+  return { name: 'structure', ...resultFromFindings(findings, { passed, total }) };
 }
 
 /**
  * Check that canonical doc files contain required sections
  */
 export function validateDocSections(projectDir, config) {
-  const results = { name: 'doc-sections', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
   const ptc = config.projectTypeConfig || {};
 
   const requiredSections = {
@@ -86,7 +112,7 @@ export function validateDocSections(projectDir, config) {
     const content = readFileSync(fullPath, 'utf-8');
 
     for (const section of sections) {
-      results.total++;
+      total++;
       // Match a real heading (H2–H6), not a substring in a TOC link or code
       // block. v0.24: synonym- and section-number-tolerant via docHasSection, so
       // arc42/C4 docs ("## 5.4 Layer boundaries", "## Building Block View")
@@ -110,19 +136,28 @@ export function validateDocSections(projectDir, config) {
         'i'
       );
       if (docHasSection(content, section)) {
-        results.passed++;
+        passed++;
       } else if (naRe.test(content)) {
         // v0.16-P7: explicit N/A — counts as passed (the project has owned
         // the absence) and doesn't pollute the warnings list.
-        results.passed++;
+        passed++;
       } else {
-        results.warnings.push(
-          `${file}: missing section "${section}". ` +
-          `If genuinely not applicable, add: <!-- docguard:section ${slug} n/a — your reason -->`
-        );
+        findings.push(mkFinding({
+          code: 'STR003',
+          validator: 'structure',
+          severity: 'warn',
+          message: `${file}: missing section "${section}". ` +
+            `If genuinely not applicable, add: <!-- docguard:section ${slug} n/a — your reason -->`,
+          location: file,
+          suggestion: {
+            kind: 'suppress',
+            text: 'Add the section, or own the absence with the inline N/A marker',
+            pragma: `<!-- docguard:section ${slug} n/a — your reason -->`,
+          },
+        }));
       }
     }
   }
 
-  return results;
+  return { name: 'doc-sections', ...resultFromFindings(findings, { passed, total }) };
 }

package/cli/validators/surface-sync.mjs

@@ -59,6 +59,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, basename, extname, relative, dirname } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * Expand a simple glob (only supports `*` at the leaf segment level —
@@ -223,10 +224,13 @@ function extractDocumentedTokens(content) {
 
 /**
  * Validate surface drift for a single surface against its target docs.
- * Returns warnings, fixes, passed count, and total count.
+ * Returns findings, fixes, passed count, and total count.
+ *
+ * v0.29: migrated to structured findings (SSY001–SSY002). Messages are
+ * byte-identical to the legacy strings.
  */
 function checkSurface(projectDir, surface) {
-  const out = { warnings: [], fixes: [], passed: 0, total: 0 };
+  const out = { findings: [], fixes: [], passed: 0, total: 0 };
   const name = surface.name || 'unnamed';
   const extractor = surface.extract || 'basename-no-ext';
   const ignore = new Set(surface.ignore || []);
@@ -236,9 +240,14 @@ function checkSurface(projectDir, surface) {
 
   // Discover code-truth set from glob.
   if (!surface.glob || typeof surface.glob !== 'string') {
-    out.warnings.push(
-      `surfaceSync: surface "${name}" has no \`glob\` — skipping. Add a glob like "cli/commands/*.mjs".`
-    );
+    out.findings.push(mkFinding({
+      code: 'SSY001',
+      validator: 'surfaceSync',
+      severity: 'warn',
+      message: `surfaceSync: surface "${name}" has no \`glob\` — skipping. Add a glob like "cli/commands/*.mjs".`,
+      location: '.docguard.json',
+      suggestion: { kind: 'fix', text: `Add a \`glob\` to the "${name}" surface entry under surfaceSync.surfaces in .docguard.json` },
+    }));
     return out;
   }
   const files = expandGlob(projectDir, surface.glob);
@@ -319,7 +328,14 @@ function checkSurface(projectDir, surface) {
       const tail = extra > 0 ? ` (+${extra} more)` : '';
       parts.push(`${missingFromCode.length} listed in ${docRel} but not found in code: ${shown}${tail}`);
     }
-    out.warnings.push(`Surface "${name}" drift: ${parts.join('; ')}`);
+    out.findings.push(mkFinding({
+      code: 'SSY002',
+      validator: 'surfaceSync',
+      severity: 'warn',
+      message: `Surface "${name}" drift: ${parts.join('; ')}`,
+      location: docRel,
+      suggestion: { kind: 'review', text: `Update the "${name}" list/table in ${docRel} to match the code-truth set — add missing items, remove ghosts, or put aliases in the surface's ignore list` },
+    }));
   }
 
   return out;
@@ -347,21 +363,24 @@ export function validateSurfaceSync(projectDir, config) {
     ? config.surfaceSync.surfaces
     : [];
 
-  const result = { errors: [], warnings: [], fixes: [], passed: 0, total: 0 };
-
   if (surfaceCfg.length === 0) {
     // No surfaces configured → N/A. The validator infrastructure surfaces
-    // this as "nothing to validate" rather than a fail.
-    return result;
+    // this as "nothing to validate" rather than a fail. Legacy shape kept.
+    return { errors: [], warnings: [], fixes: [], passed: 0, total: 0 };
   }
 
+  const findings = [];
+  const fixes = [];
+  let passed = 0;
+  let total = 0;
+
   for (const surface of surfaceCfg) {
     const r = checkSurface(projectDir, surface);
-    result.warnings.push(...r.warnings);
-    result.fixes.push(...r.fixes);
-    result.passed += r.passed;
-    result.total += r.total;
+    findings.push(...r.findings);
+    fixes.push(...r.fixes);
+    passed += r.passed;
+    total += r.total;
   }
 
-  return result;
+  return { ...resultFromFindings(findings, { passed, total }), fixes };
 }