@expo/expo-modules-macros-plugin 0.0.9 → 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,116 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: Release type
+        type: choice
+        required: true
+        default: patch
+        options:
+          - patch
+          - minor
+          - major
+          - prepatch
+          - preminor
+          - premajor
+          - prerelease
+
+concurrency:
+  group: publish-${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Build and publish to npm
+    # Builds the native macOS tool binary, so it must run on macOS.
+    # The package declares swift-tools-version 6.2, which requires Xcode 26+.
+    runs-on: macos-26
+    permissions:
+      # Required for npm trusted publishing (OIDC) and provenance.
+      id-token: write
+      # Required to push the version bump commit/tag and create the release.
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          # The default token lets gh create the release and push the bump
+          # commit/tag. Note: commits pushed with GITHUB_TOKEN do NOT trigger
+          # other workflows (e.g. the Swift CI), by GitHub's design.
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Update npm
+        # Trusted publishing requires npm >= 11.5.1.
+        run: npm install -g npm@latest
+
+      - name: Configure git
+        run: |
+          git config user.name "expo-bot"
+          git config user.email "expo-bot@users.noreply.github.com"
+
+      - name: Bump version
+        id: bump
+        # Only edit package.json here; the commit, tag and release are created
+        # at the end so a failed build/publish leaves the branch untouched.
+        run: |
+          version=$(npm version "${{ inputs.release_type }}" --no-git-tag-version)
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Bumping to $version"
+
+      - name: Select Xcode
+        # Pin to an Xcode that ships Swift 6.2 (required by Package.swift).
+        run: sudo xcode-select -switch /Applications/Xcode_26.4.1.app
+
+      - name: Cache SwiftPM build
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: apple/.build
+          key: spm-${{ runner.os }}-${{ hashFiles('apple/Package.resolved') }}
+          restore-keys: |
+            spm-${{ runner.os }}-
+
+      - name: Resolve dependencies
+        run: swift package resolve
+        working-directory: apple
+
+      - name: Build release tool
+        # Runs apple/build.js: builds the release plugin binary,
+        # copies it to apple/ExpoModulesMacros-tool, and strips it.
+        run: npm run build
+
+      - name: Publish
+        # Authentication is handled via OIDC trusted publishing — no token needed.
+        # npm generates provenance automatically when publishing via OIDC.
+        run: npm publish --access public
+
+      # Everything below only runs once the publish above has succeeded.
+
+      - name: Commit, tag and push
+        run: |
+          version="${{ steps.bump.outputs.version }}"
+          git commit -am "Release $version"
+          git tag "$version"
+          git push --follow-tags origin HEAD
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        # Tag prerelease versions (those containing a hyphen) as prereleases.
+        run: |
+          version="${{ steps.bump.outputs.version }}"
+          prerelease=""
+          case "$version" in
+            *-*) prerelease="--prerelease" ;;
+          esac
+          gh release create "$version" \
+            --title "$version" \
+            --generate-notes \
+            $prerelease

package/.github/workflows/swift.yml

@@ -0,0 +1,59 @@
+name: Swift
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: apple
+
+jobs:
+  build-and-test:
+    name: Build & test
+    # The package declares swift-tools-version 6.2, which requires Xcode 26+.
+    runs-on: macos-26
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Select Xcode
+        # Pin to an Xcode that ships Swift 6.2 (required by Package.swift).
+        run: sudo xcode-select -switch /Applications/Xcode_26.4.1.app
+
+      - name: Cache SwiftPM build
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: apple/.build
+          key: spm-${{ runner.os }}-${{ hashFiles('apple/Package.resolved') }}
+          restore-keys: |
+            spm-${{ runner.os }}-
+
+      - name: Resolve dependencies
+        run: swift package resolve
+
+      - name: Build release tool
+        # Runs `npm run build` (apple/build.js): builds the universal
+        # (arm64 + x86_64) release plugin binary, copies it to
+        # apple/ExpoModulesMacros-tool, and strips it.
+        working-directory: ${{ github.workspace }}
+        run: npm run build
+
+      - name: Verify universal binary
+        run: |
+          archs="$(lipo -archs ExpoModulesMacros-tool)"
+          echo "Architectures: $archs"
+          case "$archs" in *arm64*) ;; *) echo "Missing arm64 slice"; exit 1;; esac
+          case "$archs" in *x86_64*) ;; *) echo "Missing x86_64 slice"; exit 1;; esac
+          arch -arm64 ./ExpoModulesMacros-tool < /dev/null
+          arch -x86_64 ./ExpoModulesMacros-tool < /dev/null
+
+      - name: Test
+        run: swift test -v

package/apple/Package.swift

@@ -2,6 +2,7 @@
 // The swift-tools-version declares the minimum version of Swift required to build this package.
 
 import CompilerPluginSupport
+import Foundation
 import PackageDescription
 
 let package = Package(
@@ -18,8 +19,14 @@ let package = Package(
         .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
         .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
       ]
-    ),
+    )
+  ]
+)
 
+// The Tests directory is excluded from the published npm package,
+// so only declare the test target when building from the repository.
+if FileManager.default.fileExists(atPath: Context.packageDirectory + "/Tests") {
+  package.targets.append(
     .testTarget(
       name: "ExpoModulesMacrosTests",
       dependencies: [
@@ -27,6 +34,6 @@ let package = Package(
         .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),
         .product(name: "SwiftSyntaxMacrosGenericTestSupport", package: "swift-syntax"),
       ]
-    ),
-  ]
-)
+    )
+  )
+}

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -3,13 +3,23 @@ import SwiftSyntaxBuilder
 import SwiftSyntaxMacros
 
 /**
- Member macro applied to a `Module` subclass. Scans the class body for declarations
- marked with `@JS` and synthesizes a framework-internal `_exposedDefinition()`
- method returning `[AnyDefinition]`. `expo-modules-core` calls it automatically
- and merges the result into the module's definition.
+ Macro applied to a module class. It plays three roles, each implemented in its own
+ extension below:
+
+ - `MemberMacro`: scans the class body for `@JS`-marked declarations and synthesizes a
+   framework-internal `_synthesizedDefinition()` returning `[AnyDefinition]`, which
+   `expo-modules-core` calls automatically and merges into the module's definition. When
+   the class doesn't already inherit `Module`/`BaseModule`, it also synthesizes the
+   `appContext` storage and `init(appContext:)` those base classes would have provided.
+ - `MemberAttributeMacro`: stamps `@JavaScriptActor` on `@JS` sync members and
+   `@ModuleDefinitionBuilder` on a `definition()` method.
+ - `ExtensionMacro`: adds the `AnyModule` conformance when the class doesn't inherit it.
+
+ Inheriting from `Module` is therefore optional — a class can carry any superclass (or
+ none) and still be a module, because everything inheritance used to provide is synthesized.
 
    @ExpoModule
-   public final class MyModule: Module {
+   public final class MyModule {
      public func definition() -> ModuleDefinition {
        Name("MyModule")
      }
@@ -33,7 +43,7 @@ public struct ExpoModuleMacro: MemberMacro {
     var entries: [String] = ["Name(\"\(moduleName)\")"]
 
     for typeName in classListArgument(of: node, label: "classes") {
-      entries.append("\(typeName)._exposedClassDefinition()")
+      entries.append("\(typeName)._synthesizedClassDefinition()")
     }
 
     for member in classDecl.memberBlock.members {
@@ -54,14 +64,153 @@ public struct ExpoModuleMacro: MemberMacro {
     let lines = entries.map { "    \($0)" }.joined(separator: ",\n")
     let body = "  return [\n\(lines)\n  ]"
 
+    var emitted: [DeclSyntax] = []
+
+    // `Module`/`BaseModule` already provide `appContext` storage and the
+    // `init(appContext:)` requirement, so we only synthesize them for classes that
+    // inherit from neither. Each is skipped individually if the user wrote their own,
+    // to avoid emitting a duplicate declaration.
+    if !inheritsFromAny(classDecl, names: ["Module", "BaseModule"]) {
+      if !hasStoredProperty(classDecl, named: "appContext") {
+        emitted.append("public weak var appContext: AppContext?")
+      }
+      if !hasAppContextInitializer(classDecl) {
+        emitted.append(
+          """
+          public required init(appContext: AppContext) {
+            self.appContext = appContext
+          }
+          """
+        )
+      }
+    }
+
+    // Always emitted: the definition is derived from the class name and `@JS` members,
+    // independent of any `definition()` the user wrote.
     let method: DeclSyntax = """
-      public func _exposedDefinition() -> [AnyDefinition] {
+      public func _synthesizedDefinition() -> [AnyDefinition] {
       \(raw: body)
       }
       """
+    emitted.append(method)
+
+    return emitted
+  }
+}
+
+extension ExpoModuleMacro: MemberAttributeMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingAttributesFor member: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [AttributeSyntax] {
+    // This macro is invoked once per member and may attach more than one attribute,
+    // so we collect into an array rather than returning early. The two checks below are
+    // independent — a given member matches at most one in practice, but they're written
+    // so neither precludes the other.
+    var attributes: [AttributeSyntax] = []
+
+    // `@JS` sync members run on the JS thread; stamp `@JavaScriptActor` so isolation is
+    // checked at compile time. Skipped when the member already chose an isolation
+    // (`async`, `nonisolated`, or another global actor) — see `shouldStampJavaScriptActor`.
+    if memberHasJSAttribute(member),
+      shouldStampJavaScriptActor(on: member, enclosedBy: declaration) {
+      attributes.append("@JavaScriptActor")
+    }
+
+    // Apply the result builder to `definition()` so the user doesn't have to. Skipped if
+    // they already wrote `@ModuleDefinitionBuilder` themselves, which would otherwise be
+    // a duplicate attribute.
+    if isModuleDefinitionFunction(member),
+      !memberAttributes(of: member).contains(where: { hasAttributeName($0, "ModuleDefinitionBuilder") }) {
+      attributes.append("@ModuleDefinitionBuilder")
+    }
+
+    return attributes
+  }
+}
+
+private func isModuleDefinitionFunction(_ member: some DeclSyntaxProtocol) -> Bool {
+  guard let funcDecl = member.as(FunctionDeclSyntax.self),
+    funcDecl.name.text == "definition",
+    funcDecl.signature.parameterClause.parameters.isEmpty,
+    let returnType = funcDecl.signature.returnClause?.type else {
+    return false
+  }
+  return baseIdentifier(of: returnType) == "ModuleDefinition"
+}
 
-    return [method]
+private func hasAttributeName(_ element: AttributeListSyntax.Element, _ name: String) -> Bool {
+  guard let attribute = element.as(AttributeSyntax.self) else {
+    return false
+  }
+  return attribute.attributeName.trimmedDescription == name
+}
+
+extension ExpoModuleMacro: ExtensionMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingExtensionsOf type: some TypeSyntaxProtocol,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [ExtensionDeclSyntax] {
+    // `protocols` is empty when the compiler already sees the conformance (e.g. it's
+    // spelled in the declaration), in which case there's nothing for us to add.
+    guard !protocols.isEmpty else {
+      return []
+    }
+    // These base types already supply `AnyModule`; emitting a second conformance here
+    // would be redundant and error.
+    if let classDecl = declaration.as(ClassDeclSyntax.self),
+      inheritsFromAny(classDecl, names: ["Module", "BaseModule", "AnyModule"]) {
+      return []
+    }
+    let conformance: DeclSyntax = "extension \(type.trimmed): AnyModule {}"
+    return [conformance.cast(ExtensionDeclSyntax.self)]
+  }
+}
+
+// MARK: - Synthesized-member detection
+
+private func hasStoredProperty(_ classDecl: ClassDeclSyntax, named name: String) -> Bool {
+  for member in classDecl.memberBlock.members {
+    guard let varDecl = member.decl.as(VariableDeclSyntax.self) else {
+      continue
+    }
+    for binding in varDecl.bindings {
+      if let identifier = binding.pattern.as(IdentifierPatternSyntax.self),
+        identifier.identifier.text == name {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/**
+ True if the class declares an initializer that satisfies the `init(appContext:)` protocol
+ requirement: a single parameter labeled `appContext` whose type is written as `AppContext`
+ (or `…​.AppContext`). Both must match — the label is part of the requirement, so
+ `init(c: AppContext)` does *not* satisfy it (we still synthesize ours), and the type guards
+ against a same-labeled init of an unrelated type. A macro can't resolve types, so this is a
+ syntactic match on the spelled name.
+ */
+private func hasAppContextInitializer(_ classDecl: ClassDeclSyntax) -> Bool {
+  for member in classDecl.memberBlock.members {
+    guard let initDecl = member.decl.as(InitializerDeclSyntax.self) else {
+      continue
+    }
+    let params = initDecl.signature.parameterClause.parameters
+    guard params.count == 1, let param = params.first else {
+      continue
+    }
+    if param.firstName.text == "appContext", baseIdentifier(of: param.type) == "AppContext" {
+      return true
+    }
   }
+  return false
 }
 
 // MARK: - Member builders

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -39,6 +39,122 @@ internal func classListArgument(of attribute: AttributeSyntax, label: String) ->
   return []
 }
 
+/**
+ Returns true if the class's inheritance clause names any of the given identifiers.
+ Matches by base identifier only, so `Module`, `ExpoModulesCore.Module`, and
+ `Module<Foo>` all match an entry of "Module".
+ */
+internal func inheritsFromAny(_ classDecl: ClassDeclSyntax, names: Set<String>) -> Bool {
+  guard let inherited = classDecl.inheritanceClause?.inheritedTypes else {
+    return false
+  }
+  for entry in inherited {
+    if let name = baseIdentifier(of: entry.type), names.contains(name) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ Returns the rightmost identifier of a type, e.g. `Foo` for `Foo`, `Foo` for
+ `Module.Foo`, and nil for composed or generic shapes the macro doesn't need to handle.
+ */
+internal func baseIdentifier(of type: TypeSyntax) -> String? {
+  if let identifier = type.as(IdentifierTypeSyntax.self) {
+    return identifier.name.text
+  }
+  if let member = type.as(MemberTypeSyntax.self) {
+    return member.name.text
+  }
+  return nil
+}
+
+/**
+ True if the declaration carries a `@JS` attribute. Works for functions, properties, and inits;
+ returns false for any other decl kind.
+ */
+internal func memberHasJSAttribute(_ decl: DeclSyntaxProtocol) -> Bool {
+  if let funcDecl = decl.as(FunctionDeclSyntax.self) {
+    return funcDecl.attributes.firstAttribute(named: "JS") != nil
+  }
+  if let varDecl = decl.as(VariableDeclSyntax.self) {
+    return varDecl.attributes.firstAttribute(named: "JS") != nil
+  }
+  if let initDecl = decl.as(InitializerDeclSyntax.self) {
+    return initDecl.attributes.firstAttribute(named: "JS") != nil
+  }
+  return false
+}
+
+/**
+ Decides whether the macro should stamp `@JavaScriptActor` on a `@JS`-marked member.
+ The macro defers to the user when they've already chosen an isolation:
+ - the `nonisolated` modifier is present on the member
+ - any attribute whose name matches a known global actor (`@MainActor`, `@JavaScriptActor`)
+   or follows the `*Actor` naming convention is present on the member or its enclosing type
+ Async members never get the stamp because `AsyncFunction` controls their dispatch separately.
+ */
+internal func shouldStampJavaScriptActor(
+  on member: DeclSyntaxProtocol,
+  enclosedBy enclosing: some DeclGroupSyntax
+) -> Bool {
+  let modifiers = memberModifiers(of: member)
+  if modifiers.contains(where: { $0.name.text == "nonisolated" }) {
+    return false
+  }
+
+  if let funcDecl = member.as(FunctionDeclSyntax.self),
+    funcDecl.signature.effectSpecifiers?.asyncSpecifier != nil {
+    return false
+  }
+
+  let memberAttributes = memberAttributes(of: member)
+  if memberAttributes.contains(where: hasGlobalActorShape) {
+    return false
+  }
+
+  if enclosing.attributes.contains(where: hasGlobalActorShape) {
+    return false
+  }
+
+  return true
+}
+
+private func memberModifiers(of decl: DeclSyntaxProtocol) -> DeclModifierListSyntax {
+  if let funcDecl = decl.as(FunctionDeclSyntax.self) {
+    return funcDecl.modifiers
+  }
+  if let varDecl = decl.as(VariableDeclSyntax.self) {
+    return varDecl.modifiers
+  }
+  if let initDecl = decl.as(InitializerDeclSyntax.self) {
+    return initDecl.modifiers
+  }
+  return DeclModifierListSyntax()
+}
+
+internal func memberAttributes(of decl: DeclSyntaxProtocol) -> AttributeListSyntax {
+  if let funcDecl = decl.as(FunctionDeclSyntax.self) {
+    return funcDecl.attributes
+  }
+  if let varDecl = decl.as(VariableDeclSyntax.self) {
+    return varDecl.attributes
+  }
+  if let initDecl = decl.as(InitializerDeclSyntax.self) {
+    return initDecl.attributes
+  }
+  return AttributeListSyntax()
+}
+
+private func hasGlobalActorShape(_ element: AttributeListSyntax.Element) -> Bool {
+  guard let attribute = element.as(AttributeSyntax.self) else {
+    return false
+  }
+  let name = attribute.attributeName.trimmedDescription
+  return name.hasSuffix("Actor")
+}
+
 extension AttributeListSyntax {
   internal func firstAttribute(named name: String) -> AttributeSyntax? {
     for element in self {