expo-modules-macros 0.0.1 → 0.14.0

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

@@ -0,0 +1,319 @@
+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)
+  }
+}
+
+/// 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.
+  let name: String
+
+  /// The JS module name: `@ExpoModule("Foo")` override, else the class name.
+  let jsName: String
+
+  let functions: [ExportedFunction]
+  let properties: [ExportedProperty]
+  let events: [ExportedEvent]
+
+  /// 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 events: [ExportedEvent]
+
+  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
+}
+
+/// 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

@@ -0,0 +1,66 @@
+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`, `@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, .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(
+    schemaVersion: scanExportsSchemaVersion,
+    exports: surface,
+    stats: stats
+  )
+}