docguard-cli 0.10.0 → 0.11.1

package/cli/validators/docs-coverage.mjs

@@ -16,10 +16,14 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
+import { shouldIgnore } from '../shared-ignore.mjs';
+import { detectIaC, hasInfrastructureHeading, buildIaCWarning } from '../scanners/iac.mjs';
 
 const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+  'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+  '.turbo', '.vercel', '.svelte-kit', 'cdk.out', '.claude',
+  'target', '.gradle',
 ]);
 
 // Dotfiles that are universally common and don't need documentation
@@ -50,8 +54,12 @@ export function validateDocsCoverage(projectDir, config) {
     return { errors: [], warnings, passed: 0, total: 0 };
   }
 
+  // IaC detection runs once and informs both Check 3 (suppression) and
+  // Check 6 (consolidated warning). One scan, two consumers.
+  const iac = detectIaC(projectDir);
+
   // ── Check 1: Project-specific config/dotfiles referenced in docs ──
-  const configChecks = checkConfigFiles(projectDir, allDocContent);
+  const configChecks = checkConfigFiles(projectDir, allDocContent, config);
   total += configChecks.total;
   passed += configChecks.passed;
   warnings.push(...configChecks.warnings);
@@ -63,7 +71,7 @@ export function validateDocsCoverage(projectDir, config) {
   warnings.push(...binChecks.warnings);
 
   // ── Check 3: Source directory structure matches ARCHITECTURE.md ──
-  const dirChecks = checkSourceDirs(projectDir, allDocContent, config);
+  const dirChecks = checkSourceDirs(projectDir, allDocContent, config, iac);
   total += dirChecks.total;
   passed += dirChecks.passed;
   warnings.push(...dirChecks.warnings);
@@ -80,6 +88,12 @@ export function validateDocsCoverage(projectDir, config) {
   passed += readmeChecks.passed;
   warnings.push(...readmeChecks.warnings);
 
+  // ── Check 6: IaC-aware Infrastructure documentation ──
+  const iacChecks = checkIaCDocumentation(projectDir, iac);
+  total += iacChecks.total;
+  passed += iacChecks.passed;
+  warnings.push(...iacChecks.warnings);
+
   return { errors: [], warnings, passed, total };
 }
 
@@ -88,8 +102,10 @@ export function validateDocsCoverage(projectDir, config) {
 /**
  * Check 1: Project-specific config/dotfiles are mentioned in docs.
  * Skips universally common files (.gitignore, .eslintrc, etc.).
+ * Honors config.ignore (FR-015 — applies user-configured ignore patterns
+ * consistently across all docs-coverage checks).
  */
-function checkConfigFiles(projectDir, allDocContent) {
+function checkConfigFiles(projectDir, allDocContent, config = {}) {
   const warnings = [];
   let passed = 0;
   let total = 0;
@@ -111,6 +127,17 @@ function checkConfigFiles(projectDir, allDocContent) {
     if (COMMON_DOTFILES.has(entry)) continue;
     if (entry === 'tsconfig.json' || entry === 'package-lock.json') continue;
 
+    // Skip directories — this check is for configuration FILES, not dirs.
+    // Build-cache dotdirs (.nuxt, .next, .turbo, etc.) are handled by IGNORE_DIRS.
+    try {
+      if (statSync(join(projectDir, entry)).isDirectory()) continue;
+    } catch { continue; }
+
+    // Honor user-configured ignore patterns (FR-015 / IR-5).
+    // Same dual-form check as checkSourceDirs: relative path and trailing-slash
+    // form so dotfile-style patterns and dir-style patterns both apply.
+    if (shouldIgnore(entry, config) || shouldIgnore(entry + '/', config)) continue;
+
     total++;
     if (lowerDocContent.includes(entry.toLowerCase())) {
       passed++;
@@ -160,8 +187,13 @@ function checkPackageBins(projectDir, allDocContent) {
 
 /**
  * Check 3: Source directories are referenced in ARCHITECTURE.md.
+ *
+ * Honors config.ignore (FR-006). When IaC is detected and the Infrastructure
+ * heading is missing, per-directory warnings inside the IaC package roots
+ * are suppressed — Check 6 emits one consolidated warning per IaC tool
+ * instead (FR-011).
  */
-function checkSourceDirs(projectDir, allDocContent, config = {}) {
+function checkSourceDirs(projectDir, allDocContent, config = {}, iac = { isIaC: false, tools: [] }) {
   const warnings = [];
   let passed = 0;
   let total = 0;
@@ -173,6 +205,15 @@ function checkSourceDirs(projectDir, allDocContent, config = {}) {
   try { archContent = readFileSync(archPath, 'utf-8'); } catch { return { warnings, passed, total }; }
 
   const lowerArchContent = archContent.toLowerCase();
+  const infraDocumented = hasInfrastructureHeading(archContent);
+
+  // Only suppress per-dir warnings when IaC exists AND no Infrastructure
+  // heading is present — Check 6 will fire the consolidated message instead.
+  const suppressIaCDirs = iac.isIaC && !infraDocumented;
+
+  // Flatten every IaC tool's package dirs into a single Set for fast lookup.
+  const iacPackageDirs = [];
+  for (const tool of iac.tools) iacPackageDirs.push(...tool.packageDirs);
 
   // Monorepo-aware: honor config.sourceRoot + workspaces instead of a hardcoded list.
   for (const rootDir of resolveSourceRoots(projectDir, config)) {
@@ -189,6 +230,22 @@ function checkSourceDirs(projectDir, allDocContent, config = {}) {
 
       if (IGNORE_DIRS.has(entry) || entry.startsWith('.') || entry === '__tests__' || entry === '__test__') continue;
 
+      const relPath = relative(projectDir, fullPath);
+
+      // Honor user-configured ignore patterns (FR-006 / IR-5).
+      // Patterns like `**/cdk.out/**` are written to match files INSIDE the
+      // directory; appending '/' lets us match the directory itself too.
+      if (shouldIgnore(relPath, config) || shouldIgnore(relPath + '/', config)) continue;
+
+      // Suppress per-dir warnings for IaC-relevant subdirs inside an IaC
+      // package — the consolidated Check 6 warning covers them. Includes CDK
+      // (bin/, lib/, stacks/, constructs/), Terraform (modules/, environments/),
+      // Pulumi (stacks/), SAM (events/, src/), Serverless (handlers/, src/).
+      if (suppressIaCDirs && isInsideIaCPackage(relPath, iacPackageDirs)
+          && IAC_SUBDIR_NAMES.has(entry)) {
+        continue;
+      }
+
       total++;
       const searchName = entry.toLowerCase();
       if (lowerArchContent.includes(searchName) || lowerArchContent.includes(root + '/' + entry)) {
@@ -204,6 +261,68 @@ function checkSourceDirs(projectDir, allDocContent, config = {}) {
   return { warnings, passed, total };
 }
 
+/**
+ * Subdirectory names recognized as IaC-relevant across all supported tools.
+ * When IaC is detected and the Infrastructure heading is missing, these dirs
+ * inside the IaC package are suppressed from Check 3 to avoid double-warning.
+ */
+const IAC_SUBDIR_NAMES = new Set([
+  // CDK
+  'bin', 'lib', 'stacks', 'constructs',
+  // Terraform
+  'modules', 'environments',
+  // SAM / Serverless / Pulumi
+  'handlers', 'events', 'src',
+]);
+
+/**
+ * True if `relPath` is inside any of the IaC package directories.
+ * Both inputs are project-relative POSIX paths.
+ */
+function isInsideIaCPackage(relPath, packageDirs) {
+  if (!packageDirs || packageDirs.length === 0) return false;
+  const normalized = relPath.split('\\').join('/');
+  return packageDirs.some(pkgDir => {
+    const p = pkgDir === '.' ? '' : pkgDir.split('\\').join('/');
+    if (p === '') return true;
+    return normalized === p || normalized.startsWith(p + '/');
+  });
+}
+
+/**
+ * Check 6: IaC projects should document their Infrastructure layer.
+ *
+ * Emits ONE consolidated warning per detected IaC tool when ARCHITECTURE.md
+ * has no Infrastructure heading. Suppresses the generic per-directory
+ * warnings that would otherwise fire for bin/, lib/, modules/, handlers/, etc.
+ */
+function checkIaCDocumentation(projectDir, iac) {
+  const warnings = [];
+  if (!iac || !iac.isIaC) return { warnings, passed: 0, total: 0 };
+
+  const archPath = resolve(projectDir, 'docs-canonical/ARCHITECTURE.md');
+  if (!existsSync(archPath)) {
+    // No ARCHITECTURE.md at all — structure validator will catch that.
+    // Don't double-warn here.
+    return { warnings, passed: 0, total: 0 };
+  }
+
+  let archContent;
+  try { archContent = readFileSync(archPath, 'utf-8'); } catch { return { warnings, passed: 0, total: 0 }; }
+
+  if (hasInfrastructureHeading(archContent)) {
+    // One pass per tool — counted as total per IaC tool present.
+    return { warnings, passed: iac.tools.length, total: iac.tools.length };
+  }
+
+  // One actionable warning per detected IaC tool. Most projects use one tool,
+  // but a multi-tool monorepo gets one targeted message each.
+  for (const tool of iac.tools) {
+    warnings.push(buildIaCWarning(tool));
+  }
+  return { warnings, passed: 0, total: iac.tools.length };
+}
+
 /**
  * Check 4: Config files that code actually READS are documented.
  *

package/cli/validators/docs-sync.mjs

@@ -7,10 +7,38 @@ import { resolve, join, extname, basename } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
 
 const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build',
+  'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
   'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+  // Co-located test dirs — these are not the source under documentation.
+  '__tests__', '__test__',
 ]);
 
+// Files that are tests, not source. Matched against the relative path AND
+// the basename. Covers Jest/Vitest/Mocha/Jasmine/pytest/Go/Java conventions.
+const TEST_PATH_RE = /(^|\/)__tests?__\//;
+const TEST_FILE_RE = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|java|go)$/;
+
+// Next.js App Router uses a strict filename convention for route handlers.
+// Other files in the app/api/ tree (helpers, types) are NOT routes.
+const NEXTJS_ROUTE_FILE_RE = /(^|\/)route\.(ts|tsx|js|jsx|mjs)$/;
+const NEXTJS_API_DIR_RE = /(^|\/)app\/api(\/|$)/;
+
+function isTestFile(relPath) {
+  return TEST_PATH_RE.test(relPath) || TEST_FILE_RE.test(relPath);
+}
+
+/**
+ * For Next.js App Router directories (app/api/...), only `route.{ts,js}` files
+ * are actual route handlers. Helpers and types in the same tree should not be
+ * treated as routes.
+ */
+function isValidRouteFile(relPath) {
+  if (NEXTJS_API_DIR_RE.test(relPath)) {
+    return NEXTJS_ROUTE_FILE_RE.test(relPath);
+  }
+  return true;
+}
+
 /**
  * Expand sub-path patterns (e.g. 'routes', 'src/routes') against the project
  * root AND every configured source root, returning de-duplicated existing dirs.
@@ -53,15 +81,22 @@ export function validateDocsSync(projectDir, config) {
   }
 
   // Find route/API files (monorepo-aware) and check they're mentioned in docs.
-  const routeDirs = expandDirs(projectDir, config, ['src/routes', 'src/app/api', 'routes', 'api']);
+  // Note: bare 'api' is intentionally excluded — it collides with frontend
+  // API client conventions (src/api/client.ts). Backend routes use
+  // src/routes/ or routes/ (Express). Next.js App Router uses src/app/api/
+  // or app/api/ with strict route.{ts,js} filename matching applied below.
+  const routeDirs = expandDirs(projectDir, config, ['src/routes', 'src/app/api', 'routes', 'app/api']);
   for (const routeDir of routeDirs) {
     const files = getFilesRecursive(routeDir);
     for (const file of files) {
       const ext = extname(file);
-      if (!['.ts', '.js', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
+      if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
 
-      results.total++;
       const relPath = file.replace(projectDir + '/', '');
+      if (isTestFile(relPath)) continue;
+      if (!isValidRouteFile(relPath)) continue;
+
+      results.total++;
       const name = basename(file, ext);
 
       // Check if the file path or name is mentioned in any canonical doc
@@ -79,10 +114,12 @@ export function validateDocsSync(projectDir, config) {
     const files = getFilesRecursive(serviceDir);
     for (const file of files) {
       const ext = extname(file);
-      if (!['.ts', '.js', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
+      if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
 
-      results.total++;
       const relPath = file.replace(projectDir + '/', '');
+      if (isTestFile(relPath)) continue;
+
+      results.total++;
       const name = basename(file, ext);
 
       if (canonicalContent.includes(relPath) || canonicalContent.includes(name)) {
@@ -117,11 +154,15 @@ export function validateDocsSync(projectDir, config) {
 
   if (openapiContent && openapiFile) {
     // Check that route files have corresponding paths in OpenAPI spec (monorepo-aware)
-    for (const routeDir of expandDirs(projectDir, config, ['src/routes', 'src/app/api', 'routes', 'api'])) {
+    for (const routeDir of expandDirs(projectDir, config, ['src/routes', 'src/app/api', 'routes', 'app/api'])) {
       const files = getFilesRecursive(routeDir);
       for (const file of files) {
         const ext = extname(file);
-        if (!['.ts', '.js', '.mjs'].includes(ext)) continue;
+        if (!['.ts', '.tsx', '.js', '.jsx', '.mjs'].includes(ext)) continue;
+
+        const relPathForFilter = file.replace(projectDir + '/', '');
+        if (isTestFile(relPathForFilter)) continue;
+        if (!isValidRouteFile(relPathForFilter)) continue;
 
         // Skip index/middleware files
         const rawName = basename(file, ext).toLowerCase();

package/cli/validators/metadata-sync.mjs

@@ -23,6 +23,7 @@ const IGNORE_DIRS = new Set([
  */
 export function validateMetadataSync(projectDir, config) {
   const warnings = [];
+  const fixes = [];
   let passed = 0;
   let total = 0;
 
@@ -60,6 +61,7 @@ export function validateMetadataSync(projectDir, config) {
           warnings.push(
             `${relPath} has version "${versionMatch[1]}" but package.json is "${currentVersion}"`
           );
+          fixes.push({ type: 'replace-version', file: relPath, found: versionMatch[1], actual: currentVersion });
         } else {
           passed++;
         }
@@ -120,6 +122,9 @@ export function validateMetadataSync(projectDir, config) {
           warnings.push(
             `${relPath} references "v${foundVersion}" in an actionable context (URL/install/declaration) but current version is "${currentVersion}"`
           );
+          if (!fixes.some(f => f.file === relPath && f.found === foundVersion)) {
+            fixes.push({ type: 'replace-version', file: relPath, found: foundVersion, actual: currentVersion });
+          }
         } else if (fMajor === major && fMinor === minor && foundVersion === currentVersion) {
           total++;
           passed++;
@@ -128,7 +133,7 @@ export function validateMetadataSync(projectDir, config) {
     }
   }
 
-  return { errors: [], warnings, passed, total };
+  return { errors: [], warnings, passed, total, fixes };
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────

package/cli/validators/metrics-consistency.mjs

@@ -24,6 +24,7 @@ const IGNORE_DIRS = new Set([
  */
 export function validateMetricsConsistency(projectDir, config, guardResults) {
   const warnings = [];
+  const fixes = [];
   let passed = 0;
   let total = 0;
 
@@ -83,8 +84,10 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
         const found = parseInt(match[1], 10);
         if (found !== actuals[key] && found > 0) {
           warnings.push(
-            `${relPath} says "${found} ${label}" but actual count is ${actuals[key]}. Update the doc or run \`docguard generate --force\``
+            `${relPath} says "${found} ${label}" but actual count is ${actuals[key]}. Fix with \`docguard fix --write\``
           );
+          // Deterministic, surgical token replacement — safe to auto-apply.
+          fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key] });
         } else {
           passed++;
         }
@@ -92,7 +95,7 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
     }
   }
 
-  return { errors: [], warnings, passed, total };
+  return { errors: [], warnings, passed, total, fixes };
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────

package/cli/validators/test-spec.mjs

@@ -126,17 +126,22 @@ export function validateTestSpec(projectDir, config) {
           continue;
         }
 
-        // For a ✅ journey, verify the referenced test file actually exists
-        // rather than trusting the glyph.
-        const cleanTest = testFile ? testFile.replace(/`/g, '').trim() : '';
-        if (cleanTest && cleanTest !== '—' && !cleanTest.includes('N/A')) {
-          results.total++;
-          if (existsSync(resolve(projectDir, cleanTest))) {
-            results.passed++;
-          } else {
-            results.warnings.push(
-              `E2E Journey #${num} (${journey}) marked ✅ but test file not found: ${cleanTest}`
-            );
+        // For a ✅ journey, verify the referenced test file(s) actually exist
+        // rather than trusting the glyph. Cells may list multiple paths in
+        // backticks separated by commas (e.g. `a.test.ts`, `b.test.ts`) and
+        // may include "(N suites)" annotations or globs.
+        if (testFile && testFile.trim() !== '—' && !testFile.includes('N/A')) {
+          const paths = parseTestPathCell(testFile);
+          if (paths.length > 0) {
+            results.total++;
+            const anyExists = paths.some(p => testEvidenceExists(projectDir, p));
+            if (anyExists) {
+              results.passed++;
+            } else {
+              results.warnings.push(
+                `E2E Journey #${num} (${journey}) marked ✅ but test file not found: ${paths.join(', ')}`
+              );
+            }
           }
         }
       }
@@ -182,6 +187,119 @@ export function validateTestSpec(projectDir, config) {
   return results;
 }
 
+/**
+ * Parse a TEST-SPEC.md table cell into a list of test path strings.
+ *
+ * Real-world Journey rows commonly list multiple test files in one cell:
+ *   `path/a.test.ts`, `path/b.test.ts`
+ *   `idor_*.test.ts (3 suites)`
+ *
+ * Strategy:
+ *   1. Split on commas that are OUTSIDE backticks.
+ *   2. For each segment: strip backticks, strip trailing "(N suites)" or
+ *      "(N tests)" annotations, trim whitespace.
+ *   3. Drop empties.
+ *
+ * The "(N suites)" annotation is preserved as evidence — if a glob like
+ * `idor_*.test.ts` doesn't expand to a literal file, testEvidenceExists()
+ * accepts the annotation as the author's claim of coverage.
+ */
+export function parseTestPathCell(cell) {
+  if (!cell) return [];
+  // Split on commas that are NOT inside backticks. Track backtick parity.
+  const segments = [];
+  let buf = '';
+  let inBackticks = false;
+  for (const ch of cell) {
+    if (ch === '`') { inBackticks = !inBackticks; buf += ch; continue; }
+    if (ch === ',' && !inBackticks) {
+      segments.push(buf);
+      buf = '';
+      continue;
+    }
+    buf += ch;
+  }
+  if (buf) segments.push(buf);
+
+  const result = [];
+  for (let seg of segments) {
+    seg = seg.replace(/`/g, '').trim();
+    if (!seg || seg === '—') continue;
+    result.push(seg);
+  }
+  return result;
+}
+
+/**
+ * True if a TEST-SPEC.md path segment has supporting evidence on disk.
+ *
+ * Accepts: exact file match, glob expansion (e.g. `foo_*.test.ts`), or an
+ * "(N suites)" / "(N tests)" annotation when the literal path doesn't exist.
+ * The annotation is the author's explicit claim of coverage — believe it
+ * rather than reject the row outright; the audit trail is in the markdown.
+ */
+export function testEvidenceExists(projectDir, pathSegment) {
+  if (!pathSegment) return false;
+
+  // Strip a trailing "(N suites)" / "(N tests)" annotation for the file check.
+  const annotationMatch = pathSegment.match(/\s*\((\d+)\s+(?:suites?|tests?)\)\s*$/i);
+  const pathOnly = annotationMatch ? pathSegment.slice(0, annotationMatch.index).trim() : pathSegment;
+  const hasAnnotation = !!annotationMatch;
+
+  if (!pathOnly) return hasAnnotation;
+
+  // Glob support — if the segment contains *, ?, or [, walk the parent dir.
+  if (/[*?[]/.test(pathOnly)) {
+    const matches = expandGlob(projectDir, pathOnly);
+    if (matches.length > 0) return true;
+    // Glob with annotation but no expansion → trust the annotation.
+    return hasAnnotation;
+  }
+
+  // Plain path — must exist on disk.
+  if (existsSync(resolve(projectDir, pathOnly))) return true;
+  // Plain path with explicit annotation → still trust the author's claim.
+  return hasAnnotation;
+}
+
+/**
+ * Minimal glob expansion: only handles the `*` and `?` wildcards in a single
+ * path segment. e.g. `backend/src/test-helpers/security/idor_*.test.ts`.
+ * Pure Node.js built-ins; zero dependencies.
+ */
+function expandGlob(projectDir, pattern) {
+  const parts = pattern.split('/');
+  const start = resolve(projectDir);
+  let candidates = [start];
+  for (const part of parts) {
+    if (!/[*?[]/.test(part)) {
+      candidates = candidates.map(c => resolve(c, part)).filter(c => existsSync(c));
+      continue;
+    }
+    const re = globPartToRegex(part);
+    const next = [];
+    for (const dir of candidates) {
+      let entries;
+      try { entries = readdirSync(dir); } catch { continue; }
+      for (const e of entries) {
+        if (re.test(e)) next.push(resolve(dir, e));
+      }
+    }
+    candidates = next;
+    if (candidates.length === 0) return [];
+  }
+  return candidates;
+}
+
+function globPartToRegex(part) {
+  const escaped = part
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\\\[/g, '[').replace(/\\\]/g, ']') // restore character classes
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp(`^${escaped}$`);
+}
+
 /** Recursively check if a directory contains test files */
 function hasTestFilesRecursive(dir) {
   const ignore = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);

package/cli/validators/todo-tracking.mjs

@@ -38,6 +38,25 @@ const TEST_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
 const TODO_PATTERN = /\b(TODO|FIXME|HACK|XXX|TEMP(?!late|orar)|WORKAROUND)\s*[(:]/;
 const TODO_EXTRACT = /\b(TODO|FIXME|HACK|XXX|TEMP(?!late|orar)|WORKAROUND)\s*[:(]?\s*(.+)/;
 
+// Matches a comment-opening marker. Real TODOs live in comments — restricting
+// matches to text AFTER a comment marker prevents false positives from regex
+// literals or strings that happen to contain a TODO keyword.
+//   //  — JS/TS/C/C++/Rust/Go/Java line comment
+//   #   — Python/Ruby/shell/YAML
+//   /*  — JS/C/C++ block comment open
+//   *   — block comment continuation (when at start of line)
+//   <!-- — HTML/Markdown
+const COMMENT_MARKER = /(?:\/\/|#|\/\*|<!--|^\s*\*\s)/;
+
+/**
+ * Return the portion of a line after the first comment marker, or null if
+ * the line has no comment. Used to constrain TODO matching to comments.
+ */
+function commentPortion(line) {
+  const m = line.match(COMMENT_MARKER);
+  return m ? line.slice(m.index + m[0].length) : null;
+}
+
 // Test skip patterns for common test frameworks
 const SKIP_PATTERNS = [
   /\btest\.skip\s*\(/,
@@ -290,10 +309,31 @@ function findTestFiles(rootDir, dir, files, config) {
   }
 }
 
+// Test-file path patterns — TODO scanning skips these by default to avoid
+// false positives from test fixture strings (writeFileSync(..., '// xxxxx:')
+// inside template literals is a comment marker for the regex but not a real
+// annotation to track). Set config.todoTracking.includeTestFiles = true to override.
+const TEST_FILE_RE = /(^|\/)__tests?__\//;
+const TEST_NAME_RE = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|java|go)$/;
+
+// The validator's own source file describes the keyword list in its docstring
+// and code. Skipping itself avoids self-referential false positives.
+const SELF_PATH = new URL(import.meta.url).pathname;
+
+function isTestFilePath(relPath) {
+  return TEST_FILE_RE.test(relPath) || TEST_NAME_RE.test(relPath);
+}
+
+function isSelfPath(fullPath) {
+  return fullPath === SELF_PATH;
+}
+
 function findTodos(rootDir, dir, todos, config) {
   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;
@@ -310,6 +350,15 @@ function findTodos(rootDir, dir, todos, config) {
 
       const relPath = relative(rootDir, full);
 
+      // Skip test files unless explicitly opted in — test fixture strings
+      // commonly contain comment markers inside template literals that the
+      // single-line heuristic can't distinguish from real comments.
+      if (!includeTests && isTestFilePath(relPath)) continue;
+
+      // Skip the validator's own source file — its docstring legitimately
+      // names the annotation keywords it scans for.
+      if (isSelfPath(full)) continue;
+
       // Apply config ignore patterns (todoIgnore + global ignore)
       if (config && shouldIgnore(relPath, config, 'todoIgnore')) continue;
 
@@ -322,8 +371,12 @@ function findTodos(rootDir, dir, todos, config) {
       const lines = content.split('\n');
 
       for (let i = 0; i < lines.length; i++) {
-        if (TODO_PATTERN.test(lines[i])) {
-          const match = lines[i].match(TODO_EXTRACT);
+        // Restrict scanning to text inside a comment — keeps the regex from
+        // matching its own keyword list when DocGuard reads its own source.
+        const commentText = commentPortion(lines[i]);
+        if (commentText === null) continue;
+        if (TODO_PATTERN.test(commentText)) {
+          const match = commentText.match(TODO_EXTRACT);
           if (match) {
             todos.push({
               keyword: match[1].toUpperCase(),