expo-modules-macros 0.17.0 → 0.19.0

package/apple/Sources/ExpoModulesMacros/ClosureArguments.swift

@@ -68,29 +68,20 @@ internal struct JSClosureType {
     let isVariadic: Bool
 
     init(_ element: TupleTypeElementSyntax) {
-      if let attributed = element.type.as(AttributedTypeSyntax.self), !attributed.specifiers.isEmpty {
-        self.specifiers = attributed.specifiers.map(\.trimmedDescription)
-        self.type =
-          attributed.attributes.isEmpty
-          ? attributed.baseType : TypeSyntax(attributed.with(\.specifiers, []))
-      } else {
-        self.specifiers = []
-        self.type = element.type
-      }
+      let specified = SpecifiedType(element.type)
+      self.specifiers = specified.specifiers
+      self.type = specified.type
       self.isVariadic = element.ellipsis != nil
     }
 
-    /// The first specifier the wrapper can't support, such as `inout` or `isolated`.
+    /// The first specifier the wrapper can't support, such as `inout` or `isolated`. The wrapper passes
+    /// each parameter on to the callback, so an ownership convention doesn't change what it does.
     var unsupportedSpecifier: String? {
-      return specifiers.first { !supportedParameterSpecifiers.contains($0) }
+      return specifiers.first { !ownershipSpecifiers.contains($0) }
     }
   }
 }
 
-/// The ownership specifiers a closure parameter may carry. The wrapper passes each parameter on to the
-/// callback, so the ownership convention doesn't change what it does.
-private let supportedParameterSpecifiers: Set<String> = ["borrowing", "consuming", "sending", "__shared", "__owned"]
-
 /// The statements that bind `name` to the native value of a `@JS` argument read from
 /// `valueExpression` (a `JavaScriptUnownedValue`). A closure gets a wrapper around the JS function,
 /// and every other type decodes through `decodeCall`.
@@ -99,8 +90,11 @@ internal func argumentDecodeStatements(
   into name: String,
   from valueExpression: String
 ) -> [String] {
+  // A specifier such as `borrowing` belongs to the parameter, not to the type that decodes.
+  let type = SpecifiedType(type).type
   guard let closure = JSClosureType(type) else {
-    return ["let \(name) = try \(decodeCall(type.trimmedDescription, from: valueExpression))"]
+    let decode = decodeCall(type.trimmedDescription, freeForm: freeFormConversion(of: type), from: valueExpression)
+    return ["let \(name) = try \(decode)"]
   }
   return closureArgumentStatements(closure, into: name, from: valueExpression)
 }
@@ -286,7 +280,7 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
   }
 
   // The closure's parameters are encoded and its result is decoded, so neither can be another
-  // closure or a free-form type.
+  // closure or a type that mentions `Any`, in any shape.
   let returnType = functionType.returnClause.type
   for type in closure.parameters.map(\.type) + [returnType] {
     if let nested = firstFunctionType(in: type) {
@@ -297,7 +291,7 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
             "A @JS closure argument can't take or return another closure.",
             id: "js-closure-nested"
           )))
-    } else if isFreeFormBoundaryType(type.trimmedDescription) {
+    } else if mentionsFreeFormAny(type) {
       context.diagnose(
         Diagnostic(
           node: type,

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -19,16 +19,19 @@ internal struct JSFunction {
   let parameters: [FunctionParameterSyntax]
   /// The declared return type as written, or `nil` when the function returns `Void`/nothing.
   let returnType: String?
+  /// How the return value encodes when its type mentions `Any`, or `nil` for any other type.
+  let returnFreeForm: FreeFormConversion?
   let isThrowing: Bool
   let isAsync: Bool
 
   init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
     self.swiftName = funcDecl.name.text
-    self.jsName = jsNameArgument(of: attribute) ?? funcDecl.name.text
+    self.jsName = jsNameArgument(of: attribute) ?? withoutBackticks(funcDecl.name.text)
     self.parameters = Array(funcDecl.signature.parameterClause.parameters)
 
     let declaredReturnType = funcDecl.signature.returnClause?.type
     self.returnType = isVoidType(declaredReturnType) ? nil : declaredReturnType?.trimmedDescription
+    self.returnFreeForm = declaredReturnType.flatMap(freeFormConversion(of:))
 
     let effectSpecifiers = funcDecl.signature.effectSpecifiers
     self.isThrowing = effectSpecifiers?.throwsClause?.throwsSpecifier != nil
@@ -220,9 +223,10 @@ internal struct JSFunction {
     return lines
   }
 
-  /// Encode the `result` local back to JS and return it through `JavaScriptEncodable.encode`, the same
-  /// for every type. Unlike the decode side there's no primitive fast path: `encode` produces the same
-  /// value as the primitive's `toJavaScriptValue(in:)` except for `Int`/`UInt`, where it range-checks
+  /// Encode the `result` local back to JS and return it through `JavaScriptEncodable.encode` (or, for a
+  /// type that mentions `Any`, the matching `JavaScriptValue` free-form method). Unlike the decode side
+  /// there's no primitive fast path: `encode` produces the same value as the primitive's
+  /// `toJavaScriptValue(in:)` except for `Int`/`UInt`, where it range-checks
   /// and throws instead of silently encoding an out-of-safe-range value as a lossy number — the
   /// catchable error is the right behavior, and matches how non-primitive integers already encode. A
   /// no-return function returns `.undefined()` instead.
@@ -237,7 +241,7 @@ internal struct JSFunction {
     guard let returnType else {
       return ["return .undefined()"]
     }
-    let encode = "try \(expressionType(returnType)).encode(result, in: runtime)"
+    let encode = "try \(encodeCall(returnType, freeForm: returnFreeForm, of: "result"))"
     if isAsync {
       return [
         "return try await runtime.execute {",
@@ -290,7 +294,8 @@ internal struct JSFunction {
 /// The receiver (see `Receiver`) is the module's `self` for a module binding, or the per-call `_self`
 /// unwrapped from the JS `this` for a shared object. The getter reads `<callee>.<name>` and the setter
 /// writes `<callee>.<name> = …`. Decode/encode of the value go through `JavaScriptDecodable.decode` /
-/// `JavaScriptEncodable.encode`, the same uniform path as functions.
+/// `JavaScriptEncodable.encode` (or the free-form methods for a type that mentions `Any`), the same
+/// path as functions.
 internal struct JSProperty {
   let swiftName: String
   let jsName: String
@@ -298,6 +303,8 @@ internal struct JSProperty {
   /// no literal default). When `nil` the getter still works (the encode infers from `self.<name>`)
   /// but the setter uses an untyped closure parameter.
   let valueType: String?
+  /// How the value converts when its type mentions `Any`, or `nil` for any other type.
+  let freeForm: FreeFormConversion?
   /// Whether the property is settable from JS: `true` for a stored `var` or a computed `var` with an
   /// explicit `set` accessor; `false` for a getter-only computed `var` or a `let`.
   let isSettable: Bool
@@ -309,7 +316,7 @@ internal struct JSProperty {
   /// function bindings: a module captures `self` strong, a shared object captures nothing of the
   /// instance. Getter and setter are gated independently.
   func decorateStatements(object: String, receiver: Receiver) -> String {
-    let descriptorName = "\(swiftName)Descriptor"
+    let descriptorName = derivedIdentifier(from: swiftName, suffix: "Descriptor")
     let callee = receiver.callee
     // A shared object's accessors unwrap the JS `this` into `_self` before reading/writing; a module
     // reads `self` directly. The unwrap leads each accessor body. Property accessors are synchronous, so
@@ -325,7 +332,7 @@ internal struct JSProperty {
     // no static type to call `encode` on, so the value's own `toJavaScriptValue(in:)` is the fallback.
     let getEncode: String
     if let valueType {
-      getEncode = "return try \(expressionType(valueType)).encode(\(callee).\(swiftName), in: runtime)"
+      getEncode = "return try \(encodeCall(valueType, freeForm: freeForm, of: "\(callee).\(swiftName)"))"
     } else {
       getEncode = "return \(callee).\(swiftName).toJavaScriptValue(in: runtime)"
     }
@@ -337,7 +344,8 @@ internal struct JSProperty {
     // getter-only (a settable var with neither an annotation nor a literal default is rare and can't
     // be decoded).
     if isSettable, let valueType {
-      let setDecode = "\(callee).\(swiftName) = try \(decodeCall(valueType, from: "arguments.unownedValue(at: 0)"))"
+      let decode = decodeCall(valueType, freeForm: freeForm, from: "arguments.unownedValue(at: 0)")
+      let setDecode = "\(callee).\(swiftName) = try \(decode)"
       lines.append(
         accessorClosure(
           descriptorName, "set", receiver: receiver, body: "\(unwrap)\(setDecode)\nreturn .undefined()"))

package/apple/Sources/ExpoModulesMacros/EventMacro.swift

@@ -91,9 +91,10 @@ extension EventMacro: PeerMacro {
       ? "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)"
+    let peerName = derivedIdentifier(from: name, prefix: "_assertTypesConformance_")
     return [
       """
-      private func _assertTypesConformance_\(raw: name)() {
+      private func \(raw: peerName)() {
       \(raw: helper)
       \(raw: call)
       }
@@ -172,7 +173,7 @@ private func validatedEvent(
   let swiftName = identifier.identifier.text
   return EventMember(
     swiftName: swiftName,
-    jsName: jsNameArgument(of: node) ?? defaultEventName(for: swiftName),
+    jsName: jsNameArgument(of: node) ?? defaultEventName(for: withoutBackticks(swiftName)),
     payloadType: functionType.parameters.first?.type.trimmedDescription,
     isSync: boolArgument(of: node, label: "sync") == true
   )

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -45,7 +45,7 @@ public struct ExpoModuleMacro: MemberMacro {
     // 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
+    let moduleName = jsNameArgument(of: node) ?? withoutBackticks(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

package/apple/Sources/ExpoModulesMacros/FreeFormTypes.swift

@@ -1,74 +1,123 @@
 import SwiftSyntax
 
-/// Recognition of the free-form (`Any`-bearing) boundary types and the spellings the macros emit or
-/// suggest for them. None of these types can conform to the JS codable protocols (`Any` can't conform
-/// to a protocol, and the container conditional conformances require the element/value to conform), so
-/// they can't cross the boundary through the usual `T.decode` / `T.encode` path. Instead they're
-/// accepted **only** in decode position (function/constructor arguments), decoded through a dedicated
-/// `JavaScriptValue.decodeAny…` entry point; a free-form return or getter is rejected, since there's
-/// no free-form encode.
+/// Recognition of the free-form (`Any`-bearing) boundary types and the conversions the macros emit for
+/// them. None of these types can conform to the JS codable protocols (`Any` can't conform to a
+/// protocol, and the container conditional conformances require the element/value to conform), so
+/// they can't cross the boundary through the usual `T.decode` / `T.encode` path. They convert through
+/// the `JavaScriptValue` free-form methods instead: the three free-form shapes (`Any`, `[Any]` and
+/// `[String: Any]`), optionally wrapped in one optional, use the dedicated `decodeAny…` and
+/// `encodeAny…` methods, and every other type built from `Any`, arrays, `String`-keyed dictionaries and
+/// optionals uses the generic `decodeAny(_:as:in:)` and `encodeAny(_:in:)`.
 ///
-/// Shared across the macro pipeline: `TypeConformanceAssertion` skips them, `MacroHelpers.decodeCall`
-/// reroutes their decode, and `JSMacro` uses them for the steering diagnostics.
-///
-/// `@Record` accepts a property whose type mentions `Any` anywhere (`Any?`, `[String: Any]?`,
-/// `[String: [Any]]`, …) and converts it on the JS-value paths without `decode`/`encode`: the three
-/// free-form shapes, optionally wrapped in one optional, use the dedicated `JavaScriptValue.decodeAny…`
-/// and `encodeAny…` methods, and every other type uses the generic `decodeAny(_:as:in:)` and
-/// `encodeAny(_:in:)`.
+/// Shared across the macro pipeline: `@Record` properties and `@JS` arguments, return values and
+/// properties convert through `FreeFormConversion` (the `@JS` bindings by way of
+/// `MacroHelpers.decodeCall` and `encodeCall`), `TypeConformanceAssertion` skips the free-form shapes,
+/// and `JSMacro` uses them for its diagnostics.
 
 /// The free-form boundary types: an untyped value (`Any`), an untyped array (`[Any]`), and an untyped
 /// string-keyed dictionary (`[String: Any]`). Matched by whitespace-normalized spelling so
 /// `[String: Any]` and `[String : Any]` both count.
 private let freeFormBoundaryTypes: Set<String> = ["Any", "[Any]", "[String:Any]"]
 
-/// The `JavaScriptValue.decodeAny…` method the binding calls to decode a free-form argument, keyed by
-/// the free-form type's normalized spelling. `nil` for any non-free-form type.
-private let freeFormDecodeMethods: [String: String] = [
-  "Any": "decodeAny",
-  "[Any]": "decodeAnyArray",
-  "[String:Any]": "decodeAnyDictionary",
-]
-
-/// The type-safe alternative a free-form type's diagnostic steers to: the JS wrapper of the same shape
-/// (`JavaScriptArray` for an array, `JavaScriptObject` for a dictionary, `JavaScriptValue` for an
-/// untyped value). The wrappers conform to the codable protocols and keep the value unconverted; a
-/// non-copyable `JavaScriptValue` cannot be an element of a Swift array or dictionary, so the container
-/// shapes map to a wrapper rather than to a container of values. Keyed by the free-form type's
-/// normalized spelling.
-private let typedFreeFormReplacements: [String: String] = [
-  "Any": "JavaScriptValue",
-  "[Any]": "JavaScriptArray",
-  "[String:Any]": "JavaScriptObject",
-]
-
-/// True when a boundary type (as written) is one of the free-form spellings, ignoring internal
-/// whitespace so `[String: Any]` and `[String :Any]` both match. Optionals are not free-form here: a
-/// trailing `?` would route through `Optional.decode`, which free-form can't satisfy, so an optional
-/// free-form type isn't recognized and stays a normal (failing) assertion.
+/// True when a boundary type (as written) is exactly one of the free-form shapes, ignoring internal
+/// whitespace so `[String: Any]` and `[String :Any]` both match. An optional or nested free-form type
+/// doesn't match; `freeFormConversion(of:)` recognizes those.
 internal func isFreeFormBoundaryType(_ type: String) -> Bool {
   return freeFormBoundaryTypes.contains(normalizedTypeSpelling(type))
 }
 
-/// The `JavaScriptValue.decodeAny…` method name for a free-form boundary type, or `nil` when the type
-/// isn't free-form. The binding emits `JavaScriptValue.<method>(arguments.unownedValue(at:), in:)` in
-/// place of the type's own `.decode`.
-internal func freeFormDecodeMethod(for type: String) -> String? {
-  return freeFormDecodeMethods[normalizedTypeSpelling(type)]
-}
-
-/// The type-safe alternative to suggest in place of a free-form type (the JS wrapper of the same shape),
-/// or `nil` when the type isn't free-form.
-internal func typedFreeFormReplacement(for type: String) -> String? {
-  return typedFreeFormReplacements[normalizedTypeSpelling(type)]
-}
-
 /// A type spelling with all whitespace removed, so spelling variations of the same type
 /// (`[String: Any]` vs `[String :Any]`) compare equal.
 private func normalizedTypeSpelling(_ type: String) -> String {
   return type.filter { !$0.isWhitespace }
 }
 
+/// How a type that mentions `Any` converts on the JS-value paths. Such a type can't conform to the JS
+/// codable protocols, so it converts through the `JavaScriptValue` free-form methods.
+internal enum FreeFormConversion {
+  /// `Any`, `[Any]` or `[String: Any]`, wrapped in at most one optional: the dedicated methods for
+  /// that shape, named by `decodeMethod` and `encodeMethod`. The optional is handled around them.
+  case shape(decodeMethod: String, encodeMethod: String, isOptional: Bool, isBareAny: Bool)
+  /// Any other type that mentions `Any`: the generic `decodeAny(_:as:in:)` and `encodeAny(_:in:)`.
+  case generic
+
+  /// Classifies a type that mentions `Any`; the caller checks `isConvertibleFreeFormType` first.
+  init(type: TypeSyntax) {
+    let wrapped = optionalWrappedType(type)
+    switch freeFormShape(of: wrapped ?? type) {
+    case .any:
+      self = .shape(
+        decodeMethod: "decodeAny",
+        encodeMethod: "encodeAny",
+        isOptional: wrapped != nil,
+        isBareAny: true
+      )
+    case .array:
+      self = .shape(
+        decodeMethod: "decodeAnyArray",
+        encodeMethod: "encodeAnyArray",
+        isOptional: wrapped != nil,
+        isBareAny: false
+      )
+    case .dictionary:
+      self = .shape(
+        decodeMethod: "decodeAnyDictionary",
+        encodeMethod: "encodeAnyDictionary",
+        isOptional: wrapped != nil,
+        isBareAny: false
+      )
+    case nil:
+      self = .generic
+    }
+  }
+
+  /// True for `Any` itself, optional or not.
+  var isBareAny: Bool {
+    guard case .shape(_, _, _, let isBareAny) = self else {
+      return false
+    }
+    return isBareAny
+  }
+
+  /// The decode expression, as it appears after `try`, for a `@JS` value read from `valueExpression`
+  /// (a `JavaScriptUnownedValue`) into `type` (spelled in expression position). For an optional
+  /// free-form shape, `undefined` and `null` map to `nil` around the dedicated method, just like
+  /// `Optional.decode`. The generic method takes an owning value, so the borrowed one is copied first.
+  func decodeExpression(of valueExpression: String, as type: String) -> String {
+    switch self {
+    case .shape(let decodeMethod, _, let isOptional, _):
+      let call = "JavaScriptValue.\(decodeMethod)(\(valueExpression), in: runtime)"
+      return isOptional ? "\(valueExpression).isUndefined() || \(valueExpression).isNull() ? nil : \(call)" : call
+    case .generic:
+      return "JavaScriptValue.decodeAny(\(valueExpression).copied(in: runtime), as: \(type).self, in: runtime)"
+    }
+  }
+
+  /// The encode expression, as it appears after `try`, for the `@JS` value `valueExpression`. An
+  /// optional free-form shape encodes through the generic `encodeAny(_:in:)`, which encodes `nil` as
+  /// `null` and unwraps any other value, so the expression (which may call a computed getter) is
+  /// evaluated only once.
+  func encodeExpression(of valueExpression: String) -> String {
+    switch self {
+    case .shape(_, let encodeMethod, false, _):
+      return "JavaScriptValue.\(encodeMethod)(\(valueExpression), in: runtime)"
+    case .shape(_, _, true, _), .generic:
+      // The explicit `as Any` keeps an optional value from warning about its implicit coercion.
+      return "JavaScriptValue.encodeAny(\(valueExpression) as Any, in: runtime)"
+    }
+  }
+}
+
+/// The conversion for a boundary type that mentions `Any`, or `nil` when the type doesn't mention
+/// `Any`, or holds it in a shape the free-form methods can't convert (see `isConvertibleFreeFormType`),
+/// which the caller diagnoses.
+internal func freeFormConversion(of type: TypeSyntax) -> FreeFormConversion? {
+  guard mentionsFreeFormAny(type), isConvertibleFreeFormType(type) else {
+    return nil
+  }
+  return FreeFormConversion(type: type)
+}
+
 /// True when a type mentions `Any` anywhere in its spelling, at any nesting depth: `Any`, `[Any]?`,
 /// `[String: Any]`, `Dictionary<String, [Any]>`, `[Int: Any]`, and so on. Such a type can't conform to
 /// the JS codable protocols.

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -31,6 +31,7 @@ public struct JSMacro: PeerMacro {
     providingPeersOf declaration: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
+    diagnoseParameterSpecifiers(in: declaration, in: context)
     diagnoseFreeFormTypes(in: declaration, in: context)
     diagnoseClosureTypes(in: declaration, in: context)
     diagnoseConcurrentOption(of: node, on: declaration, in: context)
@@ -114,98 +115,79 @@ private func insertAsyncFixIt(for funcDecl: FunctionDeclSyntax) -> FixIt {
   )
 }
 
-/// Emits the free-form (`Any` / `[Any]` / `[String: Any]`) diagnostics for a `@JS` declaration.
-///
-/// A free-form type is only supported crossing the boundary as an **argument**, decoded through
-/// `JavaScriptValue.decodeAny…`; there is no free-form encode, so any position that encodes is a hard
-/// error. That means:
-/// - a function/constructor **parameter** typed free-form gets a warning steering to
-///   `JavaScriptValue` (the type-safe alternative), but compiles;
-/// - a function **return** typed free-form is an error (it would need to encode);
-/// - a **property** typed free-form is an error regardless of settability, because its getter always
-///   encodes.
-///
-/// Types are matched by their written spelling on the type node, so the diagnostic points at the
-/// offending type in the user's source.
-private func diagnoseFreeFormTypes(
+/// Reports a function or constructor parameter whose specifier a decoded argument can't honor: an
+/// `inout` parameter expects its writes to reach the caller, and an `isolated` one expects an actor,
+/// while a `@JS` argument is a fresh value decoded from JavaScript. Ownership specifiers (`borrowing`,
+/// `consuming`, `sending`) are fine: the binding passes the decoded value under whichever convention
+/// the parameter asks for. The specifier is left off the decode and the assertion (see
+/// `SpecifiedType`); a parameter reported here is also left out of the assertion.
+private func diagnoseParameterSpecifiers(
   in declaration: some DeclSyntaxProtocol,
   in context: some MacroExpansionContext
 ) {
+  let parameters: FunctionParameterListSyntax
   if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
-    warnFreeFormArguments(funcDecl.signature.parameterClause.parameters, in: context)
-    if let returnType = funcDecl.signature.returnClause?.type,
-      isFreeFormBoundaryType(returnType.trimmedDescription) {
-      context.diagnose(
-        Diagnostic(node: returnType, message: freeFormReturnError(for: returnType.trimmedDescription)))
-    }
-    return
-  }
-
-  // A constructor decodes its arguments exactly like a function; it has no return value to encode, so
-  // only the argument warning applies.
-  if let initDecl = declaration.as(InitializerDeclSyntax.self) {
-    warnFreeFormArguments(initDecl.signature.parameterClause.parameters, in: context)
+    parameters = funcDecl.signature.parameterClause.parameters
+  } else if let initDecl = declaration.as(InitializerDeclSyntax.self) {
+    parameters = initDecl.signature.parameterClause.parameters
+  } else {
     return
   }
-
-  if let varDecl = declaration.as(VariableDeclSyntax.self),
-    let type = varDecl.bindings.first?.typeAnnotation?.type,
-    isFreeFormBoundaryType(type.trimmedDescription) {
-    context.diagnose(
-      Diagnostic(node: type, message: freeFormPropertyError(for: type.trimmedDescription)))
-  }
-}
-
-/// The tail of a free-form encode error: the typed wrapper of the same shape (`JavaScriptArray`,
-/// `JavaScriptObject`) when there is one, otherwise the plain `JavaScriptValue` passthrough suggestion.
-private func suggestedAlternative(for freeFormType: String) -> String {
-  if let reshaped = typedFreeFormReplacement(for: freeFormType), reshaped != "JavaScriptValue" {
-    return "Use '\(reshaped)', or 'JavaScriptValue' to pass a JS value through unchanged."
-  }
-  return "Use a concrete type, or 'JavaScriptValue' to pass a JS value through unchanged."
-}
-
-/// Emits the steering warning for each free-form parameter in a list. Shared by the function and
-/// constructor cases, which both decode their arguments through the same path.
-private func warnFreeFormArguments(
-  _ parameters: FunctionParameterListSyntax,
-  in context: some MacroExpansionContext
-) {
   for parameter in parameters {
-    let type = parameter.type.trimmedDescription
-    guard let suggested = typedFreeFormReplacement(for: type) else {
+    guard let specifier = SpecifiedType(parameter.type).unsupportedSpecifier else {
       continue
     }
     context.diagnose(
       Diagnostic(
         node: parameter.type,
-        message: freeFormArgumentWarning(for: type, suggesting: suggested)))
+        message: JSDiagnosticMessage(
+          "A @JS parameter can't be '\(specifier)': its argument is a value decoded from JavaScript, which can't be written back or carry an isolation.",
+          id: "js-parameter-specifier",
+          severity: .error
+        )))
   }
 }
 
-private func freeFormArgumentWarning(
-  for freeFormType: String,
-  suggesting suggestedType: String
-) -> JSDiagnosticMessage {
-  return JSDiagnosticMessage(
-    "Prefer '\(suggestedType)' over the free-form '\(freeFormType)' for a @JS argument. Free-form decoding boxes every value as 'Any' (slower, no static typing); '\(suggestedType)' keeps the JS value inspectable without converting it.",
-    id: "js-free-form-argument",
-    severity: .warning
-  )
-}
+/// Emits the free-form (`Any`-bearing) diagnostics for a `@JS` declaration.
+///
+/// A type built from `Any`, arrays, `String`-keyed dictionaries and optionals converts through the
+/// `JavaScriptValue` free-form methods in every position (see `FreeFormConversion`). That means:
+/// - a free-form argument, return value or property needs no diagnostic: it decodes through
+///   `decodeAny…` and encodes through `encodeAny…`;
+/// - a type that holds `Any` in any other shape (`[Int: Any]`, `Set<[String: Any]>`) is an error in
+///   every position, since the free-form methods never produce or accept it.
+///
+/// Types are matched on the type node, so the diagnostic points at the offending type in the user's
+/// source. A closure type is left to `diagnoseClosureTypes`.
+private func diagnoseFreeFormTypes(
+  in declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  var types: [TypeSyntax] = []
+  if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
+    types = funcDecl.signature.parameterClause.parameters.map { SpecifiedType($0.type).type }
+    if let returnType = funcDecl.signature.returnClause?.type {
+      types.append(returnType)
+    }
+  } else if let initDecl = declaration.as(InitializerDeclSyntax.self) {
+    // A constructor decodes its arguments exactly like a function and has no return value.
+    types = initDecl.signature.parameterClause.parameters.map { SpecifiedType($0.type).type }
+  } else if let varDecl = declaration.as(VariableDeclSyntax.self),
+    let type = varDecl.bindings.first?.typeAnnotation?.type {
+    types = [type]
+  }
 
-private func freeFormReturnError(for freeFormType: String) -> JSDiagnosticMessage {
-  return JSDiagnosticMessage(
-    "A @JS function can't return the free-form '\(freeFormType)': there's no way to encode an untyped value back to JavaScript. \(suggestedAlternative(for: freeFormType))",
-    id: "js-free-form-return",
-    severity: .error
-  )
+  for type in types
+  where mentionsFreeFormAny(type) && !isConvertibleFreeFormType(type) && !containsFunctionType(type) {
+    context.diagnose(
+      Diagnostic(node: type, message: unconvertibleFreeFormError(for: type.trimmedDescription)))
+  }
 }
 
-private func freeFormPropertyError(for freeFormType: String) -> JSDiagnosticMessage {
+private func unconvertibleFreeFormError(for type: String) -> JSDiagnosticMessage {
   return JSDiagnosticMessage(
-    "A @JS property can't have the free-form '\(freeFormType)': its getter would have to encode an untyped value back to JavaScript, which isn't supported. \(suggestedAlternative(for: freeFormType))",
-    id: "js-free-form-property",
+    "A @JS member can't use the type '\(type)': a type holding 'Any' converts to and from JavaScript only when it's built from 'Any', arrays, String-keyed dictionaries and optionals. Use one of those shapes, such as '[String: Any]', or 'JavaScriptValue' to keep the JavaScript value unconverted.",
+    id: "js-free-form-unsupported",
     severity: .error
   )
 }
@@ -254,9 +236,10 @@ private struct BoundaryMember {
 /// function contributes its parameter types (decodable) and its return type when non-Void (encodable);
 /// a property contributes its value type as encodable (the getter) and also as decodable when settable
 /// (the setter). Composed types (`[Int]`, `String?`, …) are kept verbatim, their conditional
-/// conformances transitively constraining the elements. Returns `nil` for declaration kinds `@JS`
-/// doesn't read types from, or a property whose type isn't spelled out (a syntactic macro can't
-/// recover it).
+/// conformances transitively constraining the elements. A type that mentions `Any` is left out: it
+/// converts through the free-form methods, or is diagnosed by `diagnoseFreeFormTypes`. Returns `nil`
+/// for declaration kinds `@JS` doesn't read types from, a property whose type isn't spelled out (a
+/// syntactic macro can't recover it), or one whose type mentions `Any`.
 private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> BoundaryMember? {
   if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
     // A closure argument moves data the other way: JS receives its parameters and returns its result.
@@ -265,22 +248,32 @@ private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> Boundary
     var decodableTypes: [String] = []
     var callbackArgumentTypes: [String] = []
     for parameter in funcDecl.signature.parameterClause.parameters {
-      guard let closure = JSClosureType(parameter.type) else {
-        if !containsFunctionType(parameter.type) {
-          decodableTypes.append(parameter.type.trimmedDescription)
+      // 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.
+      let specified = SpecifiedType(parameter.type)
+      guard specified.unsupportedSpecifier == nil else {
+        continue
+      }
+      guard let closure = JSClosureType(specified.type) else {
+        if !containsFunctionType(specified.type) && !mentionsFreeFormAny(specified.type) {
+          decodableTypes.append(specified.type.trimmedDescription)
         }
         continue
       }
-      for parameter in closure.parameters where !containsFunctionType(parameter.type) {
+      // A closure type that mentions `Any` is reported by `diagnoseClosureTypes` instead.
+      for parameter in closure.parameters
+      where !containsFunctionType(parameter.type) && !mentionsFreeFormAny(parameter.type) {
         callbackArgumentTypes.append(parameter.type.trimmedDescription)
       }
-      if let returnType = closure.returnType, !containsFunctionType(closure.functionType.returnClause.type) {
+      let closureReturnType = closure.functionType.returnClause.type
+      if let returnType = closure.returnType,
+        !containsFunctionType(closureReturnType) && !mentionsFreeFormAny(closureReturnType) {
         decodableTypes.append(returnType)
       }
     }
     let returnType = funcDecl.signature.returnClause?.type
     let encodableType = returnType.flatMap {
-      isVoidType($0) || containsFunctionType($0) ? nil : $0.trimmedDescription
+      isVoidType($0) || containsFunctionType($0) || mentionsFreeFormAny($0) ? nil : $0.trimmedDescription
     }
     return BoundaryMember(
       name: funcDecl.name.text,
@@ -297,7 +290,11 @@ private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> Boundary
     let type = binding.typeAnnotation?.type,
     !containsFunctionType(type) {
     // A `let`, or a `var` with no setter, is read-only (encodable only). A settable `var` is also
-    // decoded on write, so its value type is asserted in both directions.
+    // decoded on write, so its value type is asserted in both directions. A type that mentions `Any`
+    // converts through the free-form methods instead, so it isn't asserted at all.
+    guard !mentionsFreeFormAny(type) else {
+      return nil
+    }
     let typeText = type.trimmedDescription
     let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
     let isSettable = isVar && bindingIsSettable(binding)