What Is Dependency Mapping?
Dependency mapping is the process of extracting, resolving, and visualizing the relationships between files, modules, packages, and services in a codebase. It produces a directed graph where nodes represent code units and edges represent dependency relationships — imports, requires, includes, and other forms of structural reference.
Why It Matters
The dependency graph is the skeleton of a software architecture. It determines what can be changed independently, what must change together, where failures cascade, and how the system decomposes into deployable units. Yet in most organizations, the dependency graph exists only as tribal knowledge — an approximate mental model maintained by engineers who have worked with the code long enough to remember which parts connect to which.
When the dependency graph is explicit and queryable, it enables every subsequent form of structural analysis: SPOF detection, blast radius calculation, dead code identification, circular dependency detection, and architectural zone classification. Without dependency mapping, these analyses are impossible.
Dependency mapping also reveals the gap between intended architecture and actual architecture. Teams often discover that service boundaries, layer separations, and module isolations they assumed were clean actually contain violations that accumulated over time without anyone noticing.
How It Works
Dependency mapping operates in three phases: extraction, resolution, and graph construction.
Extraction parses each source file using an AST parser (such as Tree-sitter) and identifies all dependency declarations — import statements, require calls, include directives, and framework-specific references. The parser must understand the specific syntax of each programming language.
Resolution converts dependency declarations into concrete file references. This requires implementing the module resolution algorithm of each language and build system: Node.js resolution, Python import resolution, Java classpath resolution, Go module resolution, and so on. Path aliases, barrel exports, and re-export chains must be followed to their ultimate targets.
Graph construction assembles the resolved dependencies into a directed graph data structure. Each file is a node with metadata (language, size, complexity). Each dependency is a directed edge with confidence level (hard import vs. soft/dynamic reference). The resulting graph is the foundation for all centrality, SPOF, and blast radius analyses.
How Axiom Refract Addresses This
- Axiom Refract performs dependency mapping across 145+ languages using Tree-sitter AST parsing with language-specific resolution algorithms
- The dependency graph is queryable via get_graph_nodes and get_graph_edges tools, supporting filtering by zone, sorting by centrality, and edge-level confidence labeling
- Dependencies are classified as hard (static imports) or soft (dynamic/runtime references) with corresponding confidence scores