shakapacker 9.3.0.beta.6 → 9.3.0

data/lib/shakapacker/doctor.rb

@@ -391,7 +391,7 @@ module Shakapacker
         expected_binstubs = {
           "bin/shakapacker" => "Main Shakapacker binstub",
           "bin/shakapacker-dev-server" => "Development server binstub",
-          "bin/export-bundler-config" => "Config export binstub"
+          "bin/shakapacker-config" => "Config export binstub"
         }
 
         expected_binstubs.each do |path, description|
@@ -879,49 +879,81 @@ module Shakapacker
 
           def print_verbose_checks
             puts "\nVerbose diagnostics:"
+            print_environment_info
+            print_version_info
+            print_path_info
+            print_config_values
+          end
 
-            # Show environment info
+          def print_environment_info
             rails_env = defined?(Rails) ? Rails.env : ENV["RAILS_ENV"]
             node_env = ENV["NODE_ENV"]
             puts "  • Rails environment: #{rails_env || 'not set'}"
             puts "  • Node environment: #{node_env || 'not set'}"
+          end
 
-            # Show gem/npm versions
-            if doctor.send(:package_json_exists?)
-              package_json = doctor.send(:read_package_json)
-              npm_version = package_json.dig("dependencies", "shakapacker") ||
-                           package_json.dig("devDependencies", "shakapacker")
-              puts "  • Shakapacker gem version: #{Shakapacker::VERSION}"
-              puts "  • Shakapacker npm version: #{npm_version || 'not installed'}"
-            end
+          def print_version_info
+            return unless doctor.send(:package_json_exists?)
 
-            # Show paths
+            package_json = doctor.send(:read_package_json)
+            npm_version = package_json.dig("dependencies", "shakapacker") ||
+                          package_json.dig("devDependencies", "shakapacker")
+            puts "  • Shakapacker gem version: #{Shakapacker::VERSION}"
+            puts "  • Shakapacker npm version: #{npm_version || 'not installed'}"
+          end
+
+          def print_path_info
             puts "  • Root path: #{doctor.root_path}"
-            if doctor.config.config_path.exist?
-              puts "  • Cache path: #{doctor.config.cache_path}"
-              puts "  • Manifest path: #{doctor.config.manifest_path}"
+            return unless doctor.config.config_path.exist?
+
+            puts "  • Cache path: #{doctor.config.cache_path}"
+            puts "  • Manifest path: #{doctor.config.manifest_path}"
+          end
+
+          def print_config_values
+            return unless doctor.config.config_path.exist?
+
+            puts "\nConfiguration values for '#{doctor.config.env}' environment:"
+            config_data = doctor.config.send(:data)
+
+            if config_data.any?
+              print_config_data(config_data)
+            else
+              puts "  (using bundled defaults - no environment-specific config found)"
             end
+          end
 
-            # Show environment-specific shakapacker.yml configuration values
-            if doctor.config.config_path.exist?
-              puts "\nConfiguration values for '#{doctor.config.env}' environment:"
-              config_data = doctor.config.send(:data)
-              if config_data.any?
-                config_data.each do |key, value|
-                  # Format the value nicely - truncate long arrays/hashes
-                  formatted_value = case value
-                                    when Array
-                                      value.length > 3 ? "#{value.first(3).inspect}... (#{value.length} items)" : value.inspect
-                                    when Hash
-                                      value.length > 3 ? "{...} (#{value.length} keys)" : value.inspect
-                                   else
-                                      value.inspect
-                  end
-                  puts "  • #{key}: #{formatted_value}"
-                end
-              else
-                puts "  (using bundled defaults - no environment-specific config found)"
-              end
+          def print_config_data(config_data)
+            config_data.each do |key, value|
+              formatted_value = format_config_value(value)
+              puts "  • #{key}: #{formatted_value}"
+            end
+          end
+
+          def format_config_value(value)
+            case value
+            when Array
+              format_array_value(value)
+            when Hash
+              format_hash_value(value)
+            else
+              value.inspect
+            end
+          end
+
+          def format_array_value(array)
+            if array.length > 3
+              "#{array.first(3).inspect}... (#{array.length} items)"
+            else
+              array.inspect
+            end
+          end
+
+          def format_hash_value(hash)
+            if hash.length > 3
+              "{...} (#{hash.length} keys)"
+            else
+              hash.inspect
             end
           end
 
@@ -981,7 +1013,7 @@ module Shakapacker
             binstubs = [
               "bin/shakapacker",
               "bin/shakapacker-dev-server",
-              "bin/export-bundler-config"
+              "bin/shakapacker-config"
             ]
 
             existing_binstubs = binstubs.select { |b| doctor.root_path.join(b).exist? }
@@ -1033,49 +1065,61 @@ module Shakapacker
 
             item_number = 0
             doctor.warnings.each do |warning|
-              category_prefix = case warning[:category]
-                                when :action_required then "[REQUIRED]"
-                                when :info then "[INFO]"
-                                when :recommended then "[RECOMMENDED]"
-                               else ""
-              end
-
-              # Sub-items start with whitespace (indented fix instructions)
-              is_subitem = warning[:message].start_with?("  ")
-
-              if is_subitem
-                # Fix instructions align at column 16 (length of "N. [RECOMMENDED]  ")
-                # This ensures all Fix lines align vertically regardless of category
-                subitem_prefix = " " * 15
-                wrapped = wrap_text(warning[:message], 100, subitem_prefix)
-                puts wrapped
+              if subitem?(warning[:message])
+                print_subitem(warning[:message])
               else
                 item_number += 1
-                # Format: N. [CATEGORY]  Message
-                prefix = "#{item_number}. #{category_prefix}  "
-                wrapped = wrap_text(warning[:message], 100, prefix)
-                puts wrapped
+                print_main_item(item_number, warning)
               end
             end
             puts ""
           end
 
+          def subitem?(message)
+            message.start_with?("  ")
+          end
+
+          def print_subitem(message)
+            # Fix instructions align at column 16 (length of "N. [RECOMMENDED]  ")
+            # This ensures all Fix lines align vertically regardless of category
+            subitem_prefix = " " * 15
+            wrapped = wrap_text(message, 100, subitem_prefix)
+            puts wrapped
+          end
+
+          def print_main_item(item_number, warning)
+            category_prefix = case warning[:category]
+                              when :action_required then "[REQUIRED]"
+                              when :info then "[INFO]"
+                              when :recommended then "[RECOMMENDED]"
+                              else
+                                ""
+            end
+
+            # Format: N. [CATEGORY]  Message
+            prefix = "#{item_number}. #{category_prefix}  "
+            wrapped = wrap_text(warning[:message], 100, prefix)
+            puts wrapped
+          end
+
           def wrap_text(text, max_width, prefix)
-            # Strip leading whitespace from sub-items
             text = text.strip
-
-            # Calculate available width for text
             available_width = max_width - prefix.length
+
             return prefix + text if text.length <= available_width
 
-            # Wrap long lines
+            lines = build_wrapped_lines(text, available_width)
+            format_wrapped_output(lines, prefix)
+          end
+
+          def build_wrapped_lines(text, available_width)
             words = text.split(" ")
             lines = []
             current_line = []
             current_length = 0
 
             words.each do |word|
-              word_length = word.length + (current_line.empty? ? 0 : 1) # +1 for space
+              word_length = word.length + (current_line.empty? ? 0 : 1)
 
               if current_length + word_length <= available_width
                 current_line << word
@@ -1086,26 +1130,39 @@ module Shakapacker
                 current_length = word.length
               end
             end
+
             lines << current_line.join(" ") unless current_line.empty?
+            lines
+          end
 
-            # Format output
+          def format_wrapped_output(lines, prefix)
             result = prefix + lines[0]
+            indent = " " * prefix.length
+
             lines[1..].each do |line|
-              result += "\n" + (" " * prefix.length) + line
+              result += "\n#{indent}#{line}"
             end
+
             result
           end
 
           def has_dependency_issues?
-            # Check if any issues or warnings are about missing npm/package dependencies
-            # Exclude optional dependencies - only show install instructions for required dependencies
             all_messages = doctor.issues + doctor.warnings.map { |w| w[:message] }
-            all_messages.any? do |msg|
-              next if msg.include?("Optional")
-              (msg.include?("Missing") && msg.include?("dependency")) ||
-              msg.include?("not installed") ||
-              msg.include?("is not installed")
-            end
+            all_messages.any? { |msg| dependency_issue?(msg) }
+          end
+
+          def dependency_issue?(message)
+            return false if message.include?("Optional")
+
+            missing_dependency?(message) || not_installed?(message)
+          end
+
+          def missing_dependency?(message)
+            message.include?("Missing") && message.include?("dependency")
+          end
+
+          def not_installed?(message)
+            message.include?("not installed") || message.include?("is not installed")
           end
 
           def print_fix_instructions
@@ -1114,10 +1171,10 @@ module Shakapacker
             puts "  #{package_manager_install_command(package_manager)}"
             puts ""
             puts "For debugging configuration issues, export your webpack/rspack config:"
-            puts "  bin/export-bundler-config --doctor"
+            puts "  bin/shakapacker-config --doctor"
             puts "  (Exports annotated YAML configs for dev and production - best for troubleshooting)"
             puts ""
-            puts "  See 'bin/export-bundler-config --help' for more options"
+            puts "  See 'bin/shakapacker-config --help' for more options"
           end
 
           def package_manager_install_command(manager)

data/lib/shakapacker/instance.rb

@@ -1,10 +1,43 @@
 require "pathname"
 
+# Represents a single instance of Shakapacker configuration and state
+#
+# An instance encapsulates all the configuration, compilation, and manifest
+# lookup functionality for a specific Rails application. Most applications
+# will use the shared instance accessible via {Shakapacker.instance}, but
+# multiple instances can be created for testing or advanced scenarios.
+#
+# @example Using the default instance
+#   instance = Shakapacker::Instance.new
+#   instance.config.source_path
+#   instance.manifest.lookup("application.js")
+#
+# @example Creating an instance with custom paths
+#   instance = Shakapacker::Instance.new(
+#     root_path: "/path/to/app",
+#     config_path: "/custom/config.yml"
+#   )
 class Shakapacker::Instance
+  # The shared logger used by all Shakapacker instances
+  # @return [ActiveSupport::TaggedLogging] the logger
   cattr_accessor(:logger) { ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new(STDOUT)) }
 
-  attr_reader :root_path, :config_path
+  # The root path of the application
+  # @return [Pathname] the application root path
+  attr_reader :root_path
 
+  # The path to the Shakapacker configuration file
+  # @return [Pathname] the config file path
+  attr_reader :config_path
+
+  # Creates a new Shakapacker instance
+  #
+  # @param root_path [String, Pathname, nil] the application root path.
+  #   Defaults to Rails.root if Rails is defined, otherwise uses current directory
+  # @param config_path [String, Pathname, nil] the path to shakapacker.yml.
+  #   Can also be set via SHAKAPACKER_CONFIG environment variable.
+  #   Defaults to +config/shakapacker.yml+ within the root_path
+  # @return [Shakapacker::Instance] the new instance
   def initialize(root_path: nil, config_path: nil)
     # Use Rails.root if Rails is defined and no root_path is provided
     @root_path = root_path || (defined?(Rails) && Rails&.root) || Pathname.new(Dir.pwd)
@@ -15,10 +48,23 @@ class Shakapacker::Instance
     @config_path = Pathname.new(ENV["SHAKAPACKER_CONFIG"] || config_path || default_config_path)
   end
 
+  # Returns the current Rails environment as a StringInquirer
+  #
+  # This allows for convenient environment checking:
+  #   env.development? # => true/false
+  #   env.production?  # => true/false
+  #
+  # @return [ActiveSupport::StringInquirer] the environment
   def env
     @env ||= Shakapacker::Env.inquire self
   end
 
+  # Returns the configuration object for this instance
+  #
+  # The configuration is loaded from the shakapacker.yml file and provides
+  # access to all settings like source paths, output paths, and compilation options.
+  #
+  # @return [Shakapacker::Configuration] the configuration
   def config
     @config ||= Shakapacker::Configuration.new(
       root_path: root_path,
@@ -27,26 +73,64 @@ class Shakapacker::Instance
     )
   end
 
+  # Returns the compiler strategy for determining staleness
+  #
+  # The strategy (mtime or digest) determines how Shakapacker decides whether
+  # assets need recompilation.
+  #
+  # @return [Shakapacker::CompilerStrategy] the compiler strategy
+  # @api private
   def strategy
     @strategy ||= Shakapacker::CompilerStrategy.from_config
   end
 
+  # Returns the compiler for this instance
+  #
+  # The compiler is responsible for executing webpack/rspack to compile assets.
+  #
+  # @return [Shakapacker::Compiler] the compiler
   def compiler
     @compiler ||= Shakapacker::Compiler.new self
   end
 
+  # Returns the development server instance
+  #
+  # The dev server instance can query the status of the webpack-dev-server,
+  # including whether it's running, its host/port, and configuration.
+  #
+  # @return [Shakapacker::DevServer] the dev server
   def dev_server
     @dev_server ||= Shakapacker::DevServer.new config
   end
 
+  # Returns the manifest for looking up compiled assets
+  #
+  # The manifest reads the manifest.json file produced by webpack/rspack
+  # and provides methods to look up the compiled paths for source files.
+  #
+  # @return [Shakapacker::Manifest] the manifest
   def manifest
     @manifest ||= Shakapacker::Manifest.new self
   end
 
+  # Returns the commands instance for build operations
+  #
+  # The commands object provides methods for bootstrapping, cleaning,
+  # clobbering, and compiling assets.
+  #
+  # @return [Shakapacker::Commands] the commands
   def commands
     @commands ||= Shakapacker::Commands.new self
   end
 
+  # Returns whether CSS should be inlined by the dev server
+  #
+  # CSS inlining is enabled when:
+  # - The dev server has inline_css enabled
+  # - Hot Module Replacement (HMR) is enabled
+  # - The dev server is currently running
+  #
+  # @return [Boolean] true if CSS should be inlined
   def inlining_css?
     dev_server.inline_css? && dev_server.hmr? && dev_server.running?
   end

data/lib/shakapacker/manifest.rb

@@ -1,23 +1,70 @@
-# Singleton registry for accessing the packs path using a generated manifest.
-# This allows javascript_pack_tag, stylesheet_pack_tag, asset_pack_path to take a reference to,
-# say, "calendar.js" or "calendar.css" and turn it into "/packs/calendar-1016838bab065ae1e314.js" or
-# "/packs/calendar-1016838bab065ae1e314.css".
+# Manifest for looking up compiled asset paths
 #
-# When the configuration is set to on-demand compilation, with the `compile: true` option in
-# the shakapacker.yml file, any lookups will be preceded by a compilation if one is needed.
+# The manifest reads the +manifest.json+ file produced by webpack/rspack during
+# compilation and provides methods to look up the compiled (digested) paths for
+# source files.
+#
+# This allows view helpers like +javascript_pack_tag+, +stylesheet_pack_tag+, and
+# +asset_pack_path+ to take a reference to a source file (e.g., "calendar.js")
+# and turn it into the compiled path with digest (e.g., "/packs/calendar-1016838bab065ae1e314.js").
+#
+# == Automatic Compilation
+#
+# When the configuration has +compile: true+ in shakapacker.yml, any lookups will
+# automatically trigger compilation if the assets are stale. This is typically
+# enabled in development and disabled in production.
+#
+# == Caching
+#
+# The manifest can cache the loaded data in memory when +cache_manifest: true+ is
+# set in the configuration. This improves performance in production by avoiding
+# repeated file reads.
+#
+# @example Looking up assets
+#   manifest = Shakapacker.manifest
+#   manifest.lookup("application.js")
+#   #=> "/packs/application-abc123.js"
+#
+#   manifest.lookup!("missing.js")
+#   #=> raises Shakapacker::Manifest::MissingEntryError
+#
+# @see Shakapacker::Helper
 class Shakapacker::Manifest
+  # Raised when an asset cannot be found in the manifest
   class MissingEntryError < StandardError; end
 
   delegate :config, :compiler, :dev_server, to: :@instance
 
+  # Creates a new manifest instance
+  #
+  # @param instance [Shakapacker::Instance] the Shakapacker instance
+  # @return [Shakapacker::Manifest] the new manifest
   def initialize(instance)
     @instance = instance
   end
 
+  # Reloads the manifest data from disk
+  #
+  # Forces a fresh read of the manifest.json file, bypassing any cache.
+  # This is useful when you know the manifest has been updated.
+  #
+  # @return [Hash] the loaded manifest data
   def refresh
     @data = load
   end
 
+  # Looks up an entry point with all its chunks (split code)
+  #
+  # This method is used when you need to load all chunks for a pack that has
+  # been split via code splitting. It returns an array of asset paths for the
+  # main entry and all its dynamic imports.
+  #
+  # @param name [String] the entry point name (e.g., "application")
+  # @param pack_type [Hash] options hash with :type key (:javascript, :stylesheet, etc.)
+  # @return [Array<String>, nil] array of asset paths, or nil if not found
+  # @example
+  #   manifest.lookup_pack_with_chunks("application", type: :javascript)
+  #   #=> ["/packs/runtime-abc123.js", "/packs/application-def456.js"]
   def lookup_pack_with_chunks(name, pack_type = {})
     compile if compiling?
 
@@ -28,23 +75,50 @@ class Shakapacker::Manifest
     nil
   end
 
+  # Like {#lookup_pack_with_chunks}, but raises an error if not found
+  #
+  # @param name [String] the entry point name
+  # @param pack_type [Hash] options hash with :type key
+  # @return [Array<String>] array of asset paths
+  # @raise [MissingEntryError] if the entry point is not found in the manifest
   def lookup_pack_with_chunks!(name, pack_type = {})
     lookup_pack_with_chunks(name, pack_type) || handle_missing_entry(name, pack_type)
   end
 
-  # Computes the relative path for a given Shakapacker asset using manifest.json.
-  # If no asset is found, returns nil.
+  # Looks up the compiled path for a given asset
+  #
+  # Computes the relative path for a Shakapacker asset using the manifest.json file.
+  # If automatic compilation is enabled and the assets are stale, triggers a
+  # compilation before looking up the path.
   #
-  # Example:
+  # @param name [String] the source file name (e.g., "calendar.js" or "calendar")
+  # @param pack_type [Hash] options hash with :type key (:javascript, :stylesheet, etc.).
+  #   If not specified, the extension from the name is used.
+  # @return [String, nil] the compiled asset path, or nil if not found
+  # @example
+  #   Shakapacker.manifest.lookup('calendar.js')
+  #   #=> "/packs/calendar-1016838bab065ae1e122.js"
   #
-  #   Shakapacker.manifest.lookup('calendar.js') # => "/packs/calendar-1016838bab065ae1e122.js"
+  #   Shakapacker.manifest.lookup('calendar', type: :javascript)
+  #   #=> "/packs/calendar-1016838bab065ae1e122.js"
   def lookup(name, pack_type = {})
     compile if compiling?
 
     find(full_pack_name(name, pack_type[:type]))
   end
 
-  # Like lookup, except that if no asset is found, raises a Shakapacker::Manifest::MissingEntryError.
+  # Like {#lookup}, but raises an error if the asset is not found
+  #
+  # @param name [String] the source file name
+  # @param pack_type [Hash] options hash with :type key
+  # @return [String] the compiled asset path
+  # @raise [MissingEntryError] if the asset is not found in the manifest
+  # @example
+  #   Shakapacker.manifest.lookup!('calendar.js')
+  #   #=> "/packs/calendar-1016838bab065ae1e122.js"
+  #
+  #   Shakapacker.manifest.lookup!('missing.js')
+  #   #=> raises MissingEntryError
   def lookup!(name, pack_type = {})
     lookup(name, pack_type) || handle_missing_entry(name, pack_type)
   end

data/lib/shakapacker/runner.rb

@@ -29,8 +29,10 @@ module Shakapacker
       $stdout.sync = true
 
       # Show Shakapacker help and exit (don't call bundler)
-      if argv.include?("--help") || argv.include?("-h")
-        print_help
+      # Support --help, -h, and --help=verbose formats
+      help_verbose = argv.any? { |arg| arg == "--help=verbose" }
+      if argv.include?("--help") || argv.include?("-h") || help_verbose
+        print_help(verbose: help_verbose)
         exit(0)
       elsif argv.include?("--version") || argv.include?("-v")
         print_version
@@ -310,7 +312,7 @@ module Shakapacker
         $stderr.puts "Current configured path: #{config_dir}"
       end
 
-      def self.print_help
+      def self.print_help(verbose: false)
         puts <<~HELP
         ================================================================================
         SHAKAPACKER - Rails Webpack/Rspack Integration
@@ -320,6 +322,7 @@ module Shakapacker
 
         Shakapacker-specific options:
           -h, --help                Show this help message
+              --help=verbose        Show verbose help including all bundler options
           -v, --version             Show Shakapacker version
           --debug-shakapacker       Enable Node.js debugging (--inspect-brk)
           --trace-deprecation       Show stack traces for deprecations
@@ -347,7 +350,7 @@ module Shakapacker
 
         HELP
 
-        print_bundler_help
+        print_bundler_help(verbose: verbose)
 
         puts <<~HELP
 
@@ -366,8 +369,9 @@ module Shakapacker
         HELP
       end
 
-      def self.print_bundler_help
-        bundler_type, bundler_help = get_bundler_help
+      def self.print_bundler_help(verbose: false)
+        help_flag = verbose ? "--help=verbose" : "--help"
+        bundler_type, bundler_help = get_bundler_help(help_flag)
 
         if bundler_help
           bundler_name = bundler_type == :rspack ? "RSPACK" : "WEBPACK"
@@ -390,8 +394,8 @@ module Shakapacker
         end
       end
 
-      def self.get_bundler_help
-        execute_bundler_command("--help") { |stdout| stdout }
+      def self.get_bundler_help(help_flag = "--help")
+        execute_bundler_command(help_flag) { |stdout| stdout }
       end
 
       # Filter bundler help output to remove Shakapacker-managed options

data/lib/shakapacker/swc_migrator.rb

@@ -61,13 +61,13 @@ module Shakapacker
             keepClassNames: true,
             transform: {
               react: {
-                runtime: "automatic",
-                refresh: env.isDevelopment && env.runningWebpackDevServer
-              }
-            }
-          }
-        }
-      }
+                runtime: 'automatic',
+                refresh: env.isDevelopment && env.runningWebpackDevServer,
+              },
+            },
+          },
+        },
+      };
     JS
 
     def initialize(root_path, logger: nil)

data/lib/shakapacker/version.rb

@@ -1,4 +1,4 @@
 module Shakapacker
   # Change the version in package.json too, please!
-  VERSION = "9.3.0.beta.6".freeze
+  VERSION = "9.3.0".freeze
 end