feat: prepare for open source release

- add MIT license
- rewrite README with problem statement, usage docs, and architecture overview
- parameterize hardcoded paths in Ruby wrapper via environment variables
- add test suite for declaration extraction, interface rewriting, project rewriting, and string utilities
- add GitHub Actions CI workflow
- add test target to Package.swift

Author: kaanbiryol

.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build
+        run: swift build
+      - name: Test
+        run: swift test

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kaan Biryol
+
+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.

Package.swift

@@ -19,6 +19,13 @@ let package = Package(
                 .product(name: "SwiftSyntax", package: "swift-syntax"),
                 .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
                 .product(name: "SourceKittenFramework", package: "SourceKitten"),
+            ]),
+        .testTarget(
+            name: "GenerateInterfaceTests",
+            dependencies: [
+                "generateInterface",
+                .product(name: "SwiftSyntax", package: "swift-syntax"),
+                .product(name: "SwiftParser", package: "swift-syntax"),
             ])
     ]
 )

README.md

@@ -1,17 +1,98 @@
 # GenerateInterface
- 
-- `make build`
 
+A command-line tool that automatically generates Swift interface modules from compiled module interfaces using SourceKit and SwiftSyntax.
+
+## The Problem
+
+In large modular iOS codebases, modules often depend on each other's full implementations even when they only need access to the public API. This means changing an implementation detail in one module can trigger recompilation of all dependent modules, slowing down builds significantly.
+
+**Interface modules** solve this by extracting a module's public API surface into a separate, lightweight module. Dependents import the interface module instead of the full implementation, so implementation changes no longer cascade rebuilds across the dependency graph.
+
+Creating and maintaining these interface modules by hand is tedious and error-prone. This tool automates the process.
+
+## What It Does
+
+Given a module name and its compiler arguments, the tool:
+
+1. **Extracts the module interface** via SourceKit (the same engine Xcode uses for code completion and indexing)
+2. **Rewrites the interface** using SwiftSyntax - strips private/internal imports (prefixed with `_`), removes `some`/`any` type erasure wrappers, simplifies member type syntax, filters out builder classes, and merges duplicate extensions
+3. **Replaces declarations** with their original source versions when available (preserving doc comments, attributes, and formatting)
+4. **Creates the interface module directory** with `Sources/` and `TestSupport/` folders
+5. **Rewrites import statements** across the codebase (`import Module` -> `import ModuleInterface`)
+6. **Updates Project.swift** to register the new interface module with the correct dependencies (Tuist-specific)
+
+## Requirements
+
+- macOS 13+
+- Xcode (for SourceKit)
+- Swift 5.10+
+
+## Installation
+
+```bash
+# Build from source
+swift build -c release
+
+# Or use the Makefile (builds for arm64)
+make build
 ```
+
+## Usage
+
+### Direct invocation
+
+```bash
 ./generateInterface \
-  "PROJECT.SWIFT_FILE_PATH" \
-  "MODULE_NAME" \
-  "PATH_TO_MODULES" \
-  --target "arm64-apple-ios16.0.0" \
-  --sdk "/Applications/Xcode-15.4.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS17.5.sdk" \
-  --build-dir "/Users/USER/Library/Developer/Xcode/DerivedData/App-xxx/Build/Products/Debug-iphoneos"
+    "/path/to/Project.swift" \
+    "MyModule" \
+    "/path/to/modules" \
+    "/path/to/compiler-args.txt"
+```
+
+**Arguments:**
+- `projectSwiftPath` - path to the Tuist `Project.swift` file
+- `moduleName` - name of the module to generate an interface for
+- `modulesPath` - root directory containing all modules
+- `compilerArgsPath` - path to a file containing Swift compiler arguments (one per line)
+
+**Flags:**
+- `--print-only` - preview the generated interface without writing any files
+
+### With the Ruby wrapper
+
+The included `generateInterface.rb` script automates compiler argument extraction from Xcode build settings:
+
+```bash
+ruby generateInterface.rb MyModule
+ruby generateInterface.rb MyModule --print-only
+```
+
+The wrapper:
+1. Runs `xcodebuild -showBuildSettingsForIndex` for the module's scheme
+2. Extracts Swift compiler arguments from the build settings
+3. Caches build settings to avoid repeated Xcode calls
+4. Invokes the Swift tool with the extracted arguments
+
+Configure the wrapper by setting these environment variables:
+- `WORKSPACE` - Xcode workspace name (default: `App.xcworkspace`)
+- `TOOL_PATH` - path to the built `generateInterface` binary (default: `tools/generateInterface`)
+- `MODULES_PATH` - path to the modules directory (default: `libraries`)
+
+## How It Works
+
+The core pipeline uses two Apple frameworks:
+
+- **SourceKittenFramework** - sends a `source.request.editor.open.interface` request to Xcode's SourceKit daemon, which returns the full public interface of a compiled module (the same text you see in Xcode's "Generated Interface" view)
+- **SwiftSyntax** - parses and rewrites the generated interface at the AST level, ensuring transformations are structurally correct rather than fragile string replacements
+
+The `ProjectRewriter` manipulates Tuist's `Module(...)` declarations via SwiftSyntax to add the new interface module definition, update dependency lists, and wire up test support targets.
+
+## Limitations
 
-   complierArgsFilePath instead of target, sdk and build-dir as an argument
+- The `Project.swift` rewriting is specific to a Tuist project structure using `Module(...)` declarations with `kind`, `moduleDependencies`, and `features` parameters. You may need to adapt `ProjectRewriter.swift` for your project's conventions.
+- The Ruby wrapper assumes an Xcode workspace-based project. Adjust if using a different build system.
+- Builder class filtering (`classes inheriting from Builder are excluded`) is project-specific behavior.
 
-  ```
+## License
 
+MIT - see [LICENSE](LICENSE).

Tests/GenerateInterfaceTests/DeclarationExtractorTests.swift

@@ -0,0 +1,121 @@
+import XCTest
+import SwiftSyntax
+import SwiftParser
+@testable import generateInterface
+
+final class DeclarationExtractorTests: XCTestCase {
+    func testExtractsStructDeclarations() {
+        let source = """
+        public struct MyModel {
+            let name: String
+        }
+        """
+        let declarations = extractDeclarations(from: source)
+        XCTAssertEqual(declarations.count, 1)
+        XCTAssertTrue(declarations[0].is(StructDeclSyntax.self))
+    }
+
+    func testExtractsClassDeclarations() {
+        let source = """
+        public class MyService {
+            func doWork() {}
+        }
+        """
+        let declarations = extractDeclarations(from: source)
+        XCTAssertEqual(declarations.count, 1)
+        XCTAssertTrue(declarations[0].is(ClassDeclSyntax.self))
+    }
+
+    func testExtractsProtocolDeclarations() {
+        let source = """
+        public protocol MyProtocol {
+            func execute()
+        }
+        """
+        let declarations = extractDeclarations(from: source)
+        XCTAssertEqual(declarations.count, 1)
+        XCTAssertTrue(declarations[0].is(ProtocolDeclSyntax.self))
+    }
+
+    func testExtractsEnumDeclarations() {
+        let source = """
+        public enum State {
+            case active
+            case inactive
+        }
+        """
+        let declarations = extractDeclarations(from: source)
+        XCTAssertEqual(declarations.count, 1)
+        XCTAssertTrue(declarations[0].is(EnumDeclSyntax.self))
+    }
+
+    func testExtractsTypealiasDeclarations() {
+        let source = """
+        public typealias Handler = (String) -> Void
+        """
+        let declarations = extractDeclarations(from: source)
+        XCTAssertEqual(declarations.count, 1)
+        XCTAssertTrue(declarations[0].is(TypeAliasDeclSyntax.self))
+    }
+
+    func testExtractsExtensionDeclarations() {
+        let source = """
+        extension String {
+            var isEmpty: Bool { count == 0 }
+        }
+        """
+        let declarations = extractDeclarations(from: source)
+        XCTAssertEqual(declarations.count, 1)
+        XCTAssertTrue(declarations[0].is(ExtensionDeclSyntax.self))
+    }
+
+    func testExtractsMultipleDeclarations() {
+        let source = """
+        public struct MyModel {
+            let name: String
+        }
+        public protocol MyProtocol {
+            func execute()
+        }
+        public enum State {
+            case active
+        }
+        extension MyModel: MyProtocol {
+            func execute() {}
+        }
+        """
+        let declarations = extractDeclarations(from: source)
+        XCTAssertEqual(declarations.count, 4)
+    }
+
+    func testSkipsChildDeclarations() {
+        let source = """
+        public struct Outer {
+            struct Inner {
+                let value: Int
+            }
+            let inner: Inner
+        }
+        """
+        let declarations = extractDeclarations(from: source)
+        // Should only extract Outer, not Inner (skipChildren)
+        XCTAssertEqual(declarations.count, 1)
+    }
+
+    func testIgnoresFunctionDeclarations() {
+        let source = """
+        func topLevelFunction() {}
+        """
+        let declarations = extractDeclarations(from: source)
+        XCTAssertEqual(declarations.count, 0)
+    }
+
+    // MARK: - Helpers
+
+    private func extractDeclarations(from source: String) -> [DeclSyntax] {
+        let sourceFile = Parser.parse(source: source)
+        let extractor = DeclarationExtractor(viewMode: .sourceAccurate)
+        extractor.walk(sourceFile)
+        return extractor.extractedDeclarations
+    }
+}

Tests/GenerateInterfaceTests/ModuleInterfaceRewriterTests.swift

@@ -0,0 +1,114 @@
+import XCTest
+@testable import generateInterface
+
+final class ModuleInterfaceRewriterTests: XCTestCase {
+    func testRemovesUnderscoreImports() {
+        let source = """
+        import Foundation
+        import _Concurrency
+        import _StringProcessing
+        import UIKit
+
+        public struct MyModel {}
+        """
+        let result = rewriteModuleInterface(sourceText: source, additionalFiles: [], moduleName: "MyModule")!
+        XCTAssertTrue(result.contains("import Foundation"))
+        XCTAssertTrue(result.contains("import UIKit"))
+        XCTAssertFalse(result.contains("_Concurrency"))
+        XCTAssertFalse(result.contains("_StringProcessing"))
+    }
+
+    func testRemovesSomeKeyword() {
+        let source = """
+        import Foundation
+
+        public struct MyView {
+            public var body: some View { fatalError() }
+        }
+        """
+        let result = rewriteModuleInterface(sourceText: source, additionalFiles: [], moduleName: "MyModule")!
+        XCTAssertFalse(result.contains("some View"))
+        XCTAssertTrue(result.contains("View"))
+    }
+
+    func testRemovesAnyKeyword() {
+        let source = """
+        import Foundation
+
+        public func handle(error: any Error) {}
+        """
+        let result = rewriteModuleInterface(sourceText: source, additionalFiles: [], moduleName: "MyModule")!
+        XCTAssertFalse(result.contains("any Error"))
+        XCTAssertTrue(result.contains("Error"))
+    }
+
+    func testRemovesBuilderClasses() {
+        let source = """
+        import Foundation
+
+        public class MyService {}
+        public class MyBuilder: Builder {}
+        """
+        let result = rewriteModuleInterface(sourceText: source, additionalFiles: [], moduleName: "MyModule")!
+        XCTAssertTrue(result.contains("MyService"))
+        XCTAssertFalse(result.contains("MyBuilder"))
+    }
+
+    func testSimplifiesMemberTypeSyntax() {
+        let source = """
+        import Foundation
+
+        public func getValue() -> Swift.String { "" }
+        """
+        let result = rewriteModuleInterface(sourceText: source, additionalFiles: [], moduleName: "MyModule")!
+        // MemberTypeSyntax (Swift.String) should be simplified to just the name (String)
+        XCTAssertTrue(result.contains("String"))
+    }
+
+    func testPreservesRegularImports() {
+        let source = """
+        import Foundation
+        import UIKit
+        import Combine
+
+        public struct MyModel {}
+        """
+        let result = rewriteModuleInterface(sourceText: source, additionalFiles: [], moduleName: "MyModule")!
+        XCTAssertTrue(result.contains("import Foundation"))
+        XCTAssertTrue(result.contains("import UIKit"))
+        XCTAssertTrue(result.contains("import Combine"))
+    }
+
+    func testReplacesDeclarationsWithSourceVersions() throws {
+        let interfaceSource = """
+        import Foundation
+
+        public struct MyModel {
+            public let id: String
+            public let name: String
+        }
+        """
+
+        // Create a temp file with the "source" version of the declaration
+        let sourceContent = """
+        /// A model representing a user.
+        public struct MyModel {
+            public let id: String
+            public let name: String
+
+            public init(id: String, name: String) {
+                self.id = id
+                self.name = name
+            }
+        }
+        """
+        let tempFile = NSTemporaryDirectory() + "TestSource.swift"
+        try sourceContent.write(toFile: tempFile, atomically: true, encoding: .utf8)
+        defer { try? FileManager.default.removeItem(atPath: tempFile) }
+
+        let result = rewriteModuleInterface(sourceText: interfaceSource, additionalFiles: [tempFile], moduleName: "MyModule")!
+        // Should use the source version which includes the doc comment and init
+        XCTAssertTrue(result.contains("A model representing a user"))
+        XCTAssertTrue(result.contains("public init"))
+    }
+}