expo-modules-macros 0.25.0 → 0.27.0

package/AGENTS.md

@@ -5,10 +5,10 @@
 ## Layout
 
 - `apple/Package.swift`: the SwiftPM package. The test targets are declared only when `apple/Tests` exists, because the published npm package leaves it out.
-- `apple/Sources/ExpoModulesMacros`: the macro implementations. `Plugin.swift` registers every macro in `providingMacros` and holds the entry point that sends any invocation with arguments to the scanner CLI.
-- `apple/Sources/ExpoModulesScanner`: the scanner library. `Modules/` implements `scan-modules` (autolinking), `Exports/` implements `scan-exports` (type generation), `Core/` holds the shared parsing and `#if` evaluation, and `CLI.swift` is the command-line front end.
+- `apple/Sources/ExpoModulesMacros`: the compiler plugin executable. `Plugin.swift` registers the macros of `ProvidedMacro.all` in `providingMacros` and holds the entry point that sends any invocation with arguments to the CLI. `Macros/` holds one file per macro, and `Support/` the code that several macros share. `ProvidedMacros.swift` lists every macro with its attribute name and conformances in `ProvidedMacro.all`, and `Expand/MacroExpander.swift` runs the macros in process for `expand`, because only this executable target can see them.
+- `apple/Sources/ExpoModulesCLI`: the library behind the command-line tool. `CLI.swift` parses the arguments, `Commands/` holds one directory per subcommand (`ScanModules/` for autolinking, `ScanExports/` for type generation, `Expand/` for the report types and the output of `expand`, which gets the expansion from the executable as a `MacroExpander`), and `Core/` holds the shared parsing, `#if` evaluation and output.
 - `apple/Sources/ExpoModulesOptimized`: declarations for the `@OptimizedFunction` macro.
-- `apple/Tests`: `ExpoModulesMacrosTests` (expansion tests) and `ExpoModulesScannerTests`.
+- `apple/Tests`: `ExpoModulesMacrosTests` (expansion tests) and `ExpoModulesCLITests`.
 - `platforms/`: the Windows packages `@expo/modules-macros-win32-x64` and `-arm64`, and the Linux packages `@expo/modules-macros-linux-x64` and `-arm64` (a `package.json` with `os` and `cpu`, plus `libc` on Linux, a README and a copy of `LICENSE`). The Publish workflow runs `scripts/set-platform-versions.js` to give them the version of this package. Their `ExpoModulesMacros.exe` (Windows) or `ExpoModulesMacros` (Linux) is written there by `pnpm run build` on that platform and isn't committed.
 - `apple/PodTests`: a stub test so that `expo/expo` native tests can install this package as a pod. Do not add real tests here.
 - `src/`: the TypeScript wrapper around the scanner CLI. `types.ts` mirrors the Swift `Codable` output types by hand.
@@ -48,21 +48,21 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 - Write new doc comments as `///` line comments, not `/** */` blocks.
 - Tests use Swift Testing (`import Testing`, `@Test`) with backtick-quoted descriptive names, for example ``func `Prunes .build, Pods, .git, and node_modules directories`()``.
 - Macro tests compare full expansions with `assertMacroExpansion` from `SwiftSyntaxMacrosGenericTestSupport`, using `indentationWidth: .spaces(2)`. Each test file wraps it in a local `assertExpansion` helper that passes `recordIssue` (`IssueRecording.swift`) as the failure handler.
-- Scanner tests reach internal API with `@testable import ExpoModulesScanner`. Do not make scanner types `public` only for tests.
+- CLI tests reach internal API with `@testable import ExpoModulesCLI`. Do not make its types `public` only for tests.
 - `@JS` applies to functions, properties and initializers. Do not write code or comments that assume it marks only functions.
 - Code comments describe the code as it is. Do not refer to open PRs, branches or planned work.
 
 ## Changing macros
 
 - The scanner re-implements the macros' naming and member rules on the syntax tree; it does not call the macro code. When a macro changes which members it binds or how it names them (the `@JS` name override, the `on` prefix `@Event` strips, which properties `@Record` treats as fields), change `scan-exports` to match, or generated TypeScript types drift from the runtime.
-- The scanner only parses files that pass the pre-filter, `MacroPrefilter` in `Core/SourceScan.swift`. Each command builds it from the `macros` and `conformances` arguments of its `scanFiles` call. A new attribute or conformance the scanner must detect has to be added to those arguments (an attribute also needs a `DetectedMacro` case), or files that use it are skipped without an error.
-- A new macro needs: the implementation in `apple/Sources/ExpoModulesMacros`, an entry in `providingMacros` in `Plugin.swift`, an expansion test file, the `#externalMacro` declaration in `expo-modules-core`, and an entry in the macro list in `README.md`.
+- The scanner only parses files that pass the pre-filter, `MacroPrefilter` in `ExpoModulesCLI/Core/SourceScan.swift`. Each command builds it from the `macros` and `conformances` arguments of its `scanFiles` call. A new attribute or conformance the scanner must detect has to be added to those arguments (an attribute also needs a `DetectedMacro` case), or files that use it are skipped without an error.
+- A new macro needs: the implementation in `apple/Sources/ExpoModulesMacros/Macros`, an entry in `ProvidedMacro.all` in `ProvidedMacros.swift` (with the attribute name and the extension conformances of its declaration), an expansion test file, the `#externalMacro` declaration in `expo-modules-core`, and an entry in the macro list in `README.md`.
 
 ## Contracts with other packages
 
-- **Macro declarations live in `expo-modules-core`** (`ios/Core/ExpoModulesMacros.swift` in `expo/expo`), as `#externalMacro(module: "ExpoModulesMacros", type: ...)`. Adding a macro, renaming a macro type or changing a macro's signature needs a matching edit there, and the type must be listed in `providingMacros` in `Plugin.swift`.
+- **Macro declarations live in `expo-modules-core`** (`ios/Core/ExpoModulesMacros.swift` in `expo/expo`), as `#externalMacro(module: "ExpoModulesMacros", type: ...)`. Adding a macro, renaming a macro type or changing a macro's signature needs a matching edit there, and the type must be listed in `ProvidedMacro.all` in `ProvidedMacros.swift`, with the same attribute name and extension conformances as the declaration.
 - **Generated code calls `expo-modules-core` API.** An expansion that uses a new core symbol only works with a core version that has it.
-- **Scanner output is versioned.** `scanModulesSchemaVersion` (`Modules/ScanModules.swift`) and `scanExportsSchemaVersion` (`Exports/ExportedSurface.swift`) change independently. When the output shape of a command changes, bump its version and update the matching `SUPPORTED_SCAN_*_SCHEMA_VERSION` constant and mirror types in `src/types.ts`. `expo-modules-autolinking` also checks the `scan-modules` version.
+- **Scanner output is versioned.** `scanModulesSchemaVersion` (`Commands/ScanModules/ScanModules.swift`), `scanExportsSchemaVersion` (`Commands/ScanExports/ExportedSurface.swift`) and `expandSchemaVersion` (`Commands/Expand/ExpandReport.swift`) change independently. When the output shape of a command changes, bump its version and update the matching `SUPPORTED_*_SCHEMA_VERSION` constant and mirror types in `src/types.ts`. `expo-modules-autolinking` also checks the `scan-modules` version.
 - **The binary path is part of the contract.** `expo-modules-autolinking` resolves this package from `expo-modules-core` and passes `-load-plugin-executable <package>/apple/<binary>#ExpoModulesMacros` to the compiler. The scanner wrapper in autolinking uses the same path, and `expo-modules-cli` uses `getScannerBinaryPath()`. On Windows the binary is `ExpoModulesMacros.exe` in `@expo/modules-macros-win32-<arch>`, and on Linux `ExpoModulesMacros` in `@expo/modules-macros-linux-<arch>`. Renaming or moving a binary needs a matching change in `expo/expo`.
 
 ## Releases

package/README.md

@@ -25,12 +25,14 @@ This package lists them as optional dependencies, and their `os`, `cpu` and (on
 # Macros
 
 - **`@ExpoModule(_ name: String? = nil, classes: [Any.Type] = [])`** on a class. Turns the class into a module: binds its `@JS` members into the module's JavaScript object and resolves the module name from the argument, falling back to the class name. It also synthesizes everything inheriting from `Module` used to provide, so a module class can carry any superclass, or none.
-- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. A `lazy var` is read-only from JavaScript. On the first read, its getter stores the value as a data property on the JavaScript object, so later reads don't call into native code. On a frozen object the value isn't stored, and each read calls the getter. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol or the module's default isolation, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
+- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. The macro also checks that every type crossing the boundary is convertible in the direction it travels. Outside a module or shared object, a bad type is reported on the author's own declaration. In an `@ExpoModule` or `@SharedObject` class, the class macro makes the check, since only it sees the type aliases in the class body, so the error is reported on the class and names the member and its argument labels, such as `local function 'move(_:by:returning:)' requires that 'Point' conform to 'JavaScriptEncodable'`. A `lazy var` is read-only from JavaScript. On the first read, its getter stores the value as a data property on the JavaScript object, so later reads don't call into native code. On a frozen object the value isn't stored, and each read calls the getter. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol or the module's default isolation, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
 - **`@Event(_ name: String? = nil, sync: Bool = false)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. `sync: true` dispatches inline instead of asynchronously.
 - **`@SharedObject(_ name: String? = nil)`** on a subclass of `SharedObject`, direct or not, such as a `SharedRef<T>` subclass. Binds the class's `@JS` members through the `SharedObject` hooks that core calls when it builds the JavaScript class, and emits the JS class name, which defaults to the class name. A module exposes the class through `@ExpoModule(classes:)`, which only accepts `SharedObject` subclasses.
 - **`@Record()`** on a struct, or on a final class with no inheritance clause (declare a class's protocol conformances in an extension). Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.
 - **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first.
 
+A tuple can cross the boundary as a `@JS` argument, result or property, a `@Record` property, a `@Union` payload, an `@Event` payload, or a parameter or result of a closure argument that isn't `async`. An unlabeled tuple such as `(Int, String)` maps to an array with one value per element, and a labeled tuple such as `(x: Double, y: Double)` to an object with one property per label. A tuple must have two or more elements, all labeled or none, and each element must be convertible. Tuples nest in other tuples, optionals, arrays and `String`-keyed dictionaries. `@ExpoModule` and `@SharedObject` also resolve a type alias of a tuple, such as `typealias Span = (start: Int, end: Int)`, when the class body declares it. A macro sees only the declaration it is attached to, so an alias declared anywhere else doesn't resolve.
+
 How that looks in a module:
 
 ```swift
@@ -72,22 +74,57 @@ ExpoModulesMacros <subcommand> [options] <path> [<path> ...]
 subcommands:
   scan-modules   fast scan for top-level @ExpoModule types (autolinking)
   scan-exports   deep scan of the full JS-exported surface (type generation)
+  expand         print the code that the macros generate, and the macro diagnostics
 
 options (scan-modules only):
   --define <flag>   treat a conditional compilation flag as set; repeatable
+
+options (expand only):
+  --symbol <name>      only a type ('MyModule', 'MyModule.Options') or a member ('MyModule.greet'); repeatable
+  --diagnostics-only   only the diagnostics, followed by a summary
+  --json               a JSON report instead of text
+```
+
+For the scans, each path is a `.swift` file or a directory, scanned recursively for `.swift` files. Both scans print a JSON report to stdout, each carrying its own `schemaVersion` so a consumer can check it understands the shape before trusting it. The two versions are independent: the commands serve different consumers and change for different reasons.
+
+## Expand
+
+`expand` shows the code that the macros generate, as "Expand Macro" does in Xcode, but in a terminal and without a build. It takes `.swift` files and directories, runs the macros of this executable on them in process with swift-syntax, and prints the expanded source to stdout. The syntax errors and the macro diagnostics go to stderr in the compiler's `<file>:<line>:<column>: error: <message>` format, and the exit code is `1` when there is an error. With `--diagnostics-only`, it prints only the diagnostics, so it can check a module in CI or for an agent.
+
+```sh
+ExpoModulesMacros expand ios/HapticsModule.swift
+ExpoModulesMacros expand --symbol HapticsModule.impactAsync ios/HapticsModule.swift
+ExpoModulesMacros expand --diagnostics-only ios/
 ```
 
-Each path is a `.swift` file or a directory, scanned recursively for `.swift` files. Both subcommands print a JSON report to stdout, each carrying its own `schemaVersion` so a consumer can check it understands the shape before trusting it. The two versions are independent: the commands serve different consumers and change for different reasons.
+A file is always expanded and keeps its path as it was passed. A directory is walked like the scans walk it, skipping dependency, build, test and example directories, and only its files that use one of the macros are expanded, with their absolute paths.
+
+`--symbol` limits the output to one declaration:
+
+- A type (`HapticsModule`, `HapticsModule.ImpactStyle`) prints the expanded type and the extensions that its macros add.
+- A member (`HapticsModule.impactAsync`, `HapticsModule.init`) prints its type, expanded with only the declarations of that name (all overloads). So `_decorateModule` holds only the code for that member.
+
+With `--symbol`, only the diagnostics inside those declarations are printed.
+
+With `--json`, `expand` prints an `ExpandResult` with its own `schemaVersion`, and the exit code is `0` also with error diagnostics, because the report holds them. A missing path, a file that isn't Swift, or a symbol that no file declares is a usage error (`2`) in both modes.
+
+The macros only read the syntax tree, so the expansion is what the compiler gets, with two differences:
+
+- The names that a macro makes unique (`makeUniqueName`) can differ.
+- The compiler passes an extension macro only the conformances that the type doesn't have yet. `expand` passes all of them, and the macros skip the ones in the inheritance clause, so the result differs only for a conformance inherited from somewhere else.
+
+Errors that need type checking, for example the conformance assertions in `_assertTypesConformance`, still need a build.
 
 # TypeScript wrapper
 
 Node consumers can call the scanner through this package instead of locating the binary and shelling out themselves:
 
 ```ts
-import { scanModules, scanExports } from 'expo-modules-macros';
+import { expandMacros, scanModules, scanExports } from 'expo-modules-macros';
 
 const { modules, warnings } = await scanModules(['ios/'], { defines: ['DEBUG'], timeout: 30_000 });
 const { exports } = await scanExports(['ios/']);
+const { files } = await expandMacros(['ios/HapticsModule.swift'], { symbols: ['HapticsModule.impactAsync'] });
 ```
 
 The binary is a compiled executable, so each call still spawns a process. What the wrapper owns is the part consumers would otherwise duplicate: resolving the shipped binary, building the arguments, parsing the JSON, checking `schemaVersion`, and turning a non-zero exit or an exceeded `timeout` into a `ScannerError`. The result types are hand-written mirrors of the Swift `Codable` types, which is what the version check guards against drifting.

package/apple/Package.swift

@@ -20,13 +20,18 @@ let package = Package(
     .macro(
       name: "ExpoModulesMacros",
       dependencies: [
-        "ExpoModulesScanner",
+        "ExpoModulesCLI",
         .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
         .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
+        // For `expand`, which runs the macros in process.
+        .product(name: "SwiftSyntaxMacroExpansion", package: "swift-syntax"),
+        .product(name: "SwiftParser", package: "swift-syntax"),
+        .product(name: "SwiftParserDiagnostics", package: "swift-syntax"),
+        .product(name: "SwiftBasicFormat", package: "swift-syntax"),
       ]
     ),
     .target(
-      name: "ExpoModulesScanner",
+      name: "ExpoModulesCLI",
       dependencies: [
         .product(name: "SwiftSyntax", package: "swift-syntax"),
         .product(name: "SwiftParser", package: "swift-syntax"),
@@ -44,15 +49,16 @@ if FileManager.default.fileExists(atPath: Context.packageDirectory + "/Tests") {
       name: "ExpoModulesMacrosTests",
       dependencies: [
         "ExpoModulesMacros",
+        "ExpoModulesCLI",
         .product(name: "SwiftSyntaxMacrosGenericTestSupport", package: "swift-syntax"),
       ]
     )
   )
   package.targets.append(
     .testTarget(
-      name: "ExpoModulesScannerTests",
+      name: "ExpoModulesCLITests",
       dependencies: [
-        "ExpoModulesScanner",
+        "ExpoModulesCLI",
         .product(name: "SwiftParser", package: "swift-syntax"),
       ]
     )

package/apple/Sources/{ExpoModulesScanner → ExpoModulesCLI}/CLI.swift

@@ -8,10 +8,15 @@
 /// Subcommands:
 ///   scan-modules   <path>...   fast: top-level `@ExpoModule` types, for autolinking
 ///   scan-exports   <path>...   deep: full JS-exported surface, for TS type generation
+///   expand         <path>...   the code that the macros generate, and their diagnostics
 public enum ScannerCLI {
   /// Runs the CLI for the given arguments (argv without the executable path) and returns the
   /// process exit code: `0` on success, `1` if encoding the report fails, `2` on a usage error.
-  public static func run(arguments: [String]) -> Int32 {
+  /// `expand` also returns `1` for an error diagnostic (see `Scanner.runExpand`).
+  ///
+  /// `expander` expands the macros for `expand`. The plugin executable passes it, because the macro
+  /// implementations live there; without it, `expand` is a usage error.
+  public static func run(arguments: [String], expander: MacroExpander? = nil) -> Int32 {
     // `-h`/`--help` anywhere is treated as a help request: print usage to stdout and exit 0.
     if arguments.contains(where: { $0 == "-h" || $0 == "--help" }) {
       writeToStandardOutput(usageText)
@@ -26,6 +31,7 @@ public enum ScannerCLI {
     var paths: [String] = []
     var platform: String?
     var defines: [String] = []
+    var expandOptions = ExpandOptions()
 
     var rest = arguments.dropFirst().makeIterator()
     while let argument = rest.next() {
@@ -40,11 +46,25 @@ public enum ScannerCLI {
           return usageError("--define requires a value")
         }
         defines.append(value)
+      case "--symbol":
+        guard let value = rest.next() else {
+          return usageError("--symbol requires a value")
+        }
+        expandOptions.symbols.append(value)
+      case "--json":
+        expandOptions.json = true
+      case "--diagnostics-only":
+        expandOptions.diagnosticsOnly = true
       default:
         paths.append(argument)
       }
     }
 
+    // The scans print JSON in any case and have no symbols to filter.
+    if subcommand != "expand" && expandOptions != ExpandOptions() {
+      return usageError("--symbol, --json and --diagnostics-only are options of expand")
+    }
+
     switch subcommand {
     case "scan-modules":
       // scan-modules is platform-agnostic: each reported module carries the platforms that include
@@ -70,6 +90,19 @@ public enum ScannerCLI {
       }
       return Scanner.runExports(paths: paths)
 
+    case "expand":
+      guard platform == nil, defines.isEmpty else {
+        return usageError("expand does not support --platform or --define")
+      }
+      guard !paths.isEmpty else {
+        return usageError("expand requires at least one path")
+      }
+      guard let expander else {
+        return usageError("expand is only available in the macro plugin executable")
+      }
+      expandOptions.paths = paths
+      return Scanner.runExpand(options: expandOptions, expander: expander)
+
     default:
       return usageError("unknown subcommand '\(subcommand)'")
     }
@@ -80,7 +113,7 @@ public enum ScannerCLI {
 /// (the `ExpoModulesMacros` shipped in the package, or a locally built `ExpoModulesMacros-tool`).
 private var toolName: String {
   guard let path = CommandLine.arguments.first else {
-    return "ExpoModulesScanner"
+    return "ExpoModulesMacros"
   }
   // Windows paths may use either separator.
   return String(path.split(whereSeparator: { $0 == "/" || $0 == "\\" }).last ?? Substring(path))
@@ -93,11 +126,21 @@ private var usageText: String {
   subcommands:
     scan-modules   fast scan for top-level @ExpoModule types (autolinking)
     scan-exports   deep scan of the full JS-exported surface (type generation)
+    expand         print the code that the macros generate in the given .swift files (and in the
+                   files of the given directories that use a macro), and the macro diagnostics
+                   on stderr; exits with 1 when there is an error
 
   options (scan-modules only):
     --define <flag>   treat a conditional compilation flag (e.g. DEBUG) as set when resolving
                       each module's 'platforms' list; repeatable
 
+  options (expand only):
+    --symbol <name>      print only the expansion of a type ('MyModule', 'MyModule.Options') or a
+                         member ('MyModule.greet'), and only its diagnostics; repeatable
+    --diagnostics-only   print only the diagnostics, followed by a summary
+    --json               print a JSON report with the expansions and diagnostics instead; exits with
+                         0 also when there is an error
+
   options:
     -h, --help        print this help and exit
 

package/apple/Sources/ExpoModulesCLI/Commands/Expand/ExpandReport.swift

@@ -0,0 +1,120 @@
+/// Version of the `expand --json` output shape. Independent of the scan schema versions: bump it when
+/// the shape of `ExpandResult` changes, together with `SUPPORTED_EXPAND_SCHEMA_VERSION` and the mirror
+/// types in `src/types.ts`.
+public let expandSchemaVersion = 1
+
+/// The JSON report of `expand --json`.
+public struct ExpandResult: Codable, Equatable, Sendable {
+  public let schemaVersion: Int
+
+  /// One entry per expanded file: the files in argument order, the files of a directory sorted.
+  public let files: [ExpandedFile]
+}
+
+/// What the macros generate for one source file, and what they report about it.
+public struct ExpandedFile: Codable, Equatable, Sendable {
+  /// The path as it was passed on the command line, or the absolute path of a file found in a
+  /// directory.
+  public let file: String
+
+  /// Without `--symbol`, one expansion of the whole file. With it, one expansion per symbol found in
+  /// this file, in the order of the options. Empty with `--diagnostics-only`.
+  public let expansions: [Expansion]
+
+  /// The syntax errors in the file and the diagnostics of the macros, in source order. With
+  /// `--symbol`, only those inside the declarations of the symbols.
+  public let diagnostics: [ExpansionDiagnostic]
+
+  public init(file: String, expansions: [Expansion], diagnostics: [ExpansionDiagnostic]) {
+    self.file = file
+    self.expansions = expansions
+    self.diagnostics = diagnostics
+  }
+}
+
+/// Expanded source code.
+public struct Expansion: Codable, Equatable, Sendable {
+  /// The `--symbol` value this expansion is for, or `nil` for the whole file.
+  public let symbol: String?
+
+  public let source: String
+
+  public init(symbol: String?, source: String) {
+    self.symbol = symbol
+    self.source = source
+  }
+}
+
+/// A diagnostic, at its location in the original source file. A diagnostic that a macro attaches to
+/// the code it generates has the location of the macro attribute.
+public struct ExpansionDiagnostic: Codable, Equatable, Sendable {
+  public enum Severity: String, Codable, Sendable {
+    case error
+    case warning
+    case note
+    case remark
+  }
+
+  public let severity: Severity
+  public let message: String
+
+  /// 1-based, as in the compiler's output. The column counts UTF-8 bytes.
+  public let line: Int
+  public let column: Int
+
+  public let notes: [ExpansionNote]
+
+  /// The messages of the Fix-Its, for example `replace 'var' with 'let'`.
+  public let fixIts: [String]
+
+  public init(
+    severity: Severity,
+    message: String,
+    line: Int,
+    column: Int,
+    notes: [ExpansionNote] = [],
+    fixIts: [String] = []
+  ) {
+    self.severity = severity
+    self.message = message
+    self.line = line
+    self.column = column
+    self.notes = notes
+    self.fixIts = fixIts
+  }
+}
+
+/// A note attached to a diagnostic, at its own location.
+public struct ExpansionNote: Codable, Equatable, Sendable {
+  public let message: String
+  public let line: Int
+  public let column: Int
+
+  public init(message: String, line: Int, column: Int) {
+    self.message = message
+    self.line = line
+    self.column = column
+  }
+}
+
+/// Expands the macros in one source file. The macro implementations live in the plugin executable,
+/// which this library can't depend on, so the executable passes this in (see `ScannerCLI`).
+public struct MacroExpander {
+  /// The attribute names of the macros, such as `ExpoModule`. A file found in a directory is expanded
+  /// only when it contains one of them after an `@`.
+  let attributeNames: Set<String>
+
+  /// - Parameters:
+  ///   - source: The contents of the file.
+  ///   - file: The path of the file, for the diagnostics and the expansion context.
+  ///   - symbols: The `--symbol` values. Empty to expand the whole file.
+  let expand: (_ source: String, _ file: String, _ symbols: [String]) -> ExpandedFile
+
+  public init(
+    attributeNames: Set<String>,
+    expand: @escaping (_ source: String, _ file: String, _ symbols: [String]) -> ExpandedFile
+  ) {
+    self.attributeNames = attributeNames
+    self.expand = expand
+  }
+}

package/apple/Sources/ExpoModulesCLI/Commands/Expand/RunExpand.swift

@@ -0,0 +1,183 @@
+#if canImport(FoundationEssentials)
+import FoundationEssentials
+#else
+import Foundation
+#endif
+
+/// The options of `expand`, parsed by `ScannerCLI`.
+struct ExpandOptions: Equatable {
+  var paths: [String] = []
+  var symbols: [String] = []
+  var json = false
+  var diagnosticsOnly = false
+}
+
+extension Scanner {
+  /// Runs `expand`: expands the macros in each file with `expander` and prints the result. A
+  /// directory stands for the `.swift` files in it that use one of the macros.
+  ///
+  /// As text, the expanded source goes to stdout and the diagnostics go to stderr in the
+  /// `<file>:<line>:<column>: <severity>: <message>` format of the compiler. The exit code is `1`
+  /// when there is an error diagnostic. With `--json`, the report goes to stdout and the exit code
+  /// is `0` also with error diagnostics, because the report holds them; `1` then means that encoding
+  /// failed. An input that can't be expanded (a missing path, a file that isn't Swift, a symbol that
+  /// no file declares) is a usage error, `2`.
+  static func runExpand(options: ExpandOptions, expander: MacroExpander) -> Int32 {
+    let result: ExpandResult
+    switch expandFiles(options: options, expander: expander) {
+    case .success(let expanded):
+      result = expanded
+    case .failure(let error):
+      writeToStandardError("error: \(error.message)\n")
+      return 2
+    }
+
+    if options.json {
+      do {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let data = try encoder.encode(result)
+        writeToStandardOutput(String(decoding: data, as: UTF8.self) + "\n")
+        return 0
+      } catch {
+        writeToStandardError("error: failed to encode results: \(error)\n")
+        return 1
+      }
+    }
+
+    writeToStandardOutput(renderExpansions(result.files))
+    writeToStandardError(renderDiagnostics(result.files))
+    if options.diagnosticsOnly {
+      writeToStandardError(renderSummary(result.files))
+    }
+    let hasErrors = result.files.contains { $0.diagnostics.contains { $0.severity == .error } }
+    return hasErrors ? 1 : 0
+  }
+}
+
+/// The absolute path of `path` with symbolic links resolved, to tell whether two paths name the same
+/// file. A path that the directory walk returns can differ from the one passed for the same file, for
+/// example `/private/var` and `/var` on macOS.
+private func fileIdentity(_ path: String) -> String {
+  URL(fileURLWithPath: path).standardizedFileURL.resolvingSymlinksInPath().path
+}
+
+/// An input that `expand` can't take.
+struct ExpandInputError: Error, Equatable {
+  let message: String
+}
+
+/// Reads the files of `options`, expands each with `expander`, and returns the report that `expand`
+/// prints. Separate from `runExpand` so tests can drive it without stdout.
+///
+/// A file keeps its path as it was passed and is always expanded. A directory is walked like the
+/// scans walk it (`swiftFiles(in:)`, which skips dependency, build, test and example directories),
+/// and only the files that use one of the macros are expanded, with their absolute paths. A file that
+/// a directory also contains is expanded once.
+func expandFiles(options: ExpandOptions, expander: MacroExpander) -> Result<ExpandResult, ExpandInputError> {
+  let prefilter = MacroPrefilter(attributeNames: expander.attributeNames)
+  var sources: [(file: String, source: String)] = []
+  var seen: Set<String> = []
+  for path in options.paths {
+    switch isDirectory(atPath: path) {
+    case nil:
+      return .failure(ExpandInputError(message: "no such file or directory '\(path)'"))
+    case .some(true):
+      for file in swiftFiles(in: [path]) where !seen.contains(fileIdentity(file)) {
+        guard let source = try? String(contentsOfFile: file, encoding: .utf8) else {
+          return .failure(ExpandInputError(message: "could not read '\(file)'"))
+        }
+        seen.insert(fileIdentity(file))
+        if mightContainMacro(in: source, prefilter: prefilter) {
+          sources.append((file, source))
+        }
+      }
+    case .some(false):
+      guard path.hasSuffix(".swift") else {
+        return .failure(ExpandInputError(message: "expand takes .swift files and directories, but got '\(path)'"))
+      }
+      guard !seen.contains(fileIdentity(path)) else {
+        continue
+      }
+      guard let source = try? String(contentsOfFile: path, encoding: .utf8) else {
+        return .failure(ExpandInputError(message: "could not read '\(path)'"))
+      }
+      seen.insert(fileIdentity(path))
+      sources.append((path, source))
+    }
+  }
+
+  let files = sources.map { expander.expand($0.source, $0.file, options.symbols) }
+
+  let found = Set(files.flatMap { $0.expansions.compactMap(\.symbol) })
+  if let missing = options.symbols.first(where: { !found.contains($0) }) {
+    return .failure(
+      ExpandInputError(
+        message: "no declaration of '\(missing)' in the given files; name a type ('Module'), a nested "
+          + "type ('Module.Options') or a member ('Module.method')"
+      )
+    )
+  }
+
+  return .success(
+    ExpandResult(
+      schemaVersion: expandSchemaVersion,
+      files: options.diagnosticsOnly
+        ? files.map { ExpandedFile(file: $0.file, expansions: [], diagnostics: $0.diagnostics) }
+        : files
+    )
+  )
+}
+
+/// The expanded sources as text. A single expansion is printed as it is; more than one each get a
+/// `// <file>` or `// <file>: <symbol>` header and are separated by an empty line.
+func renderExpansions(_ files: [ExpandedFile]) -> String {
+  let expansions = files.flatMap { file in file.expansions.map { (file: file.file, expansion: $0) } }
+  if expansions.count == 1, let only = expansions.first {
+    return withTrailingNewline(only.expansion.source)
+  }
+  return expansions.map { file, expansion in
+    let header = expansion.symbol.map { "// \(file): \($0)" } ?? "// \(file)"
+    return "\(header)\n\n" + withTrailingNewline(expansion.source)
+  }
+  .joined(separator: "\n")
+}
+
+/// The diagnostics in the compiler's format, one line each, followed by their notes and Fix-Its.
+func renderDiagnostics(_ files: [ExpandedFile]) -> String {
+  var text = ""
+  for file in files {
+    for diagnostic in file.diagnostics {
+      text +=
+        "\(file.file):\(diagnostic.line):\(diagnostic.column): \(diagnostic.severity.rawValue): \(diagnostic.message)\n"
+      for note in diagnostic.notes {
+        text += "\(file.file):\(note.line):\(note.column): note: \(note.message)\n"
+      }
+      for fixIt in diagnostic.fixIts {
+        text += "\(file.file):\(diagnostic.line):\(diagnostic.column): note: fix-it: \(fixIt)\n"
+      }
+    }
+  }
+  return text
+}
+
+/// The summary line of `--diagnostics-only`, for example `1 error and 2 warnings in 3 files`.
+func renderSummary(_ files: [ExpandedFile]) -> String {
+  let diagnostics = files.flatMap(\.diagnostics)
+  let errors = diagnostics.filter { $0.severity == .error }.count
+  let warnings = diagnostics.filter { $0.severity == .warning }.count
+  let checked = count(files.count, "file")
+  if errors == 0 && warnings == 0 {
+    return "No macro errors or warnings in \(checked).\n"
+  }
+  let parts = [errors > 0 ? count(errors, "error") : nil, warnings > 0 ? count(warnings, "warning") : nil]
+  return "\(parts.compactMap { $0 }.joined(separator: " and ")) in \(checked).\n"
+}
+
+private func count(_ n: Int, _ noun: String) -> String {
+  "\(n) \(noun)\(n == 1 ? "" : "s")"
+}
+
+private func withTrailingNewline(_ text: String) -> String {
+  text.hasSuffix("\n") ? text : text + "\n"
+}

package/apple/Sources/{ExpoModulesScanner/Exports → ExpoModulesCLI/Commands/ScanExports}/ExportedSurface.swift

@@ -463,8 +463,9 @@ struct ExportedSurface: Encodable, Equatable {
 /// qualified names and gives a resolved ref the name of its declaration; version 8 reports
 /// declarations in `#if` blocks, adds `platforms` (with deprecations), `accessLevel`, and
 /// `defaultValue`, and replaces `constructorParameters` with `initializer`; version 9 adds the
-/// `sharedRef` type kind and the `sharedRef` of a shared object.
-let scanExportsSchemaVersion = 9
+/// `sharedRef` type kind and the `sharedRef` of a shared object; version 10 adds the `tuple` and `object` type kinds (named after a tuple alias)
+/// and resolves the tuple type aliases declared in `@ExpoModule` and `@SharedObject` classes.
+let scanExportsSchemaVersion = 10
 
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).

package/apple/Sources/{ExpoModulesScanner/Exports → ExpoModulesCLI/Commands/ScanExports}/ResolveRefs.swift

@@ -136,6 +136,15 @@ extension TypeNode {
       )
     case .promise(let value):
       return .promise(value: value.resolvingRefs(using: index, in: scope))
+    case .tuple(let elements, let name):
+      return .tuple(elements: elements.map { $0.resolvingRefs(using: index, in: scope) }, name: name)
+    case .object(let properties, let name):
+      return .object(
+        properties: properties.map {
+          TypeNodeProperty(name: $0.name, type: $0.type.resolvingRefs(using: index, in: scope))
+        },
+        name: name
+      )
     case .function(let parameters, let returns, let isAsync, let isThrowing):
       return .function(
         parameters: parameters.map { $0.resolvingRefs(using: index, in: scope) },

package/apple/Sources/{ExpoModulesScanner/Exports → ExpoModulesCLI/Commands/ScanExports}/SurfaceVisitor.swift

@@ -142,13 +142,14 @@ final class SurfaceVisitor: SyntaxVisitor {
       guard scope.isEmpty else {
         return
       }
+      let aliases = TupleTypeAliases(in: members, scope: qualified)
       let (functions, properties, events, _) = collectJSMembers(members)
       modules.append(
         ExportedModule(
           name: qualified,
           jsName: stringArgument(of: attribute) ?? name,
-          functions: functions,
-          properties: properties,
+          functions: functions.map(aliases.resolving),
+          properties: properties.map(aliases.resolving),
           events: events,
           // `jsName` is filled in by `ExportedSurface.resolvingRefs()`, since the `@SharedObject` can
           // be declared in another file.
@@ -164,7 +165,13 @@ final class SurfaceVisitor: SyntaxVisitor {
     }
 
     if let attribute = attributes.firstAttribute(named: DetectedMacro.sharedObject.rawValue) {
-      let (functions, properties, events, initializer) = collectJSMembers(members)
+      let aliases = TupleTypeAliases(in: members, scope: qualified)
+      var (functions, properties, events, initializer) = collectJSMembers(members)
+      functions = functions.map(aliases.resolving)
+      properties = properties.map(aliases.resolving)
+      if let parameters = initializer?.parameters {
+        initializer?.parameters = parameters.map(aliases.resolving)
+      }
       sharedObjects.append(
         ExportedSharedObject(
           name: qualified,