codebrain 0.1.0__tar.gz → 0.1.1__tar.gz

codebrain-0.1.1/PKG-INFO

@@ -0,0 +1,388 @@
+Metadata-Version: 2.4
+Name: codebrain
+Version: 0.1.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
+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
+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
+```
+
+That's it. Now you can:
+
+```bash
+brain impact my_function    # What breaks if I change this?
+brain health                # Codebase health score (0-100)
+brain hotspots              # Riskiest symbols in the codebase
+brain deadcode              # Unused functions with confidence levels
+brain coupling              # Which files are too tightly coupled?
+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 agent    # 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 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]` |
+| TypeScript (fallback) | regex | Experimental — used when tree-sitter not installed |
+
+### Adding Languages
+
+Implement `BaseParser` and register via entry points:
+
+```python
+from codebrain.parser.base import BaseParser
+from codebrain.parser.models import ParsedFile
+
+class RustParser(BaseParser):
+    def extensions(self) -> frozenset[str]:
+        return frozenset({".rs"})
+
+    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