codebrain 0.1.1__tar.gz → 0.3.1__tar.gz

{codebrain-0.1.1 → codebrain-0.3.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 CodeBrain Contributors
+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

codebrain-0.3.1/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: codebrain
+Version: 0.3.1
+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 — and stores it locally in
+SQLite. Wire it into Claude Code, Cursor, or any MCP-compatible agent
+and your AI suddenly knows the structure of your code instead of
+guessing.
+
+```bash
+pip install codebrain
+cd your-project
+brain init
+```
+
+```
+Indexing your-project (1,328 files) ...
+Done in 135s — 17,756 nodes, 111,793 edges
+Health: 93/100 (A)
+```
+
+Free. MIT-licensed. No cloud. No LLM required for the core features.
+
+---
+
+## Why
+
+AI coding agents (Claude Code, Cursor, Copilot) generate code faster
+than you can review it. They read fragments of code, lack persistent
+structural memory, and apply local fixes. When an agent removes a
+function, it doesn't know 3 other files call it. When it changes a
+signature, it doesn't know what depends on the old shape.
+
+CodeBrain knows. It maintains a persistent graph of every symbol and
+relationship and gives agents tools (via MCP) to query it.
+
+---
+
+## Wire it into Claude Code
+
+The killer feature. One command:
+
+```bash
+brain setup
+```
+
+Indexes the repo, drops a `CLAUDE.md` with project context, writes the
+MCP config. Restart Claude Code and it has tools like
+`mcp__codebrain__impact_analysis`, `mcp__codebrain__find_dead_code`,
+`mcp__codebrain__call_chain`, `mcp__codebrain__zoom`,
+`mcp__codebrain__ask_codebase`, plus a few dozen more. It uses them on
+its own.
+
+Manual config (any MCP-compatible client):
+
+```json
+{
+  "mcpServers": {
+    "codebrain": {
+      "command": "python",
+      "args": ["-m", "codebrain.mcp_server"],
+      "env": { "CODEBRAIN_PROJECT": "/absolute/path/to/repo" }
+    }
+  }
+}
+```
+
+---
+
+## What you can do from the CLI
+
+```bash
+brain impact create_user        # what breaks if I change this?
+brain callers create_user       # who calls this?
+brain trace create_user         # what does it call, recursively?
+brain deadcode                  # actually-unused functions, with confidence levels
+brain hotspots                  # riskiest symbols (most depended on)
+brain cycles                    # import cycles
+brain health                    # codebase score 0-100
+brain coupling                  # module-to-module coupling
+brain layers                    # architectural layers inferred from imports
+brain zoom system|module|symbol # Google Maps for your architecture
+brain ask "where does login flow live?"
+```
+
+Sample output:
+
+```
+$ 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
+  Blast radius: 5.2% of the codebase
+```
+
+```
+$ brain hotspots
+Risk hotspots (top 3):
+   48.2  function  getAstroData             48 deps   69 files
+   35.1  function  compileAstroDetails      35 deps   52 files
+   28.7  class     ProfileBuilder           28 deps   41 files
+```
+
+Run `brain --help` for the full command list (60+).
+
+---
+
+## Pre-commit and CI
+
+```bash
+brain hook install              # validates staged Python files before each commit
+brain ci --base origin/main     # exit 1 on structural regressions in a PR
+brain diff-impact               # blast radius of currently-staged changes
+```
+
+GitHub Action:
+
+```yaml
+- run: pip install codebrain
+- run: brain ci --base origin/main --json
+```
+
+---
+
+## Language support
+
+| Language | Parser | Status |
+|---|---|---|
+| Python | AST (stdlib) | full |
+| TypeScript / JS / JSX / Vue | tree-sitter | full — `pip install "codebrain[ts]"` |
+| Java | tree-sitter | full — Spring Boot aware |
+| Go, Rust, C#, Kotlin, Dart | tree-sitter / regex | good |
+| COBOL, Fortran, MUMPS, PL/SQL | regex | basic — for legacy migration |
+
+Adding a parser: implement `BaseParser`, register via the
+`codebrain.parsers` entry point. See `docs/USAGE.md`.
+
+---
+
+## Optional extras
+
+```bash
+pip install "codebrain[ts]"     # TypeScript / JS / Vue
+pip install "codebrain[api]"    # FastAPI REST server
+pip install "codebrain[llm]"    # AI-powered explain / ask / rewrite
+pip install "codebrain[all]"    # everything
+```
+
+Core install (`pip install codebrain`) is enough for Python projects
+and the MCP server.
+
+---
+
+## Configuration
+
+`.codebrain.toml` at repo root, or `CODEBRAIN_*` env vars:
+
+```toml
+[index]
+exclude = ["vendor/", "**/__generated__/**"]
+
+[mcp]
+tool_timeout = 25
+idle_timeout = 1800
+
+[parser]
+languages = ["python", "typescript", "java"]
+```
+
+---
+
+## How it works
+
+```
+Source files ─► Parser ─► Nodes + Edges ─► SQLite (.codebrain/graph.db)
+                                                │
+                          ┌─────────────────────┴───────────────────────┐
+                          ▼                                             ▼
+                       brain CLI                              MCP server / REST API
+```
+
+- **Node** — a symbol (function, class, method, file)
+- **Edge** — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
+- **GraphStore** — SQLite with WAL mode, lives in `.codebrain/` (auto-gitignored)
+- **QueryEngine** — BFS/DFS for impact, call chains, dead code, cycles
+
+Everything stays on your machine. The only thing that leaves is what
+you explicitly send to an LLM via `brain ask` / `brain explain` /
+`brain rewrite`.
+
+---
+
+## Documentation
+
+- **[docs/USAGE.md](docs/USAGE.md)** — full usage guide: workflows,
+  every command, MCP setup, troubleshooting.
+- **[docs/cli-reference.md](docs/cli-reference.md)** — generated CLI
+  reference.
+- **[docs/mcp-tools.md](docs/mcp-tools.md)** — every MCP tool with
+  examples.
+- **[docs/PRD.md](docs/PRD.md)** — product requirements.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/monk0062006/CodeBrain.git
+cd CodeBrain
+pip install -e ".[dev]"
+
+pytest tests/                   # 1,900+ tests
+ruff check codebrain/
+mypy codebrain/
+```
+
+---
+
+## License
+
+MIT. Use it however you want.
+
+## Links
+
+- PyPI: https://pypi.org/project/codebrain/
+- Issues: https://github.com/monk0062006/CodeBrain/issues

codebrain-0.3.1/README.md

@@ -0,0 +1,229 @@
+# CodeBrain
+
+**Know what breaks before you break it.**
+
+CodeBrain builds a structural knowledge graph of your codebase — every
+function, class, import, and call chain — and stores it locally in
+SQLite. Wire it into Claude Code, Cursor, or any MCP-compatible agent
+and your AI suddenly knows the structure of your code instead of
+guessing.
+
+```bash
+pip install codebrain
+cd your-project
+brain init
+```
+
+```
+Indexing your-project (1,328 files) ...
+Done in 135s — 17,756 nodes, 111,793 edges
+Health: 93/100 (A)
+```
+
+Free. MIT-licensed. No cloud. No LLM required for the core features.
+
+---
+
+## Why
+
+AI coding agents (Claude Code, Cursor, Copilot) generate code faster
+than you can review it. They read fragments of code, lack persistent
+structural memory, and apply local fixes. When an agent removes a
+function, it doesn't know 3 other files call it. When it changes a
+signature, it doesn't know what depends on the old shape.
+
+CodeBrain knows. It maintains a persistent graph of every symbol and
+relationship and gives agents tools (via MCP) to query it.
+
+---
+
+## Wire it into Claude Code
+
+The killer feature. One command:
+
+```bash
+brain setup
+```
+
+Indexes the repo, drops a `CLAUDE.md` with project context, writes the
+MCP config. Restart Claude Code and it has tools like
+`mcp__codebrain__impact_analysis`, `mcp__codebrain__find_dead_code`,
+`mcp__codebrain__call_chain`, `mcp__codebrain__zoom`,
+`mcp__codebrain__ask_codebase`, plus a few dozen more. It uses them on
+its own.
+
+Manual config (any MCP-compatible client):
+
+```json
+{
+  "mcpServers": {
+    "codebrain": {
+      "command": "python",
+      "args": ["-m", "codebrain.mcp_server"],
+      "env": { "CODEBRAIN_PROJECT": "/absolute/path/to/repo" }
+    }
+  }
+}
+```
+
+---
+
+## What you can do from the CLI
+
+```bash
+brain impact create_user        # what breaks if I change this?
+brain callers create_user       # who calls this?
+brain trace create_user         # what does it call, recursively?
+brain deadcode                  # actually-unused functions, with confidence levels
+brain hotspots                  # riskiest symbols (most depended on)
+brain cycles                    # import cycles
+brain health                    # codebase score 0-100
+brain coupling                  # module-to-module coupling
+brain layers                    # architectural layers inferred from imports
+brain zoom system|module|symbol # Google Maps for your architecture
+brain ask "where does login flow live?"
+```
+
+Sample output:
+
+```
+$ 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
+  Blast radius: 5.2% of the codebase
+```
+
+```
+$ brain hotspots
+Risk hotspots (top 3):
+   48.2  function  getAstroData             48 deps   69 files
+   35.1  function  compileAstroDetails      35 deps   52 files
+   28.7  class     ProfileBuilder           28 deps   41 files
+```
+
+Run `brain --help` for the full command list (60+).
+
+---
+
+## Pre-commit and CI
+
+```bash
+brain hook install              # validates staged Python files before each commit
+brain ci --base origin/main     # exit 1 on structural regressions in a PR
+brain diff-impact               # blast radius of currently-staged changes
+```
+
+GitHub Action:
+
+```yaml
+- run: pip install codebrain
+- run: brain ci --base origin/main --json
+```
+
+---
+
+## Language support
+
+| Language | Parser | Status |
+|---|---|---|
+| Python | AST (stdlib) | full |
+| TypeScript / JS / JSX / Vue | tree-sitter | full — `pip install "codebrain[ts]"` |
+| Java | tree-sitter | full — Spring Boot aware |
+| Go, Rust, C#, Kotlin, Dart | tree-sitter / regex | good |
+| COBOL, Fortran, MUMPS, PL/SQL | regex | basic — for legacy migration |
+
+Adding a parser: implement `BaseParser`, register via the
+`codebrain.parsers` entry point. See `docs/USAGE.md`.
+
+---
+
+## Optional extras
+
+```bash
+pip install "codebrain[ts]"     # TypeScript / JS / Vue
+pip install "codebrain[api]"    # FastAPI REST server
+pip install "codebrain[llm]"    # AI-powered explain / ask / rewrite
+pip install "codebrain[all]"    # everything
+```
+
+Core install (`pip install codebrain`) is enough for Python projects
+and the MCP server.
+
+---
+
+## Configuration
+
+`.codebrain.toml` at repo root, or `CODEBRAIN_*` env vars:
+
+```toml
+[index]
+exclude = ["vendor/", "**/__generated__/**"]
+
+[mcp]
+tool_timeout = 25
+idle_timeout = 1800
+
+[parser]
+languages = ["python", "typescript", "java"]
+```
+
+---
+
+## How it works
+
+```
+Source files ─► Parser ─► Nodes + Edges ─► SQLite (.codebrain/graph.db)
+                                                │
+                          ┌─────────────────────┴───────────────────────┐
+                          ▼                                             ▼
+                       brain CLI                              MCP server / REST API
+```
+
+- **Node** — a symbol (function, class, method, file)
+- **Edge** — a relationship (CALLS, IMPORTS, CONTAINS, EXTENDS, DATAFLOW)
+- **GraphStore** — SQLite with WAL mode, lives in `.codebrain/` (auto-gitignored)
+- **QueryEngine** — BFS/DFS for impact, call chains, dead code, cycles
+
+Everything stays on your machine. The only thing that leaves is what
+you explicitly send to an LLM via `brain ask` / `brain explain` /
+`brain rewrite`.
+
+---
+
+## Documentation
+
+- **[docs/USAGE.md](docs/USAGE.md)** — full usage guide: workflows,
+  every command, MCP setup, troubleshooting.
+- **[docs/cli-reference.md](docs/cli-reference.md)** — generated CLI
+  reference.
+- **[docs/mcp-tools.md](docs/mcp-tools.md)** — every MCP tool with
+  examples.
+- **[docs/PRD.md](docs/PRD.md)** — product requirements.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/monk0062006/CodeBrain.git
+cd CodeBrain
+pip install -e ".[dev]"
+
+pytest tests/                   # 1,900+ tests
+ruff check codebrain/
+mypy codebrain/
+```
+
+---
+
+## License
+
+MIT. Use it however you want.
+
+## Links
+
+- PyPI: https://pypi.org/project/codebrain/
+- Issues: https://github.com/monk0062006/CodeBrain/issues

codebrain-0.3.1/codebrain/__init__.py

@@ -0,0 +1,10 @@
+"""CodeBrain — persistent structural knowledge graph for codebases."""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("codebrain")
+except PackageNotFoundError:
+    # Source checkout without installation (e.g. running from a worktree).
+    # Keep in sync with [project.version] in pyproject.toml.
+    __version__ = "0.3.1"

codebrain-0.3.1/codebrain/actions/__init__.py

@@ -0,0 +1,16 @@
+"""Autonomous actions engine — CodeBrain acts, not just analyzes."""
+
+from codebrain.actions.test_gen import TestGenerator, GeneratedTest
+from codebrain.actions.reviewer import CodeReviewer, CodeReview, ReviewFinding
+from codebrain.actions.refactor import Refactorer, RefactorSuggestion, RefactorResult
+
+__all__ = [
+    "TestGenerator",
+    "GeneratedTest",
+    "CodeReviewer",
+    "CodeReview",
+    "ReviewFinding",
+    "Refactorer",
+    "RefactorSuggestion",
+    "RefactorResult",
+]

codebrain-0.3.1/codebrain/actions/base.py

@@ -0,0 +1,139 @@
+"""Shared infrastructure for autonomous actions."""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+from codebrain.context import ContextGenerator
+from codebrain.graph.query import QueryEngine
+from codebrain.graph.store import GraphStore
+from codebrain.rewriter import LLMClient
+from codebrain.utils import is_test_file
+
+
+class ActionEngine:
+    """Base class for all autonomous actions."""
+
+    def __init__(self, store: GraphStore, repo_root: Path, llm: LLMClient):
+        self.store = store
+        self.repo_root = repo_root
+        self.llm = llm
+        self.context = ContextGenerator(store)
+        self.engine = QueryEngine(store)
+
+    def _get_symbol_context(self, name: str) -> list[dict]:
+        """Full structural context for a symbol."""
+        return self.context.for_symbol(name)
+
+    def _get_file_source(self, file_path: str) -> str:
+        """Read actual source code from disk."""
+        full = self.repo_root / file_path
+        if not full.exists():
+            return ""
+        try:
+            return full.read_text(encoding="utf-8", errors="replace")
+        except Exception:
+            return ""
+
+    def _get_function_source(self, file_path: str, name: str, line_start: int) -> str:
+        """Extract a single function/class source from a file."""
+        source = self._get_file_source(file_path)
+        if not source:
+            return ""
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return ""
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                if node.name == name:
+                    lines = source.splitlines()
+                    end = getattr(node, "end_lineno", None) or (node.lineno + 20)
+                    return "\n".join(lines[node.lineno - 1 : end])
+        # Fallback: return from line_start
+        if line_start > 0:
+            lines = source.splitlines()
+            return "\n".join(lines[line_start - 1 : line_start + 30])
+        return ""
+
+    def _get_existing_tests(self, file_path: str) -> str:
+        """Find existing test files and return a sample of test patterns."""
+        # Look for test files in tests/ directory
+        tests_dir = self.repo_root / "tests"
+        if not tests_dir.exists():
+            tests_dir = self.repo_root / "test"
+        if not tests_dir.exists():
+            return "# No existing test directory found"
+
+        samples = []
+        for tf in sorted(tests_dir.iterdir()):
+            if tf.name.startswith("test_") and tf.suffix == ".py":
+                try:
+                    content = tf.read_text(encoding="utf-8", errors="replace")
+                    # Extract first test function as pattern example
+                    for match in re.finditer(
+                        r"((?:@\w+.*\n)*def test_\w+\(.*?\):.*?)(?=\ndef |\nclass |\Z)",
+                        content,
+                        re.DOTALL,
+                    ):
+                        sample = match.group(1).strip()
+                        if len(sample) < 500:
+                            samples.append(f"# From {tf.name}:\n{sample}")
+                            break
+                except Exception:
+                    continue
+            if len(samples) >= 3:
+                break
+
+        return "\n\n".join(samples) if samples else "# No test examples found"
+
+    def _validate_python(self, code: str) -> list[str]:
+        """Check Python syntax and basic correctness."""
+        errors = []
+        try:
+            ast.parse(code)
+        except SyntaxError as e:
+            errors.append(f"Syntax error: {e.msg} at line {e.lineno}")
+        return errors
+
+    def _extract_code(self, response: str) -> str:
+        """Strip markdown fences from LLM output."""
+        pattern = r"```(?:python|java|typescript|javascript)?\s*\n(.*?)```"
+        matches = re.findall(pattern, response, re.DOTALL)
+        if matches:
+            return max(matches, key=len).strip()
+        # If no fences, return as-is but trim non-code lines at start
+        lines = response.strip().split("\n")
+        for i, line in enumerate(lines):
+            s = line.strip()
+            if s.startswith(("import ", "from ", "def ", "class ", "#", '"""', "@", "async ")):
+                return "\n".join(lines[i:]).strip()
+        return response.strip()
+
+    def _interpret_fingerprint(self, fingerprint: str) -> str:
+        """Convert structural fingerprint to actionable guidance."""
+        if not fingerprint:
+            return "- No structural fingerprint available."
+        guidance = []
+        if "returns:" in fingerprint:
+            returns = fingerprint.split("returns:")[1].split("|")[0].strip()
+            guidance.append(f"- Returns: {returns}. Test each return path.")
+        if "raises:" in fingerprint:
+            exc = fingerprint.split("raises:")[1].split("|")[0].strip()
+            guidance.append(f"- Raises: {exc}. Test exception paths.")
+        if "mutates:" in fingerprint:
+            mut = fingerprint.split("mutates:")[1].split("|")[0].strip()
+            guidance.append(f"- Mutates: {mut}. Verify state changes.")
+        if "io:" in fingerprint:
+            io = fingerprint.split("io:")[1].split("|")[0].strip()
+            guidance.append(f"- I/O: {io}. Mock these in tests.")
+        if "yields" in fingerprint:
+            guidance.append("- Generator function. Test iteration and empty case.")
+        if "async" in fingerprint:
+            guidance.append("- Async function. Use @pytest.mark.asyncio.")
+        if "control:" in fingerprint:
+            ctrl = fingerprint.split("control:")[1].split("|")[0].strip()
+            guidance.append(f"- Control flow: {ctrl}. Test each branch.")
+        return "\n".join(guidance) if guidance else "- No special patterns detected."