docguard-cli 0.28.0 → 0.29.0

package/cli/validators/drift.mjs

@@ -1,10 +1,16 @@
 /**
  * Drift Validator — Every // DRIFT: comment must have a DRIFT-LOG.md entry
+ *
+ * v0.29: migrated to structured findings (DRF001–DRF002). 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.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
-import { relPosix } from '../shared-ignore.mjs';
+import { relPosix, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -19,7 +25,9 @@ const IGNORE_DIRS = new Set([
 ]);
 
 export function validateDrift(projectDir, config) {
-  const results = { name: 'drift', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
 
   // v0.15-P3: when config.changedFiles is set (--changed-only mode), only
   // visit the listed paths. Drift comments in unchanged files are still in
@@ -64,58 +72,56 @@ export function validateDrift(projectDir, config) {
 
   if (driftComments.length === 0) {
     // No // DRIFT: comments to reconcile — not applicable (NOT a pass).
-    results.note = 'no // DRIFT: comments in code';
-    return results;
+    return {
+      name: 'drift',
+      ...resultFromFindings([], { passed: 0, total: 0 }),
+      note: 'no // DRIFT: comments in code',
+    };
   }
 
   // Read DRIFT-LOG.md
   const driftLogPath = resolve(projectDir, config.requiredFiles.driftLog);
   if (!existsSync(driftLogPath)) {
-    results.total = driftComments.length;
     for (const dc of driftComments) {
-      results.errors.push(
-        `${dc.file}:${dc.line} has DRIFT comment but DRIFT-LOG.md doesn't exist`
-      );
+      findings.push(mkFinding({
+        code: 'DRF001',
+        validator: 'drift',
+        severity: 'error',
+        message: `${dc.file}:${dc.line} has DRIFT comment but DRIFT-LOG.md doesn't exist`,
+        location: `${dc.file}:${dc.line}`,
+        suggestion: { kind: 'fix', text: 'Create the drift log, then record this deviation in it', command: 'docguard init' },
+      }));
     }
-    return results;
+    return { name: 'drift', ...resultFromFindings(findings, { passed: 0, total: driftComments.length }) };
   }
 
   const driftLogContent = readFileSync(driftLogPath, 'utf-8');
 
   // Check each drift comment has a matching entry in DRIFT-LOG.md
   for (const dc of driftComments) {
-    results.total++;
+    total++;
     // Check if the file is mentioned in DRIFT-LOG.md
     if (driftLogContent.includes(dc.file)) {
-      results.passed++;
+      passed++;
     } else {
-      results.errors.push(
-        `${dc.file}:${dc.line} — DRIFT comment not logged in DRIFT-LOG.md`
-      );
+      findings.push(mkFinding({
+        code: 'DRF002',
+        validator: 'drift',
+        severity: 'error',
+        message: `${dc.file}:${dc.line} — DRIFT comment not logged in DRIFT-LOG.md`,
+        location: `${dc.file}:${dc.line}`,
+        suggestion: { kind: 'fix', text: 'Add an entry for this file to DRIFT-LOG.md explaining the deviation' },
+      }));
     }
   }
 
-  return results;
+  return { name: 'drift', ...resultFromFindings(findings, { passed, total }) };
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker;
+// the IGNORE_DIRS set above stays local because its entries are intentional
+// per-validator variance (e.g. 'cli' — DocGuard's own source has DRIFT: in
+// regex patterns).
 function walkDir(dir, callback) {
-  if (!existsSync(dir)) return;
-
-  const entries = readdirSync(dir);
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry)) continue;
-    if (entry.startsWith('.')) continue;
-
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        walkDir(fullPath, callback);
-      } else if (stat.isFile()) {
-        callback(fullPath);
-      }
-    } catch {
-      // Skip files we can't read
-    }
-  }
+  sharedWalkFiles(dir, callback, { ignoreDirs: IGNORE_DIRS });
 }

package/cli/validators/environment.mjs

@@ -1,19 +1,30 @@
 /**
  * Environment Validator — Checks ENVIRONMENT.md docs and .env.example
  * Now respects projectTypeConfig (e.g., skip env checks for CLI tools)
+ *
+ * v0.29: migrated to structured findings (ENV001–ENV005). 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.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { grepEnvUsage } from '../shared-source.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 export function validateEnvironment(projectDir, config) {
-  const results = { name: 'environment', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
   const ptc = config.projectTypeConfig || {};
 
-  const envDocPath = resolve(projectDir, 'docs-canonical/ENVIRONMENT.md');
+  const envDoc = 'docs-canonical/ENVIRONMENT.md';
+  const envDocPath = resolve(projectDir, envDoc);
   if (!existsSync(envDocPath)) {
-    return results; // Structure validator catches missing files
+    // Structure validator catches missing files. Keep the exact legacy shape
+    // here (no `findings` key) — tests deep-equal this early return.
+    return { name: 'environment', errors: [], warnings: [], passed: 0, total: 0 };
   }
 
   const content = readFileSync(envDocPath, 'utf-8');
@@ -21,18 +32,32 @@ export function validateEnvironment(projectDir, config) {
   // Check for required sections (anchored headings — not substring matches that
   // could hit a TOC entry or code block).
   const hasHeading = (re) => re.test(content);
-  results.total++;
+  total++;
   if (hasHeading(/^#{2,3}\s+(Prerequisites|Setup Steps)\b/m)) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push('ENVIRONMENT.md: missing "## Prerequisites" or "## Setup Steps" section');
+    findings.push(mkFinding({
+      code: 'ENV001',
+      validator: 'environment',
+      severity: 'warn',
+      message: 'ENVIRONMENT.md: missing "## Prerequisites" or "## Setup Steps" section',
+      location: envDoc,
+      suggestion: { kind: 'fix', text: 'Add a "## Setup Steps" (or "## Prerequisites") section describing how to get the project running' },
+    }));
   }
 
-  results.total++;
+  total++;
   if (hasHeading(/^#{2,3}\s+Environment Variables\b/m)) {
-    results.passed++;
+    passed++;
   } else {
-    results.warnings.push('ENVIRONMENT.md: missing "## Environment Variables" section');
+    findings.push(mkFinding({
+      code: 'ENV002',
+      validator: 'environment',
+      severity: 'warn',
+      message: 'ENVIRONMENT.md: missing "## Environment Variables" section',
+      location: envDoc,
+      suggestion: { kind: 'fix', text: 'Add a "## Environment Variables" section documenting each variable the app reads' },
+    }));
   }
 
   // ── Real code-truth check: env vars USED in code but documented nowhere ──
@@ -92,15 +117,20 @@ export function validateEnvironment(projectDir, config) {
     // vacuous (always passes) and would just inflate the count.
     if (codeUsed.size > 0) {
       const usedButUndocumented = [...codeUsed].filter(v => !documented.has(v));
-      results.total++;
+      total++;
       if (usedButUndocumented.length === 0) {
-        results.passed++;
+        passed++;
       } else {
         const shown = usedButUndocumented.slice(0, 10).join(', ');
         const more = usedButUndocumented.length > 10 ? ` (+${usedButUndocumented.length - 10} more)` : '';
-        results.warnings.push(
-          `${usedButUndocumented.length} env var(s) used in code but not documented in ENVIRONMENT.md / .env.example: ${shown}${more}`
-        );
+        findings.push(mkFinding({
+          code: 'ENV003',
+          validator: 'environment',
+          severity: 'warn',
+          message: `${usedButUndocumented.length} env var(s) used in code but not documented in ENVIRONMENT.md / .env.example: ${shown}${more}`,
+          location: envDoc,
+          suggestion: { kind: 'fix', text: 'Document each listed variable in ENVIRONMENT.md, or add it to .env.example' },
+        }));
       }
     }
   }
@@ -109,35 +139,45 @@ export function validateEnvironment(projectDir, config) {
   if (ptc.needsEnvExample !== false && ptc.needsEnvVars !== false) {
     // Check if .env.example is referenced and exists
     if (content.includes('.env.example')) {
-      results.total++;
+      total++;
       if (existsSync(resolve(projectDir, '.env.example'))) {
-        results.passed++;
+        passed++;
       } else {
-        results.warnings.push(
-          'ENVIRONMENT.md references .env.example but the file does not exist'
-        );
+        findings.push(mkFinding({
+          code: 'ENV004',
+          validator: 'environment',
+          severity: 'warn',
+          message: 'ENVIRONMENT.md references .env.example but the file does not exist',
+          location: envDoc,
+          suggestion: { kind: 'fix', text: 'Create .env.example with placeholder values, or remove the stale reference from ENVIRONMENT.md' },
+        }));
       }
     }
 
     // Check if any .env file exists but no .env.example is provided
-    results.total++;
+    total++;
     const hasEnvFile = ['.env', '.env.local', '.env.development'].some(f =>
       existsSync(resolve(projectDir, f))
     );
     const hasEnvExample = existsSync(resolve(projectDir, '.env.example'));
 
     if (hasEnvFile && !hasEnvExample) {
-      results.warnings.push(
-        '.env file exists but no .env.example template — new contributors won\'t know what vars to set'
-      );
+      findings.push(mkFinding({
+        code: 'ENV005',
+        validator: 'environment',
+        severity: 'warn',
+        message: '.env file exists but no .env.example template — new contributors won\'t know what vars to set',
+        location: '.env.example',
+        suggestion: { kind: 'fix', text: 'Create a .env.example template listing every variable with a placeholder value' },
+      }));
     } else {
-      results.passed++;
+      passed++;
     }
   } else {
     // CLI/library project — just verify doc exists and has basic content
-    results.total++;
-    results.passed++;
+    total++;
+    passed++;
   }
 
-  return results;
+  return { name: 'environment', ...resultFromFindings(findings, { passed, total }) };
 }

package/cli/validators/freshness.mjs

@@ -28,11 +28,8 @@ try {
   _sharedGetLastCommitDate = null;
 }
 
-const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build',
-  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
-  'templates', 'configs', 'Research',
-]);
+// (v0.29 cleanup: a dead IGNORE_DIRS set lived here — defined but never
+// referenced. Freshness reads specific configured docs; it never walks.)
 
 /**
  * Read the `<!-- docguard:last-reviewed YYYY-MM-DD -->` header from a doc file.
@@ -245,6 +242,8 @@ export function validateFreshness(dir, config) {
       // an agent that can stamp a marker but not commit was left guessing.
       results.push({
         status: 'warn',
+        code: 'FRS001',
+        doc: docFile,
         message: `${docFile} exists but is not yet committed to git — commit it, or add a <!-- docguard:last-reviewed YYYY-MM-DD --> marker (or <!-- docguard:status approved -->).`,
       });
       continue;
@@ -266,6 +265,8 @@ export function validateFreshness(dir, config) {
     if (codeCommitsSince >= WARNING_THRESHOLD_COMMITS) {
       results.push({
         status: 'warn',
+        code: 'FRS002',
+        doc: docFile,
         message: `${docFile} — ${codeCommitsSince} code commits since last doc update (${docDate.toISOString().split('T')[0]})`,
       });
       continue;
@@ -277,6 +278,8 @@ export function validateFreshness(dir, config) {
       if (daysDiff > STALE_THRESHOLD_DAYS) {
         results.push({
           status: 'warn',
+          code: 'FRS003',
+          doc: docFile,
           message: `${docFile} — last updated ${daysDiff} days before latest code change`,
         });
         continue;
@@ -300,6 +303,8 @@ export function validateFreshness(dir, config) {
       if (daysDiff > 7) {
         results.push({
           status: 'warn',
+          code: 'FRS004',
+          doc: config.requiredFiles?.changelog || 'CHANGELOG.md',
           message: `CHANGELOG.md not updated in ${daysDiff} days despite code changes`,
         });
       } else {
@@ -336,6 +341,8 @@ export function validateFreshness(dir, config) {
         if (codeCommitsSince > 3) {
           results.push({
             status: 'warn',
+            code: 'FRS005',
+            doc: config.requiredFiles?.driftLog || 'DRIFT-LOG.md',
             message: `DRIFT-LOG.md may be stale — ${driftCount} DRIFT comments found in recent commits`,
           });
         }

package/cli/validators/generated-staleness.mjs

@@ -28,6 +28,7 @@ import { resolve, basename, join } from 'node:path';
 
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { getSection } from '../writers/sections.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * v0.18-P1 fast-path: cheap pre-flight to detect whether ANY canonical doc
@@ -103,7 +104,12 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
   // `applyMechanicalFixes` can consume it via the new regenerate-section
   // applier. Lets `fix --write` actually CLOSE the loop on drift instead
   // of just warning. No AI needed — the scanner already knows the right body.
+  //
+  // v0.29: migrated to structured findings (GST001–GST002). Messages are
+  // byte-identical to the legacy strings; the N/A early returns keep the
+  // legacy shape, and `fixes` is preserved for the fix applier.
   const result = { errors: [], warnings: [], passed: 0, total: 0, fixes: [] };
+  const findings = [];
 
   // 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
@@ -150,10 +156,15 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
         const mtime = statSync(fullPath).mtime;
         const ageDays = (Date.now() - mtime.getTime()) / (1000 * 60 * 60 * 24);
         if (ageDays > draftThresholdDays) {
-          result.warnings.push(
-            `${basename(doc.path)} has been in \`status: draft\` for ${Math.floor(ageDays)} days. ` +
-            `Promote to status:current or remove. Run \`/docguard.fix --doc ${basename(doc.path)}\` to draft the prose.`
-          );
+          findings.push(mkFinding({
+            code: 'GST001',
+            validator: 'generatedStaleness',
+            severity: 'warn',
+            message: `${basename(doc.path)} has been in \`status: draft\` for ${Math.floor(ageDays)} days. ` +
+              `Promote to status:current or remove. Run \`/docguard.fix --doc ${basename(doc.path)}\` to draft the prose.`,
+            location: doc.path,
+            suggestion: { kind: 'review', text: 'Draft the prose and promote to status:current, or delete the forgotten skeleton', command: `/docguard.fix --doc ${basename(doc.path)}` },
+          }));
         } else {
           result.passed++;
         }
@@ -206,11 +217,16 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
         ? ` (first drift at line ${firstDiff + 1} of section: "${(act[firstDiff] || '').slice(0, 60)}…" vs scanner: "${(exp[firstDiff] || '').slice(0, 60)}…")`
         : '';
 
-      result.warnings.push(
-        `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections. ` +
-        `If this section is intentionally hand-maintained (the scanner mislabeled it), pin it: ` +
-        `add \`pinned="reason"\` to its \`<!-- docguard:section id=${sec.id} … -->\` marker.`
-      );
+      findings.push(mkFinding({
+        code: 'GST002',
+        validator: 'generatedStaleness',
+        severity: 'warn',
+        message: `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections. ` +
+          `If this section is intentionally hand-maintained (the scanner mislabeled it), pin it: ` +
+          `add \`pinned="reason"\` to its \`<!-- docguard:section id=${sec.id} … -->\` marker.`,
+        location: doc.path,
+        suggestion: { kind: 'fix', text: 'Refresh the code-truth section (or pin it if it is intentionally hand-maintained)', command: 'docguard sync --write' },
+      }));
       // v0.14-P3: structured fix so `docguard fix --write` can fix this
       // mechanically (no AI needed — scanner already produced the right body).
       result.fixes.push({
@@ -230,5 +246,5 @@ export function validateGeneratedStaleness(projectDir, config = {}) {
     return { ...result, applicable: false };
   }
 
-  return result;
+  return { ...resultFromFindings(findings, { passed: result.passed, total: result.total }), fixes: result.fixes };
 }

package/cli/validators/metadata-sync.mjs

@@ -3,12 +3,18 @@
  *
  * Cross-checks package.json version against extension.yml and all .md files.
  * Flags outdated version strings (e.g., README references v0.7.2 but package.json is 0.8.0).
+ *
+ * v0.29: migrated to structured findings (MDS001–MDS002). Messages are
+ * byte-identical to the legacy strings; the `fixes` array is preserved for
+ * the fix applier.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname } from 'node:path';
 import { loadIgnorePatterns } from '../shared.mjs';
 import { collectPackageJsons } from '../shared-source.mjs';
+import { walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -22,7 +28,7 @@ const IGNORE_DIRS = new Set([
  * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
  */
 export function validateMetadataSync(projectDir, config) {
-  const warnings = [];
+  const findings = [];
   const fixes = [];
   let passed = 0;
   let total = 0;
@@ -45,7 +51,8 @@ export function validateMetadataSync(projectDir, config) {
       if (pkg.version) { currentVersion = pkg.version; currentName = currentName || pkg.name || null; break; }
     }
   }
-  if (!currentVersion) return { errors: [], warnings, passed: 0, total: 0 };
+  // Literal legacy shape (no findings/fixes keys) — tests deepEqual this object.
+  if (!currentVersion) return { errors: [], warnings: [], passed: 0, total: 0 };
 
   // Parse into components for smart comparison. `|| 0` guards two-part versions
   // (e.g. "1.2"): without it vParts[2] is undefined → parseInt → NaN, and every
@@ -65,9 +72,14 @@ export function validateMetadataSync(projectDir, config) {
       const versionMatch = content.match(/version:\s*["']?(\d+\.\d+\.\d+)["']?/);
       if (versionMatch) {
         if (versionMatch[1] !== currentVersion) {
-          warnings.push(
-            `${relPath} has version "${versionMatch[1]}" but package.json is "${currentVersion}"`
-          );
+          findings.push(mkFinding({
+            code: 'MDS001',
+            validator: 'metadataSync',
+            severity: 'warn',
+            message: `${relPath} has version "${versionMatch[1]}" but package.json is "${currentVersion}"`,
+            location: relPath,
+            suggestion: { kind: 'fix', text: `Update the version field to ${currentVersion}`, command: 'docguard fix --write' },
+          }));
           fixes.push({ type: 'replace-version', file: relPath, found: versionMatch[1], actual: currentVersion });
         } else {
           passed++;
@@ -129,9 +141,14 @@ export function validateMetadataSync(projectDir, config) {
 
         if (isOlder && foundVersion !== currentVersion) {
           total++;
-          warnings.push(
-            `${relPath} references "v${foundVersion}" in an actionable context (URL/install/declaration) but current version is "${currentVersion}"`
-          );
+          findings.push(mkFinding({
+            code: 'MDS002',
+            validator: 'metadataSync',
+            severity: 'warn',
+            message: `${relPath} references "v${foundVersion}" in an actionable context (URL/install/declaration) but current version is "${currentVersion}"`,
+            location: relPath,
+            suggestion: { kind: 'fix', text: `Replace the stale ${foundVersion} reference with ${currentVersion}`, command: 'docguard fix --write' },
+          }));
           if (!fixes.some(f => f.file === relPath && f.found === foundVersion)) {
             fixes.push({ type: 'replace-version', file: relPath, found: foundVersion, actual: currentVersion });
           }
@@ -143,7 +160,7 @@ export function validateMetadataSync(projectDir, config) {
     }
   }
 
-  return { errors: [], warnings, passed, total, fixes };
+  return { ...resultFromFindings(findings, { passed, total }), fixes };
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -186,21 +203,7 @@ function findMarkdownFiles(dir) {
   return mdFiles;
 }
 
+// v0.29 consolidation: traversal delegates to the shared canonical walker.
 function walkFiles(dir, callback) {
-  if (!existsSync(dir)) return;
-  let entries;
-  try { entries = readdirSync(dir); } catch { return; }
-
-  for (const entry of entries) {
-    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        walkFiles(fullPath, callback);
-      } else if (stat.isFile()) {
-        callback(fullPath);
-      }
-    } catch { /* skip */ }
-  }
+  sharedWalkFiles(dir, callback, { ignoreDirs: IGNORE_DIRS });
 }