BridgeJS: split snippet and external module import origins

Use `from: .snippet("/my-file.js")` for a JavaScript file shipped with the Swift target and
`from: .module("node:path")` for an external module, so each keeps its own validation and
each mistaken form points at the other. The skeleton encoding is unchanged.

Author: kateinoigakukun

Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift

@@ -98,21 +98,31 @@ public final class SwiftToSkeleton {
                 importCollector.importedFunctions.compactMap(\.from)
                 + importCollector.importedTypes.compactMap(\.from)
                 + importCollector.importedGlobalGetters.compactMap(\.from)
-            // Only target-local module paths are validated here. Bare specifiers are
-            // resolved by the JavaScript host (a bundler, an import map, or Node's
-            // `node_modules` lookup), so there is nothing we can check without
-            // rejecting setups that legitimately work.
-            let modulePaths = Set(importOrigins.compactMap(\.localModulePath))
-            for path in modulePaths.sorted() {
+            // Only snippet paths are validated here. Bare module specifiers are resolved
+            // by the JavaScript host (a bundler, an import map, or Node's `node_modules`
+            // lookup), so there is nothing we can check without rejecting setups that
+            // legitimately work.
+            let snippetPaths = Set(importOrigins.compactMap(\.snippetPath))
+            for path in snippetPaths.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 snippet paths must start with '/' to indicate the Swift target root: "
+                                + "'\(path)'. For an external module, use 'from: .module(\"\(path)\")' instead."
+                        )
+                    )
+                    continue
+                }
                 guard !path.split(separator: "/").contains("..") else {
                     importCollector.errors.append(
                         DiagnosticError(
                             node: pathNode,
-                            message: "JavaScript module paths must not contain '..': '\(path)'."
+                            message: "JavaScript snippet paths must not contain '..': '\(path)'."
                         )
                     )
                     continue
@@ -122,7 +132,7 @@ public final class SwiftToSkeleton {
                     importCollector.errors.append(
                         DiagnosticError(
                             node: pathNode,
-                            message: "JavaScript modules must use a '.js' or '.mjs' extension: '\(path)'."
+                            message: "JavaScript snippets must use a '.js' or '.mjs' extension: '\(path)'."
                         )
                     )
                     continue
@@ -131,7 +141,7 @@ public final class SwiftToSkeleton {
                     importCollector.errors.append(
                         DiagnosticError(
                             node: pathNode,
-                            message: "JavaScript module file was not found at '\(path)'."
+                            message: "JavaScript snippet file was not found at '\(path)'."
                         )
                     )
                     continue
@@ -2643,21 +2653,21 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
             return
         }
         switch from {
-        case .module:
+        case .module, .snippet:
             return
         case .global:
             errors.append(
                 DiagnosticError(
                     node: node,
-                    message: "'jsName: .default' requires 'from: .module(...)'; "
+                    message: "'jsName: .default' requires 'from: .module(...)' or 'from: .snippet(...)'; "
                         + "globalThis has no default export."
                 )
             )
         case nil:
             errors.append(
                 DiagnosticError(
                     node: node,
-                    message: "'jsName: .default' requires 'from: .module(...)'."
+                    message: "'jsName: .default' requires 'from: .module(...)' or 'from: .snippet(...)'."
                 )
             )
         }
@@ -2671,8 +2681,10 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
         }
 
         if let call = argument.expression.as(FunctionCallExprSyntax.self),
-            call.calledExpression.trimmedDescription.split(separator: ".").last == "module"
+            let caseName = call.calledExpression.trimmedDescription.split(separator: ".").last,
+            caseName == "module" || caseName == "snippet"
         {
+            let isSnippet = caseName == "snippet"
             guard call.arguments.count == 1,
                 let pathExpression = call.arguments.first?.expression,
                 let literal = pathExpression.as(StringLiteralExprSyntax.self),
@@ -2681,7 +2693,9 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
                 errors.append(
                     DiagnosticError(
                         node: call.arguments.first?.expression ?? argument.expression,
-                        message: "JavaScript module path must be a string literal."
+                        message: isSnippet
+                            ? "JavaScript snippet path must be a string literal."
+                            : "JavaScript module specifier must be a string literal."
                     )
                 )
                 return nil
@@ -2690,7 +2704,28 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
                 errors.append(
                     DiagnosticError(
                         node: literal,
-                        message: "JavaScript module specifier must not be empty."
+                        message: isSnippet
+                            ? "JavaScript snippet path must not be empty."
+                            : "JavaScript module specifier must not be empty."
+                    )
+                )
+                return nil
+            }
+            if isSnippet {
+                // Full validation of the path happens in `finalize()`, where the file
+                // can also be checked for existence.
+                if importedModulePathNodes[path] == nil {
+                    importedModulePathNodes[path] = Syntax(literal)
+                }
+                return .snippet(path)
+            }
+            guard !path.hasPrefix("/") else {
+                errors.append(
+                    DiagnosticError(
+                        node: literal,
+                        message: "'\(path)' looks like a file in this target. "
+                            + "Use 'from: .snippet(\"\(path)\")' for a JavaScript file you ship with the target, "
+                            + "and 'from: .module(...)' for an external module (e.g. 'node:path')."
                     )
                 )
                 return nil
@@ -2700,15 +2735,12 @@ private final class ImportSwiftMacrosAPICollector: SyntaxAnyVisitor {
                     DiagnosticError(
                         node: literal,
                         message: "Relative JavaScript module specifiers are not supported: '\(path)'. "
-                            + "Use a '/'-prefixed path for a file in this target (e.g. '/Modules/utils.mjs'), "
+                            + "Use 'from: .snippet(\"/path/to/file.js\")' for a file in this target, "
                             + "or a bare specifier for an external module (e.g. 'node:path')."
                     )
                 )
                 return nil
             }
-            if importedModulePathNodes[path] == nil {
-                importedModulePathNodes[path] = Syntax(literal)
-            }
             return .module(path)
         }
 

Plugins/BridgeJS/Sources/BridgeJSLink/ImportedJSModuleRegistry.swift

@@ -7,19 +7,19 @@ import Foundation
 final class ImportedJSModuleRegistry {
     /// A JavaScript module that imported declarations are read from.
     ///
-    /// A `local` reference is a file inside a Swift target, which packaging copies
-    /// into the generated output. A `bare` reference is a specifier resolved by the
-    /// JavaScript host (a bundler, an import map, or Node's `node_modules` lookup),
-    /// so it has no file and nothing to copy. Because a bare specifier names the
-    /// same module no matter which Swift module mentions it — and ECMAScript caches
-    /// module instances — it is keyed by specifier alone and shared across targets.
+    /// A `snippet` reference is a file inside a Swift target, which packaging copies
+    /// into the generated output. A `module` reference is a bare specifier resolved by
+    /// the JavaScript host (a bundler, an import map, or Node's `node_modules` lookup),
+    /// so it has no file and nothing to copy. Because a bare specifier names the same
+    /// module no matter which Swift module mentions it — and ECMAScript caches module
+    /// instances — it is keyed by specifier alone and shared across targets.
     enum Reference: Hashable {
-        case local(swiftModuleName: String, path: String)
-        case bare(specifier: String)
+        case snippet(swiftModuleName: String, path: String)
+        case module(specifier: String)
     }
 
-    /// A target-local JavaScript file that packaging must copy into the output.
-    struct LocalModule: Hashable {
+    /// A JavaScript file shipped in a Swift target that packaging must copy into the output.
+    struct SnippetFile: Hashable {
         let swiftModuleName: String
         let path: String
 
@@ -40,11 +40,11 @@ final class ImportedJSModuleRegistry {
     private var bindings: [Reference: Binding] = [:]
     private(set) var references: [Reference] = []
 
-    /// The target-local files packaging must copy, in deterministic order.
-    var localModules: [LocalModule] {
+    /// The snippet files packaging must copy, in deterministic order.
+    var snippetFiles: [SnippetFile] {
         references.compactMap { reference in
-            guard case .local(let swiftModuleName, let path) = reference else { return nil }
-            return LocalModule(swiftModuleName: swiftModuleName, path: path)
+            guard case .snippet(let swiftModuleName, let path) = reference else { return nil }
+            return SnippetFile(swiftModuleName: swiftModuleName, path: path)
         }
     }
 
@@ -82,18 +82,18 @@ final class ImportedJSModuleRegistry {
         return references.sorted(by: isOrderedBefore)
     }
 
-    static func collectLocalModules(skeletons: [BridgeJSSkeleton]) -> [LocalModule] {
+    static func collectSnippetFiles(skeletons: [BridgeJSSkeleton]) -> [SnippetFile] {
         collectReferences(skeletons: skeletons).compactMap { reference in
-            guard case .local(let swiftModuleName, let path) = reference else { return nil }
-            return LocalModule(swiftModuleName: swiftModuleName, path: path)
+            guard case .snippet(let swiftModuleName, let path) = reference else { return nil }
+            return SnippetFile(swiftModuleName: swiftModuleName, path: path)
         }
     }
 
     /// Visits every module origin mentioned by the skeleton, whether or not code
     /// generation looks a member up on it.
     ///
-    /// This is what decides which modules are imported at all, and for local paths
-    /// which files packaging copies. It stays broader than `forEachMemberLookup` so
+    /// This is what decides which modules are imported at all, and for snippets which
+    /// files packaging copies. It stays broader than `forEachMemberLookup` so
     /// that a module mentioned only by a wrapper-only `@JSClass` is still imported,
     /// preserving its side effects.
     private static func forEachOrigin(
@@ -146,22 +146,25 @@ final class ImportedJSModuleRegistry {
     }
 
     private static func reference(swiftModuleName: String, from: JSImportFrom?) -> Reference? {
-        guard let specifier = from?.moduleSpecifier else { return nil }
-        if let path = from?.localModulePath {
-            return .local(swiftModuleName: swiftModuleName, path: path)
+        switch from {
+        case .snippet(let path):
+            return .snippet(swiftModuleName: swiftModuleName, path: path)
+        case .module(let specifier):
+            return .module(specifier: specifier)
+        case .global, nil:
+            return nil
         }
-        return .bare(specifier: specifier)
     }
 
     private static func isOrderedBefore(_ lhs: Reference, _ rhs: Reference) -> Bool {
         switch (lhs, rhs) {
-        case (.local(let lhsModule, let lhsPath), .local(let rhsModule, let rhsPath)):
+        case (.snippet(let lhsModule, let lhsPath), .snippet(let rhsModule, let rhsPath)):
             return (lhsModule, lhsPath) < (rhsModule, rhsPath)
-        case (.bare(let lhsSpecifier), .bare(let rhsSpecifier)):
+        case (.module(let lhsSpecifier), .module(let rhsSpecifier)):
             return lhsSpecifier < rhsSpecifier
-        case (.local, .bare):
+        case (.snippet, .module):
             return true
-        case (.bare, .local):
+        case (.module, .snippet):
             return false
         }
     }
@@ -185,12 +188,13 @@ final class ImportedJSModuleRegistry {
                 objectExpr: "globalThis",
                 propertyName: memberName
             )
-        case .module(let specifier):
+        case .snippet, .module:
             guard let reference = Self.reference(swiftModuleName: swiftModuleName, from: from),
                 let binding = bindings[reference]
             else {
                 throw BridgeJSLinkError(
-                    message: "Missing JavaScript module \(swiftModuleName)\(specifier)"
+                    message:
+                        "Missing JavaScript module \(swiftModuleName)\(from?.snippetPath ?? from?.moduleSpecifier ?? "")"
                 )
             }
             if binding.usesNamedImports {
@@ -216,11 +220,11 @@ final class ImportedJSModuleRegistry {
             guard let binding = bindings[reference] else { return nil }
             let specifier: String
             switch reference {
-            case .local(let swiftModuleName, let path):
-                let output = LocalModule(swiftModuleName: swiftModuleName, path: path).relativeOutputPath
+            case .snippet(let swiftModuleName, let path):
+                let output = SnippetFile(swiftModuleName: swiftModuleName, path: path).relativeOutputPath
                 specifier = "./" + BridgeJSLink.escapeForJavaScriptStringLiteral(output)
-            case .bare(let bareSpecifier):
-                specifier = BridgeJSLink.escapeForJavaScriptStringLiteral(bareSpecifier)
+            case .module(let moduleSpecifier):
+                specifier = BridgeJSLink.escapeForJavaScriptStringLiteral(moduleSpecifier)
             }
             guard binding.usesNamedImports else {
                 return "import * as \(Self.namespaceAlias(index: binding.index)) from \"\(specifier)\";"