diagram_dart

A Dart library that analyzes Dart projects and generates diagram from source code, extracting class relationships (extends, implements, with, uses) automatically.

Features

Automatic Analysis: Walks your Dart project and extracts all class information
Relationship Detection: Detects:
- extends relationships (inheritance)
- implements relationships (interfaces)
- with relationships (mixins)
- uses relationships (detected from field types)
- on constraints for mixins
Type Support: Handles:
- Regular classes
- Abstract classes
- Interface classes
- Sealed classes
- Mixins
- Enums
- Extension types
Mermaid Output: Generates multiple formats:
- .mmd files (Mermaid diagram syntax)
- .json files (Mermaid Live Editor compatible)
- .html files (Interactive HTML with embedded Mermaid)
- .png files (Rendered diagrams via kroki.io)
Interactive Comments: Dart doc comments (///) automatically become clickable tooltips in diagrams
Customizable: Supports .parseignore file for excluding directories/files
Large Project Support: Built-in flags to reduce diagram size:
- --no-private: Exclude all private elements (classes and methods starting with _)
- --no-external: Exclude stdlib and third-party library classes
- --only-relations: Show only specific relationship types (extends, implements, with, uses, nested)

Installation

As a Library

Add to your pubspec.yaml:

dependencies:
  diagram_dart: ^0.4.0

Then run:

dart pub get

As a CLI Tool

Install globally:

dart pub global activate diagram_dart

Then use the diagram_generator command from anywhere:

diagram_generator <path> [options]

Updating the CLI Tool

To update to the latest version:

dart pub global activate diagram_dart

This command automatically upgrades to the newest version. To update to a specific version:

dart pub global activate diagram_dart 0.1.1

To check the currently installed version:

diagram_generator --version

Interactive Comments

Dart documentation comments (///) in your code automatically become interactive click handlers in generated diagrams!

How It Works

When you document your classes with Dart doc comments:

/// Abstract base class for all animals
abstract class Animal {
  void makeSound();
}

/// A concrete dog class with special abilities
class Dog extends Animal {
  @override
  void makeSound() => print('Woof!');
}

/// Repository for managing dogs
class DogRepository {
  Animal getAnimal() => Dog();
}

These comments are automatically extracted and added to your diagrams as interactive click handlers. When you click on a class in the diagram, an alert shows the documentation comment.

Supported Formats

The interactive comments appear in all output formats:

.mmd - Click handlers in Mermaid syntax: click Dog "javascript:alert('/// A concrete dog class...')"
.json - Mermaid JSON with click handlers (compatible with Mermaid Live Editor)
.html - Interactive HTML diagram with clickable classes showing comments
.png - PNG diagram (rendered cleanly without interactive handlers, but generated from documented classes)

Example Output

Your .mmd file will include:

classDiagram
  class Animal {
    <<abstract>>
  }
  class Dog
  class DogRepository

  Animal <|-- Dog : extends
  DogRepository --> Animal : uses

  click Animal "javascript:alert('/// Abstract base class for all animals')"
  click Dog "javascript:alert('/// A concrete dog class with special abilities')"
  click DogRepository "javascript:alert('/// Repository for managing dogs')"

What Gets Included

✅ Included in diagrams:

Documentation comments using /// (single line or multiple lines)
Documentation comments using /** ... */ (block comments)

❌ Not included:

Regular comments using // (these are only for code)

Tips

Document all your classes - The more detailed your comments, the more useful your diagrams!
Use Mermaid Live Editor - Copy your JSON output to mermaid.live to get an interactive viewer
Open .html files in browser - The HTML version provides the best interactive experience with clickable comments
Share diagrams - The generated PNG files are perfect for documentation and presentations

Usage

Basic Usage

import 'package:diagram_dart/diagram_dart.dart';

void main() async {
  final parser = ParseDart('path/to/your/project');
  final result = await parser.analyze();

  // Print results
  for (final classInfo in result.classes) {
    print('${classInfo.name} (${classInfo.kind})');
  }

  // Generate Mermaid diagram
  print(result.toMermaid());

  // Save to files
  await result.saveMermaidFile('diagram.mmd');
  await result.saveJsonFile('diagram.json');
}

Command Line Usage

Using the CLI Tool

# Analyze current directory (generate all formats)
diagram_generator.

# Analyze a specific project
diagram_generator~/my_dart_project

# Analyze a monorepo with multiple packages
diagram_generator. --monorepo

# Generate only Mermaid diagram
diagram_generator. --format mermaid

# Generate specific format with custom output name
diagram_generator. --format html --prefix my_architecture

# Verbose output
diagram_generator. --verbose

# Exclude private methods (reduce diagram size)
diagram_generator. --no-private

# Exclude external libraries (great for large projects)
diagram_generator. --no-external

# Combine filters for minimal diagram
diagram_generator. --no-private --no-external --format html

# Show help
diagram_generator--help

Options:

--input <path> - Path to the Dart project to analyze (default: .)
--format <format> - Output format: mermaid, json, html, png, or all (default)
--prefix <name> - Custom project name for output files (default: auto-detect from pubspec.yaml)
--output-dir <path> - Output directory path (default: mermaid_output_parse)
--monorepo - Analyze as a monorepo (finds and analyzes all packages in nested directories)
--no-private - Exclude private methods (starting with _) from diagram
--no-external - Exclude external classes (stdlib and third-party libraries) from diagram
--only-relations <types> - Show only the specified relation types (comma-separated: extends, implements, with, uses, nested)
--verbose - Show detailed analysis output
-h, --help - Show help message
-v, --version - Show version

Output Location and Naming:

By default, all output files are saved to mermaid_output_parse/ folder with this naming pattern:

mermaid_output_parse/
├── <project-name>_parse_diagram.mmd      # Mermaid syntax
├── <project-name>_parse_diagram.json     # Mermaid JSON (Live Editor compatible)
├── <project-name>_parse_diagram.html     # Interactive HTML diagram
└── <project-name>_parse_diagram.png      # Rendered PNG

The project name is automatically detected from pubspec.yaml. You can customize it with --prefix and --output-dir:

# Auto-detect from pubspec.yaml
diagram_generator. --format all

# Custom name and directory
diagram_generator. --prefix my_architecture --output-dir ./diagrams --format html

# Different output directory
diagram_generator. --output-dir ./build/diagrams

Monorepo Support:

The tool automatically scans for all packages (directories containing pubspec.yaml) and analyzes them together:

# For a monorepo with this structure:
# monorepo/
# ├── packages/
# │   ├── package_a/pubspec.yaml
# │   └── package_b/pubspec.yaml
# └── services/
#     └── shared_lib/pubspec.yaml

diagram_generator. --monorepo

This will generate a single diagram showing all classes from all packages and their relationships. Works with any nesting depth!

Using the Example Script

dart run example/main.dart

This analyzes the test fixtures and generates diagram files.

Output Examples

Class Information

ClassInfo(
  name: 'Dog',
  filePath: 'test/fixtures/dog.dart',
  kind: ClassKind.classKind,
  extendsClass: 'Animal',
  implementsList: ['Runnable'],
  withList: ['Swimmer', 'PetOwner'],
  usesList: [],
  documentation: '/// A concrete dog class that demonstrates multiple relationships',
)

Mermaid Diagram (with Interactive Comments)

classDiagram
  class Animal {
    <<abstract>>
  }
  class Dog
  class Runnable {
    <<interface>>
  }
  class Swimmer {
    <<mixin>>
  }

  Animal <|-- Dog : extends
  Runnable <|.. Dog : implements
  Swimmer <|.. Dog : with

  click Animal "javascript:alert('/// Abstract base class for animals')"
  click Dog "javascript:alert('/// A concrete dog class that demonstrates multiple relationships')"
  click Runnable "javascript:alert('/// Abstract interface for things that can run')"
  click Swimmer "javascript:alert('/// Mixin for animals that can swim')"

Click on a class name in the diagram above to see its documentation comment!

.parseignore

Create a .parseignore file in your project root to exclude directories/files:

# Example .parseignore
.dart_tool/
build/
.git/
test/vendor/**

Default exclusions:

.dart_tool/
build/
.git/
.packages
.gitignore

Project Structure

parse_mermaid_dart/
├── lib/
│   ├── parse_mermaid_dart.dart      # Public API entry point
│   └── src/
│       ├── models/
│       │   ├── class_info.dart      # ClassInfo and ClassKind
│       │   └── relationship.dart    # RelationshipKind enum
│       ├── parser/
│       │   ├── dart_parser.dart     # AST parser
│       │   └── file_walker.dart     # Filesystem walker
│       └── generator/
│           └── mermaid_generator.dart  # Mermaid diagram generation
├── test/
│   ├── parse_dart_test.dart         # Unit tests
│   └── fixtures/                    # Test case fixtures
├── example/
│   └── main.dart                    # Example usage
└── pubspec.yaml

Handling Large Projects

For large projects with many dependencies or private implementation details, use filtering flags to reduce diagram complexity:

Problem: "Maximum Text Size" Error

Large diagrams (26KB+) may exceed Mermaid's default rendering limit. This tool automatically handles up to 500KB diagrams in HTML format.

Solution: Use Filtering Flags

Option 1: Exclude All Private Elements

diagram_generator. --no-private

Removes all private classes and methods (anything starting with _) to focus on public API:

classDiagram
  class User {
    name: String
    email: String
    getName() String
    getEmail() String
  }

Option 2: Exclude External Libraries

diagram_generator. --no-external

Removes stdlib and third-party library classes (like List, Map, Equatable, etc.) to show only your project's classes:

Before: Includes 25+ external classes After: Only your internal classes (typically 3-5x smaller)

Option 3: Combine Both Filters (Recommended)

diagram_generator. --no-private --no-external --format html

For ErmesDart and similar large projects, this typically reduces diagram size by 50-80%.

Size Comparison Example

# All details
diagram_generator. --format html
# Output: ~350KB diagram

# No private methods
diagram_generator. --no-private --format html
# Output: ~300KB diagram

# No external classes
diagram_generator. --no-external --format html
# Output: ~150KB diagram

# Minimal diagram (recommended for large projects)
diagram_generator. --no-private --no-external --format html
# Output: ~50-100KB diagram

Option 4: Filter Relationship Types

# Show only class hierarchy (inheritance)
diagram_generator . --only-relations extends

# Show only interface contracts
diagram_generator . --only-relations implements,with

# Show only dependency graph
diagram_generator . --only-relations uses

# Combine with other filters
diagram_generator . --only-relations extends,implements --no-external --format html

When to Use Each Option

--no-private: When you want to document public API architecture (removes all classes/methods starting with _)
--no-external: When external dependencies clutter the diagram
--only-relations: When you want to focus on one type of relationship (e.g., only inheritance for a class hierarchy view)
All combined: For large projects, best visualization, or documentation purposes

Testing

Run tests:

dart test

All tests are green ✓

API Reference

`ParseDart`

Main entry point for analyzing projects.

class ParseDart {
  /// Initialize with project path
  ParseDart(String projectPath);

  /// Analyze the project and return results
  Future<ParseResult> analyze();
}

`ParseResult`

Result of analysis containing all classes found.

class ParseResult {
  /// All classes found in the project
  final List<ClassInfo> classes;

  /// Generate Mermaid diagram as string
  ///
  /// Options:
  /// - noPrivate: Exclude private methods (starting with _)
  /// - noExternal: Exclude external library classes
  String toMermaid({bool noPrivate = false, bool noExternal = false});

  /// Generate Mermaid JSON (Live Editor compatible)
  Map<String, dynamic> toMermaidJson({bool noPrivate = false, bool noExternal = false});

  /// Generate HTML with embedded diagram
  String toHtml({bool noPrivate = false, bool noExternal = false});

  /// Save diagram to .mmd file
  Future<void> saveMermaidFile(String outputPath,
    {bool noPrivate = false, bool noExternal = false});

  /// Save JSON to file
  Future<void> saveJsonFile(String outputPath,
    {bool noPrivate = false, bool noExternal = false});

  /// Save interactive HTML file
  Future<void> saveHtmlFile(String outputPath,
    {bool noPrivate = false, bool noExternal = false});

  /// Save diagram as PNG (requires kroki.io)
  Future<void> savePngFile(String outputPath,
    {bool noPrivate = false, bool noExternal = false});
}

`ClassInfo`

Information about a single class.

class ClassInfo {
  final String name;
  final String filePath;              // Relative to project root
  final ClassKind kind;
  final String? extendsClass;
  final List<String> implementsList;
  final List<String> withList;        // Mixins or 'on' constraints
  final List<String> usesList;        // Classes used in fields
  final String? documentation;        // Dart doc comments (///)
}

`ClassKind`

Enum representing types of classes:

classKind - Regular class
abstractClass - Abstract class
mixin - Mixin declaration
interfaceClass - Abstract interface class
sealedClass - Sealed class
enumKind - Enum
extensionType - Extension type

Limitations

Only detects relationships through field type annotations (not method parameters or return types)
Only detects uses relationships for classes defined within the project
Does not support generic type analysis in depth

Dependencies

analyzer ^6.0.0 - Dart AST parsing
glob ^2.1.2 - File pattern matching
path ^1.9.0 - Path utilities

License

MIT

Contributing

Contributions are welcome! Please ensure all tests pass and add tests for new features.

dart test

Example Output

When run on the test fixtures, generates:

Found 13 classes:
  - Animal (ClassKind.abstractClass)
  - Dog (ClassKind.classKind)
      extends: Animal
      implements: Runnable
      with: Swimmer, PetOwner
  - Circle (ClassKind.classKind)
      extends: Shape
  - Status (ClassKind.enumKind)
      implements: Comparable

Copy the JSON output to mermaid.live to visualize the diagram!

Release Notes

v0.1.1 - Large Project Support

New Features:

✨ Increased maxTextSize: HTML diagrams now support up to 500KB (10x the default limit)
🎯 --no-private flag: Exclude private methods to simplify diagrams
🔍 --no-external flag: Exclude stdlib and third-party library classes
📊 Better handling of large projects: ErmesDart and similar projects now render without errors

What's Fixed:

Fixed "maximum text size" error for diagrams larger than 50KB
Improved performance for projects with many external dependencies
Better documentation in help message

Examples:

# Minimal diagram for large projects
diagram_generator. --no-private --no-external

# Focus on public API
diagram_generator. --no-private

# Internal architecture without external noise
diagram_generator. --no-external

v0.1.0 - Initial Release

Automatic Dart project analysis
Mermaid class diagram generation
Support for multiple output formats (mmd, json, html, png)
Interactive documentation comments
Monorepo support
Customizable with .parseignore

diagram_dart

Features

Installation

As a Library

As a CLI Tool

Updating the CLI Tool

Interactive Comments

How It Works

Supported Formats

Example Output

What Gets Included

Tips

Usage

Basic Usage

Command Line Usage

Using the CLI Tool

Using the Example Script

Output Examples

Class Information

Mermaid Diagram (with Interactive Comments)

.parseignore

Project Structure

Handling Large Projects

Problem: "Maximum Text Size" Error

Solution: Use Filtering Flags

Size Comparison Example

When to Use Each Option

Testing

API Reference

ParseDart

ParseResult

ClassInfo

ClassKind

Limitations

Dependencies

License

Contributing

Example Output

Release Notes

v0.1.1 - Large Project Support

v0.1.0 - Initial Release

Libraries

diagram_dart package

`ParseDart`

`ParseResult`

`ClassInfo`

`ClassKind`