stemedb/.claude/guides/local/quality-checks.md

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
• Go toolchain (for SDK work)
• goimports: go install golang.org/x/tools/cmd/goimports@latest
• golangci-lint (optional): go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Quick Start

# Run all quality checks (same as CI)
make quality

# Auto-fix formatting (Rust)
make fmt

# Auto-fix formatting (Go)
make go-fmt

# See clippy errors
make lint

# Lint Go SDK
make go-lint

Pre-commit Hook (v2)

The pre-commit hook at .git/hooks/pre-commit uses a two-phase approach:

Phase 1: Auto-fix

• Runs formatters (cargo fmt, gofmt, goimports)
• Re-stages formatted files automatically
• Transparent to the developer

Phase 2: Verify

• Checks formatting (should pass after phase 1)
• Runs linters (cargo clippy, go vet, golangci-lint)
• Checks file length (max 500 lines)
• Blocks commit if any check fails

Languages Supported

Language	Format	Lint	File Length
Rust	cargo fmt	cargo clippy	✅
Go	gofmt + goimports	go vet + golangci-lint	✅

Smart Detection

• Only checks staged files (fast feedback)
• Auto-detects Go modules (walks up to find go.mod)
• Skips checks if no Rust/Go files are staged
• Re-stages files after formatting

Installing the Hook

The hook should already exist. If not:

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

Rust

Check	Command	What it catches
Format	cargo fmt --check	Inconsistent formatting
Lint	cargo clippy -- -D warnings	Code smells, potential bugs
Duplication	jscpd (CI only)	Copy-pasted code blocks
Tests	cargo test (CI only)	Broken functionality

Go (SDK)

Check	Command	What it catches
Format	gofmt -l	Inconsistent formatting
Imports	goimports	Unorganized imports
Vet	go vet ./...	Suspicious constructs
Lint	golangci-lint run	Code quality issues

Universal

Check	Threshold	What it catches
File length	500 lines max	Files too large to reason about

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 Rust
make go-fmt  # Auto-fix Go
git add -u  # Re-stage (hook does this automatically)

"Clippy warnings treated as errors"

Fix the warnings. Common ones:

// Bad: unused variable
let x = 5;

// Good: prefix with underscore
let _x = 5;

"go vet failed"

Check for suspicious constructs:

cd sdk/go/steme && go vet ./...

"File too long"

Split into smaller modules. Keep files under 500 lines for maintainability.

"Duplication detected"

Refactor the duplicated code into a shared function or module.

CI/Local Parity

The pre-commit hook runs a subset of what CI runs (format, lint, file length). Full CI also runs:

• Tests (cargo test, go test)
• Duplication detection (jscpd)
• Security audit (cargo audit)

Performance

Target: <10 seconds on staged files

Scenario	Time
No Rust/Go files staged	<0.2s
Go files only (warm)	<2s
Rust files only (warm)	<3s
Both (warm)	<5s
Cold compile	~11s

Related

• Testing Guide - Running tests
• Rust Guidelines - Code standards