feat: Add variable shadowing detection in nested scopes

[meshackyaro]

Description

This PR implements a new static analysis rule to detect variable shadowing in nested scopes, which can lead to logic bugs where the wrong variable is updated or accessed.

Closes #437

Changes

Core Implementation

• New Rule: VariableShadowingRule in tooling/sanctifier-core/src/rules/variable_shadowing.rs
  • Detects variables in nested scopes that shadow outer variables
  • Tracks declarations across function parameters, blocks, for loops, closures, and match arms
  • Smart filtering to avoid false positives (skips _ prefixed variables, env, e, self)
  • Provides actionable suggestions for renaming

Testing

• 10 comprehensive unit tests covering various shadowing scenarios:
  • Simple shadowing in nested blocks
  • Shadowing in conditional blocks (if/else)
  • Shadowing in for loops
  • Shadowing in match arms
  • Shadowing in closures
  • Edge cases (sibling scopes, underscore prefix, common parameters)
• All 146 tests pass in sanctifier-core

CLI Integration

• Integrated into sanctifier analyze command
• Clear warning messages with location and suggestions
• Added to finding aggregation and reporting

Example Contract

• Created contracts/shadowing-example demonstrating:
  • 5 real-world shadowing bugs that cause logic errors
  • Correct implementations without shadowing
  • Tests proving the bugs exist

Example Output

⚠️ Found Variable Shadowing issues!
   -> [S006] Variable 'balance' shadows an outer variable declared at line 16
      Location: contracts/shadowing-example/src/lib.rs:20:16
      Suggestion: Consider renaming the inner variable to avoid shadowing (e.g., 'balance_inner', 'balance_2')

Why This Matters

Variable shadowing can cause subtle logic bugs in smart contracts where developers think they're updating one variable but are actually modifying a shadowed version. This is especially dangerous in financial applications where such bugs can lead to losses.

Testing

# Run tests
cargo test --package sanctifier-core variable_shadowing

# Test on example contract
sanctifier analyze contracts/shadowing-example

All tests pass successfully.

[drips-wave]

@meshackyaro Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits