docguard-cli 0.28.0 → 0.29.0

package/cli/commands/memory.mjs

@@ -21,8 +21,12 @@
  * Zero NPM dependencies. Pure orchestration of existing diff helpers.
  */
 
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { c } from '../shared.mjs';
 import { diffRoutes, diffEntities, diffEnvVars, diffTechStack } from './diff.mjs';
+import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
+import { runGuardInternal } from './guard.mjs';
 
 /**
  * Compute an accuracy score for a single domain. Returns:
@@ -47,7 +51,118 @@ function _domainAccuracy(d) {
   };
 }
 
+// ── Context pack (v0.29) ─────────────────────────────────────────────────────
+
+/** H2 sections of AGENTS.md whose heading reads like rules/conventions/workflow. */
+function extractConventions(agentsMd, capLines = 60) {
+  const out = [];
+  const lines = agentsMd.split('\n');
+  let taking = false;
+  for (const line of lines) {
+    const h2 = line.match(/^##\s+(.+)$/);
+    if (h2) taking = /rules|conventions|workflow/i.test(h2[1]);
+    if (taking) {
+      out.push(line);
+      if (out.length >= capLines) {
+        out.push('<!-- truncated — read AGENTS.md for the full rules -->');
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * `docguard memory --pack` — write .docguard/context-pack.md: a compact,
+ * code-truth-stamped session-start context for an AI agent. Everything in it
+ * is derived from scanners (buildMemoryPlan) and guard — numbers, not prose —
+ * so it can't hallucinate and is always regenerable.
+ */
+function runMemoryPack(projectDir, config, flags) {
+  const plan = buildMemoryPlan(projectDir, config);
+  const guard = runGuardInternal(projectDir, config);
+  const lines = [];
+
+  lines.push(`# Context Pack — ${config.projectName}`);
+  lines.push('');
+  lines.push(`<!-- Generated by \`docguard memory --pack\` ${new Date().toISOString()} — regenerate, don't edit -->`);
+  lines.push('');
+  lines.push(`**Guard:** ${guard.status} — ${guard.passed}/${guard.total} checks (${guard.errors} error(s), ${guard.warnings} warning(s))`);
+  lines.push('');
+
+  lines.push('## Code-truth surface');
+  lines.push('');
+  lines.push(`- Stack: ${plan.profile.languages.join(', ') || 'unknown'}${plan.profile.frameworks.length ? ` · ${plan.profile.frameworks.join(', ')}` : ''} · kind: ${plan.profile.kind}`);
+  lines.push(`- Modules: ${plan.surface.modules.length} · Endpoints: ${plan.surface.endpoints.length} · Entities: ${plan.surface.entities.length} · Env vars: ${plan.surface.envVars.length}`);
+  lines.push(`- Tests: ${plan.surface.tests.totalFiles} files, ${plan.surface.tests.totalCases} cases`);
+  lines.push('');
+
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(docsDir)) {
+    lines.push('## Canonical docs');
+    lines.push('');
+    let entries = [];
+    try { entries = readdirSync(docsDir).filter(f => f.endsWith('.md')).sort(); } catch { /* ignore */ }
+    for (const doc of entries) {
+      let reviewed = '';
+      try {
+        const m = readFileSync(resolve(docsDir, doc), 'utf-8').match(/docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})/);
+        if (m) reviewed = ` (last-reviewed ${m[1]})`;
+      } catch { /* ignore */ }
+      lines.push(`- docs-canonical/${doc}${reviewed}`);
+    }
+    lines.push('');
+  }
+
+  const agentsPath = resolve(projectDir, 'AGENTS.md');
+  if (existsSync(agentsPath)) {
+    let conventions = [];
+    try { conventions = extractConventions(readFileSync(agentsPath, 'utf-8')); } catch { /* ignore */ }
+    if (conventions.length > 0) {
+      lines.push('## Project rules (from AGENTS.md)');
+      lines.push('');
+      lines.push(...conventions);
+      lines.push('');
+    }
+  }
+
+  const driftPath = resolve(projectDir, 'DRIFT-LOG.md');
+  if (existsSync(driftPath)) {
+    try {
+      const drift = readFileSync(driftPath, 'utf-8');
+      const entries = drift.match(/^##\s+.+$/gm) || [];
+      if (entries.length > 0) {
+        lines.push('## Known drift');
+        lines.push('');
+        lines.push(`- ${entries.length} logged deviation(s); latest: ${entries[entries.length - 1].replace(/^##\s+/, '')}`);
+        lines.push('');
+      }
+    } catch { /* ignore */ }
+  }
+
+  lines.push('---');
+  lines.push('Verify claims: `docguard verify --semantic` · Full docs: `llms-full.txt`');
+  lines.push('');
+  const content = lines.join('\n');
+
+  if (flags.stdout) {
+    console.log(content);
+    return;
+  }
+  const outDir = resolve(projectDir, '.docguard');
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  const outPath = resolve(outDir, 'context-pack.md');
+  writeFileSync(outPath, content, 'utf-8');
+  console.log(`${c.bold}🧠 DocGuard Context Pack${c.reset}`);
+  console.log(`${c.green}✅ Wrote ${outPath}${c.reset} ${c.dim}(${lines.length} lines — load at agent session start)${c.reset}`);
+  console.log('');
+}
+
 export function runMemory(projectDir, config, flags) {
+  // v0.29: --pack writes the agent context pack and exits — a separate output
+  // artifact, not a display mode of the accuracy drill-down below.
+  if (flags.pack) return runMemoryPack(projectDir, config, flags);
+
   const isJson = flags.format === 'json';
   const wantsDiff = flags.diff || (flags.args || []).includes('--diff');
 

package/cli/commands/score.mjs

@@ -9,6 +9,8 @@ import { execSync } from 'node:child_process';
 import { c, docHasSection } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
+import { extractSemanticClaims } from '../scanners/semantic-claims.mjs';
+import { assessAgentReadability } from '../scanners/agent-readability.mjs';
 
 /**
  * Detect whether the project configures a test runner (the "Check 3" of the
@@ -299,11 +301,17 @@ export function runScore(projectDir, config, flags) {
   console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
 
   for (const attr of alcoa.attributes) {
-    const icon = attr.met ? `${c.green}✅` : `${c.yellow}⚠️`;
-    const status = attr.met ? `${c.green}${attr.evidence}` : `${c.yellow}${attr.gap}`;
-    console.log(`  ${icon} ${attr.name.padEnd(16)}${c.reset} — ${status}${c.reset}`);
+    // `unverified` is a third state: not a green pass, but not a red gap either —
+    // "checked the structure, can't confirm the facts." Render it neutrally (🔍,
+    // cyan) so it reads as a to-do, not a failure.
+    const unverified = attr.status === 'unverified';
+    const icon = attr.met ? `${c.green}✅` : unverified ? `${c.cyan}🔍` : `${c.yellow}⚠️`;
+    const tone = attr.met ? c.green : unverified ? c.cyan : c.yellow;
+    const body = attr.met ? attr.evidence : attr.gap;
+    console.log(`  ${icon} ${attr.name.padEnd(16)}${c.reset} — ${tone}${body}${c.reset}`);
     if (!attr.met && attr.fix) {
-      console.log(`  ${c.dim}     Fix: ${attr.fix}${c.reset}`);
+      const verb = unverified ? 'Verify' : 'Fix';
+      console.log(`  ${c.dim}     ${verb}: ${attr.fix}${c.reset}`);
     }
   }
 
@@ -314,6 +322,22 @@ export function runScore(projectDir, config, flags) {
   }
   console.log('');
 
+  // ── Agent Readability (v0.29) ──
+  // Display-only, like ALCOA+ — never feeds the gating CDD grade. Answers the
+  // 2026 question: can an AI consumer FIND, QUOTE, and TRUST these docs?
+  const agentRead = assessAgentReadability(projectDir, config);
+  console.log(`  ${c.bold}🤖 Agent Readability${c.reset} ${c.dim}(how well AI consumers can read this repo)${c.reset}`);
+  console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
+  for (const m of agentRead.metrics) {
+    const icon = m.score >= 60 ? `${c.green}✅` : `${c.yellow}⚠️`;
+    const tone = m.score >= 60 ? c.green : c.yellow;
+    console.log(`  ${icon} ${m.label.padEnd(28)}${c.reset} — ${tone}${m.detail}${c.reset}`);
+    if (m.fix) console.log(`  ${c.dim}     Fix: ${m.fix}${c.reset}`);
+  }
+  const arColor = agentRead.score >= 75 ? c.green : agentRead.score >= 40 ? c.yellow : c.red;
+  console.log(`\n  ${arColor}${c.bold}Agent Readability: ${agentRead.score}% (${agentRead.grade})${c.reset}`);
+  console.log('');
+
   // Badge snippet
   const bColor = totalScore >= 90 ? 'brightgreen' : totalScore >= 80 ? 'green' : totalScore >= 70 ? 'yellowgreen' : totalScore >= 60 ? 'yellow' : totalScore >= 50 ? 'orange' : 'red';
   const badgeUrl = `https://img.shields.io/badge/CDD_Score-${totalScore}%2F100_(${grade})-${bColor}`;
@@ -411,14 +435,54 @@ function computeAlcoaCompliance(projectDir, config, scores) {
   });
 
   // 5. Accurate — Do docs match the code?
-  const accurate = scores.drift >= 80 && scores.docQuality >= 50;
-  attributes.push({
-    name: 'Accurate',
-    met: accurate,
-    evidence: accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%` : null,
-    gap: !accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}% — docs may be inaccurate` : null,
-    fix: !accurate ? 'Run docguard diagnose to find doc/code mismatches' : null,
-  });
+  //
+  // Field report #6: this attribute used to read `met` purely from structural
+  // signals (drift markers + prose quality). That let it show ✅ "100%" while a
+  // watched doc stated a factually wrong number — the confidence-inverting false
+  // negative the field report is about. Structure passing is necessary but NOT
+  // sufficient for "accurate"; the factual claims (counts/limits/enums) have to be
+  // verified against code, and DocGuard's deterministic core can't do that — only
+  // an agent via `verify --semantic` can. So we add a third, honest state:
+  //   met        — structure sound AND no unverified factual claims exist
+  //   unverified — structure sound BUT documented claims remain unchecked vs code
+  //   unmet      — structural drift/quality below bar
+  // `unverified` counts as not-met for the ALCOA percentage (so the score stops
+  // overclaiming), but renders as a neutral 🔍 (not a ⚠️ failure) — "I haven't
+  // confirmed this," not "this is wrong." This is display-only: it never touches
+  // the gating CDD grade (totalScore), which CI thresholds read.
+  const structurallyAccurate = scores.drift >= 80 && scores.docQuality >= 50;
+  let unverifiedClaims = 0;
+  if (structurallyAccurate) {
+    try { unverifiedClaims = extractSemanticClaims(projectDir, config).length; } catch { /* extractor best-effort */ }
+  }
+  if (!structurallyAccurate) {
+    attributes.push({
+      name: 'Accurate',
+      met: false,
+      status: 'unmet',
+      evidence: null,
+      gap: `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}% — docs may be inaccurate`,
+      fix: 'Run docguard diagnose to find doc/code mismatches',
+    });
+  } else if (unverifiedClaims > 0) {
+    attributes.push({
+      name: 'Accurate',
+      met: false,
+      status: 'unverified',
+      evidence: null,
+      gap: `Structure sound (drift ${scores.drift}%, quality ${scores.docQuality}%), but ${unverifiedClaims} documented claim(s) (counts/limits/enums) are unverified against code`,
+      fix: 'Run docguard verify --semantic to check the documented values against the code',
+    });
+  } else {
+    attributes.push({
+      name: 'Accurate',
+      met: true,
+      status: 'met',
+      evidence: `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%, no unverified factual claims`,
+      gap: null,
+      fix: null,
+    });
+  }
 
   // 6. Complete — Are all required docs present?
   const complete = scores.structure >= 80;

package/cli/docguard.mjs

@@ -48,6 +48,7 @@ import { runVerify } from './commands/verify.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
+import { runMcp } from './commands/mcp.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -90,6 +91,7 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${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}mcp${c.reset}        MCP server over stdio — guard/score/explain/verify/diagnose as agent tools
   ${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)
@@ -375,6 +377,23 @@ async function main() {
       // 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] === '--full') {
+      // v0.29: `docguard llms --full` emits llms-full.txt (inline doc bodies,
+      // the Mintlify-popularized companion to the llms.txt index).
+      flags.full = true;
+    } else if (args[i] === '--pack') {
+      // v0.29: `docguard memory --pack` writes .docguard/context-pack.md — a
+      // compact code-truth-stamped session-start context for AI agents.
+      flags.pack = true;
+    } else if (args[i] === '--sync') {
+      // v0.29: `docguard agents --sync` regenerates the agent-file family
+      // (CLAUDE.md, GEMINI.md, copilot-instructions, .cursor rules) from
+      // AGENTS.md — the canonical source. Kills hand-duplication drift.
+      flags.sync = true;
+    } else if (args[i] === '--check') {
+      // v0.29: `docguard agents --check` — CI staleness gate for the synced
+      // agent-file family (exit 2 when a variant is missing or stale).
+      flags.check = true;
     } else if (args[i] === '--plan') {
       flags.plan = true;
     } else if (args[i] === '--since' && args[i + 1]) {
@@ -512,10 +531,13 @@ async function main() {
   // touch" — so it joins the club to suppress the banner AND ensureSkills'
   // .agent/.specify writes, which were a surprising side effect of a bare
   // `generate --plan` (and were already suppressed for `--plan --write`).
-  const jsonMode = flags.format === 'json';
+  // v0.29: 'sarif' joins 'json' — any machine format where stdout IS the
+  // artifact belongs here, or the banner corrupts the payload.
+  const jsonMode = flags.format === 'json' || flags.format === 'sarif';
   // `agent` emits a machine task graph (JSON by default) — it must be banner-
   // free and side-effect-free like the other read-only commands.
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent';
+  // `mcp`: stdout IS the JSON-RPC transport — any banner byte corrupts the stream.
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent' || command === 'mcp';
 
   if (!headless) printBanner();
 
@@ -540,6 +562,8 @@ async function main() {
     'feedback',
     // verify only reads docs and emits a task list — pure report.
     'verify',
+    // mcp serves read-only tools over stdio — scaffolding writes are off-limits.
+    'mcp',
   ]);
 
   // Silent auto-check: install skills/commands if missing. Skip entirely in
@@ -691,6 +715,11 @@ async function main() {
       // drift — the class regex/AST can't see). Read-only.
       runVerify(projectDir, config, flags);
       break;
+    case 'mcp':
+      // MCP stdio server — guard/score/explain/verify-claims/diagnose as tools
+      // for MCP clients. Long-lived; resolves when stdin closes.
+      await runMcp(projectDir, config, flags);
+      break;
     case 'memory':
       runMemory(projectDir, config, flags);
       break;