#!/bin/bash
# Wave 113 Clippy Fix Action Plan
# Based on Agent 10 analysis of 4,909 warnings
# DO NOT run automatically - this is a guide for manual fixes

set -e

echo "========================================="
echo "WAVE 113 CLIPPY FIX ACTION PLAN"
echo "========================================="
echo ""
echo "⚠️  WARNING: This script is a GUIDE only"
echo "⚠️  Review each change before applying"
echo ""

# Phase 1: Safety Comments (Priority 1 - 3-4 hours)
echo "PHASE 1: Add Safety Comments to Unsafe Blocks"
echo "----------------------------------------------"
echo "Files to fix:"
echo "  - trading_engine/src/affinity.rs (4 blocks)"
echo "  - trading_engine/src/lockfree/mpsc_queue.rs (5 blocks)"
echo "  - trading_engine/src/lockfree/ring_buffer.rs (3 blocks)"
echo "  - trading_engine/src/lockfree/small_batch_ring.rs (7 blocks)"
echo ""
echo "Template:"
echo "  // SAFETY: [Explain invariants here]"
echo "  //   - Why the unsafe operation is sound"
echo "  //   - What invariants are maintained"
echo "  //   - References to external documentation if applicable"
echo "  unsafe { ... }"
echo ""
echo "Example commands:"
echo "  # Find all unsafe blocks"
echo "  rg 'unsafe \{' --type rust"
echo ""
echo "  # Check specific file"
echo "  rg 'unsafe \{' trading_engine/src/affinity.rs"
echo ""

# Phase 2: Fix Unwrap Usage (Priority 1 - 30 minutes)
echo "PHASE 2: Fix unwrap_used (6 instances)"
echo "---------------------------------------"
echo "Strategy: Replace .unwrap() with proper error handling"
echo ""
echo "Find locations:"
echo "  rg '\.unwrap\(\)' --type rust | grep -v test | grep -v '//' | head -10"
echo ""
echo "Fix pattern:"
echo "  # Before:"
echo "  let value = result.unwrap();"
echo ""
echo "  # After (in functions returning Result):"
echo "  let value = result?;"
echo ""
echo "  # After (with context):"
echo "  let value = result.expect(\"meaningful error message\");"
echo ""

# Phase 3: Audit Indexing (Priority 2 - 2-3 hours)
echo "PHASE 3: Audit Indexing Operations (286 instances)"
echo "---------------------------------------------------"
echo "Top files:"
echo "  1. adaptive-strategy/src/regime/mod.rs"
echo "  2. adaptive-strategy/src/microstructure/mod.rs"
echo "  3. adaptive-strategy/src/models/tlob_model.rs"
echo ""
echo "Strategy:"
echo "  1. For non-critical paths: Use .get() with error handling"
echo "  2. For hot paths: Keep indexing but add debug_assert!"
echo ""
echo "Find indexing:"
echo "  rg '\[.*\]' adaptive-strategy/src/regime/mod.rs | head -20"
echo ""
echo "Fix pattern (safe):"
echo "  # Before:"
echo "  let val = arr[idx];"
echo ""
echo "  # After (with error):"
echo "  let val = arr.get(idx).ok_or(\"index out of bounds\")?;"
echo ""
echo "Fix pattern (hot path):"
echo "  # Before:"
echo "  let val = arr[idx];"
echo ""
echo "  # After (with assertion):"
echo "  debug_assert!(idx < arr.len(), \"index {idx} out of bounds\");"
echo "  let val = arr[idx];"
echo ""

# Phase 4: Type Conversions (Priority 2 - 4-6 hours)
echo "PHASE 4: Fix Dangerous Type Conversions (588 instances)"
echo "--------------------------------------------------------"
echo "Common patterns to fix:"
echo ""
echo "Pattern 1: Integer to Float (precision loss)"
echo "  # Before:"
echo "  let ratio = count as f64 / total as f64;"
echo ""
echo "  # After:"
echo "  let ratio = f64::from(count) / f64::from(total);"
echo ""
echo "Pattern 2: u64 to i64 (wrap risk)"
echo "  # Before:"
echo "  let signed = unsigned as i64;"
echo ""
echo "  # After:"
echo "  let signed = i64::try_from(unsigned)"
echo "    .map_err(|_| \"value too large for i64\")?;"
echo ""
echo "Pattern 3: usize to u32 (truncation on 64-bit)"
echo "  # Before:"
echo "  let size = len as u32;"
echo ""
echo "  # After:"
echo "  let size = u32::try_from(len)"
echo "    .map_err(|_| \"size exceeds u32::MAX\")?;"
echo ""
echo "Find all 'as' conversions:"
echo "  rg ' as (f64|i64|u32|u64|usize)' --type rust | head -20"
echo ""

# Phase 5: Arithmetic Overflow (Priority 2 - 2-3 hours)
echo "PHASE 5: Add Overflow Checks (565 instances)"
echo "---------------------------------------------"
echo ""
echo "Pattern 1: Price calculations (critical)"
echo "  # Before:"
echo "  let total_price = price * quantity;"
echo ""
echo "  # After:"
echo "  let total_price = price.checked_mul(quantity)"
echo "    .ok_or(\"price calculation overflow\")?;"
echo ""
echo "Pattern 2: Position sizing (use saturating)"
echo "  # Before:"
echo "  let position = base_size * leverage;"
echo ""
echo "  # After:"
echo "  let position = base_size.saturating_mul(leverage);"
echo ""
echo "Pattern 3: Benchmarks (allow overflow)"
echo "  # Add to benchmark functions:"
echo "  #[allow(clippy::arithmetic_side_effects)]"
echo "  fn benchmark_function() { ... }"
echo ""
echo "Find arithmetic operations:"
echo "  rg '(\+|\-|\*|/) ' trading_engine/src/ --type rust | grep -v '//' | head -20"
echo ""

# Phase 6: Documentation (Priority 3 - 3-4 hours)
echo "PHASE 6: Fix Documentation (895 missing backticks)"
echo "---------------------------------------------------"
echo ""
echo "Pattern: Add backticks to code items in docs"
echo "  # Before:"
echo "  /// Returns the Result with error details"
echo ""
echo "  # After:"
echo "  /// Returns the \`Result\` with error details"
echo ""
echo "Common items needing backticks:"
echo "  - Type names: Result, Option, Vec, HashMap"
echo "  - Method names: get(), insert(), unwrap()"
echo "  - Variable names: core_id, buffer_size"
echo "  - Constants: MAX_SIZE, DEFAULT_TIMEOUT"
echo ""
echo "Find docs needing backticks:"
echo "  rg '/// .*[A-Z][a-z]+.*[A-Z]' --type rust | grep -v '\`' | head -20"
echo ""

# Phase 7: Remove Unnecessary Results (Priority 3 - 1-2 hours)
echo "PHASE 7: Remove Unnecessary Result Wraps (78 functions)"
echo "--------------------------------------------------------"
echo ""
echo "Identify candidates:"
echo "  # Functions that:"
echo "  - Always return Ok(value)"
echo "  - Never use the ? operator"
echo "  - Have no error path"
echo ""
echo "Fix pattern:"
echo "  # Before:"
echo "  fn get_value() -> Result<u32, Error> {"
echo "    Ok(42)"
echo "  }"
echo ""
echo "  # After:"
echo "  fn get_value() -> u32 {"
echo "    42"
echo "  }"
echo ""
echo "Find potential candidates:"
echo "  rg 'fn .*-> Result' --type rust -A 5 | rg 'Ok\(' | head -20"
echo ""

# Summary and Next Steps
echo "========================================="
echo "EXECUTION PLAN"
echo "========================================="
echo ""
echo "Week 1 (Wave 113 Part 1):"
echo "  [ ] Phase 1: Safety comments (3-4 hours)"
echo "  [ ] Phase 2: Fix unwrap_used (30 mins)"
echo "  [ ] Phase 3: Audit indexing (2-3 hours)"
echo ""
echo "Week 2 (Wave 113 Part 2):"
echo "  [ ] Phase 4: Type conversions (4-6 hours)"
echo "  [ ] Phase 5: Arithmetic overflow (2-3 hours)"
echo ""
echo "Week 3 (Wave 114):"
echo "  [ ] Phase 6: Documentation (3-4 hours)"
echo "  [ ] Phase 7: Remove unnecessary Results (1-2 hours)"
echo ""
echo "Total estimated effort: 15-24 hours"
echo ""
echo "========================================="
echo "TOOLS & COMMANDS"
echo "========================================="
echo ""
echo "Check progress:"
echo "  cargo clippy --workspace --lib --bins -- -W clippy::all 2>&1 | wc -l"
echo ""
echo "Check specific category:"
echo "  cargo clippy -- -W clippy::unsafe_code 2>&1"
echo "  cargo clippy -- -W clippy::indexing_slicing 2>&1"
echo "  cargo clippy -- -W clippy::as_conversions 2>&1"
echo ""
echo "Test after changes:"
echo "  cargo test --workspace"
echo "  cargo clippy --workspace --all-targets"
echo ""
echo "Commit strategy:"
echo "  git commit -m 'fix(clippy): add safety comments to unsafe blocks'"
echo "  git commit -m 'fix(clippy): replace unwrap with proper error handling'"
echo "  git commit -m 'fix(clippy): add bounds checks to indexing operations'"
echo ""
echo "========================================="
echo "REFERENCES"
echo "========================================="
echo ""
echo "Detailed Analysis:"
echo "  - WAVE112_AGENT10_CLIPPY_REPORT.md"
echo "  - WAVE112_AGENT10_WARNING_BREAKDOWN.txt"
echo "  - WAVE112_AGENT10_SUMMARY.txt"
echo ""
echo "Raw Data:"
echo "  - clippy_full_output.txt (4909 warnings)"
echo ""
echo "Scripts:"
echo "  - analyze_clippy_warnings.py (re-run analysis)"
echo ""
echo "========================================="
echo ""
echo "✅ Review this plan before starting"
echo "✅ Fix compilation errors first (767 test errors block full analysis)"
echo "✅ Make incremental commits for each phase"
echo "✅ Run tests after each significant change"
echo ""
echo "Next: Start with Phase 1 (safety comments) - lowest risk, highest value"