Dependency Change Report

A tool to analyze dependency changes between different versions of a Node.js project and generate detailed reports with changelogs.

Features

Compare dependencies between two versions of a repository
Identify added, upgraded, removed, and modified dependencies
Generate changelogs for upgraded dependencies by analyzing commit history
Detect namespace changes in dependencies (e.g., from package to @org/package)
Create HTML reports with detailed information
Track and report errors during changelog generation

Installation

Using npx (Recommended)

No installation required! Run directly with npx:

npx dependency-change-report <github-repo> <older-version> <newer-version> [working-dir]

Global Installation (Alternative)

For frequent use, you can install globally:

npm install -g dependency-change-report

Then run with:

dependency-change-report <github-repo> <older-version> <newer-version> [working-dir]

Usage

Command Line Interface

Generate a dependency report:

# Using npx (recommended)
npx dependency-change-report <github-repo> <older-version> <newer-version> [working-dir]

# If installed globally
dependency-change-report <github-repo> <older-version> <newer-version> [working-dir]

The tool automatically generates three report formats:

report.json - Raw data in JSON format
report.html - Web-friendly HTML report
report.txt - Slack-friendly text report

Examples

# Generate a report comparing v1.0.0 and v2.0.0 of a repository
npx dependency-change-report git@github.com:user/repo.git v1.0.0 v2.0.0

# Generate a report with a specific working directory
npx dependency-change-report git@github.com:user/repo.git v1.0.0 v2.0.0 /tmp/analysis

# Filter nested dependencies by namespace (e.g., @holepunch)
npx dependency-change-report git@github.com:user/repo.git v1.0.0 v2.0.0 . @holepunch

Programmatic Usage

You can also use the tool programmatically in your own Node.js projects:

import { analyzeDependencyChanges } from 'dependency-change-report';
import { generateHtmlReport } from 'dependency-change-report/lib/generate-html.mjs';
import { generateTextReport } from 'dependency-change-report/lib/generate-text.mjs';

// Generate a dependency report
const report = await analyzeDependencyChanges(
  'git@github.com:user/repo.git',
  'v1.0.0',
  'v2.0.0'
);

// Generate an HTML report from a JSON report
await generateHtmlReport('./path/to/report.json', './path/to/output.html');

// Generate a text report from a JSON report
await generateTextReport('./path/to/report.json', './path/to/output.txt');

Report Structure

The generated JSON report includes:

Repository information
Version comparison details
Lists of added, upgraded, removed, and modified dependencies
Changelogs with commit history for upgraded dependencies
Error information for dependencies that couldn't be analyzed

The HTML report provides a user-friendly visualization of this data, including:

Summary statistics
Detailed tables of dependency changes
Commit history for upgraded dependencies
Error information

How It Works

Clones the repository at both the older and newer versions
Installs dependencies for both versions
Compares the dependency trees to identify changes
For each upgraded dependency, clones its repository and analyzes commit history
Generates a JSON report with all the collected information
Optionally converts the JSON report to an HTML report

Requirements

Node.js 14 or higher
Git
npm

GitHub Actions Integration

This tool is designed to work seamlessly with GitHub Actions to automatically generate dependency reports for pull requests and releases.

Basic Setup

Create .github/workflows/dependency-report.yml in your repository:

name: Dependency Change Report
on:
  pull_request:
    branches: [ main ]

jobs:
  dependency-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Need full history for version detection
      
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Generate dependency report
        run: npx dependency-change-report auto --output-dir ./reports
      
      - name: Upload reports as artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dependency-reports
          path: ./reports/
          retention-days: 30

Advanced Setup with PR Comments

For automatic PR comments with the dependency report:

name: Dependency Change Report
on:
  pull_request:
    branches: [ main ]

jobs:
  dependency-report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Generate dependency report
        id: dep-report
        run: npx dependency-change-report auto --output-dir ./reports
      
      - name: Upload reports as artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dependency-report-PR-${{ github.event.number }}
          path: ./reports/
          retention-days: 30
      
      - name: Comment PR with report
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const path = './reports/dependency-report-PR-${{ github.event.number }}.md';
            if (fs.existsSync(path)) {
              const report = fs.readFileSync(path, 'utf8');
              github.rest.issues.createComment({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: report
              });
            }

Compare Specific Versions

To compare specific commits or tags instead of auto-detection:

      - name: Generate dependency report
        run: npx dependency-change-report compare https://github.com/${{ github.repository }} ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }} --output-dir ./reports

Available Outputs

When running in GitHub Actions, the tool provides these outputs that can be used in subsequent steps:

has-changes: true if any dependencies changed
added-count: Number of added dependencies
upgraded-count: Number of upgraded dependencies
removed-count: Number of removed dependencies
report-dir: Directory containing the generated reports

Generated Files

In GitHub Actions, the tool automatically generates files with PR-specific names:

dependency-report-PR-123.html - Interactive HTML report
dependency-report-PR-123.md - Markdown report (perfect for PR comments)
dependency-report-PR-123.txt - Plain text report
report.json - Raw JSON data

Accessing Reports

Reports are saved as GitHub Actions artifacts and can be:

Downloaded from the Actions tab - Click on the workflow run and download the artifact
Viewed in PR comments - If using the advanced setup with PR comments
Accessed programmatically - Using the GitHub API to download artifacts

License

ISC

ryanramage/dependency-change-report