docguard-cli 0.9.11 → 0.11.0

package/cli/shared-source.mjs

@@ -0,0 +1,247 @@
+/**
+ * Shared Source Resolution — Monorepo-aware source discovery.
+ *
+ * Single source of truth for "where is the code?" so validators and
+ * scanners stop assuming a single package rooted at projectDir.
+ *
+ * Honors:
+ *   - config.sourceRoot           (string | string[], e.g. "backend/src")
+ *   - root package.json workspaces ("packages/*", { packages: [...] })
+ *   - pnpm-workspace.yaml          (packages:)
+ *   - turbo.json                   (presence → trust package.json workspaces)
+ *
+ * Zero NPM dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+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',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor', '.turbo',
+]);
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.java', '.go', '.rs', '.rb', '.php',
+]);
+
+/** Normalize config.sourceRoot into an array of relative paths. */
+function sourceRootList(config) {
+  const sr = config?.sourceRoot;
+  if (!sr) return [];
+  return Array.isArray(sr) ? sr : [sr];
+}
+
+function safeReadJson(path) {
+  try { return JSON.parse(readFileSync(path, '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
+ * expanded — explicit paths are returned as-is when they exist.
+ */
+function expandWorkspaceGlob(projectDir, pattern) {
+  const dirs = [];
+  if (pattern.endsWith('/*')) {
+    const base = resolve(projectDir, pattern.slice(0, -2));
+    if (existsSync(base)) {
+      let entries;
+      try { entries = readdirSync(base, { withFileTypes: true }); } catch { return dirs; }
+      for (const e of entries) {
+        if (!e.isDirectory() || IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+        const full = join(base, e.name);
+        if (existsSync(join(full, 'package.json'))) dirs.push(full);
+      }
+    }
+  } else {
+    const full = resolve(projectDir, pattern);
+    if (existsSync(full)) dirs.push(full);
+  }
+  return dirs;
+}
+
+/**
+ * Discover workspace package directories declared in the monorepo manifests.
+ * @returns {string[]} absolute directories
+ */
+export function getWorkspaceDirs(projectDir) {
+  const patterns = [];
+
+  // 1. root package.json "workspaces"
+  const rootPkg = safeReadJson(resolve(projectDir, 'package.json'));
+  if (rootPkg?.workspaces) {
+    const ws = Array.isArray(rootPkg.workspaces)
+      ? rootPkg.workspaces
+      : (rootPkg.workspaces.packages || []);
+    patterns.push(...ws);
+  }
+
+  // 2. pnpm-workspace.yaml — extract simple "  - 'packages/*'" entries
+  const pnpmPath = resolve(projectDir, 'pnpm-workspace.yaml');
+  if (existsSync(pnpmPath)) {
+    const content = readFileSync(pnpmPath, 'utf-8');
+    const re = /^\s*-\s*['"]?([^'"\n]+?)['"]?\s*$/gm;
+    let m;
+    let inPackages = false;
+    for (const line of content.split('\n')) {
+      if (/^packages:/.test(line.trim())) { inPackages = true; continue; }
+      if (inPackages) {
+        const mm = line.match(/^\s*-\s*['"]?([^'"\n]+?)['"]?\s*$/);
+        if (mm) patterns.push(mm[1]);
+        else if (line.trim() && !line.startsWith(' ')) inPackages = false;
+      }
+    }
+    void re; void m;
+  }
+
+  const dirs = new Set();
+  for (const p of patterns) {
+    for (const d of expandWorkspaceGlob(projectDir, p)) dirs.add(d);
+  }
+  return [...dirs];
+}
+
+/** Walk up from a directory to find the nearest enclosing package.json dir. */
+function nearestPackageDir(projectDir, startDir) {
+  let cur = startDir;
+  const root = resolve(projectDir);
+  while (cur && cur.startsWith(root)) {
+    if (existsSync(join(cur, 'package.json'))) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return null;
+}
+
+/**
+ * Resolve the set of directories that should be treated as source roots
+ * for scanning (routes, env usage, source files).
+ *
+ * Precedence: explicit config.sourceRoot → workspace packages → conventional
+ * roots that exist on disk. projectDir is always included as a fallback so
+ * single-package repos keep working.
+ *
+ * @returns {string[]} absolute directories, de-duplicated, existing only
+ */
+export function resolveSourceRoots(projectDir, config = {}) {
+  const out = new Set();
+  const add = (abs) => { if (abs && existsSync(abs)) out.add(abs); };
+
+  // 1. explicit sourceRoot(s)
+  for (const sr of sourceRootList(config)) add(resolve(projectDir, sr));
+
+  // 2. workspace package dirs
+  for (const d of getWorkspaceDirs(projectDir)) add(d);
+
+  // 3. conventional roots (only those that exist)
+  const conventional = ['src', 'app', 'lib', 'server', 'api', 'backend/src', 'backend', 'cli'];
+  for (const cr of conventional) add(resolve(projectDir, cr));
+
+  // 4. Fall back to the project root ONLY when nothing else resolved. Adding it
+  // unconditionally would pull in examples/, scripts/, and fixtures, producing
+  // false "in code" signals for env vars and routes.
+  if (out.size === 0) out.add(resolve(projectDir));
+
+  return [...out];
+}
+
+/**
+ * Collect every relevant package.json across the monorepo:
+ * root, the nearest package for each declared sourceRoot, and workspace packages.
+ * @returns {Array<{ dir: string, pkg: object }>}
+ */
+export function collectPackageJsons(projectDir, config = {}) {
+  const dirs = new Set([resolve(projectDir)]);
+
+  for (const sr of sourceRootList(config)) {
+    const npd = nearestPackageDir(projectDir, resolve(projectDir, sr));
+    if (npd) dirs.add(npd);
+  }
+  for (const d of getWorkspaceDirs(projectDir)) dirs.add(d);
+
+  const result = [];
+  for (const dir of dirs) {
+    const pkg = safeReadJson(join(dir, 'package.json'));
+    if (pkg) result.push({ dir, pkg });
+  }
+  return result;
+}
+
+/** Detect whether the project ships a Docker setup. */
+export function detectDocker(projectDir, config = {}) {
+  const candidates = ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml', '.dockerignore'];
+  const root = resolve(projectDir);
+  const dirs = new Set([root]);
+
+  // Walk every ancestor from each sourceRoot up to the project root — a
+  // Dockerfile commonly sits at the package root (e.g. backend/Dockerfile).
+  for (const sr of sourceRootList(config)) {
+    let cur = resolve(projectDir, sr);
+    while (cur && cur.startsWith(root)) {
+      dirs.add(cur);
+      const parent = dirname(cur);
+      if (parent === cur) break;
+      cur = parent;
+    }
+  }
+  for (const d of getWorkspaceDirs(projectDir)) dirs.add(d);
+
+  for (const dir of dirs) {
+    for (const f of candidates) {
+      if (existsSync(join(dir, f))) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Grep source files under the resolved source roots for environment variable
+ * usage in both the Node (process dot env) and Vite (import meta env) styles,
+ * including bracket access.
+ * @returns {Set<string>} variable names referenced in code
+ */
+export function grepEnvUsage(projectDir, config = {}) {
+  const names = new Set();
+  const roots = resolveSourceRoots(projectDir, config);
+  const seen = new Set();
+
+  const patterns = [
+    /process\.env\.([A-Z][A-Z0-9_]+)/g,
+    /process\.env\[\s*['"]([A-Z][A-Z0-9_]+)['"]\s*\]/g,
+    /import\.meta\.env\.([A-Z][A-Z0-9_]+)/g,
+  ];
+
+  const visit = (filePath) => {
+    if (seen.has(filePath)) return;
+    seen.add(filePath);
+    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; }
+    if (!content.includes('env')) return;
+    for (const re of patterns) {
+      let m;
+      const rx = new RegExp(re.source, 'g');
+      while ((m = rx.exec(content)) !== null) names.add(m[1]);
+    }
+  };
+
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile()) visit(full);
+    }
+  };
+
+  for (const root of roots) walk(root);
+  return names;
+}

package/cli/validators/api-surface.mjs

@@ -0,0 +1,254 @@
+/**
+ * API-Surface Validator — Detects drift between the documented API surface
+ * (docs-canonical/API-REFERENCE.md) and the project's actual API surface.
+ *
+ * This is the check that catches a deleted endpoint still being documented —
+ * the exact class of drift DocGuard exists to prevent.
+ *
+ * Actual surface, in order of confidence:
+ *   1. OpenAPI spec (sourceRoot/workspace-aware)  → high confidence
+ *   2. Monorepo-aware code route scan             → lower confidence (warn only)
+ *
+ * Severity policy:
+ *   - documented-but-absent  → ERROR when confirmed by an OpenAPI spec
+ *                              (docs lie about a real endpoint → fail the build);
+ *                              downgraded to WARNING on heuristic code-scan only.
+ *   - present-but-undocumented → WARNING (a real route missing from the docs).
+ *
+ * Also flags MULTIPLE OpenAPI specs in the repo that disagree on their endpoint
+ * set (e.g. a served spec and a generated spec that have diverged).
+ *
+ * Returns { errors, warnings, passed, total, fixes, authoritativeSpec } — the
+ * `fixes` array lists deterministic remove-endpoint actions that
+ * `docguard fix --write` can apply without an LLM.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+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';
+
+const MAX_REPORTED = 15;
+const API_DOC = 'docs-canonical/API-REFERENCE.md';
+
+/** Walk up from a dir to the nearest enclosing package.json directory. */
+function nearestPackageDir(projectDir, startDir) {
+  let cur = startDir;
+  const root = resolve(projectDir);
+  while (cur && cur.startsWith(root)) {
+    if (existsSync(join(cur, 'package.json'))) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return null;
+}
+
+/**
+ * Build an ordered list of directories to search for an OpenAPI spec.
+ * The spec under the configured sourceRoot's package takes precedence over a
+ * (possibly stale) copy at the repo root — monorepos frequently keep a
+ * divergent root copy. Only CANONICAL bases are searched (sourceRoot package,
+ * workspaces, repo root) — never worktrees / vendor / scan-tool dirs.
+ */
+function orderedSpecDirs(projectDir, config) {
+  const ordered = [];
+  const seen = new Set();
+  const add = (d) => { if (d && !seen.has(d)) { seen.add(d); ordered.push(d); } };
+
+  const srList = config?.sourceRoot
+    ? (Array.isArray(config.sourceRoot) ? config.sourceRoot : [config.sourceRoot])
+    : [];
+  for (const sr of srList) {
+    const abs = resolve(projectDir, sr);
+    add(nearestPackageDir(projectDir, abs));
+    add(abs);
+  }
+  for (const d of getWorkspaceDirs(projectDir)) add(d);
+  add(resolve(projectDir)); // root copy last — lowest priority
+  return ordered;
+}
+
+/**
+ * Enumerate every OpenAPI spec found in a canonical location, in priority order.
+ * @returns {Array<{ absPath: string, relPath: string, endpoints: object[] }>}
+ */
+export function findAllOpenApiSpecs(projectDir, config) {
+  const specs = [];
+  const seenAbs = new Set();
+  for (const dir of orderedSpecDirs(projectDir, config)) {
+    const oa = detectOpenAPI(dir);
+    if (!oa.found || !oa.endpoints?.length) continue;
+    const absPath = resolve(dir, oa.path);
+    if (seenAbs.has(absPath)) continue;
+    seenAbs.add(absPath);
+    specs.push({
+      absPath,
+      relPath: absPath.startsWith(resolve(projectDir))
+        ? absPath.slice(resolve(projectDir).length + 1)
+        : absPath,
+      endpoints: oa.endpoints.filter(e => e && e.method && e.path),
+    });
+  }
+  return specs;
+}
+
+/**
+ * Detect divergence between multiple canonical OpenAPI specs.
+ * @returns {null | { specs, divergent: string[], authoritative: string }}
+ */
+export function detectSpecDivergence(projectDir, config) {
+  const specs = findAllOpenApiSpecs(projectDir, config);
+  if (specs.length < 2) return null;
+
+  const keySets = specs.map(s => new Set(s.endpoints.map(e => endpointKey(e.method, e.path))));
+  // Union and symmetric difference across all specs.
+  const union = new Set();
+  for (const ks of keySets) for (const k of ks) union.add(k);
+  const divergent = [...union].filter(k => !keySets.every(ks => ks.has(k)));
+
+  if (divergent.length === 0) return null;
+  return { specs, divergent, authoritative: specs[0].relPath };
+}
+
+function detectFramework(projectDir, config) {
+  const deps = {};
+  for (const { pkg } of collectPackageJsons(projectDir, config)) {
+    Object.assign(deps, pkg.dependencies || {}, pkg.devDependencies || {});
+  }
+  if (deps.next) return 'Next.js';
+  if (deps.express) return 'Express';
+  if (deps.fastify) return 'Fastify';
+  if (deps.hono) return 'Hono';
+  return '';
+}
+
+/**
+ * Resolve the actual API surface.
+ * @returns {{ endpoints: Array<{method,path}>, confidence: 'spec'|'code'|'none', source: string }}
+ */
+export function resolveApiSurface(projectDir, config) {
+  const specs = findAllOpenApiSpecs(projectDir, config);
+  if (specs.length > 0) {
+    const spec = specs[0]; // highest priority (sourceRoot first, root last)
+    return {
+      endpoints: spec.endpoints.map(e => ({ method: e.method, path: e.path })),
+      confidence: 'spec',
+      source: spec.relPath,
+    };
+  }
+
+  // Fallback: monorepo-aware code route scan
+  const framework = detectFramework(projectDir, config);
+  const routes = scanRoutesDeep(projectDir, { framework }, { openapi: { found: false } }, { config });
+  if (routes.length) {
+    return {
+      endpoints: routes.map(r => ({ method: r.method, path: r.path })),
+      confidence: 'code',
+      source: 'code-scan',
+    };
+  }
+
+  return { endpoints: [], confidence: 'none', source: null };
+}
+
+/**
+ * Compute API-surface drift in a structured, reusable form.
+ * Used by the validator AND by `docguard fix --write`.
+ * @returns {{ applicable, confidence, source, documented, documentedButAbsent,
+ *             presentButUndocumented, matched }}
+ */
+export function computeApiSurfaceDrift(projectDir, config) {
+  const apiDocPath = resolve(projectDir, API_DOC);
+  if (!existsSync(apiDocPath)) {
+    return { applicable: false, confidence: 'none', source: null,
+      documented: [], documentedButAbsent: [], presentButUndocumented: [], matched: [] };
+  }
+
+  const documented = parseApiReferenceDoc(readFileSync(apiDocPath, 'utf-8'));
+  const surface = resolveApiSurface(projectDir, config);
+
+  if (surface.confidence === 'none' || documented.length === 0) {
+    return { applicable: false, confidence: surface.confidence, source: surface.source,
+      documented, documentedButAbsent: [], presentButUndocumented: [], matched: [] };
+  }
+
+  const cmp = compareEndpoints(documented, surface.endpoints);
+  return {
+    applicable: true,
+    confidence: surface.confidence,
+    source: surface.source,
+    documented,
+    documentedButAbsent: cmp.documentedButAbsent,
+    presentButUndocumented: cmp.presentButUndocumented,
+    matched: cmp.matched,
+  };
+}
+
+export function validateApiSurface(projectDir, config) {
+  const errors = [];
+  const warnings = [];
+  const fixes = [];
+
+  const drift = computeApiSurfaceDrift(projectDir, config);
+
+  // ── Multi-spec divergence (independent of the API-REFERENCE doc) ──
+  const divergence = detectSpecDivergence(projectDir, config);
+  if (divergence) {
+    const others = divergence.specs.slice(1).map(s => s.relPath).join(', ');
+    const sample = divergence.divergent.slice(0, 8).join(', ');
+    const more = divergence.divergent.length > 8 ? ` (+${divergence.divergent.length - 8} more)` : '';
+    warnings.push(
+      `Multiple OpenAPI specs disagree on ${divergence.divergent.length} endpoint(s): ` +
+      `${divergence.authoritative} (treated as authoritative) vs ${others}. Divergent: ${sample}${more}`
+    );
+  }
+
+  if (!drift.applicable) {
+    // Nothing to validate against the API-REFERENCE doc.
+    return { errors, warnings, passed: 0, total: 0, fixes, authoritativeSpec: drift.source };
+  }
+
+  const { documentedButAbsent, presentButUndocumented, matched, confidence, source } = drift;
+  const total = matched.length + documentedButAbsent.length + presentButUndocumented.length;
+  const passed = matched.length;
+
+  const trim = (arr) => {
+    const shown = arr.slice(0, MAX_REPORTED);
+    return { shown, extra: arr.length - shown.length };
+  };
+
+  // documented-but-absent → deterministic remove-endpoint fixes
+  if (documentedButAbsent.length) {
+    const { shown, extra } = trim(documentedButAbsent);
+    for (const e of shown) {
+      const msg = `Documented endpoint not found in code: ${e.method} ${e.path} (${API_DOC})`;
+      if (confidence === 'spec') errors.push(msg);
+      else warnings.push(`${msg} [code-scan — verify]`);
+    }
+    if (extra > 0) {
+      const tail = `…and ${extra} more documented endpoint(s) not found in code`;
+      if (confidence === 'spec') errors.push(tail);
+      else warnings.push(tail);
+    }
+    // Only spec-confirmed absences are safe to auto-remove.
+    if (confidence === 'spec') {
+      for (const e of documentedButAbsent) {
+        fixes.push({ type: 'remove-endpoint', method: e.method, path: e.path, doc: API_DOC });
+      }
+    }
+  }
+
+  // present-but-undocumented → warning (NOT auto-applied; needs a real block)
+  if (presentButUndocumented.length) {
+    const { shown, extra } = trim(presentButUndocumented);
+    for (const e of shown) {
+      warnings.push(`Undocumented endpoint in code: ${e.method} ${e.path} — add it to ${API_DOC}`);
+    }
+    if (extra > 0) warnings.push(`…and ${extra} more undocumented endpoint(s) in code`);
+  }
+
+  return { errors, warnings, passed, total, fixes, authoritativeSpec: source };
+}

package/cli/validators/architecture.mjs

@@ -58,10 +58,11 @@ export function validateArchitecture(projectDir, config) {
     }
   }
 
-  // ── 5. Report import stats ──
+  // ── 5. No boundaries declared and no circular deps to check → not applicable.
+  // (Previously this returned a fake 1/1 pass, rendering a confident green ✅
+  // for projects that declared no layer boundaries — it validated nothing.)
   if (results.total === 0) {
-    results.total = 1;
-    results.passed = 1;
+    results.note = 'no layer boundaries declared in ARCHITECTURE.md';
   }
 
   return results;

package/cli/validators/changelog.mjs

@@ -1,12 +1,31 @@
 /**
- * Changelog Validator — Checks CHANGELOG.md has [Unreleased] section
+ * Changelog Validator — Checks CHANGELOG.md has an [Unreleased] section,
+ * follows Keep a Changelog format, and (per STANDARD.md) that staged code
+ * changes are accompanied by a CHANGELOG update.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { resolve, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const CODE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|cs|kt|swift)$/;
+
+/** Return staged file paths (relative to repo root), or null if git is unavailable. */
+function getStagedFiles(projectDir) {
+  try {
+    const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
+      cwd: projectDir,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.split('\n').map(s => s.trim()).filter(Boolean);
+  } catch {
+    return null; // not a git repo, or git not installed
+  }
+}
 
 export function validateChangelog(projectDir, config) {
-  const results = { name: 'changelog', errors: [], warnings: [], passed: 0, total: 0 };
+  const results = { name: 'changelog', errors: [], warnings: [], passed: 0, total: 0, fixes: [] };
 
   const changelogPath = resolve(projectDir, config.requiredFiles.changelog);
   if (!existsSync(changelogPath)) {
@@ -21,7 +40,8 @@ export function validateChangelog(projectDir, config) {
   if (content.includes('[Unreleased]') || content.includes('[unreleased]')) {
     results.passed++;
   } else {
-    results.warnings.push('CHANGELOG.md: missing [Unreleased] section');
+    results.warnings.push('CHANGELOG.md: missing [Unreleased] section — fix with `docguard fix --write`');
+    results.fixes.push({ type: 'insert-changelog-unreleased', file: config.requiredFiles.changelog });
   }
 
   // Check it follows Keep a Changelog format (at least has ## headers)
@@ -35,5 +55,26 @@ export function validateChangelog(projectDir, config) {
     );
   }
 
+  // Per STANDARD.md: if there are staged CODE changes, CHANGELOG.md should be
+  // updated in the same commit. Only assessed when git is available AND there
+  // are staged code changes (otherwise the check is not applicable).
+  const staged = getStagedFiles(projectDir);
+  if (staged && staged.length > 0) {
+    const changelogName = basename(config.requiredFiles.changelog);
+    const stagedCode = staged.filter(f => CODE_EXT_RE.test(f));
+    const changelogStaged = staged.some(f => basename(f) === changelogName);
+
+    if (stagedCode.length > 0) {
+      results.total++;
+      if (changelogStaged) {
+        results.passed++;
+      } else {
+        results.warnings.push(
+          `${stagedCode.length} code file(s) staged but ${changelogName} is not — add a CHANGELOG entry for this change`
+        );
+      }
+    }
+  }
+
   return results;
 }

package/cli/validators/doc-quality.mjs

@@ -23,7 +23,7 @@
 
 import { existsSync, readFileSync, 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';
 
 // ──── Metric Thresholds ────
 // These define "good" vs "warning" boundaries for each metric.
@@ -464,9 +464,10 @@ function findUnderstandingCli() {
  */
 function runUnderstandingDeepScan(filePath) {
   try {
-    const result = execSync(`understanding analyze "${filePath}" --enhanced --json 2>/dev/null`, {
+    const result = execFileSync('understanding', ['analyze', filePath, '--enhanced', '--json'], {
       encoding: 'utf-8',
       timeout: 10000,
+      stdio: ['pipe', 'pipe', 'ignore'],
     });
     return JSON.parse(result);
   } catch {

package/cli/validators/docs-coverage.mjs

@@ -15,6 +15,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
+import { resolveSourceRoots } from '../shared-source.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -62,13 +63,13 @@ export function validateDocsCoverage(projectDir, config) {
   warnings.push(...binChecks.warnings);
 
   // ── Check 3: Source directory structure matches ARCHITECTURE.md ──
-  const dirChecks = checkSourceDirs(projectDir, allDocContent);
+  const dirChecks = checkSourceDirs(projectDir, allDocContent, config);
   total += dirChecks.total;
   passed += dirChecks.passed;
   warnings.push(...dirChecks.warnings);
 
   // ── Check 4: Config filenames referenced in source code but not documented ──
-  const codeConfigChecks = checkCodeReferencedConfigs(projectDir, allDocContent);
+  const codeConfigChecks = checkCodeReferencedConfigs(projectDir, allDocContent, config);
   total += codeConfigChecks.total;
   passed += codeConfigChecks.passed;
   warnings.push(...codeConfigChecks.warnings);
@@ -160,7 +161,7 @@ function checkPackageBins(projectDir, allDocContent) {
 /**
  * Check 3: Source directories are referenced in ARCHITECTURE.md.
  */
-function checkSourceDirs(projectDir, allDocContent) {
+function checkSourceDirs(projectDir, allDocContent, config = {}) {
   const warnings = [];
   let passed = 0;
   let total = 0;
@@ -172,12 +173,10 @@ function checkSourceDirs(projectDir, allDocContent) {
   try { archContent = readFileSync(archPath, 'utf-8'); } catch { return { warnings, passed, total }; }
 
   const lowerArchContent = archContent.toLowerCase();
-  const sourceRoots = ['src', 'lib', 'app', 'cli', 'server', 'api'];
-
-  for (const root of sourceRoots) {
-    const rootDir = resolve(projectDir, root);
-    if (!existsSync(rootDir)) continue;
 
+  // Monorepo-aware: honor config.sourceRoot + workspaces instead of a hardcoded list.
+  for (const rootDir of resolveSourceRoots(projectDir, config)) {
+    const root = relative(projectDir, rootDir) || basename(rootDir);
     let entries;
     try { entries = readdirSync(rootDir); } catch { continue; }
 
@@ -212,7 +211,7 @@ function checkSourceDirs(projectDir, allDocContent) {
  * patterns — these are configs the project USES. Avoids matching config names
  * sitting in arrays (scan patterns for detecting other projects' configs).
  */
-function checkCodeReferencedConfigs(projectDir, allDocContent) {
+function checkCodeReferencedConfigs(projectDir, allDocContent, config = {}) {
   const warnings = [];
   let passed = 0;
   let total = 0;
@@ -224,8 +223,6 @@ function checkCodeReferencedConfigs(projectDir, allDocContent) {
   // resolve(dir, '.docguardignore'), existsSync('.env.example'), readFileSync('vitest.config.ts')
   const usageRegex = /(?:resolve|join|existsSync|readFileSync|accessSync|writeFileSync)\s*\([^)]*['"`]([^'"`\n]{2,})['"`]/g;
 
-  const sourceRoots = ['src', 'lib', 'cli', 'bin', 'server', 'api', 'app'];
-
   const scanFile = (filePath) => {
     const ext = extname(filePath);
     if (!['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) return;
@@ -247,9 +244,7 @@ function checkCodeReferencedConfigs(projectDir, allDocContent) {
     }
   };
 
-  for (const root of sourceRoots) {
-    const rootDir = resolve(projectDir, root);
-    if (!existsSync(rootDir)) continue;
+  for (const rootDir of resolveSourceRoots(projectDir, config)) {
     walkFiles(rootDir, scanFile);
   }