docguard-cli 0.14.1 → 0.15.1

package/cli/commands/guard.mjs

@@ -198,7 +198,7 @@ export function runGuardInternal(projectDir, config) {
  * Freshness (git log), Traceability (REQ scan), Doc-Quality (prose lint) —
  * stay off for speed.
  */
-export const CHANGED_ONLY_VALIDATORS = ['docsSync', 'environment', 'apiSurface'];
+export const CHANGED_ONLY_VALIDATORS = ['docsSync', 'environment', 'apiSurface', 'drift', 'todoTracking'];
 
 /**
  * Build a validators map that enables only the pre-commit-lite set.

package/cli/commands/init.mjs

@@ -167,6 +167,10 @@ export async function runInit(projectDir, config, flags) {
     const ptc = typeDefaults[detectedType] || typeDefaults.unknown;
 
     const defaultConfig = {
+      // v0.15-P4: $schema reference enables VS Code / IDE autocomplete +
+      // validation for .docguard.json fields. Picked up by any
+      // JSON-Schema-aware editor; ignored by DocGuard itself.
+      $schema: 'https://raccioly.github.io/docguard/schemas/docguard-config.schema.json',
       projectName: config.projectName,
       version: '0.5',
       profile: profileName,

package/cli/scanners/memory-plan.mjs

@@ -29,13 +29,58 @@ const md = {
   },
 };
 
+/**
+ * v0.15-P1: in-process cache. buildMemoryPlan is expensive (~400ms on
+ * wu-whatsappinbox, 33% of total guard validator time) because it triggers
+ * routes/schemas/screens/frontend scanners — all of which walk the source
+ * tree. Within a single guard run, sync, generate, and the Generated-
+ * Staleness validator all ask for the SAME plan; without caching they each
+ * re-pay the cost.
+ *
+ * Cache key: projectDir + a config fingerprint that captures the fields the
+ * scanners actually consume (sourceRoot, ignore, projectType). Other config
+ * mutations (e.g. changedFiles per-validator) don't invalidate the plan.
+ *
+ * Bypass with `_skipCache: true` in opts — used by tests and any caller that
+ * wants a fresh scan.
+ */
+const _memoryPlanCache = new Map(); // key → plan
+
+export function clearMemoryPlanCache() {
+  _memoryPlanCache.clear();
+}
+
+function _cacheKey(projectDir, config) {
+  return JSON.stringify({
+    dir: projectDir,
+    sourceRoot: config.sourceRoot,
+    ignore: Array.isArray(config.ignore) ? [...config.ignore].sort() : null,
+    projectType: config.projectType,
+    profile: config.profile,
+  });
+}
+
 /**
  * Build the full memory plan for a project.
  * @returns {{ profile, surface, docs, agentTasks }}
  *   docs[].sections[]: { id, source:'code', body } OR { id, source:'human', task, grounding }
  *   agentTasks: flattened prose tasks the AI must write.
  */
-export function buildMemoryPlan(projectDir, config = {}) {
+export function buildMemoryPlan(projectDir, config = {}, opts = {}) {
+  if (!opts._skipCache) {
+    const key = _cacheKey(projectDir, config);
+    const cached = _memoryPlanCache.get(key);
+    if (cached) return cached;
+  }
+  const result = _buildMemoryPlanUncached(projectDir, config);
+  if (!opts._skipCache) {
+    _memoryPlanCache.set(_cacheKey(projectDir, config), result);
+  }
+  return result;
+}
+
+// Original implementation, renamed so the public buildMemoryPlan can wrap it.
+function _buildMemoryPlanUncached(projectDir, config = {}) {
   const profile = detectProjectProfile(projectDir, config);
   const primaryFramework = profile.primary?.framework || profile.frameworks[0] || '';
 

package/cli/scanners/schemas.mjs

@@ -690,20 +690,45 @@ function readFileSafe(path) {
   try { return readFileSync(path, 'utf-8'); } catch { return null; }
 }
 
+// v0.15-P2: walkDir is called 8 times across schemas.mjs (Pydantic, Mongoose,
+// Prisma, SQLAlchemy, Sequelize, GORM, Sqlx, Hibernate). Each call walks the
+// same tree. Cache the file list per (dir, extension-set) so subsequent
+// callers iterate an array instead of re-traversing.
+//
+// Cache key: just the dir path. The extension filter is constant across all
+// callers (the regex hard-coded below), so a single cache slot per dir works.
+// Lifetime: per-process. `clearWalkDirCache()` invalidates for tests.
+const _walkDirCache = new Map(); // dir → string[] of file paths
+
+export function clearWalkDirCache() {
+  _walkDirCache.clear();
+}
+
+const _CODE_FILE_RE = /\.(js|mjs|cjs|ts|tsx|jsx|py|rs|go|java|kt|rb)$/;
+
+function _collectFiles(dir, out) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      _collectFiles(fullPath, out);
+    } else if (entry.isFile() && _CODE_FILE_RE.test(entry.name)) {
+      out.push(fullPath);
+    }
+  }
+}
+
 function walkDir(dir, callback) {
   if (!existsSync(dir)) return;
-  try {
-    const entries = readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (IGNORE_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
-      const fullPath = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walkDir(fullPath, callback);
-      } else if (entry.isFile() && /\.(js|mjs|cjs|ts|tsx|jsx|py|rs|go|java|kt|rb)$/.test(entry.name)) {
-        callback(fullPath);
-      }
-    }
-  } catch { /* skip */ }
+  let files = _walkDirCache.get(dir);
+  if (!files) {
+    files = [];
+    _collectFiles(dir, files);
+    _walkDirCache.set(dir, files);
+  }
+  for (const f of files) callback(f);
 }
 
 /**

package/cli/validators/drift.mjs

@@ -20,21 +20,27 @@ const IGNORE_DIRS = new Set([
 export function validateDrift(projectDir, config) {
   const results = { name: 'drift', errors: [], warnings: [], passed: 0, total: 0 };
 
-  // Find all // DRIFT: comments in source code
-  const driftComments = [];
-  walkDir(projectDir, (filePath) => {
+  // v0.15-P3: when config.changedFiles is set (--changed-only mode), only
+  // visit the listed paths. Drift comments in unchanged files are still in
+  // git so they'll be caught by a full guard run; pre-commit hooks care
+  // about NEW drift comments in this commit.
+  const scanFile = (filePath) => {
     const ext = extname(filePath);
     if (!CODE_EXTENSIONS.has(ext)) return;
-
-    const content = readFileSync(filePath, 'utf-8');
-
-    // Fast early-return: skip expensive string split if no comment exists
+    // v0.15 hotfix: test files commonly contain literal `// DRIFT:` inside
+    // string fixtures (e.g. `'// DRIFT: a-drift\n'`). Reading the test as
+    // source would treat the string as a real drift comment. Skip test
+    // files unless the user opts in — same pattern TODO-Tracking uses.
+    const rel = filePath.replace(projectDir + '/', '');
+    const includeTests = config?.drift?.includeTestFiles === true;
+    if (!includeTests && /(^|\/)(__tests__|tests?|spec)\/|\.(test|spec)\.[^.]+$/.test(rel)) {
+      return;
+    }
+    let content;
+    try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
     if (!content.includes('DRIFT:')) return;
-
     const lines = content.split('\n');
-
     lines.forEach((line, i) => {
-      // Match various comment styles: // DRIFT:, # DRIFT:, /* DRIFT:, -- DRIFT:
       const match = line.match(/(?:\/\/|#|\/\*|\-\-)\s*DRIFT:\s*(.+)/i);
       if (match) {
         driftComments.push({
@@ -44,7 +50,16 @@ export function validateDrift(projectDir, config) {
         });
       }
     });
-  });
+  };
+
+  const driftComments = [];
+  if (Array.isArray(config.changedFiles) && config.changedFiles.length > 0) {
+    for (const rel of config.changedFiles) {
+      scanFile(resolve(projectDir, rel));
+    }
+  } else {
+    walkDir(projectDir, scanFile);
+  }
 
   if (driftComments.length === 0) {
     // No // DRIFT: comments to reconcile — not applicable (NOT a pass).

package/cli/validators/todo-tracking.mjs

@@ -329,6 +329,20 @@ function isSelfPath(fullPath) {
 }
 
 function findTodos(rootDir, dir, todos, config) {
+  // v0.15-P3: when config.changedFiles is set (--changed-only mode), only
+  // scan those paths. New TODOs in this commit get caught; pre-existing
+  // TODOs in unchanged files are still tracked by full guard runs.
+  if (dir === rootDir && Array.isArray(config?.changedFiles) && config.changedFiles.length > 0) {
+    for (const rel of config.changedFiles) {
+      const full = resolve(rootDir, rel);
+      let stat;
+      try { stat = statSync(full); } catch { continue; }
+      if (!stat.isFile()) continue;
+      _scanTodoFile(rootDir, full, todos, config);
+    }
+    return;
+  }
+
   let entries;
   try { entries = readdirSync(dir); } catch { return; }
 
@@ -345,47 +359,44 @@ function findTodos(rootDir, dir, todos, config) {
     if (stat.isDirectory()) {
       findTodos(rootDir, full, todos, config);
     } else {
-      const ext = extname(entry).toLowerCase();
-      if (!SOURCE_EXTENSIONS.has(ext)) continue;
-
-      const relPath = relative(rootDir, full);
-
-      // Skip test files unless explicitly opted in — test fixture strings
-      // commonly contain comment markers inside template literals that the
-      // single-line heuristic can't distinguish from real comments.
-      if (!includeTests && isTestFilePath(relPath)) continue;
-
-      // Skip the validator's own source file — its docstring legitimately
-      // names the annotation keywords it scans for.
-      if (isSelfPath(full)) continue;
-
-      // Apply config ignore patterns (todoIgnore + global ignore)
-      if (config && shouldIgnore(relPath, config, 'todoIgnore')) continue;
-
-      let content;
-      try { content = readFileSync(full, 'utf-8'); } catch { continue; }
-
-      // Fast early-return: skip expensive string split if no TODO patterns exist
-      if (!TODO_PATTERN.test(content)) continue;
-
-      const lines = content.split('\n');
-
-      for (let i = 0; i < lines.length; i++) {
-        // Restrict scanning to text inside a comment — keeps the regex from
-        // matching its own keyword list when DocGuard reads its own source.
-        const commentText = commentPortion(lines[i]);
-        if (commentText === null) continue;
-        if (TODO_PATTERN.test(commentText)) {
-          const match = commentText.match(TODO_EXTRACT);
-          if (match) {
-            todos.push({
-              keyword: match[1].toUpperCase(),
-              text: match[2].trim(),
-              file: relPath,
-              line: i + 1,
-            });
-          }
-        }
+      _scanTodoFile(rootDir, full, todos, config);
+    }
+  }
+}
+
+/**
+ * v0.15-P3: per-file TODO scan extracted so both the full-tree walker and
+ * the --changed-only path can reuse it. Honors test-file filtering,
+ * self-path skip, ignore patterns, and the TODO regex.
+ */
+function _scanTodoFile(rootDir, full, todos, config) {
+  const includeTests = config?.todoTracking?.includeTestFiles === true;
+  const ext = extname(full).toLowerCase();
+  if (!SOURCE_EXTENSIONS.has(ext)) return;
+
+  const relPath = relative(rootDir, full);
+
+  if (!includeTests && isTestFilePath(relPath)) return;
+  if (isSelfPath(full)) return;
+  if (config && shouldIgnore(relPath, config, 'todoIgnore')) return;
+
+  let content;
+  try { content = readFileSync(full, 'utf-8'); } catch { return; }
+  if (!TODO_PATTERN.test(content)) return;
+
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const commentText = commentPortion(lines[i]);
+    if (commentText === null) continue;
+    if (TODO_PATTERN.test(commentText)) {
+      const match = commentText.match(TODO_EXTRACT);
+      if (match) {
+        todos.push({
+          keyword: match[1].toUpperCase(),
+          text: match[2].trim(),
+          file: relPath,
+          line: i + 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.14.1"
+  version: "0.15.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."
   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.14.1
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.14.1 -->
+<!-- docguard:version: 0.15.1 -->
 
 # 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.14.1
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.14.1 -->
+<!-- docguard:version: 0.15.1 -->
 
 # 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.14.1
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.14.1 -->
+<!-- docguard:version: 0.15.1 -->
 
 # 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.14.1
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.14.1 -->
+<!-- docguard:version: 0.15.1 -->
 
 # 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.14.1
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {
@@ -51,6 +51,7 @@
     "commands/",
     "extensions/",
     "docs/",
+    "schemas/",
     "STANDARD.md",
     "PHILOSOPHY.md",
     "README.md",

package/schemas/docguard-config.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raccioly.github.io/docguard/schemas/docguard-config.schema.json",
+  "title": "DocGuard project config (.docguard.json)",
+  "description": "Schema for the .docguard.json file that DocGuard reads at the root of every project. Add `\"$schema\": \"https://raccioly.github.io/docguard/schemas/docguard-config.schema.json\"` to your file to get autocomplete + validation in VS Code and other JSON-Schema-aware editors.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for editor autocomplete. Not consumed by DocGuard itself."
+    },
+    "version": {
+      "type": "string",
+      "description": "Schema version (0.1, 0.2, ... 0.5). Bumped when fields are added or behavior changes. Migrate with `docguard upgrade --apply`.",
+      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
+    },
+    "projectName": {
+      "type": "string",
+      "description": "Human-friendly project name used in guard output."
+    },
+    "profile": {
+      "type": "string",
+      "enum": ["starter", "standard", "enterprise"],
+      "description": "Compliance profile. starter = minimal, standard = full CDD, enterprise = adds advanced validators.",
+      "default": "standard"
+    },
+    "projectType": {
+      "type": "string",
+      "enum": ["cli", "library", "webapp", "api", "unknown"],
+      "description": "Project shape. Affects which validators run (e.g. webapp + api need env vars; cli/library can skip)."
+    },
+    "projectTypeConfig": {
+      "type": "object",
+      "description": "Per-type behavior knobs that override profile defaults.",
+      "properties": {
+        "needsEnvVars":   { "type": "boolean" },
+        "needsEnvExample":{ "type": "boolean" },
+        "needsE2E":       { "type": "boolean" },
+        "needsDatabase":  { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "sourceRoot": {
+      "type": "string",
+      "description": "Subdirectory containing the project's source files (e.g. `backend/src`). Validators scope to this when set."
+    },
+    "ignore": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns for paths every validator should skip. Merged with `.docguardignore` at runtime."
+    },
+    "securityIgnore": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns the Security validator additionally skips (e.g. test fixtures with intentional secrets)."
+    },
+    "todoIgnore": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns the TODO-Tracking validator additionally skips."
+    },
+    "requiredFiles": {
+      "type": "object",
+      "description": "Files DocGuard expects to exist. Missing files become Structure validator errors.",
+      "properties": {
+        "canonical": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Canonical doc paths (e.g. docs-canonical/ARCHITECTURE.md)."
+        },
+        "agentFile": {
+          "type": ["array", "string"],
+          "description": "Agent rule file(s) (e.g. AGENTS.md, CLAUDE.md). Array means any one suffices."
+        },
+        "changelog": { "type": "string" },
+        "driftLog":  { "type": "string" },
+        "root":      { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "validators": {
+      "type": "object",
+      "description": "Enable / disable individual validators. Set to false to skip.",
+      "properties": {
+        "structure":          { "type": "boolean" },
+        "docsSync":           { "type": "boolean" },
+        "drift":              { "type": "boolean" },
+        "changelog":          { "type": "boolean" },
+        "testSpec":           { "type": "boolean" },
+        "environment":        { "type": "boolean" },
+        "security":           { "type": "boolean" },
+        "architecture":       { "type": "boolean" },
+        "freshness":          { "type": "boolean" },
+        "traceability":       { "type": "boolean" },
+        "docsDiff":           { "type": "boolean" },
+        "apiSurface":         { "type": "boolean" },
+        "metadataSync":       { "type": "boolean" },
+        "docsCoverage":       { "type": "boolean" },
+        "docQuality":         { "type": "boolean" },
+        "todoTracking":       { "type": "boolean" },
+        "schemaSync":         { "type": "boolean" },
+        "specKit":            { "type": "boolean" },
+        "crossReference":    { "type": "boolean" },
+        "generatedStaleness":{ "type": "boolean" },
+        "metricsConsistency":{ "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "severity": {
+      "type": "object",
+      "description": "Per-validator severity overrides. Affects EXIT CODE only — display is unchanged. high = warnings fail CI (exit 1). low = warnings ignored. medium (default) = exit 2.",
+      "additionalProperties": {
+        "type": "string",
+        "enum": ["high", "medium", "low"]
+      }
+    },
+    "draftStalenessDays": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "How many days a `status: draft` doc may sit unmodified before Generated-Staleness warns. Default 14."
+    },
+    "testPattern": {
+      "type": "string",
+      "description": "Single glob identifying test files (legacy single-string form)."
+    },
+    "testPatterns": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns identifying test files. Preferred over testPattern."
+    },
+    "todoTracking": {
+      "type": "object",
+      "description": "TODO-Tracking validator overrides.",
+      "properties": {
+        "includeTestFiles": {
+          "type": "boolean",
+          "description": "If true, scan test files for TODO/FIXME annotations. Off by default to avoid false positives from comment-marker strings inside test fixtures."
+        }
+      },
+      "additionalProperties": true
+    },
+    "docQuality": {
+      "type": "object",
+      "description": "Doc-Quality validator overrides.",
+      "properties": {
+        "deepScan": {
+          "type": "boolean",
+          "description": "If true and the `understanding` CLI is on PATH, run its 31-metric deep analysis. Off by default."
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}