# Dependency Update 2026

**Last Updated:** 2026-03-02

Comprehensive dependency update audit and upgrade log for all frameworks, libraries, tools, and dependencies across npm, Composer, Python, GitHub Actions, and Node.js.

## Summary

| Category | Updates | Status |
|----------|---------|--------|
| **npm** | 8 packages updated | ✅ Complete |
| **Composer** | 3 packages updated (including PhpSpreadsheet 5.x), PHP requirement updated to >=8.4 | ✅ Complete |
| **GitHub Actions PHP** | Updated workflows from PHP 8.2 to 8.4 | ✅ Complete |
| **Python** | 3 packages updated (including pandas 3.x) | ✅ Complete |
| **GitHub Actions** | 3 actions updated | ✅ Complete |
| **Node.js** | 20 → 22 LTS | ✅ Complete |
| **Security** | 4 low-severity vulnerabilities documented | ⚠️ Deferred |
| **Testing** | Core validation passed, installation complete | ✅ Complete |

## npm Package Updates

### Major Updates

| Package | Before | After | Breaking Changes |
|---------|--------|-------|------------------|
| **lint-staged** | ^15.5.2 | ^16.3.1 | Yes - see below |
| **postcss-cli** | ^9.1.0 | ^11.0.1 | Possible - check PostCSS config |
| **@fullhuman/postcss-purgecss** | ^6.0.0 | ^8.0.0 | Possible - check purge config |
| **globals** | ^15.15.0 | ^17.4.0 | Possible - ESLint globals may change |

### Minor/Patch Updates

| Package | Before | After | Notes |
|---------|--------|-------|-------|
| **markdown-link-check** | ^3.11.0 | ^3.14.2 | Minor update |
| **cssnano** | ^7.0.7 | ^7.1.2 | Patch update |
| **sharp** | ^0.34.4 | ^0.34.5 | Patch update |
| **postcss** | ^8.4.40 | ^8.5.6 | Patch update |

### Breaking Changes: lint-staged v16

**Key Changes:**

1. **Process Spawning**: Replaced `execa` with `tinyexec`. Node.js scripts must be explicitly run with `node`:
   ```json
   { "*.js": "node my-js-linter.js" }
   ```

2. **Removed `--shell` Flag**: No longer supports shell evaluation. Use shell scripts or function syntax:
   ```javascript
   export default { '*.ts': () => 'tsc --noEmit' }
   ```

3. **Node.js Requirement**: Minimum Node.js 20.18+ (project now uses Node 22)

4. **Configuration**: Advanced configuration validation removed (deprecated in v9)

**Migration Status:** ✅ No changes needed - current configuration uses standard array format compatible with v16.

## Composer Package Updates

### PHP Requirement Update

| Item | Before | After |
|------|--------|-------|
| **PHP** | >=8.0 | >=8.4 |

**Rationale:** Required for:
- google/apiclient v2.19+ (requires PHP ^8.1)
- phpoffice/phpspreadsheet v5.x (requires PHP ^8.1)
- maennchen/zipstream-php 3.2.1 (requires PHP ^8.3) - transitive dependency
- symfony/process v8.0.5 (requires PHP >=8.4) - transitive dependency

**GitHub Actions Update:** Updated workflows to use PHP 8.4 to match dependency requirements:
- `.github/workflows/production-deployment.yml`: Updated `php-version: '8.2'` → `'8.4'`
- `.github/workflows/code-quality.yml`: Updated `php-version: "8.2"` → `"8.4"`

**Deployment Fix:** Resolved deployment failure caused by PHP version mismatch between GitHub Actions (PHP 8.2) and composer.lock dependencies (requiring PHP 8.3+).

### Package Updates

| Package | Before | After | Notes |
|---------|--------|-------|-------|
| **google/apiclient** | ^2.15 | ^2.19 | Requires PHP ^8.1 |
| **phpstan/phpstan** | ^1.10 | ^1.12 | Latest stable 1.x |

### Major Updates Completed

| Package | Before | After | Breaking Changes |
|---------|--------|-------|------------------|
| **phpoffice/phpspreadsheet** | ^1.29 | ^5.5 | Yes - see below (updated in both composer.json and v2/composer.json) |

**Breaking Changes in PhpSpreadsheet 5.x:**

- **PHP Requirement:** Requires PHP ^8.1 (project updated to PHP >=8.1)
- **IOFactory Reader/Writer Names:** Format names changed (e.g., `'CSV'` → `'Csv'`, `'Excel2007'` → `'Xlsx'`)
- **Deprecated Methods Removed:** Several deprecated methods removed; use alternatives:
  - `Worksheet::duplicateStyleArray()` → `Worksheet::getStyle()->applyFromArray()`
  - `DataType::dataTypeForValue()` → `DefaultValueBinder::dataTypeForValue()`
  - `Conditional::getCondition()` → `Conditional::getConditions()[0]`
  - `Worksheet::getSelectedCell()` → `Worksheet::getSelectedCells()`

**Testing Required:** Excel generation endpoints and template generator must be thoroughly tested after upgrade.

**Testing Status:** ✅ Complete - All tests passed:
- PhpSpreadsheet 5.x verification script: All 6 tests passed
- Template generation: Successfully generated test template
- Template validator: Successfully validated generated Excel file (IOFactory::load() works correctly)
- API endpoints: Health check confirms PhpSpreadsheet 5.x available and working
- Batch generation: Successfully generated templates in batch mode
- No breaking changes found in codebase (uses IOFactory::load() which auto-detects format)

## Python Package Updates

| Package | Before | After | Notes |
|---------|--------|-------|-------|
| **jsonschema** | >=4.17.0 | >=4.26.0 | Requires Python >=3.10 (available) |
| **pytest** | >=7.4.0 | >=9.0.0 | Major update - test suite compatibility verified |

### Major Updates Completed

| Package | Before | After | Breaking Changes |
|---------|--------|-------|------------------|
| **pandas** | >=2.0.0 | >=3.0.0 | Yes - see below (BREAKING: Copy-on-Write default, string dtype changes) |

**Breaking Changes in Pandas 3.0:**

1. **Default String Data Type:**
   - String columns now use dedicated `str` dtype (backed by PyArrow if available)
   - Cannot store non-string values in string columns (raises error)
   - Missing values always represented as `NaN` (not `pd.NA`)

2. **Copy-on-Write (CoW) Default:**
   - All indexing operations behave as copies
   - Chained assignment no longer works (must use `.loc`)
   - `SettingWithCopyWarning` removed (no longer needed)

**Migration Strategy:** Test all Python scripts that use pandas. Enable warnings in pandas 2.3 first: `pd.options.mode.copy_on_write="warn"` to identify affected code.

**Affected Scripts:**
- `v2/systems/excel-template-generator/scripts/enhance-template.py`
- `v2/systems/excel-template-generator/scripts/analyze-keyword-reports.py`
- `docs/strategy-2026/scripts/extract_metrics.py`
- Various SEO strategy and blog analysis scripts

## GitHub Actions Updates

| Action | Before | After | Notes |
|--------|--------|-------|-------|
| **actions/checkout** | v4 | v6 | Latest version |
| **actions/setup-node** | v4 | v6.2.0 | Uses `.nvmrc` for Node version |
| **shivammathur/setup-php** | v2 | v2 (major tag) | Resolves to latest v2.x |
| **PHP Version** | 8.2 | 8.4 | Updated to match dependency requirements |

**Files Updated:**
- `.github/workflows/production-deployment.yml` - Updated PHP version to 8.4
- `.github/workflows/code-quality.yml` - Updated PHP version to 8.4
- `.github/workflows/lighthouse-ci.yml` - No PHP usage

**Deployment Fix (2026-03-02):**
- **Issue 1:** Deployment failed with "Your lock file does not contain a compatible set of packages" error
- **Root Cause 1:** GitHub Actions used PHP 8.2, but composer.lock dependencies require PHP 8.3+ (maennchen/zipstream-php 3.2.1) and PHP 8.4+ (symfony/process v8.0.5)
- **Solution 1:** Updated GitHub Actions workflows to use PHP 8.4 to match dependency requirements
- **Issue 2:** Deployment failed with "Unable to resolve action shivammathur/setup-php@v2.33.0, unable to find version v2.33.0"
- **Root Cause 2:** Version v2.33.0 does not exist; latest is v2.36.0
- **Solution 2:** Changed setup-php from `@v2.33.0` to `@v2` (major tag, resolves to latest v2.x)
- **Status:** Fixed - workflows updated, deployment should succeed

## Node.js Update

| Item | Before | After |
|------|--------|-------|
| **Node.js** | 20 LTS | 22 LTS |
| **EOL Date** | April 30, 2026 | April 30, 2027 |

**Rationale:** Node.js 20 reaches end of life in April 2026 (2 months away). Node.js 22 LTS provides:
- Extended security support through April 2027
- Better performance
- New features including native TypeScript support
- Avoids another major upgrade cycle soon

**Files Updated:**
- `.nvmrc` - Updated to `22`
- `.github/workflows/production-deployment.yml` - Uses `node-version-file: '.nvmrc'`
- `.github/workflows/lighthouse-ci.yml` - Uses `node-version-file: '.nvmrc'`

## Security Vulnerabilities

### npm Audit Results

**Status:** 4 low-severity vulnerabilities remain

**Details:**
- **Package:** `tmp` (via @lhci/cli dependency chain)
- **Severity:** Low
- **Issue:** Allows arbitrary temporary file/directory write via symbolic link
- **Affected:** @lhci/cli → inquirer → external-editor → tmp

**Action:** Deferred. `npm audit fix --force` would downgrade @lhci/cli from v0.15.1 to v0.1.0 (breaking change). Low-severity issue in dev dependency chain does not pose production risk.

**Monitoring:** Continue monitoring for updates to @lhci/cli that resolve this vulnerability.

## Testing & Validation

### Completed Tests

- ✅ `npm run lint` - ESLint works correctly (166 warnings, 0 errors)
- ✅ `npm run format:check` - Prettier works correctly
- ✅ `npm run build:css` - PostCSS compilation successful
- ✅ `npm run build` - Full build process successful
- ✅ `npm run minify` - Minification successful (40.2% size reduction)
- ✅ `npm install` - All dependencies install correctly
- ✅ `npm run check-links` - Markdown link validation passed
- ✅ `npm run check-links:rules` - Rules link validation passed
- ✅ `php v2/scripts/dev-helpers/check-php-extensions.php` - All extensions available
- ✅ `php v2/scripts/dev-helpers/pre-deployment-check.php` - All checks passed
- ✅ `php v2/scripts/blog/verify-lead-capture-copy.php --strict` - All posts validated
- ✅ `python3 v2/scripts/llms/validate-llms-metadata.py --report` - All metadata checks passed

### Pending Manual Tests

- ⏳ Node.js 22 local testing (requires Node 22 installation - use `nvm install 22`)
- ⏳ CI/CD workflow testing (requires PR creation to test GitHub Actions)
- ⏳ Lighthouse CI testing (requires `LHCI_GITHUB_APP_TOKEN` for upload)
- ⏳ Excel generation testing (requires `composer install` then test template generation)
- ⏳ Google API integration testing (requires actual API calls with credentials)
- ⏳ Production page testing (requires local server or production access)

## Rollback Procedures

### Node.js 22 Rollback

If Node.js 22 causes critical issues:

```bash
# Option 1: Switch to Node 20 via Homebrew
brew install node@20
export PATH="/opt/homebrew/opt/node@20/bin:$PATH"

# Option 2: Use nvm (if available)
nvm install 20
nvm use 20

# Restore .nvmrc
git checkout HEAD -- .nvmrc

# Restore CI workflows
git checkout HEAD -- .github/workflows/*.yml
```

### PhpSpreadsheet 5.x Rollback

If PhpSpreadsheet 5.x breaks Excel generation:

```bash
# Root composer.json - Rollback to 1.29
cd /Users/hadyelhady/Documents/GitHub/landingpage
php composer.phar require phpoffice/phpspreadsheet:^1.29

# v2/composer.json - Rollback to 1.20
cd v2
php ../composer.phar require phpoffice/phpspreadsheet:^1.20

# Or restore from git
git checkout HEAD -- composer.json composer.lock v2/composer.json v2/composer.lock
php composer.phar install
```

**Note:** After rollback, test Excel generation thoroughly as PhpSpreadsheet 1.x has different API patterns.

### npm Packages Rollback

```bash
# Restore package.json from git
git checkout HEAD -- package.json package-lock.json

# Reinstall
npm install
```

### Python pandas 3.x Rollback

If pandas 3.x causes issues (requires virtual environment):

```bash
# In virtual environment
source .venv/bin/activate
pip install "pandas>=2.0.0,<3.0.0"

# Or restore requirements.txt
git checkout HEAD -- requirements.txt
pip install -r requirements.txt
```

### GitHub Actions Rollback

```bash
# Restore all workflow files
git checkout HEAD -- .github/workflows/*.yml
```

## Helper Scripts Created

1. **`v2/scripts/dev-helpers/check-dependency-versions.php`**
   - Compares current vs latest package versions
   - Usage: `php v2/scripts/dev-helpers/check-dependency-versions.php`

2. **`v2/scripts/dev-helpers/test-node-22-compatibility.js`**
   - Tests Node.js 22 compatibility with build tools
   - Usage: `node v2/scripts/dev-helpers/test-node-22-compatibility.js`

## Next Steps

### Immediate

1. ✅ **Run full validation** - `make validate` completed successfully
2. ✅ **Run pre-deploy checks** - `make pre-deploy` checks passed
3. ⏳ **Test Node.js 22 locally** - Install Node 22 (`nvm install 22`) and run compatibility tests
4. ⏳ **Test CI workflows** - Create test PR to verify GitHub Actions work correctly
5. ⏳ **Test Excel generation** - Run `composer install` then test template generation with PhpSpreadsheet 5.x
6. ⏳ **Monitor production** - Watch for regressions after deployment

### Short-term (Next Sprint)

1. **Evaluate PhpSpreadsheet upgrade** - Test Excel generation with v5.x
2. **Evaluate pandas upgrade** - Review breaking changes and test Python scripts
3. **Address security vulnerabilities** - Monitor @lhci/cli updates

### Long-term

1. **Annual dependency review** - Schedule quarterly dependency audits
2. **Automated testing** - Add dependency update tests to CI
3. **Documentation** - Keep this log updated with future changes

## References

- [Tailwind v4 Migration](TAILWIND_V4_MIGRATION.md)
- [ESLint Migration 2026](ESLINT_MIGRATION_2026.md)
- [Development Tooling](DEV_TOOLING.md)
- [Pre-Production Audit Checklist](PRE_PRODUCTION_AUDIT_CHECKLIST.md)
- [lint-staged v16 Changelog](https://github.com/lint-staged/lint-staged/blob/main/CHANGELOG.md)
- [Node.js 20 EOL Announcement](https://nodejs.org/blog/announcements/node-18-eol-support)