importmap-plus 1.1.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c325b5de05deaf38ca9ed4f671d5c676b36f726ab4e3079e616dc964bdac00b8
-  data.tar.gz: c11ca96640558bf7e4f3e294139ed80b9a893239811e4afa879024268401c90d
+  metadata.gz: 1d0e4b656e7047b77938a8b92681f72ec7af73034c2c94517ef2ff37d725b76d
+  data.tar.gz: 9a83c644e76fab4892e074ea8f254877b4351c55b071294f4edd3c965167054f
 SHA512:
-  metadata.gz: a69a963a3506522598a3b0cecb6c8b95c7e4dd275a2fe1cf748f7f5b181bbae62f490f22dc066b42adaf0071dc54e24d940309b2b31ee4b971365aec89ff8a68
-  data.tar.gz: 3ff45f8c8e2ca16ef2f26d4d18438a870bcf50a12c63f29b44a58bf334a9404e3009f4544201f81d1fe7e2f862cad5e15858af5b05a14d7fb97894f2ef972638
+  metadata.gz: 39c36fbd0719746f4ca30e21632731f1d91ebc4e524132c2592b2d0a1432315cf8e2d3e7b70fffa935cbc4d3135a14d561dd86d52c6de3a18fd41030f91209a1
+  data.tar.gz: c9eaf6a0f2b07be30f46487d07ffa17ebaa538efd443d23d677fd8e95509b4d50b193162a136dec8d9d6888b5414cbfe7b832d0929b0d0f9d6373de35ad2f0bf

data/CHANGELOG.md

@@ -1,5 +1,370 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+
+- **`bin/importmap doctor` no longer reports comments and prose as unpinned
+  imports.** The import scanner read `from "…"` and `import "…"` wherever the
+  text appeared, so a line comment such as `// e.g. 'en' from 'en-US'` and
+  strings such as turbo_power's `` `…provided in the "from" attribute for
+  the "…` `` came back as `error … imports " attribute for the ", which isn't
+  pinned`. Line comments are now discounted before scanning (strings and
+  regex literals are still consumed whole, so `"https://…"` is safe), and a
+  quoted text that can't be a module specifier — whitespace, a backtick, a
+  `${` interpolation, or no word character at all — is not reported.
+
+## 1.2.0
+
+### Added
+
+- **`pin` resolves the version on the npm registry, then falls back from jspm
+  to esm.run to jsDelivr.** jspm is the default CDN and was the only one `pin`
+  asked, so a package its generator can't build — `mermaid@10.6.0` fails on a
+  cytoscape subpath, `@mui/material@5.15.0` on a module it can't find — ended
+  in `Couldn't find any packages`, and a bare `pin foo` took whatever version
+  jspm had indexed, which lags npm. A package that names no CDN of its own is
+  now asked of each in turn, and its version is settled against the registry
+  before any of them is asked:
+
+  ```
+  $ bin/importmap pin mermaid
+  Resolved "mermaid" to 10.6.0 from the npm registry
+  jspm couldn't resolve "mermaid@10.6.0" (No './dist/cytoscape.umd.js' exports subpath defined in cytoscape@3.34.3); trying esm.run
+  Pinning "mermaid" to vendor/javascript/mermaid.js via download from https://cdn.jsdelivr.net/npm/mermaid@10.6.0/+esm
+  ```
+  ```ruby
+  pin "mermaid" # @10.6.0 (esm.run)
+  ```
+
+  The pin comment already records a CDN that isn't jspm, so `update` and
+  `pristine` stay on esm.run from then on with no new state anywhere. An
+  explicit `--from`, and a provider a pin already names, are choices somebody
+  made: those are asked once and never fall back. When no CDN has the package,
+  each one's reason is printed and the summary names all three.
+- **A download that isn't an ES module is kept remote instead of vendored.**
+  The CDNs that serve a package's own `dist` file hand back the UMD bundle
+  plenty of packages still publish; vendored into an import map it runs and
+  exports nothing, so `import x from "pkg"` fails to link in the browser and
+  nowhere else. `pin google-libphonenumber --from jsdelivr` now keeps the pin
+  remote and records `(remote: not an ES module)`. `--vendor` downloads it
+  anyway, and the default `pin` never sees it, since jspm converts the package.
+- **The CDN's own reason reaches the terminal.** jspm answers 401 with its
+  generator's message in the body, which `pin` discarded: `Couldn't find any
+  packages in ["mermaid@10.6.0"] on jspm` said nothing about what went wrong.
+  That message is now printed with the sentence, whichever CDN was asked.
+
+- **`pin` keeps a package remote when its file can't stand alone, and says
+  why.** A vendored package is one file served under a digested asset path,
+  but plenty of packages ship a file that imports a sibling by relative path,
+  spawns a `Worker`, reads `import.meta.url` or fetches a `.wasm` binary —
+  every one of those 404s in the browser, and importmap-rails vendors it
+  anyway. `pin` now reads the download before writing anything to
+  `vendor/javascript`; a file that needs more than itself is pinned to its CDN
+  URL and the reason goes on the pin:
+
+  ```
+  $ bin/importmap pin fflate@0.8.2
+  Pinning "fflate" to https://ga.jspm.io/npm:fflate@0.8.2/esm/browser.js (kept remote: workers)
+  ```
+  ```ruby
+  pin "fflate", to: "https://ga.jspm.io/npm:fflate@0.8.2/esm/browser.js" # @0.8.2 (remote: workers)
+  ```
+
+  The pin then behaves like any other remote pin — `pin` and `update`
+  re-resolve it from the same CDN and keep the reason, `pristine` skips it.
+  `pin --vendor` downloads the package anyway and records `(vendored)` on the
+  pin, so a later `update` doesn't undo the override; it also converts a pin
+  that was kept remote back to a download. Nothing an app already vendored is
+  rewritten on its own — `pristine` redownloads those pins as it always has —
+  but the next `pin` or `update` that touches one re-resolves it, and a package
+  whose file can't stand alone converts to a remote pin then. That is the fix
+  arriving, not a surprise: the vendored file it replaces was already 404ing
+  for its siblings. pdf.js is the package most apps will see this on — see
+  the upgrading page for what to expect and how `--vendor` puts it back.
+
+- **A pin that stays remote carries a subresource-integrity hash.** A vendored
+  file is served by the app; a remote pin is fetched from a CDN on every page
+  load with nothing checking the bytes, and importmap-rails never wrote an
+  `integrity:` value for one — the hash had to be computed by hand and redone
+  on every update. `pin --remote`, and a package [kept remote] because its file
+  can't stand alone, now fetch the URL they just resolved, hash it and write it
+  with the pin:
+
+  ```
+  $ bin/importmap pin md5@2.2.0 --remote
+  Pinning "md5" to https://ga.jspm.io/npm:md5@2.2.0/md5.js (integrity sha384-+wqk6m3DPZ6mVMgVZlXnGgDjDY2skGEZ3U9tBnRHiPJXLRLKBmYkKlX2urz9T61b)
+  ```
+  ```ruby
+  pin "md5", to: "https://ga.jspm.io/npm:md5@2.2.0/md5.js", integrity: "sha384-+wqk6m3DPZ6mVMgVZlXnGgDjDY2skGEZ3U9tBnRHiPJXLRLKBmYkKlX2urz9T61b"
+  ```
+
+  The hash is `sha384` of the bytes the CDN served, computed here rather than
+  asked of any one CDN, so jspm, esm.run, jsDelivr, unpkg, esm.sh and skypack
+  are all covered by one code path. `update` and a later `pin` fetch the new
+  URL and rewrite the hash, so a pin never carries the hash of a file it no
+  longer points at — where before an explicit hash was simply dropped.
+  `enable_integrity!` in `config/importmap.rb` is still what puts the value in
+  the import map and on the preload link; `--no-integrity` skips the fetch for
+  a run, and `integrity: false` on a pin stays off for good. Vendored downloads
+  are unaffected: `integrity: true`, the default, already computes theirs
+  through the asset pipeline.
+
+  [kept remote]: https://importmap-plus.zoolutions.llc/docs/pinning
+
+- **`pin` vendors a package's whole file graph, so a chunked package no longer
+  needs a CDN at runtime.** A package whose entry imports a sibling by relative
+  path — `@popperjs/core`, `date-fns`, `lodash-es`, and every package built by
+  a bundler that splits chunks — could not be vendored: the browser resolves
+  `./enums.js` against a digested asset path, and neither Propshaft nor
+  Sprockets rewrites `import` statements. Those packages were [kept remote].
+  `pin` now downloads the closed set of files the entry reaches, rewrites every
+  relative specifier to a bare key, and maps the directory with one
+  `pin_all_from` line:
+
+  ```
+  $ bin/importmap pin @popperjs/core@2.11.8
+  Pinning "@popperjs/core" to vendor/javascript/@popperjs/core.js via download from https://ga.jspm.io/npm:@popperjs/core@2.11.8/lib/index.js (with 47 sibling files)
+  ```
+  ```ruby
+  pin "@popperjs/core", to: "@popperjs--core.js" # @2.11.8
+  pin_all_from "vendor/javascript/@popperjs--core", under: "@popperjs/core", to: "@popperjs--core" # @2.11.8 (graph of @popperjs/core)
+  ```
+
+  The entry keeps the flat file and the plain comment it always had, so
+  `update`, `outdated`, `lock` and `pristine` read it exactly as before, and a
+  `config/importmap.rb` written this way still parses under importmap-rails.
+  Bare specifiers are untouched, and a file that is another pin's own entry is
+  rewritten to that pin's key rather than copied, so the browser evaluates each
+  module once. (Two pins of one package do each carry their own copy of a chunk
+  they share; both write it under the same key, so one of the copies is what
+  every importer gets and the other is dead weight.) `unpin` takes the directory and the line with the pin,
+  `pristine` rebuilds the directory, `pin --minify` minifies every file in it,
+  and `pin --vendor` downloads the entry on its own and drops the directory and
+  line it had. A directory the import map doesn't map as one of ours is the
+  app's: `pin` says so, writes nothing rather than renaming it away, and exits
+  non-zero — as it does when a CDN fails partway through a crawl, where the pin
+  and the files it had are left exactly as they were.
+
+  Only jspm, jsDelivr and unpkg are crawled — their URLs say where a package's
+  directory ends. A graph that can't be taken over whole (a relative path that
+  climbs out of the package, a sibling the CDN hasn't got, a sibling that isn't
+  JavaScript, two files that would collapse to one key) keeps the whole package
+  remote, as does a download that also spawns a worker, reads
+  `import.meta.url`, computes an `import()` or names a `.wasm` file. A pin
+  importmap-plus had kept remote for its relative imports is converted back to
+  a download by the next `pin` or `update`, on the CDN its URL names.
+
+  Two things `pin` says out loud rather than doing quietly: a key some other
+  package's graph already maps (a directory wins over a pin, so the pin would
+  do nothing), and a second directory mapping a package one already maps at
+  another version (a file they share resolves to one of them).
+
+- **`bin/importmap doctor` checks an app's import map and vendored files,
+  offline.** `audit` and `outdated` ask the npm registry about your packages;
+  nothing asked whether the map still matched the files in the repo. A pin
+  whose file had gone missing, a vendored file importing a bare specifier
+  nobody pinned, a vendored file still importing the siblings it was downloaded
+  beside, a CommonJS bundle a CDN handed back — each of those said so in the
+  browser and nowhere else. `doctor` boots the app and reports them:
+
+  ```
+  $ bin/importmap doctor
+  error    pin "not_there" → nowhere.js: no such asset
+  error    vendor/javascript/shoelace.js imports "lit/decorators.js", which isn't pinned
+  error    vendor/javascript/popper.js imports "./enums.js" by relative path — run bin/importmap pin @popperjs/core to vendor its files
+  warning  vendor/javascript/old-lib.js isn't pinned by anything
+  warning  "@hotwired/turbo" and "@hotwired/turbo-rails" both resolve to turbo.min.js
+  3 errors, 2 warnings
+  ```
+
+  Errors exit 1, so it belongs in CI beside `audit` and `outdated`; warnings —
+  a file nothing serves, including a `.mjs` that `pin_all_from` never picks up,
+  and two keys on one file or one package vendored at two versions — leave the
+  exit status alone. It reports and never edits: `pin`, `unpin` and `pristine`
+  are what fix what it finds.
+
+  `--online` adds the one check that needs the network, fetching every remote
+  pin to report one the CDN no longer serves and an `integrity:` hash that
+  doesn't match the bytes it does serve. Every other check reads only the map,
+  the asset paths and the files on disk, so the default is fast and can't fail
+  because a CDN is having a bad afternoon.
+
+- **`config.importmap.preload_strategy = :reachable` preloads what the entry
+  point actually reaches.** Every pin with `preload: true` gets a modulepreload
+  link on every page, so a package the app only loads with `import()` is
+  fetched up front anyway unless someone writes `preload: false` on it — and on
+  everything it depends on, and keeps that list right as the package changes.
+  An app on this gem carried the comment "imported only by apexcharts.js, which
+  is itself lazy. Without it, 1.1 MB was preloaded on every page."
+
+  The import graph already knows. `app/javascript`, `vendor/javascript` and
+  every `pin_all_from` directory are files on disk, and their `import`
+  statements name pin keys:
+
+  ```ruby
+  # config/application.rb
+  config.importmap.preload_strategy = :reachable
+  ```
+
+  `javascript_importmap_tags "application"` now emits a link only for the pins
+  `application` reaches through **static** imports, however deep. A dynamic
+  `import()` is the lazy boundary and contributes nothing — preloading its
+  target is the deferral the app asked for, undone. A pin naming an entry point
+  (`preload: "admin"`) is preloaded whether or not the graph reaches it, which
+  is the escape hatch for a specifier no regex can see; `preload: false` stays
+  off either way.
+
+  Nothing new happens on the request path: the files are the ones the asset
+  pipeline already serves, read once per import map cache generation and
+  dropped by the same sweeper that drops the rendered map when a `.js` file
+  changes. The default `:all` — upstream's behaviour, one link per
+  `preload: true` pin — is unchanged and never opens a file.
+
+- **`javascript_importmap_tags` sends its modulepreload links as 103 Early
+  Hints.** A modulepreload link is markup, so the browser can only act on it
+  once the HTML has streamed far enough to be parsed — the whole module graph
+  waits on the response. The same list now goes out ahead of it as a `Link`
+  header, and the fetches start while the app is still rendering:
+
+  ```
+  HTTP/1.1 103 Early Hints
+  Link: </assets/application-abc.js>; rel=modulepreload, </assets/@hotwired--stimulus-def.js>; rel=modulepreload
+  ```
+
+  Exactly the modules the tags preload, so `preload: false`, an entry point's
+  own list and `preload_strategy = :reachable` all narrow the hinted set with
+  the tags. No `integrity` parameter: browsers don't honour one on a `Link`
+  header, and the tag in the body still carries it.
+
+  This is what Rails' own `javascript_include_tag` and `stylesheet_link_tag`
+  already do, and it needs what they need — a server that puts
+  `rack.early_hints` in the env, which Puma does with `early_hints true`. On a
+  server without it, `send_early_hints` is a no-op and nothing changes. Off
+  with `config.importmap.early_hints = false`.
+
+### Changed
+
+- **Everything this gem knows about esm.run lives in `Importmap::EsmRun`.**
+  The provider name, the bundle URL shapes, the rewrite that turns a bundle's
+  `/npm/dep@ver/+esm` imports into bare specifiers and the jsDelivr version
+  lookup were nine things in `Importmap::Packager`, which had grown to the
+  800-line ceiling with nowhere to put the next addition. Behaviour is
+  unchanged and no documented setting moved: `Importmap::Packager.esm_run_resolver`
+  still reads and writes the resolver, now on the new class. Only the `:nodoc:`
+  constants `Packager::ESM_RUN_*` are gone, as `Importmap::EsmRun::PROVIDER`,
+  `::CDN`, `::URL_REGEXP` and `::IMPORT_REGEXP`.
+
+### Fixed
+
+- **One package a CDN can't resolve no longer blocks — or silently moves — the
+  rest of the batch.** ([#32](https://github.com/zoolutions/importmap-plus/issues/32))
+  A CDN answers a batch of packages as a whole, so `bin/importmap update` with
+  three outdated packages reported `Couldn't find any packages in
+  ["cheap-ruler", "mapbox-gl", "mermaid"] on jspm`, updated nothing and exited
+  0, because jspm's generator can't build `mermaid`. Commenting out the one
+  package let the other two through. A refused batch of more than one package
+  is now asked for one package at a time, along the path each would have taken
+  alone:
+
+  ```
+  $ bin/importmap pin md5@2.2.0 mermaid@10.6.0
+  jspm couldn't resolve "md5@2.2.0", "mermaid@10.6.0" (No './dist/cytoscape.umd.js' exports subpath defined in cytoscape@3.34.3); asking for each on its own
+  Pinning "md5" to vendor/javascript/md5.js via download from https://ga.jspm.io/npm:md5@2.2.0/md5.js
+  jspm couldn't resolve "mermaid@10.6.0" (No './dist/cytoscape.umd.js' exports subpath defined in cytoscape@3.34.3); trying esm.run
+  Pinning "mermaid" to vendor/javascript/mermaid.js via download from https://cdn.jsdelivr.net/npm/mermaid@10.6.0/+esm
+  ```
+  ```ruby
+  pin "md5" # @2.2.0
+  pin "mermaid" # @10.6.0 (esm.run)
+  ```
+
+  Only the package the CDN refused travels the rest of the chain, so a healthy
+  package is never re-pinned from another CDN — and never has its provenance
+  comment rewritten — because a sibling failed. An explicit `--from`, or a
+  provider a pin records, still asks that one CDN and only that one, now once
+  per package. The batch stays the fast path: it is split only when it is
+  refused and holds more than one package.
+
+  `pin`, `update` and `pristine` now **exit 1** when a package was left
+  unresolved, so `bin/importmap update && git commit` can no longer commit an
+  import map that quietly missed a package. The packages that did resolve are
+  still written.
+- **A CDN that fails mid-crawl leaves the pin alone.** Vendoring a graph makes
+  one request per file — 250 of them for `date-fns` — so a 503 that outlives
+  the retries is far likelier than it was for a single download. `pin` and
+  `pristine` report it (`Skipping "date-fns": Unexpected response code (503)`)
+  and change nothing, rather than taking it for "this package can't be
+  vendored" and converting a working pin to a remote one, which would delete
+  the very files that make it work.
+- **`pristine` reports a package it can't restore and carries on.** It is the
+  repair command, and a pin whose graph the CDN no longer serves the way the
+  pin describes now raises where nothing used to — unrescued, that ended the
+  whole run with a backtrace and left every package after it unrestored. Each
+  one that fails is reported (`Couldn't restore "pdfjs-dist": it can't be
+  vendored as a single file (workers)`), the rest are restored, and the command
+  exits non-zero to say it didn't do all of it — as it does when a dependency
+  of an esm.run bundle, pinned on the way, had to be skipped.
+- **A download the CDN encoded in a way Net::HTTP can't undo is fetched
+  again.** jspm answers some files with `content-encoding: br` whatever the
+  request advertises, and Net::HTTP decompresses gzip and deflate only:
+  `@popperjs/core@2.11.8/lib/utils/computeAutoPlacement.js` arrived as brotli
+  bytes, which read as invalid UTF-8 and took the source inspection down with
+  `ArgumentError: invalid byte sequence in UTF-8`. `pin` now repeats that one
+  request asking for an unencoded body. It doesn't ask up front: supplying an
+  `Accept-Encoding` at all stops Net::HTTP decoding the gzip it does
+  understand. Inherited from importmap-rails, which downloads the same way.
+
+- **`Importmap::Packager::ServiceError` is a class again.** It was assigned
+  `Error.new(Error)` — an *instance* — so `rescue Packager::ServiceError`
+  raised `TypeError: class or module required for rescue clause`, and every
+  jspm service error arrived as a plain `Packager::Error`. Inherited from
+  importmap-rails, where it is still the case.
+- **A failed download no longer deletes the file an app already has.**
+  `pin` and `pristine` removed `vendor/javascript/<package>.js` before
+  fetching, so a CDN that answered 500 — or, now, a file that can't be
+  vendored — left the app with no file at all. The existing file is replaced
+  only once the new one has arrived and been found fit to serve.
+- **`update <package>` moves every pin of that package, not just the bare
+  one.** An app with `pin "pdfjs-dist"` and
+  `pin "pdfjs-dist/build/pdf.worker.min.mjs"` ran `update pdfjs-dist` and got
+  a new main file next to a worker still at the old version — the two are
+  built together and don't tolerate that. A package name now means every
+  key that carries it, the same set `outdated` reports and a bare `update`
+  moves; `update pdfjs-dist/build/pdf.worker.min.mjs` still means that one
+  key.
+- **A subpath pin without a CDN in its comment resolves from the CDN its
+  package's pin names.** The worker pin above, written before provenance
+  existed, was sent to jspm — which can't resolve pdf.js at all — and
+  reported "Couldn't find any packages" on every update while the main pin
+  moved on from jsdelivr. Siblings pinned together come from the same place;
+  the next update records it on the pin. A pin answers for itself first — its
+  own comment, then its own `to:` URL — and only then does its package answer
+  for it, whether that pin is vendored, recording the CDN in its comment, or
+  remote, carrying it in the URL with no comment at all.
+
+- **An array `preload:` survives a rewrite however it is quoted, and
+  `preload: []` stays `preload: []`.** The option was read back through
+  `JSON.parse`, so `pin 'md5', preload: ['admin']` — single quotes being a
+  supported pin shape everywhere else in this gem — took down every command
+  that reads a pin with `JSON::ParserError: unexpected character`. And
+  `preload: []` matched nothing at all, so `pin`, `update` and `pristine`
+  dropped it and quietly restored the `preload: true` default on a package the
+  app had asked to preload for no entry point. `config/importmap.rb` is Ruby,
+  not JSON: the entry points are scanned out of the literal now, and an empty
+  array is written back as one.
+
+- **`pin --vendor` leaves a pin to a custom URL alone.** `--vendor` is meant to
+  override the check that refuses a download, not the URL an app chose to pin,
+  but it reached the vendoring path before the branch that skips custom URLs
+  could run: `bin/importmap pin md5 --vendor` against
+  `pin "md5", to: "https://cdn.example.com/md5.js"` downloaded md5 from
+  whichever CDN the spec resolved to and replaced the line with
+  `pin "md5" # @2.3.0 (vendored)`, without a word about the URL it had just
+  dropped. It now reports the skip the way a plain `pin` does and names the
+  flag in it. Moving such a pin on purpose is still `--from`, which re-resolves
+  it from the CDN you name.
+
 ## 1.1.0
 
 ### Added

data/README.md

@@ -25,8 +25,12 @@ An app without an import map yet:
 | `--from esm.run` | Vendors jsDelivr's one-file bundle, rewrites its imports to bare specifiers, and pins the dependencies it needs. |
 | `pin --lock`, `lock`, `unlock` | Holds a package at a version. `update`, `pristine` and `pin` leave it there until you unlock it or pass `--force`. |
 | `update [PACKAGES] --all --force` | Update by name, or everything explicitly; `--force` moves locked packages and re-locks them. |
-| Provenance | The pin comment records the CDN, minification and lock — `pin "luxon" # @3.7.2 (esm.run, minified, locked)` — so nothing silently drifts back to jspm. |
-| Remote pins stay remote | A pin with a CDN URL is re-resolved from that CDN; `preload:` and a boolean `integrity:` survive every rewrite; a custom URL is left alone. |
+| Multi-file packages | A package whose entry imports siblings by relative path is vendored with its whole file graph, mapped by one `pin_all_from` line. One that needs more than files can give it — a worker, `import.meta.url`, a `.wasm` — stays on its CDN with the reason on the pin. |
+| Registry-latest, then CDN fallback | A bare name is resolved on the npm registry, then asked of jspm, esm.run and jsDelivr in turn until one of them has it. `--from` disables the fallback. |
+| `doctor` | Checks the import map against the files that are actually there — offline, reporting only, non-zero on an error — so CI catches a 404 that otherwise shows up on one page in the browser. |
+| Provenance | The pin comment records the CDN, minification, lock and why a package was kept remote — `pin "luxon" # @3.7.2 (esm.run, minified, locked)` — so nothing silently drifts back to jspm. |
+| Remote pins stay remote | A pin with a CDN URL is re-resolved from that CDN and carries a subresource-integrity hash of the bytes that were resolved; `preload:` and a boolean `integrity:` survive every rewrite; a custom URL is left alone. |
+| Preload what the page reaches | `config.importmap.preload_strategy = :reachable` preloads what the entry point actually imports rather than every preloaded pin, and `config.importmap.early_hints` sends those links as a 103 Early Hints response. Both opt-in. |
 | Requests retry | A reset connection, a timeout or a 429/5xx is tried three times with a growing pause before the command gives up. |
 
 ```bash
@@ -34,12 +38,16 @@ An app without an import map yet:
 ./bin/importmap pin @hotwired/stimulus@3.2.2 --lock
 ./bin/importmap update stimulus-use
 ./bin/importmap outdated
+./bin/importmap doctor
 ```
 
 ```ruby
 # config/importmap.rb
 pin "luxon" # @3.7.2 (esm.run, minified)
 pin "@hotwired/stimulus", to: "@hotwired--stimulus.js" # @3.2.2 (locked)
+pin "@popperjs/core", to: "@popperjs--core.js" # @2.11.8
+pin_all_from "vendor/javascript/@popperjs--core", under: "@popperjs/core", to: "@popperjs--core" # @2.11.8 (graph of @popperjs/core)
+pin "fflate", to: "https://ga.jspm.io/npm:fflate@0.8.2/esm/browser.js" # @0.8.2 (remote: workers)
 ```
 
 The full guide — every command, option and behaviour, plus importmap-rails' own documentation for the parts that are unchanged — is at [importmap-plus.zoolutions.llc](https://importmap-plus.zoolutions.llc).

data/app/helpers/importmap/importmap_tags_helper.rb

@@ -1,6 +1,9 @@
 module Importmap::ImportmapTagsHelper
   # Setup all script tags needed to use an importmap-powered entrypoint (which defaults to application.js)
   def javascript_importmap_tags(entry_point = "application", importmap: Rails.application.importmap)
+    preloaded = importmap.preloaded_module_packages(resolver: self, entry_point:, cache_key: entry_point)
+    Importmap::EarlyHints.send_modulepreload_links(self, preloaded)
+
     safe_join [
       javascript_inline_importmap_tag(importmap.to_json(resolver: self)),
       javascript_importmap_module_preload_tags(importmap, entry_point:),

data/lib/importmap/batch_resolver.rb

@@ -0,0 +1,133 @@
+require "importmap/provider_chain"
+
+# Resolves a group of specs against a CDN, batch first and then one at a time.
+#
+# The batch is the fast path and stays: one round trip, and jspm resolves the
+# specs' shared dependencies as a single graph, which is what upstream does.
+# But a CDN answers a batch as a whole — one spec its generator can't build is
+# "no" for all of them — so a refused batch of more than one spec says nothing
+# about the specs in it. Each is then asked on its own, along the path it would
+# have taken alone: through the chain when the group named no CDN, of the same
+# provider once when it did. A package that was always going to resolve is
+# pinned from the CDN it was always going to be pinned from, whatever its
+# siblings did.
+#
+# Specs nobody could resolve are collected rather than raised: each pin is
+# independent of the others, so the rest still land and the exit code says the
+# command didn't do all it was asked.
+class Importmap::BatchResolver
+  # The specs no CDN answered for, in the order they were asked.
+  attr_reader :unresolved
+
+  # +on_miss+ is the command's own "couldn't find" reporter, so the sentence a
+  # single spec gets is written in exactly one place.
+  def initialize(packager, on_miss:, chain: Importmap::ProviderChain.new)
+    @packager   = packager
+    @on_miss    = on_miss
+    @chain      = chain
+    @unresolved = []
+  end
+
+  # Yields [ package, url ] for everything that resolved, as it resolves, so a
+  # spec that fails later can't discard the work of one that succeeded earlier.
+  def each_import(specs, env:, from:, fallback:, &block)
+    @named = specs.map { |spec| @packager.package_key_for(spec) }
+    @seen  = {}
+
+    if specs.one?
+      resolve_one(specs.first, env: env, from: from, fallback: fallback, &block)
+    elsif (response = resolve_batch(specs, env: env, from: from, fallback: fallback))
+      emit(specs, response, &block)
+    else
+      specs.each { |spec| resolve_one(spec, env: env, from: from, fallback: fallback, &block) }
+    end
+  end
+
+  private
+    # The batch a group with no CDN of its own sends goes to jspm alone. Handing
+    # the whole list to the next CDN is what moved a healthy package's provenance
+    # when a sibling failed; the specs travel the rest of the chain separately.
+    def resolve_batch(specs, env:, from:, fallback:)
+      provider = fallback ? Importmap::ProviderChain::DEFAULT : from
+      error    = nil
+
+      response =
+        begin
+          @packager.import(*specs, env: env, from: provider)
+        rescue Importmap::Packager::Error => raised
+          error = raised
+          nil
+        end
+
+      return response if response
+
+      report_split(specs, provider, error&.message || @packager.last_import_error, fallback)
+      nil
+    end
+
+    def report_split(specs, provider, reason, fallback)
+      detail = Importmap::ProviderChain.tidy_reason(reason)
+      miss   = if fallback
+        %(#{provider} couldn't resolve #{quoted(specs)})
+      else
+        %(Couldn't find any packages in #{specs.inspect} on #{provider})
+      end
+
+      puts miss + (detail ? %( (#{detail})) : "") + "; asking for each on its own"
+    end
+
+    def resolve_one(spec, env:, from:, fallback:, &block)
+      source = fallback ? Importmap::ProviderChain.to_sentence : from
+
+      if (response = request_one(spec, env: env, from: from, fallback: fallback))
+        emit([ spec ], response, &block)
+      else
+        # A chain that came up empty has already said why each CDN couldn't.
+        @on_miss.call([ spec ], source, reason: fallback ? nil : @packager.last_import_error)
+        @unresolved << spec
+      end
+    rescue Importmap::Packager::Error => error
+      puts %(Couldn't resolve "#{spec}" from #{source}: #{error.message})
+      @unresolved << spec
+    end
+
+    def request_one(spec, env:, from:, fallback:)
+      if fallback
+        @chain.resolve(@packager, [ spec ], env: env) { |_provider, response| response }
+      else
+        @packager.import(spec, env: env, from: from)
+      end
+    end
+
+    # Split responses overlap: each carries the dependencies of its own spec.
+    # A spec the user named answers for itself, so a sibling's response naming
+    # it is a dependency edge and not the answer asked for. Anything else is
+    # taken from the first response that carried it, because rewriting it to a
+    # second URL would move a package the user never mentioned.
+    def emit(specs, response, &block)
+      asked_for = specs.map { |spec| @packager.package_key_for(spec) }
+
+      response[:imports].each do |package, url|
+        next if @named.include?(package) && !asked_for.include?(package)
+
+        if (kept = @seen[package])
+          report_kept(package, kept, url, specs.first) unless kept == url
+        else
+          @seen[package] = url
+          block.call(package, url)
+        end
+      end
+    end
+
+    def report_kept(package, kept, url, spec)
+      puts %(Keeping "#{package}" at #{version(kept)} ("#{spec}" resolved it to #{version(url)}))
+    end
+
+    def version(url)
+      @packager.extract_package_version_from(url) || url
+    end
+
+    def quoted(specs)
+      specs.map { |spec| %("#{spec}") }.join(", ")
+    end
+end