docguard-cli 0.23.0 → 0.24.0

package/cli/shared-source.mjs

@@ -39,6 +39,39 @@ function safeReadJson(path) {
   try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return null; }
 }
 
+/**
+ * Files DocGuard reads WHOLE and regex/AST-scans. A bundle, minified vendor
+ * file, or generated client checked into source is slow to read, hostile to
+ * regex, expensive to AST-parse, and is never the project's authored truth.
+ * 1.5 MB sits far above any hand-written module yet below typical bundles.
+ */
+export const MAX_SCAN_BYTES = 1_500_000;
+
+/** True for build artifacts / minified / generated / declaration files. */
+export function isGeneratedPath(p) {
+  const b = String(p);
+  return /\.min\.[cm]?js$/i.test(b)
+      || /\.(bundle|chunk)\.[cm]?jsx?$/i.test(b)
+      || /[.-]generated\.[a-z0-9]+$/i.test(b)
+      || /\.d\.ts$/i.test(b);
+}
+
+/**
+ * Read a source file for scanning, or return null when it should be skipped:
+ * unreadable, a generated/minified artifact, or larger than `maxBytes`. This is
+ * the single guard that keeps every scanner from choking on a checked-in
+ * bundle. Skipping is logged by callers that care (most just see "no match").
+ */
+export function readScannable(absPath, { maxBytes = MAX_SCAN_BYTES } = {}) {
+  try {
+    if (isGeneratedPath(absPath)) return null;
+    if (statSync(absPath).size > maxBytes) return null;
+    return readFileSync(absPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Expand a workspace glob (e.g. "packages/*") into concrete directories
  * that contain a package.json. Only the trailing single-level "/*" glob is
@@ -236,8 +269,8 @@ export function grepEnvUsage(projectDir, config = {}) {
     if (!CODE_EXTENSIONS.has(extname(filePath))) return;
     const rel = relative(projectDir, filePath);
     if (shouldIgnore(rel, config)) return;
-    let content;
-    try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
+    const content = readScannable(filePath);
+    if (content === null) return; // unreadable, generated, or too large to scan
     if (!content.includes('env')) return;
     // patterns[2] is the import.meta.env one — its matches are Vite-injected
     // when the name is an intrinsic, and must not be reported as user env vars.
@@ -250,6 +283,30 @@ export function grepEnvUsage(projectDir, config = {}) {
         names.add(m[1]);
       }
     }
+
+    // v0.24: env vars are increasingly declared in a validation schema
+    // (Zod / envalid / convict) and read via a typed `config` object instead of
+    // `process.env.X` — so the direct-access patterns above miss them and every
+    // documented var looked "missing from code" (field report). Only harvest
+    // when the file actually validates process.env through such a schema.
+    const validatesEnv =
+      /(?:safeParse|parse)\s*\(\s*process\.env\b/.test(content) || // zod: schema.parse(process.env)
+      /\bcleanEnv\s*\(\s*process\.env\b/.test(content) ||          // envalid
+      /\bconvict\s*\(/.test(content);                              // convict
+    if (validatesEnv) {
+      let km;
+      // Zod / envalid: the schema KEYS are the env var names. Data schemas use
+      // camelCase keys, so requiring UPPER_SNAKE keeps this env-specific.
+      const keyRe = /^\s*['"]?([A-Z][A-Z0-9_]*[A-Z0-9])['"]?\s*:/gm;
+      while ((km = keyRe.exec(content)) !== null) {
+        if (km[1].length >= 3 && !VITE_INTRINSICS.has(km[1])) names.add(km[1]);
+      }
+      // convict: the env var name is the `env:` property value, not the key.
+      const convictRe = /\benv\s*:\s*['"]([A-Z][A-Z0-9_]*[A-Z0-9])['"]/g;
+      while ((km = convictRe.exec(content)) !== null) {
+        if (km[1].length >= 3) names.add(km[1]);
+      }
+    }
   };
 
   const walk = (dir) => {

package/cli/shared-trace-patterns.mjs

@@ -12,6 +12,19 @@
  * pattern (app/api, pages/api) preserved from the v0.22.0 #195 fix.
  */
 
+/**
+ * A markdown file is documentation, never the source that *implements* a
+ * canonical doc — so it must not count as a doc→code match. Without this,
+ * SECURITY.md's "Auth modules" glob (which includes `guard`) matched
+ * `commands/docguard.guard.md` and listed DocGuard's own command docs as the
+ * project's auth modules (field report). Real config-file matches (.env,
+ * Dockerfile, pyproject.toml, .gitignore) are unaffected — none are `.md`.
+ * Used by both `docguard trace` and the guard-time Traceability validator.
+ */
+export function isTraceableSource(relPath) {
+  return !relPath.endsWith('.md');
+}
+
 export const TEST_PATTERNS = [
   // JS/TS
   /\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.test\.(mjs|cjs)$/,

package/cli/shared.mjs

@@ -39,6 +39,65 @@ export function resolveSeverity(config, validatorKey) {
   return 'medium';
 }
 
+// ── Canonical section heading matching ─────────────────────────────────────
+/**
+ * Required canonical sections used to be matched by literal substring, so an
+ * arc42/C4 doc with "## 5.4 Layer boundaries" or "## Building Block View"
+ * scored as if the section were absent — the validator made well-structured
+ * docs look WORSE than the skeleton (field report). These synonyms + section-
+ * number tolerance let equivalent headings count. Synonyms only ever ADD
+ * matches; the literal canonical heading always still passes.
+ *
+ * Keyed by the normalized canonical heading (lowercase, alphanumerics + spaces).
+ */
+export const SECTION_SYNONYMS = {
+  'system overview':       ['system context', 'system summary', 'introduction and goals', 'context and scope', 'overview and goals'],
+  'component map':         ['components', 'component overview', 'building block view', 'building blocks', 'containers', 'module overview'],
+  'tech stack':            ['technology stack', 'technologies', 'technical stack'],
+  'entities':              ['entity definitions', 'data model', 'domain model', 'data entities'],
+  'authentication':        ['auth', 'authn', 'authentication and authorization', 'identity'],
+  'secrets management':    ['secrets', 'secret management', 'secrets handling', 'credentials', 'credential management'],
+  'test categories':       ['test types', 'categories of tests', 'test strategy', 'testing strategy', 'test approach'],
+  'coverage rules':        ['coverage', 'coverage targets', 'coverage goals', 'coverage requirements', 'coverage policy'],
+  'environment variables': ['env vars', 'environment', 'configuration', 'config variables'],
+  'setup steps':           ['setup', 'getting started', 'installation', 'setup instructions', 'local setup', 'quick start'],
+  'layer boundaries':      ['layers', 'layering', 'module boundaries', 'layer boundary', 'boundaries'],
+  'external dependencies': ['dependencies', 'external systems', 'third party dependencies', 'integrations', 'external interfaces'],
+  'revision history':      ['changelog', 'change history', 'history', 'revisions', 'document history', 'change log'],
+};
+
+/** Normalize a markdown heading: drop #, leading arc42-style numbers, punctuation. */
+function normalizeHeadingText(line) {
+  return line
+    .replace(/^#{1,6}\s*/, '')             // strip leading #s
+    .replace(/^\d+(?:\.\d+)*\.?\s+/, '')   // strip leading "5.4 " / "3. " section numbers
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')           // non-alphanumeric → single space
+    .trim();
+}
+
+/**
+ * True if `content` has an H2–H6 heading equivalent to `canonicalHeading` —
+ * the exact text, a known synonym, or the same text behind an arc42-style
+ * section number (e.g. "## 5.4 Layer boundaries" satisfies "## Layer Boundaries").
+ *
+ * @param {string} content - markdown file contents
+ * @param {string} canonicalHeading - e.g. '## Component Map' or 'Component Map'
+ */
+export function docHasSection(content, canonicalHeading) {
+  const key = normalizeHeadingText(canonicalHeading);
+  if (!key) return false;
+  const accepted = [key, ...(SECTION_SYNONYMS[key] || [])];
+  const headings = content.match(/^#{2,6}\s+.+$/gm) || [];
+  for (const line of headings) {
+    const norm = normalizeHeadingText(line);
+    for (const phrase of accepted) {
+      if (norm.includes(phrase)) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Parse a dotted-decimal version string into a tuple of integers for
  * comparison. Tolerates extra suffixes (e.g. `0.4-beta` → [0, 4]).
@@ -85,7 +144,7 @@ export const c = {
 // ── Compliance Profiles ───────────────────────────────────────────────────
 export const PROFILES = {
   starter: {
-    description: 'Minimal CDD — just architecture + changelog. For side projects and prototypes.',
+    description: 'Minimal CDD — architecture + changelog, no Spec Kit framework scaffold (pass --spec-kit to add it). For side projects and prototypes.',
     requiredFiles: {
       canonical: [
         'docs-canonical/ARCHITECTURE.md',

package/cli/validator-markers.mjs

@@ -0,0 +1,91 @@
+/**
+ * Inline whole-validator N/A markers — "declare intentional non-applicability,
+ * visibly."
+ *
+ * A project can mute an entire validator from inside its docs, with the
+ * rationale right next to the declaration and tracked in git:
+ *
+ *   <!-- docguard:validator testSpec n/a — POC, no automated tests yet -->
+ *   <!-- docguard:validator traceability n/a — no formal requirements doc -->
+ *
+ * This is the validator-level sibling of the section-level
+ * `<!-- docguard:section <id> n/a — reason -->`. Unlike the config switch
+ * (`validators: { testSpec: false }`), which renders as a silent "disabled",
+ * a marked validator renders as a visible `➖ [N/A] (declared N/A: reason)` —
+ * honest non-applicability, not an invisible skip or a fake green check.
+ *
+ * Markers are read from the project's primary docs (canonical docs + the root
+ * agent/readme files) so the rationale lives where humans and agents read.
+ *
+ * Zero NPM dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+// `<!-- docguard:validator <key> n/a [— reason] -->`
+// Separator before the reason may be —, :, or one-or-more hyphens. Reason
+// is optional. Case-insensitive on the keyword and "n/a".
+const MARKER_RE = /<!--\s*docguard:validator\s+([A-Za-z0-9_-]+)\s+n\/a\b\s*(?:[—:\-]+\s*([^>]*?))?\s*-->/gi;
+
+/** Files where a validator marker is honored — the docs humans actually read. */
+function markerSourceFiles(projectDir) {
+  const files = [];
+  const canonicalDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonicalDir)) {
+    try {
+      for (const f of readdirSync(canonicalDir)) {
+        if (f.toLowerCase().endsWith('.md')) files.push(join(canonicalDir, f));
+      }
+    } catch { /* ignore */ }
+  }
+  for (const root of ['AGENTS.md', 'README.md', 'CLAUDE.md']) {
+    const p = resolve(projectDir, root);
+    if (existsSync(p)) files.push(p);
+  }
+  return files;
+}
+
+/** Normalize a key for tolerant matching: `Test-Spec`/`test_spec` → `testspec`. */
+function norm(key) {
+  return String(key).toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/**
+ * Scan the project's primary docs for `docguard:validator <key> n/a` markers.
+ *
+ * @param {string} projectDir
+ * @param {Iterable<string>} validKeys - the canonical validator keys (camelCase)
+ * @returns {{ suppressed: Map<string,string>, unknown: Array<{raw:string, file:string}> }}
+ *   `suppressed` maps a canonical validator key → reason ('' if none given).
+ *   `unknown` lists markers whose key didn't resolve (typo protection).
+ */
+export function loadValidatorSuppressions(projectDir, validKeys) {
+  const canonicalByNorm = new Map();
+  for (const k of validKeys) canonicalByNorm.set(norm(k), k);
+
+  const suppressed = new Map();
+  const unknown = [];
+
+  for (const file of markerSourceFiles(projectDir)) {
+    let content;
+    try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+    if (!content.includes('docguard:validator')) continue;
+
+    MARKER_RE.lastIndex = 0;
+    let m;
+    while ((m = MARKER_RE.exec(content)) !== null) {
+      const rawKey = m[1];
+      const reason = (m[2] || '').trim();
+      const canonical = canonicalByNorm.get(norm(rawKey));
+      if (!canonical) {
+        unknown.push({ raw: rawKey, file });
+        continue;
+      }
+      // First marker wins; keep its reason. Re-declaring is harmless.
+      if (!suppressed.has(canonical)) suppressed.set(canonical, reason);
+    }
+  }
+
+  return { suppressed, unknown };
+}

package/cli/validators/api-surface.mjs

@@ -29,6 +29,7 @@ import { detectOpenAPI } from '../scanners/doc-tools.mjs';
 import { scanRoutesDeep } from '../scanners/routes.mjs';
 import { parseApiReferenceDoc, compareEndpoints, endpointKey } from '../scanners/api-doc.mjs';
 import { collectPackageJsons, getWorkspaceDirs } from '../shared-source.mjs';
+import { relPosix } from '../shared-ignore.mjs';
 
 const MAX_REPORTED = 15;
 const API_DOC = 'docs-canonical/API-REFERENCE.md';
@@ -86,15 +87,35 @@ export function findAllOpenApiSpecs(projectDir, config) {
     seenAbs.add(absPath);
     specs.push({
       absPath,
-      relPath: absPath.startsWith(resolve(projectDir))
-        ? absPath.slice(resolve(projectDir).length + 1)
-        : absPath,
+      relPath: relPosix(projectDir, absPath),
       endpoints: oa.endpoints.filter(e => e && e.method && e.path),
     });
   }
   return specs;
 }
 
+/**
+ * OpenAPI specs that exist and declare a `paths:` section but parsed to ZERO
+ * endpoints — i.e. DocGuard's minimal YAML/JSON parser couldn't extract them
+ * (an unsupported feature: `$ref`, anchors, folded scalars). These are silently
+ * skipped by findAllOpenApiSpecs (good — code scanning takes over), but the
+ * parse failure must be SURFACED so a broken spec doesn't masquerade as a
+ * clean "no API surface" pass. Returns relative spec paths.
+ */
+export function findUnparseableSpecs(projectDir, config) {
+  const out = [];
+  const seen = new Set();
+  for (const dir of orderedSpecDirs(projectDir, config)) {
+    const oa = detectOpenAPI(dir);
+    if (!oa.found || !oa.parseIncomplete) continue;
+    const abs = resolve(dir, oa.path);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(relPosix(projectDir, abs));
+  }
+  return out;
+}
+
 /**
  * Detect divergence between multiple canonical OpenAPI specs.
  * @returns {null | { specs, divergent: string[], authoritative: string }}
@@ -208,6 +229,19 @@ export function validateApiSurface(projectDir, config) {
     }
   }
 
+  // ── Honest-failure: an OpenAPI spec we couldn't parse ──
+  // A spec that declares paths but yielded zero endpoints means our parser
+  // choked on it. We fall back to code scanning (below), but the parse failure
+  // is surfaced here rather than silently producing a clean "no surface" pass.
+  for (const specPath of findUnparseableSpecs(projectDir, config)) {
+    warnings.push(
+      `OpenAPI spec ${specPath} declares paths but DocGuard parsed 0 endpoints from it ` +
+      `(likely an unsupported YAML feature — $ref, anchors, or folded scalars). ` +
+      `Falling back to code scanning; the spec's own endpoint list is unavailable. ` +
+      `Validate it with a full OpenAPI linter.`
+    );
+  }
+
   const drift = computeApiSurfaceDrift(projectDir, config);
 
   // ── Multi-spec divergence (independent of the API-REFERENCE doc) ──

package/cli/validators/canonical-sync.mjs

@@ -124,37 +124,40 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
     actualValidatorNames = guardResults.map(r => r.name).filter(Boolean);
   }
 
-  // ── Read README ─────────────────────────────────────────────────────
-  const readmePath = resolve(projectDir, 'README.md');
-  if (!existsSync(readmePath)) {
-    result.warnings.push('canonical-sync: README.md not found — cannot check surface claims');
-    result.total = 1;
-    return result;
+  // ── Read surface docs (README.md + AGENTS.md) ──────────────────────
+  // Both carry "N commands / N validators" surface claims. Scanning only the
+  // README is why AGENTS.md's counts ("Commands (15 total)", "24 validators")
+  // drifted unchecked for releases — close that gap by checking both.
+  const surfaceFiles = ['README.md', 'AGENTS.md'];
+  let readme = '';
+  let readAny = false;
+  for (const f of surfaceFiles) {
+    const p = resolve(projectDir, f);
+    if (!existsSync(p)) continue;
+    try { readme += readFileSync(p, 'utf-8') + '\n'; readAny = true; } catch { /* skip unreadable */ }
   }
-
-  let readme;
-  try {
-    readme = readFileSync(readmePath, 'utf-8');
-  } catch {
-    result.warnings.push('canonical-sync: README.md unreadable');
+  if (!readAny) {
+    result.warnings.push('canonical-sync: no README.md or AGENTS.md found — cannot check surface claims');
     result.total = 1;
     return result;
   }
 
   // ── Check 1: "ships N commands" ─────────────────────────────────────
+  // Check ALL claims (matchAll), not just the first: with README + AGENTS.md
+  // concatenated, a correct claim in one file must not mask a stale claim in
+  // the other (the same first-match-masking trap the secret scanner had).
   result.total++;
-  const shipsCommandsRe = /ships\s+\*{0,2}(\d+)\s+commands?\*{0,2}/i;
-  const m1 = readme.match(shipsCommandsRe);
-  if (m1) {
-    const claimed = Number(m1[1]);
-    if (claimed === actualCommandCount) {
+  const cmdMatches = [...readme.matchAll(/ships\s+\*{0,2}(\d+)\s+commands?\*{0,2}/gi)];
+  if (cmdMatches.length > 0) {
+    const wrong = [...new Set(cmdMatches.map(m => Number(m[1])).filter(n => n !== actualCommandCount))];
+    if (wrong.length === 0) {
       result.passed++;
     } else {
       const detail = actualUserFacingCount !== actualCommandFileCount
         ? `${actualCommandCount} user-facing commands in --help (${actualCommandFileCount} files including deprecation aliases)`
         : `${actualCommandCount} command file(s)`;
       result.warnings.push(
-        `README.md claims "ships ${claimed} commands" but the real count is ${detail}. Update the README.`
+        `A surface doc (README.md/AGENTS.md) claims ${wrong.map(n => `"ships ${n} commands"`).join(' / ')} but the real count is ${detail}. Update it.`
       );
     }
   } else {
@@ -177,7 +180,7 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
     } else {
       const uniqueWrong = [...new Set(wrongClaims)];
       result.warnings.push(
-        `README.md claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update the README.`
+        `A surface doc (README.md/AGENTS.md) claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update it.`
       );
     }
   } else {

package/cli/validators/doc-quality.mjs

@@ -16,14 +16,12 @@
  *   cells as "long sentences"), this version extracts ONLY actual prose
  *   paragraphs. Docs that are mostly tables/code skip readability scoring.
  *
- * Optional: If `understanding` CLI is installed, runs a full 31-metric deep scan.
- *
- * Zero NPM runtime dependencies — pure Node.js built-ins only.
+ * Zero NPM runtime dependencies, and zero process execution — pure Node.js
+ * built-ins reading files only.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { execSync, execFileSync } from 'node:child_process';
 
 // ──── Metric Thresholds ────
 // These define "good" vs "warning" boundaries for each metric.
@@ -441,40 +439,6 @@ function getGradeLabel(grade) {
   return 'graduate+';
 }
 
-// ──── Understanding CLI Integration ────
-
-/**
- * Check if the `understanding` CLI is available on the system.
- */
-function findUnderstandingCli() {
-  try {
-    const cmd = process.platform === 'win32' ? 'where understanding' : 'which understanding';
-    const result = execSync(`${cmd} 2>/dev/null`, {
-      encoding: 'utf-8',
-      timeout: 3000,
-    }).trim();
-    return result || null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Run the `understanding` CLI on a file and parse results.
- */
-function runUnderstandingDeepScan(filePath) {
-  try {
-    const result = execFileSync('understanding', ['analyze', filePath, '--enhanced', '--json'], {
-      encoding: 'utf-8',
-      timeout: 10000,
-      stdio: ['pipe', 'pipe', 'ignore'],
-    });
-    return JSON.parse(result);
-  } catch {
-    return null;
-  }
-}
-
 // ──── Main Validator ────
 
 /**
@@ -587,10 +551,6 @@ export function validateDocQuality(projectDir, config) {
     return results;
   }
 
-  // Check for optional understanding CLI
-  const understandingCli = findUnderstandingCli();
-  const useDeepScan = config.docQuality?.deepScan !== false && understandingCli;
-
   for (const doc of docs) {
     if (!existsSync(doc.path)) continue;
 

package/cli/validators/docs-coverage.mjs

@@ -35,8 +35,20 @@ const COMMON_DOTFILES = new Set([
   '.env', '.env.local', '.env.development', '.env.production',
   '.vscode', '.idea', '.github', '.husky',
   '.babelrc', '.browserslistrc', '.stylelintrc',
+  '.dockerignore', '.python-version', '.tool-versions', '.ruby-version',
+  '.gitkeep', '.keep',
 ]);
 
+// Generated tool artifacts (caches, coverage data, lock-data) that land at the
+// repo root but are NOT configuration a human authors or documents. Treating
+// them as "undocumented config files" is a false positive (field test:
+// quick-recon-tool flagged pytest's `.coverage` SQLite data file). Matched by
+// exact name OR prefix (`.coverage.<host>.<pid>` is coverage.py's parallel form).
+const GENERATED_DOTFILE_PREFIXES = ['.coverage', '.eslintcache', '.stylelintcache', '.tsbuildinfo'];
+function isGeneratedArtifact(name) {
+  return GENERATED_DOTFILE_PREFIXES.some(p => name === p || name.startsWith(p + '.'));
+}
+
 /**
  * Validate that code artifacts are referenced in documentation.
  * @param {string} projectDir - Project root directory
@@ -125,6 +137,7 @@ function checkConfigFiles(projectDir, allDocContent, config = {}) {
 
     if (!isDotFile && !isProjectConfig) continue;
     if (COMMON_DOTFILES.has(entry)) continue;
+    if (isGeneratedArtifact(entry)) continue;
     if (entry === 'tsconfig.json' || entry === 'package-lock.json') continue;
 
     // Skip directories — this check is for configuration FILES, not dirs.

package/cli/validators/docs-sync.mjs

@@ -5,6 +5,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
+import { relPosix } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
@@ -103,7 +104,7 @@ export function validateDocsSync(projectDir, config) {
       const ext = extname(file);
       if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
 
-      const relPath = file.replace(projectDir + '/', '');
+      const relPath = relPosix(projectDir, file);
       if (isTestFile(relPath)) continue;
       if (!isValidRouteFile(relPath)) continue;
       // N-1: skip files outside the --changed-only scope.
@@ -129,7 +130,7 @@ export function validateDocsSync(projectDir, config) {
       const ext = extname(file);
       if (!['.ts', '.tsx', '.js', '.jsx', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
 
-      const relPath = file.replace(projectDir + '/', '');
+      const relPath = relPosix(projectDir, file);
       if (isTestFile(relPath)) continue;
       // N-1: skip files outside the --changed-only scope.
       if (!inScope(relPath)) continue;
@@ -175,7 +176,7 @@ export function validateDocsSync(projectDir, config) {
         const ext = extname(file);
         if (!['.ts', '.tsx', '.js', '.jsx', '.mjs'].includes(ext)) continue;
 
-        const relPathForFilter = file.replace(projectDir + '/', '');
+        const relPathForFilter = relPosix(projectDir, file);
         if (isTestFile(relPathForFilter)) continue;
         if (!isValidRouteFile(relPathForFilter)) continue;
 

package/cli/validators/drift.mjs

@@ -4,6 +4,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
+import { relPosix } from '../shared-ignore.mjs';
 
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -31,7 +32,7 @@ export function validateDrift(projectDir, config) {
     // string fixtures (e.g. `'// DRIFT: a-drift\n'`). Reading the test as
     // source would treat the string as a real drift comment. Skip test
     // files unless the user opts in — same pattern TODO-Tracking uses.
-    const rel = filePath.replace(projectDir + '/', '');
+    const rel = relPosix(projectDir, filePath);
     const includeTests = config?.drift?.includeTestFiles === true;
     if (!includeTests && /(^|\/)(__tests__|tests?|spec)\/|\.(test|spec)\.[^.]+$/.test(rel)) {
       return;
@@ -44,7 +45,7 @@ export function validateDrift(projectDir, config) {
       const match = line.match(/(?:\/\/|#|\/\*|\-\-)\s*DRIFT:\s*(.+)/i);
       if (match) {
         driftComments.push({
-          file: filePath.replace(projectDir + '/', ''),
+          file: relPosix(projectDir, filePath),
           line: i + 1,
           comment: match[1].trim(),
         });