docguard-cli 0.27.0 → 0.29.0

package/cli/validators/structure.mjs

@@ -1,22 +1,39 @@
 /**
  * Structure Validator — Checks that all required CDD files exist
+ *
+ * v0.29: migrated to structured findings (STR001–STR003). 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 { docHasSection } from '../shared.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 export function validateStructure(projectDir, config) {
-  const results = { name: 'structure', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
+
+  const missingFile = (file) => mkFinding({
+    code: 'STR001',
+    validator: 'structure',
+    severity: 'error',
+    message: `Missing required file: ${file}`,
+    location: file,
+    suggestion: { kind: 'fix', text: 'Create it from the professional template', command: 'docguard init' },
+  });
 
   // Check canonical docs
   for (const file of config.requiredFiles.canonical) {
-    results.total++;
+    total++;
     const fullPath = resolve(projectDir, file);
     if (existsSync(fullPath)) {
-      results.passed++;
+      passed++;
     } else {
-      results.errors.push(`Missing required file: ${file}`);
+      findings.push(missingFile(file));
     }
   }
 
@@ -27,44 +44,53 @@ export function validateStructure(projectDir, config) {
     ? config.requiredFiles.agentFile
     : (typeof config.requiredFiles?.agentFile === 'string' ? [config.requiredFiles.agentFile] : []);
   if (agentFiles.length > 0) {
-    results.total++;
+    total++;
     const agentFileFound = agentFiles.some(f =>
       existsSync(resolve(projectDir, f))
     );
     if (agentFileFound) {
-      results.passed++;
+      passed++;
     } else {
-      results.errors.push(`Missing agent file: ${agentFiles.join(' or ')}`);
+      findings.push(mkFinding({
+        code: 'STR002',
+        validator: 'structure',
+        severity: 'error',
+        message: `Missing agent file: ${agentFiles.join(' or ')}`,
+        location: agentFiles[0],
+        suggestion: { kind: 'fix', text: 'Create the agent instructions file', command: 'docguard init' },
+      }));
     }
   }
 
   // Check changelog — same defensive pattern.
   const changelogPath = config.requiredFiles?.changelog;
   if (changelogPath) {
-    results.total++;
+    total++;
     if (existsSync(resolve(projectDir, changelogPath))) {
-      results.passed++;
+      passed++;
     } else {
-      results.errors.push(`Missing required file: ${changelogPath}`);
+      findings.push(missingFile(changelogPath));
     }
   }
 
   // Check drift log
-  results.total++;
+  total++;
   if (existsSync(resolve(projectDir, config.requiredFiles.driftLog))) {
-    results.passed++;
+    passed++;
   } else {
-    results.errors.push(`Missing required file: ${config.requiredFiles.driftLog}`);
+    findings.push(missingFile(config.requiredFiles.driftLog));
   }
 
-  return results;
+  return { name: 'structure', ...resultFromFindings(findings, { passed, total }) };
 }
 
 /**
  * Check that canonical doc files contain required sections
  */
 export function validateDocSections(projectDir, config) {
-  const results = { name: 'doc-sections', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
   const ptc = config.projectTypeConfig || {};
 
   const requiredSections = {
@@ -86,7 +112,7 @@ export function validateDocSections(projectDir, config) {
     const content = readFileSync(fullPath, 'utf-8');
 
     for (const section of sections) {
-      results.total++;
+      total++;
       // Match a real heading (H2–H6), not a substring in a TOC link or code
       // block. v0.24: synonym- and section-number-tolerant via docHasSection, so
       // arc42/C4 docs ("## 5.4 Layer boundaries", "## Building Block View")
@@ -110,19 +136,28 @@ export function validateDocSections(projectDir, config) {
         'i'
       );
       if (docHasSection(content, section)) {
-        results.passed++;
+        passed++;
       } else if (naRe.test(content)) {
         // v0.16-P7: explicit N/A — counts as passed (the project has owned
         // the absence) and doesn't pollute the warnings list.
-        results.passed++;
+        passed++;
       } else {
-        results.warnings.push(
-          `${file}: missing section "${section}". ` +
-          `If genuinely not applicable, add: <!-- docguard:section ${slug} n/a — your reason -->`
-        );
+        findings.push(mkFinding({
+          code: 'STR003',
+          validator: 'structure',
+          severity: 'warn',
+          message: `${file}: missing section "${section}". ` +
+            `If genuinely not applicable, add: <!-- docguard:section ${slug} n/a — your reason -->`,
+          location: file,
+          suggestion: {
+            kind: 'suppress',
+            text: 'Add the section, or own the absence with the inline N/A marker',
+            pragma: `<!-- docguard:section ${slug} n/a — your reason -->`,
+          },
+        }));
       }
     }
   }
 
-  return results;
+  return { name: 'doc-sections', ...resultFromFindings(findings, { passed, total }) };
 }

package/cli/validators/surface-sync.mjs

@@ -59,6 +59,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, basename, extname, relative, dirname } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 /**
  * Expand a simple glob (only supports `*` at the leaf segment level —
@@ -223,10 +224,13 @@ function extractDocumentedTokens(content) {
 
 /**
  * Validate surface drift for a single surface against its target docs.
- * Returns warnings, fixes, passed count, and total count.
+ * Returns findings, fixes, passed count, and total count.
+ *
+ * v0.29: migrated to structured findings (SSY001–SSY002). Messages are
+ * byte-identical to the legacy strings.
  */
 function checkSurface(projectDir, surface) {
-  const out = { warnings: [], fixes: [], passed: 0, total: 0 };
+  const out = { findings: [], fixes: [], passed: 0, total: 0 };
   const name = surface.name || 'unnamed';
   const extractor = surface.extract || 'basename-no-ext';
   const ignore = new Set(surface.ignore || []);
@@ -236,9 +240,14 @@ function checkSurface(projectDir, surface) {
 
   // Discover code-truth set from glob.
   if (!surface.glob || typeof surface.glob !== 'string') {
-    out.warnings.push(
-      `surfaceSync: surface "${name}" has no \`glob\` — skipping. Add a glob like "cli/commands/*.mjs".`
-    );
+    out.findings.push(mkFinding({
+      code: 'SSY001',
+      validator: 'surfaceSync',
+      severity: 'warn',
+      message: `surfaceSync: surface "${name}" has no \`glob\` — skipping. Add a glob like "cli/commands/*.mjs".`,
+      location: '.docguard.json',
+      suggestion: { kind: 'fix', text: `Add a \`glob\` to the "${name}" surface entry under surfaceSync.surfaces in .docguard.json` },
+    }));
     return out;
   }
   const files = expandGlob(projectDir, surface.glob);
@@ -319,7 +328,14 @@ function checkSurface(projectDir, surface) {
       const tail = extra > 0 ? ` (+${extra} more)` : '';
       parts.push(`${missingFromCode.length} listed in ${docRel} but not found in code: ${shown}${tail}`);
     }
-    out.warnings.push(`Surface "${name}" drift: ${parts.join('; ')}`);
+    out.findings.push(mkFinding({
+      code: 'SSY002',
+      validator: 'surfaceSync',
+      severity: 'warn',
+      message: `Surface "${name}" drift: ${parts.join('; ')}`,
+      location: docRel,
+      suggestion: { kind: 'review', text: `Update the "${name}" list/table in ${docRel} to match the code-truth set — add missing items, remove ghosts, or put aliases in the surface's ignore list` },
+    }));
   }
 
   return out;
@@ -347,21 +363,24 @@ export function validateSurfaceSync(projectDir, config) {
     ? config.surfaceSync.surfaces
     : [];
 
-  const result = { errors: [], warnings: [], fixes: [], passed: 0, total: 0 };
-
   if (surfaceCfg.length === 0) {
     // No surfaces configured → N/A. The validator infrastructure surfaces
-    // this as "nothing to validate" rather than a fail.
-    return result;
+    // this as "nothing to validate" rather than a fail. Legacy shape kept.
+    return { errors: [], warnings: [], fixes: [], passed: 0, total: 0 };
   }
 
+  const findings = [];
+  const fixes = [];
+  let passed = 0;
+  let total = 0;
+
   for (const surface of surfaceCfg) {
     const r = checkSurface(projectDir, surface);
-    result.warnings.push(...r.warnings);
-    result.fixes.push(...r.fixes);
-    result.passed += r.passed;
-    result.total += r.total;
+    findings.push(...r.findings);
+    fixes.push(...r.fixes);
+    passed += r.passed;
+    total += r.total;
   }
 
-  return result;
+  return { ...resultFromFindings(findings, { passed, total }), fixes };
 }

package/cli/validators/test-spec.mjs

@@ -1,18 +1,30 @@
 /**
  * Test Spec Validator — Checks that tests exist per TEST-SPEC.md coverage rules
  * Now respects projectTypeConfig (e.g., skip E2E for CLI tools)
+ *
+ * v0.29: migrated to structured findings (TSP001–TSP007). 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 } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 export function validateTestSpec(projectDir, config) {
-  const results = { name: 'test-spec', errors: [], warnings: [], passed: 0, total: 0 };
+  const findings = [];
+  let passed = 0;
+  let total = 0;
+  let note;
 
-  const testSpecPath = resolve(projectDir, 'docs-canonical/TEST-SPEC.md');
+  const specDoc = 'docs-canonical/TEST-SPEC.md';
+  const testSpecPath = resolve(projectDir, specDoc);
   if (!existsSync(testSpecPath)) {
-    return results; // Structure validator catches this
+    // Structure validator catches this. Keep the exact legacy shape here
+    // (no `findings` key) — tests deep-equal this early return.
+    return { name: 'test-spec', errors: [], warnings: [], passed: 0, total: 0 };
   }
 
   const content = readFileSync(testSpecPath, 'utf-8');
@@ -80,22 +92,44 @@ export function validateTestSpec(projectDir, config) {
       // author's CLAIM, not proof — it is NOT counted as a pass. The real pass
       // comes from the file-existence checks below (code truth, not the glyph).
       if (status.includes('❌')) {
-        results.total++;
-        results.warnings.push(`TEST-SPEC declares ${sourceFile} as ❌ — missing tests`);
+        total++;
+        findings.push(mkFinding({
+          code: 'TSP001',
+          validator: 'testSpec',
+          severity: 'warn',
+          message: `TEST-SPEC declares ${sourceFile} as ❌ — missing tests`,
+          location: specDoc,
+          suggestion: { kind: 'fix', text: 'Write the missing tests, then update the row status to ✅' },
+        }));
       } else if (status.includes('⚠️')) {
-        results.total++;
-        results.warnings.push(`TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`);
+        total++;
+        findings.push(mkFinding({
+          code: 'TSP002',
+          validator: 'testSpec',
+          severity: 'warn',
+          message: `TEST-SPEC declares ${sourceFile} as ⚠️ — partial coverage`,
+          location: specDoc,
+          suggestion: { kind: 'fix', text: 'Extend coverage for this source, then update the row status to ✅' },
+        }));
       }
 
       // ── File existence checks ───────────────────────────────────────
       // Verify source file still exists (catch stale map entries).
       const cleanSource = sourceFile.replace(/`/g, '').trim();
       if (cleanSource && cleanSource !== '—' && cleanSource !== 'Source File' && isPathLike(cleanSource)) {
-        results.total++;
+        total++;
         if (existsSync(resolve(projectDir, cleanSource))) {
-          results.passed++;
+          passed++;
         } else {
-          results.warnings.push(`Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`);
+          findings.push(mkFinding({
+            code: 'TSP003',
+            validator: 'testSpec',
+            severity: 'warn',
+            confidence: 'low',
+            message: `Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`,
+            location: specDoc,
+            suggestion: { kind: 'review', text: 'Update or remove the stale row if the source file moved or was deleted' },
+          }));
         }
       }
 
@@ -104,11 +138,18 @@ export function validateTestSpec(projectDir, config) {
       for (const ti of testIdxs) {
         const cleanTest = (cells[ti] || '').replace(/`/g, '').trim();
         if (isPlaceholder(cleanTest) || !isPathLike(cleanTest)) continue;
-        results.total++;
+        total++;
         if (existsSync(resolve(projectDir, cleanTest))) {
-          results.passed++;
+          passed++;
         } else {
-          results.warnings.push(`Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`);
+          findings.push(mkFinding({
+            code: 'TSP004',
+            validator: 'testSpec',
+            severity: 'warn',
+            message: `Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`,
+            location: specDoc,
+            suggestion: { kind: 'fix', text: 'Create the test file, or point the row at the actual test path' },
+          }));
         }
       }
     }
@@ -140,10 +181,15 @@ export function validateTestSpec(projectDir, config) {
         if (num.startsWith('<!--') || num === '#' || journey.startsWith('<!--')) continue;
 
         if (status && status.includes('❌')) {
-          results.total++;
-          results.warnings.push(
-            `E2E Journey #${num} (${journey}) — missing test: ${testFile}`
-          );
+          total++;
+          findings.push(mkFinding({
+            code: 'TSP005',
+            validator: 'testSpec',
+            severity: 'warn',
+            message: `E2E Journey #${num} (${journey}) — missing test: ${testFile}`,
+            location: specDoc,
+            suggestion: { kind: 'fix', text: 'Implement the journey test, then update the row status to ✅' },
+          }));
           continue;
         }
 
@@ -154,14 +200,19 @@ export function validateTestSpec(projectDir, config) {
         if (testFile && testFile.trim() !== '—' && !testFile.includes('N/A')) {
           const paths = parseTestPathCell(testFile);
           if (paths.length > 0) {
-            results.total++;
+            total++;
             const anyExists = paths.some(p => testEvidenceExists(projectDir, p));
             if (anyExists) {
-              results.passed++;
+              passed++;
             } else {
-              results.warnings.push(
-                `E2E Journey #${num} (${journey}) marked ✅ but test file not found: ${paths.join(', ')}`
-              );
+              findings.push(mkFinding({
+                code: 'TSP006',
+                validator: 'testSpec',
+                severity: 'warn',
+                message: `E2E Journey #${num} (${journey}) marked ✅ but test file not found: ${paths.join(', ')}`,
+                location: specDoc,
+                suggestion: { kind: 'review', text: 'Fix the test path in the row, or restore the missing test file' },
+              }));
             }
           }
         }
@@ -172,7 +223,7 @@ export function validateTestSpec(projectDir, config) {
   // If TEST-SPEC.md declared no service-to-test mappings, there is nothing to
   // verify against. Do NOT manufacture a 1/1 pass just because tests exist
   // somewhere — that rendered a confident green ✅ for a doc that mapped nothing.
-  if (results.total === 0) {
+  if (total === 0) {
     // 1. Check top-level test dirs
     const commonTestDirs = ['tests', 'test', '__tests__', 'spec'];
     const hasTestDir = commonTestDirs.some(d =>
@@ -200,16 +251,23 @@ export function validateTestSpec(projectDir, config) {
       // file, and the last as status — so both the minimal 3-column shape and
       // the 4-column table `docguard generate` emits are accepted. Say so, since
       // the guidance previously contradicted the generated skeleton (field report).
-      results.note = 'TEST-SPEC.md declares no service-to-test mappings. Add a "## Source-to-Test Map" table — column 1 is the source, column 2 the test file, the last column the status. Both `| Source | Test file | Status |` and the generated `| Source File | Unit Test | Integration Test | Status |` shapes work. Run `docguard explain testSpec` for details.';
+      note = 'TEST-SPEC.md declares no service-to-test mappings. Add a "## Source-to-Test Map" table — column 1 is the source, column 2 the test file, the last column the status. Both `| Source | Test file | Status |` and the generated `| Source File | Unit Test | Integration Test | Status |` shapes work. Run `docguard explain testSpec` for details.';
     } else {
-      results.warnings.push(
-        'No test directory or co-located test files found. ' +
-        'Expected: tests/, src/**/__tests__/, or src/**/*.test.* files'
-      );
+      findings.push(mkFinding({
+        code: 'TSP007',
+        validator: 'testSpec',
+        severity: 'warn',
+        message: 'No test directory or co-located test files found. ' +
+          'Expected: tests/, src/**/__tests__/, or src/**/*.test.* files',
+        location: null,
+        suggestion: { kind: 'fix', text: 'Create a tests/ directory or co-located *.test.* files, then map them in TEST-SPEC.md' },
+      }));
     }
   }
 
-  return results;
+  const res = { name: 'test-spec', ...resultFromFindings(findings, { passed, total }) };
+  if (note) res.note = note;
+  return res;
 }
 
 /**