docguard-cli 0.7.3 → 0.8.2

package/README.md

@@ -81,6 +81,27 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 
 ---
 
+## Usage
+
+```bash
+# Initialize CDD docs for your project
+npx docguard-cli init
+
+# Reverse-engineer docs from existing code
+npx docguard-cli generate
+
+# Validate project — use as CI gate
+npx docguard-cli guard
+
+# Get AI-actionable fix prompts
+npx docguard-cli diagnose
+
+# Check CDD maturity score
+npx docguard-cli score
+```
+
+---
+
 ## 13 Commands
 
 ### 🔮 Generate — Reverse-engineer docs from code
@@ -202,7 +223,7 @@ $ npx docguard-cli guard
 
 ---
 
-## 9 Validators
+## 14 Validators
 
 | # | Validator | What It Checks | Default |
 |---|-----------|---------------|---------| 
@@ -213,8 +234,15 @@ $ npx docguard-cli guard
 | 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
 | 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
 | 7 | **Environment** | Env vars documented, .env.example exists | ✅ On |
-| 8 | **Security** | No hardcoded secrets in source code | ❌ Off |
-| 9 | **Architecture** | Imports follow layer boundaries | ❌ Off |
+| 8 | **Security** | No hardcoded secrets in source code | ✅ On |
+| 9 | **Architecture** | Imports follow layer boundaries | ✅ On |
+| 10 | **Freshness** | Docs not stale relative to code changes | ✅ On |
+| 11 | **Traceability** | Canonical docs linked to source code | ✅ On |
+| 12 | **Docs-Diff** | Code artifacts match documented entities | ✅ On |
+| 13 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
+| 14 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
+| 15 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
+| 16 | **Docs-Sync** | Source files have matching doc entries | ✅ On |
 
 ---
 

package/cli/commands/agents.mjs

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const AGENT_TARGETS = {
   cursor: {

package/cli/commands/badge.mjs

@@ -3,7 +3,7 @@
  * Outputs badge markdown or JSON for README, CI, and dashboards.
  */
 
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { runScoreInternal } from './score.mjs';
 
 export function runBadge(projectDir, config, flags) {

package/cli/commands/ci.mjs

@@ -8,7 +8,7 @@
  *   2 = Guard warnings only
  */
 
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
 

package/cli/commands/diagnose.mjs

@@ -13,11 +13,12 @@
  *   --format prompt  Full AI-ready prompt (all issues combined)
  */
 
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
 import { existsSync, readFileSync, mkdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 
 // Map validator failures to the right fix --doc target
@@ -103,16 +104,16 @@ export function runDiagnose(projectDir, config, flags) {
   // ── Step 2: Collect issues ──
   let issues = collectIssues(guardData);
 
-  // ── Step 3: Auto-fix what we can (unless --no-fix) ──
-  const shouldAutoFix = !flags.noFix && flags.format !== 'json';
-  if (shouldAutoFix && issues.length > 0) {
+  // ── Step 3: Auto-fix (only with --auto flag) or suggest fixes ──
+  const shouldAutoFix = flags.auto && flags.format !== 'json';
+  if (issues.length > 0) {
     const autoFixable = issues.filter(i => i.autoFixable);
     const hasStructural = issues.some(i => i.validator === 'Structure');
 
-    if (hasStructural || autoFixable.length > 0) {
+    if (shouldAutoFix && (hasStructural || autoFixable.length > 0)) {
       // Run init to create missing files
       try {
-        const cliPath = resolve(import.meta.dirname, '..', 'docguard.mjs');
+        const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
         execSync(`node "${cliPath}" init --dir "${projectDir}"`, {
           encoding: 'utf-8',
           stdio: 'pipe',
@@ -121,7 +122,7 @@ export function runDiagnose(projectDir, config, flags) {
 
       // Run generate to fill in content
       try {
-        const cliPath = resolve(import.meta.dirname, '..', 'docguard.mjs');
+        const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
         execSync(`node "${cliPath}" generate --dir "${projectDir}" --force`, {
           encoding: 'utf-8',
           stdio: 'pipe',
@@ -138,6 +139,12 @@ export function runDiagnose(projectDir, config, flags) {
           console.log(`  ${c.green}⚡ Auto-fixed ${fixedCount} issue(s)${c.reset} (created/regenerated docs)\n`);
         }
       }
+    } else if (!shouldAutoFix && (hasStructural || autoFixable.length > 0) && (!flags.format || flags.format === 'text')) {
+      // Suggest-only mode: tell user what they can do
+      console.log(`  ${c.yellow}💡 ${autoFixable.length + (hasStructural ? 1 : 0)} issue(s) can be auto-fixed.${c.reset} Run with ${c.cyan}--auto${c.reset} to create/regenerate docs, or manually:`);
+      if (hasStructural) console.log(`     ${c.dim}docguard init --dir .${c.reset}`);
+      if (autoFixable.length > 0) console.log(`     ${c.dim}docguard generate --dir . --force${c.reset}`);
+      console.log('');
     }
   }
 
@@ -340,7 +347,7 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags) {
   lines.push('VALIDATION:');
   lines.push('After making all fixes, run: docguard guard');
   lines.push('Expected result: All checks pass (0 errors, 0 warnings)');
-  lines.push(`Target score: ≥${scoreData.score + 5}/100`);
+  lines.push(`Target score: ≥${Math.min(scoreData.score + 5, 100)}/100`);
 
   // Agent-aware: add explicit checklist for basic-tier agents
   if (agentTier === 'basic') {

package/cli/commands/diff.mjs

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -99,10 +99,13 @@ function diffRoutes(dir) {
 
   // Extract route-like patterns from ARCHITECTURE.md
   const docRoutes = new Set();
-  const routeRegex = /(?:\/api\/\S+|GET|POST|PUT|DELETE|PATCH)\s+(\S+)/gi;
+  const routeRegex = /(?:\/api\/\S+|(?:GET|POST|PUT|DELETE|PATCH)\s+(\/\S+))/gi;
   let match;
   while ((match = routeRegex.exec(content)) !== null) {
-    docRoutes.add(match[1] || match[0]);
+    const route = match[1] || match[0];
+    // Skip markdown table syntax and non-route content
+    if (route.startsWith('|') || route.startsWith('(') || route.length < 3) continue;
+    docRoutes.add(route);
   }
 
   // Also check for paths in tables
@@ -183,6 +186,14 @@ function diffEntities(dir) {
     'weighted', 'method', 'provider', 'token', 'expiry', 'role',
     'permissions', 'secret', 'rotation', 'access', 'variable', 'tool',
     'command', 'run', 'component', 'responsibility', 'location', 'tests',
+    // Data types — common in table schemas, not entity names
+    'string', 'boolean', 'number', 'integer', 'float', 'double', 'decimal',
+    'array', 'object', 'null', 'undefined', 'enum', 'varchar', 'text',
+    'timestamp', 'uuid', 'bigint', 'serial', 'json', 'jsonb', 'blob',
+    'char', 'date', 'time', 'datetime', 'binary', 'bit', 'money',
+    // Common table headers and template words
+    'true', 'false', 'header', 'checks', 'project', 'count', 'grade',
+    'breakdown', 'issuecount', 'autofixable', 'projectname', 'projecttype',
   ]);
   while ((match = tableRegex.exec(content)) !== null) {
     const name = match[1];

package/cli/commands/fix.mjs

@@ -14,9 +14,10 @@
  */
 
 import { existsSync, readFileSync, mkdirSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import { resolve, basename, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
-import { c } from '../docguard.mjs';
+import { fileURLToPath } from 'node:url';
+import { c } from '../shared.mjs';
 
 // ── Document Quality Definitions ───────────────────────────────────────────
 // What each doc SHOULD contain, and what to look for in the codebase
@@ -471,7 +472,7 @@ function autoFixIssues(projectDir, config, issues) {
   }
 
   try {
-    const cliPath = resolve(import.meta.dirname, '..', 'docguard.mjs');
+    const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
     execSync(`node ${cliPath} init --dir "${projectDir}"`, {
       encoding: 'utf-8',
       stdio: 'pipe',

package/cli/commands/generate.mjs

@@ -7,7 +7,7 @@
 
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync } from 'node:fs';
 import { resolve, join, extname, basename, relative, dirname } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { detectDocTools } from '../scanners/doc-tools.mjs';
 import { scanRoutesDeep } from '../scanners/routes.mjs';
 import { scanSchemasDeep, generateERDiagram } from '../scanners/schemas.mjs';
@@ -318,7 +318,7 @@ function scanProject(dir) {
     }
   });
 
-  // Find tests
+  // Find tests — top-level test dirs
   ['tests', 'test', '__tests__', 'spec', 'e2e'].forEach(testDir => {
     const fullDir = resolve(dir, testDir);
     if (existsSync(fullDir)) {
@@ -329,6 +329,55 @@ function scanProject(dir) {
     }
   });
 
+  // Find co-located tests: src/**/__tests__/ and src/**/*.test.* / src/**/*.spec.*
+  const srcDir = resolve(dir, 'src');
+  if (existsSync(srcDir)) {
+    walkDir(srcDir, (filePath) => {
+      const rel = relative(dir, filePath);
+      const isTestDir = rel.includes('__tests__') || rel.includes('__test__');
+      const isTestFile = /\.(test|spec)\.[^.]+$/.test(rel);
+      if ((isTestDir || isTestFile) && !scan.tests.includes(rel)) {
+        scan.tests.push(rel);
+      }
+    });
+  }
+
+  // Read vitest/jest config for custom test patterns
+  const testConfigs = ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mts', 'jest.config.ts', 'jest.config.js'];
+  for (const cfgFile of testConfigs) {
+    const cfgPath = resolve(dir, cfgFile);
+    if (existsSync(cfgPath)) {
+      try {
+        const cfgContent = readFileSync(cfgPath, 'utf-8');
+        // Extract include patterns like: include: ['src/**/*.test.ts']
+        const includeMatch = cfgContent.match(/include\s*:\s*\[([^\]]+)\]/);
+        if (includeMatch) {
+          // Parse the test root from the pattern (e.g., 'src/**/*.test.ts' → 'src')
+          const patterns = includeMatch[1].match(/['"]([^'"]+)['"]/g);
+          if (patterns) {
+            for (const p of patterns) {
+              const pattern = p.replace(/['"]|\s/g, '');
+              // Extract root dir from glob (e.g., 'src/**/*.test.ts' → 'src')
+              const rootDir = pattern.split('/')[0];
+              if (rootDir && rootDir !== '**' && rootDir !== '*') {
+                const fullDir = resolve(dir, rootDir);
+                if (existsSync(fullDir)) {
+                  walkDir(fullDir, (filePath) => {
+                    const rel = relative(dir, filePath);
+                    if (/\.(test|spec)\.[^.]+$/.test(rel) && !scan.tests.includes(rel)) {
+                      scan.tests.push(rel);
+                    }
+                  });
+                }
+              }
+            }
+          }
+        }
+      } catch { /* config parse may fail */ }
+      break; // Use first found config
+    }
+  }
+
   // Find components
   ['src/components', 'components', 'src/ui'].forEach(compDir => {
     const fullDir = resolve(dir, compDir);
@@ -367,6 +416,15 @@ function scanProject(dir) {
   // Count files and lines
   countFilesAndLines(dir, scan);
 
+  // ── Filter test files out of source lists ──
+  // Test files (*.test.*, *.spec.*, __tests__/) should NOT appear as source files
+  const isTestFile = (f) => f.includes('__tests__') || f.includes('__test__') || /\.(test|spec)\.[^.]+$/.test(f);
+  scan.routes = scan.routes.filter(f => !isTestFile(f));
+  scan.models = scan.models.filter(f => !isTestFile(f));
+  scan.services = scan.services.filter(f => !isTestFile(f));
+  scan.components = scan.components.filter(f => !isTestFile(f));
+  scan.middlewares = scan.middlewares.filter(f => !isTestFile(f));
+
   return scan;
 }
 

package/cli/commands/guard.mjs

@@ -7,7 +7,7 @@
  *   runGuardInternal() → returns data, no side effects (for diagnose, ci)
  */
 
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { validateStructure, validateDocSections } from '../validators/structure.mjs';
 import { validateDrift } from '../validators/drift.mjs';
 import { validateChangelog } from '../validators/changelog.mjs';
@@ -18,6 +18,10 @@ import { validateDocsSync } from '../validators/docs-sync.mjs';
 import { validateArchitecture } from '../validators/architecture.mjs';
 import { validateFreshness } from '../validators/freshness.mjs';
 import { validateTraceability } from '../validators/traceability.mjs';
+import { validateDocsDiff } from '../validators/docs-diff.mjs';
+import { validateMetadataSync } from '../validators/metadata-sync.mjs';
+import { validateMetricsConsistency } from '../validators/metrics-consistency.mjs';
+import { validateDocsCoverage } from '../validators/docs-coverage.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -50,6 +54,10 @@ export function runGuardInternal(projectDir, config) {
       return { errors, warnings, passed, total: passed + warnings.length + errors.length };
     }},
     { key: 'traceability', name: 'Traceability', fn: () => validateTraceability(projectDir, config) },
+    { key: 'docsDiff', name: 'Docs-Diff', fn: () => validateDocsDiff(projectDir, config) },
+    { key: 'metadataSync', name: 'Metadata-Sync', fn: () => validateMetadataSync(projectDir, config) },
+    { key: 'docsCoverage', name: 'Docs-Coverage', fn: () => validateDocsCoverage(projectDir, config) },
+    // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
   for (const { key, name, fn } of validatorMap) {
@@ -82,6 +90,21 @@ export function runGuardInternal(projectDir, config) {
     }
   }
 
+  // ── Metrics-Consistency runs AFTER all other validators (needs their results) ──
+  if (validators.metricsConsistency !== false) {
+    try {
+      const result = validateMetricsConsistency(projectDir, config, results);
+      const hasErrors = result.errors.length > 0;
+      const hasWarnings = result.warnings.length > 0;
+      const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
+      const ratio = result.total > 0 ? result.passed / result.total : 1;
+      const quality = hasErrors ? 'LOW' : hasWarnings ? 'MEDIUM' : ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
+      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', status, quality });
+    } catch (err) {
+      results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
+    }
+  }
+
   const activeResults = results.filter(r => r.status !== 'skipped');
   const totalErrors = activeResults.reduce((sum, r) => sum + r.errors.length, 0);
   const totalWarnings = activeResults.reduce((sum, r) => sum + r.warnings.length, 0);
@@ -169,6 +192,12 @@ export function runGuard(projectDir, config, flags) {
     console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to get AI fix prompts.${c.reset}`);
   }
 
+  // Badge snippet
+  const pct = data.total > 0 ? Math.round((data.passed / data.total) * 100) : 0;
+  const bColor = pct >= 90 ? 'brightgreen' : pct >= 70 ? 'green' : pct >= 50 ? 'yellow' : 'red';
+  const badgeUrl = `https://img.shields.io/badge/CDD_Guard-${data.passed}%2F${data.total}_passed-${bColor}`;
+  console.log(`\n  ${c.dim}📎 Badge: ![CDD Guard](${badgeUrl})${c.reset}`);
+
   console.log('');
 
   if (data.errors > 0) process.exit(1);

package/cli/commands/hooks.mjs

@@ -5,7 +5,7 @@
 
 import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const HOOKS = {
   'pre-commit': {