docguard-cli 0.23.0 → 0.25.0

package/cli/validators/test-spec.mjs

@@ -18,76 +18,97 @@ export function validateTestSpec(projectDir, config) {
   const content = readFileSync(testSpecPath, 'utf-8');
   const ptc = config.projectTypeConfig || {};
 
-  // Parse the Source-to-Test Map table (new header) or Service-to-Test Map (old header)
-  const serviceMapMatch = content.match(
-    /## (?:Service-to-Test Map|Source-to-Test Map)[\s\S]*?\n\|.*\|.*\|.*\|([\s\S]*?)(?=\n##|\n$|$)/
-  );
-
-  if (serviceMapMatch) {
-    const tableContent = serviceMapMatch[1];
-    const rows = tableContent
+  // Parse the Source-to-Test Map (new header) / Service-to-Test Map (old).
+  //
+  // Column-HEADER-aware: read the header row to locate the source column, the
+  // status column, and EVERY test-file column (Unit Test, Integration Test, …),
+  // then map each data row by index WITHOUT discarding empty cells. The old
+  // parser filtered empty cells — which shifted every column rightward whenever
+  // a cell was blank (e.g. an empty Integration Test) — and only ever checked
+  // the 2nd column, so the generated 4-column table's Integration Test was
+  // never verified (#9). Splitting on the outer pipes and trimming preserves
+  // column alignment so a blank cell stays an empty string in its own slot.
+  const mapSection = content.match(/## (?:Service-to-Test Map|Source-to-Test Map)[\s\S]*?(?=\n## |$)/);
+  if (mapSection) {
+    const splitRow = (line) => {
+      const parts = line.split('|');
+      parts.shift();   // text before the first pipe
+      parts.pop();     // text after the last pipe
+      return parts.map(s => s.trim());
+    };
+    const pipeRows = mapSection[0]
       .split('\n')
-      .filter(line => line.startsWith('|') && !line.includes('---'));
+      .filter(l => l.trim().startsWith('|') && !/^\s*\|[\s|:-]+\|\s*$/.test(l)); // drop the `---` separator
+    const headerCells = pipeRows.length ? splitRow(pipeRows[0]) : [];
+    const header = headerCells.map(h => h.toLowerCase());
+
+    // Classify columns by header name, with positional fallbacks.
+    let sourceIdx = header.findIndex(h => /\bsource\b/.test(h));
+    if (sourceIdx < 0) sourceIdx = 0;
+    let statusIdx = header.findIndex(h => /\bstatus\b/.test(h));
+    if (statusIdx < 0) statusIdx = header.length - 1;
+    let testIdxs = header
+      .map((h, i) => (/\btest\b|\be2e\b/.test(h) ? i : -1))
+      .filter(i => i >= 0 && i !== sourceIdx && i !== statusIdx);
+    if (testIdxs.length === 0) {
+      const fallback = sourceIdx === 1 ? 0 : 1; // the non-source early column
+      if (fallback !== statusIdx && fallback < header.length) testIdxs = [fallback];
+    }
 
-    for (const row of rows) {
-      const cells = row
-        .split('|')
-        .map(s => s.trim())
-        .filter(s => s.length > 0);
+    const isPlaceholder = (v) =>
+      !v || v === '—' || v.includes('N/A') ||
+      ['source file', 'test file', 'unit test', 'integration test', 'e2e test'].includes(v.toLowerCase());
 
-      if (cells.length < 3) continue;
+    // Only existence-check a cell that actually LOOKS like a file path: no
+    // internal spaces, and either a directory separator or a file extension.
+    // A `## Service-to-Test Map` section often holds several sub-tables of
+    // different shapes (Controllers, Services, an "Integration Tests" inventory
+    // like `| test-file | what it covers |`). Without this guard a prose
+    // "what it covers" cell — "Health endpoint with real dependencies" — gets
+    // checked as a missing test file (false positive; field test: wu-whatsappinbox).
+    const isPathLike = (v) => !!v && !/\s/.test(v) && (/[\\/]/.test(v) || /\.[A-Za-z0-9]{1,6}$/.test(v));
 
-      const sourceFile = cells[0];
-      const testFile = cells[1];
-      const status = cells[cells.length - 1]; // Last column is always status
+    for (const row of pipeRows.slice(1)) { // skip the header row
+      const cells = splitRow(row);
+      const sourceFile = cells[sourceIdx] || '';
+      const status = cells[statusIdx] || '';
 
-      // Skip template/example rows and italic placeholder rows
-      if (sourceFile.startsWith('<!--') || sourceFile === 'Source File' || sourceFile.startsWith('*')) continue;
+      // Skip template/example rows and italic placeholder rows.
+      if (!sourceFile || 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('❌')) {
+      if (status.includes('❌')) {
         results.total++;
-        results.warnings.push(
-          `TEST-SPEC declares ${sourceFile} as ❌ — missing tests`
-        );
-      } else if (status && status.includes('⚠️')) {
+        results.warnings.push(`TEST-SPEC declares ${sourceFile} as ❌ — missing tests`);
+      } else if (status.includes('⚠️')) {
         results.total++;
-        results.warnings.push(
-          `TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`
-        );
+        results.warnings.push(`TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`);
       }
 
       // ── File existence checks ───────────────────────────────────────
-      // Verify source file still exists (catch stale map entries)
+      // Verify source file still exists (catch stale map entries).
       const cleanSource = sourceFile.replace(/`/g, '').trim();
-      if (cleanSource && cleanSource !== '—' && cleanSource !== 'Source File') {
-        const sourcePath = resolve(projectDir, cleanSource);
-        if (!existsSync(sourcePath)) {
-          results.total++;
-          results.warnings.push(
-            `Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`
-          );
-        } else {
-          results.total++;
+      if (cleanSource && cleanSource !== '—' && cleanSource !== 'Source File' && isPathLike(cleanSource)) {
+        results.total++;
+        if (existsSync(resolve(projectDir, cleanSource))) {
           results.passed++;
+        } else {
+          results.warnings.push(`Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`);
         }
       }
 
-      // Verify test file exists (catch wrong/stale test references)
-      const cleanTest = testFile ? testFile.replace(/`/g, '').trim() : '';
-      if (cleanTest && cleanTest !== '—' && cleanTest !== 'Test File' &&
-          cleanTest !== 'Unit Test' && !cleanTest.includes('N/A')) {
-        const testPath = resolve(projectDir, cleanTest);
-        if (!existsSync(testPath)) {
-          results.total++;
-          results.warnings.push(
-            `Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`
-          );
-        } else {
-          results.total++;
+      // Verify EVERY declared test file exists — Unit Test AND Integration Test
+      // (the old parser only checked one column).
+      for (const ti of testIdxs) {
+        const cleanTest = (cells[ti] || '').replace(/`/g, '').trim();
+        if (isPlaceholder(cleanTest) || !isPathLike(cleanTest)) continue;
+        results.total++;
+        if (existsSync(resolve(projectDir, cleanTest))) {
           results.passed++;
+        } else {
+          results.warnings.push(`Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`);
         }
       }
     }
@@ -175,7 +196,11 @@ export function validateTestSpec(projectDir, config) {
 
     if (hasTestDir || hasColocated || hasConfigTests) {
       // 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. Add a "## Source-to-Test Map" table with `| Source | Test file | Status |` columns — run `docguard explain "no service-to-test mappings"` for the exact format.';
+      // v0.24: the validator reads column 1 as source, column 2 as the test
+      // file, and the last as status — so both the minimal 3-column shape and
+      // the 4-column table `docguard generate` emits are accepted. Say so, since
+      // the guidance previously contradicted the generated skeleton (field report).
+      results.note = 'TEST-SPEC.md declares no service-to-test mappings. Add a "## Source-to-Test Map" table — column 1 is the source, column 2 the test file, the last column the status. Both `| Source | Test file | Status |` and the generated `| Source File | Unit Test | Integration Test | Status |` shapes work. Run `docguard explain testSpec` for details.';
     } else {
       results.warnings.push(
         'No test directory or co-located test files found. ' +

package/cli/validators/todo-tracking.mjs

@@ -35,8 +35,10 @@ const TEST_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
 
 // ──── Patterns ────
 
-const TODO_PATTERN = /\b(TODO|FIXME|HACK|XXX|TEMP(?!late|orar)|WORKAROUND)\s*[(:]/;
-const TODO_EXTRACT = /\b(TODO|FIXME|HACK|XXX|TEMP(?!late|orar)|WORKAROUND)\s*[:(]?\s*(.+)/;
+// TEMP must be the standalone word — `(?![A-Za-z])` excludes TEMPLATE, TEMPORARY,
+// TEMPO, TEMPEST, etc. (the old `(?!late|orar)` only caught the first two).
+const TODO_PATTERN = /\b(TODO|FIXME|HACK|XXX|TEMP(?![A-Za-z])|WORKAROUND)\s*[(:]/;
+const TODO_EXTRACT = /\b(TODO|FIXME|HACK|XXX|TEMP(?![A-Za-z])|WORKAROUND)\s*[:(]?\s*(.+)/;
 
 // Matches a comment-opening marker. Real TODOs live in comments — restricting
 // matches to text AFTER a comment marker prevents false positives from regex

package/cli/validators/traceability.mjs

@@ -15,7 +15,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
-import { TRACE_MAP, TEST_PATTERNS } from '../shared-trace-patterns.mjs';
+import { TRACE_MAP, TEST_PATTERNS, isTraceableSource } from '../shared-trace-patterns.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -39,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,
 ];
 
 /**
@@ -102,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;
       }

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.23.0"
-  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.25.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.23.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.23.0 -->
+<!-- docguard:version: 0.25.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.23.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.23.0 -->
+<!-- docguard:version: 0.25.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.23.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.23.0 -->
+<!-- docguard:version: 0.25.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.23.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.23.0 -->
+<!-- docguard:version: 0.25.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.23.0
+  version: 0.25.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
+<!-- docguard:version: 0.25.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.25.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.25.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.25.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.25.0
         with:
           command: score
           format: json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.23.0",
+  "version": "0.25.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": {}
+  ]
 }