docguard-cli 0.13.0__tar.gz → 0.14.0__tar.gz

{docguard_cli-0.13.0/extensions/spec-kit-docguard → docguard_cli-0.14.0/.agent}/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.13.0
+  version: 0.14.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.13.0 -->
+<!-- docguard:version: 0.14.0 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.13.0/extensions/spec-kit-docguard → docguard_cli-0.14.0/.agent}/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.13.0
+  version: 0.14.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.13.0 -->
+<!-- docguard:version: 0.14.0 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.13.0/extensions/spec-kit-docguard → docguard_cli-0.14.0/.agent}/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.13.0
+  version: 0.14.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.13.0 -->
+<!-- docguard:version: 0.14.0 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/.agent/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.13.0
+  version: 0.14.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.13.0 -->
+<!-- docguard:version: 0.14.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/.agent/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.13.0
+  version: 0.14.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-05-26
+
+Feature release closing the v0.13 backlog (4 features) + 2 quality investments
+(multi-fixture harness, `--timings` profiler). **481 tests** (was 448, +33).
+22 validators. Headline wins: pre-commit lite went from 2s → **78ms** on
+wu-whatsappinbox, and Generated-Doc Staleness now CLOSES THE LOOP by emitting
+structured fixes that `fix --write` consumes.
+
+### Added
+
+- **P1: Fix-history ping-pong suppression** (completes M-2). `fix --write` now skips fixes that have been applied >= N times before (default 2) — catches the "user keeps reverting, bot keeps re-applying" loop. Override with the new `--force-redo` flag. `applyCount` and `firstAppliedAt` added to each `.docguard/fixed.json` entry for an accurate audit trail.
+- **P2: Environment + API-Surface honor `config.changedFiles`** (extends N-1). When `--changed-only` is set:
+  - `grepEnvUsage` scans only the listed files instead of the whole source tree.
+  - `validateApiSurface` returns N/A when no route/spec/controller files are in the changed set.
+  - **Result on wu-whatsappinbox: `--changed-only --since HEAD~3` runs in 78ms — a 25× speedup from v0.13.**
+- **P3: Generated-Doc Staleness emits structured fixes**. M-1 (v0.13) only warned; now it ALSO produces a `fixes[]` array with new `regenerate-section` fix type that `fix --write` consumes mechanically. **Closes the loop: detect drift → fix without AI.** The applier rewrites only the named section's body, leaves surrounding prose alone, and is idempotent.
+- **P4: `docguard upgrade --apply --pr`** for team-wide schema rollouts. Creates a branch, applies the migration, commits as "chore(docguard): migrate schema X → Y", pushes, opens a PR via `gh` CLI. Pre-flight checks `gh` is installed; clear error if not. Useful when `.docguard.json` is branch-protected.
+- **Q1: Multi-fixture test harness** — `tests/fixture-projects.test.mjs`. Runs full guard against 5 real-world project shapes (Next.js webapp, Vite frontend, Express backend, Python CLI, Rust lib). Cross-cutting "no validator throws a developer error" assertion across every fixture. The harness that would have caught B-5 (v0.13.0 Freshness crash) before release.
+- **Q2: `docguard guard --timings`** — per-validator wall-time profile, sorted slowest-first, with `data.validators[].durationMs` in JSON output. Honest delivery on the "perf pass" item: instead of speculative refactoring, ship the measurement tool. Real finding on wu: Generated-Staleness is **33% of total validator time** (~400ms) — targeted v0.15 optimization candidate.
+
+### Changed
+
+- **`docguard fix --write` records `applyCount`** in `.docguard/fixed.json`. Re-applying the same fix bumps the counter; suppression engages at count >= 2.
+- **`docguard fix --history`** display unchanged but now reads richer entries (applyCount, firstAppliedAt).
+- **`docguard guard --format json`** includes `durationMs` per validator.
+
+### Internal
+
+- **5 new test files**: `tests/fix-suppression.test.mjs` (9), `tests/changed-only-scoping.test.mjs` (6), `tests/regenerate-section.test.mjs` (6), `tests/upgrade-pr.test.mjs` (3), `tests/fixture-projects.test.mjs` (6), `tests/profile-flag.test.mjs` (3). **Total: 448 → 481 tests (+33 new).**
+- New mechanical fix type: `regenerate-section`. APPLIERS registry now lists 5 types.
+- `cli/writers/mechanical.mjs` got a top-level lazy-loaded `_shouldSuppress` and `_sectionsModule` to support the new applier without circular deps.
+- `cli/commands/upgrade.mjs` got `openUpgradePR()` — gates on `gh` CLI availability.
+- `cli/commands/guard.mjs` per-validator timing via `performance.now()`.
+- Dry-run on wu-whatsappinbox: **674/674 PASS in 1.48s** (full guard), **78ms** for `--changed-only --since HEAD~3` (P2 scoping in action), Generated-Staleness identified as biggest perf hog at 33% of validator time (v0.15 target).
+- No new NPM deps.
+
+### Out of scope (deferred to v0.15)
+
+- **Generated-Staleness optimization**: 33% of validator time is the obvious target. Likely fix: memoize `buildMemoryPlan` across `--write` flows so it's not re-computed by the validator AND the writer.
+- **Shared tree walk**: the original Q2 ambition. Now that we have `--timings`, future PRs can MEASURE the gain instead of speculating.
+- **Cross-validator config.changedFiles**: only Docs-Sync, Environment, API-Surface opt in so far. Could extend to Drift-Comments, TODO-Tracking, Generated-Staleness for further `--changed-only` wins.
+- **`upgrade --pr` polish**: dry-run on a real GitHub repo with a real bot identity. The flag is wired and gated, but the actual end-to-end PR creation hasn't been battle-tested in the wild.
+
+## [0.13.1] - 2026-05-26
+
+Patch + small feature release responding to the wu-whatsappinbox v0.12/v0.13
+feedback. Fixes 2 bugs (B-5, B-6), ships 3 new features (S-7, S-11, S-12),
+and adds a cross-cutting "no validator throws" safety net. **22 validators,
+448 tests (was 434, +14 new).** New `docguard impact` command.
+
+### Fixed
+
+- **B-5: Freshness validator crashed with `getLastCommitDate is not defined`.** A wu-whatsappinbox install of v0.13.0 produced this ReferenceError despite all the imports being correct in source — we couldn't reproduce locally, but the user's report was clear. Fix: defensive dynamic import in `freshness.mjs` that falls back to the pre-v0.13 inline implementation if `../shared-git.mjs` ever fails to load. Worst-case behavior is now "rename detection silently disabled" instead of "validator crashes with useless message". Also added an inline fallback for the same defensive layering. Reported by wu-whatsappinbox.
+- **B-6: Cross-Reference didn't URL-decode link target paths.** A markdown link like `[name](../WU%20Documentation/foo.md)` (where the directory has a space) was looked up with `existsSync('../WU%20Documentation/foo.md')` literally — the filesystem stores the decoded form. Now: `resolveTarget` tries BOTH the literal path (for paths that legitimately contain `%`) and the URL-decoded form. **Effect on wu-whatsappinbox: Cross-Reference went from 28/28 to 101/101 checks — 73 previously-broken refs now resolve correctly.** Reported by wu-whatsappinbox.
+- **Cross-cutting safety net**: new `tests/guard-no-throw.test.mjs` runs guard against a fixture repo and asserts no validator leaks a ReferenceError / TypeError / "is not defined" / "is not a function" / "Cannot read properties of undefined" pattern into user-facing output. Found a *second* lurking bug while writing the test: Structure validator threw `Cannot read properties of undefined (reading 'some')` when `config.requiredFiles.agentFile` was missing — fixed with defensive array-or-string coercion + skip-when-missing for `changelog` too. This safety net runs in CI, catching the entire class of developer-error-leaks before release.
+
+### Added
+
+- **S-12: Cross-Reference suggests the closest anchor on near-miss.** When the validator flags a broken anchor, it now appends `(did you mean #athena-setup-aws-only?)` when a heading in the target doc is a close match. Two-pass matcher: (1) substring containment with ≥4-char minimum and ≥50% overlap to avoid spurious matches, (2) Levenshtein edit distance within a `max(3, len/5)` budget. **Three of the five wu user-fixes in v0.12.0 were "heading renamed, link not updated" — now deterministic-fixable from the warning text.** Reported by wu-whatsappinbox.
+- **S-7: Draft-staleness check in Generated-Doc Staleness validator.** A `docguard:generated` doc with `status: draft` (either YAML frontmatter or `<!-- status: draft -->` inline marker) that hasn't been modified in `> draftStalenessDays` days (default 14) now warns. Catches forgotten skeletons that stall before the AI fills them in. Threshold configurable via `config.draftStalenessDays`. Validator returns N/A only when there's NOTHING to check (no source=code sections AND no draft docs). Reported by wu-whatsappinbox.
+- **S-11: New `docguard impact` command.** After a commit (or before a PR), runs `git diff --name-only --since=<ref>` and shows which canonical doc sections reference any of the changed code files. Three match strategies (direct path / basename / backticked module name — same as L-2 trace --reverse). Highlights orphaned files (code that changed but no doc references it) so reviewers know what's undocumented. JSON mode emits `{ since, changedFiles, ignoredFiles, affectedDocs }` for CI bots. Designed as a post-commit hook companion to K-1's auto-fix Action. Reported by wu-whatsappinbox.
+
+### Internal
+
+- **+3 new test files**: `tests/guard-no-throw.test.mjs` (2 — cross-cutting safety), `tests/impact.test.mjs` (5 — S-11), plus 5 new test cases in `cross-reference.test.mjs` (S-12 + B-6) and `generated-staleness.test.mjs` (S-7). **Total: 434 → 448 tests (+14 new).**
+- **New module**: `cli/commands/impact.mjs` (~140 lines).
+- **Hardened**: `cli/validators/freshness.mjs` (defensive shared-git import), `cli/validators/structure.mjs` (defensive config-shape handling), `cli/validators/cross-reference.mjs` (URL-decode + anchor suggestion).
+- **Dry-run on wu-whatsappinbox before push** (read-only): 670/674 PASS in 1.8s with all 22 validators. Cross-Reference jumped from 28/28 to **101/101 checks** — B-6 fix unlocked 73 previously-broken refs.
+- No new NPM deps.
+
+### Note on wu's v0.12 feedback
+
+Several "still open" suggestions from the wu-whatsappinbox v0.12 feedback were already shipped:
+
+- **S-2 (sweep-needed nudge)** → shipped in v0.12.0 as K-6.
+- **S-3 (trace --reverse)** → shipped in v0.13.0 as L-2.
+- **S-4 (`git log --follow`)** → shipped in v0.13.0 as L-3.
+- **S-5 (.docguardignore at init)** → shipped in v0.12.0 as K-3.
+- **S-6 (per-validator severity)** → shipped in v0.12.0 as K-4.
+- **S-9 (pre-commit lite)** → shipped in v0.12.0 as K-5.
+- **S-10 (`.docguard/fixed.json`)** → shipped in v0.13.0 as M-2.
+
+Upgrade with `docguard upgrade --apply` (or `npm i -g docguard-cli@latest`) to get all of these. **The wu report header said v0.12.0 but the B-5 error pattern indicates an in-flight v0.13.0 install** — either way, this patch makes both versions resilient to the regression.
+
 ## [0.13.0] - 2026-05-26
 
 Feature release — full backlog cleanup. **Phase L** (sync intelligence: 3 features), **Phase M** (bigger validators: 2 features), **Phase N** (polish: 2 fixes), and a new `shared-git.mjs` module that gives every git-touching validator rename-aware history. **22 validators total** (was 21). 434 tests, +34 from v0.12.

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.13.0
+Version: 0.14.0
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/cli/commands/fix.mjs

@@ -272,13 +272,16 @@ IMPORTANT: A new contributor should be able to follow this doc and have the proj
  * insert-changelog-unreleased (Changelog).
  * @returns {{ applied: object[], skipped: object[], total: number }}
  */
-export function applyAllMechanicalFixes(projectDir, config, { force = false } = {}) {
+export function applyAllMechanicalFixes(projectDir, config, opts = {}) {
+  const { force = false, forceRedo = false } = opts;
   const guardData = runGuardInternal(projectDir, config);
   const fixes = [];
   for (const v of guardData.validators) {
     if (Array.isArray(v.fixes)) fixes.push(...v.fixes);
   }
-  const { applied, skipped } = applyMechanicalFixes(projectDir, fixes, { force });
+  // v0.14-P1: forwarding forceRedo so users with `--force-redo` can override
+  // ping-pong suppression for a specific fix they actually want re-applied.
+  const { applied, skipped } = applyMechanicalFixes(projectDir, fixes, { force, forceRedo });
   return { applied, skipped, total: fixes.length };
 }
 
@@ -333,7 +336,10 @@ function runHistoryMode(projectDir, flags) {
 
 function runWriteMode(projectDir, config, flags) {
   const isJson = flags.format === 'json';
-  const { applied, skipped, total } = applyAllMechanicalFixes(projectDir, config, { force: flags.force });
+  const { applied, skipped, total } = applyAllMechanicalFixes(projectDir, config, {
+    force: flags.force,
+    forceRedo: flags.forceRedo,  // v0.14-P1: bypass ping-pong suppression
+  });
 
   if (isJson) {
     console.log(JSON.stringify({

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/cli/commands/guard.mjs

@@ -109,27 +109,36 @@ export function runGuardInternal(projectDir, config) {
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
+  // v0.14-Q2: per-validator timing. Cheap (one `performance.now()` pair per
+  // validator) and the data is what we'd need to optimize anything later.
+  // Exposed via --profile in the public guard.
   for (const { key, name, fn } of validatorMap) {
     if (validators[key] === false) {
-      results.push({ name, key, status: 'skipped', quality: null, errors: [], warnings: [], passed: 0, total: 0 });
+      results.push({ name, key, status: 'skipped', quality: null, errors: [], warnings: [], passed: 0, total: 0, durationMs: 0 });
       continue;
     }
 
+    const start = performance.now();
     try {
       const result = fn();
-      results.push({ ...result, name, key, ...classifyResult(result) });
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ ...result, name, key, durationMs, ...classifyResult(result) });
     } catch (err) {
-      results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
     }
   }
 
   // ── Metrics-Consistency runs AFTER all other validators (needs their results) ──
   if (validators.metricsConsistency !== false) {
+    const start = performance.now();
     try {
       const result = validateMetricsConsistency(projectDir, config, results);
-      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', ...classifyResult(result) });
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', durationMs, ...classifyResult(result) });
     } catch (err) {
-      results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
     }
   }
 
@@ -326,6 +335,26 @@ export function runGuard(projectDir, config, flags) {
   const badgeUrl = `https://img.shields.io/badge/CDD_Guard-${data.passed}%2F${data.total}_passed-${bColor}`;
   console.log(`\n  ${c.dim}📎 Badge: ![CDD Guard](${badgeUrl})${c.reset}`);
 
+  // v0.14-Q2: --timings prints per-validator timing, sorted slowest-first.
+  // Designed for self-diagnosis on slow repos: shows exactly which validator
+  // to optimize first. Cheap to opt into; off by default to keep output clean.
+  // (Originally proposed as `--profile` but that flag is taken by `init`.)
+  if (flags.timings) {
+    console.log(`\n  ${c.bold}⏱  Profile${c.reset} ${c.dim}(per-validator wall time, slowest first)${c.reset}`);
+    const timed = data.validators
+      .filter(v => typeof v.durationMs === 'number' && v.status !== 'skipped')
+      .sort((a, b) => b.durationMs - a.durationMs);
+    const total = timed.reduce((sum, v) => sum + v.durationMs, 0);
+    for (const v of timed.slice(0, 10)) {
+      const pct = total > 0 ? Math.round((v.durationMs / total) * 100) : 0;
+      const bar = '▇'.repeat(Math.max(1, Math.round(pct / 5)));
+      console.log(`     ${v.durationMs.toFixed(1).padStart(7)}ms  ${pct.toString().padStart(2)}%  ${bar.padEnd(20)} ${v.name}`);
+    }
+    if (timed.length > 10) console.log(`     ${c.dim}... ${timed.length - 10} faster validators omitted${c.reset}`);
+    console.log(`     ${c.dim}─────────${c.reset}`);
+    console.log(`     ${c.bold}${total.toFixed(1).padStart(7)}ms${c.reset}  ${c.dim}total validator time${c.reset}`);
+  }
+
   // Schema upgrade nudge — fires when the project's .docguard.json schema is
   // behind the CLI's CURRENT_SCHEMA_VERSION. Cheap, file-local check; no
   // network access. Suppressed in JSON output to keep machine consumers clean.

docguard_cli-0.14.0/cli/commands/impact.mjs

@@ -0,0 +1,169 @@
+/**
+ * Impact Command — S-11
+ *
+ * After a commit (or before opening a PR), shows which canonical doc
+ * sections reference any file that changed since `--since` (default HEAD~1).
+ * Combines the L-2 reverse-trace logic with the changed-files diff so you
+ * get "you should re-read these doc sections" in one command.
+ *
+ * Use cases:
+ *   - Post-commit hook: `docguard impact --since HEAD~1` runs after each
+ *     commit and reminds the developer which docs to update.
+ *   - PR prep: `docguard impact --since main` shows the doc surface area
+ *     touched by the whole branch.
+ *
+ * JSON mode emits a structured `{ changedFiles, affectedDocs }` payload
+ * for CI integrations and PR-comment bots.
+ *
+ * @req SC-S11-001 — impact reports per-file → doc mappings
+ * @req SC-S11-002 — files with no doc references are listed as "no impact"
+ * @req SC-S11-003 — --format json emits parseable structured output
+ * @req SC-S11-004 — non-code files (.md, .json, etc.) are skipped from impact analysis
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+
+import { c } from '../shared.mjs';
+import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
+
+/**
+ * File extensions we consider "code" for the purposes of impact analysis.
+ * Match the set used by other validators (Docs-Sync, Freshness).
+ */
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$/;
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Find canonical doc references for a single file. Reuses the same three
+ * match strategies as trace --reverse for consistency: direct path,
+ * basename, backticked module name.
+ */
+function findReferences(file, docs) {
+  const refs = [];
+  const normalized = file.replace(/^\.\//, '');
+  const base = basename(normalized);
+  const stem = base.replace(/\.[^.]+$/, '');
+  const stemRe = new RegExp(`\`${escapeRegex(stem)}\``);
+  for (const [docName, lines] of docs) {
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      let kind = null;
+      if (line.includes(normalized)) kind = 'path';
+      else if (line.includes(base)) kind = 'basename';
+      else if (stemRe.test(line)) kind = 'module';
+      if (kind) {
+        refs.push({ doc: docName, line: i + 1, kind });
+      }
+    }
+  }
+  return refs;
+}
+
+export function runImpact(projectDir, _config, flags) {
+  const isJson = flags.format === 'json';
+  const since = flags.since || 'HEAD~1';
+
+  if (!isGitRepo(projectDir)) {
+    if (isJson) {
+      console.log(JSON.stringify({ since, error: 'not a git repository', changedFiles: [], affectedDocs: [] }, null, 2));
+    } else {
+      console.error(`${c.red}Not a git repository — impact requires git history.${c.reset}`);
+    }
+    process.exit(1);
+  }
+
+  const changed = changedFilesSince(projectDir, since);
+  // Filter to code files only — markdown/json/yaml changes don't have "doc
+  // impact" in the same sense; they ARE the docs (or config).
+  const codeChanged = changed.filter(f => CODE_EXTENSIONS.test(f));
+
+  // Index canonical docs once
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  const docsIndex = new Map(); // docName → lines[]
+  if (existsSync(docsDir)) {
+    try {
+      for (const f of readdirSync(docsDir)) {
+        if (!f.endsWith('.md')) continue;
+        try {
+          const content = readFileSync(resolve(docsDir, f), 'utf-8');
+          docsIndex.set(f, content.split('\n'));
+        } catch { /* skip unreadable */ }
+      }
+    } catch { /* skip if dir unreadable */ }
+  }
+
+  // Compute per-file references
+  const fileImpact = []; // { file, references: [{doc, line, kind}] }
+  for (const f of codeChanged) {
+    fileImpact.push({ file: f, references: findReferences(f, docsIndex) });
+  }
+
+  // Roll up: which docs are affected, with all source files
+  const docMap = new Map(); // doc → Set<file>
+  for (const { file, references } of fileImpact) {
+    for (const r of references) {
+      if (!docMap.has(r.doc)) docMap.set(r.doc, new Set());
+      docMap.get(r.doc).add(file);
+    }
+  }
+  const affectedDocs = Array.from(docMap.entries()).map(([doc, files]) => ({
+    doc,
+    files: Array.from(files),
+  }));
+
+  // ── JSON output ──
+  if (isJson) {
+    console.log(JSON.stringify({
+      since,
+      changedFiles: codeChanged,
+      ignoredFiles: changed.filter(f => !CODE_EXTENSIONS.test(f)),
+      affectedDocs,
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  // ── Text output ──
+  console.log(`${c.bold}📊 DocGuard Impact${c.reset} ${c.dim}(since ${since})${c.reset}\n`);
+
+  if (changed.length === 0) {
+    console.log(`  ${c.green}✅ No file changes since ${since}.${c.reset}`);
+    return;
+  }
+  if (codeChanged.length === 0) {
+    console.log(`  ${c.dim}No code files changed (${changed.length} non-code files: ${changed.slice(0, 3).join(', ')}${changed.length > 3 ? '…' : ''}).${c.reset}`);
+    return;
+  }
+
+  console.log(`  ${c.cyan}${codeChanged.length}${c.reset} code file(s) changed.\n`);
+
+  if (affectedDocs.length === 0) {
+    console.log(`  ${c.yellow}⚠ No canonical docs reference any of the changed files.${c.reset}`);
+    console.log(`  ${c.dim}This often means the changed code is undocumented. Consider:${c.reset}`);
+    console.log(`  ${c.dim}  - Running ${c.cyan}docguard generate --plan${c.dim} to add doc skeletons${c.reset}`);
+    console.log(`  ${c.dim}  - Reviewing whether the change belongs in an existing doc${c.reset}`);
+    return;
+  }
+
+  console.log(`  ${c.green}${affectedDocs.length}${c.reset} canonical doc(s) reference the changed files:\n`);
+  for (const { doc, files } of affectedDocs) {
+    console.log(`  ${c.cyan}${doc}${c.reset} ${c.dim}(${files.length} file${files.length > 1 ? 's' : ''})${c.reset}`);
+    for (const f of files.slice(0, 5)) {
+      console.log(`     ${c.dim}via${c.reset} ${f}`);
+    }
+    if (files.length > 5) console.log(`     ${c.dim}... ${files.length - 5} more${c.reset}`);
+  }
+
+  // List code files with NO doc references — these may need new docs
+  const orphaned = fileImpact.filter(fi => fi.references.length === 0).map(fi => fi.file);
+  if (orphaned.length > 0) {
+    console.log(`\n  ${c.yellow}${orphaned.length} changed file(s) have NO canonical doc reference:${c.reset}`);
+    for (const f of orphaned.slice(0, 5)) console.log(`     ${c.dim}• ${f}${c.reset}`);
+    if (orphaned.length > 5) console.log(`     ${c.dim}... ${orphaned.length - 5} more${c.reset}`);
+    console.log(`  ${c.dim}These may be undocumented — review whether they belong in an existing doc.${c.reset}`);
+  }
+}

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/cli/commands/upgrade.mjs

@@ -124,6 +124,65 @@ function applyCliUpgrade() {
   return r;
 }
 
+/**
+ * v0.14-P4: open a PR with the schema migration. Used when the team wants
+ * a reviewable change instead of an in-place edit. Requires `gh` CLI on
+ * PATH. Returns { ok: bool, prUrl?: string, error?: string }.
+ */
+function openUpgradePR(projectDir, migratedConfig, fromVersion, toVersion) {
+  // Pre-flight: gh must be installed
+  const which = spawnSync('which', ['gh'], { encoding: 'utf-8' });
+  if (which.status !== 0) {
+    return { ok: false, error: 'gh CLI not found. Install: https://cli.github.com' };
+  }
+
+  const branch = `docguard/upgrade-schema-${toVersion}-${Date.now().toString(36)}`;
+  // Branch off current HEAD
+  let r = spawnSync('git', ['checkout', '-b', branch], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `git checkout failed: ${r.stderr || r.stdout}` };
+
+  // Write the migrated config
+  try {
+    writeFileSync(
+      resolve(projectDir, '.docguard.json'),
+      JSON.stringify(migratedConfig, null, 2) + '\n',
+      'utf-8'
+    );
+  } catch (e) {
+    return { ok: false, error: `write .docguard.json failed: ${e.message}` };
+  }
+
+  // Commit
+  r = spawnSync('git', ['add', '.docguard.json'], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `git add failed: ${r.stderr}` };
+
+  const commitMsg = `chore(docguard): migrate .docguard.json schema ${fromVersion} → ${toVersion}\n\nAutomated migration via \`docguard upgrade --apply --pr\`.`;
+  r = spawnSync('git', ['commit', '-m', commitMsg], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `git commit failed: ${r.stderr || r.stdout}` };
+
+  // Push
+  r = spawnSync('git', ['push', '-u', 'origin', branch], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `git push failed: ${r.stderr || r.stdout}` };
+
+  // Open PR
+  const prBody =
+    `Automated schema migration from \`${fromVersion}\` → \`${toVersion}\`.\n\n` +
+    `This PR was opened by \`docguard upgrade --apply --pr\`. It updates the\n` +
+    `\`.docguard.json\` schema version and any additive fields the new schema\n` +
+    `introduces (e.g. \`severity: {}\` for v0.5).\n\n` +
+    `Review and merge to keep your team's DocGuard config in sync.\n\n` +
+    `> 🤖 Generated by [DocGuard](https://github.com/raccioly/docguard)`;
+  r = spawnSync('gh', [
+    'pr', 'create',
+    '--title', `chore(docguard): migrate schema ${fromVersion} → ${toVersion}`,
+    '--body', prBody,
+  ], { cwd: projectDir, encoding: 'utf-8' });
+  if (r.status !== 0) return { ok: false, error: `gh pr create failed: ${r.stderr || r.stdout}` };
+
+  const prUrl = (r.stdout || '').trim().split('\n').pop();
+  return { ok: true, prUrl };
+}
+
 export async function runUpgrade(projectDir, _config, flags) {
   const checkOnly = flags.checkOnly || flags['check-only'];
   const apply = flags.apply;
@@ -222,8 +281,23 @@ export async function runUpgrade(projectDir, _config, flags) {
       const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
       const { changed, newConfig } = migrateSchema(cfg, projectSchema);
       if (changed) {
-        writeFileSync(cfgPath, JSON.stringify(newConfig, null, 2) + '\n', 'utf-8');
-        console.log(`  ${c.green}✓ Schema migrated ${projectSchema} → ${newConfig.version}.${c.reset}`);
+        // v0.14-P4: --pr opens a PR for review instead of in-place editing.
+        // Useful when the team wants a reviewable diff or has branch-protected
+        // .docguard.json. Falls back to in-place if pre-flight fails.
+        if (flags.pr) {
+          console.log(`  ${c.dim}Opening PR with migrated config...${c.reset}`);
+          const pr = openUpgradePR(projectDir, newConfig, projectSchema, newConfig.version);
+          if (pr.ok) {
+            console.log(`  ${c.green}✓ Schema migration PR opened:${c.reset} ${c.cyan}${pr.prUrl}${c.reset}`);
+          } else {
+            console.error(`  ${c.red}✗ PR creation failed:${c.reset} ${pr.error}`);
+            console.log(`  ${c.dim}Tip: run without --pr to apply in place, or fix the underlying issue.${c.reset}`);
+            process.exit(1);
+          }
+        } else {
+          writeFileSync(cfgPath, JSON.stringify(newConfig, null, 2) + '\n', 'utf-8');
+          console.log(`  ${c.green}✓ Schema migrated ${projectSchema} → ${newConfig.version}.${c.reset}`);
+        }
       } else {
         console.log(`  ${c.dim}Schema migration was a no-op (no recipe registered yet for ${projectSchema} → ${CURRENT_SCHEMA_VERSION}).${c.reset}`);
       }

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/cli/docguard.mjs

@@ -41,6 +41,7 @@ import { runTrace } from './commands/trace.mjs';
 import { runLlms } from './commands/llms.mjs';
 import { runSetup } from './commands/setup.mjs';
 import { runUpgrade } from './commands/upgrade.mjs';
+import { runImpact } from './commands/impact.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -385,6 +386,15 @@ async function main() {
       flags.reverse = true;
     } else if (args[i] === '--history') {
       flags.history = true;
+    } else if (args[i] === '--force-redo') {
+      flags.forceRedo = true;
+    } else if (args[i] === '--pr') {
+      flags.pr = true;
+    } else if (args[i] === '--timings' || args[i] === '--show-timings') {
+      // v0.14-Q2: per-validator timing display. Renamed from `--profile` to
+      // avoid collision with `docguard init --profile <name>`. `--show-timings`
+      // is the long form for users who prefer explicit verbs.
+      flags.timings = true;
     } else if (!args[i].startsWith('--') && i > 0) {
       // Positional args go into flags.args for commands that take them (e.g.
       // `docguard trace --reverse <path>`). Skip the command itself (i === 0).
@@ -514,6 +524,9 @@ async function main() {
     case 'update':
       await runUpgrade(projectDir, config, flags);
       break;
+    case 'impact':
+      runImpact(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/cli/shared-source.mjs

@@ -254,6 +254,16 @@ export function grepEnvUsage(projectDir, config = {}) {
     }
   };
 
+  // v0.14-P2: when config.changedFiles is populated (by --changed-only),
+  // restrict the scan to ONLY those paths. Skips the recursive tree walk
+  // entirely — turns "scan 5000 files" into "scan 3 files" in pre-commit mode.
+  if (Array.isArray(config.changedFiles) && config.changedFiles.length > 0) {
+    for (const rel of config.changedFiles) {
+      visit(resolve(projectDir, rel));
+    }
+    return names;
+  }
+
   for (const root of roots) walk(root);
   return names;
 }

{docguard_cli-0.13.0 → docguard_cli-0.14.0}/cli/validators/api-surface.mjs

@@ -192,6 +192,22 @@ export function validateApiSurface(projectDir, config) {
   const warnings = [];
   const fixes = [];
 
+  // v0.14-P2: when --changed-only scoping is active and NONE of the changed
+  // files look like route/spec/controller files, this validator has nothing
+  // to add — return N/A so the lite-mode total reflects only what was actually
+  // checked. Route patterns mirror the SECTION_FILE_MATCHERS in sync.mjs.
+  if (Array.isArray(config.changedFiles)) {
+    const ROUTE_RE = /(^|\/)(routes|controllers|handlers|app\/api)\/|openapi|swagger/i;
+    const anyRouteFile = config.changedFiles.some(f => ROUTE_RE.test(f));
+    if (!anyRouteFile) {
+      return {
+        errors, warnings, passed: 0, total: 0, fixes,
+        applicable: false,
+        note: 'no route/spec files in changed set',
+      };
+    }
+  }
+
   const drift = computeApiSurfaceDrift(projectDir, config);
 
   // ── Multi-spec divergence (independent of the API-REFERENCE doc) ──