dependency-mapper

name	dependency-mapper
description	Use this skill to map, analyze, or audit project dependencies. MANDATORY TRIGGERS: dependency, dependencies, package.json, requirements.txt, go.mod, pom.xml, Cargo.toml, Gemfile, circular dependency, outdated packages, dependency graph, import map, module dependencies. Also use when: looking for circular imports, checking for vulnerable packages, mapping internal module coupling, preparing for a package upgrade, analyzing bundle size contributors. Do NOT use for: full architecture review (use architecture-analyzer).
metadata	{"author":"N.V","version":"1.0"}
context	fork
agent	Explore
allowed-tools	Read, Grep, Glob, Bash

Overview

Maps both external (package) and internal (module) dependencies. Detects circular dependencies, outdated/vulnerable packages, unnecessary dependencies, and coupling hotspots. Outputs a dependency matrix and actionable recommendations.

When to Use This Skill

• Understanding what a project depends on (external packages)
• Mapping internal module coupling and import relationships
• Finding circular dependencies
• Preparing for a major upgrade or migration
• Reducing bundle size by identifying heavy/unnecessary dependencies
• Security audit of third-party packages

Workflow

Quick Version (external deps only)

1. Find manifest files: package.json, requirements.txt, go.mod, etc.
2. List all dependencies with versions
3. Flag obviously outdated or risky patterns (unpinned versions, deprecated packages)
4. Output a summary table

Full Version (external + internal)

1. Find manifests — Glob for package/dependency files across the project
2. External deps — parse all declared dependencies, dev-deps, peer-deps
3. Version analysis — identify pinning strategy, range patterns, lockfile status
4. Internal imports — Grep for import/require/use patterns across source files
5. Build dependency graph — map which modules import which
6. Detect circular deps — trace import chains for cycles
7. Coupling analysis — identify highly-coupled modules (many inbound imports)
8. Generate report — dependency matrix, graphs, and recommendations

Detection Patterns

External Dependency Checks

□ All deps pinned (exact or range)
□ Lockfile present and committed (package-lock.json, poetry.lock, etc.)
□ No deprecated packages
□ Dev dependencies separated from production
□ No duplicate packages at different versions
□ Peer dependency conflicts resolved
□ Bundle-heavy packages identified (> 100KB gzipped)

Internal Dependency Checks

□ No circular import chains
□ Clear dependency direction (higher layers → lower layers)
□ No utility modules importing from business logic
□ Shared modules identified (used by 3+ other modules)
□ Orphan modules identified (exported but never imported)
□ Coupling hotspots flagged (modules with > 10 dependents)

Critical Rules

• Check ALL manifest files — monorepos may have many
• Distinguish prod vs dev deps — different risk profiles
• Map direction — A → B means A depends on B, not the reverse
• Show the cycle — for circular deps, show the full chain: A → B → C → A
• NEVER install or update packages — read-only analysis only

Output Format

# Dependency Report: [Project Name]

## External Dependencies Summary
| Category | Count | Pinned | Unpinned |
|----------|-------|--------|----------|
| Production | X | Y | Z |
| Development | X | Y | Z |

## Dependency Graph (Internal Modules)
\`\`\`mermaid
graph TD
    api --> services
    services --> models
    services --> utils
    models --> database
    utils --> config
\`\`\`

## Circular Dependencies
- ⛔ `moduleA → moduleB → moduleC → moduleA`

## Coupling Hotspots
| Module | Inbound Imports | Risk |
|--------|----------------|------|
| utils/ | 14 | High — changes here ripple across the project |

## Recommendations
1. **[Action]** — [reason and impact]