dominian 1.0.11

Enterprise-grade code intelligence for agents - static analysis, dependency tracking, and architectural insights

Dominion 🧠

Enterprise-grade code intelligence for agents - Static analysis, dependency tracking, and architectural insights at scale.

Dominian provides comprehensive code analysis capabilities with both CLI and MCP (Model Context Protocol) interfaces, making it perfect for both human developers and AI agents.

✨ Features

🔍 Comprehensive Code Analysis

• Multi-language support: Python, JavaScript, TypeScript, Java, Go, Rust, C++
• Cross-file dependency tracking - Complete dependency graphs
• AST-based parsing with Tree-sitter support
• Real-time scanning with adaptive performance

🏗️ Architecture Intelligence

• Community detection using NetworkX and Louvain algorithms
• Cross-community analysis for architectural insights
• Circular dependency detection
• Complexity hotspots identification

🔧 Refactoring Support

• Safety analysis - Check if refactoring is safe
• Impact assessment - See what will break
• Complete dependency tracking - Direct and reverse dependencies
• Cross-language impact analysis

🤖 AI Agent Optimized

• MCP Server integration for LLM agents
• Multiple output formats: Minimal, Agent, JSON
• 85% token reduction vs verbose formats
• LLM-native outputs for maximum comprehension

⚡ Performance

• SQLite-based with WAL mode and memory mapping
• Adaptive scanning: Sequential → Multi-threaded → Multi-process
• Batch operations for 10-50x performance
• Sub-second queries on large codebases

🚀 Quick Start

Installation

Minimal Installation

pip install dominian

Full Installation (All Features)

pip install dominian[all]

Selective Installation

# Core + Community Detection
pip install dominian[community]

# Core + Enhanced Parsers
pip install dominian[tree-sitter]

# Core + File Watching
pip install dominian[watchdog]

Basic Usage

# 1. Initialize project
dominian init

# 2. Scan your codebase
dominian scan . --no-watch

# 3. Get project overview
dominian info

# 4. Search for functions/classes
dominian search "database"

# 5. Analyze dependencies
dominian deps direct MyFunction
dominian deps reverse MyClass

# 6. Check refactoring safety
dominian refactor safe MyClass

📊 Commands Overview

Project Management

dominian init              # Initialize project
dominian scan . --no-watch # Scan codebase
dominian info              # Project statistics

Search & Navigation

dominian search "pattern"          # Find nodes
dominian node get EntityName       # Get details
dominian node show EntityName       # Alias for get

Dependency Analysis

dominian deps direct EntityName    # Outgoing dependencies
dominian deps reverse EntityName   # Incoming dependencies

Architecture Analysis

dominian arch impact EntityName           # Change impact
dominian arch communities                  # Detect communities
dominian arch cross-community             # Cross-community edges

Graph Analysis

dominian graph stats          # Database statistics
dominian graph hotspots       # Complexity hotspots
dominian graph cycles         # Circular dependencies

Refactoring Support

dominian refactor safe EntityName    # Check safety
dominian refactor impact EntityName   # Show impact

File Analysis

dominian file functions path/to/file.py  # List functions
dominian file classes path/to/file.py    # List classes

🎯 Output Formats

Minimal Format (Default)

dominian node get main
# LOC dominian/main_new.py:main:440-60 1 fn c:3 q:70 deps:20 used_by:0

Agent Format

dominian node get main --format agent
# NODE: main
# ====================================
# Type: function
# File: dominian/main_new.py
# Lines: 440-601
# Quality: 70.0
# Complexity: 3

JSON Format

dominian node get main --format json
# Complete structured JSON with full metadata

🤖 MCP Server Integration

Dominian provides a full MCP (Model Context Protocol) server for AI agent integration:

# Start MCP server (stdio transport)
dominian-mcp

# Start MCP server (SSE transport)
dominian-mcp --transport sse --port 8080

MCP Features

• All CLI commands as MCP tools
• LLM-optimized minimal output
• FastMCP integration for modern agents
• Environment configurable database paths

🔧 Advanced Features

Community Detection

# Requires: pip install networkx python-louvain
dominian arch communities
# [36] [87,84,79,66,60,53,50,48,38,37,36,35,29,26,19,18,16,3,2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1] avg:22

Cross-Language Analysis

# Search across all supported languages
dominian search "DatabaseClass"
# Results from Python, Java, JavaScript, etc.

# Cross-language dependencies
dominian deps reverse DatabaseClass
# Shows dependencies from all languages

Refactoring Workflow

# 1. Check if safe to refactor
dominian refactor safe MyClass
# Output: OK SAFE MyClass or WARNING with dependents

# 2. Analyze impact
dominian refactor impact MyClass
# Output: WARN LOW 1:file.py:1

# 3. Get detailed dependencies
dominian deps reverse MyClass
# Output: Complete list of dependent files

📈 Performance & Scalability

Project Size Support

• Small projects (<100 files): Sequential scanning
• Medium projects (100-2,000 files): Multi-threaded
• Large projects (2,000+ files): Multi-process with streaming

Memory Requirements

• Minimum: 512MB RAM
• Recommended: 2GB+ RAM for large projects
• Database: SQLite with 128MB cache + 256MB memory mapping

Benchmark Results

Test Project: 18 files, 1,096 nodes, 1,826 edges
Scan Time: 3.07 seconds
Database Size: ~400KB
Query Performance: <10ms for most operations

🛠️ Development

Setup Development Environment

# Clone repository
git clone https://github.com/dominian/dominian.git
cd dominian

# Install in development mode
pip install -e .[dev]

# Run tests
pytest

# Code formatting
black dominian/
flake8 dominian/
mypy dominian/

Building for Distribution

# Build wheel and source distribution
python -m build

# Test installation
pip install dist/dominian-1.0.10-py3-none-any.whl

# Upload to PyPI (requires credentials)
python -m twine upload dist/*

📋 Requirements

System Requirements

• Python: >=3.10
• OS: Windows, Linux, macOS
• Memory: 512MB minimum, 2GB+ recommended

Core Dependencies

• mcp>=1.0.0 - MCP SDK for server functionality
• cffi>=1.12 - C Foreign Function Interface

Optional Dependencies

• networkx>=3.0, python-louvain>=0.16 - Community detection
• tree-sitter-* packages - Enhanced language parsing
• watchdog>=3.0.0 - File system monitoring

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Development Process

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📄 License

Dominian is licensed under the MIT License.

🔗 Links

• Documentation: https://dominian.readthedocs.io/
• Repository: https://github.com/dominian/dominian
• Issues: https://github.com/dominian/dominian/issues
• PyPI: https://pypi.org/project/dominian/

🆚 Comparison

Feature	Dominian	Other Tools
Multi-language	✅ 7+ languages	❌ Usually single language
Cross-file analysis	✅ Complete dependency graphs	❌ Limited cross-file
MCP Integration	✅ Native MCP server	❌ No LLM integration
Refactoring safety	✅ Complete impact analysis	❌ Basic dependency checks
Performance	✅ Sub-second queries	❌ Often slow on large projects
AI Optimized	✅ LLM-native outputs	❌ Human-focused outputs

🎯 Use Cases

For Developers

• Code review automation - Understand impact before changes
• Architecture documentation - Visualize code structure
• Dependency management - Track and reduce complexity
• Refactoring safety - Know what will break

For AI Agents

• Code understanding - Rich context for LLMs
• Automated refactoring - Safe code modifications
• Documentation generation - Automated API docs
• Code analysis - Quality and complexity metrics

For Teams

• Onboarding - Quick codebase understanding
• Knowledge sharing - Architectural insights
• Quality gates - Automated complexity checks
• Technical debt tracking - Identify hotspots

---

Dominian - Enterprise code intelligence for the modern development workflow 🚀