Easy Dependency Mapper

The Easy Dependency Mapper command analyzes project dependencies at both the code level and the task level, producing a comprehensive map of relationships between modules, packages, and work items. It identifies circular dependencies, calculates critical paths, and recommends optimal task ordering for parallel execution. Run this command when you need to understand how components depend on each other or when planning the execution order of interdependent development tasks.

When to Use This Command

Run this command when...

• You need to visualize the dependency graph between modules, packages, or components in your codebase to understand coupling
• You are planning sprint work and need to determine which tasks block others so they can be scheduled in the correct order
• You suspect circular dependencies exist between modules and need to identify and break the cycles
• You want to calculate the critical path through a set of interdependent tasks to estimate minimum completion time
• You are restructuring a codebase and need to understand which modules are most heavily depended upon before modifying them

Consider alternatives when...

• You need to analyze npm package vulnerabilities rather than code-level dependencies, which package audit tools handle
• Your task dependencies are simple enough to manage with a manual checklist without automated analysis
• You are working on an isolated module with no significant external dependencies

Quick Start

Copy
# dependency-mapper.yml
analysis:
  code-dependencies: true
  task-dependencies: true
  circular-detection: true
  critical-path: true
sources:
  code: "src/**/*.{ts,js,svelte}"
  tasks: "linear"
output:
  format: "graph"
  export: "dependency-map.json"

Example invocation:

Copy
/easy-dependency-mapper --scope src/lib --detect-circular --critical-path

Example output:

Dependency Analysis Report
============================
Scope: src/lib/
Files analyzed: 67
Modules identified: 23

Dependency graph:
  Total edges: 89
  Max depth: 6
  Most depended upon: src/lib/utils/api.ts (14 dependents)

Circular dependencies: 2 detected
  1. auth/session.ts -> user/profile.ts -> auth/session.ts
     Recommendation: Extract shared types to common/types.ts
  2. store/cart.ts -> store/products.ts -> store/cart.ts
     Recommendation: Merge into single store or use events

Critical path (task ordering):
  1. Database schema migration (no dependencies)
  2. API endpoint implementation (depends on #1)
  3. Store creation (depends on #2)
  4. Component development (depends on #3)
  5. Integration tests (depends on #3, #4)

Estimated minimum time: 14 story points (sequential bottleneck)
Parallelizable tasks: #1 can run with documentation, #4 partial overlap with #3

Core Concepts

Concept	Purpose	Details
Import Graph Analysis	Map code relationships	Traces import and require statements to build a directed graph of module dependencies
Circular Detection	Find problematic cycles	Identifies dependency loops where Module A depends on Module B which depends back on Module A, creating fragile coupling
Critical Path Calculation	Optimize task scheduling	Determines the longest chain of dependent tasks that defines the minimum project duration
Coupling Metrics	Quantify dependency health	Measures afferent and efferent coupling for each module to identify overly dependent or overly depended-upon code
Topological Sorting	Order tasks correctly	Produces a valid execution order that respects all dependency constraints for parallel-safe task scheduling

Architecture: Dependency Mapper
=================================

+-------------------+     +---------------------+     +------------------+
| Import Scanner    | --> | Graph Builder       | --> | Cycle Detector   |
| (AST parsing)     |     | (directed edges)    |     | (DFS traversal)  |
+-------------------+     +---------------------+     +------------------+
                                                             |
                          +----------------------------------+
                          v
              +---------------------+     +-------------------+
              | Critical Path Calc  | --> | Report Generator  |
              | (topological sort)  |     | (graph + metrics) |
              +---------------------+     +-------------------+

Configuration

Parameter	Type	Default	Description
scope	string	"src"	Directory or file pattern to analyze for code dependencies
detect-circular	boolean	true	Enable detection and reporting of circular dependency chains
critical-path	boolean	false	Calculate the critical path through task dependencies for scheduling optimization
depth	number	10	Maximum depth to traverse in the dependency graph before stopping
export	string	""	File path to export the dependency graph data in JSON format for visualization tools

Best Practices

1. Break circular dependencies as soon as they are detected. Circular dependencies create fragile coupling where changing one module requires simultaneous changes in its dependency partner. Extract the shared contract into a separate module that both can depend on independently, converting the circular relationship into a hierarchy.

2. Focus refactoring efforts on highly-coupled modules. Modules with many dependents represent risk concentration points where a single change cascades across the codebase. Prioritize stabilizing the interface of highly-depended-upon modules and consider extracting them into well-defined, versioned abstractions.

3. Use critical path analysis to parallelize sprint work. Identify which tasks are on the critical path and which can proceed in parallel without waiting for predecessors. Assign critical path tasks to your most reliable developers while scheduling independent tasks for parallel execution to minimize total sprint duration.

4. Regenerate the dependency map after major refactoring. Architectural changes alter the dependency graph significantly. Run the mapper after refactoring to verify that coupling metrics improved, circular dependencies were eliminated, and no new problematic patterns were introduced.

5. Export dependency graphs for team review. The JSON export format can be imported into visualization tools that render interactive dependency diagrams. Share these visualizations during architecture reviews so that the entire team can see and discuss the structure of the codebase.

Common Issues

Analysis produces an overwhelming number of edges for large codebases. Projects with hundreds of modules can produce dependency graphs that are difficult to interpret. Use the scope parameter to limit analysis to specific subsystems and increase the depth limit only when investigating specific dependency chains.

Dynamic imports are not detected by static analysis. The mapper traces static import statements in the AST, but dynamic imports using import() expressions with variable paths cannot be resolved statically. Add comments or annotations for critical dynamic dependencies that the static analyzer misses.

Task dependency data requires manual annotation. While code dependencies can be extracted automatically from import statements, task-level dependencies often require manual annotation in your project management tool. Ensure that tasks in Linear or GitHub have explicit blocking relationships defined before running critical path analysis.