NPM Research Skill

Automated skill for researching npm packages to identify changelogs, security advisories, breaking changes, and compatibility impacts.

Use Cases

• Evaluate a dependency upgrade before applying it
• Find security vulnerabilities affecting a package
• Understand breaking changes between versions
• Generate research summaries for dependency reviews
• Validate compatibility with current codebase
• Check release history and maintenance status

Core Research Methods

1. Retrieve Package Metadata

Get comprehensive package information from npm registry:

npm view PACKAGE --json > package-meta.json

Extracts:

• Current version and tags (latest, next, alpha, beta)
• All published versions and release dates
• Maintainers and repository information
• Dependencies and peer dependencies
• Keywords and homepage
• Download statistics

Parse to find specific versions:

npm view PACKAGE@VERSION --json

Get only the latest version info (compact):

npm view PACKAGE version
npm view PACKAGE versions --json | jq '.[-1]'

2. Changelog Research

From npm registry (if published in README or description)

npm view PACKAGE readme | grep -A 50 -i "changelog\|release\|history" | head -100

From GitHub releases (if package has repo link)

# Extract repository URL from package metadata
REPO_URL=$(npm view PACKAGE repository.url | sed 's/git+//g' | sed 's/.git$//g' | sed 's|https://github.com/||g')

# Fetch releases using GitHub CLI
gh api repos/${REPO_URL}/releases --paginate \
  | jq -r '.[] | "\(.tag_name): \(.name)\n\(.body)\n---"' \
  | head -200

From npm package release notes

# Query npm registry for release timeline
npm view PACKAGE time --json \
  | jq 'to_entries[] | select(.key | test("VERSION_PATTERN")) | "\(.key): \(.value)"'

Manual inspection approach

1. Visit https://www.npmjs.com/package/PACKAGE
2. Navigate to Versions tab → select target version
3. Check README and Changelog links in sidebar
4. Read linked GitHub repository releases section

3. Security Vulnerability Research

NPM audit data (local or remote)

# Check local project vulnerabilities for a specific package
npm audit --package-lock-only | grep -A 5 "PACKAGE"

# Query npm registry for package vulnerabilities
curl -s https://api.github.com/repos/npm/npm-audit-db/contents/data | jq '.'

NPM security advisories database

# Use npm CLI (requires npm v6+)
npm audit --audit-level=moderate

# Check specific package audit
npm audit --package-lock-only | jq '.vulnerabilities.PACKAGE'

Third-party security resources

• Snyk.io: https://snyk.io/vuln/npm:PACKAGE (search by package name)
• CVE Database: https://cve.mitre.org/ (search by CVE ID if known)
• GitHub Security Advisories: Search package name in https://github.com/advisories
• OWASP Dependency Check: Local scanning with known vulnerabilities database

Manual security check

1. Visit https://www.npmjs.com/package/PACKAGE
2. Check Security tab (if available)
3. Review recent issues on GitHub repository (/issues or /security)
4. Check for SECURITY.md file in repo root

4. Breaking Changes Research

From package.json semver bumps

# Compare two versions to estimate breaking changes
npm view PACKAGE versions --json | jq -r '.[] | select(test("VERSION_REGEX"))' | tail -20

# Identify major version bumps (likely breaking changes)
npm view PACKAGE versions --json | jq -r '.[] | select(startswith("2.") or startswith("3."))' 

From GitHub releases and tags

# Extract repository from package metadata
REPO=$(npm view PACKAGE repository.url | sed 's/git+//g' | sed 's/.git$//g' | sed 's|https://github.com/||g')

# Get tags using GitHub CLI
gh api repos/${REPO}/tags --paginate | jq -r '.[] | "\(.name): \(.commit.message)"'

# Compare commits between two tags
gh api repos/${REPO}/compare/VERSION1...VERSION2 \
  | jq -r '.commits[] | .commit.message' \
  | grep -i "breaking\|BREAKING CHANGE\|⚠️"

From CHANGELOG files

# Extract repository from package
REPO=$(npm view PACKAGE repository.url | sed 's/git+//g' | sed 's/.git$//g' | sed 's|https://github.com/||g')

# View file directly
gh api repos/${REPO}/contents/CHANGELOG.md --jq .content | base64 -d \
  | sed -n '/## \[VERSION_FROM\]/,/## \[VERSION_TO\]/p'

# Or clone repo and extract changelog
gh repo clone ${REPO} /tmp/repo-temp -- --depth=1
cat /tmp/repo-temp/CHANGELOG.md | sed -n '/## \[VERSION_FROM\]/,/## \[VERSION_TO\]/p'

Patterns to search for breaking changes:

• BREAKING CHANGE: or breaking change
• ⚠️ (warning emoji)
• Major version bumps (1.0.0 → 2.0.0)
• API changes in function signatures
• Removed exports or modules
• Changed configuration options
• Dependency removals or upgrades with semver constraints

Manual inspection

1. Visit package repository (link in https://www.npmjs.com/package/PACKAGE)
2. Check CHANGELOG.md, HISTORY.md, or RELEASES.md in repo root
3. Navigate to GitHub Releases section → filter by versions of interest
4. Search commit history for "BREAKING CHANGE" commits between versions
5. Check repository Wiki or Discussions for migration guides

5. Dependency Impact Analysis

Check what new or updated dependencies come with the package:

# Install in temporary directory and check dependencies
npm install PACKAGE@VERSION --no-save --prefix /tmp/research-PACKAGE

# List dependency tree
npm ls --prefix /tmp/research-PACKAGE

# Find new deps vs current version
diff <(npm ls PACKAGE@OLD_VERSION --json --prefix /tmp/old | jq '.dependencies | keys') \
     <(npm ls PACKAGE@NEW_VERSION --json --prefix /tmp/new | jq '.dependencies | keys')

6. Pull Request Research (when needed)

When a release mentions specific PRs or you need to understand code-level changes:

List recent PRs in package repository

# Extract repository from package
REPO=$(npm view PACKAGE repository.url | sed 's/git+//g' | sed 's/.git$//g' | sed 's|https://github.com/||g')

# List PRs merged between two tags/versions
gh pr list --repo ${REPO} --state merged --search "merged:>=VERSION_DATE" --json number,title,mergedAt,labels

# List PRs by milestone (if package uses milestones for releases)
gh pr list --repo ${REPO} --state merged --search "milestone:VERSION" --json number,title,url

View specific PR details and code changes

# Get PR details (title, body, labels, review status)
gh pr view PR_NUMBER --repo ${REPO} --json title,body,state,labels,reviews

# View PR diff (changed files summary)
gh pr diff PR_NUMBER --repo ${REPO}

# View specific file changes in PR
gh pr diff PR_NUMBER --repo ${REPO} -- path/to/file.ts

# Get list of changed files
gh pr view PR_NUMBER --repo ${REPO} --json files | jq -r '.files[].path'

Research breaking changes from PR content

# Search PR titles/bodies for breaking change keywords
gh pr list --repo ${REPO} --state merged --search "BREAKING in:title,body" --json number,title,url

# View PR conversation and review comments (identify concerns/warnings)
gh pr view PR_NUMBER --repo ${REPO} --comments

# Check if PR has breaking change label
gh pr view PR_NUMBER --repo ${REPO} --json labels | jq -r '.labels[] | select(.name | test("breaking"; "i")) | .name'

Find PRs between two releases

# Get commit range between versions
COMMITS=$(gh api repos/${REPO}/compare/v${OLD_VERSION}...v${NEW_VERSION} --jq '.commits[].sha')

# Find PRs associated with those commits
for commit in $COMMITS; do
  gh api "repos/${REPO}/commits/${commit}/pulls" --jq '.[].number'
done | sort -u | while read pr; do
  gh pr view $pr --repo ${REPO} --json number,title,url
done

When to research PRs

• Release notes reference specific PR numbers → View those PRs for detailed context
• Breaking changes mentioned without details → Search for related PRs
• Major refactors or API changes → Review code changes to understand impact
• Security fixes → Verify the fix and check if it affects your usage patterns
• Undocumented changes → Find PRs between versions to discover unlisted changes
• Migration guidance needed → Look for migration-related PRs or discussions

7. Peer Dependency Warnings

Identify peer dependency requirements:

npm view PACKAGE@VERSION peerDependencies --json

# Check if current project satisfies peer deps
npm ls --depth=0 REQUIRED_PEER_DEP

Structured Research Template

Use this checklist for comprehensive research:

## NPM Research: PACKAGE (OLD_VERSION → NEW_VERSION)

### Release Information
- [ ] Current stable version: `X.Y.Z`
- [ ] Target version: `X.Y.Z`
- [ ] Release date: YYYY-MM-DD
- [ ] Maintenance status: (active/inactive/deprecated)

### Changelog Summary
- **Key features added**: ...
- **Bug fixes**: ...
- **Performance improvements**: ...
- **Deprecated features**: ...

### Breaking Changes
- [ ] Major version bump: Yes / No
- **Critical breaking changes**:
  - ...
- **Migration guide**: Link to docs or GitHub discussion
- **Related PRs reviewed**: #123, #456 (if applicable)

### Security Advisories
- [ ] Known vulnerabilities in current version: None / CVE-LIST
- [ ] Known vulnerabilities in target version: None / CVE-LIST
- [ ] Security advisory links: ...
- **Security fix PRs**: (if applicable)

### Dependency Changes
- **New dependencies**: (list major ones)
- **Removed dependencies**: (list major ones)
- **Updated dependency versions**: (check for conflicts)
- **Peer dependency requirements**: (verify compatibility)

### Pull Requests Reviewed (if needed)
- **PR #XXX**: Brief summary of changes and impact
- **PR #YYY**: Brief summary of changes and impact
- **Code changes affecting us**: (specific files/functions if relevant)

### Codebase Impact
- [ ] Need code changes: Yes / No
  - Details: ...
- [ ] Need configuration changes: Yes / No
  - Details: ...
- **Estimated risk level**: Low / Medium / High
- **Recommendation**: Safe to upgrade / Review carefully / Wait

### References
- npm registry: https://www.npmjs.com/package/PACKAGE
- GitHub releases: LINK
- Changelog: LINK
- Security advisories: LINK

Quick Commands Reference

Task	Command
Get latest version	npm view PACKAGE version
List all versions	npm view PACKAGE versions --json | jq '.[]'
Get package info	npm view PACKAGE --json
Check vulnerabilities	npm audit --audit-level=moderate
Read changelog	npm view PACKAGE readme | grep -i changelog
Get repo URL	npm view PACKAGE repository.url
Test install	npm install PACKAGE@VERSION --dry-run
Check peer deps	npm view PACKAGE@VERSION peerDependencies
List merged PRs	gh pr list --repo OWNER/REPO --state merged
View PR details	gh pr view PR_NUMBER --repo OWNER/REPO
View PR diff	gh pr diff PR_NUMBER --repo OWNER/REPO
Search PRs	gh pr list --repo OWNER/REPO --search "QUERY"

Integration with Fusion Framework

When used in Dependabot PR handler

The npm-research skill feeds into dependabot-pr-handler Step 4 (Research Dependencies) to provide:

1. Changelog summary for research comment
2. Security advisories for risk assessment
3. Breaking changes for code impact analysis
4. Dependency blast radius combined with pnpm-dependency-analysis
5. PR-level code changes when release notes lack details or breaking changes need investigation

Recommended workflow

1. Run npm-research to gather data (changelog, security, versions)
2. If needed: Use gh CLI to research specific PRs mentioned in release notes
3. If needed: View code-level changes from critical PRs (breaking changes, security fixes)
4. Feed findings to pnpm-dependency-analysis for workspace impact
5. Use results to populate research comment template
6. Inform decision on whether code changes are needed
7. Gate merge approval on security and breaking change assessment

Guardrails

• Always check date: Release dates reveal maintenance activity and urgency
• Cross-reference sources: Compare npm.js info, GitHub, and CVE databases
• Test locally first: Use --dry-run or test in isolated environment before full upgrade
• Document findings: Always provide research summary for team review
• Check peer dependencies: Ensure compatibility with entire dependency tree
• Verify deprecation status: Don't upgrade to deprecated versions without reason