hanami-importmap 0.1.0

data/lib/hanami/importmap/cli/install.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "json"
+require "hanami/cli"
+require_relative "../packager"
+require_relative "importmap"
+
+module Hanami
+  module Importmap
+    module CLI
+      # `hanami importmap install`
+      #
+      # Switches an app (or slice) generated by `hanami new` from esbuild to import maps.
+      #
+      # @api private
+      class Install < Hanami::CLI::Commands::App::Command
+        include SlicePaths
+
+        desc "Switch the app (or a slice) from esbuild to import maps"
+
+        option :slice, required: false, desc: "Slice name"
+
+        # Matches the import of CSS into JS that only esbuild understands.
+        CSS_IMPORT = /^\s*import\s+["'][^"']+\.css["'];?\s*\n/
+        LAYOUT_SCRIPT = /^\s*<%=\s*javascript_tag[\s(]+["']app["']\)?\s*%>\s*\n/
+        APP_CLASS = /^(?<indent>\s*)class App < Hanami::App\n/
+        CSP_NONCE = <<~RUBY
+          # Import maps are inline <script> tags. Allow them with a per-request nonce, which
+          # `javascript_importmap_tags` adds for you.
+          config.actions.content_security_policy[:script_src] += " 'nonce'"
+        RUBY
+        NPM_SETUP = /^announce "\\nRunning npm install\.\.\."\nnpm install\n\n?/
+
+        def call(slice: nil, **)
+          require_in_app_config unless slice
+          write_importmap(slice)
+          update_entry_point(slice)
+          update_layout(slice)
+          remove_node_setup unless slice
+
+          stdout.puts <<~TEXT
+
+            Import maps are set up. Pin packages with `bundle exec hanami importmap pin <package>`,
+            and run `bin/dev` (or `bundle exec hanami assets compile`) to build them.
+          TEXT
+        end
+
+        private
+
+        # Requires the gem, and allows the import map's inline `<script>` tags under Hanami's default
+        # Content Security Policy (`script-src 'self'`). Adding `'nonce'` to a policy makes Hanami add
+        # its nonce middleware, and `javascript_importmap_tags` uses the request's nonce.
+        def require_in_app_config
+          path = "config/app.rb"
+          return unless fs.exist?(path)
+
+          content = fs.read(path)
+
+          unless content.include?(%(require "hanami/importmap"))
+            if content.match?(/^require "hanami"\n/)
+              content = content.sub(/^require "hanami"\n/) { "#{_1}require \"hanami/importmap\"\n" }
+            else
+              note "Add `require \"hanami/importmap\"` to #{path}"
+            end
+          end
+
+          unless content.include?("'nonce'")
+            if content.match?(APP_CLASS)
+              content = content.sub(APP_CLASS) {
+                match = $~
+                separator = match.post_match.match?(/\A\s*end\b/) ? "" : "\n"
+                "#{match[0]}#{CSP_NONCE.gsub(/^/, "#{match[:indent]}  ")}#{separator}"
+              }
+            else
+              note "Add 'nonce' to config.actions.content_security_policy[:script_src] in #{path}"
+            end
+          end
+
+          fs.write(path, content) unless content == fs.read(path)
+        end
+
+        def write_importmap(slice)
+          path = importmap_path(slice)
+          return note("#{path} already exists") if path.file?
+
+          fs.create(path.to_s, "#{Packager::IMPORTMAP_HEADER}\npin \"app\"\n")
+        end
+
+        def update_entry_point(slice)
+          path = assets_dir(slice).join("js", "app.js")
+
+          unless path.file?
+            fs.create(path.to_s, %(// The "app" pin in #{importmap_path(slice)} points here.\n))
+            return
+          end
+
+          content = path.read
+          return unless content.match?(CSS_IMPORT)
+
+          # Stylesheets load with `stylesheet_tag` in the layout; import maps only carry JavaScript.
+          content = content.gsub(CSS_IMPORT, "")
+          content = %(// The "app" pin in #{importmap_path(slice)} points here.\n) if content.strip.empty?
+          fs.write(path.to_s, content)
+        end
+
+        def update_layout(slice)
+          layout = (slice ? slice_root(slice) : Pathname("app")).join("templates", "layouts", "app.html.erb")
+          unless layout.file?
+            return note("Add `<%= javascript_importmap_tags %>` to your layout's <head>")
+          end
+
+          content = layout.read
+          return if content.include?("javascript_importmap_tags")
+
+          unless content.include?("</head>")
+            return note("Add `<%= javascript_importmap_tags %>` to #{layout}")
+          end
+
+          indent = content[/^(\s*)<\/head>/, 1].to_s
+          content = content
+            .sub(LAYOUT_SCRIPT, "")
+            .sub(/^#{indent}<\/head>/) { "#{indent}  <%= javascript_importmap_tags %>\n#{_1}" }
+
+          fs.write(layout.to_s, content)
+        end
+
+        # Removes the Node toolchain `hanami new` sets up, but only files that are still as generated.
+        def remove_node_setup
+          remove_if("config/assets.js") { stock_assets_js?(_1) }
+          removed_package = remove_if("package.json") { stock_package_json?(_1) }
+          remove_if("package-lock.json") { removed_package }
+
+          if fs.exist?("bin/setup") && fs.read("bin/setup").match?(NPM_SETUP)
+            fs.write("bin/setup", fs.read("bin/setup").sub(NPM_SETUP, ""))
+          end
+
+          note "You can delete node_modules/" if removed_package && fs.directory?("node_modules")
+        end
+
+        def remove_if(path)
+          return false unless fs.exist?(path)
+
+          if yield(fs.read(path))
+            fs.delete(path)
+            stdout.puts "      remove  #{path}"
+            true
+          else
+            note "#{path} has been customized, so it was kept. Remove it if you no longer need Node."
+            false
+          end
+        end
+
+        def stock_assets_js?(content)
+          code = content.lines.map(&:strip).reject { _1.empty? || _1.start_with?("//") }
+          code == [
+            %(import * as assets from "hanami-assets";),
+            "await assets.run({",
+            "esbuildOptionsFn: (args, esbuildOptions) => {",
+            "return esbuildOptions;",
+            "},",
+            "});"
+          ]
+        end
+
+        def stock_package_json?(content)
+          json = JSON.parse(content)
+          (json.keys - %w[name private type dependencies]).empty? &&
+            (json.fetch("dependencies", {}).keys - %w[hanami-assets esbuild]).empty?
+        rescue JSON::ParserError
+          false
+        end
+
+        def note(message)
+          stdout.puts "        note  #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/hanami/importmap/cli.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "hanami/cli"
+require_relative "cli/assets"
+require_relative "cli/importmap"
+require_relative "cli/install"
+
+# Replace the Node-based assets commands. These registrations run after hanami-cli's own (the
+# `hanami` executable loads the `:cli` group after registering its commands), and Dry CLI replaces
+# an existing command registered under the same name.
+Hanami::CLI.register "assets compile", Hanami::Importmap::CLI::Compile
+Hanami::CLI.register "assets watch", Hanami::Importmap::CLI::Watch
+
+Hanami::CLI.register "importmap install", Hanami::Importmap::CLI::Install
+Hanami::CLI.register "importmap pin", Hanami::Importmap::CLI::Pin
+Hanami::CLI.register "importmap unpin", Hanami::Importmap::CLI::Unpin
+Hanami::CLI.register "importmap json", Hanami::Importmap::CLI::Json
+
+require_relative "cli/hooks"
+Hanami::CLI.after "install", Hanami::Importmap::CLI::Hooks::AfterInstall
+Hanami::CLI.after "generate slice", Hanami::Importmap::CLI::Hooks::AfterGenerateSlice

data/lib/hanami/importmap/compiler.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "pathname"
+require_relative "errors"
+require_relative "map"
+
+module Hanami
+  module Importmap
+    # Builds one app's or slice's assets: the pure-Ruby counterpart of hanami-assets-js.
+    #
+    # Copies every file under the assets source root into the destination directory, fingerprinting
+    # filenames in compile mode, and writes the `assets.json` manifest that hanami-assets reads. CSS
+    # `url(...)` and `@import` references to other assets are rewritten to their output paths. When
+    # an import map config is given, the pins are resolved against the manifest and written to
+    # `importmap.json` beside it.
+    #
+    # Conforms to the hanami-assets bundler specification (hanami-assets SPEC.md): one isolated
+    # invocation per app or slice (§3.1), logical names with the type directory stripped (§5.3),
+    # fingerprints of 8 uppercase hex characters of SHA-256 (§4.2), atomic manifests (§5.5) and
+    # `sri` entries only when requested (§8).
+    #
+    # @api public
+    class Compiler
+      MANIFEST = "assets.json"
+      IMPORTMAP = "importmap.json"
+
+      # Sources that need a build step, which import maps deliberately don't have.
+      UNSUPPORTED_EXTENSIONS = %w[.ts .tsx .jsx .mts .cts .scss .sass .less].freeze
+
+      CSS_URL = /url\(\s*(?<quote>["']?)(?<ref>[^"')]+?)\k<quote>\s*\)/
+      CSS_IMPORT = /@import\s+(?<quote>["'])(?<ref>[^"']+)\k<quote>/
+      EXTERNAL_REF = %r{\A(?:[a-z][a-z0-9+.-]*:|//|/|#)}i
+
+      # The result of a build.
+      Result = Data.define(:manifest, :importmap)
+
+      # @param source [String, Pathname] the assets source root, e.g. `app/assets`
+      # @param destination [String, Pathname] where output goes, e.g. `public/assets/_admin`
+      # @param public_dir [String, Pathname] the directory the web server serves (`public/`); manifest
+      #   URLs are paths relative to it
+      # @param importmap_path [String, Pathname, nil] the `config/importmap.rb` to build, if any
+      # @param fingerprint [Boolean] embed content digests in filenames (compile mode) or not (watch)
+      # @param sri [Array<String, Symbol>] subresource integrity algorithms, e.g. `[:sha384]`
+      def initialize(source:, destination:, public_dir:, importmap_path: nil, fingerprint: true, sri: [])
+        @source = Pathname(source).expand_path
+        @destination = Pathname(destination).expand_path
+        @public_dir = Pathname(public_dir).expand_path
+        @importmap_path = importmap_path && Pathname(importmap_path).expand_path
+        @fingerprint = fingerprint
+        @sri = Array(sri).map(&:to_s)
+
+        @sri.each do |algorithm|
+          raise Error, "Unsupported subresource integrity algorithm: #{algorithm}" unless SRI_DIGESTS.key?(algorithm)
+        end
+      end
+
+      # Builds the assets and returns the manifest and import map that were written.
+      #
+      # @return [Result]
+      #
+      # @raise [Error] if a source can't be built or a pin doesn't resolve
+      def call
+        previous = read_json(destination.join(MANIFEST))
+
+        @sources = collect_sources
+        @entries = {}
+        @in_progress = {}
+        @sources.each_key { compile(_1) }
+
+        manifest = @entries.sort.to_h
+        importmap = build_importmap(manifest)
+
+        FileUtils.mkdir_p(destination)
+        write_atomically(destination.join(MANIFEST), JSON.pretty_generate(manifest))
+
+        if importmap
+          write_atomically(destination.join(IMPORTMAP), JSON.pretty_generate(importmap))
+        else
+          FileUtils.rm_f(destination.join(IMPORTMAP))
+        end
+
+        remove_stale_outputs(previous, manifest) unless fingerprint
+
+        Result.new(manifest:, importmap:)
+      end
+
+      # Returns the logical name for a path relative to an assets source root: the path with its
+      # first (asset type) directory removed, so `js/controllers/hello.js` → `controllers/hello.js`
+      # and `images/logo.png` → `logo.png`.
+      #
+      # @api private
+      def self.logical_name(relative_path)
+        parts = relative_path.to_s.split("/")
+        (parts.length > 1) ? parts.drop(1).join("/") : parts.first
+      end
+
+      SRI_DIGESTS = {
+        "sha256" => Digest::SHA256,
+        "sha384" => Digest::SHA384,
+        "sha512" => Digest::SHA512
+      }.freeze
+      private_constant :SRI_DIGESTS
+
+      private
+
+      attr_reader :source, :destination, :public_dir, :importmap_path, :fingerprint, :sri
+
+      # Returns {logical name => source path}, in a stable order.
+      def collect_sources
+        unless source.directory?
+          raise Error, "Assets source directory not found: #{source}"
+        end
+
+        sources = {}
+        source.glob("**/*").sort.each do |path|
+          next unless path.file?
+
+          relative = path.relative_path_from(source)
+          next if relative.each_filename.any? { _1.start_with?(".") }
+          next if path.extname == ".map"
+
+          if UNSUPPORTED_EXTENSIONS.include?(path.extname)
+            raise Error, "#{relative} needs a build step, which hanami-importmap doesn't have. " \
+              "Write plain JavaScript and CSS, or use hanami-assets-js (esbuild) instead."
+          end
+
+          name = self.class.logical_name(relative)
+          if (existing = sources[name])
+            raise Error, "#{relative} and #{existing.relative_path_from(source)} would both be served as #{name.inspect}. " \
+              "Rename one of them."
+          end
+
+          sources[name] = path
+        end
+        sources
+      end
+
+      # Compiles one source (once) and returns its manifest entry. CSS is compiled after the assets
+      # it references, since its rewritten content (and so its fingerprint) depends on their paths.
+      def compile(name)
+        return @entries[name] if @entries.key?(name)
+        return if @in_progress[name] # a CSS import cycle; leave the reference as written
+
+        path = @sources.fetch(name)
+        content = path.binread
+
+        if path.extname == ".css"
+          @in_progress[name] = true
+          content = rewrite_css(path, content)
+          @in_progress.delete(name)
+        end
+
+        output_name = fingerprint ? fingerprinted(name, content) : name
+        output = destination.join(output_name)
+        write_if_changed(output, content)
+
+        entry = {"url" => "/#{output.relative_path_from(public_dir)}"}
+        entry["sri"] = sri.map { "#{_1}-#{SRI_DIGESTS.fetch(_1).base64digest(content)}" } if sri.any?
+        @entries[name] = entry
+      end
+
+      def fingerprinted(name, content)
+        digest = Digest::SHA256.hexdigest(content)[0, 8].upcase
+        ext = File.extname(name)
+        "#{name.delete_suffix(ext)}-#{digest}#{ext}"
+      end
+
+      def rewrite_css(path, content)
+        content = content.dup.force_encoding(Encoding::UTF_8)
+
+        content
+          .gsub(CSS_URL) { css_reference(path, $~, "url(%s)") }
+          .gsub(CSS_IMPORT) { css_reference(path, $~, "@import %s") }
+      end
+
+      def css_reference(css_path, match, format)
+        ref = match[:ref]
+        return match[0] if ref.match?(EXTERNAL_REF)
+
+        file, suffix = ref.split(/(?=[?#])/, 2)
+        target = css_path.dirname.join(file).expand_path
+        name = @sources.key(target)
+        entry = name && compile(name)
+        return match[0] unless entry
+
+        quote = match[:quote].empty? ? "" : match[:quote]
+        format % "#{quote}#{entry["url"]}#{suffix}#{quote}"
+      end
+
+      def build_importmap(manifest)
+        return unless importmap_path&.file?
+
+        map = Map.load(importmap_path, source_root: source)
+        pins = map.pins.map { |pin|
+          if pin.remote?
+            {"name" => pin.name, "url" => pin.to, "preload" => pin.preload, "integrity" => pin.integrity}.compact
+          else
+            unless manifest.key?(pin.to)
+              raise Error, %(#{importmap_path.basename}: pin "#{pin.name}" points to #{pin.to.inspect}, ) +
+                "which isn't an asset in #{source}. Expected a file such as #{source.join("js", pin.to)}."
+            end
+
+            {"name" => pin.name, "asset" => pin.to, "preload" => pin.preload}
+          end
+        }
+
+        {"version" => 1, "pins" => pins}
+      end
+
+      def write_if_changed(path, content)
+        return if path.file? && path.size == content.bytesize && path.binread == content
+
+        FileUtils.mkdir_p(path.dirname)
+        write_atomically(path, content)
+      end
+
+      def write_atomically(path, content)
+        tmp = path.dirname.join(".#{path.basename}.#{Process.pid}.tmp")
+        tmp.binwrite(content)
+        File.rename(tmp, path)
+      ensure
+        FileUtils.rm_f(tmp) if tmp&.exist?
+      end
+
+      # In watch mode, outputs keep their names, so delete the ones whose sources are gone.
+      # Only paths this build wrote before (per the old manifest) are ever removed.
+      def remove_stale_outputs(previous, manifest)
+        return unless previous.is_a?(Hash)
+
+        current = manifest.values.map { _1["url"] }
+        previous.each_value do |entry|
+          url = entry.is_a?(Hash) && entry["url"]
+          next if !url || current.include?(url)
+
+          path = public_dir.join(url.delete_prefix("/")).expand_path
+          FileUtils.rm_f(path) if path.to_s.start_with?("#{destination}/")
+        end
+      end
+
+      def read_json(path)
+        JSON.parse(path.read) if path.file?
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/hanami/importmap/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Importmap
+    # Base error for hanami-importmap.
+    #
+    # @api public
+    class Error < StandardError; end
+
+    # Raised when rendering import map tags before the import map has been built.
+    #
+    # @api public
+    class MissingImportmapError < Error; end
+  end
+end

data/lib/hanami/importmap/helpers.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "hanami/view"
+require_relative "resolver"
+
+module Hanami
+  module Importmap
+    # View helpers for import maps, included in the standard Hanami helpers (so available in
+    # templates, parts and scopes).
+    #
+    # @api public
+    module Helpers
+      # Renders the import map, `modulepreload` links for preloaded pins, and a module script that
+      # imports the entry point.
+      #
+      # The map comes from the current app's or slice's assets, so each slice gets its own.
+      #
+      # @example
+      #   <%= javascript_importmap_tags %>
+      #   <%= javascript_importmap_tags "admin" %>
+      #
+      # @param entry_point [String, nil] the pin to import; `nil` renders the map and preloads only
+      # @param nonce [String, Boolean, nil] the CSP nonce for the inline scripts. Defaults to the
+      #   current request's nonce, if any; `false` omits it
+      #
+      # @return [Hanami::View::HTML::SafeString]
+      def javascript_importmap_tags(entry_point = "app", nonce: nil)
+        map = Resolver.call(_context.assets)
+        # `false` rather than nil, so the tag helpers don't look the nonce up again.
+        nonce = _importmap_nonce(nonce) || false
+
+        tags = [javascript_importmap_tag(map, nonce:)]
+        tags.concat(map.preloads.map { _module_preload_tag(_1, map.integrity[_1], nonce || nil) })
+        tags << javascript_import_module_tag(entry_point, nonce:) if entry_point
+
+        ::Hanami::View::HTML::SafeString.new(tags.join("\n"))
+      end
+
+      # Renders only the `<script type="importmap">` tag.
+      #
+      # @return [Hanami::View::HTML::SafeString]
+      def javascript_importmap_tag(map = Resolver.call(_context.assets), nonce: nil)
+        nonce = _importmap_nonce(nonce)
+        json = JSON.generate(map.to_h, script_safe: true)
+
+        # A page can't change its import map once modules have loaded, so ask Turbo Drive for a full
+        # reload when the next page's map differs (another slice's, or a rebuilt one). Turbo ignores
+        # nonces when comparing, so pages sharing a map still get fast visits.
+        ::Hanami::View::HTML::SafeString.new(
+          %(<script type="importmap"#{_importmap_attrs("data-turbo-track": "reload", nonce:)}>#{json}</script>)
+        )
+      end
+
+      # Renders a module script that imports the given pin.
+      #
+      # @return [Hanami::View::HTML::SafeString]
+      def javascript_import_module_tag(name, nonce: nil)
+        nonce = _importmap_nonce(nonce)
+
+        ::Hanami::View::HTML::SafeString.new(
+          %(<script type="module"#{_importmap_attrs(nonce:)}>import #{JSON.generate(name.to_s, script_safe: true)}</script>)
+        )
+      end
+
+      private
+
+      def _module_preload_tag(url, integrity, nonce)
+        %(<link rel="modulepreload"#{_importmap_attrs(href: url, integrity:, nonce:)}>)
+      end
+
+      def _importmap_nonce(nonce)
+        return nil if nonce == false
+        return nonce if nonce.is_a?(String)
+
+        content_security_policy_nonce if respond_to?(:content_security_policy_nonce, true)
+      end
+
+      def _importmap_attrs(**attrs)
+        attrs.compact.map { |key, value| %( #{key}="#{CGI.escapeHTML(value.to_s)}") }.join
+      end
+    end
+  end
+end
+
+Hanami::View::Scope.include(Hanami::Importmap::Helpers)
+Hanami::Extensions::View::StandardHelpers.include(Hanami::Importmap::Helpers)

data/lib/hanami/importmap/map.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "errors"
+
+module Hanami
+  module Importmap
+    # The `config/importmap.rb` DSL.
+    #
+    # Pins name a module and point it at an asset by its logical name (the same name you'd give to
+    # `javascript_tag`), or at a full URL.
+    #
+    # @example
+    #   pin "app"                                           # → app.js
+    #   pin "@hotwired/stimulus", to: "@hotwired--stimulus.js"
+    #   pin "lodash", to: "https://ga.jspm.io/npm:lodash@4.17.21/lodash.js", preload: false
+    #   pin_all_from "js/controllers", under: "controllers"
+    #
+    # @api public
+    class Map
+      # A single pinned module.
+      Pin = Data.define(:name, :to, :preload, :integrity) do
+        def remote?
+          Map.remote?(to)
+        end
+      end
+
+      JS_EXTENSIONS = %w[.js .mjs].freeze
+
+      # @api private
+      def self.remote?(to)
+        to.match?(%r{\A(?:https?:)?//}i) || to.start_with?("/")
+      end
+
+      # Evaluates an import map config file.
+      #
+      # @param path [String, Pathname] the `config/importmap.rb` file
+      # @param source_root [String, Pathname] the assets source root that `pin_all_from` paths are
+      #   relative to
+      #
+      # @return [Map]
+      def self.load(path, source_root:)
+        path = Pathname(path)
+        new(source_root:).tap { |map|
+          map.instance_eval(path.read, path.to_s, 1)
+        }
+      end
+
+      # @api private
+      attr_reader :source_root
+
+      def initialize(source_root:)
+        @source_root = Pathname(source_root)
+        @pins = {}
+      end
+
+      # Pins a module name to an asset or URL. Pinning the same name again replaces the earlier pin.
+      #
+      # @param name [String] the module specifier, as used in `import` statements
+      # @param to [String, nil] the asset's logical name (defaults to `"#{name}.js"`) or a URL
+      # @param preload [Boolean] add a `<link rel="modulepreload">` for the module
+      # @param integrity [String, nil] an SRI hash for a remote URL (local assets get theirs from the
+      #   manifest when `config.assets.subresource_integrity` is set)
+      def pin(name, to: nil, preload: true, integrity: nil)
+        name = name.to_s
+        to = (to || "#{name}.js").to_s
+
+        if integrity && !Map.remote?(to)
+          raise Error, %(pin "#{name}": integrity: is only for URLs; local assets get theirs from config.assets.subresource_integrity)
+        end
+
+        @pins[name] = Pin.new(name:, to:, preload:, integrity:)
+      end
+
+      # Pins every JavaScript file in a directory.
+      #
+      # Each file's name is its path within the directory, without the extension, prefixed with
+      # `under/` if given. `index.js` files are pinned as their directory's name.
+      #
+      # @example
+      #   pin_all_from "js/controllers", under: "controllers"
+      #   # js/controllers/hello_controller.js → pin "controllers/hello_controller"
+      #   # js/controllers/index.js            → pin "controllers"
+      #
+      # @param dir [String] a directory relative to the assets source root
+      # @param under [String, nil] a prefix for the pinned names
+      # @param preload [Boolean]
+      def pin_all_from(dir, under: nil, preload: true)
+        root = source_root.join(dir)
+
+        unless root.directory?
+          raise Error, %(pin_all_from "#{dir}": no such directory #{root})
+        end
+
+        root.glob("**/*").sort.each do |path|
+          next unless path.file? && JS_EXTENSIONS.include?(path.extname)
+
+          relative = path.relative_path_from(root).sub_ext("").to_s
+          relative = (relative == "index") ? "" : relative.delete_suffix("/index")
+          name = [under, relative].reject { _1.nil? || _1.empty? }.join("/")
+          next if name.empty?
+
+          pin name, to: Compiler.logical_name(path.relative_path_from(source_root)), preload:
+        end
+      end
+
+      # @return [Array<Pin>]
+      def pins
+        @pins.values
+      end
+    end
+  end
+end