@expo/expo-modules-macros-plugin 0.9.0 → 0.11.0

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

@@ -50,7 +50,7 @@ func scanFiles(
 func collectDetections(
   paths: [String],
   macros: Set<DetectedMacro>,
-  configuration: ScanBuildConfiguration = .init(platform: nil, defines: [])
+  configuration: ScanBuildConfiguration? = nil
 ) -> (detections: [Detection], warnings: [ScanWarning], stats: ScanStats) {
   var detections: [Detection] = []
   var warnings: [ScanWarning] = []
@@ -68,7 +68,7 @@ func detect(
   source: String,
   file: String,
   macros: Set<DetectedMacro>,
-  configuration: ScanBuildConfiguration
+  configuration: ScanBuildConfiguration?
 ) -> (detections: [Detection], warnings: [ScanWarning]) {
   let tree = Parser.parse(source: source)
   let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: macros, configuration: configuration)
@@ -100,11 +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. `node_modules` makes any npm package root safe to pass as a
-/// scan path: nested dependencies are separate packages and get scanned on their own.
-private let prunedDirectoryNames: Set<String> = [".build", "Pods", ".git", "node_modules"]
+/// 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/Exports/ExportedSurface.swift

@@ -178,9 +178,16 @@ struct ExportedSurface: Encodable, Equatable {
   let records: [ExportedRecord]
 }
 
+/// Version of the `scan-exports` output shape. Bumped on any breaking change to the envelope or to
+/// anything under `exports`, so a consumer can verify it understands the output before trusting it.
+/// Versioned independently of `scanModulesSchemaVersion`: the two commands serve different consumers
+/// and change for different reasons.
+let scanExportsSchemaVersion = 1
+
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).
 struct ScanExportsResult: Encodable, Equatable {
+  let schemaVersion: Int
   let exports: ExportedSurface
   let stats: ScanStats
 }

package/apple/Sources/ExpoModulesScanner/Exports/ScanExports.swift

@@ -41,6 +41,7 @@ func scanExports(paths: [String]) -> ScanExportsResult {
   }
 
   return ScanExportsResult(
+    schemaVersion: scanExportsSchemaVersion,
     exports: ExportedSurface(modules: modules, sharedObjects: sharedObjects, records: records),
     stats: stats
   )

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

@@ -1,4 +1,5 @@
 import Foundation
+import SwiftParser
 
 /// 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.
@@ -10,11 +11,10 @@ public enum Scanner {
   /// 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.)
   ///
-  /// `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)
+  /// `defines` (the `--define` options) asserts conditional compilation flags; see `scanModules`
+  /// for how they and platforms shape each module's `platforms` list.
+  public static func runModules(paths: [String], defines: [String] = []) -> Int32 {
+    let result = scanModules(paths: paths, defines: Set(defines))
 
     do {
       let encoder = JSONEncoder()
@@ -31,10 +31,11 @@ public enum Scanner {
 }
 
 /// 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 the deep `scan-exports` surface carries the richer per-member detail instead.
+/// register a module: the Swift class name, the JS name it registers under, the platforms that
+/// include it, 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 the deep `scan-exports` surface carries the richer
+/// per-member detail instead.
 struct ScannedModule: Codable, Equatable {
   /// The Swift class name the module is declared as.
   let name: String
@@ -50,14 +51,22 @@ struct ScannedModule: Codable, Equatable {
   /// classes with a diagnostic instead of emitting a provider that fails to compile.
   let accessLevel: String
 
+  /// The Apple OSes whose builds include this class, spelled as `os(...)` spells them and compared
+  /// case-sensitively. An unconditional module lists every OS. Empty means no build is known to
+  /// include it, because the enclosing conditions depend on flags not asserted with `--define` or
+  /// on conditions a static scan cannot answer (those are reported in `warnings`). The consumer
+  /// must not assume such a class exists.
+  let platforms: [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
+/// trusting it (and fall back to config-declared modules when it doesn't). Version 2 added the
+/// per-module `platforms` list and made the module list platform-agnostic.
+let scanModulesSchemaVersion = 2
 
 /// 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
@@ -73,22 +82,80 @@ struct ScanModulesResult: Codable, Equatable {
   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], configuration: ScanBuildConfiguration = .init(platform: nil, defines: [])) -> ScanModulesResult {
-  let scan = collectDetections(paths: paths, macros: [.expoModule], configuration: configuration)
+/// The Apple OSes a scan attributes modules to. `condition` is what `os(...)` matches; `reported`
+/// is what the JSON carries. They are identical today, but stated separately so the output
+/// contract cannot drift if the matcher's spelling changes.
+private let platformUniverse: [(condition: String, reported: String)] = [
+  (condition: "iOS", reported: "iOS"),
+  (condition: "macOS", reported: "macOS"),
+  (condition: "tvOS", reported: "tvOS"),
+  (condition: "watchOS", reported: "watchOS"),
+  (condition: "visionOS", reported: "visionOS"),
+]
+
+/// Scans the given paths for top-level `@ExpoModule` types and returns every module found in any
+/// `#if` branch (in file then source order), each with the platforms whose builds include it, 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.
+///
+/// Each file is parsed once and walked once per platform (plus once unconditionally to enumerate
+/// every module): a module's `platforms` are the OSes whose evaluated walk reached it, given the
+/// asserted `defines`. The scanner reports the facts; filtering to the platform being linked is the
+/// consumer's call.
+func scanModules(paths: [String], defines: Set<String> = []) -> ScanModulesResult {
+  var modules: [ScannedModule] = []
+  var warnings: [ScanWarning] = []
+  var seenWarnings = Set<ScanWarning>()
+
+  let stats = scanFiles(paths: paths, macros: [.expoModule]) { source, file in
+    let tree = Parser.parse(source: source)
+
+    // The unconditional walk enumerates every module in the file, in source order.
+    let allModules = DetectionVisitor(file: file, tree: tree, detectedMacros: [.expoModule], configuration: nil)
+    allModules.walk(tree)
 
-  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, accessLevel: $0.accessLevel, file: $0.file)
+    // One evaluated walk per OS attributes each module to the platforms that include it. The walks
+    // are cheap relative to the parse, which is shared.
+    var platformsByDetection: [String: [String]] = [:]
+    for platform in platformUniverse {
+      let configuration = ScanBuildConfiguration(platform: platform.condition, defines: defines)
+      let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: [.expoModule], configuration: configuration)
+      visitor.walk(tree)
+      for detection in visitor.detections {
+        platformsByDetection[detectionKey(detection), default: []].append(platform.reported)
+      }
+      // The same unanswerable condition diagnoses identically in every per-platform walk; report
+      // it once.
+      for warning in visitor.warnings where seenWarnings.insert(warning).inserted {
+        warnings.append(warning)
+      }
+    }
+
+    for detection in allModules.detections {
+      // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")` override, else
+      // the class name.
+      modules.append(
+        ScannedModule(
+          name: detection.name,
+          jsName: detection.jsName ?? detection.name,
+          accessLevel: detection.accessLevel,
+          platforms: platformsByDetection[detectionKey(detection)] ?? [],
+          file: detection.file
+        )
+      )
+    }
   }
 
   return ScanModulesResult(
     schemaVersion: scanModulesSchemaVersion,
     modules: modules,
-    warnings: scan.warnings,
-    stats: scan.stats
+    warnings: warnings,
+    stats: stats
   )
 }
+
+/// Identifies one declaration across the per-platform walks of the same tree: the source position
+/// is unique within a file, and the name guards against any position ambiguity.
+private func detectionKey(_ detection: Detection) -> String {
+  return "\(detection.line):\(detection.column):\(detection.name)"
+}

package/build/index.d.ts

@@ -0,0 +1,51 @@
+import { ScanExportsResult, ScanModulesResult } from './types';
+export * from './types';
+/** Options accepted by `scanModules`, mirroring the CLI's `scan-modules` flags. */
+export interface ScanModulesOptions {
+    /** Conditional compilation flags to treat as set, e.g. `['DEBUG']`. */
+    defines?: string[];
+    /** Overrides the scanner binary path. Defaults to the one shipped with this package. */
+    binaryPath?: string;
+}
+/** Options accepted by `scanExports`. The deep scan doesn't evaluate `#if`, so it takes no flags. */
+export interface ScanExportsOptions {
+    /** Overrides the scanner binary path. Defaults to the one shipped with this package. */
+    binaryPath?: string;
+}
+/**
+ * Thrown when the scanner exits non-zero. Exit code 2 is a usage error (bad subcommand or flags) and
+ * 1 means the report couldn't be encoded; both put a message on stderr, carried here as `stderr`.
+ */
+export declare class ScannerError extends Error {
+    readonly exitCode: number | null;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number | null, stderr: string);
+}
+/** Thrown when the binary's output schema doesn't match what these types were written against. */
+export declare class ScannerSchemaVersionError extends Error {
+    readonly command: string;
+    readonly found: number;
+    readonly expected: number;
+    constructor(command: string, found: number, expected: number);
+}
+/**
+ * Absolute path to the scanner binary shipped with this package. It doubles as the macro plugin
+ * executable, so it lives next to the Swift package rather than in a `bin` directory.
+ */
+export declare function getScannerBinaryPath(): string;
+/**
+ * Fast scan for top-level `@ExpoModule` types, for autolinking. Each path is a `.swift` file or a
+ * directory, scanned recursively.
+ *
+ * Conditions the scan can't answer statically come back in `warnings` rather than throwing, so the
+ * caller can surface them alongside its own diagnostics.
+ */
+export declare function scanModules(paths: string[], options?: ScanModulesOptions): Promise<ScanModulesResult>;
+/**
+ * Deep scan of the full JS-exported surface, for TypeScript type generation. Each path is a `.swift`
+ * file or a directory, scanned recursively.
+ *
+ * Unlike `scanModules`, this doesn't evaluate `#if` blocks, so it takes no define option:
+ * conditional declarations are reported as if their conditions held.
+ */
+export declare function scanExports(paths: string[], options?: ScanExportsOptions): Promise<ScanExportsResult>;

package/build/index.js

@@ -0,0 +1,153 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScannerSchemaVersionError = exports.ScannerError = void 0;
+exports.getScannerBinaryPath = getScannerBinaryPath;
+exports.scanModules = scanModules;
+exports.scanExports = scanExports;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const types_1 = require("./types");
+__exportStar(require("./types"), exports);
+/**
+ * Thrown when the scanner exits non-zero. Exit code 2 is a usage error (bad subcommand or flags) and
+ * 1 means the report couldn't be encoded; both put a message on stderr, carried here as `stderr`.
+ */
+class ScannerError extends Error {
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = 'ScannerError';
+    }
+}
+exports.ScannerError = ScannerError;
+/** Thrown when the binary's output schema doesn't match what these types were written against. */
+class ScannerSchemaVersionError extends Error {
+    constructor(command, found, expected) {
+        super(`\`${command}\` returned schema version ${found}, but this package understands ${expected}. ` +
+            'The scanner binary and this wrapper are out of sync; align their versions.');
+        this.command = command;
+        this.found = found;
+        this.expected = expected;
+        this.name = 'ScannerSchemaVersionError';
+    }
+}
+exports.ScannerSchemaVersionError = ScannerSchemaVersionError;
+/**
+ * Absolute path to the scanner binary shipped with this package. It doubles as the macro plugin
+ * executable, so it lives next to the Swift package rather than in a `bin` directory.
+ */
+function getScannerBinaryPath() {
+    return node_path_1.default.join(__dirname, '..', 'apple', 'ExpoModulesMacros-tool');
+}
+/**
+ * Runs a scanner subcommand and parses its JSON report.
+ *
+ * Paths are passed after the options. The CLI has no `--` separator, so a path spelled exactly
+ * `--define` would be read as that option instead; such a path isn't representable and the scan
+ * fails with a usage error rather than scanning the wrong thing. `-h`/`--help` are worse, since the
+ * CLI answers them from anywhere in argv by printing usage and exiting 0, which would surface as an
+ * opaque parse failure. `assertRepresentablePaths` rejects those before spawning.
+ *
+ * Output is buffered rather than streamed: the report is only usable once complete. Scanning all of
+ * `expo/packages` produces ~17 KB, so the raised `maxBuffer` is headroom for a far larger tree
+ * rather than a limit anything is expected to approach.
+ */
+/**
+ * Rejects paths the CLI can't receive as paths. `-h`/`--help` are recognized anywhere in argv, so
+ * passing one as a path prints usage and exits 0: the scan never runs, and without this the caller
+ * would see a JSON parse failure pointing at the wrong cause.
+ */
+function assertRepresentablePaths(command, paths) {
+    const helpFlag = paths.find((candidate) => candidate === '-h' || candidate === '--help');
+    if (helpFlag !== undefined) {
+        throw new TypeError(`${command} cannot scan a path named \`${helpFlag}\`: the scanner reads it as a help ` +
+            'request. Pass a path that resolves to the same file, such as `./' +
+            helpFlag +
+            '`.');
+    }
+}
+function runScanner(binaryPath, args) {
+    return new Promise((resolve, reject) => {
+        (0, node_child_process_1.execFile)(binaryPath, args, { maxBuffer: 64 * 1024 * 1024, encoding: 'utf8' }, (error, stdout, stderr) => {
+            if (error) {
+                // A spawn failure reports a string `code` (e.g. 'ENOENT'); a non-zero exit reports a
+                // number. Only the latter is an exit status.
+                const exitCode = typeof error.code === 'number' ? error.code : null;
+                if (error.code === 'ENOENT') {
+                    reject(new ScannerError(`The scanner binary is missing at ${binaryPath}. Run \`npm run build\` in this package to build it.`, null, stderr));
+                    return;
+                }
+                reject(new ScannerError(`\`${node_path_1.default.basename(binaryPath)} ${args.join(' ')}\` failed: ${stderr.trim() || error.message}`, exitCode, stderr));
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch (parseError) {
+                reject(new ScannerError(`Could not parse the scanner's JSON output: ${parseError.message}`, null, stderr));
+            }
+        });
+    });
+}
+/**
+ * Fast scan for top-level `@ExpoModule` types, for autolinking. Each path is a `.swift` file or a
+ * directory, scanned recursively.
+ *
+ * Conditions the scan can't answer statically come back in `warnings` rather than throwing, so the
+ * caller can surface them alongside its own diagnostics.
+ */
+async function scanModules(paths, options = {}) {
+    if (paths.length === 0) {
+        throw new TypeError('scanModules requires at least one path');
+    }
+    assertRepresentablePaths('scanModules', paths);
+    const args = ['scan-modules'];
+    for (const define of options.defines ?? []) {
+        args.push('--define', define);
+    }
+    args.push(...paths);
+    const result = await runScanner(options.binaryPath ?? getScannerBinaryPath(), args);
+    if (result.schemaVersion !== types_1.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION) {
+        throw new ScannerSchemaVersionError('scan-modules', result.schemaVersion, types_1.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION);
+    }
+    return result;
+}
+/**
+ * Deep scan of the full JS-exported surface, for TypeScript type generation. Each path is a `.swift`
+ * file or a directory, scanned recursively.
+ *
+ * Unlike `scanModules`, this doesn't evaluate `#if` blocks, so it takes no define option:
+ * conditional declarations are reported as if their conditions held.
+ */
+async function scanExports(paths, options = {}) {
+    if (paths.length === 0) {
+        throw new TypeError('scanExports requires at least one path');
+    }
+    assertRepresentablePaths('scanExports', paths);
+    const result = await runScanner(options.binaryPath ?? getScannerBinaryPath(), [
+        'scan-exports',
+        ...paths,
+    ]);
+    if (result.schemaVersion !== types_1.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION) {
+        throw new ScannerSchemaVersionError('scan-exports', result.schemaVersion, types_1.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION);
+    }
+    return result;
+}

package/build/types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Hand-written mirrors of the scanner's JSON output. The Swift `Codable` types in
+ * `apple/Sources/ExpoModulesScanner` are the source of truth; these are kept in sync by hand, which
+ * is why each command carries a `schemaVersion` the wrapper checks at runtime.
+ */
+/** The JS `typeof` category a boundary type reports, mirroring `JSType`. */
+export type JSType = 'undefined' | 'object' | 'boolean' | 'number' | 'bigint' | 'string' | 'symbol' | 'function';
+/**
+ * A boundary type as a tagged tree, mirroring `TypeNode`. Discriminate on `kind`.
+ *
+ * `unknown` carries no `typeof`, and an `optional` reports its *wrapped* node's category, so
+ * `(Int, String)?` (an optional around an unknown) has none either. Every other node always has one.
+ * The absent (`undefined`) case is carried by the `optional` wrapper itself rather than by its
+ * wrapped node.
+ */
+export type TypeNode = {
+    kind: 'primitive';
+    typeof: JSType;
+    name: string;
+} | {
+    kind: 'optional';
+    typeof?: JSType;
+    wrapped: TypeNode;
+} | {
+    kind: 'array';
+    typeof: JSType;
+    element: TypeNode;
+} | {
+    kind: 'dictionary';
+    typeof: JSType;
+    key: TypeNode;
+    value: TypeNode;
+} | {
+    kind: 'promise';
+    typeof: JSType;
+    value: TypeNode;
+} | {
+    kind: 'function';
+    typeof: JSType;
+    parameters: TypeNode[];
+    /** Absent for a `Void` result. */
+    returns?: TypeNode;
+    async: boolean;
+    throws: boolean;
+}
+/** Any other named type (record, shared object, enum, ...); `name` may be qualified. */
+ | {
+    kind: 'ref';
+    typeof: JSType;
+    name: string;
+}
+/** A type the scanner couldn't interpret; `text` is its source spelling. */
+ | {
+    kind: 'unknown';
+    text: string;
+};
+/** One parameter of a `@JS` function or `@JS init`. */
+export interface ExportedParameter {
+    /** The argument label, or `_` when unlabeled. */
+    label: string;
+    /** The internal parameter name. */
+    name: string;
+    type: TypeNode;
+    /** True when the caller may omit it: a default value or an optional type. */
+    optional: boolean;
+}
+/** One `@JS func` on a module or shared object. */
+export interface ExportedFunction {
+    name: string;
+    /** The JS name it binds under: the `@JS("x")` override, else `name`. */
+    jsName: string;
+    parameters: ExportedParameter[];
+    /** Absent for a `Void` return. */
+    returns?: TypeNode;
+    async: boolean;
+    throws: boolean;
+    static: boolean;
+}
+/** One `@JS var` on a module or shared object. */
+export interface ExportedProperty {
+    name: string;
+    jsName: string;
+    /** Absent when the type isn't determinable syntactically; the macro binds it getter-only. */
+    type?: TypeNode;
+    readonly: boolean;
+    static: boolean;
+}
+/** One `@Record` property: a data slot, not a JS accessor. */
+export interface ExportedRecordProperty {
+    name: string;
+    type: TypeNode;
+    /** Optional-typed. */
+    optional: boolean;
+    /** Whether JS must supply it: neither defaulted nor optional. */
+    required: boolean;
+}
+/** An `@ExpoModule` type and its `@JS` surface. */
+export interface ExportedModule {
+    name: string;
+    /** The JS module name: `@ExpoModule("Foo")` override, else the class name. */
+    jsName: string;
+    functions: ExportedFunction[];
+    properties: ExportedProperty[];
+    /** Absolute source path. */
+    file: string;
+}
+/** A `@SharedObject` type: a JS class with an optional constructor plus its `@JS` members. */
+export interface ExportedSharedObject {
+    name: string;
+    jsName: string;
+    /** The `@JS init` parameters, or absent when there's none. At most one constructor. */
+    constructorParameters?: ExportedParameter[];
+    functions: ExportedFunction[];
+    properties: ExportedProperty[];
+    file: string;
+}
+/** A `@Record` type and its properties. */
+export interface ExportedRecord {
+    name: string;
+    properties: ExportedRecordProperty[];
+    file: string;
+}
+/** The exported types grouped by kind. */
+export interface ExportedSurface {
+    modules: ExportedModule[];
+    sharedObjects: ExportedSharedObject[];
+    records: ExportedRecord[];
+}
+/** A `#if` condition the scan couldn't answer statically. */
+export interface ScanWarning {
+    message: string;
+    file: string;
+    line: number;
+}
+/** Counts describing how much work a scan did. */
+export interface ScanStats {
+    /** `.swift` files the walk found and read. */
+    filesScanned: number;
+    /** Of those, how many contained a macro attribute and so were parsed. */
+    filesParsed: number;
+    /** Wall-clock duration of the scan, in milliseconds. */
+    durationMs: number;
+}
+/**
+ * An Apple OS the scanner attributes modules to, spelled as `os(...)` spells it. The casing is part
+ * of the output contract, so consumers with a lowercase convention must fold the case themselves.
+ */
+export type ScannedPlatform = 'iOS' | 'macOS' | 'tvOS' | 'watchOS' | 'visionOS';
+/** One module in the `scan-modules` output. */
+export interface ScannedModule {
+    name: string;
+    /** The resolved JS name: the `@ExpoModule("Foo")` override, else the class name. */
+    jsName: string;
+    /**
+     * The spelled access level, or `internal` when none is written. The generated provider references
+     * the class from the app target, so anything below `public` can't be registered.
+     */
+    accessLevel: string;
+    /**
+     * The OSes whose builds include this class, resolved from the enclosing `#if` conditions. An
+     * unconditional module lists every OS. Empty means no build is known to include it, so don't
+     * register it.
+     */
+    platforms: ScannedPlatform[];
+    file: string;
+}
+/** The `scan-modules` result. */
+export interface ScanModulesResult {
+    schemaVersion: number;
+    modules: ScannedModule[];
+    warnings: ScanWarning[];
+    stats: ScanStats;
+}
+/** The `scan-exports` result. */
+export interface ScanExportsResult {
+    schemaVersion: number;
+    exports: ExportedSurface;
+    stats: ScanStats;
+}
+/**
+ * The output schema versions this package was written against. The wrapper compares these to the
+ * `schemaVersion` in each report and throws on a mismatch, so a binary/wrapper version skew surfaces
+ * as a clear error instead of silently misread fields.
+ */
+export declare const SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
+export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 1;

package/build/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Hand-written mirrors of the scanner's JSON output. The Swift `Codable` types in
+ * `apple/Sources/ExpoModulesScanner` are the source of truth; these are kept in sync by hand, which
+ * is why each command carries a `schemaVersion` the wrapper checks at runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = void 0;
+/**
+ * The output schema versions this package was written against. The wrapper compares these to the
+ * `schemaVersion` in each report and throws on a mismatch, so a binary/wrapper version skew surfaces
+ * as a clear error instead of silently misread fields.
+ */
+exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
+exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 1;

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@expo/expo-modules-macros-plugin",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Swift macro plugin for Expo modules",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
   "license": "MIT",
   "author": "650 Industries, Inc.",
   "homepage": "https://github.com/expo/expo-modules-macros-plugin",
@@ -10,6 +12,14 @@
     "url": "git+https://github.com/expo/expo-modules-macros-plugin.git"
   },
   "scripts": {
-    "build": "node apple/build.js"
+    "build": "node apple/build.js",
+    "build:ts": "tsc -p tsconfig.json",
+    "clean": "rm -rf build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build:ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
   }
 }