dependency-change-report 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# 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:
+
+```bash
+npx dependency-change-report <github-repo> <older-version> <newer-version> [working-dir]
+```
+
+### Global Installation (Alternative)
+
+For frequent use, you can install globally:
+
+```bash
+npm install -g dependency-change-report
+```
+
+Then run with:
+
+```bash
+dependency-change-report <github-repo> <older-version> <newer-version> [working-dir]
+```
+
+## Usage
+
+### Command Line Interface
+
+Generate a dependency report:
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```javascript
+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
+
+1. Clones the repository at both the older and newer versions
+2. Installs dependencies for both versions
+3. Compares the dependency trees to identify changes
+4. For each upgraded dependency, clones its repository and analyzes commit history
+5. Generates a JSON report with all the collected information
+6. Optionally converts the JSON report to an HTML report
+
+## Requirements
+
+- Node.js 14 or higher
+- Git
+- npm
+
+## License
+
+ISC

package/cli.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import { analyzeDependencyChanges } from './lib/index.mjs';
+import { generateHtmlReport } from './lib/generate-html.mjs';
+import { generateTextReport } from './lib/generate-text.mjs';
+import { dirname, join, basename } from 'path';
+
+// CLI interface
+const main = async () => {
+  try {
+    const args = process.argv.slice(2);
+    
+    if (args.length < 3) {
+      console.error('Usage: dependency-change-report <github-repo> <older-version> <newer-version> [working-dir] [namespace]');
+      console.error('  <older-version> and <newer-version> can be any git reference (tag, branch, commit)');
+      console.error('  [namespace] is optional - if provided, only second-level dependencies within this namespace will be analyzed (e.g., @holepunch)');
+      console.error('');
+      console.error('This command generates three files:');
+      console.error('  - report.json (raw data)');
+      console.error('  - report.html (web-friendly report)');
+      console.error('  - report.txt (Slack-friendly text report)');
+      process.exit(1);
+    }
+    
+    const [repoUrl, olderVersion, newerVersion, workingDir, namespace] = args;
+    
+    console.log(`Analyzing dependency changes for ${repoUrl} between older version (${olderVersion}) and newer version (${newerVersion})`);
+    if (namespace) {
+      console.log(`Filtering second-level dependencies to only include those in namespace: ${namespace}`);
+    }
+    const report = await analyzeDependencyChanges(repoUrl, olderVersion, newerVersion, workingDir, namespace);
+    
+    console.log('\nSummary:');
+    console.log(`Added dependencies: ${report.changes.added.length}`);
+    console.log(`Upgraded dependencies: ${report.changes.upgraded.length}`);
+    console.log(`Removed dependencies: ${report.changes.removed.length}`);
+    console.log(`Modified dependencies (namespace changes): ${report.changes.modified ? report.changes.modified.length : 0}`);
+    
+    // Display nested dependency information if available
+    if (report.changes.nested) {
+      console.log('\nNested Dependencies:');
+      console.log(`Added nested dependencies: ${report.changes.nested.added.length}`);
+      console.log(`Upgraded nested dependencies: ${report.changes.nested.upgraded.length}`);
+      console.log(`Removed nested dependencies: ${report.changes.nested.removed.length}`);
+      
+      if (namespace) {
+        console.log(`\nNote: Nested dependencies filtered by namespace: ${namespace}`);
+      }
+    }
+    
+    const changelogCount = Object.keys(report.changelogs).length;
+    const errorCount = Object.keys(report.errors).length;
+    console.log(`Generated changelogs for ${changelogCount} upgraded dependencies`);
+    console.log(`Encountered errors with ${errorCount} dependencies`);
+    
+    // Generate HTML and text reports
+    console.log('\nGenerating additional report formats...');
+    
+    // Use the actual report directory path from the report
+    const reportJsonPath = report.reportPath;
+    const reportDir = dirname(reportJsonPath);
+    
+    // Generate HTML report
+    const htmlPath = join(reportDir, 'report.html');
+    await generateHtmlReport(reportJsonPath, htmlPath);
+    
+    // Generate text report
+    const textPath = join(reportDir, 'report.txt');
+    await generateTextReport(reportJsonPath, textPath);
+    
+    console.log('\nAll reports generated successfully!');
+    console.log(`📄 JSON: ${reportJsonPath}`);
+    console.log(`🌐 HTML: ${htmlPath}`);
+    console.log(`📝 Text: ${textPath}`);
+    
+    // Display repository information for added dependencies
+    if (report.changes.added.length > 0) {
+      console.log('\nAdded dependencies with repositories:');
+      report.changes.added.forEach(dep => {
+        if (dep.repository) {
+          console.log(`- ${dep.name}: ${dep.repository}`);
+        }
+      });
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+};
+
+// Run the main function
+main();