@expo/expo-modules-macros-plugin 0.3.0 → 0.5.0

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -245,3 +245,87 @@ extension AttributeListSyntax {
     return nil
   }
 }
+
+/// A type spelled so it's valid in expression position (before `.getDynamicType()` or after `as!`).
+/// Implicitly-unwrapped optionals (`T!`) are only allowed in type-annotation position, so a trailing
+/// `!` is rewritten to `?` (`T!` and `T?` are both `Optional<T>`, which the dynamic-type / cast layer
+/// treats identically). Other type spellings pass through unchanged.
+internal func expressionType(_ type: String) -> String {
+  guard type.hasSuffix("!") else {
+    return type
+  }
+  return type.dropLast() + "?"
+}
+
+// MARK: - @JS property collection
+
+/// Collects the `@JS var` bindings of a declaration into `JSProperty` values for direct JSI binding.
+/// Shared between `@ExpoModule` and `@SharedObject` — the resulting properties are receiver-agnostic;
+/// the decorator that emits them picks the receiver (module `self` vs. shared-object `_self`).
+internal func collectProperties(
+  varDecl: VariableDeclSyntax,
+  attribute: AttributeSyntax
+) -> [JSProperty] {
+  let jsNameOverride = jsNameArgument(of: attribute)
+  // A `let` is never settable; only `var` bindings can carry a setter.
+  let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
+
+  return varDecl.bindings.compactMap { binding in
+    guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
+      return nil
+    }
+    let swiftName = ident.identifier.text
+    // Prefer the explicit annotation; recover the type from a literal default (`var x = false`)
+    // when there's none. `nil` falls back to inference at the use site.
+    let valueType = binding.typeAnnotation?.type.trimmedDescription
+      ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
+    return JSProperty(
+      swiftName: swiftName,
+      jsName: jsNameOverride ?? swiftName,
+      valueType: valueType,
+      isSettable: isVar && bindingIsSettable(binding)
+    )
+  }
+}
+
+/// Whether a `var` binding is settable from JS. A stored property (no accessor block) is settable;
+/// a computed property is settable only when it declares an explicit `set` accessor. A getter-only
+/// computed property (`{ get }` or a single getter body) stays read-only. `willSet`/`didSet`
+/// observers imply stored storage, which is also settable.
+private func bindingIsSettable(_ binding: PatternBindingSyntax) -> Bool {
+  guard let accessorBlock = binding.accessorBlock else {
+    return true
+  }
+  switch accessorBlock.accessors {
+  case .accessors(let accessors):
+    return accessors.contains { accessor in
+      switch accessor.accessorSpecifier.tokenKind {
+      case .keyword(.set), .keyword(.willSet), .keyword(.didSet):
+        return true
+      default:
+        return false
+      }
+    }
+  case .getter:
+    return false
+  }
+}
+
+/// The throwing `JavaScriptUnownedValue` accessor that decodes the given primitive type directly
+/// (`asDouble()` for `Double`, etc.), bypassing the dynamic-type converter. Returns `nil` for types
+/// without a dedicated accessor (arrays, records, optionals, shared objects, other numeric widths),
+/// which decode through `getDynamicType().cast(...)`.
+func fastDecodeAccessor(for type: String) -> String? {
+  switch type {
+  case "Bool":
+    return "asBool"
+  case "Int":
+    return "asInt"
+  case "Double":
+    return "asDouble"
+  case "String":
+    return "asString"
+  default:
+    return nil
+  }
+}

package/apple/Sources/ExpoModulesMacros/Receiver.swift

@@ -0,0 +1,58 @@
+import SwiftSyntax
+
+/// Where a directly-bound closure gets the Swift value it calls into. A module is a singleton, so its
+/// bindings call `self` and ignore the JS `this`; a shared object has a distinct native instance per JS
+/// object, so its bindings recover the typed receiver from `this`.
+internal enum Receiver {
+  /// The module singleton; the closure captures `self` strong.
+  case module
+  /// A shared object of the given concrete type; the closure captures nothing and recovers the receiver
+  /// from `this` per call.
+  case sharedObject(typeName: String)
+
+  /// The expression the body calls members on: `self` for a module, `_self` (bound by `unwrapStatement`)
+  /// for a shared object. The leading underscore avoids colliding with a user member like `var owner`.
+  var callee: String {
+    switch self {
+    case .module:
+      return "self"
+    case .sharedObject:
+      return "_self"
+    }
+  }
+
+  /// The JS object the decorator binds members onto, matching its first parameter: `object` for a
+  /// module (its own JS object), `prototype` for a shared object (the shared class prototype).
+  var decoratedObject: String {
+    switch self {
+    case .module:
+      return "object"
+    case .sharedObject:
+      return "prototype"
+    }
+  }
+
+  /// The leading body line binding the receiver, or `nil` for a module (it reads `self` directly). For a
+  /// shared object, `native(from:as:)` recovers the typed instance from the borrowed `this`, throwing on
+  /// a foreign object or a type mismatch.
+  var unwrapStatement: String? {
+    switch self {
+    case .module:
+      return nil
+    case .sharedObject(let typeName):
+      return "let _self = try SharedObject.native(from: this.asObject(in: runtime), as: \(typeName).self)"
+    }
+  }
+
+  /// The capture-clause fragment (with a trailing space, or empty when nothing is captured). A module
+  /// captures `self` strong; a shared object captures nothing of the instance. `appContext`, when used,
+  /// is captured weak in both cases.
+  func captureClause(usesAppContext: Bool) -> String {
+    switch self {
+    case .module:
+      return usesAppContext ? "[weak appContext, self] " : "[self] "
+    case .sharedObject:
+      return usesAppContext ? "[weak appContext] " : ""
+    }
+  }
+}

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -316,7 +316,8 @@ private func jsObjectReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
   for property in properties {
     let valueVar = "\(property.name)JSValue"
-    let cast = "try \(property.type).getDynamicType().cast(jsValue: \(valueVar), appContext: appContext) as! \(property.type)"
+    let exprType = expressionType(property.type)
+    let cast = "try \(exprType).getDynamicType().cast(jsValue: \(valueVar), appContext: appContext) as! \(exprType)"
     lines.append("  let \(valueVar) = object.getProperty(\"\(property.name)\")")
     if property.isRequired {
       lines.append("  guard !\(valueVar).isUndefined() else {")
@@ -337,7 +338,8 @@ private func dictionaryReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
   for property in properties {
     let valueVar = "\(property.name)Value"
-    let cast = "try \(property.type).getDynamicType().cast(\(valueVar), appContext: appContext) as! \(property.type)"
+    let exprType = expressionType(property.type)
+    let cast = "try \(exprType).getDynamicType().cast(\(valueVar), appContext: appContext) as! \(exprType)"
     lines.append("  let \(valueVar) = dictionary[\"\(property.name)\"]")
     if property.isRequired {
       lines.append("  guard let \(valueVar) else {")
@@ -399,7 +401,7 @@ private func toObjectMethod(properties: [RecordProperty], inheritsRecord: Bool)
     lines.append("  let object = try appContext.runtime.createObject()")
   }
   for property in properties {
-    lines.append("  object.setProperty(\"\(property.name)\", value: try \(property.type).getDynamicType().convertToJS(self.\(property.name), appContext: appContext))")
+    lines.append("  object.setProperty(\"\(property.name)\", value: try \(expressionType(property.type)).getDynamicType().convertToJS(self.\(property.name), appContext: appContext))")
   }
   lines.append("  return object")
   let body = lines.joined(separator: "\n")

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -41,35 +41,38 @@ public struct SharedObjectMacro: MemberMacro {
     let typeName = classDecl.name.text
     let jsName = jsNameArgument(of: node) ?? typeName
 
-    var entries: [String] = []
-    var sawConstructor = false
+    // `@JS func`s/`var`s and the `@JS init` are bound directly into the shared object's JS object by
+    // the synthesized `_decorateSharedObject` / `_constructSharedObject` rather than described with a
+    // `Function(...)` / `Property(...)` / `Constructor { … }` DSL entry, so they're collected here
+    // instead of appended to the `Class` block. The block keeps only non-`@JS` definitions (none are
+    // collected today), so it's empty when every member is `@JS`.
+    let entries: [String] = []
+    var functions: [JSFunction] = []
+    var properties: [JSProperty] = []
+    var constructor: JSConstructor?
 
     for member in classDecl.memberBlock.members {
       let decl = member.decl
 
       if let initDecl = decl.as(InitializerDeclSyntax.self),
         initDecl.attributes.firstAttribute(named: "JS") != nil {
-        if sawConstructor {
+        if constructor != nil {
           throw MacroExpansionErrorMessage(
             "@SharedObject classes can have at most one @JS initializer; JavaScript classes have a single constructor.")
         }
-        sawConstructor = true
-        entries.append(buildConstructorEntry(initDecl: initDecl, typeName: typeName))
+        constructor = JSConstructor(initDecl: initDecl)
         continue
       }
 
       if let funcDecl = decl.as(FunctionDeclSyntax.self),
         let attribute = funcDecl.attributes.firstAttribute(named: "JS") {
-        entries.append(
-          buildClassFunctionEntry(funcDecl: funcDecl, attribute: attribute, typeName: typeName))
+        functions.append(JSFunction(funcDecl: funcDecl, attribute: attribute))
         continue
       }
 
       if let varDecl = decl.as(VariableDeclSyntax.self),
         let attribute = varDecl.attributes.firstAttribute(named: "JS") {
-        entries.append(
-          contentsOf: buildClassPropertyEntries(
-            varDecl: varDecl, attribute: attribute, typeName: typeName))
+        properties.append(contentsOf: collectProperties(varDecl: varDecl, attribute: attribute))
       }
     }
 
@@ -78,13 +81,27 @@ public struct SharedObjectMacro: MemberMacro {
       ? "  return Class(\"\(jsName)\", \(typeName).self) {\n  }"
       : "  return Class(\"\(jsName)\", \(typeName).self) {\n\(lines)\n  }"
 
-    let method: DeclSyntax = """
+    var emitted: [DeclSyntax] = [
+      """
       public static func _synthesizedClassDefinition() -> ClassDefinition {
       \(raw: body)
       }
       """
+    ]
+
+    // Direct JSI binding: one `_decorateSharedObject` that binds each `@JS func`/`var` onto the JS
+    // object (unwrapping the per-call receiver from `this`), and a `_constructSharedObject` that
+    // builds an instance from the `@JS init` arguments. Each is emitted only when it has something
+    // to do.
+    if !functions.isEmpty || !properties.isEmpty {
+      emitted.append(
+        buildDecorateSharedObject(functions: functions, properties: properties, typeName: typeName))
+    }
+    if let constructor {
+      emitted.append(constructor.buildConstructor(typeName: typeName))
+    }
 
-    return [method]
+    return emitted
   }
 }
 
@@ -111,81 +128,3 @@ extension SharedObjectMacro: MemberAttributeMacro {
 private func inheritsFromSharedObject(_ classDecl: ClassDeclSyntax) -> Bool {
   return inheritsFromAny(classDecl, names: ["SharedObject"])
 }
-
-// MARK: - Class-scope entry builders
-
-private func buildClassFunctionEntry(
-  funcDecl: FunctionDeclSyntax,
-  attribute: AttributeSyntax,
-  typeName: String
-) -> String {
-  let swiftName = funcDecl.name.text
-  let jsName = jsNameArgument(of: attribute) ?? swiftName
-  let effects = funcDecl.signature.effectSpecifiers
-  let isAsync = effects?.asyncSpecifier != nil
-  let isThrowing = effects?.throwsClause?.throwsSpecifier != nil
-  let dslEntry = isAsync ? "AsyncFunction" : "Function"
-
-  let params = funcDecl.signature.parameterClause.parameters
-  let closureParamList: String
-  let callArgList: String
-  if params.isEmpty {
-    closureParamList = "(this: \(typeName))"
-    callArgList = ""
-  } else {
-    let typedParams = params.enumerated().map { index, param in
-      "_ arg\(index): \(param.type.trimmedDescription)"
-    }.joined(separator: ", ")
-    closureParamList = "(this: \(typeName), \(typedParams))"
-
-    callArgList = params.enumerated().map { index, param in
-      let label = param.firstName.text
-      return label == "_" ? "arg\(index)" : "\(label): arg\(index)"
-    }.joined(separator: ", ")
-  }
-
-  let awaitKeyword = isAsync ? "await " : ""
-  let tryKeyword = (isAsync || isThrowing) ? "try " : ""
-  let callExpr = "\(tryKeyword)\(awaitKeyword)this.\(swiftName)(\(callArgList))"
-
-  return "\(dslEntry)(\"\(jsName)\") { \(closureParamList) in \(callExpr) }"
-}
-
-private func buildClassPropertyEntries(
-  varDecl: VariableDeclSyntax,
-  attribute: AttributeSyntax,
-  typeName: String
-) -> [String] {
-  let jsNameOverride = jsNameArgument(of: attribute)
-
-  return varDecl.bindings.compactMap { binding in
-    guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
-      return nil
-    }
-    let swiftName = ident.identifier.text
-    let jsName = jsNameOverride ?? swiftName
-    return "Property(\"\(jsName)\") { (this: \(typeName)) in this.\(swiftName) }"
-  }
-}
-
-private func buildConstructorEntry(
-  initDecl: InitializerDeclSyntax,
-  typeName: String
-) -> String {
-  let params = initDecl.signature.parameterClause.parameters
-
-  if params.isEmpty {
-    return "Constructor { \(typeName)() }"
-  }
-
-  let argList = params.enumerated().map { index, param in
-    "_ arg\(index): \(param.type.trimmedDescription)"
-  }.joined(separator: ", ")
-
-  let callArgs = params.enumerated().map { index, param in
-    let label = param.firstName.text
-    return label == "_" ? "arg\(index)" : "\(label): arg\(index)"
-  }.joined(separator: ", ")
-
-  return "Constructor { (\(argList)) in \(typeName)(\(callArgs)) }"
-}

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

@@ -0,0 +1,61 @@
+import Foundation
+
+/// Which Expo macro was found on a declaration. The scanner recognizes the entry-point macros that
+/// mark a type or member as part of a module's JS surface, plus `@Record` for convertible types.
+enum DetectedMacro: String, Codable, CaseIterable {
+  case expoModule = "ExpoModule"
+  case js = "JS"
+  case sharedObject = "SharedObject"
+  case record = "Record"
+}
+
+/// A single argument passed to a macro, e.g. `"Foo"` or `classes: [Bar.self]`. The label is `nil`
+/// for positional arguments; `value` is the argument expression's source text as written.
+struct MacroArgument: Codable, Equatable {
+  /// The argument label (`classes` in `classes: [Bar.self]`), or `nil` for a positional argument.
+  let label: String?
+
+  /// The argument value exactly as written in source, e.g. `"Foo"` (including the quotes) or
+  /// `[Bar.self]`. Kept as text because a syntactic scan can't resolve these to runtime values.
+  let value: String
+}
+
+/// A single annotated declaration the scanner found, with just enough to locate it and know
+/// what it is. Member-level details (parameters, types) are intentionally out of scope for this
+/// first prototype — see the `@JS` member walk in the macros for where that would live.
+struct Detection: Codable, Equatable {
+  /// The macro spelled on the declaration (without the leading `@`).
+  let macro: DetectedMacro
+
+  /// The declared name, e.g. the class name for `@ExpoModule`, or the func/var/init name for `@JS`.
+  let name: String
+
+  /// The kind of declaration the macro was attached to: `class`, `struct`, `func`, `var`, `init`, …
+  let declarationKind: 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?
+
+  /// Every argument passed to the macro, in source order, e.g. `@ExpoModule("Foo", classes: [Bar.self])`
+  /// yields a positional `"Foo"` and a `classes:` argument. Empty when the macro is written bare.
+  let arguments: [MacroArgument]
+
+  /// Source location, relative to the path the scanner was invoked with.
+  let file: String
+  let line: Int
+  let column: 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 {
+  /// `.swift` files the walk found and read (after directory pruning).
+  let filesScanned: Int
+
+  /// Of those, how many contained a macro attribute and so were parsed with SwiftSyntax.
+  let filesParsed: Int
+
+  /// Wall-clock duration of the scan, in milliseconds (walking, reading, filtering, and parsing).
+  let durationMs: Double
+}

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

@@ -0,0 +1,109 @@
+import SwiftSyntax
+
+/// Walks a parsed source file and records top-level declarations carrying `@ExpoModule`, `@JS`,
+/// `@SharedObject`, or `@Record`. Only file-scope declarations are considered: these macros apply to
+/// top-level types, so descending into type and function bodies would only surface false positives.
+/// 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 {
+  private let file: String
+  private let converter: SourceLocationConverter
+  /// Only these macros are recorded; the rest are ignored. Lets a `modules` scan report just
+  /// `@ExpoModule` while an `exports` scan covers them all.
+  private let detectedMacros: Set<DetectedMacro>
+  private(set) var detections: [Detection] = []
+
+  init(file: String, tree: SourceFileSyntax, detectedMacros: Set<DetectedMacro>) {
+    self.file = file
+    self.converter = SourceLocationConverter(fileName: file, tree: tree)
+    self.detectedMacros = detectedMacros
+    super.init(viewMode: .sourceAccurate)
+  }
+
+  override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {
+    if isTopLevel(node) {
+      record(attributes: node.attributes, 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
+  }
+
+  override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind {
+    if isTopLevel(node) {
+      record(attributes: node.attributes, 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.
+  ///
+  /// 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 {
+      return false
+    }
+    return item.parent?.parent?.is(SourceFileSyntax.self) == true
+  }
+
+  /// 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,
+    name: String,
+    kind: String,
+    at node: some SyntaxProtocol
+  ) {
+    for element in attributes {
+      guard let attribute = element.as(AttributeSyntax.self),
+        let macro = DetectedMacro(rawValue: attribute.attributeName.trimmedDescription),
+        detectedMacros.contains(macro) else {
+        continue
+      }
+      let location = converter.location(for: node.positionAfterSkippingLeadingTrivia)
+      detections.append(
+        Detection(
+          macro: macro,
+          name: name,
+          declarationKind: kind,
+          jsName: stringArgument(of: attribute),
+          arguments: arguments(of: attribute),
+          file: file,
+          line: location.line,
+          column: location.column
+        )
+      )
+    }
+  }
+}
+
+/// 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.
+private func arguments(of attribute: AttributeSyntax) -> [MacroArgument] {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return []
+  }
+  return args.map { arg in
+    MacroArgument(label: arg.label?.text, value: arg.expression.trimmedDescription)
+  }
+}
+
+/// The first string-literal argument of an attribute, e.g. `@JS("doWork")` -> "doWork". Returns
+/// `nil` when there's no argument or it isn't a plain string literal. (Same shape the
+/// `jsNameArgument` helper reads inside the macros.)
+private func stringArgument(of attribute: AttributeSyntax) -> String? {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
+    let first = args.first,
+    first.label == nil,
+    let str = first.expression.as(StringLiteralExprSyntax.self),
+    let segment = str.segments.first?.as(StringSegmentSyntax.self),
+    str.segments.count == 1 else {
+    return nil
+  }
+  return segment.content.text
+}

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

@@ -0,0 +1,137 @@
+import Foundation
+import SwiftParser
+import SwiftSyntax
+
+/// Walks `paths`, parses each `.swift` file that might contain one of `macros` (the pre-filter), and
+/// returns every detection (in file then source order) with the run's stats. The shared core every
+/// scan command builds on; each command projects these detections into its own output shape.
+func collectDetections(paths: [String], macros: Set<DetectedMacro>) -> (detections: [Detection], stats: ScanStats) {
+  let clock = ContinuousClock()
+  let start = clock.now
+
+  var detections: [Detection] = []
+  var filesScanned = 0
+  var filesParsed = 0
+
+  // Compile the pre-filter regex once per run, not once per file.
+  let prefilter = macroAttributeRegex(for: macros)
+
+  for file in swiftFiles(in: paths) {
+    guard let source = try? String(contentsOfFile: file, encoding: .utf8) else {
+      FileHandle.standardError.write(Data("warning: could not read \(file)\n".utf8))
+      continue
+    }
+    filesScanned += 1
+    // Skip the (relatively expensive) parse for files that can't contain any of the macros. A plain
+    // substring scan is far cheaper than a full parse, and most files in a large tree mention none
+    // of these names. See `mightContainMacro` for why this never drops a real match.
+    guard mightContainMacro(in: source, prefilter: prefilter) else {
+      continue
+    }
+    filesParsed += 1
+    detections.append(contentsOf: detect(source: source, file: file, macros: macros))
+  }
+
+  let elapsed = (clock.now - start).components
+  let durationMs = Double(elapsed.seconds) * 1000 + Double(elapsed.attoseconds) / 1e15
+
+  return (detections, ScanStats(filesScanned: filesScanned, filesParsed: filesParsed, durationMs: durationMs))
+}
+
+/// Parses one source string and returns its detections for the given macro set. The unit of work the
+/// tests exercise.
+func detect(source: String, file: String, macros: Set<DetectedMacro>) -> [Detection] {
+  let tree = Parser.parse(source: source)
+  let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: macros)
+  visitor.walk(tree)
+  return visitor.detections
+}
+
+// MARK: - Pre-filter
+
+/// Builds the pre-filter regex for a macro set, e.g. `@(ExpoModule)` for a `modules` scan or
+/// `@(ExpoModule|JS|Record|SharedObject)` for an `exports` scan. A precompiled `NSRegularExpression`
+/// benchmarked ~20x faster over a large source tree than calling `String.contains` once per macro
+/// name, because it scans each file in a single pass. Compiled once per run and reused per file.
+func macroAttributeRegex(for macros: Set<DetectedMacro>) -> NSRegularExpression {
+  // Sort for a stable pattern regardless of the set's iteration order.
+  let alternation = macros.map(\.rawValue).sorted().joined(separator: "|")
+  return try! NSRegularExpression(pattern: "@(\(alternation))")
+}
+
+/// True if the source text contains one of the pre-filter's spelled macro attributes, so it's worth
+/// parsing. A deliberate over-approximation: the pattern can still match inside a comment or string,
+/// in which case the file is parsed and correctly yields no detections — a wasted parse, never a
+/// missed module. It assumes the attribute is written with no space after `@` (`@ExpoModule`, not
+/// `@ ExpoModule`), which is universal in practice; the rare spaced form would be skipped.
+func mightContainMacro(in source: String, prefilter: NSRegularExpression) -> Bool {
+  let range = NSRange(source.startIndex..., in: source)
+  return prefilter.firstMatch(in: source, range: range) != nil
+}
+
+// MARK: - File discovery
+
+/// Directory names skipped during the recursive walk. These hold build products, dependencies, and
+/// git internals — never source worth scanning — and pruning them keeps the walk from descending
+/// into the bulk of a monorepo's files.
+private let prunedDirectoryNames: Set<String> = [".build", "Pods", ".git"]
+
+/// Expands the given paths into the list of `.swift` files to parse: a file path passes through,
+/// a directory is enumerated recursively (skipping `prunedDirectoryNames`). Order is deterministic
+/// so output is stable across runs.
+///
+/// Reported paths are absolute, so the output is unambiguous and independent of the caller's working
+/// directory. (A future `--root` option could emit paths relative to a given base when a portable,
+/// shorter form is wanted.)
+func swiftFiles(in paths: [String]) -> [String] {
+  let fileManager = FileManager.default
+  var result: [String] = []
+
+  for path in paths {
+    var isDirectory: ObjCBool = false
+    guard fileManager.fileExists(atPath: path, isDirectory: &isDirectory) else {
+      FileHandle.standardError.write(Data("warning: no such path \(path)\n".utf8))
+      continue
+    }
+
+    if isDirectory.boolValue {
+      result.append(contentsOf: swiftFiles(inDirectory: URL(fileURLWithPath: path), fileManager: fileManager))
+    } else if path.hasSuffix(".swift") {
+      // A directory walk already yields absolute paths; resolve a directly-passed file the same way
+      // so every reported path is absolute regardless of how it was spelled.
+      result.append(URL(fileURLWithPath: path).standardizedFileURL.path)
+    }
+  }
+
+  return result.sorted()
+}
+
+/// Recursively enumerates `.swift` files under a directory, calling `skipDescendants()` on any
+/// pruned directory so its subtree is never read. Uses the URL enumerator (rather than the
+/// path-based one) precisely because it supports skipping a subtree mid-walk.
+///
+/// Directory-ness is read from `hasDirectoryPath` (the enumerator sets a trailing slash on the URLs
+/// it yields) rather than `resourceValues(forKeys: [.isDirectoryKey])`, which re-`stat`s each entry.
+/// The walk is the dominant cost of a whole-tree scan, and skipping that per-entry stat measurably
+/// shortens it.
+private func swiftFiles(inDirectory directory: URL, fileManager: FileManager) -> [String] {
+  guard let enumerator = fileManager.enumerator(
+    at: directory,
+    includingPropertiesForKeys: nil,
+    options: [.skipsHiddenFiles]
+  ) else {
+    return []
+  }
+
+  var result: [String] = []
+  for case let url as URL in enumerator {
+    if url.hasDirectoryPath {
+      if prunedDirectoryNames.contains(url.lastPathComponent) {
+        enumerator.skipDescendants()
+      }
+    } else if url.pathExtension == "swift" {
+      result.append(url.path)
+    }
+  }
+  return result
+}