codespine 0.1.1__py3-none-any.whl

codespine-0.1.1.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: codespine
+Version: 0.1.1
+Summary: Local Java code intelligence indexer backed by a graph database
+Author: CodeSpine contributors
+License: MIT License
+        
+        Copyright (c) 2026 CodeSpine 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/vinayak3022/codeSpine
+Project-URL: Repository, https://github.com/vinayak3022/codeSpine
+Project-URL: Issues, https://github.com/vinayak3022/codeSpine/issues
+Keywords: java,code-indexing,graph,kuzu,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: kuzu
+Requires-Dist: tree-sitter
+Requires-Dist: tree-sitter-java
+Requires-Dist: fastmcp
+Requires-Dist: psutil
+Requires-Dist: watchfiles
+Provides-Extra: ml
+Requires-Dist: sentence-transformers; extra == "ml"
+Requires-Dist: numpy; extra == "ml"
+Provides-Extra: community
+Requires-Dist: igraph; extra == "community"
+Requires-Dist: leidenalg; extra == "community"
+Provides-Extra: full
+Requires-Dist: sentence-transformers; extra == "full"
+Requires-Dist: numpy; extra == "full"
+Requires-Dist: igraph; extra == "full"
+Requires-Dist: leidenalg; extra == "full"
+Dynamic: license-file
+
+# CodeSpine
+
+CodeSpine is a Java-native code intelligence graph for coding agents.
+
+It indexes your Java codebase into a graph, then serves high-signal retrieval and
+analysis APIs over CLI + MCP for refactoring, impact analysis, architecture
+navigation, and safe change planning.
+
+## Why CodeSpine
+
+Most tools answer "where is this symbol?".
+CodeSpine answers:
+
+- What depends on this?
+- What else changed with this historically?
+- Is this dead or framework-exempt?
+- Which architectural cluster/flow is this in?
+- What changed between branches at symbol granularity?
+
+## Core Capabilities
+
+### 1) Hybrid Search (BM25 + Vector + Fuzzy + RRF)
+- Lexical ranking (BM25-based)
+- Semantic matching (local embeddings)
+- Typo-tolerant fuzzy matching
+- Reciprocal Rank Fusion with ranking multipliers
+
+### 2) Impact Analysis
+- Traverses call graph + type/inheritance edges + coupling edges
+- Groups results by depth (`1`, `2`, `3+`)
+- Carries confidence (`1.0`, `0.8`, `0.5`) per edge
+
+### 3) Java-Aware Dead Code Detection
+- Not just zero-callers: includes exemption passes for:
+- constructors, tests, `main(String[] args)`
+- override/interface contracts
+- common lifecycle/framework annotations
+- reflection/bean-friendly method patterns
+
+### 4) Execution Flow Tracing
+- Detects framework-agnostic entry points (`main`, tests, public roots)
+- BFS flow traces with depth
+- Flow classification (`intra_community`, `cross_community`)
+
+### 5) Community Detection
+- Leiden-based clustering when dependencies are present
+- Heuristic fallback when Leiden stack is unavailable
+- Queryable symbol-to-community mapping
+
+### 6) Git Change Coupling
+- Mines recent git history (default 6 months)
+- Links co-changing files with coupling strength
+- Surfaces hidden dependencies in impact workflows
+
+### 7) Watch Mode
+- Live file watching for changed Java files
+- Incremental reindexing
+- Periodic global refresh phases (community/flow/deadcode/coupling)
+
+### 8) Branch Diff (Symbol-Level)
+- Uses git worktrees
+- Diffs class/method symbols (`added`, `removed`, `modified`)
+- Uses normalized structural hashes to reduce formatting-only noise
+
+## Performance Model
+
+CodeSpine includes:
+- Hash-based incremental invalidation (only changed files reindexed)
+- Persistent embedding cache (`sqlite`) for repeat semantic queries
+- Transactional write path during indexing to reduce commit overhead
+
+## Install
+
+### Local editable install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+If your environment is externally managed (PEP 668), use a virtualenv as above.
+
+You can also use `pip3`:
+
+```bash
+pip3 install -e .
+```
+
+### Install from GitHub
+
+```bash
+pip install "git+https://github.com/vinayak3022/codeSpine.git"
+```
+
+or
+
+```bash
+pip3 install "git+https://github.com/vinayak3022/codeSpine.git"
+```
+
+### Install from PyPI (after first release is published)
+
+```bash
+pip install codespine
+```
+
+or
+
+```bash
+pip3 install codespine
+```
+
+### Optional extras
+
+- `pip install -e .[ml]` for local embedding model dependencies
+- `pip install -e .[community]` for Leiden community detection stack
+- `pip install -e .[full]` for all optional features
+
+## Quick Start
+
+```bash
+# 1) index a repo
+codespine analyse /path/to/java-project --full
+
+# 2) search by concept/typo/name
+codespine search "payment validation typo procss" --k 20 --json
+
+# 3) get actionable context in one call
+codespine context "processPayment" --max-depth 3 --json
+
+# 4) estimate blast radius before refactor
+codespine impact com.example.Service#processPayment(java.lang.String) --max-depth 4 --json
+```
+
+Example output:
+
+```text
+$ codespine analyse .
+Walking files...               142 files found
+Parsing code...                142/142
+Tracing calls...               847 calls resolved
+Analyzing types...             234 type relationships
+Detecting communities...       8 clusters found
+Detecting execution flows...   34 processes found
+Finding dead code...           12 unreachable symbols
+Analyzing git history...       18 coupled file pairs
+Generating embeddings...       623 vectors stored
+
+Done in 4.2s - 623 symbols, 1847 edges, 8 clusters, 34 flows
+```
+
+## CLI Commands
+
+### Indexing and Retrieval
+- `codespine analyse <path> [--full|--incremental]`
+- `codespine search <query> [--k 20] [--json]`
+- `codespine context <query> [--max-depth 3] [--json]`
+
+### Analysis
+- `codespine impact <symbol> [--max-depth 4] [--json]`
+- `codespine deadcode [--limit 200] [--json]`
+- `codespine flow [--entry <symbol>] [--max-depth 6] [--json]`
+- `codespine community [--symbol <symbol>] [--json]`
+- `codespine coupling [--months 6] [--min-strength 0.3] [--min-cochanges 3] [--json]`
+
+### Operations
+- `codespine watch [--path .] [--global-interval 30]`
+- `codespine diff <base>..<head> [--json]`
+- `codespine cypher <query> [--json]`
+- `codespine list [--json]`
+- `codespine stats`
+- `codespine status [--json]`
+- `codespine setup`
+- `codespine clean [--force]`
+
+### MCP Service
+- `codespine start`
+- `codespine stop`
+- `codespine serve` (alias of `start`)
+- `codespine mcp` (foreground stdio MCP)
+
+## MCP JSON (Paste Into `mcp.json`)
+
+Use this if your MCP client supports stdio servers:
+
+```json
+{
+  "mcpServers": {
+    "codespine": {
+      "command": "codespine",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+If `codespine` is not on your PATH, use an absolute path for `command`, for example:
+- macOS/Linux: `"/Users/<you>/path/to/venv/bin/codespine"`
+- Windows: `"C:\\\\Users\\\\<you>\\\\path\\\\to\\\\venv\\\\Scripts\\\\codespine.exe"`
+
+Optional working directory (recommended for repo-scoped usage):
+
+```json
+{
+  "mcpServers": {
+    "codespine": {
+      "command": "codespine",
+      "args": ["mcp"],
+      "cwd": "/absolute/path/to/your/repo"
+    }
+  }
+}
+```
+
+## MCP Tool Surface
+
+- `search_hybrid(query, k=20)`
+- `get_symbol_context(query, max_depth=3)`
+- `get_impact(symbol, max_depth=4)`
+- `detect_dead_code(limit=200)`
+- `trace_execution_flows(entry_symbol=None, max_depth=6)`
+- `get_symbol_community(symbol)`
+- `get_change_coupling(symbol=None, months=6, min_strength=0.3, min_cochanges=3)`
+- `compare_branches(base_ref, head_ref)`
+- `get_codebase_stats()`
+- `run_cypher(query)`
+
+## Runtime Artifacts
+
+- Graph DB: `~/.codespine_db`
+- MCP PID: `~/.codespine.pid`
+- Log file: `~/.codespine.log`
+- Embedding cache: `~/.codespine_embedding_cache.sqlite3`
+
+## Architecture
+
+- `codespine/indexer`: Java parsing, symbols, call/type resolution
+- `codespine/db`: Kuzu schema and persistence
+- `codespine/search`: BM25/fuzzy/vector/RRF ranking
+- `codespine/analysis`: impact/deadcode/flow/community/coupling/context
+- `codespine/diff`: branch comparison at symbol level
+- `codespine/watch`: incremental watch pipeline
+- `codespine/mcp`: MCP tool server
+- `codespine/noise`: noise blocklists for cleaner call graphs
+
+## Security and Governance
+
+- Security policy: [`SECURITY.md`](SECURITY.md)
+- Contributions: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Code of conduct: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
+- Branch protection runbook: [`docs/GITHUB_HARDENING.md`](docs/GITHUB_HARDENING.md)
+
+## Publish to PyPI
+
+This repo includes a release workflow:
+- [`.github/workflows/publish-pypi.yml`](.github/workflows/publish-pypi.yml)
+
+Recommended setup (one-time):
+1. Create project on PyPI with the same name (`codespine`) or update `project.name` if unavailable.
+2. In PyPI, configure Trusted Publisher for this GitHub repo/workflow.
+3. In GitHub, keep the `pypi` environment enabled for publishing.
+
+Release flow:
+1. Bump version in [`pyproject.toml`](pyproject.toml).
+2. Push commit + tag (for example `v0.1.1`).
+3. Create a GitHub Release for that tag.
+4. Workflow builds and publishes to PyPI.
+
+## Compatibility
+
+`gindex.py` is retained as a compatibility shim for one release cycle.

codespine-0.1.1.dist-info/RECORD

@@ -0,0 +1,39 @@
+gindex.py,sha256=7NSmClZCWa0ARVqXM09jyIXGxVjRc-mVcF2QDlvEIuI,169
+codespine/__init__.py,sha256=5aaoIp-rA1JOeaTFJxjCwOrChrNhDpUMiYny7Vt2pbQ,74
+codespine/cli.py,sha256=W-2JeS6mpbBtaI4yM9zXQYFGlVGC_K2WvmDfrq4YCrY,14206
+codespine/config.py,sha256=73jPc7I7hmTGQwDQBB4SIosYT3D5beizmJfvn_iNInE,703
+codespine/analysis/__init__.py,sha256=zLRH3k4xSrYnDqMZpDNUZm2ee3GPpAfMVj0bZe82E0U,22
+codespine/analysis/community.py,sha256=t9aiwzke18EVIFNMoqwKcfnxQS6wO82KjnyL0QNsfwU,2481
+codespine/analysis/context.py,sha256=dPx9aIbmon0g7J8hrImkoo2x8CJxrLojqRg-0N4zM5g,835
+codespine/analysis/coupling.py,sha256=X9oO45Tn14CDuWdpJyBrKxW-EaEayfN9NHoBLxZq2qc,3759
+codespine/analysis/deadcode.py,sha256=h4vJRrzfoZrHy2EXzfhyB_fuCrrIuDdUS_zG2a4Li_E,3150
+codespine/analysis/flow.py,sha256=JbxbDXyQfc19aqNz75cALBVc44cm165w8_Cb5fAbNYw,2087
+codespine/analysis/impact.py,sha256=oC7mST1d3g-PKVqrEC-BQPTxEB5dVaSyLArlzXZ3DaI,2989
+codespine/db/__init__.py,sha256=_QXJZCVeKqgdDYTMyf47u_yObQIeCxIz0OX2DrflNyc,22
+codespine/db/schema.py,sha256=HT65ryh3zrc85XAwAbRBoNnyjDmnQPotFIZOPpcMAWI,3198
+codespine/db/store.py,sha256=KkxYBxyDg1aoa3M9zHz4zSykLlfPJ24M-igBwiS12lk,10129
+codespine/diff/__init__.py,sha256=gDcxDcXuz9sL-v3Rr0SfNmu0uijVl5jGuuGWkYFFyko,25
+codespine/diff/branch_diff.py,sha256=_TvYAoVRCFHMFljzVkvpf7alyKDieBTtcE1xf617eyI,5869
+codespine/indexer/__init__.py,sha256=TKtRH-o1DDSPDM_bYhUkA25HTJPIHXK9r-ZSIGkSgJA,22
+codespine/indexer/call_resolver.py,sha256=vN-X7C7h25iWp6za_-2zYJiWVXQCWJN3OWlvkIMWb-c,5012
+codespine/indexer/engine.py,sha256=QB5VUQ1C3GV686tUZ5eA4QjWh3tDlmfnDnnqdGaFcns,12890
+codespine/indexer/java_parser.py,sha256=nje9V01z7X9FYULziNROsmgpEdxJZKZt9bzAIFqxtxk,11037
+codespine/indexer/symbol_builder.py,sha256=Cz5E2xGvKt8gCvJz-bUZjhbpXhmaHa_IZVnJY0YwuY0,748
+codespine/mcp/__init__.py,sha256=T_yCmll9arlTWvxdvPq9TeycrCpoGjYzrS5yKMnTTDo,24
+codespine/mcp/server.py,sha256=EiSxLTSUPhdh3UjY7lLZkyWU_Q83nc9kYsdVFjl1tVI,2602
+codespine/noise/__init__.py,sha256=a6WKNhweMQPUxruPu4kBEWAAKIm7CdnekJpreewGJ64,29
+codespine/noise/blocklist.py,sha256=1zANch-RPUwO0l2jLhpN3EIMRb46CioNVtHkV236eNs,545
+codespine/search/__init__.py,sha256=3qP1vll_1PeFzp5Q3nbnBmONM64pk_4jLuKje65jzz0,20
+codespine/search/bm25.py,sha256=dQy6AaZrwIOLriyOswAwejCZcob-wtrQU5EmHx8i3N4,1604
+codespine/search/fuzzy.py,sha256=YBtdbM0KHUEdoX2FYwTPtLQs3PrcU2n5sc73CgXvLgw,1013
+codespine/search/hybrid.py,sha256=8c13546UsICG-5Oebef85gDD7NMvpt3OjC8YtaPsXg8,2561
+codespine/search/rrf.py,sha256=2itmNmQbyyY-zCl1aG2TxB_2PpttSj_3pdxR4SI4AEM,411
+codespine/search/vector.py,sha256=lSw_FXArYtIfDCrBZ82k4fXv8mL09mMvJrb1rVwng0I,3363
+codespine/watch/__init__.py,sha256=SxOnUvLuUf4Sci4QPNFkpe4x4HGr1Y_m_rlR-PrzSz4,24
+codespine/watch/watcher.py,sha256=fYjTec58UT3ICNTLX3eAc1Dj7L2sEL4iu_7voK7mS5s,1424
+codespine-0.1.1.dist-info/licenses/LICENSE,sha256=FWZ9PIBsrUyJqnVcXC5Fl3zHz2sPYqpII2hPm-zoZs4,1079
+codespine-0.1.1.dist-info/METADATA,sha256=5AN46PdV__g3YDAuThs6BPjVT8AoxfjTYxY1HicpSy4,10608
+codespine-0.1.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+codespine-0.1.1.dist-info/entry_points.txt,sha256=os-avtfI9gCs-VXuJu3gnZjv38uvQ_ErWaNXckclNHE,77
+codespine-0.1.1.dist-info/top_level.txt,sha256=49rqwCAK2fJYj9huu2caDRbpy5wVPL4GIRHpUiGCMDA,17
+codespine-0.1.1.dist-info/RECORD,,

codespine-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codespine-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+codespine = codespine.cli:main
+gindex = codespine.cli:main

codespine-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeSpine 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.

codespine-0.1.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+codespine
+gindex

gindex.py

@@ -0,0 +1,10 @@
+"""Compatibility shim for one release cycle.
+
+Use `codespine` CLI entrypoint moving forward.
+"""
+
+from codespine.cli import main
+
+
+if __name__ == "__main__":
+    main()