docguard-cli 0.5.1

package/cli/validators/architecture.mjs

@@ -0,0 +1,380 @@
+/**
+ * Architecture Validator — Enhanced with automatic import analysis
+ * 
+ * Two modes:
+ * 1. Config-driven: Uses `layers` from .docguard.json (existing behavior)
+ * 2. Auto-detect: Scans ARCHITECTURE.md for layer boundary declarations,
+ *    then validates imports across the codebase.
+ * 
+ * Import violations detected:
+ * - Circular dependencies (A → B → A)
+ * - Layer boundary violations (routes importing from routes, etc.)
+ * - Orphan modules (code files with 0 inbound imports)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname, relative, dirname, basename } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+  'templates', 'configs', 'Research', 'docs-canonical', 'docs-implementation',
+]);
+
+const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.jsx']);
+
+export function validateArchitecture(projectDir, config) {
+  const results = { name: 'architecture', errors: [], warnings: [], passed: 0, total: 0 };
+
+  // ── 1. Config-driven layer validation ──
+  const layers = config.layers;
+  if (layers && Object.keys(layers).length > 0) {
+    validateConfigLayers(projectDir, config, layers, results);
+  }
+
+  // ── 2. Auto-detect import graph ──
+  const importGraph = buildImportGraph(projectDir);
+  if (importGraph.files.length === 0) return results;
+
+  // ── 3. Detect circular dependencies ──
+  const circles = detectCircularDeps(importGraph);
+  for (const circle of circles) {
+    results.total++;
+    results.warnings.push(`Circular dependency: ${circle.join(' → ')}`);
+  }
+
+  // ── 4. Check layer boundaries from ARCHITECTURE.md ──
+  const archPath = resolve(projectDir, 'docs-canonical/ARCHITECTURE.md');
+  if (existsSync(archPath)) {
+    const archContent = readFileSync(archPath, 'utf-8');
+    const declaredLayers = parseLayerBoundaries(archContent);
+
+    if (declaredLayers.length > 0) {
+      validateLayerBoundaries(projectDir, importGraph, declaredLayers, results);
+    }
+  }
+
+  // ── 5. Report import stats ──
+  if (results.total === 0) {
+    results.total = 1;
+    results.passed = 1;
+  }
+
+  return results;
+}
+
+// ── Config-driven validation (existing behavior) ────────────────────────────
+
+function validateConfigLayers(projectDir, config, layers, results) {
+  const layerMap = {};
+  for (const [layerName, layerConfig] of Object.entries(layers)) {
+    if (layerConfig.dir && layerConfig.canImport) {
+      layerMap[layerConfig.dir] = {
+        name: layerName,
+        canImport: layerConfig.canImport,
+        forbidden: Object.entries(layers)
+          .filter(([name]) => !layerConfig.canImport.includes(name) && name !== layerName)
+          .map(([, cfg]) => cfg.dir)
+          .filter(Boolean),
+      };
+    }
+  }
+
+  for (const [dir, layer] of Object.entries(layerMap)) {
+    const layerDir = resolve(projectDir, dir);
+    if (!existsSync(layerDir)) continue;
+
+    const files = getFilesRecursive(layerDir);
+    for (const file of files) {
+      if (!CODE_EXTENSIONS.has(extname(file))) continue;
+
+      const content = readFileSync(file, 'utf-8');
+      const relPath = relative(projectDir, file);
+      const imports = extractImports(content);
+
+      for (const imp of imports) {
+        if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+
+        for (const forbiddenDir of layer.forbidden) {
+          if (imp.includes(forbiddenDir) || imp.includes(`/${forbiddenDir}/`)) {
+            results.total++;
+            results.errors.push(
+              `${relPath}: ${layer.name} layer imports from forbidden layer (${forbiddenDir})`
+            );
+          }
+        }
+      }
+    }
+  }
+}
+
+// ── Import Graph Builder ────────────────────────────────────────────────────
+
+function buildImportGraph(projectDir) {
+  const graph = { files: [], edges: [], fileMap: new Map() };
+
+  const allFiles = getFilesRecursive(projectDir);
+  const codeFiles = allFiles.filter(f => CODE_EXTENSIONS.has(extname(f)));
+
+  for (const file of codeFiles) {
+    const relPath = relative(projectDir, file);
+    graph.files.push(relPath);
+
+    try {
+      const content = readFileSync(file, 'utf-8');
+      const imports = extractImports(content);
+
+      const resolvedImports = [];
+      for (const imp of imports) {
+        if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+
+        // Resolve relative imports
+        const fromDir = dirname(file);
+        const resolved = resolveImport(fromDir, imp, projectDir);
+        if (resolved) {
+          resolvedImports.push(resolved);
+          graph.edges.push({ from: relPath, to: resolved });
+        }
+      }
+
+      graph.fileMap.set(relPath, resolvedImports);
+    } catch { /* skip binary or unreadable files */ }
+  }
+
+  return graph;
+}
+
+function extractImports(content) {
+  const imports = [];
+
+  // ES module imports
+  const esImportRegex = /import\s+(?:.*?\s+from\s+)?['"]([^'"]+)['"]/g;
+  let match;
+  while ((match = esImportRegex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  // Dynamic imports
+  const dynamicRegex = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  while ((match = dynamicRegex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  // CommonJS require
+  const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  while ((match = requireRegex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  return imports;
+}
+
+function resolveImport(fromDir, importPath, projectDir) {
+  // Try to resolve the import to an actual file
+  const extensions = ['.ts', '.tsx', '.js', '.mjs', '.jsx', '.cjs'];
+  const basePath = resolve(fromDir, importPath);
+
+  // Direct file match
+  for (const ext of extensions) {
+    const candidate = basePath + ext;
+    if (existsSync(candidate)) {
+      return relative(projectDir, candidate);
+    }
+  }
+
+  // Exact match (has extension already)
+  if (existsSync(basePath)) {
+    return relative(projectDir, basePath);
+  }
+
+  // Index file match
+  for (const ext of extensions) {
+    const candidate = join(basePath, `index${ext}`);
+    if (existsSync(candidate)) {
+      return relative(projectDir, candidate);
+    }
+  }
+
+  return null;
+}
+
+// ── Circular Dependency Detection ───────────────────────────────────────────
+
+function detectCircularDeps(graph) {
+  const circles = [];
+  const visited = new Set();
+  const inStack = new Set();
+
+  function dfs(file, path) {
+    if (inStack.has(file)) {
+      // Found a cycle — extract just the cycle portion
+      const cycleStart = path.indexOf(file);
+      if (cycleStart !== -1) {
+        const cycle = path.slice(cycleStart);
+        cycle.push(file); // complete the circle
+        // Only report cycles of 2-5 files to avoid noise
+        if (cycle.length >= 3 && cycle.length <= 6) {
+          circles.push(cycle);
+        }
+      }
+      return;
+    }
+    if (visited.has(file)) return;
+
+    visited.add(file);
+    inStack.add(file);
+
+    const deps = graph.fileMap.get(file) || [];
+    for (const dep of deps) {
+      dfs(dep, [...path, file]);
+    }
+
+    inStack.delete(file);
+  }
+
+  for (const file of graph.files) {
+    if (!visited.has(file)) {
+      dfs(file, []);
+    }
+  }
+
+  // Deduplicate cycles (same cycle can be detected starting from different nodes)
+  const seen = new Set();
+  return circles.filter(cycle => {
+    const key = [...cycle].sort().join('|');
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+// ── Layer Boundary Parser ───────────────────────────────────────────────────
+
+function parseLayerBoundaries(archContent) {
+  const layers = [];
+
+  // Parse "Layer Boundaries" table from ARCHITECTURE.md
+  const tableRegex = /\|\s*(\S+)\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|/g;
+  let match;
+  let inBoundarySection = false;
+
+  const lines = archContent.split('\n');
+  for (const line of lines) {
+    if (line.includes('Layer Boundaries') || line.includes('layer boundaries')) {
+      inBoundarySection = true;
+      continue;
+    }
+    if (inBoundarySection && line.startsWith('## ')) {
+      break; // next section
+    }
+    if (!inBoundarySection) continue;
+    if (line.includes('---') || line.includes('Layer') && line.includes('Can Import')) continue;
+
+    match = line.match(/\|\s*(\S+)\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|/);
+    if (match) {
+      const layerName = match[1].replace(/[`*]/g, '').toLowerCase();
+      const canImport = match[2].trim().split(',').map(s => s.trim().replace(/[`*]/g, '').toLowerCase());
+      const cannotImport = match[3].trim().split(',').map(s => s.trim().replace(/[`*]/g, '').toLowerCase());
+
+      // Skip markdown noise
+      if (layerName === '<!--' || layerName === 'layer' || layerName.length < 2) continue;
+
+      layers.push({ name: layerName, canImport, cannotImport });
+    }
+  }
+
+  return layers;
+}
+
+function validateLayerBoundaries(projectDir, graph, declaredLayers, results) {
+  // Map directory patterns to layer names
+  const layerDirMap = new Map();
+  for (const layer of declaredLayers) {
+    // Common directory mappings
+    const dirPatterns = getLayerDirPatterns(layer.name);
+    for (const pattern of dirPatterns) {
+      layerDirMap.set(pattern, layer);
+    }
+  }
+
+  // Check each import edge
+  for (const edge of graph.edges) {
+    const fromLayer = getFileLayer(edge.from, layerDirMap);
+    const toLayer = getFileLayer(edge.to, layerDirMap);
+
+    if (!fromLayer || !toLayer || fromLayer.name === toLayer.name) continue;
+
+    // Check if this import is forbidden
+    if (fromLayer.cannotImport.some(l => l.includes(toLayer.name) || toLayer.name.includes(l))) {
+      results.total++;
+      results.errors.push(
+        `${edge.from}: ${fromLayer.name} → ${toLayer.name} (forbidden by ARCHITECTURE.md)`
+      );
+    } else {
+      results.total++;
+      results.passed++;
+    }
+  }
+}
+
+function getLayerDirPatterns(layerName) {
+  const patterns = [];
+  const clean = layerName.replace(/\//g, '').replace(/\s/g, '').toLowerCase();
+
+  // Standard patterns
+  patterns.push(clean);
+  patterns.push(`src/${clean}`);
+
+  // Common aliases
+  const aliases = {
+    routes: ['routes', 'src/routes', 'src/app/api', 'api', 'handlers'],
+    handlers: ['routes', 'src/routes', 'handlers'],
+    services: ['services', 'src/services', 'src/lib'],
+    models: ['models', 'src/models', 'entities', 'schema'],
+    repositories: ['repositories', 'src/repositories', 'models', 'data'],
+    middleware: ['middleware', 'src/middleware'],
+    utils: ['utils', 'src/utils', 'helpers', 'src/helpers', 'lib'],
+    components: ['components', 'src/components', 'ui'],
+  };
+
+  if (aliases[clean]) {
+    patterns.push(...aliases[clean]);
+  }
+
+  return patterns;
+}
+
+function getFileLayer(filePath, layerDirMap) {
+  for (const [pattern, layer] of layerDirMap) {
+    if (filePath.startsWith(pattern + '/') || filePath.includes('/' + pattern + '/')) {
+      return layer;
+    }
+  }
+  return null;
+}
+
+// ── Utilities ───────────────────────────────────────────────────────────────
+
+function getFilesRecursive(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch { return results; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
+    const fullPath = join(dir, entry);
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        results.push(...getFilesRecursive(fullPath));
+      } else {
+        results.push(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+  return results;
+}

package/cli/validators/changelog.mjs

@@ -0,0 +1,39 @@
+/**
+ * Changelog Validator — Checks CHANGELOG.md has [Unreleased] section
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export function validateChangelog(projectDir, config) {
+  const results = { name: 'changelog', errors: [], warnings: [], passed: 0, total: 0 };
+
+  const changelogPath = resolve(projectDir, config.requiredFiles.changelog);
+  if (!existsSync(changelogPath)) {
+    // Structure validator catches missing files
+    return results;
+  }
+
+  const content = readFileSync(changelogPath, 'utf-8');
+
+  // Check for [Unreleased] section
+  results.total++;
+  if (content.includes('[Unreleased]') || content.includes('[unreleased]')) {
+    results.passed++;
+  } else {
+    results.warnings.push('CHANGELOG.md: missing [Unreleased] section');
+  }
+
+  // Check it follows Keep a Changelog format (at least has ## headers)
+  results.total++;
+  const hasVersionHeaders = /^## \[/m.test(content);
+  if (hasVersionHeaders) {
+    results.passed++;
+  } else {
+    results.warnings.push(
+      'CHANGELOG.md: no version sections found (expected ## [version] format)'
+    );
+  }
+
+  return results;
+}

package/cli/validators/docs-sync.mjs

@@ -0,0 +1,110 @@
+/**
+ * Docs-Sync Validator — Checks that source files have matching canonical doc entries
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname, basename } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+]);
+
+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 = '';
+  if (existsSync(canonicalDir)) {
+    try {
+      const files = readdirSync(canonicalDir).filter(f => f.endsWith('.md'));
+      for (const f of files) {
+        canonicalContent += readFileSync(resolve(canonicalDir, f), 'utf-8') + '\n';
+      }
+    } catch {
+      // Skip if can't read
+    }
+  }
+
+  if (!canonicalContent) {
+    return results; // No canonical docs to check against
+  }
+
+  for (const { dir, label } of routePatterns) {
+    const routeDir = resolve(projectDir, dir);
+    if (!existsSync(routeDir)) continue;
+
+    const files = getFilesRecursive(routeDir);
+    for (const file of files) {
+      const ext = extname(file);
+      if (!['.ts', '.js', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
+
+      results.total++;
+      const relPath = file.replace(projectDir + '/', '');
+      const name = basename(file, ext);
+
+      // Check if the file path or name is mentioned in any canonical doc
+      if (canonicalContent.includes(relPath) || canonicalContent.includes(name)) {
+        results.passed++;
+      } else {
+        results.warnings.push(`${label} ${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;
+
+    const files = getFilesRecursive(serviceDir);
+    for (const file of files) {
+      const ext = extname(file);
+      if (!['.ts', '.js', '.mjs', '.py', '.java', '.go'].includes(ext)) continue;
+
+      results.total++;
+      const relPath = file.replace(projectDir + '/', '');
+      const name = basename(file, ext);
+
+      if (canonicalContent.includes(relPath) || canonicalContent.includes(name)) {
+        results.passed++;
+      } else {
+        results.warnings.push(`Service ${relPath} not referenced in any canonical doc`);
+      }
+    }
+  }
+
+  return results;
+}
+
+function getFilesRecursive(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+
+  const entries = readdirSync(dir);
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
+    const fullPath = join(dir, entry);
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        results.push(...getFilesRecursive(fullPath));
+      } else {
+        results.push(fullPath);
+      }
+    } catch {
+      // Skip
+    }
+  }
+  return results;
+}

package/cli/validators/drift.mjs

@@ -0,0 +1,101 @@
+/**
+ * Drift Validator — Every // DRIFT: comment must have a DRIFT-LOG.md entry
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname } from 'node:path';
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.java', '.go', '.rs', '.swift', '.kt',
+  '.rb', '.php', '.cs', '.c', '.cpp', '.h',
+]);
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+  'cli', // Exclude DocGuard's own source (contains DRIFT: in regex patterns)
+]);
+
+export function validateDrift(projectDir, config) {
+  const results = { name: 'drift', errors: [], warnings: [], passed: 0, total: 0 };
+
+  // Find all // DRIFT: comments in source code
+  const driftComments = [];
+  walkDir(projectDir, (filePath) => {
+    const ext = extname(filePath);
+    if (!CODE_EXTENSIONS.has(ext)) return;
+
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    lines.forEach((line, i) => {
+      // Match various comment styles: // DRIFT:, # DRIFT:, /* DRIFT:, -- DRIFT:
+      const match = line.match(/(?:\/\/|#|\/\*|\-\-)\s*DRIFT:\s*(.+)/i);
+      if (match) {
+        driftComments.push({
+          file: filePath.replace(projectDir + '/', ''),
+          line: i + 1,
+          comment: match[1].trim(),
+        });
+      }
+    });
+  });
+
+  if (driftComments.length === 0) {
+    results.total = 1;
+    results.passed = 1;
+    return results;
+  }
+
+  // Read DRIFT-LOG.md
+  const driftLogPath = resolve(projectDir, config.requiredFiles.driftLog);
+  if (!existsSync(driftLogPath)) {
+    results.total = driftComments.length;
+    for (const dc of driftComments) {
+      results.errors.push(
+        `${dc.file}:${dc.line} has DRIFT comment but DRIFT-LOG.md doesn't exist`
+      );
+    }
+    return results;
+  }
+
+  const driftLogContent = readFileSync(driftLogPath, 'utf-8');
+
+  // Check each drift comment has a matching entry in DRIFT-LOG.md
+  for (const dc of driftComments) {
+    results.total++;
+    // Check if the file is mentioned in DRIFT-LOG.md
+    if (driftLogContent.includes(dc.file)) {
+      results.passed++;
+    } else {
+      results.errors.push(
+        `${dc.file}:${dc.line} — DRIFT comment not logged in DRIFT-LOG.md`
+      );
+    }
+  }
+
+  return results;
+}
+
+function walkDir(dir, callback) {
+  if (!existsSync(dir)) return;
+
+  const entries = readdirSync(dir);
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry)) continue;
+    if (entry.startsWith('.')) continue;
+
+    const fullPath = join(dir, entry);
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        walkDir(fullPath, callback);
+      } else if (stat.isFile()) {
+        callback(fullPath);
+      }
+    } catch {
+      // Skip files we can't read
+    }
+  }
+}

package/cli/validators/environment.mjs

@@ -0,0 +1,70 @@
+/**
+ * Environment Validator — Checks ENVIRONMENT.md docs and .env.example
+ * Now respects projectTypeConfig (e.g., skip env checks for CLI tools)
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export function validateEnvironment(projectDir, config) {
+  const results = { name: 'environment', errors: [], warnings: [], passed: 0, total: 0 };
+  const ptc = config.projectTypeConfig || {};
+
+  const envDocPath = resolve(projectDir, 'docs-canonical/ENVIRONMENT.md');
+  if (!existsSync(envDocPath)) {
+    return results; // Structure validator catches missing files
+  }
+
+  const content = readFileSync(envDocPath, 'utf-8');
+
+  // Check for required sections
+  results.total++;
+  if (content.includes('## Prerequisites') || content.includes('## Setup Steps')) {
+    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')) {
+    results.passed++;
+  } else {
+    results.warnings.push('ENVIRONMENT.md: missing "## Environment Variables" section');
+  }
+
+  // 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
+    if (content.includes('.env.example')) {
+      results.total++;
+      if (existsSync(resolve(projectDir, '.env.example'))) {
+        results.passed++;
+      } else {
+        results.warnings.push(
+          'ENVIRONMENT.md references .env.example but the file does not exist'
+        );
+      }
+    }
+
+    // Check if any .env file exists but no .env.example is provided
+    results.total++;
+    const hasEnvFile = ['.env', '.env.local', '.env.development'].some(f =>
+      existsSync(resolve(projectDir, f))
+    );
+    const hasEnvExample = existsSync(resolve(projectDir, '.env.example'));
+
+    if (hasEnvFile && !hasEnvExample) {
+      results.warnings.push(
+        '.env file exists but no .env.example template — new contributors won\'t know what vars to set'
+      );
+    } else {
+      results.passed++;
+    }
+  } else {
+    // CLI/library project — just verify doc exists and has basic content
+    results.total++;
+    results.passed++;
+  }
+
+  return results;
+}