Adds Variable Shadowing Rule

Author: nadeemnali

CHANGELOG.md

@@ -51,6 +51,10 @@
   and FEFF formatting character (U+FEFF) in string literals, which can cause hard-to-debug issues.  
   [kapitoshka438](https://github.com/kapitoshka438)
   [#6045](https://github.com/realm/SwiftLint/issues/6045)
+* Add `variable_shadowing` rule that flags when a variable declaration shadows
+  an identifier from an outer scope.  
+  [nadeemnali](https://github.com/nadeemnali)
+  [#6228](https://github.com/realm/SwiftLint/issues/6228)
 
 ### Bug Fixes
 

Source/SwiftLintBuiltInRules/Models/BuiltInRules.swift

@@ -240,6 +240,7 @@ public let builtInRules: [any Rule.Type] = [
     UnusedParameterRule.self,
     UnusedSetterValueRule.self,
     ValidIBInspectableRule.self,
+    VariableShadowingRule.self,
     VerticalParameterAlignmentOnCallRule.self,
     VerticalParameterAlignmentRule.self,
     VerticalWhitespaceBetweenCasesRule.self,

Source/SwiftLintBuiltInRules/Rules/Lint/VariableShadowingRule.swift

@@ -0,0 +1,148 @@
+import SwiftLintCore
+import SwiftSyntax
+
+@SwiftSyntaxRule
+struct VariableShadowingRule: Rule {
+    var configuration = SeverityConfiguration<Self>(.warning)
+
+    static let description = RuleDescription(
+        identifier: "variable_shadowing",
+        name: "Variable Shadowing",
+        description: "Prefer not to shadow variables declared in outer scopes",
+        kind: .lint,
+        nonTriggeringExamples: [
+            Example("""
+            var a: String?
+            func test(a: String?) {
+                print(a)
+            }
+            """),
+            Example("""
+            var a: String = "hello"
+            if let b = a {
+                print(b)
+            }
+            """),
+            Example("""
+            var a: String?
+            func test() {
+                if let b = a {
+                    print(b)
+                }
+            }
+            """),
+            Example("""
+            for i in 1...10 {
+                print(i)
+            }
+            for j in 1...10 {
+                print(j)
+            }
+            """),
+            Example("""
+            func test() {
+                var a: String = "hello"
+                func nested() {
+                    var b: String = "world"
+                    print(a, b)
+                }
+            }
+            """),
+            Example("""
+            class Test {
+                var a: String?
+                func test(a: String?) {
+                    print(a)
+                }
+            }
+            """),
+        ],
+        triggeringExamples: [
+            Example("""
+            var outer: String = "hello"
+            func test() {
+                let ↓outer = "world"
+                print(outer)
+            }
+            """),
+        ]
+    )
+}
+
+private extension VariableShadowingRule {
+    final class Visitor: DeclaredIdentifiersTrackingVisitor<ConfigurationType> {
+        override func visit(_ node: VariableDeclSyntax) -> SyntaxVisitorContinueKind {
+            // Early exit for member blocks (class/struct properties)
+            if node.parent?.is(MemberBlockItemSyntax.self) != true {
+                // Check for shadowing BEFORE adding to scope
+                node.bindings.forEach { binding in
+                    checkForShadowing(in: binding.pattern)
+                }
+            }
+            return super.visit(node)
+        }
+
+        override func visit(_ node: CodeBlockItemListSyntax) -> SyntaxVisitorContinueKind {
+            guard let parent = node.parent else {
+                return super.visit(node)
+            }
+
+            // Call super first so the base visitor opens the child scope and collects identifiers
+            let kind = super.visit(node)
+
+            // Check conditions if this is an if/while body AFTER identifiers from conditions were collected
+            if let ifStmt = parent.as(IfExprSyntax.self) {
+                checkForShadowingInConditions(ifStmt.conditions)
+            } else if let whileStmt = parent.as(WhileStmtSyntax.self) {
+                checkForShadowingInConditions(whileStmt.conditions)
+            }
+
+            return kind
+        }
+
+        override func visitPost(_ node: GuardStmtSyntax) {
+            // Let the base visitor collect identifiers first (it does so in its visitPost)
+            super.visitPost(node)
+            // Check for shadowing in guard conditions after collection
+            checkForShadowingInConditions(node.conditions)
+        }
+
+        private func checkForShadowingInConditions(_ conditions: ConditionElementListSyntax) {
+            for element in conditions {
+                if let binding = element.condition.as(OptionalBindingConditionSyntax.self) {
+                    checkForShadowing(in: binding.pattern)
+                }
+            }
+        }
+
+        private func checkForShadowing(in pattern: PatternSyntax) {
+            if let identifier = pattern.as(IdentifierPatternSyntax.self) {
+                let identifierText = identifier.identifier.text
+                if isShadowingOuterScope(identifierText) {
+                    violations.append(identifier.identifier.positionAfterSkippingLeadingTrivia)
+                }
+                return
+            }
+
+            if let tuple = pattern.as(TuplePatternSyntax.self) {
+                tuple.elements.forEach { element in
+                    checkForShadowing(in: element.pattern)
+                }
+                return
+            }
+
+            // Other pattern kinds are not relevant for shadowing checks here; no action needed.
+        }
+
+        private func isShadowingOuterScope(_ identifier: String) -> Bool {
+            guard !scope.isEmpty, scope.count > 1 else { return false }
+
+            // Use early exit and lazy evaluation for better performance
+            for scopeDeclarations in scope.dropLast() where
+                scopeDeclarations.lazy.contains(where: { $0.declares(id: identifier) }) {
+                return true
+            }
+            return false
+        }
+    }
+}

Tests/GeneratedTests/GeneratedTests_10.swift

@@ -85,6 +85,12 @@ final class ValidIBInspectableRuleGeneratedTests: SwiftLintTestCase {
     }
 }
 
+final class VariableShadowingRuleGeneratedTests: SwiftLintTestCase {
+    func testWithDefaultConfiguration() {
+        verifyRule(VariableShadowingRule.description)
+    }
+}
+
 final class VerticalParameterAlignmentOnCallRuleGeneratedTests: SwiftLintTestCase {
     func testWithDefaultConfiguration() {
         verifyRule(VerticalParameterAlignmentOnCallRule.description)

Tests/IntegrationTests/Resources/default_rule_configurations.yml

@@ -1383,6 +1383,11 @@ valid_ibinspectable:
   meta:
     opt-in: false
     correctable: false
+variable_shadowing:
+  severity: warning
+  meta:
+    opt-in: false
+    correctable: false
 vertical_parameter_alignment:
   severity: warning
   meta: