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

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

@@ -0,0 +1,121 @@
+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), or `nil` when no `--platform`
+  /// was given, in which case `os(...)` conditions are unanswerable.
+  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 {
+    guard let platform else {
+      throw ScanConfigurationError("cannot evaluate 'os(\(name))': no --platform was given")
+    }
+    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")
+    }
+    guard let platform else {
+      throw ScanConfigurationError("cannot evaluate 'canImport(\(module))': no --platform was given")
+    }
+    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

@@ -44,23 +44,36 @@ func scanFiles(
 }
 
 /// Walks `paths`, parses each `.swift` file that might contain one of `macros`, and returns every
-/// detection (in file then source order) with the run's stats — the shape `scan-modules` projects.
-/// A thin layer over `scanFiles` that accumulates the per-file detections.
-func collectDetections(paths: [String], macros: Set<DetectedMacro>) -> (detections: [Detection], stats: ScanStats) {
+/// 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 = .init(platform: nil, defines: [])
+) -> (detections: [Detection], warnings: [ScanWarning], stats: ScanStats) {
   var detections: [Detection] = []
+  var warnings: [ScanWarning] = []
   let stats = scanFiles(paths: paths, macros: macros) { source, file in
-    detections.append(contentsOf: detect(source: source, file: file, macros: macros))
+    let result = detect(source: source, file: file, macros: macros, configuration: configuration)
+    detections.append(contentsOf: result.detections)
+    warnings.append(contentsOf: result.warnings)
   }
-  return (detections, stats)
+  return (detections, warnings, stats)
 }
 
-/// 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] {
+/// 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)
+  let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: macros, configuration: configuration)
   visitor.walk(tree)
-  return visitor.detections
+  return (visitor.detections, visitor.warnings)
 }
 
 // MARK: - Pre-filter
@@ -87,10 +100,21 @@ func mightContainMacro(in source: String, prefilter: NSRegularExpression) -> Boo
 
 // 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"]
+/// 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

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

@@ -9,8 +9,12 @@ 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. (The deep `scan-exports` command has
   /// its own `runExports` entry returning its own result type.)
-  public static func runModules(paths: [String]) -> Int32 {
-    let result = scanModules(paths: paths)
+  ///
+  /// `platform` and `defines` (the `--platform` and `--define` options) form the configuration that
+  /// `#if` conditions are evaluated against; see `ScanBuildConfiguration`.
+  public static func runModules(paths: [String], platform: String? = nil, defines: [String] = []) -> Int32 {
+    let configuration = ScanBuildConfiguration(platform: platform, defines: Set(defines))
+    let result = scanModules(paths: paths, configuration: configuration)
 
     do {
       let encoder = JSONEncoder()
@@ -40,29 +44,51 @@ struct ScannedModule: Codable, Equatable {
   /// and the consumer never has to apply the fallback itself.
   let jsName: String
 
+  /// The class's spelled access modifier (`open`, `public`, `package`, `fileprivate`, `private`),
+  /// or `internal` when none is written. The generated modules provider references the class from
+  /// the app target, which requires `public`/`open`, so the consumer uses this to skip inaccessible
+  /// classes with a diagnostic instead of emitting a provider that fails to compile.
+  let accessLevel: String
+
   /// Source file the module was found in, relative to the path the scanner was invoked with.
   let file: String
 }
 
+/// Version of the `scan-modules` output shape. Bumped on any breaking change to the envelope or to
+/// `ScannedModule`, so `expo-modules-autolinking` can verify it understands the output before
+/// trusting it (and fall back to config-declared modules when it doesn't).
+let scanModulesSchemaVersion = 1
+
 /// The `scan-modules` result: the detected modules plus the stats describing the run. Encoded as the
 /// command's JSON output. (`scan-exports` returns its own `ScanExportsResult` shape; the two commands
 /// serve different consumers and don't share an envelope.)
 struct ScanModulesResult: Codable, Equatable {
+  let schemaVersion: Int
   let modules: [ScannedModule]
+
+  /// Warnings for `#if` conditions the scan couldn't answer statically (see `ScanWarning`). Carried
+  /// in the report rather than on stderr so the consumer can attach them to its own output.
+  let warnings: [ScanWarning]
+
   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])
+func scanModules(paths: [String], configuration: ScanBuildConfiguration = .init(platform: nil, defines: [])) -> ScanModulesResult {
+  let scan = collectDetections(paths: paths, macros: [.expoModule], configuration: configuration)
 
   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)
+    ScannedModule(name: $0.name, jsName: $0.jsName ?? $0.name, accessLevel: $0.accessLevel, file: $0.file)
   }
 
-  return ScanModulesResult(modules: modules, stats: scan.stats)
+  return ScanModulesResult(
+    schemaVersion: scanModulesSchemaVersion,
+    modules: modules,
+    warnings: scan.warnings,
+    stats: scan.stats
+  )
 }

package/package.json

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

package/apple/Sources/ExpoModulesScannerCLI/main.swift

@@ -1,71 +0,0 @@
-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":
-  guard !paths.isEmpty else {
-    fail("scan-exports requires at least one path", usage: true)
-  }
-  exit(Scanner.runExports(paths: paths))
-
-default:
-  fail("unknown subcommand '\(subcommand)'", usage: true)
-}