codecortex 0.6.0__tar.gz → 0.8.0__tar.gz

{codecortex-0.6.0/src/codecortex.egg-info → codecortex-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.6.0
+Version: 0.8.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
@@ -26,6 +26,7 @@ License-File: LICENSE
 Requires-Dist: mcp>=1.0
 Requires-Dist: sqlite-vec>=0.1
 Requires-Dist: fastembed>=0.3
+Requires-Dist: tree-sitter-language-pack>=1.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"

{codecortex-0.6.0 → codecortex-0.8.0}/pyproject.toml

@@ -31,7 +31,12 @@ classifiers = [
     "Topic :: Software Development :: Quality Assurance",
     "Typing :: Typed",
 ]
-dependencies = ["mcp>=1.0", "sqlite-vec>=0.1", "fastembed>=0.3"]
+dependencies = [
+    "mcp>=1.0",
+    "sqlite-vec>=0.1",
+    "fastembed>=0.3",
+    "tree-sitter-language-pack>=1.0",  # def-aligned chunking for non-Python languages (P3)
+]
 
 [project.urls]
 Homepage = "https://github.com/hamilton-sky/codeintel"

{codecortex-0.6.0 → codecortex-0.8.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.6.0
+Version: 0.8.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
@@ -26,6 +26,7 @@ License-File: LICENSE
 Requires-Dist: mcp>=1.0
 Requires-Dist: sqlite-vec>=0.1
 Requires-Dist: fastembed>=0.3
+Requires-Dist: tree-sitter-language-pack>=1.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"

{codecortex-0.6.0 → codecortex-0.8.0}/src/codecortex.egg-info/SOURCES.txt

@@ -56,6 +56,8 @@ tests/test_never_raise.py
 tests/test_onboarding.py
 tests/test_rbac.py
 tests/test_reindexer.py
+tests/test_rerank.py
 tests/test_reset.py
 tests/test_semantic_provider.py
-tests/test_term.py
+tests/test_term.py
+tests/test_treesitter.py

{codecortex-0.6.0 → codecortex-0.8.0}/src/codecortex.egg-info/requires.txt

@@ -1,6 +1,7 @@
 mcp>=1.0
 sqlite-vec>=0.1
 fastembed>=0.3
+tree-sitter-language-pack>=1.0
 
 [dev]
 pytest>=8

codecortex-0.8.0/src/codeintel/__init__.py

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

{codecortex-0.6.0 → codecortex-0.8.0}/src/codeintel/config.py

@@ -25,6 +25,8 @@ _DEFAULTS: dict = {
     "cosine_floor": 0.25,
     "model": "BAAI/bge-small-en-v1.5",
     "chunk_strategy": "syntax",  # syntax-aware (def/class boundaries) vs fixed line windows
+    "rerank": "on",              # hybrid lexical+semantic rerank of search results
+    "rerank_candidates": 30,     # cosine candidates fused/re-ranked before returning top-k
 }
 
 # Values restricted to a fixed set — anything else falls back to the default.
@@ -33,8 +35,9 @@ _ENUMS: dict = {
     "semantic": {"on", "off"},
     "reindex": {"on-demand", "never"},
     "chunk_strategy": {"syntax", "lines"},
+    "rerank": {"on", "off"},
 }
-_POSITIVE_INTS = ("window", "stride", "max_chunks", "max_total_chunks")
+_POSITIVE_INTS = ("window", "stride", "max_chunks", "max_total_chunks", "rerank_candidates")
 
 
 def _read_toml(path: pathlib.Path) -> dict:

{codecortex-0.6.0 → codecortex-0.8.0}/src/codeintel/doctor.py

@@ -158,4 +158,9 @@ def render_doctor_text(report: dict) -> str:
     tail = "" if report.get("deep") else c.dim("  (run with --deep to boot-check serena)")
     out.append("")
     out.append(f"  {count} engines ready for this repo.{tail}")
+    if healthy is False:
+        out.append("  " + c.dim(
+            "tip: `codeintel setup --install-uv --install-deps --index` bootstraps the "
+            "pip-installable backends; each fix: line above has the per-engine command."
+        ))
     return "\n".join(out)

{codecortex-0.6.0 → codecortex-0.8.0}/src/codeintel/indexer.py

@@ -14,7 +14,10 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 _INDEXED_EXTS = frozenset({
-    ".py", ".ts", ".js", ".go", ".rs", ".java", ".c", ".cpp", ".h", ".md"
+    ".py", ".md",
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",       # TS/JS variants
+    ".go", ".rs", ".java",
+    ".c", ".h", ".cpp", ".cc", ".cxx", ".hpp", ".hh",    # C/C++ variants
 })
 _SKIP_DIRS = frozenset({"__pycache__", ".git", "node_modules"})
 # Vendored / regenerable dirs skipped even without a .gitignore entry.
@@ -41,6 +44,49 @@ def _pos_int(val: object, default: int) -> int:
     return n if n > 0 else default
 
 
+# ---- tree-sitter chunking (P3): def-aligned chunks for non-Python languages -----------------
+# Extends the P1 chunker interface to TS/JS/Go/Rust/Java/C/C++ via tree-sitter, behind the same
+# _primary_spans → _cover pipeline. The grammar pack is a normal dependency but never a hard
+# requirement: if it (or a grammar) is unavailable, or a file's language config is missing, the
+# file falls back to line windowing — exactly like a Python parse failure.
+
+# file extension -> tree_sitter_language_pack language name. Only the *code* exts in
+# _INDEXED_EXTS; .md (and anything unmapped) keeps line-windowing.
+_TS_LANG_BY_EXT = {
+    ".ts": "typescript", ".tsx": "tsx", ".js": "javascript", ".jsx": "javascript",
+    ".mjs": "javascript", ".cjs": "javascript",
+    ".go": "go", ".rs": "rust", ".java": "java",
+    ".c": "c", ".h": "cpp", ".cpp": "cpp", ".cc": "cpp", ".cxx": "cpp",
+    ".hpp": "cpp", ".hh": "cpp",
+}
+# "Leaf" definition node types — each emitted as one whole chunk (like a top-level Python def).
+_TS_FUNC_TYPES = {
+    "typescript": {"function_declaration", "generator_function_declaration", "method_definition",
+                   "method_signature", "abstract_method_signature", "function_signature"},
+    "tsx": {"function_declaration", "generator_function_declaration", "method_definition",
+            "method_signature", "abstract_method_signature", "function_signature"},
+    "javascript": {"function_declaration", "generator_function_declaration", "method_definition"},
+    "go": {"function_declaration", "method_declaration", "type_declaration"},
+    "rust": {"function_item", "function_signature_item", "struct_item", "enum_item",
+             "union_item", "type_item", "macro_definition"},
+    "java": {"method_declaration", "constructor_declaration"},
+    "c": {"function_definition", "struct_specifier", "enum_specifier", "union_specifier"},
+    "cpp": {"function_definition"},
+}
+# "Container" definition types — emitted as a header chunk + one chunk per nested member, exactly
+# like a Python class (so per-method chunks are never shadowed by a whole-class chunk).
+_TS_CONTAINER_TYPES = {
+    "typescript": {"class_declaration", "abstract_class_declaration", "interface_declaration"},
+    "tsx": {"class_declaration", "abstract_class_declaration", "interface_declaration"},
+    "javascript": {"class_declaration"},
+    "go": set(),
+    "rust": {"impl_item", "trait_item", "mod_item"},
+    "java": {"class_declaration", "interface_declaration", "enum_declaration", "record_declaration"},
+    "c": set(),
+    "cpp": {"class_specifier", "struct_specifier", "namespace_definition"},
+}
+
+
 class Indexer:
     def __init__(
         self,
@@ -76,6 +122,7 @@ class Indexer:
             else 2 * self.window
         )
         self._embedder = None
+        self._ts_parsers: dict = {}  # per-instance tree-sitter parser cache (lang -> parser|None)
 
     def _get_embedder(self):
         if self._embedder is None:
@@ -249,16 +296,109 @@ class Indexer:
         n = len(lines)
         return self._cover(self._primary_spans(tree, n), n)
 
+    def _get_ts_parser(self, lang: str):
+        """Lazily load + cache (per instance) the tree-sitter parser for a language. Returns None
+        when ``tree-sitter-language-pack`` isn't installed or the grammar is unavailable — the
+        caller then windows (tree-sitter is a normal dep, never a hard requirement)."""
+        cache = self._ts_parsers
+        if lang in cache:
+            return cache[lang]
+        parser = None
+        try:
+            from tree_sitter_language_pack import get_parser
+            parser = get_parser(lang)
+        except Exception as exc:
+            logger.debug("tree-sitter parser for %s unavailable: %s", lang, exc)
+        cache[lang] = parser
+        return parser
+
+    @staticmethod
+    def _ts_end_line(node, n: int) -> int:
+        """0-based half-open end line of a tree-sitter node. ``end_point`` is (row, col); a col of 0
+        means the node ends at the start of that row (so the row isn't included). Clamped to
+        ``[start+1, n]``."""
+        row, col = node.end_point
+        end = row if col == 0 else row + 1
+        return min(n, max(node.start_point[0] + 1, end))
+
+    def _primary_spans_ts(self, root, lang: str, n: int) -> list[tuple[int, int]]:
+        """Def-aligned 'primary' spans from a tree-sitter tree, mirroring ``_primary_spans``: each
+        function/method → one span; each container (class/impl/trait/…) → a header span plus one
+        span per nested member. Node types the language config doesn't list are simply not treated
+        as defs — they fall into ``_cover``'s window-filled gaps, so an incomplete config degrades
+        precision, never correctness."""
+        func_types = _TS_FUNC_TYPES.get(lang, set())
+        cont_types = _TS_CONTAINER_TYPES.get(lang, set())
+        all_types = func_types | cont_types
+        if not all_types:
+            return []  # unknown language -> caller windows the whole file
+        spans: list[tuple[int, int]] = []
+
+        def nearest_defs(node):
+            """Def-type nodes reachable without crossing another def-type — top-level defs from the
+            root, a container's direct members from the container. Iterative, so deep nesting can't
+            blow the stack."""
+            found = []
+            stack = [c for c in reversed(node.children) if c.is_named]
+            while stack:
+                c = stack.pop()
+                if c.type in all_types:
+                    found.append(c)
+                else:
+                    stack.extend(g for g in reversed(c.children) if g.is_named)
+            return found
+
+        def emit(node):
+            s = node.start_point[0]
+            e = self._ts_end_line(node, n)
+            if node.type in cont_types:
+                members = sorted(nearest_defs(node), key=lambda m: m.start_point[0])
+                if members:
+                    header_end = max(s + 1, min(members[0].start_point[0], e))
+                    spans.append((s, header_end))  # header: class/impl line -> first member
+                    for m in members:
+                        emit(m)
+                    return
+            spans.append((s, e))
+
+        for node in sorted(nearest_defs(root), key=lambda x: x.start_point[0]):
+            emit(node)
+        return spans
+
+    def _chunk_treesitter(self, lines: list[str], source: str, lang: str):
+        """Parse ``source`` with tree-sitter → a complete, def-aligned cover, or ``None`` when the
+        parser is unavailable (caller windows). tree-sitter is error-tolerant, so a syntactically
+        broken file still yields a partial tree (and thus useful spans) rather than raising."""
+        parser = self._get_ts_parser(lang)
+        if parser is None:
+            return None
+        tree = parser.parse(source.encode("utf-8", errors="replace"))
+        n = len(lines)
+        return self._cover(self._primary_spans_ts(tree.root_node, lang, n), n)
+
     def _spans_for_file(
         self, filepath: Path, lines: list[str], rel_path: str
     ) -> list[tuple[int, int]]:
-        """Choose spans for one file: syntax-aware for ``.py`` under the syntax strategy (falling
-        back to windowing on any parse failure), fixed windows for everything else."""
-        if self.chunk_strategy == "syntax" and filepath.suffix.lower() == ".py":
-            try:
-                return self._chunk_python_ast(lines, "".join(lines))
-            except Exception as exc:
-                logger.debug("syntax chunking failed for %s (%s) — windowing", rel_path, exc)
+        """Choose spans for one file under the syntax strategy: ``ast`` for ``.py``, tree-sitter for
+        the mapped languages (TS/JS/Go/Rust/Java/C/C++), fixed windows for everything else and on
+        any parse/grammar failure or when tree-sitter isn't installed."""
+        if self.chunk_strategy == "syntax":
+            suffix = filepath.suffix.lower()
+            if suffix == ".py":
+                try:
+                    return self._chunk_python_ast(lines, "".join(lines))
+                except Exception as exc:
+                    logger.debug("syntax chunking failed for %s (%s) — windowing", rel_path, exc)
+            else:
+                lang = _TS_LANG_BY_EXT.get(suffix)
+                if lang is not None:
+                    try:
+                        spans = self._chunk_treesitter(lines, "".join(lines), lang)
+                        if spans is not None:
+                            return spans
+                    except Exception as exc:
+                        logger.debug("tree-sitter chunking failed for %s (%s) — windowing",
+                                     rel_path, exc)
         return self._window_spans(0, len(lines))
 
     # ---- materialisation -------------------------------------------------------------------
@@ -380,9 +520,17 @@ class Indexer:
                 try:
                     vec = embeddings[j]
                     vec_bytes = struct.pack(f"{len(vec)}f", *vec)
+                    # sqlite-vec's vec0 virtual table does NOT honor INSERT OR REPLACE — it raises
+                    # UNIQUE on an existing chunk_id instead of replacing. So re-embedding a chunk
+                    # whose content changed but whose chunk_id (start line) is stable — the common
+                    # case under syntax chunking, where a def's chunk_id is its def line — would
+                    # silently fail and keep the STALE vector. DELETE-then-INSERT is the supported
+                    # upsert for vec0. (chunk_hashes below is a normal table, where REPLACE works.)
+                    conn.execute(
+                        "DELETE FROM code_embeddings WHERE chunk_id = ?", (chunk_id,)
+                    )
                     conn.execute(
-                        "INSERT OR REPLACE INTO code_embeddings(chunk_id, embedding)"
-                        " VALUES (?, ?)",
+                        "INSERT INTO code_embeddings(chunk_id, embedding) VALUES (?, ?)",
                         (chunk_id, vec_bytes),
                     )
                     conn.execute(

{codecortex-0.6.0 → codecortex-0.8.0}/src/codeintel/providers/graph.py

@@ -157,7 +157,9 @@ class GraphProvider:
             return {
                 "installed": False, "runnable": False, "repo_indexed": False, "project": None,
                 "detail": "codebase-memory-mcp not found on PATH",
-                "remediation": "install codebase-memory-mcp (the graph backend)",
+                "remediation": "put the codebase-memory-mcp binary on PATH — it's an external "
+                               "native backend (see docs/graph.md); once present it self-updates "
+                               "via `codebase-memory-mcp update`",
             }
         raw = self._run("list_projects", {}, timeout_ms)
         if raw is None:

{codecortex-0.6.0 → codecortex-0.8.0}/src/codeintel/providers/lsp.py

@@ -144,7 +144,9 @@ class LspProvider:
             return {
                 "installed": False, "runnable": False, "repo_indexed": None,
                 "detail": "neither `serena` nor `uvx` found on PATH",
-                "remediation": "install uv (provides uvx) — serena is fetched on first use",
+                "remediation": "install uv (provides uvx): `codeintel setup --install-uv` "
+                               "(or `brew install uv` / `pip install uv`) — serena is then "
+                               "fetched on first use",
             }
         cmd = self._cmd
         if not deep:

{codecortex-0.6.0 → codecortex-0.8.0}/src/codeintel/providers/semantic.py

@@ -130,7 +130,10 @@ class SemanticProvider:
                 )
 
             matches = searcher.search(
-                target, project_root, cosine_floor=float(cfg.get("cosine_floor", 0.25))
+                target, project_root,
+                cosine_floor=float(cfg.get("cosine_floor", 0.25)),
+                rerank=str(cfg.get("rerank", "on")),
+                rerank_candidates=int(cfg.get("rerank_candidates", 30)),
             )
             if not matches:
                 return safe_null_result(op, target, engine="semantic", reason="below-floor")

codecortex-0.8.0/src/codeintel/searcher.py

@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import itertools
+import logging
+import os
+import re
+import struct
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codeintel.semantic_db import SemanticDb
+
+logger = logging.getLogger(__name__)
+
+_SNIPPET_LINES = 5
+# Hybrid rerank (0.7.0): re-read up to this many lines per candidate for lexical scoring — a hard
+# per-candidate cap so one huge file can't blow up a query. The read is further bounded at the next
+# stored chunk start (see _rerank); the returned snippet still uses only the first _SNIPPET_LINES.
+_RERANK_READ_LINES = 40
+# Hard ceiling on the candidate set regardless of rerank_candidates, so a misconfigured value can't
+# turn one query into thousands of file reads on the interactive hot path.
+_RERANK_CANDIDATES_CAP = 200
+_RRF_K = 60          # Reciprocal Rank Fusion constant (standard ≈ 60; damps rank differences)
+_SYMBOL_BOOST = 0.1  # additive fusion bonus for an exact def/class-name match (≫ one RRF term)
+
+# `\w` is Unicode-aware in Python 3, so a non-ASCII identifier is kept whole; the sub-splitter is
+# Latin-cased on purpose (camelCase only exists there) and just adds bonus pieces for ASCII names.
+_IDENT_RE = re.compile(r"\w+")
+_SUBTOKEN_RE = re.compile(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|[0-9]+")
+_SYMBOL_RE = re.compile(r"[^\W\d]\w*")  # a query that is a single identifier (letter/_ then word)
+
+
+def _pos_int(val: object, default: int) -> int:
+    """A usable positive int or the default — guards the public Searcher.search against a caller
+    passing a non-int/zero/negative k or rerank_candidates (mirrors indexer._pos_int)."""
+    try:
+        n = int(val)  # type: ignore[arg-type]
+    except (TypeError, ValueError, OverflowError):
+        return default
+    return n if n > 0 else default
+
+
+def _tokenize(text: str) -> set[str]:
+    """Lexical tokens for overlap scoring: each whole identifier plus its camel/snake sub-pieces,
+    lowercased. Deliberately set-based (presence, not frequency) — cheap and enough for ranking."""
+    toks: set[str] = set()
+    for ident in _IDENT_RE.findall(text):
+        toks.add(ident.lower())
+        for sub in _SUBTOKEN_RE.findall(ident):
+            toks.add(sub.lower())
+    return toks
+
+
+class Searcher:
+    def __init__(
+        self,
+        db: SemanticDb,
+        model_name: str = "BAAI/bge-small-en-v1.5",
+    ) -> None:
+        self.db = db
+        self.model_name = model_name
+        self._embedder = None
+
+    def _get_embedder(self):
+        if self._embedder is None:
+            from fastembed import TextEmbedding
+            self._embedder = TextEmbedding(model_name=self.model_name)
+        return self._embedder
+
+    def _embed_query(self, query: str) -> bytes | None:
+        try:
+            embedder = self._get_embedder()
+            vecs = list(embedder.embed([query]))
+            if not vecs:
+                return None
+            vec = vecs[0]
+            return struct.pack(f"{len(vec)}f", *vec)
+        except Exception as exc:
+            logger.warning("query embedding failed: %s", exc)
+            return None
+
+    def _row_count(self, project_root_real: str) -> int:
+        try:
+            conn = self.db.conn()
+            row = conn.execute(
+                "SELECT COUNT(*) FROM chunk_hashes WHERE project_root = ?",
+                (project_root_real,),
+            ).fetchone()
+            return row[0] if row else 0
+        except Exception as exc:
+            logger.warning("rowcount check failed: %s", exc)
+            return 0
+
+    def has_index(self, project_root: str) -> bool:
+        """True when this project has at least one indexed chunk — lets the provider
+        distinguish 'nothing indexed yet' (no-index) from 'matches below floor'."""
+        return self._row_count(os.path.realpath(project_root)) > 0
+
+    def _read_snippet(self, file_path: Path, chunk_start: int) -> str:
+        try:
+            with open(file_path, encoding="utf-8", errors="replace") as f:
+                lines = f.readlines()
+            snippet_lines = lines[chunk_start: chunk_start + _SNIPPET_LINES]
+            return "".join(snippet_lines).rstrip()
+        except FileNotFoundError:
+            return "[file not found]"
+        except Exception as exc:
+            logger.debug("snippet read failed for %s:%d: %s", file_path, chunk_start, exc)
+            return "[file not found]"
+
+    def _read_chunk(self, file_path: Path, chunk_start: int) -> list[str] | None:
+        """Bounded re-read from ``chunk_start`` for rerank lexical scoring (and the snippet in one
+        read). Uses ``islice`` so a huge multi-line file is not fully materialised just to take a
+        40-line window. ``None`` on any failure — the caller scores that candidate 0 and shows a
+        not-found snippet, never crashing (a missing/edited file must degrade, per never-raise)."""
+        try:
+            with open(file_path, encoding="utf-8", errors="replace") as f:
+                return list(itertools.islice(f, chunk_start, chunk_start + _RERANK_READ_LINES))
+        except Exception as exc:
+            logger.debug("chunk re-read failed for %s:%d: %s", file_path, chunk_start, exc)
+            return None
+
+    def _chunk_starts(self, project_root_real: str, file_path: str) -> list[int]:
+        """All stored chunk start lines for one file, sorted. Used to bound each candidate's rerank
+        read at the *next* chunk — the chunk's true end for tiling syntax chunks, its owned region
+        for overlapping line windows — so lexical/boost text never bleeds into an unrelated def.
+        Uses the (project_root, file_path) composite index. ``[]`` on any error → no bound applied."""
+        try:
+            rows = self.db.conn().execute(
+                "SELECT chunk_start FROM chunk_hashes"
+                " WHERE project_root = ? AND file_path = ? ORDER BY chunk_start",
+                (project_root_real, file_path),
+            ).fetchall()
+            return [int(r[0]) for r in rows]
+        except Exception as exc:
+            logger.debug("chunk-start lookup failed for %s: %s", file_path, exc)
+            return []
+
+    @staticmethod
+    def _lexical_score(query_tokens: set[str], chunk_text: str) -> float:
+        """Token overlap in [0, 1]: the fraction of query (sub)tokens present in the chunk."""
+        if not query_tokens:
+            return 0.0
+        return len(query_tokens & _tokenize(chunk_text)) / len(query_tokens)
+
+    @staticmethod
+    def _symbol_boost(query: str, chunk_text: str) -> float:
+        """Additive fusion bonus for the 'exact symbol' case: when the query is a single identifier
+        that appears in the chunk as a ``def``/``class`` name (full boost) or as a standalone word
+        (half). Case-insensitive, to match the lexical score. Cosine alone under-ranks these literal
+        matches; this is what pulls them to the top. The ``_SYMBOL_RE`` guard runs before any
+        ``re.escape`` interpolation, so no query character can ever reach the built pattern."""
+        q = (query or "").strip()
+        if not _SYMBOL_RE.fullmatch(q):
+            return 0.0  # multi-word / non-identifier query → no structural signal
+        if re.search(rf"\b(?:def|class)\s+{re.escape(q)}\b", chunk_text, re.IGNORECASE):
+            return _SYMBOL_BOOST
+        if re.search(rf"\b{re.escape(q)}\b", chunk_text, re.IGNORECASE):
+            return _SYMBOL_BOOST * 0.5
+        return 0.0
+
+    def _rerank(
+        self, query: str, root: Path, project_root_real: str, candidates: list[dict]
+    ) -> list[dict]:
+        """Reorder floor-gated candidates (given in cosine order) by Reciprocal Rank Fusion over
+        the semantic rank and a lexical rank, plus a symbol boost. Reads each candidate's chunk
+        once (bounded) — caching its 5-line snippet — so the whole rerank costs ≤ len(candidates)
+        reads. When no candidate has any lexical overlap the lexical rank mirrors the semantic
+        rank, so the cosine order is returned unchanged (rerank only *reorders* on real signal)."""
+        query_tokens = _tokenize(query)
+        n = len(candidates)
+        # Bound each candidate's lexical/boost text at the NEXT stored chunk start in its file — the
+        # chunk's true end for tiling syntax chunks, its owned region for overlapping line windows.
+        # A chunk's end line isn't stored, so a fixed 40-line read would otherwise (a) bleed into an
+        # unrelated later def, handing this chunk a symbol boost that isn't its own, and/or (b) — if
+        # we capped at neighbouring *candidates* — truncate a chunk below its own overlapping span.
+        # Bounding at the next real chunk gives each source line to exactly one chunk: the one whose
+        # 5-line snippet will actually show it.
+        starts_by_file: dict[str, list[int]] = {}
+        for path in {c["path"] for c in candidates}:
+            starts_by_file[path] = self._chunk_starts(project_root_real, path)
+
+        lex = [0.0] * n
+        boost = [0.0] * n
+        for i, c in enumerate(candidates):
+            lines = self._read_chunk(root / c["path"], c["line"])
+            if lines is None:
+                c["snippet"] = "[file not found]"
+                text = ""
+            else:
+                # snippet keeps the existing 5-line preview (bleed-tolerant, unchanged); the
+                # lexical/boost text is capped at the next stored chunk start in this file.
+                c["snippet"] = "".join(lines[:_SNIPPET_LINES]).rstrip()
+                nxt = next((s for s in starts_by_file.get(c["path"], ()) if s > c["line"]), None)
+                text = "".join(lines if nxt is None else lines[: max(1, nxt - c["line"])])
+            lex[i] = self._lexical_score(query_tokens, text)
+            boost[i] = self._symbol_boost(query, text)
+
+        # lexical rank: highest lexical score first, ties broken by the semantic rank (index i)
+        order_by_lex = sorted(range(n), key=lambda i: (-lex[i], i))
+        rank_lex = [0] * n
+        for pos, i in enumerate(order_by_lex):
+            rank_lex[i] = pos
+
+        # sem rank is the candidate's position i (they arrive in cosine order)
+        fused = [1.0 / (_RRF_K + i) + 1.0 / (_RRF_K + rank_lex[i]) + boost[i] for i in range(n)]
+        order = sorted(range(n), key=lambda i: (-fused[i], i))  # fused desc, tie → better cosine
+        return [candidates[i] for i in order]
+
+    def search(
+        self,
+        query: str,
+        project_root: str,
+        k: int = 10,
+        cosine_floor: float = 0.25,
+        rerank: str = "on",
+        rerank_candidates: int = 30,
+    ) -> list[dict]:
+        if not query or not query.strip():
+            return []
+
+        # Guard the public API: a direct caller passing a non-int/zero/negative k or
+        # rerank_candidates must degrade, not raise (never-raise). Config callers already pre-cast.
+        k = _pos_int(k, 10)
+        rerank_candidates = _pos_int(rerank_candidates, 30)
+        # Accept the documented "off" plus the obvious falsy spellings (incl. the Python bool
+        # ``False`` → ``"false"``), so a direct caller isn't silently left with rerank on.
+        do_rerank = str(rerank).strip().lower() not in ("off", "false", "0", "no", "none")
+        # With rerank on, retrieve a wider candidate set by cosine, then re-order it; still return
+        # the top-k. Cap only the *extra* rerank breadth (rerank_candidates) — the DoS guard — while
+        # always honoring k, so enabling rerank never returns fewer results than the pure-cosine
+        # path would for the same k (even a large k > cap).
+        candidate_limit = max(k, min(rerank_candidates, _RERANK_CANDIDATES_CAP)) if do_rerank else k
+
+        project_root_real = os.path.realpath(project_root)
+
+        # Scope the KNN to THIS project — a search in repo B must never surface repo A's
+        # chunks (wrong-file, wrong-content hits) from the shared cache.
+        if self._row_count(project_root_real) == 0:
+            return []
+
+        query_vec = self._embed_query(query)
+        if query_vec is None:
+            return []
+
+        try:
+            conn = self.db.conn()
+            rows = conn.execute(
+                """
+                SELECT
+                    ce.chunk_id,
+                    ch.chunk_start,
+                    ch.file_path,
+                    vec_distance_cosine(ce.embedding, ?) AS dist
+                FROM code_embeddings ce
+                JOIN chunk_hashes ch ON ce.chunk_id = ch.chunk_id
+                WHERE ch.project_root = ?
+                ORDER BY dist
+                LIMIT ?
+                """,
+                (query_vec, project_root_real, candidate_limit),
+            ).fetchall()
+        except Exception as exc:
+            logger.warning("KNN query failed: %s", exc)
+            return []
+
+        root = Path(project_root)
+
+        # Floor-gated candidate set, in cosine order. The cosine_floor stays on the *semantic*
+        # candidates (not the fused score), so rerank can only re-order what pure cosine already
+        # judged good enough — quality can't regress below the pre-0.7 path.
+        candidates: list[dict] = []
+        for row in rows:
+            try:
+                score = 1.0 - float(row["dist"])
+                if score < cosine_floor:
+                    continue
+                candidates.append({
+                    "path": str(row["file_path"]),
+                    "line": int(row["chunk_start"]),
+                    "score": round(score, 6),
+                })
+            except Exception as exc:
+                logger.debug("candidate row processing failed: %s", exc)
+                continue
+
+        if not candidates:
+            return []
+
+        # Rerank re-reads chunk text; if anything goes wrong, fall back to the cosine order so a
+        # rerank fault can never do worse than today (and never raises).
+        if do_rerank and len(candidates) > 1:
+            try:
+                candidates = self._rerank(query, root, project_root_real, candidates)
+            except Exception as exc:
+                logger.warning("rerank failed, using cosine order: %s", exc)
+
+        results: list[dict] = []
+        for c in candidates[:k]:
+            # _rerank caches the snippet on each candidate it read; fill it in otherwise.
+            snippet = c.get("snippet")
+            if snippet is None:
+                snippet = self._read_snippet(root / c["path"], c["line"])
+            results.append({
+                "path": c["path"],
+                "line": c["line"],
+                "snippet": snippet,
+                "score": c["score"],
+            })
+        return results