Code2Mermaid - Codebase Visualizer with Mermaid Diagrams

A powerful Python CLI tool that scans folders of source code files across multiple programming languages and generates beautiful Mermaid diagrams to visualize program structure, dependencies, and class hierarchies.

🚀 Features

• Multi-language support: Python, JavaScript/TypeScript, Java, C#, Go, C/C++
• Three diagram types:
  • Structure: Folder/file hierarchy flowchart
  • Dependencies: Import/dependency graph
  • Classes: Class diagram with inheritance and methods
• Smart parsing: AST-based for Python, regex-based for others
• Flexible filtering: Exclude directories and files with patterns
• Clean output: Organized Mermaid .mmd files ready for visualization

📦 Installation

1. Download the script:

   # Save code2mermaid.py to your desired location
   wget https://raw.githubusercontent.com/your-repo/code2mermaid/main/code2mermaid.py

2. Make it executable:

   chmod +x code2mermaid.py

3. Install Python dependencies:

   # No external dependencies required - uses only Python standard library!
   python3 --version  # Requires Python 3.7+

🛠️ Usage

Basic Usage

# Analyze current directory, generate all diagrams
python3 code2mermaid.py ./my-project

# Specify output directory
python3 code2mermaid.py ./my-project -o ./diagrams

# Generate only dependency diagram
python3 code2mermaid.py ./my-project --diagram deps

Advanced Usage

# Exclude test directories and generate structure only
python3 code2mermaid.py ./my-repo \
  --diagram structure \
  --exclude "tests*" \
  --exclude "*.test.*"

# Don't group files by folders
python3 code2mermaid.py ./my-repo --no-group-folders

# Limit diagram complexity
python3 code2mermaid.py ./large-repo --max-nodes 50

Command Line Options

Option	Description	Default
directory	Directory to analyze	Required
-o, --output	Output directory for .mmd files	./diagrams
--diagram	Diagram type: all, structure, deps, classes	all
--exclude	Patterns to exclude (can be used multiple times)	See defaults
--no-group-folders	Don't group files by folders in structure	False
--max-nodes	Maximum nodes per diagram	100

📊 Output Files

The tool generates up to three Mermaid diagram files:

• structure.mmd: Folder and file hierarchy
• deps.mmd: Import and dependency relationships
• classes.mmd: Class inheritance and methods

🎨 Viewing Diagrams

Option 1: Mermaid Live Editor (Recommended)

1. Go to https://mermaid.live/
2. Copy and paste the content of any .mmd file
3. View the rendered diagram instantly

Option 2: VS Code Extension

1. Install the "Mermaid Markdown Syntax Highlighting" extension
2. Open .mmd files directly in VS Code
3. Use preview to see rendered diagrams

Option 3: GitHub/GitLab

• Many platforms now support Mermaid rendering in markdown files
• Include .mmd content in markdown code blocks with mermaid language tag

🗂️ Supported Languages

Language	Extensions	Parsing Method
Python	.py	AST (full parsing)
JavaScript	.js, .jsx	Regex patterns
TypeScript	.ts, .tsx	Regex patterns
Java	.java	Regex patterns
C#	.cs	Regex patterns
Go	.go	Regex patterns
C/C++	.c, .cpp, .h, .hpp	Regex patterns

📁 Default Exclusions

The tool automatically excludes common directories and files:

• node_modules, .git, __pycache__, .pytest_cache
• venv, env, .env, dist, build, target
• *.pyc, *.pyo, *.pyd, .DS_Store, Thumbs.db

Add custom exclusions with --exclude flag.

🔧 Examples

Python Project Structure

python3 code2mermaid.py ./my-python-app --diagram structure

JavaScript Dependency Analysis

python3 code2mermaid.py ./my-react-app \
  --diagram deps \
  --exclude "node_modules" \
  --exclude "*.test.*"

Full Java Codebase Analysis

python3 code2mermaid.py ./java-project \
  -o ./documentation/diagrams \
  --exclude "target" \
  --exclude "*.class"

🎯 Use Cases

• Code Documentation: Generate visual documentation for new team members
• Architecture Review: Understand dependencies and coupling in existing codebases
• Refactoring Planning: Identify tightly coupled components before refactoring
• Code Quality: Visualize complex dependency graphs that might need simplification
• Educational: Help students understand code structure and relationships

🤝 Contributing

Found a bug or want to add support for more languages? Contributions welcome!

1. Fork the repository
2. Create a feature branch
3. Add regex patterns for new languages in RegexParser.PATTERNS
4. Test with sample codebases
5. Submit a pull request

📄 License

MIT License - feel free to use in personal and commercial projects.

🙏 Acknowledgments

• Built with Python's powerful ast module for Python parsing
• Inspired by various code visualization tools
• Mermaid.js for beautiful diagram rendering

---

Happy Coding and Visualizing! 🎨📊

For questions, issues, or feature requests, please open an issue on GitHub.