expo-modules-macros 0.0.1 → 0.14.0

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

@@ -0,0 +1,263 @@
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/**
+ Macro applied to a module class. It plays three roles, each implemented in its own
+ extension below:
+
+ - `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.
+
+ Inheriting from `Module` is therefore optional — a class can carry any superclass (or
+ none) and still be a module, because everything inheritance used to provide is synthesized.
+
+   @ExpoModule
+   public final class MyModule {
+     public func definition() -> ModuleDefinition {
+       Name("MyModule")
+     }
+
+     @JS
+     func greet(name: String) -> String { "Hi, \(name)" }
+   }
+ */
+public struct ExpoModuleMacro: MemberMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingMembersOf declaration: some DeclGroupSyntax,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    guard let classDecl = declaration.as(ClassDeclSyntax.self) else {
+      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] = []
+
+    // `@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(...)`
+    // DSL entry, so they're collected here instead of appended to `entries`.
+    var functions: [JSFunction] = []
+    var properties: [JSProperty] = []
+
+    for typeName in classListArgument(of: node, label: "classes") {
+      entries.append("\(typeName)._synthesizedClassDefinition()")
+    }
+
+    for member in classDecl.memberBlock.members {
+      let decl = member.decl
+
+      if let funcDecl = decl.as(FunctionDeclSyntax.self),
+        let attribute = funcDecl.attributes.firstAttribute(named: "JS") {
+        functions.append(JSFunction(funcDecl: funcDecl, attribute: attribute))
+        continue
+      }
+
+      if let varDecl = decl.as(VariableDeclSyntax.self),
+        let attribute = varDecl.attributes.firstAttribute(named: "JS") {
+        properties.append(contentsOf: collectProperties(varDecl: varDecl, attribute: attribute))
+      }
+    }
+
+    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)\"")
+
+    // View classes are registered by type, not spliced as definitions: an `@ExpoView` emits no
+    // definition function, so there is nothing to call on each entry. Core reads a view's props
+    // type from its `Props` typealias and its event names from that type's `_eventNames`, both
+    // static. Emitted only when the argument is present, so a module without views gains nothing.
+    let viewTypes = classListArgument(of: node, label: "views")
+    if !viewTypes.isEmpty {
+      let entries = viewTypes.map { "\($0).self" }.joined(separator: ", ")
+      emitted.append("public static let _viewTypes: [Any.Type] = [\(raw: entries)]")
+    }
+
+    // `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,
+    // to avoid emitting a duplicate declaration.
+    if !inheritsFromAny(classDecl, names: ["Module", "BaseModule"]) {
+      if !hasStoredProperty(classDecl, named: "appContext") {
+        emitted.append("public weak var appContext: AppContext?")
+      }
+      if !hasAppContextInitializer(classDecl) {
+        emitted.append(
+          """
+          public required init(appContext: AppContext) {
+            self.appContext = appContext
+          }
+          """
+        )
+      }
+    }
+
+    // Always emitted: the definition is derived from the class name and `@JS` members,
+    // independent of any `definition()` the user wrote.
+    let method: DeclSyntax = """
+      public func _synthesizedDefinition() -> [AnyDefinition] {
+      \(raw: body)
+      }
+      """
+    emitted.append(method)
+
+    // Direct JSI binding: one `_decorateModule` that binds each `@JS func` (inlined `setProperty`
+    // closure) and each `@JS var` (a `defineProperty` get/set accessor) into the module's JS object.
+    // Only emitted when there's at least one member to bind.
+    if !functions.isEmpty || !properties.isEmpty {
+      emitted.append(buildDecorateJavaScriptObject(functions: functions, properties: properties))
+    }
+
+    return emitted
+  }
+}
+
+extension ExpoModuleMacro: MemberAttributeMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingAttributesFor member: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [AttributeSyntax] {
+    // This macro is invoked once per member and may attach more than one attribute,
+    // so we collect into an array rather than returning early. The two checks below are
+    // independent — a given member matches at most one in practice, but they're written
+    // so neither precludes the other.
+    var attributes: [AttributeSyntax] = []
+
+    // `@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`.
+    // `@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")
+    }
+
+    // `@JS(.concurrent)` is the inverse: instead of the JS-thread stamp the member gets
+    // `@concurrent`, so its body runs on the concurrent pool. `shouldStampJavaScriptActor` already
+    // skipped the stamp above, leaving the two mutually exclusive.
+    if isConcurrentJSMember(member) {
+      attributes.append("@concurrent")
+    }
+
+    // Apply the result builder to `definition()` so the user doesn't have to. Skipped if
+    // they already wrote `@ModuleDefinitionBuilder` themselves, which would otherwise be
+    // a duplicate attribute.
+    if isModuleDefinitionFunction(member),
+      !memberAttributes(of: member).contains(where: { hasAttributeName($0, "ModuleDefinitionBuilder") }) {
+      attributes.append("@ModuleDefinitionBuilder")
+    }
+
+    return attributes
+  }
+}
+
+private func isModuleDefinitionFunction(_ member: some DeclSyntaxProtocol) -> Bool {
+  guard let funcDecl = member.as(FunctionDeclSyntax.self),
+    funcDecl.name.text == "definition",
+    funcDecl.signature.parameterClause.parameters.isEmpty,
+    let returnType = funcDecl.signature.returnClause?.type else {
+    return false
+  }
+  return baseIdentifier(of: returnType) == "ModuleDefinition"
+}
+
+private func hasAttributeName(_ element: AttributeListSyntax.Element, _ name: String) -> Bool {
+  guard let attribute = element.as(AttributeSyntax.self) else {
+    return false
+  }
+  return attribute.attributeName.trimmedDescription == name
+}
+
+extension ExpoModuleMacro: ExtensionMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingExtensionsOf type: some TypeSyntaxProtocol,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [ExtensionDeclSyntax] {
+    // `protocols` is empty when the compiler already sees the conformance (e.g. it's
+    // spelled in the declaration), in which case there's nothing for us to add.
+    guard !protocols.isEmpty else {
+      return []
+    }
+    // These base types already supply `AnyModule`; emitting a second conformance here
+    // would be redundant and error.
+    if let classDecl = declaration.as(ClassDeclSyntax.self),
+      inheritsFromAny(classDecl, names: ["Module", "BaseModule", "AnyModule"]) {
+      return []
+    }
+    let conformance: DeclSyntax = "extension \(type.trimmed): AnyModule {}"
+    return [conformance.cast(ExtensionDeclSyntax.self)]
+  }
+}
+
+// MARK: - Synthesized-member detection
+
+private func hasStoredProperty(_ classDecl: ClassDeclSyntax, named name: String) -> Bool {
+  for member in classDecl.memberBlock.members {
+    guard let varDecl = member.decl.as(VariableDeclSyntax.self) else {
+      continue
+    }
+    for binding in varDecl.bindings {
+      if let identifier = binding.pattern.as(IdentifierPatternSyntax.self),
+        identifier.identifier.text == name {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/**
+ True if the class declares an initializer that satisfies the `init(appContext:)` protocol
+ requirement: a single parameter labeled `appContext` whose type is written as `AppContext`
+ (or `…​.AppContext`). Both must match — the label is part of the requirement, so
+ `init(c: AppContext)` does *not* satisfy it (we still synthesize ours), and the type guards
+ against a same-labeled init of an unrelated type. A macro can't resolve types, so this is a
+ syntactic match on the spelled name.
+ */
+private func hasAppContextInitializer(_ classDecl: ClassDeclSyntax) -> Bool {
+  for member in classDecl.memberBlock.members {
+    guard let initDecl = member.decl.as(InitializerDeclSyntax.self) else {
+      continue
+    }
+    let params = initDecl.signature.parameterClause.parameters
+    guard params.count == 1, let param = params.first else {
+      continue
+    }
+    if param.firstName.text == "appContext", baseIdentifier(of: param.type) == "AppContext" {
+      return true
+    }
+  }
+  return false
+}