expo-modules-macros 0.19.1 → 0.20.0

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).

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

@@ -147,61 +147,51 @@ extension ExportedSurface {
     let index = RefIndex(surface: self)
     return ExportedSurface(
       modules: modules.map { module in
-        ExportedModule(
-          name: module.name,
-          jsName: module.jsName,
-          functions: module.functions.map { $0.resolvingRefs(using: index, in: module.name) },
-          properties: module.properties.map { $0.resolvingRefs(using: index, in: module.name) },
-          events: module.events.map { $0.resolvingRefs(using: index, in: module.name) },
-          classes: module.classes.map { exportedClass in
-            guard let entry = index.lookup(exportedClass.name, in: module.name),
-              entry.kind == .sharedObject else {
-              return exportedClass
-            }
-            return ExportedClass(name: entry.name, jsName: entry.jsName)
-          },
-          file: module.file
-        )
+        var resolved = module
+        resolved.functions = module.functions.map { $0.resolvingRefs(using: index, in: module.name) }
+        resolved.properties = module.properties.map { $0.resolvingRefs(using: index, in: module.name) }
+        resolved.events = module.events.map { $0.resolvingRefs(using: index, in: module.name) }
+        resolved.classes = module.classes.map { exportedClass in
+          guard let entry = index.lookup(exportedClass.name, in: module.name),
+            entry.kind == .sharedObject else {
+            return exportedClass
+          }
+          return ExportedClass(name: entry.name, jsName: entry.jsName)
+        }
+        return resolved
       },
       sharedObjects: sharedObjects.map { sharedObject in
-        ExportedSharedObject(
-          name: sharedObject.name,
-          jsName: sharedObject.jsName,
-          constructorParameters: sharedObject.constructorParameters?.map {
+        var resolved = sharedObject
+        if let initializer = sharedObject.initializer {
+          resolved.initializer?.parameters = initializer.parameters.map {
             $0.resolvingRefs(using: index, in: sharedObject.name)
-          },
-          functions: sharedObject.functions.map { $0.resolvingRefs(using: index, in: sharedObject.name) },
-          properties: sharedObject.properties.map { $0.resolvingRefs(using: index, in: sharedObject.name) },
-          events: sharedObject.events.map { $0.resolvingRefs(using: index, in: sharedObject.name) },
-          file: sharedObject.file
-        )
+          }
+        }
+        resolved.functions = sharedObject.functions.map { $0.resolvingRefs(using: index, in: sharedObject.name) }
+        resolved.properties = sharedObject.properties.map { $0.resolvingRefs(using: index, in: sharedObject.name) }
+        resolved.events = sharedObject.events.map { $0.resolvingRefs(using: index, in: sharedObject.name) }
+        return resolved
       },
       records: records.map { record in
-        ExportedRecord(
-          name: record.name,
-          properties: record.properties.map { property in
-            ExportedRecordProperty(
-              name: property.name,
-              type: property.type.resolvingRefs(using: index, in: record.name),
-              isOptional: property.isOptional,
-              hasDefault: property.hasDefault
-            )
-          },
-          file: record.file
-        )
+        var resolved = record
+        resolved.properties = record.properties.map { property in
+          var resolvedProperty = property
+          resolvedProperty.type = property.type.resolvingRefs(using: index, in: record.name)
+          return resolvedProperty
+        }
+        return resolved
       },
       // An enum's raw type is a primitive or an unscanned spelling, never a ref to another scanned
       // type, so there is nothing in one to resolve.
       enums: enums,
       unions: unions.map { union in
-        ExportedUnion(
-          name: union.name,
-          members: union.members.map { member in
-            ExportedUnionMember(
-              name: member.name, type: member.type.resolvingRefs(using: index, in: union.name))
-          },
-          file: union.file
-        )
+        var resolved = union
+        resolved.members = union.members.map { member in
+          var resolvedMember = member
+          resolvedMember.type = member.type.resolvingRefs(using: index, in: union.name)
+          return resolvedMember
+        }
+        return resolved
       }
     )
   }
@@ -209,40 +199,33 @@ extension ExportedSurface {
 
 extension ExportedParameter {
   fileprivate func resolvingRefs(using index: RefIndex, in scope: String) -> ExportedParameter {
-    return ExportedParameter(
-      label: label, name: name, type: type.resolvingRefs(using: index, in: scope), isOptional: isOptional)
+    var resolved = self
+    resolved.type = type.resolvingRefs(using: index, in: scope)
+    return resolved
   }
 }
 
 extension ExportedFunction {
   fileprivate func resolvingRefs(using index: RefIndex, in scope: String) -> ExportedFunction {
-    return ExportedFunction(
-      name: name,
-      jsName: jsName,
-      parameters: parameters.map { $0.resolvingRefs(using: index, in: scope) },
-      returns: returns?.resolvingRefs(using: index, in: scope),
-      isAsync: isAsync,
-      isThrowing: isThrowing,
-      isStatic: isStatic
-    )
+    var resolved = self
+    resolved.parameters = parameters.map { $0.resolvingRefs(using: index, in: scope) }
+    resolved.returns = returns?.resolvingRefs(using: index, in: scope)
+    return resolved
   }
 }
 
 extension ExportedProperty {
   fileprivate func resolvingRefs(using index: RefIndex, in scope: String) -> ExportedProperty {
-    return ExportedProperty(
-      name: name,
-      jsName: jsName,
-      type: type?.resolvingRefs(using: index, in: scope),
-      isSettable: isSettable,
-      isStatic: isStatic
-    )
+    var resolved = self
+    resolved.type = type?.resolvingRefs(using: index, in: scope)
+    return resolved
   }
 }
 
 extension ExportedEvent {
   fileprivate func resolvingRefs(using index: RefIndex, in scope: String) -> ExportedEvent {
-    return ExportedEvent(
-      name: name, jsName: jsName, payload: payload?.resolvingRefs(using: index, in: scope), isSync: isSync)
+    var resolved = self
+    resolved.payload = payload?.resolvingRefs(using: index, in: scope)
+    return resolved
   }
 }

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

@@ -46,7 +46,7 @@ func scanExports(paths: [String]) -> ScanExportsResult {
     conformances: [enumerableConformanceName]
   ) { source, file in
     let tree = Parser.parse(source: source)
-    let visitor = SurfaceVisitor(file: file)
+    let visitor = SurfaceVisitor(file: file, tree: tree)
     visitor.walk(tree)
     modules.append(contentsOf: visitor.modules)
     sharedObjects.append(contentsOf: visitor.sharedObjects)