foxhunt/DEVELOPMENT.md

Development Guide

Overview

This guide provides essential information for developing the Foxhunt HFT Trading System. Follow these practices to maintain code quality and system reliability.

Git Hooks

This project uses automated git hooks to maintain code quality and prevent regressions.

Pre-Commit Hook

Location: .git/hooks/pre-commit

Purpose: Prevents commits that would degrade code quality

Checks Performed:

1. Compilation Verification - Blocks commits with compilation errors
2. Warning Count Threshold - Blocks commits if warnings exceed 50
3. Code Quality Checks - Warns about common issues:
   • .unwrap() usage (suggests using ? operator)
   • .expect() with empty messages
   • TODO/FIXME comment counts

Example Output:

🔍 Running pre-commit quality checks...

📋 Checking compilation...
✅ Compilation check passed

📊 Checking warning count...
✅ Warning count acceptable (43/50)

🔎 Checking for common issues...
✅ All pre-commit checks passed!

Bypassing (Emergency Only):

git commit --no-verify

Warning: Only use this for genuine emergencies. Bypassing the hook can introduce technical debt.

Pre-Push Hook

Location: .git/hooks/pre-push

Purpose: Ensures code changes are properly tested before pushing

Checks Performed:

1. Test Suite Execution - Runs workspace tests (excluding integration tests)
2. Compilation Verification - For main/master branch pushes
3. Uncommitted Changes Detection - Warns about uncommitted files

Example Output:

🔍 Running pre-push checks...

📌 Pushing to main - running full quality checks

📋 Verifying compilation...
✅ Compilation verified

🧪 Running test suite...
   (Skipping integration tests: redis, kill_switch)

✅ All tests passed!

Bypassing (Emergency Only):

git push --no-verify

Code Quality Standards

Warning Management

Current Status: ~8 warnings (library code) - target: 0 warnings (Wave 149) CI Enforcement: ✅ ACTIVE - builds fail on any warnings (RUSTFLAGS="-D warnings")

Zero-Tolerance Policy:

• All code must compile without warnings
• CI configured with RUSTFLAGS="-D warnings" in 5 workflows
• Git hooks enforce warning threshold (50 warnings pre-commit)
• Target: Reduce to 0 warnings by end of Wave 149

CI Workflows with Warning Enforcement:

1. ci.yml - Zero Error Tolerance Check
2. aggressive-linting.yml - Comprehensive linting
3. compilation-guard.yml - Compilation enforcement
4. dependency-guardian.yml - Dependency validation
5. financial-security-audit.yml - Security audits

Quick Fix Commands:

# Check warnings with CI enforcement (same as CI)
RUSTFLAGS="-D warnings" cargo check --workspace --lib

# Auto-fix some warnings
cargo fix --workspace --allow-dirty

# Check specific warning types
cargo clippy --workspace -- -W unused-imports

# Check warning count (library only)
cargo check --workspace --lib 2>&1 | grep "warning:" | wc -l

Troubleshooting CI Failures: If CI fails with "COMPILATION FAILED - BLOCKING MERGE":

1. Run locally: RUSTFLAGS="-D warnings" cargo check --workspace --all-targets
2. Fix all warnings/errors shown
3. Verify: cargo check --workspace --lib shows 0 warnings
4. Commit and push - CI should pass

Best Practices

1. Error Handling

   • ❌ Avoid: .unwrap() and .expect("")
   • ✅ Use: ? operator, proper error types, descriptive error messages

2. Code Documentation

   • Add doc comments for public functions, structs, and modules
   • Include examples in doc comments for complex functionality

3. Testing

   • Write unit tests for new functionality
   • Update integration tests when changing service interfaces
   • Run tests before pushing: cargo test --workspace --lib

4. Performance Considerations

   • This is an HFT system - every nanosecond matters
   • Profile changes that affect hot paths
   • Use #[inline] judiciously for critical functions

Development Workflow

Standard Workflow

1. Create Feature Branch

   git checkout -b feature/my-feature
   

2. Make Changes

   • Write code
   • Add tests
   • Update documentation

3. Check Quality

   # Check compilation and warnings
   cargo check --workspace
   
   # Run tests
   cargo test --workspace --lib
   
   # Format code
   cargo fmt --all
   

4. Commit Changes

   git add .
   git commit -m "feat: add new feature"
   # Pre-commit hook runs automatically
   

5. Push to Remote

   git push origin feature/my-feature
   # Pre-push hook runs automatically
   

Fixing Warning Regressions

If your commit is blocked due to warnings:

# See all warnings
cargo check --workspace 2>&1 | grep "warning:"

# Count warnings by type
cargo check --workspace 2>&1 | grep "warning:" | sort | uniq -c | sort -rn

# Fix a specific file
cargo fix --bin trading-service --allow-dirty

Hook Maintenance

If you need to update the hooks:

# Edit hooks
vim .git/hooks/pre-commit
vim .git/hooks/pre-push

# Make executable (if needed)
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push

# Test hooks
.git/hooks/pre-commit
.git/hooks/pre-push

Warning Threshold Policy

Git Hook Threshold: 50 warnings (pre-commit enforcement) CI Threshold: 0 warnings (zero-tolerance, builds fail on any warning) Current Count: ~8 warnings (library code only)

Goal: ✅ NEARLY ACHIEVED - down from 2484 warnings (Wave 135-149)

Strategy (COMPLETED):

1. ✅ Wave 135: Set up enforcement infrastructure (hooks)
2. ✅ Wave 148: Mass warning elimination (2484 → ~8)
3. ✅ Wave 149: CI hardening verification
4. 🔄 Next: Final cleanup to 0 warnings

Monitoring:

# Quick warning count (matches CI)
RUSTFLAGS="-D warnings" cargo check --workspace --lib

# Or with grep
cargo check --workspace --lib 2>&1 | grep "warning:" | wc -l

# Check what CI will see
RUSTFLAGS="-D warnings" cargo check --workspace --all-targets

Warning Accumulation Prevention:

• CI enforces -D warnings (5 workflows)
• Git pre-commit hook blocks commits >50 warnings
• All warnings treated as errors in CI
• Result: Future warning accumulation impossible

Continuous Integration

✅ CI is ACTIVE with strict enforcement:

• Compilation verification - Zero-tolerance (RUSTFLAGS="-D warnings")
• Warning count threshold - 0 warnings required (fails on any warning)
• Test suite execution - Full workspace testing
• Code formatting checks - cargo fmt --all -- --check
• Security audits - cargo audit, cargo deny
• Clippy linting - All lint groups (all, pedantic, nursery, cargo)

CI Failure Debugging:

# Reproduce CI failure locally
RUSTFLAGS="-D warnings" cargo check --workspace --all-targets

# If build fails, warnings are treated as errors
# Fix all warnings, then re-run to verify

Getting Help

• Architecture Questions: See CLAUDE.md for system design
• Configuration: See config/ crate and PostgreSQL schemas
• Testing: See tests/ directory for examples
• Performance: See docs/performance.md (if exists)

Emergency Procedures

If you absolutely must bypass the hooks:

1. Understand the Risk: You're introducing technical debt
2. Document Why: Add a TODO comment explaining the bypass
3. Create a Ticket: Track the issue for future resolution
4. Use --no-verify Sparingly:

   git commit --no-verify -m "emergency: fix production issue"
   

Version History

• 2025-10-01: Initial development guide with git hooks
• 2025-09-27: Project reached compilation success milestone
• Earlier: Extensive ML models and service architecture implemented

---

Remember: These hooks exist to prevent regressions and maintain code quality. They're your friends, not obstacles.