shakapacker 8.4.0 → 9.7.0

data/CLAUDE.md

@@ -0,0 +1,63 @@
+# Shakapacker Project Guidelines
+
+## Critical Requirements
+
+- **ALWAYS end all files with a trailing newline character.** This is required by the project's linting rules.
+- **ALWAYS use `bundle exec` prefix when running Ruby commands** (rubocop, rspec, rake, etc.)
+- **ALWAYS run `bundle exec rubocop` before committing Ruby changes**
+- **ALWAYS run `yarn lint` before committing JavaScript changes**
+
+## Testing
+
+- Run corresponding RSpec tests when changing source files
+- For example, when changing `lib/shakapacker/foo.rb`, run `spec/shakapacker/foo_spec.rb`
+- Run the full test suite with `bundle exec rspec` before pushing
+- **Use explicit RSpec spy assertions** - prefer `have_received`/`not_to have_received` over indirect counter patterns
+  - Good: `expect(Open3).to have_received(:capture3).with(anything, hook_command, anything)`
+  - Good: `expect(Open3).not_to have_received(:capture3).with(anything, hook_command, anything)`
+  - Avoid: `call_count += 1` followed by `expect(call_count).to eq(1)`
+
+## Code Style
+
+- Follow existing code conventions in the file you're editing
+- Use the project's existing patterns and utilities
+- No unnecessary comments unless requested
+- Keep changes focused and minimal - avoid extraneous diffs
+
+## Git Workflow
+
+- Create feature branches for all changes
+- Never push directly to main branch
+- Create small, focused PRs that are easy to review
+- Always create a PR immediately after pushing changes
+
+## Changelog
+
+- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
+- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
+- **Format**: `[PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username)` (Shakapacker uses `#` in PR links)
+- **Use `/update-changelog` command** for guided changelog updates with automatic formatting
+- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers
+- **Examples**: Run `grep -A 3 "^### " CHANGELOG.md | head -30` to see real formatting examples
+
+## Open Source Maintainability
+
+- **Prefer removing complexity over adding configuration.** If a default causes problems, consider removing the default rather than adding an option to disable it.
+- **Every config option is maintenance surface.** Prefer convention over configuration. Don't add options for <10% of users — let them customize via existing extension points (e.g., custom webpack config).
+- **"No is temporary, yes is forever."** Adding a feature creates a permanent maintenance obligation. Reject features that solve one user's niche problem but add complexity for everyone.
+- **Security-safe defaults over convenient defaults.** Don't ship permissive defaults (e.g., `Access-Control-Allow-Origin: *`) just for convenience — make users opt in to less-secure configurations.
+- **Don't refactor adjacent code in feature PRs.** Keep PRs focused. If you spot something to clean up, do it in a separate PR.
+
+## Shakapacker-Specific
+
+- This gem supports both webpack and rspack configurations
+- Test changes with both bundlers when modifying core functionality
+- Be aware of the dual package.json/Gemfile dependency management
+
+## Conductor Environment
+
+- **Version manager support**: The setup script detects mise, asdf, or direct PATH tools (rbenv/nvm/nodenv)
+- **bin/conductor-exec**: Use this wrapper for commands when tool versions aren't detected correctly in Conductor's non-interactive shell
+  - Example: `bin/conductor-exec bundle exec rubocop`
+  - The wrapper uses `mise exec` if mise is available, otherwise falls back to direct execution
+- **conductor.json scripts** already use this wrapper, so you typically don't need to use it manually

data/CONTRIBUTING.md

@@ -3,6 +3,7 @@
 Thank you for your interest in contributing to Shakapacker! We welcome all contributions that align with our project goals and values. To ensure a smooth and productive collaboration, please follow these guidelines.
 
 ## Contents
+
 - [Reporting Issues](#reporting-issues)
 - [Submitting Pull Requests](#submitting-pull-requests)
 - [Setting Up a Development Environment](#setting-up-a-development-environment)
@@ -10,46 +11,218 @@ Thank you for your interest in contributing to Shakapacker! We welcome all contr
 - [Testing the generator](#testing-the-generator)
 
 ## Reporting Issues
+
 If you encounter any issues with the project, please first check the existing issues (including closed ones). If the issues is not reported before, please opening an issue on our GitHub repository. Please provide a clear and detailed description of the issue, including steps to reproduce it. Creating a demo repository to demonstrate the issue would be ideal (and in some cases necessary).
 
 If looking to contribute to the project by fixing existing issues, we recommend looking at issues, particularly with the "[help wanted](https://github.com/shakacode/shakapacker/issues?q=is%3Aissue+label%3A%22help+wanted%22)" label.
 
 ## Submitting Pull Requests
+
 We welcome pull requests that fix bugs, add new features, or improve existing ones. Before submitting a pull request, please make sure to:
 
-  - Open an issue about what you want to propose before start working on.
-  - Fork the repository and create a new branch for your changes.
-  - Write clear and concise commit messages.
-  - Follow our code style guidelines.
-  - Write tests for your changes and [make sure all tests pass](#making-sure-your-changes-pass-all-tests).
-  - Update the documentation as needed.
-  - Update CHANGELOG.md if the changes affect public behavior of the project.
+- Open an issue about what you want to propose before start working on.
+- Fork the repository and create a new branch for your changes.
+- Write clear and concise commit messages.
+- Follow our code style guidelines.
+- Write tests for your changes and [make sure all tests pass](#making-sure-your-changes-pass-all-tests).
+- Update the documentation as needed.
+- Update CHANGELOG.md if the changes affect public behavior of the project.
+- Update RBS type signatures in `sig/` directory if you modify public APIs.
+
+---
+
+## Git Hooks (Optional)
+
+This project includes configuration for git hooks via `husky` and `lint-staged`, but they are **opt-in for contributors**.
+
+**Why are hooks optional?** As a library project, we don't enforce git hooks because:
+
+- Different contributors may have different workflows
+- Forcing hooks can interfere with contributor tooling
+- CI/CD handles the final validation
+
+To enable pre-commit hooks locally:
+
+```bash
+npx husky install
+npx husky add .husky/pre-commit "npx lint-staged"
+```
 
 ---
+
+## RBS Type Signatures
+
+Shakapacker includes RBS type signatures for all public APIs in the `sig/` directory. These signatures provide static type checking and improved IDE support.
+
+### When to Update RBS Files
+
+Update RBS signatures when you:
+
+- Add new public methods or classes
+- Change method signatures (parameters, return types)
+- Modify public APIs
+- Add or remove public attributes
+
+### RBS File Structure
+
+```
+sig/
+├── shakapacker.rbs                    # Main Shakapacker module
+└── shakapacker/
+    ├── configuration.rbs              # Configuration class
+    ├── helper.rbs                     # View helper module
+    ├── manifest.rbs                   # Manifest class
+    ├── compiler.rbs                   # Compiler class
+    └── ...                            # Other components
+```
+
+### Validating RBS Signatures
+
+To validate your RBS signatures:
+
+```bash
+# Install RBS if not already installed
+gem install rbs
+
+# Validate all signatures
+rbs validate
+
+# Check a specific file
+rbs validate sig/shakapacker/configuration.rbs
+```
+
+### RBS Best Practices
+
+1. **Use specific types** instead of `untyped` when possible
+2. **Document optional parameters** with `?` prefix
+3. **Use union types** for methods that can return multiple types (e.g., `String | nil`)
+4. **Keep signatures in sync** with implementation changes
+5. **Test with type checkers** like [Steep](https://github.com/soutaro/steep) when possible
+6. **Use `void` vs `nil` appropriately**:
+   - Use `void` when the return value is expected to be discarded (e.g., `initialize`)
+   - Use `nil` when a method explicitly returns nil as a meaningful value
+7. **Module singleton methods**: For modules using `extend self`, use `module ModuleName : _Singleton` to indicate all methods are module-level singleton methods
+
+### Example RBS Signature
+
+```rbs
+# Good: Specific types with documentation
+class Shakapacker::Configuration
+  def initialize: (
+    root_path: Pathname,
+    config_path: Pathname,
+    env: ActiveSupport::StringInquirer,
+    ?bundler_override: String?
+  ) -> void
+
+  def source_path: () -> Pathname
+  def webpack?: () -> bool
+  def assets_bundler: () -> String
+end
+
+# Module with singleton methods (using extend self)
+module Shakapacker : _Singleton
+  def self.config: () -> Configuration
+  def self.compile: () -> bool
+end
+
+# Avoid: Overly generic types
+class Shakapacker::Configuration
+  def initialize: (**untyped) -> void
+  def source_path: () -> untyped
+end
+```
+
+---
+
+## Linting and Code Quality
+
+### Running Linters
+
+```bash
+# Full linting with type checking (slower but thorough)
+yarn lint
+
+# Fast linting without type checking (for quick feedback)
+yarn lint:fast
+
+# With caching for better performance
+yarn lint --cache
+```
+
+**Performance Note:** TypeScript ESLint uses type-aware linting for better type safety, which can be slower on large codebases. Use `yarn lint:fast` during development for quick feedback.
+
+---
+
 ## Setting Up a Development Environment
 
-1. Install [Yarn](https://classic.yarnpkg.com/)
+1. Install [Yarn](https://classic.yarnpkg.com/) & [yalc](https://github.com/wclr/yalc)
 2. To test your changes on a Rails test project do the following steps:
    - For Ruby gem, update `Gemfile` and point the `shakapacker` to the locally developing Shakapacker project:
-      ```ruby
-      gem 'shakapacker', path: "relative_or_absolute_path_to_local_shakapacker"
-      ```
+     ```ruby
+     gem 'shakapacker', path: "relative_or_absolute_path_to_local_shakapacker"
+     ```
    - For npm package, use `yalc` with following steps:
-      ```bash
-      # In Shakapacker root directory
-      yalc publish
-      # In Rails app for testing
-      yalc link shakapacker
-
-      # After every change in shakapacker, run the following in Shakapacker directory
-      yalc push # or yalc publish --push
-      ```
+
+     ```bash
+     # In Shakapacker root directory
+     yalc publish
+     # In Rails app for testing
+     yalc link shakapacker
+
+     # After every change in shakapacker, run the following in Shakapacker directory
+     yalc push # or yalc publish --push
+     ```
+
 3. Run the following commands to set up the development environment.
    ```
    bundle install
    yarn install
+   yarn prepare:husky  # Set up pre-commit hooks for linting
    ```
 
+## Understanding Optional Peer Dependencies
+
+Shakapacker uses optional peer dependencies (via `peerDependenciesMeta`) for maximum flexibility:
+
+- **All peer dependencies are optional** - Users only install what they need
+- **No installation warnings** - Package managers won't warn about missing optional dependencies
+- **Version constraints still apply** - When a package is installed, version compatibility is enforced
+
+### TypeScript Declaration Files and Optional Dependencies
+
+When importing types from optional peer dependencies, we use `@ts-ignore` directives:
+
+```typescript
+// @ts-ignore: webpack is an optional peer dependency (using type-only import)
+import type { Configuration } from "webpack"
+```
+
+This ensures that typecheck downstream won't fail if lib checks are on regardless of if `webpack` is available.
+
+### When modifying dependencies:
+
+1. Add new peer dependencies to both `peerDependencies` and `peerDependenciesMeta` (marking as optional)
+2. Keep version ranges synchronized between `devDependencies` and `peerDependencies`
+3. Test with multiple package managers: `npm`, `yarn`, and `pnpm`
+4. If adding type-only imports from optional dependencies, use the `@ts-ignore` pattern shown above
+
+### Testing peer dependency changes:
+
+```bash
+# Test with npm (no warnings expected)
+cd /tmp && mkdir test-npm && cd test-npm
+npm init -y && npm install /path/to/shakapacker
+
+# Test with yarn (no warnings expected)
+cd /tmp && mkdir test-yarn && cd test-yarn
+yarn init -y && yarn add /path/to/shakapacker
+
+# Test with pnpm (no warnings expected)
+cd /tmp && mkdir test-pnpm && cd test-pnpm
+pnpm init && pnpm add /path/to/shakapacker
+```
+
 ## Making sure your changes pass all tests
 
 There are several specs, covering different aspects of Shakapacker gem. You may run them locally or rely on GitHub CI actions configured to test the gem functionality if different Ruby, Rails, and Node environment.
@@ -101,6 +274,7 @@ bundle exec rake run_spec:gem
 ```
 
 #### 4.4 Run only Shakapacker gem specs for backward compatibility
+
 These specs are to check Shakapacker v7 backward compatibility with v6.x
 
 ```
@@ -108,6 +282,7 @@ bundle exec rake run_spec:gem_bc
 ```
 
 #### 4.5 Run dummy app test
+
 For this, you need `yalc` to be installed on your local machine
 
 ```
@@ -115,6 +290,7 @@ bundle exec rake run_spec:dummy
 ```
 
 #### 4.6 Testing the installer
+
 To ensure that your installer works as expected, either you can run `bundle exec rake run_spec:install`, or take the following manual testing steps:
 
 1. Update the `Gemfile` so that gem `shakapacker` has a line like this, pointing to your developing Shakapacker:
@@ -124,4 +300,75 @@ To ensure that your installer works as expected, either you can run `bundle exec
 2. Run `bundle install` to install the updated gem.
 3. Run `bundle exec rails shakapacker:install` to confirm that you got the right changes.
 
- **Note:** Ensure that you use bundle exec otherwise the installed shakapacker gem will run and not the one you are working on.
+**Note:** Ensure that you use bundle exec otherwise the installed shakapacker gem will run and not the one you are working on.
+
+## CI Workflows
+
+Shakapacker uses GitHub Actions for continuous integration. The CI workflows use **Yarn** as the package manager for consistency and reliability.
+
+### Package Manager Choice
+
+The project uses Yarn in CI workflows for the following reasons:
+
+- Deterministic dependency resolution with `yarn.lock`
+- Faster installation with offline mirror support
+- Better workspace support for monorepo-style testing
+- Consistent behavior across different Node.js versions
+
+### Key CI Workflow Files
+
+- `.github/workflows/test-bundlers.yml` - Tests webpack, rspack, and bundler switching
+- `.github/workflows/ruby.yml` - Ruby test suite across Ruby/Rails versions
+- `.github/workflows/node.yml` - Node.js test suite across Node versions
+- `.github/workflows/generator.yml` - Generator installation tests
+- `.github/workflows/dummy.yml` - Dummy app integration tests
+- `.github/workflows/eslint-validation.yml` - ESLint configuration validation
+
+All workflows use:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    cache: "yarn"
+    cache-dependency-path: spec/dummy/yarn.lock
+```
+
+And install dependencies with:
+
+```bash
+yarn install
+```
+
+### CI Optimization: Path Filtering
+
+To reduce CI costs and execution time, workflows use **path filtering** to run only when relevant files change:
+
+- **Ruby workflow** - Only runs when Ruby files, gemspecs, Gemfile, or RuboCop config changes
+- **Node workflow** - Only runs when JS/TS files, package.json, or Node config changes
+- **Generator specs** - Only runs when generator-related files change
+- **Dummy specs** - Only runs when dummy app or lib files change
+- **Test bundlers** - Only runs when code affecting bundler integration changes
+
+This means documentation-only PRs (e.g., only changing `README.md`) will skip all test workflows entirely.
+
+**Important:** The full test suite always runs on pushes to the `main` branch to ensure the main branch is always thoroughly tested.
+
+### Manual Workflow Execution
+
+All workflows can be triggered manually via the GitHub Actions UI using the "Run workflow" button. This is useful for:
+
+- Re-running tests after a temporary CI failure
+- Testing workflows on specific branches without creating a PR
+- Running full test suites on PRs that would normally skip certain workflows
+
+### Conditional Linting
+
+The Node workflow includes conditional execution of actionlint (GitHub Actions linter):
+
+- Only downloads and runs when `.github/workflows/*` files change
+- Saves time by skipping on most PRs
+- Includes caching for faster execution when needed
+
+### Testing with Other Package Managers
+
+While CI uses Yarn, the gem supports all major package managers (npm, yarn, pnpm, bun). Generator specs test against all package managers to ensure compatibility.

data/ESLINT_TECHNICAL_DEBT.md

@@ -0,0 +1,165 @@
+# 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**: Auto-fixed 28 style violations in `package/configExporter/cli.ts` including unnecessary type assertions, string concatenation to template literals, and object destructuring (reduced from 77 to 49 errors).
+
+## 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: ~163** (from sample analysis)
+  - TypeScript type-safety issues: ~114 (70%)
+  - Style/convention issues: ~49 (30%)
+
+**Target**: Reduce suppressed errors by 50% within Q1 2025
+**Last Updated**: 2025-10-18
+
+## 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       | 0     |
+| `class-methods-use-this`             | Low    | Low    | P3       | 0     |
+| `no-nested-ternary`                  | Low    | Low    | P3       | 0     |
+| `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` (0 instances)
+
+✅ **FIXED** - All nested ternary expressions have been refactored to if-else statements for better readability
+
+#### `no-param-reassign` (0 instances)
+
+✅ **FIXED** - Refactored `applyDefaults` function to return 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
+- ✅ **Fixed `no-nested-ternary`** - Refactored to if-else statements for better readability
+- ✅ **Fixed `no-param-reassign`** - Refactored `applyDefaults` to return new objects instead of mutating parameters
+- ✅ **Auto-fixed style violations in cli.ts** (2025-10-18):
+  - Removed unnecessary type assertions (`@typescript-eslint/no-unnecessary-type-assertion`)
+  - Used object destructuring (`prefer-destructuring`)
+  - Converted string concatenation to template literals (`prefer-template`)
+  - Removed unused eslint-disable directives
+  - Fixed `no-else-return` violations
+
+🔧 Could still fix (low risk):
+
+- `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