docguard-cli 0.26.0 → 0.28.0

package/cli/commands/sync-tests.mjs

@@ -0,0 +1,272 @@
+/**
+ * `docguard sync --tests` — reconcile the TEST-SPEC Source-to-Test Map from disk.
+ *
+ * Background (LLM field report #10): the source→test table in TEST-SPEC.md is
+ * hand-maintained, so plain `docguard sync` (which only refreshes
+ * docguard:generated code-truth SECTIONS) reports "nothing drifted" even when the
+ * table has a ghost service (source deleted), a ghost test (test file deleted),
+ * and N services that gained tests. The Test-Spec validator already detects the
+ * ghosts; this writes the reconciliation back.
+ *
+ * SAFETY — this edits a human-curated table, so it does ONLY the two unambiguous
+ * operations and previews by default (`--write` applies):
+ *   - REMOVE a row whose SOURCE file no longer exists on disk (ghost service).
+ *   - APPEND a row for a co-located source↔test pair found on disk but absent
+ *     from the table (newly-covered service).
+ * Ghost TEST references (source still exists, test file gone) are REPORTED but
+ * never auto-edited — blanking a hand-maintained status/notes cell is too
+ * destructive, and the Test-Spec validator already warns on them.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { c } from '../shared.mjs';
+import { shouldIgnore } from '../shared-ignore.mjs';
+
+const TEST_SPEC_DOC = 'docs-canonical/TEST-SPEC.md';
+const CODE_EXT = /\.[cm]?[jt]sx?$/;
+const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+const WALK_SKIP = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', '.next', '__pycache__', '.venv', 'vendor']);
+
+// ── On-disk discovery ──────────────────────────────────────────────────────
+
+function walkCodeFiles(projectDir, config) {
+  const out = [];
+  const visit = (absDir, relDir) => {
+    let entries;
+    try { entries = readdirSync(absDir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      if (WALK_SKIP.has(e.name)) continue;
+      const relPath = relDir ? `${relDir}/${e.name}` : e.name;
+      if (e.isDirectory()) { visit(resolve(absDir, e.name), relPath); continue; }
+      if (!CODE_EXT.test(e.name)) continue;
+      if (shouldIgnore(relPath, config)) continue;
+      out.push(relPath);
+    }
+  };
+  visit(resolve(projectDir), '');
+  return out;
+}
+
+const dirOf = (p) => (p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '');
+const baseOf = (p) => (p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p);
+const stemOf = (b) => b.replace(CODE_EXT, '').replace(/\.(test|spec)$/, '');
+
+/**
+ * Discover co-located source↔test pairs on disk. A test counts as covering a
+ * source when their stems match AND the test sits in the same directory or a
+ * sibling `__tests__/`. Conservative by design — cross-directory basename
+ * collisions (two `index.ts`) would pollute the table, so they're excluded.
+ *
+ * @returns {Array<{ source: string, test: string }>}
+ */
+export function discoverTestPairs(projectDir, config = {}) {
+  const files = walkCodeFiles(projectDir, config);
+  const tests = files.filter((f) => TEST_RE.test(f));
+  const sources = files.filter((f) => !TEST_RE.test(f));
+  const pairs = [];
+  for (const src of sources) {
+    const sDir = dirOf(src);
+    const sStem = stemOf(baseOf(src));
+    const match = tests.find((t) => {
+      if (stemOf(baseOf(t)) !== sStem) return false;
+      const tDir = dirOf(t);
+      return tDir === sDir || tDir === `${sDir}/__tests__` || (sDir === '' && tDir === '__tests__');
+    });
+    if (match) pairs.push({ source: src, test: match });
+  }
+  return pairs;
+}
+
+// ── Table parsing (mirrors test-spec.mjs column detection) ─────────────────
+
+const isPathLike = (v) => !!v && !/\s/.test(v) && (/[\\/]/.test(v) || /\.[A-Za-z0-9]{1,6}$/.test(v));
+const splitRow = (line) => {
+  const parts = line.split('|');
+  parts.shift();
+  parts.pop();
+  return parts.map((s) => s.trim());
+};
+
+/**
+ * Locate the Source-to-Test Map table and classify its rows against disk.
+ * @returns {null | { headerLine, sepLine, sourceIdx, testIdxs, ncols, keep:string[],
+ *                    removed:object[], ghostTests:object[], blockStart, blockEnd }}
+ */
+function parseMapTable(content, projectDir) {
+  const sectionRe = /## (?:Service-to-Test Map|Source-to-Test Map)[\s\S]*?(?=\n## |$)/;
+  const m = sectionRe.exec(content);
+  if (!m) return null;
+  const sectionStart = m.index;
+  const sectionText = m[0];
+  const sectionLines = sectionText.split('\n');
+
+  // Find the FIRST pipe table inside the section (header + separator + rows).
+  let headerLineIdx = -1;
+  for (let i = 0; i < sectionLines.length - 1; i++) {
+    if (sectionLines[i].trim().startsWith('|') && /^\s*\|[\s|:-]+\|\s*$/.test(sectionLines[i + 1])) {
+      headerLineIdx = i;
+      break;
+    }
+  }
+  if (headerLineIdx === -1) return null;
+
+  const header = splitRow(sectionLines[headerLineIdx]).map((h) => h.toLowerCase());
+  const ncols = header.length;
+  let sourceIdx = header.findIndex((h) => /\bsource\b/.test(h));
+  if (sourceIdx < 0) sourceIdx = 0;
+  let statusIdx = header.findIndex((h) => /\bstatus\b/.test(h));
+  if (statusIdx < 0) statusIdx = ncols - 1;
+  let testIdxs = header.map((h, i) => (/\btest\b|\be2e\b/.test(h) ? i : -1)).filter((i) => i >= 0 && i !== sourceIdx && i !== statusIdx);
+  if (testIdxs.length === 0) { const fb = sourceIdx === 1 ? 0 : 1; if (fb !== statusIdx && fb < ncols) testIdxs = [fb]; }
+
+  // Walk data rows after the separator until the table ends (a non-pipe line).
+  const keep = [];           // raw row lines to retain
+  const removed = [];        // { source } ghost-source rows dropped
+  const ghostTests = [];     // { source, test } source exists but a test ref is gone
+  const documentedSources = new Set();
+  let dataEndIdx = headerLineIdx + 2;
+  for (let i = headerLineIdx + 2; i < sectionLines.length; i++) {
+    const line = sectionLines[i];
+    if (!line.trim().startsWith('|')) break;
+    dataEndIdx = i + 1;
+    const cells = splitRow(line);
+    const rawSource = (cells[sourceIdx] || '').replace(/`/g, '').trim();
+    // Template/example/placeholder rows are left untouched.
+    if (!rawSource || rawSource.startsWith('<!--') || rawSource.startsWith('*') || !isPathLike(rawSource)) {
+      keep.push(line);
+      continue;
+    }
+    if (!existsSync(resolve(projectDir, rawSource))) {
+      removed.push({ source: rawSource });
+      continue; // drop ghost-source row
+    }
+    documentedSources.add(rawSource);
+    // Source exists — report (don't edit) any dead test reference.
+    for (const ti of testIdxs) {
+      const t = (cells[ti] || '').replace(/`/g, '').trim();
+      if (isPathLike(t) && !existsSync(resolve(projectDir, t))) ghostTests.push({ source: rawSource, test: t });
+    }
+    keep.push(line);
+  }
+
+  return {
+    sectionStart,
+    headerAbsLine: headerLineIdx,
+    sepLine: sectionLines[headerLineIdx + 1],
+    headerLine: sectionLines[headerLineIdx],
+    sourceIdx, testIdxs, statusIdx, ncols,
+    keep, removed, ghostTests, documentedSources,
+    // absolute char offsets of the table block within `content`
+    blockStartLine: headerLineIdx,
+    blockEndLine: dataEndIdx,
+    sectionLines,
+    sectionTextStart: sectionStart,
+  };
+}
+
+/**
+ * Compute the reconciliation. Pure: returns the diff + the rewritten content.
+ * @returns {{ applicable:boolean, removed:object[], added:object[], ghostTests:object[], newContent:string|null, reason?:string }}
+ */
+export function reconcileTestMap(content, projectDir, config) {
+  const parsed = parseMapTable(content, projectDir);
+  if (!parsed) {
+    return { applicable: false, removed: [], added: [], ghostTests: [], newContent: null, reason: 'no Source-to-Test Map table found' };
+  }
+  const pairs = discoverTestPairs(projectDir, config);
+  const added = pairs.filter((p) => !parsed.documentedSources.has(p.source));
+
+  // Build the new table block: header, separator, kept rows, appended rows.
+  const newRowFor = ({ source, test }) => {
+    const cells = new Array(parsed.ncols).fill('—');
+    cells[parsed.sourceIdx] = `\`${source}\``;
+    if (parsed.testIdxs.length) cells[parsed.testIdxs[0]] = `\`${test}\``;
+    cells[parsed.statusIdx] = '⚠️ auto-added — verify';
+    return `| ${cells.join(' | ')} |`;
+  };
+  const addedRows = added.map(newRowFor);
+  const newBlock = [parsed.headerLine, parsed.sepLine, ...parsed.keep, ...addedRows].join('\n');
+
+  // Splice the new block back into the original section text, then back into content.
+  const sectionLines = parsed.sectionLines.slice();
+  const before = sectionLines.slice(0, parsed.blockStartLine);
+  const after = sectionLines.slice(parsed.blockEndLine);
+  const newSection = [...before, newBlock, ...after].join('\n');
+  const oldSection = parsed.sectionLines.join('\n');
+  const newContent = content.slice(0, parsed.sectionTextStart) + newSection + content.slice(parsed.sectionTextStart + oldSection.length);
+
+  const changed = parsed.removed.length > 0 || added.length > 0;
+  return {
+    applicable: true,
+    removed: parsed.removed,
+    added,
+    ghostTests: parsed.ghostTests,
+    newContent: changed ? newContent : null,
+  };
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+
+export function runSyncTests(projectDir, config, flags) {
+  const apply = !!flags.write;
+  const isJson = flags.format === 'json';
+  const docPath = resolve(projectDir, TEST_SPEC_DOC);
+
+  if (!existsSync(docPath)) {
+    if (isJson) { console.log(JSON.stringify({ applicable: false, reason: 'TEST-SPEC.md not present' }, null, 2)); return; }
+    console.log(`${c.yellow}TEST-SPEC.md not found — run ${c.cyan}docguard init${c.yellow} first.${c.reset}\n`);
+    return;
+  }
+
+  const content = readFileSync(docPath, 'utf-8');
+  const r = reconcileTestMap(content, projectDir, config);
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      applicable: r.applicable, applied: apply && !!r.newContent,
+      removed: r.removed, added: r.added, ghostTests: r.ghostTests, reason: r.reason || null,
+    }, null, 2));
+    if (apply && r.newContent) writeFileSync(docPath, r.newContent, 'utf-8');
+    return;
+  }
+
+  console.log(`${c.bold}🔄 DocGuard Sync --tests — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   ${TEST_SPEC_DOC} · ${apply ? 'Applying' : 'Dry run (use --write to apply)'}${c.reset}\n`);
+
+  if (!r.applicable) {
+    console.log(`  ${c.yellow}No Source-to-Test Map table found in TEST-SPEC.md.${c.reset}`);
+    console.log(`  ${c.dim}Add a "## Source-to-Test Map" table (col 1 = source, last col = status), then re-run.${c.reset}\n`);
+    return;
+  }
+
+  if (r.removed.length === 0 && r.added.length === 0 && r.ghostTests.length === 0) {
+    console.log(`  ${c.green}✅ Source-to-Test Map matches disk — nothing to reconcile.${c.reset}\n`);
+    return;
+  }
+
+  if (r.removed.length) {
+    console.log(`  ${apply ? c.green : c.yellow}${apply ? '✅ Removed' : '• Remove'} ${r.removed.length} ghost-source row(s) (source file deleted):${c.reset}`);
+    for (const x of r.removed) console.log(`     ${c.dim}- ${x.source}${c.reset}`);
+  }
+  if (r.added.length) {
+    console.log(`  ${apply ? c.green : c.yellow}${apply ? '✅ Added' : '• Add'} ${r.added.length} newly-covered source(s):${c.reset}`);
+    for (const x of r.added) console.log(`     ${c.dim}+ ${x.source} → ${x.test}${c.reset}`);
+  }
+  if (r.ghostTests.length) {
+    console.log(`  ${c.yellow}⚠ ${r.ghostTests.length} ghost test reference(s) (source exists, test file gone) — fix by hand:${c.reset}`);
+    for (const x of r.ghostTests) console.log(`     ${c.dim}~ ${x.source} → ${x.test} (missing)${c.reset}`);
+  }
+
+  if (apply && r.newContent) {
+    writeFileSync(docPath, r.newContent, 'utf-8');
+    console.log(`\n  ${c.green}↻ ${TEST_SPEC_DOC} updated. Review the ⚠️ auto-added rows, then ${c.cyan}docguard guard${c.green}.${c.reset}\n`);
+  } else if (!apply) {
+    console.log(`\n  ${c.dim}Apply: ${c.cyan}docguard sync --tests --write${c.reset}\n`);
+  } else {
+    console.log('');
+  }
+}

package/cli/commands/sync.mjs

@@ -20,6 +20,7 @@ import { c } from '../shared.mjs';
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { getSection, replaceSection } from '../writers/sections.mjs';
 import { hasGeneratedMarker } from '../writers/api-reference.mjs';
+import { runSyncTests } from './sync-tests.mjs';
 
 function gitChangedFiles(projectDir, since) {
   const run = (args) => {
@@ -77,6 +78,11 @@ function sectionTouchedByChanges(sectionId, changedFiles) {
 }
 
 export function runSync(projectDir, config, flags) {
+  // v0.28 (field report #10): `--tests` reconciles the hand-maintained TEST-SPEC
+  // Source-to-Test Map from disk (ghost-source removal + new co-located pairs) —
+  // a distinct path from the generated code-truth section refresh below.
+  if (flags.tests) return runSyncTests(projectDir, config, flags);
+
   const plan = buildMemoryPlan(projectDir, config);
   const apply = !!flags.write;
   const isJson = flags.format === 'json';

package/cli/commands/verify.mjs

@@ -0,0 +1,67 @@
+/**
+ * Verify Command — `docguard verify --semantic` (LLM field report #5).
+ *
+ * Surfaces the semantic claims in the canonical docs (documented numbers, limits,
+ * and enums) as a structured verification task list for the agent to check
+ * against the code. DocGuard does the deterministic discovery; the LLM does the
+ * judgment — the same division of labour as `docguard agent`.
+ *
+ * Read-only. JSON is the machine artifact (the agent-executable task list);
+ * text is the human summary.
+ *
+ *   docguard verify [--semantic] [--format json]
+ */
+
+import { c } from '../shared.mjs';
+import { detectAgentMode } from '../ensure-skills.mjs';
+import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/semantic-claims.mjs';
+
+export function runVerify(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  const claims = extractSemanticClaims(projectDir, config);
+  const tasks = buildSemanticVerifyTasks(claims);
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      command: 'verify --semantic',
+      project: config.projectName,
+      claimCount: tasks.length,
+      // How to act on this: each task is a claim to confirm against the code.
+      howToVerify: 'For each task, read the cited code (or grep for the constant/config), compare it to the documented value, and report any mismatch with both values. DocGuard cannot judge these — they require reading the code.',
+      tasks,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🔬 DocGuard Verify — semantic claims${c.reset}`);
+  console.log(`${c.dim}   ${config.projectName} · documented numbers / limits / enums to check against code${c.reset}\n`);
+
+  if (tasks.length === 0) {
+    console.log(`  ${c.green}✅ No semantic claims found in the canonical docs.${c.reset}`);
+    console.log(`  ${c.dim}(Looks for numbers with units — days/ms/req-s/GSIs/roles/… — and status/enum lists.)${c.reset}\n`);
+    return;
+  }
+
+  // Group by doc for a readable summary.
+  const byDoc = new Map();
+  for (const t of tasks) {
+    if (!byDoc.has(t.doc)) byDoc.set(t.doc, []);
+    byDoc.get(t.doc).push(t);
+  }
+
+  console.log(`  ${c.yellow}${tasks.length} claim(s) to verify against the code:${c.reset}\n`);
+  for (const [doc, ts] of byDoc) {
+    console.log(`  ${c.bold}${doc}${c.reset}`);
+    for (const t of ts) {
+      const val = t.kind === 'enum' ? `enum ${t.value}` : `${t.value}${t.unit ? ` ${t.unit}` : ''}`;
+      const cited = t.citedCode ? `${c.cyan}${t.citedCode}${c.reset}` : `${c.dim}(no cited code — grep for it)${c.reset}`;
+      console.log(`    ${c.yellow}•${c.reset} L${t.line} ${c.dim}${t.section ? `[${t.section}] ` : ''}${c.reset}${c.bold}${val}${c.reset} → check ${cited}`);
+    }
+    console.log('');
+  }
+
+  const mode = detectAgentMode(projectDir);
+  const cmd = mode === 'llm' ? '/docguard.verify' : 'docguard verify --semantic --format json';
+  console.log(`  ${c.dim}This is the highest-value bug class and DocGuard can't judge it — an agent must.${c.reset}`);
+  console.log(`  ${c.dim}Get the machine task list: ${c.cyan}${cmd}${c.dim}, then read each cited file and confirm the value.${c.reset}\n`);
+}

package/cli/docguard.mjs

@@ -43,6 +43,8 @@ import { runSetup } from './commands/setup.mjs';
 import { runUpgrade } from './commands/upgrade.mjs';
 import { runImpact } from './commands/impact.mjs';
 import { runExplain } from './commands/explain.mjs';
+import { runFeedback } from './commands/feedback.mjs';
+import { runVerify } from './commands/verify.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
@@ -85,7 +87,9 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}fix${c.reset}        Generate AI fix instructions for specific docs
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code (${c.cyan}--plan${c.reset} for AI scan)
   ${c.green}agent${c.reset}      One-shot agent task graph — ordered tasks, pre-filled code-truth, per-task verify (${c.cyan}--format json${c.reset})
-  ${c.green}explain${c.reset}    Explain a validator key or warning text
+  ${c.green}explain${c.reset}    Explain a validator key, warning text, or finding code (${c.cyan}docguard explain SEC001${c.reset})
+  ${c.green}verify${c.reset}     Extract documented numbers/limits/enums for an agent to check vs code (${c.cyan}--semantic${c.reset})
+  ${c.green}feedback${c.reset}   Report likely false positives back to DocGuard (local-first + 1-click prefilled issue)
   ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
   ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
@@ -230,13 +234,14 @@ const COMMAND_HELP = {
     examples: ['docguard diff', 'docguard diff --since HEAD~5'],
   },
   sync: {
-    summary: 'Refresh code-truth doc sections (preview by default).',
-    usage: 'docguard sync [--write] [--since <ref>]',
+    summary: 'Refresh code-truth doc sections (preview by default). `--tests` reconciles the TEST-SPEC Source-to-Test Map from disk.',
+    usage: 'docguard sync [--write] [--since <ref>] [--tests]',
     flags: [
       ['--write', 'Apply the refresh (default is a dry-run preview)'],
       ['--since <ref>', 'Only sync sections whose source files changed since <ref>'],
+      ['--tests', 'Reconcile the TEST-SPEC Source-to-Test Map: drop ghost-source rows, append newly-covered source↔test pairs (report ghost tests). Pair with --write to apply.'],
     ],
-    examples: ['docguard sync', 'docguard sync --write'],
+    examples: ['docguard sync', 'docguard sync --write', 'docguard sync --tests', 'docguard sync --tests --write'],
   },
   fix: {
     summary: 'Generate AI fix instructions for docs (or apply deterministic fixes).',
@@ -279,6 +284,21 @@ const COMMAND_HELP = {
     flags: [['--diff', 'Drill into drift between memory and code']],
     examples: ['docguard memory', 'docguard memory --diff'],
   },
+  feedback: {
+    summary: 'Report likely false positives back to DocGuard. Collects the low-confidence findings of a guard run, saves a full local record under .docguard/feedback/, and prints a one-click, prefilled, redacted GitHub issue URL (zero typing, no source code or secret values).',
+    usage: 'docguard feedback [--format json]',
+    flags: [['--format json', 'Machine-readable list of reportable findings + URLs']],
+    examples: ['docguard feedback'],
+  },
+  verify: {
+    summary: 'Extract the semantic claims in your canonical docs — documented numbers, limits, and enums (retention days, rate limits, GSI/role counts, status enums) — as a verification task list the agent checks against the code. This is the highest-value bug class (a doc value that drifted from code) and the one regex/AST cannot judge. DocGuard finds the claims; the LLM confirms them.',
+    usage: 'docguard verify [--semantic] [--format json]',
+    flags: [
+      ['--semantic', 'Extract documented numbers/limits/enums to verify against code (the current — and default — mode)'],
+      ['--format json', 'Machine-readable task list (the agent-executable artifact)'],
+    ],
+    examples: ['docguard verify --semantic', 'docguard verify --semantic --format json'],
+  },
 };
 
 function printCommandHelp(command) {
@@ -347,6 +367,14 @@ async function main() {
       flags.auto = true;
     } else if (args[i] === '--write') {
       flags.write = true;
+    } else if (args[i] === '--tests') {
+      // v0.28 (field report #10): `docguard sync --tests` reconciles the
+      // TEST-SPEC Source-to-Test Map from disk.
+      flags.tests = true;
+    } else if (args[i] === '--semantic') {
+      // v0.28 (field report #5): `docguard verify --semantic` extracts
+      // documented numbers/enums/limits for the agent to check against code.
+      flags.semantic = true;
     } else if (args[i] === '--plan') {
       flags.plan = true;
     } else if (args[i] === '--since' && args[i + 1]) {
@@ -507,6 +535,11 @@ async function main() {
   const READ_ONLY_COMMANDS = new Set([
     'guard', 'audit', 'score', 'diff', 'impact',
     'diagnose', 'trace', 'explain', 'memory', 'demo', 'agent',
+    // feedback only writes its own .docguard/feedback/ — it must NOT scaffold
+    // skills or touch source, so it's gated out of ensureSkills like the rest.
+    'feedback',
+    // verify only reads docs and emits a task list — pure report.
+    'verify',
   ]);
 
   // Silent auto-check: install skills/commands if missing. Skip entirely in
@@ -646,6 +679,18 @@ async function main() {
     case 'explain':
       runExplain(projectDir, config, flags);
       break;
+    case 'feedback':
+      // v0.27 (field report #3 / LLM feedback loop): collect low-confidence
+      // findings (likely false positives) → local record + 1-click prefilled,
+      // redacted, capped GitHub issue URL. Opt-in; nothing filed automatically.
+      runFeedback(projectDir, config, flags);
+      break;
+    case 'verify':
+      // v0.28 (field report #5): extract documented numbers/limits/enums as a
+      // verification task list for the agent to check against code (semantic
+      // drift — the class regex/AST can't see). Read-only.
+      runVerify(projectDir, config, flags);
+      break;
     case 'memory':
       runMemory(projectDir, config, flags);
       break;

package/cli/findings.mjs

@@ -0,0 +1,194 @@
+/**
+ * Findings — the structured, LLM-addressable result unit (v0.27).
+ *
+ * Background (LLM field report #3): DocGuard's whole job is to tell an agent
+ * what to do NEXT. A free-text `errors`/`warnings` string can't carry a stable
+ * code (for `explain <CODE>` + inline suppression), a confidence (the signal
+ * the false-positive feedback loop runs on), or a machine-readable suggested
+ * action. A Finding carries all three.
+ *
+ * The migration is INCREMENTAL and BACKWARD-COMPATIBLE. A validator that opts in
+ * builds `Finding[]` and returns `resultFromFindings(...)`, which still emits the
+ * exact `{ errors, warnings, passed, total }` shape every existing consumer
+ * (guard counts + exit code, diagnose, score, ci, `--format json`) already reads
+ * — PLUS a `findings` array that guard renders richly (each issue gets its
+ * `→ suggestion`). Validators that haven't migrated keep returning their
+ * hand-built results and render exactly as before. Nothing regresses.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ *
+ * @typedef {Object} Suggestion
+ * @property {'fix'|'suppress'|'review'|'report'} kind
+ * @property {string}  text             One concise line: what to do next.
+ * @property {string} [command]         Optional CLI/skill command to run.
+ * @property {string} [pragma]          Optional inline suppression snippet.
+ *
+ * @typedef {Object} Finding
+ * @property {string}      code          Stable code, e.g. 'SEC001' (see CODES).
+ * @property {string}      validator     Owning validator key.
+ * @property {'error'|'warn'} severity
+ * @property {'high'|'low'} confidence   'low' = candidate false positive.
+ * @property {string}      message       Concise, NO ansi colour.
+ * @property {string|null} location      'path:line' or 'path'.
+ * @property {Suggestion|null} suggestion
+ * @property {boolean}     reportable    Surface in `docguard feedback`.
+ * @property {string|null} redactedContext  Safe-to-share context for a report.
+ */
+
+/**
+ * Stable finding-code registry. `docguard explain <CODE>` reads this, and
+ * inline `// docguard:ignore <CODE>` keys off it. Keep codes append-only — a
+ * published code is a public surface we don't renumber.
+ */
+export const CODES = {
+  SEC001: {
+    validator: 'security',
+    title: 'Hardcoded password',
+    help: 'A `password`/`passwd`/`pwd` assignment with a quoted literal value (8+ chars). If the value is natural-language UI copy or a validation message — not a credential — this is a false positive: DocGuard now flags those low-confidence, but you can suppress inline.',
+    suppress: '// docguard:ignore SEC001 — UI copy, not a credential',
+  },
+  SEC002: {
+    validator: 'security',
+    title: 'Hardcoded API key',
+    help: 'An `api_key`/`apikey` assignment with a quoted literal value (16+ chars). Move it to an environment variable and read it via `process.env`.',
+    suppress: '// docguard:ignore SEC002 — sample value in fixture',
+  },
+  SEC003: {
+    validator: 'security',
+    title: 'Hardcoded secret key',
+    help: 'A `secret_key`/`secretkey` assignment with a quoted literal value (16+ chars). Move it to an environment variable.',
+    suppress: '// docguard:ignore SEC003 — reason',
+  },
+  SEC004: {
+    validator: 'security',
+    title: 'Hardcoded access token',
+    help: 'An `access_token`/`accesstoken` assignment with a quoted literal value (16+ chars). Move it to an environment variable.',
+    suppress: '// docguard:ignore SEC004 — reason',
+  },
+  SEC005: {
+    validator: 'security',
+    title: 'AWS Access Key ID',
+    help: 'A string matching the AWS Access Key ID format (AKIA…). Rotate it immediately if real, and move credentials to the AWS credential chain / environment.',
+    suppress: '// docguard:ignore SEC005 — documented example key',
+  },
+  SEC006: {
+    validator: 'security',
+    title: 'API secret key (Stripe/OpenAI pattern)',
+    help: 'A string matching a live/test secret-key format (sk-…, sk_live_…). Rotate it if real and move it to an environment variable.',
+    suppress: '// docguard:ignore SEC006 — reason',
+  },
+  SEC010: {
+    validator: 'security',
+    title: '.env not in .gitignore',
+    help: 'No `.env` entry was found in .gitignore, so a local `.env` could be committed. Add `.env` (and `.env.local`) to .gitignore.',
+    suppress: null,
+  },
+  SEC011: {
+    validator: 'security',
+    title: 'No source files scanned for secrets',
+    help: 'The secret scan matched zero source files — usually a too-broad ignore config or a wrong sourceRoot. A scan that checks nothing is a dangerous false ✅.',
+    suppress: null,
+  },
+};
+
+/**
+ * Build a Finding with sane defaults. `reportable` defaults to true for
+ * low-confidence findings — low confidence IS the feedback signal.
+ *
+ * @param {Partial<Finding>} f
+ * @returns {Finding}
+ */
+export function mkFinding(f) {
+  const severity = f.severity === 'error' ? 'error' : 'warn';
+  const confidence = f.confidence === 'low' ? 'low' : 'high';
+  return {
+    code: f.code || null,
+    validator: f.validator || null,
+    severity,
+    confidence,
+    message: f.message || '',
+    location: f.location || null,
+    suggestion: f.suggestion || null,
+    reportable: f.reportable === true || confidence === 'low',
+    redactedContext: f.redactedContext || null,
+  };
+}
+
+/**
+ * Derive the legacy `{ errors, warnings, passed, total }` result from a list of
+ * findings, keeping `findings` attached for the rich renderer. ONE source of
+ * truth — the strings guard counts and the findings guard renders can never
+ * disagree because they're computed from the same array.
+ *
+ * @param {Finding[]} findings
+ * @param {{passed?:number, total?:number, applicable?:boolean}} [opts]
+ */
+export function resultFromFindings(findings, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  for (const f of findings) {
+    if (f.severity === 'error') errors.push(f.message);
+    else warnings.push(f.message);
+  }
+  const res = {
+    errors,
+    warnings,
+    passed: opts.passed || 0,
+    total: opts.total != null ? opts.total : 0,
+    findings,
+  };
+  if (opts.applicable !== undefined) res.applicable = opts.applicable;
+  return res;
+}
+
+/**
+ * Does an inline `docguard:ignore` pragma in `text` suppress finding `code`?
+ *
+ * Accepted forms (mirrors the ergonomics of eslint-disable / ruff `# noqa`):
+ *   docguard:ignore                 → suppresses ANY code on the line
+ *   docguard:ignore SEC001          → suppresses exactly SEC001
+ *   docguard:ignore SEC001,DQ002    → comma list
+ *   docguard:ignore SEC*            → prefix wildcard
+ *   docguard:ignore all             → suppresses any code
+ *   docguard:ignore-secret          → convenience alias for any SEC* code
+ *
+ * @param {string} text
+ * @param {string} code
+ * @returns {boolean}
+ */
+export function suppressesCode(text, code) {
+  if (!text || !code) return false;
+  const m = text.match(/docguard:ignore(-secret)?\b[ \t]*([A-Za-z0-9_,*-]+)?/i);
+  if (!m) return false;
+  if (m[1]) return /^SEC/i.test(code);            // ignore-secret alias
+  const arg = (m[2] || '').trim();
+  if (!arg) return true;                           // bare ignore → any code
+  return arg.split(',').map((s) => s.trim()).some((tok) => {
+    if (!tok) return false;
+    if (tok.toLowerCase() === 'all') return true;
+    if (tok.endsWith('*')) return code.toUpperCase().startsWith(tok.slice(0, -1).toUpperCase());
+    return tok.toUpperCase() === code.toUpperCase();
+  });
+}
+
+/**
+ * Source-line suppression: an ignore pragma counts if it's on the flagged line
+ * OR the line directly above it (so a comment can sit above the offending
+ * statement, the common style for non-trailing-comment languages).
+ */
+export function lineSuppresses(code, line, prevLine = '') {
+  return suppressesCode(line, code) || suppressesCode(prevLine, code);
+}
+
+/**
+ * Flatten a one-line, colour-free rendering of a suggestion — used by JSON
+ * consumers, diagnose, and the feedback body. Guard does its own coloured
+ * rendering and does not use this.
+ */
+export function suggestionLine(s) {
+  if (!s) return '';
+  let out = s.text || '';
+  if (s.command) out += `  →  ${s.command}`;
+  else if (s.pragma) out += `  →  ${s.pragma}`;
+  return out;
+}