docguard-cli 0.23.0 → 0.24.0

package/cli/scanners/routes.mjs

@@ -8,12 +8,10 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname, dirname } 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', '.turbo',
-]);
+import { resolveSourceRoots, readScannable } from '../shared-source.mjs';
+import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, shouldIgnore, relPosix } from '../shared-ignore.mjs';
+import { extractJsRouteCalls, extractJsRouteObjects, extractJsMountsAndImports } from './js-ast.mjs';
+import { extractPythonFiles } from './py-ast.mjs';
 
 /**
  * Scan routes from source code with framework-aware parsing.
@@ -80,12 +78,16 @@ export function scanRoutesDeep(dir, stack, docTools, opts = {}) {
     routes.push(...scanFastAPIRoutes(dir));
   }
 
-  // Deduplicate by method+path
+  // Deduplicate by method+path, and honor .docguardignore / config.ignore so a
+  // fixtures dir with fake routes doesn't pollute the API surface. Filtering the
+  // RESULTS (route.file → project-relative) keeps the per-framework walkers as-is.
+  const cfg = opts.config || {};
   const seen = new Set();
   return routes.filter(r => {
     const key = `${r.method}:${r.path}`;
     if (seen.has(key)) return false;
     seen.add(key);
+    if (r.file && shouldIgnore(relPosix(dir, resolve(dir, r.file)), cfg)) return false;
     return true;
   });
 }
@@ -118,8 +120,15 @@ function scanNextJsRoutes(dir) {
       const relDir = relative(resolve(dir, apiBase), dirname(filePath));
       const apiPath = '/' + relDir
         .replace(/\\/g, '/')
-        .replace(/\[\.\.\.(\w+)\]/g, ':$1*')  // Catch-all [...slug]
-        .replace(/\[(\w+)\]/g, ':$1');          // Dynamic [id]
+        // Strip route-group segments like `(admin)` — they organize files but
+        // do NOT appear in the URL. The frontend scanner already does this; the
+        // route scanner used to leak them, e.g. `/api/(admin)/users`.
+        .split('/')
+        .filter(seg => seg && !/^\(.*\)$/.test(seg))
+        .join('/')
+        .replace(/\[\[\.\.\.(\w+)\]\]/g, ':$1*')  // Optional catch-all [[...slug]] — before [...slug]
+        .replace(/\[\.\.\.(\w+)\]/g, ':$1*')        // Catch-all [...slug]
+        .replace(/\[(\w+)\]/g, ':$1');               // Dynamic [id]
 
       // Extract exported HTTP methods
       const methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
@@ -195,9 +204,22 @@ function scanNextJsRoutes(dir) {
 // ── Express / Generic Node.js ───────────────────────────────────────────────
 
 function scanExpressRoutes(dir, roots = null) {
-  const routes = [];
+  // Regex is the FALLBACK (used only when @babel/parser can't parse a file).
+  // It hardcodes app/router/server receivers; the AST path matches any receiver.
   const routePattern = /(?:app|router|server)\s*\.\s*(get|post|put|delete|patch|head|options)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
 
+  // ── Phase 0: collect every candidate file ONCE ──────────────────────────────
+  // The mount map (phase 1) and the route emit (phase 2) must see the same set,
+  // and we don't want to walk the tree twice.
+  const files = [];                 // { content, filePath, fileLabel }
+  const seenPaths = new Set();
+  const addFile = (filePath, fileLabel) => {
+    if (seenPaths.has(filePath)) return;
+    const content = readFileSafe(filePath);
+    if (!content) return;
+    seenPaths.add(filePath);
+    files.push({ content, filePath, fileLabel });
+  };
   // Monorepo-aware: walk resolved absolute source roots when provided,
   // otherwise fall back to conventional root-relative directories.
   const searchTargets = roots && roots.length
@@ -205,51 +227,114 @@ function scanExpressRoutes(dir, roots = null) {
     : ['src', 'routes', 'api', 'server', 'lib'].map(d => resolve(dir, d));
   for (const fullDir of searchTargets) {
     if (!existsSync(fullDir)) continue;
-
     walkRouteDirs(fullDir, (filePath) => {
-      if (!isJSFile(filePath)) return;
-      const content = readFileSafe(filePath);
-      if (!content) return;
+      if (isJSFile(filePath)) addFile(filePath, relative(dir, filePath));
+    });
+  }
+  for (const rootFile of ['app.js', 'app.mjs', 'app.ts', 'server.js', 'server.ts', 'index.js', 'index.ts']) {
+    const filePath = resolve(dir, rootFile);
+    if (existsSync(filePath)) addFile(filePath, rootFile);
+  }
 
-      let match;
-      const regex = new RegExp(routePattern.source, 'gi');
-      while ((match = regex.exec(content)) !== null) {
+  // ── Phase 1: build the mount map ────────────────────────────────────────────
+  // absFilePath -> [{ receiver|null, prefix }].  `receiver === null` means the
+  // prefix applies to EVERY route in that file (an imported sub-router); a
+  // non-null receiver means it applies only to routes whose receiver matches
+  // (a same-file `const r = Router(); app.use('/api', r)` — so a sibling
+  // `app.get('/health')` in the same file is NOT wrongly prefixed).
+  const mountMap = buildExpressMountMap(files);
+
+  // ── Phase 2: emit routes, prefixing by mount where known ────────────────────
+  const routes = [];
+  for (const { content, filePath, fileLabel } of files) {
+    const mounts = mountMap.get(filePath) || [];
+    const emit = (method, path, index, receiver) => {
+      const prefixes = mounts
+        .filter(m => m.receiver === null || m.receiver === receiver)
+        .map(m => m.prefix);
+      const finalPaths = prefixes.length ? prefixes.map(p => joinRoutePath(p, path)) : [path];
+      for (const fullPath of finalPaths) {
         routes.push({
-          method: match[1].toUpperCase(),
-          path: match[2],
-          handler: extractHandlerName(content, match.index),
-          file: relative(dir, filePath),
+          method: method.toUpperCase(),
+          path: fullPath,
+          handler: extractHandlerName(content, index),
+          file: fileLabel,
           source: 'express',
-          auth: hasAuthMiddleware(content, match[2]),
-          description: extractNearbyComment(content, match.index),
+          auth: hasAuthMiddleware(content, path),
+          description: extractNearbyComment(content, index),
         });
       }
-    });
+    };
+    const ast = extractJsRouteCalls(content, filePath);
+    if (ast) {
+      for (const r of ast) emit(r.method, r.path, r.start, r.receiver ?? null);
+    } else {
+      const regex = new RegExp(routePattern.source, 'gi');
+      let match;
+      while ((match = regex.exec(content)) !== null) emit(match[1], match[2], match.index, null);
+    }
   }
 
-  // Also check root files
-  for (const rootFile of ['app.js', 'app.mjs', 'app.ts', 'server.js', 'server.ts', 'index.js', 'index.ts']) {
-    const filePath = resolve(dir, rootFile);
-    if (!existsSync(filePath)) continue;
-    const content = readFileSafe(filePath);
-    if (!content) return;
+  return routes;
+}
 
-    let match;
-    const regex = new RegExp(routePattern.source, 'gi');
-    while ((match = regex.exec(content)) !== null) {
-      routes.push({
-        method: match[1].toUpperCase(),
-        path: match[2],
-        handler: extractHandlerName(content, match.index),
-        file: rootFile,
-        source: 'express',
-        auth: hasAuthMiddleware(content, match[2]),
-        description: extractNearbyComment(content, match.index),
-      });
+/**
+ * Build the Express mount map from the collected files (phase 1 above).
+ * For each `<x>.use('/prefix', router)`:
+ *   - router is an IMPORTED binding  → the prefix applies to ALL routes in the
+ *     resolved target file (receiver: null). One router per file is the norm.
+ *   - router is a LOCAL identifier    → the prefix applies only to that file's
+ *     routes whose receiver matches (receiver: ident).
+ *
+ * Known limitations (documented, not silently wrong): transitive composition
+ * (`app.use('/api', api)` then `api.use('/x', x)` does NOT yield `/api/x`), and
+ * dynamic mount paths (non-string-literal prefixes) are skipped. Unmounted
+ * files keep their bare paths — exactly the pre-mount-map behavior.
+ */
+function buildExpressMountMap(files) {
+  const map = new Map();
+  const add = (absFile, receiver, prefix) => {
+    if (!map.has(absFile)) map.set(absFile, []);
+    map.get(absFile).push({ receiver, prefix });
+  };
+  for (const { content, filePath } of files) {
+    const mi = extractJsMountsAndImports(content, filePath);
+    if (!mi) continue;
+    for (const { prefix, ident } of mi.mounts) {
+      const spec = mi.imports[ident];
+      if (spec) {
+        const target = resolveLocalImport(filePath, spec);
+        if (target) add(target, null, prefix);
+      } else {
+        add(filePath, ident, prefix);
+      }
     }
   }
+  return map;
+}
 
-  return routes;
+/** Resolve a RELATIVE import specifier to an absolute file path (best effort). */
+function resolveLocalImport(fromFile, spec) {
+  if (!spec.startsWith('.')) return null; // bare/node_modules specifiers aren't our routers
+  const base = resolve(dirname(fromFile), spec);
+  for (const ext of ['', '.ts', '.js', '.mjs', '.cjs', '.tsx', '.jsx']) {
+    const cand = base + ext;
+    try { if (existsSync(cand) && statSync(cand).isFile()) return cand; } catch { /* skip */ }
+  }
+  for (const idx of ['index.ts', 'index.js', 'index.mjs']) {
+    const cand = join(base, idx);
+    try { if (existsSync(cand) && statSync(cand).isFile()) return cand; } catch { /* skip */ }
+  }
+  return null;
+}
+
+/** Join a mount prefix and a route path into one normalized `/a/b` path. */
+function joinRoutePath(prefix, p) {
+  if (!prefix) return p;
+  const left = prefix.replace(/\/+$/, '');        // drop trailing slash(es)
+  const right = (p === '/' || p === '') ? '' : ('/' + p.replace(/^\/+/, '')); // single leading slash
+  const joined = left + right;
+  return joined || '/';
 }
 
 // ── Fastify ─────────────────────────────────────────────────────────────────
@@ -266,18 +351,28 @@ function scanFastifyRoutes(dir, roots = null) {
       const content = readFileSafe(filePath);
       if (!content) return;
 
-      let match;
-      const regex = new RegExp(pattern.source, 'gi');
-      while ((match = regex.exec(content)) !== null) {
-        routes.push({
-          method: match[1].toUpperCase(),
-          path: match[2],
-          handler: extractHandlerName(content, match.index),
-          file: relative(dir, filePath),
-          source: 'fastify',
-          auth: hasAuthCheck(content),
-          description: extractNearbyComment(content, match.index),
-        });
+      const emit = (method, path, index) => routes.push({
+        method: method.toUpperCase(),
+        path,
+        handler: extractHandlerName(content, index),
+        file: relative(dir, filePath),
+        source: 'fastify',
+        auth: hasAuthCheck(content),
+        description: extractNearbyComment(content, index),
+      });
+
+      // AST-first: method shorthand (fastify.get('/x')) AND the declarative
+      // object form (fastify.route({ method, url })) the regex never matched.
+      // Both return null only on parse failure → regex fallback.
+      const calls = extractJsRouteCalls(content, filePath);
+      const objs = extractJsRouteObjects(content, filePath);
+      if (calls || objs) {
+        for (const r of calls || []) emit(r.method, r.path, r.start);
+        for (const r of objs || []) emit(r.method, r.path, r.start);
+      } else {
+        let match;
+        const regex = new RegExp(pattern.source, 'gi');
+        while ((match = regex.exec(content)) !== null) emit(match[1], match[2], match.index);
       }
     });
   }
@@ -302,18 +397,25 @@ function scanHonoRoutes(dir, roots = null) {
       const content = readFileSafe(filePath);
       if (!content) return;
 
-      let match;
-      const regex = new RegExp(pattern.source, 'gi');
-      while ((match = regex.exec(content)) !== null) {
-        routes.push({
-          method: match[1].toUpperCase(),
-          path: match[2],
-          handler: '',
-          file: relative(dir, filePath),
-          source: 'hono',
-          auth: hasAuthCheck(content),
-          description: extractNearbyComment(content, match.index),
-        });
+      const emit = (method, path, index) => routes.push({
+        method: method.toUpperCase(),
+        path,
+        handler: '',
+        file: relative(dir, filePath),
+        source: 'hono',
+        auth: hasAuthCheck(content),
+        description: extractNearbyComment(content, index),
+      });
+
+      // AST-first (any receiver, multi-line, template paths — Hono/Koa method
+      // shorthand `app.get('/x')` / `router.get('/x')`); regex fallback.
+      const calls = extractJsRouteCalls(content, filePath);
+      if (calls) {
+        for (const r of calls) emit(r.method, r.path, r.start);
+      } else {
+        let match;
+        const regex = new RegExp(pattern.source, 'gi');
+        while ((match = regex.exec(content)) !== null) emit(match[1], match[2], match.index);
       }
     });
   }
@@ -357,10 +459,33 @@ function scanFastAPIRoutes(dir) {
   const pattern = /@(?:app|router)\s*\.\s*(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]/gi;
 
   const pyFiles = findFiles(dir, /\.py$/);
+  // AST-first: ONE python3 subprocess parses every file. `null` means Python is
+  // unavailable or the subprocess failed → regex fallback for all files. A
+  // per-file `ok:false` falls back for just that file. The AST form also reads
+  // multi-line decorators and Flask `methods=[...]` arrays the regex misses.
+  const astByFile = extractPythonFiles(pyFiles);
+
   for (const filePath of pyFiles) {
     const content = readFileSafe(filePath);
     if (!content) continue;
 
+    const parsed = astByFile && astByFile[filePath];
+    const fileAuth = content.includes('Depends(') && content.includes('auth');
+    if (parsed && parsed.ok) {
+      for (const r of parsed.routes || []) {
+        routes.push({
+          method: r.method,
+          path: r.path,
+          handler: r.func || '',
+          file: relative(dir, filePath),
+          source: 'fastapi',
+          auth: fileAuth,
+          description: r.desc || '',
+        });
+      }
+      continue;
+    }
+
     let match;
     const regex = new RegExp(pattern.source, 'gi');
     while ((match = regex.exec(content)) !== null) {
@@ -370,7 +495,7 @@ function scanFastAPIRoutes(dir) {
         handler: extractPythonFunctionName(content, match.index),
         file: relative(dir, filePath),
         source: 'fastapi',
-        auth: content.includes('Depends(') && content.includes('auth'),
+        auth: fileAuth,
         description: extractPythonDocstring(content, match.index),
       });
     }
@@ -515,7 +640,7 @@ function scanRustWebRoutes(dir) {
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 function readFileSafe(path) {
-  try { return readFileSync(path, 'utf-8'); } catch { return null; }
+  return readScannable(path); // size-capped; skips minified/generated bundles
 }
 
 function isJSFile(path) {

package/cli/scanners/schemas.mjs

@@ -8,11 +8,10 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
-
-const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo',
-]);
+import { extractJsSchemaBodies } from './js-ast.mjs';
+import { extractPythonFiles } from './py-ast.mjs';
+import { readScannable } from '../shared-source.mjs';
+import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, shouldIgnore, relPosix } from '../shared-ignore.mjs';
 
 /**
  * Deep scan schemas from ORM definitions, validation libraries, and OpenAPI specs.
@@ -21,7 +20,7 @@ const IGNORE_DIRS = new Set([
  * @param {object} docTools - Detected doc tools (may include OpenAPI)
  * @returns {object} { entities: [...], relationships: [...], source: string }
  */
-export function scanSchemasDeep(dir, stack, docTools) {
+export function scanSchemasDeep(dir, stack, docTools, config = {}) {
   // Priority 1: OpenAPI schemas
   if (docTools?.openapi?.found && docTools.openapi.schemas?.length > 0) {
     return {
@@ -78,10 +77,22 @@ export function scanSchemasDeep(dir, stack, docTools) {
     }
   }
 
+  // Honor .docguardignore / config.ignore: drop entities whose source file the
+  // user excluded (e.g. test/fixtures/**), then drop relationships that point at
+  // a dropped entity. Filtering the RESULTS (not the walk) keeps the cache and
+  // the per-ORM walkers untouched. entity.file is project-relative already.
+  const keptEntities = entities.filter(
+    e => !e.file || !shouldIgnore(relPosix(dir, resolve(dir, e.file)), config)
+  );
+  const keptNames = new Set(keptEntities.map(e => e.name));
+  const keptRelationships = keptEntities.length === entities.length
+    ? relationships
+    : relationships.filter(r => keptNames.has(r.from) && keptNames.has(r.to));
+
   return {
-    entities,
-    relationships,
-    source: entities.length > 0 ? entities[0].source : 'none',
+    entities: keptEntities,
+    relationships: keptRelationships,
+    source: keptEntities.length > 0 ? keptEntities[0].source : 'none',
   };
 }
 
@@ -220,26 +231,15 @@ function scanDrizzleSchemas(dir) {
       const content = readFileSafe(filePath);
       if (!content || !content.includes('Table(')) return;
 
-      let match;
-      const regex = new RegExp(tablePattern.source, 'g');
-      while ((match = regex.exec(content)) !== null) {
-        const varName = match[1];
-        const tableName = match[2];
-        const body = match[3];
+      // Emit one entity from a (tableName, body) pair. `body` is the balanced
+      // inner text of the table's column object.
+      const emit = (tableName, body) => {
         const fields = parseDrizzleColumns(body);
-
-        // Look for references (foreign keys)
         for (const field of fields) {
           if (field._ref) {
-            relationships.push({
-              from: tableName,
-              to: field._ref,
-              type: 'many-to-one',
-              field: field.name,
-            });
+            relationships.push({ from: tableName, to: field._ref, type: 'many-to-one', field: field.name });
           }
         }
-
         entities.push({
           name: tableName,
           fields: fields.map(f => ({ ...f, _ref: undefined })),
@@ -247,6 +247,17 @@ function scanDrizzleSchemas(dir) {
           source: 'drizzle',
           description: '',
         });
+      };
+
+      // Full-support tier: AST extraction (nested braces handled). Falls back
+      // to the legacy regex only when @babel/parser can't parse the file.
+      const ast = extractJsSchemaBodies(content, filePath);
+      if (ast) {
+        for (const s of ast) if (s.kind === 'drizzle') emit(s.table, s.body);
+      } else {
+        let match;
+        const regex = new RegExp(tablePattern.source, 'g');
+        while ((match = regex.exec(content)) !== null) emit(match[2], match[3]);
       }
     });
   }
@@ -327,20 +338,28 @@ function scanZodSchemas(dir) {
       const content = readFileSafe(filePath);
       if (!content || !content.includes('z.object')) return;
 
-      let match;
-      const regex = new RegExp(zodPattern.source, 'g');
-      while ((match = regex.exec(content)) !== null) {
-        const schemaName = match[1].replace(/Schema$|Validator$/, '');
-        const body = match[2];
-        const fields = parseZodFields(body);
-
+      const emit = (rawName, body) => {
+        const schemaName = rawName.replace(/Schema$|Validator$/, '');
         entities.push({
           name: schemaName,
-          fields,
+          fields: parseZodFields(body),
           file: relative(dir, filePath),
           source: 'zod',
           description: '',
         });
+      };
+
+      const ast = extractJsSchemaBodies(content, filePath);
+      if (ast) {
+        // Keep the legacy naming gate (only *Schema/Validator/Input/Output) so
+        // inline z.object() validations aren't treated as data-model entities.
+        for (const s of ast) {
+          if (s.kind === 'zod' && /(?:Schema|Validator|Input|Output)$/.test(s.name)) emit(s.name, s.body);
+        }
+      } else {
+        let match;
+        const regex = new RegExp(zodPattern.source, 'g');
+        while ((match = regex.exec(content)) !== null) emit(match[1], match[2]);
       }
     });
   }
@@ -407,25 +426,14 @@ function scanMongooseSchemas(dir) {
       const content = readFileSafe(filePath);
       if (!content || !content.includes('Schema(')) return;
 
-      let match;
-      const regex = new RegExp(schemaPattern.source, 'g');
-      while ((match = regex.exec(content)) !== null) {
-        const schemaName = match[1].replace(/Schema$/i, '');
-        const body = match[2];
+      const emit = (rawName, body) => {
+        const schemaName = rawName.replace(/Schema$/i, '');
         const fields = parseMongooseFields(body);
-
-        // Check for refs (relationships)
         for (const field of fields) {
           if (field._ref) {
-            relationships.push({
-              from: schemaName,
-              to: field._ref,
-              type: 'many-to-one',
-              field: field.name,
-            });
+            relationships.push({ from: schemaName, to: field._ref, type: 'many-to-one', field: field.name });
           }
         }
-
         entities.push({
           name: schemaName.charAt(0).toUpperCase() + schemaName.slice(1),
           fields: fields.map(f => ({ ...f, _ref: undefined })),
@@ -433,6 +441,15 @@ function scanMongooseSchemas(dir) {
           source: 'mongoose',
           description: '',
         });
+      };
+
+      const ast = extractJsSchemaBodies(content, filePath);
+      if (ast) {
+        for (const s of ast) if (s.kind === 'mongoose') emit(s.name, s.body);
+      } else {
+        let match;
+        const regex = new RegExp(schemaPattern.source, 'g');
+        while ((match = regex.exec(content)) !== null) emit(match[1], match[2]);
       }
     });
   }
@@ -504,8 +521,38 @@ function mapMongooseType(type) {
 function scanPythonModels(dir) {
   const entities = [];
   const relationships = [];
-  walkDir(dir, (filePath) => {
-    if (!filePath.endsWith('.py')) return;
+
+  // Collect .py files first so the AST tier parses them in ONE python3
+  // subprocess. `null` → Python unavailable / subprocess failed → regex
+  // fallback for all; a per-file `ok:false` falls back for that file only.
+  // The AST tier gets every field exactly (no body-capture truncation, no
+  // miss on multi-base classes) — undercounting fields is what makes the
+  // data-model validators falsely pass on a stale DATA-MODEL.md.
+  const pyFiles = [];
+  walkDir(dir, (filePath) => { if (filePath.endsWith('.py')) pyFiles.push(filePath); });
+  const astByFile = extractPythonFiles(pyFiles);
+
+  for (const filePath of pyFiles) {
+    const parsed = astByFile && astByFile[filePath];
+    if (parsed && parsed.ok) {
+      for (const s of parsed.schemas || []) {
+        const fields = (s.fields || []).map(f => ({
+          name: f.name, type: f.type || '', required: f.required !== false, description: '',
+        }));
+        if (fields.length > 0) entities.push({ name: s.name, fields, file: filePath, source: s.kind });
+        for (const to of s.rels || []) relationships.push({ from: s.name, to, type: 'related' });
+      }
+      continue;
+    }
+    scanPythonModelsRegex(filePath, entities, relationships);
+  }
+  return { entities, relationships };
+}
+
+// Regex (beta) fallback — used per-file when the Python AST tier is unavailable
+// or couldn't parse that file. Identical behavior to the pre-AST scanner.
+function scanPythonModelsRegex(filePath, entities, relationships) {
+  {
     const content = readFileSafe(filePath);
     if (!content) return;
     if (!/class\s+\w+\s*\([^)]*(Base|BaseModel|db\.Model|Model|SQLModel)/.test(content)) return;
@@ -549,8 +596,7 @@ function scanPythonModels(dir) {
       }
       if (fields.length > 0) entities.push({ name, fields, file: filePath, source: 'pydantic' });
     }
-  });
-  return { entities, relationships };
+  }
 }
 
 // ── Rust: Diesel `table! { ... }` ─────────────────────────────────────────────
@@ -687,7 +733,7 @@ function extractOpenAPIRelationships(schemas) {
 }
 
 function readFileSafe(path) {
-  try { return readFileSync(path, 'utf-8'); } catch { return null; }
+  return readScannable(path); // size-capped; skips minified/generated bundles
 }
 
 // v0.15-P2: walkDir is called 8 times across schemas.mjs (Pydantic, Mongoose,

package/cli/shared-ignore.mjs

@@ -50,7 +50,22 @@ const ALWAYS_REJECT_PATH_RE =
  * Returns [] if the file is missing or unreadable — never throws.
  */
 import { readFileSync, existsSync } from 'node:fs';
-import { resolve as resolvePath } from 'node:path';
+import { resolve as resolvePath, relative as relativePath, sep } from 'node:path';
+
+/**
+ * Project-relative path with POSIX (`/`) separators — the canonical form that
+ * every validator should compare against docs, ignore globs, and changed-file
+ * sets.
+ *
+ * Replaces the old `absPath.replace(projectDir + '/', '')` idiom, which failed
+ * two ways: on Windows the `/` literal never matched the OS `\` separators, and
+ * for a sibling dir sharing a prefix (`/repo` vs `/repo-staging`) the replace
+ * was a no-op — both cases left an ABSOLUTE path, silently breaking
+ * `content.includes(relPath)`, glob matching, and `--changed-only` scoping.
+ */
+export function relPosix(projectDir, absPath) {
+  return relativePath(projectDir, absPath).split(sep).join('/');
+}
 
 export function loadDocguardIgnore(projectDir) {
   const p = resolvePath(projectDir, '.docguardignore');