Validation Pipeline
SveltyCMS tiered validation architecture for contributors — fast commits, safe pushes, deterministic CI
On this page
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.
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
scripts/check/check-test-db-safety.ts— never point tests at a live DB name or live config pathbun run gate:fast— lint-staged (formats staged files beforecheckruns)bun run check—oxfmt --check+oxlint+ 18 parallel policy/AST/assurance gates (scripts/check/rule-registry.tsis the single owner of the list) +svelte-kit sync+tsc/svelte-check(parallel typecheck)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--fullto force non-incremental scanning)bun run test:unit— full Vitest suite, invoked directly (skipped if only docs changed)bun run test:unit:components— real-DOM interaction suite (only when.svelteor UI/component/route/widget/store files are staged)- SBOM sync —
bun run audit:sbomwhenbun.lock/package.jsonchanged
Tier 2 — Pre-push (~10–15 min warm)
Hook: .githooks/pre-push · Manual: bun run gate or bun run prepush
scripts/check/check-test-db-safety.ts- 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 - Bundle-size gate —
scripts/check/check-bundle-size.ts - Build & security probes (parallel) —
scripts/runs/run-probe-group.ts: prod-backdoor, secret-misuse, hardware-tiers, tenant-isolation bun run check— TypeScript / Svelte quality gate (reused when this tree already passed it at commit time)- CI unit parity —
bun run test:coverage(full suite under coverage, ~4 min; skipped when nosrc/,tests/or coverage config changed) +bun run test:unit:components - CVE audit —
bun audit(informational) - SQLite integration —
scripts/runs/run-integration.ts --no-build --diff(diff-scoped; full suite when harness/helpers or an unmapped path changed) - DB parity — only when adapter/service code changed, plus a non-UTC clock run
- Browser gate —
smoke.spec.tsplus the changed-path accessibility/visual/behavioural/media specs, thencheck-flake-budget.ts - Deploy backdoor probe —
scripts/probe/probe-deploy-testing-api.ts(after the browser gate: it rebuildsbuild/without the testing harness) - Mutation —
scripts/test/mutate-core.ts --changedruns last (FULL_MUTATION=truefor 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.
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