expo-modules-macros 0.26.0 → 0.27.0

package/AGENTS.md

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

package/README.md

@@ -74,22 +74,57 @@ ExpoModulesMacros <subcommand> [options] <path> [<path> ...]
 subcommands:
   scan-modules   fast scan for top-level @ExpoModule types (autolinking)
   scan-exports   deep scan of the full JS-exported surface (type generation)
+  expand         print the code that the macros generate, and the macro diagnostics
 
 options (scan-modules only):
   --define <flag>   treat a conditional compilation flag as set; repeatable
+
+options (expand only):
+  --symbol <name>      only a type ('MyModule', 'MyModule.Options') or a member ('MyModule.greet'); repeatable
+  --diagnostics-only   only the diagnostics, followed by a summary
+  --json               a JSON report instead of text
+```
+
+For the scans, each path is a `.swift` file or a directory, scanned recursively for `.swift` files. Both scans print a JSON report to stdout, each carrying its own `schemaVersion` so a consumer can check it understands the shape before trusting it. The two versions are independent: the commands serve different consumers and change for different reasons.
+
+## Expand
+
+`expand` shows the code that the macros generate, as "Expand Macro" does in Xcode, but in a terminal and without a build. It takes `.swift` files and directories, runs the macros of this executable on them in process with swift-syntax, and prints the expanded source to stdout. The syntax errors and the macro diagnostics go to stderr in the compiler's `<file>:<line>:<column>: error: <message>` format, and the exit code is `1` when there is an error. With `--diagnostics-only`, it prints only the diagnostics, so it can check a module in CI or for an agent.
+
+```sh
+ExpoModulesMacros expand ios/HapticsModule.swift
+ExpoModulesMacros expand --symbol HapticsModule.impactAsync ios/HapticsModule.swift
+ExpoModulesMacros expand --diagnostics-only ios/
 ```
 
-Each path is a `.swift` file or a directory, scanned recursively for `.swift` files. Both subcommands print a JSON report to stdout, each carrying its own `schemaVersion` so a consumer can check it understands the shape before trusting it. The two versions are independent: the commands serve different consumers and change for different reasons.
+A file is always expanded and keeps its path as it was passed. A directory is walked like the scans walk it, skipping dependency, build, test and example directories, and only its files that use one of the macros are expanded, with their absolute paths.
+
+`--symbol` limits the output to one declaration:
+
+- A type (`HapticsModule`, `HapticsModule.ImpactStyle`) prints the expanded type and the extensions that its macros add.
+- A member (`HapticsModule.impactAsync`, `HapticsModule.init`) prints its type, expanded with only the declarations of that name (all overloads). So `_decorateModule` holds only the code for that member.
+
+With `--symbol`, only the diagnostics inside those declarations are printed.
+
+With `--json`, `expand` prints an `ExpandResult` with its own `schemaVersion`, and the exit code is `0` also with error diagnostics, because the report holds them. A missing path, a file that isn't Swift, or a symbol that no file declares is a usage error (`2`) in both modes.
+
+The macros only read the syntax tree, so the expansion is what the compiler gets, with two differences:
+
+- The names that a macro makes unique (`makeUniqueName`) can differ.
+- The compiler passes an extension macro only the conformances that the type doesn't have yet. `expand` passes all of them, and the macros skip the ones in the inheritance clause, so the result differs only for a conformance inherited from somewhere else.
+
+Errors that need type checking, for example the conformance assertions in `_assertTypesConformance`, still need a build.
 
 # TypeScript wrapper
 
 Node consumers can call the scanner through this package instead of locating the binary and shelling out themselves:
 
 ```ts
-import { scanModules, scanExports } from 'expo-modules-macros';
+import { expandMacros, scanModules, scanExports } from 'expo-modules-macros';
 
 const { modules, warnings } = await scanModules(['ios/'], { defines: ['DEBUG'], timeout: 30_000 });
 const { exports } = await scanExports(['ios/']);
+const { files } = await expandMacros(['ios/HapticsModule.swift'], { symbols: ['HapticsModule.impactAsync'] });
 ```
 
 The binary is a compiled executable, so each call still spawns a process. What the wrapper owns is the part consumers would otherwise duplicate: resolving the shipped binary, building the arguments, parsing the JSON, checking `schemaVersion`, and turning a non-zero exit or an exceeded `timeout` into a `ScannerError`. The result types are hand-written mirrors of the Swift `Codable` types, which is what the version check guards against drifting.

package/apple/Package.swift

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

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

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

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

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

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

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

package/apple/Sources/{ExpoModulesScanner → ExpoModulesCLI}/Core/SourceScan.swift

@@ -102,7 +102,13 @@ struct MacroPrefilter {
   private let bareNames: [[UInt8]]
 
   init(macros: Set<DetectedMacro>, conformances: Set<String> = []) {
-    attributes = macros.map { Array($0.rawValue.utf8) }
+    self.init(attributeNames: Set(macros.map(\.rawValue)), conformances: conformances)
+  }
+
+  /// A pre-filter for attributes that `DetectedMacro` doesn't list, such as every macro that `expand`
+  /// runs.
+  init(attributeNames: Set<String>, conformances: Set<String> = []) {
+    attributes = attributeNames.map { Array($0.utf8) }
     bareNames = conformances.map { Array($0.utf8) }
   }
 
@@ -196,7 +202,7 @@ func swiftFiles(in paths: [String]) -> [String] {
 }
 
 /// Whether `path` is a directory (following symbolic links), or `nil` if nothing exists there.
-private func isDirectory(atPath path: String, fileManager: FileManager) -> Bool? {
+func isDirectory(atPath path: String, fileManager: FileManager = .default) -> Bool? {
   #if canImport(FoundationEssentials)
   var isDirectory = false
   #else