feat: Add state variable packing detection rule

FILE_STRUCTURE_GUIDE.md

@@ -0,0 +1,318 @@
+# 📂 State Variable Packing Detection - File Structure Overview
+
+## 📍 Implementation Location
+
+```
+/workspaces/GasGuard/
+├── packages/rules/src/
+│   ├── optimization/                          # NEW: Optimization module
+│   │   ├── mod.rs                            # Module exports
+│   │   ├── README.md                         # Implementation guide
+│   │   └── storage/                          # Storage optimization rules
+│   │       ├── mod.rs                        # Storage module exports
+│   │       ├── state_variable_packing.rs     # Core detection logic ⭐
+│   │       └── state_variable_packing.tests.rs # Test suite
+│   │
+│   ├── solidity/
+│   │   ├── mod.rs                            # MODIFIED: Updated exports
+│   │   └── state_variable_packing.rs         # NEW: Solidity rule ⭐
+│   │
+│   └── lib.rs                                # MODIFIED: Added optimization exports
+│
+└── docs/
+    ├── STATE_VARIABLE_PACKING.md             # NEW: Core documentation ⭐
+    ├── STATE_VARIABLE_PACKING_INTEGRATION.md # NEW: Integration guide ⭐
+    └── STATE_VARIABLE_PACKING_REFACTORING.md # NEW: Refactoring examples ⭐
+
+PACKING_IMPLEMENTATION_SUMMARY.md             # NEW: This summary ⭐
+```
+
+## 📄 File Descriptions
+
+### Core Implementation Files
+
+#### 1. **state_variable_packing.rs** (Core Logic)
+**Location**: `packages/rules/src/optimization/storage/state_variable_packing.rs`
+**Size**: ~250 lines
+
+**Key Components**:
+- `VariableInfo` struct - State variable metadata
+- `PackingOpportunity` struct - Detected opportunity
+- `get_type_size()` - Size calculation for types
+- `is_packable_type()` - Packability check
+- `detect_packing_opportunities()` - Main detection algorithm
+- `find_consecutive_packable_groups()` - Variable grouping
+- Unit tests
+
+**Usage**:
+```rust
+use gasguard_rules::detect_packing_opportunities;
+```
+
+#### 2. **state_variable_packing.rs** (Solidity Rule)
+**Location**: `packages/rules/src/solidity/state_variable_packing.rs`
+**Size**: ~80 lines
+
+**Key Components**:
+- `StateVariablePackingRule` struct
+- Implements `Rule` trait
+- `analyze()` method for UnifiedAST
+- Integration with rule engine
+
+**Usage**:
+```rust
+use gasguard_rules::StateVariablePackingRule;
+```
+
+#### 3. **state_variable_packing.tests.rs** (Test Suite)
+**Location**: `packages/rules/src/optimization/storage/state_variable_packing.tests.rs`
+**Size**: ~300 lines
+
+**Test Coverage**:
+- 11 comprehensive tests
+- Type size validation
+- Packability checking
+- Packing scenarios
+- Edge cases
+
+**Run Tests**:
+```bash
+cargo test -p gasguard-rules state_variable_packing
+```
+
+### Module Files
+
+#### 4. **optimization/mod.rs**
+**Location**: `packages/rules/src/optimization/mod.rs`
+**Purpose**: Re-exports optimization module components
+
+#### 5. **storage/mod.rs**
+**Location**: `packages/rules/src/optimization/storage/mod.rs`
+**Purpose**: Re-exports storage optimization components
+
+### Documentation Files
+
+#### 6. **STATE_VARIABLE_PACKING.md** (Core Documentation)
+**Location**: `docs/STATE_VARIABLE_PACKING.md`
+**Size**: ~400 lines
+
+**Contents**:
+- Overview and motivation
+- Why storage optimization matters
+- Storage slot sizes reference table
+- Practical before/after examples
+- Detection algorithm explanation
+- Gas savings estimation
+- Best practices
+- Rule details and usage
+- Limitations and considerations
+- Future enhancements
+
+**Read when**: Understanding storage optimization fundamentals
+
+#### 7. **STATE_VARIABLE_PACKING_INTEGRATION.md** (Integration Guide)
+**Location**: `docs/STATE_VARIABLE_PACKING_INTEGRATION.md`
+**Size**: ~350 lines
+
+**Contents**:
+- Using detection engine directly
+- Integrating with rule engine
+- CLI usage examples
+- Custom analysis tool integration
+- Real-world token contract example
+- Step-by-step integration walkthrough
+- Common patterns
+- Performance benchmarks
+- Integration checklist
+- Example report formats
+
+**Read when**: Integrating packing detection into projects
+
+#### 8. **STATE_VARIABLE_PACKING_REFACTORING.md** (Refactoring Guide)
+**Location**: `docs/STATE_VARIABLE_PACKING_REFACTORING.md`
+**Size**: ~500 lines
+
+**Contents**:
+- Complete refactoring examples:
+  - Simple ERC20 contract
+  - NFT contract with flags
+  - DeFi protocol
+- Before/after comparisons
+- Gas improvement analysis
+- Migration strategies
+- Proxy pattern usage
+- Testing optimizations
+- Benchmarking results
+- Implementation checklist
+- Common mistakes to avoid
+
+**Read when**: Implementing optimizations in actual contracts
+
+#### 9. **optimization/README.md** (Implementation Details)
+**Location**: `packages/rules/src/optimization/README.md`
+**Size**: ~400 lines
+
+**Contents**:
+- Implementation structure diagram
+- Component descriptions
+- Core functions explanation
+- Usage examples (basic and complex)
+- Packing efficiency examples
+- How detection works (5 steps)
+- Performance characteristics
+- Configuration options
+- Future enhancements
+- Related documentation
+- Integration points
+- Notes and acceptance criteria
+
+**Read when**: Understanding implementation details
+
+#### 10. **PACKING_IMPLEMENTATION_SUMMARY.md** (Summary)
+**Location**: `/workspaces/GasGuard/PACKING_IMPLEMENTATION_SUMMARY.md`
+
+**Contents**:
+- Requirements checklist
+- Deliverables overview
+- Quick start guide
+- Feature list
+- Test results
+- Architecture overview
+- Files created/modified
+- Learning resources
+- Quality assurance info
+- Next steps
+
+**Read when**: Getting a complete overview of implementation
+
+### Modified Files
+
+#### 11. **lib.rs** (Exports)
+**Location**: `packages/rules/src/lib.rs`
+**Changes**:
+- Added `pub mod optimization`
+- Added `pub mod solidity`
+- Added optimization exports to public API
+- Exports: `detect_packing_opportunities`, `VariableInfo`, `PackingOpportunity`, etc.
+
+#### 12. **solidity/mod.rs** (Module Updates)
+**Location**: `packages/rules/src/solidity/mod.rs`
+**Changes**:
+- Added `pub mod state_variable_packing`
+- Added re-export of `StateVariablePackingRule`
+
+## 🎯 Quick Navigation
+
+### For Different User Types
+
+**📚 Researchers/Learners**:
+1. Start: [STATE_VARIABLE_PACKING.md](docs/STATE_VARIABLE_PACKING.md)
+2. Examples: [STATE_VARIABLE_PACKING_REFACTORING.md](docs/STATE_VARIABLE_PACKING_REFACTORING.md)
+3. Deep dive: [optimization/README.md](packages/rules/src/optimization/README.md)
+
+**👨‍💻 Developers**:
+1. Start: [optimization/README.md](packages/rules/src/optimization/README.md)
+2. Integration: [STATE_VARIABLE_PACKING_INTEGRATION.md](docs/STATE_VARIABLE_PACKING_INTEGRATION.md)
+3. Code: Review `state_variable_packing.rs` files
+4. Tests: [state_variable_packing.tests.rs](packages/rules/src/optimization/storage/state_variable_packing.tests.rs)
+
+**🚀 Smart Contract Engineers**:
+1. Start: [STATE_VARIABLE_PACKING_REFACTORING.md](docs/STATE_VARIABLE_PACKING_REFACTORING.md)
+2. Integration: [STATE_VARIABLE_PACKING_INTEGRATION.md](docs/STATE_VARIABLE_PACKING_INTEGRATION.md)
+3. Reference: [STATE_VARIABLE_PACKING.md](docs/STATE_VARIABLE_PACKING.md)
+
+**📊 Project Managers**:
+1. Start: [PACKING_IMPLEMENTATION_SUMMARY.md](PACKING_IMPLEMENTATION_SUMMARY.md)
+2. Examples: [STATE_VARIABLE_PACKING_REFACTORING.md](docs/STATE_VARIABLE_PACKING_REFACTORING.md) (Examples section)
+
+## 📊 File Statistics
+
+| Category | Files | Lines | Purpose |
+|----------|-------|-------|---------|
+| Core Logic | 2 | ~330 | Detection algorithms |
+| Tests | 1 | ~300 | Test coverage |
+| Modules | 3 | ~30 | Organization |
+| Docs | 4 | ~1,650 | Education & guidance |
+| Summary | 2 | ~200 | Overview |
+| **Total** | **12** | **~2,510** | Complete system |
+
+## 🔍 Content Mapping
+
+### Understanding "What" (Why Packing Matters)
+→ [STATE_VARIABLE_PACKING.md](docs/STATE_VARIABLE_PACKING.md) Section: "Why It Matters"
+
+### Understanding "How" (Algorithm Details)
+→ [optimization/README.md](packages/rules/src/optimization/README.md) Section: "How Detection Works"
+
+### Understanding "Examples" (Real-world cases)
+→ [STATE_VARIABLE_PACKING_REFACTORING.md](docs/STATE_VARIABLE_PACKING_REFACTORING.md) Section: "Complete Refactoring Examples"
+
+### Using the Code
+→ [STATE_VARIABLE_PACKING_INTEGRATION.md](docs/STATE_VARIABLE_PACKING_INTEGRATION.md) Section: "How to Use in Your Project"
+
+### Implementation Details
+→ [packages/rules/src/optimization/README.md](packages/rules/src/optimization/README.md) Section: "Key Components"
+
+### Testing
+→ [packages/rules/src/optimization/storage/state_variable_packing.tests.rs](packages/rules/src/optimization/storage/state_variable_packing.tests.rs)
+
+## ✅ Verification Checklist
+
+Use this to verify all files are in place:
+
+```bash
+# Navigate to workspace
+cd /workspaces/GasGuard
+
+# Check core implementation files
+[ -f packages/rules/src/optimization/mod.rs ] && echo "✓ optimization/mod.rs"
+[ -f packages/rules/src/optimization/README.md ] && echo "✓ optimization/README.md"
+[ -f packages/rules/src/optimization/storage/mod.rs ] && echo "✓ storage/mod.rs"
+[ -f packages/rules/src/optimization/storage/state_variable_packing.rs ] && echo "✓ state_variable_packing.rs (core)"
+[ -f packages/rules/src/optimization/storage/state_variable_packing.tests.rs ] && echo "✓ state_variable_packing.tests.rs"
+[ -f packages/rules/src/solidity/state_variable_packing.rs ] && echo "✓ state_variable_packing.rs (solidity)"
+
+# Check documentation
+[ -f docs/STATE_VARIABLE_PACKING.md ] && echo "✓ STATE_VARIABLE_PACKING.md"
+[ -f docs/STATE_VARIABLE_PACKING_INTEGRATION.md ] && echo "✓ STATE_VARIABLE_PACKING_INTEGRATION.md"
+[ -f docs/STATE_VARIABLE_PACKING_REFACTORING.md ] && echo "✓ STATE_VARIABLE_PACKING_REFACTORING.md"
+
+# Check summary
+[ -f PACKING_IMPLEMENTATION_SUMMARY.md ] && echo "✓ PACKING_IMPLEMENTATION_SUMMARY.md"
+```
+
+## 🔗 Cross-References
+
+### Documentation Internal Links
+- STATE_VARIABLE_PACKING.md
+  ↔ STATE_VARIABLE_PACKING_INTEGRATION.md
+  ↔ STATE_VARIABLE_PACKING_REFACTORING.md
+
+### Code Structure Links
+- optimization/mod.rs → storage/mod.rs → state_variable_packing.rs
+- solidity/mod.rs → state_variable_packing.rs (Solidity rule)
+- lib.rs → All public exports
+
+### Test to Implementation Links
+- state_variable_packing.tests.rs
+  → state_variable_packing.rs (core logic)
+  → state_variable_packing.rs (solidity rule)
+
+## 📚 Additional Resources
+
+- **Solidity Docs**: https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html
+- **EVM Opcodes**: https://www.evm.codes/
+- **Gas Optimization**: Check project documentation
+
+## 🎓 Usage Flow
+
+1. **Read**: [PACKING_IMPLEMENTATION_SUMMARY.md](PACKING_IMPLEMENTATION_SUMMARY.md)
+2. **Understand**: [STATE_VARIABLE_PACKING.md](docs/STATE_VARIABLE_PACKING.md)
+3. **Learn**: [STATE_VARIABLE_PACKING_INTEGRATION.md](docs/STATE_VARIABLE_PACKING_INTEGRATION.md)
+4. **Implement**: [STATE_VARIABLE_PACKING_REFACTORING.md](docs/STATE_VARIABLE_PACKING_REFACTORING.md)
+5. **Reference**: [optimization/README.md](packages/rules/src/optimization/README.md)
+6. **Review**: Code files and tests
+
+---
+
+**All files are now in place and ready for use! 🚀**