docguard-cli 0.25.1 → 0.27.0

package/cli/validators/security.mjs

@@ -8,6 +8,18 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { shouldIgnore, relPosix } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings, lineSuppresses } from '../findings.mjs';
+
+// Each secret pattern maps to a stable finding code (see cli/findings.mjs CODES)
+// so it is `explain`-able and inline-suppressible (`// docguard:ignore SEC00x`).
+const LABEL_TO_CODE = {
+  'hardcoded password': 'SEC001',
+  'hardcoded API key': 'SEC002',
+  'hardcoded secret key': 'SEC003',
+  'hardcoded access token': 'SEC004',
+  'AWS Access Key ID': 'SEC005',
+  'API secret key (Stripe/OpenAI pattern)': 'SEC006',
+};
 
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -54,11 +66,46 @@ function isSafePlaceholder(line, matchStr) {
   return SAFE_PATTERNS.some(p => p.test(line));
 }
 
-export function validateSecurity(projectDir, config) {
-  const results = { name: 'security', errors: [], warnings: [], passed: 0, total: 0 };
+/**
+ * v0.27 (field report #1): a password-style key whose VALUE is natural
+ * language — an error message, validation copy, UI string — is almost never a
+ * credential. e.g. a "New password must differ from recent passwords"
+ * validation message assigned to such a key.
+ *
+ * We don't drop these (a real secret that happens to read like prose must still
+ * surface — false-green is the failure mode this tool exists to prevent); we
+ * downgrade them to a LOW-CONFIDENCE warning the agent can suppress inline,
+ * instead of a blocking error. Heuristic per the field report: ≥3 words, OR
+ * ≥2 internal spaces, OR ends in sentence punctuation.
+ *
+ * @param {string} value - the literal inside the quotes
+ */
+function looksLikeProse(value) {
+  if (!value) return false;
+  const v = value.trim();
+  const words = v.split(/\s+/).filter(Boolean);
+  // Multi-word natural language (validation messages, UI copy, sentences).
+  if (words.length >= 3) return true;
+  // A 2-word sentence fragment ending in terminal punctuation — but NOT a
+  // single token like "SuperSecretPassword!" (strong passwords end in !/? too,
+  // so terminal punctuation ALONE must never reclassify a one-word value).
+  if (words.length >= 2 && /[.!?]$/.test(v)) return true;
+  return false;
+}
+
+/** Pull the first quoted literal out of a matched secret expression. */
+function quotedValue(matchStr) {
+  const m = matchStr.match(/['"]([^'"]*)['"]/);
+  return m ? m[1] : '';
+}
 
+export function validateSecurity(projectDir, config) {
+  /** @type {import('../findings.mjs').Finding[]} */
   const findings = [];
+  let passed = 0;
+  let total = 0;
   let scanned = 0;
+  let realSecretCount = 0;
 
   walkDir(projectDir, (filePath) => {
     const ext = extname(filePath);
@@ -89,25 +136,58 @@ export function validateSecurity(projectDir, config) {
         // Lazily initialize lines only when a match is found
         if (!lines) lines = content.split('\n');
 
-        // Find the line containing this match for context-aware filtering
-        const matchPos = match.index;
-        let charCount = 0;
-        let matchLine = '';
-        for (const line of lines) {
-          charCount += line.length + 1; // +1 for newline
-          if (charCount > matchPos) {
-            matchLine = line;
-            break;
-          }
-        }
+        // 1-based line number + the line above (for inline-pragma suppression).
+        const lineNo = content.slice(0, match.index).split('\n').length;
+        const matchLine = lines[lineNo - 1] || '';
+        const prevLine = lines[lineNo - 2] || '';
 
         // Skip known-safe placeholder/example values, but keep scanning for a
         // real one further down the file.
         if (isSafePlaceholder(matchLine, match[0])) continue;
 
-        findings.push({ file: relPath, label, match: match[0].substring(0, 30) + '...' });
+        const code = LABEL_TO_CODE[label];
+
+        // v0.27 (#8): honour an inline `// docguard:ignore SEC00x` pragma on the
+        // line or the line above — per-line suppression instead of blinding the
+        // whole file via `securityIgnore`.
+        if (code && lineSuppresses(code, matchLine, prevLine)) break;
+
+        const location = `${relPath}:${lineNo}`;
+        const value = quotedValue(match[0]);
+        const isProse = looksLikeProse(value);
+
+        if (isProse) {
+          // v0.27 (#1): natural-language value → low-confidence warning, not a
+          // blocking error. Still surfaced (no false-green), still suppressible,
+          // and now reportable via `docguard feedback`.
+          findings.push(mkFinding({
+            code, validator: 'security', severity: 'warn', confidence: 'low',
+            message: `${location}: possible ${label} — but the value reads like natural-language text (likely UI copy / a validation message, not a credential)`,
+            location,
+            suggestion: {
+              kind: 'suppress',
+              text: 'If this is UI copy or a message and not a real secret, suppress it inline.',
+              pragma: `// docguard:ignore ${code} — UI copy, not a credential`,
+            },
+            reportable: true,
+            redactedContext: `${label} pattern fired on a value that is natural-language text (~${value.trim().split(/\s+/).filter(Boolean).length} words). Literal omitted.`,
+          }));
+        } else {
+          realSecretCount++;
+          findings.push(mkFinding({
+            code, validator: 'security', severity: 'error', confidence: 'high',
+            message: `${location}: possible ${label} found`,
+            location,
+            suggestion: {
+              kind: 'fix',
+              text: 'Move the secret to an environment variable and read it via process.env / the platform secret store. Never commit credentials.',
+              command: code ? `docguard explain ${code}` : undefined,
+              pragma: code ? `// docguard:ignore ${code} — reason (only if a confirmed false positive)` : undefined,
+            },
+          }));
+        }
         // One finding per (file, label) is enough — the reported message is
-        // identical for repeats and we've already proven a real secret exists.
+        // identical for repeats and we've already proven a match exists.
         break;
       }
     }
@@ -116,35 +196,41 @@ export function validateSecurity(projectDir, config) {
   // Only count the secret scan as a passed check if we actually scanned files.
   // An empty scan that reports "no secrets" is a dangerous false ✅ — surface it.
   if (scanned > 0) {
-    results.total++;
-    if (findings.length === 0) {
-      results.passed++;
-    } else {
-      for (const f of findings) {
-        results.errors.push(`${f.file}: possible ${f.label} found`);
-      }
-    }
+    total++;
+    // Low-confidence (prose) findings do not fail the check — only real secrets do.
+    if (realSecretCount === 0) passed++;
   } else {
-    results.warnings.push(
-      'No source files were scanned for secrets — check config.sourceRoot / ignore patterns'
-    );
+    findings.push(mkFinding({
+      code: 'SEC011', validator: 'security', severity: 'warn', confidence: 'high',
+      message: 'No source files were scanned for secrets — check config.sourceRoot / ignore patterns',
+      suggestion: { kind: 'review', text: 'Verify config.sourceRoot and ignore patterns actually include your source tree.' },
+    }));
   }
 
   // Check .gitignore includes .env
-  results.total++;
+  total++;
   const gitignorePath = resolve(projectDir, '.gitignore');
   if (existsSync(gitignorePath)) {
     const gitignore = readFileSync(gitignorePath, 'utf-8');
     if (gitignore.includes('.env') || gitignore.includes('.env.local')) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push('.gitignore does not include .env — secrets may be committed');
+      findings.push(mkFinding({
+        code: 'SEC010', validator: 'security', severity: 'warn', confidence: 'high',
+        message: '.gitignore does not include .env — secrets may be committed',
+        location: '.gitignore',
+        suggestion: { kind: 'fix', text: 'Add `.env` and `.env.local` to .gitignore.' },
+      }));
     }
   } else {
-    results.warnings.push('No .gitignore found — secrets may be committed');
+    findings.push(mkFinding({
+      code: 'SEC010', validator: 'security', severity: 'warn', confidence: 'high',
+      message: 'No .gitignore found — secrets may be committed',
+      suggestion: { kind: 'fix', text: 'Create a .gitignore that excludes `.env` and `.env.local`.' },
+    }));
   }
 
-  return results;
+  return resultFromFindings(findings, { passed, total });
 }
 
 function walkDir(dir, callback) {

package/cli/validators/todo-tracking.mjs

@@ -262,6 +262,10 @@ function loadTrackingDocs(projectDir, config) {
   const trackingFiles = [
     'ROADMAP.md', 'CURRENT-STATE.md', 'TODO.md', 'BACKLOG.md',
     'docs-canonical/ARCHITECTURE.md', 'CHANGELOG.md',
+    // v0.27 (field report #6): many projects keep the roadmap/backlog under
+    // docs-canonical/ — a TODO tracked there was wrongly read as "untracked".
+    'docs-canonical/ROADMAP.md', 'docs-canonical/CURRENT-STATE.md',
+    'docs-canonical/BACKLOG.md', 'docs-canonical/TODO.md',
     ...(config.todoTracking?.trackingFiles || []),
   ];
 

package/cli/writers/mechanical.mjs

@@ -47,15 +47,33 @@ const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 function applyReplaceCount(projectDir, fix) {
   const full = resolve(projectDir, fix.file);
   if (!existsSync(full)) return { applied: false };
+  // Bug #2 (fail-closed): NEVER overwrite a number without provenance proving
+  // the "actual" describes the SAME subject. The Metrics-Consistency validator
+  // stamps `actualSource` (e.g. "docguard.guard.checks") only for claims it
+  // verified are bound to DocGuard. A fix lacking it is refused rather than risk
+  // corrupting a correct, unrelated number.
+  if (!fix.actualSource) {
+    return { applied: false, detail: `${fix.file}: skipped "${fix.found} ${fix.label}" → "${fix.actual}" — no provenance (actualSource) to prove same subject` };
+  }
   const content = readFileSync(full, 'utf-8');
   // v0.15.2 hotfix: case-insensitive label match. Mirrors the validator's
   // detection regex (which is `gi`). Without `i` here, the applier would
   // skip "21 Validators" (capitalized) even though Metrics-Consistency
   // detected it — leaving the user with a warning they couldn't auto-fix.
-  // The /docguard.diagnose run on canonical-spec-kit surfaced this.
   const re = new RegExp(`\\b${esc(fix.found)}(\\s+(?:automated\\s+)?${esc(fix.label)}\\b)`, 'gi');
-  const next = content.replace(re, `${fix.actual}$1`);
-  if (next === content) return { applied: false };
+  // Only rewrite occurrences on a DocGuard-bound line (same predicate as the
+  // validator's subject-binding) so a stray "<found> <label>" elsewhere in the
+  // file is never collateral-damaged by the global replace.
+  let changed = false;
+  const next = content.replace(re, (m, tail, offset, str) => {
+    const lineStart = str.lastIndexOf('\n', offset) + 1;
+    let lineEnd = str.indexOf('\n', offset);
+    if (lineEnd === -1) lineEnd = str.length;
+    if (!/docguard/i.test(str.slice(lineStart, lineEnd))) return m; // not bound → leave untouched
+    changed = true;
+    return `${fix.actual}${tail}`;
+  });
+  if (!changed || next === content) return { applied: false };
   writeFileSync(full, next, 'utf-8');
   return { applied: true, detail: `${fix.file}: "${fix.found} ${fix.label}" → "${fix.actual} ${fix.label}"` };
 }

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.25.1"
+  version: "0.27.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"

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

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

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

package/package.json

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