expo-modules-macros 0.18.0 → 0.19.0

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

@@ -158,7 +158,8 @@ struct ExportedEvent: Encodable, Equatable {
 
 /// A `@ExpoModule` type and its `@JS` surface.
 struct ExportedModule: Encodable, Equatable {
-  /// The Swift class name.
+  /// The Swift class name. A module is always declared at file scope, since autolinking registers no
+  /// other.
   let name: String
 
   /// The JS module name: `@ExpoModule("Foo")` override, else the class name.
@@ -178,7 +179,9 @@ struct ExportedModule: Encodable, Equatable {
 
 /// One entry of `@ExpoModule(classes: [...])`.
 struct ExportedClass: Encodable, Equatable {
-  /// The Swift name as spelled in the argument, e.g. `Database` or `Outer.Statement`.
+  /// The `name` of the matching `@SharedObject`, which is qualified when the class is nested
+  /// (`Outer.Statement`). The Swift name as spelled in the argument when the scan found no
+  /// `@SharedObject` with this name.
   let name: String
 
   /// The name of the module member JS reads the class from: the matching `@SharedObject`'s `jsName`.
@@ -189,10 +192,11 @@ struct ExportedClass: Encodable, Equatable {
 
 /// A `@SharedObject` type: a JS class with an optional `@JS init` constructor plus its `@JS` members.
 struct ExportedSharedObject: Encodable, Equatable {
-  /// The Swift class name.
+  /// The Swift class name, qualified with the types it is nested in (`Outer.Player`).
   let name: String
 
-  /// The JS class name: `@SharedObject("Foo")` override, else the class name.
+  /// The JS class name: `@SharedObject("Foo")` override, else the class name without the enclosing
+  /// types.
   let jsName: String
 
   /// The `@JS init` parameters, or `nil` when there's none. A shared object has at most one.
@@ -207,7 +211,8 @@ struct ExportedSharedObject: Encodable, Equatable {
 
 /// A `@Record` type and its properties (data only: no functions, accessors, or constructor).
 struct ExportedRecord: Encodable, Equatable {
-  /// The Swift type name (struct or class).
+  /// The Swift type name (struct or class), qualified with the types it is nested in
+  /// (`Outer.Options`).
   let name: String
 
   let properties: [ExportedRecordProperty]
@@ -247,8 +252,9 @@ struct ExportedEnumCase: Encodable, Equatable {
 /// 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.
+  /// The Swift enum name, qualified with the types it is nested in (`Options.Encoding`). 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
@@ -296,8 +302,9 @@ struct ExportedUnionMember: Encodable, Equatable {
 /// `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.
+  /// The Swift enum name, qualified with the types it is nested in (`Options.Value`). 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]
@@ -320,8 +327,9 @@ struct ExportedSurface: Encodable, Equatable {
 /// 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`; version 6 added `classes` to modules.
-let scanExportsSchemaVersion = 6
+/// an enum ref's `typeof`; version 6 added `classes` to modules; version 7 reports nested types under
+/// qualified names and gives a resolved ref the name of its declaration.
+let scanExportsSchemaVersion = 7
 
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).

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

@@ -5,65 +5,88 @@
 /// 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:
+/// A name is looked up the way Swift looks it up: from the type the use site is written in, outward to
+/// file scope. In `Options`, `Encoding` names `Options.Encoding` when the scan declares one, else a
+/// file-scope `Encoding`.
+///
+/// Three things change on a resolved ref:
+/// - `name` becomes the declaration's qualified name, so a consumer can match it to the declaration
+///   without repeating the scoped lookup.
 /// - `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.
+/// A name the scan never declared keeps its spelling, `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)] = [:]
+  /// The declaration a ref resolves to.
+  struct Entry: Equatable {
+    /// The declaration's qualified name.
+    let name: String
+    let kind: RefKind
+    /// The JS category a ref to the declaration crosses as.
+    let jsType: JSType
+    /// A `@SharedObject`'s JS name, `nil` for every other kind.
+    var jsName: String? = nil
+  }
 
-  /// A `@SharedObject`'s Swift name -> its JS name.
-  private var sharedObjectJSNames: [String: String] = [:]
+  /// A declaration's qualified name -> its entry.
+  private var entries: [String: Entry] = [:]
 
   init(surface: ExportedSurface) {
     for record in surface.records {
-      entries[record.name] = (.record, .object)
+      entries[record.name] = Entry(name: record.name, kind: .record, jsType: .object)
     }
     for sharedObject in surface.sharedObjects {
-      entries[sharedObject.name] = (.sharedObject, .object)
-      sharedObjectJSNames[sharedObject.name] = sharedObject.jsName
+      entries[sharedObject.name] = Entry(
+        name: sharedObject.name, kind: .sharedObject, jsType: .object, jsName: sharedObject.jsName)
     }
     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)
+      entries[union.name] = Entry(name: union.name, kind: .union, jsType: .object)
     }
     for enumeration in surface.enums {
-      entries[enumeration.name] = (.enum, jsType(ofRawType: enumeration.rawType))
+      entries[enumeration.name] = Entry(
+        name: enumeration.name, kind: .enum, jsType: 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)? {
-    lookupQualified(name, in: entries)
-  }
-
-  /// The JS name of the `@SharedObject` declared as `name`, or `nil` when the scan declares none.
-  func sharedObjectJSName(_ name: String) -> String? {
-    lookupQualified(name, in: sharedObjectJSNames)
-  }
-}
-
-/// The value for `name` in `table`, falling back to its trailing component. A qualified use site
-/// (`Media.Status`) names the same type a bare declaration did, which is how the conformance and
-/// raw-type checks already match names.
-private func lookupQualified<Value>(_ name: String, in table: [String: Value]) -> Value? {
-  if let value = table[name] {
-    return value
-  }
-  guard let trailing = name.split(separator: ".").last.map(String.init), trailing != name else {
+  /// The declaration a ref to `name` written inside the type `scope` resolves to, or `nil` when the
+  /// scan declares no such type. `scope` is the qualified name of the type the use site is written
+  /// in.
+  ///
+  /// The name is first looked up in `scope` and then in each enclosing scope out to file scope, so the
+  /// innermost declaration wins, as in Swift. A leading `Self.` names `scope` itself, so it is dropped
+  /// before the lookup. When that finds nothing, the leading components of a qualified spelling are
+  /// dropped one at a time (`Media.Status` -> `Status`): a use site may qualify a name with a module
+  /// the scan doesn't see, which is how the conformance and raw-type checks already match names.
+  func lookup(_ name: String, in scope: String) -> Entry? {
+    let name = name.hasPrefix("Self.") ? String(name.dropFirst("Self.".count)) : name
+    var components = scope.split(separator: ".").map(String.init)
+    while true {
+      if let entry = entries[(components + [name]).joined(separator: ".")] {
+        return entry
+      }
+      if components.isEmpty {
+        break
+      }
+      components.removeLast()
+    }
+    var suffix = name.split(separator: ".").map(String.init).dropFirst()
+    while !suffix.isEmpty {
+      if let entry = entries[suffix.joined(separator: ".")] {
+        return entry
+      }
+      suffix = suffix.dropFirst()
+    }
     return nil
   }
-  return table[trailing]
 }
 
 /// The JS category a raw-value enum crosses as: its raw value's. A bare `Enumerable` conformance with
@@ -76,32 +99,35 @@ private func jsType(ofRawType rawType: TypeNode?) -> 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 {
+  /// This node with every `.ref` in it resolved against `index` from the type `scope`, recursively.
+  /// Returns an unchanged node when nothing in it resolves.
+  func resolvingRefs(using index: RefIndex, in scope: String) -> TypeNode {
     switch self {
     case .primitive, .unknown:
       return self
     case .ref(let name, _, _):
-      guard let entry = index.lookup(name) else {
+      guard let entry = index.lookup(name, in: scope) 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)
+        name: entry.name,
+        refKind: entry.kind,
+        jsTypeOverride: entry.jsType == .object ? nil : entry.jsType)
     case .optional(let wrapped):
-      return .optional(wrapped: wrapped.resolvingRefs(using: index))
+      return .optional(wrapped: wrapped.resolvingRefs(using: index, in: scope))
     case .array(let element):
-      return .array(element: element.resolvingRefs(using: index))
+      return .array(element: element.resolvingRefs(using: index, in: scope))
     case .dictionary(let key, let value):
       return .dictionary(
-        key: key.resolvingRefs(using: index), value: value.resolvingRefs(using: index))
+        key: key.resolvingRefs(using: index, in: scope),
+        value: value.resolvingRefs(using: index, in: scope))
     case .promise(let value):
-      return .promise(value: value.resolvingRefs(using: index))
+      return .promise(value: value.resolvingRefs(using: index, in: scope))
     case .function(let parameters, let returns, let isAsync, let isThrowing):
       return .function(
-        parameters: parameters.map { $0.resolvingRefs(using: index) },
-        returns: returns?.resolvingRefs(using: index),
+        parameters: parameters.map { $0.resolvingRefs(using: index, in: scope) },
+        returns: returns?.resolvingRefs(using: index, in: scope),
         isAsync: isAsync,
         isThrowing: isThrowing
       )
@@ -113,9 +139,10 @@ 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.
+  /// Each type's refs are looked up from that type, so a ref resolves to a type nested in it before
+  /// one at file scope. 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(
@@ -123,11 +150,15 @@ extension ExportedSurface {
         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) },
-          classes: module.classes.map {
-            ExportedClass(name: $0.name, jsName: index.sharedObjectJSName($0.name))
+          functions: module.functions.map { $0.resolvingRefs(using: index, in: module.name) },
+          properties: module.properties.map { $0.resolvingRefs(using: index, in: module.name) },
+          events: module.events.map { $0.resolvingRefs(using: index, in: module.name) },
+          classes: module.classes.map { exportedClass in
+            guard let entry = index.lookup(exportedClass.name, in: module.name),
+              entry.kind == .sharedObject else {
+              return exportedClass
+            }
+            return ExportedClass(name: entry.name, jsName: entry.jsName)
           },
           file: module.file
         )
@@ -136,10 +167,12 @@ extension ExportedSurface {
         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) },
+          constructorParameters: sharedObject.constructorParameters?.map {
+            $0.resolvingRefs(using: index, in: sharedObject.name)
+          },
+          functions: sharedObject.functions.map { $0.resolvingRefs(using: index, in: sharedObject.name) },
+          properties: sharedObject.properties.map { $0.resolvingRefs(using: index, in: sharedObject.name) },
+          events: sharedObject.events.map { $0.resolvingRefs(using: index, in: sharedObject.name) },
           file: sharedObject.file
         )
       },
@@ -149,7 +182,7 @@ extension ExportedSurface {
           properties: record.properties.map { property in
             ExportedRecordProperty(
               name: property.name,
-              type: property.type.resolvingRefs(using: index),
+              type: property.type.resolvingRefs(using: index, in: record.name),
               isOptional: property.isOptional,
               hasDefault: property.hasDefault
             )
@@ -164,7 +197,8 @@ extension ExportedSurface {
         ExportedUnion(
           name: union.name,
           members: union.members.map { member in
-            ExportedUnionMember(name: member.name, type: member.type.resolvingRefs(using: index))
+            ExportedUnionMember(
+              name: member.name, type: member.type.resolvingRefs(using: index, in: union.name))
           },
           file: union.file
         )
@@ -174,19 +208,19 @@ extension ExportedSurface {
 }
 
 extension ExportedParameter {
-  fileprivate func resolvingRefs(using index: RefIndex) -> ExportedParameter {
+  fileprivate func resolvingRefs(using index: RefIndex, in scope: String) -> ExportedParameter {
     return ExportedParameter(
-      label: label, name: name, type: type.resolvingRefs(using: index), isOptional: isOptional)
+      label: label, name: name, type: type.resolvingRefs(using: index, in: scope), isOptional: isOptional)
   }
 }
 
 extension ExportedFunction {
-  fileprivate func resolvingRefs(using index: RefIndex) -> ExportedFunction {
+  fileprivate func resolvingRefs(using index: RefIndex, in scope: String) -> ExportedFunction {
     return ExportedFunction(
       name: name,
       jsName: jsName,
-      parameters: parameters.map { $0.resolvingRefs(using: index) },
-      returns: returns?.resolvingRefs(using: index),
+      parameters: parameters.map { $0.resolvingRefs(using: index, in: scope) },
+      returns: returns?.resolvingRefs(using: index, in: scope),
       isAsync: isAsync,
       isThrowing: isThrowing,
       isStatic: isStatic
@@ -195,11 +229,11 @@ extension ExportedFunction {
 }
 
 extension ExportedProperty {
-  fileprivate func resolvingRefs(using index: RefIndex) -> ExportedProperty {
+  fileprivate func resolvingRefs(using index: RefIndex, in scope: String) -> ExportedProperty {
     return ExportedProperty(
       name: name,
       jsName: jsName,
-      type: type?.resolvingRefs(using: index),
+      type: type?.resolvingRefs(using: index, in: scope),
       isSettable: isSettable,
       isStatic: isStatic
     )
@@ -207,8 +241,8 @@ extension ExportedProperty {
 }
 
 extension ExportedEvent {
-  fileprivate func resolvingRefs(using index: RefIndex) -> ExportedEvent {
+  fileprivate func resolvingRefs(using index: RefIndex, in scope: String) -> ExportedEvent {
     return ExportedEvent(
-      name: name, jsName: jsName, payload: payload?.resolvingRefs(using: index), isSync: isSync)
+      name: name, jsName: jsName, payload: payload?.resolvingRefs(using: index, in: scope), isSync: isSync)
   }
 }

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

@@ -1,10 +1,14 @@
 import SwiftSyntax
 
-/// Extracts the full JS-exported surface of every top-level `@ExpoModule`, `@SharedObject`, and
-/// `@Record` type: their `@JS` members and record properties. The deep counterpart to
-/// `DetectionVisitor`. Recognition is purely syntactic and re-reads what the macros read (the macro
-/// target can't be imported), so it stays in step with `JSFunction` / `JSProperty` / `JSConstructor` /
+/// Extracts the full JS-exported surface of every `@ExpoModule`, `@SharedObject`, and `@Record` type:
+/// their `@JS` members and record properties. The deep counterpart to `DetectionVisitor`.
+/// Recognition is purely syntactic and re-reads what the macros read (the macro target can't be
+/// imported), so it stays in step with `JSFunction` / `JSProperty` / `JSConstructor` /
 /// `RecordProperty`.
+///
+/// Types nested in another type's body, or in a file-scope `extension`, are reported under their
+/// qualified Swift name (`Options.Encoding`), so a ref to one can be resolved from the scope it is
+/// written in. A type declared in a function body or a closure is local and is not reported.
 final class SurfaceVisitor: SyntaxVisitor {
   private let file: String
   private(set) var modules: [ExportedModule] = []
@@ -19,19 +23,48 @@ final class SurfaceVisitor: SyntaxVisitor {
   }
 
   override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {
-    if isTopLevel(node) {
-      classify(name: node.name.identifierName, attributes: node.attributes, members: node.memberBlock.members)
+    guard let scope = enclosingTypes(of: node) else {
+      return .skipChildren
     }
-    // The member walk reads the body itself; nested types aren't part of this surface (matching
-    // `DetectionVisitor`'s top-level-only scope), so there's no reason to descend.
-    return .skipChildren
+    classify(
+      name: node.name.identifierName, scope: scope, attributes: node.attributes, members: node.memberBlock.members)
+    // The member walk reads the body itself; the children are visited only to find nested types.
+    return .visitChildren
   }
 
   override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind {
-    if isTopLevel(node) {
-      classify(name: node.name.identifierName, attributes: node.attributes, members: node.memberBlock.members)
+    guard let scope = enclosingTypes(of: node) else {
+      return .skipChildren
     }
-    return .skipChildren
+    classify(
+      name: node.name.identifierName, scope: scope, attributes: node.attributes, members: node.memberBlock.members)
+    return .visitChildren
+  }
+
+  override func visit(_ node: ActorDeclSyntax) -> SyntaxVisitorContinueKind {
+    // No macro the surface reports applies to an actor, but its body can declare types that do.
+    enclosingTypes(of: node) == nil ? .skipChildren : .visitChildren
+  }
+
+  override func visit(_ node: ExtensionDeclSyntax) -> SyntaxVisitorContinueKind {
+    // Only for the types declared in its body. Members an extension adds to a module, shared object,
+    // or record are not part of the surface, since the macros only read the type's own body.
+    enclosingTypes(of: node) == nil ? .skipChildren : .visitChildren
+  }
+
+  // A type declared in a function or accessor body or in a closure is local and never reported, so
+  // these are not walked.
+
+  override func visit(_ node: CodeBlockSyntax) -> SyntaxVisitorContinueKind {
+    .skipChildren
+  }
+
+  override func visit(_ node: AccessorBlockSyntax) -> SyntaxVisitorContinueKind {
+    .skipChildren
+  }
+
+  override func visit(_ node: ClosureExprSyntax) -> SyntaxVisitorContinueKind {
+    .skipChildren
   }
 
   /// The two kinds of enum the surface reports: a `@Union` by its attribute, an `Enumerable` enum by
@@ -41,14 +74,15 @@ final class SurfaceVisitor: SyntaxVisitor {
   /// 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 {
+    guard let scope = enclosingTypes(of: node) else {
       return .skipChildren
     }
+    let name = qualifiedName(node.name.identifierName, in: scope)
 
     if node.attributes.firstAttribute(named: DetectedMacro.union.rawValue) != nil {
       unions.append(
         ExportedUnion(
-          name: node.name.identifierName,
+          name: name,
           members: collectUnionMembers(node.memberBlock.members),
           file: file
         ))
@@ -56,24 +90,38 @@ final class SurfaceVisitor: SyntaxVisitor {
       let rawType = rawValueType(of: node.inheritanceClause)
       enums.append(
         ExportedEnum(
-          name: node.name.identifierName,
+          name: name,
           rawType: rawType,
           cases: collectEnumCases(node.memberBlock.members, rawType: rawType),
           file: file
         ))
     }
-    return .skipChildren
+    // An enum is often a namespace for other types, so its body is searched too.
+    return .visitChildren
   }
 
-  /// Routes a top-level type to the right collector based on which Expo macro it carries. A type
+  /// Routes a class or struct 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) {
+  ///
+  /// `name` is the declared name and `scope` the names of the types enclosing it. The reported `name`
+  /// is qualified with the scope, while a default `jsName` is the declared name alone, as the macros
+  /// spell it.
+  private func classify(
+    name: String, scope: [String], attributes: AttributeListSyntax, members: MemberBlockItemListSyntax
+  ) {
+    let qualified = qualifiedName(name, in: scope)
+
     if let attribute = attributes.firstAttribute(named: DetectedMacro.expoModule.rawValue) {
+      // Only a file-scope module is reported. Autolinking registers no other (`DetectionVisitor`
+      // reads file scope only), so a nested one never loads.
+      guard scope.isEmpty else {
+        return
+      }
       let (functions, properties, events, _) = collectJSMembers(members)
       modules.append(
         ExportedModule(
-          name: name,
+          name: qualified,
           jsName: stringArgument(of: attribute) ?? name,
           functions: functions,
           properties: properties,
@@ -92,7 +140,7 @@ final class SurfaceVisitor: SyntaxVisitor {
       let (functions, properties, events, constructor) = collectJSMembers(members)
       sharedObjects.append(
         ExportedSharedObject(
-          name: name,
+          name: qualified,
           jsName: stringArgument(of: attribute) ?? name,
           constructorParameters: constructor,
           functions: functions,
@@ -104,7 +152,7 @@ final class SurfaceVisitor: SyntaxVisitor {
     }
 
     if attributes.firstAttribute(named: DetectedMacro.record.rawValue) != nil {
-      records.append(ExportedRecord(name: name, properties: collectRecordProperties(members), file: file))
+      records.append(ExportedRecord(name: qualified, properties: collectRecordProperties(members), file: file))
     }
   }
 
@@ -364,16 +412,40 @@ final class SurfaceVisitor: SyntaxVisitor {
     }
   }
 
-  /// True when the declaration sits at file scope. Same rule as `DetectionVisitor.isTopLevel`: its
-  /// parent is a `CodeBlockItemSyntax` directly under the source file's top-level item list.
-  private func isTopLevel(_ node: some SyntaxProtocol) -> Bool {
-    guard let item = node.parent?.as(CodeBlockItemSyntax.self) else {
-      return false
+  /// The names of the types enclosing a declaration, outermost first: empty at file scope, and `nil`
+  /// when the declaration is local to a function body or a closure, or sits in a `#if` block.
+  ///
+  /// File scope uses the same rule as `DetectionVisitor.isTopLevel`, except that `#if` is not looked
+  /// through: the parent is a `CodeBlockItemSyntax` directly under the source file's top-level item
+  /// list. A member is reached from its type through `MemberBlockItemSyntax`; an `extension`
+  /// contributes its extended type as written (without backticks), so its spelling may already be
+  /// qualified.
+  private func enclosingTypes(of node: some SyntaxProtocol) -> [String]? {
+    if let item = node.parent?.as(CodeBlockItemSyntax.self) {
+      return item.parent?.parent?.is(SourceFileSyntax.self) == true ? [] : nil
     }
-    return item.parent?.parent?.is(SourceFileSyntax.self) == true
+    guard let item = node.parent?.as(MemberBlockItemSyntax.self),
+      let parent = item.parent?.parent?.parent,
+      let scope = enclosingTypes(of: parent) else {
+      return nil
+    }
+    if let decl = parent.as(ExtensionDeclSyntax.self) {
+      // Without backticks, like every other reported name.
+      return scope + [String(decl.extendedType.trimmedDescription.filter { $0 != "`" })]
+    }
+    // A class, struct, enum, or actor. A protocol body cannot declare types.
+    guard !parent.is(ProtocolDeclSyntax.self), let decl = parent.asProtocol(NamedDeclSyntax.self) else {
+      return nil
+    }
+    return scope + [decl.name.identifierName]
   }
 }
 
+/// A declared name qualified with the names of its enclosing types: `Options.Encoding`.
+private func qualifiedName(_ name: String, in scope: [String]) -> String {
+  (scope + [name]).joined(separator: ".")
+}
+
 // MARK: - Syntactic helpers (shared spelling with the macros)
 
 extension TokenSyntax {

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

@@ -58,7 +58,9 @@ indirect enum TypeNode: Equatable {
   case function(parameters: [TypeNode], returns: TypeNode?, isAsync: Bool, isThrowing: Bool)
 
   /// Any other named type (record, shared object, enum, union, …). `name` is the possibly-qualified
-  /// spelling.
+  /// spelling until resolution. A resolved ref takes the qualified name of its declaration instead,
+  /// so `Encoding` written in `Options` becomes `Options.Encoding`, and a consumer finds the
+  /// declaration by an exact match.
   ///
   /// `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