fix: cause error by rollup module on release

[cawpea]

GitHub Actions でのビルドエラー解決

問題の概要

GitHub Actions の CI 環境で npm run build を実行すると、以下のエラーが発生していました:

Error: Cannot find module @rollup/rollup-linux-x64-gnu. npm has a bug related to optional dependencies (npm/cli#4828).

根本原因

1. tsup が rollup に依存している

   • tsup は内部的に rollup を使用してビルドを実行
   • rollup はプラットフォーム固有のネイティブバイナリ (optional dependencies) を必要とする

2. npm の既知のバグ

   • npm ci が optional dependencies を正しくインストールできないことがある
   • 特に CI 環境のキャッシュと組み合わさると問題が発生しやすい
   • 参考: [BUG] Platform-specific optional dependencies not being included in package-lock.json when reinstalling with node_modules present npm/cli#4828

3. Linux 固有のネイティブバイナリが欠損

   • @rollup/rollup-linux-x64-gnu というプラットフォーム固有のパッケージがインストールされていなかった

試行した解決策

❌ 失敗した対策

1. npm cache のクリア

   - name: Clear npm cache
     run: npm cache clean --force
   → 効果なし
   

2. npm rebuild の追加

• name: Rebuild native dependencies
  run: npm rebuild

2. → ネイティブバイナリがインストールされていないため失敗
3. npm ci 後に npm install を実行

• name: Install dependencies
  run: |
  npm ci
  npm install

3. → optional dependencies が依然としてインストールされず
4. rollup を devDependencies に明示的に追加
   "devDependencies": {
   "rollup": "^4.54.0",
   ...
   }
5. → npm ci が依然として optional dependencies をスキップ

✅ 成功した解決策

rollup を削除して再インストール

• name: Install dependencies
  run: npm ci

• name: Install rollup with native binaries
  run: |
  rm -rf node_modules/rollup
  npm install rollup --no-save

解決策の詳細

実装方法

.github/workflows/release.yml に以下のステップを追加:

• name: Install rollup with native binaries
  run: |
  rm -rf node_modules/rollup
  npm install rollup --no-save

動作原理

1. npm ci で依存関係をクリーンインストール
2. rollup ディレクトリを完全に削除
3. npm install rollup で rollup を再インストール
   - この時、npm が optional dependencies を正しく解決してインストールする
   - --no-save フラグで package.json への書き込みを防ぐ

なぜこれで解決するのか

• npm ci で作成された node_modules の状態をリセット
• 新規インストールとして扱われることで、npm が optional dependencies を正しく評価
• CI 環境のキャッシュや不完全なインストール状態の影響を受けない

最終的なワークフロー構成

steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
persist-credentials: false

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: 22.x

- name: Install dependencies
  run: npm ci

- name: Install rollup with native binaries
  run: |
    rm -rf node_modules/rollup
    npm install rollup --no-save

- name: Build package
  run: npm run build

追加の対策

package.json の更新

rollup を明示的に devDependencies に追加しました (将来的な安定性のため):

"devDependencies": {
"rollup": "^4.54.0",
...
}

学んだこと

1. npm ci の制限
   - npm ci は reproducible なインストールを優先するため、optional dependencies の扱いが保守的
   - CI 環境では特に問題が発生しやすい
2. ネイティブモジュールの扱い
   - プラットフォーム固有のネイティブバイナリは optional dependencies として配布される
   - CI 環境のプラットフォームと開発環境が異なる場合、特に注意が必要
3. transitive dependencies の課題
   - 間接的な依存関係 (tsup → rollup) の問題は見つけにくい
   - 重要な依存関係は明示的に devDependencies に追加することを検討

参考リンク

• [BUG] Platform-specific optional dependencies not being included in package-lock.json when reinstalling with node_modules present npm/cli#4828 - Optional dependencies bug
• https://rollupjs.org/
• https://tsup.egoist.dev/

[github-actions]

Code Review

Overview

This PR addresses a rollup module error during the release workflow by adding an explicit rollup installation step and updating the Node.js engine requirement.

---

🔴 Critical Issues

1. Breaking Change Without Proper Versioning (High Priority)

Location: package.json:52

The Node.js engine requirement changed from >=16.0.0 to >=22.0.0 - this is a major breaking change that affects all users running Node.js 16-21.

Issues:

• This breaks compatibility for users on Node.js 16, 18, and 20 LTS versions
• The commit type is fix: but this should be feat\!: or include BREAKING CHANGE: in the commit body
• No justification provided for requiring Node.js 22
• Current package version is 0.1.0 - this change should trigger a major version bump to 1.0.0

Recommendation:

• If Node.js 22 is truly required, document WHY in the PR description
• Change commit type to indicate breaking change per Conventional Commits
• Consider if the issue can be solved without dropping support for Node.js 16-20
• Update documentation to reflect new Node.js requirement

2. Workaround Without Root Cause Analysis (High Priority)

Location: .github/workflows/release.yml:34-37

The workflow now removes and reinstalls rollup, which suggests a deeper issue:

- name: Install rollup with native binaries
  run: |
    rm -rf node_modules/rollup
    npm install rollup --no-save

Issues:

• This is a workaround, not a fix
• No explanation of what "cause error by rollup module" means
• --no-save flag seems incorrect since rollup is already in package.json
• May cause version mismatches between package-lock.json and installed version
• Could indicate npm cache corruption, platform-specific binary issues, or dependency conflicts

Questions:

• What was the actual error message?
• Why does reinstalling rollup fix it?
• Is this a CI environment issue or a dependency resolution problem?
• Why is cache: 'npm' removed from setup-node?

Recommendation:

• Document the actual error in the PR description
• Investigate if this is an npm ci vs npm install issue
• Consider if npm ci --force or clearing the cache would be more appropriate
• If platform-specific binaries are the issue, document this clearly

---

⚠️ Moderate Issues

3. Missing PR Description

The PR body is empty. For a fix that changes engine requirements and modifies CI workflows, context is essential.

Should include:

• The actual error that occurred
• Why the workaround works
• Why Node.js 22 is now required
• Testing performed to validate the fix

4. Removing npm Cache May Impact CI Performance

Location: .github/workflows/release.yml:29

The cache: 'npm' option was removed from setup-node:

- uses: actions/setup-node@v4
  with:
    node-version: 22.x
-   cache: 'npm'  # Removed

Impact:

• Every release will re-download all dependencies
• Slower CI runs
• Increased bandwidth usage

Question: Is this removal intentional or related to the rollup issue?

---

📋 Additional Observations

5. Rollup Added as Direct DevDependency

Rollup is now explicitly added to devDependencies, but it's likely already a transitive dependency of tsup.

Questions:

• Is the explicit dependency necessary?
• Could version mismatches with tsup's expected rollup version cause issues?
• Have you verified this doesn't create a duplicate rollup installation?

6. Testing Coverage

No evidence of testing:

• Was the release workflow tested in a fork or test environment?
• Does the build succeed locally with Node.js 22?
• Are there any automated tests that validate the build process?

---

🎯 Recommendations

1. Before merging:

   • Provide the actual error message and context in the PR description
   • Justify the Node.js 22 requirement or revert it
   • Fix the commit message to indicate breaking change if keeping Node.js 22 requirement
   • Test the workflow in a safe environment
   • Consider restoring npm cache if not causing issues

2. Better solution (if possible):

   • Investigate root cause instead of workaround
   • Keep compatibility with Node.js 16+ if possible
   • Use npm ci flags or cache clearing instead of manual rm/install

3. Documentation updates:

   • Update README with new Node.js requirement
   • Document any rollup-related build issues in troubleshooting guide
   • Add changelog entry for breaking change

---

✅ Positive Aspects

• Follows conventional commit format (type)
• Targets a real CI/CD issue
• Minimal changes to accomplish the goal

Verdict

⚠️ Needs Work - This PR addresses a symptom but may not fix the root cause. The breaking change to Node.js requirements needs proper justification and semantic versioning treatment.

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 0.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀