Metadata-Version: 2.4
Name: dominian
Version: 1.0.11
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 (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* 🚀
