BridgeJS: Global namespace configuration and tests

Author: krodak

Examples/PlayBridgeJS/Sources/PlayBridgeJS/main.swift

@@ -17,7 +17,7 @@ import class Foundation.JSONDecoder
     }
 
     func _update(swiftSource: String, dtsSource: String) throws -> PlayBridgeJSOutput {
-        let exportSwift = ExportSwift(progress: .silent, moduleName: "Playground")
+        let exportSwift = ExportSwift(progress: .silent, moduleName: "Playground", exposeToGlobal: false)
         let sourceFile = Parser.parse(source: swiftSource)
         try exportSwift.addSourceFile(sourceFile, "Playground.swift")
         let exportResult = try exportSwift.finalize()
@@ -40,8 +40,7 @@ import class Foundation.JSONDecoder
                     children: [importSkeleton]
                 )
             ],
-            sharedMemory: false,
-            exposeToGlobal: true
+            sharedMemory: false
         )
         let linked = try linker.link()
 

Makefile

@@ -11,6 +11,16 @@ unittest:
 	    --disable-sandbox \
 	    js test --prelude ./Tests/prelude.mjs -Xnode --expose-gc
 
+.PHONY: unittest-with-global
+unittest-with-global:
+	cp Tests/BridgeJSRuntimeTests/bridge-js.config.exposeToGlobal.json Tests/BridgeJSRuntimeTests/bridge-js.config.local.json
+	swift package --allow-writing-to-directory Tests/BridgeJSRuntimeTests \
+	    bridge-js --package-path Tests/BridgeJSRuntimeTests
+	rm -f Tests/BridgeJSRuntimeTests/bridge-js.config.local.json
+	env JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS=1 swift package --swift-sdk "$(SWIFT_SDK_ID)" \
+	    --disable-sandbox \
+	    js test --prelude ./Tests/prelude.exposeToGlobal.mjs -Xnode --expose-gc
+
 .PHONY: regenerate_swiftpm_resources
 regenerate_swiftpm_resources:
 	npm run build

Plugins/BridgeJS/Sources/BridgeJSBuildPlugin/BridgeJSBuildPlugin.swift

@@ -44,6 +44,8 @@ struct BridgeJSBuildPlugin: BuildToolPlugin {
                 "export",
                 "--module-name",
                 target.name,
+                "--target-dir",
+                target.directoryURL.path,
                 "--output-skeleton",
                 outputSkeletonPath.path,
                 "--output-swift",

Plugins/BridgeJS/Sources/BridgeJSCommandPlugin/BridgeJSCommandPlugin.swift

@@ -107,6 +107,8 @@ extension BridgeJSCommandPlugin.Context {
                 "export",
                 "--module-name",
                 target.name,
+                "--target-dir",
+                target.directoryURL.path,
                 "--output-skeleton",
                 generatedJavaScriptDirectory.appending(path: "BridgeJS.ExportSwift.json").path,
                 "--output-swift",

Plugins/BridgeJS/Sources/BridgeJSCore/BridgeJSConfig.swift

@@ -10,6 +10,15 @@ public struct BridgeJSConfig: Codable {
     /// If not present, the tool will be searched for in the system PATH.
     public var tools: [String: String]?
 
+    /// Whether to expose exported Swift APIs to the global namespace.
+    ///
+    /// When `true`, exported functions, classes, and namespaces are available
+    /// via `globalThis` in JavaScript. When `false`, they are only available
+    /// through the exports object returned by `createExports()`.
+    ///
+    /// Default: `false`
+    public var exposeToGlobal: Bool = false
+
     /// Load the configuration file from the SwiftPM package target directory.
     ///
     /// Files are loaded **in this order** and merged (later files override earlier ones):
@@ -49,7 +58,8 @@ public struct BridgeJSConfig: Codable {
     /// Merge the current configuration with the overrides.
     func merging(overrides: BridgeJSConfig) -> BridgeJSConfig {
         return BridgeJSConfig(
-            tools: (tools ?? [:]).merging(overrides.tools ?? [:], uniquingKeysWith: { $1 })
+            tools: (tools ?? [:]).merging(overrides.tools ?? [:], uniquingKeysWith: { $1 }),
+            exposeToGlobal: overrides.exposeToGlobal
         )
     }
 }

Plugins/BridgeJS/Sources/BridgeJSCore/ExportSwift.swift

@@ -20,7 +20,7 @@ import BridgeJSUtilities
 public class ExportSwift {
     let progress: ProgressReporting
     let moduleName: String
-
+    private let exposeToGlobal: Bool
     private var exportedFunctions: [ExportedFunction] = []
     private var exportedClasses: [ExportedClass] = []
     private var exportedEnums: [ExportedEnum] = []
@@ -30,9 +30,10 @@ public class ExportSwift {
     private let enumCodegen: EnumCodegen = EnumCodegen()
     private let closureCodegen = ClosureCodegen()
 
-    public init(progress: ProgressReporting, moduleName: String) {
+    public init(progress: ProgressReporting, moduleName: String, exposeToGlobal: Bool) {
         self.progress = progress
         self.moduleName = moduleName
+        self.exposeToGlobal = exposeToGlobal
     }
 
     /// Processes a Swift source file to find declarations marked with @JS
@@ -55,6 +56,8 @@ public class ExportSwift {
 
     /// Finalizes the export process and generates the bridge code
     ///
+    /// - Parameters:
+    ///   - exposeToGlobal: Whether to expose exported APIs to the global namespace (default: false)
     /// - Returns: A tuple containing the generated Swift code and a skeleton
     /// describing the exported APIs
     public func finalize() throws -> (outputSwift: String, outputSkeleton: ExportedSkeleton)? {
@@ -68,7 +71,8 @@ public class ExportSwift {
                 functions: exportedFunctions,
                 classes: exportedClasses,
                 enums: exportedEnums,
-                protocols: exportedProtocols
+                protocols: exportedProtocols,
+                exposeToGlobal: exposeToGlobal
             )
         )
     }

Plugins/BridgeJS/Sources/BridgeJSLink/BridgeJSLink.swift

@@ -12,24 +12,26 @@ struct BridgeJSLink {
     var exportedSkeletons: [ExportedSkeleton] = []
     var importedSkeletons: [ImportedModuleSkeleton] = []
     let sharedMemory: Bool
-    let exposeToGlobal: Bool
+    var exposeToGlobal: Bool
     private let namespaceBuilder = NamespaceBuilder()
 
     init(
         exportedSkeletons: [ExportedSkeleton] = [],
         importedSkeletons: [ImportedModuleSkeleton] = [],
-        sharedMemory: Bool,
-        exposeToGlobal: Bool = true
+        sharedMemory: Bool
     ) {
         self.exportedSkeletons = exportedSkeletons
         self.importedSkeletons = importedSkeletons
         self.sharedMemory = sharedMemory
-        self.exposeToGlobal = exposeToGlobal
+        self.exposeToGlobal = exportedSkeletons.contains { $0.exposeToGlobal }
     }
 
     mutating func addExportedSkeletonFile(data: Data) throws {
         let skeleton = try JSONDecoder().decode(ExportedSkeleton.self, from: data)
         exportedSkeletons.append(skeleton)
+        if skeleton.exposeToGlobal {
+            exposeToGlobal = true
+        }
     }
 
     mutating func addImportedSkeletonFile(data: Data) throws {
@@ -80,7 +82,7 @@ struct BridgeJSLink {
         var enumStaticAssignments: [String] = []
     }
 
-    private func collectLinkData(exposeToGlobal: Bool) throws -> LinkData {
+    private func collectLinkData() throws -> LinkData {
         var data = LinkData()
 
         // Swift heap object class definitions
@@ -1079,11 +1081,11 @@ struct BridgeJSLink {
                 )
                 printer.write(lines: namespaceInitCode)
 
-                    let propertyAssignments = try generateNamespacePropertyAssignments(
-                        data: data,
-                        exportedSkeletons: exportedSkeletons,
-                        namespaceBuilder: namespaceBuilder,
-                        exposeToGlobal: exposeToGlobal
+                let propertyAssignments = try generateNamespacePropertyAssignments(
+                    data: data,
+                    exportedSkeletons: exportedSkeletons,
+                    namespaceBuilder: namespaceBuilder,
+                    exposeToGlobal: exposeToGlobal
                 )
                 printer.write(lines: propertyAssignments)
             }
@@ -1097,7 +1099,7 @@ struct BridgeJSLink {
     }
 
     func link() throws -> (outputJs: String, outputDts: String) {
-        let data = try collectLinkData(exposeToGlobal: exposeToGlobal)
+        let data = try collectLinkData()
         let outputJs = try generateJavaScript(data: data)
         let outputDts = generateTypeScript(data: data)
         return (outputJs, outputDts)
@@ -1160,7 +1162,6 @@ struct BridgeJSLink {
     ) throws -> [String] {
         let printer = CodeFragmentPrinter()
 
-        // Only write globalThis property assignments when exposeToGlobal is true
         if exposeToGlobal {
             printer.write(lines: data.enumStaticAssignments)
         }
@@ -1171,7 +1172,6 @@ struct BridgeJSLink {
 
             let hierarchicalLines = try namespaceBuilder.buildHierarchicalExportsObject(
                 exportedSkeletons: exportedSkeletons,
-                exposeToGlobal: exposeToGlobal,
                 renderFunctionImpl: { function in
                     let (js, _) = try self.renderExportedFunction(function: function)
                     return js
@@ -2478,7 +2478,6 @@ extension BridgeJSLink {
 
         fileprivate func buildHierarchicalExportsObject(
             exportedSkeletons: [ExportedSkeleton],
-            exposeToGlobal: Bool,
             renderFunctionImpl: (ExportedFunction) throws -> [String]
         ) throws -> [String] {
             let printer = CodeFragmentPrinter()
@@ -2698,7 +2697,7 @@ extension BridgeJSLink {
                     guard hasContent(node: childNode) else {
                         continue
                     }
-                    
+
                     let exportKeyword = exposeToGlobal ? "" : "export "
                     printer.write("\(exportKeyword)namespace \(childName) {")
                     printer.indent()

Plugins/BridgeJS/Sources/BridgeJSSkeleton/BridgeJSSkeleton.swift

@@ -499,19 +499,27 @@ public struct ExportedSkeleton: Codable {
     public let classes: [ExportedClass]
     public let enums: [ExportedEnum]
     public let protocols: [ExportedProtocol]
+    /// Whether to expose exported APIs to the global namespace.
+    ///
+    /// When `true`, exported functions, classes, and namespaces are available
+    /// via `globalThis` in JavaScript. When `false`, they are only available
+    /// through the exports object.
+    public var exposeToGlobal: Bool
 
     public init(
         moduleName: String,
         functions: [ExportedFunction],
         classes: [ExportedClass],
         enums: [ExportedEnum],
-        protocols: [ExportedProtocol] = []
+        protocols: [ExportedProtocol] = [],
+        exposeToGlobal: Bool
     ) {
         self.moduleName = moduleName
         self.functions = functions
         self.classes = classes
         self.enums = enums
         self.protocols = protocols
+        self.exposeToGlobal = exposeToGlobal
     }
 }
 

Plugins/BridgeJS/Sources/BridgeJSTool/BridgeJSTool.swift

@@ -162,6 +162,10 @@ import TS2Skeleton
                         help: "The name of the module for external function references",
                         required: true
                     ),
+                    "target-dir": OptionRule(
+                        help: "The SwiftPM package target directory",
+                        required: true
+                    ),
                     "output-skeleton": OptionRule(
                         help: "The output file path for the skeleton of the exported Swift APIs",
                         required: true
@@ -181,7 +185,13 @@ import TS2Skeleton
                 arguments: Array(arguments.dropFirst())
             )
             let progress = ProgressReporting(verbose: doubleDashOptions["verbose"] == "true")
-            let exporter = ExportSwift(progress: progress, moduleName: doubleDashOptions["module-name"]!)
+            let targetDirectory = URL(fileURLWithPath: doubleDashOptions["target-dir"]!)
+            let config = try BridgeJSConfig.load(targetDirectory: targetDirectory)
+            let exporter = ExportSwift(
+                progress: progress,
+                moduleName: doubleDashOptions["module-name"]!,
+                exposeToGlobal: config.exposeToGlobal
+            )
             for inputFile in positionalArguments.sorted() {
                 let sourceURL = URL(fileURLWithPath: inputFile)
                 guard sourceURL.pathExtension == "swift" else { continue }

Plugins/BridgeJS/Tests/BridgeJSToolTests/BridgeJSLinkTests.swift

@@ -47,16 +47,12 @@ import Testing
     func snapshotExport(input: String) throws {
         let url = Self.inputsDirectory.appendingPathComponent(input)
         let sourceFile = Parser.parse(source: try String(contentsOf: url, encoding: .utf8))
-        let swiftAPI = ExportSwift(progress: .silent, moduleName: "TestModule")
+        let swiftAPI = ExportSwift(progress: .silent, moduleName: "TestModule", exposeToGlobal: false)
         try swiftAPI.addSourceFile(sourceFile, input)
         let name = url.deletingPathExtension().lastPathComponent
 
         let (_, outputSkeleton) = try #require(try swiftAPI.finalize())
-        let encoder = JSONEncoder()
-        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-        let outputSkeletonData = try encoder.encode(outputSkeleton)
-        var bridgeJSLink = BridgeJSLink(sharedMemory: false, exposeToGlobal: true)
-        try bridgeJSLink.addExportedSkeletonFile(data: outputSkeletonData)
+        let bridgeJSLink: BridgeJSLink = BridgeJSLink(exportedSkeletons: [outputSkeleton], sharedMemory: false)
         try snapshot(bridgeJSLink: bridgeJSLink, name: name + ".Export")
     }
 
@@ -74,7 +70,7 @@ import Testing
         encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
         let outputSkeletonData = try encoder.encode(importTS.skeleton)
 
-        var bridgeJSLink = BridgeJSLink(sharedMemory: false, exposeToGlobal: true)
+        var bridgeJSLink = BridgeJSLink(sharedMemory: false)
         try bridgeJSLink.addImportedSkeletonFile(data: outputSkeletonData)
         try snapshot(bridgeJSLink: bridgeJSLink, name: name + ".Import")
     }
@@ -83,45 +79,16 @@ import Testing
         "Namespaces.swift",
         "StaticFunctions.swift",
         "StaticProperties.swift",
-        "EnumNamespace.swift"
+        "EnumNamespace.swift",
     ])
-    func testWithoutGlobal(inputFile: String) throws {
+    func snapshotExportWithGlobal(inputFile: String) throws {
         let url = Self.inputsDirectory.appendingPathComponent(inputFile)
         let sourceFile = Parser.parse(source: try String(contentsOf: url, encoding: .utf8))
-        let swiftAPI = ExportSwift(progress: .silent, moduleName: "TestModule")
+        let swiftAPI = ExportSwift(progress: .silent, moduleName: "TestModule", exposeToGlobal: true)
         try swiftAPI.addSourceFile(sourceFile, inputFile)
-
+        let name = url.deletingPathExtension().lastPathComponent
         let (_, outputSkeleton) = try #require(try swiftAPI.finalize())
-        let encoder = JSONEncoder()
-        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-        let outputSkeletonData = try encoder.encode(outputSkeleton)
-
-        var bridgeJSLink = BridgeJSLink(sharedMemory: false, exposeToGlobal: false)
-        try bridgeJSLink.addExportedSkeletonFile(data: outputSkeletonData)
-
-        let (outputJs, outputDts) = try bridgeJSLink.link()
-
-        // Verify no global declarations
-        #expect(!outputDts.contains("declare global"))
-        #expect(!outputJs.contains("globalThis."))
-
-        // Save snapshots
-        let name = url.deletingPathExtension().lastPathComponent + "_NoGlobal.Export"
-        try assertSnapshot(
-            name: name,
-            filePath: #filePath,
-            function: #function,
-            sourceLocation: #_sourceLocation,
-            input: outputJs.data(using: .utf8)!,
-            fileExtension: "js"
-        )
-        try assertSnapshot(
-            name: name,
-            filePath: #filePath,
-            function: #function,
-            sourceLocation: #_sourceLocation,
-            input: outputDts.data(using: .utf8)!,
-            fileExtension: "d.ts"
-        )
+        let bridgeJSLink: BridgeJSLink = BridgeJSLink(exportedSkeletons: [outputSkeleton], sharedMemory: false)
+        try snapshot(bridgeJSLink: bridgeJSLink, name: name + ".Global.Export")
     }
 }