dot-layered-transform 0.0.8a0

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 available as a PyPI package, making it easy to install and use as a command-line interface (CLI). It 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: A robust command-line interface (python -m dot_analyzer.cli) with subcommands for various operations.
• 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 (python -m dot_analyzer.cli) that takes a raw DOT dependency graph (e.g., from cargo modules) and performs various analyses or transformations.

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 (using analyze command):
   • 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 (using transform command):
   • 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 analyze command also provides a summary of detected circular dependencies and layer violations.

Getting Started

Requirements

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

Installation

You can install the package directly from PyPI:

pip install dot-layered-transform

If you have multiple Python versions, you might use:

python3 -m pip install dot-layered-transform

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 dot-layered-transform CLI tool to analyze the graph, detect violations, and generate a layered DOT file:

# Analyze for violations and cycles
python -m dot_analyzer.cli analyze graph.dot

# Transform and generate a layered DOT file
python -m dot_analyzer.cli transform graph.dot -o layered_graph.dot

The analyze command will 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

After installing the package (pip install dot-layered-transform), you can use the CLI tool:

python -m dot_analyzer.cli --help

This will show the main commands available: transform and analyze.

Transform Command:

python -m dot_analyzer.cli transform <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.

Analyze Command:

python -m dot_analyzer.cli analyze <INPUT_DOT_FILE> [--format <FORMAT>]

• <INPUT_DOT_FILE>: Path to your original DOT file.
• --format <FORMAT> (optional): Output format for analysis results. Can be text (default) or json.

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.