Metadata-Version: 2.4
Name: dominian
Version: 1.0.10
Summary: Code intelligence for AI agents — scan codebases, query dependency graphs, detect cycles, find hotspots, analyze impact, and assess refactoring safety.
Author: Dominian Contributors
License: MIT
Project-URL: Homepage, https://github.com/yourusername/dominian
Project-URL: Documentation, https://github.com/yourusername/dominian#readme
Project-URL: Repository, https://github.com/yourusername/dominian
Project-URL: Issues, https://github.com/yourusername/dominian/issues
Project-URL: Changelog, https://github.com/yourusername/dominian/blob/main/CHANGELOG.md
Keywords: code-intelligence,dependency-graph,static-analysis,llm,ai-agent,mcp,code-analysis,circular-dependencies,impact-analysis,refactoring
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: tree-sitter
Requires-Dist: tree-sitter>=0.20.0; extra == "tree-sitter"
Requires-Dist: tree-sitter-python>=0.21.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: communities
Requires-Dist: networkx>=3.0; extra == "communities"
Requires-Dist: python-louvain>=0.16; extra == "communities"
Provides-Extra: all
Requires-Dist: mcp>=1.0.0; extra == "all"
Requires-Dist: tree-sitter>=0.20.0; extra == "all"
Requires-Dist: tree-sitter-python>=0.21.0; extra == "all"
Requires-Dist: tree-sitter-javascript>=0.20.0; extra == "all"
Requires-Dist: tree-sitter-typescript>=0.20.0; extra == "all"
Requires-Dist: tree-sitter-java>=0.20.0; extra == "all"
Requires-Dist: tree-sitter-go>=0.20.0; extra == "all"
Requires-Dist: tree-sitter-rust>=0.20.0; extra == "all"
Requires-Dist: tree-sitter-cpp>=0.20.0; extra == "all"
Requires-Dist: networkx>=3.0; extra == "all"
Requires-Dist: python-louvain>=0.16; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# Dominian

**Code Intelligence for AI Agents**

Dominian scans your codebase, builds a dependency graph in SQLite, and exposes that graph through a CLI and an MCP (Model Context Protocol) server — purpose-built for LLM agents to query code structure, dependencies, impact, and refactoring safety without reading every file.

[![PyPI version](https://img.shields.io/pypi/v/dominian.svg)](https://pypi.org/project/dominian/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

---

## Why Dominian?

When an AI agent needs to understand a codebase, it currently has two bad options:

1. **Read every file** — burns through token budgets, hits context windows, and still misses cross-file relationships.
2. **Use grep/search** — finds text matches but cannot tell you *who depends on this function* or *what breaks if I change this class*.

Dominian gives agents a third option: **query a structured graph**. One `dominian deps reverse MyClass` call tells an agent exactly who uses `MyClass`, without reading 200 files to find out.

### What It Does

- **Scans** source files in 7 languages (Python, JavaScript, TypeScript, Java, Go, Rust, C/C++)
- **Extracts** code entities: functions, classes, methods, modules, variables, imports
- **Resolves** dependency edges: imports, calls, uses, defines, inherits, implements
- **Stores** everything in a local SQLite graph database (WAL mode, fully indexed)
- **Exposes** the graph via CLI commands and MCP tools with three output formats:
  - **minimal** — ultra-compact, ~85% token reduction vs verbose (default, designed for agents)
  - **agent** — human-readable with structure and context
  - **json** — machine-parseable for programmatic use

---

## Quick Start

### Installation

```bash
# Core package (CLI + graph database)
pip install dominian

# With MCP server support
pip install dominian[mcp]

# With community detection (networkx + python-louvain)
pip install dominian[communities]

# Everything
pip install dominian[all]
```

### Initialize and Scan

```bash
# Initialize the project database
dominian init

# Scan the current directory
dominian scan . --no-watch

# Check what was found
dominian info
```

### Query the Graph

```bash
# Search for a function or class
dominian search "handle_request"

# Get details about a specific entity
dominian node get handle_request

# What does this function depend on?
dominian deps direct handle_request

# What depends on this function? (reverse deps)
dominian deps reverse handle_request

# Impact analysis — what breaks if I change this?
dominian arch impact handle_request

# Is this safe to refactor?
dominian refactor safe handle_request

# Find circular dependencies
dominian graph cycles

# Find complexity hotspots
dominian graph hotspots

# Detect code communities (requires python-louvain)
dominian arch communities

# List functions in a file
dominian file functions src/server.py
```

### MCP Server (for AI Agents)

```bash
# Start MCP server with stdio transport (default)
dominian-mcp

# Or with SSE transport for remote access
dominian-mcp --transport sse --port 8080
```

Then configure your MCP client (Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "dominian": {
      "command": "dominian-mcp",
      "args": []
    }
  }
}
```

---

## Output Formats

Dominian's output is designed with token efficiency as a first-class concern. The `minimal` format (default) uses a compact locator syntax and achieves ~85% token reduction compared to verbose output while retaining 100% of the information.

### Example: Node Lookup

**Minimal format** (default):
```
📍 src/server.py:handle_request:42-89 fn c:12 q:78.3 deps:5 used_by:3
```

**Agent format** (`--format agent`):
```
NODE: handle_request
============================================================

Type: function
File: src/server.py
Lines: 42-89
Quality: 78.3
Complexity: 12
Signature: def handle_request(req: Request, db: Database) -> Response
Docstring: Process incoming HTTP request and route to appropriate handler
```

**JSON format** (`--format json`):
```json
{
  "type": "agentgraph_result",
  "data": {
    "node": {
      "name": "handle_request",
      "type": "function",
      "file": "src/server.py",
      "line_start": 42,
      "line_end": 89,
      "complexity": 12,
      "quality": 78.3
    }
  }
}
```

### Locator Syntax

The minimal format uses a universal locator pattern:

```
folder/file:name:line(type)
```

| Component | Meaning | Example |
|-----------|---------|---------|
| `folder/file` | Relative file path (last two segments) | `src/server.py` |
| `name` | Entity name | `handle_request` |
| `line` | Start line number | `42` |
| `(type)` | Abbreviated type: `fn`, `cls`, `mod`, `var`, `imp` | `(fn)` |

Full example: `src/server.py:handle_request:42(fn)`

---

## CLI Reference

Dominian follows a strict `dominian <group> <action> [target] [options]` structure.

### Project Lifecycle

| Command | Description |
|---------|-------------|
| `dominian init [--db-path PATH]` | Initialize project and create database |
| `dominian scan [PATH] [--db-path PATH] [--no-watch]` | Scan codebase and populate database |
| `dominian info [--db-path PATH]` | Show project status and statistics |

### Search & Lookup

| Command | Description |
|---------|-------------|
| `dominian search QUERY [--format FMT]` | Search for code entities by name |
| `dominian node get ENTITY [--format FMT]` | Get details of a specific entity |
| `dominian node show ENTITY [--format FMT]` | Alias for `node get` |

### Dependency Analysis

| Command | Description |
|---------|-------------|
| `dominian deps direct ENTITY [--format FMT]` | Show direct dependencies |
| `dominian deps reverse ENTITY [--format FMT]` | Show reverse dependencies (who uses this) |

### Architecture Analysis

| Command | Description |
|---------|-------------|
| `dominian arch impact ENTITY [--format FMT]` | Analyze blast radius of a change |
| `dominian arch communities [--format FMT]` | Detect code communities (Louvain) |
| `dominian arch cross-community [--format FMT]` | Find cross-community boundary edges |

### Graph Analysis

| Command | Description |
|---------|-------------|
| `dominian graph stats [--format FMT]` | Graph statistics |
| `dominian graph hotspots [--limit N] [--format FMT]` | Complexity hotspots |
| `dominian graph cycles [--format FMT]` | Circular dependency detection |

### Refactoring Support

| Command | Description |
|---------|-------------|
| `dominian refactor safe ENTITY [--format FMT]` | Check refactoring safety |
| `dominian refactor impact ENTITY [--format FMT]` | Show refactoring impact (alias for arch impact) |

### File Analysis

| Command | Description |
|---------|-------------|
| `dominian file functions FILE [--format FMT]` | List functions in a file |
| `dominian file classes FILE [--format FMT]` | List classes in a file |

### Global Options

| Option | Description |
|--------|-------------|
| `--version` | Show version |
| `--format FORMAT` | Output format: `minimal` (default), `agent`, `json` |
| `--db-path PATH` | Custom database path (default: `.dominian/agentgraph.db`) |

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DOMINIAN_DB` | `.dominian/agentgraph.db` | Database path |
| `DOMINIAN_ROOT` | Current working directory | Project root path |

---

## MCP Tools

The MCP server exposes all CLI functionality as tools with minimal-format output. See [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) for detailed agent integration instructions.

| Tool | Description |
|------|-------------|
| `dominian_init` | Initialize project |
| `dominian_scan` | Scan codebase |
| `dominian_search` | Search entities |
| `dominian_node_get` | Get entity details |
| `dominian_deps_direct` | Direct dependencies |
| `dominian_deps_reverse` | Reverse dependencies |
| `dominian_arch_impact` | Impact analysis |
| `dominian_arch_communities` | Community detection |
| `dominian_arch_cross_community` | Cross-community edges |
| `dominian_graph_stats` | Graph statistics |
| `dominian_graph_hotspots` | Complexity hotspots |
| `dominian_graph_cycles` | Circular dependencies |
| `dominian_refactor_safe` | Refactoring safety check |
| `dominian_refactor_impact` | Refactoring impact |
| `dominian_file_functions` | Functions in a file |
| `dominian_file_classes` | Classes in a file |
| `dominian_info` | Project status |
| `dominian_nodes_by_type` | Entities by type |
| `dominian_nodes_by_quality` | Entities by quality score |
| `dominian_god_nodes` | Highly connected nodes |
| `dominian_orphans` | Unconnected nodes |
| `dominian_surprising_connections` | Cross-directory coupling |

### MCP Resources

| Resource | Description |
|----------|-------------|
| `dominian://status` | Current project status |
| `dominian://schema` | Database schema information |

### MCP Prompts

| Prompt | Description |
|--------|-------------|
| `code_review(entity)` | Generate a code review for a specific entity |
| `architecture_review()` | Full architecture review workflow |
| `refactor_plan(entity)` | Generate a refactoring plan |

---

## Language Support

| Language | Extensions | Parser | Import Resolution |
|----------|-----------|--------|-------------------|
| Python | `.py`, `.pyw`, `.pyi` | tree-sitter + regex fallback | Yes (relative + absolute) |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | tree-sitter + regex fallback | Yes (relative) |
| TypeScript | `.ts`, `.tsx` | tree-sitter + regex fallback | Yes (relative) |
| Java | `.java` | tree-sitter + regex fallback | Yes (package-based) |
| Go | `.go` | tree-sitter + regex fallback | Yes (relative) |
| Rust | `.rs` | tree-sitter + regex fallback | Yes (crate-relative) |
| C/C++ | `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | tree-sitter + regex fallback | Yes (relative includes) |

Tree-sitter is used when available; regex-based extraction serves as the universal fallback when tree-sitter grammars are not installed.

---

## Database Schema

Dominian stores everything in a single SQLite database with WAL mode for concurrent read/write performance.

### Nodes Table

| Column | Type | Description |
|--------|------|-------------|
| `id` | TEXT PK | `{file}::{name}` |
| `name` | TEXT | Entity name |
| `type` | TEXT | `function`, `method`, `class`, `module`, `variable`, `import`, `dependency` |
| `file` | TEXT | Source file path |
| `language` | TEXT | Source language |
| `line_start` | INTEGER | Start line |
| `line_end` | INTEGER | End line |
| `complexity` | INTEGER | Cyclomatic complexity score |
| `quality` | REAL | Quality score (0-100, default 100) |
| `signature` | TEXT | Function/method signature |
| `docstring` | TEXT | Documentation string |
| `metadata` | TEXT (JSON) | Additional metadata |
| `confidence` | TEXT | `EXTRACTED` or `INFERRED` |
| `provenance` | TEXT | `regex_parser` or `tree_sitter` |
| `community` | INTEGER | Community ID (after detection) |

### Edges Table

| Column | Type | Description |
|--------|------|-------------|
| `id` | TEXT PK | `{from_id}--{relationship}--{to_id}` |
| `from_node` | TEXT | Source node ID |
| `to_node` | TEXT | Target node ID |
| `relationship` | TEXT | `imports`, `depends_on`, `uses`, `calls`, `defines`, `inherits`, `implements` |
| `weight` | REAL | Edge weight (1.0-9.0) |
| `confidence` | REAL | Extraction confidence |
| `provenance` | TEXT | Parser that created this edge |

---

## How Dominian Helps Agents

### Token Efficiency

Dominian's minimal format was designed from the ground up to maximize information density per token. Instead of returning multi-line verbose output, a dependency query returns a single compact line:

```
📥 handle_request→ src/db.py:get_conn:15(fn) imports | src/utils.py:validate:8(fn) calls
```

This single line tells the agent: `handle_request` depends on `get_conn` (import relationship, in `src/db.py` at line 15, it's a function) and `validate` (call relationship, in `src/utils.py` at line 8, also a function). The agent gets file, name, line, type, and relationship in one token-efficient string.

### Impact Analysis

Before an agent modifies code, it can check the blast radius:

```bash
dominian arch impact process_payment
# Output: ⚠️ HIGH 7:order_service,invoice_gen,payment_validator,refund_handler,...
```

This immediately tells the agent: changing `process_payment` has HIGH risk and affects 7 other entities. The agent can then make informed decisions about whether to proceed, add tests, or request human review.

### Refactoring Safety

```bash
dominian refactor safe utility_function
# Output: ✅ SAFE utility_function
```

Zero dependents. The agent can modify this freely without risk of breaking anything.

### Architecture Understanding

Community detection groups code into logical modules. Cross-community edges reveal hidden coupling. An agent can use this to understand the codebase's modular structure without reading every file.

---

## Architecture

```
                    ┌─────────────┐
                    │   CLI       │  main_new.py
                    │ (argparse)  │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │   MCP       │  server.py
                    │  Server     │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐ ┌──▼───┐ ┌──────▼──────┐
       │  Formatter   │ │Engine│ │  Database   │
       │  formatter.py│ │engine│ │  database.py│
       └─────────────┘ │.py   │ └─────────────┘
                       └──┬───┘
                          │
                  ┌───────▼───────┐
                  │  Adaptive     │  adaptive_scanner.py
                  │  Scanner      │
                  └───────┬───────┘
                          │
              ┌───────────┼───────────┐
              │           │           │
     ┌────────▼──┐ ┌──────▼──────┐ ┌─▼──────────────┐
     │ Parser    │ │ Import      │ │ Tree-sitter    │
     │ Registry  │ │ Resolver    │ │ Parser + Config│
     │ __init__.py│ │import_resolv│ │ tree_sitter_*.py│
     └───────────┘ └─────────────┘ └────────────────┘
```

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed design decisions.

---

## Development

```bash
# Clone
git clone https://github.com/yourusername/dominian.git
cd dominian

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

# Run CLI
python -m dominian init
python -m dominian scan . --no-watch

# Run MCP server
python -m dominian.server
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

---

## Documentation

| Document | Description |
|----------|-------------|
| [README.md](README.md) | This file — overview and quick start |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
| [CHANGELOG.md](CHANGELOG.md) | Version history |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and design |
| [docs/API_REFERENCE.md](docs/API_REFERENCE.md) | Full API and tool reference |
| [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) | Guide for AI agent integration |
| [docs/TOKEN_USAGE.md](docs/TOKEN_USAGE.md) | Token usage analysis and optimization |

---

## License

[MIT](LICENSE)
