docguard-cli 0.31.0 → 0.33.0

package/cli/writers/history.mjs

@@ -0,0 +1,82 @@
+/**
+ * Score History — local-first trend memory at `.docguard/history.jsonl`.
+ *
+ * `docguard ci` appends one line per run ({timestamp, commit, score, grade,
+ * errors, warnings, passed, total, status}); `docguard score --trend` reads
+ * it back and renders the trajectory. JSONL because append is the hot path:
+ * one O(1) write per CI run, and a truncated last line (crash mid-write)
+ * corrupts one entry, not the file. The rare trim rewrite goes through a
+ * temp-file + rename so a crash mid-trim can't truncate history; concurrent
+ * appends during a trim window can still lose an entry — acceptable for a
+ * trend log, not a ledger.
+ *
+ * Local-first by design: `.docguard/` is gitignored, so history accumulates
+ * per checkout. In ephemeral CI, persist it across runs with a cache/artifact
+ * step (see CI-RECIPES) — the file format is stable and merge-friendly.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+
+const HISTORY_PATH = '.docguard/history.jsonl';
+
+// Trim trigger: beyond this many entries the file is rewritten keeping the
+// most recent MAX_ENTRIES. Generous — 1000 CI runs of ~150 bytes ≈ 150 KB.
+const MAX_ENTRIES = 1000;
+
+/**
+ * Append one run entry. Silent no-op on failure (read-only checkouts, odd
+ * CI filesystems) — recording history must never fail the pipeline it's
+ * recording.
+ */
+export function appendHistory(projectDir, entry) {
+  try {
+    const p = resolve(projectDir, HISTORY_PATH);
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, JSON.stringify(entry) + '\n');
+    // Occasional trim, checked cheaply by size (~200 KB ≫ MAX_ENTRIES rows).
+    // Temp-file + rename: a crash mid-trim leaves the old file intact
+    // instead of a truncated one (L2).
+    if (statSync(p).size > 256 * 1024) {
+      const rows = loadHistory(projectDir, MAX_ENTRIES);
+      const tmp = p + '.tmp';
+      writeFileSync(tmp, rows.map(r => JSON.stringify(r)).join('\n') + '\n');
+      renameSync(tmp, p);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the last `limit` valid entries, oldest → newest. Malformed lines
+ * (partial writes, hand edits) are skipped, never thrown.
+ */
+export function loadHistory(projectDir, limit = 50) {
+  try {
+    const p = resolve(projectDir, HISTORY_PATH);
+    if (!existsSync(p)) return [];
+    const out = [];
+    for (const line of readFileSync(p, 'utf-8').split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e && typeof e.score === 'number') out.push(e);
+      } catch { /* skip malformed line */ }
+    }
+    return out.slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Unicode sparkline over the score series (0–100 → ▁–█). Pure display.
+ */
+export function sparkline(scores) {
+  const BARS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+  return scores
+    .map(s => BARS[Math.min(BARS.length - 1, Math.max(0, Math.floor((s / 100) * BARS.length)))])
+    .join('');
+}

package/cli/writers/junit.mjs

@@ -0,0 +1,103 @@
+/**
+ * JUnit XML writer — `docguard guard --format junit`.
+ *
+ * SARIF covers GitHub Code Scanning; JUnit covers everything else an
+ * enterprise runs: GitLab CI (`artifacts:reports:junit`), Jenkins
+ * (`junit` step), Azure DevOps, CircleCI, Bamboo. One testcase per
+ * validator keeps the report readable in those UIs — a failed validator
+ * shows its findings (code + message + location) as the failure body.
+ *
+ * Mapping (deterministic):
+ *   validator error findings         → <failure> (red in every CI)
+ *   validator crashed (fail, no
+ *   structured findings)             → <error> from its string errors (red)
+ *   warn-only validator              → passing testcase + findings in
+ *                                      <system-out> (visible, non-gating)
+ *   skipped / n/a                    → <skipped/>
+ *
+ * Zero npm dependencies — pure string assembly with strict XML escaping.
+ */
+
+function esc(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function findingLine(f) {
+  const code = f.code ? `[${f.code}] ` : '';
+  const loc = f.location ? ` (${f.location})` : '';
+  return `${code}${f.message}${loc}`;
+}
+
+/**
+ * Build the JUnit XML document from runGuardInternal's data.
+ * `data.validators` entries: { name, status, findings? }; `data.findings`
+ * is the flat list with `validator` back-references — we group by the
+ * validator display name via each result's own findings when present,
+ * falling back to the flat list.
+ */
+export function toJUnit(data) {
+  const cases = [];
+  let failures = 0, errorCount = 0, skipped = 0;
+
+  for (const v of data.validators || []) {
+    const vFindings = Array.isArray(v.findings)
+      ? v.findings
+      : (data.findings || []).filter(f => f.validator === v.key || f.validator === v.name);
+    const errors = vFindings.filter(f => f.severity === 'error');
+    const warns = vFindings.filter(f => f.severity !== 'error');
+    const attrs = `name="${esc(v.name)}" classname="docguard.guard"`;
+
+    if (v.status === 'skipped' || v.status === 'na') {
+      skipped++;
+      cases.push(`    <testcase ${attrs}><skipped/></testcase>`);
+    } else if (errors.length > 0) {
+      failures++;
+      const body = errors.map(findingLine).join('\n');
+      cases.push(
+        `    <testcase ${attrs}>\n` +
+        `      <failure message="${esc(errors[0].message)}" type="${esc(errors[0].code || 'docguard')}">${esc(body)}</failure>\n` +
+        `    </testcase>`
+      );
+    } else if (v.status === 'fail') {
+      // A validator that failed WITHOUT structured error findings — the
+      // crash path (guard catches the throw and records string errors only).
+      // This must go red in CI, not render as a passing testcase (M1).
+      errorCount++;
+      const body = (v.errors || []).join('\n') || 'validator failed without structured findings';
+      cases.push(
+        `    <testcase ${attrs}>\n` +
+        `      <error message="${esc((v.errors || [])[0] || 'validator failed')}" type="docguard.crash">${esc(body)}</error>\n` +
+        `    </testcase>`
+      );
+    } else if (warns.length > 0) {
+      const body = warns.map(findingLine).join('\n');
+      cases.push(
+        `    <testcase ${attrs}>\n` +
+        `      <system-out>${esc(body)}</system-out>\n` +
+        `    </testcase>`
+      );
+    } else {
+      cases.push(`    <testcase ${attrs}/>`);
+    }
+  }
+
+  const total = (data.validators || []).length;
+  const suiteAttrs =
+    `name="docguard guard — ${esc(data.project || 'project')}" ` +
+    `tests="${total}" failures="${failures}" errors="${errorCount}" skipped="${skipped}" ` +
+    `timestamp="${esc(data.timestamp || '')}"`;
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<testsuites tests="${total}" failures="${failures}" errors="${errorCount}">\n` +
+    `  <testsuite ${suiteAttrs}>\n` +
+    cases.join('\n') + (cases.length ? '\n' : '') +
+    `  </testsuite>\n` +
+    `</testsuites>`
+  );
+}

package/docs/commands.md

@@ -38,6 +38,17 @@ npx docguard-cli diagnose --format prompt # Raw AI prompt (all issues combined)
 npx docguard-cli guard                   # Text output
 npx docguard-cli guard --format json     # Structured JSON (the stable agent contract)
 npx docguard-cli guard --format sarif    # SARIF 2.1.0 for GitHub Code Scanning
+npx docguard-cli guard --format junit    # JUnit XML for GitLab/Jenkins/Azure DevOps
+npx docguard-cli guard --update-baseline # Freeze current findings (brownfield adoption)
+npx docguard-cli guard --no-baseline     # Ignore the committed baseline this run
+```
+
+**Adoption baseline:** on a legacy repo, `--update-baseline` writes
+`.docguard.baseline.json` (commit it). From then on guard/ci suppress those
+frozen findings — visibly — and gate only new drift. Fingerprints are stable
+across line-number churn and volatile counts, so the baseline doesn't rot.
+
+```bash
 npx docguard-cli guard --verbose         # Show all check details
 npx docguard-cli guard --changed-only    # Pre-commit lite mode (fast subset)
 ```
@@ -181,7 +192,7 @@ never touched without `--force`.
 
 **MCP server over stdio** — DocGuard's read-only core as native agent tools
 (`docguard_guard`, `docguard_score`, `docguard_explain`,
-`docguard_verify_claims`, `docguard_diagnose`).
+`docguard_verify_claims`, `docguard_report`, `docguard_diagnose`).
 
 ```bash
 claude mcp add docguard -- npx docguard-cli mcp
@@ -211,15 +222,32 @@ npx docguard-cli memory --pack     # .docguard/context-pack.md (session-start co
 
 ## DevOps Commands
 
+### `docguard report`
+
+**Compliance-evidence bundle for audits** — guard verdict, CDD score, ALCOA+
+data-integrity attributes, findings grouped by code, and fix history, stamped
+with the git commit and a tamper-evident sha256 integrity hash. Evidence, not
+a gate: always exits 0 (`guard`/`ci` fail builds).
+
+```bash
+npx docguard-cli report                          # markdown to stdout
+npx docguard-cli report --format json            # machine bundle
+npx docguard-cli report --out evidence.md        # write to a file
+```
+
 ### `docguard ci`
 
-**Single command for CI/CD pipelines.** Runs guard + score internally (no subprocess).
+**Single command for CI/CD pipelines.** Runs guard + score internally (no
+subprocess). Read-only and machine-clean: it never scaffolds or mutates the
+workspace it validates. Each run appends one line to `.docguard/history.jsonl`
+so `docguard score --trend` can show the trajectory (opt out: `--no-history`).
 
 ```bash
 npx docguard-cli ci                              # Basic check
 npx docguard-cli ci --threshold 70               # Fail below score 70
 npx docguard-cli ci --threshold 80 --fail-on-warning  # Strict mode
 npx docguard-cli ci --format json                # JSON for GitHub Actions
+npx docguard-cli score --trend                   # Score history from past ci runs
 ```
 
 ### `docguard hooks`

package/docs/configuration.md

@@ -111,6 +111,20 @@ Conventional doc folders (`docs/`, `doc/`, `documentation/`, `guides/`,
 that set with non-standard homes — it never replaces auto-detection. To exclude
 a conventional dir, list it in `.docguardignore`.
 
+## Adoption baseline — `baseline`
+
+When a committed `.docguard.baseline.json` exists (written by
+`docguard guard --update-baseline`), guard/ci suppress the frozen findings
+and gate only new drift. Set `"baseline": false` in `.docguard.json` to
+ignore the file entirely (same as always passing `--no-baseline`):
+
+```json
+{ "baseline": false }
+```
+
+Suppression is always visible in output and in the `baselineSuppressed`
+JSON field — nothing is silently hidden.
+
 ## Muting a validator
 
 Two ways to turn a validator off, for two different intents:

package/docs/faq.md

@@ -123,6 +123,18 @@ Yes — DocGuard ships a template at `templates/ci/github-actions.yml`. Copy it
 
 Only if you install hooks (`docguard hooks`). Without hooks, it's advisory only.
 
+### I ran guard on our legacy repo and got dozens of findings. Now what?
+
+Freeze them and move forward:
+
+```bash
+npx docguard-cli guard --update-baseline   # writes .docguard.baseline.json — commit it
+```
+
+From then on guard/ci pass, suppress the frozen findings **visibly**
+("N pre-existing finding(s) suppressed"), and gate only NEW drift. Burn the
+baseline down at your own pace; `--no-baseline` shows the full picture anytime.
+
 ---
 
 ## Technical

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.31.0"
+  version: "0.33.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.31.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.31.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Sync Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {

package/schemas/docguard-config.schema.json

@@ -29,6 +29,11 @@
       "enum": ["cli", "library", "webapp", "api", "unknown"],
       "description": "Project shape. Affects which validators run (e.g. webapp + api need env vars; cli/library can skip)."
     },
+    "baseline": {
+      "type": "boolean",
+      "description": "Set false to ignore a committed .docguard.baseline.json entirely (equivalent to always passing --no-baseline). Default: the baseline auto-applies when the file exists.",
+      "default": true
+    },
     "projectTypeConfig": {
       "type": "object",
       "description": "Per-type behavior knobs that override profile defaults.",