codingbuddy-rules 2.4.2 → 3.0.2

package/.ai-rules/skills/dependency-management/lock-file-management.md

@@ -0,0 +1,437 @@
+# Lock File Management
+
+Procedures for maintaining lock file integrity and resolving conflicts.
+
+## Why Lock Files Matter
+
+Lock files ensure **reproducible builds**:
+- Exact versions installed across all environments
+- Prevents "works on my machine" issues
+- Security audit trail for dependencies
+- Faster installs (resolved dependency tree)
+
+**Treat lock files as source code.** They deserve the same care as any other code.
+
+## Lock File Types by Package Manager
+
+| Manager | Lock File | Format |
+|---------|-----------|--------|
+| npm | `package-lock.json` | JSON |
+| Yarn Classic | `yarn.lock` | Custom |
+| Yarn Berry | `yarn.lock` | YAML |
+| pnpm | `pnpm-lock.yaml` | YAML |
+| Bun | `bun.lockb` | Binary |
+
+## Merge Conflict Resolution
+
+### Prevention First
+
+**Golden rule:** Never have two PRs modifying dependencies at the same time.
+
+If unavoidable:
+1. Merge one PR first
+2. Rebase second PR
+3. Regenerate lock file
+
+### Resolution Procedure
+
+When conflicts occur:
+
+```bash
+# Step 1: Accept the target branch's package.json (usually main)
+git checkout main -- package.json
+
+# Step 2: Delete the conflicted lock file
+rm package-lock.json  # or yarn.lock, pnpm-lock.yaml
+
+# Step 3: Reinstall to regenerate lock file
+npm install  # or yarn, pnpm install
+
+# Step 4: Verify no unexpected changes
+git diff package-lock.json
+
+# Step 5: Commit the resolved lock file
+git add package.json package-lock.json
+git commit -m "chore: resolve lock file conflict"
+```
+
+### What NOT to Do
+
+- **Don't manually edit lock files** - Always regenerate
+- **Don't merge conflict markers** - Lock files aren't mergeable
+- **Don't use `--force` flags** - Investigate the conflict
+- **Don't skip lock file in commits** - It's required for reproducibility
+
+## CI/CD Validation
+
+### Lock File Integrity Check
+
+```yaml
+# GitHub Actions example
+- name: Verify lock file integrity
+  run: |
+    # For npm
+    npm ci
+    # Fails if lock file would change
+
+    # For yarn
+    yarn install --frozen-lockfile
+
+    # For pnpm
+    pnpm install --frozen-lockfile
+```
+
+### Preventing Lock File Drift
+
+```yaml
+# Fail if lock file is out of sync
+- name: Check lock file sync
+  run: |
+    npm install
+    git diff --exit-code package-lock.json || {
+      echo "Lock file out of sync with package.json"
+      exit 1
+    }
+```
+
+### Security Audit in CI
+
+```yaml
+- name: Security audit
+  run: |
+    npm audit --audit-level=high
+    # Fails build on high+ vulnerabilities
+```
+
+## Automated Update Strategies
+
+### Dependabot Configuration
+
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    # Group minor/patch updates
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+    # Separate PRs for majors
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+```
+
+### Renovate Configuration
+
+```json
+{
+  "extends": ["config:recommended"],
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["patch", "minor"],
+      "automerge": true,
+      "automergeType": "branch"
+    },
+    {
+      "matchUpdateTypes": ["major"],
+      "automerge": false,
+      "labels": ["breaking-change"]
+    }
+  ],
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": ["before 5am on monday"]
+  }
+}
+```
+
+### Auto-merge Safety Rules
+
+Only auto-merge when:
+- [ ] Patch/minor version only
+- [ ] All CI checks pass
+- [ ] No security advisories for new version
+- [ ] Package has >1M weekly downloads (stability indicator)
+- [ ] Not a critical dependency
+
+## Lock File Best Practices
+
+### Commit Lock Files Always
+
+```gitignore
+# .gitignore - DON'T ignore lock files
+# ❌ package-lock.json
+# ❌ yarn.lock
+```
+
+### Regenerate Periodically
+
+Schedule lock file regeneration:
+- Weekly for active projects
+- Before major releases
+- After security incidents
+
+```bash
+# Full regeneration
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Review Lock File Changes
+
+When reviewing PRs with lock file changes:
+
+1. **Check package.json first** - What was the intended change?
+2. **Verify version updates match** - Lock file should reflect package.json
+3. **Look for unexpected changes** - Transitive deps shouldn't change randomly
+4. **Check integrity hashes** - Should be present for all packages
+
+## Troubleshooting
+
+### "Lock file out of date"
+
+```bash
+# Regenerate lock file
+rm package-lock.json
+npm install
+```
+
+### "Peer dependency conflict"
+
+```bash
+# Find the conflict
+npm ls <conflicting-package>
+
+# Options:
+# 1. Update the parent package
+# 2. Use resolutions/overrides to force version
+# 3. Use --legacy-peer-deps (last resort)
+```
+
+### "Integrity checksum mismatch"
+
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Remove node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### "Different lock file locally vs CI"
+
+Causes:
+- Different npm version
+- Different Node version
+- npm registry differences
+
+Solutions:
+```bash
+# Pin npm version in CI
+npm install -g npm@10.x
+
+# Use .npmrc for registry consistency
+# .npmrc
+registry=https://registry.npmjs.org/
+
+# Use engines in package.json
+{
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  }
+}
+```
+
+## Lock File Audit
+
+### Finding Outdated Lock Entries
+
+```bash
+# List outdated packages
+npm outdated
+
+# Check for packages not in package.json
+npm prune --dry-run
+```
+
+### Removing Unused Dependencies
+
+```bash
+# Find unused dependencies
+npx depcheck
+
+# Remove and regenerate lock
+npm uninstall <unused-package>
+```
+
+### Lock File Size Management
+
+Large lock files indicate:
+- Too many dependencies
+- Duplicate packages
+- Outdated transitive deps
+
+```bash
+# Deduplicate (npm 7+)
+npm dedupe
+
+# Check package count
+jq '.packages | length' package-lock.json
+```
+
+## Private Registry Handling
+
+When using private npm registries (npm Enterprise, Artifactory, Verdaccio, GitHub Packages):
+
+### Authentication Setup
+
+```bash
+# .npmrc for private registry
+@myorg:registry=https://npm.mycompany.com/
+//npm.mycompany.com/:_authToken=${NPM_TOKEN}
+
+# GitHub Packages
+@myorg:registry=https://npm.pkg.github.com/
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+
+# Multiple registries
+@company-a:registry=https://npm.company-a.com/
+@company-b:registry=https://npm.company-b.com/
+```
+
+### CI/CD Authentication
+
+```yaml
+# GitHub Actions
+- name: Setup npm auth
+  run: |
+    echo "@myorg:registry=https://npm.pkg.github.com/" >> .npmrc
+    echo "//npm.pkg.github.com/:_authToken=${{ secrets.NPM_TOKEN }}" >> .npmrc
+
+# GitLab CI
+before_script:
+  - echo "@myorg:registry=https://${CI_SERVER_HOST}/api/v4/packages/npm/" >> .npmrc
+  - echo "//${CI_SERVER_HOST}/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
+```
+
+### Audit with Private Registries
+
+```bash
+# npm audit may not work with all private registries
+# Alternative: use registry-specific tools
+
+# Artifactory
+jfrog rt audit
+
+# Snyk (works with private registries)
+snyk test
+
+# GitHub Advisory Database (public packages only)
+npm audit --registry=https://registry.npmjs.org/
+```
+
+### Lock File Considerations
+
+1. **Registry URLs in lock file**
+   - Lock files contain resolved URLs
+   - Private registry URLs will be in lock file
+   - Don't commit auth tokens (they shouldn't be in lock file)
+
+2. **Mirrored packages**
+   - If using registry mirror, lock file URLs point to mirror
+   - CI/CD needs access to same registry
+   - Consider fallback to public registry
+
+3. **Scoped packages**
+   - Scoped packages (@org/pkg) route to configured registry
+   - Unscoped packages use default registry
+   - Verify both are accessible in CI
+
+### Troubleshooting Private Registries
+
+**"401 Unauthorized"**
+```bash
+# Verify token is set
+npm whoami --registry=https://npm.mycompany.com/
+
+# Re-authenticate
+npm login --registry=https://npm.mycompany.com/ --scope=@myorg
+```
+
+**"404 Not Found"**
+```bash
+# Check if package exists in private registry
+npm view @myorg/package --registry=https://npm.mycompany.com/
+
+# May need to proxy to public registry
+```
+
+**"UNABLE_TO_VERIFY_LEAF_SIGNATURE"**
+```bash
+# Self-signed certificate issue
+npm config set strict-ssl false  # Not recommended for production
+
+# Better: Add CA certificate
+npm config set cafile /path/to/ca-cert.pem
+```
+
+## Emergency Procedures
+
+### Lock File Corruption
+
+```bash
+# Nuclear option - full reset
+rm -rf node_modules package-lock.json .npm
+npm cache clean --force
+npm install
+```
+
+### Rollback Lock File
+
+```bash
+# Find last known good lock file
+git log --oneline -- package-lock.json
+
+# Restore specific version
+git checkout <commit-hash> -- package-lock.json
+npm ci
+```
+
+### Force Specific Versions
+
+When you need to override versions:
+
+```json
+// package.json (npm)
+{
+  "overrides": {
+    "vulnerable-package": "2.0.1"
+  }
+}
+
+// package.json (yarn)
+{
+  "resolutions": {
+    "vulnerable-package": "2.0.1"
+  }
+}
+
+// package.json (pnpm)
+{
+  "pnpm": {
+    "overrides": {
+      "vulnerable-package": "2.0.1"
+    }
+  }
+}
+```

package/.ai-rules/skills/dependency-management/major-upgrade-guide.md

@@ -0,0 +1,292 @@
+# Major Upgrade Guide
+
+Systematic approach to major version upgrades with breaking changes.
+
+## When Major Upgrades Are Needed
+
+- Current version reaches end-of-life
+- Security vulnerability only fixed in major version
+- Required feature only in major version
+- Dependency chain requires newer version
+
+## Breaking Change Analysis
+
+### Step 1: Read the Changelog
+
+**Completely.** Not skimming.
+
+For each breaking change, document:
+
+| Change | Current Usage | Impact | Migration |
+|--------|---------------|--------|-----------|
+| API renamed | 5 files | Low | Find/replace |
+| Behavior changed | 3 modules | Medium | Logic update |
+| Type changed | 15 imports | High | Refactor |
+
+### Step 2: Search Your Codebase
+
+```bash
+# Find all usages of changed APIs
+grep -r "deprecatedFunction" src/
+grep -r "changedType" src/
+
+# For TypeScript, also check type imports
+grep -r "import.*{.*ChangedType" src/
+```
+
+### Step 3: Check Peer Dependencies
+
+```bash
+# List what depends on this package
+npm ls <package>
+
+# Check if peers also need updates
+npm info <package>@<new-version> peerDependencies
+```
+
+## Staged Upgrade Strategy
+
+For major version jumps (e.g., v2 to v5), never jump directly.
+
+### Determine Intermediate Versions
+
+```
+Current: 2.4.1
+Target: 5.2.0
+
+Path: 2.4.1 → 3.0.0 → 4.0.0 → 5.0.0 → 5.2.0
+```
+
+### Benefits of Staged Upgrades
+
+1. **Smaller changesets** - Easier to review and test
+2. **Isolated failures** - Know which version broke
+3. **Incremental migrations** - Handle deprecations step by step
+4. **Rollback points** - Can stop at stable intermediate
+
+### When to Skip Stages
+
+Direct upgrade acceptable when:
+- Comprehensive migration guide exists
+- Breaking changes are well-documented
+- Test coverage is high (>90%)
+- Staging environment available
+
+## Compatibility Testing Strategy
+
+### Test Matrix
+
+| Test Type | When | Coverage Target |
+|-----------|------|-----------------|
+| Unit tests | Every upgrade | 90%+ |
+| Integration | Major versions | Critical paths |
+| E2E | Before production | Happy paths |
+| Performance | If perf-critical | Baseline comparison |
+
+### Regression Checklist
+
+Before each upgrade stage:
+
+- [ ] All existing tests pass
+- [ ] No new TypeScript errors
+- [ ] No new console warnings
+- [ ] Build size within 5% of baseline
+- [ ] Critical user flows work manually
+
+### Canary Testing
+
+For high-risk upgrades:
+
+1. Deploy to canary environment
+2. Route 5% of traffic
+3. Monitor error rates for 24 hours
+4. Gradually increase traffic
+5. Full rollout if stable
+
+## Common Upgrade Patterns
+
+### Pattern 1: Adapter Layer
+
+Create abstraction to isolate changes:
+
+```typescript
+// Before: Direct usage spread across codebase
+import { oldApi } from 'library';
+oldApi.doThing();
+
+// After: Centralized adapter
+// src/adapters/library-adapter.ts
+import { newApi } from 'library';
+
+export function doThing() {
+  // Translate old interface to new
+  return newApi.doNewThing();
+}
+
+// Usage unchanged
+import { doThing } from '@/adapters/library-adapter';
+doThing();
+```
+
+### Pattern 2: Feature Flag Migration
+
+Gradual migration with feature flags:
+
+```typescript
+const useNewLibraryVersion = featureFlags.get('USE_NEW_LIBRARY');
+
+if (useNewLibraryVersion) {
+  // New implementation
+  newLibrary.process(data);
+} else {
+  // Old implementation (fallback)
+  oldLibrary.process(data);
+}
+```
+
+### Pattern 3: Parallel Running
+
+Run both versions, compare results:
+
+```typescript
+async function processWithValidation(data: Input) {
+  const [oldResult, newResult] = await Promise.all([
+    oldLibrary.process(data),
+    newLibrary.process(data),
+  ]);
+
+  if (!deepEqual(oldResult, newResult)) {
+    logger.warn('Mismatch detected', { oldResult, newResult });
+    // Use old result while investigating
+    return oldResult;
+  }
+
+  return newResult;
+}
+```
+
+## Deprecation Handling
+
+### Types of Deprecations
+
+| Type | Urgency | Action |
+|------|---------|--------|
+| **Hard removal** | Before upgrade | Must fix |
+| **Soft deprecation** | Within 2 releases | Plan migration |
+| **Warning only** | Low priority | Track for future |
+
+### Finding Deprecation Warnings
+
+```bash
+# Run build and capture warnings
+npm run build 2>&1 | grep -i deprecat
+
+# Run tests with verbose output
+npm test -- --verbose 2>&1 | grep -i deprecat
+```
+
+### Documenting Deprecation Debt
+
+```markdown
+## Deprecation Tracking
+
+| Package | Deprecated API | Replacement | Files Affected | Target Version |
+|---------|---------------|-------------|----------------|----------------|
+| react | componentWillMount | useEffect | 5 | Remove in 18.x |
+| lodash | _.pluck | _.map | 12 | Already removed |
+```
+
+## Rollback Planning
+
+### Before Every Upgrade
+
+1. **Document current state**
+   ```bash
+   npm ls > pre-upgrade-deps.txt
+   git tag pre-upgrade-<package>-<date>
+   ```
+
+2. **Preserve lock file**
+   ```bash
+   cp package-lock.json package-lock.json.backup
+   ```
+
+3. **Test rollback procedure**
+   - Can you revert package.json?
+   - Does lock file restore work?
+   - Are there database migrations?
+
+### Rollback Triggers
+
+Rollback immediately if:
+- Error rate increases >5%
+- Critical path failures
+- Performance degrades >20%
+- Security regression detected
+
+### Rollback Procedure
+
+```bash
+# Revert package.json and lock file
+git checkout HEAD~1 -- package.json package-lock.json
+
+# Clean and reinstall
+rm -rf node_modules
+npm ci
+
+# Verify rollback
+npm test
+npm run build
+```
+
+## Estimation Guidelines
+
+| Factor | Multiplier |
+|--------|------------|
+| Well-documented migration guide | 1x |
+| No migration guide | 2x |
+| Breaking type changes | +0.5x per type |
+| Behavior changes | +1x per behavior |
+| Low test coverage (<60%) | 2x |
+| No staging environment | 1.5x |
+
+**Example estimation:**
+
+```
+Base: 2 hours
+- No migration guide: 2x = 4 hours
+- 3 breaking types: +1.5 hours
+- Low test coverage: 2x = 11 hours
+- Buffer (20%): 13.2 hours
+
+Estimate: 2 days
+```
+
+## Upgrade Checklist Template
+
+```markdown
+## Upgrade: [package] v[X] → v[Y]
+
+### Pre-upgrade
+- [ ] Changelog reviewed
+- [ ] Breaking changes documented
+- [ ] Impact assessed (files: X, risk: High/Medium/Low)
+- [ ] Tests baseline captured
+- [ ] Rollback procedure documented
+
+### Upgrade stages
+- [ ] Stage 1: v[X] → v[X+1]
+  - [ ] Tests passing
+  - [ ] Build successful
+  - [ ] Manual verification
+- [ ] Stage N: v[Y-1] → v[Y]
+  - [ ] Tests passing
+  - [ ] Build successful
+  - [ ] Manual verification
+
+### Post-upgrade
+- [ ] Full test suite passing
+- [ ] Performance verified
+- [ ] Deprecation warnings addressed
+- [ ] Documentation updated
+```