expo-modules-macros 0.28.0 → 0.30.0

package/.github/workflows/linux.yml

@@ -15,7 +15,6 @@ concurrency:
 
 defaults:
   run:
-    working-directory: apple
     shell: bash
 
 jobs:
@@ -56,8 +55,8 @@ jobs:
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: apple/.build
-          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('apple/Package.resolved') }}
+          path: .build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('Package.resolved') }}
           restore-keys: |
             spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-
 
@@ -70,14 +69,13 @@ jobs:
       - name: Build release tool
         # Runs `pnpm run build` (scripts/build.js): builds the release plugin binary for this
         # architecture as platforms/linux-<arch>/ExpoModulesMacros.
-        working-directory: ${{ github.workspace }}
         run: pnpm run build
 
       - name: Verify the release tool
         # With no arguments it is the plugin server, which exits when stdin closes; with arguments it
         # is the scanner CLI.
         run: |
-          tool="../platforms/linux-${{ matrix.arch }}/ExpoModulesMacros"
+          tool="platforms/linux-${{ matrix.arch }}/ExpoModulesMacros"
           # The Swift runtime must be linked in statically, so no Swift library may be a dependency.
           needed="$(readelf --dynamic "$tool" | sed -n 's/.*(NEEDED).*\[\(.*\)\]$/\1/p')"
           echo "Needed libraries:" $needed
@@ -98,7 +96,6 @@ jobs:
         # Checks what `npm pack` would publish from `platforms/linux-<arch>`, where the release build
         # put the tool: the executable with its executable bit, the README, the license and the
         # manifest, with the `os`, `cpu` and `libc` fields for this machine.
-        working-directory: ${{ github.workspace }}
         run: |
           # The `./` matters: npm reads `platforms/linux-<arch>` as a GitHub repository.
           npm pack "./platforms/linux-${{ matrix.arch }}" --pack-destination "$RUNNER_TEMP" --json > "$RUNNER_TEMP/pack.json"
@@ -126,7 +123,6 @@ jobs:
       - name: Scan through the TypeScript wrapper
         # Installs the packed platform package. The wrapper must find the executable in
         # `@expo/modules-macros-linux-<arch>`, as it would in a project, not the local build.
-        working-directory: ${{ github.workspace }}
         run: |
           pnpm install
           pnpm add --save-optional "$PLATFORM_PACKAGE_TARBALL"

package/.github/workflows/publish.yml

@@ -284,14 +284,13 @@ jobs:
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: apple/.build
-          key: spm-${{ github.repository }}-${{ runner.os }}-${{ hashFiles('apple/Package.resolved') }}
+          path: .build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ hashFiles('Package.resolved') }}
           restore-keys: |
             spm-${{ github.repository }}-${{ runner.os }}-
 
       - name: Resolve dependencies
         run: swift package resolve
-        working-directory: apple
 
       - name: Install dependencies
         # The wrapper's `prepublishOnly` build needs `tsc`; the tool binary needs none.

package/.github/workflows/swift.yml

@@ -11,10 +11,6 @@ concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-defaults:
-  run:
-    working-directory: apple
-
 jobs:
   build-and-test:
     name: Build & test
@@ -34,8 +30,8 @@ jobs:
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: apple/.build
-          key: spm-${{ github.repository }}-${{ runner.os }}-${{ hashFiles('apple/Package.resolved') }}
+          path: .build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ hashFiles('Package.resolved') }}
           restore-keys: |
             spm-${{ github.repository }}-${{ runner.os }}-
 
@@ -46,26 +42,24 @@ jobs:
         # Runs `pnpm run build` (scripts/build.js): builds the universal
         # (arm64 + x86_64) release plugin binary, copies it to
         # apple/ExpoModulesMacros, and strips it.
-        working-directory: ${{ github.workspace }}
         run: pnpm run build
 
       - name: Verify universal binary
         run: |
-          archs="$(lipo -archs ExpoModulesMacros)"
+          archs="$(lipo -archs apple/ExpoModulesMacros)"
           echo "Architectures: $archs"
           case "$archs" in *arm64*) ;; *) echo "Missing arm64 slice"; exit 1;; esac
           case "$archs" in *x86_64*) ;; *) echo "Missing x86_64 slice"; exit 1;; esac
-          arch -arm64 ./ExpoModulesMacros < /dev/null
-          arch -x86_64 ./ExpoModulesMacros < /dev/null
+          arch -arm64 apple/ExpoModulesMacros < /dev/null
+          arch -x86_64 apple/ExpoModulesMacros < /dev/null
           # With arguments the same binary runs the scanner CLI instead of the plugin server.
-          arch -arm64 ./ExpoModulesMacros --help > /dev/null
-          arch -x86_64 ./ExpoModulesMacros --help > /dev/null
+          arch -arm64 apple/ExpoModulesMacros --help > /dev/null
+          arch -x86_64 apple/ExpoModulesMacros --help > /dev/null
 
       - name: Test
         run: swift test -v
 
       - name: Typecheck the TypeScript wrapper
-        working-directory: ${{ github.workspace }}
         run: |
           pnpm install
           pnpm run typecheck

package/.github/workflows/windows.yml

@@ -13,10 +13,6 @@ concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-defaults:
-  run:
-    working-directory: apple
-
 jobs:
   windows:
     name: Build & test (Windows ${{ matrix.arch }})
@@ -56,8 +52,8 @@ jobs:
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: apple/.build
-          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('apple/Package.resolved') }}
+          path: .build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('Package.resolved') }}
           restore-keys: |
             spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-
 
@@ -70,7 +66,6 @@ jobs:
       - name: Build release tool
         # Runs `pnpm run build` (scripts/build.js): builds the release plugin binary for this
         # architecture as platforms/win32-<arch>/ExpoModulesMacros.exe.
-        working-directory: ${{ github.workspace }}
         run: pnpm run build
 
       - name: Verify the release tool
@@ -79,7 +74,7 @@ jobs:
         # is the scanner CLI.
         shell: pwsh
         run: |
-          $exe = (Resolve-Path "../platforms/win32-${{ matrix.arch }}/ExpoModulesMacros.exe").Path
+          $exe = (Resolve-Path "platforms/win32-${{ matrix.arch }}/ExpoModulesMacros.exe").Path
           $env:PATH = "$env:SystemRoot\System32;$env:SystemRoot"
           cmd /c "`"$exe`" < NUL"
           if ($LASTEXITCODE -ne 0) { throw "The plugin server exited with $LASTEXITCODE" }
@@ -90,7 +85,6 @@ jobs:
         # Checks what `npm pack` would publish from `platforms/win32-<arch>`, where the release build
         # put the tool: the executable, the README, the license and the manifest, with the `os` and
         # `cpu` fields for this machine.
-        working-directory: ${{ github.workspace }}
         shell: pwsh
         run: |
           # The `./` matters: npm reads `platforms/win32-<arch>` as a GitHub repository.
@@ -109,7 +103,6 @@ jobs:
       - name: Scan through the TypeScript wrapper
         # Installs the packed platform package. The wrapper must find the executable in
         # `@expo/modules-macros-win32-<arch>`, as it would in a project, not the local build.
-        working-directory: ${{ github.workspace }}
         shell: pwsh
         run: |
           pnpm install

package/AGENTS.md

@@ -4,9 +4,11 @@
 
 ## 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 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.
+- `Package.swift`: the SwiftPM package, at the root so that its identity is `expo-modules-macros` (an `apple/` manifest would have the identity `apple`, which conflicts with other packages that keep theirs in `apple/`). The targets name their paths under `apple/`. The `ExpoModulesMacrosPlugin` library product vends the macro target to Swift packages, and its name must differ from the target's. The test targets are declared only when `apple/Tests` exists, because the published npm package leaves it out.
+- `apple/Sources/ExpoModulesMacrosCore`: the macro implementations, in a library target so that both executables below can link them. `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`. `PluginServer.swift` runs the compiler plugin protocol with a provider that resolves the macros of `ProvidedMacro.all` by type name, because the default `CompilerPlugin` lookup expects them in a module named `ExpoModulesMacros`. It uses the `@_spi(PluginMessage)` API of swift-syntax.
+- `apple/Sources/ExpoModulesMacros`: the `.macro` target that the `ExpoModulesMacrosPlugin` product vends to Swift packages. It only runs the plugin server, so Swift packages don't compile the CLI.
+- `apple/Sources/ExpoModulesMacrosTool`: the executable that ships as `apple/ExpoModulesMacros` and in the Windows and Linux packages. `main.swift` runs the plugin server without arguments and sends any invocation with arguments to the CLI.
+- `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 `expand`, with `MacroExpander.swift`, which runs the macros in process, and `Fix/` for `fix`, which applies the Fix-Its that `expand` reports), and `Core/` holds the shared parsing, `#if` evaluation and output.
 - `apple/Sources/ExpoModulesOptimized`: declarations for the `@OptimizedFunction` macro.
 - `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.
@@ -20,8 +22,8 @@
 Swift 6.2 is required (Xcode 26 or newer on macOS). The package manager is pnpm, at the version in `packageManager` in `package.json`.
 
 ```sh
-cd apple && swift build      # debug build
-cd apple && swift test       # all Swift tests
+swift build                  # debug build
+swift test                   # all Swift tests
 pnpm install                 # TypeScript dependencies
 pnpm run typecheck           # TypeScript wrapper
 pnpm run build               # release binary (slow; on macOS uses Rosetta for x86_64)
@@ -56,14 +58,15 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 
 - 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 `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`.
+- A new macro needs: the implementation in `apple/Sources/ExpoModulesMacrosCore/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 `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` (`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.
+- **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 in a way that breaks a consumer, bump its version and update the matching `SUPPORTED_*_SCHEMA_VERSION` constant. A new field that older consumers can ignore doesn't need a bump, but still update the mirror types in `src/types.ts`. The TypeScript wrapper throws when a report's version differs from its constant. `expo-modules-autolinking` gets the `scan-modules` report through the wrapper, and when the call throws, it links only the modules declared in `expo-module.config.json`.
 - **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`.
+- **Swift packages depend on the product.** A Swift package that declares or uses the macros depends on the `ExpoModulesMacrosPlugin` product and builds the plugin from source, without the binary. Renaming the product or the macro target, or moving `Package.swift`, needs a matching change in `expo/expo`.
 
 ## Releases
 
@@ -74,4 +77,4 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 
 ## Installed copies
 
-In `node_modules`, the compiler runs the prebuilt binary `apple/ExpoModulesMacros` (on Windows and Linux, the binary from `@expo/modules-macros-<platform>-<arch>`); editing the Swift sources there has no effect. Macro and scanner fixes belong in this repository and ship in a new release. The TypeScript wrapper ships compiled in `build/`, since `src/` is not published.
+In `node_modules`, a CocoaPods build runs the prebuilt binary `apple/ExpoModulesMacros` (on Windows and Linux, the binary from `@expo/modules-macros-<platform>-<arch>`); editing the Swift sources there has no effect. Macro and scanner fixes belong in this repository and ship in a new release. The TypeScript wrapper ships compiled in `build/`, since `src/` is not published.

package/Package.swift

@@ -0,0 +1,110 @@
+// swift-tools-version: 6.2
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import CompilerPluginSupport
+import Foundation
+import PackageDescription
+
+let package = Package(
+  name: "ExpoModulesMacros",
+  platforms: [.macOS(.v13)],
+  products: [
+    // Lets a SwiftPM package depend on the macros, so the compiler builds and loads the plugin from
+    // source, with no `-load-plugin-executable` flag. A target that declares the macros with
+    // `#externalMacro(module: "ExpoModulesMacros", ...)` depends on this product, and the targets that
+    // depend on it get the plugin too. CocoaPods builds keep loading the prebuilt binary. The name
+    // differs from the macro target's, because SwiftPM already has a product of that name for it.
+    .library(name: "ExpoModulesMacrosPlugin", targets: ["ExpoModulesMacros"]),
+    .executable(name: "ExpoModulesMacrosTool", targets: ["ExpoModulesMacrosTool"]),
+  ],
+  dependencies: [
+    .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "604.0.0-latest")
+  ],
+  targets: [
+    // The macro implementations, shared by the plugin and the tool. The macro target can't be a
+    // dependency of an executable, so they live in a library target.
+    .target(
+      name: "ExpoModulesMacrosCore",
+      dependencies: [
+        .product(name: "SwiftSyntax", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+        .product(name: "SwiftDiagnostics", package: "swift-syntax"),
+        // For the plugin server, which resolves the macros by type name (see PluginServer.swift).
+        .product(name: "_SwiftCompilerPluginMessageHandling", package: "swift-syntax"),
+      ],
+      path: "apple/Sources/ExpoModulesMacrosCore"
+    ),
+    // The plugin that Swift packages build from source. It serves only the macros, so it doesn't
+    // compile the CLI. It lists the swift-syntax products of the implementation again: when SwiftPM
+    // uses its prebuilt swift-syntax, it links the prebuilt library only for the products that the
+    // macro target itself depends on, and the link fails without them.
+    .macro(
+      name: "ExpoModulesMacros",
+      dependencies: [
+        "ExpoModulesMacrosCore",
+        .product(name: "SwiftSyntax", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+        .product(name: "SwiftDiagnostics", package: "swift-syntax"),
+        .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
+      ],
+      path: "apple/Sources/ExpoModulesMacros"
+    ),
+    // The shipped binary, `apple/ExpoModulesMacros` and the Windows and Linux binaries. It is both the
+    // compiler plugin and the scanner CLI: the compiler launches it without arguments and speaks the
+    // plugin protocol over stdin, while an invocation with arguments dispatches into `ScannerCLI`
+    // (see main.swift). CocoaPods builds, `expo-modules-autolinking` and `expo-modules-cli` all
+    // use this one executable.
+    .executableTarget(
+      name: "ExpoModulesMacrosTool",
+      dependencies: [
+        "ExpoModulesCLI",
+        "ExpoModulesMacrosCore",
+      ],
+      path: "apple/Sources/ExpoModulesMacrosTool"
+    ),
+    .target(
+      name: "ExpoModulesCLI",
+      dependencies: [
+        "ExpoModulesMacrosCore",
+        .product(name: "SwiftSyntax", package: "swift-syntax"),
+        .product(name: "SwiftParser", package: "swift-syntax"),
+        .product(name: "SwiftIfConfig", package: "swift-syntax"),
+        // For `expand`, which runs the macros in process.
+        .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxMacroExpansion", package: "swift-syntax"),
+        .product(name: "SwiftParserDiagnostics", package: "swift-syntax"),
+        .product(name: "SwiftBasicFormat", package: "swift-syntax"),
+        .product(name: "SwiftDiagnostics", package: "swift-syntax"),
+      ],
+      path: "apple/Sources/ExpoModulesCLI"
+    ),
+  ]
+)
+
+// The Tests directory is excluded from the published npm package,
+// so only declare the test target when building from the repository.
+if FileManager.default.fileExists(atPath: Context.packageDirectory + "/apple/Tests") {
+  package.targets.append(
+    .testTarget(
+      name: "ExpoModulesMacrosTests",
+      dependencies: [
+        "ExpoModulesMacrosCore",
+        "ExpoModulesCLI",
+        .product(name: "SwiftSyntaxMacrosGenericTestSupport", package: "swift-syntax"),
+      ],
+      path: "apple/Tests/ExpoModulesMacrosTests"
+    )
+  )
+  package.targets.append(
+    .testTarget(
+      name: "ExpoModulesCLITests",
+      dependencies: [
+        "ExpoModulesCLI",
+        .product(name: "SwiftParser", package: "swift-syntax"),
+      ],
+      path: "apple/Tests/ExpoModulesCLITests"
+    )
+  )
+}

package/README.md

@@ -13,7 +13,7 @@ The same executable doubles as a source scanner CLI.
 
 # Installation
 
-This package is not meant to be installed directly. It is a dependency of `expo-modules-core`, so every Expo project already has it. The published package contains a prebuilt universal (arm64 + x86_64) macOS binary at `apple/ExpoModulesMacros`, so consumers never build the plugin themselves.
+This package is not meant to be installed directly. It is a dependency of `expo-modules-core`, so every Expo project already has it. The published package contains a prebuilt universal (arm64 + x86_64) macOS binary at `apple/ExpoModulesMacros`, so CocoaPods builds never build the plugin themselves. A Swift package can build it from source instead (see [Swift packages](#swift-packages)).
 
 The Windows and Linux binaries ship in their own packages, one per platform and architecture:
 
@@ -25,8 +25,8 @@ 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. It adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet (see [Sendable conformance](#sendable-conformance)).
-- **`@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, 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.
+- **`@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. Because of that, a `.concurrent` function and a function with `.withAsync` can't take a JavaScript value such as `JavaScriptValue` or `JavaScriptObject`, which is valid only on the JavaScript thread; the macro reports such a parameter. 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, 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, _ options: EventOptions...)`** 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. The `.sync` option dispatches inline on the JavaScript thread instead of asynchronously, and `@ExpoModule` and `@SharedObject` isolate the property to `@JavaScriptActor`.
 - **`@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. A subclass of another `@SharedObject` class also gets the `@JS` members of that class, and its own members replace inherited members with the same JS name. A subclass that isn't `final` can't be constructed from JavaScript through the `@JS init` of its superclass, so give each subclass that JavaScript constructs its own `@JS init`. Like `@ExpoModule`, it adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet.
 - **`@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. A record converts only from and to JavaScript values: its `from(dictionary:appContext:)` throws `RecordDictionaryConversionException`, so a record can't be created from a native `[String: Any]`. A `@Union` can be a record property. 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.
@@ -70,6 +70,10 @@ The author-facing documentation for each macro lives next to its declaration in
 
 Native code calls a module or shared object from more than one thread: a `.withAsync` variant runs on the concurrent thread pool, and events and closure arguments can be called from any thread. So the generated code needs the class to be `Sendable`. A subclass of `Module` or `SharedObject` can't be checked `Sendable`, because those base classes aren't, so `@ExpoModule` and `@SharedObject` add `extension MyModule: @unchecked Sendable {}`. The compiler doesn't check the class's mutable state then: keep state that more than one thread uses behind a lock or an actor. The macros add nothing when the class already declares `Sendable` or `@unchecked Sendable`, or inherits it. Swift warns on a subclass of a module or shared object until the subclass restates `@unchecked Sendable`.
 
+## Access level
+
+Autolinking generates the modules provider in the app target, so it can reference only the `public` and `open` classes of other modules. `@ExpoModule` and `@SharedObject` warn when the class isn't `public` or `open`, with a fix-it that makes it `public`. The fix-it replaces an `internal`, `package`, `fileprivate` or `private` modifier, or adds `public` before the other modifiers. A class declared in a function can't have an access modifier, so it gets no warning.
+
 # Scanner
 
 The Swift compiler launches a plugin executable with no arguments and speaks the plugin protocol over stdin, so the binary treats any argument as a scanner invocation instead:
@@ -78,17 +82,24 @@ The Swift compiler launches a plugin executable with no arguments and speaks the
 ExpoModulesMacros <subcommand> [options] <path> [<path> ...]
 
 subcommands:
-  scan-modules   fast scan for top-level @ExpoModule types (autolinking)
+  scan-modules   fast scan for top-level @ExpoModule and @SharedObject 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
+  fix            apply the Fix-Its of the macro diagnostics to the files
 
 options (scan-modules only):
   --define <flag>   treat a conditional compilation flag as set; repeatable
 
-options (expand only):
+options (expand and fix):
   --symbol <name>      only a type ('MyModule', 'MyModule.Options') or a member ('MyModule.greet'); repeatable
+
+options (expand only):
   --diagnostics-only   only the diagnostics, followed by a summary
   --json               a JSON report instead of text
+
+options (fix only):
+  --dry-run            print the Fix-Its without changing the files
+  --only-errors        apply only the Fix-Its of errors, not those of warnings
 ```
 
 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.
@@ -121,6 +132,26 @@ The macros only read the syntax tree, so the expansion is what the compiler gets
 
 Errors that need type checking, for example the conformance assertions in `_assertTypesConformance`, still need a build.
 
+## Fix
+
+`fix` applies the Fix-Its that the macros attach to their diagnostics, such as "Mark the function 'async'" for a `.concurrent` function, and writes the files in place. It takes the same paths and `--symbol` options as `expand`, and expands the files in the same way.
+
+```sh
+ExpoModulesMacros fix --dry-run ios/
+ExpoModulesMacros fix ios/
+```
+
+Each applied Fix-It is printed to stdout as `<file>:<line>:<column>: fix-it: <message>`, followed by a summary. With `--dry-run`, the files aren't written.
+
+`fix` applies the Fix-Its of errors and of warnings, such as "Make the class 'public'" for a module class that isn't `public`. With `--only-errors`, it applies only those of errors.
+
+- A macro can stop at its first error, so after applying the Fix-Its of a file, `fix` expands it again and applies the new ones, until none applies (at most 10 passes). The location of a Fix-It is in the file as it was when the Fix-It was applied.
+- A diagnostic with more than one Fix-It is skipped, because they are alternatives. So is a Fix-It whose edits overlap the edits of another one, or whose text isn't in the file where the edit expects it. Each skipped Fix-It is printed to stderr as a warning.
+- It applies only the Fix-Its of the macros, not those of syntax errors.
+- It changes only the text that a Fix-It changes and doesn't format the file. An inserted keyword can make a line longer than your formatter allows, so run your formatter after `fix` if you use one.
+
+The exit code is `0` also when a Fix-It is skipped or errors remain, `1` when a file can't be written, and `2` for an input that `expand` doesn't take.
+
 # TypeScript wrapper
 
 Node consumers can call the scanner through this package instead of locating the binary and shelling out themselves:
@@ -145,16 +176,33 @@ The binary is a compiled executable, so each call still spawns a process. What t
 
 to `OTHER_SWIFT_FLAGS` for `ExpoModulesCore`, every pod that depends on it, and their test specs. Expo's SPM prebuilds pass the same flag when they generate `Package.swift`, so both build systems load the same binary.
 
+## Swift packages
+
+The package manifest is `Package.swift` at the root of this package, so a Swift package can depend on it by its path in `node_modules` or by the URL of this repository. Its identity is then `expo-modules-macros`. The `ExpoModulesMacrosPlugin` library product holds the `ExpoModulesMacros` macro target:
+
+```swift
+dependencies: [
+  .package(path: "../node_modules/expo-modules-macros")
+],
+targets: [
+  .target(
+    name: "ExpoModulesCore",
+    dependencies: [.product(name: "ExpoModulesMacrosPlugin", package: "expo-modules-macros")]
+  )
+]
+```
+
+SwiftPM then builds the plugin from source for the host (the macros, without the scanner CLI) and loads it into every target that depends on that target, with no `-load-plugin-executable` flag and no unsafe flags. When the resolved swift-syntax version is a release, SwiftPM and Xcode can use their prebuilt swift-syntax for it, so only the sources of this package compile.
+
 On Windows and Linux, the compiler loads `ExpoModulesMacros.exe` from `@expo/modules-macros-win32-<arch>` or `ExpoModulesMacros` from `@expo/modules-macros-linux-<arch>` with the same flag. `getScannerBinaryPath()` in the TypeScript wrapper returns the binary for the current platform and architecture. On Windows and Linux it falls back to the local `pnpm run build` output in `platforms/<platform>-<arch>` when the platform package isn't installed, for example in this repository.
 
-The module and type names in `#externalMacro` must stay in sync with `apple/Sources/ExpoModulesMacros/Plugin.swift`.
+The module and type names in `#externalMacro` must stay in sync with `ProvidedMacro.all` in `apple/Sources/ExpoModulesMacrosCore/ProvidedMacros.swift`.
 
 # Development
 
 Requires a toolchain with Swift 6.2 or newer: on macOS 13 or newer that means Xcode 26 or newer, and on Windows and Linux the Swift toolchain from swift.org (CI uses 6.4).
 
 ```sh
-cd apple
 swift build
 swift test
 ```
@@ -174,7 +222,7 @@ cp "$(cd /tmp/swift-format && swift build -c release --show-bin-path)/swift-form
 
 Then add `~/.local/bin` to `PATH`.
 
-`pnpm run build` runs `scripts/build.js`, which builds the release binary with SwiftPM's native build system (Swift Build, the default since Swift 6.4, doesn't build a macro tool that no target in the package uses).
+`pnpm run build` runs `scripts/build.js`, which builds the release binary, the `ExpoModulesMacrosTool` executable, with SwiftPM's native build system.
 
 - On macOS, it builds for arm64 and x86_64, merges the slices into `apple/ExpoModulesMacros` with `lipo`, strips it, and verifies both slices are present. SwiftPM only builds macro tools for the host architecture, so the x86_64 slice is produced by running the toolchain under Rosetta; the script installs Rosetta if it is missing.
 - On Windows, it builds for the host architecture only, with the Swift runtime linked in statically and without debug info, and writes `platforms/win32-<arch>/ExpoModulesMacros.exe` (`x64` or `arm64`, as Node's `process.arch` names them), the file that the package for that architecture publishes. It strips the executable with `llvm-strip` from the Swift toolchain and checks the architecture in its header.

package/apple/Sources/ExpoModulesCLI/CLI.swift

@@ -6,16 +6,18 @@
 /// files).
 ///
 /// Subcommands:
-///   scan-modules   <path>...   fast: top-level `@ExpoModule` types, for autolinking
+///   scan-modules   <path>...   fast: top-level `@ExpoModule` and `@SharedObject` 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
+///   fix            <path>...   applies the Fix-Its of the macro diagnostics to the files
 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.
-  /// `expand` also returns `1` for an error diagnostic (see `Scanner.runExpand`).
+  /// `expand` also returns `1` for an error diagnostic (see `Scanner.runExpand`), and `fix` when it
+  /// can't write a file (see `Scanner.runFix`).
   ///
-  /// `expander` expands the macros for `expand`. The plugin executable passes it, because the macro
-  /// implementations live there; without it, `expand` is a usage error.
+  /// `expander` expands the macros for `expand` and `fix`. The plugin executable passes it, because the
+  /// macro implementations live there; without it, `expand` and `fix` are usage errors.
   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" }) {
@@ -32,6 +34,8 @@ public enum ScannerCLI {
     var platform: String?
     var defines: [String] = []
     var expandOptions = ExpandOptions()
+    var dryRun = false
+    var onlyErrors = false
 
     var rest = arguments.dropFirst().makeIterator()
     while let argument = rest.next() {
@@ -55,14 +59,24 @@ public enum ScannerCLI {
         expandOptions.json = true
       case "--diagnostics-only":
         expandOptions.diagnosticsOnly = true
+      case "--dry-run":
+        dryRun = true
+      case "--only-errors":
+        onlyErrors = 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")
+    if subcommand != "expand" && subcommand != "fix" && !expandOptions.symbols.isEmpty {
+      return usageError("--symbol is an option of expand and fix")
+    }
+    if subcommand != "expand" && (expandOptions.json || expandOptions.diagnosticsOnly) {
+      return usageError("--json and --diagnostics-only are options of expand")
+    }
+    if subcommand != "fix" && (dryRun || onlyErrors) {
+      return usageError("--dry-run and --only-errors are options of fix")
     }
 
     switch subcommand {
@@ -103,6 +117,21 @@ public enum ScannerCLI {
       expandOptions.paths = paths
       return Scanner.runExpand(options: expandOptions, expander: expander)
 
+    case "fix":
+      guard platform == nil, defines.isEmpty else {
+        return usageError("fix does not support --platform or --define")
+      }
+      guard !paths.isEmpty else {
+        return usageError("fix requires at least one path")
+      }
+      guard let expander else {
+        return usageError("fix is only available in the macro plugin executable")
+      }
+      return Scanner.runFix(
+        options: FixOptions(paths: paths, symbols: expandOptions.symbols, dryRun: dryRun, onlyErrors: onlyErrors),
+        expander: expander
+      )
+
     default:
       return usageError("unknown subcommand '\(subcommand)'")
     }
@@ -110,7 +139,7 @@ public enum ScannerCLI {
 }
 
 /// The invoked executable's basename, so the usage text matches however the tool was launched
-/// (the `ExpoModulesMacros` shipped in the package, or a locally built `ExpoModulesMacros-tool`).
+/// (the `ExpoModulesMacros` shipped in the package, or a locally built `ExpoModulesMacrosTool`).
 private var toolName: String {
   guard let path = CommandLine.arguments.first else {
     return "ExpoModulesMacros"
@@ -124,23 +153,31 @@ private var usageText: String {
   usage: \(toolName) <subcommand> [options] <path> [<path> ...]
 
   subcommands:
-    scan-modules   fast scan for top-level @ExpoModule types (autolinking)
+    scan-modules   fast scan for top-level @ExpoModule and @SharedObject 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
+    fix            apply the Fix-Its of the macro diagnostics to the files that expand takes, in
+                   place, and print each one; doesn't format the files
 
   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 and fix):
+    --symbol <name>      expand only a type ('MyModule', 'MyModule.Options') or a member
+                         ('MyModule.greet'), and use only its diagnostics; 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 (fix only):
+    --dry-run            print the Fix-Its without changing the files
+    --only-errors        apply only the Fix-Its of errors, not those of warnings
+
   options:
     -h, --help        print this help and exit