importmap-rails 0.8.0 → 2.2.3

data/lib/importmap/commands.rb

@@ -1,5 +1,6 @@
 require "thor"
 require "importmap/packager"
+require "importmap/npm"
 
 class Importmap::Commands < Thor
   include Thor::Actions
@@ -7,53 +8,39 @@ class Importmap::Commands < Thor
   def self.exit_on_failure?
     false
   end
-  
+
   desc "pin [*PACKAGES]", "Pin new packages"
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
-  option :download, type: :boolean, aliases: :d, default: false
+  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|
-        if options[:download]
-          puts %(Pinning "#{package}" to vendor/#{package}.js via download from #{url})
-          packager.download(package, url)
-          pin = packager.vendored_pin_for(package, url)
-        else
-          puts %(Pinning "#{package}" to #{url})
-          pin = packager.pin_for(package, url)
-        end
-
-        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[:provider]}"
+    for_each_import(packages, env: options[:env], from: options[:from]) do |package, url|
+      pin_package(package, url, options[:preload])
     end
   end
 
   desc "unpin [*PACKAGES]", "Unpin existing packages"
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
-  option :download, type: :boolean, aliases: :d, default: false
   def unpin(*packages)
-    if imports = packager.import(*packages, env: options[:env], from: options[:from])
-      imports.each do |package, url|
-        if packager.packaged?(package)
-          if options[:download]
-            puts %(Unpinning and removing "#{package}")
-          else
-            puts %(Unpinning "#{package}")
-          end
-
-          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[:provider]}"
+    end
+  end
+
+  desc "pristine", "Redownload all pinned packages"
+  option :env, type: :string, aliases: :e, default: "production"
+  option :from, type: :string, aliases: :f, default: "jspm"
+  def pristine
+    packages = prepare_packages_with_versions
+
+    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
 
@@ -63,11 +50,97 @@ class Importmap::Commands < Thor
     puts Rails.application.importmap.to_json(resolver: ActionController::Base.helpers)
   end
 
+  desc "audit", "Run a security audit"
+  def audit
+    vulnerable_packages = npm.vulnerable_packages
+
+    if vulnerable_packages.any?
+      table = [["Package", "Severity", "Vulnerable versions", "Vulnerability"]]
+      vulnerable_packages.each { |p| table << [p.name, p.severity, p.vulnerable_versions, p.vulnerability] }
+
+      puts_table(table)
+      vulnerabilities = 'vulnerability'.pluralize(vulnerable_packages.size)
+      severities = vulnerable_packages.map(&:severity).tally.sort_by(&:last).reverse
+                                      .map { |severity, count| "#{count} #{severity}" }
+                                      .join(", ")
+      puts "  #{vulnerable_packages.size} #{vulnerabilities} found: #{severities}"
+
+      exit 1
+    else
+      puts "No vulnerable packages found"
+    end
+  end
+
+  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] }
+
+      puts_table(table)
+      packages = 'package'.pluralize(outdated_packages.size)
+      puts "  #{outdated_packages.size} outdated #{packages} found"
+
+      exit 1
+    else
+      puts "No outdated packages found"
+    end
+  end
+
+  desc "update", "Update outdated package pins"
+  def update
+    if (outdated_packages = npm.outdated_packages).any?
+      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
+  end
+
+  desc "packages", "Print out packages with version numbers"
+  def packages
+    puts npm.packages_with_versions.map { |x| x.join(' ') }
+  end
+
   private
     def packager
       @packager ||= Importmap::Packager.new
     end
 
+    def npm
+      @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)
 
@@ -78,6 +151,40 @@ class Importmap::Commands < Thor
         with_lines_removed.each { |line| file.write(line) }
       end
     end
+
+    def puts_table(array)
+      column_sizes = array.reduce([]) do |lengths, row|
+        row.each_with_index.map{ |iterand, index| [lengths[index] || 0, iterand.to_s.length].max }
+      end
+
+      divider = "|" + (column_sizes.map { |s| "-" * (s + 2) }.join('|')) + '|'
+      array.each_with_index do |row, row_number|
+        row = row.fill(nil, row.size..(column_sizes.size - 1))
+        row = row.each_with_index.map { |v, i| v.to_s + " " * (column_sizes[i] - v.to_s.length) }
+        puts "| " + row.join(" | ") + " |"
+        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/engine.rb

@@ -6,29 +6,34 @@ Rails::Application.send(:attr_accessor, :importmap)
 module Importmap
   class Engine < ::Rails::Engine
     config.importmap = ActiveSupport::OrderedOptions.new
+    config.importmap.paths = []
     config.importmap.sweep_cache = Rails.env.development? || Rails.env.test?
+    config.importmap.cache_sweepers = []
+    config.importmap.rescuable_asset_errors = []
 
-    config.autoload_once_paths = %W( #{root}/app/helpers )
+    config.autoload_once_paths = %W( #{root}/app/helpers #{root}/app/controllers )
 
     initializer "importmap" do |app|
-      app.importmap = Importmap::Map.new.draw("config/importmap.rb")
+      app.importmap = Importmap::Map.new
+      app.config.importmap.paths << app.root.join("config/importmap.rb")
+      app.config.importmap.paths.each { |path| app.importmap.draw(path) }
     end
 
     initializer "importmap.reloader" do |app|
-      app.config.paths.add "config/importmap.rb"
-
-      Importmap::Reloader.new.tap do |reloader|
-        reloader.execute
-        app.reloaders << reloader
-        app.reloader.to_run { reloader.execute }
+      unless app.config.cache_classes
+        Importmap::Reloader.new.tap do |reloader|
+          reloader.execute
+          app.reloaders << reloader
+          app.reloader.to_run { reloader.execute }
+        end
       end
     end
 
     initializer "importmap.cache_sweeper" do |app|
-      if app.config.importmap.sweep_cache
-        app.importmap.cache_sweeper watches: [ 
-          app.root.join("app/javascript"), app.root.join("vendor/javascript")
-        ]
+      if app.config.importmap.sweep_cache && !app.config.cache_classes
+        app.config.importmap.cache_sweepers << app.root.join("app/javascript")
+        app.config.importmap.cache_sweepers << app.root.join("vendor/javascript")
+        app.importmap.cache_sweeper(watches: app.config.importmap.cache_sweepers)
 
         ActiveSupport.on_load(:action_controller_base) do
           before_action { Rails.application.importmap.cache_sweeper.execute_if_updated }
@@ -36,11 +41,16 @@ module Importmap
       end
     end
 
-    initializer "importmap.assets" do
-      if Rails.application.config.respond_to?(:assets)
-        Rails.application.config.assets.precompile += %w( es-module-shims.js es-module-shims.min.js )
-        Rails.application.config.assets.paths << Rails.root.join("app/javascript")
-        Rails.application.config.assets.paths << Rails.root.join("vendor/javascript")
+    initializer "importmap.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << Rails.root.join("app/javascript")
+        app.config.assets.paths << Rails.root.join("vendor/javascript")
+      end
+    end
+
+    initializer "importmap.concerns" do
+      ActiveSupport.on_load(:action_controller_base) do
+        extend Importmap::Freshness
       end
     end
 
@@ -49,5 +59,15 @@ module Importmap
         helper Importmap::ImportmapTagsHelper
       end
     end
+
+    initializer "importmap.rescuable_asset_errors" do |app|
+      if defined?(Propshaft)
+        app.config.importmap.rescuable_asset_errors << Propshaft::MissingAssetError
+      end
+
+      if defined?(Sprockets::Rails)
+        app.config.importmap.rescuable_asset_errors << Sprockets::Rails::Helper::AssetNotFound
+      end
+    end
   end
 end

data/lib/importmap/map.rb

@@ -3,17 +3,27 @@ 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
 
   def draw(path = nil, &block)
     if path && File.exist?(path)
       begin
         instance_eval(File.read(path), path.to_s)
-      rescue Exception => e
+      rescue StandardError => e
         Rails.logger.error "Unable to parse import map from #{path}: #{e.message}"
-        raise "Unable to parse import map from #{path}: #{e.message}"
+        raise InvalidFile, "Unable to parse import map from #{path}: #{e.message}"
       end
     elsif block_given?
       instance_eval(&block)
@@ -22,25 +32,138 @@ class Importmap::Map
     self
   end
 
-  def pin(name, to: nil, preload: false)
+  # 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: false)
+  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 preloaded_module_paths(resolver:)
-    cache_as(:preloaded_module_paths) do
-      resolve_asset_paths(expanded_preloading_packages_and_directories, resolver: resolver).values
+  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
+  # `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. In case you need to
+  # 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
+      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
 
-  def to_json(resolver:)
-    cache_as(:json) do
-      JSON.pretty_generate({ "imports" => resolve_asset_paths(expanded_packages_and_directories, resolver: resolver) })
+  # Returns a JSON hash (as a string) of all the resolved module paths of the pinned packages in the import map format.
+  # 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. In case you need to 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 to_json(resolver:, cache_key: :json)
+    cache_as(cache_key) do
+      packages = expanded_packages_and_directories
+      map = build_import_map(packages, resolver: resolver)
+      JSON.pretty_generate(map)
     end
   end
 
@@ -56,7 +179,7 @@ class Importmap::Map
     Digest::SHA1.hexdigest(to_json(resolver: resolver).to_s)
   end
 
-  # Returns an instance ActiveSupport::EventedFileUpdateChecker configured to clear the cache of the map
+  # Returns an instance of ActiveSupport::EventedFileUpdateChecker configured to clear the cache of the map
   # when the directories passed on initialization via `watches:` have changes. This is used in development
   # and test to ensure the map caches are reset when javascript files are changed.
   def cache_sweeper(watches: nil)
@@ -71,35 +194,78 @@ 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 = instance_variable_get("@cached_#{name}")
+      if result = @cache[name.to_s]
         result
       else
-        instance_variable_set("@cached_#{name}", yield)
+        @cache[name.to_s] = yield
       end
     end
 
     def clear_cache
-      @cached_json = nil
-      @cached_preloaded_module_paths = nil
+      @cache.clear
+    end
+
+    def rescuable_asset_error?(error)
+      Rails.application.config.importmap.rescuable_asset_errors.any? { |e| error.is_a?(e) }
     end
 
     def resolve_asset_paths(paths, resolver:)
       paths.transform_values do |mapping|
-        begin
-          resolver.asset_path(mapping.path)
-        rescue Sprockets::Rails::Helper::AssetNotFound
-          Rails.logger.warn "Importmap skipped missing path: #{mapping.path}"
+        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.compact
+      end
     end
 
-    def expanded_preloading_packages_and_directories
-      expanded_packages_and_directories.select { |name, mapping| mapping.preload }
+    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
 
     def expanded_packages_and_directories
@@ -114,22 +280,37 @@ 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
     end
 
     def module_name_from(filename, mapping)
-      [ mapping.under, filename.to_s.remove(filename.extname).remove(/\/?index$/).presence ].compact.join("/")
+      # Regex explanation:
+      # (?:\/|^) # Matches either / OR the start of the string
+      # index   # Matches the word index
+      # $       # Matches the end of the string
+      #
+      # Sample matches
+      # index
+      # folder/index
+      index_regex = /(?:\/|^)index$/
+
+      [ mapping.under, filename.to_s.chomp(filename.extname).remove(index_regex).presence ].compact.join("/")
     end
 
     def module_path_from(filename, mapping)
-      [ mapping.path || mapping.under, filename.to_s ].compact.join("/")
+      [ mapping.path || mapping.under, filename.to_s ].compact.reject(&:empty?).join("/")
     end
 
     def find_javascript_files_in_tree(path)
-      Dir[path.join("**/*.js{,m}")].collect { |file| Pathname.new(file) }.select(&:file?)
+      Dir[path.join("**/*.js{,m}")].sort.collect { |file| Pathname.new(file) }.select(&:file?)
     end
 
     def absolute_root_of(path)