shakapacker 9.3.0.beta.7 → 9.3.0

data/docs/troubleshooting.md

@@ -21,7 +21,7 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
 
 4. You can also pass additional options to the command to run the webpack-dev-server and start the webpack-dev-server with the option `--debug-shakapacker`
 
-5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/export-bundler-config` utility to export your complete resolved configuration. This is especially helpful for:
+5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/shakapacker-config` utility to export your complete resolved configuration. This is especially helpful for:
    - **Migrations**: Comparing configurations before and after migrating between webpack and rspack, or between different Shakapacker versions
    - **Debugging**: Inspecting the exact configuration webpack/rspack is using, including all merged settings
    - **AI Analysis**: Uploading the exported config to ChatGPT or other AI tools for troubleshooting
@@ -35,7 +35,7 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
    rake shakapacker:binstubs
 
    # Export EVERYTHING for troubleshooting (dev + prod, annotated YAML)
-   bin/export-bundler-config --doctor
+   bin/shakapacker-config --doctor
    # Creates: webpack-development-client.yaml, webpack-development-server.yaml,
    #          webpack-production-client.yaml, webpack-production-server.yaml
    ```
@@ -44,28 +44,28 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
 
    ```bash
    # Save current environment configs with auto-generated names
-   bin/export-bundler-config --save
+   bin/shakapacker-config --save
    # Creates: webpack-development-client.yaml, webpack-development-server.yaml
 
    # Save to specific directory
-   bin/export-bundler-config --save --save-dir=./debug-configs
+   bin/shakapacker-config --save --save-dir=./debug-configs
 
    # Export only client config for production
-   bin/export-bundler-config --save --env=production --client-only
+   bin/shakapacker-config --save --env=production --client-only
    # Creates: webpack-production-client.yaml
 
    # Compare development vs production configs
-   bin/export-bundler-config --save --save-dir=./configs
+   bin/shakapacker-config --save --save-dir=./configs
    diff configs/webpack-development-client.yaml configs/webpack-production-client.yaml
 
    # View config in terminal (no files created)
-   bin/export-bundler-config
+   bin/shakapacker-config
 
    # Export without inline documentation annotations
-   bin/export-bundler-config --save --no-annotate
+   bin/shakapacker-config --save --no-annotate
 
    # Export in JSON format for programmatic analysis
-   bin/export-bundler-config --save --format=json
+   bin/shakapacker-config --save --format=json
    ```
 
    **Config files are automatically named:** `{bundler}-{env}-{type}.{ext}`
@@ -73,9 +73,9 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
    - YAML format includes inline documentation explaining each config key
    - Separate files for client and server bundles (cleaner than combined)
 
-   See `bin/export-bundler-config --help` for all available options.
+   See `bin/shakapacker-config --help` for all available options.
 
-6. **Validate your webpack/rspack builds**: Use `bin/export-bundler-config --validate` to test that all your build configurations compile successfully. This is especially useful for:
+6. **Validate your webpack/rspack builds**: Use `bin/shakapacker-config --validate` to test that all your build configurations compile successfully. This is especially useful for:
    - **CI/CD pipelines**: Catch configuration errors before deployment
    - **Migration testing**: Verify builds work after upgrading webpack, rspack, or Shakapacker
    - **Multi-environment testing**: Ensure all build configurations (dev, prod, HMR) compile correctly
@@ -84,13 +84,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
 
    ```bash
    # Validate all builds defined in .bundler-config.yml
-   bin/export-bundler-config --validate
+   bin/shakapacker-config --validate
 
    # Validate with full output logs (shows all webpack/rspack compilation output)
-   bin/export-bundler-config --validate --verbose
+   bin/shakapacker-config --validate --verbose
 
    # Validate a specific build
-   bin/export-bundler-config --validate-build=dev-hmr
+   bin/shakapacker-config --validate-build=dev-hmr
    ```
 
    **Verbose Mode:**
@@ -108,13 +108,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
 
    ```bash
    # Create a .bundler-config.yml file with example builds
-   bin/export-bundler-config --init
+   bin/shakapacker-config --init
 
    # List all available builds
-   bin/export-bundler-config --list-builds
+   bin/shakapacker-config --list-builds
 
    # Validate all builds
-   bin/export-bundler-config --validate
+   bin/shakapacker-config --validate
    ```
 
    **Advanced options:**
@@ -177,9 +177,9 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
    💡 Debugging Tips:
       To get more details, run individual builds with --verbose:
 
-      bin/export-bundler-config --validate-build prod --verbose
+      bin/shakapacker-config --validate-build prod --verbose
 
-      Or validate all builds with full output: bin/export-bundler-config --validate --verbose
+      Or validate all builds with full output: bin/shakapacker-config --validate --verbose
    ================================================================================
    ```
 
@@ -189,13 +189,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
    1. **Run a specific build with verbose output** to see full webpack/rspack logs:
 
       ```bash
-      bin/export-bundler-config --validate-build prod --verbose
+      bin/shakapacker-config --validate-build prod --verbose
       ```
 
    2. **Validate all builds with verbose output** to see everything:
 
       ```bash
-      bin/export-bundler-config --validate --verbose
+      bin/shakapacker-config --validate --verbose
       ```
 
    3. **Test individual builds manually** using the same configuration:

data/eslint.config.fast.js

@@ -25,6 +25,14 @@ module.exports = [
     ]
   },
 
+  // Global linter options
+  {
+    linterOptions: {
+      reportUnusedDisableDirectives: "error",
+      reportUnusedInlineConfigs: "error"
+    }
+  },
+
   // Base config for all JS files
   ...compat.extends("airbnb"),
   {

data/eslint.config.js

@@ -23,10 +23,20 @@ module.exports = [
       // Temporarily ignore TypeScript files until technical debt is resolved
       // See ESLINT_TECHNICAL_DEBT.md for tracking
       // TODO: Remove this once ESLint issues are fixed (tracked in #723)
-      "package/**/*.ts"
+      // Exception: configExporter is being fixed in #707
+      "package/**/*.ts",
+      "!package/configExporter/**/*.ts" // Enable linting for configExporter (issue #707)
     ]
   },
 
+  // Global linter options
+  {
+    linterOptions: {
+      reportUnusedDisableDirectives: "error",
+      reportUnusedInlineConfigs: "error"
+    }
+  },
+
   // Base config for all JS files
   ...compat.extends("airbnb"),
   {
@@ -181,21 +191,48 @@ module.exports = [
     }
   },
   {
+    // #707: Significant type safety improvements in configExporter module!
+    // - configFile.ts: ✅ Fully type-safe (0 type errors)
+    // - buildValidator.ts: ✅ Fully type-safe (0 type errors)
+    // - yamlSerializer.ts: ✅ Fully type-safe (0 type errors)
+    // - cli.ts: ⚠️ Partial (dynamic webpack config loading requires some `any`)
+    //
+    // Remaining overrides are for:
+    // 1. Code style/organization (not type safety)
+    // 2. Dynamic require() in cli.ts for webpack config loading
     files: ["package/configExporter/**/*.ts"],
+    rules: {
+      // Code organization (functions before use due to large file)
+      "@typescript-eslint/no-use-before-define": "off",
+      // Import style (CommonJS require for dynamic imports)
+      "@typescript-eslint/no-require-imports": "off",
+      "import/no-dynamic-require": "off",
+      "global-require": "off",
+      // Class methods that are part of public API
+      "class-methods-use-this": "off",
+      // Template expressions (valid use cases with union types)
+      "@typescript-eslint/restrict-template-expressions": "off",
+      // Style preferences
+      "no-continue": "off",
+      "import/prefer-default-export": "off",
+      "no-await-in-loop": "off",
+      "no-underscore-dangle": "off",
+      "no-shadow": "off",
+      "no-restricted-globals": "off",
+      "@typescript-eslint/no-unused-vars": "off",
+      "@typescript-eslint/require-await": "off"
+    }
+  },
+  {
+    // cli.ts: Dynamic webpack config loading requires `any` types
+    // This is acceptable as webpack configs can have any shape
+    files: ["package/configExporter/cli.ts"],
     rules: {
       "@typescript-eslint/no-explicit-any": "off",
       "@typescript-eslint/no-unsafe-assignment": "off",
       "@typescript-eslint/no-unsafe-member-access": "off",
       "@typescript-eslint/no-unsafe-call": "off",
-      "@typescript-eslint/no-unsafe-return": "off",
-      "@typescript-eslint/no-unsafe-argument": "off",
-      "@typescript-eslint/no-unsafe-function-type": "off",
-      "@typescript-eslint/no-unused-vars": "off",
-      "@typescript-eslint/require-await": "off",
-      "no-await-in-loop": "off",
-      "import/prefer-default-export": "off",
-      "global-require": "off",
-      "no-underscore-dangle": "off"
+      "@typescript-eslint/no-unsafe-return": "off"
     }
   },
   {

data/knip.ts

@@ -47,7 +47,14 @@ const config: KnipConfig = {
     "css-loader",
     "esbuild-loader",
     "swc-loader",
-    "webpack"
+    "webpack",
+    // eslint-config-airbnb isn't detected because it's used by compat.extends("airbnb"),
+    // the rest are its peerDependencies
+    "eslint-config-airbnb",
+    "eslint-plugin-import",
+    "eslint-plugin-jsx-a11y",
+    "eslint-plugin-react",
+    "eslint-plugin-react-hooks"
   ]
 }
 

data/lib/install/config/shakapacker.yml

@@ -67,9 +67,8 @@ default: &default
   compiler_strategy: digest
 
   # Select whether the compiler will always use a content hash and not just in production
-  # Don't use contentHash except for production for performance
-  # https://webpack.js.org/guides/build-performance/#avoid-production-specific-tooling
-  useContentHash: false
+  # Content hashes are recommended for production cache busting
+  useContentHash: true
 
   # Setting the asset host here will override Rails.application.config.asset_host.
   # Here, you can set different asset_host per environment. Note that
@@ -101,6 +100,10 @@ development:
   compile: true
   compiler_strategy: mtime
 
+  # Disable content hashes in development for faster builds
+  # https://webpack.js.org/guides/caching/
+  useContentHash: false
+
   # Early hints disabled by default in development
   # To enable: Set enabled: true AND start Puma with: bundle exec puma --early-hints
   # See docs/early_hints_new_api.md for setup instructions
@@ -164,9 +167,6 @@ production:
   # Production depends on precompilation of packs prior to booting for performance.
   compile: false
 
-  # Use content hash for naming assets. Cannot be overridden in production.
-  useContentHash: true
-
   # Cache manifest.json for performance
   cache_manifest: true
 

data/lib/shakapacker/configuration.rb

@@ -3,13 +3,62 @@ require "json"
 require "active_support/core_ext/hash/keys"
 require "active_support/core_ext/hash/indifferent_access"
 
+# Configuration management for Shakapacker
+#
+# Loads and provides access to settings from +config/shakapacker.yml+, including:
+# - Source and output paths
+# - Compilation settings
+# - Dev server configuration
+# - Asset bundler selection (webpack vs rspack)
+# - JavaScript transpiler configuration (babel, swc, esbuild)
+#
+# Configuration values can be overridden via environment variables:
+# - +SHAKAPACKER_CONFIG+ - path to config file
+# - +SHAKAPACKER_PRECOMPILE+ - whether to precompile assets
+# - +SHAKAPACKER_ASSETS_BUNDLER+ - which bundler to use
+# - +SHAKAPACKER_ASSET_HOST+ - CDN or asset host URL
+#
+# @example Accessing configuration
+#   config = Shakapacker.config
+#   config.source_path
+#   #=> #<Pathname:/app/app/packs>
+#   config.webpack?
+#   #=> true
+#
+# @see https://github.com/shakacode/shakapacker/blob/main/docs/shakapacker.yml.md
 class Shakapacker::Configuration
   class << self
+    # Flag indicating whether Shakapacker is currently being installed
+    # Used to suppress certain validations during installation
+    # @return [Boolean] true if installation is in progress
+    # @api private
     attr_accessor :installing
   end
 
-  attr_reader :root_path, :config_path, :env, :bundler_override
-
+  # The application root path
+  # @return [Pathname] the root path
+  attr_reader :root_path
+
+  # The path to the shakapacker.yml configuration file
+  # @return [Pathname] the config file path
+  attr_reader :config_path
+
+  # The current Rails environment
+  # @return [ActiveSupport::StringInquirer] the environment
+  attr_reader :env
+
+  # Override for the assets bundler (set via CLI flag)
+  # @return [String, nil] the bundler override or nil
+  # @api private
+  attr_reader :bundler_override
+
+  # Creates a new configuration instance
+  #
+  # @param root_path [Pathname] the application root path
+  # @param config_path [Pathname] the path to shakapacker.yml
+  # @param env [ActiveSupport::StringInquirer] the Rails environment
+  # @param bundler_override [String, nil] optional bundler override (webpack or rspack)
+  # @return [Shakapacker::Configuration] the new configuration instance
   def initialize(root_path:, config_path:, env:, bundler_override: nil)
     @root_path = root_path
     @env = env
@@ -17,22 +66,52 @@ class Shakapacker::Configuration
     @bundler_override = bundler_override
   end
 
+  # Returns the dev server configuration hash
+  #
+  # Contains settings like host, port, https, hmr, etc. for the webpack-dev-server.
+  #
+  # @return [Hash] the dev server configuration
   def dev_server
     fetch(:dev_server)
   end
 
+  # Returns whether automatic compilation is enabled
+  #
+  # When true, Shakapacker will automatically compile assets when they're requested
+  # and are stale. This is typically enabled in development and disabled in production.
+  #
+  # @return [Boolean] true if automatic compilation is enabled
   def compile?
     fetch(:compile)
   end
 
+  # Returns whether nested entries are enabled
+  #
+  # When true, allows organizing entry points in subdirectories within the
+  # source entry path.
+  #
+  # @return [Boolean] true if nested entries are allowed
   def nested_entries?
     fetch(:nested_entries)
   end
 
+  # Returns whether consistent versioning check is enabled
+  #
+  # When true, verifies that package.json and Gemfile versions of shakapacker match.
+  #
+  # @return [Boolean] true if version consistency checking is enabled
   def ensure_consistent_versioning?
     fetch(:ensure_consistent_versioning)
   end
 
+  # Returns whether Shakapacker should precompile assets
+  #
+  # Checks in order:
+  # 1. SHAKAPACKER_PRECOMPILE environment variable (yes/true/y/t or no/false/n/f)
+  # 2. shakapacker_precompile setting in config file
+  # 3. Defaults to false if config file doesn't exist
+  #
+  # @return [Boolean] true if assets should be precompiled
   def shakapacker_precompile?
     # ENV of false takes precedence
     return false if %w(no false n f).include?(ENV["SHAKAPACKER_PRECOMPILE"])
@@ -42,18 +121,40 @@ class Shakapacker::Configuration
     fetch(:shakapacker_precompile)
   end
 
+  # Returns the absolute path to the source directory
+  #
+  # This is where your JavaScript/CSS source files live (e.g., app/packs).
+  #
+  # @return [Pathname] the absolute source path
   def source_path
     root_path.join(fetch(:source_path))
   end
 
+  # Returns additional paths to include in compilation
+  #
+  # These paths are added to webpack/rspack's resolve configuration to allow
+  # importing modules from additional directories.
+  #
+  # @return [Array<String>] array of additional paths
   def additional_paths
     fetch(:additional_paths)
   end
 
+  # Returns the absolute path to the source entry directory
+  #
+  # Entry points (application.js, etc.) are found in this directory.
+  #
+  # @return [Pathname] the absolute entry path
   def source_entry_path
     source_path.join(relative_path(fetch(:source_entry_path)))
   end
 
+  # Returns the absolute path to the manifest.json file
+  #
+  # The manifest maps source file names to their compiled output paths with digests.
+  # Defaults to manifest.json in the public output directory if not configured.
+  #
+  # @return [Pathname] the absolute manifest path
   def manifest_path
     if data.has_key?(:manifest_path)
       root_path.join(fetch(:manifest_path))
@@ -62,14 +163,30 @@ class Shakapacker::Configuration
     end
   end
 
+  # Alias for {#manifest_path}
+  #
+  # @return [Pathname] the absolute manifest path
+  # @see #manifest_path
   def public_manifest_path
     manifest_path
   end
 
+  # Returns the absolute path to the public root directory
+  #
+  # This is typically the Rails +public/+ directory where compiled assets
+  # are served from.
+  #
+  # @return [Pathname] the absolute public path
   def public_path
     root_path.join(fetch(:public_root_path))
   end
 
+  # Returns the absolute path to the private output directory
+  #
+  # The private output path is for server-side bundles (e.g., SSR) that should
+  # not be publicly accessible. Returns nil if not configured.
+  #
+  # @return [Pathname, nil] the absolute private output path or nil
   def private_output_path
     private_path = fetch(:private_output_path)
     return nil unless private_path
@@ -77,26 +194,66 @@ class Shakapacker::Configuration
     root_path.join(private_path)
   end
 
+  # Returns the absolute path to the public output directory
+  #
+  # This is where compiled assets are written for public serving
+  # (typically +public/packs+).
+  #
+  # @return [Pathname] the absolute public output path
   def public_output_path
     public_path.join(fetch(:public_output_path))
   end
 
+  # Returns whether manifest caching is enabled
+  #
+  # When true, the manifest.json file is cached in memory and only reloaded
+  # when it changes. This improves performance in production.
+  #
+  # @return [Boolean] true if manifest should be cached
   def cache_manifest?
     fetch(:cache_manifest)
   end
 
+  # Returns the absolute path to the compilation cache directory
+  #
+  # Webpack/rspack uses this directory to cache compilation results for faster
+  # subsequent builds.
+  #
+  # @return [Pathname] the absolute cache path
   def cache_path
     root_path.join(fetch(:cache_path))
   end
 
+  # Returns whether webpack/rspack compilation output should be shown
+  #
+  # When true, displays webpack/rspack's compilation progress and results.
+  #
+  # @return [Boolean] true if compilation output should be displayed
   def webpack_compile_output?
     fetch(:webpack_compile_output)
   end
 
+  # Returns the compiler strategy for determining staleness
+  #
+  # Options:
+  # - +"mtime"+ - use file modification times (faster, less accurate)
+  # - +"digest"+ - use file content digests (slower, more accurate)
+  #
+  # @return [String] the compiler strategy ("mtime" or "digest")
   def compiler_strategy
     fetch(:compiler_strategy)
   end
 
+  # Returns the assets bundler to use (webpack or rspack)
+  #
+  # Resolution order:
+  # 1. CLI --bundler flag (via bundler_override)
+  # 2. SHAKAPACKER_ASSETS_BUNDLER environment variable
+  # 3. assets_bundler setting in config file
+  # 4. bundler setting in config file (deprecated)
+  # 5. Defaults to "webpack"
+  #
+  # @return [String] "webpack" or "rspack"
   def assets_bundler
     # CLI --bundler flag takes highest precedence
     return @bundler_override if @bundler_override
@@ -108,19 +265,35 @@ class Shakapacker::Configuration
     ENV["SHAKAPACKER_ASSETS_BUNDLER"] || fetch(:assets_bundler) || fetch(:bundler) || "webpack"
   end
 
-  # Deprecated: Use assets_bundler instead
+  # Deprecated alias for {#assets_bundler}
+  #
+  # @deprecated Use {#assets_bundler} instead
+  # @return [String] the assets bundler
+  # @see #assets_bundler
   def bundler
     assets_bundler
   end
 
+  # Returns whether rspack is the configured bundler
+  #
+  # @return [Boolean] true if using rspack
   def rspack?
     assets_bundler == "rspack"
   end
 
+  # Returns whether webpack is the configured bundler
+  #
+  # @return [Boolean] true if using webpack
   def webpack?
     assets_bundler == "webpack"
   end
 
+  # Returns the precompile hook command to run after compilation
+  #
+  # The hook is a shell command that runs after successful compilation,
+  # useful for post-processing tasks.
+  #
+  # @return [String, nil] the hook command or nil if not configured
   def precompile_hook
     hook = fetch(:precompile_hook)
     return nil if hook.nil? || (hook.is_a?(String) && hook.strip.empty?)
@@ -132,6 +305,16 @@ class Shakapacker::Configuration
     hook.strip
   end
 
+  # Returns the JavaScript transpiler to use (babel, swc, or esbuild)
+  #
+  # Resolution order:
+  # 1. javascript_transpiler setting in config file
+  # 2. webpack_loader setting in config file (deprecated)
+  # 3. Default based on bundler (swc for rspack, babel for webpack)
+  #
+  # Validates that the configured transpiler matches installed packages.
+  #
+  # @return [String] "babel", "swc", or "esbuild"
   def javascript_transpiler
     # Show deprecation warning if using old 'webpack_loader' key
     if data.has_key?(:webpack_loader) && !data.has_key?(:javascript_transpiler)
@@ -147,11 +330,21 @@ class Shakapacker::Configuration
     transpiler
   end
 
-  # Deprecated: Use javascript_transpiler instead
+  # Deprecated alias for {#javascript_transpiler}
+  #
+  # @deprecated Use {#javascript_transpiler} instead
+  # @return [String] the JavaScript transpiler
+  # @see #javascript_transpiler
   def webpack_loader
     javascript_transpiler
   end
 
+  # Returns the path to the bundler configuration directory
+  #
+  # This is where webpack.config.js or rspack.config.js should be located.
+  # Defaults to config/webpack for webpack or config/rspack for rspack.
+  #
+  # @return [String] the relative path to the bundler config directory
   def assets_bundler_config_path
     custom_path = fetch(:assets_bundler_config_path)
     return custom_path if custom_path
@@ -220,10 +413,28 @@ class Shakapacker::Configuration
 
   public
 
+  # Fetches a configuration value
+  #
+  # Looks up the value in the loaded configuration data, falling back to
+  # the default configuration if not found.
+  #
+  # @param key [Symbol] the configuration key to fetch
+  # @return [Object] the configuration value
+  # @api private
   def fetch(key)
     data.fetch(key, defaults[key])
   end
 
+  # Returns the asset host URL for serving assets
+  #
+  # Resolution order:
+  # 1. SHAKAPACKER_ASSET_HOST environment variable
+  # 2. asset_host setting in config file
+  # 3. Rails ActionController::Base.helpers.compute_asset_host
+  #
+  # Used to serve assets from a CDN or different domain.
+  #
+  # @return [String, nil] the asset host URL or nil
   def asset_host
     ENV.fetch(
       "SHAKAPACKER_ASSET_HOST",
@@ -231,10 +442,22 @@ class Shakapacker::Configuration
     )
   end
 
+  # Returns whether subresource integrity (SRI) is enabled
+  #
+  # When true, generates integrity hashes for script and link tags to
+  # protect against compromised CDNs or man-in-the-middle attacks.
+  #
+  # @return [Boolean] true if integrity checking is enabled
   def integrity
     fetch(:integrity)
   end
 
+  # Returns whether HTTP/2 Early Hints are enabled
+  #
+  # When true, sends Early Hints headers to start loading assets before
+  # the full response is ready.
+  #
+  # @return [Boolean] true if early hints are enabled
   def early_hints
     fetch(:early_hints)
   end