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

• Visit https://www.npmjs.com/package/PACKAGE

• Navigate to Versions tab → select target version

• Check README and Changelog links in sidebar

• 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

• Visit https://www.npmjs.com/package/PACKAGE

• Check Security tab (if available)

• Review recent issues on GitHub repository (/issues or /security )

• 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

• Visit package repository (link in https://www.npmjs.com/package/PACKAGE )

• Check CHANGELOG.md, HISTORY.md, or RELEASES.md in repo root

• Navigate to GitHub Releases section → filter by versions of interest

• Search commit history for "BREAKING CHANGE" commits between versions

• 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:

• Changelog summary for research comment

• Security advisories for risk assessment

• Breaking changes for code impact analysis

• Dependency blast radius combined with pnpm-dependency-analysis

• PR-level code changes when release notes lack details or breaking changes need investigation

Recommended workflow

• Run npm-research to gather data (changelog, security, versions)

• If needed: Use gh CLI to research specific PRs mentioned in release notes

• If needed: View code-level changes from critical PRs (breaking changes, security fixes)

• Feed findings to pnpm-dependency-analysis for workspace impact

• Use results to populate research comment template

• Inform decision on whether code changes are needed

• 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