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

package/apple/Sources/ExpoModulesScanner/Modules/ScanModules.swift

@@ -0,0 +1,68 @@
+import Foundation
+
+/// The scanner's public entry point. Argument parsing, subcommand dispatch, and usage text live in
+/// the CLI target; this just runs a command and writes its JSON report to stdout.
+///
+/// The detection model (`Detection`, `DetectionVisitor`, …) stays `internal`: tests reach it via
+/// `@testable import`, and the CLI only needs these entries, so nothing else is exposed.
+public enum Scanner {
+  /// Runs the `scan-modules` command over `paths`, prints the JSON report to stdout, and returns a
+  /// process exit code: `0` on success, `1` if encoding fails. (`scan-exports` will get its own
+  /// `run`-style entry returning its own result type when implemented.)
+  public static func runModules(paths: [String]) -> Int32 {
+    let result = scanModules(paths: paths)
+
+    do {
+      let encoder = JSONEncoder()
+      encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+      let data = try encoder.encode(result)
+      FileHandle.standardOutput.write(data)
+      FileHandle.standardOutput.write(Data("\n".utf8))
+      return 0
+    } catch {
+      FileHandle.standardError.write(Data("error: failed to encode results: \(error)\n".utf8))
+      return 1
+    }
+  }
+}
+
+/// One module in the `scan-modules` output. Trimmed to what `expo-modules-autolinking` needs to
+/// register a module: the Swift class name, the JS name it registers under, and the file it's in.
+/// The richer fields the visitor captures (declaration kind, raw macro arguments, line/column) are
+/// dropped here — they're redundant for this command (the macro is always `@ExpoModule` on a class)
+/// and belong to the deep `scan-exports` surface instead.
+struct ScannedModule: Codable, Equatable {
+  /// The Swift class name the module is declared as.
+  let name: String
+
+  /// The fully-resolved JS module name: the `@ExpoModule("Foo")` override when present, otherwise the
+  /// class name. Resolved here (rather than left `nil`) so it matches how the macro derives the name
+  /// and the consumer never has to apply the fallback itself.
+  let jsName: String
+
+  /// Source file the module was found in, relative to the path the scanner was invoked with.
+  let file: String
+}
+
+/// The `scan-modules` result: the detected modules plus the stats describing the run. Encoded as the
+/// command's JSON output. (`scan-exports` will return its own shape when implemented; the two
+/// commands serve different consumers and aren't expected to share an envelope.)
+struct ScanModulesResult: Codable, Equatable {
+  let modules: [ScannedModule]
+  let stats: ScanStats
+}
+
+/// Scans the given paths for top-level `@ExpoModule` types and returns the modules (in file then
+/// source order) plus the stats for the run — the `scan-modules` command. Kept separate from the
+/// public entry (and `internal`) so tests can drive it without going through argv/stdout.
+func scanModules(paths: [String]) -> ScanModulesResult {
+  let scan = collectDetections(paths: paths, macros: [.expoModule])
+
+  let modules = scan.detections.map {
+    // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")` override, else the
+    // class name.
+    ScannedModule(name: $0.name, jsName: $0.jsName ?? $0.name, file: $0.file)
+  }
+
+  return ScanModulesResult(modules: modules, stats: scan.stats)
+}

package/apple/Sources/ExpoModulesScannerCLI/main.swift

@@ -0,0 +1,70 @@
+import ExpoModulesScanner
+import Foundation
+
+/// Command-line front end for the scanner. Parses the subcommand and paths, then delegates to the
+/// matching library entry (which runs the scan and writes its JSON output). 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
+
+let toolName = "ExpoModulesScanner"
+
+let usageText = """
+  usage: \(toolName) <subcommand> <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:
+    -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.
+func printUsage(to handle: FileHandle = .standardError) {
+  handle.write(Data(usageText.utf8))
+}
+
+func fail(_ message: String, usage: Bool = false, code: Int32 = 2) -> Never {
+  FileHandle.standardError.write(Data("error: \(message)\n".utf8))
+  if usage {
+    printUsage()
+  }
+  exit(code)
+}
+
+var arguments = Array(CommandLine.arguments.dropFirst())
+
+// `-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)
+  exit(0)
+}
+
+guard !arguments.isEmpty else {
+  printUsage()
+  exit(2)
+}
+
+let subcommand = arguments.removeFirst()
+let paths = arguments
+
+switch subcommand {
+case "scan-modules":
+  guard !paths.isEmpty else {
+    fail("scan-modules requires at least one path", usage: true)
+  }
+  exit(Scanner.runModules(paths: paths))
+
+case "scan-exports":
+  // Deep extraction (members, record fields, the JS surface of each type) lands in a separate PR.
+  // The subcommand is recognized so the CLI surface is stable, but it isn't implemented yet.
+  fail("scan-exports is not yet implemented", code: 1)
+
+default:
+  fail("unknown subcommand '\(subcommand)'", usage: true)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/expo-modules-macros-plugin",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Swift macro plugin for Expo modules",
   "license": "MIT",
   "author": "650 Industries, Inc.",