depmole 🐾

Dig deep. Detect dependency issues.

depmole is a developer-friendly CLI tool that scans, analyzes, filters, and verifies your npm dependencies — ensuring your package.json, imports, and node_modules stay perfectly aligned.

✨ Features

• Detect unused dependencies (declared but not used)
• Detect missing dependencies (imported but not declared)
• Detect declared but not installed packages
• Filter by dependency type (dependencies, devDependencies, peerDependencies)
• Flat grouping mode by dependency type
• Scoped verification against the npm registry
• Reads directly from package.json (source of truth)
• Powered by intelligent static analysis via depcheck

📦 Installation

Install globally:

npm install -g depmole

After installing globally, you can use either:

depmole

or the short alias:

dm

Or run without installing using npx:

npx depmole

🚀 Usage

Run inside your project root:

depmole

Short alias:

dm

Using npx:

npx depmole

⚙️ Options

| Flag | Description | | ---------------- | ---------------------------------------------------------- | | --verify | Verify dependencies against the npm registry | | --all | Include all dependencies (default behavior) | | --dev | Only analyze devDependencies | | --peer | Only analyze peerDependencies | | --prod | Only analyze regular dependencies | | --healthy | Show only healthy dependencies (used + installed) | | --unused | Show only unused dependencies | | --notinstalled | Show declared but missing in node_modules | | --missing | Show only missing dependencies (imported but not declared) | | --flat | Group dependencies by type |

🔎 Scoped Verification

Verification respects your selected scope.

Examples:

depmole --unused --verify

→ Verifies only unused dependencies.

depmole --healthy --verify

→ Verifies only healthy dependencies.

depmole --missing --verify

→ Verifies only missing dependencies.

depmole --dev --verify

→ Verifies only devDependencies.

📊 Flat Mode

Group dependencies by type:

depmole --flat

Output example:

dependencies:
  - react
  - express

devDependencies:
  - typescript
  - jest

peerDependencies:
  - react-dom

You can also verify within flat mode:

depmole --flat --verify

⚠️ Flat Mode Rules

--flat can only be used with:

• --verify
• --all
• --dev
• --peer
• --prod

It cannot be combined with:

• --healthy
• --unused
• --notinstalled
• --missing

This ensures consistent reporting logic.

📋 Example (Default Run)

depmole

Example output:

Healthy dependencies:
  - react
  - express

Unused dependencies:
  - lodash

Declared but missing in node_modules:
  - chalk

Missing dependencies (imported but not declared):
  - axios

🧠 How It Works

depmole follows a structured dependency model:

• 1️⃣ Reads declared dependencies from package.json
• 2️⃣ Checks installation status in node_modules
• 3️⃣ Analyzes real usage via depcheck
• 4️⃣ Applies scoped filters based on CLI flags
• 5️⃣ Optionally verifies against the npm registry
• 6️⃣ Generates a structured report

Responsibility Model

| Source | Responsibility | | -------------- | ---------------------- | | package.json | Declared dependencies | | node_modules | Installed dependencies | | depcheck | Usage detection | | npm registry | Existence validation |

This ensures depmole builds a full dependency state model, not just a simple mismatch check.

🧭 Workflow Diagram

         ┌──────────────────  ┐
         │  Read package.json │
         └──────────┬─────────┘
                    │
                    ▼
         ┌──────────────────   ┐
         │  Check node_modules │
         └──────────┬───────── ┘
                    │
                    ▼
         ┌──────────────────  ┐
         │ Analyze Imports    │
         │    (depcheck)      │
         └──────────┬─────────┘
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
   Healthy       Unused     Not Installed
 Dependencies   Dependencies Dependencies
                    │
                    ▼
              Missing Imports
                    │
                    ▼
         ┌──────────────────  ┐
         │  Scoped Verify     │
         │  (npm registry)    │
         └──────────┬─────────┘
                    ▼
               Structured Report

🎯 Use Cases

• Clean up bloated package.json files
• Catch missing dependencies before deployment
• Ensure CI pipelines fail on inconsistencies
• Audit third-party packages quickly
• Improve project hygiene and maintainability

🐾 Why depmole?

Unlike simple dependency checkers, depmole:

• Treats package.json as the source of truth
• Separates declared, installed, and used states
• Supports scoped analysis
• Supports type-based filtering
• Enforces consistent flag combinations
• Can validate against the live npm registry

It’s not just a checker — it’s a dependency investigator.

📄 License

MIT License – see LICENSE