Metadata-Version: 2.4
Name: codebrain
Version: 0.3.0
Summary: Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required.
Author: CodeBrain Contributors
License: MIT License
        
        Copyright (c) 2026 CodeBrain Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/monk0062006/CodeBrain
Project-URL: Repository, https://github.com/monk0062006/CodeBrain
Project-URL: Issues, https://github.com/monk0062006/CodeBrain/issues
Keywords: code-analysis,static-analysis,knowledge-graph,impact-analysis,dead-code,codebase-health,mcp,ai-coding,structural-analysis,refactoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: watchdog>=3.0
Requires-Dist: mcp<1.20,>=1.0
Requires-Dist: jinja2>=3.1
Requires-Dist: psutil>=5.9
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn>=0.27; extra == "api"
Provides-Extra: llm
Requires-Dist: httpx>=0.27; extra == "llm"
Provides-Extra: ts
Requires-Dist: tree-sitter>=0.21; extra == "ts"
Requires-Dist: tree-sitter-languages>=1.10; extra == "ts"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-tmp-files>=0.0.2; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Provides-Extra: all
Requires-Dist: codebrain[api,llm,ts]; extra == "all"
Dynamic: license-file

# CodeBrain

**Know what breaks before you break it.**

CodeBrain builds a structural knowledge graph of your codebase — every function, class, import, and call chain — stored locally in SQLite. No cloud. No LLM required. Just deterministic structural analysis.

```bash
pip install codebrain
cd your-project
brain init
```

You'll immediately see:

```
Indexing my-project (93 files) ...
Done in 1.2s — 1861 nodes, 8837 edges

=== Instant Findings ===
Health: 60/100 (B)
Riskiest symbols: Flask (34 files), App (35 files), Scaffold (28 files)
Dead code: 11 candidates (none high-confidence)
```

Then explore:

```bash
brain impact my_function    # What breaks if I change this?
brain callers my_function   # Who calls this?
brain health                # Codebase health score (0-100)
brain hotspots              # Riskiest symbols in the codebase
brain deadcode              # Unused functions with confidence levels
brain zoom                  # Google Maps-style navigation of your architecture
```

## Why CodeBrain?

AI coding agents (Claude Code, Cursor, Copilot) generate code faster than you can review it. They apply local fixes without understanding global structure. When an agent removes a function, it doesn't know 3 other files call it.

CodeBrain knows. It maintains a persistent knowledge graph of every symbol and relationship in your codebase, and can tell you exactly what would break before any change is made.

**No API keys. No cloud. No LLM. Everything runs locally on your machine.**

## Features

### Impact Analysis

```
$ brain impact getAstroData
Impact of changing predictions_api.py::getAstroData:
  [1] Ascendant.py::compileAstroDetails  (CALLS)
  [1] AsthaKoota.py::getNakAndRasi  (CALLS)
  [2] ProfileBuilder.py::buildProfile  (CALLS via compileAstroDetails)
  ... 48 dependents across 69 files
```

### Health Score

```
$ brain health
Codebase Health
  Score: 93/100 (A)
  [##################--]
  Dead code:     517 symbols (4.2%)  score 79/100
  Import cycles: 0                   score 100/100
  Coupling:      3 hotspot(s)        score 94/100
```

### Risk Hotspots

```
$ brain hotspots
Risk hotspots (top 5):
  Score  Type       Name                            Deps  Files
   48.2  function   getAstroData                      48     69
   35.1  function   compileAstroDetails               35     52
   28.7  class      ProfileBuilder                    28     41
```

### Dead Code Detection

Finds unused symbols with confidence levels:
- **High** — truly unreferenced, safe to delete
- **Medium** — file uses dynamic patterns (callbacks, registries)
- **Low** — might be used via reflection or external entry points

### Implicit Contracts

```
$ brain contracts
Implicit contracts (12):
  [co_import       ] (100%) 'Colors' and 'Spacing' are imported together in 141/141 files
  [co_import       ] (98%)  'Spacing' and 'react-native' are imported together in 138/141 files
```

### Module Coupling

```
$ brain coupling
Most coupled file pairs:
  140  logger.py  <->  main.py
  101  ForeignSettlementProfile.py  <->  ForeignSettlementProfiling.py
```

### Architectural Layers

```
$ brain layers
Layer 0 — foundation (deepest dependencies)
    utils/logger.py
    utils/constants.py
Layer 1 — core
    core/engine.py
    core/models.py
```

### Multi-Resolution Zoom

Navigate your codebase like Google Maps — zoom from system level to package to file to symbol:

```
$ brain zoom
System: 1328 files, 17756 symbols across 5 packages
Backbone: debug_astrodata.py, debug_dasha_data.py, debug_house_data.py

$ brain zoom backend
Package: backend (978 files, 14794 symbols)
Top modules: ProfileAPI/main.py (429 symbols), test_subscription_tiers.py (210 symbols)

$ brain zoom backend/vedic-profiles/ProfileAPI/main.py
Module: main.py — 429 symbols, 15853 lines. Isolated (no dependents).
```

## AI Agent Integration

### Claude Code (MCP)

```bash
brain setup    # auto-generates CLAUDE.md + MCP config
```

Or add manually to your MCP config:

```json
{
  "mcpServers": {
    "codebrain": {
      "command": "python",
      "args": ["-m", "codebrain.mcp_server"],
      "cwd": "/path/to/your/repo"
    }
  }
}
```

22 MCP tools available including:

| Tool | Purpose |
|------|---------|
| `propose_change` | Validate before writing — the structural safety gate |
| `impact_analysis` | Trace transitive dependents of any symbol |
| `ask_codebase` | Natural language questions about the codebase |
| `validate_change` | Check if a file change would break callers |
| `risk_hotspots` | Find structurally dangerous symbols |
| `find_dead_code` | Unused symbols with confidence levels |
| `codebase_overview` | System-level architecture summary |

### Structural Safety Gate

The `propose_change` MCP tool validates changes **before** the AI writes them. When a change would remove a function that other files call, or change a signature that callers depend on, CodeBrain blocks it and tells the agent exactly what would break.

## All CLI Commands

| Command | Description |
|---------|-------------|
| `brain init` | Index the current repository |
| `brain status` | Show index statistics |
| `brain search <query>` | Find symbols by name |
| `brain impact <name>` | What breaks if this changes? |
| `brain callers <name>` | Who calls this function? (reverse trace) |
| `brain trace <name>` | Forward call chain from a symbol |
| `brain deps <name>` | Dependencies of a symbol or file |
| `brain deadcode` | Find unused functions/classes |
| `brain cycles` | Detect import cycles |
| `brain health` | Codebase health score (0-100) |
| `brain hotspots` | Riskiest symbols by structural exposure |
| `brain coupling` | Module coupling analysis |
| `brain contracts` | Implicit contract detection |
| `brain layers` | Architectural layer inference |
| `brain zoom [target]` | Multi-resolution navigation |
| `brain overview` | System-level codebase overview |
| `brain module <file>` | Module-level view |
| `brain context <name>` | LLM-optimized symbol context |
| `brain validate <file>` | Check if a file change is safe |
| `brain ci --base main` | CI validation for pull requests |
| `brain watch` | File watcher daemon (re-index on save) |
| `brain hook install` | Install pre-commit validation hook |
| `brain reindex` | Force a full rebuild |
| `brain doctor` | Diagnostic health check |
| `brain serve` | Start REST API server |

All commands support `--json` for machine-readable output, `--repo <path>` for different repos, `--timeout N` for analysis timeout (default: 120s), and `--verbose` for debug logging.

## Configuration

Create `.codebrain.toml` in your repo root (optional):

```toml
[codebrain]
skip_dirs = ["__pycache__", ".git", "node_modules", "vendor"]
extensions = [".py", ".ts", ".tsx", ".js", ".jsx"]
max_file_size_kb = 1024
cli_timeout = 120
```

Or use environment variables:

| Variable | Description |
|----------|-------------|
| `CODEBRAIN_SKIP_DIRS` | Comma-separated directories to skip |
| `CODEBRAIN_EXTENSIONS` | Comma-separated file extensions to index |
| `CODEBRAIN_CLI_TIMEOUT` | Analysis timeout in seconds (default: 120) |
| `CODEBRAIN_MAX_WORKERS` | Max parallel worker processes |

## Language Support

| Language | Parser | Quality |
|----------|--------|---------|
| Python | AST (stdlib) | Full — functions, classes, imports, calls, dataflow |
| TypeScript/JSX | tree-sitter | Full — requires `pip install codebrain[ts]` |
| JavaScript/JSX | tree-sitter | Full — requires `pip install codebrain[ts]` |
| Java | tree-sitter | Full — Spring Boot aware (DI, endpoints, JPA) |
| Go | tree-sitter | Full — interfaces, goroutines, struct methods |
| Rust | tree-sitter | Full — traits, impls, modules, derive macros |
| C# | tree-sitter | Full — async/await, LINQ, attributes |
| Kotlin | tree-sitter | Full — coroutines, extensions, data classes |
| Dart/Flutter | regex | Good — classes, mixins, extensions |
| Vue SFC | regex | Good — components, props, events |

### Adding Languages

Implement `BaseParser` and register via entry points:

```python
from codebrain.parser.base import BaseParser
from codebrain.parser.models import ParsedFile

class MyParser(BaseParser):
    def extensions(self) -> frozenset[str]:
        return frozenset({".xyz"})

    def parse(self, path, repo_root) -> ParsedFile:
        ...  # parse and return nodes + edges
```

```toml
# pyproject.toml
[project.entry-points."codebrain.parsers"]
rust = "your_package.parser:RustParser"
```

## CI Integration

### Pre-commit Hook

```bash
brain hook install     # validates staged files before every commit
brain hook uninstall   # remove the hook
```

### GitHub Action

```yaml
name: CodeBrain Validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install codebrain
      - run: brain ci --base origin/main --json
```

## Optional Extras

```bash
pip install codebrain[ts]    # TypeScript/JavaScript tree-sitter parser
pip install codebrain[api]   # REST API server (FastAPI)
pip install codebrain[llm]   # LLM-enhanced explanations (optional, requires API key)
pip install codebrain[all]   # Everything
```

**The core tool requires no extras.** Python parsing, impact analysis, health scores, dead code detection, coupling analysis — all work out of the box with just `pip install codebrain`.

## How It Works

```
Source Files  -->  Parser (Python AST / tree-sitter)  -->  Nodes + Edges
                                                               |
                                                         GraphStore (SQLite)
                                                               |
                                                         QueryEngine
                                                               |
                                 CLI / MCP Server / REST API / VS Code Extension
```

- **Node** — a code symbol (function, class, method, variable, file)
- **Edge** — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
- **GraphStore** — persistent SQLite database with WAL mode, lives in `.codebrain/graph.db`
- **QueryEngine** — BFS/DFS traversal for impact analysis, call chains, dead code, cycle detection

Everything is local. The database is a single SQLite file in your repo's `.codebrain/` directory (auto-gitignored).

## Real-World Validation

Tested on a 1,328-file mixed Python + TypeScript production codebase:

| Metric | Result |
|--------|--------|
| Files indexed | 1,328 (zero errors) |
| Symbols extracted | 17,756 |
| Relationships mapped | 111,793 |
| Indexing time | 135 seconds |
| Health score | 93/100 |
| Impact analysis | 48 dependents traced across 69 files |
| Implicit contracts | Found co-import pattern in 141/141 files |
| Tests passing | 794 |

## Requirements

- Python 3.11+
- No internet connection required
- No API keys required
- No LLM required
- Works on Windows, macOS, and Linux

## Development

```bash
git clone https://github.com/monk0062006/CodeBrain.git
cd CodeBrain
pip install -e ".[dev]"

pytest tests/ -v              # Run tests
mypy codebrain/               # Type checking
ruff check codebrain/         # Linting
pytest --cov=codebrain        # Coverage
```

## License

MIT
