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):**
```bash
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):**
```bash
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:**
```bash
# 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**
   ```bash
   git checkout -b feature/my-feature
   ```

2. **Make Changes**
   - Write code
   - Add tests
   - Update documentation

3. **Check Quality**
   ```bash
   # Check compilation and warnings
   cargo check --workspace

   # Run tests
   cargo test --workspace --lib

   # Format code
   cargo fmt --all
   ```

4. **Commit Changes**
   ```bash
   git add .
   git commit -m "feat: add new feature"
   # Pre-commit hook runs automatically
   ```

5. **Push to Remote**
   ```bash
   git push origin feature/my-feature
   # Pre-push hook runs automatically
   ```

### Fixing Warning Regressions

If your commit is blocked due to warnings:

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

```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
   ```bash
   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.