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

package/apple/Sources/ExpoModulesMacros/UnionMacro.swift

@@ -0,0 +1,365 @@
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/// Member + extension macro applied to an `enum` whose cases each carry one associated value: a typed
+/// union of the payload types (`A | B | C` in TypeScript). The enum is a tagged union at the Swift
+/// level, so the author switches over it exhaustively with each payload keeping its static type, and
+/// the macro synthesizes the conversion surface that makes it a JS boundary type:
+///
+/// - `decode(_:in:)`: an ordered decode that tries each case's payload converter in declaration order
+///   and returns the first case that decodes; when none does, it throws
+///   `Exceptions.UnionCaseMismatch` naming the union, the JS kind received, and the alternatives.
+/// - `encode(_:in:)`: a `switch` over the cases, encoding the payload through its own type.
+/// - `as(_:)`: one throwing overload per case, keyed by the payload's metatype, returning that payload
+///   (`try source.as(String.self)` is `String`; `try? source.as(String.self)` is `String?`). It unwraps
+///   by type without naming the case and throws `Exceptions.UnionCaseMismatch` when the union holds a
+///   different case. Since a payload type may appear only once, each overload is unambiguous, and asking
+///   for a type the union doesn't carry is a compile error.
+///
+/// The type is auto-conformed to `JavaScriptDecodable` and `JavaScriptEncodable`, so it can be a `@JS`
+/// argument or return value, an `@Event` payload, or nested inside an optional, array, or dictionary.
+/// Author-facing shape:
+///
+///   @Union
+///   enum Source {
+///     case text(String)
+///     case options(SourceOptions)   // a @Record
+///   }
+///
+/// Discrimination is structural and order-dependent: the first case whose payload decodes wins. When
+/// two payload shapes overlap (two records with compatible fields, `Int` and `Double`), the earlier
+/// case matches; the author orders the more specific case first. A case may not repeat another case's
+/// payload type, since it could never be chosen.
+///
+/// The named-union counterpart of core's `Either`: any number of named cases instead of two anonymous
+/// slots, no `Any?` box, and an exhaustive `switch` as the primary way to read it (`as(_:)` covers the
+/// one-type lookup `Either.as(_:)` offered, with the same throwing shape).
+public struct UnionMacro: MemberMacro, ExtensionMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingMembersOf declaration: some DeclGroupSyntax,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    let union = try validatedUnion(of: declaration)
+
+    var members: [DeclSyntax] = []
+
+    // A single never-called member that makes the compiler verify each payload type converts both
+    // ways. Each case keeps its own named assertion inside, so the conformance diagnostic names the
+    // offending case (see `typeConformanceAssertions`). Emitted first so a non-conforming payload
+    // reports the clear "requires that '…' conform to …" error ahead of the noisier "no member
+    // 'decode'"/"'encode'" errors from the conversion code below.
+    let assertions = union.cases.map { ConformanceAssertion(name: $0.name, types: [$0.payloadType]) }
+    if let assertionMember = typeConformanceAssertions(for: assertions, constraint: unionPayloadProtocolName) {
+      members.append(assertionMember)
+    }
+
+    members.append(decodeMethod(union: union))
+    members.append(encodeMethod(union: union))
+    members.append(contentsOf: accessorMethods(union: union))
+    members.append(payloadTypeNameProperty(union: union))
+    return members
+  }
+
+  /// Auto-conforms the enum to `JavaScriptDecodable` and `JavaScriptEncodable`, the protocols whose
+  /// requirements are exactly the `decode`/`encode` members synthesized above. A conformance the author
+  /// already spelled out in the inheritance clause is not repeated.
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingExtensionsOf type: some TypeSyntaxProtocol,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [ExtensionDeclSyntax] {
+    // Diagnostics are owned by the member expansion; an invalid declaration silently emits no extension
+    // here, so each error is reported once and no witness-less conformance piles "does not conform"
+    // errors on top of it.
+    guard (try? validatedUnion(of: declaration)) != nil else {
+      return []
+    }
+    // The compiler hands over only the conformances the type still lacks; the test harness passes the
+    // declared list verbatim, so filter against the inheritance clause here as well.
+    let missing = protocols.filter { protocolType in
+      guard let name = baseIdentifier(of: protocolType) else {
+        return true
+      }
+      return !inheritsProtocol(named: name, in: declaration)
+    }
+    guard !missing.isEmpty else {
+      return []
+    }
+
+    let conformances = missing.map { $0.trimmedDescription }.joined(separator: ", ")
+    let ext: DeclSyntax = """
+      extension \(type.trimmed): \(raw: conformances) {}
+      """
+    guard let extDecl = ext.as(ExtensionDeclSyntax.self) else {
+      return []
+    }
+    return [extDecl]
+  }
+}
+
+// MARK: - Union model
+
+/// A validated `@Union` enum: its spelled name (for the mismatch error) and its cases in declaration
+/// order (the decode order).
+private struct UnionType {
+  let name: String
+  let cases: [UnionCase]
+}
+
+/// One alternative of the union: the case name, its single payload type as written, and the payload's
+/// argument label when the author gave it one (`case id(value: Int)`), needed to construct the case.
+private struct UnionCase {
+  let name: String
+  let payloadType: String
+  let payloadLabel: String?
+
+  /// The expression constructing this case from a `payload` local: `.id(payload)`, or
+  /// `.id(value: payload)` for a labeled associated value.
+  var construction: String {
+    if let payloadLabel {
+      return ".\(name)(\(payloadLabel): payload)"
+    }
+    return ".\(name)(payload)"
+  }
+
+  /// The pattern binding this case's payload to a `payload` local in a `switch`.
+  var pattern: String {
+    return ".\(name)(let payload)"
+  }
+}
+
+/// Reads and validates the union off the attached declaration. Every check is a compile error located
+/// on the offending node: the macro must be on a non-generic `enum` with at least one case, and every
+/// case must carry exactly one associated value, its payload type distinct from every earlier case's.
+private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> UnionType {
+  guard let enumDecl = declaration.as(EnumDeclSyntax.self) else {
+    throw MacroExpansionErrorMessage("@Union can only be applied to an enum")
+  }
+  if let genericParameterClause = enumDecl.genericParameterClause {
+    throw DiagnosticsError(diagnostics: [
+      Diagnostic(
+        node: genericParameterClause,
+        message: UnionDiagnosticMessage(
+          "@Union cannot be applied to a generic enum: each case's payload type must be concrete so the macro can select its converter.",
+          id: "union-generic-enum"
+        ))
+    ])
+  }
+
+  var cases: [UnionCase] = []
+  var seenPayloadTypes: [String: String] = [:]
+  var diagnostics: [Diagnostic] = []
+
+  for member in enumDecl.memberBlock.members {
+    guard let caseDecl = member.decl.as(EnumCaseDeclSyntax.self) else {
+      continue
+    }
+    for element in caseDecl.elements {
+      let name = element.name.text
+      guard let parameters = element.parameterClause?.parameters, !parameters.isEmpty else {
+        diagnostics.append(
+          Diagnostic(
+            node: element,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' must carry exactly one associated value: the type this alternative decodes from. A payload-less enum is not a union; make it a raw-value enum conforming to 'Enumerable' instead.",
+              id: "union-case-without-payload"
+            )))
+        continue
+      }
+      guard parameters.count == 1, let parameter = parameters.first else {
+        diagnostics.append(
+          Diagnostic(
+            node: element,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' must carry exactly one associated value, but has \(parameters.count). Group them in a @Record type and use it as the single payload.",
+              id: "union-case-with-multiple-payloads"
+            )))
+        continue
+      }
+
+      // A default on the associated value can never apply: the macro constructs the case from the
+      // decoded JS value every time, and there is no "omitted" slot the way a `@Record` property has.
+      // Left in place it would read as a JS-side default that doesn't exist, so it's rejected with a
+      // fix-it that removes it.
+      if let defaultValue = parameter.defaultValue {
+        diagnostics.append(defaultValueDiagnostic(for: parameter, defaultValue: defaultValue, caseName: name))
+        continue
+      }
+
+      let payloadType = parameter.type.trimmedDescription
+      // Alternatives decode in declaration order and the first success wins, so a case whose payload
+      // type repeats an earlier case's is unreachable: an exact-spelling duplicate is an error. (An
+      // overlap between *different* types, like `Int` and `Double`, is the author's ordering call and
+      // isn't checked here.)
+      let normalizedType = payloadType.filter { !$0.isWhitespace }
+      if let earlierCase = seenPayloadTypes[normalizedType] {
+        diagnostics.append(
+          Diagnostic(
+            node: element,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' repeats the payload type '\(payloadType)' of case '\(earlierCase)' and can never be decoded: alternatives are tried in declaration order and the first match wins.",
+              id: "union-duplicate-payload-type"
+            )))
+        continue
+      }
+      seenPayloadTypes[normalizedType] = name
+
+      // `firstName` is the associated value's label (`case id(value: Int)`); a `_` label is the same as
+      // none for construction purposes.
+      let label = parameter.firstName.flatMap { $0.text == "_" ? nil : $0.text }
+      cases.append(UnionCase(name: name, payloadType: payloadType, payloadLabel: label))
+    }
+  }
+
+  if !diagnostics.isEmpty {
+    throw DiagnosticsError(diagnostics: diagnostics)
+  }
+  if cases.isEmpty {
+    throw MacroExpansionErrorMessage("@Union requires at least one case carrying an associated value")
+  }
+  return UnionType(name: enumDecl.name.text, cases: cases)
+}
+
+// MARK: - Synthesized members
+
+/// `decode(_:in:)`: tries each case's payload converter in declaration order and returns the first
+/// case that decodes. `try?` turns a candidate's failure into "try the next one" without erasing the
+/// payload (each `payload` local keeps its concrete type); the candidate's own error is discarded, since
+/// with several alternatives there is no single failure to surface. When no alternative accepts the
+/// value the factory throws `Exceptions.UnionCaseMismatch`, naming the union, the JS kind of the value
+/// received, and every payload type the union accepts.
+private func decodeMethod(union: UnionType) -> DeclSyntax {
+  var lines: [String] = []
+  for unionCase in union.cases {
+    let payloadType = expressionType(unionCase.payloadType)
+    lines.append("  if let payload = try? \(payloadType).decode(value, in: runtime) {")
+    lines.append("    return \(unionCase.construction)")
+    lines.append("  }")
+  }
+  let expected = union.cases.map { "\"\($0.payloadType)\"" }.joined(separator: ", ")
+  let mismatch = "(unionName: \"\(union.name)\", received: value.kind.rawValue, expected: [\(expected)])"
+  lines.append("  throw Exceptions.UnionCaseMismatch(\(mismatch))")
+  let body = lines.joined(separator: "\n")
+  return """
+    @JavaScriptActor
+    public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Self {
+    \(raw: body)
+    }
+    """
+}
+
+/// `encode(_:in:)`: a `switch` over the cases, each encoding its payload through the payload type's
+/// own `encode`. Exhaustive by construction, so a case added later without re-expansion can't slip
+/// through silently.
+private func encodeMethod(union: UnionType) -> DeclSyntax {
+  var lines: [String] = ["  switch value {"]
+  for unionCase in union.cases {
+    lines.append("  case \(unionCase.pattern):")
+    lines.append("    return try \(expressionType(unionCase.payloadType)).encode(payload, in: runtime)")
+  }
+  lines.append("  }")
+  let body = lines.joined(separator: "\n")
+  return """
+    @JavaScriptActor
+    public static func encode(_ value: Self, in runtime: borrowing JavaScriptRuntime) throws -> JavaScriptValue {
+    \(raw: body)
+    }
+    """
+}
+
+/// `as(_:)`: a typed accessor per case, selected by the payload's metatype rather than the case name,
+/// so a caller that only knows the type it wants writes `try value.as(String.self)` and gets a `String`.
+/// When
+/// the union holds a different case it throws `Exceptions.UnionCaseMismatch`, the same error `decode`
+/// throws, with the held case's payload type as `received` and the requested type as `expected`. The
+/// overloads can't collide because a payload type appears in at most one case (enforced above), and a
+/// metatype the union doesn't carry fails to resolve at compile time. `as` is a keyword, so the
+/// declaration is backticked; a call site after a dot (`value.as(…)`) needs no backticks. The parameter
+/// is spelled in expression form (`T!` rewritten to `T?`), since `T!.Type` isn't valid.
+private func accessorMethods(union: UnionType) -> [DeclSyntax] {
+  return union.cases.map { unionCase in
+    let payloadType = expressionType(unionCase.payloadType)
+    let mismatch = "(unionName: \"\(union.name)\", received: _payloadTypeName, expected: [\"\(unionCase.payloadType)\"])"
+    return """
+      public func `as`(_ type: \(raw: payloadType).Type) throws -> \(raw: payloadType) {
+        if case \(raw: unionCase.pattern) = self {
+          return payload
+        }
+        throw Exceptions.UnionCaseMismatch(\(raw: mismatch))
+      }
+      """
+  }
+}
+
+/// `_payloadTypeName`: the spelled payload type of the case the union currently holds, as written in the
+/// declaration, so every `as(_:)` overload reports the actual type in its mismatch error through one
+/// shared `switch` instead of each overload enumerating the other cases.
+private func payloadTypeNameProperty(union: UnionType) -> DeclSyntax {
+  var lines: [String] = ["  switch self {"]
+  for unionCase in union.cases {
+    lines.append("  case .\(unionCase.name):")
+    lines.append("    return \"\(unionCase.payloadType)\"")
+  }
+  lines.append("  }")
+  let body = lines.joined(separator: "\n")
+  return """
+    private var _payloadTypeName: String {
+    \(raw: body)
+    }
+    """
+}
+
+// MARK: - Diagnostics
+
+/// The error for a default value on a case's associated value, attached to the `= …` clause and carrying
+/// a fix-it that deletes it (trimming the space the type carried before the `=`).
+private func defaultValueDiagnostic(
+  for parameter: EnumCaseParameterSyntax,
+  defaultValue: InitializerClauseSyntax,
+  caseName: String
+) -> Diagnostic {
+  let fixIt = FixIt(
+    message: UnionFixItMessage("Remove the default value", id: "union-remove-default-value"),
+    changes: [
+      .replace(
+        oldNode: Syntax(parameter),
+        newNode: Syntax(
+          parameter
+            .with(\.type, parameter.type.with(\.trailingTrivia, []))
+            .with(\.defaultValue, nil))
+      )
+    ]
+  )
+  let message = UnionDiagnosticMessage(
+    "@Union case '\(caseName)' cannot give its associated value a default: the payload is always decoded from the JavaScript value, so the default would never apply. Remove '\(defaultValue.trimmedDescription)'.",
+    id: "union-case-default-value"
+  )
+  return Diagnostic(node: defaultValue, message: message, fixIts: [fixIt])
+}
+
+private struct UnionDiagnosticMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID: MessageID
+  let severity: DiagnosticSeverity = .error
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+private struct UnionFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}

package/apple/Sources/ExpoModulesScanner/CLI.swift

@@ -0,0 +1,110 @@
+import Foundation
+
+/// Command-line front end for the scanner: parses the subcommand and paths, then delegates to the
+/// matching `Scanner` entry (which runs the scan and writes its JSON output). Lives in the library
+/// so the macro plugin executable can dispatch into it: the compiler always launches that executable
+/// without arguments and speaks the plugin protocol over stdin, so any argument means a scanner
+/// invocation. Each path may be a `.swift` file or a directory (scanned recursively for `.swift`
+/// files).
+///
+/// Subcommands:
+///   scan-modules   <path>...   fast: top-level `@ExpoModule` types, for autolinking
+///   scan-exports   <path>...   deep: full JS-exported surface, for TS type generation
+public enum ScannerCLI {
+  /// Runs the CLI for the given arguments (argv without the executable path) and returns the
+  /// process exit code: `0` on success, `1` if encoding the report fails, `2` on a usage error.
+  public static func run(arguments: [String]) -> Int32 {
+    // `-h`/`--help` anywhere is treated as a help request: print usage to stdout and exit 0.
+    if arguments.contains(where: { $0 == "-h" || $0 == "--help" }) {
+      printUsage(to: .standardOutput)
+      return 0
+    }
+
+    guard let subcommand = arguments.first else {
+      printUsage()
+      return 2
+    }
+
+    var paths: [String] = []
+    var platform: String?
+    var defines: [String] = []
+
+    var rest = arguments.dropFirst().makeIterator()
+    while let argument = rest.next() {
+      switch argument {
+      case "--platform":
+        guard let value = rest.next() else {
+          return usageError("--platform requires a value")
+        }
+        platform = value
+      case "--define":
+        guard let value = rest.next() else {
+          return usageError("--define requires a value")
+        }
+        defines.append(value)
+      default:
+        paths.append(argument)
+      }
+    }
+
+    switch subcommand {
+    case "scan-modules":
+      guard !paths.isEmpty else {
+        return usageError("scan-modules requires at least one path")
+      }
+      return Scanner.runModules(paths: paths, platform: platform, defines: defines)
+
+    case "scan-exports":
+      // The exports surface visitor doesn't evaluate `#if` blocks yet, so accepting the options
+      // here would silently do nothing.
+      guard platform == nil, defines.isEmpty else {
+        return usageError("scan-exports does not support --platform or --define")
+      }
+      guard !paths.isEmpty else {
+        return usageError("scan-exports requires at least one path")
+      }
+      return Scanner.runExports(paths: paths)
+
+    default:
+      return usageError("unknown subcommand '\(subcommand)'")
+    }
+  }
+}
+
+/// The invoked executable's basename, so the usage text matches however the tool was launched
+/// (the `ExpoModulesMacros-tool` shipped in the package, or a locally built copy).
+private var toolName: String {
+  return (CommandLine.arguments.first as NSString?)?.lastPathComponent ?? "ExpoModulesScanner"
+}
+
+private var usageText: String {
+  """
+  usage: \(toolName) <subcommand> [options] <path> [<path> ...]
+
+  subcommands:
+    scan-modules   fast scan for top-level @ExpoModule types (autolinking)
+    scan-exports   deep scan of the full JS-exported surface (type generation)
+
+  options (scan-modules only):
+    --platform <os>   evaluate '#if os(...)' against this platform (iOS, macOS, tvOS, ...);
+                      without it, os-conditional declarations are skipped with a warning
+    --define <flag>   treat a conditional compilation flag (e.g. DEBUG) as set; repeatable
+
+  options:
+    -h, --help        print this help and exit
+
+  """
+}
+
+/// Prints the usage text to the given handle. Goes to stdout when help was explicitly requested
+/// (a successful action), stderr when it accompanies a usage error.
+private func printUsage(to handle: FileHandle = .standardError) {
+  handle.write(Data(usageText.utf8))
+}
+
+/// Reports a usage error on stderr, followed by the usage text, and returns the usage exit code.
+private func usageError(_ message: String) -> Int32 {
+  FileHandle.standardError.write(Data("error: \(message)\n".utf8))
+  printUsage()
+  return 2
+}

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

@@ -33,6 +33,12 @@ struct Detection: Codable, Equatable {
   /// The kind of declaration the macro was attached to: `class`, `struct`, `func`, `var`, `init`, …
   let declarationKind: String
 
+  /// The declaration's spelled access modifier (`open`, `public`, `package`, `fileprivate`,
+  /// `private`), or `internal` when none is written. Consumers that reference the declaration from
+  /// another Swift module (the generated modules provider does) need `public`/`open` and can reject
+  /// the rest up front instead of failing at compile time.
+  let accessLevel: String
+
   /// The explicit JS name override when written as `@ExpoModule("Foo")` / `@JS("bar")` /
   /// `@SharedObject("Baz")`, otherwise `nil` (the name defaults to `name` at expansion time).
   let jsName: String?
@@ -47,6 +53,16 @@ struct Detection: Codable, Equatable {
   let column: Int
 }
 
+/// A non-fatal problem found while scanning, tied to the source location that caused it — today,
+/// an `#if` condition the scan's static configuration cannot answer (`canImport`, `arch`, an
+/// `os(...)` check with no `--platform` given, …). The affected region is treated as inactive, so
+/// the warning tells the consumer which declarations may have been skipped and why.
+struct ScanWarning: Codable, Equatable {
+  let message: String
+  let file: String
+  let line: Int
+}
+
 /// Counts describing how much work the scan did, so callers can see the pre-filter's effect: of all
 /// the `.swift` files read, how many actually needed parsing, and how long the run took.
 struct ScanStats: Codable, Equatable {

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

@@ -1,3 +1,4 @@
+import SwiftIfConfig
 import SwiftSyntax
 
 /// Walks a parsed source file and records top-level declarations carrying `@ExpoModule`, `@JS`,
@@ -6,7 +7,12 @@ import SwiftSyntax
 /// Recognition mirrors the macros themselves — a purely syntactic match on the spelled attribute
 /// name — so it sees the same declarations the compiler would hand the plugin, without compiling
 /// anything.
-final class DetectionVisitor: SyntaxVisitor {
+///
+/// `#if` blocks are handled by the `ActiveSyntaxVisitor` base: only clauses active under the scan's
+/// `ScanBuildConfiguration` are visited, so a declaration inside `#if os(tvOS)` is recorded exactly
+/// when the scan targets tvOS. Conditions the configuration cannot answer make their region
+/// inactive and land in the inherited `diagnostics`, which the scan surfaces as warnings.
+final class DetectionVisitor: ActiveSyntaxVisitor {
   private let file: String
   private let converter: SourceLocationConverter
   /// Only these macros are recorded; the rest are ignored. Lets a `modules` scan report just
@@ -14,16 +20,30 @@ final class DetectionVisitor: SyntaxVisitor {
   private let detectedMacros: Set<DetectedMacro>
   private(set) var detections: [Detection] = []
 
-  init(file: String, tree: SourceFileSyntax, detectedMacros: Set<DetectedMacro>) {
+  init(
+    file: String,
+    tree: SourceFileSyntax,
+    detectedMacros: Set<DetectedMacro>,
+    configuration: ScanBuildConfiguration
+  ) {
     self.file = file
     self.converter = SourceLocationConverter(fileName: file, tree: tree)
     self.detectedMacros = detectedMacros
-    super.init(viewMode: .sourceAccurate)
+    super.init(viewMode: .sourceAccurate, configuration: configuration)
+  }
+
+  /// The accumulated `#if` warnings as `Detection`-style locations plus the message, ready for the
+  /// scan report. These come from conditions the configuration cannot answer statically.
+  var warnings: [ScanWarning] {
+    return diagnostics.map { diagnostic in
+      let location = diagnostic.location(converter: converter)
+      return ScanWarning(message: diagnostic.message, file: file, line: location.line)
+    }
   }
 
   override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {
     if isTopLevel(node) {
-      record(attributes: node.attributes, name: node.name.text, kind: "class", at: node)
+      record(attributes: node.attributes, modifiers: node.modifiers, name: node.name.text, kind: "class", at: node)
     }
     // Members live in the type body; we never report them, so there's no reason to descend.
     return .skipChildren
@@ -31,29 +51,45 @@ final class DetectionVisitor: SyntaxVisitor {
 
   override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind {
     if isTopLevel(node) {
-      record(attributes: node.attributes, name: node.name.text, kind: "struct", at: node)
+      record(attributes: node.attributes, modifiers: node.modifiers, name: node.name.text, kind: "struct", at: node)
     }
     return .skipChildren
   }
 
-  /// True when the declaration sits at file scope: its parent is a `CodeBlockItemSyntax` directly
-  /// under the source file's top-level item list. Members of a type are nested in a
-  /// `MemberBlockItemSyntax` instead, so they don't match.
+  /// True when the declaration sits at file scope: its parent chain reaches the source file through
+  /// only code-block items and `#if` structure. Members of a type are nested in a
+  /// `MemberBlockItemSyntax` instead, so they don't match. The `#if` wrappers are allowed because a
+  /// top-level declaration inside an (active) `#if` clause is still a top-level declaration.
   ///
   /// TODO: decide whether to support nested types. A macro on a type nested in another type/enum/
   /// extension is valid Swift but missed here; supporting it means descending into type bodies and
   /// recording the enclosing path for a qualified name (e.g. `Namespace.InnerModule`).
   private func isTopLevel(_ node: some SyntaxProtocol) -> Bool {
-    guard let item = node.parent?.as(CodeBlockItemSyntax.self) else {
+    guard node.parent?.is(CodeBlockItemSyntax.self) == true else {
       return false
     }
-    return item.parent?.parent?.is(SourceFileSyntax.self) == true
+    var current = node.parent?.parent
+    while let node = current {
+      if node.is(SourceFileSyntax.self) {
+        return true
+      }
+      guard node.is(CodeBlockItemListSyntax.self)
+        || node.is(CodeBlockItemSyntax.self)
+        || node.is(IfConfigClauseSyntax.self)
+        || node.is(IfConfigClauseListSyntax.self)
+        || node.is(IfConfigDeclSyntax.self) else {
+        return false
+      }
+      current = node.parent
+    }
+    return false
   }
 
   /// Emits one detection per recognized Expo attribute on the declaration. A declaration can in
   /// principle carry more than one (uncommon), so each is recorded independently.
   private func record(
     attributes: AttributeListSyntax,
+    modifiers: DeclModifierListSyntax,
     name: String,
     kind: String,
     at node: some SyntaxProtocol
@@ -70,6 +106,7 @@ final class DetectionVisitor: SyntaxVisitor {
           macro: macro,
           name: name,
           declarationKind: kind,
+          accessLevel: accessLevel(of: modifiers),
           jsName: stringArgument(of: attribute),
           arguments: arguments(of: attribute),
           file: file,
@@ -81,6 +118,19 @@ final class DetectionVisitor: SyntaxVisitor {
   }
 }
 
+/// The spelled access modifiers, in the order Swift defines them. Other modifiers (`final`,
+/// `static`, …) are not access levels and are skipped when resolving one.
+private let accessModifierNames: Set<String> = ["open", "public", "package", "internal", "fileprivate", "private"]
+
+/// The declaration's access level: the first spelled access modifier, or Swift's default of
+/// `internal` when none is written. A declaration can spell at most one, so first is the only one.
+private func accessLevel(of modifiers: DeclModifierListSyntax) -> String {
+  for modifier in modifiers where accessModifierNames.contains(modifier.name.text) {
+    return modifier.name.text
+  }
+  return "internal"
+}
+
 /// Every argument passed to the attribute, in source order, each as a label (or `nil` when
 /// positional) plus the value expression's source text. Returns an empty array when the attribute
 /// is written bare (`@ExpoModule`) or with empty parens.