docguard-cli 0.9.11 → 0.10.0

package/cli/validators/test-spec.mjs

@@ -5,6 +5,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { resolveSourceRoots } from '../shared-source.mjs';
 
 export function validateTestSpec(projectDir, config) {
   const results = { name: 'test-spec', errors: [], warnings: [], passed: 0, total: 0 };
@@ -43,6 +44,9 @@ export function validateTestSpec(projectDir, config) {
       // Skip template/example rows and italic placeholder rows
       if (sourceFile.startsWith('<!--') || sourceFile === 'Source File' || sourceFile.startsWith('*')) continue;
 
+      // Author-declared gaps (❌/⚠️) are surfaced as warnings. A ✅ glyph is the
+      // author's CLAIM, not proof — it is NOT counted as a pass. The real pass
+      // comes from the file-existence checks below (code truth, not the glyph).
       if (status && status.includes('❌')) {
         results.total++;
         results.warnings.push(
@@ -53,9 +57,6 @@ export function validateTestSpec(projectDir, config) {
         results.warnings.push(
           `TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`
         );
-      } else if (status && status.includes('✅')) {
-        results.total++;
-        results.passed++;
       }
 
       // ── File existence checks ───────────────────────────────────────
@@ -122,34 +123,41 @@ export function validateTestSpec(projectDir, config) {
           results.warnings.push(
             `E2E Journey #${num} (${journey}) — missing test: ${testFile}`
           );
-        } else if (status && status.includes('✅')) {
+          continue;
+        }
+
+        // For a ✅ journey, verify the referenced test file actually exists
+        // rather than trusting the glyph.
+        const cleanTest = testFile ? testFile.replace(/`/g, '').trim() : '';
+        if (cleanTest && cleanTest !== '—' && !cleanTest.includes('N/A')) {
           results.total++;
-          results.passed++;
+          if (existsSync(resolve(projectDir, cleanTest))) {
+            results.passed++;
+          } else {
+            results.warnings.push(
+              `E2E Journey #${num} (${journey}) marked ✅ but test file not found: ${cleanTest}`
+            );
+          }
         }
       }
     }
   }
 
-  // If no test spec entries parsed, check if tests exist anywhere
+  // If TEST-SPEC.md declared no service-to-test mappings, there is nothing to
+  // verify against. Do NOT manufacture a 1/1 pass just because tests exist
+  // somewhere — that rendered a confident green ✅ for a doc that mapped nothing.
   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))
     );
 
-    // 2. Check co-located tests (src/**/__tests__/, src/**/*.test.*)
+    // 2. Check co-located tests (honors config.sourceRoot + workspaces)
     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;
-        }
+      for (const rootPath of resolveSourceRoots(projectDir, config)) {
+        if (hasTestFilesRecursive(rootPath)) { hasColocated = true; break; }
       }
     }
 
@@ -161,7 +169,8 @@ export function validateTestSpec(projectDir, config) {
     }
 
     if (hasTestDir || hasColocated || hasConfigTests) {
-      results.passed = 1;
+      // Tests exist but the spec maps none of them → not applicable, not a pass.
+      results.note = 'TEST-SPEC.md declares no service-to-test mappings';
     } else {
       results.warnings.push(
         'No test directory or co-located test files found. ' +

package/cli/validators/todo-tracking.mjs

@@ -67,7 +67,7 @@ export function validateTodoTracking(projectDir, config) {
   results.passed += skipResults.passed;
   results.total += skipResults.total;
 
-  // ── Part 2: Untracked TODOs/FIXMEs ──
+  // ── Part 2: Untracked Annotations ──
   const todoResults = checkUntrackedTodos(projectDir, config);
   results.errors.push(...todoResults.errors);
   results.warnings.push(...todoResults.warnings);
@@ -105,6 +105,10 @@ function checkSkippedTests(projectDir, config) {
     let content;
     try { content = readFileSync(fullPath, 'utf-8'); } catch { continue; }
 
+    // Fast early-return: skip expensive string split if no skip patterns exist
+    const hasSkip = SKIP_PATTERNS.some(p => p.test(content));
+    if (!hasSkip) continue;
+
     const lines = content.split('\n');
 
     for (let i = 0; i < lines.length; i++) {
@@ -151,7 +155,7 @@ function checkSkippedTests(projectDir, config) {
   return { errors, warnings, passed, total };
 }
 
-// ──── Untracked TODOs ──────────────────────────────────────────────────────
+// ──── Untracked Annotations ────────────────────────────────────────────────
 
 /**
  * Scan source files for TODO/FIXME annotations and check if they appear
@@ -183,15 +187,19 @@ function checkUntrackedTodos(projectDir, config) {
   for (const todo of todos) {
     // Check if the TODO is tracked in documentation
     // Improved matching: check full text AND file location context
+    // ⚡ Bolt: Precompute string lowercasing and trimming once per TODO
+    // instead of inside the trackingContent.some loop
+    const todoTextLower = todo.text.toLowerCase().trim();
+    const searchText = todoTextLower.length > 20
+      ? todoTextLower.substring(0, 40)
+      : todoTextLower;
+
     const isTracked = trackingContent.some(doc => {
       const content = doc.content;
-      const contentLower = content.toLowerCase();
-      const todoTextLower = todo.text.toLowerCase().trim();
+      // ⚡ Bolt: use the precomputed lowercased content
+      const contentLower = doc.contentLower;
 
       // Match 1: Full TODO text appears in the doc (at least 20 chars or full text)
-      const searchText = todoTextLower.length > 20
-        ? todoTextLower.substring(0, 40)
-        : todoTextLower;
       const hasText = contentLower.includes(searchText);
 
       // Match 2: File location appears nearby in the doc
@@ -240,7 +248,9 @@ function loadTrackingDocs(projectDir, config) {
     const fullPath = resolve(projectDir, file);
     if (existsSync(fullPath)) {
       try {
-        docs.push({ file, content: readFileSync(fullPath, 'utf-8') });
+        const content = readFileSync(fullPath, 'utf-8');
+        // ⚡ Bolt: Precompute lowercased content during file load to avoid N*M overhead
+        docs.push({ file, content, contentLower: content.toLowerCase() });
       } catch { /* ignore */ }
     }
   }
@@ -306,6 +316,9 @@ function findTodos(rootDir, dir, todos, config) {
       let content;
       try { content = readFileSync(full, 'utf-8'); } catch { continue; }
 
+      // Fast early-return: skip expensive string split if no TODO patterns exist
+      if (!TODO_PATTERN.test(content)) continue;
+
       const lines = content.split('\n');
 
       for (let i = 0; i < lines.length; i++) {

package/cli/validators/traceability.mjs

@@ -130,13 +130,16 @@ export function validateTraceability(projectDir, config) {
     }
 
     // Count matching source files
-    let totalSources = 0;
+    // ⚡ Bolt: Fast early return using .some() instead of .filter()
+    let hasSource = false;
     for (const pattern of traceInfo.sourcePatterns) {
-      const matches = projectFiles.filter(f => pattern.glob.test(f));
-      totalSources += matches.length;
+      if (projectFiles.some(f => pattern.glob.test(f))) {
+        hasSource = true;
+        break;
+      }
     }
 
-    if (totalSources > 0) {
+    if (hasSource) {
       passed++;
     } else {
       warnings.push(`${docName} — exists but no matching source code found (unlinked doc)`);
@@ -186,6 +189,46 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
     : DEFAULT_REQ_PATTERNS;
 
   // ── Step 1: Collect requirement IDs from documentation ──
+  const reqIds = collectRequirementIds(projectDir, config, patterns);
+
+  // If no requirement IDs found, silently pass — this project doesn't use them
+  if (reqIds.size === 0) {
+    return { errors, warnings, passed, total };
+  }
+
+  // ── Step 2: Scan test files for requirement ID references ──
+  const testRefs = scanTestFilesForReferences(projectDir, projectFiles, patterns);
+
+  // ── Step 3: Report traceability results ──
+
+  // Check each documented requirement has at least one test reference
+  for (const [reqId, location] of reqIds) {
+    total++;
+    if (testRefs.has(reqId)) {
+      passed++;
+    } else {
+      warnings.push(
+        `Requirement ${reqId} (${location.file}:${location.line}) has no test coverage. ` +
+        `Add @req ${reqId} comment to the test that verifies this requirement`
+      );
+    }
+  }
+
+  // Check for orphaned test refs (tests referencing non-existent requirements)
+  for (const [reqId, refs] of testRefs) {
+    if (!reqIds.has(reqId)) {
+      total++;
+      warnings.push(
+        `Test references ${reqId} (${refs[0].file}:${refs[0].line}) but no requirement ` +
+        `with this ID exists in documentation. Remove the reference or add the requirement to docs`
+      );
+    }
+  }
+
+  return { errors, warnings, passed, total };
+}
+
+function collectRequirementIds(projectDir, config, patterns) {
   const reqIds = new Map(); // reqId → { file, line }
   const docSearchPaths = getRequirementDocPaths(projectDir, config);
 
@@ -193,6 +236,11 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
     if (!existsSync(docPath)) continue;
 
     const content = readFileSync(docPath, 'utf-8');
+
+    // Fast early-return: skip expensive string split if no requirement patterns exist
+    const hasMatch = patterns.some(p => { p.lastIndex = 0; return p.test(content); });
+    if (!hasMatch) continue;
+
     const lines = content.split('\n');
     const docName = relative(projectDir, docPath);
 
@@ -211,12 +259,10 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
     }
   }
 
-  // If no requirement IDs found, silently pass — this project doesn't use them
-  if (reqIds.size === 0) {
-    return { errors, warnings, passed, total };
-  }
+  return reqIds;
+}
 
-  // ── Step 2: Scan test files for requirement ID references ──
+function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
   const testFiles = projectFiles.filter(f =>
     /\.(test|spec)\.(mjs|cjs|[jt]sx?)$/.test(f) ||
     /__tests__\//.test(f) ||
@@ -231,6 +277,11 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
 
     let content;
     try { content = readFileSync(fullPath, 'utf-8'); } catch { continue; }
+
+    // Fast early-return: skip expensive string split if no requirement patterns exist
+    const hasMatch = patterns.some(p => { p.lastIndex = 0; return p.test(content); });
+    if (!hasMatch) continue;
+
     const lines = content.split('\n');
 
     for (let i = 0; i < lines.length; i++) {
@@ -246,33 +297,7 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
     }
   }
 
-  // ── Step 3: Report traceability results ──
-
-  // Check each documented requirement has at least one test reference
-  for (const [reqId, location] of reqIds) {
-    total++;
-    if (testRefs.has(reqId)) {
-      passed++;
-    } else {
-      warnings.push(
-        `Requirement ${reqId} (${location.file}:${location.line}) has no test coverage. ` +
-        `Add @req ${reqId} comment to the test that verifies this requirement`
-      );
-    }
-  }
-
-  // Check for orphaned test refs (tests referencing non-existent requirements)
-  for (const [reqId, refs] of testRefs) {
-    if (!reqIds.has(reqId)) {
-      total++;
-      warnings.push(
-        `Test references ${reqId} (${refs[0].file}:${refs[0].line}) but no requirement ` +
-        `with this ID exists in documentation. Remove the reference or add the requirement to docs`
-      );
-    }
-  }
-
-  return { errors, warnings, passed, total };
+  return testRefs;
 }
 
 /**

package/commands/docguard.guard.md

@@ -1,5 +1,5 @@
 ---
-description: Run DocGuard guard validation — check project documentation against CDD standards with 19 validators
+description: Run DocGuard guard validation — check project documentation against CDD standards with 20 validators
 handoffs:
   - label: Fix All Issues
     agent: docguard.fix
@@ -23,14 +23,14 @@ Run the DocGuard CLI to validate all documentation against Canonical-Driven Deve
 npx docguard-cli guard
 ```
 
-2. **Parse the output**. Each of the 19 validators reports ✅ (pass), ⚠️ (warning), or ❌ (fail):
+2. **Parse the output**. Each of the 20 validators reports ✅ (pass), ⚠️ (warning), ❌ (fail), or ➖ (N/A — nothing to validate). **A ➖ N/A is NOT a pass**: it means the validator found nothing to check (e.g. no API-REFERENCE.md, no DB schema, no layer boundaries declared). Don't read N/A as "healthy" — read it as "not assessed".
 
    | Validator | What It Checks |
    |-----------|---------------|
    | Structure | Required CDD files exist |
    | Doc Sections | Canonical docs have required sections |
    | Docs-Sync | External doc references are valid |
-   | Drift | Code deviations logged in DRIFT-LOG.md |
+   | Drift-Comments | `// DRIFT:` code comments logged in DRIFT-LOG.md |
    | Changelog | CHANGELOG.md is maintained |
    | Test-Spec | Tests match TEST-SPEC.md rules |
    | Environment | Environment documentation |
@@ -39,6 +39,7 @@ npx docguard-cli guard
    | Freshness | Docs updated within commit window |
    | Traceability | Requirements trace to tests |
    | Docs-Diff | Doc changes match code changes |
+   | API-Surface | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes) |
    | Metadata-Sync | Metadata headers are consistent |
    | Docs-Coverage | All config files documented |
    | Doc-Quality | Readability, IEEE 830 compliance |
@@ -49,7 +50,7 @@ npx docguard-cli guard
 
 3. **Triage findings by severity**:
    - **CRITICAL**: Structure, Security, Test-Spec failures
-   - **HIGH**: Doc Sections, Drift, Changelog, Traceability failures
+   - **HIGH**: Doc Sections, Drift-Comments, Changelog, Traceability, API-Surface (documented-but-absent endpoint) failures
    - **MEDIUM**: Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency warnings
    - **LOW**: TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync warnings
 

package/docs/quickstart.md

@@ -68,7 +68,7 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check (19 validators)
+npx docguard-cli guard        # Pass/fail check (20 validators)
 npx docguard-cli score        # 0-100 maturity score
 ```
 

package/extensions/spec-kit-docguard/README.md

@@ -4,7 +4,7 @@ Enterprise-grade Canonical-Driven Development (CDD) enforcement for [Spec Kit](h
 
 ## Features
 
-- **19 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift, Freshness, and 13 more
+- **20 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, and 13 more
 - **4 AI Skills** — Enterprise-grade AI behavior protocols (not just step-lists)
 - **3 Bash Scripts** — JSON-output orchestration for AI consumption
 - **Workflow Chaining** — YAML handoffs enable guard → fix → review → score flows

package/extensions/spec-kit-docguard/commands/guard.md

@@ -14,7 +14,7 @@ handoffs:
 
 # DocGuard Guard
 
-Validate your project against its canonical documentation. Runs 160+ automated checks across 19 validators.
+Validate your project against its canonical documentation. Runs 160+ automated checks across 20 validators.
 
 ## User Input
 
@@ -31,11 +31,11 @@ You **MUST** consider the user input before proceeding (if not empty).
 npx --yes docguard-cli@latest guard $ARGUMENTS
 ```
 
-2. Parse each validator's result and build a severity-ranked findings table.
+2. Parse each validator's result and build a severity-ranked findings table. Status glyphs: ✅ pass, ⚠️ warning, ❌ fail, ➖ N/A (nothing to validate — NOT a pass; the dimension was not assessed).
 
 3. **Triage by severity**:
    - **CRITICAL**: Structure, Security, Test-Spec failures → fix immediately
-   - **HIGH**: Doc Sections, Drift, Changelog, Traceability → fix before commit
+   - **HIGH**: Doc Sections, Drift-Comments, Changelog, Traceability, API-Surface → fix before commit
    - **MEDIUM**: Freshness, Docs-Coverage, Doc-Quality, Metrics → fix this sprint
    - **LOW**: TODO-Tracking, Schema-Sync, Spec-Kit, Metadata → fix when convenient
 
@@ -43,14 +43,14 @@ npx --yes docguard-cli@latest guard $ARGUMENTS
 
 5. Re-run guard after fixes. Iterate until all checks pass (max 3 iterations).
 
-## Validators (19 total)
+## Validators (20 total)
 
 | Validator | What It Checks |
 |-----------|---------------|
 | Structure | Required CDD files exist |
 | Doc Sections | Canonical docs have required sections |
 | Docs-Sync | External doc references are valid |
-| Drift | `// DRIFT:` comments have DRIFT-LOG entries |
+| Drift-Comments | `// DRIFT:` comments have DRIFT-LOG entries |
 | Changelog | CHANGELOG.md is maintained |
 | Test-Spec | TEST-SPEC.md matches actual test files |
 | Environment | Environment docs and .env.example exist |
@@ -59,6 +59,7 @@ npx --yes docguard-cli@latest guard $ARGUMENTS
 | Freshness | Docs updated after recent code changes |
 | Traceability | Canonical docs linked to source code |
 | Docs-Diff | Entity/route/field drift between code and docs |
+| API-Surface | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes) |
 | Metadata-Sync | Metadata headers are consistent |
 | Docs-Coverage | All config files documented |
 | Doc-Quality | Readability, IEEE 830 compliance |

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -78,7 +78,8 @@ Classify every non-passing check using this priority matrix:
 
 **HIGH (fix before commit)**:
 - Doc Sections failures (missing required sections)
-- Drift detection (undocumented code deviations)
+- Drift-Comments (a `// DRIFT:` comment without a DRIFT-LOG.md entry)
+- API-Surface (API-REFERENCE.md documents an endpoint that no longer exists in code)
 - Changelog gaps
 - Traceability breaks
 
@@ -138,7 +139,7 @@ For each finding, provide a **specific, actionable fix** — not "fix the issue"
 
 Based on the triage results:
 
-- **If all PASS**: "All 19 validators passed. Project is CDD-compliant. Ready to commit."
+- **If all PASS**: "All 20 validators passed. Project is CDD-compliant. Ready to commit."
 - **If only MEDIUM/LOW warnings**: "Non-blocking warnings found. Safe to commit, but consider running `/docguard.fix` for automated remediation."
 - **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next."
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.9.11",
+  "version": "0.10.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {

package/templates/commands/docguard.guard.md

@@ -1,5 +1,5 @@
 ---
-description: Run DocGuard guard validation — check all 19 validators and fix any issues
+description: Run DocGuard guard validation — check all 20 validators and fix any issues
 handoffs:
   - label: Fix Issues
     agent: docguard.fix
@@ -19,12 +19,12 @@ You are an AI agent enforcing Canonical-Driven Development (CDD) compliance usin
 npx docguard-cli guard
 ```
 
-Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the 19 validators:
+Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the 20 validators:
 
 | Priority | Validators |
 |----------|-----------|
 | CRITICAL | Structure, Security, Test-Spec |
-| HIGH | Doc Sections, Drift, Changelog, Traceability |
+| HIGH | Doc Sections, Drift-Comments, Changelog, Traceability, API-Surface |
 | MEDIUM | Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency |
 | LOW | TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync |