docguard-cli 0.27.0 → 0.29.0

package/cli/validators/generated-staleness.mjs

@@ -28,6 +28,7 @@ import { resolve, basename, join } from 'node:path';
 
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { getSection } from '../writers/sections.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * v0.18-P1 fast-path: cheap pre-flight to detect whether ANY canonical doc
@@ -103,7 +104,12 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
   // `applyMechanicalFixes` can consume it via the new regenerate-section
   // applier. Lets `fix --write` actually CLOSE the loop on drift instead
   // of just warning. No AI needed — the scanner already knows the right body.
+  //
+  // v0.29: migrated to structured findings (GST001–GST002). Messages are
+  // byte-identical to the legacy strings; the N/A early returns keep the
+  // legacy shape, and `fixes` is preserved for the fix applier.
   const result = { errors: [], warnings: [], passed: 0, total: 0, fixes: [] };
+  const findings = [];
 
   // v0.18-P1: cheap pre-flight. If no canonical doc has a source=code marker
   // AND no doc is in status:draft, this validator has nothing to do — skip
@@ -150,10 +156,15 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
         const mtime = statSync(fullPath).mtime;
         const ageDays = (Date.now() - mtime.getTime()) / (1000 * 60 * 60 * 24);
         if (ageDays > draftThresholdDays) {
-          result.warnings.push(
-            `${basename(doc.path)} has been in \`status: draft\` for ${Math.floor(ageDays)} days. ` +
-            `Promote to status:current or remove. Run \`/docguard.fix --doc ${basename(doc.path)}\` to draft the prose.`
-          );
+          findings.push(mkFinding({
+            code: 'GST001',
+            validator: 'generatedStaleness',
+            severity: 'warn',
+            message: `${basename(doc.path)} has been in \`status: draft\` for ${Math.floor(ageDays)} days. ` +
+              `Promote to status:current or remove. Run \`/docguard.fix --doc ${basename(doc.path)}\` to draft the prose.`,
+            location: doc.path,
+            suggestion: { kind: 'review', text: 'Draft the prose and promote to status:current, or delete the forgotten skeleton', command: `/docguard.fix --doc ${basename(doc.path)}` },
+          }));
         } else {
           result.passed++;
         }
@@ -206,11 +217,16 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
         ? ` (first drift at line ${firstDiff + 1} of section: "${(act[firstDiff] || '').slice(0, 60)}…" vs scanner: "${(exp[firstDiff] || '').slice(0, 60)}…")`
         : '';
 
-      result.warnings.push(
-        `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections. ` +
-        `If this section is intentionally hand-maintained (the scanner mislabeled it), pin it: ` +
-        `add \`pinned="reason"\` to its \`<!-- docguard:section id=${sec.id} … -->\` marker.`
-      );
+      findings.push(mkFinding({
+        code: 'GST002',
+        validator: 'generatedStaleness',
+        severity: 'warn',
+        message: `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections. ` +
+          `If this section is intentionally hand-maintained (the scanner mislabeled it), pin it: ` +
+          `add \`pinned="reason"\` to its \`<!-- docguard:section id=${sec.id} … -->\` marker.`,
+        location: doc.path,
+        suggestion: { kind: 'fix', text: 'Refresh the code-truth section (or pin it if it is intentionally hand-maintained)', command: 'docguard sync --write' },
+      }));
       // v0.14-P3: structured fix so `docguard fix --write` can fix this
       // mechanically (no AI needed — scanner already produced the right body).
       result.fixes.push({
@@ -230,5 +246,5 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
     return { ...result, applicable: false };
   }
 
-  return result;
+  return { ...resultFromFindings(findings, { passed: result.passed, total: result.total }), fixes: result.fixes };
 }

package/cli/validators/metadata-sync.mjs

@@ -3,12 +3,18 @@
  *
  * Cross-checks package.json version against extension.yml and all .md files.
  * Flags outdated version strings (e.g., README references v0.7.2 but package.json is 0.8.0).
+ *
+ * v0.29: migrated to structured findings (MDS001–MDS002). Messages are
+ * byte-identical to the legacy strings; the `fixes` array is preserved for
+ * the fix applier.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname } from 'node:path';
 import { loadIgnorePatterns } from '../shared.mjs';
 import { collectPackageJsons } 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',
@@ -22,7 +28,7 @@ const IGNORE_DIRS = new Set([
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
  */
 export function validateMetadataSync(projectDir, config) {
-  const warnings = [];
+  const findings = [];
   const fixes = [];
   let passed = 0;
   let total = 0;
@@ -45,7 +51,8 @@ export function validateMetadataSync(projectDir, config) {
       if (pkg.version) { currentVersion = pkg.version; currentName = currentName || pkg.name || null; break; }
     }
   }
-  if (!currentVersion) return { errors: [], warnings, passed: 0, total: 0 };
+  // Literal legacy shape (no findings/fixes keys) — tests deepEqual this object.
+  if (!currentVersion) return { errors: [], warnings: [], passed: 0, total: 0 };
 
   // Parse into components for smart comparison. `|| 0` guards two-part versions
   // (e.g. "1.2"): without it vParts[2] is undefined → parseInt → NaN, and every
@@ -65,9 +72,14 @@ export function validateMetadataSync(projectDir, config) {
       const versionMatch = content.match(/version:\s*["']?(\d+\.\d+\.\d+)["']?/);
       if (versionMatch) {
         if (versionMatch[1] !== currentVersion) {
-          warnings.push(
-            `${relPath} has version "${versionMatch[1]}" but package.json is "${currentVersion}"`
-          );
+          findings.push(mkFinding({
+            code: 'MDS001',
+            validator: 'metadataSync',
+            severity: 'warn',
+            message: `${relPath} has version "${versionMatch[1]}" but package.json is "${currentVersion}"`,
+            location: relPath,
+            suggestion: { kind: 'fix', text: `Update the version field to ${currentVersion}`, command: 'docguard fix --write' },
+          }));
           fixes.push({ type: 'replace-version', file: relPath, found: versionMatch[1], actual: currentVersion });
         } else {
           passed++;
@@ -129,9 +141,14 @@ export function validateMetadataSync(projectDir, config) {
 
         if (isOlder && foundVersion !== currentVersion) {
           total++;
-          warnings.push(
-            `${relPath} references "v${foundVersion}" in an actionable context (URL/install/declaration) but current version is "${currentVersion}"`
-          );
+          findings.push(mkFinding({
+            code: 'MDS002',
+            validator: 'metadataSync',
+            severity: 'warn',
+            message: `${relPath} references "v${foundVersion}" in an actionable context (URL/install/declaration) but current version is "${currentVersion}"`,
+            location: relPath,
+            suggestion: { kind: 'fix', text: `Replace the stale ${foundVersion} reference with ${currentVersion}`, command: 'docguard fix --write' },
+          }));
           if (!fixes.some(f => f.file === relPath && f.found === foundVersion)) {
             fixes.push({ type: 'replace-version', file: relPath, found: foundVersion, actual: currentVersion });
           }
@@ -143,7 +160,7 @@ export function validateMetadataSync(projectDir, config) {
     }
   }
 
-  return { errors: [], warnings, passed, total, fixes };
+  return { ...resultFromFindings(findings, { passed, total }), fixes };
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -186,21 +203,7 @@ function findMarkdownFiles(dir) {
   return mdFiles;
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker.
 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 { /* skip */ }
-  }
+  sharedWalkFiles(dir, callback, { ignoreDirs: IGNORE_DIRS });
 }

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';