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

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

@@ -10,6 +10,8 @@ final class SurfaceVisitor: SyntaxVisitor {
   private(set) var modules: [ExportedModule] = []
   private(set) var sharedObjects: [ExportedSharedObject] = []
   private(set) var records: [ExportedRecord] = []
+  private(set) var enums: [ExportedEnum] = []
+  private(set) var unions: [ExportedUnion] = []
 
   init(file: String) {
     self.file = file
@@ -32,25 +34,57 @@ final class SurfaceVisitor: SyntaxVisitor {
     return .skipChildren
   }
 
+  /// The two kinds of enum the surface reports: a `@Union` by its attribute, an `Enumerable` enum by
+  /// its conformance (core converts it with no macro involved, so there is no attribute to key on).
+  ///
+  /// `@Union` wins when a type carries both. Its cases hold payloads rather than raw values, so there
+  /// would be nothing to report as an enum, and listing it in both arrays would describe two
+  /// contradictory JS types for one declaration.
+  override func visit(_ node: EnumDeclSyntax) -> SyntaxVisitorContinueKind {
+    guard isTopLevel(node) else {
+      return .skipChildren
+    }
+
+    if node.attributes.firstAttribute(named: DetectedMacro.union.rawValue) != nil {
+      unions.append(
+        ExportedUnion(
+          name: node.name.text,
+          members: collectUnionMembers(node.memberBlock.members),
+          file: file
+        ))
+    } else if inherits(from: enumerableConformanceName, in: node.inheritanceClause) {
+      let rawType = rawValueType(of: node.inheritanceClause)
+      enums.append(
+        ExportedEnum(
+          name: node.name.text,
+          rawType: rawType,
+          cases: collectEnumCases(node.memberBlock.members, rawType: rawType),
+          file: file
+        ))
+    }
+    return .skipChildren
+  }
+
   /// Routes a top-level type to the right collector based on which Expo macro it carries. A type
   /// carrying none of them is ignored. `@Record` and `@ExpoModule`/`@SharedObject` are mutually
   /// exclusive in practice, so the first match wins.
   private func classify(name: String, attributes: AttributeListSyntax, members: MemberBlockItemListSyntax) {
     if let attribute = attributes.firstAttribute(named: DetectedMacro.expoModule.rawValue) {
-      let (functions, properties, _) = collectJSMembers(members)
+      let (functions, properties, events, _) = collectJSMembers(members)
       modules.append(
         ExportedModule(
           name: name,
           jsName: stringArgument(of: attribute) ?? name,
           functions: functions,
           properties: properties,
+          events: events,
           file: file
         ))
       return
     }
 
     if let attribute = attributes.firstAttribute(named: DetectedMacro.sharedObject.rawValue) {
-      let (functions, properties, constructor) = collectJSMembers(members)
+      let (functions, properties, events, constructor) = collectJSMembers(members)
       sharedObjects.append(
         ExportedSharedObject(
           name: name,
@@ -58,6 +92,7 @@ final class SurfaceVisitor: SyntaxVisitor {
           constructorParameters: constructor,
           functions: functions,
           properties: properties,
+          events: events,
           file: file
         ))
       return
@@ -68,13 +103,17 @@ final class SurfaceVisitor: SyntaxVisitor {
     }
   }
 
-  /// The `@JS` members of a module / shared-object body: functions, properties, and the single
-  /// `@JS init` constructor parameters (`nil` when absent). Only declarations carrying `@JS` count.
+  /// The exported members of a module / shared-object body: `@JS` functions and properties, `@Event`
+  /// events, and the single `@JS init` constructor parameters (`nil` when absent).
   private func collectJSMembers(
     _ members: MemberBlockItemListSyntax
-  ) -> (functions: [ExportedFunction], properties: [ExportedProperty], constructor: [ExportedParameter]?) {
+  ) -> (
+    functions: [ExportedFunction], properties: [ExportedProperty], events: [ExportedEvent],
+    constructor: [ExportedParameter]?
+  ) {
     var functions: [ExportedFunction] = []
     var properties: [ExportedProperty] = []
+    var events: [ExportedEvent] = []
     var constructor: [ExportedParameter]?
 
     for member in members {
@@ -98,10 +137,52 @@ final class SurfaceVisitor: SyntaxVisitor {
       if let varDecl = decl.as(VariableDeclSyntax.self),
         let attribute = varDecl.attributes.firstAttribute(named: DetectedMacro.js.rawValue) {
         properties.append(contentsOf: makeProperties(varDecl: varDecl, attribute: attribute))
+        continue
+      }
+
+      if let varDecl = decl.as(VariableDeclSyntax.self),
+        let attribute = varDecl.attributes.firstAttribute(named: DetectedMacro.event.rawValue) {
+        events.append(contentsOf: makeEvents(varDecl: varDecl, attribute: attribute))
       }
     }
 
-    return (functions, properties, constructor)
+    return (functions, properties, events, constructor)
+  }
+
+  /// Builds the `ExportedEvent` entries for an `@Event var`, applying the same checks
+  /// `EventMacro.validatedEvent(of:on:)` does. A rejected declaration expands to no event, so
+  /// reporting one would describe a surface that does not exist. `@JS` on the same property is
+  /// caught by the caller, which reaches the `@JS` branch first.
+  private func makeEvents(varDecl: VariableDeclSyntax, attribute: AttributeSyntax) -> [ExportedEvent] {
+    guard varDecl.bindingSpecifier.tokenKind != .keyword(.let),
+      !isTypeLevel(varDecl.modifiers) else {
+      return []
+    }
+    let override = stringArgument(of: attribute)
+    let isSync = boolArgument(of: attribute, label: "sync") == true
+    var result: [ExportedEvent] = []
+
+    for binding in varDecl.bindings {
+      // Binding-level checks, in the macro's order: a named binding with a function type that takes
+      // at most one payload and returns Void, with no initializer or hand-written accessors.
+      guard let ident = binding.pattern.as(IdentifierPatternSyntax.self),
+        binding.initializer == nil,
+        binding.accessorBlock == nil,
+        let functionType = underlyingFunctionType(of: binding.typeAnnotation?.type),
+        isVoidEventReturn(functionType.returnClause.type),
+        functionType.parameters.count <= 1 else {
+        continue
+      }
+      let name = ident.identifier.text
+      result.append(
+        ExportedEvent(
+          name: name,
+          jsName: override ?? defaultEventName(for: name),
+          payload: functionType.parameters.first.map { typeNode(from: $0.type) },
+          isSync: isSync
+        ))
+    }
+    return result
   }
 
   /// Builds an `ExportedFunction` from a `@JS func`: JS-name fallback, parameters, a `Void` return as
@@ -208,6 +289,61 @@ final class SurfaceVisitor: SyntaxVisitor {
     return properties
   }
 
+  /// The declared cases of an enum, in source order. One `case` declaration can introduce several
+  /// cases (`case a, b`), so each element is read separately. A case carrying associated values is
+  /// skipped: it has no raw value, so it can't cross the boundary as one.
+  ///
+  /// A `String`-backed case with no written value takes the case's own name, so those are filled in
+  /// here and a `String`-backed enum reports a raw value on every case. `Int` is deliberately left
+  /// alone: see `derivedStringRawValue(for:rawType:)`.
+  private func collectEnumCases(
+    _ members: MemberBlockItemListSyntax,
+    rawType: TypeNode?
+  ) -> [ExportedEnumCase] {
+    var cases: [ExportedEnumCase] = []
+
+    for member in members {
+      guard let caseDecl = member.decl.as(EnumCaseDeclSyntax.self) else {
+        continue
+      }
+      for element in caseDecl.elements where element.parameterClause == nil {
+        let name = element.name.text
+        cases.append(
+          ExportedEnumCase(
+            name: name,
+            rawValue: writtenRawValue(of: element) ?? derivedStringRawValue(for: name, rawType: rawType)
+          ))
+      }
+    }
+    return cases
+  }
+
+  /// The alternatives of a `@Union`, in declaration order (the decode depends on it). Skips the cases
+  /// `UnionMacro.validatedUnion(of:)` rejects (no associated value, more than one, or a default), since
+  /// those don't exist at runtime. The scanner never diagnoses, it just declines to report.
+  ///
+  /// A generic `@Union` is rejected wholesale by the macro but still reported, since the declaration
+  /// names a type a consumer may meet.
+  private func collectUnionMembers(_ members: MemberBlockItemListSyntax) -> [ExportedUnionMember] {
+    var result: [ExportedUnionMember] = []
+
+    for member in members {
+      guard let caseDecl = member.decl.as(EnumCaseDeclSyntax.self) else {
+        continue
+      }
+      for element in caseDecl.elements {
+        guard let parameters = element.parameterClause?.parameters,
+          parameters.count == 1, let parameter = parameters.first,
+          parameter.defaultValue == nil else {
+          continue
+        }
+        result.append(
+          ExportedUnionMember(name: element.name.text, type: typeNode(from: parameter.type)))
+      }
+    }
+    return result
+  }
+
   /// Projects a parameter clause into `ExportedParameter`s: label = first name, name = second (else
   /// first), and `optional` when it has a default value or an optional type.
   private func parameters(of clause: FunctionParameterClauseSyntax) -> [ExportedParameter] {
@@ -236,6 +372,79 @@ final class SurfaceVisitor: SyntaxVisitor {
 // MARK: - Syntactic helpers (shared spelling with the macros)
 
 /// True when the modifiers make a member type-level (`static` or `class`).
+// MARK: - `@Event` helpers
+
+// The macro target can't be imported, so these are deliberate copies of `EventMacro`'s logic. They
+// must stay in step with it: a drift changes the reported surface without failing any build.
+
+/// The Swift name with a conventional `on` prefix stripped and the remainder decapitalized
+/// (`onStatusChange` -> `statusChange`); names without the prefix pass through verbatim. A drift
+/// from the macro's copy would produce listener names the module never emits.
+func defaultEventName(for swiftName: String) -> String {
+  guard swiftName.hasPrefix("on") else {
+    return swiftName
+  }
+  let rest = swiftName.dropFirst(2)
+  guard let first = rest.first, first.isUppercase else {
+    return swiftName
+  }
+  return decapitalized(String(rest))
+}
+
+/// Lowercases the leading uppercase run the way Swift's API importer does: a single leading capital
+/// is lowercased, and a longer acronym run keeps its last capital when a lowercase letter follows it
+/// (`StatusChange` -> `statusChange`, `URLChange` -> `urlChange`, `URL` -> `url`).
+private func decapitalized(_ name: String) -> String {
+  let runEnd = name.firstIndex { !$0.isUppercase } ?? name.endIndex
+  if name[..<runEnd].count > 1 && runEnd != name.endIndex {
+    let lastCapital = name.index(before: runEnd)
+    return name[..<lastCapital].lowercased() + name[lastCapital...]
+  }
+  return name[..<runEnd].lowercased() + name[runEnd...]
+}
+
+/// The function type underlying a property's type annotation, unwrapping attributes
+/// (`@Sendable (P) -> Void`) and single-element parentheses (`((P) -> Void)`). `nil` when the
+/// annotation is missing or isn't a function type.
+private func underlyingFunctionType(of type: TypeSyntax?) -> FunctionTypeSyntax? {
+  guard let type else {
+    return nil
+  }
+  if let attributed = type.as(AttributedTypeSyntax.self) {
+    return underlyingFunctionType(of: attributed.baseType)
+  }
+  if let tuple = type.as(TupleTypeSyntax.self),
+    tuple.elements.count == 1, let element = tuple.elements.first, element.firstName == nil {
+    return underlyingFunctionType(of: element.type)
+  }
+  return type.as(FunctionTypeSyntax.self)
+}
+
+/// True when an event's function type returns `Void`. The shared `isVoidType` is not reused: it
+/// accepts neither `Swift.Void` nor a parenthesized `(Void)`, so it would drop valid events.
+private func isVoidEventReturn(_ type: TypeSyntax) -> Bool {
+  if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
+    let element = tuple.elements.first, element.firstName == nil {
+    return isVoidEventReturn(element.type)
+  }
+  let text = type.trimmedDescription
+  return text == "Void" || text == "()" || text == "Swift.Void"
+}
+
+/// The value of a labeled boolean macro argument (`@Event(sync: true)`), or `nil` when absent.
+private func boolArgument(of attribute: AttributeSyntax, label: String) -> Bool? {
+  guard let arguments = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return nil
+  }
+  for argument in arguments where argument.label?.text == label {
+    guard let literal = argument.expression.as(BooleanLiteralExprSyntax.self) else {
+      return nil
+    }
+    return literal.literal.tokenKind == .keyword(.true)
+  }
+  return nil
+}
+
 private func isTypeLevel(_ modifiers: DeclModifierListSyntax) -> Bool {
   modifiers.contains {
     $0.name.tokenKind == .keyword(.static) || $0.name.tokenKind == .keyword(.class)
@@ -255,6 +464,106 @@ private func isExcludedRecordModifier(_ modifiers: DeclModifierListSyntax) -> Bo
   }
 }
 
+/// The protocol whose conformance marks an enum as convertible at the JS boundary. Core converts such
+/// an enum through `Coding/…+Enumerable`, keyed on this conformance, so the scanner keys on it too.
+let enumerableConformanceName = "Enumerable"
+
+/// True when an inheritance clause names `name`. Matched on the trailing component of the written
+/// spelling, so a qualified `ExpoModulesCore.Enumerable` counts. Purely syntactic: a conformance added
+/// in a separate `extension`, or inherited through another protocol, is invisible to a scan and so is
+/// not reported.
+func inherits(from name: String, in clause: InheritanceClauseSyntax?) -> Bool {
+  guard let clause else {
+    return false
+  }
+  return clause.inheritedTypes.contains { inherited in
+    inherited.type.trimmedDescription.split(separator: ".").last.map(String.init) == name
+  }
+}
+
+/// The raw value a case writes, or `nil` when it writes none.
+///
+/// A string literal is reported **decoded**: `case a = "act"` yields `act`, with no quotes, because a
+/// `String` raw value is always fully known (see `derivedStringRawValue(for:rawType:)`) and a consumer
+/// should not have to unquote it. Every other expression is reported as **source text**, since an
+/// integer raw value may be any literal expression the scanner can't evaluate. Which of the two a
+/// `rawValue` holds follows from the enum's `rawType`, and `ExportedEnumCase` documents that contract.
+///
+/// A literal this can't decode is treated as writing no raw value rather than reported half-read: an
+/// interpolated string (`case a = "x\(y)"`, not a legal raw value anyway), or one whose segment carries
+/// a backslash escape, which would need real unescaping to turn into its value. A `String` case then
+/// falls back to the derived name, keeping that invariant intact.
+private func writtenRawValue(of element: EnumCaseElementSyntax) -> String? {
+  guard let value = element.rawValue?.value else {
+    return nil
+  }
+  guard let literal = value.as(StringLiteralExprSyntax.self) else {
+    // Not a string: an integer literal, a negative value, or an expression. Source text verbatim.
+    return value.trimmedDescription
+  }
+  guard literal.segments.count == 1,
+    let segment = literal.segments.first?.as(StringSegmentSyntax.self) else {
+    return nil
+  }
+  // The segment's text is the literal's content with its delimiters already stripped, so a plain
+  // `"act"` and a raw `#"act"#` both read as `act`. An escape is left to the fallback rather than
+  // emitted raw, since `\n` here is two characters, not a newline.
+  let content = segment.content.text
+  return content.contains("\\") ? nil : content
+}
+
+/// The raw value Swift gives a `String`-backed case that writes none: the case's own name.
+///
+/// Only `String` is derived. Its defaulting is per-case and carry-free, so a case that can't be read
+/// can't affect any other, and every legal spelling is a single-segment literal. That closes the case
+/// and lets a `String`-backed enum report a raw value on *every* case. `Int` continues
+/// from the preceding case's value (`case a = 1; case b` makes `b` 2), whether that value was written
+/// or itself derived, so one unreadable expression would corrupt every case after it. Deriving it
+/// partially would be worse than not deriving it, so integer-backed enums report only what's written
+/// and the consumer applies the continuation rule.
+private func derivedStringRawValue(for caseName: String, rawType: TypeNode?) -> String? {
+  // `String` is a `.primitive`, but a qualified `Swift.String` parses as a `.ref`, and both are legal
+  // raw types. Matching the trailing component covers each, the same way the conformance check does.
+  let name: String?
+  switch rawType {
+  case .primitive(let spelling, _), .ref(let spelling, _, _):
+    name = spelling.split(separator: ".").last.map(String.init)
+  default:
+    name = nil
+  }
+  guard name == "String" else {
+    return nil
+  }
+  // Decoded, matching how a written string literal is reported: the value, not its source spelling.
+  return caseName
+}
+
+/// Protocols an `Enumerable` enum commonly adopts, which a syntactic scan would otherwise mistake for
+/// a raw value type when one is written ahead of the conformance (`enum E: Codable, Enumerable`, which
+/// has no raw type). Only the first inherited entry is ever tested against this, so the list needs to
+/// name just what can legally precede `Enumerable`, not every protocol in existence.
+private let knownNonRawValueProtocols: Set<String> = [
+  "CaseIterable", "Codable", "Decodable", "Encodable", "Equatable", "Error", "Hashable",
+  "Identifiable", "Sendable", enumerableConformanceName,
+]
+
+/// The raw value type of an enum, or `nil` when it declares none.
+///
+/// Swift allows a raw type only in first position, so nothing after the first entry can be one. The
+/// first entry is still not necessarily a raw type: `enum E: Codable, Enumerable` is a legal
+/// raw-value-less enum, and a scan can't resolve a bare name to tell a protocol from a type. It's
+/// matched against `knownNonRawValueProtocols` instead, which covers what an `Enumerable` enum
+/// realistically adopts. An unlisted protocol written first would still be misreported as a raw type;
+/// that is the residual limit of reading this syntactically.
+func rawValueType(of clause: InheritanceClauseSyntax?) -> TypeNode? {
+  guard let first = clause?.inheritedTypes.first?.type,
+    let trailing = first.trimmedDescription.split(separator: ".").last.map(String.init),
+    !knownNonRawValueProtocols.contains(trailing) else {
+    return nil
+  }
+  return typeNode(from: first)
+}
+
 /// True when a type is written as an optional: `T?`, `T!`, or `Optional<T>`, mirroring the macros'
 /// `isOptionalType`.
 private func isOptionalType(_ type: TypeSyntax) -> Bool {

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

@@ -21,6 +21,21 @@ enum JSType: String, Encodable {
   case function
 }
 
+/// Which of the scanned kinds declares the name a `.ref` points at.
+///
+/// Resolution happens after the whole scan (`ExportedSurface.resolvingRefs()`), not while parsing a
+/// type: a `TypeNode` is built from one `TypeSyntax` in isolation, long before the scanner knows what
+/// else exists. A ref the scan can't place carries no `refKind` at all rather than a value meaning "none",
+/// matching how the rest of the surface signals "nothing to say" (`returns` for `Void`, `rawType` for
+/// a bare conformance). That is not an error: it covers a platform or built-in convertible (`CGPoint`,
+/// `URL`) and a type from another module, which the consumer resolves against its own catalog.
+enum RefKind: String, Encodable {
+  case record
+  case sharedObject
+  case `enum`
+  case union
+}
+
 indirect enum TypeNode: Equatable {
   /// `Bool`, `Int`, `Double`, `String`: the types core fast-decodes. `name` is the Swift spelling;
   /// `jsType` is `boolean`/`number`/`string`.
@@ -42,9 +57,18 @@ indirect enum TypeNode: Equatable {
   /// the effects (encoded `async`/`throws`).
   case function(parameters: [TypeNode], returns: TypeNode?, isAsync: Bool, isThrowing: Bool)
 
-  /// Any other named type (record, shared object, enum, …). `name` is the possibly-qualified spelling;
-  /// the generator resolves it against the scanned types or treats it as opaque.
-  case ref(name: String)
+  /// Any other named type (record, shared object, enum, union, …). `name` is the possibly-qualified
+  /// spelling.
+  ///
+  /// `refKind` says which scanned kind declares that name, filled in after the scan by
+  /// `ExportedSurface.resolvingRefs()`; it is `nil` until then, and stays `nil` for a name the scan
+  /// never declared (a platform type like `CGPoint`, or one from another module).
+  ///
+  /// `jsTypeOverride` carries the category a resolved ref actually crosses as, when that isn't
+  /// `object`: a raw-value enum reaches JS as its raw value, so `Status: String` is a `string`. Only
+  /// resolution can know this, since the category comes from the *declaration's* `rawType`, which a
+  /// node parsed at a use site has never seen.
+  case ref(name: String, refKind: RefKind? = nil, jsTypeOverride: JSType? = nil)
 
   /// A spelling the parser doesn't model (generic parameter, tuple, metatype, …), kept verbatim so
   /// nothing is lost. Has no `typeof`.
@@ -56,8 +80,11 @@ indirect enum TypeNode: Equatable {
     switch self {
     case .primitive(_, let jsType):
       return jsType
-    case .array, .dictionary, .promise, .ref:
+    case .array, .dictionary, .promise:
       return .object
+    case .ref(_, _, let jsTypeOverride):
+      // An unresolved ref, and every resolved one but an enum, is an object.
+      return jsTypeOverride ?? .object
     case .function:
       return .function
     case .optional(let wrapped):
@@ -70,6 +97,7 @@ indirect enum TypeNode: Equatable {
 
 extension TypeNode: Encodable {
   private enum CodingKeys: String, CodingKey {
+    case refKind
     case kind
     case name
     // The `typeof` category. Spelled `typeof` in JSON (what the consumer reads); the Swift property is
@@ -109,9 +137,10 @@ extension TypeNode: Encodable {
       try container.encodeIfPresent(returns, forKey: .returns)
       try container.encode(isAsync, forKey: .isAsync)
       try container.encode(isThrowing, forKey: .isThrowing)
-    case .ref(let name):
+    case .ref(let name, let refKind, _):
       try container.encode("ref", forKey: .kind)
       try container.encode(name, forKey: .name)
+      try container.encodeIfPresent(refKind, forKey: .refKind)
     case .unknown(let text):
       try container.encode("unknown", forKey: .kind)
       try container.encode(text, forKey: .text)
@@ -236,7 +265,7 @@ extension TypeNode {
     switch self {
     case .primitive(let name, _):
       return name
-    case .ref(let name):
+    case .ref(let name, _, _):
       return name
     case .optional(let wrapped):
       return "\(wrapped.spelling)?"

package/apple/Sources/ExpoModulesScanner/Modules/ScanModules.swift

@@ -1,4 +1,5 @@
 import Foundation
+import SwiftParser
 
 /// The scanner's public entry point. Argument parsing, subcommand dispatch, and usage text live in
 /// the CLI target; this just runs a command and writes its JSON report to stdout.
@@ -10,11 +11,10 @@ public enum Scanner {
   /// process exit code: `0` on success, `1` if encoding fails. (The deep `scan-exports` command has
   /// its own `runExports` entry returning its own result type.)
   ///
-  /// `platform` and `defines` (the `--platform` and `--define` options) form the configuration that
-  /// `#if` conditions are evaluated against; see `ScanBuildConfiguration`.
-  public static func runModules(paths: [String], platform: String? = nil, defines: [String] = []) -> Int32 {
-    let configuration = ScanBuildConfiguration(platform: platform, defines: Set(defines))
-    let result = scanModules(paths: paths, configuration: configuration)
+  /// `defines` (the `--define` options) asserts conditional compilation flags; see `scanModules`
+  /// for how they and platforms shape each module's `platforms` list.
+  public static func runModules(paths: [String], defines: [String] = []) -> Int32 {
+    let result = scanModules(paths: paths, defines: Set(defines))
 
     do {
       let encoder = JSONEncoder()
@@ -31,10 +31,11 @@ public enum Scanner {
 }
 
 /// One module in the `scan-modules` output. Trimmed to what `expo-modules-autolinking` needs to
-/// register a module: the Swift class name, the JS name it registers under, and the file it's in.
-/// The richer fields the visitor captures (declaration kind, raw macro arguments, line/column) are
-/// dropped here — they're redundant for this command (the macro is always `@ExpoModule` on a class)
-/// and the deep `scan-exports` surface carries the richer per-member detail instead.
+/// register a module: the Swift class name, the JS name it registers under, the platforms that
+/// include it, and the file it's in. The richer fields the visitor captures (declaration kind, raw
+/// macro arguments, line/column) are dropped here — they're redundant for this command (the macro
+/// is always `@ExpoModule` on a class) and the deep `scan-exports` surface carries the richer
+/// per-member detail instead.
 struct ScannedModule: Codable, Equatable {
   /// The Swift class name the module is declared as.
   let name: String
@@ -50,14 +51,22 @@ struct ScannedModule: Codable, Equatable {
   /// classes with a diagnostic instead of emitting a provider that fails to compile.
   let accessLevel: String
 
+  /// The Apple OSes whose builds include this class, spelled as `os(...)` spells them and compared
+  /// case-sensitively. An unconditional module lists every OS. Empty means no build is known to
+  /// include it, because the enclosing conditions depend on flags not asserted with `--define` or
+  /// on conditions a static scan cannot answer (those are reported in `warnings`). The consumer
+  /// must not assume such a class exists.
+  let platforms: [String]
+
   /// Source file the module was found in, relative to the path the scanner was invoked with.
   let file: String
 }
 
 /// Version of the `scan-modules` output shape. Bumped on any breaking change to the envelope or to
 /// `ScannedModule`, so `expo-modules-autolinking` can verify it understands the output before
-/// trusting it (and fall back to config-declared modules when it doesn't).
-let scanModulesSchemaVersion = 1
+/// trusting it (and fall back to config-declared modules when it doesn't). Version 2 added the
+/// per-module `platforms` list and made the module list platform-agnostic.
+let scanModulesSchemaVersion = 2
 
 /// The `scan-modules` result: the detected modules plus the stats describing the run. Encoded as the
 /// command's JSON output. (`scan-exports` returns its own `ScanExportsResult` shape; the two commands
@@ -73,22 +82,80 @@ struct ScanModulesResult: Codable, Equatable {
   let stats: ScanStats
 }
 
-/// Scans the given paths for top-level `@ExpoModule` types and returns the modules (in file then
-/// source order) plus the stats for the run — the `scan-modules` command. Kept separate from the
-/// public entry (and `internal`) so tests can drive it without going through argv/stdout.
-func scanModules(paths: [String], configuration: ScanBuildConfiguration = .init(platform: nil, defines: [])) -> ScanModulesResult {
-  let scan = collectDetections(paths: paths, macros: [.expoModule], configuration: configuration)
+/// The Apple OSes a scan attributes modules to. `condition` is what `os(...)` matches; `reported`
+/// is what the JSON carries. They are identical today, but stated separately so the output
+/// contract cannot drift if the matcher's spelling changes.
+private let platformUniverse: [(condition: String, reported: String)] = [
+  (condition: "iOS", reported: "iOS"),
+  (condition: "macOS", reported: "macOS"),
+  (condition: "tvOS", reported: "tvOS"),
+  (condition: "watchOS", reported: "watchOS"),
+  (condition: "visionOS", reported: "visionOS"),
+]
+
+/// Scans the given paths for top-level `@ExpoModule` types and returns every module found in any
+/// `#if` branch (in file then source order), each with the platforms whose builds include it, plus
+/// the stats for the run — the `scan-modules` command. Kept separate from the public entry (and
+/// `internal`) so tests can drive it without going through argv/stdout.
+///
+/// Each file is parsed once and walked once per platform (plus once unconditionally to enumerate
+/// every module): a module's `platforms` are the OSes whose evaluated walk reached it, given the
+/// asserted `defines`. The scanner reports the facts; filtering to the platform being linked is the
+/// consumer's call.
+func scanModules(paths: [String], defines: Set<String> = []) -> ScanModulesResult {
+  var modules: [ScannedModule] = []
+  var warnings: [ScanWarning] = []
+  var seenWarnings = Set<ScanWarning>()
+
+  let stats = scanFiles(paths: paths, macros: [.expoModule]) { source, file in
+    let tree = Parser.parse(source: source)
+
+    // The unconditional walk enumerates every module in the file, in source order.
+    let allModules = DetectionVisitor(file: file, tree: tree, detectedMacros: [.expoModule], configuration: nil)
+    allModules.walk(tree)
 
-  let modules = scan.detections.map {
-    // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")` override, else the
-    // class name.
-    ScannedModule(name: $0.name, jsName: $0.jsName ?? $0.name, accessLevel: $0.accessLevel, file: $0.file)
+    // One evaluated walk per OS attributes each module to the platforms that include it. The walks
+    // are cheap relative to the parse, which is shared.
+    var platformsByDetection: [String: [String]] = [:]
+    for platform in platformUniverse {
+      let configuration = ScanBuildConfiguration(platform: platform.condition, defines: defines)
+      let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: [.expoModule], configuration: configuration)
+      visitor.walk(tree)
+      for detection in visitor.detections {
+        platformsByDetection[detectionKey(detection), default: []].append(platform.reported)
+      }
+      // The same unanswerable condition diagnoses identically in every per-platform walk; report
+      // it once.
+      for warning in visitor.warnings where seenWarnings.insert(warning).inserted {
+        warnings.append(warning)
+      }
+    }
+
+    for detection in allModules.detections {
+      // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")` override, else
+      // the class name.
+      modules.append(
+        ScannedModule(
+          name: detection.name,
+          jsName: detection.jsName ?? detection.name,
+          accessLevel: detection.accessLevel,
+          platforms: platformsByDetection[detectionKey(detection)] ?? [],
+          file: detection.file
+        )
+      )
+    }
   }
 
   return ScanModulesResult(
     schemaVersion: scanModulesSchemaVersion,
     modules: modules,
-    warnings: scan.warnings,
-    stats: scan.stats
+    warnings: warnings,
+    stats: stats
   )
 }
+
+/// Identifies one declaration across the per-platform walks of the same tree: the source position
+/// is unique within a file, and the name guards against any position ambiguity.
+private func detectionKey(_ detection: Detection) -> String {
+  return "\(detection.line):\(detection.column):\(detection.name)"
+}