dependency-upgrade

補足資料の利用可否

このカタログのコピーには、以下のインラインガイダンスが含まれていますが、次の補足パスは含まれていません。これらは外部の前提資料であり、同梱ファイルではありません。

• <support-root>/references/semver.md
• <support-root>/references/compatibility-matrix.md
• <support-root>/references/staged-upgrades.md
• <support-root>/references/testing-strategy.md
• <support-root>/assets/upgrade-checklist.md
• <support-root>/assets/compatibility-matrix.csv
• <support-root>/scripts/audit-dependencies.sh

これらのパスに依存する手順を実行する前に、元の補足資料または既存のインストール環境を入手してください。このカタログには、検証済みのダウンロード元は記載されていません。各パスをそのインストール環境を基準に解決し、内容を確認して、該当するライセンスと実行要件を検証してください。必要なファイルが存在することを確認するまでは、コマンドを実行したり、参照先の手順に従ったと主張したりしないでください。不足しているスクリプトを捏造したり、同じ名前の無関係なファイルを同等のものとして扱ったりしないでください。ここに完全に記載されている独立した手順は、ユーザーが許可した範囲内で実行できます。依存する手順は利用できないものとして報告してください。

依存関係のアップグレード

主要な依存関係バージョンのアップグレード、互換性分析、段階的なアップグレード戦略、包括的なテスト手法を習得します。

このスキルを使用しない場合

• タスクが依存関係のアップグレードに関係しない場合
• この範囲外の別の分野やツールが必要な場合

手順

• 目標、制約、必要な入力を明確にします。
• 関連するベストプラクティスを適用し、結果を検証します。
• 実行可能な手順と検証方法を提示します。

このスキルを使用する場合

• 主要なフレームワークのバージョンをアップグレードするとき
• セキュリティ上の脆弱性がある依存関係を更新するとき
• レガシー依存関係を最新化するとき
• 依存関係の競合を解決するとき
• 段階的なアップグレード経路を計画するとき
• 互換性マトリックスをテストするとき
• 依存関係の更新を自動化するとき

セマンティックバージョニングの確認

MAJOR.MINOR.PATCH (e.g., 2.3.1)

MAJOR: Breaking changes
MINOR: New features, backward compatible
PATCH: Bug fixes, backward compatible

^2.3.1 = >=2.3.1 <3.0.0 (minor updates)
~2.3.1 = >=2.3.1 <2.4.0 (patch updates)
2.3.1 = exact version

確認と変更は分けてください。npm audit fix/dedupe、yarn dedupe、ncu -u は依存関係の状態を変更します。codemod／CLI パッケージは、実行前に対象を固定して確認してください。以下の changelog-parser/react-codeshift コマンドの形式は例示であり、実行可能だと決めつけず、実際の公式ツールに照らして確認する必要があります。正規表現による移行は構文を認識しないため、文字列、コメント、インポートを破損する可能性があります。確認済みの AST 変換を使用し、すべての差分を確認してください。SemVer の保証は互換性を証明するものではなく、1.0 未満ではキャレットのルールも異なります。最新バージョンではなく、リリースノートや peer 要件に基づいて正確な対象バージョンを選んでください。--force／--legacy-peer-deps は互換性の問題を解決するのではなく、保護機能を迂回します。React のバージョンが一致していることや DOM スナップショットがあることだけでは、完全なランタイム／ビジュアル検証にはなりません。既存の UPGRADE_PLAN.md を上書きしたり、暗黙に automerge を有効にしたりしないでください。

依存関係の分析

依存関係を監査する

# npm
npm outdated
npm audit
npm audit fix

# yarn
yarn outdated
yarn audit

# Check for major updates
npx npm-check-updates
npx npm-check-updates -u  # Update package.json

依存関係ツリーを分析する

# See why a package is installed
npm ls package-name
yarn why package-name

# Find duplicate packages
npm dedupe
yarn dedupe

# Visualize dependencies
npx madge --image graph.png src/

互換性マトリックス

// compatibility-matrix.js
const compatibilityMatrix = {
  'react': {
    '16.x': {
      'react-dom': '^16.0.0',
      'react-router-dom': '^5.0.0',
      '@testing-library/react': '^11.0.0'
    },
    '17.x': {
      'react-dom': '^17.0.0',
      'react-router-dom': '^5.0.0 || ^6.0.0',
      '@testing-library/react': '^12.0.0'
    },
    '18.x': {
      'react-dom': '^18.0.0',
      'react-router-dom': '^6.0.0',
      '@testing-library/react': '^13.0.0'
    }
  }
};

function checkCompatibility(packages) {
  // Validate package versions against matrix
}

段階的なアップグレード戦略

フェーズ 1：計画

# 1. Identify current versions
npm list --depth=0

# 2. Check for breaking changes
# Read CHANGELOG.md and MIGRATION.md

# 3. Create upgrade plan
echo "Upgrade order:
1. TypeScript
2. React
3. React Router
4. Testing libraries
5. Build tools" > UPGRADE_PLAN.md

フェーズ 2：段階的な更新

# Don't upgrade everything at once!

# Step 1: Update TypeScript
npm install typescript@latest

# Test
npm run test
npm run build

# Step 2: Update React (one major version at a time)
npm install react@17 react-dom@17

# Test again
npm run test

# Step 3: Continue with other packages
npm install react-router-dom@6

# And so on...

フェーズ 3：検証

// tests/compatibility.test.js
describe('Dependency Compatibility', () => {
  it('should have compatible React versions', () => {
    const reactVersion = require('react/package.json').version;
    const reactDomVersion = require('react-dom/package.json').version;

    expect(reactVersion).toBe(reactDomVersion);
  });

  it('should not have peer dependency warnings', () => {
    // Run npm ls and check for warnings
  });
});

破壊的変更への対応

破壊的変更を特定する

# Use changelog parsers
npx changelog-parser react 16.0.0 17.0.0

# Or manually check
curl https://raw.githubusercontent.com/facebook/react/main/CHANGELOG.md

自動修正用の Codemod

# React upgrade codemods
npx react-codeshift <transform> <path>

# Example: Update lifecycle methods
npx react-codeshift \
  --parser tsx \
  --transform react-codeshift/transforms/rename-unsafe-lifecycles.js \
  src/

カスタム移行スクリプト

// migration-script.js
const fs = require('fs');
const glob = require('glob');

glob('src/**/*.tsx', (err, files) => {
  files.forEach(file => {
    let content = fs.readFileSync(file, 'utf8');

    // Replace old API with new API
    content = content.replace(
      /componentWillMount/g,
      'UNSAFE_componentWillMount'
    );

    // Update imports
    content = content.replace(
      /import { Component } from 'react'/g,
      "import React, { Component } from 'react'"
    );

    fs.writeFileSync(file, content);
  });
});

テスト戦略

単体テスト

// Ensure tests pass before and after upgrade
npm run test

// Update test utilities if needed
npm install @testing-library/react@latest

統合テスト

// tests/integration/app.test.js
describe('App Integration', () => {
  it('should render without crashing', () => {
    render(<App />);
  });

  it('should handle navigation', () => {
    const { getByText } = render(<App />);
    fireEvent.click(getByText('Navigate'));
    expect(screen.getByText('New Page')).toBeInTheDocument();
  });
});

ビジュアルリグレッションテスト

// visual-regression.test.js
describe('Visual Regression', () => {
  it('should match snapshot', () => {
    const { container } = render(<App />);
    expect(container.firstChild).toMatchSnapshot();
  });
});

E2E テスト

// cypress/e2e/app.cy.js
describe('E2E Tests', () => {
  it('should complete user flow', () => {
    cy.visit('/');
    cy.get('[data-testid="login"]').click();
    cy.get('input[name="email"]').type('[email protected]');
    cy.get('button[type="submit"]').click();
    cy.url().should('include', '/dashboard');
  });
});

依存関係の自動更新

Renovate の設定

// renovate.json
{
  "extends": ["config:base"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": false
    },
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "labels": ["major-update"]
    }
  ],
  "schedule": ["before 3am on Monday"],
  "timezone": "America/New_York"
}

Dependabot の設定

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    reviewers:
      - "team-leads"
    commit-message:
      prefix: "chore"
      include: "scope"

ロールバック計画

# Work on a topic branch with a clean or separately preserved starting state.
# Record the original full commit SHA and lockfile before changing dependencies.
# If validation fails, keep the failed diff and logs for diagnosis.
# Review and revert only task-owned manifest/lockfile changes when appropriate,
# then use npm ci to restore the recorded lockfile; never delete the branch or others' work.

よくあるアップグレードパターン

ロックファイルの管理

# npm
npm install --package-lock-only  # Update lock file only
npm ci  # Clean install from lock file

# yarn
yarn install --frozen-lockfile  # CI mode
yarn upgrade-interactive  # Interactive upgrades

Peer 依存関係の解決

# npm 7+: strict peer dependencies
npm install --legacy-peer-deps  # Ignore peer deps

# npm 8+: override peer dependencies
npm install --force

ワークスペースのアップグレード

# Update all workspace packages
npm install --workspaces

# Update specific workspace
npm install package@latest --workspace=packages/app

リソース

• references/semver.md: セマンティックバージョニングガイド
• references/compatibility-matrix.md: よくある互換性の問題
• references/staged-upgrades.md: 段階的なアップグレード戦略
• references/testing-strategy.md: 包括的なテスト方法
• assets/upgrade-checklist.md: ステップごとのチェックリスト
• assets/compatibility-matrix.csv: バージョン互換性表
• scripts/audit-dependencies.sh: 依存関係の監査スクリプト

ベストプラクティス

1. 変更履歴を読む: 変更内容を把握します
2. 段階的にアップグレードする: メジャーバージョンを一度に1つずつアップグレードします
3. 十分にテストする: ユニットテスト、統合テスト、E2Eテストを実施します
4. ピア依存関係を確認する: 早めに競合を解決します
5. ロックファイルを使用する: 再現可能なインストールを確保します
6. 更新を自動化する: Renovate または Dependabot を使用します
7. 監視する: アップグレード後に実行時エラーがないか確認します
8. 記録する: アップグレードのメモを残します

アップグレードチェックリスト

Pre-Upgrade:
- [ ] Review current dependency versions
- [ ] Read changelogs for breaking changes
- [ ] Create feature branch
- [ ] Backup current state (git tag)
- [ ] Run full test suite (baseline)

During Upgrade:
- [ ] Upgrade one dependency at a time
- [ ] Update peer dependencies
- [ ] Fix TypeScript errors
- [ ] Update tests if needed
- [ ] Run test suite after each upgrade
- [ ] Check bundle size impact

Post-Upgrade:
- [ ] Full regression testing
- [ ] Performance testing
- [ ] Update documentation
- [ ] Deploy to staging
- [ ] Monitor for errors
- [ ] Deploy to production

よくある落とし穴

• すべての依存関係を一度にアップグレードする
• アップグレードのたびにテストしない
• ピア依存関係の警告を無視する
• ロックファイルの更新を忘れる
• 破壊的変更に関する注記を読まない
• メジャーバージョンを飛ばす
• ロールバック計画を用意しない

制限事項

• 上記で説明した範囲にタスクが明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。