Skip to content

V4 — Compliance Manual Generator — Test Runbook

Asset: V4 (apps/compliance-manual/) — offline composer that turns a framework manual spec (+ optional E0 snapshot) into a branded framework compliance manual (markdown + HTML, optional PDF). Finishes the V series. Owner: SH · Milestone: M4. Offline-only (Parts A + B); no live phase — mirrors S4.md / V5.md.

Part A — Offline build + test gate (~3 min, $0)

cd apps/compliance-manual
npm ci
npm run typecheck         # tsc over src + tests, --noEmit
npm test                  # jest: adapt + render suites

Acceptance: - [ ] npm run typecheck exits 0. - [ ] npm test is green — coverage math, honest-missing-implementation, status derivation, family grouping, posture-appendix present/absent, HTML self-containment + injection escaping, determinism. - [ ] Auto-discovered by .github/workflows/app-tests.yml (has a test script).

Part B — Worked composition (~4 min, $0)

cd apps/compliance-manual
npm run build
node dist/index.js \
  --spec     examples/spec.json \
  --branding examples/branding.json \
  --output   /tmp/v4 \
  --now 2026-06-10T12:00:00.000Z

Acceptance — composition is re-presentation, never fabrication: - [ ] Writes compliance-manual.md, compliance-manual.html, and model.json to /tmp/v4. Stdout reports the framework + coverage (e.g. SOC 2 Trust Services Criteria: 9/12 implemented, coverage 75%). - [ ] Each control renders its requirement, the implementation statement, the enforcing SnowOps asset(s), evidence references, governing policy, and a status badge. - [ ] Honest about undocumented controls — a control with no implementation statement renders a "not yet documented" status rather than an invented one; the coverage % derivation is stated, not opaque. - [ ] Re-run with --snapshot examples/snapshot.json and confirm a posture appendix re-presents the E0 numbers; omit it and confirm the appendix is absent (not fabricated). - [ ] HTML is self-contained — grep -c 'http' /tmp/v4/compliance-manual.html returns 0 when no logoUrl is set (inline CSS, no JS, no network refs). - [ ] Optional: --pdf renders compliance-manual.pdf via Pandoc where available; a Pandoc failure is logged but never fails the run.

Notes

  • No cross-package imports (D37/D40/D49): V4 re-declares its manual-spec + E0 input contracts; it depends on the artifact shapes, not the producing packages.
  • Inputs: the manual spec pairs each framework control with its implementation + enforcing asset + evidence + policy — the policies authored in V1 (templates/policies/) are the natural policy references; the control mappings under docs/compliance/ inform the spec's control set.