Fix unused import false-positives where the only referenced declaration is generated by a macro. Closes #863 (#910)

ileitch · web-flow · commit 871de38518ea · 2025-04-12T14:12:38.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,7 +10,7 @@
 
 ##### Bug Fixes
 
-- None.
+- Fix unused import false-positives where the only referenced declaration is generated by a macro.
 
 ## 3.1.0 (2025-04-05)
 
diff --git a/Sources/Indexer/SwiftIndexer.swift b/Sources/Indexer/SwiftIndexer.swift
@@ -255,7 +255,7 @@ final class SwiftIndexer: Indexer {
         private func establishDeclarationHierarchy() {
             graph.withLock {
                 for (parent, decls) in childDeclsByParentUsr {
-                    guard let parentDecl = graph.explicitDeclarationWithoutLock(withUsr: parent) else {
+                    guard let parentDecl = graph.declarationWithoutLock(withUsr: parent) else {
                         if varParameterUsrs.contains(parent) {
                             // These declarations are children of a parameter and are redundant.
                             decls.forEach { graph.removeWithoutLock($0) }
@@ -276,7 +276,7 @@ final class SwiftIndexer: Indexer {
         private func associateLatentReferences() {
             for (usr, refs) in referencesByUsr {
                 graph.withLock {
-                    if let decl = graph.explicitDeclarationWithoutLock(withUsr: usr) {
+                    if let decl = graph.declarationWithoutLock(withUsr: usr) {
                         for ref in refs {
                             associateUnsafe(ref, with: decl)
                         }
diff --git a/Sources/SourceGraph/Mutators/ExtensionReferenceBuilder.swift b/Sources/SourceGraph/Mutators/ExtensionReferenceBuilder.swift
@@ -21,7 +21,7 @@ final class ExtensionReferenceBuilder: SourceGraphMutator {
         for extensionDeclaration in graph.declarations(ofKind: kind) {
             guard let extendedTypeReference = try graph.extendedDeclarationReference(forExtension: extensionDeclaration) else { continue }
 
-            guard let extendedDeclaration = graph.explicitDeclaration(withUsr: extendedTypeReference.usr) else {
+            guard let extendedDeclaration = graph.declaration(withUsr: extendedTypeReference.usr) else {
                 // This is an extension on an external type and cannot be folded.
                 graph.markRetained(extensionDeclaration)
                 continue
diff --git a/Sources/SourceGraph/Mutators/ExternalOverrideRetainer.swift b/Sources/SourceGraph/Mutators/ExternalOverrideRetainer.swift
@@ -29,7 +29,7 @@ final class ExternalOverrideRetainer: SourceGraphMutator {
                 {
                     didIdentifyRelatedRef = true
 
-                    if graph.explicitDeclaration(withUsr: relatedRef.usr) == nil {
+                    if graph.declaration(withUsr: relatedRef.usr) == nil {
                         // The related decl is external.
                         graph.markRetained(decl)
                     }
diff --git a/Sources/SourceGraph/Mutators/ExternalTypeProtocolConformanceReferenceRemover.swift b/Sources/SourceGraph/Mutators/ExternalTypeProtocolConformanceReferenceRemover.swift
@@ -17,7 +17,7 @@ final class ExternalTypeProtocolConformanceReferenceRemover: SourceGraphMutator
             guard try graph.extendedDeclaration(forExtension: extDecl) == nil else { continue }
 
             // Ensure the type is extended by local protocols.
-            let protocolDecls = extDecl.related.filter { $0.kind == .protocol }.map { graph.explicitDeclaration(withUsr: $0.usr) }
+            let protocolDecls = extDecl.related.filter { $0.kind == .protocol }.map { graph.declaration(withUsr: $0.usr) }
             guard !protocolDecls.isEmpty else { continue }
 
             // Find all related references that may be protocol members.
@@ -26,7 +26,7 @@ final class ExternalTypeProtocolConformanceReferenceRemover: SourceGraphMutator
             for relatedRef in relatedRefs {
                 // Ensure the relatedDecl is a member of a protocol.
                 guard
-                    let relatedDecl = graph.explicitDeclaration(withUsr: relatedRef.usr),
+                    let relatedDecl = graph.declaration(withUsr: relatedRef.usr),
                     let parentDecl = relatedDecl.parent,
                     protocolDecls.contains(parentDecl)
                 else { continue }
diff --git a/Sources/SourceGraph/Mutators/ProtocolConformanceReferenceBuilder.swift b/Sources/SourceGraph/Mutators/ProtocolConformanceReferenceBuilder.swift
@@ -44,7 +44,7 @@ final class ProtocolConformanceReferenceBuilder: SourceGraphMutator {
                     // Find all superclasses.
                     let superclassDecls = graph.inheritedTypeReferences(of: conformingClass)
                         .filter { $0.kind == .class }
-                        .compactMap { graph.explicitDeclaration(withUsr: $0.usr) }
+                        .compactMap { graph.declaration(withUsr: $0.usr) }
                         .flatMap(\.declarations)
 
                     for unimplementedProtoDecl in unimplementedProtoDecls {
@@ -104,7 +104,7 @@ final class ProtocolConformanceReferenceBuilder: SourceGraphMutator {
             guard equivalentDeclarationKinds.contains(conformingDeclaration.kind),
                   conformingDeclaration.name == relatedReference.name else { continue }
 
-            if let protocolDeclaration = graph.explicitDeclaration(withUsr: relatedReference.usr) {
+            if let protocolDeclaration = graph.declaration(withUsr: relatedReference.usr) {
                 // Invert the related reference such that instead of the conforming declaration
                 // referencing the declaration within the protocol, the protocol declaration
                 // now references the conforming declaration.
diff --git a/Sources/SourceGraph/Mutators/RedundantExplicitPublicAccessibilityMarker.swift b/Sources/SourceGraph/Mutators/RedundantExplicitPublicAccessibilityMarker.swift
@@ -91,7 +91,7 @@ final class RedundantExplicitPublicAccessibilityMarker: SourceGraphMutator {
                         // the call site arguments with function parameters, as parameters with
                         // default types can cause misalignment between the positions of the two.
                         if let functionRef = $0.parent?.references.first(where: { $0.role == .variableInitFunctionCall }),
-                           let functionDecl = graph.explicitDeclaration(withUsr: functionRef.usr),
+                           let functionDecl = graph.declaration(withUsr: functionRef.usr),
                            functionDecl.hasGenericFunctionReturnedMetatypeParameters
                         {
                             return $0.parent
diff --git a/Sources/SourceGraph/Mutators/RedundantProtocolMarker.swift b/Sources/SourceGraph/Mutators/RedundantProtocolMarker.swift
@@ -34,7 +34,7 @@ final class RedundantProtocolMarker: SourceGraphMutator {
                 .references
                 .lazy
                 .filter { $0.kind == .extensionProtocol }
-                .compactMap { self.graph.explicitDeclaration(withUsr: $0.usr) }
+                .compactMap { self.graph.declaration(withUsr: $0.usr) }
                 .flatMap(\.declarations)
                 .allSatisfy { unusedDeclarations.contains($0) }
 
diff --git a/Sources/SourceGraph/Mutators/UnusedImportMarker.swift b/Sources/SourceGraph/Mutators/UnusedImportMarker.swift
@@ -28,7 +28,8 @@ final class UnusedImportMarker: SourceGraphMutator {
 
         // Build a mapping of source files and the modules they reference.
         for ref in graph.allReferences {
-            guard let decl = graph.explicitDeclaration(withUsr: ref.usr) else { continue }
+            guard let decl = graph.declaration(withUsr: ref.usr) else { continue }
+
             // Record directly referenced modules and also identify any modules that extended
             // the declaration. These extensions may provide members/conformances that aren't
             // referenced directly but which are still required.
diff --git a/Sources/SourceGraph/Mutators/UnusedParameterRetainer.swift b/Sources/SourceGraph/Mutators/UnusedParameterRetainer.swift
@@ -24,7 +24,7 @@ final class UnusedParameterRetainer: SourceGraphMutator {
             for protoFuncDecl in protoFuncDecls {
                 let relatedFuncDecls = protoFuncDecl.related
                     .filter(\.kind.isFunctionKind)
-                    .compactMapSet { graph.explicitDeclaration(withUsr: $0.usr) }
+                    .compactMapSet { graph.declaration(withUsr: $0.usr) }
                 let extFuncDecls = relatedFuncDecls.filter { $0.parent?.kind.isExtensionKind ?? false }
                 let conformingDecls = relatedFuncDecls.subtracting(extFuncDecls)
 
diff --git a/Sources/SourceGraph/Mutators/UsedDeclarationMarker.swift b/Sources/SourceGraph/Mutators/UsedDeclarationMarker.swift
@@ -26,7 +26,7 @@ final class UsedDeclarationMarker: SourceGraphMutator {
         for protocolDecl in graph.declarations(ofKind: .protocol) {
             for memberDecl in protocolDecl.declarations {
                 for relatedRef in memberDecl.related {
-                    guard let relatedDecl = graph.explicitDeclaration(withUsr: relatedRef.usr) else { continue }
+                    guard let relatedDecl = graph.declaration(withUsr: relatedRef.usr) else { continue }
 
                     let hasDereferencedAncestor = relatedDecl.ancestralDeclarations.contains {
                         !(graph.isRetained($0) || graph.hasReferences(to: $0))
@@ -59,7 +59,7 @@ final class UsedDeclarationMarker: SourceGraphMutator {
     private func declarationsReferenced(by reference: Reference) -> Set<Declaration> {
         var declarations: Set<Declaration> = []
 
-        if let declaration = graph.explicitDeclaration(withUsr: reference.usr) {
+        if let declaration = graph.declaration(withUsr: reference.usr) {
             declarations.insert(declaration)
         }
 
diff --git a/Sources/SourceGraph/SourceGraph.swift b/Sources/SourceGraph/SourceGraph.swift
@@ -22,7 +22,7 @@ public final class SourceGraph {
     public private(set) var extensions: [Declaration: Set<Declaration>] = [:]
 
     private var allDeclarationsByKind: [Declaration.Kind: Set<Declaration>] = [:]
-    private var allExplicitDeclarationsByUsr: [String: Declaration] = [:]
+    private var allDeclarationsByUsr: [String: Declaration] = [:]
     private var moduleToExportingModules: [String: Set<String>] = [:]
 
     private let configuration: Configuration
@@ -52,8 +52,8 @@ public final class SourceGraph {
         kinds.flatMapSet { allDeclarationsByKind[$0, default: []] }
     }
 
-    public func explicitDeclaration(withUsr usr: String) -> Declaration? {
-        allExplicitDeclarationsByUsr[usr]
+    public func declaration(withUsr usr: String) -> Declaration? {
+        allDeclarationsByUsr[usr]
     }
 
     public func references(to decl: Declaration) -> Set<Reference> {
@@ -103,21 +103,15 @@ public final class SourceGraph {
     public func add(_ declaration: Declaration) {
         allDeclarations.insert(declaration)
         allDeclarationsByKind[declaration.kind, default: []].insert(declaration)
-
-        if !declaration.isImplicit {
-            declaration.usrs.forEach { allExplicitDeclarationsByUsr[$0] = declaration }
-        }
+        declaration.usrs.forEach { allDeclarationsByUsr[$0] = declaration }
     }
 
     public func add(_ declarations: Set<Declaration>) {
         allDeclarations.formUnion(declarations)
 
         for declaration in declarations {
             allDeclarationsByKind[declaration.kind, default: []].insert(declaration)
-
-            if !declaration.isImplicit {
-                declaration.usrs.forEach { allExplicitDeclarationsByUsr[$0] = declaration }
-            }
+            declaration.usrs.forEach { allDeclarationsByUsr[$0] = declaration }
         }
     }
 
@@ -128,7 +122,7 @@ public final class SourceGraph {
         rootDeclarations.remove(declaration)
         usedDeclarations.remove(declaration)
         assignOnlyProperties.remove(declaration)
-        declaration.usrs.forEach { allExplicitDeclarationsByUsr.removeValue(forKey: $0) }
+        declaration.usrs.forEach { allDeclarationsByUsr.removeValue(forKey: $0) }
     }
 
     public func add(_ reference: Reference) {
@@ -175,7 +169,7 @@ public final class SourceGraph {
     }
 
     func isExternal(_ reference: Reference) -> Bool {
-        explicitDeclaration(withUsr: reference.usr) == nil
+        declaration(withUsr: reference.usr) == nil
     }
 
     public func addIndexedSourceFile(_ file: SourceFile) {
@@ -223,7 +217,7 @@ public final class SourceGraph {
         for reference in decl.immediateInheritedTypeReferences {
             references.insert(reference)
 
-            if let inheritedDecl = explicitDeclaration(withUsr: reference.usr) {
+            if let inheritedDecl = declaration(withUsr: reference.usr) {
                 // Detect circular references. The following is valid Swift.
                 // class SomeClass {}
                 // extension SomeClass: SomeProtocol {}
@@ -237,14 +231,14 @@ public final class SourceGraph {
     }
 
     func inheritedDeclarations(of decl: Declaration) -> [Declaration] {
-        inheritedTypeReferences(of: decl).compactMap { explicitDeclaration(withUsr: $0.usr) }
+        inheritedTypeReferences(of: decl).compactMap { declaration(withUsr: $0.usr) }
     }
 
     func immediateSubclasses(of decl: Declaration) -> Set<Declaration> {
         references(to: decl)
             .filter { $0.isRelated && $0.kind == .class }
             .flatMap { $0.parent?.usrs ?? [] }
-            .compactMapSet { explicitDeclaration(withUsr: $0) }
+            .compactMapSet { declaration(withUsr: $0) }
     }
 
     func subclasses(of decl: Declaration) -> Set<Declaration> {
@@ -264,7 +258,7 @@ public final class SourceGraph {
     func extendedDeclaration(forExtension extensionDeclaration: Declaration) throws -> Declaration? {
         guard let extendedReference = try extendedDeclarationReference(forExtension: extensionDeclaration) else { return nil }
 
-        if let extendedDeclaration = allExplicitDeclarationsByUsr[extendedReference.usr] {
+        if let extendedDeclaration = allDeclarationsByUsr[extendedReference.usr] {
             return extendedDeclaration
         }
 
@@ -293,7 +287,7 @@ public final class SourceGraph {
 
     func allOverrideDeclarations(fromBase decl: Declaration) -> Set<Declaration> {
         decl.relatedEquivalentReferences
-            .compactMap { explicitDeclaration(withUsr: $0.usr) }
+            .compactMap { declaration(withUsr: $0.usr) }
             .reduce(into: .init()) { result, decl in
                 guard decl.isOverride else { return }
                 result.insert(decl)
diff --git a/Sources/SourceGraph/SynchronizedSourceGraph.swift b/Sources/SourceGraph/SynchronizedSourceGraph.swift
@@ -54,8 +54,8 @@ public final class SynchronizedSourceGraph {
         graph.remove(declaration)
     }
 
-    public func explicitDeclarationWithoutLock(withUsr usr: String) -> Declaration? {
-        graph.explicitDeclaration(withUsr: usr)
+    public func declarationWithoutLock(withUsr usr: String) -> Declaration? {
+        graph.declaration(withUsr: usr)
     }
 
     public func markRetainedWithoutLock(_ declaration: Declaration) {
diff --git a/Tests/SPMTests/SPMProject/Package.resolved b/Tests/SPMTests/SPMProject/Package.resolved
diff --git a/Tests/SPMTests/SPMProject/Package.swift b/Tests/SPMTests/SPMProject/Package.swift
@@ -1,22 +1,40 @@
-// swift-tools-version:5.10
+import CompilerPluginSupport
+
+// swift-tools-version: 6.0
 import PackageDescription
 
 let package = Package(
     name: "SPMProject",
+    platforms: [.macOS(.v13)],
     products: [
         .executable(
             name: "frontend",
             targets: ["Frontend"]
         ),
     ],
+    dependencies: [
+        .package(url: "https://github.com/swiftlang/swift-syntax", from: "601.0.1"),
+    ],
     targets: [
         .executableTarget(
             name: "Frontend",
             dependencies: ["SPMProjectKit"]
         ),
         .target(
             name: "SPMProjectKit",
-            dependencies: []
+            dependencies: ["SPMProjectMacros"]
+        ),
+        .macro(
+            name: "SPMProjectMacros",
+            dependencies: [
+                .product(name: "SwiftSyntax", package: "swift-syntax"),
+                .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+                .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
+            ]
+        ),
+        .testTarget(
+            name: "Tests",
+            dependencies: ["SPMProjectKit"]
         ),
     ]
 )
diff --git a/Tests/SPMTests/SPMProject/Sources/SPMProjectKit/Macros.swift b/Tests/SPMTests/SPMProject/Sources/SPMProjectKit/Macros.swift
@@ -0,0 +1,2 @@
+@attached(peer, names: suffixed(Mock))
+public macro Mock() = #externalMacro(module: "SPMProjectMacros", type: "MockMacro")
diff --git a/Tests/SPMTests/SPMProject/Sources/SPMProjectKit/MockedProtocol.swift b/Tests/SPMTests/SPMProject/Sources/SPMProjectKit/MockedProtocol.swift
@@ -0,0 +1,2 @@
+@Mock
+protocol MockedProtocol {}
diff --git a/Tests/SPMTests/SPMProject/Sources/SPMProjectMacros/MockMacro.swift b/Tests/SPMTests/SPMProject/Sources/SPMProjectMacros/MockMacro.swift
@@ -0,0 +1,30 @@
+import Foundation
+import SwiftOperators
+import SwiftSyntax
+import SwiftSyntaxMacros
+
+struct MockMacro: PeerMacro {
+    public static func expansion(
+        of _: AttributeSyntax,
+        providingPeersOf declaration: some DeclSyntaxProtocol,
+        in _: some MacroExpansionContext
+    ) throws -> [DeclSyntax] {
+        guard let protocolDecl = declaration.as(ProtocolDeclSyntax.self) else { return [] }
+
+        let protocolName = protocolDecl.name.text
+        let mockName = "\(protocolName)Mock"
+
+        let mockClass = DeclSyntax(
+            ClassDeclSyntax(
+                modifiers: [DeclModifierSyntax(name: "public")],
+                name: .identifier(mockName),
+                inheritanceClause: InheritanceClauseSyntax {
+                    InheritedTypeSyntax(type: TypeSyntax(stringLiteral: protocolName))
+                },
+                memberBlock: MemberBlockSyntax {}
+            )
+        )
+
+        return [mockClass]
+    }
+}
diff --git a/Tests/SPMTests/SPMProject/Sources/SPMProjectMacros/Plugin.swift b/Tests/SPMTests/SPMProject/Sources/SPMProjectMacros/Plugin.swift
@@ -0,0 +1,9 @@
+import SwiftCompilerPlugin
+import SwiftSyntaxMacros
+
+@main
+struct TestPlugin: CompilerPlugin {
+    let providingMacros: [Macro.Type] = [
+        MockMacro.self,
+    ]
+}
diff --git a/Tests/SPMTests/SPMProject/Tests/MacroImportTests.swift b/Tests/SPMTests/SPMProject/Tests/MacroImportTests.swift
@@ -0,0 +1,9 @@
+import SPMProjectKit
+import XCTest
+
+class MacroImportTests: XCTestCase {
+    func testMacro() {
+        // This is the only reference to SPMProjectKit.
+        _ = MockedProtocolMock.self
+    }
+}
diff --git a/Tests/SPMTests/SPMProjectTest.swift b/Tests/SPMTests/SPMProjectTest.swift
@@ -17,4 +17,8 @@ final class SPMProjectTest: SPMSourceGraphTestCase {
         assertReferenced(.class("PublicCrossModuleReferenced"))
         assertNotReferenced(.class("PublicCrossModuleNotReferenced"))
     }
+
+    func testMacroImport() {
+        assertReferenced(.module("SPMProjectKit"))
+    }
 }
diff --git a/Tests/Shared/SourceGraphTestCase.swift b/Tests/Shared/SourceGraphTestCase.swift
@@ -82,7 +82,6 @@ open class SourceGraphTestCase: XCTestCase {
             if let declaration = Self.graph.unusedModuleImports.first(where: { $0.name == description.name }) {
                 XCTFail("Expected declaration to be referenced: \(declaration)", file: file, line: line)
             }
-
         } else {
             guard let declaration = materialize(description, file: file, line: line) else { return }
 

Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ final class ExternalOverrideRetainer: SourceGraphMutator {`
`29`	`29`	`{`
`30`	`30`	`didIdentifyRelatedRef = true`
`31`	`31`
`32`		`- if graph.explicitDeclaration(withUsr: relatedRef.usr) == nil {`
	`32`	`+ if graph.declaration(withUsr: relatedRef.usr) == nil {`
`33`	`33`	`// The related decl is external.`
`34`	`34`	`graph.markRetained(decl)`
`35`	`35`	`}`
Original file line number	Diff line number	Diff line change
`@@ -91,7 +91,7 @@ final class RedundantExplicitPublicAccessibilityMarker: SourceGraphMutator {`
`91`	`91`	`// the call site arguments with function parameters, as parameters with`
`92`	`92`	`// default types can cause misalignment between the positions of the two.`
`93`	`93`	`if let functionRef = $0.parent?.references.first(where: { $0.role == .variableInitFunctionCall }),`
`94`		`- let functionDecl = graph.explicitDeclaration(withUsr: functionRef.usr),`
	`94`	`+ let functionDecl = graph.declaration(withUsr: functionRef.usr),`
`95`	`95`	`functionDecl.hasGenericFunctionReturnedMetatypeParameters`
`96`	`96`	`{`
`97`	`97`	`return $0.parent`