expo-modules-macros 0.19.1 → 0.20.0

package/README.md

@@ -81,11 +81,11 @@ Node consumers can call the scanner through this package instead of locating the
 ```ts
 import { scanModules, scanExports } from 'expo-modules-macros';
 
-const { modules, warnings } = await scanModules(['ios/'], { defines: ['DEBUG'] });
+const { modules, warnings } = await scanModules(['ios/'], { defines: ['DEBUG'], timeout: 30_000 });
 const { exports } = await scanExports(['ios/']);
 ```
 
-The binary is a compiled executable, so each call still spawns a process. What the wrapper owns is the part consumers would otherwise duplicate: resolving the shipped binary, building the arguments, parsing the JSON, checking `schemaVersion`, and turning a non-zero exit into a `ScannerError`. The result types are hand-written mirrors of the Swift `Codable` types, which is what the version check guards against drifting.
+The binary is a compiled executable, so each call still spawns a process. What the wrapper owns is the part consumers would otherwise duplicate: resolving the shipped binary, building the arguments, parsing the JSON, checking `schemaVersion`, and turning a non-zero exit or an exceeded `timeout` into a `ScannerError`. The result types are hand-written mirrors of the Swift `Codable` types, which is what the version check guards against drifting.
 
 # How the plugin reaches the compiler
 

package/apple/Sources/ExpoModulesMacros/ClosureArguments.swift

@@ -344,7 +344,7 @@ internal func containsFunctionType(_ type: TypeSyntax) -> Bool {
 }
 
 /// The first function type in `type` or anywhere inside it, in source order.
-private func firstFunctionType(in type: some SyntaxProtocol) -> FunctionTypeSyntax? {
+internal func firstFunctionType(in type: some SyntaxProtocol) -> FunctionTypeSyntax? {
   if let functionType = type.as(FunctionTypeSyntax.self) {
     return functionType
   }

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -206,8 +206,8 @@ internal struct JSFunction {
   }
 
   /// The flat (single-arity) call-and-encode lines used when no trailing parameter is omittable:
-  /// `let result = <callee>.f(...)` then the return encode (or the no-return `<callee>.f(...)` +
-  /// `.undefined()`).
+  /// `let result = <callee>.f(...)` then the return encode (or just `<callee>.f(...)` for a function
+  /// that returns nothing).
   private func callAndEncodeLines(receiver: Receiver, arity: Int, decodingFrom: Int) -> [String] {
     var lines: [String] = []
     for index in decodingFrom..<arity {
@@ -218,7 +218,6 @@ internal struct JSFunction {
       lines.append(contentsOf: encodeResultLines())
     } else {
       lines.append(callExpression(receiver: receiver, arity: arity))
-      lines.append("return .undefined()")
     }
     return lines
   }
@@ -229,7 +228,8 @@ internal struct JSFunction {
   /// `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.
+  /// no-return function has nothing to encode: its binding closure returns `Void` (see
+  /// `decorateStatements(object:receiver:)`).
   ///
   /// For an `async` function the encode must run on the JS thread. An `async` body may suspend and
   /// resume on an arbitrary cooperative-pool thread, and encoding a heap-allocated JS value (a string,
@@ -239,7 +239,7 @@ internal struct JSFunction {
   /// which always run on the JS thread — keep encoding directly without the wrapper.
   private func encodeResultLines() -> [String] {
     guard let returnType else {
-      return ["return .undefined()"]
+      return []
     }
     let encode = "try \(encodeCall(returnType, freeForm: returnFreeForm, of: "result"))"
     if isAsync {
@@ -272,11 +272,16 @@ internal struct JSFunction {
     // a shorthand `{ [capture] name, name in }` parameter; for a sync binding the explicit
     // `JavaScriptUnownedValue` also selects the (otherwise `@_disfavoredOverload`) unowned-`this`
     // overload.
+    // A sync function that returns nothing binds through the `Void` overload, which leaves JS's
+    // result as `undefined` without building and writing a value. The closure declares `-> Void`
+    // because a body of several statements without a `return` is otherwise ambiguous between the
+    // two unowned-`this` overloads.
     let captures = receiver.captureClause
     let parameters = "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
+    let returnClause = returnType == nil && !isAsync ? " -> Void" : ""
 
     return """
-        \(object).setProperty("\(jsName)") { \(captures)\(parameters) in
+        \(object).setProperty("\(jsName)") { \(captures)\(parameters)\(returnClause) in
       \(bodyStatements(receiver: receiver, indent: "    "))
         }
       """
@@ -348,7 +353,7 @@ internal struct JSProperty {
       let setDecode = "\(callee).\(swiftName) = try \(decode)"
       lines.append(
         accessorClosure(
-          descriptorName, "set", receiver: receiver, body: "\(unwrap)\(setDecode)\nreturn .undefined()"))
+          descriptorName, "set", receiver: receiver, returnsVoid: true, body: "\(unwrap)\(setDecode)"))
     }
 
     lines.append("\(object).defineProperty(\"\(jsName)\", descriptor: \(descriptorName))")
@@ -361,8 +366,10 @@ internal struct JSProperty {
 
   /// One `descriptor.setProperty("get"/"set") { … }` accessor entry. The capture list follows the
   /// receiver: a module captures `self` strong; a shared object captures nothing of the instance.
+  /// A setter passes `returnsVoid`, so its closure declares `-> Void` and binds through the `Void`
+  /// overload, like a function that returns nothing.
   private func accessorClosure(
-    _ descriptorName: String, _ key: String, receiver: Receiver, body: String
+    _ descriptorName: String, _ key: String, receiver: Receiver, returnsVoid: Bool = false, body: String
   ) -> String {
     let captures = receiver.captureClause
     // Indent each line of a (possibly multi-line) body to sit one level inside the closure; a bare
@@ -377,8 +384,9 @@ internal struct JSProperty {
     // `borrowing JavaScriptUnownedValue` selects the unowned-`this` overload. A module ignores `this`;
     // a shared object unwraps it in the body.
     let parameters = "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
+    let returnClause = returnsVoid ? " -> Void" : ""
     return """
-      \(descriptorName).setProperty("\(key)") { \(captures)\(parameters) in
+      \(descriptorName).setProperty("\(key)") { \(captures)\(parameters)\(returnClause) in
       \(indentedBody)
       }
       """
@@ -445,7 +453,7 @@ internal func buildDecorateSharedObjectPhase(
 }
 
 /// True when a return clause is absent or written as `Void` / `()` — i.e. the function returns
-/// nothing JS-visible, so the binding returns `.undefined()`.
+/// nothing JS-visible, so the binding closure returns `Void`.
 private func isVoidType(_ type: TypeSyntax?) -> Bool {
   guard let type else {
     return true

package/apple/Sources/ExpoModulesMacros/EventMacro.swift

@@ -122,7 +122,7 @@ private struct EventMember {
 /// 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.
+/// function type returning `Void` with at most one payload parameter, which holds no closure.
 private func validatedEvent(
   of node: AttributeSyntax,
   on declaration: some DeclSyntaxProtocol
@@ -169,6 +169,17 @@ private func validatedEvent(
     throw MacroExpansionErrorMessage(
       "@Event function type takes at most one payload parameter; combine multiple values into a single record")
   }
+  // The payload is encoded to JavaScript, and a native closure can't be encoded.
+  if let payloadClosure = functionType.parameters.first.flatMap({ firstFunctionType(in: $0.type) }) {
+    throw DiagnosticsError(diagnostics: [
+      Diagnostic(
+        node: payloadClosure,
+        message: EventDiagnosticMessage(
+          "@Event payload can't hold a closure: the payload is encoded to JavaScript, and a native closure can't be encoded.",
+          id: "event-closure-payload"
+        ))
+    ])
+  }
 
   let swiftName = identifier.identifier.text
   return EventMember(

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -1,3 +1,4 @@
+import SwiftDiagnostics
 import SwiftSyntax
 import SwiftSyntaxBuilder
 import SwiftSyntaxMacros
@@ -226,8 +227,21 @@ private func recordProperties(
           "@Record properties must declare an explicit type — '\(ident.identifier.text)' has none"
         )
       }
-      // A literal-inferred type never mentions `Any`, so only an explicit annotation can be free-form.
+      // A literal-inferred type never mentions `Any` or a closure, so only an explicit annotation can.
       let annotatedType = binding.typeAnnotation?.type
+      // A closure has no `decode`, `encode` or dynamic type, and the record converts every property both
+      // ways. A JavaScript function decodes into a native closure only as a `@JS` argument; a native
+      // closure can't be encoded.
+      if let functionType = annotatedType.flatMap(firstFunctionType(in:)) {
+        throw DiagnosticsError(diagnostics: [
+          Diagnostic(
+            node: functionType,
+            message: RecordDiagnosticMessage(
+              "@Record property '\(ident.identifier.text)' can't hold a closure: a record property is also encoded to JavaScript, and a native closure can't be encoded",
+              id: "record-closure-property"
+            ))
+        ])
+      }
       let freeForm = try annotatedType.flatMap { annotatedType -> FreeFormConversion? in
         guard mentionsFreeFormAny(annotatedType) else {
           return nil
@@ -545,3 +559,14 @@ private func classHasInheritance(_ declaration: some DeclGroupSyntax) -> Bool {
   }
   return true
 }
+
+private struct RecordDiagnosticMessage: 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)
+  }
+}

package/apple/Sources/ExpoModulesMacros/UnionMacro.swift

@@ -141,7 +141,8 @@ private struct UnionCase {
 
 /// Reads and validates the union off the attached declaration. Every check is a compile error located
 /// on the offending node: the macro must be on a non-generic `enum` with at least one case, and every
-/// case must carry exactly one associated value, its payload type distinct from every earlier case's.
+/// case must carry exactly one associated value that holds no closure, its payload type distinct from
+/// every earlier case's.
 private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> UnionType {
   guard let enumDecl = declaration.as(EnumDeclSyntax.self) else {
     throw MacroExpansionErrorMessage("@Union can only be applied to an enum")
@@ -197,6 +198,18 @@ private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> Unio
         continue
       }
 
+      // A payload is decoded from and encoded to JavaScript, and a native closure can't be encoded.
+      if let payloadClosure = firstFunctionType(in: parameter.type) {
+        diagnostics.append(
+          Diagnostic(
+            node: payloadClosure,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' can't carry a closure: the payload is also encoded to JavaScript, and a native closure can't be encoded.",
+              id: "union-closure-payload"
+            )))
+        continue
+      }
+
       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

package/apple/Sources/ExpoModulesScanner/Exports/Availability.swift

@@ -0,0 +1,259 @@
+import SwiftIfConfig
+import SwiftSyntax
+
+/// The Apple OSes `scan-exports` attributes declarations to, in the order they are reported. Spelled
+/// as `os(...)` spells them.
+let applePlatforms = ["iOS", "macOS", "tvOS", "watchOS", "visionOS"]
+
+/// The platform names `@available` accepts for each reported OS, including the legacy `OSX`. Other
+/// names (`iOSApplicationExtension`, `macCatalyst`, `swift`, …) do not change where a declaration is
+/// built for an app, so they are ignored.
+private let availabilityPlatformNames: [String: String] = [
+  "iOS": "iOS",
+  "macOS": "macOS",
+  "OSX": "macOS",
+  "tvOS": "tvOS",
+  "watchOS": "watchOS",
+  "visionOS": "visionOS",
+]
+
+/// Answers which platforms build a declaration in one file: those whose `#if` evaluation keeps it,
+/// less those an `@available` attribute on it or on an enclosing type makes unavailable. The `#if`
+/// regions are evaluated once per platform for the whole file. Each platform also carries the
+/// deprecation the declaration's own `@available` attributes give it there.
+///
+/// A condition the scan cannot answer (`#if DEBUG`, `targetEnvironment`, a non-SDK `canImport`)
+/// makes its region inactive on every platform, so a declaration under one is built nowhere.
+struct PlatformResolver {
+  private let regions: [(platform: String, regions: ConfiguredRegions)]
+
+  init(tree: SourceFileSyntax) {
+    regions = applePlatforms.map { platform in
+      (platform, tree.configuredRegions(in: ScanBuildConfiguration(platform: platform, defines: [])))
+    }
+  }
+
+  /// The platforms that build `node`, in `applePlatforms` order. Empty when none does.
+  func platforms(of node: some SyntaxProtocol) -> [ExportedPlatform] {
+    let availability = Availability(of: node)
+    return regions.compactMap { platform, regions in
+      guard regions.isActive(node) == .active, !availability.isUnavailable(on: platform) else {
+        return nil
+      }
+      return ExportedPlatform(
+        name: platform,
+        introduced: availability.introduced[platform],
+        deprecated: availability.deprecation(on: platform)
+      )
+    }
+  }
+}
+
+/// What the `@available` attributes on a declaration and its enclosing declarations say. A member
+/// cannot be more available than the type it is declared in, so the attributes combine: a platform
+/// any of them makes unavailable is unavailable, and the latest introduced version wins.
+/// Deprecations are read from the declaration's own attributes only.
+private struct Availability {
+  private var unavailable: Set<String> = []
+  private var isUnavailableEverywhere = false
+  private(set) var introduced: [String: String] = [:]
+  /// The deprecation from `@available(*, deprecated, ...)`, which applies on every platform.
+  private var deprecatedEverywhere: ExportedDeprecation?
+  /// The deprecations from attributes that name a platform.
+  private var deprecated: [String: ExportedDeprecation] = [:]
+
+  init(of node: some SyntaxProtocol) {
+    var current: Syntax? = Syntax(node)
+    var isOwn = true
+    while let decl = current {
+      if let attributes = decl.asProtocol(WithAttributesSyntax.self)?.attributes {
+        for element in attributes {
+          if let attribute = element.as(AttributeSyntax.self),
+            attribute.attributeName.trimmedDescription == "available",
+            case .availability(let arguments) = attribute.arguments {
+            read(arguments, readsDeprecation: isOwn)
+          }
+        }
+      }
+      isOwn = false
+      current = decl.parent
+    }
+  }
+
+  func isUnavailable(on platform: String) -> Bool {
+    return isUnavailableEverywhere || unavailable.contains(platform)
+  }
+
+  /// The deprecation on `platform`: the platform's own, with any field it leaves out taken from the
+  /// `*` one.
+  func deprecation(on platform: String) -> ExportedDeprecation? {
+    switch (deprecated[platform], deprecatedEverywhere) {
+    case (nil, let everywhere):
+      return everywhere
+    case (let own?, nil):
+      return own
+    case (let own?, let everywhere?):
+      return own.filling(from: everywhere)
+    }
+  }
+
+  /// Reads one attribute. The long form names one platform (or `*`) first and then what applies to
+  /// it: `@available(iOS, introduced: 16)`, `@available(tvOS, unavailable)`,
+  /// `@available(*, deprecated, renamed: "other")`. The shorthand lists platforms with versions:
+  /// `@available(iOS 17, macOS 14, *)`.
+  ///
+  /// A long-form attribute deprecates its platform when it writes `deprecated` (bare or with a
+  /// version) or `obsoleted:`. `message:` and `renamed:` describe that deprecation, and are ignored
+  /// when the attribute deprecates nothing.
+  private mutating func read(_ arguments: AvailabilityArgumentListSyntax, readsDeprecation: Bool) {
+    guard case .token(let first) = arguments.first?.argument else {
+      for argument in arguments {
+        if case .availabilityVersionRestriction(let restriction) = argument.argument,
+          let platform = availabilityPlatformNames[restriction.platform.text],
+          let version = restriction.version {
+          raiseIntroduced(on: platform, to: version.trimmedDescription)
+        }
+      }
+      return
+    }
+    let isWildcard = first.tokenKind == .binaryOperator("*")
+    let platform = availabilityPlatformNames[first.text]
+    guard isWildcard || platform != nil else {
+      return
+    }
+    var deprecation = ExportedDeprecation()
+    var isDeprecated = false
+    for argument in arguments.dropFirst() {
+      switch argument.argument {
+      case .token(let token) where token.text == "unavailable":
+        if let platform {
+          unavailable.insert(platform)
+        } else {
+          isUnavailableEverywhere = true
+        }
+      case .token(let token) where token.text == "deprecated":
+        isDeprecated = true
+      case .availabilityLabeledArgument(let labeled):
+        switch (labeled.label.text, labeled.value) {
+        case ("introduced", .version(let version)):
+          if let platform {
+            raiseIntroduced(on: platform, to: version.trimmedDescription)
+          }
+        case ("deprecated", .version(let version)):
+          isDeprecated = true
+          deprecation.since = version.trimmedDescription
+        case ("obsoleted", .version(let version)):
+          isDeprecated = true
+          deprecation.obsoleted = version.trimmedDescription
+        case ("message", .string(let literal)):
+          deprecation.message = decodedText(of: literal)
+        case ("renamed", .string(let literal)):
+          deprecation.renamed = decodedText(of: literal)
+        default:
+          continue
+        }
+      default:
+        continue
+      }
+    }
+    guard readsDeprecation, isDeprecated else {
+      return
+    }
+    if let platform {
+      deprecated[platform] = deprecated[platform].map { deprecation.filling(from: $0) } ?? deprecation
+    } else {
+      deprecatedEverywhere = deprecatedEverywhere.map { deprecation.filling(from: $0) } ?? deprecation
+    }
+  }
+
+  private mutating func raiseIntroduced(on platform: String, to version: String) {
+    if let current = introduced[platform], !isVersion(version, laterThan: current) {
+      return
+    }
+    introduced[platform] = version
+  }
+}
+
+extension ExportedDeprecation {
+  /// This deprecation with each field it leaves out taken from `other`.
+  fileprivate func filling(from other: ExportedDeprecation) -> ExportedDeprecation {
+    return ExportedDeprecation(
+      since: since ?? other.since,
+      obsoleted: obsoleted ?? other.obsoleted,
+      message: message ?? other.message,
+      renamed: renamed ?? other.renamed
+    )
+  }
+}
+
+/// The value of a string literal in an attribute, with its escape sequences decoded: `\"` reads as
+/// `"`, `\n` as a line break, and `\u{2192}` as `→`. An escaped line break in a multi-line literal
+/// joins the lines, as in Swift. An escape that isn't valid is kept as written.
+private func decodedText(of literal: SimpleStringLiteralExprSyntax) -> String {
+  let text = literal.segments.map(\.content.text).joined()
+  var result = ""
+  var index = text.startIndex
+  while index < text.endIndex {
+    let character = text[index]
+    index = text.index(after: index)
+    guard character == "\\", index < text.endIndex else {
+      result.append(character)
+      continue
+    }
+    let escaped = text[index]
+    index = text.index(after: index)
+    switch escaped {
+    case "0":
+      result.append("\0")
+    case "n":
+      result.append("\n")
+    case "r":
+      result.append("\r")
+    case "t":
+      result.append("\t")
+    case "\"", "'", "\\":
+      result.append(escaped)
+    case "\n", "\r\n":
+      continue
+    case "u":
+      if text[index...].hasPrefix("{"), let close = text[index...].firstIndex(of: "}"),
+        let scalarValue = UInt32(text[text.index(after: index)..<close], radix: 16),
+        let scalar = Unicode.Scalar(scalarValue) {
+        result.unicodeScalars.append(scalar)
+        index = text.index(after: close)
+      } else {
+        result.append("\\u")
+      }
+    default:
+      result.append("\\")
+      result.append(escaped)
+    }
+  }
+  return result
+}
+
+/// Compares two dotted version spellings component by component, treating a missing component as
+/// `0`, so `17` and `17.0` are equal.
+private func isVersion(_ lhs: String, laterThan rhs: String) -> Bool {
+  let left = lhs.split(separator: ".").map { Int($0) ?? 0 }
+  let right = rhs.split(separator: ".").map { Int($0) ?? 0 }
+  for index in 0..<max(left.count, right.count) {
+    let l = index < left.count ? left[index] : 0
+    let r = index < right.count ? right[index] : 0
+    if l != r {
+      return l > r
+    }
+  }
+  return false
+}
+
+/// The spelled access modifier of a declaration (`open`, `public`, `package`, `internal`,
+/// `fileprivate`, `private`), or `nil` when none is written. A modifier with a detail, like the
+/// `private` in `private(set)`, limits only the setter, so it is not the declaration's.
+func spelledAccessLevel(of modifiers: DeclModifierListSyntax) -> String? {
+  return modifiers.first { modifier in
+    modifier.detail == nil && accessModifierNames.contains(modifier.name.text)
+  }?.name.text
+}
+
+private let accessModifierNames: Set<String> = ["open", "public", "package", "internal", "fileprivate", "private"]