Package Upgrade Review

Evaluates npm/yarn package version upgrades by performing source-level diff analysis, tracing all call sites, and producing a structured compatibility report.

Output language: Chinese (matching team conventions).

Quick Reference

Topic Guide Description

Review workflow review-workflow.md Step-by-step review process

Report template report-template.md Output format and risk guidelines

Example report example-report.md Real case: @isaacs/brace-expansion 5.0.0 -> 5.0.1

When to Use

• Dependabot / Renovate PRs that bump dependency versions

• Manual yarn upgrade or npm update changes

• Any PR that modifies yarn.lock or package-lock.json

• When team needs to understand what actually changed inside a package before merging

Workflow Overview

• Identify the package name and version range (old -> new)

• Download both versions from npm registry and extract

• Diff source code between versions (focus on JS/TS, not metadata)

• Classify changes: API signature, return value, new exports, removed exports, behavior changes

• Search project source code for direct imports/usage

• Search node_modules for indirect usage via intermediate packages

• Trace each call site to verify argument usage and compatibility

• Assess compatibility risks: signature, return type, return content, side effects

• Generate structured report to node_modules/.cache/pkg-upgrade/

• Post the full report as a PR comment via gh pr comment

Key Commands

Download and extract both versions for diffing

mkdir -p /tmp/pkg-diff && cd /tmp/pkg-diff curl -sL $(npm view PKG@OLD_VER dist.tarball) | tar xz -C old curl -sL $(npm view PKG@NEW_VER dist.tarball) | tar xz -C new

Compare file lists

diff -rq old/package new/package

Diff main source

diff old/package/dist/commonjs/index.js new/package/dist/commonjs/index.js

Search project code for direct usage

grep -r "PACKAGE_NAME" --include=".ts" --include=".tsx" --include="*.js" -l .
--exclude-dir=.git --exclude-dir=node_modules

Search node_modules for indirect usage

grep -rn "from ['"]PACKAGE_NAME['"]" node_modules/ --include=".js" --include=".mjs"
| grep -v "node_modules/.cache"

Check package metadata

npm view PKG@NEW_VER deprecated npm view PKG@NEW_VER dist.integrity

Report Output

• Local file: node_modules/.cache/pkg-upgrade/<package-name>-<old>-to-<new>.md

• PR comment: The full report MUST also be posted as a comment on the PR via gh pr comment

Related Skills

• /1k-code-review-pr
• Comprehensive PR code review (security, code quality, platform patterns)