docguard-cli 0.28.0 → 0.30.0

package/cli/validators/test-spec.mjs

@@ -1,18 +1,30 @@
 /**
  * Test Spec Validator — Checks that tests exist per TEST-SPEC.md coverage rules
  * Now respects projectTypeConfig (e.g., skip E2E for CLI tools)
+ *
+ * v0.29: migrated to structured findings (TSP001–TSP007). 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, readdirSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 export function validateTestSpec(projectDir, config) {
-  const results = { name: 'test-spec', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
+  let note;
 
-  const testSpecPath = resolve(projectDir, 'docs-canonical/TEST-SPEC.md');
+  const specDoc = 'docs-canonical/TEST-SPEC.md';
+  const testSpecPath = resolve(projectDir, specDoc);
   if (!existsSync(testSpecPath)) {
-    return results; // Structure validator catches this
+    // Structure validator catches this. Keep the exact legacy shape here
+    // (no `findings` key) — tests deep-equal this early return.
+    return { name: 'test-spec', errors: [], warnings: [], passed: 0, total: 0 };
   }
 
   const content = readFileSync(testSpecPath, 'utf-8');
@@ -80,22 +92,44 @@ export function validateTestSpec(projectDir, config) {
       // author's CLAIM, not proof — it is NOT counted as a pass. The real pass
       // comes from the file-existence checks below (code truth, not the glyph).
       if (status.includes('❌')) {
-        results.total++;
-        results.warnings.push(`TEST-SPEC declares ${sourceFile} as ❌ — missing tests`);
+        total++;
+        findings.push(mkFinding({
+          code: 'TSP001',
+          validator: 'testSpec',
+          severity: 'warn',
+          message: `TEST-SPEC declares ${sourceFile} as ❌ — missing tests`,
+          location: specDoc,
+          suggestion: { kind: 'fix', text: 'Write the missing tests, then update the row status to ✅' },
+        }));
       } else if (status.includes('⚠️')) {
-        results.total++;
-        results.warnings.push(`TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`);
+        total++;
+        findings.push(mkFinding({
+          code: 'TSP002',
+          validator: 'testSpec',
+          severity: 'warn',
+          message: `TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`,
+          location: specDoc,
+          suggestion: { kind: 'fix', text: 'Extend coverage for this source, then update the row status to ✅' },
+        }));
       }
 
       // ── File existence checks ───────────────────────────────────────
       // Verify source file still exists (catch stale map entries).
       const cleanSource = sourceFile.replace(/`/g, '').trim();
       if (cleanSource && cleanSource !== '—' && cleanSource !== 'Source File' && isPathLike(cleanSource)) {
-        results.total++;
+        total++;
         if (existsSync(resolve(projectDir, cleanSource))) {
-          results.passed++;
+          passed++;
         } else {
-          results.warnings.push(`Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`);
+          findings.push(mkFinding({
+            code: 'TSP003',
+            validator: 'testSpec',
+            severity: 'warn',
+            confidence: 'low',
+            message: `Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`,
+            location: specDoc,
+            suggestion: { kind: 'review', text: 'Update or remove the stale row if the source file moved or was deleted' },
+          }));
         }
       }
 
@@ -104,11 +138,18 @@ export function validateTestSpec(projectDir, config) {
       for (const ti of testIdxs) {
         const cleanTest = (cells[ti] || '').replace(/`/g, '').trim();
         if (isPlaceholder(cleanTest) || !isPathLike(cleanTest)) continue;
-        results.total++;
+        total++;
         if (existsSync(resolve(projectDir, cleanTest))) {
-          results.passed++;
+          passed++;
         } else {
-          results.warnings.push(`Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`);
+          findings.push(mkFinding({
+            code: 'TSP004',
+            validator: 'testSpec',
+            severity: 'warn',
+            message: `Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`,
+            location: specDoc,
+            suggestion: { kind: 'fix', text: 'Create the test file, or point the row at the actual test path' },
+          }));
         }
       }
     }
@@ -140,10 +181,15 @@ export function validateTestSpec(projectDir, config) {
         if (num.startsWith('<!--') || num === '#' || journey.startsWith('<!--')) continue;
 
         if (status && status.includes('❌')) {
-          results.total++;
-          results.warnings.push(
-            `E2E Journey #${num} (${journey}) — missing test: ${testFile}`
-          );
+          total++;
+          findings.push(mkFinding({
+            code: 'TSP005',
+            validator: 'testSpec',
+            severity: 'warn',
+            message: `E2E Journey #${num} (${journey}) — missing test: ${testFile}`,
+            location: specDoc,
+            suggestion: { kind: 'fix', text: 'Implement the journey test, then update the row status to ✅' },
+          }));
           continue;
         }
 
@@ -154,14 +200,19 @@ export function validateTestSpec(projectDir, config) {
         if (testFile && testFile.trim() !== '—' && !testFile.includes('N/A')) {
           const paths = parseTestPathCell(testFile);
           if (paths.length > 0) {
-            results.total++;
+            total++;
             const anyExists = paths.some(p => testEvidenceExists(projectDir, p));
             if (anyExists) {
-              results.passed++;
+              passed++;
             } else {
-              results.warnings.push(
-                `E2E Journey #${num} (${journey}) marked ✅ but test file not found: ${paths.join(', ')}`
-              );
+              findings.push(mkFinding({
+                code: 'TSP006',
+                validator: 'testSpec',
+                severity: 'warn',
+                message: `E2E Journey #${num} (${journey}) marked ✅ but test file not found: ${paths.join(', ')}`,
+                location: specDoc,
+                suggestion: { kind: 'review', text: 'Fix the test path in the row, or restore the missing test file' },
+              }));
             }
           }
         }
@@ -172,7 +223,7 @@ export function validateTestSpec(projectDir, config) {
   // If TEST-SPEC.md declared no service-to-test mappings, there is nothing to
   // verify against. Do NOT manufacture a 1/1 pass just because tests exist
   // somewhere — that rendered a confident green ✅ for a doc that mapped nothing.
-  if (results.total === 0) {
+  if (total === 0) {
     // 1. Check top-level test dirs
     const commonTestDirs = ['tests', 'test', '__tests__', 'spec'];
     const hasTestDir = commonTestDirs.some(d =>
@@ -200,16 +251,23 @@ export function validateTestSpec(projectDir, config) {
       // file, and the last as status — so both the minimal 3-column shape and
       // the 4-column table `docguard generate` emits are accepted. Say so, since
       // the guidance previously contradicted the generated skeleton (field report).
-      results.note = 'TEST-SPEC.md declares no service-to-test mappings. Add a "## Source-to-Test Map" table — column 1 is the source, column 2 the test file, the last column the status. Both `| Source | Test file | Status |` and the generated `| Source File | Unit Test | Integration Test | Status |` shapes work. Run `docguard explain testSpec` for details.';
+      note = 'TEST-SPEC.md declares no service-to-test mappings. Add a "## Source-to-Test Map" table — column 1 is the source, column 2 the test file, the last column the status. Both `| Source | Test file | Status |` and the generated `| Source File | Unit Test | Integration Test | Status |` shapes work. Run `docguard explain testSpec` for details.';
     } else {
-      results.warnings.push(
-        'No test directory or co-located test files found. ' +
-        'Expected: tests/, src/**/__tests__/, or src/**/*.test.* files'
-      );
+      findings.push(mkFinding({
+        code: 'TSP007',
+        validator: 'testSpec',
+        severity: 'warn',
+        message: 'No test directory or co-located test files found. ' +
+          'Expected: tests/, src/**/__tests__/, or src/**/*.test.* files',
+        location: null,
+        suggestion: { kind: 'fix', text: 'Create a tests/ directory or co-located *.test.* files, then map them in TEST-SPEC.md' },
+      }));
     }
   }
 
-  return results;
+  const res = { name: 'test-spec', ...resultFromFindings(findings, { passed, total }) };
+  if (note) res.note = note;
+  return res;
 }
 
 /**

package/cli/validators/todo-tracking.mjs

@@ -17,7 +17,8 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname } 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', 'coverage',
@@ -77,25 +78,34 @@ const SKIP_REASON_PATTERN = /\/\/\s*(REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:/i;
 
 /**
  * Main validator — checks for untracked TODOs and unexplained test skips.
+ *
+ * v0.29: migrated to structured findings (TDO001–TDO003). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings array.
  */
 export function validateTodoTracking(projectDir, config) {
-  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
 
   // ── Part 1: Skipped Tests ──
   const skipResults = checkSkippedTests(projectDir, config);
-  results.errors.push(...skipResults.errors);
-  results.warnings.push(...skipResults.warnings);
-  results.passed += skipResults.passed;
-  results.total += skipResults.total;
+  findings.push(...skipResults.findings);
+  passed += skipResults.passed;
+  total += skipResults.total;
 
   // ── Part 2: Untracked Annotations ──
   const todoResults = checkUntrackedTodos(projectDir, config);
-  results.errors.push(...todoResults.errors);
-  results.warnings.push(...todoResults.warnings);
-  results.passed += todoResults.passed;
-  results.total += todoResults.total;
-
-  return results;
+  findings.push(...todoResults.findings);
+  passed += todoResults.passed;
+  total += todoResults.total;
+
+  const res = resultFromFindings(findings, { passed, total });
+  // Back-compat: on a clean run the legacy result carried no extra keys (the
+  // empty-project test deep-equals the whole object), and an empty findings
+  // array has nothing to render — so omit the key when there are no findings.
+  if (findings.length === 0) delete res.findings;
+  return res;
 }
 
 // ──── Skipped Tests ────────────────────────────────────────────────────────
@@ -104,15 +114,14 @@ export function validateTodoTracking(projectDir, config) {
  * Scan test files for skip/todo patterns without adjacent explanation comments.
  */
 function checkSkippedTests(projectDir, config) {
-  const errors = [];
-  const warnings = [];
+  const findings = [];
   let passed = 0;
   let total = 0;
 
   const testFiles = [];
   findTestFiles(projectDir, projectDir, testFiles, config);
 
-  if (testFiles.length === 0) return { errors, warnings, passed, total };
+  if (testFiles.length === 0) return { findings, passed, total };
 
   // Check: "Project has test files" → pass
   total++;
@@ -157,10 +166,19 @@ function checkSkippedTests(projectDir, config) {
         skippedWithReason++;
       } else {
         skippedWithoutReason++;
-        warnings.push(
-          `Skipped test without explanation at ${relPath}:${i + 1}. ` +
-          `Add a // REASON: comment explaining why the test is skipped`
-        );
+        findings.push(mkFinding({
+          code: 'TDO001',
+          validator: 'todoTracking',
+          severity: 'warn',
+          message: `Skipped test without explanation at ${relPath}:${i + 1}. ` +
+            `Add a // REASON: comment explaining why the test is skipped`,
+          location: `${relPath}:${i + 1}`,
+          suggestion: {
+            kind: 'fix',
+            text: 'Add a // REASON: comment on or up to 3 lines above the skip explaining why',
+            pragma: '// REASON: <why this test is skipped>',
+          },
+        }));
       }
     }
   }
@@ -173,7 +191,7 @@ function checkSkippedTests(projectDir, config) {
     }
   }
 
-  return { errors, warnings, passed, total };
+  return { findings, passed, total };
 }
 
 // ──── Untracked Annotations ────────────────────────────────────────────────
@@ -183,8 +201,7 @@ function checkSkippedTests(projectDir, config) {
  * in tracking documentation.
  */
 function checkUntrackedTodos(projectDir, config) {
-  const errors = [];
-  const warnings = [];
+  const findings = [];
   let passed = 0;
   let total = 0;
 
@@ -196,7 +213,7 @@ function checkUntrackedTodos(projectDir, config) {
     // No TODOs found — that's clean code
     total++;
     passed++;
-    return { errors, warnings, passed, total };
+    return { findings, passed, total };
   }
 
   // Check if TODOs are tracked in documentation
@@ -235,23 +252,41 @@ function checkUntrackedTodos(projectDir, config) {
       untrackedCount++;
       // Only report first 5 to avoid noise
       if (untrackedCount <= 5) {
-        warnings.push(
-          `Untracked ${todo.keyword} at ${todo.file}:${todo.line}: "${todo.text.substring(0, 60)}". ` +
-          `Add to ROADMAP.md, CURRENT-STATE.md, or a GitHub issue`
-        );
+        findings.push(mkFinding({
+          code: 'TDO002',
+          validator: 'todoTracking',
+          severity: 'warn',
+          message: `Untracked ${todo.keyword} at ${todo.file}:${todo.line}: "${todo.text.substring(0, 60)}". ` +
+            `Add to ROADMAP.md, CURRENT-STATE.md, or a GitHub issue`,
+          location: `${todo.file}:${todo.line}`,
+          suggestion: {
+            kind: 'fix',
+            text: 'Track it in ROADMAP.md or CURRENT-STATE.md (or resolve it) — or exclude the path via todoIgnore in .docguard.json',
+          },
+        }));
       }
     }
   }
 
   if (untrackedCount > 5) {
-    warnings.push(`...and ${untrackedCount - 5} more untracked TODO/FIXME items`);
+    findings.push(mkFinding({
+      code: 'TDO003',
+      validator: 'todoTracking',
+      severity: 'warn',
+      message: `...and ${untrackedCount - 5} more untracked TODO/FIXME items`,
+      location: null,
+      suggestion: {
+        kind: 'suppress',
+        text: 'Address the items above and re-run guard to surface the rest — or exclude noisy paths via todoIgnore in .docguard.json',
+      },
+    }));
   }
 
   if (untrackedCount === 0) {
     passed++;
   }
 
-  return { errors, warnings, passed, total };
+  return { findings, passed, total };
 }
 
 /**
@@ -285,34 +320,23 @@ function loadTrackingDocs(projectDir, config) {
 
 // ──── File Scanners ────────────────────────────────────────────────────────
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker;
+// test-file pattern matching and config-ignore filtering stay per-file here.
 function findTestFiles(rootDir, dir, files, config) {
-  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()) {
-      findTestFiles(rootDir, full, files, config);
-    } else {
-      const ext = extname(entry).toLowerCase();
-      if (!TEST_EXTENSIONS.has(ext)) continue;
-
-      // Match test file patterns
-      if (/\.(test|spec)\.(mjs|cjs|[jt]sx?)$/.test(entry) ||
-          /__(tests|test)__/.test(relative(rootDir, full))) {
-        const relPath = relative(rootDir, full);
-        // Apply config ignore patterns (todoIgnore + global ignore)
-        if (config && shouldIgnore(relPath, config, 'todoIgnore')) continue;
-        files.push(relPath);
-      }
+  sharedWalkFiles(dir, (full) => {
+    const entry = full.slice(full.lastIndexOf('/') + 1);
+    const ext = extname(entry).toLowerCase();
+    if (!TEST_EXTENSIONS.has(ext)) return;
+
+    // Match test file patterns
+    if (/\.(test|spec)\.(mjs|cjs|[jt]sx?)$/.test(entry) ||
+        /__(tests|test)__/.test(relative(rootDir, full))) {
+      const relPath = relative(rootDir, full);
+      // Apply config ignore patterns (todoIgnore + global ignore)
+      if (config && shouldIgnore(relPath, config, 'todoIgnore')) return;
+      files.push(relPath);
     }
-  }
+  }, { ignoreDirs: IGNORE_DIRS });
 }
 
 // Test-file path patterns — TODO scanning skips these by default to avoid
@@ -349,25 +373,10 @@ function findTodos(rootDir, dir, todos, config) {
     return;
   }
 
-  let entries;
-  try { entries = readdirSync(dir); } catch { return; }
-
-  const includeTests = config?.todoTracking?.includeTestFiles === true;
-
-  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()) {
-      findTodos(rootDir, full, todos, config);
-    } else {
-      _scanTodoFile(rootDir, full, todos, config);
-    }
-  }
+  // v0.29 consolidation: traversal delegates to the shared canonical walker.
+  sharedWalkFiles(dir, (full) => _scanTodoFile(rootDir, full, todos, config), {
+    ignoreDirs: IGNORE_DIRS,
+  });
 }
 
 /**

package/cli/validators/traceability.mjs

@@ -16,6 +16,8 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
 import { TRACE_MAP, TEST_PATTERNS, isTraceableSource } from '../shared-trace-patterns.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',
@@ -51,18 +53,21 @@ const DEFAULT_REQ_PATTERNS = [
  * Validate traceability — ensures canonical docs have corresponding source artifacts,
  * and requirement IDs trace through to test files.
  * Respects config.requiredFiles.canonical — only checks docs the user requires.
+ *
+ * v0.29: migrated to structured findings (TRC001–TRC005). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings array.
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
  */
 export function validateTraceability(projectDir, config) {
-  const errors = [];
-  const warnings = [];
+  const findings = [];
   let passed = 0;
   let total = 0;
 
   const docsDir = resolve(projectDir, 'docs-canonical');
   if (!existsSync(docsDir)) {
     // No docs-canonical dir at all — structure validator handles this
-    return { errors, warnings, passed: 0, total: 0 };
+    return resultFromFindings([], { passed: 0, total: 0 });
   }
 
   // Build set of required doc basenames from config
@@ -93,7 +98,14 @@ export function validateTraceability(projectDir, config) {
     const docExists = existsSync(docPath);
 
     if (!docExists) {
-      warnings.push(`${docName} — required but missing, no traceability possible`);
+      findings.push(mkFinding({
+        code: 'TRC001',
+        validator: 'traceability',
+        severity: 'warn',
+        message: `${docName} — required but missing, no traceability possible`,
+        location: `docs-canonical/${docName}`,
+        suggestion: { kind: 'fix', text: 'Create the required doc from the professional template', command: 'docguard init' },
+      }));
       continue;
     }
 
@@ -121,7 +133,18 @@ export function validateTraceability(projectDir, config) {
     if (hasSource) {
       passed++;
     } else {
-      warnings.push(`${docName} — exists but no matching source code found (unlinked doc)`);
+      findings.push(mkFinding({
+        code: 'TRC002',
+        validator: 'traceability',
+        severity: 'warn',
+        message: `${docName} — exists but no matching source code found (unlinked doc)`,
+        location: `docs-canonical/${docName}`,
+        suggestion: {
+          kind: 'fix',
+          text: 'Link a source file explicitly with a header annotation if the code lives in a non-standard location',
+          pragma: `// @doc ${docName}`,
+        },
+      }));
     }
   }
 
@@ -130,19 +153,25 @@ export function validateTraceability(projectDir, config) {
     const existingDocs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
     for (const docFile of existingDocs) {
       if (!requiredDocs.has(docFile) && TRACE_MAP[docFile]) {
-        warnings.push(`${docFile} — file exists in docs-canonical/ but is not in your requiredFiles config. Consider deleting it or adding it to .docguard.json requiredFiles.canonical`);
+        findings.push(mkFinding({
+          code: 'TRC003',
+          validator: 'traceability',
+          severity: 'warn',
+          message: `${docFile} — file exists in docs-canonical/ but is not in your requiredFiles config. Consider deleting it or adding it to .docguard.json requiredFiles.canonical`,
+          location: `docs-canonical/${docFile}`,
+          suggestion: { kind: 'review', text: 'Delete the doc, or add it to requiredFiles.canonical in .docguard.json so it gets validated' },
+        }));
       }
     }
   } catch { /* ignore */ }
 
   // ── Part 2: Requirement ID Traceability (V-Model) ──
   const reqResult = validateRequirementTraceability(projectDir, config, projectFiles);
-  errors.push(...reqResult.errors);
-  warnings.push(...reqResult.warnings);
+  findings.push(...reqResult.findings);
   passed += reqResult.passed;
   total += reqResult.total;
 
-  return { errors, warnings, passed, total };
+  return resultFromFindings(findings, { passed, total });
 }
 
 // ──── Requirement ID Traceability ────────────────────────────────────────────
@@ -156,8 +185,7 @@ export function validateTraceability(projectDir, config) {
  *   - Reports untraced requirements and orphaned test refs
  */
 function validateRequirementTraceability(projectDir, config, projectFiles) {
-  const errors = [];
-  const warnings = [];
+  const findings = [];
   let passed = 0;
   let total = 0;
 
@@ -172,7 +200,7 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
 
   // If no requirement IDs found, silently pass — this project doesn't use them
   if (reqIds.size === 0) {
-    return { errors, warnings, passed, total };
+    return { findings, passed, total };
   }
 
   // ── Step 2: Scan test files for requirement ID references ──
@@ -186,10 +214,15 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
     if (testRefs.has(reqId)) {
       passed++;
     } else {
-      warnings.push(
-        `Requirement ${reqId} (${location.file}:${location.line}) has no test coverage. ` +
-        `Add @req ${reqId} comment to the test that verifies this requirement`
-      );
+      findings.push(mkFinding({
+        code: 'TRC004',
+        validator: 'traceability',
+        severity: 'warn',
+        message: `Requirement ${reqId} (${location.file}:${location.line}) has no test coverage. ` +
+          `Add @req ${reqId} comment to the test that verifies this requirement`,
+        location: `${location.file}:${location.line}`,
+        suggestion: { kind: 'fix', text: `Add an @req ${reqId} comment to the test that verifies this requirement` },
+      }));
     }
   }
 
@@ -197,14 +230,19 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   for (const [reqId, refs] of testRefs) {
     if (!reqIds.has(reqId)) {
       total++;
-      warnings.push(
-        `Test references ${reqId} (${refs[0].file}:${refs[0].line}) but no requirement ` +
-        `with this ID exists in documentation. Remove the reference or add the requirement to docs`
-      );
+      findings.push(mkFinding({
+        code: 'TRC005',
+        validator: 'traceability',
+        severity: 'warn',
+        message: `Test references ${reqId} (${refs[0].file}:${refs[0].line}) but no requirement ` +
+          `with this ID exists in documentation. Remove the reference or add the requirement to docs`,
+        location: `${refs[0].file}:${refs[0].line}`,
+        suggestion: { kind: 'review', text: 'Remove the stale reference, or add the requirement to the documentation' },
+      }));
     }
   }
 
-  return { errors, warnings, passed, total };
+  return { findings, passed, total };
 }
 
 function collectRequirementIds(projectDir, config, patterns) {
@@ -377,23 +415,13 @@ function scanDocAnnotations(projectFiles, projectDir) {
   return map;
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker.
+// keepDot preserves the traceability-relevant dot entries (.env, .env.example,
+// .gitignore, .github/) that a doc may legitimately reference.
 function scanDir(rootDir, dir, files) {
-  let entries;
-  try { entries = readdirSync(dir); } catch { return; }
-
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry)) continue;
-    if (entry.startsWith('.') && entry !== '.env' && entry !== '.env.example'
-        && entry !== '.gitignore' && !entry.startsWith('.github')) continue;
-
-    const full = join(dir, entry);
-    let stat;
-    try { stat = statSync(full); } catch { continue; }
-
-    if (stat.isDirectory()) {
-      scanDir(rootDir, full, files);
-    } else {
-      files.push(relative(rootDir, full));
-    }
-  }
+  sharedWalkFiles(dir, (full) => files.push(relative(rootDir, full)), {
+    ignoreDirs: IGNORE_DIRS,
+    keepDot: (entry) => entry === '.env' || entry === '.env.example'
+      || entry === '.gitignore' || entry.startsWith('.github'),
+  });
 }