docguard-cli 0.5.1

package/cli/commands/agents.mjs

@@ -0,0 +1,221 @@
+/**
+ * Agents Command — Generate agent-specific config files from AGENTS.md
+ * Creates .cursor/rules/, .clinerules, .github/copilot-instructions.md, etc.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { c } from '../docguard.mjs';
+
+const AGENT_TARGETS = {
+  cursor: {
+    path: '.cursor/rules/cdd.mdc',
+    name: 'Cursor',
+    generate: generateCursorRules,
+  },
+  copilot: {
+    path: '.github/copilot-instructions.md',
+    name: 'GitHub Copilot',
+    generate: generateCopilotInstructions,
+  },
+  cline: {
+    path: '.clinerules',
+    name: 'Cline',
+    generate: generateClineRules,
+  },
+  windsurf: {
+    path: '.windsurfrules',
+    name: 'Windsurf',
+    generate: generateWindsurfRules,
+  },
+  claude: {
+    path: 'CLAUDE.md',
+    name: 'Claude Code',
+    generate: generateClaudeMd,
+  },
+  gemini: {
+    path: '.gemini/settings.json',
+    name: 'Gemini CLI',
+    generate: generateGeminiSettings,
+  },
+};
+
+export function runAgents(projectDir, config, flags) {
+  console.log(`${c.bold}🤖 DocGuard Agents — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+
+  // Read AGENTS.md content
+  const agentsPath = resolve(projectDir, 'AGENTS.md');
+  if (!existsSync(agentsPath)) {
+    console.log(`  ${c.red}❌ AGENTS.md not found. Run ${c.cyan}docguard init${c.red} first.${c.reset}\n`);
+    process.exit(1);
+  }
+
+  const agentsContent = readFileSync(agentsPath, 'utf-8');
+
+  // Parse which agents to generate for
+  let targets = Object.keys(AGENT_TARGETS);
+  const specificAgent = flags.agent;
+  if (specificAgent) {
+    if (!AGENT_TARGETS[specificAgent]) {
+      console.log(`  ${c.red}Unknown agent: ${specificAgent}${c.reset}`);
+      console.log(`  Available: ${targets.join(', ')}\n`);
+      process.exit(1);
+    }
+    targets = [specificAgent];
+  }
+
+  let created = 0;
+  let skipped = 0;
+
+  for (const key of targets) {
+    const target = AGENT_TARGETS[key];
+    const targetPath = resolve(projectDir, target.path);
+
+    if (existsSync(targetPath) && !flags.force) {
+      console.log(`  ${c.dim}⏭️  ${target.name}: ${target.path} (exists, use --force to overwrite)${c.reset}`);
+      skipped++;
+      continue;
+    }
+
+    const content = target.generate(agentsContent, config);
+
+    // Create directories
+    const dir = dirname(targetPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    writeFileSync(targetPath, content, 'utf-8');
+    console.log(`  ${c.green}✅ ${target.name}${c.reset}: ${target.path}`);
+    created++;
+  }
+
+  console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
+  console.log(`  Created: ${created}  Skipped: ${skipped}\n`);
+}
+
+// ── Generator Functions ────────────────────────────────────────────────────
+
+function getCddBlock(config) {
+  return `## Canonical-Driven Development (CDD)
+
+This project follows the CDD methodology. Documentation is the source of truth.
+
+### Required Reading (Before Any Code Change)
+- \`docs-canonical/ARCHITECTURE.md\` — System design and boundaries
+- \`docs-canonical/DATA-MODEL.md\` — Database schemas
+- \`docs-canonical/SECURITY.md\` — Auth and secrets rules
+- \`docs-canonical/TEST-SPEC.md\` — Test requirements
+- \`docs-canonical/ENVIRONMENT.md\` — Environment setup
+
+### Rules
+1. Read canonical docs BEFORE writing code
+2. If code deviates from docs, add \`// DRIFT: reason\` comment
+3. Log all drift in \`DRIFT-LOG.md\`
+4. Update \`CHANGELOG.md\` for every change
+5. Never modify canonical docs without team review`;
+}
+
+function generateCursorRules(agentsContent, config) {
+  return `---
+description: CDD rules for ${config.projectName}
+globs: "**/*"
+---
+
+${getCddBlock(config)}
+
+### Workflow
+1. Check \`docs-canonical/\` before suggesting changes
+2. Match existing code patterns
+3. Add \`// DRIFT: reason\` if deviating from canonical docs
+4. Update CHANGELOG.md for every meaningful change
+
+### Original AGENTS.md Content
+${agentsContent}
+`;
+}
+
+function generateCopilotInstructions(agentsContent, config) {
+  return `# GitHub Copilot Instructions — ${config.projectName}
+
+${getCddBlock(config)}
+
+### For Copilot
+- Prioritize suggestions that align with canonical documentation
+- When generating new files, follow the patterns in \`docs-canonical/ARCHITECTURE.md\`
+- Always suggest tests that match \`docs-canonical/TEST-SPEC.md\` requirements
+
+---
+
+${agentsContent}
+`;
+}
+
+function generateClineRules(agentsContent, config) {
+  return `# Cline Rules — ${config.projectName}
+
+${getCddBlock(config)}
+
+### For Cline
+- Always research docs-canonical/ before suggesting changes
+- Show what docs you checked before proposing code
+- Flag any drift from canonical docs
+
+---
+
+${agentsContent}
+`;
+}
+
+function generateWindsurfRules(agentsContent, config) {
+  return `# Windsurf Rules — ${config.projectName}
+
+${getCddBlock(config)}
+
+---
+
+${agentsContent}
+`;
+}
+
+function generateClaudeMd(agentsContent, config) {
+  return `# CLAUDE.md — ${config.projectName}
+
+${getCddBlock(config)}
+
+### Pre-Implementation Checklist
+Before suggesting any code changes:
+\`\`\`
+1. Docs reviewed: [which canonical docs you checked]
+2. Existing patterns: [similar code found]
+3. Proposed approach: [your plan]
+4. Files to change: [list]
+5. Risk level: LOW | MEDIUM | HIGH
+\`\`\`
+
+---
+
+${agentsContent}
+`;
+}
+
+function generateGeminiSettings(agentsContent, config) {
+  return JSON.stringify({
+    projectName: config.projectName,
+    methodology: 'Canonical-Driven Development (CDD)',
+    canonicalDocs: [
+      'docs-canonical/ARCHITECTURE.md',
+      'docs-canonical/DATA-MODEL.md',
+      'docs-canonical/SECURITY.md',
+      'docs-canonical/TEST-SPEC.md',
+      'docs-canonical/ENVIRONMENT.md',
+    ],
+    rules: [
+      'Read canonical docs before suggesting code changes',
+      'Add // DRIFT: comments for deviations',
+      'Update CHANGELOG.md for every change',
+      'Log drift in DRIFT-LOG.md',
+    ],
+  }, null, 2);
+}

package/cli/commands/audit.mjs

@@ -0,0 +1,92 @@
+/**
+ * Audit Command — Scan project, report what CDD docs exist or are missing
+ * Now uses the full documentTypes config to show ALL docs with categories.
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { c } from '../docguard.mjs';
+
+export function runAudit(projectDir, config, flags) {
+  console.log(`${c.bold}📋 DocGuard Audit — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+
+  const results = { found: 0, missing: 0, optional: 0, total: 0, details: [] };
+
+  // Use documentTypes from config (all 16 doc types with required/optional)
+  const docTypes = config.documentTypes || {};
+
+  // Group by category
+  const categories = {};
+  for (const [filePath, meta] of Object.entries(docTypes)) {
+    const cat = meta.category || 'other';
+    if (!categories[cat]) categories[cat] = [];
+    categories[cat].push({ filePath, ...meta });
+  }
+
+  // Category display names and order
+  const categoryLabels = {
+    canonical: '📘 Canonical Documentation (Design Intent)',
+    implementation: '📗 Implementation Documentation (Current State)',
+    agent: '🤖 Agent Instructions',
+    tracking: '📑 Change Tracking',
+  };
+
+  const categoryOrder = ['canonical', 'implementation', 'agent', 'tracking'];
+
+  for (const cat of categoryOrder) {
+    const docs = categories[cat];
+    if (!docs || docs.length === 0) continue;
+
+    console.log(`${c.bold}  ${categoryLabels[cat] || cat}${c.reset}`);
+
+    for (const doc of docs) {
+      const fullPath = resolve(projectDir, doc.filePath);
+      const exists = existsSync(fullPath);
+
+      if (exists) {
+        results.found++;
+        results.total++;
+        results.details.push({ file: doc.filePath, status: 'found', required: doc.required });
+        console.log(`    ${c.green}✅${c.reset} ${doc.filePath} ${c.dim}— ${doc.description}${c.reset}`);
+      } else if (doc.required) {
+        results.missing++;
+        results.total++;
+        results.details.push({ file: doc.filePath, status: 'missing', required: true });
+        console.log(`    ${c.red}❌${c.reset} ${doc.filePath} ${c.dim}— ${doc.description}${c.reset} ${c.red}(required)${c.reset}`);
+      } else {
+        results.optional++;
+        results.details.push({ file: doc.filePath, status: 'optional', required: false });
+        if (flags.verbose) {
+          console.log(`    ${c.dim}○  ${doc.filePath} — ${doc.description} (optional)${c.reset}`);
+        }
+      }
+    }
+    console.log('');
+  }
+
+  // Score (only required files)
+  const requiredTotal = results.found + results.missing;
+  const pct = requiredTotal === 0 ? 100 : Math.round((results.found / requiredTotal) * 100);
+  const scoreColor = pct >= 80 ? c.green : pct >= 50 ? c.yellow : c.red;
+
+  console.log(`${c.bold}  ─────────────────────────────────────${c.reset}`);
+  console.log(`  ${c.bold}Required:${c.reset} ${scoreColor}${results.found - (results.found - requiredTotal + results.missing)}/${requiredTotal} files (${pct}%)${c.reset}`);
+
+  // Show optional count
+  if (!flags.verbose && results.optional > 0) {
+    console.log(`  ${c.dim}Optional: ${results.optional} not present (use --verbose to see all)${c.reset}`);
+  }
+
+  if (results.missing > 0) {
+    console.log(`\n  ${c.yellow}💡 Run ${c.cyan}docguard init${c.yellow} to create missing docs from templates.${c.reset}`);
+    console.log(`  ${c.yellow}💡 Run ${c.cyan}docguard generate${c.yellow} to auto-fill docs from your codebase.${c.reset}`);
+  } else {
+    console.log(`\n  ${c.green}🎉 All required CDD documentation present!${c.reset}`);
+    console.log(`  ${c.dim}Run ${c.cyan}docguard guard${c.dim} to validate content alignment.${c.reset}`);
+    console.log(`  ${c.dim}Run ${c.cyan}docguard score${c.dim} to check your CDD maturity.${c.reset}`);
+  }
+
+  console.log('');
+  return results;
+}

package/cli/commands/badge.mjs

@@ -0,0 +1,72 @@
+/**
+ * Badge Command — Generate shields.io badge URLs and markdown for CDD score
+ * Outputs badge markdown or JSON for README, CI, and dashboards.
+ */
+
+import { c } from '../docguard.mjs';
+import { runScoreInternal } from './score.mjs';
+
+export function runBadge(projectDir, config, flags) {
+  console.log(`${c.bold}🏷️  DocGuard Badge — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+
+  // Get score internally
+  const scoreData = runScoreInternal(projectDir, config);
+  const score = scoreData.score;
+  const grade = scoreData.grade;
+
+  // Determine badge color
+  let color;
+  if (score >= 90) color = 'brightgreen';
+  else if (score >= 80) color = 'green';
+  else if (score >= 70) color = 'yellowgreen';
+  else if (score >= 60) color = 'yellow';
+  else if (score >= 50) color = 'orange';
+  else color = 'red';
+
+  // Shields.io badge URL
+  const badgeUrl = `https://img.shields.io/badge/CDD_Score-${score}%2F100_(${grade})-${color}`;
+  const badgeMarkdown = `![CDD Score](${badgeUrl})`;
+
+  // Separate badge for project type
+  const projectType = config.projectType || 'unknown';
+  const typeBadgeUrl = `https://img.shields.io/badge/type-${projectType}-blue`;
+  const typeBadgeMarkdown = `![Type](${typeBadgeUrl})`;
+
+  // DocGuard badge
+  const sgBadgeUrl = `https://img.shields.io/badge/guarded_by-DocGuard-cyan`;
+  const sgBadgeMarkdown = `![DocGuard](${sgBadgeUrl})`;
+
+  if (flags.format === 'json') {
+    const result = {
+      score,
+      grade,
+      color,
+      projectType,
+      badges: {
+        score: { url: badgeUrl, markdown: badgeMarkdown },
+        type: { url: typeBadgeUrl, markdown: typeBadgeMarkdown },
+        docguard: { url: sgBadgeUrl, markdown: sgBadgeMarkdown },
+      },
+      readmeSnippet: `${badgeMarkdown} ${typeBadgeMarkdown} ${sgBadgeMarkdown}`,
+    };
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  // Display badges
+  console.log(`  ${c.bold}Score Badge:${c.reset}`);
+  console.log(`    ${c.cyan}${badgeMarkdown}${c.reset}\n`);
+
+  console.log(`  ${c.bold}Type Badge:${c.reset}`);
+  console.log(`    ${c.cyan}${typeBadgeMarkdown}${c.reset}\n`);
+
+  console.log(`  ${c.bold}DocGuard Badge:${c.reset}`);
+  console.log(`    ${c.cyan}${sgBadgeMarkdown}${c.reset}\n`);
+
+  console.log(`  ${c.bold}README snippet:${c.reset}`);
+  console.log(`    ${c.dim}Add this to the top of your README.md:${c.reset}\n`);
+  console.log(`    ${badgeMarkdown} ${typeBadgeMarkdown} ${sgBadgeMarkdown}`);
+
+  console.log('');
+}

package/cli/commands/ci.mjs

@@ -0,0 +1,80 @@
+/**
+ * CI Command — Single command for CI/CD pipelines
+ * Uses runGuardInternal directly (no subprocess) for reliability.
+ *
+ * Exit codes:
+ *   0 = All pass, score meets threshold
+ *   1 = Guard errors or score below threshold
+ *   2 = Guard warnings only
+ */
+
+import { c } from '../docguard.mjs';
+import { runGuardInternal } from './guard.mjs';
+import { runScoreInternal } from './score.mjs';
+
+export function runCI(projectDir, config, flags) {
+  const threshold = parseInt(flags.threshold || '0', 10);
+  const failOnWarning = flags.failOnWarning || false;
+  const isJson = flags.format === 'json';
+
+  if (!isJson) {
+    console.log(`${c.bold}🔄 DocGuard CI — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
+    if (threshold > 0) console.log(`${c.dim}   Score threshold: ${threshold}${c.reset}`);
+    console.log('');
+  }
+
+  // ── Run guard (internal — no subprocess) ──
+  const guardData = runGuardInternal(projectDir, config);
+  const hasErrors = guardData.errors > 0;
+  const hasWarnings = guardData.warnings > 0;
+
+  // ── Get score ──
+  const scoreData = runScoreInternal(projectDir, config);
+
+  // ── Output ──
+  if (isJson) {
+    const result = {
+      project: config.projectName,
+      profile: config.profile || 'standard',
+      projectType: config.projectType || 'unknown',
+      score: scoreData.score,
+      grade: scoreData.grade,
+      guard: {
+        passed: guardData.passed,
+        total: guardData.total,
+        status: guardData.status,
+        validators: guardData.validators.filter(v => v.status !== 'skipped'),
+      },
+      threshold,
+      thresholdMet: threshold <= 0 || scoreData.score >= threshold,
+      status: hasErrors ? 'FAIL' : hasWarnings ? 'WARN' : 'PASS',
+      timestamp: new Date().toISOString(),
+    };
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    // Text output
+    const guardStatus = hasErrors
+      ? `${c.red}❌ FAIL${c.reset}`
+      : hasWarnings
+      ? `${c.yellow}⚠️  WARN${c.reset}`
+      : `${c.green}✅ PASS${c.reset}`;
+
+    console.log(`  ${c.bold}Guard:${c.reset}  ${guardStatus}  (${guardData.passed}/${guardData.total})`);
+    console.log(`  ${c.bold}Score:${c.reset}  ${scoreData.score}/100 (${scoreData.grade})`);
+
+    if (threshold > 0) {
+      const met = scoreData.score >= threshold;
+      console.log(`  ${c.bold}Threshold:${c.reset}  ${met ? `${c.green}✅ ≥${threshold}` : `${c.red}❌ <${threshold}`}${c.reset}`);
+    }
+
+    console.log('');
+  }
+
+  // Exit code determination
+  if (hasErrors) process.exit(1);
+  if (threshold > 0 && scoreData.score < threshold) process.exit(1);
+  if (failOnWarning && hasWarnings) process.exit(1);
+  if (hasWarnings) process.exit(2);
+  process.exit(0);
+}