npmchangelogcheck

npmchangelogcheck is a CLI that analyzes npm dependency updates, detects public API differences, and maps those differences to imports used in your project.

It helps answer:

• Which updated packages look breaking for my code?
• Which imports and symbols are affected?
• Do package changelogs/releases explain what changed?

Key Capabilities

• Detect version changes from:
  • package-lock.json old/new pair
  • git refs (--base / --head)
  • npm audit fix --dry-run --json (plan --source auditfix)
• Analyze project imports with ts-morph (fallback: tree-sitter)
• Snapshot package APIs using multiple strategies:
  • native .d.ts
  • generated declarations from JS entrypoints
  • AST fallback (tree-sitter/regex)
• Diff APIs and estimate release impact:
  • major / minor / patch / none / unknown
• Attach changelog context from:
  • packaged changelog files
  • npm diff
  • GitHub Releases API
• Render reports in console, json, or markdown

Requirements

• Node.js >= 20.17
• npm (lockfile-based workflow)
• package-lock.json with packages entries (npm v7+ lockfile)
• git if you use --base/--head mode
• Internet access for package extraction/changelog providers

Installation

From source:

npm install
npm run build

Run without build:

npm run dev -- --help

Run built CLI:

node dist/cli.js --help

Quick Start

1. Prepare two lockfiles (before/after update).
2. Run scan and output Markdown report.

npm run dev -- scan \
  --from-lock package-lock.old.json \
  --to-lock package-lock.json \
  --format markdown \
  --out npmchangelogcheck-report.md

Git-based diff example (uses package-lock.json from refs):

npm run dev -- scan --base origin/main --head WORKTREE

CLI Reference

scan

Scans updated dependencies and produces an API-impact report.

npm run dev -- scan [options]

Main options:

• --from-lock <path> old lockfile path
• --to-lock <path> new lockfile path
• --base <git-ref> base git ref containing package-lock.json
• --head <git-ref> head git ref (default: WORKTREE)
• --project-root <path> project root
• --cache-dir <path> extraction cache directory
• --temp-dir <path> temp directory for generated artifacts
• --package <name...> restrict analysis to specific packages
• --format <console|json|markdown> output format
• --out <path> write output to file
• --no-changelog disable all changelog providers
• --no-github-releases disable GitHub releases fetch
• --no-npm-diff disable npm diff provider
• --github-token <token> GitHub token (or use GITHUB_TOKEN)

Notes:

• scan requires either:
  • --from-lock and --to-lock, or
  • --base and --head
• Analysis is resilient: if one package fails, scanning continues and records errors.

plan

Shows planned dependency updates without full API diffing.

npm run dev -- plan --source lockdiff --from-lock package-lock.old.json --to-lock package-lock.json
npm run dev -- plan --source auditfix

Options:

• --source <lockdiff|auditfix> update source (lockdiff default)
• --from-lock, --to-lock, --base, --head, --project-root
• --format <console|json|markdown>

explain

Wrapper around npm explain to inspect why a package is installed.

npm run dev -- explain lodash
npm run dev -- explain lodash --json

How It Works

1. Build package update list from lockfile diff or git refs.
2. Scan your source files to collect imported package specifiers/symbols.
3. Extract old/new package versions via pacote.
4. Snapshot public surface per used specifier (.d.ts -> generated d.ts -> AST fallback).
5. Compare snapshots and estimate impact (major/minor/patch/none/unknown).
6. Annotate with changelog/release notes and usage callsites.

Output

scan summary includes:

• packagesChanged
• breakingPackages (estimated)
• breakingChanges affecting imports found in your code

releaseType is an estimate based on detected API changes, not a guarantee of runtime behavior.

Limitations

• Static analysis only; runtime behavior changes are out of scope.
• Dynamic imports/reflection patterns may be missed.
• Accuracy is best when packages provide high-quality .d.ts.
• Currently built around npm lockfile workflows (package-lock.json).

Development

npm install
npm run lint
npm test
npm run build

Contributing

Issues and pull requests are welcome.

• Bug reports: include lockfile inputs, command used, and output format.
• Feature requests: describe expected workflow and constraints.

License

AGPL-3.0-only (see LICENSE).