jordan 3cfaa1e1d3 feat: Complete Phase 1 (The Spine) - storage foundation

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>

2026-01-31 14:15:34 -07:00

2.5 KiB

Raw Blame History

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

# 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:

Checks if any Rust files are staged
Runs make quality (format check, clippy, duplication, tests)
Blocks commit if any check fails

Installing the Hook

The hook should already exist. If not:

# 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)

# 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"

make fmt  # Auto-fix
git add -u  # Re-stage fixed files

"Clippy warnings treated as errors"

Fix the warnings. Common ones:

// 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.

Testing Guide - Running tests
Rust Guidelines - Code standards

2.5 KiB Raw Blame History