3cfaa1e1d3
Phase 1 delivers the complete durability and storage layer:
- WAL with crash recovery: Append-only journal with BLAKE3 checksums,
fsync guarantees, and proper seek-to-EOF on reopen
- Storage engine: sled-backed KVStore with scan_prefix for range queries
- Content-addressed storage: H:{hash}, V:{hash}, E:{hash} key patterns
- Ingestor: Background worker tailing WAL, writing to KV with 8-byte
aligned record headers for rkyv zero-copy deserialization
- Comprehensive tests: 31 tests covering crash recovery, round-trips,
and multi-cycle durability
New crates: stemedb-wal, stemedb-storage, stemedb-ingest
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
107 lines
2.5 KiB
Markdown
107 lines
2.5 KiB
Markdown
# Quality Checks & Pre-commit Hooks
|
|
|
|
**When to use:** Setting up your dev environment, understanding CI/local parity, or debugging pre-commit failures.
|
|
|
|
## Prerequisites
|
|
|
|
- Rust toolchain installed (`rustup`)
|
|
- `jscpd` for duplication checks: `npm install -g jscpd`
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Run all quality checks (same as CI)
|
|
make quality
|
|
|
|
# Auto-fix formatting
|
|
make fmt
|
|
|
|
# See clippy errors
|
|
make lint
|
|
```
|
|
|
|
## Pre-commit Hook
|
|
|
|
The pre-commit hook at `.git/hooks/pre-commit` runs automatically on every commit. It:
|
|
|
|
1. Checks if any Rust files are staged
|
|
2. Runs `make quality` (format check, clippy, duplication, tests)
|
|
3. Blocks commit if any check fails
|
|
|
|
### Installing the Hook
|
|
|
|
The hook should already exist. If not:
|
|
|
|
```bash
|
|
# Copy the sample and make executable
|
|
cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
|
|
chmod +x .git/hooks/pre-commit
|
|
```
|
|
|
|
### Bypassing (Emergency Only)
|
|
|
|
```bash
|
|
# Skip pre-commit hook (logged, use sparingly)
|
|
git commit --no-verify -m "emergency fix"
|
|
```
|
|
|
|
## What Gets Checked
|
|
|
|
| Check | Command | What it catches |
|
|
|-------|---------|-----------------|
|
|
| Format | `cargo fmt --check` | Inconsistent formatting |
|
|
| Lint | `cargo clippy -- -D warnings` | Code smells, potential bugs |
|
|
| Duplication | `jscpd` | Copy-pasted code blocks |
|
|
| Tests | `cargo test` | Broken functionality |
|
|
|
|
## Enforced Lints
|
|
|
|
These are set to `deny` in `Cargo.toml` (CI will fail):
|
|
|
|
| Lint | Why |
|
|
|------|-----|
|
|
| `clippy::unwrap_used` | Panics are forbidden in production code |
|
|
| `clippy::expect_used` | Panics are forbidden in production code |
|
|
| `clippy::panic` | Explicit panics are forbidden in production code |
|
|
|
|
**Tests are exempt** via `clippy.toml`:
|
|
- `allow-unwrap-in-tests = true`
|
|
- `allow-expect-in-tests = true`
|
|
- `allow-panic-in-tests = true`
|
|
|
|
To add a new enforced lint, update `[workspace.lints.clippy]` in root `Cargo.toml`.
|
|
|
|
## Troubleshooting
|
|
|
|
### "Format check failed"
|
|
|
|
```bash
|
|
make fmt # Auto-fix
|
|
git add -u # Re-stage fixed files
|
|
```
|
|
|
|
### "Clippy warnings treated as errors"
|
|
|
|
Fix the warnings. Common ones:
|
|
|
|
```rust
|
|
// Bad: unused variable
|
|
let x = 5;
|
|
|
|
// Good: prefix with underscore
|
|
let _x = 5;
|
|
```
|
|
|
|
### "Duplication detected"
|
|
|
|
Refactor the duplicated code into a shared function or module.
|
|
|
|
## CI/Local Parity
|
|
|
|
The pre-commit hook runs `make quality`, which is the **exact same** command CI runs. If it passes locally, it passes in CI.
|
|
|
|
## Related
|
|
|
|
- [Testing Guide](./testing.md) - Running tests
|
|
- [Rust Guidelines](../backend/rust-guidelines.md) - Code standards
|