docguard-cli 0.28.0 → 0.30.0

package/cli/validators/canonical-sync.mjs

@@ -40,6 +40,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * Validate that README count claims about DocGuard's surface match code-truth.
@@ -48,30 +49,38 @@ import { resolve, join } from 'node:path';
  * @param {string} projectDir - Project root directory
  * @param {object} config - DocGuard config (unused but required by validator interface)
  * @param {Array} [guardResults] - Results array from runGuardInternal (optional but recommended)
+ *
+ * v0.29: migrated to structured findings (CSY001–CSY004). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings array at every return point.
  * @returns {{ errors: string[], warnings: string[], fixes: object[], passed: number, total: number, na?: boolean, naReason?: string }}
  */
 export function validateCanonicalSync(projectDir, config, guardResults) {
-  const result = { errors: [], warnings: [], fixes: [], passed: 0, total: 0 };
+  const findings = [];
+  const fixes = [];
+  let passed = 0;
+  let total = 0;
+  // Compose the legacy result shape (plus findings) at every return point.
+  const compose = (extra) => ({ ...resultFromFindings(findings, { passed, total }), fixes, ...extra });
 
   // ── Gate: only run in DocGuard's own repo ─────────────────────────────
   const pkgPath = resolve(projectDir, 'package.json');
   if (!existsSync(pkgPath)) {
-    return { ...result, na: true, naReason: 'no package.json' };
+    return compose({ na: true, naReason: 'no package.json' });
   }
 
   let pkg;
   try {
     pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
   } catch {
-    return { ...result, na: true, naReason: 'unreadable package.json' };
+    return compose({ na: true, naReason: 'unreadable package.json' });
   }
 
   if (pkg.name !== 'docguard-cli') {
-    return {
-      ...result,
+    return compose({
       na: true,
       naReason: 'canonical-sync only runs in the docguard-cli repo (it polices DocGuard\'s own surface)',
-    };
+    });
   }
 
   // ── Gather code-truth ────────────────────────────────────────────────
@@ -80,7 +89,7 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
   const validatorsDir = resolve(cliDir, 'validators');
 
   if (!existsSync(commandsDir) || !existsSync(validatorsDir)) {
-    return { ...result, na: true, naReason: 'cli/commands or cli/validators not found' };
+    return compose({ na: true, naReason: 'cli/commands or cli/validators not found' });
   }
 
   const commandFiles = readdirSync(commandsDir).filter(f => f.endsWith('.mjs'));
@@ -137,60 +146,77 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
     try { readme += readFileSync(p, 'utf-8') + '\n'; readAny = true; } catch { /* skip unreadable */ }
   }
   if (!readAny) {
-    result.warnings.push('canonical-sync: no README.md or AGENTS.md found — cannot check surface claims');
-    result.total = 1;
-    return result;
+    findings.push(mkFinding({
+      code: 'CSY001',
+      validator: 'canonicalSync',
+      severity: 'warn',
+      message: 'canonical-sync: no README.md or AGENTS.md found — cannot check surface claims',
+      location: 'README.md',
+      suggestion: { kind: 'review', text: 'Add a README.md (or AGENTS.md) so DocGuard can police its own surface claims' },
+    }));
+    total = 1;
+    return compose();
   }
 
   // ── Check 1: "ships N commands" ─────────────────────────────────────
   // Check ALL claims (matchAll), not just the first: with README + AGENTS.md
   // concatenated, a correct claim in one file must not mask a stale claim in
   // the other (the same first-match-masking trap the secret scanner had).
-  result.total++;
+  total++;
   const cmdMatches = [...readme.matchAll(/ships\s+\*{0,2}(\d+)\s+commands?\*{0,2}/gi)];
   if (cmdMatches.length > 0) {
     const wrong = [...new Set(cmdMatches.map(m => Number(m[1])).filter(n => n !== actualCommandCount))];
     if (wrong.length === 0) {
-      result.passed++;
+      passed++;
     } else {
       const detail = actualUserFacingCount !== actualCommandFileCount
         ? `${actualCommandCount} user-facing commands in --help (${actualCommandFileCount} files including deprecation aliases)`
         : `${actualCommandCount} command file(s)`;
-      result.warnings.push(
-        `A surface doc (README.md/AGENTS.md) claims ${wrong.map(n => `"ships ${n} commands"`).join(' / ')} but the real count is ${detail}. Update it.`
-      );
+      findings.push(mkFinding({
+        code: 'CSY002',
+        validator: 'canonicalSync',
+        severity: 'warn',
+        message: `A surface doc (README.md/AGENTS.md) claims ${wrong.map(n => `"ships ${n} commands"`).join(' / ')} but the real count is ${detail}. Update it.`,
+        location: null,
+        suggestion: { kind: 'fix', text: 'Update the "ships N commands" claim in README.md/AGENTS.md to the real count' },
+      }));
     }
   } else {
     // No claim found — that's OK, just don't check this one
-    result.passed++;
+    passed++;
   }
 
   // ── Check 2: "N validators" in surface context ──────────────────────
   // Match phrases like "22 validators", "all 22 validators", "the 22 validators"
   // but NOT phase-log entries like "Built with 9 validators" (those are
   // historical, and ROADMAP.md/CHANGELOG.md are skipped at the file level).
-  result.total++;
+  total++;
   const validatorMatches = [...readme.matchAll(/(?:all|the|with|across|ships?)\s+\*{0,2}(\d+)\s+validators?\*{0,2}/gi)];
   if (validatorMatches.length > 0) {
     const wrongClaims = validatorMatches
       .map(m => Number(m[1]))
       .filter(n => n !== actualValidatorCount);
     if (wrongClaims.length === 0) {
-      result.passed++;
+      passed++;
     } else {
       const uniqueWrong = [...new Set(wrongClaims)];
-      result.warnings.push(
-        `A surface doc (README.md/AGENTS.md) claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update it.`
-      );
+      findings.push(mkFinding({
+        code: 'CSY003',
+        validator: 'canonicalSync',
+        severity: 'warn',
+        message: `A surface doc (README.md/AGENTS.md) claims ${uniqueWrong.map(n => `"${n} validators"`).join(' / ')} but guard reports ${actualValidatorCount}. Update it.`,
+        location: null,
+        suggestion: { kind: 'fix', text: 'Update the "N validators" claim in README.md/AGENTS.md to match guard\'s count' },
+      }));
     }
   } else {
-    result.passed++;
+    passed++;
   }
 
   // ── Check 3: architecture-diagram counts ────────────────────────────
   // Catches the specific "Commands (N)" and "Validators (N)" patterns in
   // the mermaid block that drifted across 5 releases.
-  result.total++;
+  total++;
   const archMatches = [
     { re: /Commands\s*\((\d+)\)/, label: 'Commands', expected: actualCommandCount },
     { re: /Validators\s*\((\d+)\)/, label: 'Validators', expected: actualValidatorCount },
@@ -203,12 +229,17 @@ export function validateCanonicalSync(projectDir, config, guardResults) {
     }
   }
   if (archWrong.length === 0) {
-    result.passed++;
+    passed++;
   } else {
-    result.warnings.push(
-      `README.md architecture diagram has stale counts: ${archWrong.join('; ')}. Update the mermaid block.`
-    );
+    findings.push(mkFinding({
+      code: 'CSY004',
+      validator: 'canonicalSync',
+      severity: 'warn',
+      message: `README.md architecture diagram has stale counts: ${archWrong.join('; ')}. Update the mermaid block.`,
+      location: 'README.md',
+      suggestion: { kind: 'fix', text: 'Update the Commands (N) / Validators (N) labels in the README mermaid block' },
+    }));
   }
 
-  return result;
+  return compose();
 }

package/cli/validators/changelog.mjs

@@ -7,6 +7,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const CODE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|cs|kt|swift)$/;
 
@@ -24,35 +25,53 @@ function getStagedFiles(projectDir) {
   }
 }
 
+// v0.29: migrated to structured findings (CHG001–CHG003). Messages are
+// byte-identical to the legacy strings; the `fixes` array is preserved for
+// the fix applier.
 export function validateChangelog(projectDir, config) {
-  const results = { name: 'changelog', errors: [], warnings: [], passed: 0, total: 0, fixes: [] };
+  const findings = [];
+  const fixes = [];
+  let passed = 0;
+  let total = 0;
 
   const changelogPath = resolve(projectDir, config.requiredFiles.changelog);
   if (!existsSync(changelogPath)) {
     // Structure validator catches missing files
-    return results;
+    return { name: 'changelog', ...resultFromFindings([], { passed: 0, total: 0 }), fixes };
   }
 
   const content = readFileSync(changelogPath, 'utf-8');
 
   // Check for [Unreleased] section
-  results.total++;
+  total++;
   if (content.includes('[Unreleased]') || content.includes('[unreleased]')) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push('CHANGELOG.md: missing [Unreleased] section — fix with `docguard fix --write`');
-    results.fixes.push({ type: 'insert-changelog-unreleased', file: config.requiredFiles.changelog });
+    findings.push(mkFinding({
+      code: 'CHG001',
+      validator: 'changelog',
+      severity: 'warn',
+      message: 'CHANGELOG.md: missing [Unreleased] section — fix with `docguard fix --write`',
+      location: config.requiredFiles.changelog,
+      suggestion: { kind: 'fix', text: 'Insert an [Unreleased] section', command: 'docguard fix --write' },
+    }));
+    fixes.push({ type: 'insert-changelog-unreleased', file: config.requiredFiles.changelog });
   }
 
   // Check it follows Keep a Changelog format (at least has ## headers)
-  results.total++;
+  total++;
   const hasVersionHeaders = /^## \[/m.test(content);
   if (hasVersionHeaders) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push(
-      'CHANGELOG.md: no version sections found (expected ## [version] format)'
-    );
+    findings.push(mkFinding({
+      code: 'CHG002',
+      validator: 'changelog',
+      severity: 'warn',
+      message: 'CHANGELOG.md: no version sections found (expected ## [version] format)',
+      location: config.requiredFiles.changelog,
+      suggestion: { kind: 'review', text: 'Adopt Keep a Changelog format: ## [version] - YYYY-MM-DD headers' },
+    }));
   }
 
   // Per STANDARD.md: if there are staged CODE changes, CHANGELOG.md should be
@@ -65,16 +84,21 @@ export function validateChangelog(projectDir, config) {
     const changelogStaged = staged.some(f => basename(f) === changelogName);
 
     if (stagedCode.length > 0) {
-      results.total++;
+      total++;
       if (changelogStaged) {
-        results.passed++;
+        passed++;
       } else {
-        results.warnings.push(
-          `${stagedCode.length} code file(s) staged but ${changelogName} is not — add a CHANGELOG entry for this change`
-        );
+        findings.push(mkFinding({
+          code: 'CHG003',
+          validator: 'changelog',
+          severity: 'warn',
+          message: `${stagedCode.length} code file(s) staged but ${changelogName} is not — add a CHANGELOG entry for this change`,
+          location: config.requiredFiles.changelog,
+          suggestion: { kind: 'fix', text: `Describe the staged change under [Unreleased] in ${changelogName}, then stage it` },
+        }));
       }
     }
   }
 
-  return results;
+  return { name: 'changelog', ...resultFromFindings(findings, { passed, total }), fixes };
 }

package/cli/validators/cross-reference.mjs

@@ -28,6 +28,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname, basename, relative } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * Slugify a heading the way GitHub's markdown anchors work.
@@ -290,17 +291,21 @@ function collectCanonicalDocs(projectDir) {
 /**
  * Validator entrypoint — matches the standard signature returning
  * { errors, warnings, passed, total }.
+ *
+ * v0.29: migrated to structured findings (XRF001–XRF002). Messages are
+ * byte-identical to the legacy strings — resultFromFindings derives the
+ * errors/warnings arrays from the same findings, so counts, exit codes, and
+ * existing tests are unaffected; guard just renders richer output.
  */
 export function validateCrossReferences(projectDir, _config = {}) {
-  const errors = [];
-  const warnings = [];
+  const findings = [];
   const fixes = [];
   let passed = 0;
   let total = 0;
 
   const docs = collectCanonicalDocs(projectDir);
   if (docs.length === 0) {
-    return { errors, warnings, passed, total, applicable: false };
+    return resultFromFindings([], { passed, total, applicable: false });
   }
 
   // Build a map of doc path → anchor set for fast lookups during ref resolution.
@@ -336,9 +341,14 @@ export function validateCrossReferences(projectDir, _config = {}) {
         }
         targetPath = resolveTarget(docPath, ref.file, projectDir);
         if (!targetPath) {
-          warnings.push(
-            `${docName}:${ref.line} — broken link: target file "${ref.file}" not found`
-          );
+          findings.push(mkFinding({
+            code: 'XRF001',
+            validator: 'crossReference',
+            severity: 'warn',
+            message: `${docName}:${ref.line} — broken link: target file "${ref.file}" not found`,
+            location: `${relative(projectDir, docPath)}:${ref.line}`,
+            suggestion: { kind: 'fix', text: 'Fix the link target path (or remove the dead link)' },
+          }));
           continue;
         }
       } else {
@@ -372,10 +382,17 @@ export function validateCrossReferences(projectDir, _config = {}) {
           // `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}` +
-            (isHighConfidence ? ' [auto-fixable]' : '')
-          );
+          findings.push(mkFinding({
+            code: 'XRF002',
+            validator: 'crossReference',
+            severity: 'warn',
+            message: `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading${hint}` +
+              (isHighConfidence ? ' [auto-fixable]' : ''),
+            location: `${relative(projectDir, docPath)}:${ref.line}`,
+            suggestion: isHighConfidence
+              ? { kind: 'fix', text: `Replace #${ref.anchor} with #${suggestion}`, command: 'docguard fix --write' }
+              : { kind: 'review', text: 'Update the anchor to match a real heading in the target doc' },
+          }));
           if (isHighConfidence) {
             fixes.push({
               type: 'replace-anchor',
@@ -394,7 +411,7 @@ export function validateCrossReferences(projectDir, _config = {}) {
     }
   }
 
-  return { errors, warnings, passed, total, fixes };
+  return { ...resultFromFindings(findings, { passed, total }), fixes };
 }
 
 /**

package/cli/validators/doc-quality.mjs

@@ -21,7 +21,8 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, extname } from 'node:path';
+import { resolve, join, extname, relative } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 // ──── Metric Thresholds ────
 // These define "good" vs "warning" boundaries for each metric.
@@ -548,13 +549,21 @@ function analyzeDocument(doc) {
  *
  * Scans all canonical docs, runs 8 metrics on each, and reports
  * per-doc findings as warnings when thresholds are exceeded.
+ *
+ * v0.29: migrated to structured findings (DQ001–DQ008, one code per metric).
+ * Messages are byte-identical to the legacy strings — resultFromFindings
+ * derives the errors/warnings arrays from the same findings, so counts, exit
+ * codes, and existing tests are unaffected; guard just renders richer output.
  */
 export function validateDocQuality(projectDir, config) {
-  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
 
   const docs = getCanonicalDocs(projectDir);
   if (docs.length === 0) {
-    return results;
+    // Literal legacy shape (no findings key) — tests deepEqual this object.
+    return { errors: [], warnings: [], passed: 0, total: 0 };
   }
 
   for (const doc of docs) {
@@ -564,107 +573,132 @@ export function validateDocQuality(projectDir, config) {
     if (analysis.skipped) continue;
 
     const m = analysis.metrics;
+    const loc = relative(projectDir, doc.path);
+    const warn = (code, message, suggestion) => {
+      findings.push(mkFinding({
+        code,
+        validator: 'docQuality',
+        severity: 'warn',
+        message,
+        location: loc,
+        suggestion,
+      }));
+    };
 
     // ── Check 1: Passive Voice ──
-    results.total++;
+    total++;
     const passiveOv = analysis.overrides?.passiveVoice;
     const passiveThreshold = passiveOv?.threshold
       ?? config.docQuality?.passiveVoiceThreshold
       ?? THRESHOLDS.passiveVoiceRatio.warn;
     if (passiveOv?.off || m.passiveVoiceRatio <= passiveThreshold) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
+      warn('DQ001',
         `${doc.name}: High passive voice ratio (${(m.passiveVoiceRatio * 100).toFixed(0)}% of sentences). ` +
         `Use active voice for clarity. Found ${analysis.details.passive.count}/${analysis.details.passive.total} passive sentences. ` +
-        `If the passive voice is intentional (sequence/flow doc), add: <!-- docguard:quality passive-voice off — your reason -->`
-      );
+        `If the passive voice is intentional (sequence/flow doc), add: <!-- docguard:quality passive-voice off — your reason -->`,
+        {
+          kind: 'suppress',
+          text: 'Rewrite in active voice, or opt this doc out if passive is intentional',
+          pragma: '<!-- docguard:quality passive-voice off — your reason -->',
+        });
     }
 
     // ── Check 2: Ambiguous Pronouns ──
-    results.total++;
+    total++;
     if (m.ambiguousPronounRatio <= THRESHOLDS.ambiguousPronounRatio.warn) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
+      warn('DQ002',
         `${doc.name}: High ambiguous pronoun ratio (${(m.ambiguousPronounRatio * 100).toFixed(1)}%). ` +
-        `Replace "it/this/that/they" with specific nouns for clarity`
-      );
+        `Replace "it/this/that/they" with specific nouns for clarity`,
+        { kind: 'fix', text: 'Replace vague pronouns with the specific noun they refer to' });
     }
 
     // ── Check 3: Atomicity ──
-    results.total++;
+    total++;
     if (m.atomicityScore <= THRESHOLDS.atomicityScore.warn) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
+      warn('DQ003',
         `${doc.name}: Low atomicity (${(m.atomicityScore * 100).toFixed(0)}% compound sentences). ` +
-        `Split compound sentences for easier verification (IEEE 830 §4.1)`
-      );
+        `Split compound sentences for easier verification (IEEE 830 §4.1)`,
+        { kind: 'fix', text: 'Split compound sentences into one statement per sentence' });
     }
 
     // ── Check 4: Flesch Reading Ease ──
-    results.total++;
+    total++;
     if (m.fleschReadingEase >= THRESHOLDS.fleschReadingEase.warn) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
+      warn('DQ004',
         `${doc.name}: Very low readability (Flesch score: ${m.fleschReadingEase}/100 — ${getReadabilityLabel(m.fleschReadingEase)}). ` +
-        `Shorten sentences and use simpler words`
-      );
+        `Shorten sentences and use simpler words`,
+        { kind: 'fix', text: 'Shorten sentences and prefer simpler words' });
     }
 
     // ── Check 5: Flesch-Kincaid Grade ──
-    results.total++;
+    total++;
     if (m.fleschKincaidGrade <= THRESHOLDS.fleschKincaidGrade.warn) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
+      warn('DQ005',
         `${doc.name}: Reading level too high (grade ${m.fleschKincaidGrade} — ${getGradeLabel(m.fleschKincaidGrade)}). ` +
-        `Aim for grade 12-16 for technical docs`
-      );
+        `Aim for grade 12-16 for technical docs`,
+        { kind: 'fix', text: 'Simplify the prose toward a grade 12-16 reading level' });
     }
 
     // ── Check 6: Sentence Length ──
-    results.total++;
+    total++;
     if (m.avgSentenceLength <= THRESHOLDS.avgSentenceLength.warn) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
+      warn('DQ006',
         `${doc.name}: Average sentence too long (${m.avgSentenceLength} words). ` +
-        `Target ≤30 words per sentence for readability`
-      );
+        `Target ≤30 words per sentence for readability`,
+        { kind: 'fix', text: 'Break long sentences up — target 30 words or fewer' });
     }
 
     // ── Check 7: Negation Load ──
     // Per-doc override (security/operational docs legitimately use "never",
     // "must not", "cannot") and a project-wide config threshold both honored.
-    results.total++;
+    total++;
     const negOv = analysis.overrides?.negationLoad;
     const negThreshold = negOv?.threshold
       ?? config.docQuality?.negationLoadThreshold
       ?? THRESHOLDS.negationLoad.warn;
     if (negOv?.off || m.negationLoad <= negThreshold) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
+      warn('DQ007',
         `${doc.name}: High negation load (${(m.negationLoad * 100).toFixed(0)}% of sentences use negation). ` +
         `Rephrase in positive terms: "must not fail" → "must succeed" (IEEE 830 §4.3). ` +
-        `If the negation is intentional, add: <!-- docguard:quality negation-load off — your reason -->`
-      );
+        `If the negation is intentional, add: <!-- docguard:quality negation-load off — your reason -->`,
+        {
+          kind: 'suppress',
+          text: 'Rephrase in positive terms, or opt this doc out if the negation is intentional',
+          pragma: '<!-- docguard:quality negation-load off — your reason -->',
+        });
     }
 
     // ── Check 8: Conditional Load ──
-    results.total++;
+    total++;
     if (m.conditionalLoad <= THRESHOLDS.conditionalLoad.warn) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push(
+      warn('DQ008',
         `${doc.name}: High conditional load (${(m.conditionalLoad * 100).toFixed(0)}% of sentences are conditional). ` +
-        `Simplify by splitting conditionals into separate requirements`
-      );
+        `Simplify by splitting conditionals into separate requirements`,
+        { kind: 'fix', text: 'Split conditional sentences into separate, unconditional requirements' });
     }
   }
 
-  return results;
+  if (total === 0) {
+    // Every doc was skipped (insufficient prose) — same literal legacy shape,
+    // because tests deepEqual this exact object for the all-skipped case too.
+    return { errors: [], warnings: [], passed: 0, total: 0 };
+  }
+
+  return resultFromFindings(findings, { passed, total });
 }