importmap-plus 1.0.0

data/lib/importmap/map.rb

@@ -0,0 +1,319 @@
+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 StandardError => e
+        Rails.logger.error "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)
+    end
+
+    self
+  end
+
+  # 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
+    @integrity = true
+  end
+
+  def pin(name, to: nil, preload: true, integrity: true)
+    clear_cache
+    @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
+  # `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
+
+  # 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
+
+  # Returns a SHA1 digest of the import map json that can be used as a part of a page etag to
+  # ensure that a html cache is invalidated when the import map is changed.
+  #
+  # Example:
+  #
+  #   class ApplicationController < ActionController::Base
+  #     etag { Rails.application.importmap.digest(resolver: helpers) if request.format&.html? }
+  #   end
+  def digest(resolver:)
+    Digest::SHA1.hexdigest(to_json(resolver: resolver).to_s)
+  end
+
+  # 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)
+    if watches
+      @cache_sweeper =
+        Rails.application.config.file_watcher.new([], Array(watches).collect { |dir| [ dir.to_s, "js"] }.to_h) do
+          clear_cache
+        end
+    else
+      @cache_sweeper
+    end
+  end
+
+  private
+    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]
+        result
+      else
+        @cache[name.to_s] = yield
+      end
+    end
+
+    def clear_cache
+      @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|
+        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
+
+    def expanded_packages_and_directories
+      @packages.dup.tap { |expanded| expand_directories_into expanded }
+    end
+
+    def expand_directories_into(paths)
+      @directories.values.each do |mapping|
+        if (absolute_path = absolute_root_of(mapping.dir)).exist?
+          find_javascript_files_in_tree(absolute_path).each do |filename|
+            module_filename = filename.relative_path_from(absolute_path)
+            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,
+              integrity: mapping.integrity
+            )
+          end
+        end
+      end
+    end
+
+    def module_name_from(filename, mapping)
+      # 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.reject(&:empty?).join("/")
+    end
+
+    def find_javascript_files_in_tree(path)
+      Dir[path.join("**/*.js{,m}")].sort.collect { |file| Pathname.new(file) }.select(&:file?)
+    end
+
+    def absolute_root_of(path)
+      (pathname = Pathname.new(path)).absolute? ? pathname : Rails.root.join(path)
+    end
+end

data/lib/importmap/minifier.rb

@@ -0,0 +1,76 @@
+require "open3"
+require "tmpdir"
+
+# Minifies a vendored package with whichever JavaScript minifier is installed:
+# bun, esbuild or terser, looked up in node_modules/.bin and then on PATH.
+# Every tool runs in transform-only mode, so bare import specifiers are left
+# exactly as the CDN resolved them and the import map keeps working.
+class Importmap::Minifier
+  Error = Class.new(StandardError)
+
+  TOOLS = {
+    "bun"     => ->(input, output) { [ "build", "--no-bundle", "--minify", "--format=esm", "--target=browser", input, "--outfile=#{output}" ] },
+    "esbuild" => ->(input, output) { [ input, "--minify", "--format=esm", "--outfile=#{output}" ] },
+    "terser"  => ->(input, output) { [ input, "--module", "--compress", "--mangle", "--output", output ] }
+  }.freeze # :nodoc:
+
+  class << self
+    def detect
+      TOOLS.keys.find { |tool| executable_for(tool) }
+    end
+
+    def available?
+      !detect.nil?
+    end
+
+    def executable_for(tool)
+      directories = [ File.expand_path(File.join("node_modules", ".bin")), *ENV["PATH"].to_s.split(File::PATH_SEPARATOR) ]
+
+      directories.each do |directory|
+        command_extensions.each do |extension|
+          candidate = File.join(directory, "#{tool}#{extension}")
+          return candidate if File.file?(candidate) && File.executable?(candidate)
+        end
+      end
+
+      nil
+    end
+
+    # On Windows npm installs these tools as .cmd shims, so the bare name
+    # never resolves. Elsewhere the extensionless name is the only candidate.
+    def command_extensions
+      return [ "" ] unless Gem.win_platform?
+
+      [ "", *ENV.fetch("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";") ]
+    end
+  end
+
+  attr_reader :tool
+
+  # Pass a tool name to force one, or nothing to use the first one found.
+  def initialize(tool = :auto)
+    @tool = tool == :auto ? self.class.detect : tool&.to_s
+  end
+
+  def call(source)
+    executable = tool && self.class.executable_for(tool)
+
+    unless executable
+      raise Error, "No JavaScript minifier found: install bun, esbuild or terser (globally or in node_modules/.bin)"
+    end
+
+    Dir.mktmpdir("importmap-minify") do |directory|
+      input  = File.join(directory, "package.js")
+      output = File.join(directory, "package.min.js")
+      File.write(input, source)
+
+      _stdout, stderr, status = Open3.capture3(executable, *TOOLS.fetch(tool).call(input, output))
+
+      unless status.success? && File.exist?(output)
+        raise Error, "#{tool} failed to minify: #{stderr.strip}"
+      end
+
+      File.read(output)
+    end
+  end
+end

data/lib/importmap/npm.rb

@@ -0,0 +1,189 @@
+require "net/http"
+require "uri"
+require "json"
+require "importmap/http_retries"
+
+class Importmap::Npm
+  include Importmap::HttpRetries
+
+  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", 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)
+
+      if !(response = get_package(package))
+        outdated_package.error = 'Response error'
+      elsif (error = response['error'])
+        outdated_package.error = error
+      else
+        latest_version = find_latest_version(response)
+        next unless outdated?(current_version, latest_version)
+
+        outdated_package.latest_version = latest_version
+      end
+
+      outdated_packages << outdated_package
+    end.sort_by(&:name)
+  end
+
+  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']
+        )
+      end
+    end.sort_by { |p| [p.name, p.severity] }
+  end
+
+  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!
+
+    vendored_packages_without_version(with_versions).each do |package, path|
+      $stdout.puts "Ignoring #{package} (#{path}) since no version is specified in the importmap"
+    end
+
+    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
+
+    def get_package(package)
+      uri = self.class.base_uri.dup
+      uri.path = "/" + package
+      response = get_json(uri)
+
+      JSON.parse(response)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def get_json(uri)
+      request = Net::HTTP::Get.new(uri)
+      request["Content-Type"] = "application/json"
+
+      response = begin
+        with_retries("fetching #{uri}") do
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
+            http.request(request)
+          }
+        end
+      rescue HTTPError
+        raise
+      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
+    end
+
+    def find_latest_version(response)
+      latest_version = response.is_a?(String) ? response : response.dig('dist-tags', 'latest')
+      return latest_version if latest_version
+
+      return unless response['versions']
+
+      response['versions'].keys.map { |v| Gem::Version.new(v) rescue nil }.compact.sort.last
+    end
+
+    def outdated?(current_version, latest_version)
+      Gem::Version.new(current_version) < Gem::Version.new(latest_version)
+    rescue ArgumentError
+      current_version.to_s < latest_version.to_s
+    end
+
+    def get_audit
+      uri = self.class.base_uri.dup
+      uri.path = "/-/npm/v1/security/advisories/bulk"
+
+      body = packages_with_versions.each.with_object({}) { |(package, version), data|
+        data[package] ||= []
+        data[package] << version
+      }
+      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
+
+    def post_json(uri, body)
+      with_retries("posting to #{uri}") do
+        Net::HTTP.post(uri, body.to_json, "Content-Type" => "application/json")
+      end
+    rescue HTTPError
+      raise
+    rescue => error
+      raise HTTPError, "Unexpected transport error (#{error.class}: #{error.message})"
+    end
+
+    def extract_base_package_name(package)
+      if package.start_with?("@")
+        # Scoped packages can have nested paths, e.g. @scope/package/subpath
+        parts = package.split("/", 3)
+        parts.size > 2 ? parts.first(2).join("/") : package
+      else
+        # Non-scoped packages - just take the first part
+        package.split("/").first
+      end
+    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