docguard-cli 0.11.1 → 0.11.2

package/cli/commands/diff.mjs

@@ -10,6 +10,8 @@ import { collectPackageJsons, detectDocker, grepEnvUsage, resolveSourceRoots } f
 import { parseApiReferenceDoc, compareEndpoints } from '../scanners/api-doc.mjs';
 import { resolveApiSurface } from '../validators/api-surface.mjs';
 import { collectCodeTests } from '../validators/docs-diff.mjs';
+import { scanSchemasDeep } from '../scanners/schemas.mjs';
+import { detectDocTools } from '../scanners/doc-tools.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -163,22 +165,17 @@ function diffEntities(dir, config = {}) {
     docEntities.add(name.toLowerCase());
   }
 
-  // Find model/entity files in code — monorepo-aware (honors config.sourceRoot/workspaces).
+  // Use the REAL exported entity names from scanSchemasDeep, not file basenames
+  // (a file `dynamoModels.ts` exports `User`/`Order`/etc. — its basename is not
+  // an entity). scanSchemasDeep covers JS ORMs, SQLAlchemy/Pydantic, Diesel,
+  // Go structs, JPA, Rails, and OpenAPI schemas.
+  const docTools = detectDocTools(dir);
+  const schemas = scanSchemasDeep(dir, {}, docTools);
   const codeEntities = new Set();
-  const modelSubdirs = ['models', 'entities', 'schema', 'schemas', 'prisma'];
-  const roots = resolveSourceRoots(dir, config);
-  for (const root of roots) {
-    for (const sub of modelSubdirs) {
-      const modelDir = join(root, sub);
-      if (!existsSync(modelDir)) continue;
-      const files = getFilesRecursive(modelDir);
-      for (const f of files) {
-        const name = basename(f, extname(f)).toLowerCase();
-        // Skip non-entity infrastructure/aggregation filenames.
-        if (CODE_ENTITY_NOISE.has(name)) continue;
-        codeEntities.add(name);
-      }
-    }
+  for (const e of (schemas.entities || [])) {
+    const n = String(e.name || '').toLowerCase();
+    if (!n || CODE_ENTITY_NOISE.has(n)) continue;
+    codeEntities.add(n);
   }
 
   // No code-side entity source (e.g. DynamoDB single-table design with no model
@@ -207,7 +204,8 @@ function diffEnvVars(dir, config = {}) {
 
   // Extract env var names from ENVIRONMENT.md
   const docVars = new Set();
-  const varRegex = /`([A-Z][A-Z0-9_]{2,})`/g;
+  // Reject names ending in `_` (e.g. the literal prefix `VITE_` in prose).
+  const varRegex = /`([A-Z][A-Z0-9_]*[A-Z0-9])`/g;
   let match;
   while ((match = varRegex.exec(content)) !== null) {
     docVars.add(match[1]);
@@ -220,7 +218,7 @@ function diffEnvVars(dir, config = {}) {
     const envExamplePath = resolve(dir, envFile);
     if (existsSync(envExamplePath)) {
       const envContent = readFileSync(envExamplePath, 'utf-8');
-      const envRegex = /^([A-Z][A-Z0-9_]+)\s*=/gm;
+      const envRegex = /^([A-Z][A-Z0-9_]*[A-Z0-9])\s*=/gm;
       while ((match = envRegex.exec(envContent)) !== null) {
         codeVars.add(match[1]);
       }

package/cli/commands/guard.mjs

@@ -194,16 +194,26 @@ export function runGuard(projectDir, config, flags) {
       console.log(`  ${c.yellow}⚠️  ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     }
 
-    if (flags.verbose || v.status === 'fail') {
+    // --show-failing forces enumeration of every error/warning regardless of
+    // overall validator status — useful when a validator passes overall
+    // (passed < total) without surfacing the specific failing checks.
+    const show = flags.verbose || flags.showFailing;
+    if (show || v.status === 'fail') {
       for (const err of v.errors) {
         console.log(`     ${c.red}✗ ${err}${c.reset}`);
       }
     }
-    if (flags.verbose || v.status === 'warn') {
+    if (show || v.status === 'warn') {
       for (const warn of v.warnings) {
         console.log(`     ${c.yellow}⚠ ${warn}${c.reset}`);
       }
     }
+    // If a validator reports passed < total but has no errors/warnings, surface
+    // the gap honestly so users aren't left wondering where the deficit went.
+    if (v.status === 'pass' && v.total > v.passed && v.errors.length === 0 && v.warnings.length === 0) {
+      const gap = v.total - v.passed;
+      console.log(`     ${c.yellow}⚠ ${gap} check(s) did not pass but emitted no message — likely a validator bug. Please file an issue.${c.reset}`);
+    }
   }
 
   // Summary

package/cli/docguard.mjs

@@ -365,6 +365,8 @@ async function main() {
     } else if (args[i] === '--since' && args[i + 1]) {
       flags.since = args[i + 1];
       i++;
+    } else if (args[i] === '--show-failing') {
+      flags.showFailing = true;
     } else if (args[i] === '--doc' && args[i + 1]) {
       flags.doc = args[i + 1];
       i++;

package/cli/ensure-skills.mjs

@@ -54,8 +54,13 @@ export function detectAgentMode(projectDir) {
     '.specify',
     '.github/copilot-instructions.md',
     'CLAUDE.md',
+    'GEMINI.md',
     '.gemini',
     '.agents',
+    '.antigravity',
+    'ANTIGRAVITY.md',
+    '.kiro',
+    '.windsurf',
   ];
 
   for (const signal of llmSignals) {
@@ -105,7 +110,9 @@ export function detectAIAgent(projectDir) {
     { signal: '.claude',                        agent: 'claude' },
     { signal: 'CLAUDE.md',                      agent: 'claude' },
     { signal: '.gemini',                        agent: 'gemini' },
-    { signal: '.agents',                        agent: 'agy' },         // Antigravity
+    { signal: '.agents',                        agent: 'agy' },         // Antigravity (Spec Kit convention)
+    { signal: '.antigravity',                   agent: 'agy' },         // Antigravity (alt convention)
+    { signal: 'ANTIGRAVITY.md',                 agent: 'agy' },         // Antigravity rules file
     { signal: '.github/copilot-instructions.md', agent: 'copilot' },
     { signal: '.windsurf',                      agent: 'windsurf' },
     { signal: '.codex',                         agent: 'codex' },

package/cli/shared-source.mjs

@@ -210,11 +210,16 @@ export function grepEnvUsage(projectDir, config = {}) {
   const roots = resolveSourceRoots(projectDir, config);
   const seen = new Set();
 
+  // Require names to start with a letter and END with a letter/digit (NOT an
+  // underscore) — fixes "VITE_" being captured as a literal env var name.
+  const NAME = '([A-Z][A-Z0-9_]*[A-Z0-9])';
   const patterns = [
-    /process\.env\.([A-Z][A-Z0-9_]+)/g,
-    /process\.env\[\s*['"]([A-Z][A-Z0-9_]+)['"]\s*\]/g,
-    /import\.meta\.env\.([A-Z][A-Z0-9_]+)/g,
+    new RegExp(`process\\.env\\.${NAME}`, 'g'),
+    new RegExp(`process\\.env\\[\\s*['"]${NAME}['"]\\s*\\]`, 'g'),
+    new RegExp(`import\\.meta\\.env\\.${NAME}`, 'g'),
   ];
+  // Vite injects these at build time; they are not user-set env vars.
+  const VITE_INTRINSICS = new Set(['DEV', 'PROD', 'MODE', 'BASE_URL', 'SSR']);
 
   const visit = (filePath) => {
     if (seen.has(filePath)) return;
@@ -225,10 +230,16 @@ export function grepEnvUsage(projectDir, config = {}) {
     let content;
     try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
     if (!content.includes('env')) return;
-    for (const re of patterns) {
+    // patterns[2] is the import.meta.env one — its matches are Vite-injected
+    // when the name is an intrinsic, and must not be reported as user env vars.
+    for (let i = 0; i < patterns.length; i++) {
       let m;
-      const rx = new RegExp(re.source, 'g');
-      while ((m = rx.exec(content)) !== null) names.add(m[1]);
+      const rx = new RegExp(patterns[i].source, 'g');
+      const isViteSource = i === 2;
+      while ((m = rx.exec(content)) !== null) {
+        if (isViteSource && VITE_INTRINSICS.has(m[1])) continue;
+        names.add(m[1]);
+      }
     }
   };
 

package/cli/validators/docs-coverage.mjs

@@ -422,9 +422,12 @@ function checkReadmeSections(projectDir) {
     }
   }
 
+  // Recommended sections are a BONUS — present = +1 to both passed and total,
+  // missing = no-op. Counting missing recommended toward `total` without a
+  // corresponding warning would be a silent fail (caught by B-4 nudge).
   for (const section of recommendedSections) {
-    total++;
     if (section.patterns.some(p => lowerContent.includes(p))) {
+      total++;
       passed++;
     }
   }

package/cli/validators/environment.mjs

@@ -41,13 +41,19 @@ export function validateEnvironment(projectDir, config) {
   // CLI/library projects that declare no env vars skip this.)
   if (ptc.needsEnvVars !== false) {
     const documented = new Set();
-    const varRe = /`([A-Z][A-Z0-9_]{2,})`/g;
+    // Require the matched name to end with a letter/digit — prevents prose-only
+    // tokens like `VITE_` (the convention prefix) from being treated as a real
+    // variable name.
+    const varRe = /`([A-Z][A-Z0-9_]*[A-Z0-9])`/g;
     let m;
-    while ((m = varRe.exec(content)) !== null) documented.add(m[1]);
+    while ((m = varRe.exec(content)) !== null) {
+      if (m[1].length < 3) continue; // 'OK' / 'ID' etc. are too short to be env var refs
+      documented.add(m[1]);
+    }
     for (const envFile of ['.env.example', '.env.template']) {
       const p = resolve(projectDir, envFile);
       if (!existsSync(p)) continue;
-      const re = /^([A-Z][A-Z0-9_]+)\s*=/gm;
+      const re = /^([A-Z][A-Z0-9_]*[A-Z0-9])\s*=/gm;
       const ex = readFileSync(p, 'utf-8');
       let em;
       while ((em = re.exec(ex)) !== null) documented.add(em[1]);

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.11.1"
+  version: "0.11.2"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with 19 automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. Zero NPM runtime dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

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

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.11.1
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.11.1 -->
+<!-- docguard:version: 0.11.2 -->
 
 # DocGuard Fix Skill
 

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

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.11.1
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.11.1 -->
+<!-- docguard:version: 0.11.2 -->
 
 # DocGuard Guard Skill
 

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

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.11.1
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.11.1 -->
+<!-- docguard:version: 0.11.2 -->
 
 # DocGuard Review Skill
 

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

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.11.1
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.11.1 -->
+<!-- docguard:version: 0.11.2 -->
 
 # DocGuard Score Skill
 

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

@@ -4,7 +4,7 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.11.1
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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