docguard-cli 0.9.9 → 0.9.11

package/cli/commands/score.mjs

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { c } from '../shared.mjs';
+import { validateSecurity } from '../validators/security.mjs';
 
 const WEIGHTS = {
   structure: 25,     // Required files exist
@@ -410,15 +411,32 @@ function calcTestingScore(dir, config) {
   const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
   const hasTopLevelTestDir = testDirs.some(d => existsSync(resolve(dir, d)));
 
-  // Check co-located tests: src/**/__tests__/ and src/**/*.test.* / src/**/*.spec.*
+  // Check co-located tests: **/__tests__/ and **/*.test.* / **/*.spec.*
+  // Scan ALL common source roots — not just src/, also backend/, packages/, etc.
   let hasColocatedTests = false;
   if (!hasTopLevelTestDir) {
     hasColocatedTests = findColocatedTests(dir);
   }
 
+  // Check if testPatterns config points to existing test locations
+  let hasPatternTests = false;
+  if (!hasTopLevelTestDir && !hasColocatedTests) {
+    const patterns = config.testPatterns || [];
+    if (patterns.length > 0) {
+      for (const pattern of patterns) {
+        // Extract the root directory from the pattern
+        const rootDir = pattern.split('/')[0].split('*')[0];
+        if (rootDir && existsSync(resolve(dir, rootDir))) {
+          hasPatternTests = true;
+          break;
+        }
+      }
+    }
+  }
+
   // Check vitest/jest config for custom test patterns
   let hasConfigTests = false;
-  if (!hasTopLevelTestDir && !hasColocatedTests) {
+  if (!hasTopLevelTestDir && !hasColocatedTests && !hasPatternTests) {
     const testConfigs = ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mts', 'jest.config.ts', 'jest.config.js'];
     for (const cfgFile of testConfigs) {
       const cfgPath = resolve(dir, cfgFile);
@@ -448,7 +466,7 @@ function calcTestingScore(dir, config) {
     }
   }
 
-  if (hasTopLevelTestDir || hasColocatedTests || hasConfigTests) score += 40;
+  if (hasTopLevelTestDir || hasColocatedTests || hasPatternTests || hasConfigTests) score += 40;
 
   // ── Check 2: TEST-SPEC.md exists (30 pts) ──
   if (existsSync(resolve(dir, 'docs-canonical/TEST-SPEC.md'))) score += 30;
@@ -476,8 +494,30 @@ function calcTestingScore(dir, config) {
   }
 
   // ── Check 4: CI test step (15 pts) ──
-  const ciFiles = ['.github/workflows/ci.yml', '.github/workflows/test.yml'];
-  const hasCITest = ciFiles.some(f => existsSync(resolve(dir, f)));
+  // Support multiple CI systems — not just GitHub Actions
+  const ciFiles = [
+    '.github/workflows/ci.yml', '.github/workflows/test.yml',
+    '.github/workflows/ci.yaml', '.github/workflows/test.yaml',
+    'buildspec.yml', 'buildspec.test.yml',     // AWS CodeBuild
+    'amplify.yml',                              // AWS Amplify
+    'Jenkinsfile',                              // Jenkins
+    '.circleci/config.yml',                     // CircleCI
+    '.gitlab-ci.yml',                           // GitLab CI
+    '.travis.yml',                              // Travis CI
+  ];
+  let hasCITest = ciFiles.some(f => existsSync(resolve(dir, f)));
+
+  // Also check turbo.json for "test" pipeline task
+  if (!hasCITest) {
+    const turboPath = resolve(dir, 'turbo.json');
+    if (existsSync(turboPath)) {
+      try {
+        const turboContent = readFileSync(turboPath, 'utf-8');
+        if (/"test"/.test(turboContent)) hasCITest = true;
+      } catch { /* skip */ }
+    }
+  }
+
   if (hasCITest) score += 15;
 
   return Math.min(100, score);
@@ -490,7 +530,8 @@ function calcTestingScore(dir, config) {
  */
 function findColocatedTests(dir) {
   // Scan these common source roots for co-located tests
-  const sourceRoots = ['src', 'app', 'lib', 'packages', 'modules'];
+  // Includes backend/, server/ for monorepo-style projects (e.g., backend/src/__tests__/)
+  const sourceRoots = ['src', 'app', 'lib', 'packages', 'modules', 'backend', 'server'];
   const ignoreSet = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache']);
 
   for (const root of sourceRoots) {
@@ -534,25 +575,44 @@ function calcSecurityScore(dir, config) {
   let score = 0;
   const ptc = config.projectTypeConfig || {};
 
-  // SECURITY.md exists
-  if (existsSync(resolve(dir, 'docs-canonical/SECURITY.md'))) score += 30;
+  // SECURITY.md exists (25 pts)
+  if (existsSync(resolve(dir, 'docs-canonical/SECURITY.md'))) score += 25;
 
-  // .gitignore exists and includes .env
+  // .gitignore exists and includes .env (15 + 15 pts)
   const gitignorePath = resolve(dir, '.gitignore');
   if (existsSync(gitignorePath)) {
-    score += 20;
+    score += 15;
     const content = readFileSync(gitignorePath, 'utf-8');
-    if (content.includes('.env')) score += 20;
+    if (content.includes('.env')) score += 15;
   }
 
-  // No .env file committed (check if .env exists but .gitignore covers it)
-  if (!existsSync(resolve(dir, '.env')) || existsSync(gitignorePath)) score += 15;
+  // No .env file committed (10 pts)
+  if (!existsSync(resolve(dir, '.env')) || existsSync(gitignorePath)) score += 10;
 
-  // .env.example exists (safe template) — only check if project needs env vars
+  // .env.example exists (safe template) — only check if project needs env vars (10 pts)
   if (ptc.needsEnvExample === false) {
-    score += 15; // Full marks — project doesn't need env vars
+    score += 10; // Full marks — project doesn't need env vars
   } else if (existsSync(resolve(dir, '.env.example'))) {
-    score += 15;
+    score += 10;
+  }
+
+  // No hardcoded secrets found by security validator (25 pts)
+  // Commands MAY compose validator results (Constitution IV, v1.1.0)
+  try {
+    const secResults = validateSecurity(dir, config);
+    if (secResults.errors.length === 0) {
+      score += 25;
+    } else {
+      // Partial credit: deduct proportionally, but give at least some credit
+      // if there are few findings relative to project size
+      const findingCount = secResults.errors.length;
+      if (findingCount <= 2) score += 15;
+      else if (findingCount <= 5) score += 5;
+      // 6+ findings = 0 pts for this check
+    }
+  } catch {
+    // If validator fails to run, give benefit of the doubt
+    score += 25;
   }
 
   return Math.min(100, score);
@@ -668,8 +728,12 @@ function getSuggestion(category, score, details) {
   const suggestions = {
     structure: 'Run `docguard init` to create missing documentation',
     docQuality: 'Run `docguard fix` to get AI prompts for each doc that needs content',
-    testing: 'Add tests/ directory and configure TEST-SPEC.md',
-    security: 'Create SECURITY.md and add .env to .gitignore → Run `docguard fix --doc security`',
+    testing: score < 40
+      ? 'Add test files (tests/, src/**/__tests__/, or configure testPatterns in .docguard.json) and create TEST-SPEC.md'
+      : 'Configure TEST-SPEC.md and add CI test step → Run `docguard fix --doc test-spec`',
+    security: score < 50
+      ? 'Create SECURITY.md and add .env to .gitignore → Run `docguard fix --doc security`'
+      : 'Review security findings with `docguard guard --verbose` — configure securityIgnore for false positives',
     environment: 'Document env variables and create .env.example → Run `docguard fix --doc environment`',
     drift: 'Create DRIFT-LOG.md and log any code deviations',
     changelog: 'Maintain CHANGELOG.md with [Unreleased] section',

package/cli/docguard.mjs

@@ -128,6 +128,15 @@ export function loadConfig(projectDir) {
         ...getProjectTypeDefaults(merged.projectType),
         ...(merged.projectTypeConfig || {}),
       };
+      // Normalize testPattern (string) → testPatterns (array) for backward compat
+      if (merged.testPattern && !merged.testPatterns) {
+        merged.testPatterns = [merged.testPattern];
+      } else if (merged.testPattern && merged.testPatterns) {
+        // Both set — merge, deduplicate
+        if (!merged.testPatterns.includes(merged.testPattern)) {
+          merged.testPatterns.push(merged.testPattern);
+        }
+      }
       return merged;
     } catch (e) {
       console.error(`${c.red}Error parsing .docguard.json: ${e.message}${c.reset}`);

package/cli/shared-ignore.mjs

@@ -0,0 +1,119 @@
+/**
+ * Shared Ignore Utility — Unified file filtering for all validators.
+ *
+ * Provides consistent glob matching for config ignore arrays:
+ *   - config.ignore        (global — all validators)
+ *   - config.securityIgnore (security validator only)
+ *   - config.todoIgnore     (TODO-tracking validator only)
+ *
+ * Supports exact paths AND glob patterns:
+ *   - "src/foo.ts"           → exact match
+ *   - "packages/cdk/**"      → match any file under packages/cdk/
+ *   - "backend/src/__tests__/**" → match any file under that path
+ *   - "*.test.ts"            → match files ending in .test.ts
+ *
+ * Zero NPM dependencies — pure Node.js built-ins only.
+ */
+
+/**
+ * Convert a glob pattern to a RegExp.
+ * Supports: * (any chars except /), ** (any path segments), . (literal dot).
+ *
+ * @param {string} pattern - Glob pattern
+ * @returns {RegExp}
+ */
+function globToRegex(pattern) {
+  const escaped = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*\*/g, '§§')     // temp placeholder for **
+    .replace(/\*/g, '[^/]*')
+    .replace(/§§/g, '.*');
+  // Match if the relative path:
+  //   - equals the pattern exactly
+  //   - ends with /pattern
+  //   - starts with pattern/
+  //   - contains /pattern/
+  return new RegExp(`^${escaped}$|/${escaped}$|^${escaped}/|/${escaped}/`);
+}
+
+/**
+ * Build a filter function from an array of glob patterns.
+ * Returns a function that returns true if a relative path should be SKIPPED.
+ *
+ * @param {string[]} patterns - Glob patterns (from config.ignore, config.securityIgnore, etc.)
+ * @returns {(relPath: string) => boolean} - true if file should be ignored
+ */
+export function buildIgnoreFilter(patterns = []) {
+  if (!patterns || patterns.length === 0) return () => false;
+
+  const regexes = patterns.map(p => globToRegex(p));
+  return (relPath) => regexes.some(regex => regex.test(relPath));
+}
+
+/**
+ * Check if a relative path should be ignored by BOTH
+ * global ignore + validator-specific ignore.
+ *
+ * @param {string} relPath - Relative file path (e.g., "backend/src/__tests__/foo.test.ts")
+ * @param {object} config - DocGuard config object
+ * @param {string} [validatorKey] - Optional validator-specific key (e.g., 'securityIgnore', 'todoIgnore')
+ * @returns {boolean} - true if file should be skipped
+ */
+export function shouldIgnore(relPath, config, validatorKey) {
+  // Check global ignore
+  if (config.ignore && config.ignore.length > 0) {
+    const globalFilter = buildIgnoreFilter(config.ignore);
+    if (globalFilter(relPath)) return true;
+  }
+
+  // Check validator-specific ignore
+  if (validatorKey && config[validatorKey] && config[validatorKey].length > 0) {
+    const validatorFilter = buildIgnoreFilter(config[validatorKey]);
+    if (validatorFilter(relPath)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Convert a glob pattern to a RegExp for POSITIVE matching.
+ * Unlike globToRegex (used for ignore filtering), this anchors the match
+ * to the full relative path from the project root.
+ *
+ * Supports: * (any chars except /), ** (any path segments), . (literal dot).
+ *
+ * @param {string} pattern - Glob pattern (e.g., "backend/**\/__tests__/**\/*.test.ts")
+ * @returns {RegExp}
+ */
+function globToMatchRegex(pattern) {
+  // Normalize: replace **/ with a placeholder that means "zero or more path segments"
+  let escaped = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*\*\//g, '§STARSTAR§')   // **/ → zero-or-more segments
+    .replace(/\*\*/g, '.*')             // standalone ** → any chars
+    .replace(/\*/g, '[^/]*')            // single * → any chars except /
+    .replace(/§STARSTAR§/g, '(.*/)?');  // **/ → optional path prefix
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Check if a relative path matches ANY of the given glob patterns.
+ * Purpose-built for POSITIVE matching (e.g., "is this a test file?").
+ *
+ * ALWAYS rejects paths containing node_modules at any depth.
+ * This is the correct function for test file discovery — do NOT use
+ * buildIgnoreFilter() for this purpose.
+ *
+ * @param {string} relPath - Relative path from project root
+ * @param {string[]} patterns - Array of glob patterns to match against
+ * @returns {boolean} - true if path matches a pattern AND is not in node_modules
+ */
+export function globMatch(relPath, patterns) {
+  if (!relPath || !patterns || patterns.length === 0) return false;
+
+  // Always reject paths containing node_modules at any depth
+  if (/(?:^|[/\\])node_modules(?:[/\\]|$)/.test(relPath)) return false;
+
+  const regexes = patterns.map(p => globToMatchRegex(p));
+  return regexes.some(r => r.test(relPath));
+}

package/cli/validators/architecture.mjs

@@ -10,10 +10,14 @@
  * - Circular dependencies (A → B → A)
  * - Layer boundary violations (routes importing from routes, etc.)
  * - Orphan modules (code files with 0 inbound imports)
+ *
+ * Respects config.ignore (global) for file filtering.
+ * Uses shared-ignore.mjs for consistent filtering (Constitution IV, v1.1.0).
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, relative, dirname, basename } from 'node:path';
+import { shouldIgnore } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -33,7 +37,7 @@ export function validateArchitecture(projectDir, config) {
   }
 
   // ── 2. Auto-detect import graph ──
-  const importGraph = buildImportGraph(projectDir);
+  const importGraph = buildImportGraph(projectDir, config);
   if (importGraph.files.length === 0) return results;
 
   // ── 3. Detect circular dependencies ──
@@ -84,7 +88,7 @@ function validateConfigLayers(projectDir, config, layers, results) {
     const layerDir = resolve(projectDir, dir);
     if (!existsSync(layerDir)) continue;
 
-    const files = getFilesRecursive(layerDir);
+    const files = getFilesRecursive(layerDir, config, projectDir);
     for (const file of files) {
       if (!CODE_EXTENSIONS.has(extname(file))) continue;
 
@@ -110,14 +114,18 @@ function validateConfigLayers(projectDir, config, layers, results) {
 
 // ── Import Graph Builder ────────────────────────────────────────────────────
 
-function buildImportGraph(projectDir) {
+function buildImportGraph(projectDir, config) {
   const graph = { files: [], edges: [], fileMap: new Map() };
 
-  const allFiles = getFilesRecursive(projectDir);
+  const allFiles = getFilesRecursive(projectDir, config, projectDir);
   const codeFiles = allFiles.filter(f => CODE_EXTENSIONS.has(extname(f)));
 
   for (const file of codeFiles) {
     const relPath = relative(projectDir, file);
+
+    // Skip files in ignored directories (config.ignore)
+    if (config && shouldIgnore(relPath, config)) continue;
+
     graph.files.push(relPath);
 
     try {
@@ -355,7 +363,7 @@ function getFileLayer(filePath, layerDirMap) {
 
 // ── Utilities ───────────────────────────────────────────────────────────────
 
-function getFilesRecursive(dir) {
+function getFilesRecursive(dir, config, projectDir) {
   const results = [];
   if (!existsSync(dir)) return results;
 
@@ -366,11 +374,18 @@ function getFilesRecursive(dir) {
 
   for (const entry of entries) {
     if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
+
+    // Check config.ignore for this directory
+    if (config && projectDir) {
+      const relPath = relative(projectDir, join(dir, entry));
+      if (shouldIgnore(relPath, config)) continue;
+    }
+
     const fullPath = join(dir, entry);
     try {
       const stat = statSync(fullPath);
       if (stat.isDirectory()) {
-        results.push(...getFilesRecursive(fullPath));
+        results.push(...getFilesRecursive(fullPath, config, projectDir));
       } else {
         results.push(fullPath);
       }

package/cli/validators/docs-diff.mjs

@@ -4,10 +4,14 @@
  * Runs as part of `docguard guard` on every invocation.
  * Detects undocumented code artifacts and documented items not found in code.
  * Returns warnings (not errors) since drift is a soft signal.
+ *
+ * Respects config.ignore and config.testPatterns for test file discovery.
+ * Uses shared-ignore.mjs for consistent filtering (Constitution IV, v1.1.0).
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, extname, basename } from 'node:path';
+import { resolve, join, extname, basename, relative } from 'node:path';
+import { shouldIgnore, globMatch } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -32,7 +36,7 @@ export function validateDocsDiff(projectDir, config) {
   const checks = [
     diffTechStack(projectDir),
     diffEnvVars(projectDir),
-    diffTests(projectDir),
+    diffTests(projectDir, config),
   ];
 
   for (const result of checks) {
@@ -131,7 +135,13 @@ function diffEnvVars(dir) {
   };
 }
 
-function diffTests(dir) {
+/**
+ * Diff test files between TEST-SPEC.md and actual code.
+ * Uses config.testPatterns if available, otherwise falls back to
+ * scanning standard test directories.
+ * Always ignores node_modules via globMatch().
+ */
+function diffTests(dir, config) {
   const testSpecPath = resolve(dir, 'docs-canonical/TEST-SPEC.md');
   if (!existsSync(testSpecPath)) return null;
 
@@ -143,14 +153,26 @@ function diffTests(dir) {
     docTests.add(match[1]);
   }
 
+  // Collect test files from disk using globMatch (always excludes node_modules)
   const codeTests = new Set();
-  const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
-  for (const td of testDirs) {
-    const testDir = resolve(dir, td);
-    if (!existsSync(testDir)) continue;
-    const files = getFilesRecursive(testDir);
-    for (const f of files) {
-      codeTests.add(f.replace(dir + '/', ''));
+  const testPatterns = config?.testPatterns || [];
+
+  if (testPatterns.length > 0) {
+    // Use configured patterns — globMatch handles node_modules exclusion
+    const allTestFiles = getTestFilesFromPatterns(dir, testPatterns, config);
+    for (const f of allTestFiles) {
+      codeTests.add(f);
+    }
+  } else {
+    // Fall back to standard test directories
+    const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
+    for (const td of testDirs) {
+      const testDir = resolve(dir, td);
+      if (!existsSync(testDir)) continue;
+      const files = getFilesRecursive(testDir, config);
+      for (const f of files) {
+        codeTests.add(f.replace(dir + '/', ''));
+      }
     }
   }
 
@@ -163,7 +185,44 @@ function diffTests(dir) {
   };
 }
 
-function getFilesRecursive(dir) {
+/**
+ * Find test files matching configured testPatterns.
+ * Uses globMatch() for pattern matching — always excludes node_modules.
+ * Results are deduplicated via Set (handles overlapping patterns).
+ */
+function getTestFilesFromPatterns(dir, patterns, config) {
+  const results = new Set();
+
+  function walk(currentDir) {
+    let entries;
+    try { entries = readdirSync(currentDir); } catch { return; }
+
+    for (const entry of entries) {
+      // Skip node_modules and other ignored dirs at directory level (fast path)
+      if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
+      const fullPath = join(currentDir, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          walk(fullPath);
+        } else if (stat.isFile()) {
+          const relPath = relative(dir, fullPath);
+          // Skip files in globally ignored paths
+          if (config && shouldIgnore(relPath, config)) continue;
+          // Use globMatch for positive pattern matching (rejects node_modules internally)
+          if (globMatch(relPath, patterns)) {
+            results.add(relPath);
+          }
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  walk(dir);
+  return [...results];
+}
+
+function getFilesRecursive(dir, config) {
   const results = [];
   if (!existsSync(dir)) return results;
   let entries;
@@ -175,7 +234,7 @@ function getFilesRecursive(dir) {
     try {
       const stat = statSync(fullPath);
       if (stat.isDirectory()) {
-        results.push(...getFilesRecursive(fullPath));
+        results.push(...getFilesRecursive(fullPath, config));
       } else if (stat.isFile() && CODE_EXTENSIONS.has(extname(fullPath))) {
         results.push(fullPath);
       }

package/cli/validators/security.mjs

@@ -1,9 +1,13 @@
 /**
  * Security Validator — Basic checks for secrets in code
+ *
+ * Respects config.securityIgnore (glob patterns) and config.ignore (global).
+ * Uses shared-ignore.mjs for consistent filtering (Constitution IV, v1.1.0).
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
+import { shouldIgnore } from '../shared-ignore.mjs';
 
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -26,6 +30,30 @@ const SECRET_PATTERNS = [
   { pattern: /(?:sk-|sk_live_|sk_test_)[a-zA-Z0-9]{20,}/g, label: 'API secret key (Stripe/OpenAI pattern)' },
 ];
 
+// Known-safe placeholder/example values that should never be flagged
+const SAFE_PATTERNS = [
+  /EXAMPLE/i,                           // AWS docs example keys contain "EXAMPLE"
+  /placeholder\s*=\s*["']/i,           // HTML placeholder attributes
+  /example\s*:/i,                       // OpenAPI example: blocks
+  /['"]password123['"]/,               // Common test fixture value
+  /\/\/\s*example/i,                    // Code comments with "example"
+  /<!--.*-->/,                          // HTML comments
+];
+
+/**
+ * Check if a match line is a known-safe placeholder/example.
+ * @param {string} line - The full source line containing the match
+ * @param {string} matchStr - The matched string
+ * @returns {boolean} - true if this is a safe/placeholder value
+ */
+function isSafePlaceholder(line, matchStr) {
+  // Check if the matched string itself contains "EXAMPLE"
+  if (/EXAMPLE/i.test(matchStr)) return true;
+
+  // Check if the source line matches any safe pattern
+  return SAFE_PATTERNS.some(p => p.test(line));
+}
+
 export function validateSecurity(projectDir, config) {
   const results = { name: 'security', errors: [], warnings: [], passed: 0, total: 0 };
 
@@ -40,13 +68,33 @@ export function validateSecurity(projectDir, config) {
     // Skip .env.example — it should have placeholder values
     if (filePath.endsWith('.env.example')) return;
 
-    const content = readFileSync(filePath, 'utf-8');
     const relPath = filePath.replace(projectDir + '/', '');
 
+    // Apply config ignore patterns (securityIgnore + global ignore)
+    if (shouldIgnore(relPath, config, 'securityIgnore')) return;
+
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
     for (const { pattern, label } of SECRET_PATTERNS) {
       pattern.lastIndex = 0;
       const match = pattern.exec(content);
       if (match) {
+        // Find the line containing this match for context-aware filtering
+        const matchPos = match.index;
+        let charCount = 0;
+        let matchLine = '';
+        for (const line of lines) {
+          charCount += line.length + 1; // +1 for newline
+          if (charCount > matchPos) {
+            matchLine = line;
+            break;
+          }
+        }
+
+        // Skip known-safe placeholder/example values
+        if (isSafePlaceholder(matchLine, match[0])) continue;
+
         findings.push({ file: relPath, label, match: match[0].substring(0, 30) + '...' });
       }
     }

package/cli/validators/todo-tracking.mjs

@@ -6,6 +6,9 @@
  *
  * Also detects skipped tests without explanation.
  *
+ * Respects config.todoIgnore (glob patterns) and config.ignore (global).
+ * Uses shared-ignore.mjs for consistent filtering (Constitution IV, v1.1.0).
+ *
  * Inspired by spec-kit-cleanup (github.com/dsrednicki/spec-kit-cleanup)
  * which uses tiered issue classification for code hygiene.
  *
@@ -14,6 +17,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname } from 'node:path';
+import { shouldIgnore } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -78,14 +82,14 @@ export function validateTodoTracking(projectDir, config) {
 /**
  * Scan test files for skip/todo patterns without adjacent explanation comments.
  */
-function checkSkippedTests(projectDir) {
+function checkSkippedTests(projectDir, config) {
   const errors = [];
   const warnings = [];
   let passed = 0;
   let total = 0;
 
   const testFiles = [];
-  findTestFiles(projectDir, projectDir, testFiles);
+  findTestFiles(projectDir, projectDir, testFiles, config);
 
   if (testFiles.length === 0) return { errors, warnings, passed, total };
 
@@ -161,7 +165,7 @@ function checkUntrackedTodos(projectDir, config) {
 
   // Collect all TODO/FIXME items from source
   const todos = [];
-  findTodos(projectDir, projectDir, todos);
+  findTodos(projectDir, projectDir, todos, config);
 
   if (todos.length === 0) {
     // No TODOs found — that's clean code
@@ -177,11 +181,26 @@ function checkUntrackedTodos(projectDir, config) {
   let untrackedCount = 0;
 
   for (const todo of todos) {
-    // Check if the TODO text appears somewhere in tracking docs
-    const isTracked = trackingContent.some(doc =>
-      doc.content.includes(todo.keyword) ||
-      doc.content.toLowerCase().includes(todo.text.toLowerCase().trim().substring(0, 30))
-    );
+    // Check if the TODO is tracked in documentation
+    // Improved matching: check full text AND file location context
+    const isTracked = trackingContent.some(doc => {
+      const content = doc.content;
+      const contentLower = content.toLowerCase();
+      const todoTextLower = todo.text.toLowerCase().trim();
+
+      // Match 1: Full TODO text appears in the doc (at least 20 chars or full text)
+      const searchText = todoTextLower.length > 20
+        ? todoTextLower.substring(0, 40)
+        : todoTextLower;
+      const hasText = contentLower.includes(searchText);
+
+      // Match 2: File location appears nearby in the doc
+      const hasLocation = content.includes(todo.file) ||
+        content.includes(`${todo.file}:${todo.line}`);
+
+      // Either the full text matches, or the file location is referenced with partial text
+      return (hasText && hasLocation) || (hasText && todoTextLower.length > 30);
+    });
 
     if (!isTracked) {
       untrackedCount++;
@@ -231,7 +250,7 @@ function loadTrackingDocs(projectDir, config) {
 
 // ──── File Scanners ────────────────────────────────────────────────────────
 
-function findTestFiles(rootDir, dir, files) {
+function findTestFiles(rootDir, dir, files, config) {
   let entries;
   try { entries = readdirSync(dir); } catch { return; }
 
@@ -244,7 +263,7 @@ function findTestFiles(rootDir, dir, files) {
     try { stat = statSync(full); } catch { continue; }
 
     if (stat.isDirectory()) {
-      findTestFiles(rootDir, full, files);
+      findTestFiles(rootDir, full, files, config);
     } else {
       const ext = extname(entry).toLowerCase();
       if (!TEST_EXTENSIONS.has(ext)) continue;
@@ -252,13 +271,16 @@ function findTestFiles(rootDir, dir, files) {
       // Match test file patterns
       if (/\.(test|spec)\.(mjs|cjs|[jt]sx?)$/.test(entry) ||
           /__(tests|test)__/.test(relative(rootDir, full))) {
-        files.push(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);
       }
     }
   }
 }
 
-function findTodos(rootDir, dir, todos) {
+function findTodos(rootDir, dir, todos, config) {
   let entries;
   try { entries = readdirSync(dir); } catch { return; }
 
@@ -271,16 +293,20 @@ function findTodos(rootDir, dir, todos) {
     try { stat = statSync(full); } catch { continue; }
 
     if (stat.isDirectory()) {
-      findTodos(rootDir, full, todos);
+      findTodos(rootDir, full, todos, config);
     } else {
       const ext = extname(entry).toLowerCase();
       if (!SOURCE_EXTENSIONS.has(ext)) continue;
 
+      const relPath = relative(rootDir, full);
+
+      // Apply config ignore patterns (todoIgnore + global ignore)
+      if (config && shouldIgnore(relPath, config, 'todoIgnore')) continue;
+
       let content;
       try { content = readFileSync(full, 'utf-8'); } catch { continue; }
 
       const lines = content.split('\n');
-      const relPath = relative(rootDir, full);
 
       for (let i = 0; i < lines.length; i++) {
         if (TODO_PATTERN.test(lines[i])) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {