test: normalize inline block comments in gatekeeper scanning (#2705)

Blank single-line block comments with index-preserving spaces so
punctuation adjacency stays visible to position heuristics; document
nested-suppressed-call attribution and multi-line block comments as
parser-requiring out-of-scope patterns.

Author: steipete

Tests/CodexBarTests/ProviderArchitectureGatekeeperTests.swift

@@ -287,6 +287,15 @@ struct ProviderArchitectureGatekeeperTests {
         #expect(references.first?.providerIDs == ["claude", "codex"])
     }
 
+    @Test
+    func `provider reference scanner sees through inline block comments`() {
+        let assignment = "let provider: UsageProvider = /* fallback */ .claude"
+        let labeled = "choose(provider: /* fallback */ .claude)"
+
+        #expect(Self.providerReferences(in: assignment, providerIDs: ["claude"]).count == 1)
+        #expect(Self.providerReferences(in: labeled, providerIDs: ["claude"]).count == 1)
+    }
+
     @Test
     func `single provider argument remains an architecture finding`() {
         let failures = Self.analyze(
@@ -4402,21 +4411,38 @@ struct ProviderArchitectureGatekeeperTests {
     private static func codeBeforeLineComment(_ line: String) -> String {
         var previous: Character?
         var isInsideString = false
-        var index = line.startIndex
-        while index < line.endIndex {
-            let character = line[index]
+        var characters = Array(line)
+        var index = 0
+        while index < characters.count {
+            let character = characters[index]
             if character == "\"", previous != "\\" {
                 isInsideString.toggle()
-            } else if character == "/", !isInsideString {
-                let next = line.index(after: index)
-                if next < line.endIndex, line[next] == "/" {
-                    return String(line[..<index])
+            } else if character == "/", !isInsideString, index + 1 < characters.count {
+                if characters[index + 1] == "/" {
+                    return String(characters[..<index])
+                }
+                if characters[index + 1] == "*" {
+                    // Blank single-line block comments with spaces so punctuation adjacency stays
+                    // visible to position heuristics while every character index is preserved.
+                    var end = index + 2
+                    while end + 1 < characters.count, !(characters[end] == "*" && characters[end + 1] == "/") {
+                        end += 1
+                    }
+                    guard end + 1 < characters.count else {
+                        return String(characters[..<index])
+                    }
+                    for blank in index...(end + 1) {
+                        characters[blank] = " "
+                    }
+                    previous = " "
+                    index = end + 2
+                    continue
                 }
             }
             previous = character
-            index = line.index(after: index)
+            index += 1
         }
-        return line
+        return String(characters)
     }
 
     private static func isIdentifierCharacter(_ character: Character) -> Bool {

docs/provider.md

@@ -70,6 +70,10 @@ The following are out of scope by design:
   closure-body dataflow. A line-and-statement lexical scan cannot model those positions honestly.
 - String concatenation, reflection, and dynamic lookup. Their runtime values are not recoverable from literal-token
   matching.
+- Provider literals nested inside the arguments of a suppressed call (for example a routing call passed into a logging
+  call). Attributing a literal to the inner rather than the outer call requires expression-tree parsing.
+- Multi-line block comments interleaved with an expression. Single-line `/* ... */` comments are blanked before
+  scanning; comments spanning statement lines are treated as ending the scanned code for that line.
 - `Tests/**`, where fixtures legitimately name providers, and non-Swift files, because this tripwire is scoped to
   shipped Swift architecture.