codebrain 0.1.0__py3-none-any.whl

codebrain/__init__.py

@@ -0,0 +1,3 @@
+"""CodeBrain — persistent structural knowledge graph for codebases."""
+
+__version__ = "0.1.0"

codebrain/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m codebrain`."""
+
+from codebrain.cli import cli
+
+if __name__ == "__main__":
+    cli()

codebrain/agent_bridge.py

@@ -0,0 +1,162 @@
+"""Agent bridge — makes LLM agents aware of CodeBrain.
+
+Generates:
+  - CLAUDE.md with codebase context for Claude Code
+  - .codebrain/context.json for any agent to consume
+  - MCP server configuration snippet
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from codebrain.comprehension import ComprehensionEngine
+from codebrain.config import CODEBRAIN_DIR, DB_FILENAME
+from codebrain.graph.store import GraphStore
+
+
+def generate_claude_md(repo_root: Path) -> str:
+    """Generate a CLAUDE.md file with codebase structural context.
+
+    This file is automatically read by Claude Code at session start,
+    giving the agent instant structural knowledge.
+    """
+    db_path = repo_root / CODEBRAIN_DIR / DB_FILENAME
+    if not db_path.exists():
+        return "# CodeBrain not initialized. Run `brain init` first.\n"
+
+    with GraphStore(db_path) as store:
+        comp = ComprehensionEngine(store)
+        overview = comp.system_overview()
+        hotspots = comp.risk_hotspots(top_n=10)
+
+    stats = overview["stats"]
+    lines: list[str] = []
+
+    lines.append("# Codebase Structure (auto-generated by CodeBrain)")
+    lines.append("")
+
+    # Structural safety gate — MUST be first so the agent reads it
+    lines.append("## Structural Safety Gate")
+    lines.append("")
+    lines.append("Before writing any file that modifies existing functions, classes, or methods,")
+    lines.append("call the `propose_change` MCP tool with the file path and full new content.")
+    lines.append("")
+    lines.append("- **SAFE**: proceed with writing")
+    lines.append("- **CAUTION**: review the warnings, fix if needed, then write")
+    lines.append("- **UNSAFE**: do NOT write. Fix the violations first.")
+    lines.append("")
+    lines.append("Do not skip this step. It prevents you from breaking callers in other files.")
+    lines.append("")
+
+    lines.append(f"**{stats['files']} files, {stats['nodes']} symbols, {stats['edges']} edges**")
+    lines.append("")
+
+    # Packages
+    lines.append("## Packages")
+    for name, info in overview["packages"].items():
+        doc = f" - {info['docstring']}" if info["docstring"] else ""
+        deps = f" (depends on: {', '.join(info['depends_on'])})" if info["depends_on"] else ""
+        lines.append(f"- **{name}**: {info['file_count']} files, {info['node_count']} symbols{doc}{deps}")
+    lines.append("")
+
+    # Entry points
+    if overview["entry_points"]:
+        lines.append("## Entry Points")
+        for ep in overview["entry_points"]:
+            lines.append(f"- `{ep['file_path']}:{ep['line']}`")
+        lines.append("")
+
+    # Risk hotspots
+    if hotspots:
+        lines.append("## High-Impact Symbols (change with care)")
+        for h in hotspots[:10]:
+            lines.append(f"- `{h['name']}` ({h['type']}) in `{h['file_path']}` - {h['direct_dependents']} dependents, affects {h['affected_files']} files")
+        lines.append("")
+
+    # MCP instructions
+    lines.append("## CodeBrain Tools")
+    lines.append("")
+    lines.append("This repo has a CodeBrain knowledge graph. Use these CLI commands instead of grepping:")
+    lines.append("- `brain search <name>` - find symbols by name")
+    lines.append("- `brain context <name> --json` - get full structural context for a symbol")
+    lines.append("- `brain impact <name> --json` - see what breaks if a symbol changes")
+    lines.append("- `brain validate <file> --json` - validate a file change against the graph")
+    lines.append("- `brain module <file> --json` - understand a module's role and dependencies")
+    lines.append("- `brain overview --json` - system-level codebase overview")
+    lines.append("- `brain hotspots --json` - find riskiest symbols")
+    lines.append("")
+    lines.append("**Always run `brain validate <file> --json` after modifying a file.**")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def generate_context_json(repo_root: Path) -> dict:
+    """Generate .codebrain/context.json for any agent to consume.
+
+    This is a structured representation of the codebase that can be
+    injected into any LLM's context.
+    """
+    db_path = repo_root / CODEBRAIN_DIR / DB_FILENAME
+    if not db_path.exists():
+        return {"error": "CodeBrain not initialized"}
+
+    with GraphStore(db_path) as store:
+        comp = ComprehensionEngine(store)
+        overview = comp.system_overview()
+        hotspots = comp.risk_hotspots(top_n=15)
+
+        from codebrain.analyzer import StructuralAnalyzer
+        analyzer = StructuralAnalyzer(store)
+        layers = analyzer.detect_layers()
+
+    return {
+        "codebrain_version": "0.1.0",
+        "overview": overview,
+        "risk_hotspots": hotspots,
+        "architectural_layers": layers,
+        "instructions": {
+            "before_modifying": "Run `brain validate <file> --json` to check impact.",
+            "to_understand_symbol": "Run `brain context <name> --json` instead of reading source.",
+            "to_find_code": "Run `brain search <query> --json` instead of grepping.",
+        },
+    }
+
+
+def generate_mcp_config(repo_root: Path) -> dict:
+    """Generate MCP server configuration for claude_desktop_config.json."""
+    return {
+        "codebrain": {
+            "command": "python",
+            "args": ["-m", "codebrain.mcp_server"],
+            "cwd": str(repo_root),
+        }
+    }
+
+
+def write_agent_files(repo_root: Path) -> list[str]:
+    """Write all agent integration files. Returns list of files written."""
+    written: list[str] = []
+
+    # CLAUDE.md at repo root
+    claude_md = repo_root / "CLAUDE.md"
+    content = generate_claude_md(repo_root)
+    claude_md.write_text(content, encoding="utf-8")
+    written.append(str(claude_md))
+
+    # context.json inside .codebrain/
+    ctx_path = repo_root / CODEBRAIN_DIR / "context.json"
+    ctx_path.parent.mkdir(parents=True, exist_ok=True)
+    ctx_data = generate_context_json(repo_root)
+    ctx_path.write_text(json.dumps(ctx_data, indent=2), encoding="utf-8")
+    written.append(str(ctx_path))
+
+    # MCP config snippet
+    mcp_path = repo_root / CODEBRAIN_DIR / "mcp_config.json"
+    mcp_data = generate_mcp_config(repo_root)
+    mcp_path.write_text(json.dumps(mcp_data, indent=2), encoding="utf-8")
+    written.append(str(mcp_path))
+
+    return written