expo-modules-macros 0.0.1 → 0.15.0

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

@@ -0,0 +1,79 @@
+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 event = "Event"
+  case sharedObject = "SharedObject"
+  case record = "Record"
+  case union = "Union"
+}
+
+/// 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 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?
+
+  /// 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
+}
+
+/// A non-fatal problem found while scanning, tied to the source location that caused it — today,
+/// an `#if` condition a static scan cannot answer (`canImport` of a non-SDK module, `arch`,
+/// `targetEnvironment`, …). The affected region counts as inactive on every platform, so the
+/// warning tells the consumer which declarations may be missing platforms and why.
+struct ScanWarning: Codable, Equatable, Hashable {
+  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 {
+  /// `.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,181 @@
+import SwiftDiagnostics
+import SwiftIfConfig
+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.
+///
+/// `#if` blocks are handled according to the scan's configuration. With a `ScanBuildConfiguration`,
+/// only the active clause of each `#if` is visited, so a declaration inside `#if os(tvOS)` is
+/// recorded exactly when the scan targets tvOS, and conditions the configuration cannot answer make
+/// their region inactive and surface as warnings. With a `nil` configuration every clause of every
+/// `#if` is visited, so a declaration in any branch is recorded and nothing is evaluated; the
+/// per-platform aggregation in `scanModules` builds on both walks.
+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>
+  /// The configuration `#if` conditions are evaluated against, or `nil` to visit every branch.
+  private let configuration: ScanBuildConfiguration?
+  private var diagnostics: [Diagnostic] = []
+  private(set) var detections: [Detection] = []
+
+  init(
+    file: String,
+    tree: SourceFileSyntax,
+    detectedMacros: Set<DetectedMacro>,
+    configuration: ScanBuildConfiguration?
+  ) {
+    self.file = file
+    self.converter = SourceLocationConverter(fileName: file, tree: tree)
+    self.detectedMacros = detectedMacros
+    self.configuration = configuration
+    super.init(viewMode: .sourceAccurate)
+  }
+
+  /// 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: IfConfigDeclSyntax) -> SyntaxVisitorContinueKind {
+    guard let configuration else {
+      // Every branch is visited, so a declaration in any clause is recorded.
+      return .visitChildren
+    }
+    let (clause, clauseDiagnostics) = node.activeClause(in: configuration)
+    diagnostics.append(contentsOf: clauseDiagnostics)
+    if let elements = clause?.elements {
+      // A nested `#if` inside the active clause comes back through this method.
+      walk(elements)
+    }
+    return .skipChildren
+  }
+
+  override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {
+    if isTopLevel(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
+  }
+
+  override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind {
+    if isTopLevel(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 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 node.parent?.is(CodeBlockItemSyntax.self) == true else {
+      return false
+    }
+    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
+  ) {
+    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,
+          accessLevel: accessLevel(of: modifiers),
+          jsName: stringArgument(of: attribute),
+          arguments: arguments(of: attribute),
+          file: file,
+          line: location.line,
+          column: location.column
+        )
+      )
+    }
+  }
+}
+
+/// 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.
+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.) Shared with the `scan-exports` surface visitor,
+/// which reads the same JS-name override off `@JS`/`@ExpoModule`/`@SharedObject`.
+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/ScanBuildConfiguration.swift

@@ -0,0 +1,115 @@
+import SwiftIfConfig
+import SwiftSyntax
+
+/// The build configuration that `#if` conditions are evaluated against during a scan, built from
+/// the CLI's `--platform` and `--define` options. The scan is static: it knows the target OS and
+/// the spelled compilation flags, and nothing else. Every condition it cannot answer throws, which
+/// SwiftIfConfig turns into an inactive region plus a diagnostic, so an unanswerable `#if` skips
+/// its declarations and surfaces a warning instead of guessing.
+struct ScanBuildConfiguration: BuildConfiguration {
+  /// The target OS name to answer `os(...)` with, as spelled in the condition (`iOS`, `macOS`,
+  /// `tvOS`, `watchOS`, `visionOS`; compared case-insensitively). A scan without a target OS runs
+  /// without a configuration at all (the platform-agnostic union scan), so this is always known.
+  let platform: String
+
+  /// The conditional compilation flags treated as set, from repeated `--define` options.
+  let defines: Set<String>
+
+  func isCustomConditionSet(name: String) throws -> Bool {
+    return defines.contains(name)
+  }
+
+  func isActiveTargetOS(name: String) throws -> Bool {
+    return name.lowercased() == platform.lowercased()
+  }
+
+  // MARK: - Unanswerable conditions
+
+  // These vary within a single platform's build (device vs simulator, arm64 vs x86_64) or depend
+  // on the consumer's toolchain, so a static scan has no correct answer. Throwing makes the region
+  // inactive and emits a warning naming the condition.
+
+  func hasFeature(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate 'hasFeature(\(name))' in a static scan")
+  }
+
+  func hasAttribute(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate 'hasAttribute(\(name))' in a static scan")
+  }
+
+  func canImport(importPath: [(TokenSyntax, String)], version: CanImportVersion) throws -> Bool {
+    let module = importPath.map(\.1).joined(separator: ".")
+
+    // A curated set of SDK frameworks is answerable from the target platform alone. Everything
+    // else (arbitrary modules, submodule paths, versioned checks) stays unanswerable: a wrong
+    // "yes" would surface a declaration that doesn't exist in the real build.
+    guard importPath.count == 1,
+      case .unversioned = version,
+      let frameworkPlatforms = sdkFrameworkPlatforms[module] else {
+      throw ScanConfigurationError("cannot evaluate 'canImport(\(module))' in a static scan")
+    }
+    return frameworkPlatforms.contains(platform.lowercased())
+  }
+
+  func isActiveTargetArchitecture(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate 'arch(\(name))' in a static scan")
+  }
+
+  func isActiveTargetEnvironment(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate 'targetEnvironment(\(name))' in a static scan")
+  }
+
+  func isActiveTargetRuntime(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate '_runtime(\(name))' in a static scan")
+  }
+
+  func isActiveTargetPointerAuthentication(name: String) throws -> Bool {
+    throw ScanConfigurationError("cannot evaluate '_ptrauth(\(name))' in a static scan")
+  }
+
+  // MARK: - Fixed answers
+
+  // Non-throwing protocol requirements, so they need a value. These are constant across Apple
+  // targets (the only ones Expo modules compile for), except the versions, which assume a current
+  // toolchain; a module class gated on a *lower* Swift version would be wrongly included, which is
+  // rare enough to accept for a scan.
+
+  var targetPointerBitWidth: Int { 64 }
+  var targetAtomicBitWidths: [Int] { [32, 64, 128] }
+  var endianness: Endianness { .little }
+  var languageVersion: VersionTuple { VersionTuple(6) }
+  var compilerVersion: VersionTuple { VersionTuple(6, 2) }
+}
+
+/// The platforms (lowercased, as compared against `--platform`) that ship each of a curated set of
+/// Apple SDK frameworks, so `canImport` of one is answerable from the platform alone. The list is
+/// deliberately small and high-confidence: it covers the frameworks realistically used to gate a
+/// module class, and a framework missing here degrades to the skip-with-warning path rather than a
+/// wrong answer.
+private let sdkFrameworkPlatforms: [String: Set<String>] = [
+  "UIKit": ["ios", "tvos", "watchos", "visionos"],
+  "AppKit": ["macos"],
+  "SwiftUI": ["ios", "macos", "tvos", "watchos", "visionos"],
+  "WatchKit": ["watchos"],
+  "TVUIKit": ["tvos"],
+  "WebKit": ["ios", "macos", "visionos"],
+  "SafariServices": ["ios", "macos", "visionos"],
+  "ARKit": ["ios", "visionos"],
+  "RealityKit": ["ios", "macos", "visionos"],
+  "CarPlay": ["ios"],
+  "MessageUI": ["ios"],
+  "CoreNFC": ["ios"],
+  "HealthKit": ["ios", "watchos", "visionos"],
+  "HomeKit": ["ios", "tvos", "watchos", "visionos"],
+  "WidgetKit": ["ios", "macos", "watchos", "visionos"],
+]
+
+/// An unanswerable `#if` condition. SwiftIfConfig converts the thrown error into a diagnostic on
+/// the condition's node and treats the region as inactive.
+struct ScanConfigurationError: Error, CustomStringConvertible {
+  let description: String
+
+  init(_ description: String) {
+    self.description = description
+  }
+}

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

@@ -0,0 +1,193 @@
+import Foundation
+import SwiftParser
+import SwiftSyntax
+
+/// Walks `paths`, and for each `.swift` file that might contain one of `macros` or one of
+/// `conformances` (the pre-filter passes it), reads the source and hands it to `process` along with the
+/// file path. Returns the run's stats.
+///
+/// The shared core every scan command builds on: the walk, read, pre-filter, and stats are identical;
+/// only what each command does per parsed file differs (`scan-modules` collects `Detection`s,
+/// `scan-exports` walks a `SurfaceVisitor`), and that lives in `process`.
+func scanFiles(
+  paths: [String],
+  macros: Set<DetectedMacro>,
+  conformances: Set<String> = [],
+  process: (_ source: String, _ file: String) -> Void
+) -> ScanStats {
+  let clock = ContinuousClock()
+  let start = clock.now
+
+  var filesScanned = 0
+  var filesParsed = 0
+
+  // Compile the pre-filter regex once per run, not once per file.
+  let prefilter = macroAttributeRegex(for: macros, conformances: conformances)
+
+  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
+    process(source, file)
+  }
+
+  let elapsed = (clock.now - start).components
+  let durationMs = Double(elapsed.seconds) * 1000 + Double(elapsed.attoseconds) / 1e15
+
+  return ScanStats(filesScanned: filesScanned, filesParsed: filesParsed, durationMs: durationMs)
+}
+
+/// Walks `paths`, parses each `.swift` file that might contain one of `macros`, and returns every
+/// detection (in file then source order) with the accumulated `#if` warnings and the run's stats —
+/// the shape `scan-modules` projects. A thin layer over `scanFiles` that accumulates the per-file
+/// results.
+func collectDetections(
+  paths: [String],
+  macros: Set<DetectedMacro>,
+  configuration: ScanBuildConfiguration? = nil
+) -> (detections: [Detection], warnings: [ScanWarning], stats: ScanStats) {
+  var detections: [Detection] = []
+  var warnings: [ScanWarning] = []
+  let stats = scanFiles(paths: paths, macros: macros) { source, file in
+    let result = detect(source: source, file: file, macros: macros, configuration: configuration)
+    detections.append(contentsOf: result.detections)
+    warnings.append(contentsOf: result.warnings)
+  }
+  return (detections, warnings, stats)
+}
+
+/// Parses one source string and returns its detections for the given macro set, plus the warnings
+/// for `#if` conditions the configuration couldn't answer. The unit of work the tests exercise.
+func detect(
+  source: String,
+  file: String,
+  macros: Set<DetectedMacro>,
+  configuration: ScanBuildConfiguration?
+) -> (detections: [Detection], warnings: [ScanWarning]) {
+  let tree = Parser.parse(source: source)
+  let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: macros, configuration: configuration)
+  visitor.walk(tree)
+  return (visitor.detections, visitor.warnings)
+}
+
+// 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.
+///
+/// `conformances` adds bare (unprefixed) alternatives for types recognized by conformance rather than
+/// by an attribute (`Enumerable` for `scan-exports`). They join the same alternation so the scan stays
+/// one pass; a bare name matches more loosely than an `@`-prefixed one, which costs a wasted parse and
+/// never a miss.
+func macroAttributeRegex(
+  for macros: Set<DetectedMacro>,
+  conformances: Set<String> = []
+) -> NSRegularExpression {
+  // Sort for a stable pattern regardless of the set's iteration order.
+  let attributes = macros.map(\.rawValue).sorted().joined(separator: "|")
+  var alternatives: [String] = []
+  if !attributes.isEmpty {
+    alternatives.append("@(\(attributes))")
+  }
+  alternatives.append(contentsOf: conformances.sorted())
+  return try! NSRegularExpression(pattern: alternatives.joined(separator: "|"))
+}
+
+/// 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, in two groups:
+/// - Build products, dependencies, and git internals (`.build`, `Pods`, `.git`, `node_modules`) are
+///   never source worth scanning, and pruning them keeps the walk from descending into the bulk of
+///   a monorepo's files. `node_modules` also makes any npm package root safe to pass as a scan
+///   path: nested dependencies are separate packages and get scanned on their own.
+/// - Test and example directories, by the layout conventions of Expo module packages (`Tests`,
+///   `UITests`, `__tests__`, `__mocks__`, `example(s)`, `e2e`). Their sources are not compiled into the
+///   package's product (they belong to a `test_spec` or a standalone example app), so a declaration
+///   found there would name a type the consumer can't reference. This is a name-based heuristic;
+///   a package keeping product sources in such a directory can declare its modules in
+///   `expo-module.config.json` instead.
+private let prunedDirectoryNames: Set<String> = [
+  ".build", "Pods", ".git", "node_modules",
+  "Tests", "UITests", "__tests__", "__mocks__", "example", "examples", "e2e",
+]
+
+/// 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
+}