codecortex 0.2.1__tar.gz → 0.3.0__tar.gz

{codecortex-0.2.1/src/codecortex.egg-info → codecortex-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.2.1
+Version: 0.3.0
 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
@@ -82,6 +82,16 @@ Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine
 
 The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
 
+## What makes it good
+
+- **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
+- **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.
+- **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` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+
 ## Quickstart
 
 ```bash
@@ -173,7 +183,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
 | `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]` | Start the HTTP transport (loopback-only unless `--allow-remote`) |
+| `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 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 |
@@ -187,17 +197,28 @@ Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--n
 Create `.codeintel.toml` at your project root to override defaults:
 
 ```toml
-backend      = "auto"                   # auto | graph | lsp | semantic
-semantic     = "on"                     # on | off
-reindex      = "on-demand"              # on-demand | never
-cosine_floor = 0.25                     # minimum similarity score for semantic hits
-max_chunks   = 500                      # max chunks to embed per file
-model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
+backend          = "auto"                   # auto | graph | lsp | semantic
+semantic         = "on"                     # on | off
+reindex          = "on-demand"              # on-demand | never
+cosine_floor     = 0.25                     # minimum similarity score for semantic hits (0–1)
+max_chunks       = 500                      # max chunks to embed per file
+max_total_chunks = 100000                   # safety ceiling on chunks embedded in one index pass
+model            = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
+Config is **validated on load** — an out-of-range number, a misspelled enum, or a wrong type falls back to that key's default (with a logged warning) instead of breaking every query.
+
+**Environment variables:**
+
+| Variable | Effect |
+|---|---|
+| `CODEINTEL_HTTP_TOKEN` | Bearer token required by `serve-http` (equivalent to `--token`) |
+| `CODEINTEL_DEBUG=1` | Log the full traceback of any error the never-throw contract swallows (silent by default) — the switch for diagnosing an unexpected `null` |
+| `CODEINTEL_REINDEX=off` | Disable the background reindexer; queries then index inline to stay fresh |
+
 ## Privacy & dependencies
 
-**codeintel is local-first** — one local process, no cloud service, no API keys, no telemetry, and no per-query network. Its own code makes zero outbound HTTP calls, and the HTTP transport binds to `127.0.0.1` only.
+**codeintel is local-first** — one local process, no cloud service, no API keys, no telemetry, and no per-query network. Its own code makes zero outbound HTTP calls, and the HTTP transport binds to `127.0.0.1` only by default — binding a non-loopback host requires `--allow-remote`, and `--token` (or `CODEINTEL_HTTP_TOKEN`) then gates every request behind a bearer token. The server bounds concurrent connections, but for exposure to a hostile network you should still front it with a reverse proxy (TLS, rate-limiting) — the built-in `http.server` is not hardened for the open internet.
 
 **Bundled (installed with the package, run locally):** `mcp` (the tool interface) · `sqlite-vec` (the semantic index, a local DB file) · `fastembed` (the local embedding model).
 
@@ -230,6 +251,8 @@ Over MCP the agent calls `code.query` directly. Over HTTP, start the server and
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
 ```
 
+For a shared or remote deployment, start it with `--allow-remote --token "$CODEINTEL_HTTP_TOKEN"` and send `Authorization: Bearer <token>` on each request — a missing or wrong token gets a clean `401`. Requests are handled concurrently, so one slow query never blocks another.
+
 ```python
 import urllib.request, json
 

{codecortex-0.2.1 → codecortex-0.3.0}/README.md

@@ -49,6 +49,16 @@ Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine
 
 The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
 
+## What makes it good
+
+- **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
+- **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.
+- **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` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+
 ## Quickstart
 
 ```bash
@@ -140,7 +150,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
 | `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]` | Start the HTTP transport (loopback-only unless `--allow-remote`) |
+| `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 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 |
@@ -154,17 +164,28 @@ Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--n
 Create `.codeintel.toml` at your project root to override defaults:
 
 ```toml
-backend      = "auto"                   # auto | graph | lsp | semantic
-semantic     = "on"                     # on | off
-reindex      = "on-demand"              # on-demand | never
-cosine_floor = 0.25                     # minimum similarity score for semantic hits
-max_chunks   = 500                      # max chunks to embed per file
-model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
+backend          = "auto"                   # auto | graph | lsp | semantic
+semantic         = "on"                     # on | off
+reindex          = "on-demand"              # on-demand | never
+cosine_floor     = 0.25                     # minimum similarity score for semantic hits (0–1)
+max_chunks       = 500                      # max chunks to embed per file
+max_total_chunks = 100000                   # safety ceiling on chunks embedded in one index pass
+model            = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
+Config is **validated on load** — an out-of-range number, a misspelled enum, or a wrong type falls back to that key's default (with a logged warning) instead of breaking every query.
+
+**Environment variables:**
+
+| Variable | Effect |
+|---|---|
+| `CODEINTEL_HTTP_TOKEN` | Bearer token required by `serve-http` (equivalent to `--token`) |
+| `CODEINTEL_DEBUG=1` | Log the full traceback of any error the never-throw contract swallows (silent by default) — the switch for diagnosing an unexpected `null` |
+| `CODEINTEL_REINDEX=off` | Disable the background reindexer; queries then index inline to stay fresh |
+
 ## Privacy & dependencies
 
-**codeintel is local-first** — one local process, no cloud service, no API keys, no telemetry, and no per-query network. Its own code makes zero outbound HTTP calls, and the HTTP transport binds to `127.0.0.1` only.
+**codeintel is local-first** — one local process, no cloud service, no API keys, no telemetry, and no per-query network. Its own code makes zero outbound HTTP calls, and the HTTP transport binds to `127.0.0.1` only by default — binding a non-loopback host requires `--allow-remote`, and `--token` (or `CODEINTEL_HTTP_TOKEN`) then gates every request behind a bearer token. The server bounds concurrent connections, but for exposure to a hostile network you should still front it with a reverse proxy (TLS, rate-limiting) — the built-in `http.server` is not hardened for the open internet.
 
 **Bundled (installed with the package, run locally):** `mcp` (the tool interface) · `sqlite-vec` (the semantic index, a local DB file) · `fastembed` (the local embedding model).
 
@@ -197,6 +218,8 @@ Over MCP the agent calls `code.query` directly. Over HTTP, start the server and
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
 ```
 
+For a shared or remote deployment, start it with `--allow-remote --token "$CODEINTEL_HTTP_TOKEN"` and send `Authorization: Bearer <token>` on each request — a missing or wrong token gets a clean `401`. Requests are handled concurrently, so one slow query never blocks another.
+
 ```python
 import urllib.request, json
 

{codecortex-0.2.1 → codecortex-0.3.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.2.1
+Version: 0.3.0
 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
@@ -82,6 +82,16 @@ Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine
 
 The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
 
+## What makes it good
+
+- **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
+- **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.
+- **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` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+
 ## Quickstart
 
 ```bash
@@ -173,7 +183,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
 | `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]` | Start the HTTP transport (loopback-only unless `--allow-remote`) |
+| `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 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 |
@@ -187,17 +197,28 @@ Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--n
 Create `.codeintel.toml` at your project root to override defaults:
 
 ```toml
-backend      = "auto"                   # auto | graph | lsp | semantic
-semantic     = "on"                     # on | off
-reindex      = "on-demand"              # on-demand | never
-cosine_floor = 0.25                     # minimum similarity score for semantic hits
-max_chunks   = 500                      # max chunks to embed per file
-model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
+backend          = "auto"                   # auto | graph | lsp | semantic
+semantic         = "on"                     # on | off
+reindex          = "on-demand"              # on-demand | never
+cosine_floor     = 0.25                     # minimum similarity score for semantic hits (0–1)
+max_chunks       = 500                      # max chunks to embed per file
+max_total_chunks = 100000                   # safety ceiling on chunks embedded in one index pass
+model            = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
+Config is **validated on load** — an out-of-range number, a misspelled enum, or a wrong type falls back to that key's default (with a logged warning) instead of breaking every query.
+
+**Environment variables:**
+
+| Variable | Effect |
+|---|---|
+| `CODEINTEL_HTTP_TOKEN` | Bearer token required by `serve-http` (equivalent to `--token`) |
+| `CODEINTEL_DEBUG=1` | Log the full traceback of any error the never-throw contract swallows (silent by default) — the switch for diagnosing an unexpected `null` |
+| `CODEINTEL_REINDEX=off` | Disable the background reindexer; queries then index inline to stay fresh |
+
 ## Privacy & dependencies
 
-**codeintel is local-first** — one local process, no cloud service, no API keys, no telemetry, and no per-query network. Its own code makes zero outbound HTTP calls, and the HTTP transport binds to `127.0.0.1` only.
+**codeintel is local-first** — one local process, no cloud service, no API keys, no telemetry, and no per-query network. Its own code makes zero outbound HTTP calls, and the HTTP transport binds to `127.0.0.1` only by default — binding a non-loopback host requires `--allow-remote`, and `--token` (or `CODEINTEL_HTTP_TOKEN`) then gates every request behind a bearer token. The server bounds concurrent connections, but for exposure to a hostile network you should still front it with a reverse proxy (TLS, rate-limiting) — the built-in `http.server` is not hardened for the open internet.
 
 **Bundled (installed with the package, run locally):** `mcp` (the tool interface) · `sqlite-vec` (the semantic index, a local DB file) · `fastembed` (the local embedding model).
 
@@ -230,6 +251,8 @@ Over MCP the agent calls `code.query` directly. Over HTTP, start the server and
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
 ```
 
+For a shared or remote deployment, start it with `--allow-remote --token "$CODEINTEL_HTTP_TOKEN"` and send `Authorization: Bearer <token>` on each request — a missing or wrong token gets a clean `401`. Requests are handled concurrently, so one slow query never blocks another.
+
 ```python
 import urllib.request, json
 

{codecortex-0.2.1 → codecortex-0.3.0}/src/codecortex.egg-info/SOURCES.txt

@@ -32,12 +32,16 @@ src/codeintel/providers/graph.py
 src/codeintel/providers/lsp.py
 src/codeintel/providers/none.py
 src/codeintel/providers/semantic.py
+tests/test_cache.py
+tests/test_config.py
 tests/test_doctor.py
 tests/test_e2e.py
 tests/test_gateway.py
 tests/test_graph_provider.py
 tests/test_graph_real.py
 tests/test_graph_stdin.py
+tests/test_hardening.py
+tests/test_http_auth.py
 tests/test_http_server.py
 tests/test_integration.py
 tests/test_lsp_provider.py

codecortex-0.3.0/src/codeintel/__init__.py

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

{codecortex-0.2.1 → codecortex-0.3.0}/src/codeintel/__main__.py

@@ -50,7 +50,8 @@ def main() -> None:
     http_parser = subparsers.add_parser("serve-http", help="Start the HTTP transport server")
     http_parser.add_argument("--port", type=int, default=8766, help="Port to listen on (default: 8766)")
     http_parser.add_argument("--host", default="127.0.0.1", help="Host to bind to (default: 127.0.0.1)")
-    http_parser.add_argument("--allow-remote", action="store_true", help="Permit binding a non-loopback host (exposes an UNAUTHENTICATED endpoint)")
+    http_parser.add_argument("--allow-remote", action="store_true", help="Permit binding a non-loopback host (use with --token, or the endpoint is UNAUTHENTICATED)")
+    http_parser.add_argument("--token", default=None, help="Require this bearer token on every request (or set CODEINTEL_HTTP_TOKEN). Strongly recommended with --allow-remote.")
 
     # install subcommand
     install_parser = subparsers.add_parser("install", help="Register codeintel with AI agents")
@@ -120,6 +121,7 @@ def main() -> None:
                 window=int(cfg.get("window", 20)),
                 stride=int(cfg.get("stride", 10)),
                 max_chunks=int(cfg.get("max_chunks", 500)),
+                max_total_chunks=int(cfg.get("max_total_chunks", 100000)),
             ).index(project_root)
             if count > 0:
                 print(f"Indexed {count} chunks")
@@ -225,7 +227,7 @@ def main() -> None:
             from codeintel import server
 
             project_root = args.project_root or os.getcwd()
-            status = server.code_status_handler({})
+            status = server.code_status_handler({"project_root": project_root})
 
             print("Engine status:")
             for engine in ["graph", "lsp", "semantic"]:
@@ -318,7 +320,8 @@ def main() -> None:
     elif args.command == "serve-http":
         try:
             from codeintel.http_server import run
-            run(host=args.host, port=args.port, allow_remote=args.allow_remote)
+            token = args.token or os.environ.get("CODEINTEL_HTTP_TOKEN")
+            run(host=args.host, port=args.port, allow_remote=args.allow_remote, token=token)
         except KeyboardInterrupt:
             pass
         except Exception as exc:

{codecortex-0.2.1 → codecortex-0.3.0}/src/codeintel/cache.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import hashlib
 import os
 import threading
+from collections import OrderedDict
 from typing import Optional
 
 from codeintel.provider import Result
@@ -12,7 +13,7 @@ def _compute_hash(target: str, project_root: str) -> str:
     try:
         root = os.path.realpath(project_root) if project_root else ""
         path = os.path.realpath(target)
-        if root and path.startswith(root + os.sep) or path == root:
+        if (root and path.startswith(root + os.sep)) or path == root:
             if os.path.isfile(path):
                 with open(path, "rb") as fh:
                     return hashlib.sha256(fh.read()).hexdigest()
@@ -22,10 +23,15 @@ def _compute_hash(target: str, project_root: str) -> str:
 
 
 class ContentHashCache:
-    def __init__(self) -> None:
+    # Bounded: the server builds ONE gateway and reuses it across every request, so an unbounded
+    # store would grow for the life of the process. Capped as an LRU — past _max_entries the
+    # least-recently-used entry is evicted. Sized generously; an agent session touches at most a
+    # few hundred distinct (op, target, engine, root) keys, each holding a small Result.
+    def __init__(self, max_entries: int = 1024) -> None:
         self._lock = threading.Lock()
-        # key → (content_hash, Result)
-        self._store: dict[tuple[str, str, str, str], tuple[str, Result]] = {}
+        self._max_entries = max(1, int(max_entries))
+        # key → (content_hash, Result); OrderedDict preserves insertion/access order for LRU.
+        self._store: "OrderedDict[tuple[str, str, str, str], tuple[str, Result]]" = OrderedDict()
 
     def get(
         self,
@@ -41,10 +47,14 @@ class ContentHashCache:
         if entry is None:
             return None
         stored_hash, result = entry
+        # _compute_hash may read the target file — keep it OUTSIDE the lock (original intent).
         current_hash = f"{_compute_hash(target, project_root)}:{freshness}"
-        if current_hash == stored_hash:
-            return result
-        return None
+        if current_hash != stored_hash:
+            return None
+        with self._lock:
+            if key in self._store:  # may have been evicted between the two locked sections
+                self._store.move_to_end(key)  # mark most-recently-used
+        return result
 
     def put(
         self,
@@ -64,3 +74,6 @@ class ContentHashCache:
         content_hash = f"{_compute_hash(target, project_root)}:{freshness}"
         with self._lock:
             self._store[key] = (content_hash, result)
+            self._store.move_to_end(key)  # most-recently-used
+            while len(self._store) > self._max_entries:
+                self._store.popitem(last=False)  # evict least-recently-used

codecortex-0.3.0/src/codeintel/config.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import logging
+import pathlib
+import sys
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    try:
+        import tomllib  # type: ignore[no-redef]
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+logger = logging.getLogger("codeintel")
+
+_DEFAULTS: dict = {
+    "backend": "auto",
+    "semantic": "on",
+    "reindex": "on-demand",
+    "window": 20,
+    "stride": 10,
+    "max_chunks": 500,          # per file
+    "max_total_chunks": 100000,  # safety ceiling on chunks embedded in one index pass
+    "cosine_floor": 0.25,
+    "model": "BAAI/bge-small-en-v1.5",
+}
+
+# Values restricted to a fixed set — anything else falls back to the default.
+_ENUMS: dict = {
+    "backend": {"auto", "graph", "lsp", "semantic"},
+    "semantic": {"on", "off"},
+    "reindex": {"on-demand", "never"},
+}
+_POSITIVE_INTS = ("window", "stride", "max_chunks", "max_total_chunks")
+
+
+def _read_toml(path: pathlib.Path) -> dict:
+    try:
+        with path.open("rb") as fh:
+            return tomllib.load(fh)
+    except (FileNotFoundError, OSError, tomllib.TOMLDecodeError):
+        return {}
+
+
+def _coerce(cfg: dict) -> dict:
+    """Coerce/clamp a merged config to safe values, warning on and dropping bad ones. Never raises:
+    a malformed ``.codeintel.toml`` (a string where a number belongs, an out-of-range floor, an
+    unknown enum) must degrade to the default for that key, not break every query that loads it."""
+    out = dict(_DEFAULTS)
+    for key, default in _DEFAULTS.items():
+        if key not in cfg:
+            continue
+        val = cfg[key]
+        try:
+            if key in _ENUMS:
+                s = str(val).strip().lower()
+                if s in _ENUMS[key]:
+                    out[key] = s
+                else:
+                    logger.warning("config: %s=%r invalid (expected %s) — using %r",
+                                   key, val, sorted(_ENUMS[key]), default)
+            elif key == "model":
+                out[key] = str(val).strip() or default
+            elif key == "cosine_floor":
+                f = float(val)
+                if f != f:  # NaN (TOML allows `nan`) — reject so it can't silently disable the floor
+                    raise ValueError("nan")
+                out[key] = min(1.0, max(0.0, f))
+            elif key in _POSITIVE_INTS:
+                n = int(val)
+                if n > 0:
+                    out[key] = n
+                else:
+                    logger.warning("config: %s=%r must be > 0 — using %r", key, val, default)
+        except (TypeError, ValueError, OverflowError):
+            # int(float('inf')) raises OverflowError (TOML allows `inf`); float("x") → ValueError;
+            # int([]) → TypeError. Any non-usable value logs and keeps the default, so the
+            # docstring's never-raise promise holds even for the CLI paths that don't wrap this.
+            logger.warning("config: %s=%r not usable — using default %r", key, val, default)
+    # Keep any extra keys the user set (forward-compat) without validating them.
+    for k, v in cfg.items():
+        if k not in _DEFAULTS:
+            out[k] = v
+    return out
+
+
+def load_config(project_root: str | None = None) -> dict:
+    """Return the merged, validated config: defaults < global < project. Values that fail
+    validation fall back to their default (logged), so a bad config file never breaks a query."""
+    root = pathlib.Path(project_root) if project_root is not None else pathlib.Path.cwd()
+
+    global_cfg = _read_toml(pathlib.Path.home() / ".codeintel" / "config.toml")
+    project_cfg = _read_toml(root / ".codeintel.toml")
+
+    merged = {**_DEFAULTS, **global_cfg, **project_cfg}
+    return _coerce(merged)

{codecortex-0.2.1 → codecortex-0.3.0}/src/codeintel/gateway.py

@@ -5,7 +5,7 @@ from typing import Any
 
 from codeintel.cache import ContentHashCache
 from codeintel.policy import TieringPolicy
-from codeintel.provider import Result, safe_null_result
+from codeintel.provider import Result, log_swallowed, safe_null_result
 from codeintel.providers.none import NoneProvider
 from codeintel.reindexer import Reindexer
 
@@ -128,7 +128,8 @@ class Gateway:
             if r is not None:
                 return r
             return safe_null_result(op_str, target_str, engine=engine_str, reason="no-result")
-        except Exception:
+        except Exception as exc:
+            log_swallowed(f"Gateway._dispatch_single[{engine_str}.{op_str}]", exc)
             return safe_null_result(op_str, target_str, engine=engine_str, reason="provider-error")
 
     def query(
@@ -206,14 +207,15 @@ class Gateway:
             provider = self._provider_for(engine_str)
             result = self._dispatch_single(provider, op_str, target_str, budget, project_root, engine_str)
 
-            # overview auto-fallback (F4 Story 2): when auto-routed to graph but graph is
-            # unavailable, try lsp — a file/symbol overview is something lsp can also serve.
+            # overview auto-fallback (F4 Story 2): when auto-routed to graph but graph can't serve
+            # it — the backend is unavailable, OR this repo simply isn't in the graph — try lsp,
+            # which can produce a file/symbol overview without the graph index.
             if (
                 was_auto
                 and op_str == "overview"
                 and engine_str == "graph"
                 and result.get("result") is None
-                and result.get("reason") == "engine-unavailable"
+                and result.get("reason") in ("engine-unavailable", "project-not-indexed")
             ):
                 lsp_result = self._dispatch_single(
                     self.lsp, op_str, target_str, budget, project_root, "lsp"
@@ -224,5 +226,6 @@ class Gateway:
             self._cache.put(op_str, target_str, engine_str, root_str, result, freshness)
             return result
 
-        except Exception:
+        except Exception as exc:
+            log_swallowed("Gateway.query", exc)
             return safe_null_result(op or "", target or "", reason="gateway-error")