🌍 Marco Polo

A CLI Tool to Cartograph Codebases

Marco is a high-performance CLI tool written in Rust that scans your codebase and generates Mermaid.js Class Diagrams. It helps developers visualize structure, inheritance, and relationships in large projects quickly.

🚀 Features

• Fast Scanning: Uses the ignore crate to traverse directories while respecting .gitignore.
• Accurate Parsing: Leverages tree-sitter for robust AST-based code analysis.
• Advanced Relationships: Detects not just inheritance, but also:
  • Composition/Aggregation (*--, o--) from properties and __init__.
  • Dependencies (..>) from method parameters and return types.
• Visual Output: Generates .mmd files ready for Mermaid.js rendering.
• Multi-language Support:
  • Python: Full support for classes and relationships.
  • Java: Full support for classes, interfaces, and complex relationships.
  • C++: Full support for classes and relationships.
  • Ruby: Full support for classes, modules, and mixins.
  • TypeScript (Coming soon)

📊 Language Feature Support

Feature	Python	Java	C++
Visibility Tracking	✅	✅	✅
Namespace Awareness	✅	✅	✅
Relationship Labels	✅	✅	✅
Multi-level Inheritance	✅	✅	✅

🛠️ Getting Started

Prerequisites

• Rust & Cargo installed.

Installation

You can install marco-polo directly from crates.io:

cargo install marco-polo

Alternatively, you can build from source:

git clone https://github.com/wseabra/marco_polo.git
cd marco_polo
cargo install --path .

Now you can run the marco-polo command from anywhere.

Usage

marco-polo [OPTIONS] [PATH]

Arguments:

• [PATH]: Path to the codebase to scan (defaults to current directory .).

Options:

• -o, --output <FILE>: Output file path for the Mermaid diagram (default: output.mmd).
• -e, --extensions <EXT>: Comma-separated list of file extensions to scan (default: py,java,cpp,rb).
• -v, --visibility <LEVELS>: Comma-separated visibility levels to include (default: public). Options: public, protected, private, internal.
• -h, --help: Print help information.

Example:

marco-polo ./src --output diagram.mmd

📊 Example Output

Given the following Python code:

from typing import List

class Entity:
    def __init__(self, id: int):
        self.id = id

class Product:
    pass

class User(Entity):
    def __init__(self, id: int, name: str):
        super().__init__(id)
        self.name = name

class Order:
    def __init__(self, user: User):
        self.user = user  # Aggregation
        self.items: List[Product] = []

    def add_item(self, product: Product): # Dependency
        self.items.append(product)

Marco-Polo generates the following Mermaid diagram:

classDiagram
    class Entity {
        +id
    }
    class User {
        +name
    }
    class Order {
        +user
        +items
        +add_item()
    }
    Entity <|-- User
    User o-- Order : user
    Product o-- Order : items
    Product ..> Order

Loading

🤝 Contributing

We love contributions! Whether it's adding support for a new language, fixing a bug, or improving documentation, here's how you can help:

1. Fork the repository.
2. Create a branch for your feature: git checkout -b feat/my-new-feature.
3. Commit your changes using Conventional Commits: feat: add Java support.
4. Push to your branch and open a Pull Request.

Development

Run tests to ensure everything is working:

cargo test

📜 License

This project is licensed under the MIT License.