@expo/expo-modules-macros-plugin 0.7.0 → 0.9.0

package/.github/workflows/swift.yml

@@ -54,6 +54,9 @@ jobs:
           case "$archs" in *x86_64*) ;; *) echo "Missing x86_64 slice"; exit 1;; esac
           arch -arm64 ./ExpoModulesMacros-tool < /dev/null
           arch -x86_64 ./ExpoModulesMacros-tool < /dev/null
+          # With arguments the same binary runs the scanner CLI instead of the plugin server.
+          arch -arm64 ./ExpoModulesMacros-tool --help > /dev/null
+          arch -x86_64 ./ExpoModulesMacros-tool --help > /dev/null
 
       - name: Test
         run: swift test -v

package/apple/Package.swift

@@ -8,19 +8,19 @@ import PackageDescription
 let package = Package(
   name: "ExpoModulesMacros",
   platforms: [.macOS(.v13)],
-  products: [
-    // The scanner CLI. Named `ExpoModulesScanner` (the user-facing tool name) while its target is
-    // `ExpoModulesScannerCLI`; the detection logic lives in the importable `ExpoModulesScanner`
-    // library that both the CLI and the tests depend on.
-    .executable(name: "ExpoModulesScanner", targets: ["ExpoModulesScannerCLI"]),
-  ],
   dependencies: [
     .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "602.0.0-latest")
   ],
   targets: [
+    // The plugin executable doubles as 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 the entry point in Plugin.swift). Sharing the binary keeps the package to a
+    // single shipped executable; the scanner adds little on top of the SwiftSyntax the macros
+    // already link.
     .macro(
       name: "ExpoModulesMacros",
       dependencies: [
+        "ExpoModulesScanner",
         .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
         .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
       ]
@@ -30,12 +30,9 @@ let package = Package(
       dependencies: [
         .product(name: "SwiftSyntax", package: "swift-syntax"),
         .product(name: "SwiftParser", package: "swift-syntax"),
+        .product(name: "SwiftIfConfig", package: "swift-syntax"),
       ]
     ),
-    .executableTarget(
-      name: "ExpoModulesScannerCLI",
-      dependencies: ["ExpoModulesScanner"]
-    ),
   ]
 )
 

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -4,12 +4,15 @@ import SwiftSyntax
 /// `Function(...)` / `AsyncFunction(...)` DSL entry that the runtime interprets per call, the enclosing
 /// macro synthesizes a decorator (`_decorateModule(object:)` / `_decorateSharedObject(prototype:)`) that binds each such
 /// function into the JS object via the closure-taking `JavaScriptObject.setProperty(_:)`, with the
-/// decode-call-encode body inlined into the closure. This omits the `[Any]`/`toTuple` dynamic-call path:
+/// decode-call-encode body inlined into the closure. This omits the dynamic-call path entirely:
 /// every argument is decoded individually by its static type.
 ///
 /// The receiver (see `Receiver`) is the module's `self` for a module binding, or the per-call `_self`
-/// unwrapped from the JS `this` for a shared-object binding. An `async` `@JS func` produces an `async`
-/// closure body and is installed through the async `setProperty(_:)` overload (so JS gets a promise).
+/// unwrapped from the JS `this` for a shared-object binding. An `async` `@JS func` binds through the
+/// two-phase async `setProperty(_:)` overload: the closure is the synchronous decode phase (receiver
+/// unwrap, arity guard, argument decode, all while `this` and the arguments are still valid)
+/// and returns the async body (call and result encode), so nothing JSI-owned crosses the asynchronous
+/// boundary and JS gets a promise.
 internal struct JSFunction {
   let swiftName: String
   let jsName: String
@@ -60,7 +63,7 @@ internal struct JSFunction {
     let maximum = parameters.count
     var lines: [String] = []
 
-    if let unwrap = receiver.unwrapStatement(isAsync: isAsync) {
+    if let unwrap = receiver.unwrapStatement {
       lines.append(unwrap)
     }
 
@@ -87,8 +90,31 @@ internal struct JSFunction {
     }
 
     if required == maximum {
-      // No omittable trailing run: a single flat call with every argument decoded.
-      lines.append(contentsOf: callAndEncodeLines(receiver: receiver, arity: maximum, decodingFrom: required))
+      // No omittable trailing run: a single flat call with every argument decoded. An async
+      // function decodes any remaining slots here (still the synchronous phase) and returns its
+      // body; a sync one calls and encodes directly.
+      if isAsync {
+        for index in required..<maximum {
+          lines.append(decodeStatement(at: index))
+        }
+        lines.append(contentsOf: asyncBodyLines(receiver: receiver, arity: maximum))
+      } else {
+        lines.append(contentsOf: callAndEncodeLines(receiver: receiver, arity: maximum, decodingFrom: required))
+      }
+    } else if isAsync {
+      // One body per accepted arity, branching on `arguments.count`. A branch decodes its trailing
+      // slots synchronously and returns the async body for that call shape, so each `return` ends
+      // the decode phase for its arity.
+      lines.append("switch arguments.count {")
+      for arity in required...maximum {
+        let label = arity == maximum ? "default:" : "case \(arity):"
+        lines.append(label)
+        for index in required..<arity {
+          lines.append("  " + decodeStatement(at: index))
+        }
+        lines.append(contentsOf: asyncBodyLines(receiver: receiver, arity: arity).map { "  " + $0 })
+      }
+      lines.append("}")
     } else {
       // One call shape per accepted arity, branching on `arguments.count`. A branch decodes a
       // trailing slot before the call, so this is a `switch` statement (not an expression): a
@@ -116,14 +142,32 @@ internal struct JSFunction {
       .joined(separator: "\n")
   }
 
+  /// The `return { … }` statement closing an async binding's decode phase: the returned closure is
+  /// the function's async body (`AsyncFunctionBody`), awaiting the call and encoding the result. It
+  /// captures only what the call needs — the decoded `arg<i>` locals, the receiver, and `runtime`
+  /// for the encode — never `this` or the arguments buffer, which are only valid for the duration
+  /// of the host call.
+  private func asyncBodyLines(receiver: Receiver, arity: Int) -> [String] {
+    var lines: [String] = ["return {"]
+    if returnType != nil {
+      lines.append("  let result = \(callExpression(receiver: receiver, arity: arity))")
+      lines.append(contentsOf: encodeResultLines().map { "  " + $0 })
+    } else {
+      lines.append("  \(callExpression(receiver: receiver, arity: arity))")
+      lines.append("  return .undefined")
+    }
+    lines.append("}")
+    return lines
+  }
+
   /// `let arg<index> = …` decoding the slot at `index` by its static type through
   /// `JavaScriptDecodable.decode` on the borrowed `JavaScriptUnownedValue` — no owning value, no
   /// `jsi::Value` copy, no `Any` boxing, no force-cast; it returns the concrete type directly. A
   /// primitive's `decode` is `@inlinable` and lowers to the same direct accessor a hand-rolled fast
   /// path would use.
   private func decodeStatement(at index: Int) -> String {
-    let exprType = expressionType(parameters[index].type.trimmedDescription)
-    return "let arg\(index) = try \(exprType).decode(arguments.unownedValue(at: \(index)), in: runtime)"
+    let type = parameters[index].type.trimmedDescription
+    return "let arg\(index) = try \(decodeCall(type, from: "arguments.unownedValue(at: \(index))"))"
   }
 
   /// The `<callee>.<name>(...)` call for the given arity. Slots `0..<arity` are passed their decoded
@@ -202,28 +246,25 @@ internal struct JSFunction {
   /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode
   /// body is inlined directly into the closure passed to the closure-taking `setProperty` overload
   /// (which creates the host function under the hood) — no separate named binding. For an `async`
-  /// function the body `await`s the call, which selects the async `setProperty` overload (so JS
-  /// receives a promise).
+  /// function the closure is the synchronous decode phase and returns the async body, which selects
+  /// the async `setProperty` overload (so JS receives a promise).
   ///
-  /// Capture mirrors core's `SyncFunctionDefinition.build`: a module captures its `self` **strong** —
+  /// A module captures its `self` **strong** —
   /// the host-function closure is what keeps the native callable alive for as long as JS can invoke
   /// it; its lifetime is bounded by the JS VM's garbage collection of the object. A shared object
   /// captures nothing of the instance: it recovers the typed receiver from the JS `this` per call.
   func decorateStatements(object: String, receiver: Receiver) -> String {
-    // Synchronous `@JS` bindings bind through the unowned-`this` `setProperty` overload, which hands
-    // `this` in as a borrowed `JavaScriptUnownedValue` instead of allocating an owning
-    // `JavaScriptValue` and forming its `weak`-runtime reference on every call. A module ignores
-    // `this`; a shared object unwraps it (still borrowed). The first parameter is typed `borrowing
-    // JavaScriptUnownedValue` to select that (otherwise `@_disfavoredOverload`) overload — which
-    // requires the *parenthesized, fully typed* parameter list, since Swift rejects a type annotation
-    // on a shorthand `{ [capture] name, name in }` parameter. Async functions keep the untyped
-    // shorthand and the owning-`this` overload: there is no unowned-`this` async variant and the buffer
-    // escapes into the task anyway.
+    // Every `@JS` binding hands `this` in as a borrowed `JavaScriptUnownedValue` instead of
+    // allocating an owning `JavaScriptValue` and forming its `weak`-runtime reference on every call,
+    // and consumes the arguments buffer — sync and async closures share one parameter shape and
+    // differ only in what they return. A module ignores `this`; a shared object unwraps it (still
+    // borrowed) — an async binding does so in its synchronous decode phase, before the borrow ends.
+    // The parameter list is parenthesized and fully typed, since Swift rejects a type annotation on
+    // a shorthand `{ [capture] name, name in }` parameter; for a sync binding the explicit
+    // `JavaScriptUnownedValue` also selects the (otherwise `@_disfavoredOverload`) unowned-`this`
+    // overload.
     let captures = receiver.captureClause
-    let parameters =
-      isAsync
-      ? "this, arguments"
-      : "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
+    let parameters = "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
 
     return """
         \(object).setProperty("\(jsName)") { \(captures)\(parameters) in
@@ -237,7 +278,7 @@ internal struct JSFunction {
 /// `Property(...)` DSL entry, the enclosing macro synthesizes a get/set accessor into the JS object
 /// inside its decorator (`_decorateModule(object:)` / `_decorateSharedObject(prototype:)`): it builds a descriptor object
 /// (`enumerable` + `get`, and `set` when the property is settable) and installs it with
-/// `object.defineProperty(name, descriptor:)`, mirroring core's `PropertyDefinition.buildDescriptor`.
+/// `object.defineProperty(name, descriptor:)`.
 /// The `get`/`set` host functions are installed the same way `@JS func`s are — the closure-taking
 /// `setProperty(_:)` overload, with the read/write body inlined into the closure.
 ///
@@ -268,7 +309,7 @@ internal struct JSProperty {
     // A shared object's accessors unwrap the JS `this` into `_self` before reading/writing; a module
     // reads `self` directly. The unwrap leads each accessor body. Property accessors are synchronous, so
     // they take the borrowed unowned `this`.
-    let unwrap = receiver.unwrapStatement(isAsync: false).map { "\($0)\n" } ?? ""
+    let unwrap = receiver.unwrapStatement.map { "\($0)\n" } ?? ""
     var lines: [String] = []
 
     lines.append("let \(descriptorName) = runtime.createObject()")
@@ -291,8 +332,7 @@ internal struct JSProperty {
     // getter-only (a settable var with neither an annotation nor a literal default is rare and can't
     // be decoded).
     if isSettable, let valueType {
-      let exprType = expressionType(valueType)
-      let setDecode = "\(callee).\(swiftName) = try \(exprType).decode(arguments.unownedValue(at: 0), in: runtime)"
+      let setDecode = "\(callee).\(swiftName) = try \(decodeCall(valueType, from: "arguments.unownedValue(at: 0)"))"
       lines.append(
         accessorClosure(
           descriptorName, "set", receiver: receiver, body: "\(unwrap)\(setDecode)\nreturn .undefined"))
@@ -348,9 +388,9 @@ private func decorateBody(
 /// The module decorator: a `_decorateModule(object:)` that binds every `@JS func` (via an inlined
 /// `setProperty` closure) and every `@JS var` (via a `defineProperty` accessor) into the module's own
 /// JS object. Core supplies the object; the bindings call into the module `self`. It's an *instance*
-/// method (a module is a singleton, satisfying the `AnyModule` requirement of the same name), mirroring
-/// core's `ObjectDefinition.decorate(object:)` including the `borrowing` object parameter (it mutates
-/// through the reference without reassigning or taking ownership). Only emitted when there's at least
+/// method (a module is a singleton, satisfying the `AnyModule` requirement of the same name), with a
+/// `borrowing` object parameter (it mutates through the reference without reassigning or taking
+/// ownership). Only emitted when there's at least
 /// one member to bind. Uses the shared body generation with the module `object:` phase and `self`
 /// receiver; the shared-object counterpart is `buildDecorateSharedObjectPhase`.
 internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties: [JSProperty]) -> DeclSyntax {

package/apple/Sources/ExpoModulesMacros/FreeFormTypes.swift

@@ -0,0 +1,59 @@
+/// Recognition of the free-form (`Any`-bearing) boundary types and the spellings the macros emit or
+/// suggest for them. None of these types can conform to the JS codable protocols (`Any` can't conform
+/// to a protocol, and the container conditional conformances require the element/value to conform), so
+/// they can't cross the boundary through the usual `T.decode` / `T.encode` path. Instead they're
+/// accepted **only** in decode position (function/constructor arguments), decoded through a dedicated
+/// `JavaScriptValue.decodeAny…` entry point; a free-form return or getter is rejected, since there's
+/// no free-form encode.
+///
+/// Shared across the macro pipeline: `TypeConformanceAssertion` skips them, `MacroHelpers.decodeCall`
+/// reroutes their decode, and `JSMacro` uses them for the steering diagnostics.
+
+/// The free-form boundary types: an untyped value (`Any`), an untyped array (`[Any]`), and an untyped
+/// string-keyed dictionary (`[String: Any]`). Matched by whitespace-normalized spelling so
+/// `[String: Any]` and `[String : Any]` both count.
+private let freeFormBoundaryTypes: Set<String> = ["Any", "[Any]", "[String:Any]"]
+
+/// The `JavaScriptValue.decodeAny…` method the binding calls to decode a free-form argument, keyed by
+/// the free-form type's normalized spelling. `nil` for any non-free-form type.
+private let freeFormDecodeMethods: [String: String] = [
+  "Any": "decodeAny",
+  "[Any]": "decodeAnyArray",
+  "[String:Any]": "decodeAnyDictionary",
+]
+
+/// The type-safe alternative a free-form type's diagnostic steers to: the same shape with the `Any`
+/// element replaced by `JavaScriptValue`, which conforms to the codable protocols. Keyed by the
+/// free-form type's normalized spelling; spelled with conventional spacing for the message.
+private let typedFreeFormReplacements: [String: String] = [
+  "Any": "JavaScriptValue",
+  "[Any]": "[JavaScriptValue]",
+  "[String:Any]": "[String: JavaScriptValue]",
+]
+
+/// True when a boundary type (as written) is one of the free-form spellings, ignoring internal
+/// whitespace so `[String: Any]` and `[String :Any]` both match. Optionals are not free-form here: a
+/// trailing `?` would route through `Optional.decode`, which free-form can't satisfy, so an optional
+/// free-form type isn't recognized and stays a normal (failing) assertion.
+internal func isFreeFormBoundaryType(_ type: String) -> Bool {
+  return freeFormBoundaryTypes.contains(normalizedTypeSpelling(type))
+}
+
+/// The `JavaScriptValue.decodeAny…` method name for a free-form boundary type, or `nil` when the type
+/// isn't free-form. The binding emits `JavaScriptValue.<method>(arguments.unownedValue(at:), in:)` in
+/// place of the type's own `.decode`.
+internal func freeFormDecodeMethod(for type: String) -> String? {
+  return freeFormDecodeMethods[normalizedTypeSpelling(type)]
+}
+
+/// The type-safe alternative to suggest in place of a free-form type (its `Any` element replaced by
+/// `JavaScriptValue`), or `nil` when the type isn't free-form.
+internal func typedFreeFormReplacement(for type: String) -> String? {
+  return typedFreeFormReplacements[normalizedTypeSpelling(type)]
+}
+
+/// A type spelling with all whitespace removed, so spelling variations of the same type
+/// (`[String: Any]` vs `[String :Any]`) compare equal.
+private func normalizedTypeSpelling(_ type: String) -> String {
+  return type.filter { !$0.isWhitespace }
+}

package/apple/Sources/ExpoModulesMacros/JSConstructor.swift

@@ -27,8 +27,8 @@ internal struct JSConstructor {
 
     var callArguments: [String] = []
     for (index, parameter) in parameters.enumerated() {
-      let exprType = expressionType(parameter.type.trimmedDescription)
-      lines.append("let arg\(index) = try \(exprType).decode(arguments.unownedValue(at: \(index)), in: runtime)")
+      let type = parameter.type.trimmedDescription
+      lines.append("let arg\(index) = try \(decodeCall(type, from: "arguments.unownedValue(at: \(index))"))")
 
       let label = parameter.firstName.text
       callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -1,3 +1,4 @@
+import SwiftDiagnostics
 import SwiftSyntax
 import SwiftSyntaxMacros
 
@@ -30,6 +31,8 @@ public struct JSMacro: PeerMacro {
     providingPeersOf declaration: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
+    diagnoseFreeFormTypes(in: declaration, in: context)
+
     guard let member = boundaryMember(of: declaration),
       let assertion = directionalConformanceAssertion(
         name: member.name,
@@ -43,6 +46,115 @@ public struct JSMacro: PeerMacro {
   }
 }
 
+/// Emits the free-form (`Any` / `[Any]` / `[String: Any]`) diagnostics for a `@JS` declaration.
+///
+/// A free-form type is only supported crossing the boundary as an **argument**, decoded through
+/// `JavaScriptValue.decodeAny…`; there is no free-form encode, so any position that encodes is a hard
+/// error. That means:
+/// - a function/constructor **parameter** typed free-form gets a warning steering to
+///   `[String: JavaScriptValue]` (the type-safe alternative), but compiles;
+/// - a function **return** typed free-form is an error (it would need to encode);
+/// - a **property** typed free-form is an error regardless of settability, because its getter always
+///   encodes.
+///
+/// Types are matched by their written spelling on the type node, so the diagnostic points at the
+/// offending type in the user's source.
+private func diagnoseFreeFormTypes(
+  in declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
+    warnFreeFormArguments(funcDecl.signature.parameterClause.parameters, in: context)
+    if let returnType = funcDecl.signature.returnClause?.type,
+      isFreeFormBoundaryType(returnType.trimmedDescription) {
+      context.diagnose(
+        Diagnostic(node: returnType, message: freeFormReturnError(for: returnType.trimmedDescription)))
+    }
+    return
+  }
+
+  // A constructor decodes its arguments exactly like a function; it has no return value to encode, so
+  // only the argument warning applies.
+  if let initDecl = declaration.as(InitializerDeclSyntax.self) {
+    warnFreeFormArguments(initDecl.signature.parameterClause.parameters, in: context)
+    return
+  }
+
+  if let varDecl = declaration.as(VariableDeclSyntax.self),
+    let type = varDecl.bindings.first?.typeAnnotation?.type,
+    isFreeFormBoundaryType(type.trimmedDescription) {
+    context.diagnose(
+      Diagnostic(node: type, message: freeFormPropertyError(for: type.trimmedDescription)))
+  }
+}
+
+/// The tail of a free-form encode error: the reshaped `JavaScriptValue` alternative when the type is a
+/// container (`[String: Any]` -> `[String: JavaScriptValue]`), otherwise the passthrough suggestion
+/// for a bare `Any`. Both conform to the codable protocols, so either is a valid fix.
+private func suggestedAlternative(for freeFormType: String) -> String {
+  if let reshaped = typedFreeFormReplacement(for: freeFormType), reshaped != "JavaScriptValue" {
+    return "Use '\(reshaped)', or 'JavaScriptValue' to pass a JS value through unchanged."
+  }
+  return "Use a concrete type, or 'JavaScriptValue' to pass a JS value through unchanged."
+}
+
+/// Emits the steering warning for each free-form parameter in a list. Shared by the function and
+/// constructor cases, which both decode their arguments through the same path.
+private func warnFreeFormArguments(
+  _ parameters: FunctionParameterListSyntax,
+  in context: some MacroExpansionContext
+) {
+  for parameter in parameters {
+    let type = parameter.type.trimmedDescription
+    guard let suggested = typedFreeFormReplacement(for: type) else {
+      continue
+    }
+    context.diagnose(
+      Diagnostic(
+        node: parameter.type,
+        message: freeFormArgumentWarning(for: type, suggesting: suggested)))
+  }
+}
+
+private func freeFormArgumentWarning(
+  for freeFormType: String,
+  suggesting suggestedType: String
+) -> JSDiagnosticMessage {
+  return JSDiagnosticMessage(
+    "Prefer '\(suggestedType)' over the free-form '\(freeFormType)' for a @JS argument. Free-form decoding boxes every value as 'Any' (slower, no static typing); the 'JavaScriptValue' element keeps each value inspectable without erasing it.",
+    id: "js-free-form-argument",
+    severity: .warning
+  )
+}
+
+private func freeFormReturnError(for freeFormType: String) -> JSDiagnosticMessage {
+  return JSDiagnosticMessage(
+    "A @JS function can't return the free-form '\(freeFormType)': there's no way to encode an untyped value back to JavaScript. \(suggestedAlternative(for: freeFormType))",
+    id: "js-free-form-return",
+    severity: .error
+  )
+}
+
+private func freeFormPropertyError(for freeFormType: String) -> JSDiagnosticMessage {
+  return JSDiagnosticMessage(
+    "A @JS property can't have the free-form '\(freeFormType)': its getter would have to encode an untyped value back to JavaScript, which isn't supported. \(suggestedAlternative(for: freeFormType))",
+    id: "js-free-form-property",
+    severity: .error
+  )
+}
+
+private struct JSDiagnosticMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID: MessageID
+  let severity: DiagnosticSeverity
+
+  init(_ message: String, id: String, severity: DiagnosticSeverity) {
+    self.message = message
+    self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+    self.severity = severity
+  }
+}
+
 /// What an assertion peer needs about the `@JS` member it sits beside: a name (to keep the peer unique
 /// among siblings), the boundary types split by conversion direction, and whether the member is
 /// type-level. Arguments (and a settable property's incoming value) are decoded; return values (and a

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -261,6 +261,18 @@ internal func expressionType(_ type: String) -> String {
   return type.dropLast() + "?"
 }
 
+/// The decode expression for a boundary type read from `valueExpression` (a `JavaScriptUnownedValue`),
+/// as it appears after `try`. A free-form type (`Any`, `[Any]`, `[String: Any]`) can't conform to
+/// `JavaScriptDecodable`, so it decodes through the dedicated `JavaScriptValue.decodeAny…` entry point
+/// keyed to its shape; every other type decodes through its own static `decode`, spelled in expression
+/// position (`T!` rewritten to `T?`).
+internal func decodeCall(_ type: String, from valueExpression: String) -> String {
+  if let method = freeFormDecodeMethod(for: type) {
+    return "JavaScriptValue.\(method)(\(valueExpression), in: runtime)"
+  }
+  return "\(expressionType(type)).decode(\(valueExpression), in: runtime)"
+}
+
 // MARK: - @JS property collection
 
 /// Collects the `@JS var` bindings of a declaration into `JSProperty` values for direct JSI binding.

package/apple/Sources/ExpoModulesMacros/Plugin.swift

@@ -1,7 +1,8 @@
+import ExpoModulesScanner
+import Foundation
 import SwiftCompilerPlugin
 import SwiftSyntaxMacros
 
-@main
 struct ExpoModulesMacrosPlugin: CompilerPlugin {
   let providingMacros: [Macro.Type] = [
     OptimizedFunctionAttachedMacro.self,
@@ -12,3 +13,19 @@ struct ExpoModulesMacrosPlugin: CompilerPlugin {
     RecordMacro.self,
   ]
 }
+
+/// The executable doubles as the scanner CLI. The compiler always launches a plugin executable
+/// without arguments and speaks the plugin protocol over stdin, so any argument means a scanner
+/// invocation (`ExpoModulesMacros-tool scan-modules <path>...`); with none, this starts the plugin
+/// server exactly as `@main` on the `CompilerPlugin` type would.
+@main
+enum EntryPoint {
+  static func main() throws {
+    let arguments = Array(CommandLine.arguments.dropFirst())
+    if arguments.isEmpty {
+      try ExpoModulesMacrosPlugin.main()
+    } else {
+      exit(ScannerCLI.run(arguments: arguments))
+    }
+  }
+}

package/apple/Sources/ExpoModulesMacros/Receiver.swift

@@ -39,16 +39,15 @@ internal enum Receiver {
   /// `native(from:as:)` recovers the typed instance from `this`, throwing on a foreign object or a type
   /// mismatch.
   ///
-  /// The `this` object comes from the borrowed `JavaScriptUnownedValue` in a sync binding (`asObject(in:)`)
-  /// and from the owning `JavaScriptValue` in an async one (`asObject()`). An async binding must take an
-  /// owning `this` because a borrowed unowned value can't survive the closure's suspension points.
-  func unwrapStatement(isAsync: Bool) -> String? {
+  /// The `this` object always comes from the borrowed `JavaScriptUnownedValue` (`asObject(in:)`): an
+  /// async binding unwraps in its synchronous decode phase, before the borrowed value's lifetime ends,
+  /// and only the recovered native instance crosses into the async body.
+  var unwrapStatement: String? {
     switch self {
     case .module, .staticMember:
       return nil
     case .sharedObject(let typeName):
-      let thisObject = isAsync ? "this.asObject()" : "this.asObject(in: runtime)"
-      return "let _self = try SharedObject.native(from: \(thisObject), as: \(typeName).self)"
+      return "let _self = try SharedObject.native(from: this.asObject(in: runtime), as: \(typeName).self)"
     }
   }
 
@@ -67,7 +66,7 @@ internal enum Receiver {
 /// Which JS object a set of bindings is installed on: the second orthogonal axis alongside `Receiver`.
 /// It selects the decorator entry point's argument label and the local name the body binds members onto,
 /// mirroring JS class semantics (a class has a constructor function whose `.prototype` carries instance
-/// members) and core's `ClassDefinition.decorate`.
+/// members).
 /// The raw value is the argument label of the decorator entry point, which is also the local name the
 /// body binds members onto.
 internal enum Phase: String {

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -116,11 +116,15 @@ internal func typeConformanceAssertions(
     """
 }
 
-/// The type to assert for a boundary type as written: trailing optional markers are unwrapped to the
-/// core type, and a known-conforming primitive returns `nil` (nothing to assert). Shared with
-/// `@Event`, which folds its single payload type into a combined assertion of its own shape rather
-/// than reusing the whole body fragment below.
+/// The type to assert for a boundary type as written, or `nil` when nothing needs asserting: an
+/// exactly-free-form type (handled by the binding's `decodeAny…` reroute) and a known-conforming
+/// primitive both return `nil`; everything else is unwrapped of trailing optionals and asserted. An
+/// *optional* free-form (`[String: Any]?`) isn't rerouted and doesn't conform, so it's kept and
+/// asserted for a clean diagnostic. Shared with `@Event`.
 internal func assertableBoundaryType(_ type: String) -> String? {
+  guard !isFreeFormBoundaryType(type) else {
+    return nil
+  }
   let unwrapped = unwrappedOptional(type)
   return knownConformingPrimitives.contains(unwrapped) ? nil : unwrapped
 }
@@ -144,14 +148,12 @@ private func conformanceAssertionBody(
   return lines.joined(separator: "\n")
 }
 
-/// Normalizes a list of boundary types for assertion: unwraps each to its core type (trailing
-/// optionals stripped), drops the known-conforming primitives that never need asserting, and dedups
-/// while preserving first-seen order so a type is asserted once even when it appears more than once.
+/// The distinct types to assert from a list, mapping each through `assertableBoundaryType` (which
+/// drops what needs no assertion) and deduping in first-seen order.
 private func distinctAssertableTypes(_ types: [String]) -> [String] {
   var seen: Set<String> = []
   var distinct: [String] = []
-  for type in types.map(unwrappedOptional)
-  where !knownConformingPrimitives.contains(type) && seen.insert(type).inserted {
+  for type in types.compactMap(assertableBoundaryType) where seen.insert(type).inserted {
     distinct.append(type)
   }
   return distinct

package/apple/Sources/ExpoModulesScanner/CLI.swift

@@ -0,0 +1,110 @@
+import Foundation
+
+/// Command-line front end for the scanner: parses the subcommand and paths, then delegates to the
+/// matching `Scanner` entry (which runs the scan and writes its JSON output). Lives in the library
+/// so the macro plugin executable can dispatch into it: the compiler always launches that executable
+/// without arguments and speaks the plugin protocol over stdin, so any argument means a scanner
+/// invocation. Each path may be a `.swift` file or a directory (scanned recursively for `.swift`
+/// files).
+///
+/// Subcommands:
+///   scan-modules   <path>...   fast: top-level `@ExpoModule` types, for autolinking
+///   scan-exports   <path>...   deep: full JS-exported surface, for TS type generation
+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 {
+    // `-h`/`--help` anywhere is treated as a help request: print usage to stdout and exit 0.
+    if arguments.contains(where: { $0 == "-h" || $0 == "--help" }) {
+      printUsage(to: .standardOutput)
+      return 0
+    }
+
+    guard let subcommand = arguments.first else {
+      printUsage()
+      return 2
+    }
+
+    var paths: [String] = []
+    var platform: String?
+    var defines: [String] = []
+
+    var rest = arguments.dropFirst().makeIterator()
+    while let argument = rest.next() {
+      switch argument {
+      case "--platform":
+        guard let value = rest.next() else {
+          return usageError("--platform requires a value")
+        }
+        platform = value
+      case "--define":
+        guard let value = rest.next() else {
+          return usageError("--define requires a value")
+        }
+        defines.append(value)
+      default:
+        paths.append(argument)
+      }
+    }
+
+    switch subcommand {
+    case "scan-modules":
+      guard !paths.isEmpty else {
+        return usageError("scan-modules requires at least one path")
+      }
+      return Scanner.runModules(paths: paths, platform: platform, defines: defines)
+
+    case "scan-exports":
+      // The exports surface visitor doesn't evaluate `#if` blocks yet, so accepting the options
+      // here would silently do nothing.
+      guard platform == nil, defines.isEmpty else {
+        return usageError("scan-exports does not support --platform or --define")
+      }
+      guard !paths.isEmpty else {
+        return usageError("scan-exports requires at least one path")
+      }
+      return Scanner.runExports(paths: paths)
+
+    default:
+      return usageError("unknown subcommand '\(subcommand)'")
+    }
+  }
+}
+
+/// The invoked executable's basename, so the usage text matches however the tool was launched
+/// (the `ExpoModulesMacros-tool` shipped in the package, or a locally built copy).
+private var toolName: String {
+  return (CommandLine.arguments.first as NSString?)?.lastPathComponent ?? "ExpoModulesScanner"
+}
+
+private var usageText: String {
+  """
+  usage: \(toolName) <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)
+
+  options (scan-modules only):
+    --platform <os>   evaluate '#if os(...)' against this platform (iOS, macOS, tvOS, ...);
+                      without it, os-conditional declarations are skipped with a warning
+    --define <flag>   treat a conditional compilation flag (e.g. DEBUG) as set; repeatable
+
+  options:
+    -h, --help        print this help and exit
+
+  """
+}
+
+/// Prints the usage text to the given handle. Goes to stdout when help was explicitly requested
+/// (a successful action), stderr when it accompanies a usage error.
+private func printUsage(to handle: FileHandle = .standardError) {
+  handle.write(Data(usageText.utf8))
+}
+
+/// Reports a usage error on stderr, followed by the usage text, and returns the usage exit code.
+private func usageError(_ message: String) -> Int32 {
+  FileHandle.standardError.write(Data("error: \(message)\n".utf8))
+  printUsage()
+  return 2
+}

package/apple/Sources/ExpoModulesScanner/Core/Detection.swift

@@ -33,6 +33,12 @@ struct Detection: Codable, Equatable {
   /// The kind of declaration the macro was attached to: `class`, `struct`, `func`, `var`, `init`, …
   let declarationKind: String
 
+  /// The declaration's spelled access modifier (`open`, `public`, `package`, `fileprivate`,
+  /// `private`), or `internal` when none is written. Consumers that reference the declaration from
+  /// another Swift module (the generated modules provider does) need `public`/`open` and can reject
+  /// the rest up front instead of failing at compile time.
+  let accessLevel: String
+
   /// The explicit JS name override when written as `@ExpoModule("Foo")` / `@JS("bar")` /
   /// `@SharedObject("Baz")`, otherwise `nil` (the name defaults to `name` at expansion time).
   let jsName: String?
@@ -47,6 +53,16 @@ struct Detection: Codable, Equatable {
   let column: Int
 }
 
+/// A non-fatal problem found while scanning, tied to the source location that caused it — today,
+/// an `#if` condition the scan's static configuration cannot answer (`canImport`, `arch`, an
+/// `os(...)` check with no `--platform` given, …). The affected region is treated as inactive, so
+/// the warning tells the consumer which declarations may have been skipped and why.
+struct ScanWarning: Codable, Equatable {
+  let message: String
+  let file: String
+  let line: Int
+}
+
 /// Counts describing how much work the scan did, so callers can see the pre-filter's effect: of all
 /// the `.swift` files read, how many actually needed parsing, and how long the run took.
 struct ScanStats: Codable, Equatable {

package/apple/Sources/ExpoModulesScanner/Core/DetectionVisitor.swift

@@ -1,3 +1,4 @@
+import SwiftIfConfig
 import SwiftSyntax
 
 /// Walks a parsed source file and records top-level declarations carrying `@ExpoModule`, `@JS`,
@@ -6,7 +7,12 @@ import SwiftSyntax
 /// Recognition mirrors the macros themselves — a purely syntactic match on the spelled attribute
 /// name — so it sees the same declarations the compiler would hand the plugin, without compiling
 /// anything.
-final class DetectionVisitor: SyntaxVisitor {
+///
+/// `#if` blocks are handled by the `ActiveSyntaxVisitor` base: only clauses active under the scan's
+/// `ScanBuildConfiguration` are visited, so a declaration inside `#if os(tvOS)` is recorded exactly
+/// when the scan targets tvOS. Conditions the configuration cannot answer make their region
+/// inactive and land in the inherited `diagnostics`, which the scan surfaces as warnings.
+final class DetectionVisitor: ActiveSyntaxVisitor {
   private let file: String
   private let converter: SourceLocationConverter
   /// Only these macros are recorded; the rest are ignored. Lets a `modules` scan report just
@@ -14,16 +20,30 @@ final class DetectionVisitor: SyntaxVisitor {
   private let detectedMacros: Set<DetectedMacro>
   private(set) var detections: [Detection] = []
 
-  init(file: String, tree: SourceFileSyntax, detectedMacros: Set<DetectedMacro>) {
+  init(
+    file: String,
+    tree: SourceFileSyntax,
+    detectedMacros: Set<DetectedMacro>,
+    configuration: ScanBuildConfiguration
+  ) {
     self.file = file
     self.converter = SourceLocationConverter(fileName: file, tree: tree)
     self.detectedMacros = detectedMacros
-    super.init(viewMode: .sourceAccurate)
+    super.init(viewMode: .sourceAccurate, configuration: configuration)
+  }
+
+  /// The accumulated `#if` warnings as `Detection`-style locations plus the message, ready for the
+  /// scan report. These come from conditions the configuration cannot answer statically.
+  var warnings: [ScanWarning] {
+    return diagnostics.map { diagnostic in
+      let location = diagnostic.location(converter: converter)
+      return ScanWarning(message: diagnostic.message, file: file, line: location.line)
+    }
   }
 
   override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {
     if isTopLevel(node) {
-      record(attributes: node.attributes, name: node.name.text, kind: "class", at: node)
+      record(attributes: node.attributes, modifiers: node.modifiers, name: node.name.text, kind: "class", at: node)
     }
     // Members live in the type body; we never report them, so there's no reason to descend.
     return .skipChildren
@@ -31,29 +51,45 @@ final class DetectionVisitor: SyntaxVisitor {
 
   override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind {
     if isTopLevel(node) {
-      record(attributes: node.attributes, name: node.name.text, kind: "struct", at: node)
+      record(attributes: node.attributes, modifiers: node.modifiers, name: node.name.text, kind: "struct", at: node)
     }
     return .skipChildren
   }
 
-  /// True when the declaration sits at file scope: its parent is a `CodeBlockItemSyntax` directly
-  /// under the source file's top-level item list. Members of a type are nested in a
-  /// `MemberBlockItemSyntax` instead, so they don't match.
+  /// True when the declaration sits at file scope: its parent chain reaches the source file through
+  /// only code-block items and `#if` structure. Members of a type are nested in a
+  /// `MemberBlockItemSyntax` instead, so they don't match. The `#if` wrappers are allowed because a
+  /// top-level declaration inside an (active) `#if` clause is still a top-level declaration.
   ///
   /// TODO: decide whether to support nested types. A macro on a type nested in another type/enum/
   /// extension is valid Swift but missed here; supporting it means descending into type bodies and
   /// recording the enclosing path for a qualified name (e.g. `Namespace.InnerModule`).
   private func isTopLevel(_ node: some SyntaxProtocol) -> Bool {
-    guard let item = node.parent?.as(CodeBlockItemSyntax.self) else {
+    guard node.parent?.is(CodeBlockItemSyntax.self) == true else {
       return false
     }
-    return item.parent?.parent?.is(SourceFileSyntax.self) == true
+    var current = node.parent?.parent
+    while let node = current {
+      if node.is(SourceFileSyntax.self) {
+        return true
+      }
+      guard node.is(CodeBlockItemListSyntax.self)
+        || node.is(CodeBlockItemSyntax.self)
+        || node.is(IfConfigClauseSyntax.self)
+        || node.is(IfConfigClauseListSyntax.self)
+        || node.is(IfConfigDeclSyntax.self) else {
+        return false
+      }
+      current = node.parent
+    }
+    return false
   }
 
   /// Emits one detection per recognized Expo attribute on the declaration. A declaration can in
   /// principle carry more than one (uncommon), so each is recorded independently.
   private func record(
     attributes: AttributeListSyntax,
+    modifiers: DeclModifierListSyntax,
     name: String,
     kind: String,
     at node: some SyntaxProtocol
@@ -70,6 +106,7 @@ final class DetectionVisitor: SyntaxVisitor {
           macro: macro,
           name: name,
           declarationKind: kind,
+          accessLevel: accessLevel(of: modifiers),
           jsName: stringArgument(of: attribute),
           arguments: arguments(of: attribute),
           file: file,
@@ -81,6 +118,19 @@ final class DetectionVisitor: SyntaxVisitor {
   }
 }
 
+/// The spelled access modifiers, in the order Swift defines them. Other modifiers (`final`,
+/// `static`, …) are not access levels and are skipped when resolving one.
+private let accessModifierNames: Set<String> = ["open", "public", "package", "internal", "fileprivate", "private"]
+
+/// The declaration's access level: the first spelled access modifier, or Swift's default of
+/// `internal` when none is written. A declaration can spell at most one, so first is the only one.
+private func accessLevel(of modifiers: DeclModifierListSyntax) -> String {
+  for modifier in modifiers where accessModifierNames.contains(modifier.name.text) {
+    return modifier.name.text
+  }
+  return "internal"
+}
+
 /// Every argument passed to the attribute, in source order, each as a label (or `nil` when
 /// positional) plus the value expression's source text. Returns an empty array when the attribute
 /// is written bare (`@ExpoModule`) or with empty parens.

package/apple/Sources/ExpoModulesScanner/Core/ScanBuildConfiguration.swift

@@ -0,0 +1,121 @@
+import SwiftIfConfig
+import SwiftSyntax
+
+/// The build configuration that `#if` conditions are evaluated against during a scan, built from
+/// the CLI's `--platform` and `--define` options. The scan is static: it knows the target OS and
+/// the spelled compilation flags, and nothing else. Every condition it cannot answer throws, which
+/// SwiftIfConfig turns into an inactive region plus a diagnostic, so an unanswerable `#if` skips
+/// its declarations and surfaces a warning instead of guessing.
+struct ScanBuildConfiguration: BuildConfiguration {
+  /// The target OS name to answer `os(...)` with, as spelled in the condition (`iOS`, `macOS`,
+  /// `tvOS`, `watchOS`, `visionOS`; compared case-insensitively), or `nil` when no `--platform`
+  /// was given, in which case `os(...)` conditions are unanswerable.
+  let platform: String?
+
+  /// The conditional compilation flags treated as set, from repeated `--define` options.
+  let defines: Set<String>
+
+  func isCustomConditionSet(name: String) throws -> Bool {
+    return defines.contains(name)
+  }
+
+  func isActiveTargetOS(name: String) throws -> Bool {
+    guard let platform else {
+      throw ScanConfigurationError("cannot evaluate 'os(\(name))': no --platform was given")
+    }
+    return name.lowercased() == platform.lowercased()
+  }
+
+  // MARK: - Unanswerable conditions
+
+  // These vary within a single platform's build (device vs simulator, arm64 vs x86_64) or depend
+  // on the consumer's toolchain, so a static scan has no correct answer. Throwing makes the region
+  // inactive and emits a warning naming the condition.
+
+  func hasFeature(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate 'hasFeature(\(name))' in a static scan")
+  }
+
+  func hasAttribute(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate 'hasAttribute(\(name))' in a static scan")
+  }
+
+  func canImport(importPath: [(TokenSyntax, String)], version: CanImportVersion) throws -> Bool {
+    let module = importPath.map(\.1).joined(separator: ".")
+
+    // A curated set of SDK frameworks is answerable from the target platform alone. Everything
+    // else (arbitrary modules, submodule paths, versioned checks) stays unanswerable: a wrong
+    // "yes" would surface a declaration that doesn't exist in the real build.
+    guard importPath.count == 1,
+      case .unversioned = version,
+      let frameworkPlatforms = sdkFrameworkPlatforms[module] else {
+      throw ScanConfigurationError("cannot evaluate 'canImport(\(module))' in a static scan")
+    }
+    guard let platform else {
+      throw ScanConfigurationError("cannot evaluate 'canImport(\(module))': no --platform was given")
+    }
+    return frameworkPlatforms.contains(platform.lowercased())
+  }
+
+  func isActiveTargetArchitecture(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate 'arch(\(name))' in a static scan")
+  }
+
+  func isActiveTargetEnvironment(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate 'targetEnvironment(\(name))' in a static scan")
+  }
+
+  func isActiveTargetRuntime(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate '_runtime(\(name))' in a static scan")
+  }
+
+  func isActiveTargetPointerAuthentication(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate '_ptrauth(\(name))' in a static scan")
+  }
+
+  // MARK: - Fixed answers
+
+  // Non-throwing protocol requirements, so they need a value. These are constant across Apple
+  // targets (the only ones Expo modules compile for), except the versions, which assume a current
+  // toolchain; a module class gated on a *lower* Swift version would be wrongly included, which is
+  // rare enough to accept for a scan.
+
+  var targetPointerBitWidth: Int { 64 }
+  var targetAtomicBitWidths: [Int] { [32, 64, 128] }
+  var endianness: Endianness { .little }
+  var languageVersion: VersionTuple { VersionTuple(6) }
+  var compilerVersion: VersionTuple { VersionTuple(6, 2) }
+}
+
+/// The platforms (lowercased, as compared against `--platform`) that ship each of a curated set of
+/// Apple SDK frameworks, so `canImport` of one is answerable from the platform alone. The list is
+/// deliberately small and high-confidence: it covers the frameworks realistically used to gate a
+/// module class, and a framework missing here degrades to the skip-with-warning path rather than a
+/// wrong answer.
+private let sdkFrameworkPlatforms: [String: Set<String>] = [
+  "UIKit": ["ios", "tvos", "watchos", "visionos"],
+  "AppKit": ["macos"],
+  "SwiftUI": ["ios", "macos", "tvos", "watchos", "visionos"],
+  "WatchKit": ["watchos"],
+  "TVUIKit": ["tvos"],
+  "WebKit": ["ios", "macos", "visionos"],
+  "SafariServices": ["ios", "macos", "visionos"],
+  "ARKit": ["ios", "visionos"],
+  "RealityKit": ["ios", "macos", "visionos"],
+  "CarPlay": ["ios"],
+  "MessageUI": ["ios"],
+  "CoreNFC": ["ios"],
+  "HealthKit": ["ios", "watchos", "visionos"],
+  "HomeKit": ["ios", "tvos", "watchos", "visionos"],
+  "WidgetKit": ["ios", "macos", "watchos", "visionos"],
+]
+
+/// An unanswerable `#if` condition. SwiftIfConfig converts the thrown error into a diagnostic on
+/// the condition's node and treats the region as inactive.
+struct ScanConfigurationError: Error, CustomStringConvertible {
+  let description: String
+
+  init(_ description: String) {
+    self.description = description
+  }
+}

package/apple/Sources/ExpoModulesScanner/Core/SourceScan.swift

@@ -44,23 +44,36 @@ func scanFiles(
 }
 
 /// Walks `paths`, parses each `.swift` file that might contain one of `macros`, and returns every
-/// detection (in file then source order) with the run's stats — the shape `scan-modules` projects.
-/// A thin layer over `scanFiles` that accumulates the per-file detections.
-func collectDetections(paths: [String], macros: Set<DetectedMacro>) -> (detections: [Detection], stats: ScanStats) {
+/// detection (in file then source order) with the accumulated `#if` warnings and the run's stats —
+/// the shape `scan-modules` projects. A thin layer over `scanFiles` that accumulates the per-file
+/// results.
+func collectDetections(
+  paths: [String],
+  macros: Set<DetectedMacro>,
+  configuration: ScanBuildConfiguration = .init(platform: nil, defines: [])
+) -> (detections: [Detection], warnings: [ScanWarning], stats: ScanStats) {
   var detections: [Detection] = []
+  var warnings: [ScanWarning] = []
   let stats = scanFiles(paths: paths, macros: macros) { source, file in
-    detections.append(contentsOf: detect(source: source, file: file, macros: macros))
+    let result = detect(source: source, file: file, macros: macros, configuration: configuration)
+    detections.append(contentsOf: result.detections)
+    warnings.append(contentsOf: result.warnings)
   }
-  return (detections, stats)
+  return (detections, warnings, stats)
 }
 
-/// Parses one source string and returns its detections for the given macro set. The unit of work the
-/// tests exercise.
-func detect(source: String, file: String, macros: Set<DetectedMacro>) -> [Detection] {
+/// Parses one source string and returns its detections for the given macro set, plus the warnings
+/// for `#if` conditions the configuration couldn't answer. The unit of work the tests exercise.
+func detect(
+  source: String,
+  file: String,
+  macros: Set<DetectedMacro>,
+  configuration: ScanBuildConfiguration
+) -> (detections: [Detection], warnings: [ScanWarning]) {
   let tree = Parser.parse(source: source)
-  let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: macros)
+  let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: macros, configuration: configuration)
   visitor.walk(tree)
-  return visitor.detections
+  return (visitor.detections, visitor.warnings)
 }
 
 // MARK: - Pre-filter
@@ -89,8 +102,9 @@ func mightContainMacro(in source: String, prefilter: NSRegularExpression) -> Boo
 
 /// Directory names skipped during the recursive walk. These hold build products, dependencies, and
 /// git internals — never source worth scanning — and pruning them keeps the walk from descending
-/// into the bulk of a monorepo's files.
-private let prunedDirectoryNames: Set<String> = [".build", "Pods", ".git"]
+/// into the bulk of a monorepo's files. `node_modules` makes any npm package root safe to pass as a
+/// scan path: nested dependencies are separate packages and get scanned on their own.
+private let prunedDirectoryNames: Set<String> = [".build", "Pods", ".git", "node_modules"]
 
 /// Expands the given paths into the list of `.swift` files to parse: a file path passes through,
 /// a directory is enumerated recursively (skipping `prunedDirectoryNames`). Order is deterministic

package/apple/Sources/ExpoModulesScanner/Modules/ScanModules.swift

@@ -9,8 +9,12 @@ public enum Scanner {
   /// Runs the `scan-modules` command over `paths`, prints the JSON report to stdout, and returns a
   /// process exit code: `0` on success, `1` if encoding fails. (The deep `scan-exports` command has
   /// its own `runExports` entry returning its own result type.)
-  public static func runModules(paths: [String]) -> Int32 {
-    let result = scanModules(paths: paths)
+  ///
+  /// `platform` and `defines` (the `--platform` and `--define` options) form the configuration that
+  /// `#if` conditions are evaluated against; see `ScanBuildConfiguration`.
+  public static func runModules(paths: [String], platform: String? = nil, defines: [String] = []) -> Int32 {
+    let configuration = ScanBuildConfiguration(platform: platform, defines: Set(defines))
+    let result = scanModules(paths: paths, configuration: configuration)
 
     do {
       let encoder = JSONEncoder()
@@ -40,29 +44,51 @@ struct ScannedModule: Codable, Equatable {
   /// and the consumer never has to apply the fallback itself.
   let jsName: String
 
+  /// The class's spelled access modifier (`open`, `public`, `package`, `fileprivate`, `private`),
+  /// or `internal` when none is written. The generated modules provider references the class from
+  /// the app target, which requires `public`/`open`, so the consumer uses this to skip inaccessible
+  /// classes with a diagnostic instead of emitting a provider that fails to compile.
+  let accessLevel: String
+
   /// Source file the module was found in, relative to the path the scanner was invoked with.
   let file: String
 }
 
+/// Version of the `scan-modules` output shape. Bumped on any breaking change to the envelope or to
+/// `ScannedModule`, so `expo-modules-autolinking` can verify it understands the output before
+/// trusting it (and fall back to config-declared modules when it doesn't).
+let scanModulesSchemaVersion = 1
+
 /// The `scan-modules` result: the detected modules plus the stats describing the run. Encoded as the
 /// command's JSON output. (`scan-exports` returns its own `ScanExportsResult` shape; the two commands
 /// serve different consumers and don't share an envelope.)
 struct ScanModulesResult: Codable, Equatable {
+  let schemaVersion: Int
   let modules: [ScannedModule]
+
+  /// Warnings for `#if` conditions the scan couldn't answer statically (see `ScanWarning`). Carried
+  /// in the report rather than on stderr so the consumer can attach them to its own output.
+  let warnings: [ScanWarning]
+
   let stats: ScanStats
 }
 
 /// Scans the given paths for top-level `@ExpoModule` types and returns the modules (in file then
 /// source order) plus the stats for the run — the `scan-modules` command. Kept separate from the
 /// public entry (and `internal`) so tests can drive it without going through argv/stdout.
-func scanModules(paths: [String]) -> ScanModulesResult {
-  let scan = collectDetections(paths: paths, macros: [.expoModule])
+func scanModules(paths: [String], configuration: ScanBuildConfiguration = .init(platform: nil, defines: [])) -> ScanModulesResult {
+  let scan = collectDetections(paths: paths, macros: [.expoModule], configuration: configuration)
 
   let modules = scan.detections.map {
     // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")` override, else the
     // class name.
-    ScannedModule(name: $0.name, jsName: $0.jsName ?? $0.name, file: $0.file)
+    ScannedModule(name: $0.name, jsName: $0.jsName ?? $0.name, accessLevel: $0.accessLevel, file: $0.file)
   }
 
-  return ScanModulesResult(modules: modules, stats: scan.stats)
+  return ScanModulesResult(
+    schemaVersion: scanModulesSchemaVersion,
+    modules: modules,
+    warnings: scan.warnings,
+    stats: scan.stats
+  )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/expo-modules-macros-plugin",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Swift macro plugin for Expo modules",
   "license": "MIT",
   "author": "650 Industries, Inc.",

package/apple/Sources/ExpoModulesScannerCLI/main.swift

@@ -1,71 +0,0 @@
-import ExpoModulesScanner
-import Foundation
-
-/// Command-line front end for the scanner. Parses the subcommand and paths, then delegates to the
-/// matching library entry (which runs the scan and writes its JSON output). Each path may be a
-/// `.swift` file or a directory (scanned recursively for `.swift` files).
-///
-/// Subcommands:
-///   scan-modules   <path>...   fast: top-level `@ExpoModule` types, for autolinking
-///   scan-exports   <path>...   deep: full JS-exported surface, for TS type generation
-
-let toolName = "ExpoModulesScanner"
-
-let usageText = """
-  usage: \(toolName) <subcommand> <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)
-
-  options:
-    -h, --help     print this help and exit
-
-  """
-
-/// Prints the usage text to the given handle. Goes to stdout when help was explicitly requested
-/// (a successful action), stderr when it accompanies a usage error.
-func printUsage(to handle: FileHandle = .standardError) {
-  handle.write(Data(usageText.utf8))
-}
-
-func fail(_ message: String, usage: Bool = false, code: Int32 = 2) -> Never {
-  FileHandle.standardError.write(Data("error: \(message)\n".utf8))
-  if usage {
-    printUsage()
-  }
-  exit(code)
-}
-
-var arguments = Array(CommandLine.arguments.dropFirst())
-
-// `-h`/`--help` anywhere is treated as a help request: print usage to stdout and exit 0.
-if arguments.contains(where: { $0 == "-h" || $0 == "--help" }) {
-  printUsage(to: .standardOutput)
-  exit(0)
-}
-
-guard !arguments.isEmpty else {
-  printUsage()
-  exit(2)
-}
-
-let subcommand = arguments.removeFirst()
-let paths = arguments
-
-switch subcommand {
-case "scan-modules":
-  guard !paths.isEmpty else {
-    fail("scan-modules requires at least one path", usage: true)
-  }
-  exit(Scanner.runModules(paths: paths))
-
-case "scan-exports":
-  guard !paths.isEmpty else {
-    fail("scan-exports requires at least one path", usage: true)
-  }
-  exit(Scanner.runExports(paths: paths))
-
-default:
-  fail("unknown subcommand '\(subcommand)'", usage: true)
-}