dot-layered-transform 0.0.6a0

A Python tool for analyzing and visualizing architectural dependencies from DOT graphs.

Architectural Dependency Analyzer and Visualizer

Overview

This project provides a comprehensive toolset for analyzing and visualizing architectural dependencies within software projects, particularly those structured around Clean Architecture or layered design principles. It processes DOT-formatted dependency graphs, performs various analyses, and generates enhanced, visually intuitive DOT diagrams.

The tool is specifically designed to work with DOT files generated by Rust's cargo modules tool, but its core functionality can be adapted to any DOT-formatted graph representing module dependencies.

Key Features

• CLI-driven Analysis: Easily specify an input DOT file via the command line.
• Dependency Graph Parsing: Converts raw DOT file content into a structured Graph object for programmatic analysis.
• Circular Dependency Detection: Identifies and reports cyclic dependencies within the module graph, helping to pinpoint potential architectural issues.
• Layer Violation Detection: Verifies adherence to predefined architectural layer rules (e.g., domain should not depend on application or infrastructure, application can only depend on domain, infrastructure can only depend on application). It outputs a clear list of any detected violations.
• Layered DOT Diagram Generation: Transforms the input graph into a new DOT file that visually groups modules by their architectural layers (domain, application, infrastructure) using DOT's subgraph cluster syntax, and introduces explicit layer nodes (e.g., my_app::domain) with 'owns' relationships to their respective modules.
• Enhanced Visualization:
  • Color-coded Layers: Layers are visually distinguished with distinct background colors for improved readability, and explicit layer nodes are introduced.
  • Color-coded Edges: Dependency types (owns, uses) are represented with different edge colors, making relationships clearer.
  • Simplified Visuals: Unnecessary edges are filtered out to reduce clutter and highlight meaningful connections, ensuring the generated diagrams are clean and easy to understand.
• Extensible Design: The project is built with extensibility in mind, allowing for future additions of new analysis types, visualization options, and integration with other dependency generation tools.

Project Idea and Workflow

The core idea is to provide a robust command-line interface (manage.py) that takes a raw DOT dependency graph (e.g., from cargo modules) and transforms it into an insightful architectural overview.

Here's the typical workflow:

1. Input: Provide a DOT file representing your project's module dependencies (e.g., graph.dot).
2. Parsing: The tool parses this DOT file into an internal graph representation.
3. Analysis:
   • It checks for circular dependencies within your modules.
   • It identifies violations of architectural layer rules, ensuring your domain, application, and infrastructure layers adhere to their intended dependency flow.
4. Transformation & Visualization:
   • A new DOT file is generated. In this new file, modules are visually grouped into distinct layers using colored subgraphs, and explicit layer nodes are created with 'owns' relationships to their modules.
   • Edges are color-coded based on their type (owns or uses) and filtered to show only the most relevant connections, reducing visual noise.
5. Output: The generated DOT file (e.g., layered_graph.dot) can then be rendered into an image (e.g., PNG, SVG) using Graphviz tools (e.g., dot -Tpng layered_graph.dot -o output.png). The tool also provides a summary of detected circular dependencies and layer violations.

Getting Started

Requirements

• Python 3.10+ (compatible with 3.11)
• Graphviz (for rendering DOT files into images)

Installation

1. Clone the repository:

   git clone https://github.com/your-repo/dot-layered-transform.git
   cd dot-layered-transform
   

2. Install development dependencies (optional, for contributors):

   pip install -r requirements.txt
   

   Note: The core functionality of the manage.py script does not require any external Python dependencies beyond the standard library. The requirements.txt file is primarily for development and testing purposes.

Usage Example

Here’s a real-world example of how this tool can be used in a project.

1. Generate the initial DOT diagram

I used cargo-modules to generate a DOT file from a Rust project:

cargo modules dependencies --package <PACKAGE-NAME> --bin <PACKAGE-NAME>  --no-externs --no-sysroot --no-fns --no-traits --no-types  --layout dot > graph.dot

2. Transform the DOT file and analyze

Use the manage.py script to analyze the graph, detect violations, and generate a layered DOT file:

python manage.py graph.dot -o layered_graph.dot

This command will also print any detected circular dependencies or layer violations to the console.

3. Render the transformed DOT file

Using the Graphviz dot utility, you can generate an image for visualization:

dot -Tpng layered_graph.dot -o layered_graph.png

Visual Comparison

Before Transformation

After Transformation

Command Line Usage

Run the manage.py script from the command line:

python manage.py <INPUT_DOT_FILE> [-o <OUTPUT_DOT_FILE>]

• <INPUT_DOT_FILE>: Path to your original DOT file (e.g., example/graph.dot).
• -o <OUTPUT_DOT_FILE> (optional): Path where the transformed, layered DOT file will be saved. If omitted, the output will be printed to standard output.

Development and Contribution

This project is designed to be extensible. Future enhancements may include:

• Support for more complex layer definitions and custom rules.
• Integration with other dependency analysis tools.
• Interactive visualization features.
• More detailed reporting options.

Contributions are welcome! Please refer to the CONTRIBUTING.md (if available) for guidelines.

---

Acknowledgements

Special thanks to the developers of cargo modules for providing a powerful tool for Rust dependency graph generation.