Add a Swift source scanner CLI for the Expo module macros

[tsapeta]

Introduce ExpoModulesScanner, a SwiftSyntax-based CLI that scans Swift source for declarations annotated with the Expo module macros (@ExpoModule, @JS, @SharedObject, @Record) and emits a JSON report. It parses syntactically (no compilation), so it sees the same declarations the compiler would hand the macro plugin.

Subcommands

Two modes for two consumers, selected by subcommand. Both take <path>... (a .swift file or a directory scanned recursively):

• scan-modules (fast) — reports top-level @ExpoModule types, for expo-modules-autolinking, which just needs module class names. The pre-filter matches @ExpoModule alone, so most files skip parsing.
• scan-exports (deep) — intended for TypeScript type generation; will walk the full JS-exported surface of each type. The subcommand is recognized but currently exits "not yet implemented"; the member-level extraction lands in a separate PR.

-h/--help prints usage to stdout and exits 0.

scan-modules output

Trimmed to what autolinking needs. Each module carries the Swift class name, the resolved jsName (the @ExpoModule("Foo") override, else the class name — resolved the way the macro derives it, so the consumer never applies the fallback), and the file. A top-level stats reports the scan's effort.

File paths are absolute, so the output is unambiguous and independent of the caller's working directory. (A --root option for a portable, relative form may come later.)

{
  "modules": [
    { "name": "MyModule", "jsName": "MyModule", "file": "/Users/me/expo/packages/my-module/ios/MyModule.swift" },
    { "name": "MacroRenamed", "jsName": "RenamedMacroModule", "file": "/Users/me/expo/packages/expo-modules-core/ios/Tests/Macros/MacroModuleTests.swift" }
  ],
  "stats": { "filesScanned": 1621, "filesParsed": 7, "durationMs": 3064.6 }
}

(scan-exports will return its own shape; the two commands serve different consumers and don't share an output envelope.)

Performance

A whole-tree scan is dominated by the directory walk, not parsing, so the work went there:

• Pre-filter — a precompiled NSRegularExpression skips parsing any file that doesn't mention a relevant macro attribute. Benchmarked ~20x faster over a large tree than repeated String.contains, since almost no file matches.
• Directory pruning — .build, Pods, .git (and hidden dirs) are skipped during the walk.
• No per-entry stat — directory-ness is read from hasDirectoryPath rather than re-stat-ing each entry.

Over ~/Work/expo/main (~1600 .swift files): ~3s, only a handful of files parsed.

Structure

• Library (ExpoModulesScanner), grouped by concern, all internal:
  • Core/ — the detection model (Detection, MacroArgument, ScanStats), the SyntaxVisitor, and the shared scan core (collectDetections, pre-filter, file walk).
  • Modules/ — the scan-modules command: scanModules, its ScannedModule/ScanModulesResult output, and the public Scanner.runModules entry. Exports/ follows when that command lands.
• ExpoModulesScannerCLI executable — argument parsing, subcommand dispatch, usage text; calls into the library. Exposed as the ExpoModulesScanner product so the binary name matches the tool.
• ExpoModulesScannerTests — reaches the logic via @testable import.

Scope / follow-ups

• scan-exports deep member extraction (the @JS/@Record/constructor surface, feeding TS type generation) is a separate PR.
• Nested @ExpoModule types (valid Swift, inside another type/enum/extension) are currently not detected — flagged with a TODO as a decision to make later.
• Path scoping (e.g. excluding test fixtures) is left to the caller by design; a --root override for the reported paths' base is a possible future addition.