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

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,264 @@
+/**
+ * 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; `name` may be qualified.
+ *
+ * `refKind` says which of this surface's arrays declares that name, so you don't have to look it
+ * up. It is absent when the scan declares no such type: a platform convertible (`CGPoint`, `URL`)
+ * or a type from another module, which your own catalog resolves.
+ *
+ * `typeof` follows the resolved kind, so a raw-value enum reports `string` or `number` rather than
+ * `object`. Only the scanner can determine that, since it comes from the declaration's `rawType`.
+ */
+ | {
+    kind: 'ref';
+    typeof: JSType;
+    name: string;
+    refKind?: 'record' | 'sharedObject' | 'enum' | 'union';
+}
+/** 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[];
+    events: ExportedEvent[];
+    /** Absolute source path. */
+    file: string;
+}
+/** One `@Event var`: a typed event JS listens for by name, rather than calls. */
+export interface ExportedEvent {
+    /** The Swift property name, e.g. `onStatusChange`. */
+    name: string;
+    /**
+     * The name JS listens under: the `@Event("x")` override, else `name` with a conventional `on`
+     * prefix stripped and decapitalized (`onStatusChange` -> `statusChange`).
+     */
+    jsName: string;
+    /** The payload type, absent for a no-payload `() -> Void` event. */
+    payload?: TypeNode;
+    /** `@Event(sync: true)`, dispatching inline on the JS thread instead of scheduling. */
+    sync: boolean;
+}
+/** 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[];
+    events: ExportedEvent[];
+    file: string;
+}
+/** A `@Record` type and its properties. */
+export interface ExportedRecord {
+    name: string;
+    properties: ExportedRecordProperty[];
+    file: string;
+}
+/**
+ * One case of a reported enum.
+ *
+ * What `rawValue` carries depends on the enum's raw type:
+ * - `String`: always present, and decoded (`case active = "act"` reports `act`, unquoted). A case
+ *   writing none takes its own name, so nothing is left to derive.
+ * - an integer type: present only where written, as source text (`1`, `1 << 3`), since the value may
+ *   be an expression a syntactic scan cannot evaluate. Swift also continues from the preceding case's
+ *   value (`case a = 1; case b` makes `b` 2), and that carry is yours to apply.
+ * - no raw type: always absent, since the enum has no raw values.
+ */
+export interface ExportedEnumCase {
+    /** The case name as declared. */
+    name: string;
+    /** The raw value, decoded for a string and verbatim source text otherwise, or absent per the rule above. */
+    rawValue?: string;
+}
+/**
+ * An `Enumerable` enum: a type crossing the boundary as its raw value rather than as an object.
+ * Detected by conformance, not by a macro attribute, so it carries no `jsName`.
+ */
+export interface ExportedEnum {
+    name: string;
+    /** The raw value type as written, absent for a bare `Enumerable` conformance with no raw type. */
+    rawType?: TypeNode;
+    cases: ExportedEnumCase[];
+    file: string;
+}
+/**
+ * One alternative a `@Union` may hold. Not a member in the sense a module or shared object has members
+ * (functions, properties, events).
+ */
+export interface ExportedUnionMember {
+    /** The Swift case name. Swift-side only: discrimination is structural, so it never reaches JS. */
+    name: string;
+    /** The associated value's type: what this alternative decodes from. */
+    type: TypeNode;
+}
+/**
+ * A `@Union` enum: a typed union of its members' payload types (`A | B | C`).
+ *
+ * `members` is ordered, and the order is part of the contract: decode takes the first payload that
+ * succeeds, so where two shapes overlap (`Int` and `Double`, two compatible records) the earlier one
+ * wins. Reordering them describes a different union than the one the module runs.
+ */
+export interface ExportedUnion {
+    name: string;
+    members: ExportedUnionMember[];
+    file: string;
+}
+/** The exported types grouped by kind. */
+export interface ExportedSurface {
+    modules: ExportedModule[];
+    sharedObjects: ExportedSharedObject[];
+    records: ExportedRecord[];
+    enums: ExportedEnum[];
+    unions: ExportedUnion[];
+}
+/** 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 matched the pre-filter (a macro attribute or a scanned conformance). */
+    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 = 5;

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 = 5;

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@expo/expo-modules-macros-plugin",
-  "version": "0.10.0",
+  "version": "0.12.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"
   }
 }