Metadata-Version: 2.4
Name: dominian
Version: 1.0.13
Summary: Enterprise-grade code intelligence for agents - static analysis, dependency tracking, and architectural insights
Author-email: Dominian Team <contact@dominian.dev>
Maintainer-email: Dominian Team <contact@dominian.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dominian/dominian
Project-URL: Documentation, https://dominian.readthedocs.io/
Project-URL: Repository, https://github.com/dominian/dominian.git
Project-URL: Bug Tracker, https://github.com/dominian/dominian/issues
Project-URL: Changelog, https://github.com/dominian/dominian/blob/main/CHANGELOG.md
Keywords: code-analysis,static-analysis,dependency-analysis,architecture,refactoring,code-intelligence,ast,cross-language,mcp,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: cffi>=1.12
Provides-Extra: community
Requires-Dist: networkx>=3.0; extra == "community"
Requires-Dist: python-louvain>=0.16; extra == "community"
Provides-Extra: tree-sitter
Requires-Dist: tree-sitter>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-python>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-javascript>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-typescript>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-java>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-go>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-rust>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-cpp>=0.20.0; extra == "tree-sitter"
Provides-Extra: watchdog
Requires-Dist: watchdog>=3.0.0; extra == "watchdog"
Provides-Extra: all
Requires-Dist: dominian[community,tree-sitter,watchdog]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=0.10; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# Dominion 🧠

[![PyPI version](https://badge.fury.io/py/dominian.svg)](https://badge.fury.io/py/dominian)
[![Python versions](https://img.shields.io/pypi/pyversions/dominian.svg)](https://pypi.org/project/dominian/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**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**
```bash
pip install dominian
```

#### **Full Installation (Recommended)**
```bash
pip install dominian[all]
```

#### **Development Installation**
```bash
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

```bash
# 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**
```bash
dominian init                           # Initialize Dominian project
dominian scan . --no-watch              # Scan codebase
dominian info                           # Project information
```

### **Search Commands**
```bash
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**
```bash
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**
```bash
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**
```bash
dominian arch impact <entity> --format minimal    # Architecture impact
dominian arch communities                           # Community detection
dominian arch cross-community                      # Cross-community analysis
```

### **Graph Analysis**
```bash
dominian graph stats          # Graph statistics
dominian graph hotspots       # Complexity hotspots
dominian graph cycles         # Cycle detection
```

### **Refactoring**
```bash
dominian refactor safe <entity> --format minimal    # Safety check
dominian refactor impact <entity> --format minimal  # Impact analysis
```

### **File Analysis**
```bash
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**
```bash
# Core + Community Detection
pip install dominian[community]

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

# Core + File Watching
pip install dominian[watchdog]
```

### Basic Usage

```bash
# 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**
```bash
dominian init              # Initialize project
dominian scan . --no-watch # Scan codebase
dominian info              # Project statistics
```

### **Search & Navigation**
```bash
dominian search "pattern"          # Find nodes
dominian node get EntityName       # Get details
dominian node show EntityName       # Alias for get
```

### **Dependency Analysis**
```bash
dominian deps direct EntityName    # Outgoing dependencies
dominian deps reverse EntityName   # Incoming dependencies
```

### **Architecture Analysis**
```bash
dominian arch impact EntityName           # Change impact
dominian arch communities                  # Detect communities
dominian arch cross-community             # Cross-community edges
```

### **Graph Analysis**
```bash
dominian graph stats          # Database statistics
dominian graph hotspots       # Complexity hotspots
dominian graph cycles         # Circular dependencies
```

### **Refactoring Support**
```bash
dominian refactor safe EntityName    # Check safety
dominian refactor impact EntityName   # Show impact
```

### **File Analysis**
```bash
dominian file functions path/to/file.py  # List functions
dominian file classes path/to/file.py    # List classes
```

## 🎯 Output Formats

### **Minimal Format** (Default)
```bash
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**
```bash
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**
```bash
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:

```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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](CONTRIBUTING.md) 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](LICENSE).

## 🔗 Links

- **Documentation**: [https://dominian.readthedocs.io/](https://dominian.readthedocs.io/)
- **Repository**: [https://github.com/dominian/dominian](https://github.com/dominian/dominian)
- **Issues**: [https://github.com/dominian/dominian/issues](https://github.com/dominian/dominian/issues)
- **PyPI**: [https://pypi.org/project/dominian/](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* 🚀
