Transitive Dependency Analyzer for Node.js Projects

This AWS Prescriptive Guidance pattern provides a Python tool for analyzing Node.js dependency trees to identify all occurrences of a target dependency package. The tool uses breadth-first search (BFS) to traverse the dependency tree and provides detailed information about where and how a specific package is used throughout your project's dependencies.

Table of Contents

• Overview
• Prerequisites
• Installation
• Usage
• Output Format
• Troubleshooting
• Security
• Contributing
• License

Overview

What does this tool do?

The Transitive Dependency Analyzer helps you:

• Identify all occurrences of a specific dependency in your Node.js project
• Track dependency depth to understand how deeply nested dependencies are
• Analyze version usage to identify version conflicts or inconsistencies
• Generate detailed reports for dependency audits and security reviews

When should you use this tool?

Use this tool when you need to:

• Audit dependencies for security vulnerabilities
• Identify which packages depend on a specific library
• Understand your dependency tree structure
• Plan dependency upgrades or removals
• Document transitive dependencies for compliance

Key Features

• ✅ Fast breadth-first search algorithm
• ✅ Comprehensive error handling and validation
• ✅ Detailed logging with verbose mode
• ✅ Customizable output formats
• ✅ No external dependencies (uses Python standard library only)
• ✅ Timeout protection for large projects

Prerequisites

Before using this tool, ensure you have:

• Python 3.6 or higher installed
• Node.js and npm installed and accessible in your PATH
• A Node.js project with a package.json file

To verify your environment:

# Check Python version
python --version  # Should be 3.6+

# Check npm is available
npm --version

Installation

1. Clone this repository:

git clone https://github.com/aws-samples/transitive-dependency-analyzer
cd transitive-dependency-analyzer

2. No additional installation required - the tool uses only Python standard library modules.

Usage

Basic Usage

python tree_traverse.py --target <package-name> --path <project-path>

Command-Line Options

Option	Short	Required	Description
--target	-t	Yes	Target dependency package name to search for
--path	-p	Yes	Path to the Node.js project directory
--output	-o	No	Custom output file path (default: <target>_dependency_analysis.txt)
--verbose	-v	No	Enable verbose logging for detailed output

Examples

Example 1: Analyze a specific dependency

python tree_traverse.py --target lodash --path /path/to/my-project

Example 2: Custom output file

python tree_traverse.py -t react -p ./my-app -o react_analysis.txt

Example 3: Verbose logging for debugging

python tree_traverse.py -t express -p ~/projects/api-server -v

Example 4: Security audit

# Find all uses of a package with known vulnerabilities
python tree_traverse.py -t minimist -p ./production-app -o security-audit.txt

Output Format

The tool generates a text file with the following structure:

Dependency Analysis Report
Target Dependency: lodash
Total Occurrences: 3
============================================================

Parent Package: express
  Depth Count: 2
  Breadth Count: 5
  Currently depends on version 4.17.21 of lodash

Parent Package: body-parser
  Depth Count: 3
  Breadth Count: 8
  Currently depends on version 4.17.21 of lodash

Understanding the Metrics

• Parent Package: The package that directly depends on the target
• Depth Count: How many levels deep in the dependency tree (0 = direct dependency)
• Breadth Count: The order in which dependencies were discovered during BFS traversal
• Version: The version of the target dependency being used

Troubleshooting

Common Issues

Issue	Solution
"npm command not found"	Ensure Node.js and npm are installed and in your PATH
"No package.json found"	Verify you're pointing to a valid Node.js project root directory
"npm list command timed out"	Large projects may take time; the tool has a 60-second timeout
"No occurrences found"	Verify the package name spelling; try npm list <package> manually

Getting Help

For additional help:

1. Check the Quick Start Guide for step-by-step instructions
2. Review the Modernization Documentation for technical details
3. Open an issue on GitHub with your error message and environment details

Security

See CONTRIBUTING for more information on reporting security issues.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on:

• Reporting bugs and feature requests
• Submitting pull requests
• Code of conduct
• Development guidelines

License

This library is licensed under the MIT-0 License. See the LICENSE file.

Additional Resources

• Quick Start Guide - Get started in 2 minutes
• Modernization Details - Technical improvements and changes
• AWS Prescriptive Guidance - More patterns and best practices

---

Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.