docguard-cli 0.8.0 → 0.9.0

package/cli/validators/metrics-consistency.mjs

@@ -0,0 +1,166 @@
+/**
+ * Metrics Consistency Validator — Detects stale hardcoded numbers in docs.
+ *
+ * Scans all .md files for patterns like "N checks", "N validators", "N tests"
+ * and compares against actual values from guard results and package.json.
+ * Returns warnings for mismatches.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+]);
+
+/**
+ * Validate metrics consistency across documentation.
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - DocGuard config
+ * @param {object} [guardResults] - Results from runGuardInternal (optional)
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateMetricsConsistency(projectDir, config, guardResults) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  // ── Collect actual metrics ──
+  const actuals = {};
+
+  // Guard check count (from guard results if available)
+  if (guardResults && Array.isArray(guardResults)) {
+    const totalChecks = guardResults.reduce((sum, r) => {
+      if (r.status === 'skipped') return sum;
+      return sum + (r.total || 0);
+    }, 0);
+    const validatorCount = guardResults.filter(r => r.status !== 'skipped').length;
+
+    actuals.checks = totalChecks;
+    actuals.validators = validatorCount;
+  }
+
+  // Test count — count test files on disk
+  const testFiles = findTestFiles(projectDir);
+  if (testFiles.length > 0) {
+    actuals.tests = testFiles.length;
+  }
+
+  // If no actuals to compare, skip
+  if (Object.keys(actuals).length === 0) {
+    return { errors: [], warnings, passed: 0, total: 0 };
+  }
+
+  // ── Scan markdown files for hardcoded numbers ──
+  const isIgnored = loadIgnorePatterns(projectDir);
+  const mdFiles = findMarkdownFiles(projectDir);
+  // Patterns must match standalone number references, not ratio-style "8/8 checks"
+  const patterns = [
+    { key: 'checks', regex: /(?<!\d\/)\b(\d{2,})\s+(?:automated\s+)?checks?\b/gi, label: 'checks' },
+    { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators' },
+  ];
+
+  for (const mdFile of mdFiles) {
+    const relPath = relative(projectDir, mdFile);
+    // Skip changelog (historical numbers are fine by definition)
+    if (relPath.toLowerCase().includes('changelog')) continue;
+    // Skip files matched by .docguardignore
+    if (isIgnored(relPath)) continue;
+
+    let content;
+    try { content = readFileSync(mdFile, 'utf-8'); } catch { continue; }
+
+    for (const { key, regex, label } of patterns) {
+      if (actuals[key] === undefined) continue;
+
+      regex.lastIndex = 0;
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        total++;
+        const found = parseInt(match[1], 10);
+        if (found !== actuals[key] && found > 0) {
+          warnings.push(
+            `${relPath} says "${found} ${label}" but actual count is ${actuals[key]}. Update the doc or run \`docguard generate --force\``
+          );
+        } else {
+          passed++;
+        }
+      }
+    }
+  }
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function findTestFiles(dir) {
+  const tests = [];
+  const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
+
+  // Top-level test dirs
+  for (const td of testDirs) {
+    const fullDir = resolve(dir, td);
+    if (existsSync(fullDir)) {
+      walkFiles(fullDir, (f) => {
+        if (/\.(test|spec)\.[^.]+$/.test(f)) tests.push(f);
+      });
+    }
+  }
+
+  // Co-located tests in src/
+  const srcDir = resolve(dir, 'src');
+  if (existsSync(srcDir)) {
+    walkFiles(srcDir, (f) => {
+      if (/\.(test|spec)\.[^.]+$/.test(f) || f.includes('__tests__')) {
+        if (!tests.includes(f)) tests.push(f);
+      }
+    });
+  }
+
+  return tests;
+}
+
+function findMarkdownFiles(dir) {
+  const seen = new Set();
+  const mdFiles = [];
+  // Check root, docs-canonical, and extensions
+  const searchDirs = [
+    dir,
+    resolve(dir, 'docs-canonical'),
+    resolve(dir, 'extensions'),
+  ];
+
+  for (const searchDir of searchDirs) {
+    if (!existsSync(searchDir)) continue;
+    walkFiles(searchDir, (f) => {
+      if (f.endsWith('.md') && !seen.has(f)) {
+        seen.add(f);
+        mdFiles.push(f);
+      }
+    });
+  }
+
+  return mdFiles;
+}
+
+function walkFiles(dir, callback) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  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()) {
+        walkFiles(fullPath, callback);
+      } else if (stat.isFile()) {
+        callback(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+}

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/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,
+            });
+          }
+        }
+      }
+    }
+  }
+}