codecortex 0.13.0__tar.gz → 0.13.1__tar.gz

{codecortex-0.13.0/src/codecortex.egg-info → codecortex-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.13.0
+Version: 0.13.1
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -111,7 +111,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
 - **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
 - **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
-- **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
+- **Fast on repeat, and the cache never lies.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index, so you never read a cached answer for code that moved on. The cache is bounded (LRU), so a long-running server holds steady memory. (The *cache* is always consistent with the index; how current the index itself is depends on the engine — see [Keeping answers fresh](#keeping-answers-fresh).)
 - **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
 - **Honest about its own health.** `codeintel doctor` answers three separate questions per engine — *installed?* *runnable?* *is this repo indexed?* — with the single command to fix each gap, so "installed" is never mistaken for "working". And a readiness claim is one a query can actually honor: install a missing backend mid-session and the running server picks it up on the next call, rather than reporting the engine healthy while quietly routing around it until you restart the host.
 
@@ -274,6 +274,28 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 
 Run `codeintel doctor` at any time to see which engines are actually ready for a repo and how to fix the ones that aren't.
 
+### Keeping answers fresh
+
+The three engines have genuinely different freshness models, and it's worth knowing which you're
+reading:
+
+| Engine | Freshness |
+|---|---|
+| `lsp` | **Live.** Reads your files at query time — always current, no refresh needed. |
+| `semantic` | **Incremental.** A background reindex re-embeds only what changed; `codeintel status` shows the index age. |
+| `graph` | **Snapshot.** Built by `codeintel index` and stale until the next one. |
+
+So a `callers`/`impact`/`hotspots` answer is only as current as your last index. If a result
+describes code you just changed — or a symbol you just added comes back
+`reason: "not-in-graph"` — that's the signal to re-run:
+
+```bash
+codeintel index /path/to/repo
+```
+
+The reply names the fix when it can: a missing symbol now returns a `hint` with the exact command
+rather than a bare reason.
+
 Pass `--engine auto` (the default) and codeintel chooses the best engine per operation. Pass `--engine both` or `--engine all` to fan out to multiple engines and merge results.
 
 ## Documentation
@@ -297,12 +319,12 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |
-| `codeintel query --op OP --target TARGET [--engine auto]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | Run a single query and print the result |
 | `codeintel status [project_root]` | Show engine availability and index age |
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel reset [project_root] [--all] [--yes]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
+| `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.

{codecortex-0.13.0 → codecortex-0.13.1}/README.md

@@ -74,7 +74,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
 - **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
 - **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
-- **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
+- **Fast on repeat, and the cache never lies.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index, so you never read a cached answer for code that moved on. The cache is bounded (LRU), so a long-running server holds steady memory. (The *cache* is always consistent with the index; how current the index itself is depends on the engine — see [Keeping answers fresh](#keeping-answers-fresh).)
 - **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
 - **Honest about its own health.** `codeintel doctor` answers three separate questions per engine — *installed?* *runnable?* *is this repo indexed?* — with the single command to fix each gap, so "installed" is never mistaken for "working". And a readiness claim is one a query can actually honor: install a missing backend mid-session and the running server picks it up on the next call, rather than reporting the engine healthy while quietly routing around it until you restart the host.
 
@@ -237,6 +237,28 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 
 Run `codeintel doctor` at any time to see which engines are actually ready for a repo and how to fix the ones that aren't.
 
+### Keeping answers fresh
+
+The three engines have genuinely different freshness models, and it's worth knowing which you're
+reading:
+
+| Engine | Freshness |
+|---|---|
+| `lsp` | **Live.** Reads your files at query time — always current, no refresh needed. |
+| `semantic` | **Incremental.** A background reindex re-embeds only what changed; `codeintel status` shows the index age. |
+| `graph` | **Snapshot.** Built by `codeintel index` and stale until the next one. |
+
+So a `callers`/`impact`/`hotspots` answer is only as current as your last index. If a result
+describes code you just changed — or a symbol you just added comes back
+`reason: "not-in-graph"` — that's the signal to re-run:
+
+```bash
+codeintel index /path/to/repo
+```
+
+The reply names the fix when it can: a missing symbol now returns a `hint` with the exact command
+rather than a bare reason.
+
 Pass `--engine auto` (the default) and codeintel chooses the best engine per operation. Pass `--engine both` or `--engine all` to fan out to multiple engines and merge results.
 
 ## Documentation
@@ -260,12 +282,12 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |
-| `codeintel query --op OP --target TARGET [--engine auto]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | Run a single query and print the result |
 | `codeintel status [project_root]` | Show engine availability and index age |
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel reset [project_root] [--all] [--yes]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
+| `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.

{codecortex-0.13.0 → codecortex-0.13.1/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.13.0
+Version: 0.13.1
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -111,7 +111,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
 - **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
 - **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
-- **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
+- **Fast on repeat, and the cache never lies.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index, so you never read a cached answer for code that moved on. The cache is bounded (LRU), so a long-running server holds steady memory. (The *cache* is always consistent with the index; how current the index itself is depends on the engine — see [Keeping answers fresh](#keeping-answers-fresh).)
 - **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
 - **Honest about its own health.** `codeintel doctor` answers three separate questions per engine — *installed?* *runnable?* *is this repo indexed?* — with the single command to fix each gap, so "installed" is never mistaken for "working". And a readiness claim is one a query can actually honor: install a missing backend mid-session and the running server picks it up on the next call, rather than reporting the engine healthy while quietly routing around it until you restart the host.
 
@@ -274,6 +274,28 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 
 Run `codeintel doctor` at any time to see which engines are actually ready for a repo and how to fix the ones that aren't.
 
+### Keeping answers fresh
+
+The three engines have genuinely different freshness models, and it's worth knowing which you're
+reading:
+
+| Engine | Freshness |
+|---|---|
+| `lsp` | **Live.** Reads your files at query time — always current, no refresh needed. |
+| `semantic` | **Incremental.** A background reindex re-embeds only what changed; `codeintel status` shows the index age. |
+| `graph` | **Snapshot.** Built by `codeintel index` and stale until the next one. |
+
+So a `callers`/`impact`/`hotspots` answer is only as current as your last index. If a result
+describes code you just changed — or a symbol you just added comes back
+`reason: "not-in-graph"` — that's the signal to re-run:
+
+```bash
+codeintel index /path/to/repo
+```
+
+The reply names the fix when it can: a missing symbol now returns a `hint` with the exact command
+rather than a bare reason.
+
 Pass `--engine auto` (the default) and codeintel chooses the best engine per operation. Pass `--engine both` or `--engine all` to fan out to multiple engines and merge results.
 
 ## Documentation
@@ -297,12 +319,12 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |
-| `codeintel query --op OP --target TARGET [--engine auto]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | Run a single query and print the result |
 | `codeintel status [project_root]` | Show engine availability and index age |
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel reset [project_root] [--all] [--yes]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
+| `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.

codecortex-0.13.1/src/codeintel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.13.1"

{codecortex-0.13.0 → codecortex-0.13.1}/src/codeintel/providers/graph.py

@@ -17,6 +17,36 @@ def _cypher_literal(s: Any) -> str:
     return str(s).replace("\\", "\\\\").replace('"', '\\"')
 
 
+# Every op _dispatch recognizes. Kept beside it so "unsupported op" and "op found nothing" stay
+# distinguishable — they were the same `None` before, and the resulting `unsupported-op` on a
+# perfectly supported `callers` was the most misleading string the never-raise envelope produced.
+_GRAPH_OPS = frozenset({
+    "impact", "context", "callers", "callees", "chain", "pattern",
+    "overview", "changed", "changes", "deadcode", "hotspots",
+})
+
+
+def _repo_display_name(root: str) -> str:
+    """The repo's own directory name, for headings a human will read.
+
+    Resolves first, because callers routinely pass "." (`codeintel map .`) — the basename of which
+    is "." and would title the committed map file with a dot."""
+    if not root:
+        return ""
+    try:
+        return os.path.basename(os.path.realpath(root).rstrip(os.sep))
+    except Exception:
+        return ""
+
+
+def _int_or_zero(value: Any) -> int:
+    """A node count from an untrusted backend payload, or 0 when it is missing/not a number."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
 class GraphProvider:
     """Wraps the codebase-memory-mcp CLI. Never raises.
 
@@ -118,7 +148,14 @@ class GraphProvider:
         The real codebase-memory-mcp returns ``{"projects": [...]}``; a bare list is the
         older/mocked shape — accept both. Prefer an exact ``root_path`` match; otherwise the
         LONGEST prefix match (so ``.../project/codeintel`` resolves to codeintel, not its
-        parent ``.../project``). Pure + static so ``_resolve_project`` and ``probe`` share it."""
+        parent ``.../project``). Static so ``_resolve_project`` and ``probe`` share it.
+
+        The backend can hold MORE THAN ONE project for the same root — typically one registered
+        under a short name and one under a path slug — and the two drift apart independently.
+        Returning the first match meant a query could be answered from a months-stale index while
+        a complete one sat beside it: observed on this repo as 1475 nodes vs 2631 for the same
+        path, which is how `callers` reported a function's pre-refactor shape hours after the
+        refactor. Among exact matches, prefer the most complete index."""
         # Normalize the input to an absolute realpath: the backend stores absolute root_paths, so a
         # relative ``project_root`` (e.g. `codeintel map .` passing ".") would otherwise never match
         # — the bug where the map/query silently reported "not indexed" from inside the repo.
@@ -129,7 +166,7 @@ class GraphProvider:
         entries = raw.get("projects", []) if isinstance(raw, dict) else raw
         if not isinstance(entries, list):
             return None
-        exact: str | None = None
+        exact: list[dict] = []
         best_prefix_len = -1
         best_prefix_name: str | None = None
         for entry in entries:
@@ -139,12 +176,22 @@ class GraphProvider:
             if not rp:
                 continue
             if rp == project_root:
-                exact = entry.get("name")
-                break
+                exact.append(entry)
+                continue
             if project_root.startswith(rp.rstrip("/") + "/") and len(rp) > best_prefix_len:
                 best_prefix_len = len(rp)
                 best_prefix_name = entry.get("name")
-        return exact if exact is not None else best_prefix_name
+
+        if exact:
+            # Node count is the available completeness signal — list_projects carries no indexed-at
+            # timestamp, and head_sha is recorded per registration rather than per index pass, so
+            # duplicates routinely report the same SHA with wildly different graphs. `max` keeps
+            # the FIRST maximal entry, so with no completeness signal to go on (ties, or a backend
+            # that omits `nodes`) this falls back to the original first-listed rule rather than
+            # inventing an ordering.
+            best = max(exact, key=lambda e: _int_or_zero(e.get("nodes")))
+            return best.get("name")
+        return best_prefix_name
 
     def _resolve_project(self, project_root: str) -> str | None:
         with self._project_cache_lock:
@@ -400,12 +447,17 @@ class GraphProvider:
         except Exception:
             return None
 
-    def _op_overview(self, target: str, project: str, timeout_ms: int) -> str | None:
+    def _op_overview(self, target: str, project: str, timeout_ms: int, root: str = "") -> str | None:
         try:
             raw = self._run("get_architecture", {"project": project}, timeout_ms)
             if not isinstance(raw, dict):
                 return None
-            name = str(raw.get("project") or project)
+            # Title with the REPO's own name, not the backend's project id. That id is often a
+            # flattened absolute path (`Users-alice-Documents-project-myrepo`), and this heading
+            # lands in CODE_INTEL.md — a file that gets committed and pushed, so an internal
+            # identifier there leaks the author's home directory layout into the repository.
+            name = _repo_display_name(root)
+            name = name or str(raw.get("project") or project)
             parts = [f"## Architecture: {name}"]
             tn, te = raw.get("total_nodes"), raw.get("total_edges")
             if tn is not None or te is not None:
@@ -592,10 +644,20 @@ class GraphProvider:
                     hint=f"run: codeintel index {root_str}  (or: codeintel doctor)",
                 )
 
-            result_text = self._dispatch(op_str, target_str, project, timeout_ms)
-            if result_text is None:
+            if op_str not in _GRAPH_OPS:
                 return safe_null_result(op_str, target_str, engine="graph", reason="unsupported-op")
 
+            result_text = self._dispatch(op_str, target_str, project, timeout_ms, root_str)
+            if result_text is None:
+                # A supported op that matched nothing is NOT an unsupported op, and saying so sends
+                # the agent looking for a different tool when the real answer is almost always a
+                # stale index. Name the cause and the one command that fixes it.
+                return safe_null_result(
+                    op_str, target_str, engine="graph", reason="not-in-graph",
+                    hint=f"`{target_str}` is not in the graph index for project {project!r} — if "
+                         f"you just added or renamed it, refresh with: codeintel index {root_str}",
+                )
+
             return {
                 "ok": True,
                 "op": op_str,
@@ -609,7 +671,7 @@ class GraphProvider:
             return safe_null_result(op, target, engine="graph", reason="error")
 
     def _dispatch(
-        self, op: str, target: str, project: str, timeout_ms: int
+        self, op: str, target: str, project: str, timeout_ms: int, root: str = ""
     ) -> str | None:
         if op == "impact" or op == "context":
             # `context` (fan-out op) → the graph's richest single-symbol view: callers + callees.
@@ -623,7 +685,7 @@ class GraphProvider:
         if op == "pattern":
             return self._op_pattern(target, project, timeout_ms)
         if op == "overview":
-            return self._op_overview(target, project, timeout_ms)
+            return self._op_overview(target, project, timeout_ms, root)
         if op == "changed" or op == "changes":
             return self._op_changed(project, timeout_ms)
         if op == "deadcode":

{codecortex-0.13.0 → codecortex-0.13.1}/src/codeintel/reindexer.py

@@ -126,11 +126,25 @@ class Reindexer:
     def _graph_reindex(self, project_root: str) -> None:
         # Route through the graph provider's single subprocess/JSON seam (piped stdin, with a
         # deprecated raw-JSON fallback) rather than duplicating the deprecated raw-JSON call here.
+        #
+        # This called `detect_changes` with a `project_root` argument, and was wrong twice over:
+        # the backend takes `project` (a name from list_projects), so every call returned an
+        # argument error that `_run` folded into None — and `detect_changes` only REPORTS
+        # uncommitted drift, it never reindexes. The graph therefore never refreshed, silently,
+        # and queries answered from whatever the index held when it was first built.
         try:
             from codeintel.providers.graph import GraphProvider
             gp = GraphProvider()
             if not gp.available:
                 return
-            gp._run("detect_changes", {"project_root": project_root}, 120_000)
+            result = gp._run("index_repository", {"project_root": project_root}, 300_000)
+            # Surface a backend-reported failure. Swallowing it is what let a broken reindex look
+            # exactly like a working one for as long as nobody compared the graph to the source.
+            if isinstance(result, dict) and result.get("status") == "error":
+                logger.warning("graph index_repository reported an error for %s: %s",
+                               project_root, result.get("hint") or result)
+            elif result is None:
+                logger.warning("graph index_repository returned nothing for %s "
+                               "(backend timed out, crashed, or rejected the call)", project_root)
         except Exception as exc:
-            logger.warning("graph detect_changes failed: %s", exc)
+            logger.warning("graph index_repository failed: %s", exc)