code-context-control 2.109.0__tar.gz → 2.110.0__tar.gz

{code_context_control-2.109.0 → code_context_control-2.110.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.109.0
+Version: 2.110.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.109.0 → code_context_control-2.110.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.109.0"
+__version__ = "2.110.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):

{code_context_control-2.109.0 → code_context_control-2.110.0}/cli/mcp_server.py

@@ -489,13 +489,16 @@ async def c3_search(query: str, action: str = "code", top_k: int = 3,
     action: 'code' (default: BM25 over identifiers and their parts, digits kept, fused with the embedding
     index by reciprocal rank when one is ready; a query that IS a symbol name puts its definition first;
     an oversized chunk comes back as a window), 'lexical' (the BM25 ranking alone), 'exact' (regex over
-    every indexed file; ignore_case=True for case-insensitive), 'files' (by filename: exact name, glob
-    like 'configs/*.yml', or substring), 'semantic' (embeddings alone; falls back to code search when
-    empty), 'transcript'.
+    every indexed file, definitions printed first; ignore_case=True for case-insensitive), 'files' (by
+    filename: exact name, glob like 'configs/*.yml', or substring), 'semantic' (embeddings alone; falls
+    back to code search when empty), 'transcript'.
     Filters (all actions but transcript, comma-separated): path='src/**,*.go' (globs or substrings),
     lang='python,go' (names or extensions), kind='test,doc,config,source' and/or chunk types
     'function,class,method,heading'. A query that names tests or asks a how-to question already
     leans that way; filters make it exact.
+    top_k: up to 50 for 'files' and 'exact', 10 otherwise. Each hit header ends in the backend that
+    produced it ([lexical], [dense], [lexical+dense], symbol+, reranked); a zero result says which
+    action to try next.
     scope: '' current project | 'all' also searches linked sub-projects | '<name>' one sub-project.
     prefetch: auto-compress top results. Next step: c3_compress/c3_read on hits."""
     svc = _svc(ctx)

{code_context_control-2.109.0 → code_context_control-2.110.0}/cli/tools/search.py

@@ -14,7 +14,7 @@ from cli.tools._helpers import finalize_with_tokens, show_token_ratios
 from core import count_tokens
 from services import access_guard
 from services.indexer import DEFAULT_CODE_EXTS
-from services.lexical_index import Filters
+from services.lexical_index import Filters, doc_kind
 from services.scanner import SKIP_DIRS, iter_files
 
 # Hard cap: responses above this are truncated to avoid filling context.
@@ -24,6 +24,32 @@ _RESPONSE_TOKEN_CAP = 2400
 # token budget and hide every other file.
 _EXACT_MAX_MATCHES_PER_FILE = 20
 _RG_TIMEOUT_SECONDS = 60
+# top_k caps per action (2.110.0). A code hit spends a chunk of the token
+# budget; a files row or an exact per-file block spends a line or two, so
+# those actions may list many more before the response cap bites.
+_TOP_K_CAP_DEFAULT = 10
+_TOP_K_CAPS = {"files": 50, "exact": 50}
+
+# `exact` orders files definitions-first (2.110.0): a hit on a line that
+# declares something outranks a hit that merely mentions it, then source
+# before config, docs and tests, then path order. The index's symbol table
+# is consulted first when the query names one identifier; this regex is the
+# language-agnostic fallback for keyword-declared definitions (def/class/
+# fn/func/type/const/...) and top-level assignments. C-family functions
+# without a keyword rely on the symbol table.
+_DEF_LINE_RE = re.compile(
+    r"^\s*(?:(?:export|default|pub(?:\([^)]*\))?|public|private|protected|internal|static|"
+    r"abstract|final|async|unsafe|extern|declare|override|virtual|inline|constexpr)\s+)*"
+    r"(?:def|class|function|fn|func|type|struct|interface|enum|trait|impl|module|record|"
+    r"protocol|extension|object|namespace|const|let|var|val|#define)"
+    r"(?=\s+[A-Za-z_(*&\[]|\s*[<(])"
+    r"|^[A-Za-z_][\w.]*\s*(?::[^=]*)?=(?!=)")
+_KIND_RANK = {"source": 0, "config": 1, "doc": 2, "test": 3}
+# A forward slash or a dotted filename reads as a path; a backslash does not,
+# because `\d` / `\s` in a regex are far more common in queries than Windows
+# separators.
+_PATHLIKE_RE = re.compile(r"/|^[\w.\-]+\.[A-Za-z0-9]{1,6}$")
+_REGEX_META = set("\\^$.|?*+()[]{}")
 
 
 def _read_denied(path, svc) -> bool:
@@ -77,11 +103,66 @@ def _cap_response(resp: str) -> str:
     return "\n".join(lines[:20]) + "\n[truncated]"
 
 
+def _via_tag(r: dict) -> str:
+    """`` [lexical+dense, reranked]`` — which backend(s) produced the hit."""
+    via = r.get("via")
+    if not via:
+        return ""
+    return f" [{via}, reranked]" if r.get("reranked") else f" [{via}]"
+
+
+def _zero_hint(action: str, query: str, *, filters: Filters | None = None,
+               ignore_case: bool = False) -> str:
+    """One clause naming what to try next when an action finds nothing.
+
+    Never echoes the query: the eval harness strips it before checking for
+    forbidden text, and a masked canary must not be printed twice.
+    """
+    tips = []
+    if action == "exact":
+        if not ignore_case and re.search(r"[A-Za-z]", query):
+            tips.append("ignore_case=True")
+        tips.append("action='code', which matches identifiers by their parts")
+    elif action == "files":
+        if not any(ch in query for ch in "*?["):
+            tips.append("a glob like '**/*.yml'")
+        tips.append("action='exact' to search file contents")
+    else:
+        if _PATHLIKE_RE.search(query):
+            tips.append("action='files', which matches filenames")
+        elif any(ch in query for ch in _REGEX_META):
+            tips.append("action='exact', which takes a regex")
+        else:
+            tips.append("action='exact' for a literal or regex")
+            tips.append("action='files' for a filename")
+    if filters:
+        tips.append("dropping the path/lang/kind filter")
+    if not tips:
+        return ""
+    if len(tips) == 1:
+        return f"; try {tips[0]}"
+    return "; try " + ", ".join(tips[:-1]) + f", or {tips[-1]}"
+
+
+def _symbol_definition_files(query: str, svc) -> set:
+    """Files whose indexed symbol table defines the identifier ``query`` names."""
+    idx = getattr(svc, "indexer", None)
+    fn = getattr(idx, "_exact_symbol_ids", None)
+    if not callable(fn):
+        return set()
+    try:
+        chunks = getattr(idx, "chunks", None) or {}
+        # doc ids carry the OS separator; the manifest is POSIX.
+        return {chunks[cid]["doc_id"].replace("\\", "/") for cid in fn(query) if cid in chunks}
+    except Exception:
+        return set()
+
+
 def handle_search(query: str, action: str, top_k: int, max_tokens: int,
                   svc, finalize, maybe_facts, prefetch: bool = False,
                   scope: str = "", ignore_case: bool = False,
                   path: str = "", lang: str = "", kind: str = "") -> str:
-    top_k = max(1, min(int(top_k), 10))
+    top_k = max(1, min(int(top_k), _TOP_K_CAPS.get(action, _TOP_K_CAP_DEFAULT)))
     max_tokens = min(max(200, int(max_tokens)), _RESPONSE_TOKEN_CAP)
     filters = Filters(path=path, lang=lang, kind=kind)
 
@@ -262,10 +343,13 @@ def _exact_search(query, top_k, max_tokens, svc, finalize, ignore_case: bool = F
             return None
         file_matches = []
         n_matches = 0
+        def_line = False
         for i, line in enumerate(lines):
             if not pat.search(line):
                 continue
             n_matches += 1
+            if not def_line and _DEF_LINE_RE.match(line):
+                def_line = True
             if n_matches > _EXACT_MAX_MATCHES_PER_FILE:
                 continue  # keep counting, stop printing
             start = max(0, i - 1)
@@ -281,32 +365,45 @@ def _exact_search(query, top_k, max_tokens, svc, finalize, ignore_case: bool = F
             file_matches.append(
                 f"[+{n_matches - _EXACT_MAX_MATCHES_PER_FILE} more matching lines in this file; "
                 "narrow the pattern]")
-        return (rel, file_matches) if file_matches else None
+        return (rel, file_matches, def_line) if file_matches else None
 
-    matched_parts = []
-    file_count = 0
-    total_tokens = 0
+    # Every matching file is collected, then ordered definitions-first: the
+    # manifest walk used to decide the order, so the definition of a symbol
+    # could print behind a test and a doc that merely mention it.
+    symbol_files = _symbol_definition_files(query, svc)
+    hits = []
     if targets:
         with ThreadPoolExecutor(max_workers=min(len(targets), 8)) as pool:
             for result in pool.map(_scan_file, targets):
                 if result is None:
                     continue
-                rel, file_matches = result
+                rel, file_matches, def_line = result
                 if _read_denied(rel, svc):
                     continue  # R2: denied paths never appear in results
-                chunk = f"--- {rel} ---\n" + "\n".join(file_matches)
-                chunk_tokens = count_tokens(chunk)
-                if total_tokens + chunk_tokens > max_tokens and matched_parts:
-                    break
-                file_count += 1
-                total_tokens += chunk_tokens
-                matched_parts.append(chunk)
-                if file_count >= top_k:
-                    break
+                def_rank = 0 if rel in symbol_files else (1 if def_line else 2)
+                hits.append(((def_rank, _KIND_RANK.get(doc_kind(rel), 9), rel),
+                             rel, file_matches, def_rank < 2))
+    hits.sort(key=lambda h: h[0])
+
+    matched_parts = []
+    file_count = 0
+    total_tokens = 0
+    for _key, rel, file_matches, is_def in hits:
+        header = f"--- {rel} ---" + (" [definition]" if is_def else "")
+        chunk = header + "\n" + "\n".join(file_matches)
+        chunk_tokens = count_tokens(chunk)
+        if total_tokens + chunk_tokens > max_tokens and matched_parts:
+            break
+        file_count += 1
+        total_tokens += chunk_tokens
+        matched_parts.append(chunk)
+        if file_count >= top_k:
+            break
 
     if not matched_parts:
+        hint = _zero_hint("exact", query, filters=filters, ignore_case=ignore_case)
         return finalize("c3_search", {"action": "exact"},
-                        f"[search:exact:{query}] 0 results in {len(manifest)} files", "0")
+                        f"[search:exact:{query}] 0 results in {len(manifest)} files{hint}", "0")
 
     resp = "\n".join(matched_parts)
     return finalize("c3_search", {"action": "exact"}, resp, f"{file_count}f",
@@ -418,8 +515,9 @@ def _files_search(query, top_k, svc, finalize, filters: Filters | None = None):
                              **_filter_kwargs(filters))
     res = [r for r in res if not _read_denied(r.get("file", ""), svc)]
     if not res:
+        hint = _zero_hint("files", query, filters=filters)
         return finalize("c3_search", {"action": "files"},
-                        f"[search:files:{query}] 0 results", "0")
+                        f"[search:files:{query}] 0 results{hint}", "0")
     parts = []
     for r in res:
         meta = f"- {r['file']} (L{r['lines']})"
@@ -519,7 +617,7 @@ def _semantic_search(query, top_k, max_tokens, svc, finalize, maybe_facts,
     total_tokens = 0
     for r in results:
         name = f" {r['name']}" if r.get('name') else ""
-        ref = f"--- {r['file']}:L{r['lines']}{name} ({r['type']})"
+        ref = f"--- {r['file']}:L{r['lines']}{name} ({r['type']}) [dense]"
         lines.extend([ref, r['content']] if r.get('content') else [ref])
         total_tokens += r['tokens']
 
@@ -539,7 +637,8 @@ def _code_search(query, top_k, max_tokens, svc, finalize, maybe_facts,
     # Access Guard pre-filter BEFORE dedup/top_k (R2 deny-ENUMERATE).
     results = [r for r in results if not _read_denied(r.get("file", ""), svc)]
     if not results:
-        return finalize("c3_search", {"query": query}, f"[search:{query}] 0 results", "0")
+        hint = _zero_hint("code", query, filters=filters)
+        return finalize("c3_search", {"query": query}, f"[search:{query}] 0 results{hint}", "0")
 
     best_score = max((r.get("score", 0.0) for r in results), default=0.0)
     if best_score > 0:
@@ -564,7 +663,7 @@ def _code_search(query, top_k, max_tokens, svc, finalize, maybe_facts,
     total_tokens = 0
     for r in deduped:
         name = f" {r['name']}" if r['name'] else ""
-        ref = f"--- {r['file']}:L{r['lines']}{name} ({r['type']})"
+        ref = f"--- {r['file']}:L{r['lines']}{name} ({r['type']}){_via_tag(r)}"
         lines.extend([ref, r['content']] if r.get('content') else [ref])
         total_tokens += r['tokens']
 

{code_context_control-2.109.0 → code_context_control-2.110.0}/code_context_control.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.109.0
+Version: 2.110.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.109.0 → code_context_control-2.110.0}/code_context_control.egg-info/SOURCES.txt

@@ -431,6 +431,7 @@ tests/test_search_p2.py
 tests/test_search_p2b.py
 tests/test_search_p3.py
 tests/test_search_p4.py
+tests/test_search_p5.py
 tests/test_service_durability.py
 tests/test_session_benchmark.py
 tests/test_session_budget.py

{code_context_control-2.109.0 → code_context_control-2.110.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.109.0"
+version = "2.110.0"
 description = "Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub."
 readme = "README.md"
 requires-python = ">=3.10"

{code_context_control-2.109.0 → code_context_control-2.110.0}/services/bench/search_eval.py

@@ -330,11 +330,15 @@ def _embedding_index(project: str, indexer, *, build: bool):
 
 # ── Response parsing ────────────────────────────────────────────────────────
 
+# Headers may carry a trailing ``[tag]`` (2.110.0): ``[lexical+dense]`` /
+# ``[dense]`` / ``[symbol+lexical, reranked]`` on chunk hits, ``[definition]``
+# on exact hits. The tag is provenance, not identity, so it is optional here.
 _RE_CHUNK = re.compile(
-    r"^--- (?P<file>.+?):L(?P<lines>[^ ]+)(?: (?P<name>.+?))? \((?P<type>[^()]+)\)\s*$")
+    r"^--- (?P<file>.+?):L(?P<lines>[^ ]+)(?: (?P<name>.+?))? \((?P<type>[^()]+)\)"
+    r"(?: \[(?P<via>[^\]]*)\])?\s*$")
 _RE_FILE_ROW = re.compile(
     r"^- (?P<file>.+?) \(L(?P<lines>[^)]+)\)(?:.*?contains (?P<type>\S+) '(?P<name>[^']*)')?")
-_RE_EXACT = re.compile(r"^--- (?P<file>.+?) ---\s*$")
+_RE_EXACT = re.compile(r"^--- (?P<file>.+?) ---(?: \[(?P<via>[^\]]*)\])?\s*$")
 
 
 def parse_hits(action: str, response: str) -> list[Hit]:

{code_context_control-2.109.0 → code_context_control-2.110.0}/services/indexer.py

@@ -230,13 +230,16 @@ class CodeIndex:
             return "off"
         return str(getattr(self.reranker, "name", None) or "on")
 
-    def _apply_rerank(self, query: str, base_tokens: list, ranked: list, exact_ids: set) -> list:
+    def _apply_rerank(self, query: str, base_tokens: list, ranked: list, exact_ids: set,
+                      reranked: set | None = None) -> list:
         """Cross-encoder pass over the top ``search_rerank_top_n`` candidates.
 
         Identifier-shaped queries are left alone (services/reranker
         .is_natural_language). Exact-symbol matches keep their place ahead of
         the reranked block; candidates beyond the block keep their order.
         Any reranker failure or empty answer leaves ``ranked`` unchanged.
+        ``reranked``, when given, receives the ids the model actually
+        reordered so the caller can label them.
         """
         from services.reranker import is_natural_language, passage_text
 
@@ -258,10 +261,12 @@ class CodeIndex:
             return ranked
         order = {cid: i for i, (cid, _) in enumerate(scored)}
         block.sort(key=lambda cs: (order.get(cs[0], len(order)), -cs[1], cs[0]))
+        if reranked is not None:
+            reranked.update(cid for cid, _ in block)
         return exact_head + block + ranked[n:]
 
     def _fuse_dense(self, query: str, lexical_ranked: list, filters: Filters,
-                    exact_ids: set, want: int) -> list:
+                    exact_ids: set, want: int, provenance: dict | None = None) -> list:
         """RRF of the lexical ranking with the dense backend's candidates.
 
         Each list contributes its top ``n`` (20..50, from ``want``); dense ids
@@ -270,6 +275,9 @@ class CodeIndex:
         their override through the rank key. Lexical candidates beyond ``n``
         trail the fused block so budget filling can continue past it. Any
         backend failure returns the lexical ranking unchanged.
+        ``provenance``, when given, is filled with ``chunk_id -> {"lexical",
+        "dense"}`` naming the list(s) each fused id came from; it stays empty
+        when fusion did not happen, which the caller reads as lexical-only.
         """
         from services.retrieval import rrf
 
@@ -297,6 +305,15 @@ class CodeIndex:
             fused.setdefault(cid, 0.0)
         ranked = sorted(fused.items(), key=self._rank_key(exact_ids), reverse=True)
         tail = [(cid, score) for cid, score in lexical_ranked[n:] if cid not in fused]
+        if provenance is not None:
+            for cid in fused:
+                provenance[cid] = set()
+            for cid in lexical:
+                provenance[cid].add("lexical")
+            for cid in dense:
+                provenance[cid].add("dense")
+            for cid, _ in tail:
+                provenance[cid] = {"lexical"}
         return ranked + tail
 
     def _lexical_wanted(self) -> bool:
@@ -1254,10 +1271,17 @@ class CodeIndex:
         if ranked is None:
             ranked = self._rank_tfidf(query, query_tokens, query_bigrams, filters,
                                       exact_ids, max_mtime)
+        # Provenance (2.110.0): which list(s) produced each id, so the tool
+        # can label a hit ``[lexical+dense]`` instead of leaving the agent to
+        # guess why an unrelated-looking chunk ranked. Empty = lexical only.
+        provenance: dict = {}
+        reranked_ids: set = set()
         if fuse:
-            ranked = self._fuse_dense(query, ranked, filters, exact_ids, want=top_k)
+            ranked = self._fuse_dense(query, ranked, filters, exact_ids, want=top_k,
+                                      provenance=provenance)
         if rerank_now:
-            ranked = self._apply_rerank(query, base_tokens, ranked, exact_ids)
+            ranked = self._apply_rerank(query, base_tokens, ranked, exact_ids,
+                                        reranked=reranked_ids)
 
         # Collect results up to token budget
         results = []
@@ -1298,6 +1322,12 @@ class CodeIndex:
                 # a windowed class scores low on TF-IDF and is still the
                 # definition the query named.
                 result["exact_symbol"] = True
+            sources = ["symbol"] if chunk_id in exact_ids else []
+            lists = provenance[chunk_id] if chunk_id in provenance else {"lexical"}
+            sources.extend(s for s in ("lexical", "dense") if s in lists)
+            result["via"] = "+".join(sources)
+            if chunk_id in reranked_ids:
+                result["reranked"] = True
             if include_content:
                 result["content"] = window["content"] if window else chunk["content"]