klenod-plugin-javascript 0.0.12-x86_64-linux-gnu → 0.0.13-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8117e64488faa6ab8e716adbce568893af298b96b7d27e55c4ef4d8c5caa5681
-  data.tar.gz: a1e15c41e54b2ac75a28acb606a82e64be7f02d26d0459a2365bfff05a3d577d
+  metadata.gz: 93e12c1ce189a9594b75b4dd1089c0b89836820779e2e7eeb24c0d90d0ccc917
+  data.tar.gz: 7f37d8ce72b820bdf3f4d49811339277632a3ea50106425785134ed4823a4635
 SHA512:
-  metadata.gz: 880b4e792cbae668f96bcb2676b858808b0d46658eb454f381e5daeab2b00189a8796060fb177dd7faaca7f1499ac71ae76adc52e24e464937b3d72cf796585e
-  data.tar.gz: f17cc652483ac611d711623c7fa0758b6f01a031bb8dafdc9cd880cbdf1745ca98daa86add5fdbe1c721f8e6c7af83f74731caec8483486145e82ea52ce7232b
+  metadata.gz: 9b20181d84ce6a159b32e0c771d352dfb52286b2e6f795418ccb599589f621710119d3d9bafd42602f228d976a74aa20f26623f9fcd6e7d80058513954462191
+  data.tar.gz: 26159b0c1ec522c4b4a48cd242442818aa6c4df009f391f515cfbc0cbb1040d4af5bdaf02ba3da4dab1d4d1831f4ed6f23ccd2dcc1595208dbe50bc034c75f0e

data/README.md

@@ -7,12 +7,10 @@ It:
 
 - collects static imports, re-exports, and string-literal dynamic imports
 - transforms JavaScript, TypeScript, JSX, and TSX
-- rewrites local imports to content-hashed asset paths
+- rewrites graph imports to content-hashed asset paths
 - emits image and SVG wrappers backed by shared `ImageBase`, `ImageMetadata`, `ImageVariant`, and `SvgMetadata` classes, with frozen concrete metadata values, only for assets imported from JavaScript
 - preserves external URL imports
 
-Bare package imports and npm resolution are not currently supported.
-
 ## Options
 
 ```ruby
@@ -27,3 +25,79 @@ Klenod::Build::Plugins::JavaScriptPlugin.new(
 - `source_maps:` accepts `false`, `true`, or `:development` (the default).
 - `minify:` also minifies in development when `true`; build output is always
   minified.
+
+## npm Packages
+
+`NodeModulesPlugin` adds npm packages to the Klenod graph. It is opt-in; register
+it before `JavaScriptPlugin` so the JavaScript plugin can transform the files it
+resolves:
+
+```ruby
+plugins [
+  Klenod::Build::Plugins::NodeModulesPlugin.new,
+  Klenod::Build::Plugins::JavaScriptPlugin.new
+]
+```
+
+Use an explicit `npm://` URL from application code. This keeps package lookup
+separate from Klenod's usual rule that a bare specifier is relative to its
+importer.
+
+```js
+import * as THREE from "npm://three";
+import { vec3 } from "npm://gl-matrix";
+import { OrbitControls } from "npm://three/addons/controls/OrbitControls.js";
+import { ReactiveElement } from "npm://@lit/reactive-element";
+import { css } from "npm://@lit/reactive-element/css-tag.js";
+```
+
+The part after `npm://` is the package name, followed by an optional exported
+subpath. Scoped names retain the usual `@scope/package` form. The scheme works
+with static imports, side-effect imports, re-exports, and string-literal dynamic
+imports:
+
+```js
+import "npm://@scope/widget";
+export { html } from "npm://lit";
+button.addEventListener("click", () => import("npm://three"));
+```
+
+Exported subpaths must match the package's `exports` map. Include an extension
+when the export includes one: use
+`npm://three/addons/controls/OrbitControls.js` for Three.js, but
+`npm://zod/mini` for Zod.
+
+`NodeModulesPlugin` selects package exports using the `browser`, `import`,
+`module`, and `default` conditions. It respects the order of conditions in
+`package.json`. Packages without `exports` fall back to `module`, then `main`,
+then `index.js`.
+
+Once inside an npm package, relative imports continue within that package and
+bare specifiers resolve its dependencies from the nearest `node_modules`
+directory. Package self-references and `#` imports are supported through the
+package's `exports` and `imports` maps. Extensionless package imports probe
+`.js`, `.mjs`, `index.js`, and `index.mjs`; targets from an `exports` map are
+exact and are not probed.
+
+Resolved package files are ordinary graph modules. Klenod transforms them,
+rewrites their imports, emits content-hashed assets, and minifies them in build
+mode.
+
+### Configuration
+
+- `root:` overrides the `node_modules` directory. By default the nearest one at
+  or above the source directory is used.
+- `conditions:` overrides the matched export conditions. The default is
+  `browser`, `import`, `module`, and `default`, matched in the order the package
+  lists them.
+
+### Compatibility
+
+Only ES modules are supported. CommonJS packages, Node builtins, the legacy
+`browser` field, and JSON package imports are not supported. A `browser`
+condition inside `exports` is supported.
+
+Each package name can refer to only one physical directory in a graph because
+module IDs use the form `npm://<package>/<path>`. If resolution finds two copies
+of a package, Klenod reports the conflict; deduplicate that package in the
+lockfile.

data/lib/klenod/build/plugins/javascript_plugin.rb

@@ -30,6 +30,9 @@ module Klenod
           JSX_RUNTIME_MODULE_ID = ModuleId.new("virtual:klenod/jsx-runtime.js", nil)
           LOCAL_SPECIFIER_PATTERN = %r{\A(?:\.{1,2}/|/|app:/)}
           EXTERNAL_SPECIFIER_PATTERN = %r{\A(?:[A-Za-z][A-Za-z0-9+.-]*:)?//}
+          # Also matches EXTERNAL_SPECIFIER_PATTERN, so npm imports have to be
+          # recognised before a specifier is treated as an external URL.
+          NPM_SPECIFIER_PATTERN = %r{\Anpm://}
           VALID_SOURCE_MAP_MODES = [false, true, :development].freeze
           IDENTIFIER_PATTERN = '[$_\p{Alpha}][$\u200c\u200d\p{Alnum}_]*'
           DEFAULT_EXPORT_CLASS_PATTERN = /\bexport\s+default\s+class\s+(#{IDENTIFIER_PATTERN})\b/
@@ -217,9 +220,13 @@ module Klenod
           end
 
           def build_dependencies(module_id, imports)
+            # Inside an npm package a bare specifier names another package, so
+            # let it reach the resolver instead of rejecting it here.
+            npm_importer = module_id.scheme == :npm
+
             imports.filter_map.with_index do |import, index|
-              next if external_specifier?(import.specifier)
-              raise DynamicImportError, unsupported_specifier_message(import) unless local_specifier?(import.specifier) || import.specifier == JSX_RUNTIME_SPECIFIER
+              next if external_specifier?(import.specifier) && !npm_specifier?(import.specifier)
+              raise DynamicImportError, unsupported_specifier_message(import) unless npm_importer || bundled_specifier?(import.specifier)
 
               Dependency
                 .create(
@@ -415,13 +422,21 @@ module Klenod
           end
 
           def unsupported_specifier_message(import)
-            "Unsupported JavaScript import #{import.specifier.inspect} at #{import.loc}. Only relative, app-root, and external URL imports are supported."
+            "Unsupported JavaScript import #{import.specifier.inspect} at #{import.loc}. Only relative, app-root, npm, and external URL imports are supported."
+          end
+
+          def bundled_specifier?(specifier)
+            local_specifier?(specifier) || npm_specifier?(specifier) || specifier == JSX_RUNTIME_SPECIFIER
           end
 
           def local_specifier?(specifier)
             specifier.match?(LOCAL_SPECIFIER_PATTERN)
           end
 
+          def npm_specifier?(specifier)
+            specifier.match?(NPM_SPECIFIER_PATTERN)
+          end
+
           def external_specifier?(specifier)
             specifier.match?(EXTERNAL_SPECIFIER_PATTERN)
           end

data/lib/klenod/build/plugins/node_modules_plugin/package_exports.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+module Klenod
+  module Build
+    module Plugins
+      module NodeModulesPlugin
+        # Resolves a package subpath to a package-relative file path using the
+        # metadata in a `package.json`.
+        #
+        # This module never touches the filesystem. It reports what a package
+        # claims about itself; checking that the returned path exists, and
+        # probing for extensions when it does not, belongs to the caller.
+        module PackageExports
+          # Conditions are matched in `package.json` key order, so this is a
+          # membership set rather than a priority list.
+          #
+          # "require" is absent on purpose. It names the CommonJS entry, which
+          # the JavaScript plugin cannot transform, and leaving it out turns a
+          # CommonJS-only package into a resolve-time error instead of a module
+          # that fails in the browser.
+          DEFAULT_CONDITIONS = ["browser", "import", "module", "default"].freeze
+
+          # Consulted in order when a package has no "exports" field. "module"
+          # precedes "main" because it is the conventional ES module entry,
+          # while "main" is usually CommonJS.
+          LEGACY_ENTRY_FIELDS = ["module", "main"].freeze
+          LEGACY_INDEX = "index.js"
+
+          # Only "require" names a CommonJS entry. "node" says nothing about the
+          # module system, so a node-only target is reported as an unmatched
+          # condition instead.
+          COMMONJS_CONDITIONS = ["require"].freeze
+          MAX_LISTED_SUBPATHS = 8
+
+          BLOCKED = :blocked
+
+          Result = Data.define(:path, :reason, :message) do
+            def self.resolved(path)
+              new(path, nil, nil)
+            end
+
+            def self.unresolved(reason, message)
+              new(nil, reason, message)
+            end
+
+            def resolved?
+              !path.nil?
+            end
+          end
+
+          module_function
+
+          # Resolve +subpath+ against +package_json+.
+          #
+          # Returns a Result whose +path+ is relative to the package root, or an
+          # unresolved Result carrying a +reason+ and a human-readable +message+.
+          def resolve(package_json, subpath: ".", conditions: DEFAULT_CONDITIONS)
+            return Result.unresolved(:invalid, "package.json must contain an object.") unless package_json.is_a?(Hash)
+
+            subpath = normalize_subpath(subpath)
+            return legacy_resolve(package_json, subpath) unless package_json.key?("exports")
+
+            resolve_exports(package_json["exports"], subpath, conditions)
+          end
+
+          # Resolve a "#"-prefixed private import against the package's "imports"
+          # field.
+          #
+          # Unlike an export target, an import target may name another package,
+          # so a resolved path keeps its "./" prefix when it refers to a file
+          # inside this package and is a bare specifier otherwise.
+          def resolve_private(package_json, specifier:, conditions: DEFAULT_CONDITIONS)
+            return Result.unresolved(:invalid, "package.json must contain an object.") unless package_json.is_a?(Hash)
+
+            unless specifier.is_a?(String) && specifier.start_with?("#") && specifier != "#" && !specifier.start_with?("#/")
+              return Result.unresolved(:invalid, "#{specifier.inspect} is not a valid private import.")
+            end
+
+            imports = package_json["imports"]
+
+            unless imports.is_a?(Hash)
+              return Result.unresolved(:no_match, "The package has no imports field to resolve #{specifier.inspect}.")
+            end
+
+            if imports.key?(specifier)
+              return resolve_matched_target(imports.fetch(specifier), specifier, conditions, nil, validate: false)
+            end
+
+            key, pattern_match = best_pattern_match(imports, specifier)
+
+            unless key
+              return Result.unresolved(
+                :no_match,
+                "The package does not define #{specifier.inspect}. Available private imports: #{imports.keys.sort.first(MAX_LISTED_SUBPATHS).join(", ")}."
+              )
+            end
+
+            resolve_matched_target(imports.fetch(key), specifier, conditions, pattern_match, validate: false)
+          end
+
+          def normalize_subpath(subpath)
+            value = subpath.to_s
+            return "." if value.empty? || value == "." || value == "./"
+            return value if value.start_with?("./")
+
+            "./#{value.delete_prefix("/")}"
+          end
+
+          def legacy_resolve(package_json, subpath)
+            return relative_path(subpath, "subpath") unless subpath == "."
+
+            field = LEGACY_ENTRY_FIELDS.find { package_json[it].is_a?(String) && !package_json[it].empty? }
+            return relative_path(LEGACY_INDEX, "default entry") unless field
+
+            relative_path(package_json.fetch(field), "#{field} field")
+          end
+
+          def resolve_exports(exports, subpath, conditions)
+            if exports.is_a?(Hash) && subpath_map?(exports)
+              return mixed_keys_error(exports) unless exports.keys.all? { it.start_with?(".") }
+
+              return resolve_subpath_map(exports, subpath, conditions)
+            end
+
+            # A string, an array, or a bare condition object is sugar for ".".
+            unless subpath == "."
+              return Result.unresolved(:no_match, "The package does not export #{subpath.inspect}. It only exports \".\".")
+            end
+
+            resolve_matched_target(exports, subpath, conditions, nil)
+          end
+
+          def subpath_map?(exports)
+            exports.keys.any? { it.start_with?(".") }
+          end
+
+          def resolve_subpath_map(exports, subpath, conditions)
+            return resolve_matched_target(exports.fetch(subpath), subpath, conditions, nil) if exports.key?(subpath)
+
+            key, pattern_match = best_pattern_match(exports, subpath)
+            return no_match_error(exports, subpath) unless key
+
+            resolve_matched_target(exports.fetch(key), subpath, conditions, pattern_match)
+          end
+
+          # Node picks the pattern key with the longest prefix before "*",
+          # breaking ties on the longest suffix after it.
+          def best_pattern_match(exports, subpath)
+            best_key = nil
+            best_prefix = nil
+            best_suffix = nil
+
+            exports.each_key do |key|
+              prefix, star, suffix = key.partition("*")
+              next if star.empty? || suffix.include?("*")
+              next unless subpath.start_with?(prefix) && subpath.end_with?(suffix)
+              next if subpath.length < prefix.length + suffix.length
+              next if best_key && !better_pattern?(prefix, suffix, best_prefix, best_suffix)
+
+              best_key = key
+              best_prefix = prefix
+              best_suffix = suffix
+            end
+
+            return [nil, nil] unless best_key
+
+            [best_key, subpath[best_prefix.length...(subpath.length - best_suffix.length)]]
+          end
+
+          def better_pattern?(prefix, suffix, best_prefix, best_suffix)
+            return true if prefix.length > best_prefix.length
+
+            prefix.length == best_prefix.length && suffix.length > best_suffix.length
+          end
+
+          def resolve_matched_target(target, subpath, conditions, pattern_match, validate: true)
+            resolved = resolve_target(target, conditions, pattern_match)
+
+            case resolved
+            when String
+              if validate
+                relative_path(resolved, "export target for #{subpath.inspect}")
+              else
+                private_target(resolved, subpath)
+              end
+            when BLOCKED
+              Result.unresolved(:blocked, "The package explicitly blocks #{subpath.inspect}.")
+            else
+              conditions_unmet_error(target, subpath, conditions)
+            end
+          end
+
+          # Returns the target path, BLOCKED when the package maps the subpath to
+          # null, or nil when no condition matched.
+          def resolve_target(target, conditions, pattern_match)
+            case target
+            when String
+              substitute(target, pattern_match)
+            when Hash
+              target.each do |condition, value|
+                next unless condition == "default" || conditions.include?(condition)
+
+                resolved = resolve_target(value, conditions, pattern_match)
+                return resolved if resolved
+              end
+              nil
+            when Array
+              # A blocked entry inside an array is a failed alternative rather
+              # than a block, so keep looking.
+              target.each do |value|
+                resolved = resolve_target(value, conditions, pattern_match)
+                return resolved if resolved.is_a?(String)
+              end
+              nil
+            when nil
+              BLOCKED
+            end
+          end
+
+          def substitute(target, pattern_match)
+            return target unless pattern_match && target.include?("*")
+
+            target.gsub("*", pattern_match)
+          end
+
+          # An "imports" target either points inside the package, keeping its
+          # "./" prefix so the caller can tell the two apart, or names another
+          # package.
+          def private_target(value, specifier)
+            description = "import target for #{specifier.inspect}"
+
+            if value.empty? || value.include?("*")
+              return Result.unresolved(:invalid, "The #{description} #{value.inspect} is not a usable target.")
+            end
+
+            unless value.start_with?("./")
+              if value.start_with?("../", "/", "#")
+                return Result.unresolved(:invalid, "The #{description} #{value.inspect} must stay within the package or name another package.")
+              end
+
+              return Result.resolved(value)
+            end
+
+            inner = value.delete_prefix("./")
+
+            if inner.empty? || inner.split("/").include?("..")
+              return Result.unresolved(:invalid, "The #{description} #{value.inspect} must stay within the package.")
+            end
+
+            Result.resolved(value)
+          end
+
+          def relative_path(value, description)
+            path = value.to_s.delete_prefix("./")
+
+            if path.include?("*")
+              return Result.unresolved(:invalid, "The #{description} #{value.inspect} has an unmatched wildcard.")
+            end
+
+            if path.empty? || path.start_with?("/") || path.split("/").include?("..")
+              return Result.unresolved(:invalid, "The #{description} #{value.inspect} must stay within the package.")
+            end
+
+            Result.resolved(path)
+          end
+
+          def conditions_unmet_error(target, subpath, conditions)
+            available = available_conditions(target)
+
+            if (available & COMMONJS_CONDITIONS).any?
+              return Result.unresolved(
+                :commonjs_only,
+                "#{subpath.inspect} resolves to a CommonJS entry only. Klenod can only import ES modules."
+              )
+            end
+
+            Result.unresolved(
+              :conditions_unmet,
+              "No condition matched for #{subpath.inspect}. " \
+                "Klenod uses #{conditions.to_a.join(", ")}; the package offers #{available.join(", ")}."
+            )
+          end
+
+          def available_conditions(target)
+            case target
+            when Hash then target.flat_map { |condition, value| [condition, *available_conditions(value)] }.uniq
+            when Array then target.flat_map { available_conditions(it) }.uniq
+            else []
+            end
+          end
+
+          def no_match_error(exports, subpath)
+            available = exports.keys.sort
+            listed = available.first(MAX_LISTED_SUBPATHS)
+            ellipsis = (available.length > listed.length) ? ", ..." : ""
+
+            Result.unresolved(
+              :no_match,
+              "The package does not export #{subpath.inspect}. Available subpaths: #{listed.join(", ")}#{ellipsis}."
+            )
+          end
+
+          def mixed_keys_error(exports)
+            conditions = exports.keys.reject { it.start_with?(".") }
+
+            Result.unresolved(
+              :invalid,
+              "package.json exports mixes subpaths with conditions: #{conditions.join(", ")}."
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klenod/build/plugins/node_modules_plugin.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+require "json"
+
+require "klenod/build/dependency"
+require "klenod/build/errors"
+require "klenod/build/hashing"
+require "klenod/build/load_result"
+require "klenod/build/module_id"
+require "klenod/build/plugin"
+
+require_relative "node_modules_plugin/package_exports"
+
+module Klenod
+  module Build
+    module Plugins
+      # Resolves `npm://` imports against an installed `node_modules` directory.
+      #
+      # Bare specifiers stay relative in Klenod, so npm packages are addressed
+      # through an explicit scheme: `import { vec3 } from "npm://gl-matrix"`.
+      # Once a module resolves to the npm scheme, every import inside it comes
+      # back to this plugin, which keeps package resolution from leaking into
+      # application resolution.
+      #
+      # Module IDs are `npm://<package>/<path within the package>`, so a package
+      # name identifies exactly one directory for the life of a graph. Finding
+      # the same name in two places is reported rather than resolved, because
+      # the ID has nowhere to record which copy a module came from.
+      module NodeModulesPlugin
+        def self.new(...)
+          Plugin.new(...)
+        end
+
+        class Plugin < Klenod::Build::Plugin
+          SCHEME = :npm
+          DIRECTORY_NAME = "node_modules"
+          NPM_SPECIFIER_PATTERN = %r{\Anpm://}
+          # A leading "/" addresses the package root, matching how Klenod treats
+          # "/foo" as relative to the current scheme root.
+          RELATIVE_SPECIFIER_PATTERN = %r{\A(?:\.{1,2}/|/)}
+          # Tried for imports that omit an extension. CommonJS builds are not
+          # probed for, since they cannot be transformed anyway.
+          CANDIDATE_EXTENSIONS = [".js", ".mjs"].freeze
+          INDEX_BASENAMES = ["index.js", "index.mjs"].freeze
+          NODE_SCHEME = "node:"
+          PRIVATE_PREFIX = "#"
+          # Only consulted when a bare specifier resolves to nothing, so a
+          # package that really did install a shim named "path" still wins.
+          NODE_BUILTINS = %w[
+            assert async_hooks buffer child_process cluster console constants crypto
+            dgram diagnostics_channel dns domain events fs http http2 https inspector
+            module net os path perf_hooks process punycode querystring readline repl
+            stream string_decoder sys timers tls trace_events tty url util v8 vm wasi
+            worker_threads zlib
+          ].freeze
+
+          def initialize(root: nil, conditions: PackageExports::DEFAULT_CONDITIONS)
+            @root = root && Pathname.new(root).expand_path
+            @conditions = conditions.freeze
+            @package_roots = {}
+            @package_metadata = {}
+          end
+
+          def resolve(dependency, context)
+            specifier = dependency.specifier.to_s
+
+            if specifier.match?(NPM_SPECIFIER_PATTERN)
+              return resolve_scheme(ModuleId.parse(specifier), dependency, context)
+            end
+
+            importer_id = dependency.importer_id
+            return nil unless importer_id&.scheme == SCHEME
+
+            # "node:fs" parses as a scheme, so it has to be caught before the
+            # check that hands other schemes back to the graph.
+            raise node_builtin_error(specifier.delete_prefix(NODE_SCHEME), importer_id) if specifier.start_with?(NODE_SCHEME)
+            return resolve_private(specifier, dependency, importer_id, context) if specifier.start_with?(PRIVATE_PREFIX)
+            return nil if specifier.match?(ModuleId::SCHEME_PATTERN)
+
+            if specifier.match?(RELATIVE_SPECIFIER_PATTERN)
+              resolve_relative(importer_id.merge(specifier), dependency, context)
+            else
+              resolve_bare(specifier, dependency, importer_id, context)
+            end
+          rescue ResolveError => error
+            raise error.with_resolution_context(dependency: dependency, importer_id: dependency.importer_id)
+          end
+
+          def load(module_id, context)
+            return nil unless module_id.scheme == SCHEME
+
+            path = absolute_path(module_id, context)
+            LoadResult.new(path.read(encoding: "UTF-8"), Hashing.file_hexdigest(path), nil)
+          end
+
+          private
+
+          # An "npm://name/subpath" import from application code.
+          def resolve_scheme(module_id, dependency, context)
+            package_name, subpath = split_package(module_id)
+            package_root = root_package_root(package_name, context)
+
+            resolve_entry(package_name, package_root, subpath, dependency, module_id)
+          end
+
+          # A bare specifier inside a package names another package, or the
+          # package itself.
+          def resolve_bare(specifier, dependency, importer_id, context)
+            package_name, subpath = split_specifier(specifier)
+            importer_package, importer_subpath = split_package(importer_id)
+
+            package_root =
+              if package_name == importer_package
+                self_reference_root(package_name, subpath, importer_id, context)
+              else
+                transitive_package_root(package_name, importer_package, importer_subpath, importer_id, context)
+              end
+
+            resolve_entry(package_name, package_root, subpath, dependency, "#{specifier.inspect} in #{importer_id}")
+          end
+
+          # A "#"-prefixed specifier resolves against the importing package's own
+          # "imports" field, and may land on a file in that package or on another
+          # package entirely.
+          def resolve_private(specifier, dependency, importer_id, context)
+            importer_package, = split_package(importer_id)
+            package_root = package_root_for(importer_package, context)
+            metadata = package_metadata(importer_package, package_root)
+            result = PackageExports.resolve_private(metadata, specifier: specifier, conditions: @conditions)
+            requested = "#{specifier.inspect} in #{importer_id}"
+
+            unless result.resolved?
+              raise ResolveError, "Could not resolve #{requested} (#{result.reason}): #{result.message}"
+            end
+
+            target = result.path
+            return resolve_bare(target, dependency, importer_id, context) unless target.start_with?("./")
+
+            resolved(dependency, importer_package, package_root, target.delete_prefix("./"), requested, probe: true)
+          end
+
+          def resolve_relative(module_id, dependency, context)
+            package_name, subpath = split_package(module_id)
+            package_root = package_root_for(package_name, context)
+
+            resolved(dependency, package_name, package_root, subpath.delete_prefix("./"), module_id, probe: true)
+          end
+
+          def resolve_entry(package_name, package_root, subpath, dependency, requested)
+            metadata = package_metadata(package_name, package_root)
+            result = PackageExports.resolve(metadata, subpath: subpath, conditions: @conditions)
+
+            unless result.resolved?
+              raise ResolveError, "Could not resolve #{requested} (#{result.reason}): #{result.message}"
+            end
+
+            # An "exports" target names an exact file. Only the legacy fields and
+            # bare subpaths of packages without "exports" are probed.
+            resolved(dependency, package_name, package_root, result.path, requested, probe: !metadata.key?("exports"))
+          end
+
+          def resolved(dependency, package_name, package_root, relative_path, requested, probe: false)
+            path = package_root.join(relative_path).expand_path
+            assert_inside_package!(package_root, path, requested)
+
+            found = probe ? probe_path(path) : (path if path.file?)
+
+            unless found
+              raise ResolveError, "Could not resolve #{requested}. #{package_name} has no file at #{relative_path}."
+            end
+
+            assert_inside_package!(package_root, found, requested)
+
+            ResolvedDependency.new(
+              dependency,
+              module_id_for(package_name, found.relative_path_from(package_root).to_s),
+              {scheme: SCHEME, path: found.to_s}
+            )
+          end
+
+          def probe_path(path)
+            return path if path.file?
+
+            CANDIDATE_EXTENSIONS.each do |extension|
+              candidate = Pathname.new("#{path}#{extension}")
+              return candidate if candidate.file?
+            end
+
+            return nil unless path.directory?
+
+            INDEX_BASENAMES.each do |basename|
+              candidate = path.join(basename)
+              return candidate if candidate.file?
+            end
+
+            nil
+          end
+
+          def absolute_path(module_id, context)
+            package_name, subpath = split_package(module_id)
+            package_root = package_root_for(package_name, context)
+            path = package_root.join(subpath.delete_prefix("./")).expand_path
+            assert_inside_package!(package_root, path, module_id)
+
+            path
+          end
+
+          # "npm://gl-matrix/esm/vec3.js" is package "gl-matrix" and subpath
+          # "./esm/vec3.js". Scoped packages put the scope in the authority, so
+          # "npm://@scope/pkg/sub.js" spends its first path segment on the name.
+          def split_package(module_id)
+            host = module_id.host.to_s
+            raise ResolveError, "npm imports need a package name: #{module_id}" if host.empty?
+
+            segments = module_id.relative_path.split("/")
+
+            if host.start_with?("@")
+              scoped_name = segments.shift
+              raise ResolveError, "Scoped npm imports need a package name: #{module_id}" if scoped_name.to_s.empty?
+
+              package_name = "#{host}/#{scoped_name}"
+            else
+              package_name = host
+            end
+
+            [package_name, subpath_for(segments)]
+          end
+
+          # "@scope/pkg/sub.js" is package "@scope/pkg" and subpath "./sub.js".
+          def split_specifier(specifier)
+            segments = specifier.split("/")
+            package_name = segments.shift
+
+            if package_name.start_with?("@")
+              scoped_name = segments.shift
+              raise ResolveError, "Scoped npm imports need a package name: #{specifier}" if scoped_name.to_s.empty?
+
+              package_name = "#{package_name}/#{scoped_name}"
+            end
+
+            [package_name, subpath_for(segments)]
+          end
+
+          def subpath_for(segments)
+            segments.empty? ? "." : "./#{segments.join("/")}"
+          end
+
+          def module_id_for(package_name, relative_path)
+            ModuleId.new("npm://#{package_name}/#{relative_path}")
+          end
+
+          # Node only allows a package to import itself by name when it declares
+          # "exports", because that field is what defines its own entry points.
+          def self_reference_root(package_name, subpath, importer_id, context)
+            package_root = package_root_for(package_name, context)
+
+            unless package_metadata(package_name, package_root).key?("exports")
+              raise ResolveError,
+                "#{importer_id} imports its own package as #{package_name.inspect}, " \
+                "but #{package_name} has no exports field to resolve #{subpath.inspect} against."
+            end
+
+            package_root
+          end
+
+          def transitive_package_root(package_name, importer_package, importer_subpath, importer_id, context)
+            importer_root = package_root_for(importer_package, context)
+            start = importer_root.join(importer_subpath.delete_prefix("./")).dirname
+
+            each_node_modules_directory(start, context) do |directory|
+              candidate = directory.join(package_name)
+              return register_package_root(package_name, candidate) if candidate.directory?
+            end
+
+            raise node_builtin_error(package_name, importer_id) if NODE_BUILTINS.include?(package_name)
+
+            raise ResolveError,
+              "Could not find package #{package_name.inspect} imported by #{importer_id}. " \
+              "Is it a dependency of #{importer_package}?"
+          end
+
+          def node_builtin_error(name, importer_id)
+            ResolveError.new(
+              "#{importer_id} imports the Node builtin #{name.inspect}, which has no browser equivalent. " \
+              "Klenod bundles for the browser, so packages that need Node builtins cannot be used."
+            )
+          end
+
+          # Node's lookup: every parent directory contributes its "node_modules",
+          # nearest first. The configured root is tried last so an explicit root:
+          # still applies when it sits outside the importer's tree.
+          def each_node_modules_directory(start, context)
+            start.ascend do |directory|
+              next if directory.basename.to_s == DIRECTORY_NAME
+
+              candidate = directory.join(DIRECTORY_NAME)
+              yield candidate if candidate.directory?
+            end
+
+            root = node_modules_root(context)
+            yield root if root.directory?
+          end
+
+          def package_root_for(package_name, context)
+            @package_roots[package_name] || root_package_root(package_name, context)
+          end
+
+          def root_package_root(package_name, context)
+            return @package_roots.fetch(package_name) if @package_roots.key?(package_name)
+
+            root = node_modules_root(context)
+            path = root.join(package_name)
+
+            unless path.directory?
+              raise ResolveError, "Could not find package #{package_name.inspect} in #{root}. Is it installed?"
+            end
+
+            register_package_root(package_name, path)
+          end
+
+          # Module IDs carry only a package name, so a name has to mean one
+          # directory. Resolve symlinks first, so pnpm's store and workspace
+          # links are recognised as the same package rather than two copies.
+          def register_package_root(package_name, path)
+            path = path.realpath
+            existing = @package_roots[package_name]
+
+            if existing && existing != path
+              raise ResolveError,
+                "Found two copies of #{package_name.inspect}:\n  #{existing}\n  #{path}\n" \
+                "Klenod can only bundle one copy of a package. Deduplicate it in your lockfile."
+            end
+
+            @package_roots[package_name] = path
+          end
+
+          def package_metadata(package_name, package_root)
+            @package_metadata.fetch(package_name) do
+              path = package_root.join("package.json")
+
+              raise ResolveError, "Package #{package_name.inspect} has no package.json at #{path}." unless path.file?
+
+              @package_metadata[package_name] = JSON.parse(path.read(encoding: "UTF-8"))
+            rescue JSON::ParserError => error
+              raise ResolveError, "Could not parse #{path}: #{error.message}"
+            end
+          end
+
+          def node_modules_root(context)
+            return @root if @root
+
+            @node_modules_root = discover_root(context.source_dir) unless defined?(@node_modules_root)
+
+            @node_modules_root || raise(ResolveError, "Could not find a #{DIRECTORY_NAME} directory above #{context.source_dir}.")
+          end
+
+          def discover_root(source_dir)
+            Pathname.new(source_dir).expand_path.ascend do |directory|
+              candidate = directory.join(DIRECTORY_NAME)
+              return candidate if candidate.directory?
+            end
+
+            nil
+          end
+
+          def assert_inside_package!(package_root, path, requested)
+            prefix = "#{package_root}#{File::SEPARATOR}"
+            return if path.to_s.start_with?(prefix)
+
+            raise ResolveError, "npm import escapes its package: #{requested}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klenod/plugin/javascript/version.rb

@@ -4,7 +4,7 @@ module Klenod
   module Build
     module Plugins
       module JavaScriptPlugin
-        VERSION = "0.0.12"
+        VERSION = "0.0.13"
       end
     end
   end

data/lib/klenod/plugin/javascript.rb

@@ -2,3 +2,4 @@
 
 require "klenod/build"
 require_relative "../build/plugins/javascript_plugin"
+require_relative "../build/plugins/node_modules_plugin"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: klenod-plugin-javascript
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.13
 platform: x86_64-linux-gnu
 authors:
 - Andrés Alin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-08 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: klenod-build
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.12
+        version: 0.0.13
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.12
+        version: 0.0.13
 - !ruby/object:Gem::Dependency
   name: rake-compiler
   requirement: !ruby/object:Gem::Requirement
@@ -47,6 +47,8 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/klenod/build/plugins/javascript_plugin.rb
+- lib/klenod/build/plugins/node_modules_plugin.rb
+- lib/klenod/build/plugins/node_modules_plugin/package_exports.rb
 - lib/klenod/plugin/javascript.rb
 - lib/klenod/plugin/javascript/native.so
 - lib/klenod/plugin/javascript/parser.rb