docguard-cli 0.14.0 → 0.14.1

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/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/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.14.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.14.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.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.14.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.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.14.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.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.14.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.14.0 -->
+<!-- docguard:version: 0.14.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.14.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.14.1",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {