BridgeJS: Support @js protocol constraints on generic imports

An imported generic @JSFunction can now compose one or more @js
protocols with the bridgeable bound, in any order:

    @JSFunction func fetchNode<T: BridgedSwiftGenericBridgeable & GraphNode>(_ key: String) throws(JSException) -> T

The Swift compiler enforces the constraint at every call site, so no
runtime check is needed on imports; values still cross as the concrete
type. The skeleton's generic parameters grow from bare name strings to
{name, constraints} records (with tolerant decoding of the old string
shape, since dependency targets check in generated skeletons), and the
generated d.ts carries the constraint as 'T extends GraphNode',
referencing the protocol's generated interface.

Every protocol in the composition must be a @js protocol declared in the
module or in an indexed dependency; anything else — a missing bridgeable
bound, an unknown or non-@js protocol — is rejected with a diagnostic
that spells out the expected composition.

Author: krodak

Plugins/BridgeJS/Sources/BridgeJSCore/ImportTS.swift

@@ -381,7 +381,7 @@ public struct ImportTS {
             parameters: [Parameter],
             returnType: BridgeType,
             effects: Effects,
-            genericParameters: [String] = []
+            genericParameters: [GenericParameter] = []
         ) -> DeclSyntax {
             let printer = CodeFragmentPrinter()
             let signature = SwiftSignatureBuilder.buildFunctionSignature(
@@ -393,7 +393,11 @@ public struct ImportTS {
             let genericClause =
                 genericParameters.isEmpty
                 ? ""
-                : "<" + genericParameters.map { "\($0): BridgedSwiftGenericBridgeable" }.joined(separator: ", ")
+                : "<"
+                    + genericParameters.map { genericParameter in
+                        let constraints = ["BridgedSwiftGenericBridgeable"] + genericParameter.constraints
+                        return "\(genericParameter.name): \(constraints.joined(separator: " & "))"
+                    }.joined(separator: ", ")
                     + ">"
             printer.write("func \(name.backtickIfNeeded())\(genericClause)\(signature) {")
             printer.indent {
@@ -465,7 +469,7 @@ public struct ImportTS {
                 parameters: function.parameters,
                 returnType: function.returnType,
                 effects: function.effects,
-                genericParameters: function.genericParameterNames
+                genericParameters: function.genericParameters ?? []
             )
             .with(\.leadingTrivia, Self.renderDocumentation(documentation: function.documentation))
         ]
@@ -496,7 +500,7 @@ public struct ImportTS {
                     parameters: [selfParameter] + method.parameters,
                     returnType: method.returnType,
                     effects: method.effects,
-                    genericParameters: method.genericParameterNames
+                    genericParameters: method.genericParameters ?? []
                 )
             ]
         }
@@ -522,7 +526,7 @@ public struct ImportTS {
                     parameters: method.parameters,
                     returnType: method.returnType,
                     effects: method.effects,
-                    genericParameters: method.genericParameterNames
+                    genericParameters: method.genericParameters ?? []
                 )
             ]
         }
@@ -548,7 +552,7 @@ public struct ImportTS {
                     parameters: constructor.parameters,
                     returnType: .jsObject(nil),
                     effects: effects,
-                    genericParameters: constructor.genericParameterNames
+                    genericParameters: constructor.genericParameters ?? []
                 )
             ]
         }

Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift

@@ -7,6 +7,13 @@ import BridgeJSUtilities
 import BridgeJSSkeleton
 #endif
 
+/// Outcome of parsing the constraint clause of a generic parameter on a
+/// `@JS`/`@JSFunction` declaration.
+enum GenericConstraintParseResult {
+    case parsed(GenericParameter)
+    case failed(message: String)
+}
+
 /// Outcome of attempting to resolve a type as a reference to a generic parameter.
 enum GenericParameterResolution {
     case resolved(BridgeType)
@@ -981,11 +988,85 @@ public final class SwiftToSkeleton {
         return name.unicodeScalars.dropFirst().allSatisfy { isIdentifierPart($0, isStart: false) }
     }
 
-    fileprivate static func isBridgeableGenericConstraint(_ constraint: String?) -> Bool {
+    fileprivate static func isBridgeableGenericConstraint(_ constraint: String) -> Bool {
         constraint == "BridgedSwiftGenericBridgeable"
             || constraint == "JavaScriptKit.BridgedSwiftGenericBridgeable"
     }
 
+    /// Returns the name of the `@JS protocol` referenced by `type`, or `nil` when the
+    /// type does not resolve to a `@JS protocol` declared in this module or in a
+    /// dependency module indexed by `ExternalModuleIndex`.
+    fileprivate func resolveJSProtocolConstraint(for type: TypeSyntax) -> String? {
+        if let typeDecl = typeDeclResolver.resolve(type) {
+            guard let protocolDecl = typeDecl.as(ProtocolDeclSyntax.self),
+                protocolDecl.attributes.hasJSAttribute()
+            else {
+                return nil
+            }
+            return protocolDecl.name.text
+        }
+        var scratchErrors: [DiagnosticError] = []
+        if let externalType = resolveExternal(for: type, errors: &scratchErrors),
+            case .swiftProtocol(let name) = externalType
+        {
+            return name
+        }
+        return nil
+    }
+
+    /// Parses the constraint clause of a single generic parameter on a `@JS`/`@JSFunction`
+    /// declaration.
+    ///
+    /// The supported spellings are `BridgedSwiftGenericBridgeable` alone or a protocol
+    /// composition of `BridgedSwiftGenericBridgeable` with one or more `@JS` protocols
+    /// (in any order), e.g. `<T: BridgedSwiftGenericBridgeable & GraphNode>`.
+    fileprivate func parseGenericParameterConstraints(
+        _ genericParam: GenericParameterSyntax,
+        attributeName: String
+    ) -> GenericConstraintParseResult {
+        let paramName = genericParam.name.text
+        guard let inheritedType = genericParam.inheritedType else {
+            return .failed(
+                message:
+                    "Generic parameter '\(paramName)' must be constrained to 'BridgedSwiftGenericBridgeable' to be used with \(attributeName)."
+            )
+        }
+        let elements: [TypeSyntax]
+        if let composition = inheritedType.as(CompositionTypeSyntax.self) {
+            elements = composition.elements.map { TypeSyntax($0.type) }
+        } else {
+            elements = [inheritedType]
+        }
+        var hasBridgeableConstraint = false
+        var constraints: [String] = []
+        for element in elements {
+            if SwiftToSkeleton.isBridgeableGenericConstraint(element.trimmedDescription) {
+                hasBridgeableConstraint = true
+                continue
+            }
+            guard let protocolName = resolveJSProtocolConstraint(for: element) else {
+                return .failed(
+                    message:
+                        "Generic parameter '\(paramName)' has unsupported constraint '\(element.trimmedDescription)'. "
+                        + "Constraints on generic \(attributeName) declarations must be 'BridgedSwiftGenericBridgeable', "
+                        + "optionally composed with '@JS' protocols (e.g. '\(paramName): BridgedSwiftGenericBridgeable & MyProtocol')."
+                )
+            }
+            if !constraints.contains(protocolName) {
+                constraints.append(protocolName)
+            }
+        }
+        guard hasBridgeableConstraint else {
+            let suggested = (["BridgedSwiftGenericBridgeable"] + constraints).joined(separator: " & ")
+            return .failed(
+                message:
+                    "Generic parameter '\(paramName)' is missing the 'BridgedSwiftGenericBridgeable' constraint. "
+                    + "Write '\(paramName): \(suggested)' to combine it with '@JS' protocol constraints on \(attributeName) declarations."
+            )
+        }
+        return .parsed(GenericParameter(name: paramName, constraints: constraints))
+    }
+
 }
 
 private enum ExportSwiftConstants {
@@ -1579,19 +1660,24 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             return nil
         }
 
-        var genericParameterNames: [String] = []
+        var genericParameters: [GenericParameter] = []
         if let genericClause = node.genericParameterClause {
             for genericParam in genericClause.parameters {
-                let constraint = genericParam.inheritedType?.trimmedDescription
-                guard SwiftToSkeleton.isBridgeableGenericConstraint(constraint) else {
-                    diagnose(
-                        node: node,
-                        message:
-                            "Generic parameter '\(genericParam.name.text)' must be constrained to 'BridgedSwiftGenericBridgeable' to be used with @JS."
-                    )
+                switch parent.parseGenericParameterConstraints(genericParam, attributeName: "@JS") {
+                case .failed(let message):
+                    diagnose(node: node, message: message)
                     return nil
+                case .parsed(let genericParameter):
+                    if !genericParameter.constraints.isEmpty {
+                        diagnose(
+                            node: node,
+                            message:
+                                "'@JS' protocol constraints on generic parameters are not yet supported on exports."
+                        )
+                        return nil
+                    }
+                    genericParameters.append(genericParameter)
                 }
-                genericParameterNames.append(genericParam.name.text)
             }
             if node.genericWhereClause != nil {
                 diagnose(
@@ -1615,6 +1701,7 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
                 return nil
             }
         }
+        let genericParameterNames = genericParameters.map(\.name)
 
         let name = node.name.text
         let jsName = extractValidatedJSName(from: jsAttribute)
@@ -1780,7 +1867,7 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
             namespace: finalNamespace,
             staticContext: staticContext,
             documentation: extractDocumentation(from: node),
-            genericParameters: genericParameterNames.isEmpty ? nil : genericParameterNames
+            genericParameters: genericParameters.isEmpty ? nil : genericParameters
         )
     }
 
@@ -3589,32 +3676,27 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
 
     // MARK: - Parsing Methods
 
-    /// Validates and collects the generic parameter names of an imported
-    /// `@JSFunction` declaration (function, method or initializer).
+    /// Validates and collects the generic parameters of an imported
+    /// `@JSFunction` declaration (function, method or initializer), including
+    /// any `@JS protocol` constraints composed with `BridgedSwiftGenericBridgeable`.
     ///
     /// Returns `nil` when a diagnostic was emitted; an empty array when the
     /// declaration is not generic.
-    private func parseGenericParameterNames(
+    private func parseGenericParameters(
         genericParameterClause: GenericParameterClauseSyntax?,
         genericWhereClause: GenericWhereClauseSyntax?,
         node: Syntax
-    ) -> [String]? {
-        var genericParameterNames: [String] = []
+    ) -> [GenericParameter]? {
+        var genericParameters: [GenericParameter] = []
         if let genericParameterClause {
             for genericParam in genericParameterClause.parameters {
-                let paramName = genericParam.name.text
-                let constraintText = genericParam.inheritedType?.trimmedDescription
-                guard SwiftToSkeleton.isBridgeableGenericConstraint(constraintText) else {
-                    errors.append(
-                        DiagnosticError(
-                            node: Syntax(genericParam),
-                            message:
-                                "Generic parameter '\(paramName)' must be constrained to 'BridgedSwiftGenericBridgeable' to be used with @JSFunction."
-                        )
-                    )
+                switch parent.parseGenericParameterConstraints(genericParam, attributeName: "@JSFunction") {
+                case .failed(let message):
+                    errors.append(DiagnosticError(node: Syntax(genericParam), message: message))
                     return nil
+                case .parsed(let genericParameter):
+                    genericParameters.append(genericParameter)
                 }
-                genericParameterNames.append(paramName)
             }
         }
         if genericWhereClause != nil {
@@ -3626,7 +3708,7 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
             )
             return nil
         }
-        return genericParameterNames
+        return genericParameters
     }
 
     private func parseConstructor(
@@ -3643,14 +3725,15 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
             return nil
         }
         guard
-            let genericParameterNames = parseGenericParameterNames(
+            let genericParameters = parseGenericParameters(
                 genericParameterClause: initializer.genericParameterClause,
                 genericWhereClause: initializer.genericWhereClause,
                 node: Syntax(initializer)
             )
         else {
             return nil
         }
+        let genericParameterNames = genericParameters.map(\.name)
         if !genericParameterNames.isEmpty && effects.isAsync {
             errors.append(
                 DiagnosticError(
@@ -3683,7 +3766,7 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
         return ImportedConstructorSkeleton(
             parameters: parameters,
             accessLevel: accessLevel,
-            genericParameters: genericParameterNames.isEmpty ? nil : genericParameterNames
+            genericParameters: genericParameters.isEmpty ? nil : genericParameters
         )
     }
 
@@ -3702,14 +3785,15 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
         }
 
         guard
-            let genericParameterNames = parseGenericParameterNames(
+            let genericParameters = parseGenericParameters(
                 genericParameterClause: node.genericParameterClause,
                 genericWhereClause: node.genericWhereClause,
                 node: Syntax(node)
             )
         else {
             return nil
         }
+        let genericParameterNames = genericParameters.map(\.name)
 
         let baseName = SwiftToSkeleton.normalizeIdentifier(node.name.text)
         let extractedJSName = extractJSName(from: jsFunction)
@@ -3773,7 +3857,7 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
             effects: effects,
             documentation: nil,
             accessLevel: accessLevel,
-            genericParameters: genericParameterNames.isEmpty ? nil : genericParameterNames
+            genericParameters: genericParameters.isEmpty ? nil : genericParameters
         )
     }
 

Plugins/BridgeJS/Sources/BridgeJSLink/BridgeJSLink.swift

@@ -1607,7 +1607,7 @@ public struct BridgeJSLink {
                     // Add methods
                     for method in type.methods {
                         let methodName = method.resolvedJSName
-                        let genericClause = renderGenericClause(method.genericParameterNames)
+                        let genericClause = renderGenericClause(method.genericParameters ?? [])
                         let methodSignature =
                             "\(renderTSPropertyName(methodName))\(genericClause)\(renderTSSignature(parameters: method.parameters, returnType: method.returnType, effects: method.effects));"
                         printer.write(methodSignature)
@@ -1948,8 +1948,14 @@ public struct BridgeJSLink {
         return "(\(parameterSignatures.joined(separator: ", "))): \(returnTypeWithEffect)"
     }
 
-    private func renderGenericClause(_ genericParameterNames: [String]) -> String {
-        genericParameterNames.isEmpty ? "" : "<\(genericParameterNames.joined(separator: ", "))>"
+    private func renderGenericClause(_ genericParameters: [GenericParameter]) -> String {
+        guard !genericParameters.isEmpty else { return "" }
+        let renderedParameters = genericParameters.map { genericParameter in
+            genericParameter.constraints.isEmpty
+                ? genericParameter.name
+                : "\(genericParameter.name) extends \(genericParameter.constraints.joined(separator: " & "))"
+        }
+        return "<\(renderedParameters.joined(separator: ", "))>"
     }
 
     /// The d.ts member signature of an exported function; generic functions
@@ -1972,7 +1978,7 @@ public struct BridgeJSLink {
         for (genericName, tokenName) in zip(genericNames, tokenNames) {
             parameterSignatures.append("\(tokenName): BridgeType<\(genericName)>")
         }
-        let genericClause = renderGenericClause(genericNames)
+        let genericClause = renderGenericClause(function.genericParameters ?? [])
         let returnSignature = resolveTypeScriptType(function.returnType)
         return
             "\(function.resolvedJSName)\(genericClause)(\(parameterSignatures.joined(separator: ", "))): \(returnSignature)"
@@ -3919,10 +3925,9 @@ extension BridgeJSLink {
             returnType: function.returnType,
             intrinsicRegistry: intrinsicRegistry
         )
-        let genericParameters = function.genericParameterNames
         try thunkBuilder.liftParametersAndGenericTypeIds(
             function.parameters,
-            genericParameters: genericParameters
+            genericParameters: function.genericParameterNames
         )
         let jsName = function.resolvedJSName
         let calleeExpr = try importedModuleRegistry.memberExpression(
@@ -3934,7 +3939,7 @@ extension BridgeJSLink {
         try thunkBuilder.call(calleeExpr: calleeExpr)
         let funcLines = thunkBuilder.renderFunction(name: function.abiName(context: nil))
         if function.from == nil {
-            let genericClause = renderGenericClause(genericParameters)
+            let genericClause = renderGenericClause(function.genericParameters ?? [])
             importObjectBuilder.appendDts(
                 [
                     "\(renderTSPropertyName(jsName))\(genericClause)\(renderTSSignature(parameters: function.parameters, returnType: function.returnType, effects: function.effects));"
@@ -4027,14 +4032,14 @@ extension BridgeJSLink {
             dtsPrinter.indent {
                 if let constructor = type.constructor {
                     let returnType = BridgeType.jsObject(type.name)
-                    let genericClause = renderGenericClause(constructor.genericParameterNames)
+                    let genericClause = renderGenericClause(constructor.genericParameters ?? [])
                     dtsPrinter.write(
                         "new\(genericClause)\(renderTSSignature(parameters: constructor.parameters, returnType: returnType, effects: Effects(isAsync: false, isThrows: false)));"
                     )
                 }
                 for method in type.staticMethods {
                     let methodName = method.resolvedJSName
-                    let genericClause = renderGenericClause(method.genericParameterNames)
+                    let genericClause = renderGenericClause(method.genericParameters ?? [])
                     let signature =
                         "\(renderTSPropertyName(methodName))\(genericClause)\(renderTSSignature(parameters: method.parameters, returnType: method.returnType, effects: method.effects));"
                     dtsPrinter.write(signature)
@@ -4145,10 +4150,9 @@ extension BridgeJSLink {
             intrinsicRegistry: intrinsicRegistry
         )
         thunkBuilder.liftSelf()
-        let genericParameters = method.genericParameterNames
         try thunkBuilder.liftParametersAndGenericTypeIds(
             method.parameters,
-            genericParameters: genericParameters
+            genericParameters: method.genericParameterNames
         )
 
         try thunkBuilder.callMethod(name: method.resolvedJSName)