expo-modules-macros 0.19.1 → 0.21.0

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"]

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

@@ -2,6 +2,44 @@
 /// `@Record` type, with the per-member detail a TypeScript type generator needs. Read syntactically
 /// (like the macros): each boundary type becomes a structured `TypeNode` tree so the consumer walks a
 /// tagged tree rather than re-parsing Swift type syntax.
+///
+/// Every declaration and member carries the `platforms` that build it, and the ones that can be
+/// written with an access modifier carry the `accessLevel` they spell. A declaration no platform
+/// builds is not reported.
+
+/// One Apple OS that builds a declaration.
+struct ExportedPlatform: Encodable, Equatable {
+  /// The OS, spelled as `os(...)` spells it: `iOS`, `macOS`, `tvOS`, `watchOS`, or `visionOS`.
+  let name: String
+
+  /// The version spelled in `@available` (`17.0` in `@available(iOS 17.0, *)`), or `nil` when no
+  /// attribute on the declaration or its enclosing types names one. The latest version wins when
+  /// several do.
+  let introduced: String?
+
+  /// How the declaration's own `@available` attributes deprecate it on this OS, or `nil` when they
+  /// don't. Enclosing types are not read: a member of a deprecated type is not itself reported as
+  /// deprecated.
+  var deprecated: ExportedDeprecation? = nil
+}
+
+/// A deprecation from `@available`: `@available(*, deprecated, ...)` on every OS, or
+/// `@available(iOS, deprecated: 16, obsoleted: 18, ...)` on one. Each field is `nil` when not written.
+struct ExportedDeprecation: Encodable, Equatable {
+  /// The version from `deprecated: 16`; `nil` for a bare `deprecated`.
+  var since: String? = nil
+
+  /// The version from `obsoleted: 18`, from which the declaration is no longer available. A
+  /// declaration that is only obsoleted is still reported as deprecated.
+  var obsoleted: String? = nil
+
+  /// The `message:` text.
+  var message: String? = nil
+
+  /// The `renamed:` text: the Swift name of the replacement, as written (`newName`,
+  /// `other(value:)`). It is not resolved to a JS name.
+  var renamed: String? = nil
+}
 
 /// One parameter of a `@JS` function or `@JS init`.
 struct ExportedParameter: Encodable, Equatable {
@@ -11,14 +49,18 @@ struct ExportedParameter: Encodable, Equatable {
   /// The internal parameter name (the `second` name, else the same as `label`): `point` above.
   let name: String
 
-  let type: TypeNode
+  var type: TypeNode
 
   /// True when the caller may omit it: a default value or an optional type. Distinct from the type
   /// being `.optional` (a defaulted non-optional is also omittable). Encoded as `optional`.
   let isOptional: Bool
 
+  /// The default value expression as source text (`1`, `"x"`, `.fast`), or `nil` when none is
+  /// written. Not evaluated: it may be any expression.
+  let defaultValue: String?
+
   private enum CodingKeys: String, CodingKey {
-    case label, name, type
+    case label, name, type, defaultValue
     case isOptional = "optional"
   }
 }
@@ -31,10 +73,10 @@ struct ExportedFunction: Encodable, Equatable {
   /// The JS name it binds under: the `@JS("x")` override, else `name`.
   let jsName: String
 
-  let parameters: [ExportedParameter]
+  var parameters: [ExportedParameter]
 
   /// The return type, or `nil` for `Void`. Named `returns` to pair with `parameters`.
-  let returns: TypeNode?
+  var returns: TypeNode?
 
   /// `async` (an async function is promise-returning in JS).
   let isAsync: Bool
@@ -45,9 +87,14 @@ struct ExportedFunction: Encodable, Equatable {
   /// `static`/`class` member.
   let isStatic: Bool
 
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
+
   /// The flags are encoded under their TS-keyword spellings.
   private enum CodingKeys: String, CodingKey {
-    case name, jsName, parameters, returns
+    case name, jsName, parameters, returns, accessLevel, platforms
     case isAsync = "async"
     case isThrowing = "throws"
     case isStatic = "static"
@@ -64,7 +111,7 @@ struct ExportedProperty: Encodable, Equatable {
 
   /// The value type, or `nil` when undeterminable syntactically (no annotation and no literal
   /// default), the case the macro binds getter-only.
-  let type: TypeNode?
+  var type: TypeNode?
 
   /// True when JS can assign to it: a stored `var` or a computed `var` with a `set`. Encoded as its
   /// inverse, `readonly`.
@@ -73,8 +120,17 @@ struct ExportedProperty: Encodable, Equatable {
   /// `static`/`class` member. Encoded as `static`.
   let isStatic: Bool
 
+  /// The initial value of a stored property as source text, or `nil` when none is written.
+  let defaultValue: String?
+
+  /// The spelled access modifier, or `nil` when none is written. A setter-only modifier like
+  /// `private(set)` is not the property's access level.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
+
   private enum CodingKeys: String, CodingKey {
-    case name, jsName, type
+    case name, jsName, type, defaultValue, accessLevel, platforms
     case isReadonly = "readonly"
     case isStatic = "static"
   }
@@ -86,6 +142,9 @@ struct ExportedProperty: Encodable, Equatable {
     try container.encodeIfPresent(type, forKey: .type)
     try container.encode(!isSettable, forKey: .isReadonly)
     try container.encode(isStatic, forKey: .isStatic)
+    try container.encodeIfPresent(defaultValue, forKey: .defaultValue)
+    try container.encodeIfPresent(accessLevel, forKey: .accessLevel)
+    try container.encode(platforms, forKey: .platforms)
   }
 }
 
@@ -96,23 +155,28 @@ struct ExportedRecordProperty: Encodable, Equatable {
   let name: String
 
   /// `@Record` requires a determinable type on every property, so this is never `nil`.
-  let type: TypeNode
+  var type: TypeNode
 
   /// Optional-typed. Encoded as `optional`.
   let isOptional: Bool
 
-  /// Has a default value. Not encoded (derivable as `!isOptional && !isRequired`, and a Swift default
-  /// never reaches JS); kept only to derive `isRequired`.
-  let hasDefault: Bool
+  /// The default value as source text, or `nil` when none is written. A field JS leaves out takes it.
+  let defaultValue: String?
+
+  /// The spelled access modifier, or `nil` when none is written. Never `private` or `fileprivate`,
+  /// since those exclude a property from the record.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
 
   /// Whether JS must supply this property, matching the macro's `RecordProperty.isRequired`. Encoded
   /// as `required`.
   var isRequired: Bool {
-    return !hasDefault && !isOptional
+    return defaultValue == nil && !isOptional
   }
 
   private enum CodingKeys: String, CodingKey {
-    case name, type
+    case name, type, defaultValue, accessLevel, platforms
     case isOptional = "optional"
     case isRequired = "required"
   }
@@ -123,6 +187,9 @@ struct ExportedRecordProperty: Encodable, Equatable {
     try container.encode(type, forKey: .type)
     try container.encode(isOptional, forKey: .isOptional)
     try container.encode(isRequired, forKey: .isRequired)
+    try container.encodeIfPresent(defaultValue, forKey: .defaultValue)
+    try container.encodeIfPresent(accessLevel, forKey: .accessLevel)
+    try container.encode(platforms, forKey: .platforms)
   }
 }
 
@@ -137,13 +204,18 @@ struct ExportedEvent: Encodable, Equatable {
   let jsName: String
 
   /// The single payload parameter's type, or `nil` for a no-payload `() -> Void` event.
-  let payload: TypeNode?
+  var payload: TypeNode?
 
   /// `@Event(sync: true)`, dispatching inline on the JS thread instead of scheduling.
   let isSync: Bool
 
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
+
   private enum CodingKeys: String, CodingKey {
-    case name, jsName, payload
+    case name, jsName, payload, accessLevel, platforms
     case isSync = "sync"
   }
 
@@ -153,6 +225,8 @@ struct ExportedEvent: Encodable, Equatable {
     try container.encode(jsName, forKey: .jsName)
     try container.encodeIfPresent(payload, forKey: .payload)
     try container.encode(isSync, forKey: .isSync)
+    try container.encodeIfPresent(accessLevel, forKey: .accessLevel)
+    try container.encode(platforms, forKey: .platforms)
   }
 }
 
@@ -165,13 +239,18 @@ struct ExportedModule: Encodable, Equatable {
   /// The JS module name: `@ExpoModule("Foo")` override, else the class name.
   let jsName: String
 
-  let functions: [ExportedFunction]
-  let properties: [ExportedProperty]
-  let events: [ExportedEvent]
+  var functions: [ExportedFunction]
+  var properties: [ExportedProperty]
+  var events: [ExportedEvent]
 
   /// The classes listed in `@ExpoModule(classes: [...])`, in source order. Each is reachable from JS
   /// as a member of the module.
-  let classes: [ExportedClass]
+  var classes: [ExportedClass]
+
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
 
   /// Absolute source path, matching `scan-modules`.
   let file: String
@@ -190,6 +269,16 @@ struct ExportedClass: Encodable, Equatable {
   let jsName: String?
 }
 
+/// The `@JS init` of a shared object: the constructor JS calls with `new`.
+struct ExportedInitializer: Encodable, Equatable {
+  var parameters: [ExportedParameter]
+
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
+}
+
 /// A `@SharedObject` type: a JS class with an optional `@JS init` constructor plus its `@JS` members.
 struct ExportedSharedObject: Encodable, Equatable {
   /// The Swift class name, qualified with the types it is nested in (`Outer.Player`).
@@ -199,12 +288,18 @@ struct ExportedSharedObject: Encodable, Equatable {
   /// types.
   let jsName: String
 
-  /// The `@JS init` parameters, or `nil` when there's none. A shared object has at most one.
-  let constructorParameters: [ExportedParameter]?
+  /// The `@JS init`, or `nil` when there's none. A shared object has at most one; the first is kept
+  /// if a malformed source has more. Not named `constructor`, which every JS object inherits.
+  var initializer: ExportedInitializer?
+
+  var functions: [ExportedFunction]
+  var properties: [ExportedProperty]
+  var events: [ExportedEvent]
 
-  let functions: [ExportedFunction]
-  let properties: [ExportedProperty]
-  let events: [ExportedEvent]
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
 
   let file: String
 }
@@ -215,7 +310,12 @@ struct ExportedRecord: Encodable, Equatable {
   /// (`Outer.Options`).
   let name: String
 
-  let properties: [ExportedRecordProperty]
+  var properties: [ExportedRecordProperty]
+
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
 
   let file: String
 }
@@ -237,14 +337,17 @@ struct ExportedEnumCase: Encodable, Equatable {
   /// above.
   let rawValue: String?
 
+  let platforms: [ExportedPlatform]
+
   private enum CodingKeys: String, CodingKey {
-    case name, rawValue
+    case name, rawValue, platforms
   }
 
   func encode(to encoder: Encoder) throws {
     var container = encoder.container(keyedBy: CodingKeys.self)
     try container.encode(name, forKey: .name)
     try container.encodeIfPresent(rawValue, forKey: .rawValue)
+    try container.encode(platforms, forKey: .platforms)
   }
 }
 
@@ -264,10 +367,15 @@ struct ExportedEnum: Encodable, Equatable {
 
   let cases: [ExportedEnumCase]
 
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
+
   let file: String
 
   private enum CodingKeys: String, CodingKey {
-    case name, rawType, cases, file
+    case name, rawType, cases, accessLevel, platforms, file
   }
 
   func encode(to encoder: Encoder) throws {
@@ -275,6 +383,8 @@ struct ExportedEnum: Encodable, Equatable {
     try container.encode(name, forKey: .name)
     try container.encodeIfPresent(rawType, forKey: .rawType)
     try container.encode(cases, forKey: .cases)
+    try container.encodeIfPresent(accessLevel, forKey: .accessLevel)
+    try container.encode(platforms, forKey: .platforms)
     try container.encode(file, forKey: .file)
   }
 }
@@ -288,10 +398,12 @@ struct ExportedUnionMember: Encodable, Equatable {
 
   /// The associated value's type: what this alternative decodes from. Named `type` like every other
   /// type-valued field here; `payload` already means an event's argument type on `ExportedEvent`.
-  let type: TypeNode
+  var type: TypeNode
+
+  let platforms: [ExportedPlatform]
 
   private enum CodingKeys: String, CodingKey {
-    case name, type
+    case name, type, platforms
   }
 }
 
@@ -307,7 +419,12 @@ struct ExportedUnion: Encodable, Equatable {
   /// name.
   let name: String
 
-  let members: [ExportedUnionMember]
+  var members: [ExportedUnionMember]
+
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
 
   let file: String
 }
@@ -328,8 +445,10 @@ struct ExportedSurface: Encodable, Equatable {
 /// and change for different reasons. Version 2 added `events` to modules and shared objects; version 3
 /// added `enums`; version 4 added `unions`; version 5 resolves refs, adding `refKind` and correcting
 /// an enum ref's `typeof`; version 6 added `classes` to modules; version 7 reports nested types under
-/// qualified names and gives a resolved ref the name of its declaration.
-let scanExportsSchemaVersion = 7
+/// qualified names and gives a resolved ref the name of its declaration; version 8 reports
+/// declarations in `#if` blocks, adds `platforms` (with deprecations), `accessLevel`, and
+/// `defaultValue`, and replaces `constructorParameters` with `initializer`.
+let scanExportsSchemaVersion = 8
 
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).