expo-modules-macros 0.29.0 → 0.31.0

package/AGENTS.md

@@ -8,7 +8,7 @@
 - `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 `Core/` holds the shared parsing, `#if` evaluation and output.
+- `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.
@@ -64,7 +64,7 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 
 - **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`.
 

package/README.md

@@ -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. By default the event is scheduled on the JavaScript thread. The `.inline` option runs the listeners before the call returns when it is made on the JavaScript thread, and schedules the event otherwise; it never blocks. The `.blocking` option runs the listeners before the call returns on any thread, so a call from another thread blocks until the JavaScript thread runs them. An event property is callable from any thread with each option.
 - **`@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,28 @@ 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, with a warning when Fix-Its are left after them). 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; an insertion is checked against the few bytes after 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.
+
+`fix` writes a file only when it still has the contents that `fix` read, so it doesn't overwrite a change saved meanwhile. It writes the file in place, so on macOS and Linux, symbolic and hard links, permissions, the owner, extended attributes and ACLs stay, and a read-only file isn't written. When a write fails, `fix` writes the original contents back and reports whether the file is unchanged; when that fails too, it saves them to a file in the temporary directory and names it. A file that can't be written is reported, and the other files are still fixed. A UTF-8 byte order mark is kept.
+
+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:

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)'")
     }
@@ -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
 

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

@@ -67,13 +67,29 @@ public struct ExpansionDiagnostic: Codable, Equatable, Sendable {
   /// The messages of the Fix-Its, for example `replace 'var' with 'let'`.
   public let fixIts: [String]
 
+  /// The edits of each Fix-It in `fixIts`, in the original file, for `fix`. The edits of a Fix-It are
+  /// empty when they aren't in the original file, and this is empty for a diagnostic whose Fix-Its
+  /// `fix` doesn't apply, such as a syntax error. Not part of the JSON report, nor of equality, so a
+  /// diagnostic is equal to itself after a JSON round trip.
+  public var fixItEdits: [[ExpansionEdit]] = []
+
+  private enum CodingKeys: String, CodingKey {
+    case severity, message, line, column, notes, fixIts
+  }
+
+  public static func == (lhs: Self, rhs: Self) -> Bool {
+    lhs.severity == rhs.severity && lhs.message == rhs.message && lhs.line == rhs.line
+      && lhs.column == rhs.column && lhs.notes == rhs.notes && lhs.fixIts == rhs.fixIts
+  }
+
   public init(
     severity: Severity,
     message: String,
     line: Int,
     column: Int,
     notes: [ExpansionNote] = [],
-    fixIts: [String] = []
+    fixIts: [String] = [],
+    fixItEdits: [[ExpansionEdit]] = []
   ) {
     self.severity = severity
     self.message = message
@@ -81,6 +97,27 @@ public struct ExpansionDiagnostic: Codable, Equatable, Sendable {
     self.column = column
     self.notes = notes
     self.fixIts = fixIts
+    self.fixItEdits = fixItEdits
+  }
+}
+
+/// A change of one range of the original file: `original`, which starts at `offset`, becomes
+/// `replacement`.
+public struct ExpansionEdit: Equatable, Sendable {
+  /// The UTF-8 offset in the original file.
+  public let offset: Int
+
+  /// The text that the edit replaces, so `fix` can check that the file still has it there. An
+  /// insertion also replaces a few bytes after it with themselves, so it has text to check too, and
+  /// is empty only at the end of a declaration.
+  public let original: String
+
+  public let replacement: String
+
+  public init(offset: Int, original: String, replacement: String) {
+    self.offset = offset
+    self.original = original
+    self.replacement = replacement
   }
 }
 

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

@@ -34,13 +34,20 @@ public func expandMacros(source: String, file: String, symbols: [String]) -> Exp
   }
   let originalDeclarations = OriginalDeclarations(tree)
   diagnostics += context.diagnostics.map { diagnostic in
-    expansionDiagnostic(diagnostic) { position, node in
-      let location = context.location(for: position, anchoredAt: node, fileName: file)
-      if let original = originalDeclarations.position(of: position, in: node, shiftedOffset: location.offset) {
+    let location = { (position: AbsolutePosition, node: Syntax) -> SourceLocation in
+      let original = originalDeclarations.position(of: position, in: node) {
+        context.location(for: node.root.position, anchoredAt: node, fileName: file).offset
+      }
+      if let original {
         return converter.location(for: original)
       }
-      return location
+      return context.location(for: position, anchoredAt: node, fileName: file)
+    }
+    var result = expansionDiagnostic(diagnostic, location: location)
+    result.fixItEdits = diagnostic.fixIts.map { fixIt in
+      originalEdits(of: fixIt) { location($0, $1).offset } ?? []
     }
+    return result
   }
   diagnostics.sort { ($0.line, $0.column) < ($1.line, $1.column) }
 
@@ -203,6 +210,113 @@ private func expansionDiagnostic(
   )
 }
 
+/// The edits of `fixIt` in the original file, or `nil` when one of them isn't in the tree of the node
+/// that it changes. `offset` maps a position in the tree of a node to its UTF-8 offset in the original
+/// file.
+///
+/// A Fix-It that replaces a node replaces all of it, but the tree that a macro gets isn't always the
+/// original declaration: in a module, a `@JS` member also has the attributes that `@ExpoModule` adds.
+/// So each edit is reduced to the bytes that it changes, for example the `async ` that it inserts
+/// into a signature, which are in the original file too. The macro system detaches the attribute
+/// from the declaration, so a change has its own tree, which can differ from the diagnostic's.
+private func originalEdits(
+  of fixIt: FixIt,
+  offset: (AbsolutePosition, Syntax) -> Int
+) -> [ExpansionEdit]? {
+  // The edit of each change in the tree of its node. `FixIt.edits` drops an edit that overlaps an
+  // earlier one; this applies the same rule.
+  var changes: [(edit: SourceEdit, node: Syntax)] = []
+  for change in fixIt.changes {
+    guard let edit = FixIt(message: fixIt.message, changes: [change]).edits.first else {
+      continue
+    }
+    let node = changedNode(change)
+    if !changes.contains(where: { $0.node.root.id == node.root.id && $0.edit.range.overlaps(edit.range) }) {
+      changes.append((edit, node))
+    }
+  }
+
+  var edits: [ExpansionEdit] = []
+  for (index, (edit, node)) in changes.enumerated() {
+    let root = node.root
+    let text = Array(root.description.utf8)
+    let start = edit.range.lowerBound.utf8Offset - root.position.utf8Offset
+    let end = edit.range.upperBound.utf8Offset - root.position.utf8Offset
+    guard 0 <= start, start <= end, end <= text.count else {
+      return nil
+    }
+    let old = text[start..<end]
+    let new = Array(edit.replacement.utf8)
+    let (prefix, suffix) = commonAffixLengths(Array(old), new)
+    guard prefix + suffix < max(old.count, new.count) else {
+      continue
+    }
+    var original = Array(old.dropFirst(prefix).dropLast(suffix))
+    var replacement = Array(new.dropFirst(prefix).dropLast(suffix))
+    if original.isEmpty {
+      // An insertion has no text that `fix` can check in the file, so it also replaces the bytes after
+      // it with themselves, up to a character boundary and not into another change of the Fix-It.
+      let insertion = start + prefix
+      let nextChange = changes.enumerated().filter { $0.offset != index && $0.element.node.root.id == root.id }
+        .map { $0.element.edit.range.lowerBound.utf8Offset - root.position.utf8Offset }
+        .filter { $0 >= insertion }.min()
+      var contextEnd = min(insertion + insertionContextLength, text.count, nextChange ?? text.count)
+      while contextEnd > insertion && contextEnd < text.count && text[contextEnd] & 0xC0 == 0x80 {
+        contextEnd -= 1
+      }
+      original = Array(text[insertion..<contextEnd])
+      replacement += original
+    }
+    edits.append(
+      ExpansionEdit(
+        offset: offset(edit.range.lowerBound.advanced(by: prefix), node),
+        original: String(decoding: original, as: UTF8.self),
+        replacement: String(decoding: replacement, as: UTF8.self)
+      )
+    )
+  }
+  return edits
+}
+
+/// The number of bytes after an insertion that its edit also replaces with themselves.
+private let insertionContextLength = 8
+
+/// The node in the tree that `change` edits.
+private func changedNode(_ change: FixIt.Change) -> Syntax {
+  switch change {
+  case .replace(let oldNode, _):
+    oldNode
+  case .replaceLeadingTrivia(let token, _), .replaceTrailingTrivia(let token, _):
+    Syntax(token)
+  case .replaceChild(let data):
+    Syntax(data.parent)
+  case .replaceText(_, _, let node):
+    node
+  }
+}
+
+/// The lengths of the longest common prefix and suffix of `old` and `new` that don't overlap, at
+/// character boundaries, so the bytes between them are valid UTF-8 on both sides.
+private func commonAffixLengths(_ old: [UInt8], _ new: [UInt8]) -> (prefix: Int, suffix: Int) {
+  let isContinuation = { (bytes: [UInt8], index: Int) in index < bytes.count && bytes[index] & 0xC0 == 0x80 }
+  let shorter = min(old.count, new.count)
+  var prefix = 0
+  while prefix < shorter && old[prefix] == new[prefix] {
+    prefix += 1
+  }
+  while prefix > 0 && (isContinuation(old, prefix) || isContinuation(new, prefix)) {
+    prefix -= 1
+  }
+  var suffix = 0
+  while suffix < shorter - prefix && old[old.count - 1 - suffix] == new[new.count - 1 - suffix] {
+    suffix += 1
+  }
+  while suffix > 0 && (isContinuation(old, old.count - suffix) || isContinuation(new, new.count - suffix)) {
+    suffix -= 1
+  }
+  return (prefix, suffix)
+}
+
 private func severity(_ severity: DiagnosticSeverity) -> ExpansionDiagnostic.Severity {
   switch severity {
   case .error: .error
@@ -223,51 +337,77 @@ private func severity(_ severity: DiagnosticSeverity) -> ExpansionDiagnostic.Sev
 /// every position after the added attributes is off by their length. A diagnostic in a parameter
 /// type of a `@JS` function would be on the next line.
 ///
-/// The text from the keyword of the declaration (`func`, `var`, `init`) to its end is the same in
-/// both, so this finds the original declaration by that text and moves the position by the offset of
-/// the keyword. A position before the keyword, in the attributes or the modifiers, isn't mapped.
-private struct OriginalDeclarations {
-  /// The positions of the keywords of the declarations in the original file, in source order, by the
-  /// text from the keyword to the end of the declaration.
-  private let keywordPositions: [String: [AbsolutePosition]]
+/// The start of the declaration is before the added attributes, so the macro system maps it to the
+/// start of the original declaration. The text from the keyword of the declaration (`func`, `var`,
+/// `init`) to its end is the same in both, so this moves the position by the offset of the keyword
+/// in the original declaration. A position before the keyword, in the attributes or the modifiers,
+/// isn't mapped.
+///
+/// An accessor macro can get a declaration that swift-syntax rewrote rather than detached, for
+/// example an `@Event` property with a closure in its initializer, and its start doesn't map to the
+/// file. Such a declaration is found by its text when no other declaration in the file has it.
+private final class OriginalDeclarations {
+  /// The declarations in the original file by the UTF-8 offset of their start, with their leading
+  /// trivia: the text from the keyword to the end of each, and the position of its keyword.
+  private let declarationsByStart: [Int: [(text: String, keyword: AbsolutePosition)]]
+
+  /// The positions of the keywords of the declarations in the original file, by the text from the
+  /// keyword to the end of the declaration.
+  private let keywordsByText: [String: [AbsolutePosition]]
+
+  /// The positions of the keyword of each declaration that a macro got and of its original
+  /// declaration, or `nil` when it has no original declaration.
+  private var keywords: [SyntaxIdentifier: (keyword: AbsolutePosition, original: AbsolutePosition)?] = [:]
 
   init(_ tree: SourceFileSyntax) {
     let collector = DeclarationCollector(viewMode: .sourceAccurate)
     collector.walk(tree)
-    var keywordPositions: [String: [AbsolutePosition]] = [:]
+    var declarationsByStart: [Int: [(text: String, keyword: AbsolutePosition)]] = [:]
+    var keywordsByText: [String: [AbsolutePosition]] = [:]
     for declaration in collector.declarations {
       guard let keyword = keywordToken(of: declaration) else {
         continue
       }
-      keywordPositions[textFromKeyword(keyword, of: declaration), default: []].append(
-        keyword.positionAfterSkippingLeadingTrivia
+      let text = textFromKeyword(keyword, of: declaration)
+      declarationsByStart[declaration.position.utf8Offset, default: []].append(
+        (text, keyword.positionAfterSkippingLeadingTrivia)
       )
+      keywordsByText[text, default: []].append(keyword.positionAfterSkippingLeadingTrivia)
     }
-    self.keywordPositions = keywordPositions
+    self.declarationsByStart = declarationsByStart
+    self.keywordsByText = keywordsByText
   }
 
   /// The position in the original file of `position` in `node`, or `nil` when `node` is in the
-  /// original file, isn't in a detached declaration, or is before its keyword.
+  /// original file, isn't in a declaration that a macro got, is before its keyword, or its original
+  /// declaration isn't found.
   ///
-  /// `shiftedOffset` is the offset that the macro system maps `position` to. The added attributes
-  /// only move it forward, so when declarations with the same text are in the file, the one it is
-  /// in is the last one that starts at or before that offset.
-  func position(of position: AbsolutePosition, in node: Syntax, shiftedOffset: Int) -> AbsolutePosition? {
-    guard !node.root.is(SourceFileSyntax.self),
-      let declaration = node.root.as(DeclSyntax.self),
-      let keyword = keywordToken(of: declaration),
-      position >= keyword.positionAfterSkippingLeadingTrivia,
-      let candidates = keywordPositions[textFromKeyword(keyword, of: declaration)]
-    else {
+  /// `declarationStart` returns the offset that the macro system maps the start of the declaration
+  /// to. It is called once for each declaration.
+  func position(
+    of position: AbsolutePosition,
+    in node: Syntax,
+    declarationStart: () -> Int
+  ) -> AbsolutePosition? {
+    guard !node.root.is(SourceFileSyntax.self), let declaration = node.root.as(DeclSyntax.self) else {
       return nil
     }
-    let offset = position.utf8Offset - keyword.positionAfterSkippingLeadingTrivia.utf8Offset
-    let shiftedKeyword = shiftedOffset - offset
-    guard let originalKeyword = candidates.last(where: { $0.utf8Offset <= shiftedKeyword }) ?? candidates.first
-    else {
+    let found: (keyword: AbsolutePosition, original: AbsolutePosition)?
+    if let cached = keywords[declaration.id] {
+      found = cached
+    } else {
+      found = keywordToken(of: declaration).flatMap { keyword in
+        let text = textFromKeyword(keyword, of: declaration)
+        let byStart = declarationsByStart[declarationStart()]?.first { $0.text == text }?.keyword
+        let byText = keywordsByText[text].flatMap { $0.count == 1 ? $0.first : nil }
+        return (byStart ?? byText).map { (keyword.positionAfterSkippingLeadingTrivia, $0) }
+      }
+      keywords[declaration.id] = found
+    }
+    guard let found, position >= found.keyword else {
       return nil
     }
-    return AbsolutePosition(utf8Offset: originalKeyword.utf8Offset + offset)
+    return AbsolutePosition(utf8Offset: found.original.utf8Offset + position.utf8Offset - found.keyword.utf8Offset)
   }
 }
 

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

@@ -75,8 +75,25 @@ struct ExpandInputError: Error, Equatable {
 /// 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> {
+  expandSources(options: options, expander: expander).map { sources in
+    let files = sources.map(\.expanded)
+    return ExpandResult(
+      schemaVersion: expandSchemaVersion,
+      files: options.diagnosticsOnly
+        ? files.map { ExpandedFile(file: $0.file, expansions: [], diagnostics: $0.diagnostics) }
+        : files
+    )
+  }
+}
+
+/// The files of `options` with their sources and the bytes that were read, expanded with `expander`,
+/// as `expandFiles` describes. `fix` uses it too, because it edits the sources.
+func expandSources(
+  options: ExpandOptions,
+  expander: MacroExpander
+) -> Result<[(source: String, contents: Data, expanded: ExpandedFile)], ExpandInputError> {
   let prefilter = MacroPrefilter(attributeNames: expander.attributeNames)
-  var sources: [(file: String, source: String)] = []
+  var sources: [(file: String, source: String, contents: Data)] = []
   var seen: Set<String> = []
   for path in options.paths {
     switch isDirectory(atPath: path) {
@@ -84,12 +101,12 @@ func expandFiles(options: ExpandOptions, expander: MacroExpander) -> Result<Expa
       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 {
+        guard let (source, contents) = readSource(atPath: file) else {
           return .failure(ExpandInputError(message: "could not read '\(file)'"))
         }
         seen.insert(fileIdentity(file))
         if mightContainMacro(in: source, prefilter: prefilter) {
-          sources.append((file, source))
+          sources.append((file, source, contents))
         }
       }
     case .some(false):
@@ -99,17 +116,19 @@ func expandFiles(options: ExpandOptions, expander: MacroExpander) -> Result<Expa
       guard !seen.contains(fileIdentity(path)) else {
         continue
       }
-      guard let source = try? String(contentsOfFile: path, encoding: .utf8) else {
+      guard let (source, contents) = readSource(atPath: path) else {
         return .failure(ExpandInputError(message: "could not read '\(path)'"))
       }
       seen.insert(fileIdentity(path))
-      sources.append((path, source))
+      sources.append((path, source, contents))
     }
   }
 
-  let files = sources.map { expander.expand($0.source, $0.file, options.symbols) }
+  let files = sources.map {
+    (source: $0.source, contents: $0.contents, expanded: expander.expand($0.source, $0.file, options.symbols))
+  }
 
-  let found = Set(files.flatMap { $0.expansions.compactMap(\.symbol) })
+  let found = Set(files.flatMap { $0.expanded.expansions.compactMap(\.symbol) })
   if let missing = options.symbols.first(where: { !found.contains($0) }) {
     return .failure(
       ExpandInputError(
@@ -119,14 +138,23 @@ func expandFiles(options: ExpandOptions, expander: MacroExpander) -> Result<Expa
     )
   }
 
-  return .success(
-    ExpandResult(
-      schemaVersion: expandSchemaVersion,
-      files: options.diagnosticsOnly
-        ? files.map { ExpandedFile(file: $0.file, expansions: [], diagnostics: $0.diagnostics) }
-        : files
-    )
-  )
+  return .success(files)
+}
+
+/// The bytes of a UTF-8 byte order mark.
+let utf8ByteOrderMark: [UInt8] = [0xEF, 0xBB, 0xBF]
+
+/// The contents of the file at `path` as text, without a UTF-8 byte order mark, and the bytes that
+/// were read. `nil` when the file can't be read or isn't UTF-8.
+func readSource(atPath path: String) -> (source: String, contents: Data)? {
+  guard let contents = try? Data(contentsOf: URL(fileURLWithPath: path)) else {
+    return nil
+  }
+  let text = contents.starts(with: utf8ByteOrderMark) ? contents.dropFirst(utf8ByteOrderMark.count) : contents[...]
+  guard let source = String(bytes: text, encoding: .utf8) else {
+    return nil
+  }
+  return (source, contents)
 }
 
 /// The expanded sources as text. A single expansion is printed as it is; more than one each get a