docguard-cli 0.8.2 → 0.9.1

package/cli/validators/schema-sync.mjs

@@ -0,0 +1,219 @@
+/**
+ * Schema Sync Validator — Ensures database schemas are documented in DATA-MODEL.md
+ *
+ * Detects schema definition files from popular ORMs/frameworks and validates
+ * that table/model names appear in DATA-MODEL.md documentation.
+ *
+ * Supported: Prisma, Drizzle, Sequelize, TypeORM, Knex, Django, Rails
+ *
+ * Zero dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative, extname, basename } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+  '.amplify-hosting', '.serverless',
+]);
+
+/**
+ * Schema detection configurations for each supported framework.
+ * Each entry has a file pattern to detect and a regex to extract model/table names.
+ */
+const SCHEMA_DETECTORS = [
+  {
+    name: 'Prisma',
+    filePattern: /schema\.prisma$/,
+    searchDirs: ['prisma'],
+    // Matches: model User { ... }
+    modelPattern: /^\s*model\s+(\w+)\s*\{/gm,
+  },
+  {
+    name: 'Drizzle',
+    filePattern: /\.(ts|js|mjs)$/,
+    searchDirs: ['drizzle', 'src/db', 'src/schema', 'db'],
+    // Matches: export const users = pgTable('users', ...) or mysqlTable, sqliteTable
+    modelPattern: /(?:pg|mysql|sqlite)Table\s*\(\s*['"](\w+)['"]/g,
+  },
+  {
+    name: 'TypeORM',
+    filePattern: /\.entity\.(ts|js)$/,
+    searchDirs: ['src/entities', 'src/entity', 'entities'],
+    // Matches: @Entity('users') or @Entity() class User
+    modelPattern: /@Entity\s*\(\s*(?:['"](\w+)['"])?\s*\)\s*(?:export\s+)?class\s+(\w+)/g,
+  },
+  {
+    name: 'Sequelize',
+    filePattern: /\.(ts|js)$/,
+    searchDirs: ['models', 'src/models'],
+    // Matches: sequelize.define('User', ...) or Model.init(...)
+    modelPattern: /(?:sequelize\.define|\.init)\s*\(\s*['"](\w+)['"]/g,
+  },
+  {
+    name: 'Knex',
+    filePattern: /\.(ts|js)$/,
+    searchDirs: ['migrations', 'db/migrations'],
+    // Matches: knex.schema.createTable('users', ...)
+    modelPattern: /createTable\s*\(\s*['"](\w+)['"]/g,
+  },
+  {
+    name: 'Django',
+    filePattern: /models\.py$/,
+    searchDirs: ['', 'app', 'apps'],
+    // Matches: class User(models.Model):
+    modelPattern: /class\s+(\w+)\s*\(\s*(?:models\.)?Model\s*\)/g,
+  },
+  {
+    name: 'Rails',
+    filePattern: /\d+_\w+\.rb$/,
+    searchDirs: ['db/migrate'],
+    // Matches: create_table :users do
+    modelPattern: /create_table\s+:(\w+)/g,
+  },
+];
+
+/**
+ * Main validator entry point.
+ */
+export function validateSchemaSync(projectDir, config) {
+  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+
+  // Check if DATA-MODEL.md exists
+  const dataModelPath = resolve(projectDir, 'docs-canonical', 'DATA-MODEL.md');
+  if (!existsSync(dataModelPath)) {
+    // No DATA-MODEL.md — nothing to sync against
+    // Only warn if we detect schema files
+    const detectedModels = detectAllModels(projectDir);
+    if (detectedModels.length > 0) {
+      results.total++;
+      results.warnings.push(
+        `Found ${detectedModels.length} database model(s) (${detectedModels.map(m => m.name).slice(0, 5).join(', ')}${detectedModels.length > 5 ? '...' : ''}) ` +
+        `but no DATA-MODEL.md exists. Run \`docguard init\` to create one, then document your schema`
+      );
+    }
+    return results;
+  }
+
+  const dataModelContent = readFileSync(dataModelPath, 'utf-8').toLowerCase();
+
+  // Detect all models/tables across schemas
+  const detectedModels = detectAllModels(projectDir);
+
+  if (detectedModels.length === 0) {
+    // No schema files found — silently pass
+    return results;
+  }
+
+  // Check each model appears in DATA-MODEL.md
+  for (const model of detectedModels) {
+    results.total++;
+
+    // Check if model name appears in DATA-MODEL.md (case-insensitive)
+    const modelLower = model.name.toLowerCase();
+    // Check both singular and pluralized forms
+    const found =
+      dataModelContent.includes(modelLower) ||
+      dataModelContent.includes(modelLower + 's') ||
+      (modelLower.endsWith('s') && dataModelContent.includes(modelLower.slice(0, -1)));
+
+    if (found) {
+      results.passed++;
+    } else {
+      results.warnings.push(
+        `${model.framework} model "${model.name}" (${model.file}) not documented in DATA-MODEL.md. ` +
+        `Add it to the Entity Definitions section`
+      );
+    }
+  }
+
+  return results;
+}
+
+// ──── Model Detection ──────────────────────────────────────────────────────
+
+/**
+ * Detect all database models/tables across all supported frameworks.
+ */
+function detectAllModels(projectDir) {
+  const models = [];
+
+  for (const detector of SCHEMA_DETECTORS) {
+    const files = findSchemaFiles(projectDir, detector);
+
+    for (const filePath of files) {
+      let content;
+      try { content = readFileSync(filePath, 'utf-8'); } catch { continue; }
+
+      const relPath = relative(projectDir, filePath);
+
+      // Reset regex and extract model names
+      detector.modelPattern.lastIndex = 0;
+      let match;
+      while ((match = detector.modelPattern.exec(content)) !== null) {
+        // Some patterns have the name in group 1 or 2
+        const name = match[1] || match[2];
+        if (name && !isCommonUtilityModel(name)) {
+          models.push({
+            name,
+            framework: detector.name,
+            file: relPath,
+          });
+        }
+      }
+    }
+  }
+
+  return models;
+}
+
+/**
+ * Find schema files for a given detector configuration.
+ */
+function findSchemaFiles(projectDir, detector) {
+  const files = [];
+
+  for (const searchDir of detector.searchDirs) {
+    const dir = resolve(projectDir, searchDir);
+    if (!existsSync(dir)) continue;
+
+    scanSchemaDir(dir, detector.filePattern, files);
+  }
+
+  return files;
+}
+
+function scanSchemaDir(dir, filePattern, files) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry)) continue;
+    if (entry.startsWith('.')) continue;
+
+    const full = join(dir, entry);
+    let stat;
+    try { stat = statSync(full); } catch { continue; }
+
+    if (stat.isDirectory()) {
+      scanSchemaDir(full, filePattern, files);
+    } else if (filePattern.test(entry)) {
+      files.push(full);
+    }
+  }
+}
+
+/**
+ * Filter out common utility models that don't need documentation.
+ */
+function isCommonUtilityModel(name) {
+  const utilities = new Set([
+    'migration', 'migrations', 'seed', 'seeds',
+    'knex_migrations', 'knex_migrations_lock',
+    'schema_migrations', 'ar_internal_metadata',
+    'SequelizeMeta', 'typeorm_metadata',
+    '_prisma_migrations',
+  ]);
+  return utilities.has(name);
+}

package/cli/validators/test-spec.mjs

@@ -3,7 +3,7 @@
  * Now respects projectTypeConfig (e.g., skip E2E for CLI tools)
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 export function validateTestSpec(projectDir, config) {
@@ -130,19 +130,66 @@ export function validateTestSpec(projectDir, config) {
     }
   }
 
-  // If no test spec entries parsed, check if test directory exists
+  // If no test spec entries parsed, check if tests exist anywhere
   if (results.total === 0) {
     results.total = 1;
+
+    // 1. Check top-level test dirs
     const commonTestDirs = ['tests', 'test', '__tests__', 'spec'];
     const hasTestDir = commonTestDirs.some(d =>
       existsSync(resolve(projectDir, d))
     );
-    if (hasTestDir) {
+
+    // 2. Check co-located tests (src/**/__tests__/, src/**/*.test.*)
+    let hasColocated = false;
+    if (!hasTestDir) {
+      const sourceRoots = ['src', 'app', 'lib', 'packages'];
+      for (const root of sourceRoots) {
+        const rootPath = resolve(projectDir, root);
+        if (existsSync(rootPath) && hasTestFilesRecursive(rootPath)) {
+          hasColocated = true;
+          break;
+        }
+      }
+    }
+
+    // 3. Check vitest/jest config for custom patterns
+    let hasConfigTests = false;
+    if (!hasTestDir && !hasColocated) {
+      const configs = ['vitest.config.ts', 'vitest.config.js', 'jest.config.ts', 'jest.config.js'];
+      hasConfigTests = configs.some(f => existsSync(resolve(projectDir, f)));
+    }
+
+    if (hasTestDir || hasColocated || hasConfigTests) {
       results.passed = 1;
     } else {
-      results.warnings.push('No test directory found (expected: tests/, test/, __tests__/)');
+      results.warnings.push(
+        'No test directory or co-located test files found. ' +
+        'Expected: tests/, src/**/__tests__/, or src/**/*.test.* files'
+      );
     }
   }
 
   return results;
 }
+
+/** Recursively check if a directory contains test files */
+function hasTestFilesRecursive(dir) {
+  const ignore = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+  let entries;
+  try { entries = readdirSync(dir); } catch { return false; }
+  for (const entry of entries) {
+    if (ignore.has(entry) || entry.startsWith('.')) continue;
+    const full = resolve(dir, entry);
+    try {
+      const s = statSync(full);
+      if (s.isDirectory()) {
+        if (entry === '__tests__' || entry === '__test__') return true;
+        if (hasTestFilesRecursive(full)) return true;
+      } else if (/\.(test|spec)\.[^.]+$/.test(entry)) {
+        return true;
+      }
+    } catch { continue; }
+  }
+  return false;
+}

package/cli/validators/todo-tracking.mjs

@@ -0,0 +1,295 @@
+/**
+ * TODO/FIXME Tracking Validator — Ensures code annotations are documented
+ *
+ * Scans source files for TODO:, FIXME:, HACK:, XXX: annotations and checks
+ * if they are tracked in documentation (ROADMAP.md, CURRENT-STATE.md, etc.).
+ *
+ * Also detects skipped tests without explanation.
+ *
+ * Inspired by spec-kit-cleanup (github.com/dsrednicki/spec-kit-cleanup)
+ * which uses tiered issue classification for code hygiene.
+ *
+ * Zero dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative, extname } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+  '.amplify-hosting', '.serverless', 'Research',
+]);
+
+const SOURCE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.rb', '.go', '.rs', '.java', '.cs',
+  '.vue', '.svelte', '.astro',
+]);
+
+const TEST_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
+
+// ──── Patterns ────
+
+const TODO_PATTERN = /\b(TODO|FIXME|HACK|XXX|TEMP(?!late|orar)|WORKAROUND)\s*[(:]/;
+const TODO_EXTRACT = /\b(TODO|FIXME|HACK|XXX|TEMP(?!late|orar)|WORKAROUND)\s*[:(]?\s*(.+)/;
+
+// Test skip patterns for common test frameworks
+const SKIP_PATTERNS = [
+  /\btest\.skip\s*\(/,
+  /\bit\.skip\s*\(/,
+  /\bdescribe\.skip\s*\(/,
+  /\bxit\s*\(/,
+  /\bxdescribe\s*\(/,
+  /\bxtest\s*\(/,
+  /\.todo\s*\(/,
+  /\btest\.todo\s*\(/,
+  /\bit\.todo\s*\(/,
+];
+
+// Skip explanation patterns (comments that justify the skip)
+const SKIP_REASON_PATTERN = /\/\/\s*(REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:/i;
+
+/**
+ * Main validator — checks for untracked TODOs and unexplained test skips.
+ */
+export function validateTodoTracking(projectDir, config) {
+  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+
+  // ── Part 1: Skipped Tests ──
+  const skipResults = checkSkippedTests(projectDir, config);
+  results.errors.push(...skipResults.errors);
+  results.warnings.push(...skipResults.warnings);
+  results.passed += skipResults.passed;
+  results.total += skipResults.total;
+
+  // ── Part 2: Untracked TODOs/FIXMEs ──
+  const todoResults = checkUntrackedTodos(projectDir, config);
+  results.errors.push(...todoResults.errors);
+  results.warnings.push(...todoResults.warnings);
+  results.passed += todoResults.passed;
+  results.total += todoResults.total;
+
+  return results;
+}
+
+// ──── Skipped Tests ────────────────────────────────────────────────────────
+
+/**
+ * Scan test files for skip/todo patterns without adjacent explanation comments.
+ */
+function checkSkippedTests(projectDir) {
+  const errors = [];
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const testFiles = [];
+  findTestFiles(projectDir, projectDir, testFiles);
+
+  if (testFiles.length === 0) return { errors, warnings, passed, total };
+
+  // Check: "Project has test files" → pass
+  total++;
+  passed++;
+
+  let skippedWithoutReason = 0;
+  let skippedWithReason = 0;
+
+  for (const relPath of testFiles) {
+    const fullPath = resolve(projectDir, relPath);
+    let content;
+    try { content = readFileSync(fullPath, 'utf-8'); } catch { continue; }
+
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Check if this line has a test skip pattern
+      const isSkipped = SKIP_PATTERNS.some(p => p.test(line));
+      if (!isSkipped) continue;
+
+      // Check surrounding lines (1 above, 1 below, and inline) for explanation
+      const prevLine = i > 0 ? lines[i - 1] : '';
+      const nextLine = i < lines.length - 1 ? lines[i + 1] : '';
+
+      const hasReason =
+        SKIP_REASON_PATTERN.test(prevLine) ||
+        SKIP_REASON_PATTERN.test(line) ||
+        SKIP_REASON_PATTERN.test(nextLine);
+
+      if (hasReason) {
+        skippedWithReason++;
+      } else {
+        skippedWithoutReason++;
+        warnings.push(
+          `Skipped test without explanation at ${relPath}:${i + 1}. ` +
+          `Add a // REASON: comment explaining why the test is skipped`
+        );
+      }
+    }
+  }
+
+  // Check: "All skipped tests have explanations"
+  if (skippedWithoutReason > 0 || skippedWithReason > 0) {
+    total++;
+    if (skippedWithoutReason === 0) {
+      passed++;
+    }
+  }
+
+  return { errors, warnings, passed, total };
+}
+
+// ──── Untracked TODOs ──────────────────────────────────────────────────────
+
+/**
+ * Scan source files for TODO/FIXME annotations and check if they appear
+ * in tracking documentation.
+ */
+function checkUntrackedTodos(projectDir, config) {
+  const errors = [];
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  // Collect all TODO/FIXME items from source
+  const todos = [];
+  findTodos(projectDir, projectDir, todos);
+
+  if (todos.length === 0) {
+    // No TODOs found — that's clean code
+    total++;
+    passed++;
+    return { errors, warnings, passed, total };
+  }
+
+  // Check if TODOs are tracked in documentation
+  const trackingContent = loadTrackingDocs(projectDir, config);
+
+  total++;
+  let untrackedCount = 0;
+
+  for (const todo of todos) {
+    // Check if the TODO text appears somewhere in tracking docs
+    const isTracked = trackingContent.some(doc =>
+      doc.content.includes(todo.keyword) ||
+      doc.content.toLowerCase().includes(todo.text.toLowerCase().trim().substring(0, 30))
+    );
+
+    if (!isTracked) {
+      untrackedCount++;
+      // Only report first 5 to avoid noise
+      if (untrackedCount <= 5) {
+        warnings.push(
+          `Untracked ${todo.keyword} at ${todo.file}:${todo.line}: "${todo.text.substring(0, 60)}". ` +
+          `Add to ROADMAP.md, CURRENT-STATE.md, or a GitHub issue`
+        );
+      }
+    }
+  }
+
+  if (untrackedCount > 5) {
+    warnings.push(`...and ${untrackedCount - 5} more untracked TODO/FIXME items`);
+  }
+
+  if (untrackedCount === 0) {
+    passed++;
+  }
+
+  return { errors, warnings, passed, total };
+}
+
+/**
+ * Load doc files where TODOs should be tracked.
+ */
+function loadTrackingDocs(projectDir, config) {
+  const docs = [];
+  const trackingFiles = [
+    'ROADMAP.md', 'CURRENT-STATE.md', 'TODO.md', 'BACKLOG.md',
+    'docs-canonical/ARCHITECTURE.md', 'CHANGELOG.md',
+    ...(config.todoTracking?.trackingFiles || []),
+  ];
+
+  for (const file of trackingFiles) {
+    const fullPath = resolve(projectDir, file);
+    if (existsSync(fullPath)) {
+      try {
+        docs.push({ file, content: readFileSync(fullPath, 'utf-8') });
+      } catch { /* ignore */ }
+    }
+  }
+
+  return docs;
+}
+
+// ──── File Scanners ────────────────────────────────────────────────────────
+
+function findTestFiles(rootDir, dir, files) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry)) continue;
+    if (entry.startsWith('.')) continue;
+
+    const full = join(dir, entry);
+    let stat;
+    try { stat = statSync(full); } catch { continue; }
+
+    if (stat.isDirectory()) {
+      findTestFiles(rootDir, full, files);
+    } else {
+      const ext = extname(entry).toLowerCase();
+      if (!TEST_EXTENSIONS.has(ext)) continue;
+
+      // Match test file patterns
+      if (/\.(test|spec)\.(mjs|cjs|[jt]sx?)$/.test(entry) ||
+          /__(tests|test)__/.test(relative(rootDir, full))) {
+        files.push(relative(rootDir, full));
+      }
+    }
+  }
+}
+
+function findTodos(rootDir, dir, todos) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry)) continue;
+    if (entry.startsWith('.')) continue;
+
+    const full = join(dir, entry);
+    let stat;
+    try { stat = statSync(full); } catch { continue; }
+
+    if (stat.isDirectory()) {
+      findTodos(rootDir, full, todos);
+    } else {
+      const ext = extname(entry).toLowerCase();
+      if (!SOURCE_EXTENSIONS.has(ext)) continue;
+
+      let content;
+      try { content = readFileSync(full, 'utf-8'); } catch { continue; }
+
+      const lines = content.split('\n');
+      const relPath = relative(rootDir, full);
+
+      for (let i = 0; i < lines.length; i++) {
+        if (TODO_PATTERN.test(lines[i])) {
+          const match = lines[i].match(TODO_EXTRACT);
+          if (match) {
+            todos.push({
+              keyword: match[1].toUpperCase(),
+              text: match[2].trim(),
+              file: relPath,
+              line: i + 1,
+            });
+          }
+        }
+      }
+    }
+  }
+}