Parse connections from xib/storyboards

ileitch · ileitch · commit 22cfe6573ad8 · 2025-12-27T15:22:18.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@
 - Added the `--no-color`/`--color` option to disable/enable colored output.
 - Exclude wrapped properties from assign-only analysis, as Periphery cannot observe the behavior of the property wrapper.
 - Improved the readability of result messages.
+- Periphery now parses Interface Builder files to detect unused `@IBOutlet`, `@IBAction`, `@IBInspectable`, and `@IBSegueAction` members. Previously, all `@IB*` members were blindly retained if their containing class was referenced in a XIB or storyboard.
 
 ##### Bug Fixes
 
diff --git a/README.md b/README.md
@@ -317,7 +317,7 @@ Any class that inherits `XCTestCase` is automatically retained along with its te
 
 ### Interface Builder
 
-If your project contains Interface Builder files (such as storyboards and XIBs), Periphery will take these into account when identifying unused declarations. However, Periphery currently only identifies unused classes. This limitation exists because Periphery does not yet fully parse Interface Builder files (see [issue #212](https://github.com/peripheryapp/periphery/issues/212)). Due to Periphery's design principle of avoiding false positives, it is assumed that if a class is referenced in an Interface Builder file, all of its `IBOutlets` and `IBActions` are used, even if they might not be in reality. This approach will be revised to accurately identify unused `IBActions` and `IBOutlets` once Periphery gains the capability to parse Interface Builder files.
+If your project contains Interface Builder files (such as storyboards and XIBs), Periphery will take these into account when identifying unused declarations. Periphery parses these files to identify which classes, `@IBOutlet` properties, `@IBAction` methods, and `@IBInspectable` properties are actually referenced. Only those members that are connected in the Interface Builder file will be retained. Any `@IB*` members that are declared but not connected will be reported as unused.
 
 ## Comment Commands
 
diff --git a/Sources/Indexer/XibParser.swift b/Sources/Indexer/XibParser.swift
@@ -13,24 +13,119 @@ final class XibParser {
     func parse() throws -> [AssetReference] {
         guard let data = FileManager.default.contents(atPath: path.string) else { return [] }
         let structure = try AEXMLDocument(xml: data)
-        return references(from: structure.root).map {
-            AssetReference(absoluteName: $0, source: .interfaceBuilder)
+
+        // Build a map of element id -> customClass for resolving action destinations
+        var idToCustomClass: [String: String] = [:]
+        buildIdToCustomClassMap(from: structure.root, into: &idToCustomClass)
+
+        // Collect all references with their outlets, actions, and runtime attributes
+        var referencesByClass: [String: (outlets: Set<String>, actions: Set<String>, runtimeAttributes: Set<String>)] = [:]
+        collectReferences(from: structure.root, idToCustomClass: idToCustomClass, into: &referencesByClass)
+
+        return referencesByClass.map { className, members in
+            AssetReference(
+                absoluteName: className,
+                source: .interfaceBuilder,
+                outlets: Array(members.outlets),
+                actions: Array(members.actions),
+                runtimeAttributes: Array(members.runtimeAttributes)
+            )
         }
     }
 
     // MARK: - Private
 
-    private func references(from element: AEXMLElement) -> [String] {
-        var names: [String] = []
+    /// Builds a map of element id to customClass for resolving action destinations.
+    private func buildIdToCustomClassMap(from element: AEXMLElement, into map: inout [String: String]) {
+        if let id = element.attributes["id"], let customClass = element.attributes["customClass"] {
+            map[id] = customClass
+        }
+        for child in element.children {
+            buildIdToCustomClassMap(from: child, into: &map)
+        }
+    }
+
+    /// Recursively collects class references, outlets, actions, and runtime attributes.
+    private func collectReferences(
+        from element: AEXMLElement,
+        idToCustomClass: [String: String],
+        into referencesByClass: inout [String: (outlets: Set<String>, actions: Set<String>, runtimeAttributes: Set<String>)]
+    ) {
+        // Check if this element has a customClass
+        if let customClass = element.attributes["customClass"] {
+            // Initialize entry for this class if needed
+            if referencesByClass[customClass] == nil {
+                referencesByClass[customClass] = (outlets: [], actions: [], runtimeAttributes: [])
+            }
+
+            // Collect outlets from this element's connections
+            collectOutlets(from: element, forClass: customClass, into: &referencesByClass)
+
+            // Collect runtime attributes from this element
+            collectRuntimeAttributes(from: element, forClass: customClass, into: &referencesByClass)
+        }
+
+        // Collect actions - these reference a destination class
+        collectActions(from: element, idToCustomClass: idToCustomClass, into: &referencesByClass)
 
+        // Recurse into children
         for child in element.children {
-            if let name = child.attributes["customClass"] {
-                names.append(name)
+            collectReferences(from: child, idToCustomClass: idToCustomClass, into: &referencesByClass)
+        }
+    }
+
+    /// Collects outlet property names from an element's connections.
+    private func collectOutlets(
+        from element: AEXMLElement,
+        forClass customClass: String,
+        into referencesByClass: inout [String: (outlets: Set<String>, actions: Set<String>, runtimeAttributes: Set<String>)]
+    ) {
+        for child in element.children where child.name == "connections" {
+            for connection in child.children where connection.name == "outlet" {
+                if let property = connection.attributes["property"] {
+                    referencesByClass[customClass]?.outlets.insert(property)
+                }
             }
+        }
+    }
 
-            names += references(from: child)
+    /// Collects action selectors and associates them with the destination class.
+    private func collectActions(
+        from element: AEXMLElement,
+        idToCustomClass: [String: String],
+        into referencesByClass: inout [String: (outlets: Set<String>, actions: Set<String>, runtimeAttributes: Set<String>)]
+    ) {
+        for child in element.children where child.name == "connections" {
+            for connection in child.children where connection.name == "action" {
+                guard let selector = connection.attributes["selector"] else { continue }
+
+                // iOS uses "destination", macOS uses "target"
+                guard let targetId = connection.attributes["destination"] ?? connection.attributes["target"]
+                else { continue }
+
+                // Resolve the target to a customClass
+                if let customClass = idToCustomClass[targetId] {
+                    if referencesByClass[customClass] == nil {
+                        referencesByClass[customClass] = (outlets: [], actions: [], runtimeAttributes: [])
+                    }
+                    referencesByClass[customClass]?.actions.insert(selector)
+                }
+            }
         }
+    }
 
-        return names
+    /// Collects user-defined runtime attribute key paths (IBInspectable).
+    private func collectRuntimeAttributes(
+        from element: AEXMLElement,
+        forClass customClass: String,
+        into referencesByClass: inout [String: (outlets: Set<String>, actions: Set<String>, runtimeAttributes: Set<String>)]
+    ) {
+        for child in element.children where child.name == "userDefinedRuntimeAttributes" {
+            for attr in child.children where attr.name == "userDefinedRuntimeAttribute" {
+                if let keyPath = attr.attributes["keyPath"] {
+                    referencesByClass[customClass]?.runtimeAttributes.insert(keyPath)
+                }
+            }
+        }
     }
 }
diff --git a/Sources/SourceGraph/Elements/AssetReference.swift b/Sources/SourceGraph/Elements/AssetReference.swift
@@ -9,8 +9,39 @@ public struct AssetReference: Hashable {
             name = absoluteName
         }
         self.source = source
+        outlets = []
+        actions = []
+        runtimeAttributes = []
+    }
+
+    /// Initializer for Interface Builder references with outlet/action/attribute details.
+    public init(
+        absoluteName: String,
+        source: ProjectFileKind,
+        outlets: [String],
+        actions: [String],
+        runtimeAttributes: [String]
+    ) {
+        if let name = absoluteName.split(separator: ".").last {
+            self.name = String(name)
+        } else {
+            name = absoluteName
+        }
+        self.source = source
+        self.outlets = outlets
+        self.actions = actions
+        self.runtimeAttributes = runtimeAttributes
     }
 
     public let name: String
     public let source: ProjectFileKind
+
+    /// Outlet property names referenced in Interface Builder (e.g., "button", "label").
+    public let outlets: [String]
+
+    /// Action selector names referenced in Interface Builder (e.g., "click:", "handleTap:").
+    public let actions: [String]
+
+    /// User-defined runtime attribute key paths (IBInspectable, e.g., "cornerRadius", "borderColor").
+    public let runtimeAttributes: [String]
 }
diff --git a/Sources/SourceGraph/Mutators/AssetReferenceRetainer.swift b/Sources/SourceGraph/Mutators/AssetReferenceRetainer.swift
@@ -13,7 +13,15 @@ final class AssetReferenceRetainer: SourceGraphMutator {
     }
 
     func mutate() {
-        interfaceBuilderPropertyRetainer.retainPropertiesDeclaredInExtensions()
+        // Aggregate all IB references by class name to collect all outlets/actions/attributes
+        // across multiple XIB/storyboard files that might reference the same class.
+        let ibReferencesByClass = aggregateInterfaceBuilderReferences()
+
+        // Collect all runtime attributes for extension-based IBInspectable properties
+        let allRuntimeAttributes = ibReferencesByClass.values.reduce(into: Set<String>()) { result, refs in
+            result.formUnion(refs.runtimeAttributes)
+        }
+        interfaceBuilderPropertyRetainer.retainPropertiesDeclaredInExtensions(referencedAttributes: allRuntimeAttributes)
 
         graph
             .declarations(ofKind: .class)
@@ -34,7 +42,14 @@ final class AssetReferenceRetainer: SourceGraphMutator {
                     graph.unmarkRedundantPublicAccessibility(declaration)
                     declaration.descendentDeclarations.forEach { graph.unmarkRedundantPublicAccessibility($0) }
                 case .interfaceBuilder:
-                    interfaceBuilderPropertyRetainer.retainPropertiesDeclared(in: declaration)
+                    // Get aggregated references for this class
+                    let aggregated = ibReferencesByClass[declaration.name ?? ""]
+                    interfaceBuilderPropertyRetainer.retainPropertiesDeclared(
+                        in: declaration,
+                        referencedOutlets: aggregated?.outlets ?? [],
+                        referencedActions: aggregated?.actions ?? [],
+                        referencedAttributes: aggregated?.runtimeAttributes ?? []
+                    )
                 default:
                     break
                 }
@@ -46,4 +61,21 @@ final class AssetReferenceRetainer: SourceGraphMutator {
     private func reference(for declaration: Declaration) -> AssetReference? {
         graph.assetReferences.first { $0.name == declaration.name }
     }
+
+    /// Aggregates all Interface Builder references by class name, combining outlets, actions,
+    /// and runtime attributes from all XIB/storyboard files that reference each class.
+    private func aggregateInterfaceBuilderReferences() -> [String: (outlets: Set<String>, actions: Set<String>, runtimeAttributes: Set<String>)] {
+        var result: [String: (outlets: Set<String>, actions: Set<String>, runtimeAttributes: Set<String>)] = [:]
+
+        for ref in graph.assetReferences where ref.source == .interfaceBuilder {
+            if result[ref.name] == nil {
+                result[ref.name] = (outlets: [], actions: [], runtimeAttributes: [])
+            }
+            result[ref.name]?.outlets.formUnion(ref.outlets)
+            result[ref.name]?.actions.formUnion(ref.actions)
+            result[ref.name]?.runtimeAttributes.formUnion(ref.runtimeAttributes)
+        }
+
+        return result
+    }
 }
diff --git a/Sources/SourceGraph/Mutators/InterfaceBuilderPropertyRetainer.swift b/Sources/SourceGraph/Mutators/InterfaceBuilderPropertyRetainer.swift
@@ -2,30 +2,105 @@ import Foundation
 
 class InterfaceBuilderPropertyRetainer {
     private let graph: SourceGraph
-    private let ibAttributes = ["IBOutlet", "IBAction", "IBInspectable", "IBSegueAction"]
+    private let ibOutletAttributes: Set<String> = ["IBOutlet"]
+    private let ibActionAttributes: Set<String> = ["IBAction", "IBSegueAction"]
+    private let ibInspectableAttributes: Set<String> = ["IBInspectable"]
 
     required init(graph: SourceGraph) {
         self.graph = graph
     }
 
-    /// Some properties may be declared in extensions on external types, e.g IBInspectable.
-    func retainPropertiesDeclaredInExtensions() {
+    /// Retains IBInspectable properties declared in extensions on external types.
+    /// These cannot be reliably matched to XIB runtime attributes since the extended
+    /// type may not have a customClass in the XIB.
+    func retainPropertiesDeclaredInExtensions(referencedAttributes: Set<String>) {
         let extensions = graph.declarations(ofKind: .extensionClass)
 
         for extDecl in extensions {
-            for decl in extDecl.declarations where decl.attributes.contains(where: { ibAttributes.contains($0) }) {
-                graph.markRetained(decl)
+            for decl in extDecl.declarations {
+                // IBInspectable properties in extensions: check if referenced
+                if decl.attributes.contains(where: { ibInspectableAttributes.contains($0) }) {
+                    if let name = decl.name, referencedAttributes.contains(name) {
+                        graph.markRetained(decl)
+                    }
+                }
             }
         }
     }
 
-    func retainPropertiesDeclared(in declaration: Declaration) {
+    /// Retains only the outlets, actions, and inspectable properties that are actually
+    /// referenced in the Interface Builder file.
+    func retainPropertiesDeclared(
+        in declaration: Declaration,
+        referencedOutlets: Set<String>,
+        referencedActions: Set<String>,
+        referencedAttributes: Set<String>
+    ) {
         let inheritedDeclarations = graph.inheritedDeclarations(of: declaration)
         let descendentInheritedDeclarations = inheritedDeclarations.map(\.declarations).joined()
         let allDeclarations = declaration.declarations.union(descendentInheritedDeclarations)
 
-        for declaration in allDeclarations where declaration.attributes.contains(where: { ibAttributes.contains($0) }) {
-            graph.markRetained(declaration)
+        for decl in allDeclarations {
+            guard let declName = decl.name else { continue }
+
+            // Check IBOutlet properties
+            if decl.attributes.contains(where: { ibOutletAttributes.contains($0) }) {
+                if referencedOutlets.contains(declName) {
+                    graph.markRetained(decl)
+                }
+                continue
+            }
+
+            // Check IBAction/IBSegueAction methods
+            if decl.attributes.contains(where: { ibActionAttributes.contains($0) }) {
+                let selectorName = swiftNameToSelector(declName)
+                if referencedActions.contains(selectorName) {
+                    graph.markRetained(decl)
+                }
+                continue
+            }
+
+            // Check IBInspectable properties
+            if decl.attributes.contains(where: { ibInspectableAttributes.contains($0) }) {
+                if referencedAttributes.contains(declName) {
+                    graph.markRetained(decl)
+                }
+                continue
+            }
+        }
+    }
+
+    // MARK: - Private
+
+    /// Converts a Swift function name like `click(_:)` or `doSomething(_:withValue:)`
+    /// to an Objective-C selector like `click:` or `doSomething:withValue:`.
+    private func swiftNameToSelector(_ swiftName: String) -> String {
+        // Remove the trailing parenthesis content to get just the method name with params
+        // e.g., "click(_:)" -> "click:" or "handleTap(_:forEvent:)" -> "handleTap:forEvent:"
+        guard let parenStart = swiftName.firstIndex(of: "("),
+              let parenEnd = swiftName.lastIndex(of: ")")
+        else {
+            return swiftName
+        }
+
+        let methodName = String(swiftName[..<parenStart])
+        let paramsSection = String(swiftName[swiftName.index(after: parenStart) ..< parenEnd])
+
+        // Split by ":" to get parameter labels
+        let params = paramsSection.split(separator: ":", omittingEmptySubsequences: false)
+
+        // Build the selector: methodName + ":" for each parameter
+        var selector = methodName
+        for (index, param) in params.enumerated() {
+            if index == 0 {
+                // First parameter: just add ":"
+                selector += ":"
+            } else if !param.isEmpty {
+                // Subsequent parameters: add label + ":"
+                selector += String(param) + ":"
+            }
         }
+
+        return selector
     }
 }
diff --git a/Tests/SPMTests/SPMProjectMacOS/Sources/SPMProjectMacOSKit/SPMXibViewController.swift b/Tests/SPMTests/SPMProjectMacOS/Sources/SPMProjectMacOSKit/SPMXibViewController.swift
@@ -1,6 +1,11 @@
 import AppKit
 
 public class SPMXibViewController: NSViewController {
+    // Referenced via XIB (connected)
     @IBOutlet var button: NSButton!
     @IBAction func buttonTapped(_: Any) {}
+
+    // Unreferenced - not connected in XIB
+    @IBOutlet var unusedMacOutlet: NSTextField!
+    @IBAction func unusedMacAction(_: Any) {}
 }
diff --git a/Tests/SPMTests/SPMProjectMacOSTest.swift b/Tests/SPMTests/SPMProjectMacOSTest.swift
@@ -13,8 +13,12 @@
 
         func testRetainsInterfaceBuilderDeclarations() {
             assertReferenced(.class("SPMXibViewController")) {
+                // Referenced via XIB (connected)
                 self.assertReferenced(.functionMethodInstance("buttonTapped(_:)"))
                 self.assertReferenced(.varInstance("button"))
+                // Unreferenced - not connected in XIB
+                self.assertNotReferenced(.varInstance("unusedMacOutlet"))
+                self.assertNotReferenced(.functionMethodInstance("unusedMacAction(_:)"))
             }
         }
     }
diff --git a/Tests/XcodeTests/UIKitProject/UIKitProject/StoryboardViewController.swift b/Tests/XcodeTests/UIKitProject/UIKitProject/StoryboardViewController.swift
@@ -1,6 +1,12 @@
 import UIKit
 
 class StoryboardViewController: UIViewController {
+    // Referenced via storyboard (connected)
     @IBOutlet weak var button: UIButton!
     @IBAction func click(_ sender: Any) {}
+
+    // Unreferenced - not connected in storyboard
+    @IBOutlet weak var unusedStoryboardOutlet: UILabel!
+    @IBAction func unusedStoryboardAction(_ sender: Any) {}
+    @IBInspectable var unusedStoryboardInspectable: CGFloat = 0
 }
diff --git a/Tests/XcodeTests/UIKitProject/UIKitProject/XibViewController.swift b/Tests/XcodeTests/UIKitProject/UIKitProject/XibViewController.swift
diff --git a/Tests/XcodeTests/UIKitProject/UIKitProject/XibViewController.xib b/Tests/XcodeTests/UIKitProject/UIKitProject/XibViewController.xib
diff --git a/Tests/XcodeTests/UIKitProject/UIKitProject/XibViewController2.swift b/Tests/XcodeTests/UIKitProject/UIKitProject/XibViewController2.swift
diff --git a/Tests/XcodeTests/UIKitProjectTest.swift b/Tests/XcodeTests/UIKitProjectTest.swift

Original file line number	Diff line number	Diff line change
`@@ -13,8 +13,12 @@`
`13`	`13`
`14`	`14`	`func testRetainsInterfaceBuilderDeclarations() {`
`15`	`15`	`assertReferenced(.class("SPMXibViewController")) {`
	`16`	`+ // Referenced via XIB (connected)`
`16`	`17`	`self.assertReferenced(.functionMethodInstance("buttonTapped(_:)"))`
`17`	`18`	`self.assertReferenced(.varInstance("button"))`
	`19`	`+ // Unreferenced - not connected in XIB`
	`20`	`+ self.assertNotReferenced(.varInstance("unusedMacOutlet"))`
	`21`	`+ self.assertNotReferenced(.functionMethodInstance("unusedMacAction(_:)"))`
`18`	`22`	`}`
`19`	`23`	`}`
`20`	`24`	`}`