RubyGems - importmap-plus - Versions diffs - 1.0.0 → 1.1.1 - Mend

importmap-plus 1.0.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fea391704872c66da12c98d005e02ee2090282b4d7ce6065d46e6418ac4ca51e
-  data.tar.gz: a7bf185de0f21d3833eef1faa4d488b17f70779a744131033a1b74418c4ee194
+  metadata.gz: c325b5de05deaf38ca9ed4f671d5c676b36f726ab4e3079e616dc964bdac00b8
+  data.tar.gz: c11ca96640558bf7e4f3e294139ed80b9a893239811e4afa879024268401c90d
 SHA512:
-  metadata.gz: 2cf5e806291fd73a078b390e3cff8aeccd628cc61dfba53469081dec8951cde3a8380009ca9e7f0898c4a17b022ace9b7296f35576ffba0517ca57f2608ca42c
-  data.tar.gz: 13dc2bd3db6f202d60ad3752a33edcdd4e32a1e887cad34bc79f4eb5c9d54cb1582e9799f0af03d273309444b60c56bcba47e44057baf87af08464158b442ff4
+  metadata.gz: a69a963a3506522598a3b0cecb6c8b95c7e4dd275a2fe1cf748f7f5b181bbae62f490f22dc066b42adaf0071dc54e24d940309b2b31ee4b971365aec89ff8a68
+  data.tar.gz: 3ff45f8c8e2ca16ef2f26d4d18438a870bcf50a12c63f29b44a58bf334a9404e3009f4544201f81d1fe7e2f862cad5e15858af5b05a14d7fb97894f2ef972638

data/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,74 @@
 # Changelog
+## 1.1.0
+### Added
+- **Version locks.** `bin/importmap pin luxon@3.7.2 --lock`, or
+  `bin/importmap lock luxon` for a package already pinned, records the lock
+  in the version comment — `pin "luxon" # @3.7.2 (locked)` — and `update`
+  and a plain `pin` skip the package from then on, saying so. A remote pin
+  gains the comment too, carrying the version from its URL. `pin --force`
+  moves a locked package and keeps the lock at the new version; `--no-lock`
+  drops it; `bin/importmap unlock luxon` removes it without touching the
+  file. `pristine` still redownloads a locked vendored package, at the
+  locked version; remote pins are skipped as always. Only the packages
+  named on the command line are locked, never the dependencies a CDN
+  resolves with them, and a locked dependency stays where it is when the
+  package that needs it is pinned or updated.
+- **`update` takes package names, `--all` and `--force`.**
+  `bin/importmap update luxon stimulus-use` re-pins just those, asking the
+  registry about them alone; `update --all` says explicitly what a bare
+  `update` has always done. A named package that is up to date, or has no
+  version to compare, is reported; a name with no pin stops the command
+  before anything is touched. `--force` updates locked packages too and
+  keeps each lock at the new version.
+- **`outdated` shows locks.** A new Locked column marks packages held at
+  their version, and the command exits 1 only when an unlocked package is
+  outdated, so CI stays green for the versions the app chose.
+- **`integrity: true` and `integrity: false` survive a rewrite.** An
+  `update`, `pristine` or `pin` used to drop the option; only an integrity
+  hash, which belongs to the old file, is still removed when the URL changes.
+### Fixed
+- **`update` no longer re-pins a package the registry couldn't be checked
+  for.** A package whose registry lookup came back unusable has no latest
+  version, so nothing established that it moved — but `update` re-pinned it
+  anyway, letting a bad answer re-resolve the pin against the CDN and carry
+  it to a version nobody asked for. Those packages are now reported —
+  `Couldn't check "md5": Unexpected error response 500: …` — and left where
+  they are; every other package still updates, and the command exits 1.
+  Inherited from importmap-rails, where a bare `update` has always behaved
+  this way.
+- **`update` re-pins a subpath pin instead of appending a bare one.** The
+  registry answers about `photoswipe`, the import map pins
+  `photoswipe/lightbox`, and a bare `update` or `update --all` used to re-pin
+  the name it was answered with: the subpath pin stayed at its old version and
+  a `pin "photoswipe"` was appended beside it — vendored, since a fresh pin
+  has no provenance to say otherwise. Every key carrying an outdated package
+  is now re-pinned, and a package pinned under several keys moves all of them.
+  Only pins that declare a version take part, the same ones `outdated`
+  reports on, so an app file pinned under a package's namespace —
+  `pin "md5/helpers", to: "md5/helpers.js"` — is left alone. Inherited from
+  importmap-rails; `update photoswipe/lightbox` was fixed for the named form
+  in 1.1.0.
+- **A remote subpath pin is re-resolved from the CDN it is on.** Moving
+  `pin "photoswipe/lightbox", to: "https://cdn.jsdelivr.net/npm/photoswipe@5.3.0/…"`
+  back onto jsDelivr asked for `photoswipe/lightbox@5.4.4`, a path no CDN
+  has, so `update` gave up with `Keeping "photoswipe/lightbox" pinned to …
+  (couldn't resolve it from jsdelivr)` and the pin never moved. The version
+  now goes where a CDN expects it, ahead of the subpath —
+  `photoswipe@5.4.4/lightbox`.
+- **A registry that won't answer for one package no longer ends the run.**
+  A 404, a 5xx or a connection that kept resetting used to escape
+  `outdated_packages` once the retries were spent, so `outdated` and
+  `update` died with a backtrace and checked nothing else. The failure is
+  now recorded against that package alone — `outdated` prints the reason in
+  its Latest column, which is what the column was always for — and every
+  other package is still checked. `audit` is unchanged: a registry it can't
+  reach still fails the command outright.
 ## 1.0.0
 First release of importmap-plus, a drop-in replacement for

data/README.md CHANGED Viewed

@@ -1,457 +1,63 @@
 # importmap-plus
-A drop-in replacement for [importmap-rails](https://github.com/rails/importmap-rails) with better vendoring: `bin/importmap pin --minify`, `--from esm.run` for jsDelivr's bundled builds, and a pin comment that remembers which CDN a package came from so later updates go back to it. Everything else is importmap-rails, constants included, so an app switches by changing one line in its `Gemfile`.
+A drop-in replacement for [importmap-rails](https://github.com/rails/importmap-rails) with vendoring that keeps its promises: `bin/importmap pin --minify`, `--from esm.run` for jsDelivr's bundled builds, `--lock` to hold a package at a version, `update` by package name, and a pin comment that remembers where each package came from so later updates respect it. Everything else is importmap-rails, constants included, so an app switches by changing one line in its `Gemfile`.
-**Install this gem or importmap-rails, never both** — they define the same `Importmap::` constants and the same engine.
-See [what this adds](#loading-bundles-from-esmrun) below; the rest of this README is importmap-rails' own, which this gem tracks at the version in `Importmap::UPSTREAM_VERSION`.
----
-[Import maps](https://github.com/WICG/import-maps) let you import JavaScript modules using logical names that map to versioned/digested files – directly from the browser. So you can [build modern JavaScript applications using JavaScript libraries made for ES modules (ESM) without the need for transpiling or bundling](https://world.hey.com/dhh/modern-web-apps-without-javascript-bundling-or-transpiling-a20f2755). This frees you from needing Webpack, Yarn, npm, or any other part of the JavaScript toolchain. All you need is the asset pipeline that's already included in Rails.
-With this approach you'll ship many small JavaScript files instead of one big JavaScript file. Thanks to HTTP/2 that no longer carries a material performance penalty during the initial transport, and in fact offers substantial benefits over the long run due to better caching dynamics. Whereas before any change to any JavaScript file included in your big bundle would invalidate the cache for the whole bundle, now only the cache for that single file is invalidated.
-[Import maps are supported natively in all major, modern browsers](https://caniuse.com/?search=importmap). If you need to work with legacy browsers without native support, you can explore using [the shim available](https://github.com/guybedford/es-module-shims).
+**Documentation: [importmap-plus.zoolutions.llc](https://importmap-plus.zoolutions.llc)** — also as [llms.txt](https://importmap-plus.zoolutions.llc/llms.txt) and a read-only MCP endpoint at `https://importmap-plus.zoolutions.llc/mcp`.
+**Install this gem or importmap-rails, never both** — they define the same `Importmap::` constants and the same engine.
 ## Installation
-Rails 7+ ships importmap-rails for new applications. To use importmap-plus instead:
-1. Replace `gem "importmap-rails"` with `gem "importmap-plus"` in your `Gemfile`, or run `./bin/bundle add importmap-plus` in an app that has neither
-2. Run `./bin/rails importmap:install` if the app has no `config/importmap.rb` yet
-An app already on importmap-rails needs nothing else: the pins, the `config/importmap.rb`, the helpers and the `Importmap::` constants are unchanged.
-Note: In order to use JavaScript from Rails frameworks like Action Cable, Action Text, and Active Storage, you must be running Rails 7.0+. This was the first version that shipped with ESM compatible builds of these libraries.
-You can pin those libraries manually by relying on the compiled versions included in Rails like this:
-```ruby
-pin "@rails/actioncable", to: "actioncable.esm.js"
-pin "@rails/activestorage", to: "activestorage.esm.js"
-pin "@rails/actiontext", to: "actiontext.esm.js"
-pin "trix"
-```
-## How do importmaps work?
-At their core, importmaps are essentially a string substitution for what are referred to as "bare module specifiers". A "bare module specifier" looks like this: `import React from "react"`. This is not compatible with the ES Module loader spec. Instead, to be ESM compatible, you must provide 1 of the 3 following types of specifiers:
-- Absolute path:
-```js
-import React from "/Users/DHH/projects/basecamp/node_modules/react"
-```
-- Relative path:
-```js
-import React from "./node_modules/react"
-```
-- HTTP path:
-```js
-import React from "https://ga.jspm.io/npm:react@17.0.1/index.js"
-```
-Importmap-rails provides a clean API for mapping "bare module specifiers" like `"react"`
-to 1 of the 3 viable ways of loading ES Module javascript packages.
-For example:
-```rb
-# config/importmap.rb
-pin "react", to: "https://ga.jspm.io/npm:react@17.0.2/index.js"
-```
-means "every time you see `import React from "react"`
-change it to `import React from "https://ga.jspm.io/npm:react@17.0.2/index.js"`"
-```js
-import React from "react"
-// => import React from "https://ga.jspm.io/npm:react@17.0.2/index.js"
-```
-## Usage
-The import map is setup through `Rails.application.importmap` via the configuration in `config/importmap.rb`. This file is automatically reloaded in development upon changes, but note that you must restart the server if you remove pins and need them gone from the rendered importmap or list of preloads.
-This import map is inlined in the `<head>` of your application layout using `<%= javascript_importmap_tags %>`, which will setup the JSON configuration inside a `<script type="importmap">` tag. Then the application entrypoint is imported via `<script type="module">import "application"</script>`. That logical entrypoint, `application`, is mapped in the importmap script tag to the file `app/javascript/application.js`.
-It's in `app/javascript/application.js` you setup your application by importing any of the modules that have been defined in the import map. You can use the full ESM functionality of importing any particular export of the modules or everything.
-It makes sense to use logical names that match the package names used by npm, such that if you later want to start transpiling or bundling your code, you won't have to change any module imports.
-### Local modules
-If you want to import local js module files from `app/javascript/src` or other sub-folders of `app/javascript` (such as `channels`), you must pin these to be able to import them. You can use `pin_all_from` to pick all files in a specific folder, so you don't have to `pin` each module individually.
-```rb
-# config/importmap.rb
-pin_all_from 'app/javascript/src', under: 'src', to: 'src'
-# With automatic integrity calculation for enhanced security
-enable_integrity!
-pin_all_from 'app/javascript/controllers', under: 'controllers', integrity: true
-```
-The `:to` parameter is only required if you want to change the destination logical import name. If you drop the :to option, you must place the :under option directly after the first parameter.
-The `enable_integrity!` call enables integrity calculation globally, and `integrity: true` automatically calculates integrity hashes for all files in the directory, providing security benefits without manual hash management.
-Allows you to:
-```js
-// app/javascript/application.js
-import { ExampleFunction } from 'src/example_function'
-```
-Which imports the function from `app/javascript/src/example_function.js`.
-Note: Sprockets used to serve assets (albeit without filename digests) it couldn't find from the `app/javascripts` folder with logical relative paths, meaning pinning local files wasn't needed. Propshaft doesn't have this fallback, so when you use Propshaft you have to pin your local modules.
-## Using npm packages via JavaScript CDNs
-Importmap for Rails downloads and vendors your npm package dependencies via JavaScript CDNs that provide pre-compiled distribution versions.
-You can use the `./bin/importmap` command that's added as part of the install to pin, unpin, or update npm packages in your import map. By default this command uses an API from [JSPM.org](https://jspm.org) to resolve your package dependencies efficiently, and then add the pins to your `config/importmap.rb` file.
-```bash
-./bin/importmap pin react
-Pinning "react" to vendor/javascript/react.js via download from https://ga.jspm.io/npm:react@19.1.0/index.js
-```
-This will produce a pin in your `config/importmap.rb` like so:
-```ruby
-pin "react" # @19.1.0
-```
-Other CDNs like [unpkg.com](https://unpkg.com) and [jsdelivr.com](https://www.jsdelivr.com) can be specified with `--from`:
-```bash
-./bin/importmap pin react --from unpkg
-Pinning "react" to vendor/javascript/react.js via download from https://unpkg.com/react@19.1.0/index.js
-```
-```bash
-./bin/importmap pin react --from jsdelivr
-Pinning "react" to vendor/javascript/react.js via download from https://cdn.jsdelivr.net/npm/react@19.1.0/index.js
-```
-The packages are downloaded to `vendor/javascript`, which you can check into your source control, and they'll be available through your application's own asset pipeline serving.
-If you later wish to remove a downloaded pin:
-```bash
-./bin/importmap unpin react
-Unpinning and removing "react"
-```
-### Pinning to remote CDN URLs
-If you'd rather load a package straight from the CDN instead of vendoring a download, pass `--remote`:
-```bash
-./bin/importmap pin react --remote
-Pinning "react" to https://ga.jspm.io/npm:react@19.1.0/index.js
-```
-This will produce a pin in your `config/importmap.rb` like so:
-```ruby
-pin "react", to: "https://ga.jspm.io/npm:react@19.1.0/index.js"
-```
-Remote pins are respected from then on — no `--remote` flag needed. When a remote-pinned package is pinned again or picked up by `./bin/importmap update` (whether directly or as a dependency of another package), the pin stays remote: the URL is re-resolved from the same CDN provider it already points to (`ga.jspm.io`, `unpkg.com`, `cdn.jsdelivr.net`, `cdn.skypack.dev`, or `esm.sh`) instead of being replaced with a download. Pins pointing at any other host are left completely untouched and reported as skipped, and `./bin/importmap pristine` skips remote pins since there is nothing to redownload.
-Options on existing pins, like `preload: false`, are preserved when a pin is rewritten. An explicit `integrity:` value is dropped when the URL changes, since the old hash would no longer match — see the SRI section below for pinning fresh integrity hashes.
-### Loading bundles from esm.run
+Replace `gem "importmap-rails"` with `gem "importmap-plus"` in your `Gemfile` and run `bundle install`. An app already on importmap-rails needs nothing else: the pins, `config/importmap.rb`, the helpers and the `Importmap::` constants are unchanged.
-[esm.run](https://www.jsdelivr.com/esm) is jsDelivr's bundling endpoint: it serves one minified ES module per package, no matter what the package ships on npm. Where jspm hands you a package's own `dist` file (unminified for plenty of packages), `--from esm.run` gives you the bundle:
+An app without an import map yet:
 ```bash
-./bin/importmap pin luxon --from esm.run
-Pinning "luxon" to vendor/javascript/luxon.js via download from https://cdn.jsdelivr.net/npm/luxon@3.7.2/+esm
-```
-A bundle references the packages it depends on as absolute `/npm/dep@1.2.3/+esm` imports, which only resolve on jsDelivr. When the bundle is vendored, those imports are rewritten to bare specifiers (`import { Controller } from "@hotwired/stimulus"`) so they resolve through your import map, and every dependency without a pin is pinned the same way — vendored from esm.run, at the version the bundle was built against:
-```bash
-./bin/importmap pin stimulus-use --from esm.run
-Pinning "stimulus-use" to vendor/javascript/stimulus-use.js via download from https://cdn.jsdelivr.net/npm/stimulus-use@0.53.1/+esm
-Keeping existing pin for "@hotwired/stimulus" (bundle was built against @3.2.2)
-```
-A dependency you already pin is left alone: the bundle then resolves to whatever your import map says, exactly like a jspm download would. With `--remote`, the pin points at the bundle URL and its imports load from jsDelivr as-is.
-Versions are resolved through jsDelivr's data API, so `pin luxon@3 --from esm.run` and subpaths like `pin apexcharts/core --from esm.run` work the way they do on npm.
-### Where a package came from is remembered
-The version comment on a vendored pin also names the CDN when it isn't jspm:
-```ruby
-pin "luxon" # @3.7.2 (esm.run)
-pin "react" # @19.1.0 (unpkg)
+./bin/bundle add importmap-plus
+./bin/rails importmap:install
 ```
-`./bin/importmap update` and `./bin/importmap pristine` read it and go back to the same CDN — an esm.run bundle stays a bundle, an unpkg download stays on unpkg — and so does `pin` when you leave out `--from`. Pass `--from` to move a package to another CDN; an explicit `--from` moves a remote pin too, which is otherwise re-resolved from the CDN it already points at.
+## What it adds
-### Minifying vendored packages
-Lighthouse's unminified-javascript audit will tell you which packages ship unminified builds. Pass `--minify` to run a download through a JavaScript minifier before it lands in `vendor/javascript`:
+| | |
+|---|---|
+| `pin --minify` | Runs a download through bun, esbuild or terser before it lands in `vendor/javascript`; later updates keep minifying it. |
+| `--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. |
+| 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
-./bin/importmap pin luxon --minify
-Pinning "luxon" to vendor/javascript/luxon.js via download from https://ga.jspm.io/npm:luxon@3.7.2/build/es6/luxon.mjs (minified)
-```
-The first of [bun](https://bun.sh), [esbuild](https://esbuild.github.io) or [terser](https://terser.org) found in `node_modules/.bin` or on your `PATH` is used, always in transform-only mode so bare import specifiers are left exactly as the CDN resolved them. The pin records it (`pin "luxon" # @3.7.2 (minified)`, or `(esm.run, minified)` for a bundle), and from then on `update`, `pristine` and a plain `pin` keep minifying that package; `--no-minify` turns it off again, and `./bin/importmap pristine --minify` minifies everything you have vendored in one go.
-To use a different minifier, assign anything that responds to `call(source)` and returns the minified source. `bin/importmap` loads `config/application.rb` but not your initializers, so the assignment has to happen there (or in a file it requires):
-```ruby
-# config/application.rb
-require "importmap/packager"
-Importmap::Packager.minifier = ->(source) { MyMinifier.minify(source) }
-```
-## Subresource Integrity (SRI)
-For enhanced security, importmap-rails supports [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hashes for packages loaded from external CDNs.
-### Automatic integrity for local assets
-To enable automatic integrity calculation for local assets served by the Rails asset pipeline, you must first call `enable_integrity!` in your importmap configuration:
-```ruby
-# config/importmap.rb
-# Enable integrity calculation globally
-enable_integrity!
-# With integrity enabled, these will auto-calculate integrity hashes
-pin "application"                                               # Auto-calculated integrity
-pin "admin", to: "admin.js"                                     # Auto-calculated integrity
-pin_all_from "app/javascript/controllers", under: "controllers" # Auto-calculated integrity
-# Mixed usage - explicitly controlling integrity
-pin "cdn_package", integrity: "sha384-abc123..." # Pre-calculated hash
-pin "no_integrity_package", integrity: false     # Explicitly disable integrity
-pin "nil_integrity_package", integrity: nil      # Explicitly disable integrity
-```
-This is particularly useful for:
-* **Local JavaScript files** managed by your Rails asset pipeline
-* **Bulk operations** with `pin_all_from` where calculating hashes manually would be tedious
-* **Development workflow** where asset contents change frequently
-**Note:** Integrity calculation is opt-in and must be enabled with `enable_integrity!`. This behavior can be further controlled by setting `integrity: false` or `integrity: nil` on individual pins.
-**Important for Propshaft users:** SRI support requires Propshaft 1.2+ and you must configure the integrity hash algorithm in your application:
-```ruby
-# config/application.rb or config/environments/*.rb
-config.assets.integrity_hash_algorithm = 'sha256'  # or 'sha384', 'sha512'
-```
-Without this configuration, integrity will be disabled by default when using Propshaft. Sprockets includes integrity support out of the box.
-**Example output with `enable_integrity!` and `integrity: true`:**
-```json
-{
-  "imports": {
-    "application": "/assets/application-abc123.js",
-    "controllers/hello_controller": "/assets/controllers/hello_controller-def456.js"
-  },
-  "integrity": {
-    "/assets/application-abc123.js": "sha256-xyz789...",
-    "/assets/controllers/hello_controller-def456.js": "sha256-uvw012..."
-  }
-}
-```
-### How integrity works
-The integrity hashes are automatically included in your import map and module preload tags:
-**Import map JSON:**
-```json
-{
-  "imports": {
-    "lodash": "https://ga.jspm.io/npm:lodash@4.17.21/lodash.js",
-    "application": "/assets/application-abc123.js",
-    "controllers/hello_controller": "/assets/controllers/hello_controller-def456.js"
-  },
-  "integrity": {
-    "https://ga.jspm.io/npm:lodash@4.17.21/lodash.js": "sha384-PkIkha4kVPRlGtFantHjuv+Y9mRefUHpLFQbgOYUjzy247kvi16kLR7wWnsAmqZF"
-    "/assets/application-abc123.js": "sha256-xyz789...",
-    "/assets/controllers/hello_controller-def456.js": "sha256-uvw012..."
-  }
-}
-```
-**Module preload tags:**
-```html
-<link rel="modulepreload" href="https://ga.jspm.io/npm:lodash@4.17.21/lodash.js" integrity="sha384-PkIkha4kVPRlGtFantHjuv+Y9mRefUHpLFQbgOYUjzy247kvi16kLR7wWnsAmqZF">
-<link rel="modulepreload" href="/assets/application-abc123.js" integrity="sha256-xyz789...">
-<link rel="modulepreload" href="/assets/controllers/hello_controller-def456.js" integrity="sha256-uvw012...">
-```
-Modern browsers will automatically validate these integrity hashes when loading the JavaScript modules, ensuring the files haven't been modified.
-## Preloading pinned modules
-To avoid the waterfall effect where the browser has to load one file after another before it can get to the deepest nested import, importmap-rails uses [modulepreload links](https://developers.google.com/web/updates/2017/12/modulepreload) by default. If you don't want to preload a dependency, because you want to load it on-demand for efficiency, append `preload: false` to the pin.
-Example:
-```ruby
-# config/importmap.rb
-pin "@github/hotkey", to: "@github--hotkey.js" # file lives in vendor/javascript/@github--hotkey.js
-pin "md5", preload: false # file lives in vendor/javascript/md5.js
-# app/views/layouts/application.html.erb
-<%= javascript_importmap_tags %>
-# will include the following link before the importmap is setup:
-<link rel="modulepreload" href="/assets/javascript/@github--hotkey.js">
-...
-```
-You can also specify which entry points to preload a particular dependency in by providing `preload:` a string or array of strings.
-Example:
-```ruby
-# config/importmap.rb
-pin "@github/hotkey", to: "@github--hotkey.js", preload: 'application'
-pin "md5", preload: ['application', 'alternate']
-# app/views/layouts/application.html.erb
-<%= javascript_importmap_tags 'alternate' %>
-# will include the following link before the importmap is setup:
-<link rel="modulepreload" href="/assets/javascript/md5.js">
-...
+./bin/importmap pin luxon --from esm.run --minify
+./bin/importmap pin @hotwired/stimulus@3.2.2 --lock
+./bin/importmap update stimulus-use
+./bin/importmap outdated
 ```
-## Composing import maps
-By default, Rails loads import map definition from the application's `config/importmap.rb` to the `Importmap::Map` object available at `Rails.application.importmap`.
-You can combine multiple import maps by adding paths to additional import map configs to `Rails.application.config.importmap.paths`. For example, appending import maps defined in Rails engines:
 ```ruby
-# my_engine/lib/my_engine/engine.rb
-module MyEngine
-  class Engine < ::Rails::Engine
-    # ...
-    initializer "my-engine.importmap", before: "importmap" do |app|
-      app.config.importmap.paths << Engine.root.join("config/importmap.rb")
-      # ...
-    end
-  end
-end
-```
-And pinning JavaScript modules from the engine:
-```ruby
-# my_engine/config/importmap.rb
-pin_all_from File.expand_path("../app/assets/javascripts", __dir__)
-```
-## Selectively importing modules
-You can selectively import your javascript modules on specific pages.
-Create your javascript in `app/javascript`:
-```js
-// /app/javascript/checkout.js
-// some checkout specific js
-```
-Pin your js file:
-```rb
 # config/importmap.rb
-# ... other pins...
-pin "checkout", preload: false
-```
-Import your module on the specific page. Note: you'll likely want to use a `content_for` block on the specific page/partial, then yield it in your layout.
-```erb
-<% content_for :head do %>
-  <%= javascript_import_module_tag "checkout" %>
-<% end %>
-```
-**Important**: The `javascript_import_module_tag` should come after your `javascript_importmap_tags`
-```erb
-<%= javascript_importmap_tags %>
-<%= yield(:head) %>
+pin "luxon" # @3.7.2 (esm.run, minified)
+pin "@hotwired/stimulus", to: "@hotwired--stimulus.js" # @3.2.2 (locked)
 ```
+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).
-## Include a digest of the import map in your ETag
-If you're using [ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) generated by Rails helpers like `stale?` or `fresh_when`, you need to include the digest of the import map into this calculation. Otherwise your application will return [304](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304) cache responses even when your JavaScript assets have changed. You can avoid this using the `stale_when_importmap_changes` method:
-```ruby
-class ApplicationController < ActionController::Base
-  stale_when_importmap_changes
-end
-```
+## Tracking importmap-rails
-This will add the digest of the importmap to the etag calculation when the request format is HTML.
+This gem tracks importmap-rails at the release named in `Importmap::UPSTREAM_VERSION`; its own version is `Importmap::VERSION`. Upstream changes are merged as they land, and the parts of the documentation that describe upstream behaviour are kept in step. See [CHANGELOG.md](CHANGELOG.md) for what each release adds.
+## Development
-## Sweeping the cache in development and test
-Generating the import map json and modulepreloads may require resolving hundreds of assets. This can take a while, so these operations are cached, but in development and test, we watch for changes to both `config/importmap.rb` and files in `app/javascript` to clear this cache. This feature can be controlled in an environment configuration file via the boolean `config.importmap.sweep_cache`.
-If you're pinning local files from outside of `app/javascript`, you'll need to add them to the cache sweeper configuration or restart your development server upon changes to those external files. For example, here's how you can do it for Rails engine:
-```ruby
-# my_engine/lib/my_engine/engine.rb
-module MyEngine
-  class Engine < ::Rails::Engine
-    # ...
-    initializer "my-engine.importmap", before: "importmap" do |app|
-      # ...
-      app.config.importmap.cache_sweepers << Engine.root.join("app/assets/javascripts")
-    end
-  end
-end
+```bash
+bundle install
+bundle exec rake test          # the command tests talk to live CDNs (jspm, jsDelivr)
+cd docs && bin/dev             # the docs site, a docs-kit app at docs/
 ```
-## Checking for outdated or vulnerable packages
-Importmap for Rails provides two commands to check your pinned packages:
-- `./bin/importmap outdated` checks the NPM registry for new versions
-- `./bin/importmap audit` checks the NPM registry for known security issues
-## Supporting legacy browsers such as Safari on iOS 15
-If you want to support [legacy browsers that do not support import maps](https://caniuse.com/import-maps) such as [iOS 15.8.1 released on 22 Jan 2024](https://support.apple.com/en-us/HT201222), insert [`es-module-shims`](https://github.com/guybedford/es-module-shims) before `javascript_importmap_tags` as below.
-```erb
-<script async src="https://ga.jspm.io/npm:es-module-shims@1.8.2/dist/es-module-shims.js" data-turbo-track="reload"></script>
-<%= javascript_importmap_tags %>
-```
+Releases are cut with `bin/release`, which tags a version and publishes a GitHub Release; that fires `.github/workflows/release.yml` (RubyGems trusted publishing) and `.github/workflows/deploy-docs.yml` (the docs site).
 ## License
-Importmap for Rails is released under the [MIT License](https://opensource.org/licenses/MIT).
+Importmap for Rails is released under the [MIT License](https://opensource.org/licenses/MIT), and so is importmap-plus.

data/lib/importmap/commands.rb CHANGED Viewed

@@ -15,13 +15,33 @@ class Importmap::Commands < Thor
   option :preload, type: :string, repeatable: true, desc: "Can be used multiple times"
   option :remote, type: :boolean, default: false, desc: "Pin to the remote URL instead of vendoring a download"
   option :minify, type: :boolean, desc: "Minify the vendored download with bun, esbuild or terser"
+  option :lock, type: :boolean, desc: "Lock the pin at this version; update, pin and pristine leave it there until unlocked"
+  option :force, type: :boolean, default: false, desc: "Re-pin locked packages, keeping each lock at the new version"
   def pin(*packages)
+    packages = without_locked(packages, lock: options[:lock], force: options[:force])
+    # jspm resolves a package together with its dependencies; --lock and
+    # --no-lock are about the packages that were asked for, not those.
+    requested = packages.map { |spec| packager.package_key_for(spec) }
     for_each_import_grouped_by_provider(packages, env: options[:env], from: options[:from]) do |package, url|
+      next if keep_locked_dependency(package, requested)
       pin_package(package, url, preload: options[:preload], remote: options[:remote], env: options[:env],
-                                minify: options[:minify], from: options[:from])
+                                minify: options[:minify], from: options[:from],
+                                lock: requested.include?(package) ? options[:lock] : nil)
     end
   end
+  desc "lock [*PACKAGES]", "Lock packages at their pinned version"
+  def lock(*packages)
+    exit 1 unless packages.map { |package| lock_package(package) }.all?
+  end
+  desc "unlock [*PACKAGES]", "Let locked packages be updated again"
+  def unlock(*packages)
+    exit 1 unless packages.map { |package| unlock_package(package) }.all?
+  end
   desc "unpin [*PACKAGES]", "Unpin existing packages"
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
@@ -44,6 +64,8 @@ class Importmap::Commands < Thor
     for_each_import_grouped_by_provider(packages, env: options[:env], from: options[:from]) do |package, url|
       if packager.remote_pin?(package)
         puts %(Skipping "#{package}" (pinned to remote URL))
+      elsif (resolved = version_drift_of_locked(package, url))
+        puts %(Skipping "#{package}" (locked at #{packager.pin_provenance(package)[:version]}, CDN resolved #{resolved}))
       else
         minify = options[:minify].nil? ? vendored_minified?(package) : options[:minify]
@@ -85,28 +107,56 @@ class Importmap::Commands < Thor
   desc "outdated", "Check for outdated packages"
   def outdated
     if (outdated_packages = npm.outdated_packages).any?
-      table = [["Package", "Current", "Latest"]]
-      outdated_packages.each { |p| table << [p.name, p.current_version, p.latest_version || p.error] }
+      locked = outdated_packages.select { |p| locked_pin_covering(p.name) }
+      table = [["Package", "Current", "Latest", "Locked"]]
+      outdated_packages.each { |p| table << [p.name, p.current_version, p.latest_version || p.error, locked.include?(p) ? "yes" : ""] }
       puts_table(table)
       packages = 'package'.pluralize(outdated_packages.size)
-      puts "  #{outdated_packages.size} outdated #{packages} found"
+      puts "  #{outdated_packages.size} outdated #{packages} found#{" (#{locked.size} locked)" if locked.any?}"
-      exit 1
+      # A lock is a version the app chose, so only the rest count as drift.
+      exit 1 if locked.size < outdated_packages.size
     else
       puts "No outdated packages found"
     end
   end
-  desc "update", "Update outdated package pins"
-  def update
-    if (outdated_packages = npm.outdated_packages).any?
-      for_each_import_grouped_by_provider(outdated_packages.map(&:name), env: "production") do |package, url|
+  desc "update [*PACKAGES]", "Update outdated package pins"
+  option :all, type: :boolean, default: false, desc: "Update every outdated package (the default when no names are given)"
+  option :force, type: :boolean, default: false, desc: "Update locked packages too, keeping each lock at the new version"
+  def update(*packages)
+    if packages.any? && options[:all]
+      puts "Pass package names or --all, not both"
+      exit 1
+    end
+    # A package the registry couldn't answer for has no latest_version, so
+    # nothing established that it moved: re-pinning would let a blip
+    # re-resolve the pin against the CDN and carry it somewhere new. Each
+    # pin is independent of the others, so the rest still update; the exit
+    # code says the command didn't do all it was asked.
+    outdated_packages, unchecked_packages = npm.outdated_packages(only: packages.presence).partition(&:latest_version)
+    unchecked_packages.each { |p| puts %(Couldn't check "#{p.name}": #{p.error}) }
+    exit 1 unless every_package_known?(packages, outdated_packages, unchecked_packages)
+    if outdated_packages.empty?
+      puts "No outdated packages found" if unchecked_packages.empty?
+    elsif (names = without_locked_updates(outdated_packages.map(&:name), force: options[:force])).empty?
+      puts "Nothing to update (every outdated package is locked; pass --force)"
+    else
+      keys = packages.any? ? requested_keys_for(packages, names) : outdated_keys_for(names)
+      for_each_import_grouped_by_provider(keys, env: "production") do |package, url|
+        next if keep_locked_dependency(package, keys)
         pin_package(package, url)
       end
-    else
-      puts "No outdated packages found"
     end
+    exit 1 if unchecked_packages.any?
   end
   desc "packages", "Print out packages with version numbers"
@@ -123,32 +173,181 @@ class Importmap::Commands < Thor
       @npm ||= Importmap::Npm.new
     end
-    def pin_package(package, url, preload: nil, remote: false, env: "production", minify: nil, from: nil)
+    # A lock outlives a rewrite unless the caller says otherwise, so update
+    # and --force re-lock at the version they move to.
+    def pin_package(package, url, preload: nil, remote: false, env: "production", minify: nil, from: nil, lock: nil)
       existing_options = packager.extract_existing_pin_options(package)[package] || {}
       preload = existing_options[:preload] if preload.nil?
+      integrity = existing_options[:integrity]
+      locked = lock.nil? ? packager.locked?(package) : lock
       existing_url = existing_options[:to] if existing_options[:to].to_s.match?(Importmap::Packager::REMOTE_URL_REGEXP)
       if existing_url
-        repin_remote_package(package, url, existing_url, preload, env: env, from: from)
+        repin_remote_package(package, url, existing_url, preload, env: env, from: from, integrity: integrity, locked: locked)
       elsif remote
-        pin_remote_package(package, url, preload)
+        pin_remote_package(package, url, preload, integrity: integrity, locked: locked)
       else
-        pin_vendored_package(package, url, preload, minify: minify)
+        pin_vendored_package(package, url, preload, minify: minify, integrity: integrity, locked: locked)
       end
     end
-    def pin_vendored_package(package, url, preload, minify: nil)
+    def pin_vendored_package(package, url, preload, minify: nil, integrity: nil, locked: false)
       minify = vendored_minified?(package) if minify.nil?
       puts %(Pinning "#{package}" to #{packager.vendor_path}/#{package}.js via download from #{url}#{" (minified)" if minify})
       dependencies = packager.download(package, url, minify: minify)
-      update_importmap_with_pin(package, packager.vendored_pin_for(package, url, preload, minify: minify))
+      update_importmap_with_pin(package, packager.vendored_pin_for(package, url, preload, minify: minify, integrity: integrity, locked: locked))
+      report_lock(package) if locked
       pin_esm_run_dependencies(dependencies, preload: preload, minify: minify)
     end
+    def lock_package(spec)
+      package = packager.package_key_for(spec)
+      if package != spec
+        puts %(Use "bin/importmap pin #{spec} --lock" to lock at a different version)
+      elsif !packager.packaged?(package)
+        puts %(Couldn't find a pin for "#{package}")
+      elsif packager.locked?(package)
+        puts %("#{package}" is already locked at #{packager.pin_provenance(package)[:version]})
+        return true
+      elsif (line = packager.locked_pin_line(package))
+        update_importmap_with_pin(package, line)
+        report_lock(package)
+        return true
+      else
+        puts %(Can't lock "#{package}": its pin has no version)
+      end
+      false
+    end
+    def unlock_package(spec)
+      package = packager.package_key_for(spec)
+      if !packager.packaged?(package)
+        puts %(Couldn't find a pin for "#{package}")
+        false
+      elsif !packager.locked?(package)
+        puts %("#{package}" isn't locked)
+        true
+      else
+        update_importmap_with_pin(package, packager.unlocked_pin_line(package))
+        puts %(Unlocked "#{package}")
+        true
+      end
+    end
+    def report_lock(package)
+      puts %(Locked "#{package}" at #{packager.pin_provenance(package)[:version]})
+    end
+    # Specs the user named that point at a locked pin are dropped, with a
+    # note, unless the lock is what they are here to change.
+    def without_locked(specs, lock: nil, force: false)
+      return specs if force || !lock.nil?
+      specs.reject do |spec|
+        package = packager.package_key_for(spec)
+        packager.locked?(package).tap { |locked| puts skip_locked_message(package) if locked }
+      end
+    end
+    # update sees npm names (apexcharts) where pins are import-map keys
+    # (apexcharts/core), so a lock on any pin of the package holds it.
+    def without_locked_updates(names, force: false)
+      return names if force
+      names.reject do |name|
+        (locked = locked_pin_covering(name)).tap { puts skip_locked_message(locked) if locked }
+      end
+    end
+    def skip_locked_message(package)
+      %(Skipping "#{package}" (locked at #{packager.pin_provenance(package)[:version]}; run bin/importmap unlock #{package} or pass --force))
+    end
+    # Says why a named package won't be updated. A name with no pin at all
+    # is a typo until proven otherwise, so nothing is updated in that case.
+    # One the registry couldn't be asked about was already reported and is
+    # no reason to hold back the others.
+    def every_package_known?(names, outdated_packages, unchecked_packages)
+      versioned = npm.packages_with_versions.to_h
+      outdated  = outdated_packages.map(&:name)
+      unchecked = unchecked_packages.map(&:name)
+      names.map do |name|
+        key = packager.package_key_for(name)
+        package = packager.package_name_for(key)
+        if !packager.packaged?(key)
+          puts %(Couldn't find a pin for "#{name}")
+          next false
+        elsif outdated.include?(package) || unchecked.include?(package)
+          next true
+        elsif versioned.key?(package)
+          puts %("#{name}" is already up to date (#{versioned[package]}))
+        else
+          puts %(Can't tell whether "#{name}" is outdated: its pin has no version)
+        end
+        true
+      end.all?
+    end
+    # The registry knows a package by name and the import map by key: a pin of
+    # "photoswipe/lightbox" is outdated when "photoswipe" is. A named update
+    # re-pins the keys that were asked for, not the name the registry answered with.
+    def requested_keys_for(specs, outdated_names)
+      specs.map { |spec| packager.package_key_for(spec) }
+           .select { |key| outdated_names.include?(packager.package_name_for(key)) }
+    end
+    # An outdated package is outdated in every pin that carries it, so a bare
+    # update re-pins those keys: "photoswipe" moving updates the app's
+    # "photoswipe/lightbox" pin rather than appending a bare one beside it.
+    #
+    # Only pins that declare a version count, the same ones outdated reports
+    # on. An app file pinned under a package's namespace — pin "md5/helpers",
+    # to: "md5/helpers.js" — names no version and is none of the registry's
+    # business; asking a CDN for it 404s the whole batch and nothing updates.
+    #
+    # A name no pin's key names is one whose version came from a URL that
+    # doesn't match its key (pin "buffer", to: ".../npm:jspm-core@..."); it is
+    # still the only handle there is, so it goes through as itself.
+    def outdated_keys_for(names)
+      keys = packager.pinned_packages.select { |key| packager.pin_version(key) }
+                                     .group_by { |key| packager.package_name_for(key) }
+      names.flat_map { |name| keys[name] || [ name ] }
+    end
+    def locked_pin_covering(name)
+      packager.locked_pins.find { |key| key == name || key.start_with?("#{name}/") }
+    end
+    # A CDN resolves a package together with its dependencies. One the app has
+    # locked stays where it is: only a package named on the command line moves.
+    def keep_locked_dependency(package, requested)
+      return false if requested.include?(package) || !packager.locked?(package)
+      puts %(Keeping existing pin for "#{package}" (locked at #{packager.pin_provenance(package)[:version]}))
+      true
+    end
+    # pristine asks the CDN for the pinned version, so a locked package only
+    # drifts if the CDN answers with another one.
+    def version_drift_of_locked(package, url)
+      return unless packager.locked?(package)
+      resolved = packager.extract_package_version_from(url).to_s.delete_prefix("@")
+      resolved if resolved != packager.pin_provenance(package)[:version]
+    end
     # An esm.run bundle imports its dependencies as bare specifiers after
     # download, so each one needs a pin. Pins the app already has win: the
     # bundle then resolves to whatever version the app chose.
@@ -167,9 +366,11 @@ class Importmap::Commands < Thor
     # comment those are recorded in. Left alone otherwise: a pin may carry
     # options, such as integrity, that a rewrite would drop.
     def record_provenance(package, url, minify)
-      preload = (packager.extract_existing_pin_options(package)[package] || {})[:preload]
+      existing_options = packager.extract_existing_pin_options(package)[package] || {}
-      update_importmap_with_pin(package, packager.vendored_pin_for(package, url, preload, minify: minify))
+      update_importmap_with_pin(package, packager.vendored_pin_for(package, url, existing_options[:preload],
+                                                                   minify: minify, integrity: existing_options[:integrity],
+                                                                   locked: packager.locked?(package)))
     end
     def provenance_changed?(package, url, minify)
@@ -196,27 +397,28 @@ class Importmap::Commands < Thor
       packager.pin_provenance(packager.package_key_for(spec))&.dig(:provider)
     end
-    def pin_remote_package(package, url, preload)
+    def pin_remote_package(package, url, preload, integrity: nil, locked: false)
       puts %(Pinning "#{package}" to #{url})
       packager.remove_existing_package_file(package)
-      update_importmap_with_pin(package, packager.pin_for(package, url, preloads: preload))
+      update_importmap_with_pin(package, packager.pin_for(package, url, preloads: preload, integrity: integrity, locked: locked))
+      report_lock(package) if locked
     end
-    def repin_remote_package(package, url, existing_url, preload, env:, from: nil)
+    def repin_remote_package(package, url, existing_url, preload, env:, from: nil, integrity: nil, locked: false)
       # `url` was already resolved from the requested CDN, so an explicit
       # --from moves the pin instead of being overruled by its current one.
-      return pin_remote_package(package, url, preload) if from
+      return pin_remote_package(package, url, preload, integrity: integrity, locked: locked) if from
       provider = packager.provider_for_url(existing_url)
       if provider.nil?
         puts %(Skipping "#{package}" pinned to custom URL #{existing_url})
       elsif provider == packager.provider_for_url(url)
-        pin_remote_package(package, url, preload)
+        pin_remote_package(package, url, preload, integrity: integrity, locked: locked)
       elsif (provider_url = resolve_url_from_provider(package, url, provider, env: env))
-        pin_remote_package(package, provider_url, preload)
+        pin_remote_package(package, provider_url, preload, integrity: integrity, locked: locked)
       else
         puts %(Keeping "#{package}" pinned to #{existing_url} (couldn't resolve it from #{provider}))
       end
@@ -224,7 +426,7 @@ class Importmap::Commands < Thor
     def resolve_url_from_provider(package, reference_url, provider, env:)
       version  = packager.extract_package_version_from(reference_url)
-      response = packager.import("#{package}#{version}", env: env, from: provider)
+      response = packager.import(packager.package_spec_for(package, version), env: env, from: provider)
       response && response[:imports][package]
     rescue Importmap::Packager::Error => error

data/lib/importmap/npm.rb CHANGED Viewed

@@ -19,8 +19,13 @@ class Importmap::Npm
     @vendor_path    = Pathname.new(vendor_path)
   end
-  def outdated_packages
-    packages_with_versions.each_with_object([]) do |(package, current_version), outdated_packages|
+  # With +only:+, just those packages are looked up; names may carry a
+  # subpath (apexcharts/core), which the registry doesn't know about.
+  def outdated_packages(only: nil)
+    wanted = only&.map { |name| extract_base_package_name(name) }
+    candidates = wanted ? packages_with_versions.select { |package, _| wanted.include?(package) } : packages_with_versions
+    candidates.each_with_object([]) do |(package, current_version), outdated_packages|
       outdated_package = OutdatedPackage.new(name: package, current_version: current_version)
       if !(response = get_package(package))
@@ -51,21 +56,25 @@ class Importmap::Npm
     end.sort_by { |p| [p.name, p.severity] }
   end
+  # Memoized: a command that asks twice would otherwise report the
+  # unversioned packages twice.
   def packages_with_versions
-    # We cannot use the name after "pin" because some dependencies are loaded from inside packages
-    # Eg. pin "buffer", to: "https://ga.jspm.io/npm:@jspm/core@2.0.0-beta.19/nodelibs/browser/buffer.js"
-    with_versions = importmap.scan(/^pin .*(?<=npm:|npm\/|skypack\.dev\/|unpkg\.com\/|esm\.sh\/|esm\.sh\/\*)([^@\/]+)@(\d+\.\d+\.\d+(?:[^\/\s"']*))/) |
-      importmap.scan(/#{PIN_REGEX} #.*@(\d+\.\d+\.\d+(?:[^\s]*)).*$/)
-    with_versions.map! do |package, version|
-      [extract_base_package_name(package), version]
-    end.uniq!
+    @packages_with_versions ||= begin
+      # We cannot use the name after "pin" because some dependencies are loaded from inside packages
+      # Eg. pin "buffer", to: "https://ga.jspm.io/npm:@jspm/core@2.0.0-beta.19/nodelibs/browser/buffer.js"
+      with_versions = importmap.scan(/^pin .*(?<=npm:|npm\/|skypack\.dev\/|unpkg\.com\/|esm\.sh\/|esm\.sh\/\*)([^@\/]+)@(\d+\.\d+\.\d+(?:[^\/\s"']*))/) |
+        importmap.scan(/#{PIN_REGEX} #.*@(\d+\.\d+\.\d+(?:[^\s]*)).*$/)
+      with_versions.map! do |package, version|
+        [extract_base_package_name(package), version]
+      end.uniq!
+      vendored_packages_without_version(with_versions).each do |package, path|
+        $stdout.puts "Ignoring #{package} (#{path}) since no version is specified in the importmap"
+      end
-    vendored_packages_without_version(with_versions).each do |package, path|
-      $stdout.puts "Ignoring #{package} (#{path}) since no version is specified in the importmap"
+      with_versions
     end
-    with_versions
   end
   private
@@ -84,6 +93,11 @@ class Importmap::Npm
       JSON.parse(response)
     rescue JSON::ParserError
       nil
+    rescue HTTPError => error
+      # One package the registry won't answer for shouldn't end the run: the
+      # caller records it as unchecked, so the rest are still reported on.
+      # with_retries has already spent its attempts by the time we get here.
+      { "error" => error.message }
     end
     def get_json(uri)

data/lib/importmap/packager.rb CHANGED Viewed

@@ -10,6 +10,9 @@ class Importmap::Packager
   PIN_REGEX = /#{Importmap::Map::PIN_REGEX}(.*)/.freeze # :nodoc:
   PRELOAD_OPTION_REGEXP = /preload:\s*(\[[^\]]+\]|true|false|["'][^"']*["'])/.freeze # :nodoc:
   TO_OPTION_REGEXP = /to:\s*["']([^"']*)["']/.freeze # :nodoc:
+  # Only the booleans: a hash string is tied to the file it was computed for,
+  # so a rewrite that changes the URL has to drop it.
+  INTEGRITY_OPTION_REGEXP = /integrity:\s*(true|false)\b/.freeze # :nodoc:
   REMOTE_URL_REGEXP = %r{\Ahttps?://}.freeze # :nodoc:
   PROVIDER_HOSTS = {
@@ -41,6 +44,12 @@ class Importmap::Packager
   #   pin "luxon" # @3.7.2
   #   pin "luxon" # @3.7.2 (esm.run, minified)
   PIN_PROVENANCE_REGEXP = /#\s*@([^\s(]+)(?:\s+\(([^)]*)\))?/.freeze # :nodoc:
+  # A lock is one more detail in that list, always last:
+  #   pin "luxon" # @3.7.2 (esm.run, minified, locked)
+  # "locked: <range>" is reserved for range locks, so it is read as a lock
+  # today rather than mistaken for a provider name.
+  LOCK_DETAIL        = "locked".freeze # :nodoc:
+  LOCK_DETAIL_REGEXP = /\Alocked(?::\s*(.+))?\z/.freeze # :nodoc:
   DEFAULT_PROVIDER = "jspm.io".freeze # :nodoc:
   Error        = Class.new(StandardError)
@@ -103,45 +112,101 @@ class Importmap::Packager
     end
   end
-  def pin_for(package, url = nil, preloads: nil)
+  # A remote pin has no version comment unless it is locked; then the version
+  # in its URL is written out so the lock has something to hold:
+  #
+  #   pin "md5", to: "https://cdn.jsdelivr.net/npm/md5@2.2.0/md5.js" # @2.2.0 (locked)
+  #
+  def pin_for(package, url = nil, preloads: nil, integrity: nil, locked: false)
     to = url ? %(, to: "#{url}") : ""
     preload_param = preload(preloads)
+    integrity_param = integrity.nil? ? "" : %(, integrity: #{integrity})
+    version = extract_package_version_from(url.to_s) if locked
-     %(pin "#{package}") + to + preload_param
+    %(pin "#{package}") + to + preload_param + integrity_param + (version ? provenance_comment(version, locked: true) : "")
   end
   # The pin line for a vendored download. The version comment also records
-  # the CDN when it isn't jspm and whether the file was minified, so a later
-  # update or pristine can do the same again:
+  # the CDN when it isn't jspm, whether the file was minified and whether the
+  # version is locked, so a later update or pristine can do the same again:
   #
   #   pin "luxon" # @3.7.2
-  #   pin "luxon" # @3.7.2 (esm.run, minified)
+  #   pin "luxon" # @3.7.2 (esm.run, minified, locked)
   #
-  def vendored_pin_for(package, url, preloads = nil, minify: false)
+  def vendored_pin_for(package, url, preloads = nil, minify: false, integrity: nil, locked: false)
     filename = package_filename(package)
     version  = extract_package_version_from(url)
     to = "#{package}.js" != filename ? filename : nil
-    provenance = []
-    provenance << provider_for_url(url) if provider_for_url(url) && provider_for_url(url) != DEFAULT_PROVIDER
-    provenance << "minified" if minify
-    pin_for(package, to, preloads: preloads) + %( # #{version}) + (provenance.any? ? %( (#{provenance.join(", ")})) : "")
+    pin_for(package, to, preloads: preloads, integrity: integrity) +
+      provenance_comment(version, provider: provider_for_url(url), minified: minify, locked: locked)
   end
-  # What the pin's version comment says a vendored package was built with:
-  # { version:, provider:, minified: }, or nil for a pin without one.
+  # What the pin's version comment says a package was built with:
+  # { version:, provider:, minified:, locked: }, or nil for a pin without one.
   def pin_provenance(package)
+    provenance_of(pin_line_for(package))
+  end
+  # The line that pins +package+, without its newline, or nil.
+  def pin_line_for(package)
     return unless @importmap_path.exist?
-    line = importmap.lines.find { |candidate| candidate.match?(Importmap::Map.pin_line_regexp_for(package)) }
-    match = line&.match(PIN_PROVENANCE_REGEXP)
-    return unless match
+    importmap.lines.find { |candidate| candidate.match?(Importmap::Map.pin_line_regexp_for(package)) }&.chomp
+  end
+  # The version a pin declares, in its provenance comment or in the CDN URL it
+  # points at, or nil when it names none — as one of the app's own files
+  # doesn't. Only a pin with a version can be told to be outdated.
+  def pin_version(package)
+    provenance = pin_provenance(package)
+    return provenance[:version] if provenance
+    to = (extract_existing_pin_options(package)[package] || {})[:to]
+    extract_package_version_from(to.to_s)&.delete_prefix("@")
+  end
+  def locked?(package)
+    pin_provenance(package)&.dig(:locked) || false
+  end
+  # The import-map keys of every pin, in file order.
+  def pinned_packages
+    return [] unless @importmap_path.exist?
+    importmap.lines.filter_map { |line| line.strip[PIN_REGEX, 1] }
+  end
+  # The import-map keys of every locked pin, in file order.
+  def locked_pins
+    return [] unless @importmap_path.exist?
+    importmap.lines.filter_map do |line|
+      name = line.strip[PIN_REGEX, 1]
+      name if name && provenance_of(line)&.dig(:locked)
+    end
+  end
+  # The pin line with a lock added — to the version comment it has, or as a
+  # new comment carrying the version from its URL. Nothing else on the line is
+  # touched. Nil when the pin has no version to lock at, or isn't there.
+  def locked_pin_line(package)
+    line = pin_line_for(package)
+    return unless line
+    if line.match?(PIN_PROVENANCE_REGEXP)
+      rewrite_provenance(line) { |details| without_lock(details) << LOCK_DETAIL }
+    elsif (to = (extract_existing_pin_options(package)[package] || {})[:to].to_s).match?(REMOTE_URL_REGEXP) &&
+          (version = extract_package_version_from(to))
+      line + provenance_comment(version, locked: true)
+    end
+  end
-    details = match[2].to_s.split(",").map(&:strip)
-    minified = details.delete("minified") ? true : false
+  # The pin line with its lock removed; an empty detail list drops its parens.
+  def unlocked_pin_line(package)
+    line = pin_line_for(package)
-    { version: match[1], provider: details.first, minified: minified }
+    rewrite_provenance(line) { |details| without_lock(details) } if line
   end
   def packaged?(package)
@@ -216,6 +281,23 @@ class Importmap::Packager
     name ? "#{name}#{subpath}" : spec.to_s
   end
+  # The package a spec or key belongs to, as the registry knows it:
+  # "photoswipe/lightbox" and "@hotwired/stimulus@3" are pins of "photoswipe"
+  # and "@hotwired/stimulus".
+  def package_name_for(spec)
+    spec.to_s.match(PACKAGE_SPEC_REGEXP)&.captures&.first || spec.to_s
+  end
+  # The spec that asks a CDN for +key+ at +version+. A version belongs on the
+  # package name, ahead of the subpath: "photoswipe/lightbox" at "@5.4.4" is
+  # "photoswipe@5.4.4/lightbox", where "photoswipe/lightbox@5.4.4" is a path
+  # no CDN has.
+  def package_spec_for(key, version)
+    name, _requested, subpath = key.to_s.match(PACKAGE_SPEC_REGEXP)&.captures
+    name ? "#{name}#{version}#{subpath}" : "#{key}#{version}"
+  end
   def remove_existing_package_file(package)
     FileUtils.rm_rf vendored_package_path(package)
   end
@@ -225,6 +307,43 @@ class Importmap::Packager
   end
   private
+    def provenance_of(line)
+      match = line&.match(PIN_PROVENANCE_REGEXP)
+      return unless match
+      details  = match[2].to_s.split(",").map(&:strip)
+      minified = details.delete("minified") ? true : false
+      locked   = without_lock(details).size != details.size
+      { version: match[1], provider: without_lock(details).first, minified: minified, locked: locked }
+    end
+    def without_lock(details)
+      details.reject { |detail| detail.match?(LOCK_DETAIL_REGEXP) }
+    end
+    # " # @3.7.2 (esm.run, minified, locked)" — the details in their fixed
+    # order, the parens only when there is something to say.
+    def provenance_comment(version, provider: nil, minified: false, locked: false)
+      details = []
+      details << provider if provider && provider != DEFAULT_PROVIDER
+      details << "minified" if minified
+      details << LOCK_DETAIL if locked
+      %( # @#{version.to_s.delete_prefix("@")}) + (details.any? ? %( (#{details.join(", ")})) : "")
+    end
+    # Rewrites only the version comment of +line+, handing the block the
+    # current details and writing back what it returns.
+    def rewrite_provenance(line)
+      line.sub(PIN_PROVENANCE_REGEXP) do
+        version = $1
+        details = yield($2.to_s.split(",").map(&:strip))
+        "# @#{version}" + (details.any? ? " (#{details.join(", ")})" : "")
+      end
+    end
     def build_package_options_lookup(lines)
       lines.each_with_object({}) do |line, package_options|
         match = line.strip.match(PIN_REGEX)
@@ -243,6 +362,10 @@ class Importmap::Packager
             options[:to] = to_match[1]
           end
+          if (integrity_match = options_part.match(INTEGRITY_OPTION_REGEXP))
+            options[:integrity] = integrity_match[1] == "true"
+          end
           package_options[package_name] = options if options.any?
         end
       end

data/lib/importmap/version.rb CHANGED Viewed

@@ -1,6 +1,6 @@
 module Importmap
   # importmap-plus versions independently of the importmap-rails it forks.
   # UPSTREAM_VERSION is the importmap-rails release this tracks.
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
   UPSTREAM_VERSION = "2.2.3"
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: importmap-plus
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - David Heinemeier Hansson
@@ -54,8 +54,9 @@ dependencies:
         version: 6.0.0
 description: 'A drop-in replacement for importmap-rails. Same Importmap:: API, same
   pins, same import map, plus `bin/importmap pin --minify`, `--from esm.run` for jsDelivr''s
-  bundled builds, and a pin comment that records the CDN and minification so later
-  updates keep them. Use this gem or importmap-rails, never both.'
+  bundled builds, `--lock` to hold a package at a version, and a pin comment that
+  records the CDN, minification and lock so later updates keep them. Use this gem
+  or importmap-rails, never both.'
 email: mikael@mhenrixon.com
 executables: []
 extensions: []
@@ -103,8 +104,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.6.9
 specification_version: 4
-summary: importmap-rails with vendoring that minifies, bundles from esm.run, and remembers
-  where each package came from.
+summary: importmap-rails with vendoring that minifies, bundles from esm.run, locks
+  versions, and remembers where each package came from.
 test_files: []