Introduction

SveltyCMS uses a comprehensive Git workflow with automated testing and semantic versioning to ensure code quality and streamline the release process. A mandatory Local Quality Gate is enforced via native Git hooks to ensure that only verified code reaches the repository.

Our CI/CD and Local pipeline uses:

• Native Git Hooks: Zero-dependency quality gate (.githooks/pre-commit).
• Vitest (jsdom): Unified unit testing for components, stores, services, and API handlers.
• Unified Formatting: oxfmt-powered bun run format for lightning-fast cleanup.
• Vitest Unit Suite: Fast unit testing (1,100+ tests in under 10 seconds for the full suite).
• Playwright: Comprehensive E2E testing across multiple database backends.
• Tag-Driven Releases: Push a v* tag to main to trigger npm publish + GitHub Release.
• Standardized Network: Always use 127.0.0.1 for local consistency.

🛡️ Mandatory Local Quality Gate

Before any commit or push, SveltyCMS runs automated checks via native Git hooks. Activate them once per clone:

git config core.hooksPath .githooks

Git Hook Overview

SveltyCMS uses native Git hooks for local quality gates — no external precheck orchestrator script required.

Pre-commit (DB safety → format+lint → lint-staged → risk:audit → unit → SBOM)

.githooks/pre-commit runs:

1. Database safety — scripts/check/check-test-db-safety.ts blocks unsafe private.test.ts, live private.ts pointing at test DBs, and matching live/test DB names (user data protection).
2. Format + lint — bun run check (oxfmt + oxlint).
3. Lint-staged — bun run gate:fast.
4. risk:audit — security-risk scan (all adapters) + secret misuse + slop + bun audit + OSV (skipped if only docs changed).
5. Unit tests — vitest run (skipped if only docs changed).
6. SBOM sync — when bun.lock / package.json changed.

Pre-push (~5–8 min) — production build + verifiers + tenant + SQLite integration

.githooks/pre-push runs:

Multi-adapter DB matrix, the full 9-shard E2E matrix and benchmarks remain CI-only. Pre-push runs the SQLite suite plus the path-mapped browser contracts, so a regression outside those paths still waits for CI. Docs-only pushes skip build + integration + browser + mutation.

Release preparation (opt-in). bun run git push --release (or --release=patch|minor|major) arms a post-gate step: once the nine checks pass, scripts/version.ts auto derives the next SemVer version from the Conventional Commits since the highest v* tag, writes it into package.json and the CycloneDX root component in sbom.json (so the two can never drift), commits them as chore(release): bump version to vX.Y.Z, and prints the push that publishes it. The flag is consumed by scripts/git-safe.ts (git never forwards hook arguments), which is why the hook reads SVELTY_RELEASE. The bump runs only behind a full green gate and never inside the triggering push — git resolves the pushed refs first — so the release commit stays local until you push again; re-running is a no-op within the same release cycle. Manual equivalent: bun run gate --release.

The manifest/SBOM lockstep is asserted read-only by bun run version:verify, which runs inside bun run check (so the pre-push Quality Gate and CI 03-check both fail on drift) and again in the release workflow before anything is tagged.

bun run gate                               # pre-push gate (build + verifiers + CI unit parity + tenant + SQLite + E2E + mutation)
bun run gate --release                     # …then bump + commit the next SemVer version
bun run prepush                            # same as gate
bun run git push --release origin HEAD:next HEAD:main   # gate + release, one command
bun run version:bump --dry-run             # preview the derived version, write nothing
bun run version:verify                      # package.json ↔ sbom.json consistency (read-only)
bun test --timeout 300000 tests/integration/   # Integration only (needs build/)
bun run test:doctor                        # unit + SQLite integration + gate map
bun run risk:audit                         # same scanners as pre-commit step 4

Automated release (CI) — the GitHub Release + npm

auto-release.yaml listens for a successful CI run on main (plus push of a v* tag and manual dispatch). On success it tags exactly the version package.json carries and creates the GitHub Release with generated notes. Hardening added for enterprise predictability:

• Pre-flight bun run version:verify — the release refuses to run when the manifest and SBOM disagree.
• Post-flight verification — the job fails loudly if the tag was not pushed or the GitHub Release was not created (a “successful” job with no artifacts is the failure mode the guard exists for).
• npm is best-effort and honest — a missing NPM_TOKEN is a visible ::warning::, a token npm rejects is a visible ::error::; neither can swallow the GitHub Release (which is created first).
• Escape hatch — because every release is gated on a fully green main CI, a single persistent failure blocks releases. Actions → Auto Release → Run workflow bypasses the gate (workflow_dispatch), accepting an exact version or a bump strategy.

Branching Strategy

We have two primary, long-lived branches: main and next.

main Branch (Production)

• Purpose: Production-ready, stable code. This branch represents the latest official release.
• Protection: Protected branch requiring pull request reviews.
• Automated Actions:
  • Runs full Playwright + Vitest test suite.
  • Tag-driven releases: pushing a v* tag triggers npm publish + GitHub Release with auto-generated notes from commits.
• Version source: Git tags, not package.json.

next Branch (Development)

• Purpose: Development and staging. This is the primary branch for all new features.
• Automated Actions:
  • ✅ Runs full test suite on every push.
  • ✅ Tests across multiple databases (MongoDB, PostgreSQL, MariaDB).
  • ✅ No automatic releases (tests only).

Commit Message Convention

Our automated release process depends on a strict commit message format. We use the Conventional Commits specification.

Commit Message Model (Conventional Commits + TQA)

We follow an enhanced Conventional Commits specification to maintain a clear Technical Ledger.

Format:

<type>(<scope>): <subject> [TQA-Verified]

Types:

• tqa - Resilience & Integrity: Adding chaos tests, state-machine audits, or GDPR verification.
• perf - Throughput & Latency: Memory leak fixes, JIT optimizations, and benchmark improvements.
• feat - Feature: New functionality.
• fix - Stability: Bug fixes.
• refactor - Clean Code: Internal restructuring without behavior changes.

Mandatory Scopes:

• resilience: For any changes to circuit breakers or failover logic.
• temporal: For timezone/date normalization changes.
• concurrency: For locking and atomic transaction changes.
• ledger: For documentation and benchmark result updates.

Automated Testing Architecture

🧪 Vitest Unit Tests

• Speed: ⚡ Fast feedback on every commit (full suite via pre-commit).
• Location: tests/unit/
• Runner: Vitest with jsdom for components, stores, services, and API logic.
• Command: bun run test:unit · focused security: bun run test:security

🔗 Contract Tests (Adapter Parity)

• Purpose: Identical assertions run against all 4 databases (SQLite, MongoDB, PostgreSQL, MariaDB).
• Location: tests/integration/databases/contract.test.ts
• Contracts: Adapter, Auth, Permission, Setup Gating, Resilience.
• Command: bun run test:integration

🎭 Playwright Tests (E2E)

• Purpose: Browser automation for critical user journeys.
• Standard: Always point to 127.0.0.1:4173 via TEST_MODE=true.
• Location: tests/e2e/

🧠 Smart Test Orchestrator

• Purpose: Reads git diff and selects required test suites. Unknown changes fail closed.
• Command: bun run test:smart

🔍 AI Slop Scanner

• Purpose: Detects unsafe {@html}, legacy Svelte 4 patterns, missing ARIA, RTL violations, dead exports.
• Command: bun run slop

Unused-export findings are split into two info buckets: dead-code candidates (referenced nowhere in src/scripts/root/tests/docs — actionable) and export-surface (test-only helpers + documented public API — a tracked inventory, not dead code). A third advisory bucket, duplicate-export-name, flags the same distinctive export name in several modules — usually a legitimate re-export bridge or SvelteKit remote/server contract symmetry, occasionally a real collision. All advisory buckets are summarised as counts by default and listed with bun run scripts/security/slop-scanner.ts --surface.

Tiered Local Testing Strategy

SveltyCMS uses a three-tier testing strategy that balances developer velocity with full CI parity. Each tier corresponds to a different Git lifecycle event:

Tier 1: Pre-Commit (.githooks/pre-commit) — Fast Feedback

Runs automatically on every git commit. Target: ~40–60 seconds (full unit suite + risk audit; skipped if only docs changed).

Tier 2: Pre-Push (.githooks/pre-push) — Production Build + Integration

Runs automatically on every git push. Catches build and integration failures before they reach CI.

Multi-adapter DB integration + E2E + benchmarks are CI-only.

Manual equivalent: bun run prepush / bun run gate (via hardened git wrapper).

Tier 3: Full CI Parity — CI Pipeline

CI runs the complete matrix automatically on every PR/push to next. Covers what local hooks skip:

• Whitebox: format + lint + type check + secret scan + deploy backdoor probe + hardware tier probe (real cgroup limits)
• Build: COMPILE_ALL_ADAPTERS=true production build
• DB tests: Full multi-adapter matrix (MongoDB, PostgreSQL, MariaDB, SQLite)
• E2E: Playwright prep + 6 shards (chromium)
• Benchmarks: Performance regression detection

All local test commands must use config/private.test.ts only — they must not rename, overwrite, or connect through the developer’s config/private.ts (live user data). Isolation is env + policy (private-config-policy.ts), not backup/restore of live config.

Prerequisites for local integration tests: Docker Desktop with MongoDB (27017), MariaDB (3306), and PostgreSQL (5432) on 127.0.0.1.

Scripts Audit

All scripts in scripts/ and their role in the testing pipeline:

Core Scripts (Testing Pipeline)

Utility Scripts

Best Practices

Commit Workflow

1. Stage changes: git add .
2. Commit: git commit -m "feat(auth): add OAuth2 support" — pre-commit hook runs (DB safety → format+lint → lint-staged → unit tests).
3. Push: bun run git push origin feat/my-feature — pre-push hook runs (production build → bun test tests/integration/).
4. Before PR: Ensure CI passes — local hooks already guarantee the same gate.

Manual Verification

If you want to run checks outside the hook lifecycle:

# Pre-commit gate manually
bun run precommit

# Pre-push gate manually
bun run gate
# or: bun run prepush

# Unit + SQLite integration + gate map
bun run test:doctor

# Integration tests (SQLite; needs build/)
bun test --timeout 300000 tests/integration/

# Smart Test Orchestrator — auto-detects what to test from git diff
bun run test:smart

# AI Slop Scanner — detect code smells
bun run slop

Security & Slop Regression Check

For changes touching auth, middleware, or API routes, also run:

bun run test:security
bun run slop

Troubleshooting

“Permission Denied” on Git Hook

If you are on Linux/macOS and the hook fails to execute:

chmod +x .githooks/pre-commit .githooks/pre-push

“Database connection failed” in Tests

Ensure you are using 127.0.0.1 in your config/private.test.ts and that the test database is accessible.

Bypassing Hooks

bun run git commit and bun run git push block --no-verify. Bypassing requires invoking the system Git binary directly — a deliberate act, not muscle memory. CI will reject the same failures the hooks catch.

Docker DB Not Reachable During Pre-Push

If the pre-push hook or local CI reports postgresql is not reachable at 127.0.0.1:5432:

docker compose -f tests/docker-compose.yml --profile postgresql up -d
docker compose -f tests/docker-compose.yml --profile mariadb up -d
docker compose -f tests/docker-compose.yml --profile mongodb up -d

Credentials must match src/utils/test-db-credentials.ts (image defaults: postgres/postgres, root/mariadb, mongo no-auth).

Related Documentation

• Test Status Report
• API Testing
• Testing Strategy