expo-modules-macros 0.31.0 → 0.33.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

@@ -31,6 +31,20 @@ public struct JSMacro: PeerMacro {
     providingPeersOf declaration: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
+    diagnosePlacement(of: node, on: declaration, in: context)
+    if let genericParameterClause = jsGenericParameterClause(of: declaration) {
+      context.diagnose(
+        Diagnostic(
+          node: genericParameterClause,
+          message: JSDiagnosticMessage(
+            "A @JS function or initializer can't be generic: the binding decodes each argument and encodes the result by its static type, which a generic parameter doesn't have. Use a concrete type, a @Union of the types, or 'JavaScriptValue'.",
+            id: "js-generic-member",
+            severity: .error
+          )
+        )
+      )
+      return []
+    }
     diagnoseParameterSpecifiers(in: declaration, in: context)
     diagnoseFreeFormTypes(in: declaration, in: context)
     diagnoseClosureTypes(in: declaration, in: context)
@@ -75,6 +89,116 @@ private func isInBindingClass(_ context: some MacroExpansionContext) -> Bool {
     || classDecl.attributes.firstAttribute(named: "SharedObject") != nil
 }
 
+/// Reports a `@JS` attribute that no macro binds, so the member would be missing in JavaScript without
+/// an error:
+/// - on a declaration other than a function, property or initializer, such as a subscript;
+/// - on a member of an extension, since `@ExpoModule` and `@SharedObject` read only the class body;
+/// - on a member of a type that isn't an `@ExpoModule` or `@SharedObject` class;
+/// - on a `static` or `class` member of an `@ExpoModule` class, since JavaScript gets only the instance;
+/// - on an initializer of an `@ExpoModule` class, since JavaScript doesn't construct a module.
+private func diagnosePlacement(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  guard
+    declaration.is(FunctionDeclSyntax.self) || declaration.is(VariableDeclSyntax.self)
+      || declaration.is(InitializerDeclSyntax.self)
+  else {
+    let kind = declaration.is(SubscriptDeclSyntax.self) ? "a subscript" : "this declaration"
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "@JS applies to a function, property or initializer, so \(kind) isn't bound to JavaScript. Expose a @JS function instead.",
+          id: "js-unsupported-declaration",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if let extensionDecl = context.lexicalContext.first?.as(ExtensionDeclSyntax.self) {
+    let typeName = extensionDecl.extendedType.trimmedDescription
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "A @JS member of an extension isn't bound to JavaScript: @ExpoModule and @SharedObject bind only the @JS members declared in the class body. Move the member into the declaration of '\(typeName)'.",
+          id: "js-in-extension",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if let enclosingType = context.lexicalContext.first, enclosingType.isProtocol(DeclGroupSyntax.self),
+    !isInBindingClass(context)
+  {
+    let typeName = enclosingType.asProtocol(NamedDeclSyntax.self).map { "'\($0.name.text)'" } ?? "this type"
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "A @JS member of \(typeName) isn't bound to JavaScript: only an @ExpoModule or @SharedObject class binds its @JS members. Add one of these macros to \(typeName), or move the member into such a class.",
+          id: "js-outside-binding-class",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if let modifiers = declaration.asProtocol(WithModifiersSyntax.self)?.modifiers, isTypeLevel(modifiers),
+    let classDecl = context.lexicalContext.first?.as(ClassDeclSyntax.self),
+    classDecl.attributes.firstAttribute(named: "ExpoModule") != nil
+  {
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "A @JS member of an @ExpoModule class can't be 'static' or 'class': JavaScript gets one module object, and @ExpoModule binds the members of the instance to it. Make the member an instance member.",
+          id: "js-module-static-member",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if let initDecl = declaration.as(InitializerDeclSyntax.self),
+    let classDecl = context.lexicalContext.first?.as(ClassDeclSyntax.self),
+    classDecl.attributes.firstAttribute(named: "ExpoModule") != nil
+  {
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "@JS on an initializer of an @ExpoModule class isn't bound to JavaScript: JavaScript doesn't construct a module, it gets the instance that the app context creates. Remove @JS, or construct a @SharedObject class from JavaScript instead.",
+          id: "js-module-initializer",
+          severity: .error
+        ),
+        fixIts: removeAttributeFixIts(node, before: initDecl.initKeyword)
+      )
+    )
+  }
+}
+
+/// The fix-it that removes a `@JS` attribute written on its own line, with the line break and
+/// indentation before it. The macro gets the attribute without the trivia after it, so when the
+/// declaration starts on the line of the attribute (`@JS init()`), the fix-it can't tell how much
+/// space to remove, and there is none. It edits only the text of the attribute, since the declaration
+/// that a peer macro gets can carry attributes that other macros added.
+private func removeAttributeFixIts(_ node: AttributeSyntax, before keyword: TokenSyntax) -> [FixIt] {
+  guard keyword.leadingTrivia.contains(where: \.isNewline) else {
+    return []
+  }
+  return [
+    FixIt(
+      message: JSFixItMessage("Remove '@JS'", id: "js-remove-attribute"),
+      changes: [.replaceText(range: node.position..<node.endPosition, with: "", in: Syntax(node))]
+    )
+  ]
+}
+
 /// Emits the diagnostic for `@JS(.concurrent)` on a member that can't take it. The option maps to
 /// Swift's `@concurrent`, which requires an `async` function: a synchronous member has nowhere to
 /// suspend, and a property or initializer can't be async at all. Diagnosing here points at the

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

@@ -81,6 +81,12 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
     // the author's version stand — the factories only need *an* `init(<properties>)` and `Record` only
     // needs *an* `init()`, regardless of who wrote them.
     let existingInitLabels = initializerParameterLabels(of: declaration)
+    if !existingInitLabels.contains(properties.map { $0.key }) {
+      let diagnostics = unsetPrivatePropertyDiagnostics(of: declaration)
+      guard diagnostics.isEmpty else {
+        throw DiagnosticsError(diagnostics: diagnostics)
+      }
+    }
 
     var members: [DeclSyntax] = []
 
@@ -227,6 +233,10 @@ private func recordProperties(
       guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
         continue
       }
+      // The memberwise init sets every property, and a `let` with a default value can't be set again.
+      if varDecl.bindingSpecifier.tokenKind == .keyword(.let), binding.initializer != nil {
+        throw DiagnosticsError(diagnostics: [letWithDefaultDiagnostic(for: varDecl, name: ident.identifier.text)])
+      }
       // Prefer the explicit annotation. When it's omitted, recover the type from a literal default
       // (Swift's own default-literal type) — covers the common `var name = "foo"` case. Anything
       // whose type a syntactic macro can't determine (calls, collections, member access) still needs
@@ -637,6 +647,64 @@ private func unsupportedClassDiagnostics(of declaration: some DeclGroupSyntax) -
   return diagnostics
 }
 
+/// The errors for the `private` and `fileprivate` stored properties that the synthesized memberwise
+/// initializer would leave without a value. Such a property isn't a record property, so the initializer
+/// doesn't set it, and it needs a default value. An optional `var` starts as `nil`, so it needs none.
+private func unsetPrivatePropertyDiagnostics(of declaration: some DeclGroupSyntax) -> [Diagnostic] {
+  var diagnostics: [Diagnostic] = []
+  for member in declaration.memberBlock.members {
+    guard let varDecl = member.decl.as(VariableDeclSyntax.self),
+      let access = varDecl.modifiers.first(where: {
+        $0.name.tokenKind == .keyword(.private) || $0.name.tokenKind == .keyword(.fileprivate)
+      }),
+      !varDecl.modifiers.contains(where: {
+        $0.name.tokenKind == .keyword(.static) || $0.name.tokenKind == .keyword(.class)
+          || $0.name.tokenKind == .keyword(.lazy)
+      })
+    else {
+      continue
+    }
+    let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
+    for binding in varDecl.bindings where binding.accessorBlock == nil && binding.initializer == nil {
+      guard let ident = binding.pattern.as(IdentifierPatternSyntax.self),
+        !(isVar && binding.typeAnnotation.map { isOptionalType($0.type) } == true)
+      else {
+        continue
+      }
+      diagnostics.append(
+        Diagnostic(
+          node: ident,
+          message: RecordDiagnosticMessage(
+            "@Record leaves out the \(access.name.text) property '\(ident.identifier.text)', so the synthesized initializer doesn't set it. Give it a default value, or remove '\(access.name.text)' to make it a record property",
+            id: "record-unset-private-property"
+          )
+        )
+      )
+    }
+  }
+  return diagnostics
+}
+
+/// The error for a `let` property with a default value, attached to the `let` keyword and carrying a
+/// fix-it that replaces it with `var`. The default still applies when JavaScript omits the property.
+private func letWithDefaultDiagnostic(for varDecl: VariableDeclSyntax, name: String) -> Diagnostic {
+  let specifier = varDecl.bindingSpecifier
+  let fixIt = FixIt(
+    message: RecordFixItMessage("Replace 'let' with 'var'", id: "record-let-to-var"),
+    changes: [
+      .replace(oldNode: Syntax(specifier), newNode: Syntax(specifier.with(\.tokenKind, .keyword(.var))))
+    ]
+  )
+  return Diagnostic(
+    node: specifier,
+    message: RecordDiagnosticMessage(
+      "@Record property '\(name)' is a 'let' with a default value, so the synthesized initializer can't set it from JavaScript. Make it a 'var', and the default applies when JavaScript omits the property, or make it 'static' or 'private' to leave it out of the record",
+      id: "record-let-with-default"
+    ),
+    fixIts: [fixIt]
+  )
+}
+
 /// The fix-it for a record class that isn't `final`: add the modifier right before `class`.
 private func markFinalFixIt(for classDecl: ClassDeclSyntax) -> FixIt {
   // The new modifier takes over the leading trivia of `class` (the line break after the attribute

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

@@ -1,3 +1,4 @@
+import SwiftDiagnostics
 import SwiftSyntax
 import SwiftSyntaxBuilder
 import SwiftSyntaxMacros
@@ -42,9 +43,13 @@ public struct SharedObjectMacro: MemberMacro {
       in: context
     )
 
-    // The superclass isn't checked here: the macro sees only this declaration, so it can't tell an
+    // A class without an inheritance clause has no superclass, so it can't be a `SharedObject`. Any
+    // other superclass isn't checked: the macro sees only this declaration, so it can't tell an
     // indirect subclass (`class Thumbnail: ImageRef`) from an unrelated class. The compiler reports a
     // class that isn't a `SharedObject` subclass on the `_jsName` override, which is always emitted.
+    if classDecl.inheritanceClause == nil {
+      throw DiagnosticsError(diagnostics: [missingBaseClassDiagnostic(for: classDecl)])
+    }
     let typeName = classDecl.name.text
     let jsName = jsNameArgument(of: node) ?? withoutBackticks(typeName)
 
@@ -71,6 +76,10 @@ public struct SharedObjectMacro: MemberMacro {
     for member in classDecl.memberBlock.members {
       // The types of a `@JS` member are read with the class's tuple aliases resolved.
       let decl = aliases.resolving(member.decl)
+      // A generic member is reported by `@JS` and left out, so the build has no errors in its binding.
+      if memberHasJSAttribute(decl) && jsGenericParameterClause(of: decl) != nil {
+        continue
+      }
       if memberHasJSAttribute(decl), let assertion = jsConformanceAssertionBody(for: decl) {
         assertions.append(assertion)
       }
@@ -114,6 +123,19 @@ public struct SharedObjectMacro: MemberMacro {
 
     diagnoseJSNameCollisions(functions: instanceFunctions, properties: instanceProperties, in: context)
     diagnoseJSNameCollisions(functions: staticFunctions, properties: staticProperties, in: context)
+    diagnoseReservedJSNames(
+      functions: instanceFunctions,
+      properties: instanceProperties,
+      on: .prototype,
+      in: context
+    )
+    diagnoseReservedJSNames(
+      functions: staticFunctions,
+      properties: staticProperties,
+      on: .constructor,
+      in: context
+    )
+    diagnoseEventNameCollisions(in: classDecl.memberBlock, in: context)
 
     // The resolved JS class name, read by core when it builds the class. An `override` of the
     // `SharedObject` class property, so core reads it through the concrete type's metatype.
@@ -199,3 +221,59 @@ extension SharedObjectMacro: ExtensionMacro {
     return [sendable]
   }
 }
+
+/// The error for a `@SharedObject` class without an inheritance clause, with a fix-it that makes it
+/// inherit from `SharedObject`: `class Cache {` becomes `class Cache: SharedObject {`.
+private func missingBaseClassDiagnostic(for classDecl: ClassDeclSyntax) -> Diagnostic {
+  // 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("SharedObject"))))
+    ])
+  )
+  let fixIt = FixIt(
+    message: SharedObjectFixItMessage("Inherit from 'SharedObject'", id: "sharedobject-add-base-class"),
+    changes: [
+      .replace(
+        oldNode: Syntax(classDecl),
+        newNode: Syntax(
+          classDecl
+            .with(\.name, name.with(\.trailingTrivia, []))
+            .with(\.inheritanceClause, clause.with(\.trailingTrivia, name.trailingTrivia))
+        )
+      )
+    ]
+  )
+  return Diagnostic(
+    node: name,
+    message: SharedObjectDiagnosticMessage(
+      "@SharedObject class '\(name.text)' must inherit from 'SharedObject', directly or through another class such as 'SharedRef'. Add ': SharedObject' to the class declaration.",
+      id: "sharedobject-missing-base-class"
+    ),
+    fixIts: [fixIt]
+  )
+}
+
+private struct SharedObjectDiagnosticMessage: 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 SharedObjectFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}

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

@@ -35,7 +35,9 @@ import SwiftSyntaxMacros
 /// Discrimination is structural and order-dependent: the first case whose payload decodes wins. When
 /// two payload shapes overlap (two records with compatible fields, `Int` and `Double`), the earlier
 /// case matches; the author orders the more specific case first. A case may not repeat another case's
-/// payload type, since it could never be chosen.
+/// payload type, since it could never be chosen. A case after a `JavaScriptValue` case, or with a
+/// number-only payload after a `Double`, `Float` or `CGFloat` case, can't be chosen either, so the macro
+/// warns about it.
 ///
 /// The named-union counterpart of core's `Either`: any number of named cases instead of two anonymous
 /// slots, no `Any?` box, and an exhaustive `switch` as the primary way to read it (`as(_:)` covers the
@@ -48,6 +50,7 @@ public struct UnionMacro: MemberMacro, ExtensionMacro {
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
     let union = try validatedUnion(of: declaration)
+    diagnoseUnreachableCases(of: declaration, in: context)
 
     var members: [DeclSyntax] = []
 
@@ -223,8 +226,8 @@ private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> Unio
       let payloadType = parameter.type.trimmedDescription
       // Alternatives decode in declaration order and the first success wins, so a case whose payload
       // type repeats an earlier case's is unreachable: an exact-spelling duplicate is an error. (An
-      // overlap between *different* types, like `Int` and `Double`, is the author's ordering call and
-      // isn't checked here.)
+      // overlap between *different* types, like `Int` and `Double`, is the author's ordering call;
+      // `diagnoseUnreachableCases` warns about the overlaps that make a case unreachable.)
       let normalizedType = payloadType.filter { !$0.isWhitespace }
       if let earlierCase = seenPayloadTypes[normalizedType] {
         diagnostics.append(
@@ -256,6 +259,88 @@ private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> Unio
   return UnionType(name: enumDecl.name.text, cases: cases)
 }
 
+/// The payload types whose decode accepts every JavaScript number: they convert the number with
+/// `asDouble()`, so they never fail on one.
+private let anyNumberPayloadTypes: Set<String> = ["Double", "Float", "CGFloat"]
+
+/// The payload types that decode only a JavaScript number, so a case before them with a type of
+/// `anyNumberPayloadTypes` decodes every value they could. `Int`, `Int64`, `UInt` and `UInt64` aren't
+/// listed, since they also decode a `bigint`.
+private let numberOnlyPayloadTypes: Set<String> = [
+  "Double", "Float", "CGFloat", "Int8", "Int16", "Int32", "UInt8", "UInt16", "UInt32",
+]
+
+/// Warns about each case that an earlier case always decodes first, so it is never chosen. Cases are
+/// tried in declaration order and the first that decodes wins. The macro knows that only for some
+/// payload types: a `JavaScriptValue` payload decodes every value, and a floating-point payload every
+/// number, so a later case that decodes only numbers can't be reached. Types with the same spelling
+/// are reported as an error by `validatedUnion`, which runs first.
+private func diagnoseUnreachableCases(of declaration: some DeclGroupSyntax, in context: some MacroExpansionContext) {
+  var catchAllCase: (name: TokenSyntax, type: String)?
+  var anyNumberCase: (name: TokenSyntax, type: String)?
+
+  for member in declaration.memberBlock.members {
+    guard let caseDecl = member.decl.as(EnumCaseDeclSyntax.self) else {
+      continue
+    }
+    for element in caseDecl.elements {
+      guard let parameter = element.parameterClause?.parameters.first else {
+        continue
+      }
+      let type = unqualifiedPayloadTypeName(parameter.type)
+      let reason: String?
+      let earlier: (name: TokenSyntax, type: String)?
+      if let catchAllCase {
+        earlier = catchAllCase
+        reason = "'\(catchAllCase.type)' decodes every JavaScript value"
+      } else if let anyNumberCase, numberOnlyPayloadTypes.contains(type) {
+        earlier = anyNumberCase
+        reason = "'\(anyNumberCase.type)' decodes every JavaScript number, and '\(type)' decodes only numbers"
+      } else {
+        earlier = nil
+        reason = nil
+      }
+      if let earlier, let reason {
+        let name = element.name.text
+        context.diagnose(
+          Diagnostic(
+            node: element,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' is never decoded: case '\(earlier.name.text)' is tried first, and \(reason). Move case '\(name)' before case '\(earlier.name.text)'.",
+              id: "union-unreachable-case",
+              severity: .warning
+            ),
+            notes: [
+              Note(
+                node: Syntax(earlier.name),
+                message: UnionNoteMessage(
+                  "case '\(earlier.name.text)' is declared here",
+                  id: "union-unreachable-case-earlier"
+                )
+              )
+            ]
+          )
+        )
+        continue
+      }
+      if type == "JavaScriptValue" {
+        catchAllCase = (element.name, type)
+      } else if anyNumberCase == nil, anyNumberPayloadTypes.contains(type) {
+        anyNumberCase = (element.name, type)
+      }
+    }
+  }
+}
+
+/// The name of a payload type without the module that it may be qualified with, such as `Swift.Double`.
+private func unqualifiedPayloadTypeName(_ type: TypeSyntax) -> String {
+  let modules = ["Swift", "CoreGraphics", "CoreFoundation", "Foundation", "ExpoModulesCore", "ExpoModulesJSI"]
+  if let memberType = type.as(MemberTypeSyntax.self), modules.contains(memberType.baseType.trimmedDescription) {
+    return memberType.name.text
+  }
+  return type.trimmedDescription
+}
+
 // MARK: - Synthesized members
 
 /// `decode(_:in:)`: tries each case's payload converter in declaration order and returns the first
@@ -429,11 +514,22 @@ private func defaultValueDiagnostic(
 private struct UnionDiagnosticMessage: DiagnosticMessage {
   let message: String
   let diagnosticID: MessageID
-  let severity: DiagnosticSeverity = .error
+  let severity: DiagnosticSeverity
 
-  init(_ message: String, id: String) {
+  init(_ message: String, id: String, severity: DiagnosticSeverity = .error) {
     self.message = message
     self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+    self.severity = severity
+  }
+}
+
+private struct UnionNoteMessage: NoteMessage {
+  let message: String
+  let noteID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.noteID = MessageID(domain: "ExpoModulesMacros", id: id)
   }
 }