ci: Add Developer Linter

Author: mcgaryp

.swiftlint.yml

@@ -0,0 +1,18 @@
+disabled_rules: # rules to exclude from running
+  - trailing_whitespace
+
+opt_in_rules: # some rules are disabled by default, so you need to opt-in
+  - redundant_void_return
+
+included: # paths to include during linting. Takes precedence over `excluded`.
+  - Sources
+  - Tests
+  - Playground
+
+excluded: # paths to ignore during linting. Takes precedence over `included`.
+  - Carthage
+  - Pods
+  - .build
+  - Docs
+
+line_length: 120 # max line length

Package.resolved

@@ -17,11 +17,14 @@ let package = Package(
         .library(name: "Astroject-Nexus", targets: ["Nexus"]),
         .library(name: "Astroject-Singularity", targets: ["Singularity"])
     ],
+    dependencies: [
+        .package(url: "https://github.com/realm/SwiftLint.git", from: "0.58.2") // Add SwiftLint as a development dependency
+    ],
     targets: [
-        .target(name: "Core"),
-        .target(name: "Nexus", dependencies: ["Core"]),
-        .target(name: "Singularity", dependencies: ["Core"]),
-        
+        .target(name: "Core", plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLint")]),
+        .target(name: "Nexus", dependencies: ["Core"], plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLint")]),
+        .target(name: "Singularity", dependencies: ["Core"], plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLint")]),
+
         .testTarget(name: "CoreTests", dependencies: ["Core"]),
         .testTarget(name: "NexusTests", dependencies: ["Nexus"]),
         .testTarget(name: "SingularityTests", dependencies: ["Singularity"]),

Package.swift

@@ -1,18 +1,22 @@
 //
-//  Assembler.swift
-//  Astroject
+// Assembler.swift
+// Astroject
 //
-//  Created by Porter McGary on 2/27/25.
+// Created by Porter McGary on 2/27/25.
 //
 
 import Foundation
 
 /// Assembles dependencies into a `Container` using provided `Assembly` instances.
+///
+/// The `Assembler` class is responsible for applying one or more `Assembly` instances to a `Container`,
+/// which registers dependencies and performs any necessary setup.
 public class Assembler {
     /// The `Container` instance that dependencies are assembled into.
     let container: Container
-    
+
     /// A `Resolver` instance that provides access to the assembled dependencies.
+    /// This property returns the `Container` itself, as it conforms to the `Resolver` protocol.
     var resolver: Resolver { container }
 
     /// Initializes an `Assembler` with a given `Container`.
@@ -24,23 +28,35 @@ public class Assembler {
 
     /// Applies a single `Assembly` to the `Container`.
     ///
+    /// This function applies the `assemble` and `loaded` methods of the provided `Assembly` instance.
+    ///
     /// - Parameter assembly: The `Assembly` instance to apply.
     public func apply(assembly: Assembly) {
         run(assemblies: [assembly])
     }
 
     /// Applies an array of `Assembly` instances to the `Container`.
     ///
+    /// This function applies the `assemble` and `loaded` methods of each `Assembly` instance in the provided array.
+    ///
     /// - Parameter assemblies: The array of `Assembly` instances to apply.
     public func apply(assemblies: [Assembly]) {
         run(assemblies: assemblies)
     }
 
     /// Runs the assembly process for an array of `Assembly` instances.
     ///
+    /// This function iterates through the provided array of `Assembly` instances
+    /// and calls their `assemble` and `loaded` methods.
+    /// The `assemble` method registers dependencies in the `Container`,
+    /// and the `loaded` method performs any post-registration setup.
+    ///
     /// - Parameter assemblies: The array of `Assembly` instances to run.
     func run(assemblies: [Assembly]) {
+        // Iterate through the assemblies and call the assemble method on each one to register the dependencies.
         assemblies.forEach { $0.assemble(container: container) }
+        // Iterate through the assemblies again and call the loaded
+        // method on each one to perform any post-registration configuration.
         assemblies.forEach { $0.loaded(resolver: resolver) }
     }
 }

Sources/Core/Assemble/Assembler.swift

@@ -1,28 +1,42 @@
 //
-//  Assembly.swift
-//  Astroject
+// Assembly.swift
+// Astroject
 //
-//  Created by Porter McGary on 2/27/25.
+// Created by Porter McGary on 2/27/25.
 //
 
 import Foundation
 
 /// A protocol defining an assembly that configures dependencies in a `Container`.
+///
+/// The `Assembly` protocol is used to define a set of instructions for configuring
+/// dependencies within a dependency injection `Container`.
+/// Implementations of this protocol are responsible for registering dependencies and performing any necessary setup.
 public protocol Assembly {
     /// Configures dependencies within the provided `Container`.
     ///
+    /// This function is called by an `Assembler` to register dependencies in the given `Container`.
+    /// Implementations should use the `Container` to register factories and other configuration.
+    ///
     /// - Parameter container: The `Container` instance to configure.
     func assemble(container: Container)
 
     /// Called after the assembly has been loaded into the `Container`.
     ///
+    /// This function is called by an `Assembler` after all assemblies have been processed.
+    /// It allows performing any post-registration setup or configuration that requires access to
+    /// the resolved dependencies.
+    ///
     /// - Parameter resolver: The `Resolver` instance providing access to the assembled dependencies.
     func loaded(resolver: Resolver)
 }
 
 public extension Assembly {
     /// Default implementation of `loaded(resolver:)`, which does nothing.
     ///
+    /// This default implementation is provided for convenience, allowing assemblies
+    /// that do not require post-registration setup to omit implementing the `loaded` function.
+    ///
     /// - Parameter resolver: The `Resolver` instance (unused in the default implementation).
     func loaded(resolver: Resolver) {}
 }

Sources/Core/Assemble/Assembly.swift

@@ -0,0 +1,111 @@
+//
+// AstrojectError.swift
+// Astroject
+//
+// Created by Porter McGary on 2/27/25.
+//
+
+import Foundation
+
+/// Represents errors that can occur during dependency registration and resolution
+/// within the Astroject dependency injection framework.
+///
+/// This enum consolidates various error scenarios, including issues related to
+/// dependency registration, resolution, and factory execution.
+/// It conforms to `LocalizedError` to provide user-friendly error descriptions,
+/// failure reasons, and recovery suggestions.
+public enum AstrojectError: LocalizedError {
+    /// A registration is attempted with a `RegistrationKey` that already exists.
+    ///
+    /// This case indicates that a dependency registration with the same type and
+    /// optional name has already been performed.
+    case alreadyRegistered(type: String, name: String? = nil)
+
+    /// A dependency is requested but no corresponding registration is found in the container.
+    ///
+    /// This case occurs when attempting to resolve a dependency that has not been registered.
+    case noRegistrationFound
+
+    /// A circular dependency is detected during the resolution process.
+    ///
+    /// This case indicates that a chain of dependencies forms a loop, preventing successful resolution.
+    case circularDependencyDetected
+
+    /// An error occurred within the factory closure during dependency resolution.
+    ///
+    /// This case wraps an underlying error that occurred while executing the factory
+    /// closure responsible for creating a dependency instance.
+    case underlyingError(Error)
+
+    /// Provides a user-friendly description of the error.
+    public var errorDescription: String? {
+        switch self {
+        case .alreadyRegistered:
+            return "A registration with the same ProductKey already exists."
+        case .noRegistrationFound:
+            return "No registration found for the requested dependency."
+        case .circularDependencyDetected:
+            return "A circular dependency was detected."
+        case .underlyingError(let error):
+            return "An error occurred within the factory closure: \(error.localizedDescription)"
+        }
+    }
+
+    /// Provides a reason for the error, explaining why it occurred.
+    public var failureReason: String? {
+        switch self {
+        case .alreadyRegistered:
+            return "Attempting to register a dependency with a ProductKey that has already been used."
+        case .noRegistrationFound:
+            return "Register the dependency before attempting to resolve it."
+        case .circularDependencyDetected:
+            return "Review your dependency graph to eliminate circular dependencies."
+        case .underlyingError:
+            return "Inspect the underlying error for more details."
+        }
+    }
+
+    /// Provides a suggestion for recovering from the error.
+    public var recoverySuggestion: String? {
+        switch self {
+        case .alreadyRegistered:
+            return "Use a different ProductKey or remove the existing registration before registering a new one."
+        case .noRegistrationFound:
+            return "Use the `register` or `registerAsync` method to register the dependency."
+        case .circularDependencyDetected:
+            // swiftlint:disable:next line_length
+            return "Break the circular dependency by introducing an abstraction or using a different dependency injection pattern or by using `postInitAction` to initialize cyclical dependencies."
+        case .underlyingError:
+            return "Check the factory closure for errors and ensure that it's correctly implemented."
+        }
+    }
+}
+
+/// Extends `AstrojectError` to conform to `Equatable` when the associated `Product` type is also `Equatable`.
+///
+/// This extension allows for easy comparison of `AstrojectError` instances based on their associated values.
+extension AstrojectError: Equatable {
+    /// Checks if two `AstrojectError` instances are equal.
+    ///
+    /// - Parameters:
+    ///   - lhs: The left-hand side `AstrojectError` instance.
+    ///   - rhs: The right-hand side `AstrojectError` instance.
+    /// - Returns: `true` if the errors are equal, `false` otherwise.
+    public static func == (lhs: AstrojectError, rhs: AstrojectError) -> Bool {
+        switch (lhs, rhs) {
+        case (.alreadyRegistered(let lhsType, let lhsName), .alreadyRegistered(let rhsType, let rhsName)):
+            // Compare the associated types and names for alreadyRegistered errors.
+            return lhsType == rhsType && lhsName == rhsName
+        case (.noRegistrationFound, .noRegistrationFound),
+             (.circularDependencyDetected, .circularDependencyDetected):
+            // noRegistrationFound and circularDependencyDetected errors are equal if they are the same case.
+            return true
+        case (.underlyingError(let lhsError), .underlyingError(let rhsError)):
+            // Compare the descriptions of the underlying errors.
+            return String(describing: lhsError) == String(describing: rhsError)
+        default:
+            // All other cases are not equal.
+            return false
+        }
+    }
+}

Sources/Core/AstrojectError.swift

@@ -1,20 +1,24 @@
 //
-//  Behavior.swift
-//  Astroject
+// Behavior.swift
+// Astroject
 //
-//  Created by Porter McGary on 2/27/25.
+// Created by Porter McGary on 2/27/25.
 //
 
 import Foundation
 
 /// Protocol for adding custom behavior to the `Container` during registration.
+///
+/// Implement this protocol to add custom logic that is executed after a registration
+/// is added to the dependency injection container.
+/// This can be useful for logging, analytics, or other side effects related to the registration process.
 public protocol Behavior {
     /// Called after a registration has been added to the `Container`.
     ///
     /// - Parameters:
     ///   - type: The type of the product being registered.
     ///   - container: The `Container` instance to which the registration was added.
-    ///   - registration: The `Registration` instance that was added.
+    ///   - registration: The `Registrable` instance that was added.
     ///   - name: An optional name associated with the registration.
     func didRegister<Product>(
         type: Product.Type,