depdoctor

Production-grade dependency and code health CLI for Node.js & TypeScript projects.

What it does

depdoctor scans your project and finds:

• Unused dependencies — packages listed in package.json but never imported
• Unused imports — specifiers imported but never referenced in code
• Unused variables — declared but never used
• Circular dependencies — import chains that loop back on themselves
• Duplicate packages — same package installed with multiple versions in the lock file
• Vulnerabilities — via npm audit integration
• Dangerous scripts — curl | bash patterns in postinstall
• Typosquatting — suspicious package names that mimic popular packages
• Bad .env variables — duplicates and invalid naming

Install

npm install -g depdoctor

Usage

Scan your project

depdoctor scan

depdoctor — dependency & code health report
════════════════════════════════════════════
Scanned: 312 file(s) in 420ms

Unused Dependencies (3)
  ⚠ lodash   — not imported anywhere
  ⚠ moment   — not imported anywhere

Circular Dependencies (1)
  ⚠ src/auth/token.ts → src/user/session.ts → (back to start)

Duplicate Packages (2)
  ⚠ semver   6.3.1, 7.5.0
  ⚠ chalk    4.1.2, 5.3.0

Security Issues (1)
  ❌ express  critical — Prototype Pollution

Fix issues (dry run first)

depdoctor fix --dry-run   # preview
depdoctor fix             # apply with confirmation
depdoctor fix --yes       # skip prompt

Check for outdated dependencies

depdoctor outdated

Outdated Dependencies (3)
  lodash   3.10.1   3.10.1   4.17.21   major
  axios    1.4.0    1.6.0    1.6.0     minor
  chalk    5.3.0    5.3.0    5.3.1     patch

Check license compliance

# Flag anything that isn't MIT or Apache-2.0
depdoctor licenses --allow MIT,Apache-2.0

# Flag GPL packages as errors
depdoctor licenses --deny GPL-3.0,GPL-2.0

Security audit only

depdoctor security

Generate a report

depdoctor report --markdown    # writes .depdoctor-report.md
depdoctor report --json        # stdout JSON
depdoctor report --pdf         # writes .depdoctor-report.pdf

JSON output (for CI)

depdoctor scan --json
depdoctor outdated --json
depdoctor licenses --allow MIT --json

Rollback last fix

depdoctor rollback

Commands

| Command | Description | |---------|-------------| | scan | Full project scan — deps, imports, variables, circular deps, duplicates, security | | fix | Auto-fix unused imports and uninstall unused dependencies | | outdated | Check for newer versions of installed dependencies | | licenses | Audit dependency licenses for compliance | | security | Standalone security audit (npm audit + script analysis) | | report | Generate a full report (terminal / JSON / Markdown / PDF) | | rollback | Restore files from the last backup created by fix |

Options

| Command | Flag | Description | |---------|------|-------------| | scan | --json | Output as JSON | | scan | --no-security | Skip security checks | | scan | --pdf | Generate PDF report | | fix | --dry-run | Preview without modifying | | fix | --yes | Skip confirmation prompt | | outdated | --json | Output as JSON | | licenses | --allow <list> | Comma-separated allowed licenses | | licenses | --deny <list> | Comma-separated denied licenses | | licenses | --json | Output as JSON | | report | --markdown | Write .depdoctor-report.md | | report | --json | Write JSON report | | report | --pdf | Write PDF report | | report | --output <file> | Custom output path | | security | --json | Output as JSON | | All | --cwd <path> | Project root (default: cwd) | | All | --debug | Enable debug logging |

Configuration

Create .depdoctorrc in your project root:

{
  "ignoreDependencies": ["react", "react-dom"],
  "ignoreVariables": ["_temp"],
  "allowedLicenses": ["MIT", "Apache-2.0", "ISC", "BSD-3-Clause"],
  "deniedLicenses": ["GPL-3.0", "AGPL-3.0"],
  "security": true,
  "fix": false,
  "maxFileSizeMB": 10
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | ignoreDependencies | string[] | [] | Packages to skip in dep check | | ignoreVariables | string[] | [] | Variable names to skip | | ignoreFiles | string[] | [] | File glob patterns to skip | | allowedLicenses | string[] | [] | Allowed licenses for licenses command (empty = allow all) | | deniedLicenses | string[] | [] | Denied licenses for licenses command | | security | boolean | true | Enable security checks | | fix | boolean | false | Auto-fix on scan | | maxFileSizeMB | number | 10 | Max file size to parse | | maxFiles | number | 10000 | Max files to scan | | maxDepth | number | 20 | Max directory recursion depth | | includeDevDependencies | boolean | true | Check devDependencies too | | reportFormat | string | "terminal" | Default report format |

CI Integration

depdoctor scan exits with code 1 when critical or high-severity issues are found — drop it straight into any CI pipeline:

# GitHub Actions example
- name: Run depdoctor
  run: npx depdoctor scan --no-security

- name: Check outdated deps
  run: npx depdoctor outdated --json

Security Architecture

• No code execution — only static analysis, never require(userFile)
• Path traversal protection — all file operations validated within project root
• Symlink protection — symbolic links are skipped
• DOS limits — max file count, file size, and recursion depth enforced

Requirements

• Node.js >= 18
• npm (for security and outdated commands)

License

MIT