@zimezone/z-command 1.0.1 → 1.1.1

package/templates/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,409 @@
+---
+name: dependency-upgrade
+description: Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing breaking changes in libraries.
+---
+
+# Dependency Upgrade
+
+Master major dependency version upgrades, compatibility analysis, staged upgrade strategies, and comprehensive testing approaches.
+
+## When to Use This Skill
+
+- Upgrading major framework versions
+- Updating security-vulnerable dependencies
+- Modernizing legacy dependencies
+- Resolving dependency conflicts
+- Planning incremental upgrade paths
+- Testing compatibility matrices
+- Automating dependency updates
+
+## Semantic Versioning Review
+
+```
+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
+```
+
+## Dependency Analysis
+
+### Audit Dependencies
+```bash
+# 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
+```
+
+### Analyze Dependency Tree
+```bash
+# 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
+
+```javascript
+// 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
+}
+```
+
+## Staged Upgrade Strategy
+
+### Phase 1: Planning
+```bash
+# 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
+```
+
+### Phase 2: Incremental Updates
+```bash
+# 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...
+```
+
+### Phase 3: Validation
+```javascript
+// 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
+  });
+});
+```
+
+## Breaking Change Handling
+
+### Identifying Breaking Changes
+```bash
+# 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 for Automated Fixes
+```bash
+# 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/
+```
+
+### Custom Migration Script
+```javascript
+// 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);
+  });
+});
+```
+
+## Testing Strategy
+
+### Unit Tests
+```javascript
+// Ensure tests pass before and after upgrade
+npm run test
+
+// Update test utilities if needed
+npm install @testing-library/react@latest
+```
+
+### Integration Tests
+```javascript
+// 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 Tests
+```javascript
+// visual-regression.test.js
+describe('Visual Regression', () => {
+  it('should match snapshot', () => {
+    const { container } = render(<App />);
+    expect(container.firstChild).toMatchSnapshot();
+  });
+});
+```
+
+### E2E Tests
+```javascript
+// 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('user@example.com');
+    cy.get('button[type="submit"]').click();
+    cy.url().should('include', '/dashboard');
+  });
+});
+```
+
+## Automated Dependency Updates
+
+### Renovate Configuration
+```json
+// renovate.json
+{
+  "extends": ["config:base"],
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["minor", "patch"],
+      "automerge": true
+    },
+    {
+      "matchUpdateTypes": ["major"],
+      "automerge": false,
+      "labels": ["major-update"]
+    }
+  ],
+  "schedule": ["before 3am on Monday"],
+  "timezone": "America/New_York"
+}
+```
+
+### Dependabot Configuration
+```yaml
+# .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"
+```
+
+## Rollback Plan
+
+```javascript
+// rollback.sh
+#!/bin/bash
+
+# Save current state
+git stash
+git checkout -b upgrade-branch
+
+# Attempt upgrade
+npm install package@latest
+
+# Run tests
+if npm run test; then
+  echo "Upgrade successful"
+  git add package.json package-lock.json
+  git commit -m "chore: upgrade package"
+else
+  echo "Upgrade failed, rolling back"
+  git checkout main
+  git branch -D upgrade-branch
+  npm install  # Restore from package-lock.json
+fi
+```
+
+## Common Upgrade Patterns
+
+### Lock File Management
+```bash
+# 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 Dependency Resolution
+```bash
+# npm 7+: strict peer dependencies
+npm install --legacy-peer-deps  # Ignore peer deps
+
+# npm 8+: override peer dependencies
+npm install --force
+```
+
+### Workspace Upgrades
+```bash
+# Update all workspace packages
+npm install --workspaces
+
+# Update specific workspace
+npm install package@latest --workspace=packages/app
+```
+
+## Resources
+
+- **references/semver.md**: Semantic versioning guide
+- **references/compatibility-matrix.md**: Common compatibility issues
+- **references/staged-upgrades.md**: Incremental upgrade strategies
+- **references/testing-strategy.md**: Comprehensive testing approaches
+- **assets/upgrade-checklist.md**: Step-by-step checklist
+- **assets/compatibility-matrix.csv**: Version compatibility table
+- **scripts/audit-dependencies.sh**: Dependency audit script
+
+## Best Practices
+
+1. **Read Changelogs**: Understand what changed
+2. **Upgrade Incrementally**: One major version at a time
+3. **Test Thoroughly**: Unit, integration, E2E tests
+4. **Check Peer Dependencies**: Resolve conflicts early
+5. **Use Lock Files**: Ensure reproducible installs
+6. **Automate Updates**: Use Renovate or Dependabot
+7. **Monitor**: Watch for runtime errors post-upgrade
+8. **Document**: Keep upgrade notes
+
+## Upgrade Checklist
+
+```markdown
+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
+```
+
+## Common Pitfalls
+
+- Upgrading all dependencies at once
+- Not testing after each upgrade
+- Ignoring peer dependency warnings
+- Forgetting to update lock file
+- Not reading breaking change notes
+- Skipping major versions
+- Not having rollback plan