@expo/expo-modules-macros-plugin 0.10.0 → 0.12.0

package/apple/Sources/ExpoModulesScanner/Core/SourceScan.swift

@@ -2,14 +2,17 @@ import Foundation
 import SwiftParser
 import SwiftSyntax
 
-/// Walks `paths`, and for each `.swift` file that might contain one of `macros` (the pre-filter passes
-/// it), reads the source and hands it to `process` along with the file path. Returns the run's stats.
+/// Walks `paths`, and for each `.swift` file that might contain one of `macros` or one of
+/// `conformances` (the pre-filter passes it), reads the source and hands it to `process` along with the
+/// file path. Returns the run's stats.
+///
 /// The shared core every scan command builds on: the walk, read, pre-filter, and stats are identical;
 /// only what each command does per parsed file differs (`scan-modules` collects `Detection`s,
 /// `scan-exports` walks a `SurfaceVisitor`), and that lives in `process`.
 func scanFiles(
   paths: [String],
   macros: Set<DetectedMacro>,
+  conformances: Set<String> = [],
   process: (_ source: String, _ file: String) -> Void
 ) -> ScanStats {
   let clock = ContinuousClock()
@@ -19,7 +22,7 @@ func scanFiles(
   var filesParsed = 0
 
   // Compile the pre-filter regex once per run, not once per file.
-  let prefilter = macroAttributeRegex(for: macros)
+  let prefilter = macroAttributeRegex(for: macros, conformances: conformances)
 
   for file in swiftFiles(in: paths) {
     guard let source = try? String(contentsOfFile: file, encoding: .utf8) else {
@@ -50,7 +53,7 @@ func scanFiles(
 func collectDetections(
   paths: [String],
   macros: Set<DetectedMacro>,
-  configuration: ScanBuildConfiguration = .init(platform: nil, defines: [])
+  configuration: ScanBuildConfiguration? = nil
 ) -> (detections: [Detection], warnings: [ScanWarning], stats: ScanStats) {
   var detections: [Detection] = []
   var warnings: [ScanWarning] = []
@@ -68,7 +71,7 @@ func detect(
   source: String,
   file: String,
   macros: Set<DetectedMacro>,
-  configuration: ScanBuildConfiguration
+  configuration: ScanBuildConfiguration?
 ) -> (detections: [Detection], warnings: [ScanWarning]) {
   let tree = Parser.parse(source: source)
   let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: macros, configuration: configuration)
@@ -82,10 +85,23 @@ func detect(
 /// `@(ExpoModule|JS|Record|SharedObject)` for an `exports` scan. A precompiled `NSRegularExpression`
 /// benchmarked ~20x faster over a large source tree than calling `String.contains` once per macro
 /// name, because it scans each file in a single pass. Compiled once per run and reused per file.
-func macroAttributeRegex(for macros: Set<DetectedMacro>) -> NSRegularExpression {
+///
+/// `conformances` adds bare (unprefixed) alternatives for types recognized by conformance rather than
+/// by an attribute (`Enumerable` for `scan-exports`). They join the same alternation so the scan stays
+/// one pass; a bare name matches more loosely than an `@`-prefixed one, which costs a wasted parse and
+/// never a miss.
+func macroAttributeRegex(
+  for macros: Set<DetectedMacro>,
+  conformances: Set<String> = []
+) -> NSRegularExpression {
   // Sort for a stable pattern regardless of the set's iteration order.
-  let alternation = macros.map(\.rawValue).sorted().joined(separator: "|")
-  return try! NSRegularExpression(pattern: "@(\(alternation))")
+  let attributes = macros.map(\.rawValue).sorted().joined(separator: "|")
+  var alternatives: [String] = []
+  if !attributes.isEmpty {
+    alternatives.append("@(\(attributes))")
+  }
+  alternatives.append(contentsOf: conformances.sorted())
+  return try! NSRegularExpression(pattern: alternatives.joined(separator: "|"))
 }
 
 /// True if the source text contains one of the pre-filter's spelled macro attributes, so it's worth

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

@@ -128,6 +128,36 @@ struct ExportedRecordProperty: Encodable, Equatable {
   }
 }
 
+/// One `@Event var` on a module or shared object: a typed event JS listens for with
+/// `addListener(jsName, …)` rather than calls.
+struct ExportedEvent: Encodable, Equatable {
+  /// The Swift property name, e.g. `onStatusChange`.
+  let name: String
+
+  /// The name JS listens under: the `@Event("x")` override, else `name` with a conventional `on`
+  /// prefix stripped and decapitalized (`onStatusChange` -> `statusChange`).
+  let jsName: String
+
+  /// The single payload parameter's type, or `nil` for a no-payload `() -> Void` event.
+  let payload: TypeNode?
+
+  /// `@Event(sync: true)`, dispatching inline on the JS thread instead of scheduling.
+  let isSync: Bool
+
+  private enum CodingKeys: String, CodingKey {
+    case name, jsName, payload
+    case isSync = "sync"
+  }
+
+  func encode(to encoder: Encoder) throws {
+    var container = encoder.container(keyedBy: CodingKeys.self)
+    try container.encode(name, forKey: .name)
+    try container.encode(jsName, forKey: .jsName)
+    try container.encodeIfPresent(payload, forKey: .payload)
+    try container.encode(isSync, forKey: .isSync)
+  }
+}
+
 /// A `@ExpoModule` type and its `@JS` surface.
 struct ExportedModule: Encodable, Equatable {
   /// The Swift class name.
@@ -138,6 +168,7 @@ struct ExportedModule: Encodable, Equatable {
 
   let functions: [ExportedFunction]
   let properties: [ExportedProperty]
+  let events: [ExportedEvent]
 
   /// Absolute source path, matching `scan-modules`.
   let file: String
@@ -156,6 +187,7 @@ struct ExportedSharedObject: Encodable, Equatable {
 
   let functions: [ExportedFunction]
   let properties: [ExportedProperty]
+  let events: [ExportedEvent]
 
   let file: String
 }
@@ -170,17 +202,118 @@ struct ExportedRecord: Encodable, Equatable {
   let file: String
 }
 
+/// One case of a reported enum.
+///
+/// What `rawValue` carries depends on the enum's raw type, and a consumer reads it that way:
+/// - `String`: always present, and **decoded** (`case active = "act"` reports `act`, unquoted). A case
+///   writing none takes its own name, so nothing is left to derive.
+/// - an integer type: present only where written, as **source text** (`1`, `1 << 3`), since the value
+///   may be an expression a syntactic scan can't evaluate. Swift also continues from the preceding
+///   case's value (`case a = 1; case b` makes `b` 2), and that carry is the consumer's to apply.
+/// - no raw type: always absent, since the enum has no raw values.
+struct ExportedEnumCase: Encodable, Equatable {
+  /// The case name as declared.
+  let name: String
+
+  /// The raw value, decoded for a string and verbatim source text otherwise, or `nil` per the rule
+  /// above.
+  let rawValue: String?
+
+  private enum CodingKeys: String, CodingKey {
+    case name, rawValue
+  }
+
+  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)
+  }
+}
+
+/// An `Enumerable` enum: a type that crosses the boundary as its raw value rather than as an object.
+/// Detected by conformance, not by a macro attribute, because core converts it through its
+/// `RawRepresentable`/`Enumerable` conformance (`Coding/…+Enumerable`) with no macro involved.
+struct ExportedEnum: Encodable, Equatable {
+  /// The Swift enum name. No `jsName`: an enum carries no macro to spell an override on, and it
+  /// reaches JS as its raw values, not under a bound name.
+  let name: String
+
+  /// The raw value type as written (`String`, `Int`, …), or `nil` for a bare `Enumerable` conformance
+  /// with no raw type. A `nil` raw type is reported as-is rather than dropped: the enum is still
+  /// declared convertible, and the consumer decides how to treat it.
+  let rawType: TypeNode?
+
+  let cases: [ExportedEnumCase]
+
+  let file: String
+
+  private enum CodingKeys: String, CodingKey {
+    case name, rawType, cases, file
+  }
+
+  func encode(to encoder: Encoder) throws {
+    var container = encoder.container(keyedBy: CodingKeys.self)
+    try container.encode(name, forKey: .name)
+    try container.encodeIfPresent(rawType, forKey: .rawType)
+    try container.encode(cases, forKey: .cases)
+    try container.encode(file, forKey: .file)
+  }
+}
+
+/// One alternative a `@Union` may hold: the Swift case name plus its payload type. Not a member in the
+/// sense a module or shared object has members (functions, properties, events).
+struct ExportedUnionMember: Encodable, Equatable {
+  /// The case name as declared. Swift-side only: discrimination is structural, so it never reaches JS,
+  /// but it ties an alternative back to the declaration.
+  let name: String
+
+  /// 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
+
+  private enum CodingKeys: String, CodingKey {
+    case name, type
+  }
+}
+
+/// A `@Union` enum: a typed union of its cases' payload types (`A | B | C` in TypeScript).
+///
+/// **`members` is ordered, and the order is part of the contract.** Decode tries each payload in
+/// declaration order and takes the first that succeeds, so where two shapes overlap (`Int` and
+/// `Double`, two compatible records) the earlier case wins. Reordering them describes a different
+/// union than the one the module runs.
+struct ExportedUnion: Encodable, Equatable {
+  /// The Swift enum name. No `jsName`: `@Union` takes no arguments, and a union reaches JS as its
+  /// payload types rather than under a bound name.
+  let name: String
+
+  let members: [ExportedUnionMember]
+
+  let file: String
+}
+
 /// The exported types grouped by kind, nested under `exports` in the result so the surface is one
 /// self-contained object separate from `stats`.
 struct ExportedSurface: Encodable, Equatable {
   let modules: [ExportedModule]
   let sharedObjects: [ExportedSharedObject]
   let records: [ExportedRecord]
+  let enums: [ExportedEnum]
+  let unions: [ExportedUnion]
 }
 
+/// Version of the `scan-exports` output shape. Bumped on any breaking change to the envelope or to
+/// anything under `exports`, so a consumer can verify it understands the output before trusting it.
+/// Versioned independently of `scanModulesSchemaVersion`: the two commands serve different consumers
+/// 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`.
+let scanExportsSchemaVersion = 5
+
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).
 struct ScanExportsResult: Encodable, Equatable {
+  let schemaVersion: Int
   let exports: ExportedSurface
   let stats: ScanStats
 }

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

@@ -0,0 +1,199 @@
+import Foundation
+
+/// Fills in each `.ref`'s `refKind` once the whole scan is done.
+///
+/// A `TypeNode` is parsed from one `TypeSyntax` in isolation, so at parse time a name like `Status` is
+/// just a name: the parser has no idea whether the scan will turn up an `@Record`, an `Enumerable`
+/// enum, or nothing at all. Resolution is therefore a second pass over the collected surface, run once
+/// every file has been walked.
+///
+/// Two things change on a resolved ref:
+/// - `refKind` names which kind declares it, so a consumer doesn't repeat this lookup.
+/// - the `typeof` category is corrected for an enum, which crosses as its raw value rather than as an
+///   object. That correction is the reason this can't be left to the consumer: the scanner is the only
+///   side that knows the enum's `rawType`.
+///
+/// A name the scan never declared keeps `refKind: nil` and its `object` category. Not an error: it is
+/// a platform convertible (`CGPoint`, `URL`) or a type from another module, and the consumer's own
+/// catalog decides.
+
+/// The declared names of a scanned surface, each mapped to how it should be reported at a use site.
+/// Built once per scan and used for every ref lookup.
+struct RefIndex {
+  /// `name` -> the kind declaring it, plus the JS category a ref to it crosses as.
+  private var entries: [String: (kind: RefKind, jsType: JSType)] = [:]
+
+  init(surface: ExportedSurface) {
+    for record in surface.records {
+      entries[record.name] = (.record, .object)
+    }
+    for sharedObject in surface.sharedObjects {
+      entries[sharedObject.name] = (.sharedObject, .object)
+    }
+    for union in surface.unions {
+      // A union crosses as whichever alternative matched, so its category is only meaningful per
+      // member. `object` is the honest coarse answer; the consumer reads `members` for the real shape.
+      entries[union.name] = (.union, .object)
+    }
+    for enumeration in surface.enums {
+      entries[enumeration.name] = (.enum, jsType(ofRawType: enumeration.rawType))
+    }
+  }
+
+  /// How a ref to `name` should be reported, or `nil` when the scan declares no such type.
+  func lookup(_ name: String) -> (kind: RefKind, jsType: JSType)? {
+    if let entry = entries[name] {
+      return entry
+    }
+    // A qualified use site (`Media.Status`) names the same type a bare declaration did. Fall back to
+    // the trailing component, which is how the conformance and raw-type checks already match names.
+    guard let trailing = name.split(separator: ".").last.map(String.init), trailing != name else {
+      return nil
+    }
+    return entries[trailing]
+  }
+}
+
+/// The JS category a raw-value enum crosses as: its raw value's. A bare `Enumerable` conformance with
+/// no raw type has nothing to go on, so it stays an object.
+private func jsType(ofRawType rawType: TypeNode?) -> JSType {
+  guard let rawType, let jsType = rawType.jsType else {
+    return .object
+  }
+  return jsType
+}
+
+extension TypeNode {
+  /// This node with every `.ref` in it resolved against `index`, recursively. Returns an unchanged
+  /// node when nothing in it resolves.
+  func resolvingRefs(using index: RefIndex) -> TypeNode {
+    switch self {
+    case .primitive, .unknown:
+      return self
+    case .ref(let name, _, _):
+      guard let entry = index.lookup(name) else {
+        return self
+      }
+      // Only an enum crosses as something other than an object, so only it carries an override.
+      return .ref(
+        name: name, refKind: entry.kind, jsTypeOverride: entry.jsType == .object ? nil : entry.jsType)
+    case .optional(let wrapped):
+      return .optional(wrapped: wrapped.resolvingRefs(using: index))
+    case .array(let element):
+      return .array(element: element.resolvingRefs(using: index))
+    case .dictionary(let key, let value):
+      return .dictionary(
+        key: key.resolvingRefs(using: index), value: value.resolvingRefs(using: index))
+    case .promise(let value):
+      return .promise(value: value.resolvingRefs(using: index))
+    case .function(let parameters, let returns, let isAsync, let isThrowing):
+      return .function(
+        parameters: parameters.map { $0.resolvingRefs(using: index) },
+        returns: returns?.resolvingRefs(using: index),
+        isAsync: isAsync,
+        isThrowing: isThrowing
+      )
+    }
+  }
+}
+
+extension ExportedSurface {
+  /// This surface with every `.ref` in every reported type resolved against its own declarations. The
+  /// second pass `scanExports` runs once the walk is done.
+  ///
+  /// Only the boundary types are rewritten; names, flags, and ordering are untouched. The declared
+  /// types (a record's own name, a union's members) are not themselves refs, so they carry no
+  /// `refKind`: it is the *use sites* that gain one.
+  func resolvingRefs() -> 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) },
+          properties: module.properties.map { $0.resolvingRefs(using: index) },
+          events: module.events.map { $0.resolvingRefs(using: index) },
+          file: module.file
+        )
+      },
+      sharedObjects: sharedObjects.map { sharedObject in
+        ExportedSharedObject(
+          name: sharedObject.name,
+          jsName: sharedObject.jsName,
+          constructorParameters: sharedObject.constructorParameters?.map { $0.resolvingRefs(using: index) },
+          functions: sharedObject.functions.map { $0.resolvingRefs(using: index) },
+          properties: sharedObject.properties.map { $0.resolvingRefs(using: index) },
+          events: sharedObject.events.map { $0.resolvingRefs(using: index) },
+          file: sharedObject.file
+        )
+      },
+      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),
+              isOptional: property.isOptional,
+              hasDefault: property.hasDefault
+            )
+          },
+          file: record.file
+        )
+      },
+      // 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))
+          },
+          file: union.file
+        )
+      }
+    )
+  }
+}
+
+extension ExportedParameter {
+  fileprivate func resolvingRefs(using index: RefIndex) -> ExportedParameter {
+    return ExportedParameter(
+      label: label, name: name, type: type.resolvingRefs(using: index), isOptional: isOptional)
+  }
+}
+
+extension ExportedFunction {
+  fileprivate func resolvingRefs(using index: RefIndex) -> ExportedFunction {
+    return ExportedFunction(
+      name: name,
+      jsName: jsName,
+      parameters: parameters.map { $0.resolvingRefs(using: index) },
+      returns: returns?.resolvingRefs(using: index),
+      isAsync: isAsync,
+      isThrowing: isThrowing,
+      isStatic: isStatic
+    )
+  }
+}
+
+extension ExportedProperty {
+  fileprivate func resolvingRefs(using index: RefIndex) -> ExportedProperty {
+    return ExportedProperty(
+      name: name,
+      jsName: jsName,
+      type: type?.resolvingRefs(using: index),
+      isSettable: isSettable,
+      isStatic: isStatic
+    )
+  }
+}
+
+extension ExportedEvent {
+  fileprivate func resolvingRefs(using index: RefIndex) -> ExportedEvent {
+    return ExportedEvent(
+      name: name, jsName: jsName, payload: payload?.resolvingRefs(using: index), isSync: isSync)
+  }
+}

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

@@ -22,26 +22,45 @@ extension Scanner {
   }
 }
 
-/// Scans `paths` for `@ExpoModule`, `@SharedObject`, and `@Record` types and returns their exported
-/// surface plus the run's stats. Separate from the public entry so tests can drive it without
-/// argv/stdout. The shared `scanFiles` walk + pre-filter selects files; a `SurfaceVisitor` extracts
-/// each one.
+/// Scans `paths` for `@ExpoModule`, `@SharedObject`, `@Record`, and `@Union` types plus `Enumerable`
+/// enums, and returns their exported surface plus the run's stats. Separate from the public entry so
+/// tests can drive it without argv/stdout.
+///
+/// The pre-filter omits `@Event`: an event only declares a member of one of these three types, so a
+/// file containing one already matches on its enclosing type. It does include `Enumerable`, which is a
+/// conformance rather than an attribute: an enum is commonly declared in a file of its own, which no
+/// macro attribute would match.
 func scanExports(paths: [String]) -> ScanExportsResult {
   var modules: [ExportedModule] = []
   var sharedObjects: [ExportedSharedObject] = []
   var records: [ExportedRecord] = []
+  var enums: [ExportedEnum] = []
+  var unions: [ExportedUnion] = []
 
-  let stats = scanFiles(paths: paths, macros: [.expoModule, .sharedObject, .record]) { source, file in
+  let stats = scanFiles(
+    paths: paths,
+    macros: [.expoModule, .sharedObject, .record, .union],
+    conformances: [enumerableConformanceName]
+  ) { source, file in
     let tree = Parser.parse(source: source)
     let visitor = SurfaceVisitor(file: file)
     visitor.walk(tree)
     modules.append(contentsOf: visitor.modules)
     sharedObjects.append(contentsOf: visitor.sharedObjects)
     records.append(contentsOf: visitor.records)
+    enums.append(contentsOf: visitor.enums)
+    unions.append(contentsOf: visitor.unions)
   }
 
+  // Refs resolve only once every file has been walked: a type parsed in one file may name a type
+  // declared in another, so the full set of declarations has to exist before any lookup is valid.
+  let surface = ExportedSurface(
+    modules: modules, sharedObjects: sharedObjects, records: records, enums: enums, unions: unions
+  ).resolvingRefs()
+
   return ScanExportsResult(
-    exports: ExportedSurface(modules: modules, sharedObjects: sharedObjects, records: records),
+    schemaVersion: scanExportsSchemaVersion,
+    exports: surface,
     stats: stats
   )
 }