Skip to content

Documentation

Validation Pipeline

SveltyCMS tiered validation architecture for contributors — fast commits, safe pushes, deterministic CI

11/13/2026
5 min read Edit on GitHub

SveltyCMS uses a three-tier validation architecture that balances developer velocity with code safety. Every tier catches a different class of defect at the right stage of the development lifecycle.

Tip

New to the repo? Run bun run test:doctor --list for the live gate map, or bun run test:doctor to run unit + SQLite integration. Live dashboard: Test Status.

Tier 1 — Pre-commit (~2–3 min warm)

Hook: .githooks/pre-commit · Manual: bun run precommit

  1. scripts/check/check-test-db-safety.ts — never point tests at a live DB name or live config path
  2. bun run gate:fast — lint-staged (formats staged files before check runs)
  3. bun run check — oxfmt --check + oxlint + 18 parallel policy/AST/assurance gates (scripts/check/rule-registry.ts is the single owner of the list) + svelte-kit sync + tsc/svelte-check (parallel typecheck)
  4. bun run risk:audit — 6 parallel gates: global security-risk scan (all 4 adapters + loopback/tenant/test-mode/AST batch guards) + secret misuse + slop + tenant-isolation API hygiene (lint-tenant-api) + bun audit + OSV.dev (skipped if only docs changed; pass --full to force non-incremental scanning)
  5. bun run test:unit — full Vitest suite, invoked directly (skipped if only docs changed)
  6. bun run test:unit:components — real-DOM interaction suite (only when .svelte or UI/component/route/widget/store files are staged)
  7. SBOM sync — bun run audit:sbom when bun.lock / package.json changed

Tier 2 — Pre-push (~10–15 min warm)

Hook: .githooks/pre-push · Manual: bun run gate or bun run prepush

  1. scripts/check/check-test-db-safety.ts
  2. Production build via scripts/runs/integration-harness.ts --ensure-build — reuses a fresh 4-adapter build (with /api/testing) in <1 s, rebuilds when stale
  3. Bundle-size gate — scripts/check/check-bundle-size.ts
  4. Build & security probes (parallel) — scripts/runs/run-probe-group.ts: prod-backdoor, secret-misuse, hardware-tiers, tenant-isolation
  5. bun run check — TypeScript / Svelte quality gate (reused when this tree already passed it at commit time)
  6. CI unit parity — bun run test:coverage (full suite under coverage, ~4 min; skipped when no src/, tests/ or coverage config changed) + bun run test:unit:components
  7. CVE audit — bun audit (informational)
  8. SQLite integration — scripts/runs/run-integration.ts --no-build --diff (diff-scoped; full suite when harness/helpers or an unmapped path changed)
  9. DB parity — only when adapter/service code changed, plus a non-UTC clock run
  10. Browser gate — smoke.spec.ts plus the changed-path accessibility/visual/behavioural/media specs, then check-flake-budget.ts
  11. Deploy backdoor probe — scripts/probe/probe-deploy-testing-api.ts (after the browser gate: it rebuilds build/ without the testing harness)
  12. Mutation — scripts/test/mutate-core.ts --changed runs last (FULL_MUTATION=true for all seams)

scripts/runs/gate-cache.ts keys a passing gate on the tree hash (plus manifest/lock/test-config/runtime/DB mode, and the diff base for diff-scoped gates) and stores it in .git/svelty-gate-cache.json. A dirty or untracked tree never records or hits. bun run scripts/runs/gate-cache.ts clear forces a full run.

To keep the fast tier cheap, two registry entries aggregate rules instead of spawning one process each: check-source-lints (scripts/check/run-source-lints.ts) runs thirteen rules over a single workspace read, and check-ast-gates runs the module-graph linkmap and the tenant-scope analysis in one process. The newer gates — locale-format, css-tokens and click-away (rules inside check-source-lints) and check-hardcoded-copy (the check:copy:ratchet baseline) — add no step to the hook: see Testing Scripts Catalog.

Docs-only pushes skip build + integration. The multi-engine DB matrix and benchmarks are CI-only; pre-push runs the SQLite suite plus the changed-path browser contracts, not the full 11-shard E2E partition.

Release preparation — --release[=kind] runs scripts/version.ts after a green gate, commits the manifest as chore(release): bump version to vX.Y.Z and prints the push that publishes it. Reaches the hook two ways: bun run gate --release, or bun run git push --release … (the wrapper consumes the flag and exports SVELTY_RELEASE, since git never forwards hook arguments). Skipped on the docs-only and --only-failures paths — a release commit is only prepared behind a full gate. Details: Release Pipeline.

Important

CI-parity rule: pre-push re-runs the full unit suite under coverage (test:coverage), because unhandled errors and coverage floors only surface under the CI reporter and instrumentation. The plain, un-instrumented suite is not re-run — pre-commit already ran it.

Tier 3 — GitHub Actions

Workflow: .github/workflows/ci.yml

bootstrap → whitebox ×2 (policy/quality + unit) → build → db-tests × 4 → bench-core × 4 → e2e-prep → e2e × 8 named groups → all-green

Manual commands

Command Purpose
bun run test:doctor Gate map + unit + SQLite integration
bun run test:security Focused hooks security suite
bun run risk:audit Full pre-commit security scanners
bun run test:smart Git-diff suite picker
bun run test:e2e CI-parity Playwright
bun run gate Same as pre-push

Private config safety

Local automated runs use config/private.test.ts only. Never read or write the developer’s live config/private.ts. CI may create an ephemeral private.ts on the runner only.

Full detail: docs/tests/git-workflow.mdx · docs/tests/index.mdx · AGENTS.md technical standards

validationci-cdgit-hooksquality-gate
Was this page helpful?