Verify dependency upgrades

Compatibility & Regression Verification

When to Use

Use during diagnosis, planning, and implementation of any dependency upgrade to prove that the updated package graph installs cleanly, compiles, passes type and contract checks, and works at runtime across affected code paths.

Verification Hierarchy ("Installed $\neq$ Working")

A successful package manager install proves only that version constraints resolved and archives downloaded. Verify every upgrade across five layers:

1. Lockfile & Dependency Graph Diff Audit

Inspect git diff *lock* before running builds:

• Intended Scope: Confirm only targeted packages and their expected transitive dependencies moved.
• No Silent Downgrades or Major Splits: Ensure shared transitive dependencies were not accidentally downgraded or split into duplicate conflicting major versions.
• Registry & Integrity Sanity: Verify resolved URLs remain on trusted registries (registry.npmjs.org, packagist.org, pypi.org, crates.io), integrity hashes (sha512/sha256) are intact, and no unexpected git+ssh:// or untrusted tarball URLs appeared.
• Singleton Uniqueness: Run npm ls <pkg>, pnpm why <pkg>, or cargo tree -d to confirm critical singletons (framework core, router, ORM client, GraphQL, state store, tracer) resolve to a single unified instance.

2. Reproducible Install & Lifecycle Script Check

• Verify frozen lockfile semantics (npm ci, pnpm install --frozen-lockfile, yarn install --immutable, composer validate --strict, uv lock --check, cargo test --locked).
• Confirm native addons and postinstall codegen (node-gyp, sharp, esbuild, swc, prisma generate, composer dump-autoload --strict-psr) complete cleanly.

3. Static Analysis, Typechecking & Production Build

• Run the full typechecker (tsc --noEmit, vue-tsc, ngc, phpstan, mypy/pyright, cargo check --all-targets) to catch signature drift across all files.
• Run the production build / bundler (npm run build, vite build, next build, cargo build --release). Bundlers, tree-shakers, and SSR compilers surface ESM/CJS export condition errors that unit test runners mask.

4. Targeted Runtime & Integration Verification

• Run test suites covering every module that imports or configures the upgraded dependency, exercising the real library code path (not tests that mock out the upgraded package!) for I/O, serialization, auth, HTTP, database queries, CLI execution, or UI rendering. Compare results against the pre-upgrade baseline.

5. Handoff Report: Version Summary, Rollout & Rollback

Every completed dependency upgrade must report:

1. Version Table: Package name, previous locked version $\rightarrow$ new locked version, and upgrade rationale.
2. Contract & Code Changes: Call sites, configs, types, or overrides updated (plus removal conditions for temporary shims).
3. Verification Evidence: Exact install, typecheck, build, and test commands run and their outcomes.
4. Deployment & Rollback Notes: Required runtime/container updates, whether rollback is a clean git revert or involves persistent data/cache/schema state, and any unverified platforms.