CLI tool to analyze dependency evolution and release frequency
npm install @boilerbuilder/deps-analyzerš Advanced CLI tool to analyze dependency evolution, release frequency, and semver patterns in JavaScript/Node.js projects.
- š Auto-discovery: Finds package.json files in directories or glob patterns
- š NPM Analysis: Fetches release data from NPM registry with smart filtering
- š·ļø Semver Analysis: Detailed breakdown of major/minor/patch releases
- š
Time-based Analysis: Compares releases from different time periods (12m vs 12-24m)
- š Multiple Outputs: Generates both JSON and Markdown reports
- š Multiple Projects: Analyze multiple patterns/projects in one command
- ā” Fast: Built-in NPM CLI integration and efficient processing
- š”ļø Robust: Handles errors gracefully and continues processing
- š§ Smart Filtering: Automatically filters dev/beta/alpha/nightly versions
``bash`
git clone
cd deps-analyzer
npm install
`bash`
npm run link # Link globally for testing
deps-analyzer --help # Test the command
npm run unlink # Unlink when done
For detailed information on specific topics:
- Libyear Algorithm - Understanding drift/pulse metrics and calculations
- Max-Deps Configuration - Strategic version control and constraints
- NPM Client - Data collection strategies and filtering
- Report Interpretation - How to read and act on analysis results
`bashAnalyze templates directory
deps-analyzer ./templates
$3
`bash
Analyze specific projects
deps-analyzer templates/next-app templates/react-spa-vite --output selected-projectsMix directories and files
deps-analyzer ./frontend ./backend/package.json --output fullstack-analysis
`$3
`bash
Custom analysis period
deps-analyzer ./templates --months 18Custom output name
deps-analyzer ./templates --output my-reportSkip NPM analysis (discovery only)
deps-analyzer ./templates --no-npmUse HTTP instead of npm CLI (slower but more compatible)
deps-analyzer ./templates --use-httpAdvanced filtering for internal libraries
deps-analyzer ./templates --internal-libs "@akad/,design-system"Skip specific version filters
deps-analyzer ./templates --ignore-filter alpha,beta,rcCombined enterprise usage
deps-analyzer ./templates --internal-libs "@company/*" --ignore-filter canary,nightlyCustom max-deps configuration file
deps-analyzer ./templates --max-deps-config ./my-constraints.jsonStrategic version control example
echo '{"react": "^18.0.0", "typescript": "^5.0.0"}' > max-deps.json
deps-analyzer ./project --max-deps-config max-deps.jsonHelp and version
deps-analyzer --help
deps-analyzer --version
`$3
Analyze only internal or external dependencies using
--scope:`bash
Analyze only internal dependencies
deps-analyzer ./templates --scope=internal --internal-libs "@company/*"Analyze only external dependencies (excludes internal)
deps-analyzer ./templates --scope=external --internal-libs "@company/*"Analyze all dependencies (default behavior)
deps-analyzer ./templates --scope=all --internal-libs "@company/*"
`$3
Strategic version control with custom configuration files:
`bash
Production environment constraints
deps-analyzer ./templates --max-deps-config ./configs/production.jsonShared team constraints
deps-analyzer ./templates --max-deps-config /shared/team-constraints.jsonBenchmark analysis (zero-drift simulation)
deps-analyzer ./templates --max-deps-config ./benchmarks/zero-drift.json --output benchmarkEnterprise compliance analysis
deps-analyzer ./microservices --max-deps-config ./security/approved-versions.json
`Output
The tool generates two files with comprehensive analysis:
$3
`json
{
"metadata": {
"generatedAt": "2025-08-14T00:26:31.877Z",
"period": "24 months",
"totalProjects": 2,
"totalDependencies": 52,
"uniqueDependencies": 36,
"globalUniqueReleases": {
"totalLast12m": 1130,
"totalLast12to24m": 983,
"avgPerMonthLast12m": 94.17,
"avgPerMonthLast12to24m": 81.92,
"semverBreakdown": {
"majorLast12m": 26,
"minorLast12m": 165,
"patchLast12m": 597,
"avgMajorPerMonthLast12m": 2.17,
"avgMinorPerMonthLast12m": 13.75,
"avgPatchPerMonthLast12m": 49.75
}
}
},
"projects": {
"react-spa-vite": {
"packagePath": "/path/to/package.json",
"dependencyCount": 32,
"dependencies": {
"react": {
"currentVersion": "19.1.1",
"last12Months": 3,
"months12to24": 2,
"totalReleases": 345,
"avgReleasesPerMonthLast12m": 0.25,
"avgReleasesPerMonthLast12to24m": 0.17,
"avgDaysBetweenReleases": 14.6,
"semverBreakdown": {
"majorLast12m": 1,
"minorLast12m": 1,
"patchLast12m": 1,
"majorLast12to24m": 0,
"minorLast12to24m": 1,
"patchLast12to24m": 1
},
"monthlyBreakdown": {
"2024-12": ["19.0.0"],
"2025-03": ["19.1.0"],
"2025-07": ["19.1.1"]
},
"mostActiveMonth": "2024-12 (1)"
}
},
"metadata": {
"totalReleasesLast12m": 672,
"totalReleasesLast12to24m": 655,
"totalReleases": 6429,
"avgReleasesPerMonthLast12m": 56,
"avgReleasesPerMonthLast12to24m": 54.58,
"semverBreakdown": {
"totalMajorLast12m": 22,
"totalMinorLast12m": 140,
"totalPatchLast12m": 419,
"avgMajorPerMonthLast12m": 1.83,
"avgMinorPerMonthLast12m": 11.67,
"avgPatchPerMonthLast12m": 34.92
}
}
}
}
}
`$3
`markdown
Dependencies Evolution Report
Summary
- Generated at: 2025-08-14 00:26:31 UTC
- Analysis period: 24 months
- Projects analyzed: 2
- Total dependencies: 52
- Unique dependencies: 36Global Statistics
- Total releases (12m): 1,130 (avg: 94.17/month)
- Total releases (12-24m): 983 (avg: 81.92/month)
- Semver breakdown (12m): 26 major, 165 minor, 597 patchProject: react-spa-vite (32 dependencies)
$3
| Package | Current | 12m | 12-24m | Major | Minor | Patch | Most Active Month |
|---------|---------|-----|--------|-------|-------|-------|-------------------|
| react | 19.1.1 | 3 | 2 | 1 | 1 | 1 | 2024-12 (1) |
`API
$3
`javascript
const { main } = require('deps-analyzer');// Basic analysis
const result = await main(['./templates']);
// Multiple patterns
const result = await main([
'./templates/next-app',
'./templates/react-spa-vite'
]);
// With options
const result = await main(['./templates'], {
months: 18,
output: 'custom-report',
analyzeNpm: true,
useNpmCli: true
});
`Options Reference
| Option | Default | Description |
|--------|---------|-------------|
|
--months | 24 | Analysis period in months |
| --output | dependency-report | Output file base name |
| --scope | all | Filter dependencies by scope: internal, external, all |
| --no-npm | false | Skip NPM registry analysis (discovery only) |
| --use-http | false | Use HTTP requests instead of npm CLI (slower) |
| --ignore-filter | [] | Skip filtering specific version types (alpha,beta,rc,etc) |
| --internal-libs | [] | Libraries to include alpha/beta versions (supports wildcards: @akad/,design-system) |
| --max-deps-config | null | Custom max-deps.json file path for strategic version control |
| --help, -h | - | Show help information |
| --version, -v | - | Show version |Examples
$3
`bash
Analyze all templates
deps-analyzer ./templates --months 12 --output templates-reportAnalyze specific templates
deps-analyzer templates/next-app templates/react-spa-vite --output selected-templates
`$3
`bash
Analyze all packages
deps-analyzer "packages/*/package.json" --months 18Analyze specific workspaces
deps-analyzer packages/frontend packages/backend packages/shared --output monorepo-analysis
`$3
`bash
Skip NPM analysis for faster results
deps-analyzer ./project --no-npmDiscovery only with HTTP fallback
deps-analyzer ./project --no-npm --use-http
`$3
`bash
Comprehensive analysis with custom period
deps-analyzer ./microservices ./shared-libs --months 36 --output enterprise-deps
`Advanced Filtering
$3
The tool applies filtering in a specific order to ensure predictable results:
1. Scope Filtering (
--scope): First, filter dependencies by scope (internal, external, all)
2. Internal Library Classification (--internal-libs): Classify remaining dependencies as internal/external
3. Selective Version Filtering: Apply different filtering rules based on classification
4. Filter Overrides (--ignore-filter): Override specific version type filtering$3
The tool implements selective filtering that treats internal and external dependencies differently:
- External Dependencies: Automatically filters out pre-release versions (alpha, beta, rc, etc.)
- Internal Dependencies: Can include pre-release versions when specified via
--internal-libs$3
-
--scope=internal: Analyze only dependencies matching --internal-libs patterns
- --scope=external: Analyze only dependencies NOT matching --internal-libs patterns
- --scope=all: Analyze all dependencies (default), but still apply selective filtering logic$3
The
--internal-libs flag supports wildcard patterns:`bash
Exact match
deps-analyzer ./project --internal-libs "my-package"Scoped packages with wildcard
deps-analyzer ./project --internal-libs "@company/*"Multiple patterns
deps-analyzer ./project --internal-libs "@company/,design-system,@internal/*"
`$3
Use
--ignore-filter to skip specific version type filtering:`bash
Include alpha versions for ALL dependencies
deps-analyzer ./project --ignore-filter alphaInclude multiple pre-release types
deps-analyzer ./project --ignore-filter alpha,beta,rcCombined usage: include alpha/beta for internal libs only
deps-analyzer ./project --internal-libs "@company/*" --ignore-filter canary,nightly
`$3
#### Enterprise Monorepo Analysis
`bash
Analyze with company-specific internal libraries
deps-analyzer ./packages/* \
--internal-libs "@acme/,design-tokens" \
--ignore-filter canary \
--output enterprise-analysis
`#### Mixed Public/Private Dependencies
`bash
Allow alpha/beta for internal libs, strict filtering for external
deps-analyzer ./apps/frontend ./apps/backend \
--internal-libs "@company/,internal-" \
--output mixed-dependencies
`#### Historical Analysis with Custom Filters
`bash
Skip all pre-release filtering for specific analysis
deps-analyzer ./legacy-projects \
--ignore-filter alpha,beta,rc,canary,experimental \
--output legacy-comprehensive
`Understanding the Output
$3
The tool provides two different types of drift/pulse calculations that serve different purposes:
#### š¢ Global/Portfolio Metrics (Unique Dependencies)
- What it measures: Drift/pulse for each dependency once per portfolio
- Calculation: Sums drift only from unique dependencies across all projects
- Example: If
react appears in 4 projects, its drift is counted only once
- Use case: Strategic decisions - "Which dependencies should we prioritize updating?"#### š Project Metrics (Total Across Projects)
- What it measures: Drift/pulse for every occurrence of each dependency
- Calculation: Sums drift from all dependencies in all projects
- Example: If
react appears in 4 projects, its drift is counted 4 times
- Use case: Effort estimation - "How much total work is needed to update everything?"#### š” Example: 4 Projects with React (2y drift)
Scenario:
- 4 projects each use
react with 2 years of drift
- Each project also has lodash with 1 year of driftGlobal Drift (Unique Dependencies):
-
react: 2 years (counted once)
- lodash: 1 year (counted once)
- Total: 3 yearsProject Drift (Sum Across Projects):
- Project 1:
react (2y) + lodash (1y) = 3y
- Project 2: react (2y) + lodash (1y) = 3y
- Project 3: react (2y) + lodash (1y) = 3y
- Project 4: react (2y) + lodash (1y) = 3y
- Total: 12 years#### šÆ When to Use Each Metric
| Scenario | Use Global Metrics | Use Project Metrics |
|----------|-------------------|-------------------|
| Prioritizing which deps to update | ā
Focus on unique deps | ā May mislead priorities |
| Estimating update effort/time | ā Underestimates work | ā
Shows true scope |
| Executive reporting | ā
Clear strategic view | ā May seem inflated |
| Sprint planning | ā Doesn't show full work | ā
Shows actual tasks |
| Ecosystem health assessment | ā
True portfolio state | ā Duplicated concerns |
$3
The tool performs intelligent semver analysis:
- Major: Breaking changes (1.0.0 ā 2.0.0)
- Minor: New features (1.0.0 ā 1.1.0)
- Patch: Bug fixes (1.0.0 ā 1.0.1)$3
Automatically filters out:
- Development versions (-dev, -nightly)
- Alpha/Beta releases (-alpha, -beta)
- Release candidates (-rc)
- Experimental builds (-experimental, -canary)
- Malformed versions (0.0.0-*)$3
The tool detects version backports/downgrades:
- Total releases include all stable versions
- Semver breakdown only counts progressive releases
- Difference represents maintenance releases for older versionsTechnical Details
- Rate Limiting: Intelligent batching with NPM CLI
- Error Handling: Continues processing even if some packages fail
- Ignores:
node_modules/, public/, dist/, build/ directories
- Node Version: Requires Node.js >= 16.0.0
- NPM Version: Works with npm >= 7.0.0Development
$3
`
deps-analyzer/
āāā package.json
āāā README.md
āāā bin/
ā āāā deps-analyzer.js # CLI entry point
āāā lib/
ā āāā index.js # Core logic & discovery
ā āāā npm-client.js # NPM registry client
ā āāā libyear.js # Drift/pulse calculations
ā āāā reporter.js # Report generation
āāā utils/ # Utility functions
āāā chunkArray.js # Array chunking
āāā cleanVersion.js # Version cleaning
āāā filterDependenciesByScope.js # Dependency filtering
āāā findMaxAllowedVersion.js # Version constraint parsing
āāā findWorkspaceRoot.js # Workspace detection
āāā isInternalLib.js # Internal library matching
āāā parsePnpmLock.js # PNPM lock file parsing
āāā parseYarnLock.js # Yarn lock file parsing
āāā versionSatisfiesConstraint.js # Semver constraint checking
`$3
`bash
npm run start # Run with default args
npm run test # Test with templates
npm run dev # Run with debugging
npm run link # Link globally
npm run unlink # Unlink globally
`$3
`bash
Enable detailed error information
DEBUG=1 deps-analyzer ./templatesUse HTTP instead of npm CLI if issues
deps-analyzer ./templates --use-http
`Troubleshooting
$3
npm CLI not found
`bash
Use HTTP fallback
deps-analyzer ./templates --use-http
`Permission errors
`bash
Check npm permissions
npm config get prefix
npm config get cache
`Network timeouts
`bash
Increase npm timeout
npm config set timeout 60000
deps-analyzer ./templates
`Memory issues with large projects
`bash
Analyze projects separately
deps-analyzer ./project1 --output report1
deps-analyzer ./project2 --output report2
`Performance
$3
- Small project (10 deps): ~2-5 seconds
- Medium project (50 deps): ~10-20 seconds
- Large monorepo (200+ deps): ~1-3 minutes$3
- Use npm CLI mode (default) for better performance
- Analyze fewer projects simultaneously for large codebases
- Use --no-npm for quick dependency discoveryLicense
MIT
Contributing
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)---
Built with ā¤ļø for better dependency management and DevOps insights