importmap-plus 1.1.1 → 2.0.0

data/lib/importmap/doctor.rb

@@ -0,0 +1,331 @@
+require "net/http"
+require "uri"
+require "pathname"
+require "active_support/core_ext/array/conversions"
+require "active_support/core_ext/string/inflections"
+require "importmap/http_retries"
+require "importmap/import_scanner"
+require "importmap/integrity"
+require "importmap/module_inspector"
+require "importmap/packager"
+require "importmap/package_graph"
+require "importmap/vendored_graph"
+
+# Everything that can be wrong with an app's import map without anything
+# saying so until a page fails in the browser: a pin whose file isn't there, a
+# vendored file importing a bare specifier nobody pinned, a vendored file that
+# still needs the siblings it was downloaded beside, a CommonJS bundle a CDN
+# handed back, two pins serving one file, a file left in vendor/javascript that
+# nothing maps.
+#
+# It reports; it never fixes. `pin`, `unpin` and `pin --vendor` are what fix
+# things, and a doctor that edited config/importmap.rb would be a doctor nobody
+# could run in CI.
+#
+# Offline by default: every check but the last reads the map, the asset paths
+# and the files on disk. +online+ adds the one check that can't be made without
+# the network — that a remote pin is still served, and still serves the bytes
+# its integrity hash was computed from.
+class Importmap::Doctor
+  include Importmap::HttpRetries
+
+  Error     = Class.new(StandardError)
+  HTTPError = Class.new(Error)
+
+  # Wide enough for "warning" plus the space that separates every level from
+  # its message, so the messages line up under each other.
+  LEVEL_WIDTH = 8 # :nodoc:
+
+  Finding = Struct.new(:level, :message) do # :nodoc:
+    def to_s
+      "#{level.to_s.ljust(LEVEL_WIDTH)} #{message}"
+    end
+  end
+
+  # +path+ is the logical asset path or the URL the key maps to, +file+ the
+  # file on disk that serves it, or nil when no asset path holds one.
+  Entry = Struct.new(:name, :path, :integrity, :file, keyword_init: true) # :nodoc:
+
+  # Where `pin --vendor` and a vendored graph write, and so the only directory
+  # whose contents this gem is entitled to have an opinion about.
+  VENDOR_PATH = "vendor/javascript".freeze # :nodoc:
+
+  # Importmap::Map's directory glob is `**/*.js{,m}` — .js and .jsm, not .mjs.
+  # This one takes .mjs too, on purpose: a .mjs under a pin_all_from directory
+  # is precisely the file the map can never see, and saying so is the point.
+  VENDORED_GLOB = "**/*.{js,jsm,mjs}".freeze # :nodoc:
+
+  # A specifier the import map has to define. Anything the browser resolves
+  # against the importing file's own URL, or fetches outright, is not one.
+  SCHEME_REGEXP = %r{\A[a-zA-Z][a-zA-Z0-9+\-.]*:}.freeze # :nodoc:
+
+  def initialize(importmap:, resolver:, root:, asset_paths: [], online: false)
+    @importmap   = importmap
+    @resolver    = resolver
+    @root        = Pathname.new(root)
+    @asset_paths = Array(asset_paths).map { |path| Pathname.new(path) }
+    @online      = online
+  end
+
+  # Every finding, errors before warnings within each check and the checks in
+  # the order they are defined below.
+  def diagnose
+    @diagnose ||= [
+      *unresolvable_pins,
+      *unpinned_specifiers,
+      *stray_relative_imports,
+      *non_modules,
+      *unserved_vendored_files,
+      *keys_sharing_a_path,
+      *packages_vendored_twice,
+      *(@online ? unreachable_remote_pins : [])
+    ]
+  end
+
+  def errors?
+    diagnose.any? { |finding| finding.level == :error }
+  end
+
+  def summary
+    errors, warnings = diagnose.partition { |finding| finding.level == :error }
+
+    "#{errors.size} #{"error".pluralize(errors.size)}, #{warnings.size} #{"warning".pluralize(warnings.size)}"
+  end
+
+  private
+    def unresolvable_pins
+      entries.reject { |entry| remote?(entry.path) }.filter_map do |entry|
+        error(%(pin "#{entry.name}" → #{entry.path}: no such asset)) unless resolves?(entry.path)
+      end
+    end
+
+    def unpinned_specifiers
+      scannable.flat_map do |entry|
+        imports_in(entry.file).filter_map do |import|
+          next unless bare?(import.specifier)
+          next if pinned?(import.specifier)
+
+          error(%(#{relative(entry.file)} imports "#{import.specifier}", which isn't pinned))
+        end
+      end
+    end
+
+    # A vendored file's relative imports were rewritten to the keys of the
+    # files vendored beside it, so one left over points at a file that isn't
+    # there: the download predates the fork learning to vendor a file graph, or
+    # the graph directory has since been removed.
+    def stray_relative_imports
+      vendored.flat_map do |entry|
+        imports_in(entry.file).filter_map do |import|
+          next unless relative?(import.specifier)
+          next if sibling_of(entry.file, import.specifier)&.file?
+
+          error(%(#{relative(entry.file)} imports "#{import.specifier}" by relative path — ) +
+                %(run bin/importmap pin #{vendored_package_of(entry.file) || entry.name} to vendor its files))
+        end
+      end
+    end
+
+    def non_modules
+      vendored.filter_map do |entry|
+        next if Importmap::ModuleInspector.new(source_of(entry.file)).es_module?
+
+        error("#{relative(entry.file)} isn't an ES module")
+      end
+    end
+
+    def unserved_vendored_files
+      (vendored_files - entries.filter_map(&:file)).map do |file|
+        warning("#{relative(file)} isn't pinned by anything")
+      end
+    end
+
+    # Two keys on one file are two modules in the browser, each with its own
+    # state, and whichever one a package imports is the one the other half of
+    # the app isn't using.
+    def keys_sharing_a_path
+      entries.group_by(&:path).filter_map do |path, sharing|
+        next unless sharing.size > 1
+
+        names = sharing.map { |entry| %("#{entry.name}") }
+        warning("#{names.to_sentence} #{all_or_both(names)} resolve to #{path}")
+      end
+    end
+
+    def packages_vendored_twice
+      vendored_versions.group_by { |_file, package, _version| package }.filter_map do |package, group|
+        versions = group.map { |_file, _package, version| version }
+        next if versions.uniq.size < 2
+
+        files = group.map { |file, _package, _version| relative(file) }
+        warning("#{files.to_sentence} #{all_or_both(files)} vendor #{package}, at #{versions.to_sentence}")
+      end
+    end
+
+    def unreachable_remote_pins
+      entries.select { |entry| remote?(entry.path) }.filter_map { |entry| remote_finding_for(entry) }
+    end
+
+    def remote_finding_for(entry)
+      response = with_retries("fetching #{entry.path}") { Net::HTTP.get_response(URI(entry.path)) }
+
+      if response.code != "200"
+        error(%(pin "#{entry.name}" → #{entry.path}: the CDN answered #{response.code}))
+      elsif Importmap::Integrity.hash?(entry.integrity) && entry.integrity != Importmap::Integrity.for(response.body)
+        error(%(pin "#{entry.name}" → #{entry.path}: integrity doesn't match what the CDN served))
+      end
+    rescue HTTPError => e
+      # The reason with_retries gives already names the URL, so the finding
+      # doesn't name it a second time.
+      error(%(pin "#{entry.name}": #{e.message}))
+    end
+
+    def entries
+      @entries ||= @importmap.each_expanded_package.map do |name, mapping|
+        Entry.new(name: name, path: mapping.path, integrity: mapping.integrity, file: file_for(mapping.path))
+      end
+    end
+
+    # The files this gem may read: the app's own, not a file an engine serves
+    # out of its gem, which no `bin/importmap` command can do anything about.
+    # One file serving two keys is scanned once.
+    def scannable
+      @scannable ||= entries.select { |entry| entry.file && under?(entry.file, @root) }.uniq(&:file)
+    end
+
+    def vendored
+      @vendored ||= scannable.select { |entry| under?(entry.file, @root.join(VENDOR_PATH)) }
+    end
+
+    def vendored_files
+      @vendored_files ||= Pathname.glob(@root.join(VENDOR_PATH, VENDORED_GLOB)).select(&:file?).sort
+    end
+
+    # The package and version every vendored file's header names, read out of
+    # the CDN URL it was downloaded from — the npm identity, which is what says
+    # two pins hold one package, rather than the key, which is whatever the app
+    # typed. A file with no header, or from a CDN whose URLs don't spell the
+    # package out, simply isn't in the answer.
+    def vendored_versions
+      @vendored_versions ||= vendored_files.filter_map do |file|
+        url = header_url_of(file)
+        package, version = Importmap::PackageGraph.package_and_version_for(url) if url
+
+        [ file, package, version ] if package && version
+      end
+    end
+
+    # The files a graph vendored carry no header of their own — the entry they
+    # were downloaded beside does, and Importmap::Packager names their
+    # directory after that entry's file. So a sibling asks the entry what
+    # package it belongs to, and the hint names something `bin/importmap pin`
+    # can act on rather than the key of the one file that went missing.
+    def vendored_package_of(file)
+      vendored_packages[file] || vendored_packages[graph_entry_for(file)]
+    end
+
+    def vendored_packages
+      @vendored_packages ||= vendored_versions.to_h { |file, package, _version| [ file, package ] }
+    end
+
+    def graph_entry_for(file)
+      segments = file.relative_path_from(@root.join(VENDOR_PATH)).each_filename.to_a
+      return if segments.size < 2
+
+      @root.join(VENDOR_PATH, "#{segments.first}.js")
+    end
+
+    def header_url_of(file)
+      File.open(file, "rb") { |io| io.gets.to_s }[Importmap::VendoredGraph::DOWNLOADED_FROM_REGEXP, 1]
+    end
+
+    def file_for(path)
+      return if remote?(path)
+
+      @asset_paths.lazy.map { |root| root.join(path) }.find(&:file?)
+    end
+
+    def resolves?(path)
+      @resolver.path_to_asset(path)
+      true
+    rescue => error
+      raise error unless rescuable_asset_error?(error)
+
+      false
+    end
+
+    # The same list Importmap::Map rescues on the request path, so a pin the
+    # map would quietly skip is the pin this reports.
+    def rescuable_asset_error?(error)
+      Rails.application.config.importmap.rescuable_asset_errors.any? { |klass| error.is_a?(klass) }
+    end
+
+    def imports_in(file)
+      Importmap::ImportScanner.new(source_of(file)).imports
+    end
+
+    # Read as bytes and scrubbed: a vendored file this gem didn't write, or
+    # wrote before it learned to ask CDNs for a body it can read, can hold a
+    # sequence no UTF-8 regexp will match without raising, and one such file
+    # must not stop every other check.
+    def source_of(file)
+      @sources ||= {}
+      @sources[file] ||= File.binread(file).force_encoding(Encoding::UTF_8).scrub
+    end
+
+    # A specifier the map resolves: a key it defines outright, a key ending in
+    # "/" that covers everything under it, or — leniently — a key the specifier
+    # is a subpath of. That last one is not what a browser does, which needs
+    # the trailing-slash key. It is here because the alternative is an error on
+    # every subpath of every package vendored with its file graph, whose keys
+    # this gem writes one by one, and a check that cries wolf is a check nobody
+    # runs. A missed subpath still fails in the browser exactly as loudly as it
+    # did before anyone ran the doctor.
+    def pinned?(specifier)
+      keys.any? do |key|
+        key == specifier || (key.end_with?("/") ? specifier.start_with?(key) : specifier.start_with?("#{key}/"))
+      end
+    end
+
+    def keys
+      @keys ||= entries.map(&:name)
+    end
+
+    def bare?(specifier)
+      !specifier.empty? && !relative?(specifier) && !specifier.start_with?("/") && !specifier.match?(SCHEME_REGEXP)
+    end
+
+    def relative?(specifier)
+      specifier.start_with?("./", "../")
+    end
+
+    def remote?(path)
+      path.match?(Importmap::Packager::REMOTE_URL_REGEXP)
+    end
+
+    def sibling_of(file, specifier)
+      file.dirname.join(specifier.sub(/[?#].*\z/, ""))
+    rescue ArgumentError
+      nil
+    end
+
+    def under?(file, directory)
+      file.to_s.start_with?("#{directory}/")
+    end
+
+    def relative(file)
+      file.relative_path_from(@root)
+    end
+
+    def all_or_both(items)
+      items.size > 2 ? "all" : "both"
+    end
+
+    def error(message)
+      Finding.new(:error, message)
+    end
+
+    def warning(message)
+      Finding.new(:warning, message)
+    end
+end

data/lib/importmap/early_hints.rb

@@ -0,0 +1,50 @@
+# The modulepreload links of javascript_importmap_tags, sent ahead of the
+# response as 103 Early Hints.
+#
+# A link in the body can only be acted on once the browser has parsed that far
+# into the HTML, so the whole module graph waits on the response. The same list
+# sent as a Link header before the response starts lets the fetches begin while
+# the app is still rendering — which is what Rails' own javascript_include_tag
+# and stylesheet_link_tag already do for their assets.
+#
+# `request.send_early_hints` is `env["rack.early_hints"]&.call(links)`: a no-op
+# unless the server put the callable there (Puma does with `early_hints true`),
+# so on a server without it this costs one joined string and nothing else.
+module Importmap::EarlyHints
+  class << self
+    # `view` is the view rendering the tags — the request and response are read
+    # off it the way ActionView's own send_preload_links_header reads them, so a
+    # context that has neither is left alone. `packages` is a
+    # preloaded_module_packages hash, resolved asset path to the package behind
+    # it, which makes the hinted set exactly the tags' set.
+    def send_modulepreload_links(view, packages)
+      return if packages.empty? || !enabled? || sending?(view)
+
+      request = view.request if view.respond_to?(:request)
+      return unless request.respond_to?(:send_early_hints)
+
+      request.send_early_hints("link" => link_header_for(packages.keys))
+    end
+
+    private
+      # No integrity parameter: browsers don't honour one on a Link header, and
+      # the modulepreload tag in the body still carries it, which is where the
+      # hash has to match anyway.
+      def link_header_for(paths)
+        paths.collect { |path| "<#{path}>; rel=modulepreload" }.join(", ")
+      end
+
+      # A 103 is a response of its own, written to the socket before the real
+      # one. Under `render stream: true` the layout renders while the 200 is
+      # already going out, and a hint sent then lands in the middle of the body.
+      def sending?(view)
+        return false unless view.respond_to?(:response)
+
+        (response = view.response).respond_to?(:sending?) && response.sending?
+      end
+
+      def enabled?
+        Rails.application.config.importmap.early_hints
+      end
+  end
+end

data/lib/importmap/engine.rb

@@ -1,4 +1,5 @@
 require "importmap/map"
+require "importmap/early_hints"
 
 # Use Rails.application.importmap to access the map
 Rails::Application.send(:attr_accessor, :importmap)
@@ -10,6 +11,8 @@ module Importmap
     config.importmap.sweep_cache = Rails.env.development? || Rails.env.test?
     config.importmap.cache_sweepers = []
     config.importmap.rescuable_asset_errors = []
+    config.importmap.preload_strategy = :all
+    config.importmap.early_hints = true
 
     config.autoload_once_paths = %W( #{root}/app/helpers #{root}/app/controllers )
 

data/lib/importmap/esm_run.rb

@@ -0,0 +1,118 @@
+require "uri"
+require "json"
+
+# Everything this gem knows about jsDelivr's bundling endpoint
+# (https://www.jsdelivr.com/esm): one minified ESM file per package, with its
+# dependencies referenced as /npm/dep@ver/+esm.
+#
+# It is the one provider whose URLs a CDN host can't identify — an esm.run
+# bundle and a plain jsDelivr file are both served from cdn.jsdelivr.net — and
+# the one whose downloads have to be rewritten before they can be vendored, so
+# both facts live here rather than in Importmap::Packager, which asks this
+# class the two questions it has: is this that provider, and is this one of its
+# URLs.
+#
+# Nothing here writes a file or reads config/importmap.rb. The version lookup
+# is the one request, and it goes out through the Packager so a jsDelivr that
+# rate-limits or resets gets the same bounded retries as every other request
+# this gem makes, and fails as the same Importmap::Packager::HTTPError.
+class Importmap::EsmRun
+  PROVIDER   = "esm.run".freeze # :nodoc:
+  CDN        = "https://cdn.jsdelivr.net/npm/".freeze # :nodoc:
+  URL_REGEXP = %r{\Ahttps://cdn\.jsdelivr\.net/npm/.+/\+esm\z}.freeze # :nodoc:
+  # A bundle's own imports: `from"/npm/dep@1.2.3/+esm"`, `import"…"`,
+  # `import("…")`, `export … from"…"`. Anchored on the keyword so an ordinary
+  # string that happens to look like a bundle URL is left alone. What it does
+  # not do is parse JavaScript, so the same text inside a string or a comment
+  # would still be rewritten — a jsDelivr bundle is esbuild output whose only
+  # surviving comment is the banner, and a root-relative /npm/ URL is
+  # meaningless anywhere but in one of its own imports.
+  IMPORT_REGEXP =
+    %r{((?:\bfrom|\bimport)\s*\(?\s*)(["'])/npm/((?:@[^/"'@]+/)?[^/"'@]+)@([^/"']+)((?:/[^"']*?)?)/\+esm\2}.freeze # :nodoc:
+
+  # The jsDelivr data API versions are resolved through. Also readable and
+  # writable as Importmap::Packager.esm_run_resolver, which is where an app
+  # that points this at a mirror has always set it.
+  singleton_class.attr_accessor :resolver
+  self.resolver = URI("https://data.jsdelivr.com/v1/packages/npm/")
+
+  class << self
+    def provider?(provider)
+      provider.to_s == PROVIDER
+    end
+
+    def url?(url)
+      url.to_s.match?(URL_REGEXP)
+    end
+
+    def url_for(name, version, subpath = nil)
+      "#{CDN}#{name}@#{version}#{subpath}/+esm"
+    end
+
+    # Turns import "/npm/dep@1.2.3/+esm" into import "dep" so the bundle
+    # resolves through the import map, and lists what it needs pinned as
+    # [ [ package, url ], … ].
+    def rewrite_imports(source)
+      dependencies = {}
+      versions = Hash.new { |hash, key| hash[key] = [] }
+
+      rewritten = source.gsub(IMPORT_REGEXP) do
+        keyword, quote, name, version, subpath = $1, $2, $3, $4, $5.to_s
+        key = "#{name}#{subpath}"
+        dependencies[key] ||= url_for(name, version, subpath)
+        versions[key] << version unless versions[key].include?(version)
+        "#{keyword}#{quote}#{name}#{subpath}#{quote}"
+      end
+
+      warn_about_conflicting_versions(versions)
+
+      [ rewritten, dependencies.to_a ]
+    end
+
+    private
+      # An import map maps a bare specifier to one file, so a bundle that
+      # imports the same package at two versions can only get the first one it
+      # asked for. Say so rather than pick silently.
+      def warn_about_conflicting_versions(versions)
+        versions.each do |key, seen|
+          next if seen.one?
+
+          warn %(#{key} is imported at #{seen.join(", ")} by this bundle; pinning @#{seen.first}, an import map holds one version)
+        end
+      end
+  end
+
+  def initialize(packager)
+    @packager = packager
+  end
+
+  # The import map Importmap::Packager#import answers with, built from the
+  # version jsDelivr resolves each spec to; nil when it hasn't got one of them,
+  # because a bundle URL for a version nobody published is a 404 at download.
+  def imports(specs)
+    imports = Array(specs).to_h do |spec|
+      name, requested, subpath = spec.to_s.match(Importmap::Packager::PACKAGE_SPEC_REGEXP)&.captures
+      raise Importmap::Packager::Error, "Can't parse package spec #{spec.inspect}" unless name
+
+      version = resolve_version(name, requested)
+      return nil unless version
+
+      [ "#{name}#{subpath}", self.class.url_for(name, version, subpath) ]
+    end
+
+    { imports: imports }
+  end
+
+  private
+    def resolve_version(name, requested)
+      uri = self.class.resolver.dup
+      uri.path += "#{name}/resolved"
+      uri.query = "specifier=#{URI.encode_www_form_component(requested)}" if requested
+
+      body = @packager.fetch_remote(uri, allow_missing: true, description: "resolving #{uri}")
+
+      body && JSON.parse(body)["version"]
+    rescue JSON::ParserError
+      raise Importmap::Packager::HTTPError, "Unexpected response from #{uri}"
+    end
+end

data/lib/importmap/graph.rb

@@ -0,0 +1,126 @@
+require "pathname"
+require "set"
+require "importmap/import_scanner"
+
+# Which pins an entry point actually reaches, read out of the files the map
+# already lists. An import map says what every key resolves to; it says nothing
+# about which keys a given page loads, and so `preload: true` preloads
+# everything on every page. The graph is the missing half: `application.js`
+# imports some of the map, those files import more of it, and the rest is only
+# ever reached through `import()` — or not at all.
+#
+# Static imports only. A dynamic `import()` is the app saying "later", and
+# preloading its target undoes the deferral the app asked for. That makes this
+# a walk of what the browser fetches while linking the entry point, which is
+# exactly what a modulepreload link is for.
+#
+# Nothing here reaches the network. The files are the ones the asset pipeline
+# already serves, read once per Map cache generation and dropped with the rest
+# of the cache when the sweeper sees a .js change.
+class Importmap::Graph
+  # A path the browser fetches itself rather than one the asset pipeline
+  # serves — `https://…`, and the protocol-relative `//…` a hand-written pin
+  # can hold. Importmap::Packager::REMOTE_URL_REGEXP says the same thing, but
+  # requiring the CLI onto the request path to borrow it would be a poor trade.
+  REMOTE_PATH_REGEXP = %r{\A(?:[a-zA-Z][a-zA-Z0-9+\-.]*:)?//}.freeze # :nodoc:
+
+  def initialize(map, roots: [])
+    @map   = map
+    @roots = Array(roots).map { |root| Pathname.new(root) }
+  end
+
+  # The keys reachable from +entry_points+ through static imports, the entry
+  # points themselves included. An entry point the map doesn't define, a pin
+  # whose file isn't on any asset path and a remote pin are all leaves: they
+  # contribute themselves and nothing further.
+  def reachable_from(entry_points)
+    queue   = Array(entry_points).select { |key| entries.key?(key) }
+    reached = Set.new(queue)
+
+    while (key = queue.shift)
+      edges_from(key).each { |target| queue << target if reached.add?(target) }
+    end
+
+    reached
+  end
+
+  private
+    def entries
+      @entries ||= @map.each_expanded_package.to_h
+    end
+
+    # The key a path belongs to, for resolving a relative import back into the
+    # map. Two keys can name one file; the first one drawn wins, and since both
+    # resolve to the same asset path the preload set can't tell them apart
+    # anyway.
+    def keys_by_path
+      @keys_by_path ||= entries.each_with_object({}) { |(key, mapping), keys| keys[mapping.path] ||= key }
+    end
+
+    def edges_from(key)
+      @edges ||= {}
+      @edges[key] ||= compute_edges(entries[key])
+    end
+
+    def compute_edges(mapping)
+      file = file_for(mapping.path)
+      return [] unless file
+
+      Importmap::ImportScanner.new(source_of(file)).imports.filter_map { |import|
+        key_for(import.specifier, mapping.path) if import.kind == :static
+      }.uniq
+    end
+
+    def file_for(path)
+      return if path.match?(REMOTE_PATH_REGEXP)
+
+      @roots.lazy.map { |root| root.join(path) }.find(&:file?)
+    end
+
+    # Read as bytes and scrubbed, like Importmap::Doctor: a vendored file this
+    # gem didn't write can hold a sequence no UTF-8 regexp will match without
+    # raising, and one such file must not take a page's preloads with it.
+    def source_of(file)
+      File.binread(file).force_encoding(Encoding::UTF_8).scrub
+    end
+
+    # A relative specifier is resolved against the importing key's own path and
+    # matched back to the key holding that path — the browser resolves it
+    # against the importing module's URL, and the map's paths are what those
+    # URLs are built from. Anything else names a key outright, a path a key
+    # maps to, or a subpath of a package pinned as one file.
+    def key_for(specifier, importer_path)
+      return if specifier.empty?
+
+      if relative?(specifier)
+        keys_by_path[resolved_path(specifier, importer_path)]
+      else
+        exact_key(specifier) || enclosing_key(specifier)
+      end
+    end
+
+    def relative?(specifier)
+      specifier.start_with?("./", "../")
+    end
+
+    def resolved_path(specifier, importer_path)
+      Pathname.new(importer_path).dirname.join(specifier.sub(/[?#].*\z/, "")).cleanpath.to_s
+    rescue ArgumentError
+      nil
+    end
+
+    def exact_key(specifier)
+      entries.key?(specifier) ? specifier : keys_by_path[specifier]
+    end
+
+    # `pin "foo/", to: "foo/"` covers everything under it, and a subpath of a
+    # package pinned as one file — which the browser can't resolve, and
+    # Importmap::Doctor reports — is counted as reaching that package, because
+    # preloading one file too many costs a request and preloading one too few
+    # costs the waterfall this whole mechanism exists to avoid.
+    def enclosing_key(specifier)
+      entries.keys.select { |key|
+        key.end_with?("/") ? specifier.start_with?(key) : specifier.start_with?("#{key}/")
+      }.max_by(&:length)
+    end
+end