docguard-cli 0.17.1 → 0.18.1

package/cli/commands/score.mjs

@@ -8,6 +8,63 @@ import { resolve, join, extname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { c } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
+import { runGuardInternal } from './guard.mjs';
+
+/**
+ * v0.18-P3: map score categories to the validator keys that contribute.
+ * One category can roll up multiple validators (e.g. "environment" pulls
+ * from Environment validator findings). When --diff fires, we use this
+ * to surface the underlying warnings.
+ */
+const _SCORE_TO_VALIDATORS = {
+  structure:    ['structure'],
+  docQuality:   ['docQuality', 'docsCoverage', 'docsSync'],
+  testing:      ['testSpec', 'todoTracking'],
+  security:     ['security'],
+  environment:  ['environment'],
+  drift:        ['drift'],
+  changelog:    ['changelog'],
+  architecture: ['architecture'],
+};
+
+function _showScoreDiff(projectDir, config, scores) {
+  console.log(`  ${c.bold}── Drill-down (--diff) ──${c.reset}\n`);
+  // Pull live guard data; reuses the in-process plan cache so this is
+  // cheap when run right after the score calc.
+  const guard = runGuardInternal(projectDir, config);
+  const byKey = new Map(guard.validators.map(v => [v.key, v]));
+
+  let anyShown = false;
+  for (const [category, score] of Object.entries(scores)) {
+    if (score === 100) continue;
+    const validatorKeys = _SCORE_TO_VALIDATORS[category];
+    if (!validatorKeys) continue;
+    const warnings = [];
+    const errors = [];
+    for (const k of validatorKeys) {
+      const v = byKey.get(k);
+      if (!v) continue;
+      warnings.push(...(v.warnings || []));
+      errors.push(...(v.errors || []));
+    }
+    if (warnings.length === 0 && errors.length === 0) continue;
+    anyShown = true;
+    console.log(`  ${c.yellow}${category}${c.reset} ${c.dim}(${score}/100)${c.reset}`);
+    for (const e of errors.slice(0, 5)) console.log(`     ${c.red}✗${c.reset} ${e}`);
+    for (const w of warnings.slice(0, 5)) console.log(`     ${c.yellow}⚠${c.reset} ${w}`);
+    const totalIssues = errors.length + warnings.length;
+    if (totalIssues > 5) console.log(`     ${c.dim}... ${totalIssues - 5} more${c.reset}`);
+    console.log('');
+  }
+
+  if (!anyShown) {
+    console.log(`  ${c.dim}No specific findings available for the weakest categories. They may be scoring below 100 due to structural/quality heuristics rather than discrete check failures.${c.reset}\n`);
+  } else {
+    console.log(`  ${c.dim}Fix options:${c.reset}`);
+    console.log(`    ${c.dim}• Run ${c.cyan}docguard explain "<warning>"${c.dim} for the full validator help on any line above${c.reset}`);
+    console.log(`    ${c.dim}• Run ${c.cyan}docguard fix --write${c.dim} for the mechanical fixes${c.reset}`);
+  }
+}
 
 const WEIGHTS = {
   structure: 25,     // Required files exist
@@ -116,6 +173,14 @@ export function runScore(projectDir, config, flags) {
     console.log('');
   }
 
+  // v0.18-P3: --diff drill-down. Symmetric to v0.17 memory --diff.
+  // Shows WHICH specific checks dragged each weak category down by joining
+  // the guard validator warnings to score categories. Cheap: we already
+  // import runGuardInternal; one extra guard run on `--diff` is acceptable.
+  if (flags.diff) {
+    _showScoreDiff(projectDir, config, scores);
+  }
+
   // ── Tax Estimate (--tax flag) ──
   if (flags.tax) {
     const tax = estimateDocTax(projectDir, config, scores);

package/cli/scanners/memory-plan.mjs

@@ -30,21 +30,112 @@ const md = {
 };
 
 /**
- * v0.15-P1: in-process cache. buildMemoryPlan is expensive (~400ms on
- * an enterprise client project, 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.
+ * v0.15-P1: in-process cache (Map). buildMemoryPlan is expensive (~400ms on
+ * an enterprise client project) because it triggers routes/schemas/screens/
+ * frontend scanners — all of which walk the source tree.
  *
- * 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.
+ * v0.18-P2: cross-process cache (`.docguard/plan.cache.json`). CI flows that
+ * run guard → sync → fix as separate processes each pay the build cost.
+ * The disk cache shares the plan across processes, keyed by a tree-state
+ * hash so we invalidate when the source tree changes.
  *
- * Bypass with `_skipCache: true` in opts — used by tests and any caller that
- * wants a fresh scan.
+ * Cache key: projectDir + a config fingerprint (sourceRoot, ignore,
+ * projectType, profile). Other config mutations (e.g. changedFiles
+ * per-validator) don't invalidate the plan.
+ *
+ * Bypass with `_skipCache: true` in opts — used by tests.
  */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { resolve as resolvePath, join as joinPath } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
 const _memoryPlanCache = new Map(); // key → plan
+const _DISK_CACHE_PATH = '.docguard/plan.cache.json';
+const _DISK_CACHE_VERSION = '1';  // bump if cache shape changes
+
+/**
+ * v0.18-P2: tree-state hash. Cheap signature of the source tree that
+ * changes whenever something a scanner would care about changes. We use:
+ *   - git HEAD commit SHA (when in a git repo) — captures committed state
+ *   - mtime sum of top-level config files (package.json, pyproject.toml,
+ *     Cargo.toml, etc.) — captures uncommitted bumps to deps
+ * Combined into a 12-char hex fingerprint.
+ *
+ * NOT a perfect cache key — a user editing src/foo.ts without bumping a
+ * config file won't invalidate. But guard/sync/fix all run in quick
+ * succession within a CI step, and the user's flow IS bump + commit + run.
+ * The tradeoff favors speed: the worst case is one stale plan per CI run,
+ * recoverable with `--no-plan-cache` or a tree change.
+ */
+function _treeStateHash(projectDir) {
+  let signal = '';
+  // git HEAD
+  try {
+    const sha = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    signal += `git:${sha};`;
+  } catch { /* not a git repo, or no commits */ }
+  // mtime of common manifest files
+  const manifests = [
+    'package.json', 'pyproject.toml', 'Cargo.toml', 'go.mod',
+    'pom.xml', 'build.gradle', 'Gemfile', 'composer.json',
+    '.docguard.json',
+  ];
+  for (const m of manifests) {
+    try {
+      const s = statSync(resolvePath(projectDir, m));
+      signal += `${m}:${s.mtimeMs};`;
+    } catch { /* not present */ }
+  }
+  return createHash('sha256').update(signal).digest('hex').slice(0, 12);
+}
+
+/**
+ * v0.18-P2: read the disk cache. Returns null when the file is missing,
+ * the schema version mismatches, the tree hash doesn't match, or anything
+ * about the load is suspicious. Never throws — cache miss is silent.
+ */
+function _readDiskCache(projectDir, configKey) {
+  try {
+    const p = resolvePath(projectDir, _DISK_CACHE_PATH);
+    if (!existsSync(p)) return null;
+    const data = JSON.parse(readFileSync(p, 'utf-8'));
+    if (data.v !== _DISK_CACHE_VERSION) return null;
+    if (data.configKey !== configKey) return null;
+    const currentHash = _treeStateHash(projectDir);
+    if (data.treeHash !== currentHash) return null;
+    return data.plan || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * v0.18-P2: write the disk cache. Best-effort — failures are silent (the
+ * in-process cache still works). `.docguard/` directory created if needed.
+ */
+function _writeDiskCache(projectDir, configKey, plan) {
+  try {
+    const fullDir = resolvePath(projectDir, '.docguard');
+    if (!existsSync(fullDir)) mkdirSync(fullDir, { recursive: true });
+    const payload = {
+      v: _DISK_CACHE_VERSION,
+      configKey,
+      treeHash: _treeStateHash(projectDir),
+      plan,
+      writtenAt: new Date().toISOString(),
+    };
+    writeFileSync(
+      resolvePath(projectDir, _DISK_CACHE_PATH),
+      JSON.stringify(payload),  // compact — this file isn't human-edited
+      'utf-8'
+    );
+  } catch {
+    // swallow — the cache is auxiliary
+  }
+}
 
 export function clearMemoryPlanCache() {
   _memoryPlanCache.clear();
@@ -67,14 +158,35 @@ function _cacheKey(projectDir, config) {
  *   agentTasks: flattened prose tasks the AI must write.
  */
 export function buildMemoryPlan(projectDir, config = {}, opts = {}) {
-  if (!opts._skipCache) {
-    const key = _cacheKey(projectDir, config);
+  const useCache = !opts._skipCache;
+  const key = useCache ? _cacheKey(projectDir, config) : null;
+
+  // L1: in-process Map (same-run guard → sync → fix).
+  if (useCache) {
     const cached = _memoryPlanCache.get(key);
     if (cached) return cached;
   }
+
+  // L2: cross-process disk cache (CI guard → CI sync → CI fix).
+  // v0.18-P2: opt-in via config.diskCache !== false (default ON).
+  // Tree-state hash invalidates when source files change.
+  const diskCacheEnabled = useCache && config.diskCache !== false;
+  if (diskCacheEnabled) {
+    const onDisk = _readDiskCache(projectDir, key);
+    if (onDisk) {
+      _memoryPlanCache.set(key, onDisk);  // promote to L1
+      return onDisk;
+    }
+  }
+
+  // Miss — build fresh.
   const result = _buildMemoryPlanUncached(projectDir, config);
-  if (!opts._skipCache) {
-    _memoryPlanCache.set(_cacheKey(projectDir, config), result);
+
+  if (useCache) {
+    _memoryPlanCache.set(key, result);
+  }
+  if (diskCacheEnabled) {
+    _writeDiskCache(projectDir, key, result);
   }
   return result;
 }

package/cli/validators/generated-staleness.mjs

@@ -23,12 +23,55 @@
  * @req SC-M1-004 — N/A when no source=code sections present in any doc
  */
 
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, basename, join } from 'node:path';
 
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { getSection } from '../writers/sections.mjs';
 
+/**
+ * v0.18-P1 fast-path: cheap pre-flight to detect whether ANY canonical doc
+ * has a `<!-- docguard:section ... source=code -->` marker OR a `status:
+ * draft` frontmatter. If neither exists anywhere, this validator has
+ * nothing to do — skip the expensive buildMemoryPlan call (~400ms on
+ * mid-sized repos, was 26-33% of total guard validator time).
+ *
+ * Returns { hasMarkers, hasDrafts }.
+ */
+function _quickScan(projectDir) {
+  const out = { hasMarkers: false, hasDrafts: false };
+  const candidateDirs = [
+    resolve(projectDir, 'docs-canonical'),
+    projectDir, // for README.md, AGENTS.md, etc.
+  ];
+  // We only need a single match in any file to know the validator has work.
+  // Short-circuit aggressively: stop the moment we find either signal.
+  for (const dir of candidateDirs) {
+    if (!existsSync(dir)) continue;
+    let entries;
+    try { entries = readdirSync(dir); } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.endsWith('.md')) continue;
+      // Skip very large files quickly — for canonical docs, > 200 KB is unusual
+      // and almost certainly not the marker-heavy file we're looking for.
+      let stat;
+      try { stat = statSync(join(dir, entry)); } catch { continue; }
+      if (!stat.isFile()) continue;
+      if (stat.size > 200_000) continue;
+      let content;
+      try { content = readFileSync(join(dir, entry), 'utf-8'); } catch { continue; }
+      if (!out.hasMarkers && /<!--\s*docguard:section\s+[^>]*source=code/i.test(content)) {
+        out.hasMarkers = true;
+      }
+      if (!out.hasDrafts && /(?:^---\s*\n[\s\S]*?\bstatus:\s*draft\b[\s\S]*?\n---|<!--\s*status:\s*draft\s*-->)/im.test(content)) {
+        out.hasDrafts = true;
+      }
+      if (out.hasMarkers && out.hasDrafts) return out;
+    }
+  }
+  return out;
+}
+
 /**
  * S-7: how long a generated doc may sit in `status: draft` before we warn.
  * 14 days is the v0.13.1 default — long enough to absorb a typical sprint,
@@ -62,6 +105,17 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
   // of just warning. No AI needed — the scanner already knows the right body.
   const result = { errors: [], warnings: [], passed: 0, total: 0, fixes: [] };
 
+  // v0.18-P1: cheap pre-flight. If no canonical doc has a source=code marker
+  // AND no doc is in status:draft, this validator has nothing to do — skip
+  // the expensive buildMemoryPlan call. Generated-Staleness used to be
+  // 26-33% of total validator time on projects with NO markers, all
+  // wasted. The fast-path scans markdown files for the marker substring
+  // only — no parsing, no tree walk.
+  const quick = _quickScan(projectDir);
+  if (!quick.hasMarkers && !quick.hasDrafts) {
+    return { ...result, applicable: false, note: 'no docguard:section markers and no status:draft docs' };
+  }
+
   // Build the canonical memory plan (what the docs SHOULD contain). If this
   // fails or produces no docs, the validator is N/A.
   let plan;

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.17.1"
+  version: "0.18.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.17.1
+  version: 0.18.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.17.1 -->
+<!-- docguard:version: 0.18.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.17.1
+  version: 0.18.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.17.1 -->
+<!-- docguard:version: 0.18.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.17.1
+  version: 0.18.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.17.1 -->
+<!-- docguard:version: 0.18.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.17.1
+  version: 0.18.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.17.1 -->
+<!-- docguard:version: 0.18.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.17.1
+  version: 0.18.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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