importmap-rails 2.1.0 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24bbd66810fcdeffe321841aa86a4308b0fa76749e9ec20105f8d74475634aa7
-  data.tar.gz: ea19b79e7701a7aafd6fe546edc88880aa5e68858999959d8e52005ce0be5a34
+  metadata.gz: 91837e96107f59efa73a314dec3955a488f9f40826c27e116da43c5d9ef0a44a
+  data.tar.gz: ce9d44539cd6bb86b1e027c9c714dc8274b4a7b918ee0a67493b79b9eb58103f
 SHA512:
-  metadata.gz: 741aab3cb6747eba7daf39dd5d311c126dfccfb55132c68d1e1cdaafe2b84a9e2596ea4746446cf6f1702d851a109cae3413b97a233889cd8855e347098ee592
-  data.tar.gz: 3b9ed94a737134bbfcd8be54f95fa5094539b2b6d56b7365362bdf7ac961bb1e727cef396eca0001629d45e2c50578c3af819559a521829f41b4e875733d3e80
+  metadata.gz: 95a4d846c8a808b8037e2425ad307e1cecd736051053e86f5c9739f9118375d81e0e967f64be3f6cee916d0ce7ca763fd7b236684f9b0889679b62f5718643a0
+  data.tar.gz: 5e20ed5b2d79945a603db1cf6e0e5d694a8a7ad7b96f5bb13e6e1083225034fcbf7ba2019acf397b004345bd4d54827895b9e4ffd5c831eb1fdfc2c051dcb063

data/README.md

@@ -44,7 +44,7 @@ import React from "./node_modules/react"
 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"` 
+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:
@@ -54,11 +54,11 @@ For example:
 pin "react", to: "https://ga.jspm.io/npm:react@17.0.2/index.js"
 ```
 
-means "everytime you see `import React from "react"` 
+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 "react"
 // => import React from "https://ga.jspm.io/npm:react@17.0.2/index.js"
 ```
 
@@ -79,10 +79,16 @@ If you want to import local js module files from `app/javascript/src` or other s
 ```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
@@ -97,19 +103,29 @@ Note: Sprockets used to serve assets (albeit without filename digests) it couldn
 
 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. 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. It can resolve these dependencies from JSPM itself, but also from other CDNs, like [unpkg.com](https://unpkg.com) and [jsdelivr.com](https://www.jsdelivr.com).
+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/react.js via download from https://ga.jspm.io/npm:react@17.0.2/index.js
-Pinning "object-assign" to vendor/object-assign.js via download from https://ga.jspm.io/npm:object-assign@4.1.1/index.js
+Pinning "react" to vendor/javascript/react.js via download from https://ga.jspm.io/npm:react@19.1.0/index.js
 ```
 
-This will produce pins in your `config/importmap.rb` like so:
+This will produce a pin in your `config/importmap.rb` like so:
 
 ```ruby
-pin "react" # https://ga.jspm.io/npm:react@17.0.2/index.js
-pin "object-assign" # https://ga.jspm.io/npm:object-assign@4.1.1/index.js
+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.
@@ -119,9 +135,92 @@ If you later wish to remove a downloaded pin:
 ```bash
 ./bin/importmap unpin react
 Unpinning and removing "react"
-Unpinning and removing "object-assign"
 ```
 
+## 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.
@@ -208,7 +307,7 @@ Pin your js file:
 pin "checkout", preload: false
 ```
 
-Import your module on the specific page. Note: you'll likely want to use a `content_for` block on the specifc page/partial, then yield it in your layout.
+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 %>

data/app/helpers/importmap/importmap_tags_helper.rb

@@ -25,13 +25,23 @@ module Importmap::ImportmapTagsHelper
   # (defaults to Rails.application.importmap), such that they'll be fetched
   # in advance by browsers supporting this link type (https://caniuse.com/?search=modulepreload).
   def javascript_importmap_module_preload_tags(importmap = Rails.application.importmap, entry_point: "application")
-    javascript_module_preload_tag(*importmap.preloaded_module_paths(resolver: self, entry_point:, cache_key: entry_point))
+    packages = importmap.preloaded_module_packages(resolver: self, entry_point:, cache_key: entry_point)
+
+    _generate_preload_tags(packages) { |path, package| [path, { integrity: package.integrity }] }
   end
 
   # Link tag(s) for preloading the JavaScript module residing in `*paths`. Will return one link tag per path element.
   def javascript_module_preload_tag(*paths)
-    safe_join(Array(paths).collect { |path|
-      tag.link rel: "modulepreload", href: path, nonce: request&.content_security_policy_nonce
-    }, "\n")
+    _generate_preload_tags(paths) { |path| [path, {}] }
   end
+
+  private
+    def _generate_preload_tags(items)
+      content_security_policy_nonce = request&.content_security_policy_nonce
+
+      safe_join(Array(items).collect { |item|
+        path, options = yield(item)
+        tag.link rel: "modulepreload", href: path, nonce: content_security_policy_nonce, **options
+      }, "\n")
+    end
 end

data/lib/importmap/commands.rb

@@ -12,21 +12,10 @@ class Importmap::Commands < Thor
   desc "pin [*PACKAGES]", "Pin new packages"
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
+  option :preload, type: :string, repeatable: true, desc: "Can be used multiple times"
   def pin(*packages)
-    if imports = packager.import(*packages, env: options[:env], from: options[:from])
-      imports.each do |package, url|
-        puts %(Pinning "#{package}" to #{packager.vendor_path}/#{package}.js via download from #{url})
-        packager.download(package, url)
-        pin = packager.vendored_pin_for(package, url)
-
-        if packager.packaged?(package)
-          gsub_file("config/importmap.rb", /^pin "#{package}".*$/, pin, verbose: false)
-        else
-          append_to_file("config/importmap.rb", "#{pin}\n", verbose: false)
-        end
-      end
-    else
-      puts "Couldn't find any packages in #{packages.inspect} on #{options[:from]}"
+    for_each_import(packages, env: options[:env], from: options[:from]) do |package, url|
+      pin_package(package, url, options[:preload])
     end
   end
 
@@ -34,15 +23,11 @@ class Importmap::Commands < Thor
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
   def unpin(*packages)
-    if imports = packager.import(*packages, env: options[:env], from: options[:from])
-      imports.each do |package, url|
-        if packager.packaged?(package)
-          puts %(Unpinning and removing "#{package}")
-          packager.remove(package)
-        end
+    for_each_import(packages, env: options[:env], from: options[:from]) do |package, url|
+      if packager.packaged?(package)
+        puts %(Unpinning and removing "#{package}")
+        packager.remove(package)
       end
-    else
-      puts "Couldn't find any packages in #{packages.inspect} on #{options[:from]}"
     end
   end
 
@@ -50,17 +35,12 @@ class Importmap::Commands < Thor
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
   def pristine
-    packages = npm.packages_with_versions.map do |p, v|
-      v.blank? ? p : [p, v].join("@")
-    end
+    packages = prepare_packages_with_versions
 
-    if imports = packager.import(*packages, env: options[:env], from: options[:from])
-      imports.each do |package, url|
-        puts %(Downloading "#{package}" to #{packager.vendor_path}/#{package}.js from #{url})
-        packager.download(package, url)
-      end
-    else
-      puts "Couldn't find any packages in #{packages.inspect} on #{options[:from]}"
+    for_each_import(packages, env: options[:env], from: options[:from]) do |package, url|
+      puts %(Downloading "#{package}" to #{packager.vendor_path}/#{package}.js from #{url})
+
+      packager.download(package, url)
     end
   end
 
@@ -110,7 +90,14 @@ class Importmap::Commands < Thor
   desc "update", "Update outdated package pins"
   def update
     if (outdated_packages = npm.outdated_packages).any?
-      pin(*outdated_packages.map(&:name))
+      package_names = outdated_packages.map(&:name)
+      packages_with_options = packager.extract_existing_pin_options(package_names)
+
+      for_each_import(package_names, env: "production", from: "jspm") do |package, url|
+        options = packages_with_options[package] || {}
+
+        pin_package(package, url, options[:preload])
+      end
     else
       puts "No outdated packages found"
     end
@@ -130,6 +117,30 @@ class Importmap::Commands < Thor
       @npm ||= Importmap::Npm.new
     end
 
+    def pin_package(package, url, preload)
+      puts %(Pinning "#{package}" to #{packager.vendor_path}/#{package}.js via download from #{url})
+
+      packager.download(package, url)
+
+      pin = packager.vendored_pin_for(package, url, preload)
+
+      update_importmap_with_pin(package, pin)
+    end
+
+    def update_importmap_with_pin(package, pin)
+      new_pin = "#{pin}\n"
+
+      if packager.packaged?(package)
+        gsub_file("config/importmap.rb", Importmap::Map.pin_line_regexp_for(package), pin, verbose: false)
+      else
+        append_to_file("config/importmap.rb", new_pin, verbose: false)
+      end
+    end
+
+    def handle_package_not_found(packages, from)
+      puts "Couldn't find any packages in #{packages.inspect} on #{from}"
+    end
+
     def remove_line_from_file(path, pattern)
       path = File.expand_path(path, destination_root)
 
@@ -154,6 +165,26 @@ class Importmap::Commands < Thor
         puts divider if row_number == 0
       end
     end
+
+    def prepare_packages_with_versions(packages = [])
+      if packages.empty?
+        npm.packages_with_versions.map do |p, v|
+          v.blank? ? p : [p, v].join("@")
+        end
+      else
+        packages
+      end
+    end
+
+    def for_each_import(packages, **options, &block)
+      response = packager.import(*packages, **options)
+
+      if response
+        response[:imports].each(&block)
+      else
+        handle_package_not_found(packages, options[:from])
+      end
+    end
 end
 
 Importmap::Commands.start(ARGV)

data/lib/importmap/map.rb

@@ -3,9 +3,16 @@ require "pathname"
 class Importmap::Map
   attr_reader :packages, :directories
 
+  PIN_REGEX = /^pin\s+["']([^"']+)["']/.freeze # :nodoc:
+
+  def self.pin_line_regexp_for(package) # :nodoc:
+    /^.*pin\s+["']#{Regexp.escape(package)}["'].*$/.freeze
+  end
+
   class InvalidFile < StandardError; end
 
   def initialize
+    @integrity = false
     @packages, @directories = {}, {}
     @cache = {}
   end
@@ -25,14 +32,51 @@ class Importmap::Map
     self
   end
 
-  def pin(name, to: nil, preload: true)
+  # Enables automatic integrity hash calculation for all pinned modules.
+  #
+  # When enabled, integrity values are included in the importmap JSON for all
+  # pinned modules. For local assets served by the Rails asset pipeline,
+  # integrity hashes are automatically calculated when +integrity: true+ is
+  # specified. For modules with explicit integrity values, those values are
+  # included as provided. This provides Subresource Integrity (SRI) protection
+  # to ensure JavaScript modules haven't been tampered with.
+  #
+  # Clears the importmap cache when called to ensure fresh integrity hashes
+  # are generated.
+  #
+  # ==== Examples
+  #
+  #   # config/importmap.rb
+  #   enable_integrity!
+  #
+  #   # These will now auto-calculate integrity hashes
+  #   pin "application"                   # integrity: true by default
+  #   pin "admin", to: "admin.js"         # integrity: true by default
+  #   pin_all_from "app/javascript/lib"   # integrity: true by default
+  #
+  #   # Manual control still works
+  #   pin "no_integrity", integrity: false
+  #   pin "custom_hash", integrity: "sha384-abc123..."
+  #
+  # ==== Notes
+  #
+  # * Integrity calculation is disabled by default and must be explicitly enabled
+  # * Requires asset pipeline support for integrity calculation (Sprockets or Propshaft 1.2+)
+  # * For Propshaft, you must configure +config.assets.integrity_hash_algorithm+
+  # * External CDN packages should provide their own integrity hashes
+  def enable_integrity!
     clear_cache
-    @packages[name] = MappedFile.new(name: name, path: to || "#{name}.js", preload: preload)
+    @integrity = true
   end
 
-  def pin_all_from(dir, under: nil, to: nil, preload: true)
+  def pin(name, to: nil, preload: true, integrity: true)
     clear_cache
-    @directories[dir] = MappedDir.new(dir: dir, under: under, path: to, preload: preload)
+    @packages[name] = MappedFile.new(name: name, path: to || "#{name}.js", preload: preload, integrity: integrity)
+  end
+
+  def pin_all_from(dir, under: nil, to: nil, preload: true, integrity: true)
+    clear_cache
+    @directories[dir] = MappedDir.new(dir: dir, under: under, path: to, preload: preload, integrity: integrity)
   end
 
   # Returns an array of all the resolved module paths of the pinned packages. The `resolver` must respond to
@@ -41,8 +85,72 @@ class Importmap::Map
   # resolve for different asset hosts, you can pass in a custom `cache_key` to vary the cache used by this method for
   # the different cases.
   def preloaded_module_paths(resolver:, entry_point: "application", cache_key: :preloaded_module_paths)
+    preloaded_module_packages(resolver: resolver, entry_point: entry_point, cache_key: cache_key).keys
+  end
+
+  # Returns a hash of resolved module paths to their corresponding package objects for all pinned packages
+  # that are marked for preloading. The hash keys are the resolved asset paths, and the values are the
+  # +MappedFile+ objects containing package metadata including name, path, preload setting, and integrity.
+  #
+  # The +resolver+ must respond to +path_to_asset+, such as +ActionController::Base.helpers+ or
+  # +ApplicationController.helpers+. You'll want to use the resolver that has been configured for the
+  # +asset_host+ you want these resolved paths to use.
+  #
+  # ==== Parameters
+  #
+  # [+resolver+]
+  #   An object that responds to +path_to_asset+ for resolving asset paths.
+  #
+  # [+entry_point+]
+  #   The entry point name or array of entry point names to determine which packages should be preloaded.
+  #   Defaults to +"application"+. Packages with +preload: true+ are always included regardless of entry point.
+  #   Packages with specific entry point names (e.g., +preload: "admin"+) are only included when that entry
+  #   point is specified.
+  #
+  # [+cache_key+]
+  #   A custom cache key to vary the cache used by this method for different cases, such as resolving
+  #   for different asset hosts. Defaults to +:preloaded_module_packages+.
+  #
+  # ==== Returns
+  #
+  # A hash where:
+  # * Keys are resolved asset paths (strings)
+  # * Values are +MappedFile+ objects with +name+, +path+, +preload+, and +integrity+ attributes
+  #
+  # Missing assets are gracefully handled and excluded from the returned hash.
+  #
+  # ==== Examples
+  #
+  #   # Get all preloaded packages for the default "application" entry point
+  #   packages = importmap.preloaded_module_packages(resolver: ApplicationController.helpers)
+  #   # => { "/assets/application-abc123.js" => #<struct name="application", path="application.js", preload=true, integrity=nil>,
+  #   #      "https://cdn.skypack.dev/react" => #<struct name="react", path="https://cdn.skypack.dev/react", preload=true, integrity="sha384-..."> }
+  #
+  #   # Get preloaded packages for a specific entry point
+  #   packages = importmap.preloaded_module_packages(resolver: helpers, entry_point: "admin")
+  #
+  #   # Get preloaded packages for multiple entry points
+  #   packages = importmap.preloaded_module_packages(resolver: helpers, entry_point: ["application", "admin"])
+  #
+  #   # Use a custom cache key for different asset hosts
+  #   packages = importmap.preloaded_module_packages(resolver: helpers, cache_key: "cdn_host")
+  def preloaded_module_packages(resolver:, entry_point: "application", cache_key: :preloaded_module_packages)
     cache_as(cache_key) do
-      resolve_asset_paths(expanded_preloading_packages_and_directories(entry_point:), resolver:).values
+      expanded_preloading_packages_and_directories(entry_point:).filter_map do |_, package|
+        resolved_path = resolve_asset_path(package.path, resolver: resolver)
+        next unless resolved_path
+
+        resolved_integrity = resolve_integrity_value(package.integrity, package.path, resolver: resolver)
+
+        package = MappedFile.new(
+          name: package.name,
+          path: package.path,
+          preload: package.preload,
+          integrity: resolved_integrity
+        )
+
+        [resolved_path, package]
+      end.to_h
     end
   end
 
@@ -53,7 +161,9 @@ class Importmap::Map
   # `cache_key` to vary the cache used by this method for the different cases.
   def to_json(resolver:, cache_key: :json)
     cache_as(cache_key) do
-      JSON.pretty_generate({ "imports" => resolve_asset_paths(expanded_packages_and_directories, resolver: resolver) })
+      packages = expanded_packages_and_directories
+      map = build_import_map(packages, resolver: resolver)
+      JSON.pretty_generate(map)
     end
   end
 
@@ -84,8 +194,8 @@ class Importmap::Map
   end
 
   private
-    MappedDir  = Struct.new(:dir, :path, :under, :preload, keyword_init: true)
-    MappedFile = Struct.new(:name, :path, :preload, keyword_init: true)
+    MappedDir  = Struct.new(:dir, :path, :under, :preload, :integrity, keyword_init: true)
+    MappedFile = Struct.new(:name, :path, :preload, :integrity, keyword_init: true)
 
     def cache_as(name)
       if result = @cache[name.to_s]
@@ -105,19 +215,55 @@ class Importmap::Map
 
     def resolve_asset_paths(paths, resolver:)
       paths.transform_values do |mapping|
-        begin
-          resolver.path_to_asset(mapping.path)
-        rescue => e
-          if rescuable_asset_error?(e)
-            Rails.logger.warn "Importmap skipped missing path: #{mapping.path}"
-            nil
-          else
-            raise e
-          end
-        end
+        resolve_asset_path(mapping.path, resolver:)
       end.compact
     end
 
+    def resolve_asset_path(path, resolver:)
+      begin
+        resolver.path_to_asset(path)
+      rescue => e
+        if rescuable_asset_error?(e)
+          Rails.logger.warn "Importmap skipped missing path: #{path}"
+          nil
+        else
+          raise e
+        end
+      end
+    end
+
+    def build_import_map(packages, resolver:)
+      map = { "imports" => resolve_asset_paths(packages, resolver: resolver) }
+      integrity = build_integrity_hash(packages, resolver: resolver)
+      map["integrity"] = integrity unless integrity.empty?
+      map
+    end
+
+    def build_integrity_hash(packages, resolver:)
+      packages.filter_map do |name, mapping|
+        next unless mapping.integrity
+
+        resolved_path = resolve_asset_path(mapping.path, resolver: resolver)
+        next unless resolved_path
+
+        integrity_value = resolve_integrity_value(mapping.integrity, mapping.path, resolver: resolver)
+        next unless integrity_value
+
+        [resolved_path, integrity_value]
+      end.to_h
+    end
+
+    def resolve_integrity_value(integrity, path, resolver:)
+      return unless @integrity
+
+      case integrity
+      when true
+        resolver.asset_integrity(path) if resolver.respond_to?(:asset_integrity)
+      when String
+        integrity
+      end
+    end
+
     def expanded_preloading_packages_and_directories(entry_point:)
       expanded_packages_and_directories.select { |name, mapping| mapping.preload.in?([true, false]) ? mapping.preload : (Array(mapping.preload) & Array(entry_point)).any? }
     end
@@ -134,7 +280,12 @@ class Importmap::Map
             module_name     = module_name_from(module_filename, mapping)
             module_path     = module_path_from(module_filename, mapping)
 
-            paths[module_name] = MappedFile.new(name: module_name, path: module_path, preload: mapping.preload)
+            paths[module_name] = MappedFile.new(
+              name: module_name,
+              path: module_path,
+              preload: mapping.preload,
+              integrity: mapping.integrity
+            )
           end
         end
       end

data/lib/importmap/npm.rb

@@ -3,20 +3,22 @@ require "uri"
 require "json"
 
 class Importmap::Npm
+  PIN_REGEX = /#{Importmap::Map::PIN_REGEX}.*/.freeze # :nodoc:
+
   Error     = Class.new(StandardError)
   HTTPError = Class.new(Error)
 
   singleton_class.attr_accessor :base_uri
   self.base_uri = URI("https://registry.npmjs.org")
 
-  def initialize(importmap_path = "config/importmap.rb")
+  def initialize(importmap_path = "config/importmap.rb", vendor_path: "vendor/javascript")
     @importmap_path = Pathname.new(importmap_path)
+    @vendor_path    = Pathname.new(vendor_path)
   end
 
   def outdated_packages
-    packages_with_versions.each.with_object([]) do |(package, current_version), outdated_packages|
-      outdated_package = OutdatedPackage.new(name: package,
-                                             current_version: current_version)
+    packages_with_versions.each_with_object([]) do |(package, current_version), outdated_packages|
+      outdated_package = OutdatedPackage.new(name: package, current_version: current_version)
 
       if !(response = get_package(package))
         outdated_package.error = 'Response error'
@@ -36,10 +38,12 @@ class Importmap::Npm
   def vulnerable_packages
     get_audit.flat_map do |package, vulnerabilities|
       vulnerabilities.map do |vulnerability|
-        VulnerablePackage.new(name: package,
-                              severity: vulnerability['severity'],
-                              vulnerable_versions: vulnerability['vulnerable_versions'],
-                              vulnerability: vulnerability['title'])
+        VulnerablePackage.new(
+          name: package,
+          severity: vulnerability['severity'],
+          vulnerable_versions: vulnerability['vulnerable_versions'],
+          vulnerability: vulnerability['title']
+        )
       end
     end.sort_by { |p| [p.name, p.severity] }
   end
@@ -47,17 +51,20 @@ class Importmap::Npm
   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\/)([^@\/]+)@(\d+\.\d+\.\d+(?:[^\/\s"']*))/) |
+      importmap.scan(/#{PIN_REGEX} #.*@(\d+\.\d+\.\d+(?:[^\s]*)).*$/)
+
+    vendored_packages_without_version(with_versions).each do |package, path|
+      $stdout.puts "Ignoring #{package} (#{path}) since no version is specified in the importmap"
+    end
 
-    importmap.scan(/^pin .*(?<=npm:|npm\/|skypack\.dev\/|unpkg\.com\/)(.*)(?=@\d+\.\d+\.\d+)@(\d+\.\d+\.\d+(?:[^\/\s["']]*)).*$/) |
-      importmap.scan(/^pin ["']([^["']]*)["'].* #.*@(\d+\.\d+\.\d+(?:[^\s]*)).*$/)
+    with_versions
   end
 
   private
     OutdatedPackage   = Struct.new(:name, :current_version, :latest_version, :error, keyword_init: true)
     VulnerablePackage = Struct.new(:name, :severity, :vulnerable_versions, :vulnerability, keyword_init: true)
 
-
-
     def importmap
       @importmap ||= File.read(@importmap_path)
     end
@@ -76,13 +83,19 @@ class Importmap::Npm
       request = Net::HTTP::Get.new(uri)
       request["Content-Type"] = "application/json"
 
-      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
-        http.request(request)
-      }
+      response = begin
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
+          http.request(request)
+        }
+      rescue => error
+        raise HTTPError, "Unexpected transport error (#{error.class}: #{error.message})"
+      end
+
+      unless response.code.to_i < 300
+        raise HTTPError, "Unexpected error response #{response.code}: #{response.body}"
+      end
 
       response.body
-    rescue => error
-      raise HTTPError, "Unexpected transport error (#{error.class}: #{error.message})"
     end
 
     def find_latest_version(response)
@@ -111,6 +124,11 @@ class Importmap::Npm
       return {} if body.empty?
 
       response = post_json(uri, body)
+
+      unless response.code.to_i < 300
+        raise HTTPError, "Unexpected error response #{response.code}: #{response.body}"
+      end
+
       JSON.parse(response.body)
     end
 
@@ -119,4 +137,27 @@ class Importmap::Npm
     rescue => error
       raise HTTPError, "Unexpected transport error (#{error.class}: #{error.message})"
     end
+
+    def vendored_packages_without_version(packages_with_versions)
+      versioned_packages = packages_with_versions.map(&:first).to_set
+
+      importmap
+        .lines
+        .filter_map { |line| find_unversioned_vendored_package(line, versioned_packages) }
+    end
+
+    def find_unversioned_vendored_package(line, versioned_packages)
+      regexp = line.include?("to:")? /#{PIN_REGEX}to: ["']([^"']*)["'].*/ : PIN_REGEX
+      match = line.match(regexp)
+
+      return unless match
+
+      package, filename = match.captures
+      filename ||= "#{package}.js"
+
+      return if versioned_packages.include?(package)
+
+      path = File.join(@vendor_path, filename)
+      [package, path] if File.exist?(path)
+    end
 end

data/lib/importmap/packager.rb

@@ -3,6 +3,9 @@ require "uri"
 require "json"
 
 class Importmap::Packager
+  PIN_REGEX = /#{Importmap::Map::PIN_REGEX}(.*)/.freeze # :nodoc:
+  PRELOAD_OPTION_REGEXP = /preload:\s*(\[[^\]]+\]|true|false|["'][^"']*["'])/.freeze # :nodoc:
+
   Error        = Class.new(StandardError)
   HTTPError    = Class.new(Error)
   ServiceError = Error.new(Error)
@@ -22,33 +25,36 @@ class Importmap::Packager
       "install"      => Array(packages),
       "flattenScope" => true,
       "env"          => [ "browser", "module", env ],
-      "provider"     => normalize_provider(from)
+      "provider"     => normalize_provider(from),
     })
 
     case response.code
-    when "200"        then extract_parsed_imports(response)
-    when "404", "401" then nil
-    else                   handle_failure_response(response)
+    when "200"
+      extract_parsed_response(response)
+    when "404", "401"
+      nil
+    else
+      handle_failure_response(response)
     end
   end
 
-  def pin_for(package, url)
-    %(pin "#{package}", to: "#{url}")
+  def pin_for(package, url = nil, preloads: nil)
+    to = url ? %(, to: "#{url}") : ""
+    preload_param = preload(preloads)
+
+     %(pin "#{package}") + to + preload_param
   end
 
-  def vendored_pin_for(package, url)
+  def vendored_pin_for(package, url, preloads = nil)
     filename = package_filename(package)
     version  = extract_package_version_from(url)
+    to = "#{package}.js" != filename ? filename : nil
 
-    if "#{package}.js" == filename
-      %(pin "#{package}" # #{version})
-    else
-      %(pin "#{package}", to: "#{filename}" # #{version})
-    end
+    pin_for(package, to, preloads: preloads) + %( # #{version})
   end
 
   def packaged?(package)
-    importmap.match(/^pin ["']#{package}["'].*$/)
+    importmap.match(Importmap::Map.pin_line_regexp_for(package))
   end
 
   def download(package, url)
@@ -62,7 +68,65 @@ class Importmap::Packager
     remove_package_from_importmap(package)
   end
 
+  def extract_existing_pin_options(packages)
+    return {} unless @importmap_path.exist?
+
+    packages = Array(packages)
+
+    all_package_options = build_package_options_lookup(importmap.lines)
+
+    packages.to_h do |package|
+      [package, all_package_options[package] || {}]
+    end
+  end
+
   private
+    def build_package_options_lookup(lines)
+      lines.each_with_object({}) do |line, package_options|
+        match = line.strip.match(PIN_REGEX)
+
+        if match
+          package_name = match[1]
+          options_part = match[2]
+
+          preload_match = options_part.match(PRELOAD_OPTION_REGEXP)
+
+          if preload_match
+            preload = preload_from_string(preload_match[1])
+            package_options[package_name] = { preload: preload }
+          end
+        end
+      end
+    end
+
+    def preload_from_string(value)
+      case value
+      when "true"
+        true
+      when "false"
+        false
+      when /^\[.*\]$/
+        JSON.parse(value)
+      else
+        value.gsub(/["']/, "")
+      end
+    end
+
+    def preload(preloads)
+      case Array(preloads)
+      in []
+        ""
+      in ["true"] | [true]
+        %(, preload: true)
+      in ["false"] | [false]
+        %(, preload: false)
+      in [string]
+        %(, preload: "#{string}")
+      else
+        %(, preload: #{preloads})
+      end
+    end
+
     def post_json(body)
       Net::HTTP.post(self.class.endpoint, body.to_json, "Content-Type" => "application/json")
     rescue => error
@@ -73,8 +137,13 @@ class Importmap::Packager
       name.to_s == "jspm" ? "jspm.io" : name.to_s
     end
 
-    def extract_parsed_imports(response)
-      JSON.parse(response.body).dig("map", "imports")
+    def extract_parsed_response(response)
+      parsed = JSON.parse(response.body)
+      imports = parsed.dig("map", "imports")
+
+      {
+        imports: imports,
+      }
     end
 
     def handle_failure_response(response)
@@ -106,7 +175,7 @@ class Importmap::Packager
 
     def remove_package_from_importmap(package)
       all_lines = File.readlines(@importmap_path)
-      with_lines_removed = all_lines.grep_v(/pin ["']#{package}["']/)
+      with_lines_removed = all_lines.grep_v(Importmap::Map.pin_line_regexp_for(package))
 
       File.open(@importmap_path, "w") do |file|
         with_lines_removed.each { |line| file.write(line) }

data/lib/importmap/version.rb

@@ -1,3 +1,3 @@
 module Importmap
-  VERSION = "2.1.0"
+  VERSION = "2.2.2"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: importmap-rails
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.2
 platform: ruby
 authors:
 - David Heinemeier Hansson
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-21 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -52,7 +51,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 6.0.0
-description:
 email: david@loudthinking.com
 executables: []
 extensions: []
@@ -81,7 +79,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/rails/importmap-rails
   source_code_uri: https://github.com/rails/importmap-rails
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -96,8 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Use ESM with importmap to manage modern JavaScript in Rails without transpiling
   or bundling.