codespine 0.9.0__tar.gz → 0.9.1__tar.gz

{codespine-0.9.0 → codespine-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.9.0
+Version: 0.9.1
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -68,9 +68,9 @@ CodeSpine cuts token burn for coding agents working on Java codebases.
 
 Instead of having an agent open dozens of `.java` files to answer one question, CodeSpine indexes the codebase once and serves the structure over MCP. The agent asks for symbols, callers, impact, flows, dead code, and module boundaries directly, which means fewer file reads, fewer wasted context windows, and fewer hallucinated code paths.
 
-It indexes classes, methods, calls, type relationships, cross-module links, git coupling, dead-code candidates, and execution flows so agents can work from graph answers first and source files second.
+It indexes classes, methods, calls, type relationships, DI bindings, cross-module links, git coupling, dead-code candidates, and execution flows so agents can work from graph answers first and source files second.
 
-It also keeps a separate dirty overlay for uncommitted Java edits, so agents can query current work-in-progress without forcing the committed base index to churn on every save.
+File changes are written directly to the graph and are immediately queryable — no stale overlay merging, no OOM accumulation. The MCP daemon reloads from an atomic read replica the moment indexing or watch mode completes a batch.
 
 The MCP daemon and the indexer run independently. Querying while a full re-index is running no longer causes crashes or memory contention — reads go to an isolated snapshot that is atomically updated when indexing completes.
 
@@ -78,9 +78,10 @@ The MCP daemon and the indexer run independently. Querying while a full re-index
 
 - One MCP call can replace many file opens. `get_symbol_context("PaymentService")` returns a resolved neighborhood instead of forcing the agent to read every caller and callee file manually.
 - Search is structure-aware. Agents can ask for a symbol, concept, impact radius, or dead-code candidate without scanning entire packages.
+- DI bindings are first-class. `@Inject`, `@Autowired`, `@Bean`, and `@Provides` edges are resolved and included in impact analysis — Spring and Guice consumers are never missed.
 - Multi-module repos stay scoped. Project-aware IDs and `project=` parameters reduce noise from unrelated modules and workspaces.
 - Repeat sessions get cheaper. Once indexed, the agent reuses the graph instead of re-discovering the same relationships every turn.
-- Active edits stay smooth. Dirty files are kept in an overlay and merged into fast queries until you commit, instead of hammering the main graph DB on each change.
+- Active edits are visible immediately. Watch mode writes changes directly to the graph (not a slow overlay), so every MCP query reflects the latest file save.
 
 ## Install
 
@@ -96,8 +97,9 @@ pip install "codespine[ml]"
 
 ## What It Does
 
-- Hybrid search: BM25 + fuzzy by default, semantic vector search with `--embed`
-- Impact analysis: callers, dependencies, and confidence-scored edges
+- Hybrid search: BM25 + fuzzy by default, semantic vector search with `--embed`; results carry `high/medium/low` confidence scores
+- Impact analysis: callers, DI consumers, and confidence-scored edges; same-class callers separated from cross-class ones
+- DI analysis: `@Inject`/`@Autowired`/`@Bean`/`@Provides` edges resolved into `INJECTS` + `BINDS_INTERFACE` graph relationships
 - Dead code detection: Java-aware exemptions for tests, framework hooks, contracts, and common DI patterns
 - Execution flows: traces from entry points through the call graph
 - Community detection: structural clusters for architectural context
@@ -105,33 +107,42 @@ pip install "codespine[ml]"
 - Multi-project and multi-module indexing: workspaces, Maven modules, Gradle subprojects
 - Cross-module call linking: signature-based detection of calls between Maven/Gradle modules
 - Concurrent read/write isolation: MCP queries run against a read replica; the indexer writes separately, with no memory contention
-- MCP server: structured tools for Claude, Cursor, Cline, Copilot, and similar clients
+- Git commit hook: optional post-commit hook re-indexes only the changed files within seconds
+- MCP server: 44 structured tools for Claude, Cursor, Cline, Copilot, and similar clients
 
-## Editing Without Stale Indexes
+## Instant Change Visibility
 
-CodeSpine uses a two-layer model:
+CodeSpine writes file changes directly to the graph — no O(N) overlay merging on every query.
 
-- Base index: last committed state
-- Dirty overlay: uncommitted Java changes
+When `codespine watch` detects a file save:
+1. Parses the changed file with tree-sitter
+2. Atomically clears then re-writes that file's methods, calls, and type relationships
+3. Snapshots the write DB to the read replica
+4. The MCP server picks up the new snapshot on its next tool call
 
-Fast tools read merged `base + overlay` state by default:
+The result is that every tool — `search_hybrid`, `get_impact`, `get_symbol_context`, `find_injections`, and all others — reflects unsaved work within the debounce window (default 1–2 s).
 
-- `search`
-- `context`
-- `impact`
-- MCP `search_hybrid`
-- MCP `find_symbol`
-- MCP `get_symbol_context`
-- MCP `get_impact`
+### Git Commit Auto Re-index
 
-Deep analyses stay committed-only until promotion:
+Watch mode polls `git HEAD` every 5 seconds. When HEAD changes it uses `git diff --name-only` to find only the modified Java files and re-indexes those — not the entire project.
 
-- `deadcode`
-- `flow`
-- `community`
-- `coupling`
+You can also install an optional post-commit hook so re-indexing fires immediately on every commit:
 
-`codespine watch` updates the dirty overlay after a debounce window, then promotes it into the base index when local `HEAD` changes.
+```bash
+codespine watch --path . --install-hook
+```
+
+Or via MCP:
+
+```python
+start_watch(path=".", install_hook=True)
+```
+
+The hook is idempotent and can be removed with:
+
+```bash
+codespine watch --uninstall-hook --path .
+```
 
 ## Quick Start
 
@@ -161,6 +172,7 @@ Walking files...               142 files found
 Index mode...                  incremental (8 files to index, 0 deleted)
 Parsing code...                8/8
 Tracing calls...               847 calls resolved
+Analyzing DI bindings...       63 INJECTS edges, 14 BINDS_INTERFACE edges
 Analyzing types...             234 type relationships
 Cross-module linking...        skipped (single module)
 Detecting communities...       loading symbols
@@ -254,8 +266,8 @@ codespine guide --json   # structured JSON for tooling
 
 | Tool | Description |
 |------|-------------|
-| `search_hybrid(query, k, project)` | Ranked symbol search (BM25 + vector + fuzzy via RRF). |
-| `find_symbol(name, kind, project, limit)` | Exact/prefix name lookup across all projects. |
+| `search_hybrid(query, k, project)` | Ranked symbol search (BM25 + vector + fuzzy via RRF) with confidence scores. |
+| `find_symbol(name, kind, project, limit)` | Exact/prefix name lookup; returns `primary_match` flag and disambiguated results. |
 | `get_symbol_context(query, max_depth, project)` | One-shot deep context: search + impact + community + flows. |
 | `get_neighborhood(symbol, project)` | Callers, callees, siblings, and override/implements. |
 
@@ -263,12 +275,32 @@ codespine guide --json   # structured JSON for tooling
 
 | Tool | Description |
 |------|-------------|
-| `get_impact(symbol, max_depth, project)` | Caller-tree impact analysis with confidence scores. |
+| `get_impact(symbol, max_depth, project)` | Caller-tree impact analysis including DI consumers. Same-class callers in `self_callers`; cross-class in `impacted_callers`. |
+| `find_injections(symbol, project)` | All classes that `@Inject`/`@Autowired` a given type, and all `@Bean`/`@Provides` providers. |
 | `detect_dead_code(limit, project, strict)` | Methods with no callers (Java-aware exemptions). |
 | `trace_execution_flows(entry_symbol, max_depth, project)` | Execution paths from entry points. |
 | `get_symbol_community(symbol)` | Architectural community cluster for a symbol. |
 | `get_change_coupling(days, min_strength, min_cochanges)` | Files that changed together in the last N days (default 5). |
 
+**LLM-Native Tools**
+
+Higher-level tools designed to answer full agent questions in a single call:
+
+| Tool | Description |
+|------|-------------|
+| `ask(question, project)` | Answer a free-form question about the codebase using indexed structure. |
+| `what_breaks(symbol, project)` | Plain-English summary of what could break if this symbol changes. |
+| `explain(symbol, project)` | Explain what a class or method does and how it fits in the architecture. |
+| `read_symbols(symbols, project)` | Bulk-resolve a list of symbol names to context in one call. |
+| `semantic_summary(query, project)` | Narrative summary of modules or concepts matching a query. |
+| `get_api_surface(project)` | All public entry points: REST controllers, gRPC services, CLI commands. |
+| `file_context(file_path, project)` | Everything known about a file: classes, methods, callers, type deps. |
+| `pre_flight_check(project)` | Readiness report: index freshness, coverage, missing embeddings, DI gaps. |
+| `related(symbol, project)` | Symbols structurally or semantically related to the given one. |
+| `test_coverage(symbol, project)` | Test classes and methods that exercise the given symbol. |
+| `diff_impact(base_ref, head_ref, project)` | Impact analysis scoped to the symbols changed between two git refs. |
+| `find_pattern(pattern, project)` | Find code matching a structural or naming pattern across the codebase. |
+
 **Git**
 
 | Tool | Description |
@@ -283,8 +315,8 @@ codespine guide --json   # structured JSON for tooling
 |------|-------------|
 | `analyse_project(path, full, deep, embed)` | Index a Java project (background job). |
 | `get_analyse_status()` | Poll analysis progress. |
-| `reindex_file(file_path, project)` | Re-index a single `.java` file (<1 s). |
-| `start_watch(path)` | Watch for `.java` changes and update overlay in real time. |
+| `reindex_file(file_path, project)` | Re-index a single `.java` file (<1 s). Changes are immediately queryable. |
+| `start_watch(path, install_hook)` | Watch for `.java` changes and write directly to graph in real time. Pass `install_hook=True` to also install a post-commit git hook. |
 | `stop_watch()` | Stop the background watch process. |
 | `get_watch_status()` | Watch mode status: running, path, uptime. |
 
@@ -318,12 +350,13 @@ codespine analyse <path>                     # incremental index
 codespine analyse <path> --full              # full re-index
 codespine analyse <path> --deep              # + communities, flows, dead code, coupling
 codespine analyse <path> --embed             # + vector embeddings
-codespine watch --path .                     # live re-index on file changes
+codespine watch --path .                     # live re-index on file changes (direct-to-graph)
+codespine watch --path . --install-hook      # also install post-commit git hook
 
 # Search & Analysis
 codespine search "query"                     # hybrid search
 codespine context "symbol"                   # one-shot deep context
-codespine impact "symbol"                    # caller-tree impact
+codespine impact "symbol"                    # caller-tree impact (includes DI consumers)
 codespine deadcode                           # dead code candidates
 codespine flow                               # execution flows
 codespine community                          # architectural clusters
@@ -370,6 +403,30 @@ Project IDs are:
 
 That same project ID can be passed into MCP tools and CLI analysis calls that support project scoping.
 
+## DI / Injection Analysis
+
+CodeSpine resolves dependency injection bindings at index time and stores them as first-class graph edges.
+
+**What is indexed:**
+
+- `@Inject` / `@Autowired` fields → `INJECTS(consumer → provider, confidence=0.85)`
+- `@Provides` / `@Bean` methods → `INJECTS(config → return_type, confidence=0.90)`
+- `@Component` / `@Service` implementing an interface → `BINDS_INTERFACE(impl → interface, confidence=0.95)`
+
+**How it affects existing tools:**
+
+- `get_impact("PaymentService")` now includes all classes that inject `PaymentService`, not just direct callers.
+- `detect_dead_code` skips classes referenced only via DI edges.
+
+**New tool:**
+
+```python
+find_injections("PaymentProcessor")
+# → all @Inject/@Autowired consumers
+# → all @Bean/@Provides providers
+# → all @Component/@Service implementations of the interface
+```
+
 ## Deep Analysis Trade-Offs
 
 `--deep` enables the expensive graph-wide passes:
@@ -381,8 +438,6 @@ That same project ID can be passed into MCP tools and CLI analysis calls that su
 
 Use it when you want architecture-level context. Skip it when you just need the graph refreshed for search, context, and impact.
 
-When a dirty overlay exists, deep-analysis results intentionally exclude those uncommitted edits until promotion.
-
 `--embed` is also optional. Without it, CodeSpine still supports exact, keyword, and fuzzy search. Add embeddings when you need concept-level retrieval.
 
 ## Concurrent Indexing and Querying
@@ -405,12 +460,13 @@ Running `codespine analyse --deep --embed` on one project while querying a diffe
 - `~/.codespine.log` - server log
 - `~/.codespine_embedding_cache.json` - embedding cache
 - `~/.codespine_index_meta/` - incremental file metadata cache
-- `~/.codespine_overlay/` - uncommitted dirty overlay state
+- `~/.codespine_overlay/` - uncommitted dirty overlay state (legacy; direct-to-graph is now the primary path)
 
 ## Notes
 
 - `codespine start` launches a background MCP server. Most IDE MCP clients should use `codespine mcp` instead and manage the process themselves.
-- `codespine watch` updates the dirty overlay first; it does not rewrite the committed base index on every save.
+- `codespine watch` writes changes directly to the graph and snapshots the read replica after each batch. MCP queries reflect file saves within the debounce window.
+- `git HEAD` is polled every 5 seconds. On a new commit, only the changed Java files are re-indexed using `git diff --name-only`, not the full project.
 - `codespine clear-index` rebuilds the local index database from scratch. This also removes the read replica; run `analyse` again to republish it.
 - `codespine force-reset` is the nuclear option — it deletes all data files without going through the DB engine. Use it when `clear-index` fails due to DB corruption.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.

{codespine-0.9.0 → codespine-0.9.1}/README.md

@@ -4,9 +4,9 @@ CodeSpine cuts token burn for coding agents working on Java codebases.
 
 Instead of having an agent open dozens of `.java` files to answer one question, CodeSpine indexes the codebase once and serves the structure over MCP. The agent asks for symbols, callers, impact, flows, dead code, and module boundaries directly, which means fewer file reads, fewer wasted context windows, and fewer hallucinated code paths.
 
-It indexes classes, methods, calls, type relationships, cross-module links, git coupling, dead-code candidates, and execution flows so agents can work from graph answers first and source files second.
+It indexes classes, methods, calls, type relationships, DI bindings, cross-module links, git coupling, dead-code candidates, and execution flows so agents can work from graph answers first and source files second.
 
-It also keeps a separate dirty overlay for uncommitted Java edits, so agents can query current work-in-progress without forcing the committed base index to churn on every save.
+File changes are written directly to the graph and are immediately queryable — no stale overlay merging, no OOM accumulation. The MCP daemon reloads from an atomic read replica the moment indexing or watch mode completes a batch.
 
 The MCP daemon and the indexer run independently. Querying while a full re-index is running no longer causes crashes or memory contention — reads go to an isolated snapshot that is atomically updated when indexing completes.
 
@@ -14,9 +14,10 @@ The MCP daemon and the indexer run independently. Querying while a full re-index
 
 - One MCP call can replace many file opens. `get_symbol_context("PaymentService")` returns a resolved neighborhood instead of forcing the agent to read every caller and callee file manually.
 - Search is structure-aware. Agents can ask for a symbol, concept, impact radius, or dead-code candidate without scanning entire packages.
+- DI bindings are first-class. `@Inject`, `@Autowired`, `@Bean`, and `@Provides` edges are resolved and included in impact analysis — Spring and Guice consumers are never missed.
 - Multi-module repos stay scoped. Project-aware IDs and `project=` parameters reduce noise from unrelated modules and workspaces.
 - Repeat sessions get cheaper. Once indexed, the agent reuses the graph instead of re-discovering the same relationships every turn.
-- Active edits stay smooth. Dirty files are kept in an overlay and merged into fast queries until you commit, instead of hammering the main graph DB on each change.
+- Active edits are visible immediately. Watch mode writes changes directly to the graph (not a slow overlay), so every MCP query reflects the latest file save.
 
 ## Install
 
@@ -32,8 +33,9 @@ pip install "codespine[ml]"
 
 ## What It Does
 
-- Hybrid search: BM25 + fuzzy by default, semantic vector search with `--embed`
-- Impact analysis: callers, dependencies, and confidence-scored edges
+- Hybrid search: BM25 + fuzzy by default, semantic vector search with `--embed`; results carry `high/medium/low` confidence scores
+- Impact analysis: callers, DI consumers, and confidence-scored edges; same-class callers separated from cross-class ones
+- DI analysis: `@Inject`/`@Autowired`/`@Bean`/`@Provides` edges resolved into `INJECTS` + `BINDS_INTERFACE` graph relationships
 - Dead code detection: Java-aware exemptions for tests, framework hooks, contracts, and common DI patterns
 - Execution flows: traces from entry points through the call graph
 - Community detection: structural clusters for architectural context
@@ -41,33 +43,42 @@ pip install "codespine[ml]"
 - Multi-project and multi-module indexing: workspaces, Maven modules, Gradle subprojects
 - Cross-module call linking: signature-based detection of calls between Maven/Gradle modules
 - Concurrent read/write isolation: MCP queries run against a read replica; the indexer writes separately, with no memory contention
-- MCP server: structured tools for Claude, Cursor, Cline, Copilot, and similar clients
+- Git commit hook: optional post-commit hook re-indexes only the changed files within seconds
+- MCP server: 44 structured tools for Claude, Cursor, Cline, Copilot, and similar clients
 
-## Editing Without Stale Indexes
+## Instant Change Visibility
 
-CodeSpine uses a two-layer model:
+CodeSpine writes file changes directly to the graph — no O(N) overlay merging on every query.
 
-- Base index: last committed state
-- Dirty overlay: uncommitted Java changes
+When `codespine watch` detects a file save:
+1. Parses the changed file with tree-sitter
+2. Atomically clears then re-writes that file's methods, calls, and type relationships
+3. Snapshots the write DB to the read replica
+4. The MCP server picks up the new snapshot on its next tool call
 
-Fast tools read merged `base + overlay` state by default:
+The result is that every tool — `search_hybrid`, `get_impact`, `get_symbol_context`, `find_injections`, and all others — reflects unsaved work within the debounce window (default 1–2 s).
 
-- `search`
-- `context`
-- `impact`
-- MCP `search_hybrid`
-- MCP `find_symbol`
-- MCP `get_symbol_context`
-- MCP `get_impact`
+### Git Commit Auto Re-index
 
-Deep analyses stay committed-only until promotion:
+Watch mode polls `git HEAD` every 5 seconds. When HEAD changes it uses `git diff --name-only` to find only the modified Java files and re-indexes those — not the entire project.
 
-- `deadcode`
-- `flow`
-- `community`
-- `coupling`
+You can also install an optional post-commit hook so re-indexing fires immediately on every commit:
 
-`codespine watch` updates the dirty overlay after a debounce window, then promotes it into the base index when local `HEAD` changes.
+```bash
+codespine watch --path . --install-hook
+```
+
+Or via MCP:
+
+```python
+start_watch(path=".", install_hook=True)
+```
+
+The hook is idempotent and can be removed with:
+
+```bash
+codespine watch --uninstall-hook --path .
+```
 
 ## Quick Start
 
@@ -97,6 +108,7 @@ Walking files...               142 files found
 Index mode...                  incremental (8 files to index, 0 deleted)
 Parsing code...                8/8
 Tracing calls...               847 calls resolved
+Analyzing DI bindings...       63 INJECTS edges, 14 BINDS_INTERFACE edges
 Analyzing types...             234 type relationships
 Cross-module linking...        skipped (single module)
 Detecting communities...       loading symbols
@@ -190,8 +202,8 @@ codespine guide --json   # structured JSON for tooling
 
 | Tool | Description |
 |------|-------------|
-| `search_hybrid(query, k, project)` | Ranked symbol search (BM25 + vector + fuzzy via RRF). |
-| `find_symbol(name, kind, project, limit)` | Exact/prefix name lookup across all projects. |
+| `search_hybrid(query, k, project)` | Ranked symbol search (BM25 + vector + fuzzy via RRF) with confidence scores. |
+| `find_symbol(name, kind, project, limit)` | Exact/prefix name lookup; returns `primary_match` flag and disambiguated results. |
 | `get_symbol_context(query, max_depth, project)` | One-shot deep context: search + impact + community + flows. |
 | `get_neighborhood(symbol, project)` | Callers, callees, siblings, and override/implements. |
 
@@ -199,12 +211,32 @@ codespine guide --json   # structured JSON for tooling
 
 | Tool | Description |
 |------|-------------|
-| `get_impact(symbol, max_depth, project)` | Caller-tree impact analysis with confidence scores. |
+| `get_impact(symbol, max_depth, project)` | Caller-tree impact analysis including DI consumers. Same-class callers in `self_callers`; cross-class in `impacted_callers`. |
+| `find_injections(symbol, project)` | All classes that `@Inject`/`@Autowired` a given type, and all `@Bean`/`@Provides` providers. |
 | `detect_dead_code(limit, project, strict)` | Methods with no callers (Java-aware exemptions). |
 | `trace_execution_flows(entry_symbol, max_depth, project)` | Execution paths from entry points. |
 | `get_symbol_community(symbol)` | Architectural community cluster for a symbol. |
 | `get_change_coupling(days, min_strength, min_cochanges)` | Files that changed together in the last N days (default 5). |
 
+**LLM-Native Tools**
+
+Higher-level tools designed to answer full agent questions in a single call:
+
+| Tool | Description |
+|------|-------------|
+| `ask(question, project)` | Answer a free-form question about the codebase using indexed structure. |
+| `what_breaks(symbol, project)` | Plain-English summary of what could break if this symbol changes. |
+| `explain(symbol, project)` | Explain what a class or method does and how it fits in the architecture. |
+| `read_symbols(symbols, project)` | Bulk-resolve a list of symbol names to context in one call. |
+| `semantic_summary(query, project)` | Narrative summary of modules or concepts matching a query. |
+| `get_api_surface(project)` | All public entry points: REST controllers, gRPC services, CLI commands. |
+| `file_context(file_path, project)` | Everything known about a file: classes, methods, callers, type deps. |
+| `pre_flight_check(project)` | Readiness report: index freshness, coverage, missing embeddings, DI gaps. |
+| `related(symbol, project)` | Symbols structurally or semantically related to the given one. |
+| `test_coverage(symbol, project)` | Test classes and methods that exercise the given symbol. |
+| `diff_impact(base_ref, head_ref, project)` | Impact analysis scoped to the symbols changed between two git refs. |
+| `find_pattern(pattern, project)` | Find code matching a structural or naming pattern across the codebase. |
+
 **Git**
 
 | Tool | Description |
@@ -219,8 +251,8 @@ codespine guide --json   # structured JSON for tooling
 |------|-------------|
 | `analyse_project(path, full, deep, embed)` | Index a Java project (background job). |
 | `get_analyse_status()` | Poll analysis progress. |
-| `reindex_file(file_path, project)` | Re-index a single `.java` file (<1 s). |
-| `start_watch(path)` | Watch for `.java` changes and update overlay in real time. |
+| `reindex_file(file_path, project)` | Re-index a single `.java` file (<1 s). Changes are immediately queryable. |
+| `start_watch(path, install_hook)` | Watch for `.java` changes and write directly to graph in real time. Pass `install_hook=True` to also install a post-commit git hook. |
 | `stop_watch()` | Stop the background watch process. |
 | `get_watch_status()` | Watch mode status: running, path, uptime. |
 
@@ -254,12 +286,13 @@ codespine analyse <path>                     # incremental index
 codespine analyse <path> --full              # full re-index
 codespine analyse <path> --deep              # + communities, flows, dead code, coupling
 codespine analyse <path> --embed             # + vector embeddings
-codespine watch --path .                     # live re-index on file changes
+codespine watch --path .                     # live re-index on file changes (direct-to-graph)
+codespine watch --path . --install-hook      # also install post-commit git hook
 
 # Search & Analysis
 codespine search "query"                     # hybrid search
 codespine context "symbol"                   # one-shot deep context
-codespine impact "symbol"                    # caller-tree impact
+codespine impact "symbol"                    # caller-tree impact (includes DI consumers)
 codespine deadcode                           # dead code candidates
 codespine flow                               # execution flows
 codespine community                          # architectural clusters
@@ -306,6 +339,30 @@ Project IDs are:
 
 That same project ID can be passed into MCP tools and CLI analysis calls that support project scoping.
 
+## DI / Injection Analysis
+
+CodeSpine resolves dependency injection bindings at index time and stores them as first-class graph edges.
+
+**What is indexed:**
+
+- `@Inject` / `@Autowired` fields → `INJECTS(consumer → provider, confidence=0.85)`
+- `@Provides` / `@Bean` methods → `INJECTS(config → return_type, confidence=0.90)`
+- `@Component` / `@Service` implementing an interface → `BINDS_INTERFACE(impl → interface, confidence=0.95)`
+
+**How it affects existing tools:**
+
+- `get_impact("PaymentService")` now includes all classes that inject `PaymentService`, not just direct callers.
+- `detect_dead_code` skips classes referenced only via DI edges.
+
+**New tool:**
+
+```python
+find_injections("PaymentProcessor")
+# → all @Inject/@Autowired consumers
+# → all @Bean/@Provides providers
+# → all @Component/@Service implementations of the interface
+```
+
 ## Deep Analysis Trade-Offs
 
 `--deep` enables the expensive graph-wide passes:
@@ -317,8 +374,6 @@ That same project ID can be passed into MCP tools and CLI analysis calls that su
 
 Use it when you want architecture-level context. Skip it when you just need the graph refreshed for search, context, and impact.
 
-When a dirty overlay exists, deep-analysis results intentionally exclude those uncommitted edits until promotion.
-
 `--embed` is also optional. Without it, CodeSpine still supports exact, keyword, and fuzzy search. Add embeddings when you need concept-level retrieval.
 
 ## Concurrent Indexing and Querying
@@ -341,12 +396,13 @@ Running `codespine analyse --deep --embed` on one project while querying a diffe
 - `~/.codespine.log` - server log
 - `~/.codespine_embedding_cache.json` - embedding cache
 - `~/.codespine_index_meta/` - incremental file metadata cache
-- `~/.codespine_overlay/` - uncommitted dirty overlay state
+- `~/.codespine_overlay/` - uncommitted dirty overlay state (legacy; direct-to-graph is now the primary path)
 
 ## Notes
 
 - `codespine start` launches a background MCP server. Most IDE MCP clients should use `codespine mcp` instead and manage the process themselves.
-- `codespine watch` updates the dirty overlay first; it does not rewrite the committed base index on every save.
+- `codespine watch` writes changes directly to the graph and snapshots the read replica after each batch. MCP queries reflect file saves within the debounce window.
+- `git HEAD` is polled every 5 seconds. On a new commit, only the changed Java files are re-indexed using `git diff --name-only`, not the full project.
 - `codespine clear-index` rebuilds the local index database from scratch. This also removes the read replica; run `analyse` again to republish it.
 - `codespine force-reset` is the nuclear option — it deletes all data files without going through the DB engine. Use it when `clear-index` fails due to DB corruption.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.

{codespine-0.9.0 → codespine-0.9.1}/codespine/__init__.py

@@ -1,4 +1,4 @@
 """CodeSpine package."""
 
 __all__ = ["__version__"]
-__version__ = "0.9.0"
+__version__ = "0.9.1"

{codespine-0.9.0 → codespine-0.9.1}/codespine/analysis/crossmodule.py

@@ -90,7 +90,31 @@ def link_cross_module_calls(store, project_ids: list[str] | None = None, progres
         if len(c["name"]) > _MIN_CLASS_NAME_LEN:
             classes_per_project[c["pid"]].add(c["name"])
 
-    # ── 3. Scan methods for cross-project type references ─────────────
+    # ── 3. Pre-load all destination-class methods in ONE bulk query ───────
+    # Collect every class ID that belongs to a project OTHER than its own so
+    # we can load their methods in one round-trip instead of one per class.
+    all_cross_cids: set[str] = set()
+    for c in all_classes:
+        if len(c["name"]) > _MIN_CLASS_NAME_LEN:
+            all_cross_cids.add(c["cid"])
+
+    _ping(f"loading methods for {len(all_cross_cids)} cross-module classes")
+    dst_methods_by_cid: dict[str, list[dict]] = defaultdict(list)
+    if all_cross_cids:
+        bulk = store.query_records(
+            """
+            MATCH (m:Method)
+            WHERE m.class_id IN $cids
+            RETURN m.id as mid, m.name as name, m.signature as sig,
+                   m.modifiers as modifiers, m.is_constructor as is_ctor,
+                   m.class_id as cid
+            """,
+            {"cids": list(all_cross_cids)},
+        )
+        for dm in bulk:
+            dst_methods_by_cid[dm["cid"]].append(dm)
+
+    # ── 4. Scan methods for cross-project type references ─────────────
     new_edges = 0
     seen: set[tuple[str, str]] = set()
 
@@ -127,19 +151,13 @@ def link_cross_module_calls(store, project_ids: list[str] | None = None, progres
             if not matched_class_names:
                 continue
 
-            # For each matched class, create CALLS edges
+            # For each matched class, create CALLS edges using pre-loaded methods.
             for class_name in matched_class_names:
                 for dst_cid, dst_pid in name_to_classes.get(class_name, []):
                     if dst_pid == src_pid:
                         continue  # same project — not cross-module
 
-                    # Get methods of the destination class
-                    dst_methods = store.query_records(
-                        """MATCH (m:Method) WHERE m.class_id = $cid
-                           RETURN m.id as mid, m.name as name, m.signature as sig,
-                                  m.modifiers as modifiers, m.is_constructor as is_ctor""",
-                        {"cid": dst_cid},
-                    )
+                    dst_methods = dst_methods_by_cid.get(dst_cid)
                     if not dst_methods:
                         continue
 

{codespine-0.9.0 → codespine-0.9.1}/codespine/db/store.py

@@ -820,15 +820,57 @@ class GraphStore:
             },
         )
 
+    # Lock and flag for background snapshot coalescing.
+    # Only one snapshot runs at a time; a pending request supersedes queued ones.
+    _snapshot_lock: threading.Lock = threading.Lock()
+    _snapshot_pending: threading.Event = threading.Event()
+
     @staticmethod
-    def snapshot_to_read_replica() -> bool:
+    def snapshot_to_read_replica(background: bool = False) -> bool:
         """Atomically copy the write DB to the read-replica path.
 
         The read replica is used by the MCP daemon and all read-only CLI
         commands so they never contend with the write process's buffer pool.
-        Returns True on success, False if the source DB does not exist.
+
+        Parameters
+        ----------
+        background:
+            When True the copy runs in a daemon thread and this call returns
+            immediately (always returns True). Only one copy runs at a time;
+            rapid successive background calls are coalesced — the next copy
+            starts only after the current one finishes, so the sentinel is
+            always written with the *latest* data.
+
+        Returns True on success (or when dispatched to background), False if
+        the source DB does not exist.
         """
         src = SETTINGS.db_path
+        if not os.path.exists(src):
+            return False
+
+        if background:
+            # Signal that a snapshot is wanted, then ensure a worker is running.
+            GraphStore._snapshot_pending.set()
+
+            def _worker() -> None:
+                while GraphStore._snapshot_pending.is_set():
+                    GraphStore._snapshot_pending.clear()
+                    with GraphStore._snapshot_lock:
+                        GraphStore._do_snapshot()
+
+            if not GraphStore._snapshot_lock.locked():
+                t = threading.Thread(target=_worker, daemon=True, name="codespine-snapshot")
+                t.start()
+            return True
+
+        # Foreground (blocking) path — used by CLI analyse and tests.
+        with GraphStore._snapshot_lock:
+            return GraphStore._do_snapshot()
+
+    @staticmethod
+    def _do_snapshot() -> bool:
+        """Perform the actual copy.  Must be called with _snapshot_lock held."""
+        src = SETTINGS.db_path
         dst = SETTINGS.db_snapshot_path
         if not os.path.exists(src):
             return False