docguard-cli 0.11.0__tar.gz → 0.11.2__tar.gz

{docguard_cli-0.11.0/extensions/spec-kit-docguard → docguard_cli-0.11.2/.agent}/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.9.9
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.2 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.11.0/extensions/spec-kit-docguard → docguard_cli-0.11.2/.agent}/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.9.9
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.2 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.11.0/extensions/spec-kit-docguard → docguard_cli-0.11.2/.agent}/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.9.9
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.2 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/.agent/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.9.9
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.9.9 -->
+<!-- docguard:version: 0.11.2 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/.agent/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.10.0
+  version: 0.11.2
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/AGENTS.md

@@ -96,6 +96,7 @@ extensions/spec-kit-docguard/
 
 ## Rules
 
+- **PR-first workflow — no direct-to-main commits.** Create a branch (`git checkout -b <type>/<slug>`), push, `gh pr create`, let CI run, self-review, squash-merge. Tag releases only after merge on `main`. The only acceptable direct-to-main: typo fixes in comments or README badge URLs.
 - Never commit without updating CHANGELOG.md
 - If code deviates from docs, add `// DRIFT: reason`
 - Security rules in SECURITY.md are mandatory

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-05-25
+
+Patch release addressing the four bugs (B-1..B-4) reported from the v0.11.1 audit of `wu-whatsappinbox` (score 98/100, 572/575 passed, 1 warning), plus Antigravity/Kiro/Windsurf agent-routing aliases and a Docs-Coverage silent-fail fix that the new B-4 nudge itself exposed.
+
+### Fixed
+- **B-1: Vite intrinsics no longer reported as user env vars.** `grepEnvUsage` in `cli/shared-source.mjs` now skips `DEV`, `PROD`, `MODE`, `BASE_URL`, and `SSR` on `import.meta.env.*` — these are injected by Vite at build time, not user-configured. Real user vars like `VITE_API_URL` are still captured. (Reported by wu-whatsappinbox v0.11.1 audit.)
+- **B-2: `docguard diff` Data Entities now uses real exported names, not file basenames.** Previously the entity diff walked filenames and reported the stem (e.g. `models.py` → "models"), missing all the actual classes inside. Now uses `scanSchemasDeep` — the same code-side scanner the rest of DocGuard uses — which extracts real Pydantic/Dataclass/Mongoose/Prisma/Zod/Sequelize/Sqlx/SQLAlchemy/JPA entity names. (Reported by wu-whatsappinbox v0.11.1 audit.)
+- **B-3: Literal `` `VITE_` `` prefix in prose no longer captured as an env var name.** Tightened the env-var name regex across `shared-source.mjs`, `validators/environment.mjs`, and `commands/diff.mjs` from `[A-Z][A-Z0-9_]*` to `[A-Z][A-Z0-9_]*[A-Z0-9]` (must end with letter/digit, not underscore). Documentation like ``All vars start with `VITE_` (Vite convention)`` no longer triggers a "missing `VITE_`" warning. (Reported by wu-whatsappinbox v0.11.1 audit.)
+- **B-4 nudge surfaced: Docs-Coverage Check 5 (`checkReadmeSections`) silent-fail fixed.** The "recommended sections" loop bumped `total` without emitting a message when missing — exactly the anti-pattern B-4 flags. Recommended sections are now a true bonus: present = +1 to both passed/total, missing = no-op. Restores honest scoring on the README checker. (Found by the B-4 nudge running on the wu-whatsappinbox fixture.)
+
+### Added
+- **B-4: `--show-failing` flag and validator-bug nudge.** `docguard guard --show-failing` shows warnings/errors for every non-passing validator even if the overall status would have suppressed them. New nudge fires when a validator has `passed < total` but emits no warning or error messages — points at a likely silent-fail validator bug for the user to file an issue. (Reported by wu-whatsappinbox v0.11.1 audit.)
+- **Antigravity / Kiro / Windsurf / GEMINI agent signals.** `cli/ensure-skills.mjs` now detects these agent ecosystems via additional signal files (`.agents`, `.antigravity`, `ANTIGRAVITY.md`, `.kiro`, `.windsurf`, `GEMINI.md`) so the right skills are installed for each. Antigravity was already wired via `.agents → agy`; this expands the alias surface so neither side-by-side IDEs nor Spec Kit's `.agents` convention break detection.
+
+### Internal
+- New test file: `tests/patch-0.11.2.test.mjs` with regression coverage for B-1 (Vite intrinsics skip), B-2 (Pydantic class names, not file basename), and B-3 (literal `VITE_` not captured). **Total: 339 tests passing (was 336, +3 new).**
+- No new NPM dependencies. Zero schema or config-file changes. Bumped `pyproject.toml` from `0.11.0 → 0.11.2` to re-sync the PyPI publish (the previous patch released to npm but skipped PyPI version bump).
+
+### Out of scope (deferred to v0.12)
+- S-1 (`sync --since` surgical refresh), S-2 (sweep-needed nudge from freshness counters), S-3 (`trace --reverse` code→doc map), S-4 (rename detection via `git log --follow`), S-5 (`.docguardignore` template at init), S-6 (per-validator severity in `.docguard.json`), S-7 (generated-doc-in-draft staleness validator), S-8 (cross-reference validator for broken `§X` anchors), S-9 (pre-commit lite on changed files only), S-10 (`.docguard/fixed.json` memory of past fixes).
+
+Credit: feedback from running v0.11.1 on the `wu-whatsappinbox` enterprise monorepo (audit score 98/100, 572/575 passed).
+
+## [0.11.1] - 2026-05-25
+
+Patch release addressing false positives surfaced by the v0.11.0 audit of the `wu-whatsappinbox` enterprise monorepo, generalized into a multi-tool IaC detector, plus several DocGuard self-audit improvements. Spec: `specs/003-v011-false-positives/`.
+
+### Fixed
+- **Docs-Sync no longer misclassifies frontend API clients as backend routes.** Dropped the ambiguous bare `'api'` from the route-directory convention list. `src/api/client.ts` (frontend axios) and similar are no longer scanned as Express/Next.js routes (FP-1). For Next.js App Router (`src/app/api`, `app/api`), only files matching the strict `route.{ts,tsx,js,jsx,mjs}` filename convention are counted — helper files in the same tree are skipped (FR-001, FR-002).
+- **Test files are no longer flagged as undocumented services or routes.** The docs-sync route and service loops now skip paths under `__tests__/` and filenames matching `*.{test,spec}.{ts,tsx,js,jsx,mjs,py,java,go}` (FP-2, FR-003, FR-004). Eliminates ~7 spurious warnings per monorepo with co-located tests.
+- **Build outputs no longer flagged as undocumented source.** Added `cdk.out`, `out`, `.nuxt`, `.claude` to the docs-coverage `IGNORE_DIRS` set (FP-3, FR-005).
+- **`config.ignore` is now honored by Docs-Coverage's source-directory scan** (FP-3, FR-006 / IR-5). Closes a long-standing inconsistency where other validators respected the user's ignore but the source-dir scan did not. Patterns like `**/cdk.out/**` now match the directory itself as well as files inside it.
+- **Worktree copies no longer double-counted.** `globMatch` in `cli/shared-ignore.mjs` now rejects paths under `.claude/worktrees/`, `.git/worktrees/`, and `.jj/` at any depth — same treatment as `node_modules` (FP-4, FR-007). Affects every Claude-Code project using parallel-agent worktrees.
+- **Check 1 (config files) no longer flags build-cache dotdirs as undocumented configs.** Now skips directories — `.nuxt`, `.claude`, etc. are excluded by `IGNORE_DIRS` for the source-dir scan instead.
+- **Check 1 (config files) now honors `config.ignore` too.** Originally fixed only for the source-directory scan; a follow-up audit reproduced the same FP-3 class with `.local` in `ignore` still being flagged. Both Docs-Coverage scans now call `shouldIgnore(entry, config) || shouldIgnore(entry + '/', config)`. Closes FR-015 (audit-confirmed gap).
+- **Test-Spec validator parses multi-path Journey rows correctly.** Previously a Journey cell like `` `path/a.test.ts`, `path/b.test.ts` `` was stripped of all backticks then `existsSync()`d as one string — a 100% false-positive rate on multi-path rows. Now: split on commas outside backticks, strip backticks per segment, evaluate each independently. Row passes if ANY referenced file has evidence. Glob entries (`foo_*.test.ts`) are expanded; `(N suites)` / `(N tests)` annotations are accepted as the author's explicit coverage claim. Closes FP-6 and FR-016.
+- **TODO-Tracking validator no longer false-positives on its own keyword list.** Previously the regex matched `TEMP(?!late|orar)` inside its own source. Two-part fix: (1) match restricted to text following a comment marker (`//`, `#`, `/*`, `<!--`, block `*`), (2) the validator skips its own source file (`cli/validators/todo-tracking.mjs`) since the docstring legitimately names the keywords.
+- **TODO-Tracking validator no longer false-positives on test fixture strings.** Test files commonly contain `// TODO:` inside template literals (`writeFileSync(..., '// TODO:')`) that single-line heuristics can't distinguish from real comments. Test files are now skipped by default; opt back in with `config.todoTracking.includeTestFiles = true`.
+- **Traceability validator's own fixtures no longer leak as orphan refs.** `tests/traceability.test.mjs` previously contained literal `REQ-001`/`REQ-002`/`REQ-003` strings that the validator scanned and reported as orphaned test references. Fixtures now build the IDs from parts so the validator's pattern doesn't match.
+
+### Added
+- **Multi-tool IaC detector + consolidated documentation reminder.** New `cli/scanners/iac.mjs` identifies projects shipping any of: **AWS CDK** (`cdk.json`), **Terraform** (`*.tf` files), **Pulumi** (`Pulumi.yaml`), **AWS SAM** (`template.yaml` with `AWS::Serverless::`), and **Serverless Framework** (`serverless.yml`). When an IaC project's ARCHITECTURE.md has no Infrastructure heading, DocGuard emits ONE actionable warning per detected tool naming the marker file location and the expected source layout — instead of multiple generic per-directory warnings (FR-009, FR-010, FR-011). The generic per-dir warnings inside IaC packages (`bin/`, `lib/`, `modules/`, `stacks/`, `constructs/`, `handlers/`, etc.) are suppressed in favor of these consolidated messages. The legacy `cli/scanners/cdk.mjs` is preserved as a thin re-export for backward compatibility.
+- **`## Infrastructure (IaC)` section in `templates/ARCHITECTURE.md.template`.** New projects initialized via `docguard init` start with placeholder tables for AWS CDK, Terraform, and Pulumi/SAM/Serverless layouts plus a Deployment Pipeline subsection (FR-012). Explicitly skippable for non-IaC projects via a header comment.
+- **`DEFAULT_IGNORE_DIRS`** exported from `cli/shared-ignore.mjs` — canonical shared ignore set covering build outputs (`dist`, `build`, `out`, `cdk.out`, `target`, `.gradle`), VCS internals (`.git`, `.jj`, `.hg`, `.svn`), package caches (`node_modules`, `vendor`, `.venv`, `__pycache__`), and framework synth outputs (`.next`, `.nuxt`, `.turbo`, `.vercel`, `.cache`, `.svelte-kit`) (FR-008). Added `target` (Rust/Java), `.gradle`, and `.svelte-kit` per the updated wu-whatsappinbox audit. Available for any future validator to import; existing per-validator `IGNORE_DIRS` sets are left in place (deferred migration).
+
+### Changed
+- **DocGuard package version bumped to 0.11.1** across `package.json` and all `extensions/spec-kit-docguard/` files (extension.yml + 5 SKILL.md files were referencing stale `v0.9.9`/`v0.10.0`).
+- **`docs-canonical/ARCHITECTURE.md`** updated to add `cli/writers/` and `cli/shared-*.mjs` to the Component Map and Layer Boundaries — closes a real doc gap surfaced by dogfooding (the writers/ directory has shipped for several releases without being documented).
+- **`specs/003-v011-false-positives/plan.md`** restructured to match the spec-kit `plan-template.md` shape (added Summary, Technical Context, Constitution Check, Project Structure sections). `tasks.md` rewritten with the spec-kit phased T### convention.
+
+### Internal
+- New test files: `tests/cdk-detection.test.mjs` (CDK + multi-tool IaC detector tests + `globMatch` worktree rejection + `DEFAULT_IGNORE_DIRS` shape). Existing test suites extended with regression cases for FP-1..FP-5, TODO-tracking false-positive guards, and IaC-tool detection across Terraform/Pulumi/SAM/Serverless. New tests are annotated with `// @req FR-NNN` / `// @req SC-NNN` comments for traceability. **Total: 329 tests passing (was 306, +23 new).**
+- **DocGuard self-audit improvements**: ran `docguard guard` on the repo as part of this release. Warnings dropped from **57 → 15** across the session by fixing real drift (stale extension versions, missing `cli/writers/` mention, traceability gaps) and reducing self-referential false positives (TODO validator scanning its own keyword list).
+- **Round 2 fixes after a second audit report**: FP-3 part B (`checkConfigFiles` honoring `config.ignore`), FP-6 (Test-Spec multi-path Journey row parsing with glob and `(N suites)` annotation support), additional `DEFAULT_IGNORE_DIRS` entries for Rust/Java/SvelteKit. **Total tests passing: 336** (was 306).
+- No new NPM dependencies. Zero schema or config-file changes.
+
+### Out of scope (deferred to v0.12)
+- Feature requests IR-1..IR-4, IR-6..IR-8 (per-validator severity, `--diff-only`, draft-staleness warning, `sync --section`, `.docguardignore` template at init, extended Next.js detection, `routesGlob`/`servicesGlob` overrides). IR-5 (honor ignore in source-dir scan) shipped as part of this release alongside FP-3.
+- Migrating all 17 modules that define their own `IGNORE_DIRS` constant to import `DEFAULT_IGNORE_DIRS` — mechanical, large diff, tracked separately.
+- Multi-line string-literal detection in TODO-Tracking — current heuristic still false-positives on `// TODO:` inside multi-line template literals. Workaround: keep test files out of TODO scanning (now default) or use `config.todoIgnore` globs.
+
+Credit: feedback from running v0.11.0 on the `wu-whatsappinbox` enterprise monorepo (audit score 98/100, 40 warnings).
+
 ## [0.11.0] - 2026-05-22
 
 This release reshapes DocGuard from a documentation linter into an **AI-readable, always-current project memory builder** — for any language project, not just JS/web. The four-mode lifecycle (`generate → guard → sync → fix`) is now coherent end-to-end.

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.11.0
+Version: 0.11.2
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/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]);
       }

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/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

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/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++;

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/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' },

docguard_cli-0.11.2/cli/scanners/cdk.mjs

@@ -0,0 +1,10 @@
+/**
+ * CDK Detector — Re-export shim.
+ *
+ * The CDK-specific detector has been generalized into a multi-tool IaC
+ * detector at cli/scanners/iac.mjs covering CDK, Terraform, Pulumi, SAM,
+ * and Serverless Framework. This module re-exports the CDK-only API for
+ * backward compatibility. New code should import from iac.mjs directly.
+ */
+
+export { detectCDK, hasInfrastructureHeading } from './iac.mjs';

docguard_cli-0.11.2/cli/scanners/iac.mjs

@@ -0,0 +1,235 @@
+/**
+ * IaC Detector — Identifies Infrastructure-as-Code projects.
+ *
+ * IaC code is real production source that defines cloud infrastructure.
+ * It MUST be documented in ARCHITECTURE.md, not silently ignored. This
+ * detector identifies which IaC tool the project uses so docs-coverage
+ * can emit ONE consolidated actionable warning naming the actual layout
+ * (instead of multiple generic per-directory warnings).
+ *
+ * Supported tools:
+ *   - AWS CDK         → cdk.json marker file
+ *   - Terraform       → *.tf files in any non-ignored directory
+ *   - Pulumi          → Pulumi.yaml marker file
+ *   - AWS SAM         → template.yaml/yml with "AWS::Serverless::"
+ *   - Serverless Fmw  → serverless.yml/serverless.yaml/serverless.ts
+ *
+ * Zero NPM dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { DEFAULT_IGNORE_DIRS } from '../shared-ignore.mjs';
+
+const MAX_DEPTH = 6;
+
+/**
+ * Per-tool conventions: marker file/pattern + the directories that hold the
+ * actual IaC source. Used to construct the consolidated warning text.
+ */
+const TOOL_PROFILES = {
+  cdk: {
+    label: 'AWS CDK',
+    markerFile: 'cdk.json',
+    sourceDirs: ['bin/ (app entrypoint)', 'lib/stacks/', 'lib/constructs/'],
+    headingPattern: /^#+\s+(infrastructure|cdk|iac)\b/im,
+  },
+  terraform: {
+    label: 'Terraform',
+    markerFile: null, // any *.tf file
+    sourceDirs: ['*.tf (root module)', 'modules/ (reusable modules)', 'environments/ (per-env tfvars)'],
+    headingPattern: /^#+\s+(infrastructure|terraform|iac)\b/im,
+  },
+  pulumi: {
+    label: 'Pulumi',
+    markerFile: 'Pulumi.yaml',
+    sourceDirs: ['index.ts (main program)', 'stacks/', 'config/'],
+    headingPattern: /^#+\s+(infrastructure|pulumi|iac)\b/im,
+  },
+  sam: {
+    label: 'AWS SAM',
+    markerFile: 'template.yaml', // also template.yml — checked below
+    sourceDirs: ['template.yaml (SAM manifest)', 'src/ (Lambda handlers)', 'events/'],
+    headingPattern: /^#+\s+(infrastructure|sam|serverless|iac)\b/im,
+  },
+  serverless: {
+    label: 'Serverless Framework',
+    markerFile: 'serverless.yml', // also .yaml, .ts — checked below
+    sourceDirs: ['serverless.yml (manifest)', 'handlers/', 'src/'],
+    headingPattern: /^#+\s+(infrastructure|serverless|iac)\b/im,
+  },
+};
+
+/**
+ * Detect every IaC tool used in the project. Walks the tree from projectDir
+ * looking for marker files, respecting DEFAULT_IGNORE_DIRS.
+ *
+ * @param {string} projectDir - Absolute path to project root
+ * @returns {{
+ *   isIaC: boolean,
+ *   tools: Array<{
+ *     tool: string,             // 'cdk' | 'terraform' | 'pulumi' | 'sam' | 'serverless'
+ *     label: string,            // 'AWS CDK' etc.
+ *     markerPaths: string[],    // relative paths to detected marker files
+ *     packageDirs: string[],    // relative dirs containing the markers
+ *     sourceDirs: string[],     // expected source layout per tool convention
+ *   }>
+ * }}
+ */
+export function detectIaC(projectDir) {
+  const findings = {
+    cdk: { markerPaths: [], packageDirs: [] },
+    terraform: { markerPaths: [], packageDirs: [] },
+    pulumi: { markerPaths: [], packageDirs: [] },
+    sam: { markerPaths: [], packageDirs: [] },
+    serverless: { markerPaths: [], packageDirs: [] },
+  };
+
+  const recordFinding = (tool, fullPath) => {
+    const relPath = relative(projectDir, fullPath);
+    findings[tool].markerPaths.push(relPath);
+    const pkgDir = relative(projectDir, dirnameOf(fullPath)) || '.';
+    if (!findings[tool].packageDirs.includes(pkgDir)) {
+      findings[tool].packageDirs.push(pkgDir);
+    }
+  };
+
+  const walk = (dir, depth) => {
+    if (depth > MAX_DEPTH) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+
+    for (const e of entries) {
+      if (!e.isFile()) continue;
+      const full = join(dir, e.name);
+
+      // CDK
+      if (e.name === 'cdk.json') recordFinding('cdk', full);
+
+      // Terraform — any .tf file (we record one per directory, not per file)
+      if (e.name.endsWith('.tf')) {
+        const pkgDir = relative(projectDir, dir) || '.';
+        if (!findings.terraform.packageDirs.includes(pkgDir)) {
+          findings.terraform.markerPaths.push(relative(projectDir, full));
+          findings.terraform.packageDirs.push(pkgDir);
+        }
+      }
+
+      // Pulumi
+      if (e.name === 'Pulumi.yaml' || e.name === 'Pulumi.yml') {
+        recordFinding('pulumi', full);
+      }
+
+      // SAM — template.yaml/yml WITH AWS::Serverless::
+      if (e.name === 'template.yaml' || e.name === 'template.yml') {
+        if (fileContains(full, 'AWS::Serverless::')) recordFinding('sam', full);
+      }
+
+      // Serverless Framework
+      if (
+        e.name === 'serverless.yml' ||
+        e.name === 'serverless.yaml' ||
+        e.name === 'serverless.ts' ||
+        e.name === 'serverless.js'
+      ) {
+        recordFinding('serverless', full);
+      }
+    }
+
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (DEFAULT_IGNORE_DIRS.has(e.name)) continue;
+      if (e.name.startsWith('.')) continue;
+      walk(join(dir, e.name), depth + 1);
+    }
+  };
+
+  if (existsSync(projectDir)) {
+    try {
+      if (statSync(projectDir).isDirectory()) walk(projectDir, 0);
+    } catch { /* skip */ }
+  }
+
+  const tools = [];
+  for (const [tool, data] of Object.entries(findings)) {
+    if (data.markerPaths.length > 0) {
+      tools.push({
+        tool,
+        label: TOOL_PROFILES[tool].label,
+        markerPaths: data.markerPaths,
+        packageDirs: data.packageDirs,
+        sourceDirs: TOOL_PROFILES[tool].sourceDirs,
+      });
+    }
+  }
+
+  return { isIaC: tools.length > 0, tools };
+}
+
+/**
+ * Check whether ARCHITECTURE.md content includes an Infrastructure/CDK/IaC/
+ * Terraform/Pulumi/SAM heading at any level. Case-insensitive.
+ *
+ * @param {string} archContent - Full ARCHITECTURE.md content
+ * @returns {boolean}
+ */
+export function hasInfrastructureHeading(archContent) {
+  if (!archContent) return false;
+  return /^#+\s+(infrastructure|cdk|iac|terraform|pulumi|sam|serverless)\b/im.test(archContent);
+}
+
+/**
+ * Build the consolidated warning text for a detected IaC tool.
+ * One warning per tool — names the marker location and required content.
+ */
+export function buildIaCWarning(toolFinding) {
+  const primary = toolFinding.markerPaths[0];
+  const pkgDir = toolFinding.packageDirs[0];
+  const where = pkgDir === '.' ? '' : pkgDir + '/';
+  const sourceList = toolFinding.sourceDirs
+    .map(s => s.startsWith('*.') ? `${where}${s}` : `${where}${s}`)
+    .join(', ');
+  return `${toolFinding.label} detected at ${primary} — add an "Infrastructure" section to ` +
+    `ARCHITECTURE.md covering ${sourceList}`;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function dirnameOf(p) {
+  const i = p.lastIndexOf('/');
+  if (i < 0) {
+    const j = p.lastIndexOf('\\');
+    return j < 0 ? p : p.slice(0, j);
+  }
+  return p.slice(0, i);
+}
+
+function fileContains(filePath, needle) {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    return content.includes(needle);
+  } catch {
+    return false;
+  }
+}
+
+// ── Backwards-compatibility shim ────────────────────────────────────────────
+
+/**
+ * Legacy CDK-only API kept for callers that don't need multi-tool detection.
+ * Delegates to detectIaC and projects the CDK slice into the old shape.
+ *
+ * @deprecated Use detectIaC for new code.
+ */
+export function detectCDK(projectDir) {
+  const result = detectIaC(projectDir);
+  const cdk = result.tools.find(t => t.tool === 'cdk');
+  if (!cdk) {
+    return { isCDK: false, cdkJsonPaths: [], cdkPackageDirs: [] };
+  }
+  return {
+    isCDK: true,
+    cdkJsonPaths: cdk.markerPaths,
+    cdkPackageDirs: cdk.packageDirs,
+  };
+}

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/cli/shared-ignore.mjs

@@ -15,6 +15,31 @@
  * Zero NPM dependencies — pure Node.js built-ins only.
  */
 
+/**
+ * Canonical set of directory names that should never be scanned, regardless
+ * of validator. Build outputs, VCS internals, package caches, framework synth
+ * outputs. Validators MAY extend this with their own additions but SHOULD
+ * start from this base so behavior is consistent across the tool.
+ */
+export const DEFAULT_IGNORE_DIRS = new Set([
+  // Package managers
+  'node_modules', 'vendor', '.venv', '__pycache__',
+  // VCS
+  '.git', '.jj', '.hg', '.svn',
+  // Build outputs — JS/TS, Rust/Java, generic
+  'dist', 'build', 'out', 'coverage', 'target', '.gradle',
+  // Framework synth/cache
+  '.next', '.nuxt', '.turbo', '.vercel', '.cache', '.svelte-kit', 'cdk.out',
+  // OS
+  '.DS_Store',
+]);
+
+// Regex for paths that must always be rejected at any depth, regardless of
+// the glob pattern matching them. These are duplicate file trees (worktrees)
+// or runtime caches that should NEVER be treated as primary source.
+const ALWAYS_REJECT_PATH_RE =
+  /(?:^|[/\\])(?:node_modules|\.claude[/\\]worktrees|\.git[/\\]worktrees|\.jj)(?:[/\\]|$)/;
+
 /**
  * Convert a glob pattern to a RegExp.
  * Supports: * (any chars except /), ** (any path segments), . (literal dot).
@@ -111,8 +136,10 @@ function globToMatchRegex(pattern) {
 export function globMatch(relPath, patterns) {
   if (!relPath || !patterns || patterns.length === 0) return false;
 
-  // Always reject paths containing node_modules at any depth
-  if (/(?:^|[/\\])node_modules(?:[/\\]|$)/.test(relPath)) return false;
+  // Always reject paths inside node_modules / worktree copies / .jj at any
+  // depth. A user's testPatterns like "**/*.test.ts" would otherwise match
+  // duplicate trees under .claude/worktrees and inflate test counts.
+  if (ALWAYS_REJECT_PATH_RE.test(relPath)) return false;
 
   const regexes = patterns.map(p => globToMatchRegex(p));
   return regexes.some(r => r.test(relPath));

{docguard_cli-0.11.0 → docguard_cli-0.11.2}/cli/shared-source.mjs

@@ -18,8 +18,9 @@ import { resolve, join, dirname, relative, extname } from 'node:path';
 import { shouldIgnore } from './shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build',
+  'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
   'coverage', '.cache', '__pycache__', '.venv', 'vendor', '.turbo',
+  'cdk.out',
 ]);
 
 const CODE_EXTENSIONS = new Set([
@@ -209,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;
@@ -224,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]);
+      }
     }
   };