dominian 1.0.13

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 (Recommended)

pip install dominian[all]

Development Installation

pip install dominian[dev]

Requirements

Core Dependencies (Automatically installed)

• mcp>=1.0.0 - Model Context Protocol support
• cffi>=1.12 - Foreign Function Interface

Optional Dependencies

• networkx>=3.0, python-louvain>=0.16 - Community detection
• tree-sitter>=0.20.0 and language parsers - Enhanced parsing
• watchdog>=3.0.0 - File watching capabilities

Quick Usage

# Initialize and scan your project
dominian init
dominian scan . --no-watch

# Get project information
dominian info

# Search for entities
dominian search GraphDatabase --format minimal

# Analyze dependencies
dominian deps direct GraphDatabase --format minimal
dominian deps reverse GraphDatabase --format minimal

# Check refactoring safety
dominian refactor safe GraphDatabase --format minimal

# Find complexity hotspots
dominian graph hotspots

📋 Complete Command Reference

Basic Commands

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

Search Commands

dominian search <entity> --format minimal    # Find entities (token-efficient)
dominian search <entity> --format agent      # Find entities (agent format)
dominian search <entity> --format json       # Find entities (full JSON)
dominian search <entity> --format text       # Find entities (verbose)

Node Analysis

dominian node get <entity> --format minimal   # Get node details
dominian node get <entity> --format agent     # Get node details (agent)
dominian node get <entity> --format json      # Get node details (full JSON)

Dependencies

dominian deps direct <entity> --format minimal    # Direct dependencies
dominian deps direct <entity> --format agent      # Direct dependencies (agent)
dominian deps reverse <entity> --format minimal   # Reverse dependencies
dominian deps reverse <entity> --format agent     # Reverse dependencies (agent)

Architecture

dominian arch impact <entity> --format minimal    # Architecture impact
dominian arch communities                           # Community detection
dominian arch cross-community                      # Cross-community analysis

Graph Analysis

dominian graph stats          # Graph statistics
dominian graph hotspots       # Complexity hotspots
dominian graph cycles         # Cycle detection

Refactoring

dominian refactor safe <entity> --format minimal    # Safety check
dominian refactor impact <entity> --format minimal  # Impact analysis

File Analysis

dominian file functions <file> --format minimal    # List functions
dominian file classes <file> --format minimal      # List classes

🎯 Output Formats

Minimal Format (Recommended for Agents)

• Token-efficient: 85% reduction vs verbose formats
• LLM-optimized: Structured for maximum comprehension
• Fast: Sub-second queries on large codebases

Agent Format

• Agent-optimized: Designed for AI agents
• Structured: Easy parsing for automated systems

JSON Format

• Complete: Full metadata and relationships
• Machine-readable: Perfect for API integration
• Detailed: All available information included

Text Format

• Human-readable: Verbose output with explanations
• Detailed: Comprehensive information with context
• Educational: Great for learning and documentation

🌐 Cross-Language Support

Dominian supports multiple programming languages:

Language	Status	Features
Python	✅ Full Support	AST parsing, imports, classes, functions
JavaScript	✅ Full Support	Functions, classes, imports, exports
TypeScript	✅ Full Support	Types, interfaces, generics
Java	✅ Full Support	Classes, methods, packages
Go	✅ Full Support	Functions, structs, packages
Rust	✅ Full Support	Functions, structs, traits
C++	✅ Full Support	Classes, functions, headers

📁 Cross-Folder Support

• Recursive scanning: Automatically scans all subdirectories
• Full path tracking: Maintains complete file paths in database
• Cross-folder relationships: Tracks dependencies across folders
• Unified search: Search across entire codebase

🔄 Automatic Change Detection

• Function deletion: Automatically detects deleted functions on rescan
• Node updates: Tracks changes in node count and relationships
• Database updates: Automatic updates without manual intervention
• Real-time sync: Database stays in sync with codebase changes

#### **Full Installation (All Features)**
```bash
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 🚀