codebrain 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- codebrain-0.1.0/LICENSE +21 -0
- codebrain-0.1.0/PKG-INFO +360 -0
- codebrain-0.1.0/README.md +316 -0
- codebrain-0.1.0/codebrain/__init__.py +3 -0
- codebrain-0.1.0/codebrain/__main__.py +6 -0
- codebrain-0.1.0/codebrain/agent_bridge.py +162 -0
- codebrain-0.1.0/codebrain/analyzer.py +943 -0
- codebrain-0.1.0/codebrain/api.py +578 -0
- codebrain-0.1.0/codebrain/api_models.py +102 -0
- codebrain-0.1.0/codebrain/cli.py +1927 -0
- codebrain-0.1.0/codebrain/comprehension.py +1939 -0
- codebrain-0.1.0/codebrain/config.py +46 -0
- codebrain-0.1.0/codebrain/context.py +276 -0
- codebrain-0.1.0/codebrain/export.py +334 -0
- codebrain-0.1.0/codebrain/graph/__init__.py +0 -0
- codebrain-0.1.0/codebrain/graph/query.py +656 -0
- codebrain-0.1.0/codebrain/graph/schema.py +113 -0
- codebrain-0.1.0/codebrain/graph/store.py +295 -0
- codebrain-0.1.0/codebrain/hook_runner.py +71 -0
- codebrain-0.1.0/codebrain/hooks.py +107 -0
- codebrain-0.1.0/codebrain/indexer.py +450 -0
- codebrain-0.1.0/codebrain/llm.py +676 -0
- codebrain-0.1.0/codebrain/logging.py +42 -0
- codebrain-0.1.0/codebrain/mcp_server.py +1635 -0
- codebrain-0.1.0/codebrain/memory/__init__.py +5 -0
- codebrain-0.1.0/codebrain/memory/store.py +270 -0
- codebrain-0.1.0/codebrain/parser/__init__.py +0 -0
- codebrain-0.1.0/codebrain/parser/base.py +27 -0
- codebrain-0.1.0/codebrain/parser/config_parser.py +228 -0
- codebrain-0.1.0/codebrain/parser/models.py +44 -0
- codebrain-0.1.0/codebrain/parser/python_parser.py +658 -0
- codebrain-0.1.0/codebrain/parser/registry.py +144 -0
- codebrain-0.1.0/codebrain/parser/typescript_parser.py +1189 -0
- codebrain-0.1.0/codebrain/parser/typescript_treesitter.py +535 -0
- codebrain-0.1.0/codebrain/py.typed +0 -0
- codebrain-0.1.0/codebrain/resolver.py +171 -0
- codebrain-0.1.0/codebrain/settings.py +88 -0
- codebrain-0.1.0/codebrain/utils.py +59 -0
- codebrain-0.1.0/codebrain/validator.py +563 -0
- codebrain-0.1.0/codebrain/watcher/__init__.py +0 -0
- codebrain-0.1.0/codebrain/watcher/file_watcher.py +173 -0
- codebrain-0.1.0/codebrain.egg-info/PKG-INFO +360 -0
- codebrain-0.1.0/codebrain.egg-info/SOURCES.txt +91 -0
- codebrain-0.1.0/codebrain.egg-info/dependency_links.txt +1 -0
- codebrain-0.1.0/codebrain.egg-info/entry_points.txt +6 -0
- codebrain-0.1.0/codebrain.egg-info/requires.txt +26 -0
- codebrain-0.1.0/codebrain.egg-info/top_level.txt +1 -0
- codebrain-0.1.0/pyproject.toml +111 -0
- codebrain-0.1.0/setup.cfg +4 -0
- codebrain-0.1.0/tests/test_agent_bridge.py +57 -0
- codebrain-0.1.0/tests/test_analyzer.py +446 -0
- codebrain-0.1.0/tests/test_api.py +412 -0
- codebrain-0.1.0/tests/test_ci.py +184 -0
- codebrain-0.1.0/tests/test_cli.py +475 -0
- codebrain-0.1.0/tests/test_comprehension.py +635 -0
- codebrain-0.1.0/tests/test_context.py +107 -0
- codebrain-0.1.0/tests/test_contracts_real.py +123 -0
- codebrain-0.1.0/tests/test_dataflow.py +265 -0
- codebrain-0.1.0/tests/test_dead_code_confidence.py +129 -0
- codebrain-0.1.0/tests/test_error_recovery.py +192 -0
- codebrain-0.1.0/tests/test_export.py +213 -0
- codebrain-0.1.0/tests/test_hooks.py +142 -0
- codebrain-0.1.0/tests/test_indexer.py +115 -0
- codebrain-0.1.0/tests/test_install.py +41 -0
- codebrain-0.1.0/tests/test_integration.py +287 -0
- codebrain-0.1.0/tests/test_jyotishyamitra.py +368 -0
- codebrain-0.1.0/tests/test_llm.py +475 -0
- codebrain-0.1.0/tests/test_mcp_server.py +615 -0
- codebrain-0.1.0/tests/test_memory.py +462 -0
- codebrain-0.1.0/tests/test_multi_project_cli.py +184 -0
- codebrain-0.1.0/tests/test_narratives.py +166 -0
- codebrain-0.1.0/tests/test_parser.py +249 -0
- codebrain-0.1.0/tests/test_plugin_system.py +221 -0
- codebrain-0.1.0/tests/test_production_hardening.py +377 -0
- codebrain-0.1.0/tests/test_query.py +447 -0
- codebrain-0.1.0/tests/test_real_world.py +298 -0
- codebrain-0.1.0/tests/test_resolver.py +66 -0
- codebrain-0.1.0/tests/test_scale.py +245 -0
- codebrain-0.1.0/tests/test_scale_optimizations.py +229 -0
- codebrain-0.1.0/tests/test_scale_real.py +220 -0
- codebrain-0.1.0/tests/test_schema.py +100 -0
- codebrain-0.1.0/tests/test_settings.py +113 -0
- codebrain-0.1.0/tests/test_store.py +190 -0
- codebrain-0.1.0/tests/test_ts_ast_parser.py +130 -0
- codebrain-0.1.0/tests/test_ts_parser_enhanced.py +224 -0
- codebrain-0.1.0/tests/test_typescript_parser.py +170 -0
- codebrain-0.1.0/tests/test_utils.py +37 -0
- codebrain-0.1.0/tests/test_validation_narratives.py +103 -0
- codebrain-0.1.0/tests/test_validator.py +120 -0
- codebrain-0.1.0/tests/test_validator_scenarios.py +328 -0
- codebrain-0.1.0/tests/test_watch_validate.py +107 -0
- codebrain-0.1.0/tests/test_watcher.py +135 -0
- codebrain-0.1.0/tests/test_zoom.py +189 -0
codebrain-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 CodeBrain Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
codebrain-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codebrain
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Persistent structural knowledge graph for codebases — lets LLM agents skip grep and understand repos in seconds.
|
|
5
|
+
Author: CodeBrain Contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/monk0062006/CodeBrain
|
|
8
|
+
Project-URL: Repository, https://github.com/monk0062006/CodeBrain
|
|
9
|
+
Project-URL: Issues, https://github.com/monk0062006/CodeBrain/issues
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: click>=8.1
|
|
23
|
+
Requires-Dist: watchdog>=3.0
|
|
24
|
+
Requires-Dist: mcp<1.20,>=1.0
|
|
25
|
+
Requires-Dist: jinja2>=3.1
|
|
26
|
+
Provides-Extra: api
|
|
27
|
+
Requires-Dist: fastapi>=0.110; extra == "api"
|
|
28
|
+
Requires-Dist: uvicorn>=0.27; extra == "api"
|
|
29
|
+
Provides-Extra: llm
|
|
30
|
+
Requires-Dist: httpx>=0.27; extra == "llm"
|
|
31
|
+
Provides-Extra: ts
|
|
32
|
+
Requires-Dist: tree-sitter>=0.21; extra == "ts"
|
|
33
|
+
Requires-Dist: tree-sitter-languages>=1.10; extra == "ts"
|
|
34
|
+
Provides-Extra: dev
|
|
35
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
36
|
+
Requires-Dist: pytest-tmp-files>=0.0.2; extra == "dev"
|
|
37
|
+
Requires-Dist: pytest-cov>=4.0; extra == "dev"
|
|
38
|
+
Requires-Dist: mypy>=1.8; extra == "dev"
|
|
39
|
+
Requires-Dist: ruff>=0.3; extra == "dev"
|
|
40
|
+
Requires-Dist: httpx>=0.27; extra == "dev"
|
|
41
|
+
Provides-Extra: all
|
|
42
|
+
Requires-Dist: codebrain[api,llm,ts]; extra == "all"
|
|
43
|
+
Dynamic: license-file
|
|
44
|
+
|
|
45
|
+
# CodeBrain
|
|
46
|
+
|
|
47
|
+
Structural intelligence for AI-assisted development. CodeBrain builds a
|
|
48
|
+
persistent knowledge graph of your codebase and validates changes before
|
|
49
|
+
they land — preventing AI coding agents from silently breaking things.
|
|
50
|
+
|
|
51
|
+
## The Problem
|
|
52
|
+
|
|
53
|
+
AI coding agents (Claude Code, Cursor, Copilot) generate code faster than
|
|
54
|
+
you can review it. They grep fragments, apply local fixes, and don't
|
|
55
|
+
maintain a mental model. When the AI removes a function, it doesn't know
|
|
56
|
+
3 other files call it.
|
|
57
|
+
|
|
58
|
+
CodeBrain knows.
|
|
59
|
+
|
|
60
|
+
## Quick Start
|
|
61
|
+
|
|
62
|
+
### 1. Install
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pip install codebrain
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Optional extras:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
pip install codebrain[api] # REST API server
|
|
72
|
+
pip install codebrain[llm] # LLM-enhanced explanations
|
|
73
|
+
pip install codebrain[ts] # TypeScript AST parser (tree-sitter)
|
|
74
|
+
pip install codebrain[all] # Everything
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### 2. Index your project
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
cd your-project
|
|
81
|
+
brain init
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### 3. Connect to Claude Code
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
brain agent # generates CLAUDE.md + MCP config
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Or add to your MCP config manually:
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"codebrain": {
|
|
96
|
+
"command": "python",
|
|
97
|
+
"args": ["-m", "codebrain.mcp_server"],
|
|
98
|
+
"cwd": "/path/to/your/repo"
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### 4. That's it
|
|
105
|
+
|
|
106
|
+
CodeBrain will automatically validate changes before Claude writes them.
|
|
107
|
+
When a change would break something, it says so — with the specific files
|
|
108
|
+
and callers that would be affected.
|
|
109
|
+
|
|
110
|
+
## What It Does
|
|
111
|
+
|
|
112
|
+
### Structural Safety Gate
|
|
113
|
+
|
|
114
|
+
Before an AI agent writes a file, CodeBrain checks if the change would break
|
|
115
|
+
callers in other files. If it would, the agent is told to fix the breakage first.
|
|
116
|
+
|
|
117
|
+
### Impact Analysis
|
|
118
|
+
|
|
119
|
+
"What would break if I change this?" — answers with specific files, symbols,
|
|
120
|
+
and call chains. Not grep results. Deterministic graph traversal.
|
|
121
|
+
|
|
122
|
+
### Risk Hotspots
|
|
123
|
+
|
|
124
|
+
Identifies the most structurally dangerous code — functions called by many files,
|
|
125
|
+
modules with high coupling, symbols where a signature change would cascade.
|
|
126
|
+
|
|
127
|
+
### Dead Code Detection
|
|
128
|
+
|
|
129
|
+
Finds unused symbols with confidence levels. High-confidence means it's really dead.
|
|
130
|
+
Medium means the file uses dynamic patterns. Low means it might be used indirectly.
|
|
131
|
+
|
|
132
|
+
### Comprehension Narratives
|
|
133
|
+
|
|
134
|
+
Plain English explanations: "store.py is the most depended-on file — 8 modules
|
|
135
|
+
import from it. Changes here have the highest blast radius in the codebase."
|
|
136
|
+
|
|
137
|
+
## CLI Commands
|
|
138
|
+
|
|
139
|
+
| Command | Description |
|
|
140
|
+
|---------|-------------|
|
|
141
|
+
| `brain init` | Index the current repository |
|
|
142
|
+
| `brain reindex` | Force a full rebuild |
|
|
143
|
+
| `brain status [--json]` | Show index statistics |
|
|
144
|
+
| `brain search <query> [--json]` | Find symbols by name |
|
|
145
|
+
| `brain trace <name> [--depth N] [--json]` | Forward call chain |
|
|
146
|
+
| `brain impact <name> [--depth N] [--json]` | Reverse impact analysis |
|
|
147
|
+
| `brain deps <name> [--json]` | Dependencies of a symbol or file |
|
|
148
|
+
| `brain deadcode [--json]` | Find unused functions/classes |
|
|
149
|
+
| `brain cycles [--json]` | Detect import cycles |
|
|
150
|
+
| `brain validate <file> [--json]` | Check if a file change is safe |
|
|
151
|
+
| `brain overview [--json]` | System-level codebase overview |
|
|
152
|
+
| `brain module <file> [--json]` | Module-level view |
|
|
153
|
+
| `brain context <name> [--json]` | LLM-optimized symbol context |
|
|
154
|
+
| `brain hotspots [--top N] [--json]` | Riskiest symbols |
|
|
155
|
+
| `brain coupling [--json]` | Module coupling analysis |
|
|
156
|
+
| `brain contracts [--json]` | Implicit contract detection |
|
|
157
|
+
| `brain layers [--json]` | Architectural layer inference |
|
|
158
|
+
| `brain doctor` | Diagnostic health check |
|
|
159
|
+
| `brain zoom [target] [--json]` | Multi-resolution navigation (system/package/module/symbol) |
|
|
160
|
+
| `brain ci [--base B] [--fail-on F] [--json]` | CI validation of changed files |
|
|
161
|
+
| `brain diff` | Show files changed since last index |
|
|
162
|
+
| `brain watch` | Start file watcher daemon |
|
|
163
|
+
| `brain repair` | Check database integrity, rebuild if corrupted |
|
|
164
|
+
| `brain mcp` | Start MCP server (stdio) |
|
|
165
|
+
| `brain hook install` | Install pre-commit hook |
|
|
166
|
+
| `brain hook uninstall` | Remove pre-commit hook |
|
|
167
|
+
| `brain agent` | Generate agent integration files |
|
|
168
|
+
| `brain serve [--host H] [--port P]` | Start REST API server |
|
|
169
|
+
|
|
170
|
+
All commands accept `--repo <path>` to specify a different repository root, `--verbose` for debug logging, and `--timeout N` to set analysis timeout in seconds (default: 120).
|
|
171
|
+
|
|
172
|
+
## MCP Tools (for AI agents)
|
|
173
|
+
|
|
174
|
+
22+ tools available via MCP protocol. Key tools:
|
|
175
|
+
|
|
176
|
+
| Tool | Purpose |
|
|
177
|
+
|------|---------|
|
|
178
|
+
| `propose_change` | Validate before writing — the structural safety gate |
|
|
179
|
+
| `impact_analysis` | Trace transitive dependents of any symbol |
|
|
180
|
+
| `get_file_context` | Full file understanding for LLM context |
|
|
181
|
+
| `get_symbol_context` | Full symbol understanding for LLM context |
|
|
182
|
+
| `ask_codebase` | Natural language questions about the codebase |
|
|
183
|
+
| `validate_change` | Check if a file change would break callers |
|
|
184
|
+
| `risk_hotspots` | Find structurally dangerous symbols |
|
|
185
|
+
| `find_dead_code` | Unused symbols with confidence levels |
|
|
186
|
+
| `codebase_overview` | System-level architecture summary |
|
|
187
|
+
| `get_task_context` | Pull relevant context for a development task |
|
|
188
|
+
|
|
189
|
+
See [docs/mcp-tools.md](docs/mcp-tools.md) for full documentation.
|
|
190
|
+
|
|
191
|
+
## Configuration
|
|
192
|
+
|
|
193
|
+
Create `.codebrain.toml` in your repo root:
|
|
194
|
+
|
|
195
|
+
```toml
|
|
196
|
+
[codebrain]
|
|
197
|
+
# Extra directories to skip during indexing
|
|
198
|
+
skip_dirs = ["__pycache__", ".git", "node_modules", "vendor"]
|
|
199
|
+
|
|
200
|
+
# File extensions to index
|
|
201
|
+
extensions = [".py", ".ts", ".tsx", ".js", ".jsx"]
|
|
202
|
+
|
|
203
|
+
# Watcher debounce interval (seconds)
|
|
204
|
+
watcher_debounce = 0.5
|
|
205
|
+
|
|
206
|
+
# File count threshold for parallel parsing
|
|
207
|
+
parallel_threshold = 50
|
|
208
|
+
|
|
209
|
+
# Maximum file size to index (KB)
|
|
210
|
+
max_file_size_kb = 1024
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Environment variables override the config file:
|
|
214
|
+
|
|
215
|
+
| Variable | Description |
|
|
216
|
+
|----------|-------------|
|
|
217
|
+
| `CODEBRAIN_SKIP_DIRS` | Comma-separated skip directories |
|
|
218
|
+
| `CODEBRAIN_EXTENSIONS` | Comma-separated file extensions |
|
|
219
|
+
| `CODEBRAIN_DEBOUNCE` | Watcher debounce seconds |
|
|
220
|
+
| `CODEBRAIN_PARALLEL_THRESHOLD` | Parallel parsing threshold |
|
|
221
|
+
| `CODEBRAIN_MAX_WORKERS` | Max parallel worker processes |
|
|
222
|
+
| `CODEBRAIN_CLI_TIMEOUT` | CLI analysis timeout in seconds (default: 120) |
|
|
223
|
+
|
|
224
|
+
See [docs/configuration.md](docs/configuration.md) for full reference.
|
|
225
|
+
|
|
226
|
+
## Language Support
|
|
227
|
+
|
|
228
|
+
- **Python**: Full AST parsing (stable)
|
|
229
|
+
- **TypeScript/JavaScript**: tree-sitter parsing (`pip install codebrain[ts]`)
|
|
230
|
+
- **TypeScript fallback**: regex-based (experimental, limited coverage)
|
|
231
|
+
|
|
232
|
+
## CI Integration
|
|
233
|
+
|
|
234
|
+
### Pre-commit Hook
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
brain hook install # validates staged files before every commit
|
|
238
|
+
brain hook uninstall # remove the hook
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
The hook blocks commits with critical structural violations. Use `git commit --no-verify` to bypass.
|
|
242
|
+
|
|
243
|
+
### CI Pipeline
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
brain ci --base main # exits 1 if UNSAFE changes detected
|
|
247
|
+
brain ci --base main --json # machine-readable output
|
|
248
|
+
brain ci --fail-on caution # stricter: also fail on CAUTION
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### GitHub Action
|
|
252
|
+
|
|
253
|
+
```yaml
|
|
254
|
+
# .github/workflows/codebrain.yml
|
|
255
|
+
name: CodeBrain Validation
|
|
256
|
+
on: [pull_request]
|
|
257
|
+
jobs:
|
|
258
|
+
validate:
|
|
259
|
+
runs-on: ubuntu-latest
|
|
260
|
+
steps:
|
|
261
|
+
- uses: actions/checkout@v4
|
|
262
|
+
with:
|
|
263
|
+
fetch-depth: 0
|
|
264
|
+
- uses: actions/setup-python@v5
|
|
265
|
+
with:
|
|
266
|
+
python-version: '3.11'
|
|
267
|
+
- run: pip install codebrain
|
|
268
|
+
- run: brain ci --base origin/main --json
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Or use the reusable composite action:
|
|
272
|
+
|
|
273
|
+
```yaml
|
|
274
|
+
- uses: ./.github/actions/codebrain-validate
|
|
275
|
+
with:
|
|
276
|
+
base-branch: main
|
|
277
|
+
fail-on: unsafe
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
## VS Code Extension
|
|
281
|
+
|
|
282
|
+
See [`vscode-extension/`](vscode-extension/) — 5 commands (impact, context, search, validate, hotspots) plus validate-on-save with inline diagnostics.
|
|
283
|
+
|
|
284
|
+
## REST API
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
pip install codebrain[api]
|
|
288
|
+
brain serve --port 8484
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
~20 endpoints at `/api/status`, `/api/search`, `/api/impact/{name}`, `/api/hotspots`, etc. Interactive docs at `/docs`.
|
|
292
|
+
|
|
293
|
+
## Plugin System
|
|
294
|
+
|
|
295
|
+
Add custom language parsers by implementing `BaseParser` and registering via entry points:
|
|
296
|
+
|
|
297
|
+
```python
|
|
298
|
+
from codebrain.parser.base import BaseParser
|
|
299
|
+
|
|
300
|
+
class RustParser(BaseParser):
|
|
301
|
+
def extensions(self) -> frozenset[str]:
|
|
302
|
+
return frozenset({".rs"})
|
|
303
|
+
|
|
304
|
+
def parse(self, path, repo_root):
|
|
305
|
+
... # return ParsedFile
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
```toml
|
|
309
|
+
# pyproject.toml
|
|
310
|
+
[project.entry-points."codebrain.parsers"]
|
|
311
|
+
rust = "your_package.parser:RustParser"
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
## Architecture
|
|
315
|
+
|
|
316
|
+
```
|
|
317
|
+
Source Files --> Parser (Python/TS) --> ParsedFile (Nodes + Edges)
|
|
318
|
+
|
|
|
319
|
+
GraphStore (SQLite)
|
|
320
|
+
|
|
|
321
|
+
QueryEngine
|
|
322
|
+
|
|
|
323
|
+
CLI / MCP / REST API / VS Code / Agent Bridge
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
**Key abstractions:**
|
|
327
|
+
|
|
328
|
+
- **Node** — a code symbol (function, class, method, variable)
|
|
329
|
+
- **Edge** — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
|
|
330
|
+
- **GraphStore** — CRUD over the SQLite knowledge graph
|
|
331
|
+
- **QueryEngine** — impact analysis, call chains, dead code, cycles
|
|
332
|
+
|
|
333
|
+
## Validated on Real Codebases
|
|
334
|
+
|
|
335
|
+
CodeBrain has been tested on a 1,328-file mixed Python + TypeScript project (17,756 symbols, 111,793 edges):
|
|
336
|
+
|
|
337
|
+
- **Indexing**: 1,328 files in 135s, zero errors
|
|
338
|
+
- **Health score**: 93/100 in under 5s
|
|
339
|
+
- **Impact analysis**: Traces `getAstroData` → 48 dependents across 69 files
|
|
340
|
+
- **Contracts**: Found `Colors` + `Spacing` co-imported in 141/141 files (confidence 1.0)
|
|
341
|
+
- **Coupling**: Identified `logger.py` ↔ `main.py` (score 140)
|
|
342
|
+
- **Layers**: Detected architectural cycles in `kp-astrology` module
|
|
343
|
+
- **752 tests passing** across unit, integration, and real-world validation
|
|
344
|
+
|
|
345
|
+
## Development
|
|
346
|
+
|
|
347
|
+
```bash
|
|
348
|
+
git clone https://github.com/monk0062006/CodeBrain.git
|
|
349
|
+
cd CodeBrain
|
|
350
|
+
pip install -e ".[dev]"
|
|
351
|
+
|
|
352
|
+
pytest tests/ -v # Run tests
|
|
353
|
+
mypy codebrain/ # Type checking
|
|
354
|
+
ruff check codebrain/ # Linting
|
|
355
|
+
pytest --cov=codebrain # Coverage
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
## License
|
|
359
|
+
|
|
360
|
+
MIT
|
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
# CodeBrain
|
|
2
|
+
|
|
3
|
+
Structural intelligence for AI-assisted development. CodeBrain builds a
|
|
4
|
+
persistent knowledge graph of your codebase and validates changes before
|
|
5
|
+
they land — preventing AI coding agents from silently breaking things.
|
|
6
|
+
|
|
7
|
+
## The Problem
|
|
8
|
+
|
|
9
|
+
AI coding agents (Claude Code, Cursor, Copilot) generate code faster than
|
|
10
|
+
you can review it. They grep fragments, apply local fixes, and don't
|
|
11
|
+
maintain a mental model. When the AI removes a function, it doesn't know
|
|
12
|
+
3 other files call it.
|
|
13
|
+
|
|
14
|
+
CodeBrain knows.
|
|
15
|
+
|
|
16
|
+
## Quick Start
|
|
17
|
+
|
|
18
|
+
### 1. Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pip install codebrain
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Optional extras:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install codebrain[api] # REST API server
|
|
28
|
+
pip install codebrain[llm] # LLM-enhanced explanations
|
|
29
|
+
pip install codebrain[ts] # TypeScript AST parser (tree-sitter)
|
|
30
|
+
pip install codebrain[all] # Everything
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### 2. Index your project
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
cd your-project
|
|
37
|
+
brain init
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### 3. Connect to Claude Code
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
brain agent # generates CLAUDE.md + MCP config
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Or add to your MCP config manually:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"mcpServers": {
|
|
51
|
+
"codebrain": {
|
|
52
|
+
"command": "python",
|
|
53
|
+
"args": ["-m", "codebrain.mcp_server"],
|
|
54
|
+
"cwd": "/path/to/your/repo"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### 4. That's it
|
|
61
|
+
|
|
62
|
+
CodeBrain will automatically validate changes before Claude writes them.
|
|
63
|
+
When a change would break something, it says so — with the specific files
|
|
64
|
+
and callers that would be affected.
|
|
65
|
+
|
|
66
|
+
## What It Does
|
|
67
|
+
|
|
68
|
+
### Structural Safety Gate
|
|
69
|
+
|
|
70
|
+
Before an AI agent writes a file, CodeBrain checks if the change would break
|
|
71
|
+
callers in other files. If it would, the agent is told to fix the breakage first.
|
|
72
|
+
|
|
73
|
+
### Impact Analysis
|
|
74
|
+
|
|
75
|
+
"What would break if I change this?" — answers with specific files, symbols,
|
|
76
|
+
and call chains. Not grep results. Deterministic graph traversal.
|
|
77
|
+
|
|
78
|
+
### Risk Hotspots
|
|
79
|
+
|
|
80
|
+
Identifies the most structurally dangerous code — functions called by many files,
|
|
81
|
+
modules with high coupling, symbols where a signature change would cascade.
|
|
82
|
+
|
|
83
|
+
### Dead Code Detection
|
|
84
|
+
|
|
85
|
+
Finds unused symbols with confidence levels. High-confidence means it's really dead.
|
|
86
|
+
Medium means the file uses dynamic patterns. Low means it might be used indirectly.
|
|
87
|
+
|
|
88
|
+
### Comprehension Narratives
|
|
89
|
+
|
|
90
|
+
Plain English explanations: "store.py is the most depended-on file — 8 modules
|
|
91
|
+
import from it. Changes here have the highest blast radius in the codebase."
|
|
92
|
+
|
|
93
|
+
## CLI Commands
|
|
94
|
+
|
|
95
|
+
| Command | Description |
|
|
96
|
+
|---------|-------------|
|
|
97
|
+
| `brain init` | Index the current repository |
|
|
98
|
+
| `brain reindex` | Force a full rebuild |
|
|
99
|
+
| `brain status [--json]` | Show index statistics |
|
|
100
|
+
| `brain search <query> [--json]` | Find symbols by name |
|
|
101
|
+
| `brain trace <name> [--depth N] [--json]` | Forward call chain |
|
|
102
|
+
| `brain impact <name> [--depth N] [--json]` | Reverse impact analysis |
|
|
103
|
+
| `brain deps <name> [--json]` | Dependencies of a symbol or file |
|
|
104
|
+
| `brain deadcode [--json]` | Find unused functions/classes |
|
|
105
|
+
| `brain cycles [--json]` | Detect import cycles |
|
|
106
|
+
| `brain validate <file> [--json]` | Check if a file change is safe |
|
|
107
|
+
| `brain overview [--json]` | System-level codebase overview |
|
|
108
|
+
| `brain module <file> [--json]` | Module-level view |
|
|
109
|
+
| `brain context <name> [--json]` | LLM-optimized symbol context |
|
|
110
|
+
| `brain hotspots [--top N] [--json]` | Riskiest symbols |
|
|
111
|
+
| `brain coupling [--json]` | Module coupling analysis |
|
|
112
|
+
| `brain contracts [--json]` | Implicit contract detection |
|
|
113
|
+
| `brain layers [--json]` | Architectural layer inference |
|
|
114
|
+
| `brain doctor` | Diagnostic health check |
|
|
115
|
+
| `brain zoom [target] [--json]` | Multi-resolution navigation (system/package/module/symbol) |
|
|
116
|
+
| `brain ci [--base B] [--fail-on F] [--json]` | CI validation of changed files |
|
|
117
|
+
| `brain diff` | Show files changed since last index |
|
|
118
|
+
| `brain watch` | Start file watcher daemon |
|
|
119
|
+
| `brain repair` | Check database integrity, rebuild if corrupted |
|
|
120
|
+
| `brain mcp` | Start MCP server (stdio) |
|
|
121
|
+
| `brain hook install` | Install pre-commit hook |
|
|
122
|
+
| `brain hook uninstall` | Remove pre-commit hook |
|
|
123
|
+
| `brain agent` | Generate agent integration files |
|
|
124
|
+
| `brain serve [--host H] [--port P]` | Start REST API server |
|
|
125
|
+
|
|
126
|
+
All commands accept `--repo <path>` to specify a different repository root, `--verbose` for debug logging, and `--timeout N` to set analysis timeout in seconds (default: 120).
|
|
127
|
+
|
|
128
|
+
## MCP Tools (for AI agents)
|
|
129
|
+
|
|
130
|
+
22+ tools available via MCP protocol. Key tools:
|
|
131
|
+
|
|
132
|
+
| Tool | Purpose |
|
|
133
|
+
|------|---------|
|
|
134
|
+
| `propose_change` | Validate before writing — the structural safety gate |
|
|
135
|
+
| `impact_analysis` | Trace transitive dependents of any symbol |
|
|
136
|
+
| `get_file_context` | Full file understanding for LLM context |
|
|
137
|
+
| `get_symbol_context` | Full symbol understanding for LLM context |
|
|
138
|
+
| `ask_codebase` | Natural language questions about the codebase |
|
|
139
|
+
| `validate_change` | Check if a file change would break callers |
|
|
140
|
+
| `risk_hotspots` | Find structurally dangerous symbols |
|
|
141
|
+
| `find_dead_code` | Unused symbols with confidence levels |
|
|
142
|
+
| `codebase_overview` | System-level architecture summary |
|
|
143
|
+
| `get_task_context` | Pull relevant context for a development task |
|
|
144
|
+
|
|
145
|
+
See [docs/mcp-tools.md](docs/mcp-tools.md) for full documentation.
|
|
146
|
+
|
|
147
|
+
## Configuration
|
|
148
|
+
|
|
149
|
+
Create `.codebrain.toml` in your repo root:
|
|
150
|
+
|
|
151
|
+
```toml
|
|
152
|
+
[codebrain]
|
|
153
|
+
# Extra directories to skip during indexing
|
|
154
|
+
skip_dirs = ["__pycache__", ".git", "node_modules", "vendor"]
|
|
155
|
+
|
|
156
|
+
# File extensions to index
|
|
157
|
+
extensions = [".py", ".ts", ".tsx", ".js", ".jsx"]
|
|
158
|
+
|
|
159
|
+
# Watcher debounce interval (seconds)
|
|
160
|
+
watcher_debounce = 0.5
|
|
161
|
+
|
|
162
|
+
# File count threshold for parallel parsing
|
|
163
|
+
parallel_threshold = 50
|
|
164
|
+
|
|
165
|
+
# Maximum file size to index (KB)
|
|
166
|
+
max_file_size_kb = 1024
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Environment variables override the config file:
|
|
170
|
+
|
|
171
|
+
| Variable | Description |
|
|
172
|
+
|----------|-------------|
|
|
173
|
+
| `CODEBRAIN_SKIP_DIRS` | Comma-separated skip directories |
|
|
174
|
+
| `CODEBRAIN_EXTENSIONS` | Comma-separated file extensions |
|
|
175
|
+
| `CODEBRAIN_DEBOUNCE` | Watcher debounce seconds |
|
|
176
|
+
| `CODEBRAIN_PARALLEL_THRESHOLD` | Parallel parsing threshold |
|
|
177
|
+
| `CODEBRAIN_MAX_WORKERS` | Max parallel worker processes |
|
|
178
|
+
| `CODEBRAIN_CLI_TIMEOUT` | CLI analysis timeout in seconds (default: 120) |
|
|
179
|
+
|
|
180
|
+
See [docs/configuration.md](docs/configuration.md) for full reference.
|
|
181
|
+
|
|
182
|
+
## Language Support
|
|
183
|
+
|
|
184
|
+
- **Python**: Full AST parsing (stable)
|
|
185
|
+
- **TypeScript/JavaScript**: tree-sitter parsing (`pip install codebrain[ts]`)
|
|
186
|
+
- **TypeScript fallback**: regex-based (experimental, limited coverage)
|
|
187
|
+
|
|
188
|
+
## CI Integration
|
|
189
|
+
|
|
190
|
+
### Pre-commit Hook
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
brain hook install # validates staged files before every commit
|
|
194
|
+
brain hook uninstall # remove the hook
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
The hook blocks commits with critical structural violations. Use `git commit --no-verify` to bypass.
|
|
198
|
+
|
|
199
|
+
### CI Pipeline
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
brain ci --base main # exits 1 if UNSAFE changes detected
|
|
203
|
+
brain ci --base main --json # machine-readable output
|
|
204
|
+
brain ci --fail-on caution # stricter: also fail on CAUTION
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### GitHub Action
|
|
208
|
+
|
|
209
|
+
```yaml
|
|
210
|
+
# .github/workflows/codebrain.yml
|
|
211
|
+
name: CodeBrain Validation
|
|
212
|
+
on: [pull_request]
|
|
213
|
+
jobs:
|
|
214
|
+
validate:
|
|
215
|
+
runs-on: ubuntu-latest
|
|
216
|
+
steps:
|
|
217
|
+
- uses: actions/checkout@v4
|
|
218
|
+
with:
|
|
219
|
+
fetch-depth: 0
|
|
220
|
+
- uses: actions/setup-python@v5
|
|
221
|
+
with:
|
|
222
|
+
python-version: '3.11'
|
|
223
|
+
- run: pip install codebrain
|
|
224
|
+
- run: brain ci --base origin/main --json
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Or use the reusable composite action:
|
|
228
|
+
|
|
229
|
+
```yaml
|
|
230
|
+
- uses: ./.github/actions/codebrain-validate
|
|
231
|
+
with:
|
|
232
|
+
base-branch: main
|
|
233
|
+
fail-on: unsafe
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
## VS Code Extension
|
|
237
|
+
|
|
238
|
+
See [`vscode-extension/`](vscode-extension/) — 5 commands (impact, context, search, validate, hotspots) plus validate-on-save with inline diagnostics.
|
|
239
|
+
|
|
240
|
+
## REST API
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
pip install codebrain[api]
|
|
244
|
+
brain serve --port 8484
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
~20 endpoints at `/api/status`, `/api/search`, `/api/impact/{name}`, `/api/hotspots`, etc. Interactive docs at `/docs`.
|
|
248
|
+
|
|
249
|
+
## Plugin System
|
|
250
|
+
|
|
251
|
+
Add custom language parsers by implementing `BaseParser` and registering via entry points:
|
|
252
|
+
|
|
253
|
+
```python
|
|
254
|
+
from codebrain.parser.base import BaseParser
|
|
255
|
+
|
|
256
|
+
class RustParser(BaseParser):
|
|
257
|
+
def extensions(self) -> frozenset[str]:
|
|
258
|
+
return frozenset({".rs"})
|
|
259
|
+
|
|
260
|
+
def parse(self, path, repo_root):
|
|
261
|
+
... # return ParsedFile
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
```toml
|
|
265
|
+
# pyproject.toml
|
|
266
|
+
[project.entry-points."codebrain.parsers"]
|
|
267
|
+
rust = "your_package.parser:RustParser"
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## Architecture
|
|
271
|
+
|
|
272
|
+
```
|
|
273
|
+
Source Files --> Parser (Python/TS) --> ParsedFile (Nodes + Edges)
|
|
274
|
+
|
|
|
275
|
+
GraphStore (SQLite)
|
|
276
|
+
|
|
|
277
|
+
QueryEngine
|
|
278
|
+
|
|
|
279
|
+
CLI / MCP / REST API / VS Code / Agent Bridge
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
**Key abstractions:**
|
|
283
|
+
|
|
284
|
+
- **Node** — a code symbol (function, class, method, variable)
|
|
285
|
+
- **Edge** — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
|
|
286
|
+
- **GraphStore** — CRUD over the SQLite knowledge graph
|
|
287
|
+
- **QueryEngine** — impact analysis, call chains, dead code, cycles
|
|
288
|
+
|
|
289
|
+
## Validated on Real Codebases
|
|
290
|
+
|
|
291
|
+
CodeBrain has been tested on a 1,328-file mixed Python + TypeScript project (17,756 symbols, 111,793 edges):
|
|
292
|
+
|
|
293
|
+
- **Indexing**: 1,328 files in 135s, zero errors
|
|
294
|
+
- **Health score**: 93/100 in under 5s
|
|
295
|
+
- **Impact analysis**: Traces `getAstroData` → 48 dependents across 69 files
|
|
296
|
+
- **Contracts**: Found `Colors` + `Spacing` co-imported in 141/141 files (confidence 1.0)
|
|
297
|
+
- **Coupling**: Identified `logger.py` ↔ `main.py` (score 140)
|
|
298
|
+
- **Layers**: Detected architectural cycles in `kp-astrology` module
|
|
299
|
+
- **752 tests passing** across unit, integration, and real-world validation
|
|
300
|
+
|
|
301
|
+
## Development
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
git clone https://github.com/monk0062006/CodeBrain.git
|
|
305
|
+
cd CodeBrain
|
|
306
|
+
pip install -e ".[dev]"
|
|
307
|
+
|
|
308
|
+
pytest tests/ -v # Run tests
|
|
309
|
+
mypy codebrain/ # Type checking
|
|
310
|
+
ruff check codebrain/ # Linting
|
|
311
|
+
pytest --cov=codebrain # Coverage
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
## License
|
|
315
|
+
|
|
316
|
+
MIT
|