@expo/expo-modules-macros-plugin 0.2.2 → 0.4.0

package/apple/Package.swift

@@ -8,7 +8,12 @@ import PackageDescription
 let package = Package(
   name: "ExpoModulesMacros",
   platforms: [.macOS(.v13)],
-  products: [],
+  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")
   ],
@@ -19,7 +24,18 @@ let package = Package(
         .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
         .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
       ]
-    )
+    ),
+    .target(
+      name: "ExpoModulesScanner",
+      dependencies: [
+        .product(name: "SwiftSyntax", package: "swift-syntax"),
+        .product(name: "SwiftParser", package: "swift-syntax"),
+      ]
+    ),
+    .executableTarget(
+      name: "ExpoModulesScannerCLI",
+      dependencies: ["ExpoModulesScanner"]
+    ),
   ]
 )
 
@@ -36,4 +52,13 @@ if FileManager.default.fileExists(atPath: Context.packageDirectory + "/Tests") {
       ]
     )
   )
+  package.targets.append(
+    .testTarget(
+      name: "ExpoModulesScannerTests",
+      dependencies: [
+        "ExpoModulesScanner",
+        .product(name: "SwiftParser", package: "swift-syntax"),
+      ]
+    )
+  )
 }

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -34,64 +34,157 @@ internal struct JSFunction {
     self.isAsync = effectSpecifiers?.asyncSpecifier != nil
   }
 
+  /// The number of leading parameters that must always be supplied: the total minus the maximal
+  /// trailing run of *omittable* parameters (each having a default value or an optional type). A
+  /// non-omittable parameter part-way through stops the run, since arguments are positional — a
+  /// required parameter after an omittable one forces the earlier one to be supplied too.
+  private var requiredArgumentCount: Int {
+    var required = parameters.count
+    for parameter in parameters.reversed() {
+      guard isOmittable(parameter) else {
+        break
+      }
+      required -= 1
+    }
+    return required
+  }
+
   /// The decode-call-encode statements that form the host-function body, indented with the given
-  /// prefix. Arity guard, then per-argument decode (primitives via a direct typed accessor like
-  /// `asDouble()` on a zero-copy `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`),
-  /// the `self.<name>(...)` call, and the
-  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`).
+  /// prefix. An arity guard (an exact check when every parameter is required, otherwise a range
+  /// check) throwing `Exceptions.ArgumentsRangeMismatch`; then the decode of the always-present
+  /// required prefix (primitives via a direct typed accessor like `asDouble()` on a zero-copy
+  /// `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`); then the call and
+  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`). When a
+  /// trailing run of parameters is omittable the call branches on `arguments.count`, decoding only
+  /// the slots that branch actually has — `arguments[i]` traps past `count`, so a slot the caller
+  /// didn't pass is never indexed.
   private func bodyStatements(indent: String) -> String {
+    let required = requiredArgumentCount
+    let maximum = parameters.count
     var lines: [String] = []
 
-    lines.append(
-      """
-      guard arguments.count == \(parameters.count) else {
-        throw Exception(name: "InvalidArgumentCount", description: "Function '\(jsName)' expects \(parameters.count) argument(s), but got \\(arguments.count)")
-      }
-      """)
+    if required == maximum {
+      lines.append(
+        """
+        guard arguments.count == \(maximum) else {
+          throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
+        }
+        """)
+    } else {
+      lines.append(
+        """
+        guard arguments.count >= \(required) && arguments.count <= \(maximum) else {
+          throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
+        }
+        """)
+    }
 
-    var callArguments: [String] = []
-    for (index, parameter) in parameters.enumerated() {
-      let type = parameter.type.trimmedDescription
+    // Decode the required prefix once — these slots are present in every accepted arity, so the
+    // decode is shared rather than repeated per branch.
+    for index in 0..<required {
+      lines.append(decodeStatement(at: index))
+    }
 
-      // Primitives decode through a direct typed accessor (`asDouble()`, etc.) on a borrowed
-      // `JavaScriptUnownedValue` — no owning `JavaScriptValue` allocation, no `jsi::Value` copy, no
-      // `getDynamicType()` allocation, no `Any` boxing, no force-cast — while still validating and
-      // throwing `TypeError` on a mismatch. Other types fall back to the dynamic converter, which
-      // needs an owning value, so they index the buffer directly.
-      if let accessor = fastDecodeAccessor(for: type) {
-        lines.append("let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()")
+    if required == maximum {
+      // No omittable trailing run: a single flat call with every argument decoded.
+      lines.append(contentsOf: callAndEncodeLines(arity: maximum, decodingFrom: required))
+    } else {
+      // One call shape per accepted arity. Each branch decodes only the trailing slots it has and
+      // fills the rest (defaulted params drop their label so Swift applies the default; optional
+      // params are passed `nil`). A value-returning function binds the result from a `switch`
+      // expression and encodes once after it; a no-return one calls inline in a `switch` statement
+      // and returns `.undefined`.
+      if returnType != nil {
+        lines.append("let result = switch arguments.count {")
       } else {
-        lines.append(
-          "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)")
+        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("  \(callExpression(arity: arity))")
       }
+      lines.append("}")
+      lines.append(contentsOf: encodeResultLines())
+    }
 
-      let label = parameter.firstName.text
-      callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")
+    return lines
+      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
+      .map { indent + $0 }
+      .joined(separator: "\n")
+  }
+
+  /// `let arg<index> = …` decoding the slot at `index` by its static type: a primitive through a
+  /// direct typed accessor on a borrowed `JavaScriptUnownedValue` (no owning value, no `jsi::Value`
+  /// copy, no `getDynamicType()` allocation, no `Any` boxing, no force-cast — still validating and
+  /// throwing `TypeError` on a mismatch), any other type through the dynamic converter (which needs
+  /// an owning value, so it indexes the buffer directly).
+  private func decodeStatement(at index: Int) -> String {
+    let type = parameters[index].type.trimmedDescription
+    if let accessor = fastDecodeAccessor(for: type) {
+      return "let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()"
     }
+    return "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)"
+  }
 
+  /// The `self.<name>(...)` call for the given arity. Slots `0..<arity` are passed their decoded
+  /// `arg<i>`; a trailing optional-without-default slot that this arity omits is passed `nil`; a
+  /// trailing defaulted slot that this arity omits is dropped entirely so Swift applies its default.
+  private func callExpression(arity: Int) -> String {
+    var callArguments: [String] = []
+    for (index, parameter) in parameters.enumerated() {
+      let label = parameter.firstName.text
+      let value: String?
+      if index < arity {
+        value = "arg\(index)"
+      } else if hasDefaultValue(parameter) {
+        // Omitted defaulted slot: drop it from the call so Swift fills in the default.
+        value = nil
+      } else {
+        // Omitted optional-without-default slot: pass `nil`.
+        value = "nil"
+      }
+      guard let value else {
+        continue
+      }
+      callArguments.append(label == "_" ? value : "\(label): \(value)")
+    }
     let tryKeyword = (isThrowing || isAsync) ? "try " : ""
     let awaitKeyword = isAsync ? "await " : ""
-    let callExpression =
-      "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
+    return "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
+  }
 
-    if let returnType {
-      lines.append("let result = \(callExpression)")
-      // Primitives encode through `toJavaScriptValue(in:)` (the typed `JavaScriptRepresentable`
-      // conversion) — no `Any`, no dynamic-type allocation. Others go through the dynamic converter.
-      if fastDecodeAccessor(for: returnType) != nil {
-        lines.append("return result.toJavaScriptValue(in: runtime)")
-      } else {
-        lines.append("return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)")
-      }
+  /// The flat (single-arity) call-and-encode lines used when no trailing parameter is omittable:
+  /// `let result = self.f(...)` then the return encode (or the no-return `self.f(...)` + `.undefined`).
+  private func callAndEncodeLines(arity: Int, decodingFrom: Int) -> [String] {
+    var lines: [String] = []
+    for index in decodingFrom..<arity {
+      lines.append(decodeStatement(at: index))
+    }
+    if returnType != nil {
+      lines.append("let result = \(callExpression(arity: arity))")
+      lines.append(contentsOf: encodeResultLines())
     } else {
-      lines.append(callExpression)
+      lines.append(callExpression(arity: arity))
       lines.append("return .undefined")
     }
-
     return lines
-      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
-      .map { indent + $0 }
-      .joined(separator: "\n")
+  }
+
+  /// Encode the `result` local back to JS and return it: a primitive through `toJavaScriptValue(in:)`
+  /// (the typed `JavaScriptRepresentable` conversion — no `Any`, no dynamic-type allocation), any
+  /// other type through the dynamic converter. A no-return function returns `.undefined` instead.
+  private func encodeResultLines() -> [String] {
+    guard let returnType else {
+      return ["return .undefined"]
+    }
+    if fastDecodeAccessor(for: returnType) != nil {
+      return ["return result.toJavaScriptValue(in: runtime)"]
+    }
+    return ["return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)"]
   }
 
   /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode
@@ -108,9 +201,24 @@ internal struct JSFunction {
   /// body never references `appContext`, so the capture and guard are omitted to avoid the
   /// unused-capture warning.
   var decorateStatements: String {
+    // Synchronous `@JS` functions never decode `this` (the receiver is the module's real `self`), so
+    // they 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. 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.
+    let captures = usesAppContext ? "[weak appContext, self]" : "[self]"
+    let parameters =
+      isAsync
+      ? "this, arguments"
+      : "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
+
     if usesAppContext {
       return """
-          object.setProperty("\(jsName)") { [weak appContext, self] this, arguments in
+          object.setProperty("\(jsName)") { \(captures) \(parameters) in
             guard let appContext else {
               throw Exceptions.AppContextLost()
             }
@@ -119,7 +227,7 @@ internal struct JSFunction {
         """
     }
     return """
-        object.setProperty("\(jsName)") { [self] this, arguments in
+        object.setProperty("\(jsName)") { \(captures) \(parameters) in
       \(bodyStatements(indent: "    "))
         }
       """
@@ -230,9 +338,14 @@ internal struct JSProperty {
       .split(separator: "\n", omittingEmptySubsequences: false)
       .map { "  \($0)" }
       .joined(separator: "\n")
+    // Property `get`/`set` accessors are always synchronous and never decode `this`, so they bind
+    // through the unowned-`this` `setProperty` overload like sync functions. The parameter list is
+    // parenthesized and fully typed because Swift rejects a type annotation on a shorthand closure
+    // parameter; the explicit `borrowing JavaScriptUnownedValue` selects the unowned-`this` overload.
+    let parameters = "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
     if usesAppContext {
       return """
-        \(descriptorName).setProperty("\(key)") { [weak appContext, self] this, arguments in
+        \(descriptorName).setProperty("\(key)") { [weak appContext, self] \(parameters) in
           guard let appContext else {
             throw Exceptions.AppContextLost()
           }
@@ -241,7 +354,7 @@ internal struct JSProperty {
         """
     }
     return """
-      \(descriptorName).setProperty("\(key)") { [self] this, arguments in
+      \(descriptorName).setProperty("\(key)") { [self] \(parameters) in
       \(indentedBody)
       }
       """

package/apple/Sources/ExpoModulesMacros/EventMacro.swift

@@ -0,0 +1,330 @@
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxMacros
+
+/// Accessor macro applied to a function-typed `var` on a module or shared object, turning it into a
+/// typed JavaScript event. A function-typed `var` can't be a stored property without an initializer,
+/// so the macro expands it into a computed getter returning a closure that dispatches by name into
+/// the `EventEmitter` `emit` overloads (core conforms both `BaseModule` and `SharedObject` to that
+/// protocol, so `self.emit` resolves on each):
+///
+///   @Event
+///   var onProgress: (ProgressEvent) -> Void
+///   // expands to:
+///   var onProgress: (ProgressEvent) -> Void {
+///     get {
+///       { [weak self] payload in self?.emit(event: "progress", payload: payload) }
+///     }
+///   }
+///
+/// A no-payload event (`() -> Void`) dispatches through the dedicated `emit(event:)` overload.
+/// The JS event name defaults to the property name with the conventional `on` prefix stripped
+/// (see `defaultEventName(for:)`); `@Event("customName")` overrides it verbatim.
+///
+/// The closure captures `self` **weakly**: it's usually invoked inline (`self.onProgress(…)`), but an
+/// author may store it or hand it to a delegate, and a strong capture would then extend the module's
+/// lifetime. After the emitter deallocates the closure silently no-ops, which matches what `emit`
+/// already does once the runtime is gone.
+///
+/// The synthesized property is deliberately **not** isolated to `@JavaScriptActor`, unlike `@JS`
+/// members: `emit` is itself non-isolated and schedules the dispatch onto the JS thread internally,
+/// so the event is callable from any thread or isolation with no actor hop at the call site. It is
+/// also self-contained: `@ExpoModule`/`@SharedObject` neither collect `@Event` members nor register
+/// their names anywhere.
+///
+/// `@Event(sync: true)` opts into **synchronous dispatch**: the closure calls `emitSync` (inline
+/// conversion + dispatch, no scheduling) instead of `emit`, and `@ExpoModule`/`@SharedObject` stamp
+/// the member `@JavaScriptActor` so the compiler forces the call site onto the JS thread, the
+/// inverse of the async default. The isolation is on the property access, so it guards the inline
+/// `self.onTick(…)` usage; a closure stored or handed off escapes it, after which `emitSync` runs
+/// wherever the caller invokes it.
+///
+/// As a **peer**, the macro emits a never-called conformance assertion (see
+/// `TypeConformanceAssertion.swift`) checking that the payload type is JS-convertible and that the
+/// enclosing type conforms to `EventEmitter`, so both failure modes surface as clear conformance
+/// errors on the user's own declaration.
+public struct EventMacro: AccessorMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingAccessorsOf declaration: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [AccessorDeclSyntax] {
+    let event = try validatedEvent(of: node, on: declaration)
+    // The closure's parameter and return types are inferred from the property's declared type
+    // through the getter, so the body never has to spell the payload type. A sync event calls
+    // `emitSync` (inline dispatch, JS thread only); the default calls the scheduling `emit`.
+    let emitMethod = event.isSync ? "emitSync" : "emit"
+    let closure = event.hasPayload
+      ? "{ [weak self] payload in self?.\(emitMethod)(event: \"\(event.jsName)\", payload: payload) }"
+      : "{ [weak self] in self?.\(emitMethod)(event: \"\(event.jsName)\") }"
+    return [
+      """
+      get {
+        \(raw: closure)
+      }
+      """
+    ]
+  }
+}
+
+extension EventMacro: PeerMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingPeersOf declaration: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    // Diagnostics are owned by the accessor expansion; an invalid declaration silently emits no
+    // peer here so each error is reported once.
+    guard let event = try? validatedEvent(of: node, on: declaration) else {
+      return []
+    }
+    // One nested helper asserts everything in a single call: the payload type is JS-convertible
+    // (the `P` parameter, dropped for no-payload events and known-conforming primitives) and the
+    // enclosing type can emit (the `E` parameter, always present since any `@Event` dispatches
+    // through `self.emit`). Named after the member so the member shows up in either diagnostic,
+    // and asserting the enclosing type by its spelled name so the conformance error names the
+    // user's type rather than 'Self'.
+    let name = event.swiftName
+    let payload = event.payloadType.flatMap(assertableBoundaryType)
+    let owner = enclosingTypeName(in: context) ?? "Self"
+    let helper = payload != nil
+      ? "func \(name)<P: \(jsConvertibleProtocolName), E: \(eventEmitterProtocolName)>(_: P.Type, _: E.Type) {}"
+      : "func \(name)<E: \(eventEmitterProtocolName)>(_: E.Type) {}"
+    let call = payload.map { "\(name)(\($0).self, \(owner).self)" } ?? "\(name)(\(owner).self)"
+    return [
+      """
+      private func _assertTypesConformance_\(raw: name)() {
+      \(raw: helper)
+      \(raw: call)
+      }
+      """
+    ]
+  }
+}
+
+/// What the expansions need to know about a validated `@Event` declaration: the property name, the
+/// JS event name (after an `@Event("…")` override), and the payload type when the function type
+/// takes one.
+private struct EventMember {
+  let swiftName: String
+  let jsName: String
+  /// The payload type as written, or `nil` for a no-payload `() -> Void` event.
+  let payloadType: String?
+  /// Whether the event dispatches synchronously (`@Event(sync: true)`) via `emitSync`.
+  let isSync: Bool
+
+  var hasPayload: Bool {
+    return payloadType != nil
+  }
+}
+
+/// Validates the declaration `@Event` is attached to and reads the event out of it. The checks
+/// mirror what the expansion relies on: a single-binding instance `var` (the macro synthesizes a
+/// computed getter, so `let`, accessors, and initializers are all incompatible) whose type is a
+/// function type returning `Void` with at most one payload parameter.
+private func validatedEvent(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol
+) throws -> EventMember {
+  guard let varDecl = declaration.as(VariableDeclSyntax.self) else {
+    throw MacroExpansionErrorMessage("@Event can only be applied to a property")
+  }
+  if varDecl.attributes.firstAttribute(named: "JS") != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event and @JS cannot be combined on the same property; an event is exposed to JS on its own, so remove one of the attributes")
+  }
+  // The compiler also rejects accessor macros on a `let`, but with a generic message; this one says
+  // what to do instead and carries the fix-it doing it. The synthesized property is getter-only, so
+  // switching to `var` loses nothing.
+  if varDecl.bindingSpecifier.tokenKind == .keyword(.let) {
+    throw letBindingDiagnostic(for: varDecl)
+  }
+  if varDecl.modifiers.contains(where: isTypeLevelModifier) {
+    throw MacroExpansionErrorMessage(
+      "@Event must be an instance property; events are emitted from a module or shared object instance.")
+  }
+  guard varDecl.bindings.count == 1, let binding = varDecl.bindings.first,
+    let identifier = binding.pattern.as(IdentifierPatternSyntax.self) else {
+    throw MacroExpansionErrorMessage(
+      "@Event must be applied to a single named property; declare each event separately")
+  }
+  if binding.initializer != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event property cannot have an initial value; the macro synthesizes the closure")
+  }
+  if binding.accessorBlock != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event property cannot declare its own accessors; the macro synthesizes the getter")
+  }
+  guard let functionType = underlyingFunctionType(of: binding.typeAnnotation?.type) else {
+    throw MacroExpansionErrorMessage(
+      "@Event property must declare a function type, such as '(Payload) -> Void' or '() -> Void'")
+  }
+  guard isVoidReturn(functionType.returnClause.type) else {
+    throw MacroExpansionErrorMessage(
+      "@Event function type must return 'Void'; an event dispatches to JS and has no return value")
+  }
+  guard functionType.parameters.count <= 1 else {
+    throw MacroExpansionErrorMessage(
+      "@Event function type takes at most one payload parameter; combine multiple values into a single record")
+  }
+
+  let swiftName = identifier.identifier.text
+  return EventMember(
+    swiftName: swiftName,
+    jsName: jsNameArgument(of: node) ?? defaultEventName(for: swiftName),
+    payloadType: functionType.parameters.first?.type.trimmedDescription,
+    isSync: boolArgument(of: node, label: "sync") == true
+  )
+}
+
+// MARK: - Default event name
+
+/// The default JS event name for a property: the Swift name with the conventional `on` prefix
+/// stripped and the remainder decapitalized (`onStatusChange` → `statusChange`). The two sides
+/// idiomatically want different names: the Swift property reads as invoking a handler
+/// (`self.onStatusChange(…)`) and the prefix keeps it from colliding with a state property
+/// (`status`), while JS listens by bare name (`addListener("statusChange")`, the Node/DOM idiom
+/// that module and shared-object events follow). Names without the prefix (`statusChange`,
+/// `online`) pass through verbatim, and an explicit `@Event("name")` override is never
+/// transformed — that's also the escape hatch for legacy `onX` wire names.
+private func defaultEventName(for swiftName: String) -> String {
+  guard swiftName.hasPrefix("on") else {
+    return swiftName
+  }
+  let rest = swiftName.dropFirst(2)
+  guard let first = rest.first, first.isUppercase else {
+    return swiftName
+  }
+  return decapitalized(String(rest))
+}
+
+/// Lowercases the leading uppercase run the way Swift's API importer does: a single leading
+/// capital is lowercased (`StatusChange` → `statusChange`); a longer acronym run keeps its last
+/// capital when a lowercase letter follows it, since that capital starts the next word
+/// (`URLChange` → `urlChange`, `URL` → `url`).
+private func decapitalized(_ name: String) -> String {
+  let runEnd = name.firstIndex { !$0.isUppercase } ?? name.endIndex
+  if name[..<runEnd].count > 1 && runEnd != name.endIndex {
+    let lastCapital = name.index(before: runEnd)
+    return name[..<lastCapital].lowercased() + name[lastCapital...]
+  }
+  return name[..<runEnd].lowercased() + name[runEnd...]
+}
+
+// MARK: - The `let` diagnostic
+
+/// The error for `@Event let`, attached to the `let` keyword itself and carrying a fix-it that
+/// replaces it with `var`. Unlike the other checks (plain thrown messages located at the attribute),
+/// this one is a structured `Diagnostic` so Xcode can offer the one-click fix.
+private func letBindingDiagnostic(for varDecl: VariableDeclSyntax) -> DiagnosticsError {
+  let specifier = varDecl.bindingSpecifier
+  let fixIt = FixIt(
+    message: EventFixItMessage("Replace 'let' with 'var'", id: "event-let-to-var"),
+    changes: [
+      // Rewriting just the token's kind keeps its surrounding trivia (indentation, the space
+      // before the property name) intact.
+      .replace(
+        oldNode: Syntax(specifier),
+        newNode: Syntax(specifier.with(\.tokenKind, .keyword(.var)))
+      )
+    ]
+  )
+  let message = EventDiagnosticMessage(
+    "@Event must be applied to a 'var': it expands into a computed property, which a 'let' cannot be. The synthesized property is read-only anyway.",
+    id: "event-on-let"
+  )
+  return DiagnosticsError(diagnostics: [
+    Diagnostic(node: specifier, message: message, fixIts: [fixIt])
+  ])
+}
+
+private struct EventDiagnosticMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID: MessageID
+  let severity: DiagnosticSeverity = .error
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+private struct EventFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+// MARK: - Declaration shape helpers
+
+/// The spelled name of the innermost type declaration enclosing the macro, read from the lexical
+/// context, so the emitter assertion can name the user's type in the conformance diagnostic
+/// ("requires that 'MyModule' conform to 'EventEmitter'" instead of "'Self'"). Returns `nil` (the
+/// caller falls back to `Self`) when there's no enclosing type, or when it's a generic type
+/// declaration: `Foo.self` isn't valid for an unbound generic, while `Self` works anywhere. An
+/// extension can't be detected as generic syntactically (see the extension case below).
+private func enclosingTypeName(in context: some MacroExpansionContext) -> String? {
+  for scope in context.lexicalContext {
+    if let classDecl = scope.as(ClassDeclSyntax.self) {
+      return classDecl.genericParameterClause == nil ? classDecl.name.text : nil
+    }
+    if let structDecl = scope.as(StructDeclSyntax.self) {
+      return structDecl.genericParameterClause == nil ? structDecl.name.text : nil
+    }
+    if let actorDecl = scope.as(ActorDeclSyntax.self) {
+      return actorDecl.genericParameterClause == nil ? actorDecl.name.text : nil
+    }
+    if let extensionDecl = scope.as(ExtensionDeclSyntax.self) {
+      // An extension carries no generic-parameter clause of its own, so a bare extended type
+      // (`extension Box`) is indistinguishable from a non-generic one (`extension Foo`); both read
+      // as a plain identifier here. A written bound form (`extension Box<Int>`) is valid as `.self`,
+      // and the common non-generic case keeps its spelled name in the diagnostic. The unguarded gap
+      // is `extension <Generic>` with the parameters omitted, where the spelled name is an unbound
+      // generic invalid as `.self`; events on generic types in an extension are rare enough that the
+      // resulting compile error is an acceptable price for naming the user's type everywhere else.
+      return extensionDecl.extendedType.trimmedDescription
+    }
+  }
+  return nil
+}
+
+private func isTypeLevelModifier(_ modifier: DeclModifierSyntax) -> Bool {
+  return modifier.name.tokenKind == .keyword(.static) || modifier.name.tokenKind == .keyword(.class)
+}
+
+/// The function type underlying a property's type annotation, unwrapping attributes
+/// (`@Sendable (P) -> Void`) and single-element parentheses (`((P) -> Void)`). Returns `nil` when
+/// the annotation is missing or isn't a function type, including an optional function type:
+/// an event is always present, never `nil`.
+private func underlyingFunctionType(of type: TypeSyntax?) -> FunctionTypeSyntax? {
+  guard let type else {
+    return nil
+  }
+  if let attributed = type.as(AttributedTypeSyntax.self) {
+    return underlyingFunctionType(of: attributed.baseType)
+  }
+  if let tuple = type.as(TupleTypeSyntax.self),
+    tuple.elements.count == 1, let element = tuple.elements.first, element.firstName == nil {
+    return underlyingFunctionType(of: element.type)
+  }
+  return type.as(FunctionTypeSyntax.self)
+}
+
+/// True when the function type's return is written as `Void` / `()`. Function types always carry an
+/// explicit return clause, so unlike a function declaration there's no "absent" case. A module-qualified
+/// `Swift.Void` and redundant parentheses (`(Void)`, `(())`) are accepted too, so a valid void return
+/// written one of those ways isn't rejected with a misleading "must return 'Void'" diagnostic.
+private func isVoidReturn(_ type: TypeSyntax) -> Bool {
+  // Peel single-element, unlabeled parentheses: `(Void)` and `(())` are the same type as their content.
+  if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
+    let element = tuple.elements.first, element.firstName == nil {
+    return isVoidReturn(element.type)
+  }
+  let text = type.trimmedDescription
+  return text == "Void" || text == "()" || text == "Swift.Void"
+}

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -6,11 +6,13 @@ import SwiftSyntaxMacros
  Macro applied to a module class. It plays three roles, each implemented in its own
  extension below:
 
- - `MemberMacro`: scans the class body for `@JS`-marked declarations and synthesizes a
-   framework-internal `_synthesizedDefinition()` returning `[AnyDefinition]`, which
-   `expo-modules-core` calls automatically and merges into the module's definition. When
-   the class doesn't already inherit `Module`/`BaseModule`, it also synthesizes the
-   `appContext` storage and `init(appContext:)` those base classes would have provided.
+ - `MemberMacro`: binds `@JS`-marked members directly into the module's JS object via the
+   synthesized `_decorateModule`, and emits the resolved module name as a non-optional
+   `_jsName` static (no `Name(…)` DSL element). It also synthesizes a
+   framework-internal `_synthesizedDefinition()` returning `[AnyDefinition]` (now carrying
+   only nested `classes` entries) that `expo-modules-core` merges into the module's
+   definition. When the class doesn't already inherit `Module`/`BaseModule`, it also
+   synthesizes the `appContext` storage and `init(appContext:)` those base classes provide.
  - `MemberAttributeMacro`: stamps `@JavaScriptActor` on `@JS` sync members and
    `@ModuleDefinitionBuilder` on a `definition()` method.
  - `ExtensionMacro`: adds the `AnyModule` conformance when the class doesn't inherit it.
@@ -39,8 +41,12 @@ public struct ExpoModuleMacro: MemberMacro {
       throw MacroExpansionErrorMessage("@ExpoModule can only be applied to a class")
     }
 
+    // The module name is fully resolved here (the explicit `@ExpoModule("…")` argument, else the
+    // class name) and emitted as a non-optional `_jsName` static below — so the
+    // macro no longer emits a `Name(…)` DSL entry. Core reads the static for the module name,
+    // ahead of its type-name fallback (which then only applies to non-macro DSL modules).
     let moduleName = jsNameArgument(of: node) ?? classDecl.name.text
-    var entries: [String] = ["Name(\"\(moduleName)\")"]
+    var entries: [String] = []
 
     // `@JS func`s (sync and async) and `@JS var`s are bound directly into the JS object by the
     // synthesized `_decorateModule` rather than described with a `Function(...)` / `Property(...)`
@@ -67,11 +73,21 @@ public struct ExpoModuleMacro: MemberMacro {
       }
     }
 
-    let lines = entries.map { "    \($0)" }.joined(separator: ",\n")
-    let body = "  return [\n\(lines)\n  ]"
+    let body: String
+    if entries.isEmpty {
+      body = "  return []"
+    } else {
+      let lines = entries.map { "    \($0)" }.joined(separator: ",\n")
+      body = "  return [\n\(lines)\n  ]"
+    }
 
     var emitted: [DeclSyntax] = []
 
+    // The fully-resolved module name as a non-optional stored constant. Core reads this
+    // instead of the retired `Name(…)` DSL element; it feeds both native registration and the
+    // JS object name, so they can't diverge.
+    emitted.append("public static let _jsName = \"\(raw: moduleName)\"")
+
     // `Module`/`BaseModule` already provide `appContext` storage and the
     // `init(appContext:)` requirement, so we only synthesize them for classes that
     // inherit from neither. Each is skipped individually if the user wrote their own,
@@ -127,7 +143,10 @@ extension ExpoModuleMacro: MemberAttributeMacro {
     // `@JS` sync members run on the JS thread; stamp `@JavaScriptActor` so isolation is
     // checked at compile time. Skipped when the member already chose an isolation
     // (`async`, `nonisolated`, or another global actor) — see `shouldStampJavaScriptActor`.
-    if memberHasJSAttribute(member),
+    // `@Event(sync: true)` members get the stamp too: a sync event dispatches inline, so the
+    // isolation forces its call site onto the JS thread. Async events (the default) are
+    // deliberately left unstamped — their `emit` schedules onto the JS thread itself.
+    if memberHasJSAttribute(member) || isSyncEventMember(member),
       shouldStampJavaScriptActor(on: member, enclosedBy: declaration) {
       attributes.append("@JavaScriptActor")
     }

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -14,6 +14,64 @@ internal func jsNameArgument(of attribute: AttributeSyntax) -> String? {
   return segment.content.text
 }
 
+/**
+ Reads a labeled boolean-literal argument of an attribute, e.g. `@Event(sync: true)` -> true.
+ Returns nil if the attribute has no argument with that label or its value isn't a boolean literal.
+ */
+internal func boolArgument(of attribute: AttributeSyntax, label: String) -> Bool? {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return nil
+  }
+  for arg in args where arg.label?.text == label {
+    guard let literal = arg.expression.as(BooleanLiteralExprSyntax.self) else {
+      return nil
+    }
+    return literal.literal.tokenKind == .keyword(.true)
+  }
+  return nil
+}
+
+/// True if the type is written as an optional: `T?`, `T!`, or the explicit `Optional<T>`. Used to
+/// decide argument requiredness (an optional parameter may be omitted) and record-field nullability.
+internal func isOptionalType(_ type: TypeSyntax) -> Bool {
+  if type.is(OptionalTypeSyntax.self) || type.is(ImplicitlyUnwrappedOptionalTypeSyntax.self) {
+    return true
+  }
+  if let identifier = type.as(IdentifierTypeSyntax.self), identifier.name.text == "Optional" {
+    return true
+  }
+  return false
+}
+
+/// True if a trailing occurrence of this parameter may be omitted by the JS caller: it either has a
+/// default value (Swift applies it) or is an optional type (an absent slot becomes `nil`). The arity
+/// range and the per-arity call branches are derived from this.
+internal func isOmittable(_ parameter: FunctionParameterSyntax) -> Bool {
+  return hasDefaultValue(parameter) || isOptionalType(parameter.type)
+}
+
+/// True if the parameter declares a default value (`b: Int = 5`). An omitted defaulted slot is left
+/// out of the call so Swift fills in the default, distinguishing it from an omitted optional slot
+/// (passed `nil`).
+internal func hasDefaultValue(_ parameter: FunctionParameterSyntax) -> Bool {
+  return parameter.defaultValue != nil
+}
+
+/**
+ True if the declaration is a `@Event(sync: true)` property. A sync event dispatches inline on the
+ JS thread instead of scheduling, so `@ExpoModule`/`@SharedObject` stamp it with `@JavaScriptActor`,
+ making "must be called on the JS thread" a compile-time guarantee at the call site. Async events
+ (the default) are deliberately not stamped: their `emit` schedules onto the JS thread itself, so
+ they stay callable from any thread.
+ */
+internal func isSyncEventMember(_ decl: DeclSyntaxProtocol) -> Bool {
+  guard let varDecl = decl.as(VariableDeclSyntax.self),
+    let attribute = varDecl.attributes.firstAttribute(named: "Event") else {
+    return false
+  }
+  return boolArgument(of: attribute, label: "sync") == true
+}
+
 /**
  Reads a labeled array-literal argument of an attribute, e.g. `@ExpoModule(classes: [Foo.self, Bar.self])`,
  and returns the type names referenced (e.g. `["Foo", "Bar"]`). Each element must be a

package/apple/Sources/ExpoModulesMacros/Plugin.swift

@@ -6,6 +6,7 @@ struct ExpoModulesMacrosPlugin: CompilerPlugin {
   let providingMacros: [Macro.Type] = [
     OptimizedFunctionAttachedMacro.self,
     JSMacro.self,
+    EventMacro.self,
     ExpoModuleMacro.self,
     SharedObjectMacro.self,
     RecordMacro.self,

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -453,19 +453,6 @@ private func isExcludedByModifier(_ modifiers: DeclModifierListSyntax) -> Bool {
   return false
 }
 
-/**
- True if the type syntax is optional: `T?`, `T!`, or the spelled-out `Optional<T>`.
- */
-private func isOptionalType(_ type: TypeSyntax) -> Bool {
-  if type.is(OptionalTypeSyntax.self) || type.is(ImplicitlyUnwrappedOptionalTypeSyntax.self) {
-    return true
-  }
-  if let identifier = type.as(IdentifierTypeSyntax.self), identifier.name.text == "Optional" {
-    return true
-  }
-  return false
-}
-
 /**
  True if the type's inheritance clause already lists a protocol with the given name.
  Matches either the bare identifier (`Record`) or a qualified member access ending in

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -95,7 +95,10 @@ extension SharedObjectMacro: MemberAttributeMacro {
     providingAttributesFor member: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [AttributeSyntax] {
-    guard memberHasJSAttribute(member),
+    // `@Event(sync: true)` members are stamped alongside `@JS` ones: a sync event dispatches
+    // inline, so the isolation forces its call site onto the JS thread. Async events (the
+    // default) stay unstamped — their `emit` schedules onto the JS thread itself.
+    guard memberHasJSAttribute(member) || isSyncEventMember(member),
       shouldStampJavaScriptActor(on: member, enclosedBy: declaration) else {
       return []
     }

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -5,6 +5,11 @@ import SwiftSyntax
 /// asserts the conformance (`@JS`, `@Record`, …).
 internal let jsConvertibleProtocolName = "AnyArgument"
 
+/// The protocol a type must conform to for `self.emit(event:…)` to resolve; core conforms
+/// `BaseModule` and `SharedObject` to it. Asserted by `@Event` so attaching it to a type that can't
+/// emit fails with a conformance diagnostic instead of an opaque "no member 'emit'" error.
+internal let eventEmitterProtocolName = "EventEmitter"
+
 /// Types we never assert because they're statically known to conform and never reach the dynamic
 /// converter: the JS primitives. Asserting them would only add noise to the expansion. Kept here
 /// (rather than reusing the decode-path's `fastDecodeAccessor`) because "known-to-conform" is a
@@ -66,6 +71,15 @@ internal func typeConformanceAssertions(for assertions: [ConformanceAssertion])
     """
 }
 
+/// 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.
+internal func assertableBoundaryType(_ type: String) -> String? {
+  let unwrapped = unwrappedOptional(type)
+  return knownConformingPrimitives.contains(unwrapped) ? nil : unwrapped
+}
+
 /// The assertion's body fragment: a nested generic helper named after the member, plus one call per
 /// distinct non-primitive type. Nesting the helper keeps the constraint entirely local — no shared
 /// symbol, nothing to collide, nothing left in the type's namespace — and naming it after the member

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

@@ -0,0 +1,61 @@
+import Foundation
+
+/// Which Expo macro was found on a declaration. The scanner recognizes the entry-point macros that
+/// mark a type or member as part of a module's JS surface, plus `@Record` for convertible types.
+enum DetectedMacro: String, Codable, CaseIterable {
+  case expoModule = "ExpoModule"
+  case js = "JS"
+  case sharedObject = "SharedObject"
+  case record = "Record"
+}
+
+/// A single argument passed to a macro, e.g. `"Foo"` or `classes: [Bar.self]`. The label is `nil`
+/// for positional arguments; `value` is the argument expression's source text as written.
+struct MacroArgument: Codable, Equatable {
+  /// The argument label (`classes` in `classes: [Bar.self]`), or `nil` for a positional argument.
+  let label: String?
+
+  /// The argument value exactly as written in source, e.g. `"Foo"` (including the quotes) or
+  /// `[Bar.self]`. Kept as text because a syntactic scan can't resolve these to runtime values.
+  let value: String
+}
+
+/// A single annotated declaration the scanner found, with just enough to locate it and know
+/// what it is. Member-level details (parameters, types) are intentionally out of scope for this
+/// first prototype — see the `@JS` member walk in the macros for where that would live.
+struct Detection: Codable, Equatable {
+  /// The macro spelled on the declaration (without the leading `@`).
+  let macro: DetectedMacro
+
+  /// The declared name, e.g. the class name for `@ExpoModule`, or the func/var/init name for `@JS`.
+  let name: String
+
+  /// The kind of declaration the macro was attached to: `class`, `struct`, `func`, `var`, `init`, …
+  let declarationKind: 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?
+
+  /// Every argument passed to the macro, in source order, e.g. `@ExpoModule("Foo", classes: [Bar.self])`
+  /// yields a positional `"Foo"` and a `classes:` argument. Empty when the macro is written bare.
+  let arguments: [MacroArgument]
+
+  /// Source location, relative to the path the scanner was invoked with.
+  let file: String
+  let line: Int
+  let column: 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 {
+  /// `.swift` files the walk found and read (after directory pruning).
+  let filesScanned: Int
+
+  /// Of those, how many contained a macro attribute and so were parsed with SwiftSyntax.
+  let filesParsed: Int
+
+  /// Wall-clock duration of the scan, in milliseconds (walking, reading, filtering, and parsing).
+  let durationMs: Double
+}

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

@@ -0,0 +1,109 @@
+import SwiftSyntax
+
+/// Walks a parsed source file and records top-level declarations carrying `@ExpoModule`, `@JS`,
+/// `@SharedObject`, or `@Record`. Only file-scope declarations are considered: these macros apply to
+/// top-level types, so descending into type and function bodies would only surface false positives.
+/// 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 {
+  private let file: String
+  private let converter: SourceLocationConverter
+  /// Only these macros are recorded; the rest are ignored. Lets a `modules` scan report just
+  /// `@ExpoModule` while an `exports` scan covers them all.
+  private let detectedMacros: Set<DetectedMacro>
+  private(set) var detections: [Detection] = []
+
+  init(file: String, tree: SourceFileSyntax, detectedMacros: Set<DetectedMacro>) {
+    self.file = file
+    self.converter = SourceLocationConverter(fileName: file, tree: tree)
+    self.detectedMacros = detectedMacros
+    super.init(viewMode: .sourceAccurate)
+  }
+
+  override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {
+    if isTopLevel(node) {
+      record(attributes: node.attributes, 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
+  }
+
+  override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind {
+    if isTopLevel(node) {
+      record(attributes: node.attributes, 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.
+  ///
+  /// 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 {
+      return false
+    }
+    return item.parent?.parent?.is(SourceFileSyntax.self) == true
+  }
+
+  /// 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,
+    name: String,
+    kind: String,
+    at node: some SyntaxProtocol
+  ) {
+    for element in attributes {
+      guard let attribute = element.as(AttributeSyntax.self),
+        let macro = DetectedMacro(rawValue: attribute.attributeName.trimmedDescription),
+        detectedMacros.contains(macro) else {
+        continue
+      }
+      let location = converter.location(for: node.positionAfterSkippingLeadingTrivia)
+      detections.append(
+        Detection(
+          macro: macro,
+          name: name,
+          declarationKind: kind,
+          jsName: stringArgument(of: attribute),
+          arguments: arguments(of: attribute),
+          file: file,
+          line: location.line,
+          column: location.column
+        )
+      )
+    }
+  }
+}
+
+/// 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.
+private func arguments(of attribute: AttributeSyntax) -> [MacroArgument] {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return []
+  }
+  return args.map { arg in
+    MacroArgument(label: arg.label?.text, value: arg.expression.trimmedDescription)
+  }
+}
+
+/// The first string-literal argument of an attribute, e.g. `@JS("doWork")` -> "doWork". Returns
+/// `nil` when there's no argument or it isn't a plain string literal. (Same shape the
+/// `jsNameArgument` helper reads inside the macros.)
+private func stringArgument(of attribute: AttributeSyntax) -> String? {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
+    let first = args.first,
+    first.label == nil,
+    let str = first.expression.as(StringLiteralExprSyntax.self),
+    let segment = str.segments.first?.as(StringSegmentSyntax.self),
+    str.segments.count == 1 else {
+    return nil
+  }
+  return segment.content.text
+}

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

@@ -0,0 +1,137 @@
+import Foundation
+import SwiftParser
+import SwiftSyntax
+
+/// Walks `paths`, parses each `.swift` file that might contain one of `macros` (the pre-filter), and
+/// returns every detection (in file then source order) with the run's stats. The shared core every
+/// scan command builds on; each command projects these detections into its own output shape.
+func collectDetections(paths: [String], macros: Set<DetectedMacro>) -> (detections: [Detection], stats: ScanStats) {
+  let clock = ContinuousClock()
+  let start = clock.now
+
+  var detections: [Detection] = []
+  var filesScanned = 0
+  var filesParsed = 0
+
+  // Compile the pre-filter regex once per run, not once per file.
+  let prefilter = macroAttributeRegex(for: macros)
+
+  for file in swiftFiles(in: paths) {
+    guard let source = try? String(contentsOfFile: file, encoding: .utf8) else {
+      FileHandle.standardError.write(Data("warning: could not read \(file)\n".utf8))
+      continue
+    }
+    filesScanned += 1
+    // Skip the (relatively expensive) parse for files that can't contain any of the macros. A plain
+    // substring scan is far cheaper than a full parse, and most files in a large tree mention none
+    // of these names. See `mightContainMacro` for why this never drops a real match.
+    guard mightContainMacro(in: source, prefilter: prefilter) else {
+      continue
+    }
+    filesParsed += 1
+    detections.append(contentsOf: detect(source: source, file: file, macros: macros))
+  }
+
+  let elapsed = (clock.now - start).components
+  let durationMs = Double(elapsed.seconds) * 1000 + Double(elapsed.attoseconds) / 1e15
+
+  return (detections, ScanStats(filesScanned: filesScanned, filesParsed: filesParsed, durationMs: durationMs))
+}
+
+/// 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] {
+  let tree = Parser.parse(source: source)
+  let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: macros)
+  visitor.walk(tree)
+  return visitor.detections
+}
+
+// MARK: - Pre-filter
+
+/// Builds the pre-filter regex for a macro set, e.g. `@(ExpoModule)` for a `modules` scan or
+/// `@(ExpoModule|JS|Record|SharedObject)` for an `exports` scan. A precompiled `NSRegularExpression`
+/// benchmarked ~20x faster over a large source tree than calling `String.contains` once per macro
+/// name, because it scans each file in a single pass. Compiled once per run and reused per file.
+func macroAttributeRegex(for macros: Set<DetectedMacro>) -> NSRegularExpression {
+  // Sort for a stable pattern regardless of the set's iteration order.
+  let alternation = macros.map(\.rawValue).sorted().joined(separator: "|")
+  return try! NSRegularExpression(pattern: "@(\(alternation))")
+}
+
+/// True if the source text contains one of the pre-filter's spelled macro attributes, so it's worth
+/// parsing. A deliberate over-approximation: the pattern can still match inside a comment or string,
+/// in which case the file is parsed and correctly yields no detections — a wasted parse, never a
+/// missed module. It assumes the attribute is written with no space after `@` (`@ExpoModule`, not
+/// `@ ExpoModule`), which is universal in practice; the rare spaced form would be skipped.
+func mightContainMacro(in source: String, prefilter: NSRegularExpression) -> Bool {
+  let range = NSRange(source.startIndex..., in: source)
+  return prefilter.firstMatch(in: source, range: range) != nil
+}
+
+// MARK: - File discovery
+
+/// 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"]
+
+/// 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
+/// so output is stable across runs.
+///
+/// Reported paths are absolute, so the output is unambiguous and independent of the caller's working
+/// directory. (A future `--root` option could emit paths relative to a given base when a portable,
+/// shorter form is wanted.)
+func swiftFiles(in paths: [String]) -> [String] {
+  let fileManager = FileManager.default
+  var result: [String] = []
+
+  for path in paths {
+    var isDirectory: ObjCBool = false
+    guard fileManager.fileExists(atPath: path, isDirectory: &isDirectory) else {
+      FileHandle.standardError.write(Data("warning: no such path \(path)\n".utf8))
+      continue
+    }
+
+    if isDirectory.boolValue {
+      result.append(contentsOf: swiftFiles(inDirectory: URL(fileURLWithPath: path), fileManager: fileManager))
+    } else if path.hasSuffix(".swift") {
+      // A directory walk already yields absolute paths; resolve a directly-passed file the same way
+      // so every reported path is absolute regardless of how it was spelled.
+      result.append(URL(fileURLWithPath: path).standardizedFileURL.path)
+    }
+  }
+
+  return result.sorted()
+}
+
+/// Recursively enumerates `.swift` files under a directory, calling `skipDescendants()` on any
+/// pruned directory so its subtree is never read. Uses the URL enumerator (rather than the
+/// path-based one) precisely because it supports skipping a subtree mid-walk.
+///
+/// Directory-ness is read from `hasDirectoryPath` (the enumerator sets a trailing slash on the URLs
+/// it yields) rather than `resourceValues(forKeys: [.isDirectoryKey])`, which re-`stat`s each entry.
+/// The walk is the dominant cost of a whole-tree scan, and skipping that per-entry stat measurably
+/// shortens it.
+private func swiftFiles(inDirectory directory: URL, fileManager: FileManager) -> [String] {
+  guard let enumerator = fileManager.enumerator(
+    at: directory,
+    includingPropertiesForKeys: nil,
+    options: [.skipsHiddenFiles]
+  ) else {
+    return []
+  }
+
+  var result: [String] = []
+  for case let url as URL in enumerator {
+    if url.hasDirectoryPath {
+      if prunedDirectoryNames.contains(url.lastPathComponent) {
+        enumerator.skipDescendants()
+      }
+    } else if url.pathExtension == "swift" {
+      result.append(url.path)
+    }
+  }
+  return result
+}

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

@@ -0,0 +1,68 @@
+import Foundation
+
+/// The scanner's public entry point. Argument parsing, subcommand dispatch, and usage text live in
+/// the CLI target; this just runs a command and writes its JSON report to stdout.
+///
+/// The detection model (`Detection`, `DetectionVisitor`, …) stays `internal`: tests reach it via
+/// `@testable import`, and the CLI only needs these entries, so nothing else is exposed.
+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. (`scan-exports` will get its own
+  /// `run`-style entry returning its own result type when implemented.)
+  public static func runModules(paths: [String]) -> Int32 {
+    let result = scanModules(paths: paths)
+
+    do {
+      let encoder = JSONEncoder()
+      encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+      let data = try encoder.encode(result)
+      FileHandle.standardOutput.write(data)
+      FileHandle.standardOutput.write(Data("\n".utf8))
+      return 0
+    } catch {
+      FileHandle.standardError.write(Data("error: failed to encode results: \(error)\n".utf8))
+      return 1
+    }
+  }
+}
+
+/// One module in the `scan-modules` output. Trimmed to what `expo-modules-autolinking` needs to
+/// register a module: the Swift class name, the JS name it registers under, and the file it's in.
+/// The richer fields the visitor captures (declaration kind, raw macro arguments, line/column) are
+/// dropped here — they're redundant for this command (the macro is always `@ExpoModule` on a class)
+/// and belong to the deep `scan-exports` surface instead.
+struct ScannedModule: Codable, Equatable {
+  /// The Swift class name the module is declared as.
+  let name: String
+
+  /// The fully-resolved JS module name: the `@ExpoModule("Foo")` override when present, otherwise the
+  /// class name. Resolved here (rather than left `nil`) so it matches how the macro derives the name
+  /// and the consumer never has to apply the fallback itself.
+  let jsName: String
+
+  /// Source file the module was found in, relative to the path the scanner was invoked with.
+  let file: String
+}
+
+/// The `scan-modules` result: the detected modules plus the stats describing the run. Encoded as the
+/// command's JSON output. (`scan-exports` will return its own shape when implemented; the two
+/// commands serve different consumers and aren't expected to share an envelope.)
+struct ScanModulesResult: Codable, Equatable {
+  let modules: [ScannedModule]
+  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])
+
+  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)
+  }
+
+  return ScanModulesResult(modules: modules, stats: scan.stats)
+}

package/apple/Sources/ExpoModulesScannerCLI/main.swift

@@ -0,0 +1,70 @@
+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":
+  // Deep extraction (members, record fields, the JS surface of each type) lands in a separate PR.
+  // The subcommand is recognized so the CLI surface is stable, but it isn't implemented yet.
+  fail("scan-exports is not yet implemented", code: 1)
+
+default:
+  fail("unknown subcommand '\(subcommand)'", usage: true)
+}

package/package.json

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