docguard-cli 0.11.0 → 0.11.1

package/cli/scanners/cdk.mjs

@@ -0,0 +1,10 @@
+/**
+ * CDK Detector — Re-export shim.
+ *
+ * The CDK-specific detector has been generalized into a multi-tool IaC
+ * detector at cli/scanners/iac.mjs covering CDK, Terraform, Pulumi, SAM,
+ * and Serverless Framework. This module re-exports the CDK-only API for
+ * backward compatibility. New code should import from iac.mjs directly.
+ */
+
+export { detectCDK, hasInfrastructureHeading } from './iac.mjs';

package/cli/scanners/iac.mjs

@@ -0,0 +1,235 @@
+/**
+ * IaC Detector — Identifies Infrastructure-as-Code projects.
+ *
+ * IaC code is real production source that defines cloud infrastructure.
+ * It MUST be documented in ARCHITECTURE.md, not silently ignored. This
+ * detector identifies which IaC tool the project uses so docs-coverage
+ * can emit ONE consolidated actionable warning naming the actual layout
+ * (instead of multiple generic per-directory warnings).
+ *
+ * Supported tools:
+ *   - AWS CDK         → cdk.json marker file
+ *   - Terraform       → *.tf files in any non-ignored directory
+ *   - Pulumi          → Pulumi.yaml marker file
+ *   - AWS SAM         → template.yaml/yml with "AWS::Serverless::"
+ *   - Serverless Fmw  → serverless.yml/serverless.yaml/serverless.ts
+ *
+ * Zero NPM dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { DEFAULT_IGNORE_DIRS } from '../shared-ignore.mjs';
+
+const MAX_DEPTH = 6;
+
+/**
+ * Per-tool conventions: marker file/pattern + the directories that hold the
+ * actual IaC source. Used to construct the consolidated warning text.
+ */
+const TOOL_PROFILES = {
+  cdk: {
+    label: 'AWS CDK',
+    markerFile: 'cdk.json',
+    sourceDirs: ['bin/ (app entrypoint)', 'lib/stacks/', 'lib/constructs/'],
+    headingPattern: /^#+\s+(infrastructure|cdk|iac)\b/im,
+  },
+  terraform: {
+    label: 'Terraform',
+    markerFile: null, // any *.tf file
+    sourceDirs: ['*.tf (root module)', 'modules/ (reusable modules)', 'environments/ (per-env tfvars)'],
+    headingPattern: /^#+\s+(infrastructure|terraform|iac)\b/im,
+  },
+  pulumi: {
+    label: 'Pulumi',
+    markerFile: 'Pulumi.yaml',
+    sourceDirs: ['index.ts (main program)', 'stacks/', 'config/'],
+    headingPattern: /^#+\s+(infrastructure|pulumi|iac)\b/im,
+  },
+  sam: {
+    label: 'AWS SAM',
+    markerFile: 'template.yaml', // also template.yml — checked below
+    sourceDirs: ['template.yaml (SAM manifest)', 'src/ (Lambda handlers)', 'events/'],
+    headingPattern: /^#+\s+(infrastructure|sam|serverless|iac)\b/im,
+  },
+  serverless: {
+    label: 'Serverless Framework',
+    markerFile: 'serverless.yml', // also .yaml, .ts — checked below
+    sourceDirs: ['serverless.yml (manifest)', 'handlers/', 'src/'],
+    headingPattern: /^#+\s+(infrastructure|serverless|iac)\b/im,
+  },
+};
+
+/**
+ * Detect every IaC tool used in the project. Walks the tree from projectDir
+ * looking for marker files, respecting DEFAULT_IGNORE_DIRS.
+ *
+ * @param {string} projectDir - Absolute path to project root
+ * @returns {{
+ *   isIaC: boolean,
+ *   tools: Array<{
+ *     tool: string,             // 'cdk' | 'terraform' | 'pulumi' | 'sam' | 'serverless'
+ *     label: string,            // 'AWS CDK' etc.
+ *     markerPaths: string[],    // relative paths to detected marker files
+ *     packageDirs: string[],    // relative dirs containing the markers
+ *     sourceDirs: string[],     // expected source layout per tool convention
+ *   }>
+ * }}
+ */
+export function detectIaC(projectDir) {
+  const findings = {
+    cdk: { markerPaths: [], packageDirs: [] },
+    terraform: { markerPaths: [], packageDirs: [] },
+    pulumi: { markerPaths: [], packageDirs: [] },
+    sam: { markerPaths: [], packageDirs: [] },
+    serverless: { markerPaths: [], packageDirs: [] },
+  };
+
+  const recordFinding = (tool, fullPath) => {
+    const relPath = relative(projectDir, fullPath);
+    findings[tool].markerPaths.push(relPath);
+    const pkgDir = relative(projectDir, dirnameOf(fullPath)) || '.';
+    if (!findings[tool].packageDirs.includes(pkgDir)) {
+      findings[tool].packageDirs.push(pkgDir);
+    }
+  };
+
+  const walk = (dir, depth) => {
+    if (depth > MAX_DEPTH) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+
+    for (const e of entries) {
+      if (!e.isFile()) continue;
+      const full = join(dir, e.name);
+
+      // CDK
+      if (e.name === 'cdk.json') recordFinding('cdk', full);
+
+      // Terraform — any .tf file (we record one per directory, not per file)
+      if (e.name.endsWith('.tf')) {
+        const pkgDir = relative(projectDir, dir) || '.';
+        if (!findings.terraform.packageDirs.includes(pkgDir)) {
+          findings.terraform.markerPaths.push(relative(projectDir, full));
+          findings.terraform.packageDirs.push(pkgDir);
+        }
+      }
+
+      // Pulumi
+      if (e.name === 'Pulumi.yaml' || e.name === 'Pulumi.yml') {
+        recordFinding('pulumi', full);
+      }
+
+      // SAM — template.yaml/yml WITH AWS::Serverless::
+      if (e.name === 'template.yaml' || e.name === 'template.yml') {
+        if (fileContains(full, 'AWS::Serverless::')) recordFinding('sam', full);
+      }
+
+      // Serverless Framework
+      if (
+        e.name === 'serverless.yml' ||
+        e.name === 'serverless.yaml' ||
+        e.name === 'serverless.ts' ||
+        e.name === 'serverless.js'
+      ) {
+        recordFinding('serverless', full);
+      }
+    }
+
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (DEFAULT_IGNORE_DIRS.has(e.name)) continue;
+      if (e.name.startsWith('.')) continue;
+      walk(join(dir, e.name), depth + 1);
+    }
+  };
+
+  if (existsSync(projectDir)) {
+    try {
+      if (statSync(projectDir).isDirectory()) walk(projectDir, 0);
+    } catch { /* skip */ }
+  }
+
+  const tools = [];
+  for (const [tool, data] of Object.entries(findings)) {
+    if (data.markerPaths.length > 0) {
+      tools.push({
+        tool,
+        label: TOOL_PROFILES[tool].label,
+        markerPaths: data.markerPaths,
+        packageDirs: data.packageDirs,
+        sourceDirs: TOOL_PROFILES[tool].sourceDirs,
+      });
+    }
+  }
+
+  return { isIaC: tools.length > 0, tools };
+}
+
+/**
+ * Check whether ARCHITECTURE.md content includes an Infrastructure/CDK/IaC/
+ * Terraform/Pulumi/SAM heading at any level. Case-insensitive.
+ *
+ * @param {string} archContent - Full ARCHITECTURE.md content
+ * @returns {boolean}
+ */
+export function hasInfrastructureHeading(archContent) {
+  if (!archContent) return false;
+  return /^#+\s+(infrastructure|cdk|iac|terraform|pulumi|sam|serverless)\b/im.test(archContent);
+}
+
+/**
+ * Build the consolidated warning text for a detected IaC tool.
+ * One warning per tool — names the marker location and required content.
+ */
+export function buildIaCWarning(toolFinding) {
+  const primary = toolFinding.markerPaths[0];
+  const pkgDir = toolFinding.packageDirs[0];
+  const where = pkgDir === '.' ? '' : pkgDir + '/';
+  const sourceList = toolFinding.sourceDirs
+    .map(s => s.startsWith('*.') ? `${where}${s}` : `${where}${s}`)
+    .join(', ');
+  return `${toolFinding.label} detected at ${primary} — add an "Infrastructure" section to ` +
+    `ARCHITECTURE.md covering ${sourceList}`;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function dirnameOf(p) {
+  const i = p.lastIndexOf('/');
+  if (i < 0) {
+    const j = p.lastIndexOf('\\');
+    return j < 0 ? p : p.slice(0, j);
+  }
+  return p.slice(0, i);
+}
+
+function fileContains(filePath, needle) {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    return content.includes(needle);
+  } catch {
+    return false;
+  }
+}
+
+// ── Backwards-compatibility shim ────────────────────────────────────────────
+
+/**
+ * Legacy CDK-only API kept for callers that don't need multi-tool detection.
+ * Delegates to detectIaC and projects the CDK slice into the old shape.
+ *
+ * @deprecated Use detectIaC for new code.
+ */
+export function detectCDK(projectDir) {
+  const result = detectIaC(projectDir);
+  const cdk = result.tools.find(t => t.tool === 'cdk');
+  if (!cdk) {
+    return { isCDK: false, cdkJsonPaths: [], cdkPackageDirs: [] };
+  }
+  return {
+    isCDK: true,
+    cdkJsonPaths: cdk.markerPaths,
+    cdkPackageDirs: cdk.packageDirs,
+  };
+}

package/cli/shared-ignore.mjs

@@ -15,6 +15,31 @@
  * Zero NPM dependencies — pure Node.js built-ins only.
  */
 
+/**
+ * Canonical set of directory names that should never be scanned, regardless
+ * of validator. Build outputs, VCS internals, package caches, framework synth
+ * outputs. Validators MAY extend this with their own additions but SHOULD
+ * start from this base so behavior is consistent across the tool.
+ */
+export const DEFAULT_IGNORE_DIRS = new Set([
+  // Package managers
+  'node_modules', 'vendor', '.venv', '__pycache__',
+  // VCS
+  '.git', '.jj', '.hg', '.svn',
+  // Build outputs — JS/TS, Rust/Java, generic
+  'dist', 'build', 'out', 'coverage', 'target', '.gradle',
+  // Framework synth/cache
+  '.next', '.nuxt', '.turbo', '.vercel', '.cache', '.svelte-kit', 'cdk.out',
+  // OS
+  '.DS_Store',
+]);
+
+// Regex for paths that must always be rejected at any depth, regardless of
+// the glob pattern matching them. These are duplicate file trees (worktrees)
+// or runtime caches that should NEVER be treated as primary source.
+const ALWAYS_REJECT_PATH_RE =
+  /(?:^|[/\\])(?:node_modules|\.claude[/\\]worktrees|\.git[/\\]worktrees|\.jj)(?:[/\\]|$)/;
+
 /**
  * Convert a glob pattern to a RegExp.
  * Supports: * (any chars except /), ** (any path segments), . (literal dot).
@@ -111,8 +136,10 @@ function globToMatchRegex(pattern) {
 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;
+  // Always reject paths inside node_modules / worktree copies / .jj at any
+  // depth. A user's testPatterns like "**/*.test.ts" would otherwise match
+  // duplicate trees under .claude/worktrees and inflate test counts.
+  if (ALWAYS_REJECT_PATH_RE.test(relPath)) return false;
 
   const regexes = patterns.map(p => globToMatchRegex(p));
   return regexes.some(r => r.test(relPath));

package/cli/shared-source.mjs

@@ -18,8 +18,9 @@ import { resolve, join, dirname, relative, extname } from 'node:path';
 import { shouldIgnore } from './shared-ignore.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', '.turbo',
+  'cdk.out',
 ]);
 
 const CODE_EXTENSIONS = new Set([

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/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(),

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.9.9"
+  version: "0.11.1"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with 19 automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. Zero NPM runtime dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.9
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.1 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.10.0
+  version: 0.11.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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

package/templates/ARCHITECTURE.md.template

@@ -58,6 +58,58 @@
 |---------|---------|-----|----------|
 | <!-- e.g. Stripe --> | <!-- e.g. Payments --> | <!-- e.g. 99.99% --> | <!-- e.g. Queue + retry --> |
 
+## Infrastructure (IaC)
+
+<!--
+  Skip this section if the project does not use Infrastructure-as-Code.
+  DocGuard auto-detects AWS CDK (cdk.json), Terraform (*.tf), Pulumi
+  (Pulumi.yaml), AWS SAM (template.yaml with AWS::Serverless::), and
+  Serverless Framework (serverless.yml). When any are detected and this
+  section is missing, DocGuard emits ONE consolidated reminder per tool.
+
+  Document the layout for YOUR IaC tool below. Remove the blocks that
+  don't apply.
+-->
+
+### AWS CDK
+
+<!-- Remove this block if you don't use CDK -->
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| App entrypoint | <!-- e.g. packages/cdk/bin/app.ts --> | Instantiates stacks per environment |
+| Stacks | <!-- e.g. packages/cdk/lib/stacks/ --> | One file per CloudFormation stack |
+| Constructs | <!-- e.g. packages/cdk/lib/constructs/ --> | Reusable infrastructure components |
+| Synth config | <!-- e.g. packages/cdk/cdk.json --> | CDK CLI configuration |
+| Context cache | <!-- e.g. packages/cdk/cdk.context.json --> | Environment lookup results (committed) |
+| Synth output | <!-- e.g. packages/cdk/cdk.out/ --> | Generated CloudFormation (gitignored) |
+
+### Terraform
+
+<!-- Remove this block if you don't use Terraform -->
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| Root module | <!-- e.g. infra/*.tf --> | Top-level resources |
+| Reusable modules | <!-- e.g. infra/modules/ --> | Composable infrastructure blocks |
+| Environment configs | <!-- e.g. infra/environments/ --> | Per-env tfvars (dev, staging, prod) |
+| State backend | <!-- e.g. S3 bucket + DynamoDB lock table --> | Remote state storage |
+
+### Pulumi / SAM / Serverless Framework
+
+<!--
+  Document app program (index.ts), stack config, or manifest location.
+  Remove this block if you don't use these tools.
+-->
+
+### Deployment Pipeline
+
+<!-- How does IaC code reach the cloud? -->
+
+- <!-- e.g. PR → CI workflow → terraform plan + manual approval → terraform apply -->
+- <!-- e.g. PR → CodePipeline → cdk deploy → dev/staging/prod -->
+
+
 ## Diagrams
 
 <!-- Architecture diagrams using Mermaid, ASCII art, or linked images -->