Add mock generation for @Instantiable types

Documentation/Manual.md

@@ -469,6 +469,118 @@ public struct ParentView: View, Instantiable {
 }
 ```
 
+## Mock generation
+
+SafeDI can automatically generate `mock()` methods for every `@Instantiable` type, drastically simplifying testing and SwiftUI previews. Mock generation requires a `@SafeDIConfiguration` enum to be present. When one exists, mock generation is enabled by default (controlled by the `generateMocks` property).
+
+### Configuration
+
+```swift
+@SafeDIConfiguration
+enum MyConfiguration {
+    static let additionalImportedModules: [StaticString] = []
+    static let additionalDirectoriesToInclude: [StaticString] = []
+    static let generateMocks: Bool = true
+    static let mockConditionalCompilation: StaticString? = "DEBUG"
+}
+```
+
+- `generateMocks`: Set to `false` to disable mock generation entirely.
+- `mockConditionalCompilation`: The `#if` flag wrapping generated mocks. Default is `"DEBUG"`. Set to `nil` to generate mocks without conditional compilation.
+
+### Using generated mocks
+
+Each `@Instantiable` type gets a `mock()` static method that builds its full dependency subtree. If the decorated type declaration already contains a `static func mock(...)` or `class func mock(...)` method, SafeDI will not generate a mock file for that type — your hand-written mock takes precedence. However, parent types that instantiate the child will call `ChildType.mock(...)` instead of `ChildType(...)` when constructing it, threading mock parameters through your custom method. Note that mocks defined in separate extensions are not detected; the method must be in the `@Instantiable`-decorated declaration body.
+
+Your user-defined `mock()` method must be `public` (or `open`) and must accept parameters for each of the type's `@Instantiated`, `@Received`, and `@Forwarded` dependencies. It may also accept additional parameters with default values. The `@Instantiable` macro validates these requirements and provides fix-its for any issues.
+
+```swift
+#if DEBUG
+#Preview {
+    MyView.mock()
+}
+#endif
+```
+
+Every dependency in the tree can be overridden via optional closure parameters:
+
+```swift
+let view = MyView.mock(
+    sharedThing: { _ in CustomSharedThing() }
+)
+```
+
+### Path enums
+
+Each `@Instantiable` type with dependencies gets a `SafeDIMockPath` enum containing nested enums per dependency type. The enum is named after the type, and each case describes where in the tree that dependency is created:
+
+- `case root` — the dependency is created at the top level of the mock
+- `case childA` — the dependency is created inside the `childA` property's scope
+
+This lets you differentiate when the same type is instantiated at multiple tree locations:
+
+```swift
+let root = Root.mock(
+    cache: { path in
+        switch path {
+        case .root: return Cache(size: 100)
+        case .childA: return Cache(size: 200)
+        }
+    }
+)
+```
+
+### @Forwarded properties in mocks
+
+`@Forwarded` properties become required parameters on the mock method (no default value), since they represent runtime input:
+
+```swift
+let noteView = NoteView.mock(userName: "Preview User")
+```
+
+### Default-valued init parameters in mocks
+
+If an `@Instantiable` type's initializer has parameters with default values that are not annotated with `@Instantiated`, `@Received`, or `@Forwarded`, those parameters are automatically exposed in the generated `mock()` method. This lets you override values like feature flags or optional view models in tests while keeping the original defaults for production code.
+
+```swift
+@Instantiable
+public struct ProfileView: Instantiable {
+    public init(user: User, showDebugInfo: Bool = false) {
+        self.user = user
+    }
+    @Received let user: User
+}
+```
+
+The generated mock for a parent that instantiates `ProfileView` will include `showDebugInfo` as an optional closure parameter:
+
+```swift
+let root = Root.mock(
+    showDebugInfo: { _ in true }  // Override the default
+)
+```
+
+When no override is provided, the original default expression (`false`) is used.
+
+Default-valued parameters bubble transitively through the dependency tree — a grandchild's default parameter will appear at the root mock level. However, they do **not** bubble through `Instantiator`, `SendableInstantiator`, `ErasedInstantiator`, or `SendableErasedInstantiator` boundaries, since those represent user-provided closures that control construction at runtime.
+
+### The `mockAttributes` parameter
+
+When a type's initializer is bound to a global actor that the plugin cannot detect (e.g. inherited `@MainActor`), use `mockAttributes` to annotate the generated mock:
+
+```swift
+@Instantiable(mockAttributes: "@MainActor")
+public final class MyPresenter: Instantiable { ... }
+```
+
+### Multi-module mock generation
+
+To generate mocks for non-root modules, add the `SafeDIGenerator` plugin to all first-party targets in your `Package.swift`. Each module's mocks are scoped to its own types to avoid duplicates.
+
+Each module that generates mocks must have its own `@SafeDIConfiguration` with `generateMocks: true`. When no configuration exists, mock generation is disabled by default.
+
+**Note:** Mock generation only creates mocks for types defined in the current module. Types from dependent modules or `additionalDirectoriesToInclude` are not mocked — each module must have its own `SafeDIGenerator` plugin to generate mocks for its types.
+
 ## Comparing SafeDI and Manual Injection: Key Differences
 
 SafeDI is designed to be simple to adopt and minimize architectural changes required to get the benefits of a compile-time safe DI system. Despite this design goal, there are a few key differences between projects that utilize SafeDI and projects that don’t. As the benefits of this system are clearly outlined in the [Features](../README.md#features) section above, this section outlines the pattern changes required to utilize a DI system like SafeDI.

Examples/Example Package Integration/Package.swift

@@ -52,6 +52,9 @@ let package = Package(
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIGenerator", package: "SafeDI"),
+			],
 		),
 		.target(
 			name: "ChildBModule",
@@ -63,6 +66,9 @@ let package = Package(
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIGenerator", package: "SafeDI"),
+			],
 		),
 		.target(
 			name: "ChildCModule",
@@ -74,6 +80,9 @@ let package = Package(
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIGenerator", package: "SafeDI"),
+			],
 		),
 		.target(
 			name: "GrandchildrenModule",
@@ -84,13 +93,19 @@ let package = Package(
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIGenerator", package: "SafeDI"),
+			],
 		),
 		.target(
 			name: "SharedModule",
 			dependencies: ["SafeDI"],
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIGenerator", package: "SafeDI"),
+			],
 		),
 	],
 )

Examples/ExampleMultiProjectIntegration/ExampleMultiProjectIntegration.xcodeproj/project.pbxproj

@@ -18,6 +18,7 @@
 		3289B4082BF955720053F2E4 /* Subproject.framework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 3289B4012BF955710053F2E4 /* Subproject.framework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		3289B40D2BF955A10053F2E4 /* StringStorage.swift in Sources */ = {isa = PBXBuildFile; fileRef = 324F1ECC2B314DB20001AC0C /* StringStorage.swift */; };
 		3289B40F2BF955A10053F2E4 /* UserService.swift in Sources */ = {isa = PBXBuildFile; fileRef = 324F1ECA2B314D8D0001AC0C /* UserService.swift */; };
+		BB000003BBBBBBBB00000001 /* SafeDIConfiguration.swift in Sources */ = {isa = PBXBuildFile; fileRef = BB000004BBBBBBBB00000001 /* SafeDIConfiguration.swift */; };
 		32B72E192D39763900F5EB6F /* SafeDI in Frameworks */ = {isa = PBXBuildFile; productRef = 32B72E182D39763900F5EB6F /* SafeDI */; };
 		32B72E1B2D39764200F5EB6F /* SafeDI in Frameworks */ = {isa = PBXBuildFile; productRef = 32B72E1A2D39764200F5EB6F /* SafeDI */; };
 /* End PBXBuildFile section */
@@ -47,9 +48,9 @@
 /* End PBXCopyFilesBuildPhase section */
 
 /* Begin PBXFileReference section */
+		324F1EBF2B314E030001AC0C /* SafeDIConfiguration.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SafeDIConfiguration.swift; sourceTree = "<group>"; };
 		324F1ECA2B314D8D0001AC0C /* UserService.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UserService.swift; sourceTree = "<group>"; };
 		324F1ECC2B314DB20001AC0C /* StringStorage.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = StringStorage.swift; sourceTree = "<group>"; };
-		324F1EBF2B314E030001AC0C /* SafeDIConfiguration.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SafeDIConfiguration.swift; sourceTree = "<group>"; };
 		324F1ECE2B314E030001AC0C /* NameEntryView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NameEntryView.swift; sourceTree = "<group>"; };
 		324F1ED12B3150480001AC0C /* NoteView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NoteView.swift; sourceTree = "<group>"; };
 		32756FE22B24C042006BDD24 /* ExampleMultiProjectIntegration.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = ExampleMultiProjectIntegration.app; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -59,6 +60,7 @@
 		32756FED2B24C044006BDD24 /* Preview Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = "Preview Assets.xcassets"; sourceTree = "<group>"; };
 		3289B4012BF955710053F2E4 /* Subproject.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Subproject.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		3289B4032BF955720053F2E4 /* Subproject.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = Subproject.h; sourceTree = "<group>"; };
+		BB000004BBBBBBBB00000001 /* SafeDIConfiguration.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SafeDIConfiguration.swift; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -134,6 +136,7 @@
 		3289B4022BF955720053F2E4 /* Subproject */ = {
 			isa = PBXGroup;
 			children = (
+				BB000004BBBBBBBB00000001 /* SafeDIConfiguration.swift */,
 				324F1ECA2B314D8D0001AC0C /* UserService.swift */,
 				324F1ECC2B314DB20001AC0C /* StringStorage.swift */,
 				3289B4032BF955720053F2E4 /* Subproject.h */,
@@ -197,6 +200,7 @@
 			buildRules = (
 			);
 			dependencies = (
+				BB000001BBBBBBBB00000001 /* PBXTargetDependency */,
 			);
 			name = Subproject;
 			packageProductDependencies = (
@@ -281,6 +285,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				BB000003BBBBBBBB00000001 /* SafeDIConfiguration.swift in Sources */,
 				3289B40D2BF955A10053F2E4 /* StringStorage.swift in Sources */,
 				3289B40F2BF955A10053F2E4 /* UserService.swift in Sources */,
 			);
@@ -298,6 +303,10 @@
 			isa = PBXTargetDependency;
 			productRef = 32B72E1C2D39765B00F5EB6F /* SafeDIGenerator */;
 		};
+		BB000001BBBBBBBB00000001 /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			productRef = BB000002BBBBBBBB00000001 /* SafeDIGenerator */;
+		};
 /* End PBXTargetDependency section */
 
 /* Begin XCBuildConfiguration section */
@@ -629,6 +638,11 @@
 			package = 32B72E172D39763900F5EB6F /* XCLocalSwiftPackageReference "../../../SafeDI" */;
 			productName = "plugin:SafeDIGenerator";
 		};
+		BB000002BBBBBBBB00000001 /* SafeDIGenerator */ = {
+			isa = XCSwiftPackageProductDependency;
+			package = 32B72E172D39763900F5EB6F /* XCLocalSwiftPackageReference "../../../SafeDI" */;
+			productName = "plugin:SafeDIGenerator";
+		};
 /* End XCSwiftPackageProductDependency section */
 	};
 	rootObject = 32756FDA2B24C042006BDD24 /* Project object */;

Examples/ExampleMultiProjectIntegration/ExampleMultiProjectIntegration/SafeDIConfiguration.swift

@@ -28,5 +28,13 @@ enum ExampleSafeDIConfiguration {
 
 	/// Directories containing Swift files to include, relative to the executing directory.
 	/// This property only applies to SafeDI repos that utilize the SPM plugin via an Xcode project.
+	/// Needed for DI tree generation even though Subproject has its own plugin for mock generation.
 	static let additionalDirectoriesToInclude: [StaticString] = ["Subproject"]
+
+	/// Whether to generate `mock()` methods for `@Instantiable` types.
+	static let generateMocks: Bool = true
+
+	/// The conditional compilation flag to wrap generated mock code in.
+	/// Set to `nil` to generate mocks without conditional compilation.
+	static let mockConditionalCompilation: StaticString? = "DEBUG"
 }

Examples/ExampleMultiProjectIntegration/ExampleMultiProjectIntegration/Views/NameEntryView.swift

@@ -50,6 +50,8 @@ public struct NameEntryView: Instantiable, View {
 	@Received private let userService: AnyUserService
 }
 
-#Preview {
-	NameEntryView(userService: .init(DefaultUserService(stringStorage: UserDefaults.standard)))
-}
+#if DEBUG
+	#Preview {
+		NameEntryView.mock()
+	}
+#endif

Examples/ExampleMultiProjectIntegration/ExampleMultiProjectIntegration/Views/NoteView.swift

@@ -55,10 +55,8 @@ public struct NoteView: Instantiable, View {
 	@State private var note: String = ""
 }
 
-#Preview {
-	NoteView(
-		userName: "dfed",
-		userService: .init(DefaultUserService(stringStorage: UserDefaults.standard)),
-		stringStorage: UserDefaults.standard,
-	)
-}
+#if DEBUG
+	#Preview {
+		NoteView.mock(userName: "dfed")
+	}
+#endif

Examples/ExampleMultiProjectIntegration/Subproject/SafeDIConfiguration.swift

@@ -0,0 +1,36 @@
+// Distributed under the MIT License
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import SafeDI
+
+@SafeDIConfiguration
+enum SubprojectSafeDIConfiguration {
+	/// The names of modules to import in the generated dependency tree.
+	static let additionalImportedModules: [StaticString] = []
+
+	/// Directories containing Swift files to include, relative to the executing directory.
+	static let additionalDirectoriesToInclude: [StaticString] = []
+
+	/// Whether to generate `mock()` methods for `@Instantiable` types.
+	static let generateMocks: Bool = true
+
+	/// The conditional compilation flag to wrap generated mock code in.
+	static let mockConditionalCompilation: StaticString? = "DEBUG"
+}

Examples/ExamplePrebuiltPackageIntegration/Package.swift

@@ -52,6 +52,9 @@ let package = Package(
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIPrebuiltGenerator", package: "SafeDI"),
+			],
 		),
 		.target(
 			name: "ChildBModule",
@@ -63,6 +66,9 @@ let package = Package(
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIPrebuiltGenerator", package: "SafeDI"),
+			],
 		),
 		.target(
 			name: "ChildCModule",
@@ -74,6 +80,9 @@ let package = Package(
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIPrebuiltGenerator", package: "SafeDI"),
+			],
 		),
 		.target(
 			name: "GrandchildrenModule",
@@ -84,13 +93,19 @@ let package = Package(
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIPrebuiltGenerator", package: "SafeDI"),
+			],
 		),
 		.target(
 			name: "SharedModule",
 			dependencies: ["SafeDI"],
 			swiftSettings: [
 				.swiftLanguageMode(.v6),
 			],
+			plugins: [
+				.plugin(name: "SafeDIPrebuiltGenerator", package: "SafeDI"),
+			],
 		),
 	],
 )