Metadata-Version: 2.4
Name: dot-layered-transform
Version: 0.0.6a0
Summary: A Python tool for analyzing and visualizing architectural dependencies from DOT graphs.
Author-email: J4CK VVH173 <i78901234567890@gmail.com>
Project-URL: Homepage, https://github.com/J4CKVVH173/dot-layered-transform
Project-URL: Bug Tracker, https://github.com/J4CKVVH173/dot-layered-transform/issues
Keywords: dot,graph,architecture,dependencies,visualization,analyzer
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

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

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

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

    ```bash
    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`](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 `manage.py` script to analyze the graph, detect violations, and generate a layered DOT file:

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

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

Run the `manage.py` script from the command line:

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