add JS-snippet support using from: .module("/path/to/js-module.js") syntax (#792)

Author: sliemeobn

Package.swift

@@ -198,6 +198,7 @@ let package = Package(
                 "bridge-js.global.d.ts",
                 "Generated/JavaScript",
                 "JavaScript",
+                "Modules",
             ],
             swiftSettings: [
                 .enableExperimentalFeature("Extern")

Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift

@@ -23,6 +23,8 @@ public final class SwiftToSkeleton {
 
     private var sourceFiles: [(sourceFile: SourceFileSyntax, inputFilePath: String)] = []
     private var usedExternalModules = Set<String>()
+    private let javaScriptModuleExists: (String) throws -> Bool
+    private var validatedJavaScriptModulePaths = Set<String>()
 
     /// Non-fatal diagnostics collected during `finalize()`. These do not fail the build.
     public private(set) var warnings: [(file: String, diagnostic: DiagnosticError)] = []
@@ -32,12 +34,14 @@ public final class SwiftToSkeleton {
         moduleName: String,
         exposeToGlobal: Bool,
         externalModuleIndex: ExternalModuleIndex,
-        identityMode: String? = nil
+        identityMode: String? = nil,
+        javaScriptModuleExists: @escaping (String) throws -> Bool = { _ in false }
     ) {
         self.progress = progress
         self.moduleName = moduleName
         self.exposeToGlobal = exposeToGlobal
         self.identityMode = identityMode
+        self.javaScriptModuleExists = javaScriptModuleExists
         self.typeDeclResolver = TypeDeclResolver()
         self.externalModuleIndex = externalModuleIndex
 
@@ -90,6 +94,57 @@ public final class SwiftToSkeleton {
             )
             importCollector.walk(sourceFile)
 
+            let importOrigins =
+                importCollector.importedFunctions.compactMap(\.from)
+                + importCollector.importedTypes.compactMap(\.from)
+                + importCollector.importedGlobalGetters.compactMap(\.from)
+            let modulePaths = Set(importOrigins.compactMap(\.modulePath))
+            for path in modulePaths.sorted() {
+                if validatedJavaScriptModulePaths.contains(path) {
+                    continue
+                }
+                let pathNode = importCollector.importedModulePathNodes[path] ?? Syntax(sourceFile)
+                guard path.hasPrefix("/") else {
+                    importCollector.errors.append(
+                        DiagnosticError(
+                            node: pathNode,
+                            message: "JavaScript module paths must start with '/' to indicate the Swift target root: "
+                                + "'\(path)'."
+                        )
+                    )
+                    continue
+                }
+                guard !path.split(separator: "/").contains("..") else {
+                    importCollector.errors.append(
+                        DiagnosticError(
+                            node: pathNode,
+                            message: "JavaScript module paths must not contain '..': '\(path)'."
+                        )
+                    )
+                    continue
+                }
+                let lowercasedPath = path.lowercased()
+                guard lowercasedPath.hasSuffix(".js") || lowercasedPath.hasSuffix(".mjs") else {
+                    importCollector.errors.append(
+                        DiagnosticError(
+                            node: pathNode,
+                            message: "JavaScript modules must use a '.js' or '.mjs' extension: '\(path)'."
+                        )
+                    )
+                    continue
+                }
+                guard try javaScriptModuleExists(path) else {
+                    importCollector.errors.append(
+                        DiagnosticError(
+                            node: pathNode,
+                            message: "JavaScript module file was not found at '\(path)'."
+                        )
+                    )
+                    continue
+                }
+                validatedJavaScriptModulePaths.insert(path)
+            }
+
             let exportErrors = exportCollector.errors.filter { $0.severity == .error }
             let importErrorsFatal = importCollector.errors.filter {
                 $0.severity == .error && !$0.message.contains("Unsupported type '")
@@ -2413,6 +2468,7 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
     var importedFunctions: [ImportedFunctionSkeleton] = []
     var importedTypes: [ImportedTypeSkeleton] = []
     var importedGlobalGetters: [ImportedGetterSkeleton] = []
+    var importedModulePathNodes: [String: Syntax] = [:]
     var errors: [DiagnosticError] = []
 
     private let inputFilePath: String
@@ -2507,22 +2563,41 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
             }
             return nil
         }
+    }
+
+    private func extractJSImportFrom(from attribute: AttributeSyntax) -> JSImportFrom? {
+        guard let arguments = attribute.arguments?.as(LabeledExprListSyntax.self),
+            let argument = arguments.first(where: { $0.label?.text == "from" })
+        else {
+            return nil
+        }
 
-        /// Extracts the `from` argument value from an attribute, if present.
-        static func extractJSImportFrom(from attribute: AttributeSyntax) -> JSImportFrom? {
-            guard let arguments = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+        if let call = argument.expression.as(FunctionCallExprSyntax.self),
+            call.calledExpression.trimmedDescription.split(separator: ".").last == "module"
+        {
+            guard call.arguments.count == 1,
+                let pathExpression = call.arguments.first?.expression,
+                let literal = pathExpression.as(StringLiteralExprSyntax.self),
+                let path = literal.representedLiteralValue
+            else {
+                errors.append(
+                    DiagnosticError(
+                        node: call.arguments.first?.expression ?? argument.expression,
+                        message: "JavaScript module path must be a string literal."
+                    )
+                )
                 return nil
             }
-            for argument in arguments {
-                guard argument.label?.text == "from" else { continue }
-
-                // Accept `.global`, `JSImportFrom.global`, etc.
-                let description = argument.expression.trimmedDescription
-                let caseName = description.split(separator: ".").last.map(String.init) ?? description
-                return JSImportFrom(rawValue: caseName)
+            if importedModulePathNodes[path] == nil {
+                importedModulePathNodes[path] = Syntax(literal)
             }
-            return nil
+            return .module(path)
         }
+
+        // Accept `.global`, `JSImportFrom.global`, etc.
+        let description = argument.expression.trimmedDescription
+        let caseName = description.split(separator: ".").last.map(String.init) ?? description
+        return caseName == "global" ? .global : nil
     }
 
     // MARK: - Validation Helpers
@@ -2705,7 +2780,7 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
         if AttributeChecker.hasJSClassAttribute(node.attributes) {
             let attribute = AttributeChecker.firstJSClassAttribute(node.attributes)
             let jsName = attribute.flatMap(AttributeChecker.extractJSName)
-            let from = attribute.flatMap(AttributeChecker.extractJSImportFrom)
+            let from = attribute.flatMap { extractJSImportFrom(from: $0) }
             let accessLevel = Self.bridgeAccessLevel(from: node.modifiers)
             enterJSClass(node.name.text, jsName: jsName, from: from, accessLevel: accessLevel)
         }
@@ -2722,7 +2797,7 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
         if AttributeChecker.hasJSClassAttribute(node.attributes) {
             let attribute = AttributeChecker.firstJSClassAttribute(node.attributes)
             let jsName = attribute.flatMap(AttributeChecker.extractJSName)
-            let from = attribute.flatMap(AttributeChecker.extractJSImportFrom)
+            let from = attribute.flatMap { extractJSImportFrom(from: $0) }
             let accessLevel = Self.bridgeAccessLevel(from: node.modifiers)
             enterJSClass(node.name.text, jsName: jsName, from: from, accessLevel: accessLevel)
         }
@@ -2916,7 +2991,7 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
 
         let baseName = SwiftToSkeleton.normalizeIdentifier(node.name.text)
         let jsName = AttributeChecker.extractJSName(from: jsFunction)
-        let from = AttributeChecker.extractJSImportFrom(from: jsFunction)
+        let from = extractJSImportFrom(from: jsFunction)
         let name = baseName
 
         let parameters = parseParameters(from: node.signature.parameterClause)
@@ -2969,7 +3044,7 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
         }
         let propertyName = SwiftToSkeleton.normalizeIdentifier(identifier.identifier.text)
         let jsName = AttributeChecker.extractJSName(from: jsGetter)
-        let from = AttributeChecker.extractJSImportFrom(from: jsGetter)
+        let from = extractJSImportFrom(from: jsGetter)
         let accessLevel = Self.bridgeAccessLevel(from: node.modifiers)
         return ImportedGetterSkeleton(
             name: propertyName,

Plugins/BridgeJS/Sources/BridgeJSLink/BridgeJSLink.swift

@@ -16,6 +16,7 @@ public struct BridgeJSLink {
     let enableLifetimeTracking: Bool = false
     private let namespaceBuilder = NamespaceBuilder()
     private let intrinsicRegistry = JSIntrinsicRegistry()
+    private let importedModuleRegistry = ImportedJSModuleRegistry()
 
     public init(
         skeletons: [BridgeJSSkeleton] = [],
@@ -40,10 +41,12 @@ public struct BridgeJSLink {
         return configIdentityMode == "pointer"
     }
 
-    mutating func addSkeletonFile(data: Data) throws {
+    @discardableResult
+    mutating func addSkeletonFile(data: Data) throws -> BridgeJSSkeleton {
         do {
             let unified = try JSONDecoder().decode(BridgeJSSkeleton.self, from: data)
             skeletons.append(unified)
+            return unified
         } catch {
             struct SkeletonDecodingError: Error, CustomStringConvertible {
                 let description: String
@@ -1077,6 +1080,11 @@ public struct BridgeJSLink {
         let printer = CodeFragmentPrinter(header: header)
         printer.nextLine()
 
+        printer.write(lines: importedModuleRegistry.importLines)
+        if !importedModuleRegistry.importLines.isEmpty {
+            printer.nextLine()
+        }
+
         printer.write(lines: data.topLevelTypeLines)
 
         let exportedSkeletons = skeletons.compactMap(\.exported)
@@ -1222,6 +1230,7 @@ public struct BridgeJSLink {
 
     public func link() throws -> (outputJs: String, outputDts: String) {
         intrinsicRegistry.reset()
+        importedModuleRegistry.configure(skeletons: skeletons)
         intrinsicRegistry.classNamespaces = skeletons.reduce(into: [:]) { result, unified in
             guard let skeleton = unified.exported else { return }
             for klass in skeleton.classes {
@@ -1586,7 +1595,7 @@ public struct BridgeJSLink {
         return "\"\(Self.escapeForJavaScriptStringLiteral(name))\""
     }
 
-    fileprivate static func escapeForJavaScriptStringLiteral(_ string: String) -> String {
+    static func escapeForJavaScriptStringLiteral(_ string: String) -> String {
         string
             .replacingOccurrences(of: "\\", with: "\\\\")
             .replacingOccurrences(of: "\"", with: "\\\"")
@@ -3460,7 +3469,10 @@ extension BridgeJSLink {
             try thunkBuilder.liftParameter(param: param)
         }
         let jsName = function.jsName ?? function.name
-        let importRootExpr = function.from == .global ? "globalThis" : "imports"
+        let importRootExpr = try importedModuleRegistry.namespaceExpression(
+            swiftModuleName: importObjectBuilder.moduleName,
+            from: function.from
+        )
 
         try thunkBuilder.call(name: jsName, fromObjectExpr: importRootExpr)
         let funcLines = thunkBuilder.renderFunction(name: function.abiName(context: nil))
@@ -3484,7 +3496,10 @@ extension BridgeJSLink {
             intrinsicRegistry: intrinsicRegistry
         )
         let jsName = getter.jsName ?? getter.name
-        let importRootExpr = getter.from == .global ? "globalThis" : "imports"
+        let importRootExpr = try importedModuleRegistry.namespaceExpression(
+            swiftModuleName: importObjectBuilder.moduleName,
+            from: getter.from
+        )
         try thunkBuilder.getImportProperty(
             name: jsName,
             fromObjectExpr: importRootExpr,
@@ -3539,7 +3554,11 @@ extension BridgeJSLink {
         }
         for method in type.staticMethods {
             let abiName = method.abiName(context: type, operation: "static")
-            let (js, dts) = try renderImportedStaticMethod(context: type, method: method)
+            let (js, dts) = try renderImportedStaticMethod(
+                swiftModuleName: importObjectBuilder.moduleName,
+                context: type,
+                method: method
+            )
             importObjectBuilder.assignToImportObject(name: abiName, function: js)
             importObjectBuilder.appendDts(dts)
         }
@@ -3583,7 +3602,10 @@ extension BridgeJSLink {
         for param in constructor.parameters {
             try thunkBuilder.liftParameter(param: param)
         }
-        let importRootExpr = type.from == .global ? "globalThis" : "imports"
+        let importRootExpr = try importedModuleRegistry.namespaceExpression(
+            swiftModuleName: importObjectBuilder.moduleName,
+            from: type.from
+        )
         try thunkBuilder.callConstructor(
             jsName: type.jsName ?? type.name,
             swiftTypeName: type.name,
@@ -3627,6 +3649,7 @@ extension BridgeJSLink {
     }
 
     func renderImportedStaticMethod(
+        swiftModuleName: String,
         context: ImportedTypeSkeleton,
         method: ImportedFunctionSkeleton
     ) throws -> (js: [String], dts: [String]) {
@@ -3638,7 +3661,10 @@ extension BridgeJSLink {
         for param in method.parameters {
             try thunkBuilder.liftParameter(param: param)
         }
-        let importRootExpr = context.from == .global ? "globalThis" : "imports"
+        let importRootExpr = try importedModuleRegistry.namespaceExpression(
+            swiftModuleName: swiftModuleName,
+            from: context.from
+        )
         let constructorExpr = ImportedThunkBuilder.propertyAccessExpr(
             objectExpr: importRootExpr,
             propertyName: context.jsName ?? context.name

Plugins/BridgeJS/Sources/BridgeJSLink/ImportedJSModuleRegistry.swift

@@ -0,0 +1,67 @@
+#if canImport(BridgeJSSkeleton)
+import BridgeJSSkeleton
+#endif
+
+final class ImportedJSModuleRegistry {
+    struct Reference: Hashable {
+        let swiftModuleName: String
+        let path: String
+
+        var relativeOutputPath: String {
+            "bridge-js-modules/\(swiftModuleName)\(path)"
+        }
+    }
+
+    private var aliases: [Reference: String] = [:]
+    private(set) var references: [Reference] = []
+
+    func configure(skeletons: [BridgeJSSkeleton]) {
+        aliases.removeAll(keepingCapacity: true)
+        references = Self.collectReferences(skeletons: skeletons)
+        for (index, reference) in references.enumerated() {
+            aliases[reference] = "__bjs_imported_module_\(index)"
+        }
+    }
+
+    static func collectReferences(skeletons: [BridgeJSSkeleton]) -> [Reference] {
+        var references = Set<Reference>()
+        for skeleton in skeletons {
+            for file in skeleton.imported?.children ?? [] {
+                let origins =
+                    file.functions.compactMap(\.from)
+                    + file.globalGetters.compactMap(\.from)
+                    + file.types.compactMap(\.from)
+                for case .module(let path) in origins {
+                    references.insert(Reference(swiftModuleName: skeleton.moduleName, path: path))
+                }
+            }
+        }
+        return references.sorted {
+            ($0.swiftModuleName, $0.path) < ($1.swiftModuleName, $1.path)
+        }
+    }
+
+    func namespaceExpression(swiftModuleName: String, from: JSImportFrom?) throws -> String {
+        switch from {
+        case nil:
+            return "imports"
+        case .global:
+            return "globalThis"
+        case .module(let path):
+            let reference = Reference(swiftModuleName: swiftModuleName, path: path)
+            guard let alias = aliases[reference] else {
+                throw BridgeJSLinkError(
+                    message: "Missing JavaScript module \(swiftModuleName)\(path)"
+                )
+            }
+            return alias
+        }
+    }
+
+    var importLines: [String] {
+        references.enumerated().map { index, reference in
+            let path = BridgeJSLink.escapeForJavaScriptStringLiteral(reference.relativeOutputPath)
+            return "import * as __bjs_imported_module_\(index) from \"./\(path)\";"
+        }
+    }
+}