docguard-cli 0.9.11 → 0.11.0

package/cli/validators/docs-diff.mjs

@@ -12,6 +12,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename, relative } from 'node:path';
 import { shouldIgnore, globMatch } from '../shared-ignore.mjs';
+import { collectPackageJsons, detectDocker, resolveSourceRoots } from '../shared-source.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -33,9 +34,11 @@ export function validateDocsDiff(projectDir, config) {
   let passed = 0;
   let total = 0;
 
+  // NOTE: env-var drift is owned by the Environment validator (which compares
+  // documented vars against real process.env / import.meta.env usage). Docs-Diff
+  // covers tech-stack and test-file drift to avoid double-reporting.
   const checks = [
-    diffTechStack(projectDir),
-    diffEnvVars(projectDir),
+    diffTechStack(projectDir, config),
     diffTests(projectDir, config),
   ];
 
@@ -61,14 +64,17 @@ export function validateDocsDiff(projectDir, config) {
 
 // ── Diff Functions (lightweight versions for validator) ──────────────────
 
-function diffTechStack(dir) {
+export function diffTechStack(dir, config = {}) {
   const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
-  const pkgPath = resolve(dir, 'package.json');
-  if (!existsSync(archPath) || !existsSync(pkgPath)) return null;
+  if (!existsSync(archPath)) return null;
+
+  // Monorepo-aware: merge dependencies across the root package + the source-root
+  // package + any workspace packages. A repo with no parseable package.json
+  // anywhere yields no code-side truth → return null (graceful, like before).
+  const pkgs = collectPackageJsons(dir, config);
+  if (pkgs.length === 0) return null;
 
   const archContent = readFileSync(archPath, 'utf-8');
-  let pkg;
-  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { return null; }
 
   const docTech = new Set();
   const techPatterns = ['React', 'Next.js', 'Vue', 'Angular', 'Svelte', 'Express', 'Fastify', 'Hono',
@@ -82,7 +88,10 @@ function diffTechStack(dir) {
   }
 
   const codeTech = new Set();
-  const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const allDeps = {};
+  for (const { pkg } of pkgs) {
+    Object.assign(allDeps, pkg.dependencies || {}, pkg.devDependencies || {});
+  }
   const depMap = {
     'react': 'React', 'next': 'Next.js', 'vue': 'Vue', 'express': 'Express',
     'fastify': 'Fastify', 'hono': 'Hono', 'prisma': 'Prisma', '@prisma/client': 'Prisma',
@@ -95,6 +104,11 @@ function diffTechStack(dir) {
     if (allDeps[dep]) codeTech.add(tech);
   }
 
+  // Docker is not an npm dependency — detect it via a Dockerfile/compose file.
+  if (detectDocker(dir, config)) codeTech.add('Docker');
+  // Terraform: detect via .tf files anywhere in the project (non-npm artifact).
+  if (hasFileWithExt(dir, '.tf', config)) codeTech.add('Terraform');
+
   if (docTech.size === 0 && codeTech.size === 0) return null;
 
   return {
@@ -104,37 +118,6 @@ function diffTechStack(dir) {
   };
 }
 
-function diffEnvVars(dir) {
-  const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
-  if (!existsSync(envDocPath)) return null;
-
-  const content = readFileSync(envDocPath, 'utf-8');
-  const docVars = new Set();
-  const varRegex = /`([A-Z][A-Z0-9_]{2,})`/g;
-  let match;
-  while ((match = varRegex.exec(content)) !== null) {
-    docVars.add(match[1]);
-  }
-
-  const codeVars = new Set();
-  const envExamplePath = resolve(dir, '.env.example');
-  if (existsSync(envExamplePath)) {
-    const envContent = readFileSync(envExamplePath, 'utf-8');
-    const envRegex = /^([A-Z][A-Z0-9_]+)\s*=/gm;
-    while ((match = envRegex.exec(envContent)) !== null) {
-      codeVars.add(match[1]);
-    }
-  }
-
-  if (docVars.size === 0 && codeVars.size === 0) return null;
-
-  return {
-    title: 'Environment Variables',
-    onlyInDocs: [...docVars].filter(v => !codeVars.has(v)),
-    onlyInCode: [...codeVars].filter(v => !docVars.has(v)),
-  };
-}
-
 /**
  * Diff test files between TEST-SPEC.md and actual code.
  * Uses config.testPatterns if available, otherwise falls back to
@@ -145,52 +128,95 @@ function diffTests(dir, config) {
   const testSpecPath = resolve(dir, 'docs-canonical/TEST-SPEC.md');
   if (!existsSync(testSpecPath)) return null;
 
-  const content = readFileSync(testSpecPath, 'utf-8');
+  // Strip fenced code blocks first — they contain shell commands like
+  // `npx playwright test login.spec.ts` whose tokens were being mis-extracted
+  // as documented test files.
+  const content = readFileSync(testSpecPath, 'utf-8').replace(/```[\s\S]*?```/g, '');
   const docTests = new Set();
-  const testFileRegex = /`([^`]*\.(test|spec)\.[^`]+)`/g;
+  // A documented test reference: a single whitespace-free token ending in
+  // .test.<ext> or .spec.<ext>, optionally containing glob '*'.
+  const testFileRegex = /`([^`\s]*\.(?:test|spec)\.[a-zA-Z0-9]+)`/g;
   let match;
   while ((match = testFileRegex.exec(content)) !== null) {
     docTests.add(match[1]);
   }
 
-  // Collect test files from disk using globMatch (always excludes node_modules)
-  const codeTests = new Set();
-  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 + '/', ''));
-      }
-    }
-  }
+  // Collect ALL test files from disk: configured patterns + every *.test.* /
+  // *.spec.* file found recursively under each source root (catches co-located
+  // and nested __tests__ dirs) + root-level conventional test dirs (e2e/, tests/).
+  const codeTests = collectCodeTests(dir, config);
 
   if (docTests.size === 0 && codeTests.size === 0) return null;
 
+  // TEST-SPEC.md frequently documents tests as GLOB PATTERNS
+  // (`backend/src/*/__tests__/*.test.ts`, `e2e/*.spec.ts`), and entries may be
+  // bare basenames or full paths. Treat each documented entry as a glob and
+  // match it against code test paths (or basenames when the entry has no slash).
+  // Exact-string comparison produced the false "N documented but not found".
+  const codeArr = [...codeTests];
+  const docArr = [...docTests];
+
+  const matches = (docEntry, codeRel) => {
+    const entry = String(docEntry).trim();
+    const hasSlash = entry.includes('/');
+    const target = hasSlash ? entry : basename(entry);
+    const subject = hasSlash ? codeRel : basename(codeRel);
+    // Glob -> regex: escape regex specials, then any run of '*' becomes '.*'.
+    const rx = new RegExp('^' + target
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*+/g, '.*') + '$');
+    return rx.test(subject);
+  };
+
   return {
     title: 'Test Files',
-    onlyInDocs: [...docTests].filter(t => !codeTests.has(t)),
-    onlyInCode: [...codeTests].filter(t => !docTests.has(t)),
+    onlyInDocs: docArr.filter(d => !codeArr.some(c => matches(d, c))),
+    onlyInCode: codeArr.filter(c => !docArr.some(d => matches(d, c))),
   };
 }
 
+/**
+ * Collect every test file in the project (relative paths), monorepo-aware:
+ *   - configured config.testPatterns
+ *   - any *.test.* / *.spec.* found recursively under each source root
+ *     (catches co-located and deeply-nested __tests__ directories)
+ *   - root-level conventional test dirs (tests/, e2e/, cypress/, etc.)
+ * @returns {Set<string>} relative test file paths
+ */
+export function collectCodeTests(dir, config = {}) {
+  const codeTests = new Set();
+  const isTest = (f) => /\.(test|spec)\./.test(f);
+
+  // 1. configured patterns
+  for (const f of getTestFilesFromPatterns(dir, config?.testPatterns || [], config)) {
+    codeTests.add(f);
+  }
+
+  // 2. recursive scan of each source root (co-located + nested __tests__)
+  for (const root of resolveSourceRoots(dir, config)) {
+    for (const f of getFilesRecursive(root, config)) {
+      if (isTest(f)) codeTests.add(relative(dir, f));
+    }
+  }
+
+  // 3. root-level conventional test dirs (e2e lives outside any source root)
+  for (const td of ['tests', 'test', '__tests__', 'spec', 'e2e', 'cypress']) {
+    const testDir = join(resolve(dir), td);
+    if (!existsSync(testDir)) continue;
+    for (const f of getFilesRecursive(testDir, config)) {
+      if (isTest(f)) codeTests.add(relative(dir, f));
+    }
+  }
+
+  return codeTests;
+}
+
 /**
  * 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) {
+export function getTestFilesFromPatterns(dir, patterns, config) {
   const results = new Set();
 
   function walk(currentDir) {
@@ -222,6 +248,31 @@ function getTestFilesFromPatterns(dir, patterns, config) {
   return [...results];
 }
 
+/** Returns true if any file with the given extension exists under dir (ignoring vendor dirs). */
+function hasFileWithExt(dir, ext, config) {
+  let found = false;
+  const walk = (d) => {
+    if (found) return;
+    let entries;
+    try { entries = readdirSync(d); } catch { return; }
+    for (const entry of entries) {
+      if (found) return;
+      if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
+      const full = join(d, entry);
+      try {
+        const stat = statSync(full);
+        if (stat.isDirectory()) walk(full);
+        else if (stat.isFile() && extname(full) === ext) {
+          const rel = relative(dir, full);
+          if (!config || !shouldIgnore(rel, config)) found = true;
+        }
+      } catch { /* skip */ }
+    }
+  };
+  walk(dir);
+  return found;
+}
+
 function getFilesRecursive(dir, config) {
   const results = [];
   if (!existsSync(dir)) return results;

package/cli/validators/docs-sync.mjs

@@ -4,23 +4,36 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 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',
   'coverage', '.cache', '__pycache__', '.venv', 'vendor',
 ]);
 
+/**
+ * Expand sub-path patterns (e.g. 'routes', 'src/routes') against the project
+ * root AND every configured source root, returning de-duplicated existing dirs.
+ * Makes route/service discovery monorepo-aware (e.g. backend/src/routes).
+ */
+function expandDirs(projectDir, config, subPaths) {
+  const bases = [resolve(projectDir), ...resolveSourceRoots(projectDir, config)];
+  const out = [];
+  const seen = new Set();
+  for (const base of bases) {
+    for (const sub of subPaths) {
+      const dir = resolve(base, sub);
+      if (seen.has(dir) || !existsSync(dir)) continue;
+      seen.add(dir);
+      out.push(dir);
+    }
+  }
+  return out;
+}
+
 export function validateDocsSync(projectDir, config) {
   const results = { name: 'docs-sync', errors: [], warnings: [], passed: 0, total: 0 };
 
-  // Find route/API files and check they're mentioned in canonical docs
-  const routePatterns = [
-    { dir: 'src/routes', label: 'route' },
-    { dir: 'src/app/api', label: 'API route' },
-    { dir: 'api', label: 'API route' },
-    { dir: 'routes', label: 'route' },
-  ];
-
   // Load all canonical doc content for checking
   const canonicalDir = resolve(projectDir, 'docs-canonical');
   let canonicalContent = '';
@@ -39,10 +52,9 @@ export function validateDocsSync(projectDir, config) {
     return results; // No canonical docs to check against
   }
 
-  for (const { dir, label } of routePatterns) {
-    const routeDir = resolve(projectDir, dir);
-    if (!existsSync(routeDir)) continue;
-
+  // 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']);
+  for (const routeDir of routeDirs) {
     const files = getFilesRecursive(routeDir);
     for (const file of files) {
       const ext = extname(file);
@@ -56,17 +68,14 @@ export function validateDocsSync(projectDir, config) {
       if (canonicalContent.includes(relPath) || canonicalContent.includes(name)) {
         results.passed++;
       } else {
-        results.warnings.push(`${label} ${relPath} not referenced in any canonical doc`);
+        results.warnings.push(`route ${relPath} not referenced in any canonical doc`);
       }
     }
   }
 
-  // Find service files and check they're documented
-  const serviceDirs = ['src/services', 'services', 'src/lib'];
-  for (const dir of serviceDirs) {
-    const serviceDir = resolve(projectDir, dir);
-    if (!existsSync(serviceDir)) continue;
-
+  // Find service files (monorepo-aware) and check they're documented.
+  const serviceDirs = expandDirs(projectDir, config, ['src/services', 'services', 'src/lib']);
+  for (const serviceDir of serviceDirs) {
     const files = getFilesRecursive(serviceDir);
     for (const file of files) {
       const ext = extname(file);
@@ -107,11 +116,8 @@ export function validateDocsSync(projectDir, config) {
   }
 
   if (openapiContent && openapiFile) {
-    // Check that route files have corresponding paths in OpenAPI spec
-    for (const { dir } of routePatterns) {
-      const routeDir = resolve(projectDir, dir);
-      if (!existsSync(routeDir)) continue;
-
+    // 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'])) {
       const files = getFilesRecursive(routeDir);
       for (const file of files) {
         const ext = extname(file);

package/cli/validators/drift.mjs

@@ -27,6 +27,10 @@ export function validateDrift(projectDir, config) {
     if (!CODE_EXTENSIONS.has(ext)) return;
 
     const content = readFileSync(filePath, 'utf-8');
+
+    // Fast early-return: skip expensive string split if no comment exists
+    if (!content.includes('DRIFT:')) return;
+
     const lines = content.split('\n');
 
     lines.forEach((line, i) => {
@@ -43,8 +47,8 @@ export function validateDrift(projectDir, config) {
   });
 
   if (driftComments.length === 0) {
-    results.total = 1;
-    results.passed = 1;
+    // No // DRIFT: comments to reconcile — not applicable (NOT a pass).
+    results.note = 'no // DRIFT: comments in code';
     return results;
   }
 

package/cli/validators/environment.mjs

@@ -5,6 +5,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { grepEnvUsage } from '../shared-source.mjs';
 
 export function validateEnvironment(projectDir, config) {
   const results = { name: 'environment', errors: [], warnings: [], passed: 0, total: 0 };
@@ -17,21 +18,60 @@ export function validateEnvironment(projectDir, config) {
 
   const content = readFileSync(envDocPath, 'utf-8');
 
-  // Check for required sections
+  // Check for required sections (anchored headings — not substring matches that
+  // could hit a TOC entry or code block).
+  const hasHeading = (re) => re.test(content);
   results.total++;
-  if (content.includes('## Prerequisites') || content.includes('## Setup Steps')) {
+  if (hasHeading(/^#{2,3}\s+(Prerequisites|Setup Steps)\b/m)) {
     results.passed++;
   } else {
     results.warnings.push('ENVIRONMENT.md: missing "## Prerequisites" or "## Setup Steps" section');
   }
 
   results.total++;
-  if (content.includes('## Environment Variables') || content.includes('## Setup Steps')) {
+  if (hasHeading(/^#{2,3}\s+Environment Variables\b/m)) {
     results.passed++;
   } else {
     results.warnings.push('ENVIRONMENT.md: missing "## Environment Variables" section');
   }
 
+  // ── Real code-truth check: env vars USED in code but documented nowhere ──
+  // (Replaces the old pure section-presence heuristic with an actual comparison
+  // against process.env / import.meta.env usage. .env.example counts as docs.
+  // CLI/library projects that declare no env vars skip this.)
+  if (ptc.needsEnvVars !== false) {
+    const documented = new Set();
+    const varRe = /`([A-Z][A-Z0-9_]{2,})`/g;
+    let m;
+    while ((m = varRe.exec(content)) !== null) documented.add(m[1]);
+    for (const envFile of ['.env.example', '.env.template']) {
+      const p = resolve(projectDir, envFile);
+      if (!existsSync(p)) continue;
+      const re = /^([A-Z][A-Z0-9_]+)\s*=/gm;
+      const ex = readFileSync(p, 'utf-8');
+      let em;
+      while ((em = re.exec(ex)) !== null) documented.add(em[1]);
+    }
+
+    const codeUsed = grepEnvUsage(projectDir, config);
+
+    // Only assess when code actually reads env vars — otherwise the check is
+    // vacuous (always passes) and would just inflate the count.
+    if (codeUsed.size > 0) {
+      const usedButUndocumented = [...codeUsed].filter(v => !documented.has(v));
+      results.total++;
+      if (usedButUndocumented.length === 0) {
+        results.passed++;
+      } else {
+        const shown = usedButUndocumented.slice(0, 10).join(', ');
+        const more = usedButUndocumented.length > 10 ? ` (+${usedButUndocumented.length - 10} more)` : '';
+        results.warnings.push(
+          `${usedButUndocumented.length} env var(s) used in code but not documented in ENVIRONMENT.md / .env.example: ${shown}${more}`
+        );
+      }
+    }
+  }
+
   // Only check .env.example if the project type needs it
   if (ptc.needsEnvExample !== false && ptc.needsEnvVars !== false) {
     // Check if .env.example is referenced and exists

package/cli/validators/freshness.mjs

@@ -8,7 +8,7 @@
 
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -22,8 +22,9 @@ const IGNORE_DIRS = new Set([
  */
 function getLastGitDate(filePath, dir) {
   try {
-    const result = execSync(
-      `git log -1 --format="%aI" -- "${filePath}"`,
+    const result = execFileSync(
+      'git',
+      ['log', '-1', '--format=%aI', '--', filePath],
       { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
     ).trim();
     return result ? new Date(result) : null;

package/cli/validators/metadata-sync.mjs

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname } from 'node:path';
 import { loadIgnorePatterns } from '../shared.mjs';
+import { collectPackageJsons } from '../shared-source.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -22,18 +23,23 @@ const IGNORE_DIRS = new Set([
  */
 export function validateMetadataSync(projectDir, config) {
   const warnings = [];
+  const fixes = [];
   let passed = 0;
   let total = 0;
 
   // ── Get source of truth: package.json version ──
+  // Prefer the root package version; in a monorepo where the root is just a
+  // workspace manifest with no version, fall back to a source-root package.
   const pkgPath = resolve(projectDir, 'package.json');
-  if (!existsSync(pkgPath)) {
-    return { errors: [], warnings, passed: 0, total: 0 };
+  let currentVersion = null;
+  if (existsSync(pkgPath)) {
+    try { currentVersion = JSON.parse(readFileSync(pkgPath, 'utf-8')).version || null; } catch { /* ignore */ }
+  }
+  if (!currentVersion) {
+    for (const { pkg } of collectPackageJsons(projectDir, config)) {
+      if (pkg.version) { currentVersion = pkg.version; break; }
+    }
   }
-
-  let pkg;
-  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { return { errors: [], warnings, passed: 0, total: 0 }; }
-  const currentVersion = pkg.version;
   if (!currentVersion) return { errors: [], warnings, passed: 0, total: 0 };
 
   // Parse into components for smart comparison
@@ -55,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++;
         }
@@ -115,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++;
@@ -123,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

@@ -8,7 +8,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative } from 'node:path';
-import { loadIgnorePatterns } from '../shared.mjs';
+import { loadIgnorePatterns, c } from '../shared.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -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 ──────────────────────────────────────────────────────────────────
@@ -162,6 +165,8 @@ function walkFiles(dir, callback) {
       } else if (stat.isFile()) {
         callback(fullPath);
       }
-    } catch { /* skip */ }
+    } catch (err) {
+      console.error(`${c.red}Error reading file or directory: ${err.message}${c.reset}`);
+    }
   }
 }

package/cli/validators/schema-sync.mjs

@@ -11,6 +11,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname, basename } from 'node:path';
+import { resolveSourceRoots } from '../shared-source.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -85,7 +86,7 @@ export function validateSchemaSync(projectDir, config) {
   if (!existsSync(dataModelPath)) {
     // No DATA-MODEL.md — nothing to sync against
     // Only warn if we detect schema files
-    const detectedModels = detectAllModels(projectDir);
+    const detectedModels = detectAllModels(projectDir, config);
     if (detectedModels.length > 0) {
       results.total++;
       results.warnings.push(
@@ -99,7 +100,7 @@ export function validateSchemaSync(projectDir, config) {
   const dataModelContent = readFileSync(dataModelPath, 'utf-8').toLowerCase();
 
   // Detect all models/tables across schemas
-  const detectedModels = detectAllModels(projectDir);
+  const detectedModels = detectAllModels(projectDir, config);
 
   if (detectedModels.length === 0) {
     // No schema files found — silently pass
@@ -136,11 +137,11 @@ export function validateSchemaSync(projectDir, config) {
 /**
  * Detect all database models/tables across all supported frameworks.
  */
-function detectAllModels(projectDir) {
+function detectAllModels(projectDir, config = {}) {
   const models = [];
 
   for (const detector of SCHEMA_DETECTORS) {
-    const files = findSchemaFiles(projectDir, detector);
+    const files = findSchemaFiles(projectDir, detector, config);
 
     for (const filePath of files) {
       let content;
@@ -171,14 +172,22 @@ function detectAllModels(projectDir) {
 /**
  * Find schema files for a given detector configuration.
  */
-function findSchemaFiles(projectDir, detector) {
+function findSchemaFiles(projectDir, detector, config = {}) {
   const files = [];
 
-  for (const searchDir of detector.searchDirs) {
-    const dir = resolve(projectDir, searchDir);
-    if (!existsSync(dir)) continue;
-
-    scanSchemaDir(dir, detector.filePattern, files);
+  // Monorepo-aware: resolve each searchDir against the project root AND every
+  // configured source root (config.sourceRoot + workspaces), so schemas under
+  // e.g. backend/src/models are found — not just root-relative paths.
+  const bases = [resolve(projectDir), ...resolveSourceRoots(projectDir, config)];
+  const seenDirs = new Set();
+
+  for (const base of bases) {
+    for (const searchDir of detector.searchDirs) {
+      const dir = resolve(base, searchDir);
+      if (seenDirs.has(dir) || !existsSync(dir)) continue;
+      seenDirs.add(dir);
+      scanSchemaDir(dir, detector.filePattern, files);
+    }
   }
 
   return files;