@expo/expo-modules-macros-plugin 0.5.1 → 0.6.0

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -1,19 +1,33 @@
 import SwiftSyntax
 
 /// The protocol that every type crossing the JS boundary must conform to. Centralized here so the
-/// eventual rename (this is a placeholder name) is a single edit, and shared by every macro that
-/// asserts the conformance (`@JS`, `@Record`, …).
+/// eventual rename (this is a placeholder name) is a single edit, and shared by the macros whose
+/// generated conversions go through the dynamic-type API (`@Record`, `@Event`).
 internal let jsConvertibleProtocolName = "AnyArgument"
 
+/// The constraint a `@JS` boundary type must satisfy, by direction: an argument (and a settable
+/// property's incoming value) is decoded, so it must be `JavaScriptDecodable`; a return value (and a
+/// property's outgoing value) is encoded, so it must be `JavaScriptEncodable`. Asserting each
+/// direction on its own keeps a decode-only or encode-only type from being over-constrained, and
+/// surfaces a missing conformance as a clear "requires that '…' conform to …" diagnostic on the
+/// member instead of an opaque error inside the generated closure.
+internal let javaScriptDecodableProtocolName = "JavaScriptDecodable"
+internal let javaScriptEncodableProtocolName = "JavaScriptEncodable"
+
+/// The constraint a `@Record` property type must satisfy: it must be both `AnyArgument` (the
+/// `from(dictionary:)` / `toDictionary(appContext:)` paths still convert native `Any` through the
+/// dynamic-type API) and `JavaScriptDecodable & JavaScriptEncodable` (the `from(object:)` /
+/// `toObject(appContext:)` paths convert JS values through `decode`/`encode`). A record field has to
+/// support both directions, so the assertion requires the intersection.
+internal let recordFieldProtocolName = "AnyArgument & JavaScriptDecodable & JavaScriptEncodable"
+
 /// The protocol a type must conform to for `self.emit(event:…)` to resolve; core conforms
 /// `BaseModule` and `SharedObject` to it. Asserted by `@Event` so attaching it to a type that can't
 /// emit fails with a conformance diagnostic instead of an opaque "no member 'emit'" error.
 internal let eventEmitterProtocolName = "EventEmitter"
 
-/// Types we never assert because they're statically known to conform and never reach the dynamic
-/// converter: the JS primitives. Asserting them would only add noise to the expansion. Kept here
-/// (rather than reusing the decode-path's `fastDecodeAccessor`) because "known-to-conform" is a
-/// concept that belongs with the assertion logic, not with how a value is decoded.
+/// Types we never assert because they're statically known to conform: the JS primitives. Asserting
+/// them would only add noise to the expansion.
 private let knownConformingPrimitives: Set<String> = ["Bool", "Int", "Double", "String"]
 
 /// One member's worth of conformance assertion: a name (the member it stands for) and the declared
@@ -27,27 +41,55 @@ internal struct ConformanceAssertion {
   let types: [String]
 }
 
-/// A single conformance-assertion peer for a `@JS` member: a never-called `private func` whose body
-/// statically asserts the member's boundary types conform. The assertion is compile-time only — the
-/// function is never invoked, but Swift still type-checks its body, so a non-conforming type becomes
-/// a compile error. Emitted as a **peer** of the user's declaration, so that error lands on the
-/// user's own member rather than on the enclosing macro.
-///
-/// `isStatic` makes the peer `static`, mirroring a `static`/`class` member so it's emitted in the
-/// right metatype context (a peer of a type-level member can't be an instance method). `class func`
-/// members collapse to `static` here too: the peer is private and never called or overridden, so
-/// `static` is always sufficient.
+/// A directional conformance-assertion peer for a `@JS` member: a never-called `private func` whose
+/// body asserts each argument type is `JavaScriptDecodable` and the return/getter type is
+/// `JavaScriptEncodable`, matching how the generated binding converts each (decode on the way in,
+/// encode on the way out). The check is a single member-named nested helper with one `A0…` generic
+/// parameter per non-primitive argument and a single `Return` parameter for the value, called once with
+/// every type's metatype; naming the helper after the member puts the member in the compiler's
+/// diagnostic, and the per-slot constraint reports the offending type against the protocol for *its*
+/// direction.
 ///
-/// Returns `nil` when nothing is left to assert (every type was a known-conforming primitive, or the
-/// list was empty), so the caller emits nothing in that case.
-internal func typeConformanceAssertion(for assertion: ConformanceAssertion, isStatic: Bool) -> DeclSyntax? {
-  guard let body = conformanceAssertionBody(assertion) else {
+/// `decodableTypes` are the argument types (and a settable property's value type); `encodableType` is
+/// the single return type (or a property's value type on read), or `nil` when there's none. Primitives
+/// are dropped from each; when nothing is left in either, returns `nil` so the caller emits no peer.
+/// `isStatic` mirrors a `static`/`class` member so the peer sits in the right metatype context.
+internal func directionalConformanceAssertion(
+  name: String,
+  decodableTypes: [String],
+  encodableType: String?,
+  isStatic: Bool
+) -> DeclSyntax? {
+  let decodables = distinctAssertableTypes(decodableTypes)
+  let encodable = encodableType.flatMap(assertableBoundaryType)
+  guard !decodables.isEmpty || encodable != nil else {
     return nil
   }
+
+  // Build the generic parameter list and the matching call arguments in lockstep: one `A0…` slot
+  // constrained `JavaScriptDecodable` per argument, and a single `Return` slot constrained
+  // `JavaScriptEncodable` for the return/getter value (there's only ever one, so it isn't indexed).
+  var parameters: [String] = []
+  var typeParameters: [String] = []
+  var arguments: [String] = []
+  for (index, type) in decodables.enumerated() {
+    parameters.append("A\(index): \(javaScriptDecodableProtocolName)")
+    typeParameters.append("_: A\(index).Type")
+    arguments.append("\(type).self")
+  }
+  if let encodable {
+    parameters.append("Return: \(javaScriptEncodableProtocolName)")
+    typeParameters.append("_: Return.Type")
+    arguments.append("\(encodable).self")
+  }
+
+  let helper = "func \(name)<\(parameters.joined(separator: ", "))>(\(typeParameters.joined(separator: ", "))) {}"
+  let call = "\(name)(\(arguments.joined(separator: ", ")))"
   let staticKeyword = isStatic ? "static " : ""
   return """
-    private \(raw: staticKeyword)func _assertTypesConformance_\(raw: assertion.name)() {
-    \(raw: body)
+    private \(raw: staticKeyword)func _assertTypesConformance_\(raw: name)() {
+    \(raw: helper)
+    \(raw: call)
     }
     """
 }
@@ -59,8 +101,11 @@ internal func typeConformanceAssertion(for assertion: ConformanceAssertion, isSt
 ///
 /// Returns `nil` when no assertion has anything left to verify (all primitives / empty), so the
 /// caller emits nothing.
-internal func typeConformanceAssertions(for assertions: [ConformanceAssertion]) -> DeclSyntax? {
-  let bodies = assertions.compactMap(conformanceAssertionBody)
+internal func typeConformanceAssertions(
+  for assertions: [ConformanceAssertion],
+  constraint: String = jsConvertibleProtocolName
+) -> DeclSyntax? {
+  let bodies = assertions.compactMap { conformanceAssertionBody($0, constraint: constraint) }
   guard !bodies.isEmpty else {
     return nil
   }
@@ -85,24 +130,33 @@ internal func assertableBoundaryType(_ type: String) -> String? {
 /// symbol, nothing to collide, nothing left in the type's namespace — and naming it after the member
 /// puts the member's name in the compiler's conformance diagnostic. Returns `nil` when every type was
 /// a known-conforming primitive or the list was empty.
-private func conformanceAssertionBody(_ assertion: ConformanceAssertion) -> String? {
-  // Unwrap top-level optionals to the core type, then dedup so each type is asserted once even when
-  // it appears more than once; skip known primitives.
-  var seen: Set<String> = []
-  var distinct: [String] = []
-  for type in assertion.types.map(unwrappedOptional)
-  where !knownConformingPrimitives.contains(type) && seen.insert(type).inserted {
-    distinct.append(type)
-  }
+private func conformanceAssertionBody(
+  _ assertion: ConformanceAssertion,
+  constraint: String = jsConvertibleProtocolName
+) -> String? {
+  let distinct = distinctAssertableTypes(assertion.types)
   guard !distinct.isEmpty else {
     return nil
   }
 
-  var lines = ["func \(assertion.name)<T: \(jsConvertibleProtocolName)>(_: T.Type) {}"]
+  var lines = ["func \(assertion.name)<T: \(constraint)>(_: T.Type) {}"]
   lines.append(contentsOf: distinct.map { "\(assertion.name)(\($0).self)" })
   return lines.joined(separator: "\n")
 }
 
+/// Normalizes a list of boundary types for assertion: unwraps each to its core type (trailing
+/// optionals stripped), drops the known-conforming primitives that never need asserting, and dedups
+/// while preserving first-seen order so a type is asserted once even when it appears more than once.
+private func distinctAssertableTypes(_ types: [String]) -> [String] {
+  var seen: Set<String> = []
+  var distinct: [String] = []
+  for type in types.map(unwrappedOptional)
+  where !knownConformingPrimitives.contains(type) && seen.insert(type).inserted {
+    distinct.append(type)
+  }
+  return distinct
+}
+
 /// Strips every trailing optional marker (`?`/`!`) so the assertion targets the core wrapped type.
 /// `Optional<W>: AnyArgument` holds exactly when `W: AnyArgument` (and `T!` is just `T?`), so each
 /// layer is conformance-equivalent to its wrapped type. Asserting the core gives a cleaner diagnostic

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

@@ -95,8 +95,9 @@ private func arguments(of attribute: AttributeSyntax) -> [MacroArgument] {
 
 /// The first string-literal argument of an attribute, e.g. `@JS("doWork")` -> "doWork". Returns
 /// `nil` when there's no argument or it isn't a plain string literal. (Same shape the
-/// `jsNameArgument` helper reads inside the macros.)
-private func stringArgument(of attribute: AttributeSyntax) -> String? {
+/// `jsNameArgument` helper reads inside the macros.) Shared with the `scan-exports` surface visitor,
+/// which reads the same JS-name override off `@JS`/`@ExpoModule`/`@SharedObject`.
+func stringArgument(of attribute: AttributeSyntax) -> String? {
   guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
     let first = args.first,
     first.label == nil,

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

@@ -2,14 +2,19 @@ import Foundation
 import SwiftParser
 import SwiftSyntax
 
-/// Walks `paths`, parses each `.swift` file that might contain one of `macros` (the pre-filter), and
-/// returns every detection (in file then source order) with the run's stats. The shared core every
-/// scan command builds on; each command projects these detections into its own output shape.
-func collectDetections(paths: [String], macros: Set<DetectedMacro>) -> (detections: [Detection], stats: ScanStats) {
+/// 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.
+/// 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>,
+  process: (_ source: String, _ file: String) -> Void
+) -> ScanStats {
   let clock = ContinuousClock()
   let start = clock.now
 
-  var detections: [Detection] = []
   var filesScanned = 0
   var filesParsed = 0
 
@@ -29,13 +34,24 @@ func collectDetections(paths: [String], macros: Set<DetectedMacro>) -> (detectio
       continue
     }
     filesParsed += 1
-    detections.append(contentsOf: detect(source: source, file: file, macros: macros))
+    process(source, file)
   }
 
   let elapsed = (clock.now - start).components
   let durationMs = Double(elapsed.seconds) * 1000 + Double(elapsed.attoseconds) / 1e15
 
-  return (detections, ScanStats(filesScanned: filesScanned, filesParsed: filesParsed, durationMs: durationMs))
+  return ScanStats(filesScanned: filesScanned, filesParsed: filesParsed, durationMs: durationMs)
+}
+
+/// Walks `paths`, parses each `.swift` file that might contain one of `macros`, and returns every
+/// detection (in file then source order) with the run's stats — the shape `scan-modules` projects.
+/// A thin layer over `scanFiles` that accumulates the per-file detections.
+func collectDetections(paths: [String], macros: Set<DetectedMacro>) -> (detections: [Detection], stats: ScanStats) {
+  var detections: [Detection] = []
+  let stats = scanFiles(paths: paths, macros: macros) { source, file in
+    detections.append(contentsOf: detect(source: source, file: file, macros: macros))
+  }
+  return (detections, stats)
 }
 
 /// Parses one source string and returns its detections for the given macro set. The unit of work the

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

@@ -0,0 +1,186 @@
+import Foundation
+
+/// The deep-scan surface: the full JS-exported shape of every `@ExpoModule`, `@SharedObject`, and
+/// `@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.
+
+/// One parameter of a `@JS` function or `@JS init`.
+struct ExportedParameter: Encodable, Equatable {
+  /// The argument label (the `first` name): `to` in `func move(to point: Point)`, or `_` if unlabeled.
+  let label: String
+
+  /// The internal parameter name (the `second` name, else the same as `label`): `point` above.
+  let name: String
+
+  let 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
+
+  private enum CodingKeys: String, CodingKey {
+    case label, name, type
+    case isOptional = "optional"
+  }
+}
+
+/// One `@JS func` on a module or shared object.
+struct ExportedFunction: Encodable, Equatable {
+  /// The Swift declaration name.
+  let name: String
+
+  /// The JS name it binds under: the `@JS("x")` override, else `name`.
+  let jsName: String
+
+  let parameters: [ExportedParameter]
+
+  /// The return type, or `nil` for `Void`. Named `returns` to pair with `parameters`.
+  let returns: TypeNode?
+
+  /// `async` (an async function is promise-returning in JS).
+  let isAsync: Bool
+
+  /// `throws`.
+  let isThrowing: Bool
+
+  /// `static`/`class` member.
+  let isStatic: Bool
+
+  /// The flags are encoded under their TS-keyword spellings.
+  private enum CodingKeys: String, CodingKey {
+    case name, jsName, parameters, returns
+    case isAsync = "async"
+    case isThrowing = "throws"
+    case isStatic = "static"
+  }
+}
+
+/// One `@JS var` on a module or shared object.
+struct ExportedProperty: Encodable, Equatable {
+  /// The Swift declaration name.
+  let name: String
+
+  /// The JS name it binds under: the `@JS("x")` override, else `name`.
+  let jsName: String
+
+  /// The value type, or `nil` when undeterminable syntactically (no annotation and no literal
+  /// default), the case the macro binds getter-only.
+  let type: TypeNode?
+
+  /// True when JS can assign to it: a stored `var` or a computed `var` with a `set`. Encoded as its
+  /// inverse, `readonly`.
+  let isSettable: Bool
+
+  /// `static`/`class` member. Encoded as `static`.
+  let isStatic: Bool
+
+  private enum CodingKeys: String, CodingKey {
+    case name, jsName, type
+    case isReadonly = "readonly"
+    case isStatic = "static"
+  }
+
+  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(type, forKey: .type)
+    try container.encode(!isSettable, forKey: .isReadonly)
+    try container.encode(isStatic, forKey: .isStatic)
+  }
+}
+
+/// One `@Record` property: a plain data slot exposing `optional`/`required` (vs. `ExportedProperty`,
+/// a JS accessor exposing `readonly`/`static`). A record crosses the boundary by value, so the whole
+/// type is read-only in JS; that's a record-level fact and isn't stamped per property.
+struct ExportedRecordProperty: Encodable, Equatable {
+  let name: String
+
+  /// `@Record` requires a determinable type on every property, so this is never `nil`.
+  let 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
+
+  /// Whether JS must supply this property, matching the macro's `RecordProperty.isRequired`. Encoded
+  /// as `required`.
+  var isRequired: Bool {
+    return !hasDefault && !isOptional
+  }
+
+  private enum CodingKeys: String, CodingKey {
+    case name, type
+    case isOptional = "optional"
+    case isRequired = "required"
+  }
+
+  func encode(to encoder: Encoder) throws {
+    var container = encoder.container(keyedBy: CodingKeys.self)
+    try container.encode(name, forKey: .name)
+    try container.encode(type, forKey: .type)
+    try container.encode(isOptional, forKey: .isOptional)
+    try container.encode(isRequired, forKey: .isRequired)
+  }
+}
+
+/// A `@ExpoModule` type and its `@JS` surface.
+struct ExportedModule: Encodable, Equatable {
+  /// The Swift class name.
+  let name: String
+
+  /// The JS module name: `@ExpoModule("Foo")` override, else the class name.
+  let jsName: String
+
+  let functions: [ExportedFunction]
+  let properties: [ExportedProperty]
+
+  /// Absolute source path, matching `scan-modules`.
+  let file: String
+}
+
+/// A `@SharedObject` type: a JS class with an optional `@JS init` constructor plus its `@JS` members.
+struct ExportedSharedObject: Encodable, Equatable {
+  /// The Swift class name.
+  let name: String
+
+  /// The JS class name: `@SharedObject("Foo")` override, else the class name.
+  let jsName: String
+
+  /// The `@JS init` parameters, or `nil` when there's none. A shared object has at most one.
+  let constructorParameters: [ExportedParameter]?
+
+  let functions: [ExportedFunction]
+  let properties: [ExportedProperty]
+
+  let file: String
+}
+
+/// A `@Record` type and its properties (data only: no functions, accessors, or constructor).
+struct ExportedRecord: Encodable, Equatable {
+  /// The Swift type name (struct or class).
+  let name: String
+
+  let properties: [ExportedRecordProperty]
+
+  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]
+}
+
+/// 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 exports: ExportedSurface
+  let stats: ScanStats
+}

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

@@ -0,0 +1,47 @@
+import Foundation
+import SwiftParser
+import SwiftSyntax
+
+extension Scanner {
+  /// Runs `scan-exports` over `paths`, prints the JSON report to stdout, and returns the exit code
+  /// (`0` on success, `1` if encoding fails). The deep counterpart to `runModules`.
+  public static func runExports(paths: [String]) -> Int32 {
+    let result = scanExports(paths: paths)
+
+    do {
+      let encoder = JSONEncoder()
+      encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+      let data = try encoder.encode(result)
+      FileHandle.standardOutput.write(data)
+      FileHandle.standardOutput.write(Data("\n".utf8))
+      return 0
+    } catch {
+      FileHandle.standardError.write(Data("error: failed to encode results: \(error)\n".utf8))
+      return 1
+    }
+  }
+}
+
+/// 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.
+func scanExports(paths: [String]) -> ScanExportsResult {
+  var modules: [ExportedModule] = []
+  var sharedObjects: [ExportedSharedObject] = []
+  var records: [ExportedRecord] = []
+
+  let stats = scanFiles(paths: paths, macros: [.expoModule, .sharedObject, .record]) { 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)
+  }
+
+  return ScanExportsResult(
+    exports: ExportedSurface(modules: modules, sharedObjects: sharedObjects, records: records),
+    stats: stats
+  )
+}