shakapacker 10.0.0 → 10.1.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08b8b40c44fa65d3a426d14596e15d7e5da7e486f0659c03822aa34a7f7e5474'
-  data.tar.gz: eadf1441efba9b99b1e9918075d12eb5cb08f4d71c63bb00d8c58c93d36d4ab6
+  metadata.gz: 632a8c1773b8b7168ac13d0b0675e886c3d1359635ddd695b32e12218748708c
+  data.tar.gz: 8dcd25b6593ff26d8b277c01c54a1df970e69ced4166a5a918c9123fc04bdea1
 SHA512:
-  metadata.gz: c50b9fe63645ef4f2890ed6e0ddeeb73a21afe51e827ed39d5daebafda00517bf5299e72ad056ecf74650214d21407f0de948a876a7a5ac789de1581240f8e64
-  data.tar.gz: 6651deb390179edc5aea7f0abe9db2a6065b5674be9e4d8eee13de5642d590f600673eab5f7178caa12d14547cce9e1ad376e784ebee2c1377205e9112e38a05
+  metadata.gz: 461f192f52757479deb8251b434b34b7c1839f923ae02725917f85ba96b47e1a1f9d45cc1dabf989f9fa33156dbcfa479d613143f2f2e0b95152a589be9bb852
+  data.tar.gz: a6070c988e4a317f91210f642eb25471fc2827c67e7cdad659a0c040839c0cd2c3adb1b9293eceb17a7586fd2128c4d46a776a8b387f5322bd53a348ec5ece82

data/CHANGELOG.md

@@ -9,6 +9,41 @@
 
 ## [Unreleased]
 
+## [v10.1.0-rc.0] - May 20, 2026
+
+### Added
+
+- **Added supplemental npm packages `shakapacker-webpack` and `shakapacker-rspack`**. [PR #1096](https://github.com/shakacode/shakapacker/pull/1096) by [justin808](https://github.com/justin808). Optional packages that lockstep with core and bundle the managed-build stack as direct `dependencies` (so a single `yarn add shakapacker-webpack` pulls in `shakapacker`, `webpack`, `webpack-cli`, and `webpack-assets-manifest`; the rspack package bundles `shakapacker`, `@rspack/core`, `@rspack/cli`, and `rspack-manifest-plugin`). Optional features (transpilers, dev-server, CSS preprocessors, react-refresh) remain as opt-in `peerDependencies` so SCSS/native-binding bloat isn't forced on every install. The wrappers emit structured warnings (`SHAKAPACKER_BUNDLER_MISMATCH`, `SHAKAPACKER_NO_TRANSPILER`) when `config.assets_bundler` or `javascript_transpiler` doesn't match the installed peers. See the [v10.1 migration guide](docs/migration/v10.1-supplemental-packages.md) for adoption steps and [`docs/dependency-strategy.md`](docs/dependency-strategy.md) for the design rationale and v11 roadmap.
+- **Added `shakapacker:doctor` check for disabled Rspack cache**. [PR #1100](https://github.com/shakacode/shakapacker/pull/1100) by [justin808](https://github.com/justin808). The doctor now inspects the Rspack config file for an explicit `cache: false`, warns when found (disabling cache causes significantly slower builds), and also flags Rspack v1 installs (where persistent cache is experimental) with a recommendation to upgrade to v2.
+- **Added a `shakapacker:doctor` hint to compiler output**. [PR #1100](https://github.com/shakacode/shakapacker/pull/1100) by [justin808](https://github.com/justin808). The compiler now logs a one-time tip suggesting `bundle exec rake shakapacker:doctor` after a failed compilation, so healthy build loops stay quiet.
+
+### Migration Notes
+
+- **Simplify your `package.json` by adopting a supplemental package**. Existing apps can drop the explicit managed-build deps from `devDependencies` and rely on the bundled stack:
+  - **Rspack apps** can replace `shakapacker` + `@rspack/core` + `@rspack/cli` + `rspack-manifest-plugin` with a single `shakapacker-rspack`. See `packages/shakapacker-rspack/README.md` §"Simplifying an existing rspack install" for the before/after.
+  - **Webpack apps** can replace `shakapacker` + `webpack` + `webpack-cli` + `webpack-assets-manifest` with a single `shakapacker-webpack`. See `packages/shakapacker-webpack/README.md` §"Simplifying an existing webpack install" for the before/after.
+  - Optional peers (transpilers, `webpack-dev-server`, CSS preprocessors, react-refresh) stay only if your app uses those features.
+  - Adoption is opt-in: leaving your `package.json` untouched on v10.1 also continues to work.
+
+- **Adopting `shakapacker-webpack` requires `webpack-assets-manifest@^6.0.0`**. Core `shakapacker` still accepts both v5 and v6 (`^5.0.6 || ^6.0.0`), but `shakapacker-webpack` pins `~6.5.1`. Apps still on `webpack-assets-manifest@5.x` must upgrade when switching to the supplemental package; v6 fixed an ENOENT crash on clean builds with `merge: true` and dropped a Node 14 install path. See [the v5→v6 release notes](https://github.com/webdeveric/webpack-assets-manifest/releases) and `packages/shakapacker-webpack/README.md` for details.
+
+### ⚠️ Breaking Changes
+
+- **Breaking: tightened `package.json` `engines.node` to `^20.19.0 || >=22.12.0`**. [PR #1099](https://github.com/shakacode/shakapacker/pull/1099) by [justin808](https://github.com/justin808). Raised from `>= 20`, dropping support for Node 20.0.0–20.18.x and Node 21.x to match `@rspack/core@2.0.0-rc.0`. Consumers on those versions will hit an engine error with `--engine-strict` or yarn workspaces and need to upgrade. The PR also bumps `.node-version` to `22.20.0` and updates `conductor-setup.sh` to enforce the same disjoint range up front, so contributors get a clear error before `yarn install` fails with a confusing engine mismatch.
+
+### Changed
+
+- **Changed `shakapacker:install` to default fresh Rspack installs to v2 (`^2.0.0-0`)**. [PR #1091](https://github.com/shakacode/shakapacker/pull/1091) by [ihabadham](https://github.com/ihabadham). `lib/install/package.json` now declares `@rspack/core` and `@rspack/cli` as `^1.0.0 || ^2.0.0-0`; fresh installs pick the v2 range. Existing apps are unaffected. Note: Rspack v2 requires Node.js 20.19.0+.
+- **Slimmed the published gem from ~486K (294 files) to ~121K (75 files)**. [PR #1110](https://github.com/shakacode/shakapacker/pull/1110) by [justin808](https://github.com/justin808). Replaced the broad `git ls-files` gem manifest with an explicit runtime/install allowlist (`CHANGELOG.md`, `MIT-LICENSE`, `README.md`, gemspec, `lib`, `sig`), excluding repo-only docs, tests, JavaScript package source, CI/tooling files, and `test_files` metadata from the published gem. Fixes [#987](https://github.com/shakacode/shakapacker/issues/987).
+
+### Fixed
+
+- **Fixed Rspack React Refresh plugin loading with `@rspack/plugin-react-refresh` v2**. [PR #1116](https://github.com/shakacode/shakapacker/pull/1116) by [justin808](https://github.com/justin808). Shakapacker now reads the v2 named `ReactRefreshRspackPlugin` export while retaining compatibility with v1 direct/default CommonJS export shapes, preventing `TypeError: ReactRefreshRspackPlugin is not a constructor` during rspack dev-server startup.
+- **Widened `@rspack/plugin-react-refresh` peer range to `^1.0.0 || ^2.0.0-0`**. [PR #1091](https://github.com/shakacode/shakapacker/pull/1091) by [ihabadham](https://github.com/ihabadham). Fixes the `ERESOLVE` conflict when installing `@rspack/plugin-react-refresh@^2.0.0` alongside `shakapacker@10.0.0`.
+- **Fixed `NodePackageVersion#find_version` for local-path `shakapacker` installs (e.g. `yalc`, `file:`, relative paths)**. [PR #1086](https://github.com/shakacode/shakapacker/pull/1086) by [justin808](https://github.com/justin808). The version check now consults `package.json` first and short-circuits on `../` or `file:` dependencies, so stale lockfile semvers no longer trigger false gem↔node version mismatches. `package_json_dependency` also consults `devDependencies` in addition to `dependencies`. The `LOCAL_PATH_REGEX` constant replaces a duplicated inline regex and anchors both alternatives to the start of the string, removing a latent false-positive on version strings containing `..` mid-value.
+- **Detected single-dot (`./...`) local-path declarations in `NodePackageVersion#find_version`**. [PR #1106](https://github.com/shakacode/shakapacker/pull/1106) by [justin808](https://github.com/justin808). Extended `LOCAL_PATH_REGEX` to treat `./vendor/shakapacker`-style declarations as local-path installs (alongside the `../` and `file:` patterns added in [#1086](https://github.com/shakacode/shakapacker/pull/1086)), so version checks short-circuit before consulting potentially stale lockfile semvers. Fixes [#1103](https://github.com/shakacode/shakapacker/issues/1103).
+- **Fix rspack setup not reusing certain shared webpack-rspack config settings**. [PR #1085](https://github.com/shakacode/shakapacker/pull/1085) by [brunodccarvalho](https://github.com/brunodccarvalho). Default config changes include `optimization.splitChunks.chunks="all"`, `optimization.runtimeChunk="single"`, the webpack compression plugin in production, and the removal of minimization plugins in development. Fixes [#984](https://github.com/shakacode/shakapacker/issues/984).
+
 ## [v10.0.0] - April 8, 2026
 
 ### Added
@@ -909,7 +944,8 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v10.0.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v10.1.0-rc.0...main
+[v10.1.0-rc.0]: https://github.com/shakacode/shakapacker/compare/v10.0.0...v10.1.0-rc.0
 [v10.0.0]: https://github.com/shakacode/shakapacker/compare/v9.7.0...v10.0.0
 [v9.7.0]: https://github.com/shakacode/shakapacker/compare/v9.6.1...v9.7.0
 [v9.6.1]: https://github.com/shakacode/shakapacker/compare/v9.6.0...v9.6.1

data/README.md

@@ -1,8 +1,8 @@
-# Shakapacker (v9)
+# Shakapacker (v10)
 
 ---
 
-_🚀 Shakapacker 9 supports [Rspack](https://rspack.rs/)! 10x faster than webpack!_
+_🚀 Shakapacker 10 supports [Rspack](https://rspack.rs/) — up to 17x faster than webpack per [upstream benchmarks](./docs/transpiler-performance.md#published-benchmarks)!_
 
 _📖 **Full documentation at [shakapacker.com](https://shakapacker.com)**_
 
@@ -11,7 +11,8 @@ _📖 **Full documentation at [shakapacker.com](https://shakapacker.com)**_
 _Official, actively maintained successor to [rails/webpacker](https://github.com/rails/webpacker). ShakaCode stands behind the long-term maintenance and development of this project for the Rails community._
 
 - ⚠️ See the [6-stable](https://github.com/shakacode/shakapacker/tree/6-stable) branch for Shakapacker v6.x code and documentation. :warning:
-- **See [V9 Upgrade](./docs/v9_upgrade.md) for upgrading from the v8 release.**
+- **See the [v10.0.0 release notes](https://github.com/shakacode/shakapacker/releases/tag/v10.0.0) for upgrading from v9 to v10.**
+- **See [V9 Upgrade](./docs/v9_upgrade.md) for upgrading from v8 to v9.**
 - See [V8 Upgrade](./docs/v8_upgrade.md) for upgrading from the v7 release.
 - See [V7 Upgrade](./docs/v7_upgrade.md) for upgrading from the v6 release.
 - See [V6 Upgrade](./docs/v6_upgrade.md) for upgrading from v5 or prior v6 releases.
@@ -21,7 +22,7 @@ _Official, actively maintained successor to [rails/webpacker](https://github.com
 [![Rubocop](https://github.com/shakacode/shakapacker/workflows/Rubocop/badge.svg)](https://github.com/shakacode/shakapacker/actions)
 [![JS lint](https://github.com/shakacode/shakapacker/workflows/JS%20lint/badge.svg)](https://github.com/shakacode/shakapacker/actions)
 
-[![node.js](https://img.shields.io/badge/node-%3E%3D%2020-brightgreen.svg)](https://www.npmjs.com/package/shakapacker)
+[![node.js](https://img.shields.io/badge/node-%5E20.19.0%20%7C%7C%20%3E%3D22.12.0-brightgreen.svg)](https://www.npmjs.com/package/shakapacker)
 [![Gem](https://img.shields.io/gem/v/shakapacker.svg)](https://rubygems.org/gems/shakapacker)
 [![npm version](https://badge.fury.io/js/shakapacker.svg)](https://badge.fury.io/js/shakapacker)
 
@@ -133,7 +134,7 @@ Here's a testimonial from Jon Rajavuori of [Academia.edu](https://www.academia.e
 
 - Ruby 2.7+
 - Rails 5.2+
-- Node.js 20+
+- Node.js `^20.19.0` or `>=22.12.0`
 
 ## Features
 
@@ -159,6 +160,8 @@ _Requires extra packages to be installed._
 
 ## Installation
 
+See the [Installation guide](./docs/installation.md) for a step-by-step walkthrough.
+
 ### Rails v6+
 
 With Rails v6+, skip JavaScript for a new app and follow below Manual Installation Steps to manually add the `shakapacker` gem to your Gemfile.
@@ -238,7 +241,7 @@ Depending on your setup, you'll need different subsets of the optional peer depe
 ```json
 {
   "dependencies": {
-    "shakapacker": "^9.0.0",
+    "shakapacker": "^10.0.0",
     "@babel/core": "^7.17.9",
     "@babel/plugin-transform-runtime": "^7.17.0",
     "@babel/preset-env": "^7.16.11",
@@ -261,7 +264,7 @@ Depending on your setup, you'll need different subsets of the optional peer depe
 ```json
 {
   "dependencies": {
-    "shakapacker": "^9.0.0",
+    "shakapacker": "^10.0.0",
     "@swc/core": "^1.3.0",
     "swc-loader": "^0.2.0",
     "compression-webpack-plugin": "^9.0.0",
@@ -274,14 +277,14 @@ Depending on your setup, you'll need different subsets of the optional peer depe
 }
 ```
 
-**For Rspack + SWC (10x faster bundling):**
+**For Rspack + SWC (largest end-to-end speedup — see [transpiler-performance guide](./docs/transpiler-performance.md#published-benchmarks)):**
 
 ```json
 {
   "dependencies": {
-    "shakapacker": "^9.0.0",
-    "@rspack/core": "^1.0.0",
-    "@rspack/cli": "^1.0.0",
+    "shakapacker": "^10.0.0",
+    "@rspack/core": "^2.0.0-0",
+    "@rspack/cli": "^2.0.0-0",
     "@swc/core": "^1.3.0",
     "swc-loader": "^0.2.0",
     "rspack-manifest-plugin": "^5.0.0"
@@ -923,7 +926,7 @@ You can also change your Babel configuration by removing these lines in your `pa
 
 ### SWC configuration
 
-SWC is the recommended JavaScript transpiler in Shakapacker v9+ (20x faster than Babel). New installations use SWC by default via the installation template. You can read more at [SWC usage docs](./docs/using_swc_loader.md).
+SWC is the recommended JavaScript transpiler in Shakapacker v10 (this default was introduced in v9). SWC's own benchmark reports being [20x faster than Babel on a single thread and 70x faster on four cores](https://swc.rs/); end-to-end Shakapacker speedups are typically smaller but still substantial. New installations use SWC by default via the installation template. You can read more at [SWC usage docs](./docs/using_swc_loader.md).
 
 **Note on defaults**: The installation template explicitly sets `javascript_transpiler: "swc"` for new projects. However, for backward compatibility, webpack's runtime default (when no explicit config exists) remains `"babel"`. Rspack always defaults to `"swc"`.
 
@@ -1272,13 +1275,19 @@ npm install shakapacker@next
 
 Also, consult the [CHANGELOG](./CHANGELOG.md) for additional upgrade links.
 
+#### Automating Updates with Dependabot
+
+Shakapacker is shipped as both a Ruby gem and an npm package, so they must be
+upgraded together. See [Dependabot configuration for Shakapacker](./docs/dependabot.md)
+for a `.github/dependabot.yml` example that updates both in a single PR.
+
 #### Common Upgrade Scenarios
 
 For step-by-step guides on common migrations, see the [Common Upgrades Guide](./docs/common-upgrades.md):
 
 - [Migrating Package Managers](./docs/common-upgrades.md#migrating-package-managers) (Yarn ↔ npm, pnpm)
-- [Migrating from Babel to SWC](./docs/common-upgrades.md#migrating-from-babel-to-swc) (20-70x faster builds)
-- [Migrating from Webpack to Rspack](./docs/common-upgrades.md#migrating-from-webpack-to-rspack) (5-10x faster builds)
+- [Migrating from Babel to SWC](./docs/common-upgrades.md#migrating-from-babel-to-swc) (upstream: ~20x faster transpilation)
+- [Migrating from Webpack to Rspack](./docs/common-upgrades.md#migrating-from-webpack-to-rspack) (upstream: ~8–17x faster bundler)
 
 ### Paths
 

data/lib/install/package.json

@@ -1,7 +1,7 @@
 {
   "rspack": {
-    "@rspack/cli": "^1.0.0",
-    "@rspack/core": "^1.0.0",
+    "@rspack/cli": "^1.0.0 || ^2.0.0-0",
+    "@rspack/core": "^1.0.0 || ^2.0.0-0",
     "rspack-manifest-plugin": "^5.0.0"
   },
   "webpack": {

data/lib/shakapacker/compiler.rb

@@ -9,6 +9,14 @@ class Shakapacker::Compiler
   # Shakapacker::Compiler.env['FRONTEND_API_KEY'] = 'your_secret_key'
   cattr_accessor(:env) { {} }
 
+  # Class-level state keeps the compile-time doctor hint once-per-process.
+  @doctor_hint_shown = false
+  DOCTOR_HINT_MUTEX = Mutex.new
+
+  class << self
+    attr_accessor :doctor_hint_shown
+  end
+
   delegate :config, :logger, :strategy, to: :instance
   delegate :fresh?, :stale?, :after_compile_hook, to: :strategy
 
@@ -184,6 +192,7 @@ class Shakapacker::Compiler
       else
         non_empty_streams = [stdout, stderr].delete_if(&:empty?)
         logger.error "\nCOMPILATION FAILED:\nEXIT STATUS: #{status}\nOUTPUTS:\n#{non_empty_streams.join("\n\n")}"
+        show_doctor_hint_once
       end
 
       status.success?
@@ -201,4 +210,24 @@ class Shakapacker::Compiler
     def bin_shakapacker_path
       config.root_path.join("bin/shakapacker")
     end
+
+    # Fires only after a failed compile, so users in a healthy loop never see the tip.
+    def show_doctor_hint_once
+      return if self.class.doctor_hint_shown
+
+      DOCTOR_HINT_MUTEX.synchronize do
+        return if self.class.doctor_hint_shown
+
+        begin
+          logger.info "Tip: run 'bundle exec rake shakapacker:doctor' to diagnose configuration issues."
+        rescue StandardError => _e
+          # Non-critical tip; never abort a build because the logger failed.
+          # Named (but unused) variable makes the deliberate swallow explicit.
+          return
+        end
+
+        # Assignment is outside the rescue so a flag-setter failure propagates rather than being silenced.
+        self.class.doctor_hint_shown = true
+      end
+    end
 end

data/lib/shakapacker/doctor.rb

@@ -60,6 +60,16 @@ module Shakapacker
         add_warning(message, CATEGORY_INFO)
       end
 
+      # Marks the warning as a Fix sub-item; the renderer owns the "Fix: " prefix and indentation.
+      # The stored category mirrors the parent warning so a fix attached to an action-required
+      # item is itself action-required (it's only rendered alongside its parent, but the data
+      # stays consistent for any downstream consumer).
+      def add_fix_hint(message)
+        parent = @warnings.reverse_each.find { |w| !w[:fix] }
+        category = parent ? parent[:category] : CATEGORY_RECOMMENDED
+        @warnings << { category: category, message: message, fix: true }
+      end
+
       def print_help
         puts <<~HELP
           Shakapacker Doctor - Diagnostic tool for Shakapacker configuration
@@ -110,6 +120,7 @@ module Shakapacker
         check_css_dependencies
         check_css_modules_configuration
         check_bundler_dependencies if config_exists?
+        check_rspack_cache_configuration if config_exists?
         check_file_type_dependencies if config_exists?
         check_sri_dependencies if config_exists?
         check_peer_dependencies
@@ -200,7 +211,7 @@ module Shakapacker
         # Match "bundler:" at start of line or preceded by non-underscore character
         if config_file.match?(/^\s*bundler:/m) || config_file.match?(/[^_]bundler:/)
           add_action_required("Deprecated config: 'bundler' should be renamed to 'assets_bundler' in #{config_relative_path}.")
-          add_action_required("  Fix: Open #{config_relative_path} and change 'bundler:' to 'assets_bundler:'.")
+          add_fix_hint("Open #{config_relative_path} and change 'bundler:' to 'assets_bundler:'.")
         end
       rescue => e
         # Ignore read errors as config file check already handles missing file
@@ -407,7 +418,7 @@ module Shakapacker
 
         unless missing_binstubs.empty?
           add_action_required("Missing binstubs: #{missing_binstubs.join(', ')}.")
-          add_action_required("  Fix: Run 'bundle exec rake shakapacker:binstubs' to create them.")
+          add_fix_hint("Run 'bundle exec rake shakapacker:binstubs' to create them.")
         end
       end
 
@@ -480,7 +491,7 @@ module Shakapacker
                         else "npm uninstall swc-loader"
             end
             add_warning("swc-loader is not needed with Rspack (SWC is built-in). Rspack includes SWC transpilation natively, so this package is redundant.")
-            add_warning("  Fix: Remove it with: #{remove_cmd}.")
+            add_fix_hint("Remove it with: #{remove_cmd}.")
           end
         end
       end
@@ -520,7 +531,7 @@ module Shakapacker
           babel_files << "package.json" if babel_in_package_json
           babel_files_str = babel_files.join(", ")
           add_warning("Babel configuration files found (#{babel_files_str}) but javascript_transpiler is '#{transpiler}'. These Babel configs are ignored by Shakapacker (though they may still be used by ESLint or other tools).")
-          add_warning("  Fix: Remove Babel config files if not needed, or set javascript_transpiler: 'babel' in shakapacker.yml to use Babel for transpilation.")
+          add_fix_hint("Remove Babel config files if not needed, or set javascript_transpiler: 'babel' in shakapacker.yml to use Babel for transpilation.")
         end
 
         # Check for redundant dependencies
@@ -681,6 +692,307 @@ module Shakapacker
         end
       end
 
+      def check_rspack_cache_configuration
+        return unless config.rspack?
+
+        rspack_major = rspack_major_version
+
+        if rspack_major == 1
+          add_warning("Rspack v1 detected: persistent caching is experimental in v1 and requires manual opt-in. " \
+                      "Upgrading to Rspack v2 enables stable persistent caching out of the box for significantly faster rebuilds.")
+          add_fix_hint("Bump @rspack/core and @rspack/cli to ^2.0.0-0 in package.json. See https://rspack.rs/config/cache and docs/rspack.md for details.")
+        end
+
+        path = active_assets_bundler_config_path
+        return unless path
+
+        content = read_active_assets_bundler_config(path)
+        return unless content
+
+        return unless rspack_cache_disabled?(content)
+
+        relative = config_path_for_warning(path)
+        add_warning("Rspack cache appears to be disabled in #{relative} (found 'cache: false'). Disabling cache " \
+                    "causes significantly slower builds, especially on rebuilds. Rspack v2 promotes filesystem " \
+                    "caching from experimental to stable.")
+        add_fix_hint("Remove the 'cache: false' setting, or use 'cache: { type: \"filesystem\" }' for persistent caching. " \
+                     "See https://rspack.rs/config/cache for options.")
+      end
+
+      # Returns the single active config path the runner would load, or nil. Mirrors the
+      # resolution order in Shakapacker::Runner#find_rspack_config_with_fallback so the
+      # doctor inspects the same file the build will actually use (and so unused sibling
+      # configs in the same directory don't trigger spurious warnings).
+      # NOTE: keep this candidate list in sync with Runner#find_rspack_config_with_fallback.
+      def active_assets_bundler_config_path
+        config_dir = config.assets_bundler_config_path.to_s
+
+        candidates = %w[ts js].map { |ext| Pathname.new(File.join(root_path.to_s, config_dir, "rspack.config.#{ext}")) }
+        candidates += %w[ts js].map { |ext| Pathname.new(File.join(root_path.to_s, config_dir, "webpack.config.#{ext}")) }
+        if default_rspack_config_dir?(config_dir)
+          candidates += %w[ts js].map { |ext| Pathname.new(File.join(root_path.to_s, "config/webpack", "webpack.config.#{ext}")) }
+        end
+
+        candidates.find(&:exist?)
+      end
+
+      def read_active_assets_bundler_config(path)
+        File.read(path)
+      rescue SystemCallError => e
+        add_info_warning("Unable to validate rspack cache configuration: #{e.message}")
+        nil
+      end
+
+      def default_rspack_config_dir?(config_dir)
+        # Intentionally exact-string match: mirrors the runner's own comparison,
+        # so a trailing slash or Pathname argument won't spuriously add the config/webpack fallback.
+        config_dir == "config/rspack"
+      end
+
+      def config_path_for_warning(path)
+        expanded_root = root_path.expand_path
+        expanded_path = path.expand_path
+
+        return path.to_s unless expanded_path.to_s == expanded_root.to_s ||
+                                expanded_path.to_s.start_with?("#{expanded_root}#{File::SEPARATOR}")
+
+        path.relative_path_from(root_path)
+      rescue ArgumentError
+        path.to_s
+      end
+
+      def rspack_cache_disabled?(content)
+        stripped = stripped_rspack_config_content(content)
+
+        direct_export_cache_disabled?(stripped) || exported_variable_cache_disabled?(stripped)
+      end
+
+      def stripped_rspack_config_content(content)
+        # Normalize quoted property keys before stripping string literals; otherwise
+        # `'cache'` and `"cache"` collapse to `""` and the match below misses them.
+        # Lookahead is restricted to horizontal whitespace so a multiline ternary
+        # like `condition ? "cache"\n  : false` doesn't fold across the newline
+        # and produce a spurious cache: false match.
+        stripped = content.gsub(/(['"])(\w+)\1(?=[ \t]*:)/, '\2')
+
+        stripped = strip_rspack_config_comments_and_literals(stripped)
+
+        # Regex literal stripping runs after comment removal. The line-comment
+        # pass above ignores escaped slashes so /https?:\/\/host/ stays intact
+        # until this pass removes the whole regex literal. The heuristic can
+        # false-match bare division like `a / b / c`, but rspack config files
+        # rarely contain arithmetic near `cache:`, so the risk is low.
+        stripped.gsub(%r{/(?:\\.|\[[^\]\n]*\]|[^/\n\\\[])+?/[gimsuy]*}, "")
+      end
+
+      def strip_rspack_config_comments_and_literals(content)
+        stripped = +""
+        index = 0
+
+        while index < content.length
+          char = content[index]
+          pair = content[index, 2]
+
+          if pair == "/*"
+            comment_end = content.index("*/", index + 2)
+            if comment_end
+              comment = content[index..comment_end + 1]
+              stripped << comment.gsub(/[^\n]/, " ")
+              index = comment_end + 2
+            else
+              stripped << content[index..].gsub(/[^\n]/, " ")
+              break
+            end
+          elsif pair == "//"
+            line_end = content.index("\n", index + 2) || content.length
+            stripped << content[index...line_end].gsub(/[^\n]/, " ")
+            index = line_end
+          elsif char == "'" || char == '"'
+            literal_end = index + 1
+            escaped = false
+
+            while literal_end < content.length
+              current = content[literal_end]
+              break if current == "\n"
+
+              if escaped
+                escaped = false
+              elsif current == "\\"
+                escaped = true
+              elsif current == char
+                literal_end += 1
+                break
+              end
+
+              literal_end += 1
+            end
+
+            literal = content[index...literal_end]
+            stripped << '""'
+            stripped << literal.gsub(/[^\n]/, "")
+            index = literal_end
+          elsif char == "`"
+            literal_end = index + 1
+            escaped = false
+            closed = false
+
+            while literal_end < content.length
+              current = content[literal_end]
+
+              if escaped
+                escaped = false
+              elsif current == "\\"
+                escaped = true
+              elsif current == "`"
+                literal_end += 1
+                closed = true
+                break
+              end
+
+              literal_end += 1
+            end
+
+            if closed
+              literal = content[index...literal_end]
+              stripped << '""'
+              stripped << literal.gsub(/[^\n]/, "")
+              index = literal_end
+            else
+              stripped << char
+              index += 1
+            end
+          else
+            stripped << char
+            index += 1
+          end
+        end
+
+        stripped
+      end
+
+      def direct_export_cache_disabled?(stripped)
+        # Match `cache: false` only near an exported config object at brace depth
+        # 1. This avoids warning on local base config objects while still
+        # catching the common direct export and generateRspackConfig patterns.
+        #
+        # Known false-positive gaps (rare; the "appears to be disabled" wording
+        # is the user-visible mitigation):
+        #   * Named intermediate export — `export const helper = { cache: false }`
+        #     at depth 1 is flagged even when `helper` is not the final config and
+        #     a separate `export default { … }` provides the real configuration.
+        #   * ASI + prior `module.exports` — in semicolon-free code, an earlier
+        #     `module.exports = merge(…)` followed by a local helper literal can
+        #     leak into `statement_prefix` because `pre.rindex(";")` returns nil
+        #     and the prefix spans back to the start of the file.
+        stripped.to_enum(:scan, /\bcache\s*:\s*false\b/).any? do
+          pre = Regexp.last_match.pre_match
+          next false unless (pre.count("{") - pre.count("}")) == 1
+
+          statement_prefix = pre[(pre.rindex(";") || -1) + 1..]
+          # generateRspackConfig is Shakapacker's own helper; user-defined wrappers
+          # like makeRspackConfig/createConfig are a known false-negative gap.
+          statement_prefix.match?(/\bmodule\.exports\b|\bexport\s+default\b|\bexport\s+(?:const|let|var)\b|\bgenerateRspackConfig\b/)
+        end
+      end
+
+      # Catches the `const cfg = { cache: false }; module.exports = cfg` pattern.
+      # Composition via merge (`module.exports = merge(cfg, …)`) is a known
+      # false-negative since the variable is never referenced by name in the
+      # export statement. The `[^=;]+` type-annotation clause also stops at the
+      # first `=`, so TypeScript generics with default type parameters such as
+      # `Configuration<Opts = DefaultOpts>` are another known false-negative gap.
+      def exported_variable_cache_disabled?(stripped)
+        variable_declaration = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)(?:\s*:\s*[^=;]+)?\s*=\s*\{/
+
+        stripped.to_enum(:scan, variable_declaration).any? do
+          name = Regexp.last_match[1]
+          open_index = Regexp.last_match.end(0) - 1
+          close_index = matching_closing_brace(stripped, open_index)
+          next false unless close_index
+
+          object_source = stripped[open_index..close_index]
+          top_level_cache_false?(object_source) && exported_config_variable?(stripped, name)
+        end
+      end
+
+      def top_level_cache_false?(object_source)
+        object_source.to_enum(:scan, /\bcache\s*:\s*false\b/).any? do
+          pre = Regexp.last_match.pre_match
+          (pre.count("{") - pre.count("}")) == 1
+        end
+      end
+
+      def exported_config_variable?(stripped, name)
+        escaped_name = Regexp.escape(name)
+        stripped.match?(/\bmodule\.exports\s*=\s*#{escaped_name}\b/) ||
+          stripped.match?(/\bexport\s+default\s+#{escaped_name}\b/) ||
+          stripped.match?(/\bexport\s*\{[^}]*\b#{escaped_name}\s+as\s+default\b/)
+      end
+
+      def matching_closing_brace(content, open_index)
+        depth = 0
+
+        content[open_index..].each_char.with_index do |char, offset|
+          depth += 1 if char == "{"
+          depth -= 1 if char == "}"
+
+          return open_index + offset if depth.zero?
+        end
+
+        nil
+      end
+
+      def rspack_major_version
+        # Prefer the resolved version from node_modules, since package.json specifiers
+        # (ranges, git refs, file paths) often don't parse to a clean major number.
+        resolved = installed_rspack_major_version
+        return resolved unless resolved.nil?
+
+        %w[@rspack/core @rspack/cli].each do |package_name|
+          major = rspack_major_from_specifier(package_json_dependency_version(package_name))
+          return major unless major.nil?
+        end
+
+        nil
+      end
+
+      def rspack_major_from_specifier(version)
+        return nil unless version
+
+        # Only trust specifiers starting with a digit or ^/~ prefix followed by
+        # a digit. Skip git+, file:, npm: aliases, "latest", "*", or ranges like
+        # ">=1.5 <2". Accept shorthand forms (e.g. `^1`, `~1`, `1`, `1.x`) so
+        # we still emit the v1 advisory when node_modules isn't populated yet.
+        cleaned = version.strip
+        return nil unless cleaned.match?(/\A[\^~]?\d/)
+        return nil if cleaned.match?(/(\s|\|\||[<>=:]|\A(?:git|file|link|workspace|npm):)/)
+        return nil unless cleaned.match?(/\A[\^~]?\d+(?:\.(?:\d+|x|\*)){0,2}(?:-[0-9A-Za-z.-]+)?\z/i)
+
+        match = cleaned.sub(/\A[\^~]/, "").match(/\A(\d+)/)
+        match && match[1].to_i
+      end
+
+      def installed_rspack_major_version
+        rspack_pkg = root_path.join("node_modules/@rspack/core/package.json")
+        return nil unless rspack_pkg.exist?
+
+        version = JSON.parse(File.read(rspack_pkg))["version"]
+        match = version.to_s.match(/\A(\d+)\./)
+        match && match[1].to_i
+      rescue JSON::ParserError, SystemCallError
+        nil
+      end
+
+      def package_json_dependency_version(name)
+        return nil unless package_json_exists?
+
+        pkg = read_package_json
+        # Production dependencies take precedence on key conflict so the version
+        # actually shipped in production wins over a devDependencies override.
+        deps = (pkg["devDependencies"] || {}).merge(pkg["dependencies"] || {})
+        deps[name]
+      end
+
       def check_file_type_dependencies
         source_path = config.source_path
         return unless source_path.exist?
@@ -1064,15 +1376,14 @@ module Shakapacker
           end
 
           def print_warnings
-            # Count only main items (not sub-items)
-            main_item_count = doctor.warnings.count { |w| !w[:message].start_with?("  ") }
+            main_item_count = doctor.warnings.count { |w| !subitem?(w) }
             puts "⚠️  Warnings (#{main_item_count}):"
             puts ""
 
             item_number = 0
             doctor.warnings.each do |warning|
-              if subitem?(warning[:message])
-                print_subitem(warning[:message])
+              if subitem?(warning)
+                print_subitem(warning)
               else
                 item_number += 1
                 print_main_item(item_number, warning)
@@ -1081,15 +1392,16 @@ module Shakapacker
             puts ""
           end
 
-          def subitem?(message)
-            message.start_with?("  ")
+          def subitem?(warning)
+            warning[:fix] || warning[:message].start_with?("  ")
           end
 
-          def print_subitem(message)
+          def print_subitem(warning)
             # Fix instructions align at column 16 (length of "N. [RECOMMENDED]  ")
-            # This ensures all Fix lines align vertically regardless of category
+            # This keeps every Fix line aligned regardless of category.
             subitem_prefix = " " * 15
-            wrapped = wrap_text(message, 100, subitem_prefix)
+            text = warning[:fix] ? "Fix: #{warning[:message]}" : warning[:message]
+            wrapped = wrap_text(text, 100, subitem_prefix)
             puts wrapped
           end
 

data/lib/shakapacker/version.rb

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