shakapacker 9.3.0.beta.0 → 9.3.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 673dbe7651111125cf2c4c408e128be24f73475825910473ced26eba32929f6e
-  data.tar.gz: 83af8568e4d40e9859483ee4d71d7164facb0c5c2131880912e0aa42143aa427
+  metadata.gz: d196f7ff4fd6270c0a4739f62ed17ee202eef663222018dc0b031b7dfb8ec015
+  data.tar.gz: cb645bae3cb677c7b7f7e35164d99b779dfb92d7d6a975204ac0fcae71b56f40
 SHA512:
-  metadata.gz: 302f3c9f98e999524573103dbaf5ecdfc048f5c780a293ddcf1bfb0409a3779e83b0176070a2c7563f74be56a3c118e23812ba8065c048d1eb9fb9765d00a272
-  data.tar.gz: ff0f655f57a37baee93a04147b9e2d0e50fd0f2607c2413bac46a420275a0e40c302d41a1a3d4d38e35a0e1d70b525c60ecbc0a742c634c22b202b36d3422fd5
+  metadata.gz: ee177b62cc41abd5fbd460d34f8f8dfe387385152cc683aed5034fe3fd67050043dd3cd2fe32f09f06735ff28a4e71ec6f1f4f945e6ea582dbba06e0883dbb1d
+  data.tar.gz: dcb85543ec034ede52cf91ed5e36ab5a987e8fb485d54c857fd1762f133252a827d760ac92dd36b9973897e30c3ab1d89f64bacd5761ffe6815b75c990c2c2f9

data/.github/workflows/eslint-validation.yml

@@ -0,0 +1,46 @@
+name: ESLint Validation
+
+on:
+  pull_request:
+    paths:
+      - "eslint.config.js"
+      - "package.json"
+      - "package/**/*.js"
+      - "test/**/*.js"
+      - ".github/workflows/eslint-validation.yml"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "yarn"
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Validate ESLint config
+        run: |
+          echo "Validating ESLint configuration..."
+          node -e "const config = require('./eslint.config.js'); console.log('✓ Config is valid with', config.length, 'rule sets')"
+
+      - name: Run ESLint
+        run: |
+          echo "Running ESLint on allowed files..."
+          yarn eslint . --max-warnings 5
+
+      - name: Check warning count
+        run: |
+          echo "Checking warning count..."
+          WARNING_COUNT=$(yarn eslint . 2>&1 | grep -E "^✖.*warning" | grep -oE "[0-9]+ warning" | cut -d' ' -f1)
+          echo "Current warning count: $WARNING_COUNT"
+          if [ "$WARNING_COUNT" -gt "5" ]; then
+            echo "❌ Too many warnings: $WARNING_COUNT (max allowed: 5)"
+            exit 1
+          fi
+          echo "✓ Warning count is acceptable"

data/CHANGELOG.md

@@ -11,9 +11,56 @@
 
 Changes since the last non-beta release.
 
+## [v9.3.0-beta.0] - October 13, 2025
+
+### Added
+
+- **New `precompile_hook` configuration option** to run custom commands during asset precompilation. [PR #678](https://github.com/shakacode/shakapacker/pull/678) by [justin808](https://github.com/justin808).
+  - Allows executing custom scripts or tasks during the precompile process
+  - Configure in `shakapacker.yml` with `precompile_hook: "command to run"`
+- **New `assets_bundler_config_path` configuration option** for custom bundler config locations. [PR #710](https://github.com/shakacode/shakapacker/pull/710) by [justin808](https://github.com/justin808).
+  - Allows specifying a custom path for webpack/rspack configuration files
+  - Useful for complex project structures or shared configurations
+- **YAML output format support for `bin/export-bundler-config`**. [PR #704](https://github.com/shakacode/shakapacker/pull/704) by [justin808](https://github.com/justin808).
+  - New `--format yaml` option exports bundler configuration as YAML
+  - Easier to read than JSON for debugging and documentation
+- **Custom help messages for `bin/shakapacker` commands**. [PR #702](https://github.com/shakacode/shakapacker/pull/702) by [justin808](https://github.com/justin808).
+  - Improved help output for better command discoverability
+  - Clear usage examples and option descriptions
+- **HMR client config export in doctor mode**. [PR #701](https://github.com/shakacode/shakapacker/pull/701) by [justin808](https://github.com/justin808).
+  - `bin/export-bundler-config --doctor` now includes HMR client configuration
+  - Helps debug Hot Module Replacement issues
+- **Build timing logs** for webpack and rspack. [PR #706](https://github.com/shakacode/shakapacker/pull/706) by [justin808](https://github.com/justin808).
+  - Shows duration of build operations
+  - Helps identify performance bottlenecks
+- Added Knip for detecting dead code to CI. [PR #675](https://github.com/shakacode/shakapacker/pull/675) by [justin808](https://github.com/justin808).
+
 ### Changed
 
-- Allow ESLint v9 and migrated to flat config format. [PR #677](https://github.com/shakacode/shakapacker/pull/677) by [justin808](https://github.com/justin808).
+- **Migrated to ESLint v9 with flat config format**. [PR #677](https://github.com/shakacode/shakapacker/pull/677) by [justin808](https://github.com/justin808).
+  - Updated all ESLint plugins to latest versions
+  - Uses new flat config format for better maintainability
+- **Replaced custom argument parser with yargs**. [PR #692](https://github.com/shakacode/shakapacker/pull/692) by [justin808](https://github.com/justin808).
+  - More robust command-line argument parsing
+  - Better error messages and help output
+- Replaced `require` with `import` in package/index.ts. [PR #674](https://github.com/shakacode/shakapacker/pull/674) by [justin808](https://github.com/justin808).
+- Updated @rspack dependencies to 1.5.8. [PR #700](https://github.com/shakacode/shakapacker/pull/700) by [justin808](https://github.com/justin808).
+
+### Improved
+
+- **Enhanced rspack migration documentation** with real-world lessons. [PR #713](https://github.com/shakacode/shakapacker/pull/713) by [justin808](https://github.com/justin808).
+  - Added practical migration guidance based on actual project experiences
+  - Common pitfalls and solutions documented
+- **Consolidated duplicate configuration documentation**. [PR #714](https://github.com/shakacode/shakapacker/pull/714) by [justin808](https://github.com/justin808).
+  - Removed redundant documentation
+  - Single source of truth for configuration options
+- **Improved error messages** to suggest `assets_bundler_config_path`. [PR #712](https://github.com/shakacode/shakapacker/pull/712) by [justin808](https://github.com/justin808).
+  - More helpful error messages when bundler config is not found
+  - Suggests using `assets_bundler_config_path` for custom locations
+- **Improved doctor command output** clarity and accuracy. [PR #682](https://github.com/shakacode/shakapacker/pull/682) by [justin808](https://github.com/justin808).
+  - Better formatting and organization of diagnostic information
+  - More actionable recommendations
+- Formatted all markdown files with prettier. [PR #673](https://github.com/shakacode/shakapacker/pull/673) by [justin808](https://github.com/justin808).
 
 ### Fixed
 
@@ -26,6 +73,12 @@ Changes since the last non-beta release.
 - Fixed TypeScript type definitions to export proper types instead of `any`. [PR #684](https://github.com/shakacode/shakapacker/pull/684) by [justin808](https://github.com/justin808).
   - Previously `package/index.d.ts` was exporting all types as `any`, breaking IDE autocomplete
   - Now properly exports typed interfaces for `WebpackConfig`, `RspackConfig`, etc.
+- Fixed integrity config handling and sass-loader version check. [PR #688](https://github.com/shakacode/shakapacker/pull/688) by [justin808](https://github.com/justin808).
+  - Properly handles subresource integrity configuration
+  - Correctly detects sass-loader version for conditional logic
+- Prevented index.d.ts confusion in build process. [PR #698](https://github.com/shakacode/shakapacker/pull/698) by [justin808](https://github.com/justin808).
+  - TypeScript declaration files no longer interfere with build output
+- Fixed yarn.lock formatting changes in Conductor setup. [PR #683](https://github.com/shakacode/shakapacker/pull/683) by [justin808](https://github.com/justin808).
 
 ## [v9.2.0] - October 9, 2025
 
@@ -679,7 +732,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/v9.0.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.3.0-beta.0...main
+[v9.3.0-beta.0]: https://github.com/shakacode/shakapacker/compare/v9.2.0...v9.3.0-beta.0
 [v9.2.0]: https://github.com/shakacode/shakapacker/compare/v9.1.0...v9.2.0
 [v9.1.0]: https://github.com/shakacode/shakapacker/compare/v9.0.0...v9.1.0
 [v9.0.0]: https://github.com/shakacode/shakapacker/compare/v8.4.0...v9.0.0

data/ESLINT_TECHNICAL_DEBT.md

@@ -0,0 +1,160 @@
+# ESLint Technical Debt Documentation
+
+This document tracks the ESLint errors currently suppressed in the codebase and outlines the plan to address them.
+
+## Current Approach
+
+**As of 2025-10-14**: All TypeScript files in `package/` directory are temporarily excluded from linting via the ignore pattern `package/**/*.ts` in `eslint.config.js`. This allows the project to adopt ESLint configuration without requiring immediate fixes to all existing issues.
+
+**Latest Update**: Fixed all `class-methods-use-this` violations by converting FileWriter methods to static methods (4 violations resolved).
+
+## Current Linting Status
+
+**Files currently linted** (`test/**/*.js`, `scripts/*.js`):
+
+- ✅ **0 errors** (CI passing)
+- ⚠️ **3 warnings** (acceptable, won't block CI)
+  - 1x unused eslint-disable directive in `scripts/remove-use-strict.js`
+  - 2x jest/no-disabled-tests in test files (expected for conditional test skipping)
+
+**TypeScript files** (currently ignored via `package/**/*.ts`):
+
+- **Estimated suppressed errors: ~172** (from sample analysis)
+  - TypeScript type-safety issues: ~114 (66%)
+  - Style/convention issues: ~58 (34%)
+
+**Target**: Reduce suppressed errors by 50% within Q1 2025
+**Last Updated**: 2025-10-14
+
+## Priority Matrix
+
+| Category                             | Impact | Effort | Priority | Count |
+| ------------------------------------ | ------ | ------ | -------- | ----- |
+| `@typescript-eslint/no-explicit-any` | High   | High   | P1       | 22    |
+| `@typescript-eslint/no-unsafe-*`     | High   | High   | P1       | 85    |
+| `config.ts` type safety              | High   | Medium | P1       | 7     |
+| `no-param-reassign`                  | Medium | Low    | P2       | 7     |
+| `class-methods-use-this`             | Low    | Low    | P3       | 0     |
+| `no-nested-ternary`                  | Low    | Low    | P3       | 3     |
+| `import/prefer-default-export`       | Low    | Medium | P3       | 9     |
+| `global-require`                     | Medium | High   | P2       | 3     |
+| Other style issues                   | Low    | Low    | P3       | 31    |
+
+## Categories of Suppressed Errors
+
+### 1. TypeScript Type Safety (Requires Major Refactoring)
+
+#### `@typescript-eslint/no-explicit-any` (22 instances)
+
+**Files affected:** `configExporter/`, `config.ts`, `utils/`
+**Why suppressed:** These require careful type definitions and potentially breaking API changes
+**Fix strategy:** Create proper type definitions for configuration objects and YAML parsing
+
+#### `@typescript-eslint/no-unsafe-*` (85 instances)
+
+- `no-unsafe-assignment`: 47 instances
+- `no-unsafe-member-access`: 20 instances
+- `no-unsafe-call`: 8 instances
+- `no-unsafe-return`: 8 instances
+- `no-unsafe-argument`: 7 instances
+  **Why suppressed:** These stem from `any` types and dynamic property access
+  **Fix strategy:** Requires comprehensive type refactoring alongside `no-explicit-any` fixes
+
+### 2. Module System (Potential Breaking Changes)
+
+#### `global-require` (3 instances)
+
+**Files affected:** `configExporter/cli.ts`
+**Why suppressed:** Dynamic require calls are needed for conditional module loading
+**Fix strategy:** Would require converting to ES modules with dynamic imports
+
+#### `import/prefer-default-export` (9 instances)
+
+**Files affected:** Multiple single-export modules
+**Why suppressed:** Adding default exports alongside named exports could break consumers
+**Fix strategy:** Can be fixed non-breaking by adding default exports that match named exports
+
+### 3. Code Style (Can Be Fixed)
+
+#### `class-methods-use-this` (0 instances)
+
+✅ **FIXED** - All FileWriter methods that didn't use instance state have been converted to static methods
+
+#### `no-nested-ternary` (3 instances)
+
+**Fix strategy:** Refactor to if-else statements
+
+#### `no-param-reassign` (7 instances)
+
+**Files affected:** `configExporter/cli.ts`
+**Why suppressed:** Common pattern for option objects
+**Fix strategy:** Create new objects instead of mutating parameters
+
+#### `no-underscore-dangle` (2 instances)
+
+**Fix strategy:** Rename variables or add exceptions for Node internals
+
+### 4. Control Flow
+
+#### `no-await-in-loop` (1 instance)
+
+**Fix strategy:** Use `Promise.all()` for parallel execution
+
+#### `no-continue` (1 instance)
+
+**Fix strategy:** Refactor loop logic
+
+## Recommended Approach
+
+### Phase 1: Non-Breaking Fixes
+
+✅ Completed:
+
+- Fixed `no-use-before-define` by reordering functions
+- Fixed redundant type constituents with `string & {}` pattern
+- Added proper type annotations for `requireOrError` calls
+- Configured appropriate global rule disables (`no-console`, `no-restricted-syntax`)
+- ✅ **Fixed `class-methods-use-this`** - Converted FileWriter methods to static methods
+
+🔧 Could still fix (low risk):
+
+- `no-nested-ternary` - Refactor conditionals
+- `no-useless-escape` - Remove unnecessary escapes
+- Unused variables - Remove or prefix with underscore
+
+### Phase 2: Follow-up PRs (Non-Breaking)
+
+- Systematic type safety improvements file by file
+- Add explicit type definitions for configuration objects
+- Replace `any` with `unknown` where possible
+
+### Phase 3: Future Major Version (Breaking Changes)
+
+- Convert `export =` to `export default`
+- Convert `require()` to ES6 imports
+- Full TypeScript strict mode compliance
+- Provide codemod for automatic migration
+
+## Configuration Strategy
+
+The current approach uses file-specific overrides to suppress errors in affected files while maintaining strict checking elsewhere. This allows:
+
+1. New code to follow strict standards
+2. Gradual refactoring of existing code
+3. Clear visibility of technical debt
+
+## Issue Tracking
+
+GitHub issues should be created for each category:
+
+1. [ ] Issue: Type safety refactoring for configExporter module
+2. [ ] Issue: Type safety for dynamic config loading
+3. [ ] Issue: Convert class methods to static where appropriate
+4. [ ] Issue: Module system modernization (ES6 modules)
+5. [ ] Issue: Create codemod for breaking changes migration
+
+## Notes
+
+- All suppressed errors are documented in `eslint.config.js` with TODO comments
+- The suppressions are scoped to specific files to prevent spreading technical debt
+- New code should not add to these suppressions

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.3.0.beta.0)
+    shakapacker (9.3.0.beta.2)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)

data/docs/common-upgrades.md

@@ -6,6 +6,7 @@ This document provides step-by-step instructions for the most common upgrade sce
 
 ## Table of Contents
 
+- [Upgrading Shakapacker](#upgrading-shakapacker)
 - [Migrating Package Managers](#migrating-package-managers)
   - [Yarn to npm](#yarn-to-npm)
   - [npm to Yarn](#npm-to-yarn)
@@ -15,6 +16,85 @@ This document provides step-by-step instructions for the most common upgrade sce
 
 ---
 
+## Upgrading Shakapacker
+
+> **⚠️ Important:** Shakapacker is both a Ruby gem AND an npm package. **You must update BOTH** when upgrading.
+
+Shakapacker consists of two components that must be updated together:
+
+1. **Ruby gem** - provides Rails integration and view helpers
+2. **npm package** - provides webpack/rspack configuration and build tools
+
+### Upgrade Steps
+
+#### 1. Update `Gemfile`
+
+```ruby
+gem "shakapacker", "9.3.0"  # or the version you want to upgrade to
+```
+
+**Pre-release versions:** Ruby gems use dot notation (e.g., `"9.3.0.beta.1"`)
+
+#### 2. Update `package.json`
+
+```json
+{
+  "dependencies": {
+    "shakapacker": "9.3.0"
+  }
+}
+```
+
+**Pre-release versions:** npm uses hyphen notation (e.g., `"9.3.0-beta.1"`)
+
+#### 3. Run bundler and package manager
+
+```bash
+bundle update shakapacker
+yarn install  # or npm install, pnpm install, bun install
+```
+
+#### 4. Test your build
+
+```bash
+bin/shakapacker
+bin/shakapacker-dev-server
+```
+
+### Why Both Must Be Updated
+
+- **Mismatched versions can cause build failures** - The Ruby gem expects specific configuration formats from the npm package
+- **Feature compatibility** - New features in the gem require corresponding npm package updates
+- **Bug fixes** - Fixes often span both Ruby and JavaScript code
+
+### Version Format Differences
+
+Note that pre-release versions use different formats:
+
+| Component    | Stable Version | Pre-release Version |
+| ------------ | -------------- | ------------------- |
+| Gemfile      | `"9.3.0"`      | `"9.3.0.beta.1"`    |
+| package.json | `"9.3.0"`      | `"9.3.0-beta.1"`    |
+
+### Finding the Latest Version
+
+- **Ruby gem:** Check [RubyGems.org](https://rubygems.org/gems/shakapacker)
+- **npm package:** Check [npmjs.com](https://www.npmjs.com/package/shakapacker)
+- **Releases:** See [GitHub Releases](https://github.com/shakacode/shakapacker/releases)
+
+### Major Version Upgrades
+
+For major version upgrades, always consult the version-specific upgrade guides for breaking changes and new features:
+
+- [V9 Upgrade Guide](./v9_upgrade.md) - Upgrading from v8 to v9 (includes CSS Modules changes, SWC defaults, and more)
+- [V8 Upgrade Guide](./v8_upgrade.md) - Upgrading from v7 to v8
+- [V7 Upgrade Guide](./v7_upgrade.md) - Upgrading from v6 to v7
+- [V6 Upgrade Guide](./v6_upgrade.md) - Upgrading from v5 to v6
+
+> **💡 Note:** Major version upgrades may include breaking changes. The steps above cover the basic gem/package updates that apply to all versions, but you should always review the version-specific guide for additional migration steps.
+
+---
+
 ## Migrating Package Managers
 
 ### Yarn to npm

data/docs/troubleshooting.md

@@ -71,7 +71,147 @@
 
    See `bin/export-bundler-config --help` for all available options.
 
-6. Generate webpack stats for build analysis (useful for bundle size optimization):
+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:
+   - **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
+
+   **Quick validation:**
+
+   ```bash
+   # Validate all builds defined in .bundler-config.yml
+   bin/export-bundler-config --validate
+
+   # Validate with full output logs (shows all webpack/rspack compilation output)
+   bin/export-bundler-config --validate --verbose
+
+   # Validate a specific build
+   bin/export-bundler-config --validate-build=dev-hmr
+   ```
+
+   **Verbose Mode:**
+
+   When using `--verbose`, you'll see:
+   - A clear header indicating verbose mode is enabled
+   - Full real-time compilation output from webpack/rspack
+   - All warnings and progress messages
+   - Detailed error traces
+   - Separators between builds for clarity
+
+   This is useful for debugging compilation issues or understanding build performance.
+
+   **Setting up build configurations:**
+
+   ```bash
+   # Create a .bundler-config.yml file with example builds
+   bin/export-bundler-config --init
+
+   # List all available builds
+   bin/export-bundler-config --list-builds
+
+   # Validate all builds
+   bin/export-bundler-config --validate
+   ```
+
+   **Advanced options:**
+
+   The validator uses a default timeout of 2 minutes per build. For large projects or slow CI environments, you can customize this behavior by modifying the `ValidatorOptions` in your code, or by adjusting your build configuration to be more efficient.
+
+   If validation times out, try:
+   - Using `--verbose` to see where the build is hanging
+   - Optimizing your webpack/rspack configuration for faster builds
+   - Running validation on a single build with `--validate-build=build-name`
+
+   **How it works:**
+
+   The validator will:
+   - For HMR builds (with `WEBPACK_SERVE=true`): Start webpack-dev-server, wait for successful compilation, then shut down
+   - For static builds: Run webpack/rspack and check for compilation errors
+   - Report all errors and warnings with clear output
+   - Exit with code 1 if any build fails (perfect for CI)
+
+   **Example output:**
+
+   ```text
+   🔍 Validating Builds
+   ================================================================================
+
+   📦 Validating build: dev-hmr
+      ✅ Build passed
+
+   📦 Validating build: dev
+      ✅ Build passed
+
+   📦 Validating build: prod
+      ❌ Build failed with 2 error(s)
+
+   ================================================================================
+   🔍 Build Validation Results
+   ================================================================================
+
+   ✅ Build: dev-hmr (2.34s)
+      📦 Outputs: client
+      ⚙️  Config: config/webpack/webpack.config.js
+
+   ✅ Build: dev (3.12s)
+      📦 Outputs: client, server
+      ⚙️  Config: config/webpack/webpack.config.js
+      📁 Output: /app/public/packs
+
+   ❌ Build: prod (4.56s)
+      📦 Outputs: client, server
+      ⚙️  Config: config/webpack/webpack.config.js
+      📁 Output: /app/public/packs
+      ❌ 2 error(s)
+         Module not found: Error: Can't resolve './missing'
+         SyntaxError: Unexpected token
+
+   ================================================================================
+   Summary: 2/3 builds passed, 1 failed (Total: 10.02s)
+   ================================================================================
+
+   💡 Debugging Tips:
+      To get more details, run individual builds with --verbose:
+
+      bin/export-bundler-config --validate-build prod --verbose
+
+      Or validate all builds with full output: bin/export-bundler-config --validate --verbose
+   ================================================================================
+   ```
+
+   **Debugging Failed Builds:**
+
+   When builds fail, the validator automatically provides debugging commands. You can:
+   1. **Run a specific build with verbose output** to see full webpack/rspack logs:
+
+      ```bash
+      bin/export-bundler-config --validate-build prod --verbose
+      ```
+
+   2. **Validate all builds with verbose output** to see everything:
+
+      ```bash
+      bin/export-bundler-config --validate --verbose
+      ```
+
+   3. **Test individual builds manually** using the same configuration:
+
+      ```bash
+      # For static builds
+      NODE_ENV=production RAILS_ENV=production bundle exec webpack --config config/webpack/webpack.config.js
+
+      # For HMR/dev-server builds
+      NODE_ENV=development WEBPACK_SERVE=true bundle exec webpack serve --config config/webpack/webpack.config.js
+      ```
+
+   The verbose mode shows:
+   - Full real-time compilation output
+   - All webpack/rspack warnings and progress messages
+   - Detailed stack traces for errors
+   - Timing information for each build phase
+   - Clear separators between different builds
+
+7. Generate webpack stats for build analysis (useful for bundle size optimization):
 
    ```bash
    NODE_ENV=development bin/shakapacker --profile --json > /tmp/webpack-stats.json