docguard-cli 0.5.1

package/cli/validators/freshness.mjs

@@ -0,0 +1,224 @@
+/**
+ * Freshness Validator — Check if documentation is stale relative to code changes.
+ * Uses git history to compare when docs were last modified vs when code was last changed.
+ * 
+ * This catches the exact issue the user identified: docs say "[ ] planned"
+ * but the code has already been implemented and committed.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+  'templates', 'configs', 'Research',
+]);
+
+/**
+ * Get the last git commit date for a file.
+ * Returns null if the file isn't tracked or git isn't available.
+ */
+function getLastGitDate(filePath, dir) {
+  try {
+    const result = execSync(
+      `git log -1 --format="%aI" -- "${filePath}"`,
+      { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    return result ? new Date(result) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the count of commits that touched code files since a given date.
+ */
+function getCodeCommitsSince(date, dir) {
+  try {
+    const isoDate = date.toISOString();
+    const result = execSync(
+      `git log --since="${isoDate}" --oneline --diff-filter=M -- "*.js" "*.mjs" "*.ts" "*.tsx" "*.py" "*.java" "*.go" | wc -l`,
+      { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    return parseInt(result) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Check if git is available in this project.
+ */
+function isGitRepo(dir) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', {
+      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get total number of commits in the repo.
+ */
+function getTotalCommits(dir) {
+  try {
+    return parseInt(execSync('git rev-list --count HEAD', {
+      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Get the last N commits touching code files (not docs).
+ */
+function getRecentCodeCommits(dir, count = 5) {
+  try {
+    const result = execSync(
+      `git log -${count} --format="%h %aI %s" -- "*.js" "*.mjs" "*.ts" "*.tsx" "*.py" "*.java"`,
+      { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    return result ? result.split('\n') : [];
+  } catch {
+    return [];
+  }
+}
+
+export function validateFreshness(dir, config) {
+  const results = [];
+
+  if (!isGitRepo(dir)) {
+    results.push({
+      status: 'skip',
+      message: 'Not a git repository — freshness check skipped',
+    });
+    return results;
+  }
+
+  const totalCommits = getTotalCommits(dir);
+  if (totalCommits < 3) {
+    results.push({
+      status: 'skip',
+      message: `Only ${totalCommits} commits — freshness check needs ≥3 commits`,
+    });
+    return results;
+  }
+
+  // ── 1. Check each canonical doc's last update vs latest code commit ──
+  const docFiles = [
+    'docs-canonical/ARCHITECTURE.md',
+    'docs-canonical/DATA-MODEL.md',
+    'docs-canonical/SECURITY.md',
+    'docs-canonical/TEST-SPEC.md',
+    'docs-canonical/ENVIRONMENT.md',
+    'ROADMAP.md',
+    'AGENTS.md',
+  ];
+
+  // Get the most recent code commit date
+  const recentCodeCommits = getRecentCodeCommits(dir, 1);
+  let latestCodeDate = null;
+  if (recentCodeCommits.length > 0) {
+    const parts = recentCodeCommits[0].split(' ');
+    if (parts.length >= 2) {
+      latestCodeDate = new Date(parts[1]);
+    }
+  }
+
+  const STALE_THRESHOLD_DAYS = 30; // Docs older than 30 days vs latest code = stale
+  const WARNING_THRESHOLD_COMMITS = 10; // More than 10 code commits since last doc update = stale
+
+  for (const docFile of docFiles) {
+    const docPath = resolve(dir, docFile);
+    if (!existsSync(docPath)) continue;
+
+    const docDate = getLastGitDate(docFile, dir);
+    if (!docDate) {
+      // File exists but isn't tracked in git yet
+      results.push({
+        status: 'warn',
+        message: `${docFile} exists but is not yet committed to git`,
+      });
+      continue;
+    }
+
+    // Check how many code commits happened since this doc was last updated
+    const codeCommitsSince = getCodeCommitsSince(docDate, dir);
+
+    if (codeCommitsSince >= WARNING_THRESHOLD_COMMITS) {
+      results.push({
+        status: 'warn',
+        message: `${docFile} — ${codeCommitsSince} code commits since last doc update (${docDate.toISOString().split('T')[0]})`,
+      });
+      continue;
+    }
+
+    // Check age vs latest code commit
+    if (latestCodeDate) {
+      const daysDiff = Math.floor((latestCodeDate - docDate) / (1000 * 60 * 60 * 24));
+      if (daysDiff > STALE_THRESHOLD_DAYS) {
+        results.push({
+          status: 'warn',
+          message: `${docFile} — last updated ${daysDiff} days before latest code change`,
+        });
+        continue;
+      }
+    }
+
+    results.push({
+      status: 'pass',
+      message: `${docFile} is fresh`,
+    });
+  }
+
+  // ── 2. Check CHANGELOG.md was updated in the last 5 code commits ──
+  const changelogPath = resolve(dir, config.requiredFiles?.changelog || 'CHANGELOG.md');
+  if (existsSync(changelogPath)) {
+    const changelogDate = getLastGitDate(config.requiredFiles?.changelog || 'CHANGELOG.md', dir);
+    if (changelogDate && latestCodeDate) {
+      const daysDiff = Math.floor((latestCodeDate - changelogDate) / (1000 * 60 * 60 * 24));
+      if (daysDiff > 7) {
+        results.push({
+          status: 'warn',
+          message: `CHANGELOG.md not updated in ${daysDiff} days despite code changes`,
+        });
+      } else {
+        results.push({
+          status: 'pass',
+          message: 'CHANGELOG.md is up to date',
+        });
+      }
+    }
+  }
+
+  // ── 3. Check DRIFT-LOG.md was updated if there are DRIFT comments ──
+  const driftPath = resolve(dir, config.requiredFiles?.driftLog || 'DRIFT-LOG.md');
+  if (existsSync(driftPath)) {
+    const driftDate = getLastGitDate(config.requiredFiles?.driftLog || 'DRIFT-LOG.md', dir);
+    // Check for recent DRIFT comments added to code
+    try {
+      const recentDrifts = execSync(
+        `git log -5 --all -p -- "*.js" "*.mjs" "*.ts" "*.tsx" "*.py" | grep -c "DRIFT:" || true`,
+        { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+      ).trim();
+      const driftCount = parseInt(recentDrifts) || 0;
+      if (driftCount > 0 && driftDate) {
+        const codeCommitsSince = getCodeCommitsSince(driftDate, dir);
+        if (codeCommitsSince > 3) {
+          results.push({
+            status: 'warn',
+            message: `DRIFT-LOG.md may be stale — ${driftCount} DRIFT comments found in recent commits`,
+          });
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  return results;
+}

package/cli/validators/security.mjs

@@ -0,0 +1,101 @@
+/**
+ * Security Validator — Basic checks for secrets in code
+ */
+
+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', '.env',
+]);
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+]);
+
+// Patterns that might indicate hardcoded secrets
+const SECRET_PATTERNS = [
+  { pattern: /(?:password|passwd|pwd)\s*[:=]\s*['"][^'"]{8,}['"]/gi, label: 'hardcoded password' },
+  { pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{16,}['"]/gi, label: 'hardcoded API key' },
+  { pattern: /(?:secret[_-]?key|secretkey)\s*[:=]\s*['"][^'"]{16,}['"]/gi, label: 'hardcoded secret key' },
+  { pattern: /(?:access[_-]?token|accesstoken)\s*[:=]\s*['"][^'"]{16,}['"]/gi, label: 'hardcoded access token' },
+  { pattern: /AKIA[0-9A-Z]{16}/g, label: 'AWS Access Key ID' },
+  { pattern: /(?:sk-|sk_live_|sk_test_)[a-zA-Z0-9]{20,}/g, label: 'API secret key (Stripe/OpenAI pattern)' },
+];
+
+export function validateSecurity(projectDir, config) {
+  const results = { name: 'security', errors: [], warnings: [], passed: 0, total: 0 };
+
+  const findings = [];
+
+  walkDir(projectDir, (filePath) => {
+    const ext = extname(filePath);
+    if (!CODE_EXTENSIONS.has(ext)) return;
+
+    // Skip .env files — they're supposed to have secrets
+    if (filePath.endsWith('.env') || filePath.endsWith('.env.local')) return;
+    // Skip .env.example — it should have placeholder values
+    if (filePath.endsWith('.env.example')) return;
+
+    const content = readFileSync(filePath, 'utf-8');
+    const relPath = filePath.replace(projectDir + '/', '');
+
+    for (const { pattern, label } of SECRET_PATTERNS) {
+      pattern.lastIndex = 0;
+      const match = pattern.exec(content);
+      if (match) {
+        findings.push({ file: relPath, label, match: match[0].substring(0, 30) + '...' });
+      }
+    }
+  });
+
+  results.total = 1;
+  if (findings.length === 0) {
+    results.passed = 1;
+  } else {
+    for (const f of findings) {
+      results.errors.push(`${f.file}: possible ${f.label} found`);
+    }
+  }
+
+  // Check .gitignore includes .env
+  results.total++;
+  const gitignorePath = resolve(projectDir, '.gitignore');
+  if (existsSync(gitignorePath)) {
+    const gitignore = readFileSync(gitignorePath, 'utf-8');
+    if (gitignore.includes('.env') || gitignore.includes('.env.local')) {
+      results.passed++;
+    } else {
+      results.warnings.push('.gitignore does not include .env — secrets may be committed');
+    }
+  } else {
+    results.warnings.push('No .gitignore found — secrets may be committed');
+  }
+
+  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('.') && entry !== '.env') 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 unreadable files
+    }
+  }
+}

package/cli/validators/structure.mjs

@@ -0,0 +1,88 @@
+/**
+ * Structure Validator — Checks that all required CDD files exist
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export function validateStructure(projectDir, config) {
+  const results = { name: 'structure', errors: [], warnings: [], passed: 0, total: 0 };
+
+  // Check canonical docs
+  for (const file of config.requiredFiles.canonical) {
+    results.total++;
+    const fullPath = resolve(projectDir, file);
+    if (existsSync(fullPath)) {
+      results.passed++;
+    } else {
+      results.errors.push(`Missing required file: ${file}`);
+    }
+  }
+
+  // Check agent file (any one is fine)
+  results.total++;
+  const agentFileFound = config.requiredFiles.agentFile.some(f =>
+    existsSync(resolve(projectDir, f))
+  );
+  if (agentFileFound) {
+    results.passed++;
+  } else {
+    results.errors.push(`Missing agent file: ${config.requiredFiles.agentFile.join(' or ')}`);
+  }
+
+  // Check changelog
+  results.total++;
+  if (existsSync(resolve(projectDir, config.requiredFiles.changelog))) {
+    results.passed++;
+  } else {
+    results.errors.push(`Missing required file: ${config.requiredFiles.changelog}`);
+  }
+
+  // Check drift log
+  results.total++;
+  if (existsSync(resolve(projectDir, config.requiredFiles.driftLog))) {
+    results.passed++;
+  } else {
+    results.errors.push(`Missing required file: ${config.requiredFiles.driftLog}`);
+  }
+
+  return results;
+}
+
+/**
+ * Check that canonical doc files contain required sections
+ */
+export function validateDocSections(projectDir, config) {
+  const results = { name: 'doc-sections', errors: [], warnings: [], passed: 0, total: 0 };
+  const ptc = config.projectTypeConfig || {};
+
+  const requiredSections = {
+    'docs-canonical/ARCHITECTURE.md': ['## System Overview', '## Component Map', '## Tech Stack'],
+    'docs-canonical/DATA-MODEL.md': ptc.needsDatabase !== false
+      ? ['## Entities']
+      : [], // CLI/library projects don't need entity docs
+    'docs-canonical/SECURITY.md': ['## Authentication', '## Secrets Management'],
+    'docs-canonical/TEST-SPEC.md': ['## Test Categories', '## Coverage Rules'],
+    'docs-canonical/ENVIRONMENT.md': ptc.needsEnvVars !== false
+      ? ['## Environment Variables', '## Setup Steps']
+      : ['## Setup Steps'], // Always need setup steps, env vars optional
+  };
+
+  for (const [file, sections] of Object.entries(requiredSections)) {
+    const fullPath = resolve(projectDir, file);
+    if (!existsSync(fullPath)) continue;
+
+    const content = readFileSync(fullPath, 'utf-8');
+
+    for (const section of sections) {
+      results.total++;
+      if (content.includes(section)) {
+        results.passed++;
+      } else {
+        results.warnings.push(`${file}: missing section "${section}"`);
+      }
+    }
+  }
+
+  return results;
+}

package/cli/validators/test-spec.mjs

@@ -0,0 +1,115 @@
+/**
+ * Test Spec Validator — Checks that tests exist per TEST-SPEC.md coverage rules
+ * Now respects projectTypeConfig (e.g., skip E2E for CLI tools)
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export function validateTestSpec(projectDir, config) {
+  const results = { name: 'test-spec', errors: [], warnings: [], passed: 0, total: 0 };
+
+  const testSpecPath = resolve(projectDir, 'docs-canonical/TEST-SPEC.md');
+  if (!existsSync(testSpecPath)) {
+    return results; // Structure validator catches this
+  }
+
+  const content = readFileSync(testSpecPath, 'utf-8');
+  const ptc = config.projectTypeConfig || {};
+
+  // Parse the Source-to-Test Map table (new header) or Service-to-Test Map (old header)
+  const serviceMapMatch = content.match(
+    /## (?:Service-to-Test Map|Source-to-Test Map)[\s\S]*?\n\|.*\|.*\|.*\|([\s\S]*?)(?=\n##|\n$|$)/
+  );
+
+  if (serviceMapMatch) {
+    const tableContent = serviceMapMatch[1];
+    const rows = tableContent
+      .split('\n')
+      .filter(line => line.startsWith('|') && !line.includes('---'));
+
+    for (const row of rows) {
+      const cells = row
+        .split('|')
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+
+      if (cells.length < 3) continue;
+
+      const sourceFile = cells[0];
+      const status = cells[cells.length - 1]; // Last column is always status
+
+      // Skip template/example rows and italic placeholder rows
+      if (sourceFile.startsWith('<!--') || sourceFile === 'Source File' || sourceFile.startsWith('*')) continue;
+
+      if (status && status.includes('❌')) {
+        results.total++;
+        results.warnings.push(
+          `TEST-SPEC declares ${sourceFile} as ❌ — missing tests`
+        );
+      } else if (status && status.includes('⚠️')) {
+        results.total++;
+        results.warnings.push(
+          `TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`
+        );
+      } else if (status && status.includes('✅')) {
+        results.total++;
+        results.passed++;
+      }
+    }
+  }
+
+  // Parse Critical User Journeys OR Critical CLI Flows
+  // Only check E2E journeys if the project type needs E2E
+  if (ptc.needsE2E !== false) {
+    const journeyMatch = content.match(
+      /## Critical (?:User Journeys|CLI Flows)[\s\S]*?\n\|.*\|.*\|.*\|.*\|([\s\S]*?)(?=\n##|\n---|\n$|$)/
+    );
+
+    if (journeyMatch) {
+      const tableContent = journeyMatch[1];
+      const rows = tableContent
+        .split('\n')
+        .filter(line => line.startsWith('|') && !line.includes('---'));
+
+      for (const row of rows) {
+        const cells = row
+          .split('|')
+          .map(s => s.trim())
+          .filter(s => s.length > 0);
+
+        if (cells.length < 4) continue;
+
+        const [num, journey, testFile, status] = cells;
+        // Skip template rows (comments), headers
+        if (num.startsWith('<!--') || num === '#' || journey.startsWith('<!--')) continue;
+
+        if (status && status.includes('❌')) {
+          results.total++;
+          results.warnings.push(
+            `E2E Journey #${num} (${journey}) — missing test: ${testFile}`
+          );
+        } else if (status && status.includes('✅')) {
+          results.total++;
+          results.passed++;
+        }
+      }
+    }
+  }
+
+  // If no test spec entries parsed, check if test directory exists
+  if (results.total === 0) {
+    results.total = 1;
+    const commonTestDirs = ['tests', 'test', '__tests__', 'spec'];
+    const hasTestDir = commonTestDirs.some(d =>
+      existsSync(resolve(projectDir, d))
+    );
+    if (hasTestDir) {
+      results.passed = 1;
+    } else {
+      results.warnings.push('No test directory found (expected: tests/, test/, __tests__/)');
+    }
+  }
+
+  return results;
+}

package/docs/ai-integration.md

@@ -0,0 +1,179 @@
+# AI Integration Guide
+
+DocGuard is **AI-native**. It generates prompts that AI agents execute — the human reviews, not writes.
+
+## How It Works
+
+```
+docguard diagnose  →  AI reads output  →  AI writes docs  →  docguard guard  →  ✅
+```
+
+DocGuard is designed to be used **by** AI agents, not just **for** humans.
+
+## Supported AI Agents
+
+DocGuard works with any AI coding agent that can read CLI output:
+
+| Agent | Integration |
+|-------|------------|
+| **Claude Code** | Reads `diagnose` output, writes docs, runs `guard` |
+| **GitHub Copilot** | Slash commands in `.github/commands/` |
+| **Cursor** | Slash commands in `.cursor/rules/` |
+| **Google Antigravity** | Workflows in `.agents/workflows/` |
+| **Google Gemini** | Commands in `.gemini/commands/` |
+| **Any CLI-capable LLM** | Reads JSON output from `--format json` |
+
+## Slash Commands
+
+`docguard init` auto-installs slash commands for detected AI agents:
+
+```
+.github/commands/diagnose.md     # GitHub Copilot
+.cursor/rules/diagnose.md        # Cursor
+.gemini/commands/diagnose.md     # Google Gemini
+.agents/workflows/diagnose.md    # Antigravity
+```
+
+## The AI Workflow
+
+### Step 1: Diagnose
+
+```bash
+npx docguard diagnose
+```
+
+Output:
+```
+🔍 DocGuard Diagnose — my-project
+   Profile: standard | Score: 75/100 (B)
+   Guard:   35/41 passed | Status: WARN
+
+  Warnings (3):
+  ⚠ [Freshness] docs-canonical/ARCHITECTURE.md — 15 commits since last update
+    Fix: docguard fix --doc architecture
+
+  📋 Remediation Plan:
+  1. docguard fix --doc architecture
+  2. docguard guard ← verify fixes
+
+  🤖 AI-Ready Prompt:
+  TASK: Fix 3 documentation issue(s) in project "my-project"
+  ...
+```
+
+### Step 2: AI Fixes
+
+The AI reads the remediation plan and executes `docguard fix --doc <name>` for each issue. Each fix command outputs research instructions:
+
+```bash
+npx docguard fix --doc architecture
+```
+
+Output:
+```
+TASK: Write ARCHITECTURE.md for "my-project"
+
+RESEARCH STEPS:
+1. Read package.json for dependencies and project structure
+2. List top-level directories (src/, lib/, cli/)
+3. Read 2-3 representative files per directory
+4. Map the import graph
+5. Identify external dependencies
+
+WRITE THE DOCUMENT:
+- System Overview (2-3 sentences)
+- Component Map (table of modules)
+- Layer Boundaries (import rules)
+- Data Flow (request lifecycle)
+```
+
+### Step 3: Verify
+
+```bash
+npx docguard guard
+```
+
+If all checks pass → done. If issues remain → repeat from Step 1.
+
+## JSON Output for Automation
+
+For programmatic integration:
+
+```bash
+npx docguard diagnose --format json
+```
+
+```json
+{
+  "project": "my-project",
+  "profile": "standard",
+  "status": "WARN",
+  "score": 75,
+  "grade": "B",
+  "issues": [
+    {
+      "severity": "warning",
+      "validator": "Freshness",
+      "message": "ARCHITECTURE.md — 15 commits since last update",
+      "command": "docguard fix --doc architecture",
+      "docTarget": "architecture"
+    }
+  ],
+  "fixCommands": ["docguard fix --doc architecture"]
+}
+```
+
+```bash
+npx docguard guard --format json
+```
+
+```json
+{
+  "project": "my-project",
+  "profile": "standard",
+  "status": "PASS",
+  "passed": 41,
+  "total": 41,
+  "validators": [
+    { "name": "Structure", "status": "pass", "passed": 8, "total": 8 }
+  ]
+}
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+DocGuard ships a ready-to-use workflow:
+
+```yaml
+# .github/workflows/docguard.yml
+name: DocGuard CDD Check
+on: [pull_request]
+jobs:
+  docguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npx docguard ci --format json --threshold 70
+```
+
+Or copy `templates/ci/github-actions.yml` from this repo.
+
+### Pre-commit Hook
+
+```bash
+npx docguard hooks
+```
+
+Automatically runs `guard` before every commit.
+
+## Best Practices for AI Agents
+
+1. **Always run `diagnose` first** — it's the one command that identifies everything
+2. **Use `--format json`** for structured, parseable output
+3. **Run `guard` after fixes** to verify — loop until all checks pass
+4. **Use `fix --doc <name>`** for targeted prompts when you know which doc needs work
+5. **Check `score --tax`** periodically to ensure documentation isn't becoming a burden