shakapacker 9.2.0 → 9.3.0.beta.0

data/lib/shakapacker/runner.rb

@@ -1,9 +1,11 @@
 require_relative "utils/misc"
 require_relative "utils/manager"
 require_relative "configuration"
+require_relative "version"
 
 require "package_json"
 require "pathname"
+require "stringio"
 
 module Shakapacker
   class Runner
@@ -24,6 +26,16 @@ module Shakapacker
     ].freeze
     def self.run(argv)
       $stdout.sync = true
+
+      # Show Shakapacker help and exit (don't call bundler)
+      if argv.include?("--help") || argv.include?("-h")
+        print_help
+        exit(0)
+      elsif argv.include?("--version") || argv.include?("-v")
+        print_version
+        exit(0)
+      end
+
       Shakapacker.ensure_node_env!
 
       # Create a single runner instance to avoid loading configuration twice.
@@ -112,9 +124,22 @@ module Shakapacker
       puts "[Shakapacker] Final command: #{cmd.join(" ")}"
       puts "[Shakapacker] Working directory: #{@app_path}"
 
+      watch_mode = @argv.include?("--watch") || @argv.include?("-w")
+      start_time = Time.now unless watch_mode
+
       Dir.chdir(@app_path) do
-        Kernel.exec env, *cmd
+        system(env, *cmd)
       end
+
+      if !watch_mode && start_time
+        bundler_name = @config.rspack? ? "rspack" : "webpack"
+        elapsed_time = Time.now - start_time
+        minutes = (elapsed_time / 60).floor
+        seconds = (elapsed_time % 60).round(2)
+        time_display = minutes > 0 ? "#{minutes}:#{format('%05.2f', seconds)}s" : "#{elapsed_time.round(2)}s"
+        puts "[Shakapacker] Completed #{bundler_name} build in #{time_display} (#{elapsed_time.round(2)}s)"
+      end
+      exit($?.exitstatus || 1) unless $?.success?
     end
 
     protected
@@ -123,6 +148,213 @@ module Shakapacker
         BASE_COMMANDS
       end
 
+      def print_config_not_found_error(bundler_type, config_path, config_dir)
+        $stderr.puts "[Shakapacker] ERROR: #{bundler_type} config #{config_path} not found."
+        $stderr.puts ""
+        $stderr.puts "Please run 'bundle exec rails shakapacker:install' to install Shakapacker with default configs,"
+        $stderr.puts "or create the missing config file."
+        $stderr.puts ""
+        $stderr.puts "If your config file is in a different location, you can configure it in config/shakapacker.yml:"
+        $stderr.puts ""
+        $stderr.puts "  assets_bundler_config_path: your/custom/path"
+        $stderr.puts ""
+        $stderr.puts "Current configured path: #{config_dir}"
+      end
+
+      def self.print_help
+        puts <<~HELP
+        ================================================================================
+        SHAKAPACKER - Rails Webpack/Rspack Integration
+        ================================================================================
+
+        Usage: bin/shakapacker [options]
+
+        Shakapacker-specific options:
+          -h, --help                Show this help message
+          -v, --version             Show Shakapacker version
+          --debug-shakapacker       Enable Node.js debugging (--inspect-brk)
+          --trace-deprecation       Show stack traces for deprecations
+          --no-deprecation          Silence deprecation warnings
+
+        Examples:
+          bin/shakapacker                              # Build for production
+          bin/shakapacker --mode development           # Build for development
+          bin/shakapacker --watch                      # Watch mode
+          bin/shakapacker --mode development --analyze # Development build with analysis
+          bin/shakapacker --debug-shakapacker          # Debug with Node inspector
+
+        HELP
+
+        print_bundler_help
+
+        puts <<~HELP
+
+        Options managed by Shakapacker (configured via config files):
+          --config                  Set automatically based on assets_bundler_config_path
+                                    (defaults to config/webpack or config/rspack)
+          --node-env                Set from RAILS_ENV or NODE_ENV
+        HELP
+      end
+
+      def self.print_bundler_help
+        bundler_type, bundler_help = get_bundler_help
+
+        if bundler_help
+          bundler_name = bundler_type == :rspack ? "RSPACK" : "WEBPACK"
+          puts "=" * 80
+          puts "AVAILABLE #{bundler_name} OPTIONS (Passed directly to #{bundler_name.downcase})"
+          puts "=" * 80
+          puts
+          puts filter_managed_options(bundler_help)
+          puts
+          puts "For complete documentation:"
+          if bundler_type == :rspack
+            puts "  https://rspack.dev/api/cli"
+          else
+            puts "  https://webpack.js.org/api/cli/"
+          end
+        else
+          puts "For complete documentation:"
+          puts "  Webpack: https://webpack.js.org/api/cli/"
+          puts "  Rspack:  https://rspack.dev/api/cli"
+        end
+      end
+
+      def self.get_bundler_help
+        execute_bundler_command("--help") { |stdout| stdout }
+      end
+
+      # Filter bundler help output to remove Shakapacker-managed options
+      #
+      # This method processes the raw help output from webpack/rspack and removes:
+      # 1. Command sections (e.g., "Commands: webpack build")
+      # 2. Options that Shakapacker manages automatically (--config, --nodeEnv, etc.)
+      # 3. Help/version flags (shown separately in Shakapacker's help)
+      #
+      # The filtering uses stateful line-by-line processing:
+      # - in_commands_section: tracks when we're inside a Commands: block
+      # - skip_until_blank: tracks multi-line option descriptions to skip entirely
+      #
+      # Note: This relies on bundler help format conventions. If webpack/rspack
+      # significantly changes their help output format, this may need adjustment.
+      def self.filter_managed_options(help_text)
+        lines = help_text.lines
+        filtered_lines = []
+        skip_until_blank = false
+        in_commands_section = false
+
+        lines.each do |line|
+          # Skip the [options] line and Commands section headers
+          # These appear in formats like "[options]" or "Commands:"
+          if line.match?(/^\[options\]/) || line.match?(/^Commands:/)
+            in_commands_section = true
+            next
+          end
+
+          # Continue skipping until we exit the commands section
+          # Exit when we hit "Options:" header or double blank lines
+          if in_commands_section
+            if line.match?(/^Options:/) || (line.strip.empty? && filtered_lines.last&.strip&.empty?)
+              in_commands_section = false
+            else
+              next
+            end
+          end
+
+          # Skip options that Shakapacker manages and their descriptions
+          # These options are shown in the "Options managed by Shakapacker" section
+          if line.match?(/^\s*(-c,\s*)?--config\b/) ||
+             line.match?(/^\s*--configName\b/) ||
+             line.match?(/^\s*--configLoader\b/) ||
+             line.match?(/^\s*--nodeEnv\b/) ||
+             line.match?(/^\s*(-h,\s*)?--help\b/) ||
+             line.match?(/^\s*(-v,\s*)?--version\b/)
+            skip_until_blank = true
+            next
+          end
+
+          # Continue skipping lines that are part of a filtered option's description
+          # Reset when we hit a blank line or the start of a new option (starts with -)
+          if skip_until_blank
+            if line.strip.empty? || line.match?(/^\s*-/)
+              skip_until_blank = false
+            else
+              next
+            end
+          end
+
+          filtered_lines << line
+        end
+
+        filtered_lines.join
+      end
+
+      def self.print_version
+        puts "Shakapacker #{Shakapacker::VERSION}"
+        puts "Framework: Rails #{Rails.version}" if defined?(Rails)
+
+        # Try to get bundler version
+        bundler_type, bundler_version = get_bundler_version
+        if bundler_version
+          bundler_name = bundler_type == :rspack ? "Rspack" : "Webpack"
+          puts "Bundler: #{bundler_name} #{bundler_version}"
+        end
+      end
+
+      def self.get_bundler_version
+        execute_bundler_command("--version") { |stdout| stdout.strip }
+      end
+
+      # Shared helper to execute bundler commands with output suppression
+      # Returns [bundler_type, processed_output] or [nil, nil] on error
+      #
+      # @param bundler_args [String, Array<String>] Arguments to pass to bundler command
+      # @yield [stdout] Block to process the command output
+      # @yieldparam stdout [String] The raw stdout from the bundler command
+      # @yieldreturn [Object] The processed output to return
+      def self.execute_bundler_command(*bundler_args)
+        # Check if we're in a Rails project with necessary files
+        app_path = File.expand_path(".", Dir.pwd)
+        config_path = ENV["SHAKAPACKER_CONFIG"] || File.join(app_path, "config/shakapacker.yml")
+        return [nil, nil] unless File.exist?(config_path)
+
+        original_stdout = $stdout
+        original_stderr = $stderr
+
+        begin
+          # Suppress any output during config loading
+          $stdout = StringIO.new
+          $stderr = StringIO.new
+
+          # Try to detect bundler type
+          runner = new([])
+          return [nil, nil] unless runner.config
+
+          bundler_type = runner.config.rspack? ? :rspack : :webpack
+          bundler_name = bundler_type == :rspack ? "rspack" : "webpack"
+          cmd = runner.package_json.manager.native_exec_command(bundler_name, bundler_args.flatten)
+
+          # Restore output before running command
+          $stdout = original_stdout
+          $stderr = original_stderr
+
+          # Capture command output
+          require "open3"
+          stdout, _stderr, status = Open3.capture3(*cmd)
+          return [nil, nil] unless status.success?
+
+          # Process output using the provided block
+          processed_output = yield(stdout)
+          [bundler_type, processed_output]
+        rescue StandardError => e
+          [nil, nil]
+        ensure
+          # Always restore output streams
+          $stdout = original_stdout
+          $stderr = original_stderr
+        end
+      end
+
     private
       def find_assets_bundler_config
         if @config.rspack?
@@ -133,9 +365,11 @@ module Shakapacker
       end
 
       def find_rspack_config_with_fallback
-        # First try rspack-specific paths
+        config_dir = @config.assets_bundler_config_path
+
+        # First try rspack-specific paths in the configured directory
         rspack_paths = %w[ts js].map do |ext|
-          File.join(@app_path, "config/rspack/rspack.config.#{ext}")
+          File.join(@app_path, config_dir, "rspack.config.#{ext}")
         end
 
         puts "[Shakapacker] Looking for Rspack config in: #{rspack_paths.join(", ")}"
@@ -147,31 +381,33 @@ module Shakapacker
 
         # Fallback to webpack config with deprecation warning
         webpack_paths = %w[ts js].map do |ext|
-          File.join(@app_path, "config/webpack/webpack.config.#{ext}")
+          File.join(@app_path, config_dir, "webpack.config.#{ext}")
         end
 
         puts "[Shakapacker] Rspack config not found, checking for webpack config fallback..."
         webpack_path = webpack_paths.find { |f| File.exist?(f) }
         if webpack_path
           $stderr.puts "⚠️  DEPRECATION WARNING: Using webpack config file for Rspack assets bundler."
-          $stderr.puts "   Please create config/rspack/rspack.config.js and migrate your configuration."
+          $stderr.puts "   Please create #{config_dir}/rspack.config.js and migrate your configuration."
           $stderr.puts "   Using: #{webpack_path}"
           return webpack_path
         end
 
         # No config found
-        $stderr.puts "[Shakapacker] ERROR: rspack config #{rspack_paths.last} not found, please run 'bundle exec rails shakapacker:install' to install Shakapacker with default configs or create the missing config file."
+        print_config_not_found_error("rspack", rspack_paths.last, config_dir)
         exit(1)
       end
 
       def find_webpack_config
+        config_dir = @config.assets_bundler_config_path
+
         possible_paths = %w[ts js].map do |ext|
-          File.join(@app_path, "config/webpack/webpack.config.#{ext}")
+          File.join(@app_path, config_dir, "webpack.config.#{ext}")
         end
         puts "[Shakapacker] Looking for Webpack config in: #{possible_paths.join(", ")}"
         path = possible_paths.find { |f| File.exist?(f) }
         unless path
-          $stderr.puts "[Shakapacker] ERROR: webpack config #{possible_paths.last} not found, please run 'bundle exec rails shakapacker:install' to install Shakapacker with default configs or add the missing config file for your custom environment."
+          print_config_not_found_error("webpack", possible_paths.last, config_dir)
           exit(1)
         end
         puts "[Shakapacker] Found Webpack config: #{path}"

data/lib/shakapacker/version.rb

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

data/lib/tasks/shakapacker/doctor.rake

@@ -1,8 +1,48 @@
 require "shakapacker/doctor"
 
 namespace :shakapacker do
-  desc "Checks for common Shakapacker configuration issues and missing dependencies"
+  desc <<~DESC
+    Checks for common Shakapacker configuration issues and missing dependencies
+
+    Performs comprehensive diagnostics including:
+    • Configuration file validity and deprecated settings
+    • Entry points, output paths, and asset compilation status
+    • Node.js and package manager installation
+    • Required and optional npm dependencies
+    • JavaScript transpiler (Babel, SWC, esbuild) configuration
+    • CSS, CSS Modules, and stylesheet preprocessor setup
+    • Binstubs presence (shakapacker, shakapacker-dev-server, export-bundler-config)
+    • Version consistency between gem and npm package
+    • Legacy Webpacker file detection
+
+    Options:
+      --help       Show detailed help and usage information
+      --verbose    Display additional diagnostic details (paths, versions, environment)
+
+    Examples:
+      bin/rails shakapacker:doctor
+      bin/rails shakapacker:doctor -- --verbose
+      bin/rails shakapacker:doctor -- --help
+
+    Exit codes:
+      0 - No issues found
+      1 - Issues or warnings detected (see output for details)
+  DESC
   task doctor: :environment do
-    Shakapacker::Doctor.new.run
+    # Parse command-line options
+    options = {}
+    ARGV.each do |arg|
+      case arg
+      when "--help", "-h"
+        options[:help] = true
+      when "--verbose", "-v"
+        options[:verbose] = true
+      end
+    end
+
+    Shakapacker::Doctor.new(nil, nil, options).run
+
+    # Prevent rake from treating options as task names
+    ARGV.each { |arg| task arg.to_sym do; end if arg.start_with?("--", "-") }
   end
 end

data/package/babel/preset.ts

@@ -17,7 +17,10 @@ const coreJsVersion = (): string => {
   }
 }
 
-export = function config(api: ConfigAPI): { presets: PluginItem[]; plugins: PluginItem[] } {
+export = function config(api: ConfigAPI): {
+  presets: PluginItem[]
+  plugins: PluginItem[]
+} {
   const validEnv = ["development", "test", "production"]
   const currentEnv = api.env()
   const isDevelopmentEnv = api.env("development")
@@ -45,9 +48,9 @@ export = function config(api: ConfigAPI): { presets: PluginItem[]; plugins: Plug
     moduleExists("@babel/preset-typescript") && "@babel/preset-typescript"
   ].filter(Boolean) as PluginItem[]
 
-  const plugins: PluginItem[] = [["@babel/plugin-transform-runtime", { helpers: false }]].filter(
-    Boolean
-  ) as PluginItem[]
+  const plugins: PluginItem[] = [
+    ["@babel/plugin-transform-runtime", { helpers: false }]
+  ].filter(Boolean) as PluginItem[]
 
   return {
     presets,

data/package/config.ts

@@ -7,17 +7,25 @@ const { railsEnv } = require("./env")
 const configPath = require("./utils/configPath")
 const defaultConfigPath = require("./utils/defaultConfigPath")
 import { Config, YamlConfig, LegacyConfig } from "./types"
-const { isValidYamlConfig, createConfigValidationError, isPartialConfig, isValidConfig } = require("./utils/typeGuards")
-const { isFileNotFoundError, createFileOperationError } = require("./utils/errorHelpers")
+const {
+  isValidYamlConfig,
+  createConfigValidationError,
+  isPartialConfig,
+  isValidConfig
+} = require("./utils/typeGuards")
+const {
+  isFileNotFoundError,
+  createFileOperationError
+} = require("./utils/errorHelpers")
 
 const loadAndValidateYaml = (path: string): YamlConfig => {
   const fileContent = readFileSync(path, "utf8")
   const yamlContent = load(fileContent)
-  
+
   if (!isValidYamlConfig(yamlContent)) {
     throw createConfigValidationError(path, railsEnv, "Invalid YAML structure")
   }
-  
+
   return yamlContent as YamlConfig
 }
 
@@ -28,8 +36,8 @@ const getDefaultConfig = (): Partial<Config> => {
   } catch (error) {
     if (isFileNotFoundError(error)) {
       throw createFileOperationError(
-        'read', 
-        defaultConfigPath, 
+        "read",
+        defaultConfigPath,
         `Default configuration not found at ${defaultConfigPath}. Please ensure Shakapacker is properly installed. You may need to run 'yarn add shakapacker' or 'npm install shakapacker'.`
       )
     }
@@ -43,34 +51,34 @@ let config: Config
 if (existsSync(configPath)) {
   try {
     const appYmlObject = loadAndValidateYaml(configPath)
-    
+
     const envAppConfig = appYmlObject[railsEnv]
 
     if (!envAppConfig) {
       /* eslint no-console:0 */
       console.warn(
         `[SHAKAPACKER WARNING] Environment '${railsEnv}' not found in ${configPath}\n` +
-        `Available environments: ${Object.keys(appYmlObject).join(', ')}\n` +
-        `Using 'production' configuration as fallback.\n\n` +
-        `To fix this, either:\n` +
-        `  - Add a '${railsEnv}' section to your shakapacker.yml\n` +
-        `  - Set RAILS_ENV to one of the available environments\n` +
-        `  - Copy settings from another environment as a starting point`
+          `Available environments: ${Object.keys(appYmlObject).join(", ")}\n` +
+          `Using 'production' configuration as fallback.\n\n` +
+          `To fix this, either:\n` +
+          `  - Add a '${railsEnv}' section to your shakapacker.yml\n` +
+          `  - Set RAILS_ENV to one of the available environments\n` +
+          `  - Copy settings from another environment as a starting point`
       )
     }
 
     // Merge returns the merged type
     const mergedConfig = merge(defaults, envAppConfig || {})
-    
+
     // Validate merged config before type assertion
     if (!isPartialConfig(mergedConfig)) {
       throw createConfigValidationError(
-        configPath, 
-        railsEnv, 
+        configPath,
+        railsEnv,
         `Invalid configuration structure in ${configPath}. Please check your shakapacker.yml syntax and ensure all required fields are properly defined.`
       )
     }
-    
+
     // After merging with defaults, config should be complete
     // Use type assertion only after validation
     config = mergedConfig as Config
@@ -79,8 +87,8 @@ if (existsSync(configPath)) {
       // File not found is OK, use defaults
       if (!isPartialConfig(defaults)) {
         throw createConfigValidationError(
-          defaultConfigPath, 
-          railsEnv, 
+          defaultConfigPath,
+          railsEnv,
           `Invalid default configuration. This may indicate a corrupted Shakapacker installation. Try reinstalling with 'yarn add shakapacker --force'.`
         )
       }
@@ -94,8 +102,8 @@ if (existsSync(configPath)) {
   // No user config, use defaults
   if (!isPartialConfig(defaults)) {
     throw createConfigValidationError(
-      defaultConfigPath, 
-      railsEnv, 
+      defaultConfigPath,
+      railsEnv,
       `Invalid default configuration. This may indicate a corrupted Shakapacker installation. Try reinstalling with 'yarn add shakapacker --force'.`
     )
   }
@@ -122,7 +130,9 @@ if (config.manifest_path) {
 }
 // Ensure no duplicate hash functions exist in the returned config object
 if (config.integrity?.hash_functions) {
-  config.integrity.hash_functions = [...new Set(config.integrity.hash_functions)]
+  config.integrity.hash_functions = [
+    ...new Set(config.integrity.hash_functions)
+  ]
 }
 
 // Ensure assets_bundler has a default value
@@ -130,7 +140,7 @@ if (!config.assets_bundler) {
   config.assets_bundler = "webpack"
 }
 
-// Allow ENV variable to override assets_bundler  
+// Allow ENV variable to override assets_bundler
 if (process.env.SHAKAPACKER_ASSETS_BUNDLER) {
   config.assets_bundler = process.env.SHAKAPACKER_ASSETS_BUNDLER
 }
@@ -138,16 +148,18 @@ if (process.env.SHAKAPACKER_ASSETS_BUNDLER) {
 // Define clear defaults
 // Keep Babel as default for webpack to maintain backward compatibility
 // Use SWC for rspack as it's a newer bundler where we can set modern defaults
-const DEFAULT_JAVASCRIPT_TRANSPILER = 
+const DEFAULT_JAVASCRIPT_TRANSPILER =
   config.assets_bundler === "rspack" ? "swc" : "babel"
 
 // Backward compatibility: Check for webpack_loader using proper type guard
-function hasWebpackLoader(obj: unknown): obj is Config & { webpack_loader: string } {
+function hasWebpackLoader(
+  obj: unknown
+): obj is Config & { webpack_loader: string } {
   return (
-    typeof obj === 'object' &&
+    typeof obj === "object" &&
     obj !== null &&
-    'webpack_loader' in obj &&
-    typeof (obj as Record<string, unknown>).webpack_loader === 'string'
+    "webpack_loader" in obj &&
+    typeof (obj as Record<string, unknown>).webpack_loader === "string"
   )
 }
 
@@ -157,7 +169,7 @@ if (process.env.SHAKAPACKER_JAVASCRIPT_TRANSPILER) {
 } else if (hasWebpackLoader(config) && !config.javascript_transpiler) {
   console.warn(
     "[SHAKAPACKER DEPRECATION] The 'webpack_loader' configuration option is deprecated.\n" +
-    "Please use 'javascript_transpiler' instead as it better reflects its purpose of configuring JavaScript transpilation regardless of the bundler used."
+      "Please use 'javascript_transpiler' instead as it better reflects its purpose of configuring JavaScript transpilation regardless of the bundler used."
   )
   config.javascript_transpiler = config.webpack_loader
 } else if (!config.javascript_transpiler) {
@@ -165,7 +177,7 @@ if (process.env.SHAKAPACKER_JAVASCRIPT_TRANSPILER) {
 }
 
 // Ensure webpack_loader is always available for backward compatibility
-Object.defineProperty(config, 'webpack_loader', {
+Object.defineProperty(config, "webpack_loader", {
   value: config.javascript_transpiler,
   writable: true,
   enumerable: true,