expo-modules-macros 0.32.0 → 0.34.0

package/apple/Sources/ExpoModulesMacrosCore/Macros/ExpoViewMacro.swift

@@ -3,11 +3,11 @@ import SwiftSyntax
 import SwiftSyntaxBuilder
 import SwiftSyntaxMacros
 
-/// Member macro applied to an `ExpoView` subclass, binding it to its props type:
+/// Member and extension macro applied to an `ExpoNativeView` subclass, binding it to its props type:
 ///
 ///   @ExpoView<CardProps>
-///   final class CardView: ExpoView {
-///     override func didUpdateProps(_ diff: CardProps.Diff) {
+///   final class CardView: ExpoNativeView {
+///     func didUpdateProps(_ diff: CardProps.Diff) {
 ///       if diff.changed(.color) {
 ///         backgroundColor = props.color
 ///       }
@@ -21,23 +21,25 @@ import SwiftSyntaxMacros
 /// compile error at the author's own line ("requires that 'X' conform to 'AnyViewProps'")
 /// rather than a macro diagnostic. This macro therefore validates nothing about the props type.
 ///
-/// The whole expansion is one line:
+/// The expansion is a typealias and a conformance:
 ///
 ///   public typealias Props = CardProps
+///   extension CardView: AnyNativeView {}
 ///
-/// That is deliberately all of it. There is **no view definition**: no `ViewDefinition`, no
-/// `View(…) { }` builder, no `Props(_:)` or `Events(_:)` element. `_synthesizedViewDefinition()`
-/// existed only to hand core a DSL value the old registration path could consume, and modules and
-/// shared objects already moved to direct hooks. Core reads the props type from this typealias and
-/// the event names from the props type's own `_eventNames` (synthesized by `@ViewProps`), both
-/// static, neither needing a builder to be evaluated.
+/// There is **no view definition**: no `ViewDefinition`, no `View(…) { }` builder, no `Props(_:)` or
+/// `Events(_:)` element. Core reaches the view through the `AnyNativeView` conformance: it reads the
+/// props type from the `Props` typealias, which satisfies the protocol's associated type, and the
+/// event names from the props type's own `_eventNames` (synthesized by `@ViewProps`). Both are
+/// static, so no builder has to be evaluated.
 ///
-/// Views also get no `_decorateView` hook in its place: `_decorateModule` and `_decorateSharedObject`
-/// exist to bind members into a JS object, and a view has no such object. Props reach a view through
-/// Fabric's mounting layer, not a JS call, so a view's runtime entry point is the props update hook.
+/// Views also get no `_decorateView` hook: `_decorateModule` and `_decorateSharedObject` exist to bind
+/// members into a JS object, and a view has no such object. Props reach a view through Fabric's
+/// mounting layer, not a JS call, so a view's runtime entry point is the props update hook.
 ///
-/// `didUpdateProps` is a core-called override, not synthesized here.
-public struct ExpoViewMacro: MemberMacro {
+/// `didUpdateProps` is an `AnyNativeView` requirement with a default in core, not synthesized here.
+/// It isn't an `override`: `ExpoNativeView` has no such method, because its parameter type depends on
+/// the props type.
+public struct ExpoViewMacro: MemberMacro, ExtensionMacro {
   public static func expansion(
     of node: AttributeSyntax,
     providingMembersOf declaration: some DeclGroupSyntax,
@@ -87,38 +89,66 @@ public struct ExpoViewMacro: MemberMacro {
       """
     ]
   }
+
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingExtensionsOf type: some TypeSyntaxProtocol,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [ExtensionDeclSyntax] {
+    // A class that the member macro rejects gets no conformance either: the member macro has already
+    // reported the error, and a conformance without the `Props` typealias would only add a second
+    // error about the associated type.
+    guard let classDecl = declaration.as(ClassDeclSyntax.self),
+      inheritsFromAny(classDecl, names: expoViewBaseClassNames),
+      classDecl.genericParameterClause == nil,
+      existingPropsMemberKind(in: classDecl) == nil,
+      genericArgument(of: node) != nil,
+      !inheritsProtocol(named: nativeViewProtocolName, in: declaration)
+    else {
+      return []
+    }
+    let ext: DeclSyntax = """
+      extension \(type.trimmed): \(raw: nativeViewProtocolName) {}
+      """
+    guard let extDecl = ext.as(ExtensionDeclSyntax.self) else {
+      return []
+    }
+    return [extDecl]
+  }
 }
 
 // MARK: - Diagnostics
 
-/// The error for a class that doesn't name `ExpoView` in its inheritance clause, carrying a fix-it
+/// The error for a class that doesn't name `ExpoNativeView` in its inheritance clause, carrying a fix-it
 /// that adds it.
 ///
 /// The fix-it only applies where the edit is unambiguous. With no inheritance clause at all it
-/// inserts `: ExpoView`; with an existing clause it prepends `ExpoView` as the first entry, since
+/// inserts `: ExpoNativeView`; with an existing clause it prepends `ExpoNativeView` as the first entry, since
 /// Swift requires the superclass to come before any protocol. A class that already names some other
 /// superclass gets the diagnostic without a fix-it: replacing that superclass is a decision the macro
 /// can't make (see the indirect-inheritance note on `expoViewBaseClassNames`).
 private func missingBaseClassDiagnostic(for classDecl: ClassDeclSyntax) -> Diagnostic {
   let message = ExpoViewDiagnosticMessage(
-    "@ExpoView class must inherit from ExpoView. Add `: ExpoView` to the class declaration.",
+    "@ExpoView class must inherit from ExpoNativeView. Add `: ExpoNativeView` to the class declaration.",
     id: "expoview-missing-base-class"
   )
   var fixIts: [FixIt] = []
 
   if classDecl.inheritanceClause == nil {
-    // `class CardView {` → `class CardView: ExpoView {`. The name carries the space before `{` as
+    // `class CardView {` → `class CardView: ExpoNativeView {`. The name carries the space before `{` as
     // trailing trivia, so move it onto the clause to keep the spacing.
     let name = classDecl.name
     let clause = InheritanceClauseSyntax(
       colon: .colonToken(trailingTrivia: .space),
       inheritedTypes: InheritedTypeListSyntax([
-        InheritedTypeSyntax(type: TypeSyntax(IdentifierTypeSyntax(name: .identifier("ExpoView"))))
+        InheritedTypeSyntax(type: TypeSyntax(IdentifierTypeSyntax(name: .identifier("ExpoNativeView"))))
       ])
     )
     fixIts.append(
       FixIt(
-        message: ExpoViewFixItMessage("Inherit from 'ExpoView'", id: "expoview-add-base-class"),
+        message: ExpoViewFixItMessage("Inherit from 'ExpoNativeView'", id: "expoview-add-base-class"),
         changes: [
           .replace(
             oldNode: Syntax(classDecl),
@@ -132,16 +162,16 @@ private func missingBaseClassDiagnostic(for classDecl: ClassDeclSyntax) -> Diagn
       )
     )
   } else if let clause = classDecl.inheritanceClause, inheritsOnlyProtocolsByConvention(clause) {
-    // `class CardView: Identifiable {` → `class CardView: ExpoView, Identifiable {`.
+    // `class CardView: Identifiable {` → `class CardView: ExpoNativeView, Identifiable {`.
     var inherited = clause.inheritedTypes
     if var first = inherited.first {
       first.trailingComma = .commaToken(trailingTrivia: .space)
-      first.type = TypeSyntax(IdentifierTypeSyntax(name: .identifier("ExpoView")))
+      first.type = TypeSyntax(IdentifierTypeSyntax(name: .identifier("ExpoNativeView")))
       inherited.insert(first, at: inherited.startIndex)
     }
     fixIts.append(
       FixIt(
-        message: ExpoViewFixItMessage("Inherit from 'ExpoView'", id: "expoview-add-base-class"),
+        message: ExpoViewFixItMessage("Inherit from 'ExpoNativeView'", id: "expoview-add-base-class"),
         changes: [
           .replace(
             oldNode: Syntax(clause),
@@ -157,7 +187,7 @@ private func missingBaseClassDiagnostic(for classDecl: ClassDeclSyntax) -> Diagn
 
 /// Whether every entry in the clause looks like a protocol rather than a superclass, by the
 /// capitalization-free heuristic that a Swift superclass must come first: if the first entry is one
-/// the macro would be replacing, prepending `ExpoView` would produce two superclasses. A macro can't
+/// the macro would be replacing, prepending `ExpoNativeView` would produce two superclasses. A macro can't
 /// resolve names, so this only reports true when the clause is empty of anything that could be a
 /// base class the author chose deliberately. Conservative by design: a wrong guess here would emit a
 /// fix-it that doesn't compile.
@@ -223,14 +253,14 @@ private func existingPropsMemberKind(in classDecl: ClassDeclSyntax) -> String? {
 }
 
 /// Base classes an `@ExpoView` may inherit from. The check is syntactic, matching the name in the
-/// class's own inheritance clause: both `: ExpoView` and a qualified `: ExpoModulesCore.ExpoView`
+/// class's own inheritance clause: both `: ExpoNativeView` and a qualified `: ExpoModulesCore.ExpoNativeView`
 /// pass, since `baseIdentifier` reads the trailing name.
 ///
-/// Indirect inheritance does not: a view whose superclass is itself an `ExpoView` subclass
-/// (`class Base: ExpoView` then `class CardView: Base`) is rejected, because a macro can't resolve
+/// Indirect inheritance does not: a view whose superclass is itself an `ExpoNativeView` subclass
+/// (`class Base: ExpoNativeView` then `class CardView: Base`) is rejected, because a macro can't resolve
 /// the superclass to check. `@SharedObject` has the same limitation, through the same helper. The
-/// workaround is to apply `@ExpoView` to the class that names `ExpoView` directly.
-private let expoViewBaseClassNames: Set<String> = ["ExpoView"]
+/// workaround is to apply `@ExpoView` to the class that names `ExpoNativeView` directly.
+private let expoViewBaseClassNames: Set<String> = ["ExpoNativeView"]
 
 /// The attribute's single generic argument, verbatim (`@ExpoView<CardProps>` → `"CardProps"`), or
 /// `nil` when the attribute carries no generic argument clause.
@@ -257,3 +287,7 @@ private func genericArgument(of attribute: AttributeSyntax) -> String? {
   }
   return type.trimmedDescription
 }
+
+/// The core protocol that `@ExpoView` conforms the class to. Core registers the view and decodes its
+/// props through it.
+private let nativeViewProtocolName = "AnyNativeView"

package/apple/Sources/ExpoModulesMacrosCore/Macros/JSMacro.swift

@@ -51,6 +51,7 @@ public struct JSMacro: PeerMacro {
     diagnoseConcurrentOption(of: node, on: declaration, in: context)
     diagnoseAsyncVariantOption(of: node, on: declaration, in: context)
     diagnoseJavaScriptValuesOffThread(of: node, on: declaration, in: context)
+    diagnoseRuntimeParameter(of: node, on: declaration, in: context)
 
     // In an `@ExpoModule` or `@SharedObject` class, the class macro emits the assertion instead: it sees
     // the type aliases declared in the class body, which this macro can't (see `TupleTypeAliases`).
@@ -425,6 +426,175 @@ private func diagnoseJavaScriptValuesOffThread(
   }
 }
 
+/// Emits the diagnostics for a parameter that takes the JavaScript runtime (see `isRuntimeParameter`).
+/// The binding passes the runtime of the call, which can be used only on the JavaScript thread. So
+/// the parameter must be:
+/// - in a synchronous function or an initializer. An `async` function can resume on another thread
+///   after an `await`: `@JavaScriptActor` runs a job on the thread that enqueues it, and doesn't move
+///   it to the JavaScript thread. A `.concurrent` function and the variant that `.withAsync` adds run
+///   on the concurrent thread pool;
+/// - `borrowing`, so the body can't keep the runtime for later without an explicit `copy`;
+/// - not optional, since the binding always has a runtime to pass;
+/// - the last parameter, labeled `in` (or `runtime`), so every declaration reads the same and the JavaScript
+///   arguments keep their order.
+private func diagnoseRuntimeParameter(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  let parameters: FunctionParameterListSyntax
+  if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
+    parameters = funcDecl.signature.parameterClause.parameters
+    // `.concurrent` is checked first: its body never runs on the JavaScript thread, so making the
+    // function synchronous doesn't help (a synchronous `.concurrent` function is an error too).
+    let offThread: (reason: String, remedy: String)?
+    if hasOption(node, named: "concurrent") {
+      offThread = ("'.concurrent' runs the body on the concurrent thread pool", "Remove the parameter.")
+    } else if funcDecl.signature.effectSpecifiers?.asyncSpecifier != nil {
+      offThread = (
+        "an 'async' function can resume on another thread after an 'await'",
+        "Remove the parameter, or make the function synchronous."
+      )
+    } else if asyncVariantOption(of: node) != nil {
+      offThread = (
+        "the variant that '.withAsync' adds runs the function on the concurrent thread pool",
+        "Remove the parameter, or remove '.withAsync'."
+      )
+    } else {
+      offThread = nil
+    }
+    if let offThread {
+      for parameter in parameters where isRuntimeParameter(parameter) {
+        context.diagnose(
+          Diagnostic(
+            node: parameter.type,
+            message: JSDiagnosticMessage(
+              "A @JS function can take the JavaScript runtime only when it's synchronous: \(offThread.reason), and the runtime can be used only on the JavaScript thread. \(offThread.remedy)",
+              id: "js-runtime-parameter-async",
+              severity: .error
+            )
+          )
+        )
+      }
+      return
+    }
+  } else if let initDecl = declaration.as(InitializerDeclSyntax.self) {
+    parameters = initDecl.signature.parameterClause.parameters
+  } else {
+    return
+  }
+  for (index, parameter) in parameters.enumerated() where isRuntimeParameter(parameter) {
+    guard index == parameters.count - 1 else {
+      context.diagnose(
+        Diagnostic(
+          node: parameter,
+          message: JSDiagnosticMessage(
+            "The JavaScript runtime must be the last parameter of a @JS function or initializer, and only one parameter can take it. Move it to the end as 'in runtime: borrowing JavaScriptRuntime'.",
+            id: "js-runtime-parameter-position",
+            severity: .error
+          )
+        )
+      )
+      continue
+    }
+    // The errors and the docs name only `in`, which matches the JSI API, such as `encode(_:into:in:)`.
+    // An escaped label (`` `in` ``) is the same label.
+    if !runtimeParameterLabels.contains(withoutBackticks(parameter.firstName.text)) {
+      context.diagnose(
+        Diagnostic(
+          node: parameter.firstName,
+          message: JSDiagnosticMessage(
+            "The parameter that takes the JavaScript runtime must be labeled 'in', as in 'in runtime: borrowing JavaScriptRuntime'.",
+            id: "js-runtime-parameter-label",
+            severity: .error
+          ),
+          fixIts: [runtimeLabelFixIt(for: parameter)]
+        )
+      )
+    }
+    let specified = SpecifiedType(parameter.type)
+    let wrapped = optionalWrappedType(specified.type)
+    if let wrapped {
+      context.diagnose(
+        Diagnostic(
+          node: specified.type,
+          message: JSDiagnosticMessage(
+            "The parameter that takes the JavaScript runtime can't be optional: the binding always passes the runtime of the call.",
+            id: "js-runtime-parameter-optional",
+            severity: .error
+          ),
+          fixIts: [
+            FixIt(
+              message: JSFixItMessage("Remove the optional", id: "js-runtime-parameter-remove-optional"),
+              changes: [
+                .replace(
+                  oldNode: Syntax(specified.type),
+                  newNode: Syntax(
+                    wrapped.trimmed
+                      .with(\.leadingTrivia, specified.type.leadingTrivia)
+                      .with(\.trailingTrivia, specified.type.trailingTrivia)
+                  )
+                )
+              ]
+            )
+          ]
+        )
+      )
+    }
+    if specified.specifiers != ["borrowing"] {
+      context.diagnose(
+        Diagnostic(
+          node: parameter.type,
+          message: JSDiagnosticMessage(
+            "The parameter that takes the JavaScript runtime must be 'borrowing': the runtime can be used only on the JavaScript thread, and a borrowed parameter can't be kept for later without an explicit 'copy'.",
+            id: "js-runtime-parameter-borrowing",
+            severity: .error
+          ),
+          fixIts: [
+            FixIt(
+              message: JSFixItMessage("Mark the parameter 'borrowing'", id: "js-runtime-parameter-insert-borrowing"),
+              changes: [
+                .replace(
+                  oldNode: Syntax(parameter.type),
+                  newNode: Syntax(borrowingType(wrapped ?? specified.type, like: parameter.type))
+                )
+              ]
+            )
+          ]
+        )
+      )
+    }
+  }
+}
+
+/// The labels that the runtime parameter can have.
+private let runtimeParameterLabels: Set<String> = ["in", "runtime"]
+
+/// The fix-it that labels the runtime parameter `in`. It keeps the parameter name that the body uses, or
+/// names the parameter `runtime` when it has no name.
+private func runtimeLabelFixIt(for parameter: FunctionParameterSyntax) -> FixIt {
+  var newParameter = parameter
+  let name = parameter.secondName ?? (parameter.firstName.tokenKind == .wildcard ? nil : parameter.firstName)
+  newParameter.firstName = .keyword(.in, leadingTrivia: parameter.firstName.leadingTrivia, trailingTrivia: .space)
+  newParameter.secondName = name?.trimmed ?? .identifier("runtime")
+  return FixIt(
+    message: JSFixItMessage("Label the parameter 'in'", id: "js-runtime-parameter-label"),
+    changes: [.replace(oldNode: Syntax(parameter), newNode: Syntax(newParameter))]
+  )
+}
+
+/// The type `type` with the single specifier `borrowing`, with the trivia of `original`.
+private func borrowingType(_ type: TypeSyntax, like original: TypeSyntax) -> TypeSyntax {
+  let specifier = SimpleTypeSpecifierSyntax(specifier: .keyword(.borrowing, trailingTrivia: .space))
+  let attributed = AttributedTypeSyntax(
+    specifiers: [.simpleTypeSpecifier(specifier)],
+    baseType: type.trimmed
+  )
+  return TypeSyntax(attributed)
+    .with(\.leadingTrivia, original.leadingTrivia)
+    .with(\.trailingTrivia, original.trailingTrivia)
+}
+
 private func diagnoseParameterSpecifiers(
   in declaration: some DeclSyntaxProtocol,
   in context: some MacroExpansionContext
@@ -437,7 +607,8 @@ private func diagnoseParameterSpecifiers(
   } else {
     return
   }
-  for parameter in parameters {
+  // The runtime parameter isn't decoded, and `diagnoseRuntimeParameter` requires it to be `borrowing`.
+  for parameter in parameters where !isRuntimeParameter(parameter) {
     guard let specifier = SpecifiedType(parameter.type).unsupportedSpecifier else {
       continue
     }
@@ -608,7 +779,8 @@ private func argumentBoundaryTypes(of parameters: FunctionParameterListSyntax) -
   // A closure in any other position is diagnosed by `diagnoseClosureTypes` and left out here, since
   // its metatype isn't a valid expression in the assertion.
   var types: [AssertedType] = []
-  for parameter in parameters {
+  // The runtime parameter takes no JavaScript argument, so nothing decodes into it.
+  for parameter in parameters where !isRuntimeParameter(parameter) {
     let label = parameter.firstName.tokenKind == .wildcard ? nil : parameter.firstName.text
     // The specifier isn't part of the asserted type, and a parameter with one the binding can't honor
     // is reported by `diagnoseParameterSpecifiers` and not asserted.