dot-layered-transform 0.0.8a0
A Python tool for analyzing and visualizing architectural dependencies from DOT graphs.
Requires Python: >=3.10
Keywords: dot, graph, architecture, dependencies, visualization, analyzer

# 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:

```bash
pip install dot-layered-transform
```

If you have multiple Python versions, you might use:

```bash
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`](https://github.com/regexident/cargo-modules) to generate a DOT file from a Rust project:

```bash
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:

```bash
# 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:

```bash
dot -Tpng layered_graph.dot -o layered_graph.png
```

### Visual Comparison

#### Before Transformation

![Before Transformation](./example/before_transformation.png)

#### After Transformation

![After Transformation](./example/after_transformation.png)

### Command Line Usage

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

```bash
python -m dot_analyzer.cli --help
```

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

**Transform Command:**

```bash
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:**

```bash
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.