Module

debug.dependency_visualizer

Dependency visualizer for understanding build dependencies.

Generates visual representations of dependency graphs to help understand what depends on what, and the blast radius of changes.

Key Features:

  • Visualize page dependencies (templates, partials, data)
  • Show reverse dependencies (what would rebuild if X changed)
  • Generate Mermaid diagrams for documentation
  • Export to DOT format for Graphviz

Related Modules:

  • bengal.cache.dependency_tracker: Dependency tracking
  • bengal.cache.build_cache: Cached dependencies
  • bengal.analysis.knowledge_graph: Content relationships

See Also:

  • bengal/debug/base.py: Debug tool infrastructure
View source
3 Classes

Classes

DependencyNode dataclass
A node in the dependency graph.
3

A node in the dependency graph.

Attributes

Name Type Description
path str

File path of this node
node_type str

Type of node (page, template, partial, data, config)
dependencies set[str]

Files this node depends on
dependents set[str]

Files that depend on this node
metadata dict[str, Any]

Additional node metadata

Methods 3

is_leaf property
Check if node has no dependencies.
bool 
def is_leaf(self) -> bool

Check if node has no dependencies.

Returns

bool

is_root property
Check if nothing depends on this node.
bool 
def is_root(self) -> bool

Check if nothing depends on this node.

Returns

bool

short_path property
Get shortened path for display.
str 
def short_path(self) -> str

Get shortened path for display.

Returns

str

DependencyGraph dataclass
Complete dependency graph for a project. Provides methods for traversal, analysis, and visualization.
9

Complete dependency graph for a project.

Provides methods for traversal, analysis, and visualization.

Attributes

Name Type Description
nodes dict[str, DependencyNode]

All nodes in the graph
edges set[tuple[str, str]]

Edges as (from, to) tuples

Methods 8

add_node
Add or get a node.
2 DependencyNode 
def add_node(self, path: str, node_type: str = 'unknown') -> DependencyNode

Add or get a node.

Parameters 2
path str
node_type str
Returns

DependencyNode

add_edge
Add a dependency edge (from depends on to).
2 None 
def add_edge(self, from_path: str, to_path: str) -> None

Add a dependency edge (from depends on to).

Parameters 2
from_path str
to_path str
get_dependencies
Get dependencies of a node.
2 set[str] 
def get_dependencies(self, path: str, recursive: bool = False) -> set[str]

Get dependencies of a node.

Parameters 2
path str

Node path
recursive bool

Whether to get transitive dependencies
Returns

set[str] —

Set of dependency paths

get_dependents
Get what depends on a node (reverse dependencies).
2 set[str] 
def get_dependents(self, path: str, recursive: bool = False) -> set[str]

Get what depends on a node (reverse dependencies).

Parameters 2
path str

Node path
recursive bool

Whether to get transitive dependents
Returns

set[str] —

Set of dependent paths

get_blast_radius
Get the "blast radius" of changing a file. Returns all pages that would need t…
1 set[str] 
def get_blast_radius(self, path: str) -> set[str]

Get the "blast radius" of changing a file.

Returns all pages that would need to rebuild if this file changed.

Parameters 1
path str

Path to the file that would change
Returns

set[str] —

Set of page paths that would rebuild

to_mermaid
Generate Mermaid diagram of the graph.
3 str 
def to_mermaid(self, root: str | None = None, max_depth: int = 3, direction: str = 'TB') -> str

Generate Mermaid diagram of the graph.

Parameters 3
root str | None

Optional root node to start from
max_depth int

Maximum depth to traverse
direction str

Diagram direction (TB, BT, LR, RL)
Returns

str —

Mermaid diagram source code

to_dot
Generate DOT format for Graphviz.
2 str 
def to_dot(self, root: str | None = None, max_depth: int = 3) -> str

Generate DOT format for Graphviz.

Parameters 2
root str | None

Optional root node to start from
max_depth int

Maximum depth to traverse
Returns

str —

DOT format source code

format_tree
Format dependencies as ASCII tree.
2 str 
def format_tree(self, root: str, max_depth: int = 3) -> str

Format dependencies as ASCII tree.

Parameters 2
root str

Root node to start from
max_depth int

Maximum depth to show
Returns

str —

ASCII tree representation

Internal Methods 1
_get_icon
Get icon for file type.
1 str 
def _get_icon(self, path: str) -> str

Get icon for file type.

Parameters 1
path str
Returns

str

DependencyVisualizer
Debug tool for visualizing dependencies. Helps understand the dependency structure of builds and v…
8

Debug tool for visualizing dependencies.

Helps understand the dependency structure of builds and visualize the blast radius of changes.

Creation:

Direct instantiation or via DebugRegistry:
    viz = DependencyVisualizer(cache=cache)
Inherits from DebugTool

Methods 6

analyze
Analyze dependency structure.
0 DebugReport 
def analyze(self) -> DebugReport

Analyze dependency structure.

Returns

DebugReport —

DebugReport with dependency analysis

build_graph
Build dependency graph from cache.
0 DependencyGraph 
def build_graph(self) -> DependencyGraph

Build dependency graph from cache.

Returns

DependencyGraph —

DependencyGraph with all dependencies

visualize_page
Visualize dependencies for a specific page.
2 str 
def visualize_page(self, page_path: str, max_depth: int = 3) -> str

Visualize dependencies for a specific page.

Parameters 2
page_path str

Path to the page
max_depth int

Maximum depth to show
Returns

str —

ASCII tree of dependencies

get_blast_radius
Get pages that would rebuild if file changed.
1 set[str] 
def get_blast_radius(self, file_path: str) -> set[str]

Get pages that would rebuild if file changed.

Parameters 1
file_path str

Path to the file that would change
Returns

set[str] —

Set of page paths that would rebuild

export_mermaid
Export dependency graph as Mermaid diagram.
2 str 
def export_mermaid(self, output_path: Path | None = None, root: str | None = None) -> str

Export dependency graph as Mermaid diagram.

Parameters 2
output_path Path | None

Optional path to save the diagram
root str | None

Optional root node to start from
Returns

str —

Mermaid diagram source

export_dot
Export dependency graph as DOT format.
2 str 
def export_dot(self, output_path: Path | None = None, root: str | None = None) -> str

Export dependency graph as DOT format.

Parameters 2
output_path Path | None

Optional path to save the file
root str | None

Optional root node to start from
Returns

str —

DOT format source

Internal Methods 2
_classify_file
Classify file type for graph.
1 str 
def _classify_file(self, path: str) -> str

Classify file type for graph.

Parameters 1
path str
Returns

str

_generate_recommendations
Generate recommendations based on analysis.
2 list[str] 
def _generate_recommendations(self, graph: DependencyGraph, report: DebugReport) -> list[str]

Generate recommendations based on analysis.

Parameters 2
graph DependencyGraph
report DebugReport
Returns

list[str]