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:** 302 warnings (target: <50)

**Priority Warning Types:**
1. **unused_imports** - Clean up unused imports immediately
2. **missing_debug_implementations** - Add `#[derive(Debug)]` where possible
3. **non_snake_case** - Rename fields to follow Rust naming conventions
4. **missing_docs** - Add documentation for public items

**Quick Fix Commands:**
```bash
# Check specific warning types
cargo clippy --workspace -- -W unused-imports

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

# Check warning count
cargo check --workspace 2>&1 | grep "warning:" | wc -l
```

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

**Current Threshold:** 50 warnings
**Current Count:** 302 warnings

**Goal:** Reduce warnings to under threshold through incremental improvements.

**Strategy:**
1. **Wave 19 (Current):** Set up enforcement infrastructure (hooks)
2. **Wave 20:** Fix unused imports and missing Debug implementations
3. **Wave 21:** Address non_snake_case and missing documentation
4. **Wave 22:** Final cleanup and threshold reduction to 25

**Monitoring:**
```bash
# Quick warning count
make check-warnings  # If you add this to Makefile

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

## Continuous Integration

When CI is set up, these same checks will run automatically:
- Compilation verification
- Warning count threshold
- Test suite execution
- Code formatting checks
- Security audits

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