docguard-cli 0.22.1 → 0.24.0

package/cli/validators/traceability.mjs

@@ -15,6 +15,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
+import { TRACE_MAP, TEST_PATTERNS, isTraceableSource } from '../shared-trace-patterns.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -22,57 +23,6 @@ const IGNORE_DIRS = new Set([
   '.amplify-hosting', '.serverless',
 ]);
 
-/**
- * Mapping of canonical docs to source code patterns they should trace to.
- */
-const TRACE_MAP = {
-  'ARCHITECTURE.md': {
-    sourcePatterns: [
-      { label: 'Entry points', glob: /^(index|main|app|server)\.[jt]sx?$/ },
-      { label: 'Config files', glob: /^(package\.json|tsconfig.*|next\.config|vite\.config)/ },
-      { label: 'Route handlers', glob: /(routes?|api|pages|app)\// },
-    ],
-  },
-  'DATA-MODEL.md': {
-    sourcePatterns: [
-      { label: 'Schema definitions', glob: /(schema|model|entity|migration|prisma)/i },
-      { label: 'Type definitions', glob: /types?\.[jt]sx?$/ },
-      { label: 'Database configs', glob: /(drizzle|knex|sequelize|typeorm)/i },
-    ],
-  },
-  'TEST-SPEC.md': {
-    sourcePatterns: [
-      { label: 'Test files', glob: /\.(test|spec)\.(mjs|cjs|[jt]sx?)$/ },
-      { label: 'Test config', glob: /(jest|vitest|playwright|cypress)\.config/ },
-      { label: 'E2E tests', glob: /(e2e|integration)\// },
-    ],
-  },
-  'SECURITY.md': {
-    sourcePatterns: [
-      { label: 'Auth modules', glob: /(auth|login|session|jwt|oauth|middleware)/i },
-      { label: 'Secret configs', glob: /\.(env|env\.example|env\.local)$/ },
-      { label: 'Gitignore', glob: /^\.gitignore$/ },
-    ],
-  },
-  'ENVIRONMENT.md': {
-    sourcePatterns: [
-      { label: 'Env files', glob: /\.env/ },
-      { label: 'Docker configs', glob: /(Dockerfile|docker-compose|\.dockerignore)/ },
-      { label: 'CI/CD configs', glob: /\.(github|gitlab-ci|circleci)/ },
-    ],
-  },
-  'API-REFERENCE.md': {
-    sourcePatterns: [
-      { label: 'Route handlers', glob: /(routes?|controllers?|handlers?)\// },
-      // Next.js App Router (and Pages Router) — `app/api/`, `src/app/api/`,
-      // `pages/api/`, `src/pages/api/`. Without this, a perfectly-populated
-      // Next.js API tree gets reported as "API-REFERENCE.md — unlinked doc".
-      { label: 'Next.js API routes', glob: /(^|\/)(app|pages)\/api\// },
-      { label: 'OpenAPI spec', glob: /(openapi|swagger)\.(json|ya?ml)/ },
-      { label: 'API middleware', glob: /middleware\// },
-    ],
-  },
-};
 
 // ──── Default requirement ID patterns ────
 // Users can override via config.traceability.requirementPattern
@@ -89,7 +39,12 @@ const DEFAULT_REQ_PATTERNS = [
   /\b(ARCH)-(\d{2,4})\b/g,
   /\b(MOD)-(\d{2,4})\b/g,
   /\b(SC)-(\d{2,4})\b/g,     // Spec Kit: Success Criteria
-  /\b(T)(\d{3,4})\b/g,       // Spec Kit: Task IDs (T001, T002)
+  // Spec Kit task IDs (T001, T002). Unlike the hyphenated IDs above, a bare
+  // `T350` over-matches prose (timeouts, model names, status codes), forcing
+  // spurious "untraced requirement" warnings. Anchor to the two contexts where
+  // a real task ID actually appears: a markdown checklist marker (`- [ ] T001`,
+  // the spec-kit tasks.md format) or a test annotation (`@req T001`/`@task`).
+  /(?<=\[[ xX]\]\s|@(?:req|task|covers)\s)(T)(\d{3,4})\b/g,
 ];
 
 /**
@@ -152,9 +107,12 @@ export function validateTraceability(projectDir, config) {
 
     // Count matching source files
     // ⚡ Bolt: Fast early return using .some() instead of .filter()
+    // v0.24: skip .md files — a doc isn't "linked" just because another doc's
+    // name matches the glob (e.g. SECURITY's `guard` matching docguard.guard.md);
+    // that masked genuinely unlinked docs (field report).
     let hasSource = false;
     for (const pattern of traceInfo.sourcePatterns) {
-      if (projectFiles.some(f => pattern.glob.test(f))) {
+      if (projectFiles.some(f => isTraceableSource(f) && pattern.glob.test(f))) {
         hasSource = true;
         break;
       }
@@ -285,7 +243,7 @@ function collectRequirementIds(projectDir, config, patterns) {
 
 function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
   const testFiles = projectFiles.filter(f =>
-    /\.(test|spec)\.(mjs|cjs|[jt]sx?)$/.test(f) ||
+    TEST_PATTERNS.some(p => p.test(f)) ||   // multilingual: JS/TS, Python, Go, Rust, Java/Kotlin, Ruby, PHP
     /__tests__\//.test(f) ||
     /tests?\//.test(f)
   );

package/cli/writers/sections.mjs

@@ -36,8 +36,20 @@ function parseAttrs(attrStr) {
 
 /**
  * Parse all well-formed sections in a document.
- * A section is a line matching the open marker, then content lines, then a
- * close-marker line. An open with no matching close is ignored (not corrupted).
+ * A section is an open-marker line, then content lines, then a close-marker
+ * line. Sections are FLAT — there is no nesting.
+ *
+ * Two malformed cases are handled so that a hand-edit mistake can never cause
+ * a later regenerate to overwrite human prose:
+ *   - An open with no matching close (reached EOF) is dropped, not returned.
+ *   - A NEW open encountered while a previous one is still unclosed means the
+ *     previous open was malformed (its close was deleted or typo'd). We ABANDON
+ *     the previous open and restart at the new one. The earlier, broken
+ *     approach kept the first open and paired it with the *next* section's
+ *     close — swallowing the human prose and the next section into one body,
+ *     which a subsequent replaceSection() would then silently overwrite.
+ * A dropped section simply isn't returned, so replaceSection() no-ops on it
+ * (returns content unchanged) instead of corrupting the surrounding document.
  * @returns {Array<{ id, source, attrs, openLine, closeLine, body }>}
  */
 export function parseSections(content) {
@@ -47,25 +59,26 @@ export function parseSections(content) {
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    if (open === null) {
-      const om = line.match(OPEN_RE);
-      if (om) {
-        const attrs = parseAttrs(om[1] || '');
-        open = { attrs, openLine: i };
+    if (CLOSE_RE.test(line)) {
+      if (open !== null) {
+        sections.push({
+          id: open.attrs.id || '',
+          source: open.attrs.source || 'code',
+          attrs: open.attrs,
+          openLine: open.openLine,
+          closeLine: i,
+          body: lines.slice(open.openLine + 1, i).join('\n'),
+        });
+        open = null;
       }
-    } else if (CLOSE_RE.test(line)) {
-      sections.push({
-        id: open.attrs.id || '',
-        source: open.attrs.source || 'code',
-        attrs: open.attrs,
-        openLine: open.openLine,
-        closeLine: i,
-        body: lines.slice(open.openLine + 1, i).join('\n'),
-      });
-      open = null;
+      // A close with no matching open is ignored.
+      continue;
+    }
+    const om = line.match(OPEN_RE);
+    if (om) {
+      // Abandon any still-open (malformed) section; start fresh here.
+      open = { attrs: parseAttrs(om[1] || ''), openLine: i };
     }
-    // Note: a second open before a close just extends the search for a close;
-    // we keep the FIRST open's start, so malformed nesting can't corrupt content.
   }
   return sections;
 }

package/docs/commands.md

@@ -1,6 +1,6 @@
 # Commands Reference
 
-DocGuard v0.5.0 — 13 commands, zero dependencies.
+DocGuard CLI — one pinned runtime dependency (`@babel/parser`, optional-load); Node.js 18+. See `package.json` for the current version.
 
 ## The AI Loop
 

package/docs/configuration.md

@@ -73,6 +73,17 @@ See [Profiles](./profiles.md) for details.
 | `environment` | `true` | Setup steps, env vars, prerequisites, .env.example |
 | `freshness` | varies | Docs updated recently relative to code changes (git-based) |
 
+## Muting a validator
+
+Two ways to turn a validator off, for two different intents:
+
+| Intent | How | Renders as |
+|--------|-----|-----------|
+| Operational toggle (CI speed, not relevant *right now*) | `.docguard.json` → `"validators": { "testSpec": false }` | silent — disabled |
+| **Intentional non-applicability** (POC with no tests, library with no auth) | inline marker in a canonical doc or `AGENTS.md`:<br>`<!-- docguard:validator testSpec n/a — POC, no automated tests yet -->` | `➖ Test-Spec [N/A] (declared N/A: …)` — visible, git-tracked |
+
+The marker is preferred when the validator genuinely does not apply: the rationale lives next to the declaration, travels with the repo, and shows up honestly as N/A rather than a hidden skip or a fake green check. The key is the validator key from the table above (case/separator tolerant — `test-spec` works too); a mistyped key is reported as a warning rather than silently ignored. A no-tests POC typically marks both `testSpec` and `traceability` N/A.
+
 ## Project Type Detection
 
 DocGuard auto-detects your project type from `package.json`:

package/docs/faq.md

@@ -129,7 +129,7 @@ Only if you install hooks (`docguard hooks`). Without hooks, it's advisory only.
 
 ### Does DocGuard have dependencies?
 
-**Zero.** Pure Node.js, no npm dependencies. Works with Node.js 18+.
+**One.** `@babel/parser` (exact-pinned), for AST-accurate JS/TS parsing — and it's loaded *optionally*, so DocGuard still runs (on the regex fallback tier) if it's ever missing. Everything else is pure Node.js built-ins. Works with Node.js 18+. Python parsing optionally shells out to the project's own `python3`.
 
 ### Does it work with non-JavaScript projects?
 

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

@@ -12,7 +12,7 @@ Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readabl
 - **5 AI Skills** — docguard-fix, docguard-guard, docguard-sync, docguard-review, docguard-score (enterprise-grade behavior protocols, not just step-lists)
 - **Workflow Chaining** — YAML handoffs enable guard → sync → fix → review → score flows
 - **Spec Kit Hooks** — Quality gate integrations at implement, tasks, and review phases
-- **Zero Dependencies** — Pure Node.js built-ins only
+- **Minimal Dependencies** — one pinned, optional-load parser (`@babel/parser`); Node.js built-ins otherwise
 
 ## Installation
 

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

@@ -3,8 +3,8 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.22.1"
-  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."
+  version: "0.24.0"
+  description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"
   license: "MIT"

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.22.1
+  version: 0.24.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.22.1 -->
+<!-- docguard:version: 0.24.0 -->
 
 # 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.22.1
+  version: 0.24.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.22.1 -->
+<!-- docguard:version: 0.24.0 -->
 
 # 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.22.1
+  version: 0.24.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.22.1 -->
+<!-- docguard:version: 0.24.0 -->
 
 # 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.22.1
+  version: 0.24.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.22.1 -->
+<!-- docguard:version: 0.24.0 -->
 
 # DocGuard Score Skill
 

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

@@ -4,9 +4,10 @@ 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.22.1
+  version: 0.24.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
+<!-- docguard:version: 0.24.0 -->
 
 # DocGuard Sync Skill
 

package/extensions/spec-kit-docguard/templates/github-workflows/docguard-autofix.yml

@@ -13,7 +13,8 @@
 # Setup:
 #   1. Copy this file to .github/workflows/docguard-autofix.yml
 #   2. Ensure the workflow has the permissions block below (write access).
-#   3. (Optional) Pin to a specific DocGuard version by changing `@main` to a tag.
+#   3. Pinned to the `@v0.24.0` release tag for reproducible CI. Change it to a
+#      newer tag to upgrade, or to `@main` to always track the latest (unpinned).
 #
 # Security note: this workflow makes commits back to the PR branch. It refuses
 # to run on PRs from forks (where pushing back is impossible by design).
@@ -43,7 +44,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run DocGuard fix --write + auto-commit + PR comment
-        uses: raccioly/docguard@main
+        uses: raccioly/docguard@v0.24.0
         with:
           command: fix
           auto-commit: 'true'

package/extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml

@@ -28,7 +28,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run all validators
-        uses: raccioly/docguard@main
+        uses: raccioly/docguard@v0.24.0
         with:
           command: guard
           # Flip to 'true' once your repo is clean — turns warnings into hard failures.
@@ -42,7 +42,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Score & comment
-        uses: raccioly/docguard@main
+        uses: raccioly/docguard@v0.24.0
         with:
           command: score
           format: json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {
@@ -45,6 +45,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {
+    "@babel/parser": "7.29.7"
+  },
   "files": [
     "cli/",
     "templates/",
@@ -56,6 +59,5 @@
     "PHILOSOPHY.md",
     "README.md",
     "LICENSE"
-  ],
-  "dependencies": {}
+  ]
 }