docguard-cli 0.14.0 → 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/cross-reference.mjs

@@ -27,7 +27,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, dirname, basename } from 'node:path';
+import { resolve, join, dirname, basename, relative } from 'node:path';
 
 /**
  * Slugify a heading the way GitHub's markdown anchors work.
@@ -294,6 +294,7 @@ function collectCanonicalDocs(projectDir) {
 export function validateCrossReferences(projectDir, _config = {}) {
   const errors = [];
   const warnings = [];
+  const fixes = [];
   let passed = 0;
   let total = 0;
 
@@ -364,13 +365,27 @@ export function validateCrossReferences(projectDir, _config = {}) {
         if (!matches) {
           const where = targetPath === docPath ? 'same doc' : basename(targetPath);
           // S-12: suggest the closest matching anchor when there's a near-miss.
-          // Three of five wu user-fixes were "heading renamed, link not updated"
-          // — a suggested-slug hint makes those deterministic-fixable.
           const suggestion = anchors ? suggestAnchor(normalizedAnchor, anchors) : null;
           const hint = suggestion ? ` (did you mean #${suggestion}?)` : '';
+          // v0.14.1-S12+: when the suggestion is HIGH-CONFIDENCE — unambiguous
+          // and very close (edit distance <= 2) — emit a mechanical fix so
+          // `docguard fix --write` resolves it without AI. Other near-misses
+          // still get the hint but no fix (the user needs to verify intent).
+          const isHighConfidence = suggestion && isUnambiguousSuggestion(normalizedAnchor, suggestion, anchors);
           warnings.push(
-            `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading${hint}`
+            `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading${hint}` +
+            (isHighConfidence ? ' [auto-fixable]' : '')
           );
+          if (isHighConfidence) {
+            fixes.push({
+              type: 'replace-anchor',
+              doc: relative(projectDir, docPath),
+              line: ref.line,
+              from: ref.anchor,
+              to: suggestion,
+              summary: `${docName}:${ref.line} #${ref.anchor} → #${suggestion}`,
+            });
+          }
           continue;
         }
       }
@@ -379,5 +394,28 @@ export function validateCrossReferences(projectDir, _config = {}) {
     }
   }
 
-  return { errors, warnings, passed, total };
+  return { errors, warnings, passed, total, fixes };
+}
+
+/**
+ * v0.14.1-S12+ — is the suggested anchor an unambiguous, high-confidence
+ * match? Two criteria, both must hold:
+ *   1. Edit distance between the broken anchor and the suggestion is <= 2
+ *      (catches typos and minor renames, refuses major slug rewrites).
+ *   2. The suggestion is the ONLY anchor that close — no other anchor
+ *      within distance <= 2. Avoids fixing to the wrong candidate when
+ *      multiple are similar.
+ */
+function isUnambiguousSuggestion(broken, suggestion, anchors) {
+  if (!broken || !suggestion || !anchors) return false;
+  const sugDist = editDistance(broken, suggestion);
+  if (sugDist > 2) return false;
+  // Count other anchors that are also within the same tight budget.
+  let closeCandidates = 0;
+  for (const a of anchors) {
+    if (a === suggestion) continue;
+    if (editDistance(broken, a) <= 2) closeCandidates++;
+    if (closeCandidates > 0) return false; // ambiguous
+  }
+  return true;
 }

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/metrics-consistency.mjs

@@ -64,6 +64,14 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
     { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators' },
   ];
 
+  // v0.14.1-N1: dedup by (file, label, found) — a file that mentions the
+  // stale number multiple times produces ONE warning, not one per occurrence.
+  // The replace-count applier already uses replace-all semantics, so a single
+  // fix per (file, label) is sufficient. Previously: "X.md" appearing 2× with
+  // the same drift would generate 2 warnings + 2 fixes (the second a no-op).
+  const reportedDrift = new Set();      // key: `${relPath}|${label}|${found}`
+  const reportedPass  = new Set();      // key: `${relPath}|${label}` — only count one pass per (file, label)
+
   for (const mdFile of mdFiles) {
     const relPath = relative(projectDir, mdFile);
     // Skip changelog (historical numbers are fine by definition)
@@ -79,16 +87,32 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
 
       regex.lastIndex = 0;
       let match;
+      // Collect distinct (found-value) instances within THIS file first,
+      // then emit ONE warning per distinct value. A file that says "20" on
+      // line 5 and "20" on line 50 is the same drift; "20" on line 5 and
+      // "19" on line 50 are two distinct drifts.
+      const distinctFoundInFile = new Set();
       while ((match = regex.exec(content)) !== null) {
-        total++;
-        const found = parseInt(match[1], 10);
-        if (found !== actuals[key] && found > 0) {
+        distinctFoundInFile.add(parseInt(match[1], 10));
+      }
+      if (distinctFoundInFile.size === 0) continue;
+
+      for (const found of distinctFoundInFile) {
+        if (found > 0 && found !== actuals[key]) {
+          const driftKey = `${relPath}|${label}|${found}`;
+          if (reportedDrift.has(driftKey)) continue;
+          reportedDrift.add(driftKey);
+          total++;
           warnings.push(
             `${relPath} says "${found} ${label}" but actual count is ${actuals[key]}. Fix with \`docguard fix --write\``
           );
-          // Deterministic, surgical token replacement — safe to auto-apply.
           fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key] });
         } else {
+          // Matches the actual count — one pass per (file, label), not per occurrence.
+          const passKey = `${relPath}|${label}`;
+          if (reportedPass.has(passKey)) continue;
+          reportedPass.add(passKey);
+          total++;
           passed++;
         }
       }

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/cli/writers/mechanical.mjs

@@ -143,12 +143,45 @@ function applyRegenerateSection(projectDir, fix) {
   return { applied: true, detail: `${fix.doc}: regenerated § ${fix.sectionId}` };
 }
 
+/**
+ * v0.14.1-S12+ — replace-anchor: rewrite a broken markdown anchor with a
+ * high-confidence suggested slug. Emitted by Cross-Reference when its
+ * fuzzy match is unambiguous (edit distance <= 2, no other close candidates).
+ *
+ * fix shape: { type: 'replace-anchor', doc, from, to, line?, summary? }
+ *
+ * Bounded: only rewrites occurrences of `](#${from})` and `](#X${from})`-like
+ * forms — won't touch the broken slug if it happens to appear as plain text.
+ * Idempotent: if no occurrence is found (already fixed), no-op.
+ */
+function applyReplaceAnchor(projectDir, fix) {
+  if (!fix.doc || !fix.from || !fix.to) {
+    return { applied: false, skipped: 'replace-anchor needs doc, from, to' };
+  }
+  const full = resolve(projectDir, fix.doc);
+  if (!existsSync(full)) return { applied: false, skipped: `doc not found: ${fix.doc}` };
+  const content = readFileSync(full, 'utf-8');
+
+  // Match an anchor inside a markdown link: `](#from)` OR `](path#from)`.
+  // Use a regex that captures the prefix and suffix so we only touch the
+  // anchor part — leaving the link text and path intact.
+  const fromEsc = esc(fix.from);
+  const re = new RegExp(`(\\]\\([^)]*#)${fromEsc}([)\\s])`, 'g');
+  const next = content.replace(re, `$1${fix.to}$2`);
+  if (next === content) {
+    return { applied: false, skipped: `${fix.doc}: anchor #${fix.from} not found (already fixed?)` };
+  }
+  writeFileSync(full, next, 'utf-8');
+  return { applied: true, detail: `${fix.doc}: #${fix.from} → #${fix.to}` };
+}
+
 const APPLIERS = {
   'replace-count': applyReplaceCount,
   'replace-version': applyReplaceVersion,
   'insert-changelog-unreleased': applyInsertChangelogUnreleased,
   'remove-endpoint': applyRemoveEndpoint,
   'regenerate-section': applyRegenerateSection,
+  'replace-anchor': applyReplaceAnchor,
 };
 
 export const MECHANICAL_FIX_TYPES = Object.keys(APPLIERS);

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.0"
+  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.0
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- 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.0
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- 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.0
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- 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.0
+  version: 0.15.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- 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.0
+  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.0",
+  "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
+}