codecortex 0.15.2__tar.gz → 0.15.4__tar.gz

{codecortex-0.15.2/src/codecortex.egg-info → codecortex-0.15.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.2
+Version: 0.15.4
 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

{codecortex-0.15.2 → codecortex-0.15.4/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.2
+Version: 0.15.4
 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

{codecortex-0.15.2 → codecortex-0.15.4}/src/codecortex.egg-info/SOURCES.txt

@@ -20,13 +20,16 @@ src/codeintel/http_server.py
 src/codeintel/indexer.py
 src/codeintel/injector.py
 src/codeintel/installer.py
+src/codeintel/loc.py
 src/codeintel/logconfig.py
 src/codeintel/mapper.py
 src/codeintel/metrics.py
 src/codeintel/onboarding.py
+src/codeintel/outcome.py
 src/codeintel/policy.py
 src/codeintel/provider.py
 src/codeintel/py.typed
+src/codeintel/redact.py
 src/codeintel/reindexer.py
 src/codeintel/reset.py
 src/codeintel/searcher.py
@@ -60,12 +63,15 @@ tests/test_cache.py
 tests/test_chunking.py
 tests/test_cli_commands.py
 tests/test_cli_help.py
+tests/test_cold_process.py
 tests/test_config.py
+tests/test_corpus.py
 tests/test_doctor.py
 tests/test_e2e.py
 tests/test_engine_adoption.py
 tests/test_enterprise.py
 tests/test_gateway.py
+tests/test_graph_failure_population.py
 tests/test_graph_provider.py
 tests/test_graph_real.py
 tests/test_graph_stdin.py
@@ -73,8 +79,10 @@ tests/test_grapher.py
 tests/test_hardening.py
 tests/test_http_auth.py
 tests/test_http_server.py
+tests/test_incompleteness.py
 tests/test_installer.py
 tests/test_integration.py
+tests/test_loc_census.py
 tests/test_lsp_provider.py
 tests/test_lsp_real.py
 tests/test_mapper.py

codecortex-0.15.4/src/codeintel/__init__.py

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

{codecortex-0.15.2 → codecortex-0.15.4}/src/codeintel/commands/query.py

@@ -1,6 +1,7 @@
 """`codeintel query` — one question against the gateway: search, callers, callees, impact, chain."""
 
 import json
+import os
 import sys
 import time
 from typing import Any
@@ -12,6 +13,36 @@ from codeintel.provider import Result, safe_null_result
 # and reporting whatever the gateway last said.
 _WARMING_TIMEOUT_S = 45.0
 
+# Per-query time budget, in milliseconds, handed to whichever engine answers.
+#
+# This used to be omitted entirely, so every engine fell back to its own default — 5s for the LSP
+# provider — against a cold first `symbol` query measured at 11.65s on a real 841-file TypeScript
+# repo. The call timed out, the reference lookup came back empty, and the empty list was rendered
+# as "(none)": a confident false answer produced by a missing argument. A CLI invocation is a
+# human or an agent waiting on one question; it can afford to wait properly.
+_CLI_BUDGET_MS = 30_000
+
+
+def _budget_ms() -> int:
+    """The per-query budget, overridable via ``CODEINTEL_BUDGET_MS``.
+
+    Two reasons this is an env var rather than a constant. Operators on slow machines or huge
+    repositories need to raise it. And tests need to LOWER it: the cold-process tier exists to catch
+    the defect where a timed-out backend call is rendered as a confident "(none)", but on a fast
+    machine the cold call simply succeeds, so the tier passed with that exact regression planted
+    back in. A budget it can drive to near-zero lets it reproduce the starvation condition
+    deterministically instead of waiting for a slow day.
+    """
+    raw = os.environ.get("CODEINTEL_BUDGET_MS", "").strip()
+    if raw:
+        try:
+            n = int(raw)
+            if n > 0:
+                return n
+        except ValueError:
+            pass
+    return _CLI_BUDGET_MS
+
 
 def run(args: Any) -> int:
     """`--json` promises parseable stdout, so its failures must be JSON too.
@@ -55,7 +86,9 @@ def _query(args: Any) -> Result:
 
     project_root = resolve_root(args)
     engine = args.engine if args.engine != "auto" else None
-    gw = server._build_gateway()
+    # oneshot: this process exits when the query returns, so it must not start a background
+    # reindex it cannot finish (and must not then report that reindex as staleness).
+    gw = server._build_gateway(oneshot=True)
 
     def _run_query() -> Result:
         return gw.query(
@@ -63,6 +96,7 @@ def _query(args: Any) -> Result:
             target=args.target,
             engine=engine,
             role="",
+            budget=_budget_ms(),
             project_root=project_root,
         )
 

{codecortex-0.15.2 → codecortex-0.15.4}/src/codeintel/gateway.py

@@ -6,8 +6,9 @@ from typing import Any
 
 from codeintel.cache import ContentHashCache
 from codeintel.policy import TieringPolicy
-from codeintel.provider import Result, log_swallowed, safe_null_result
+from codeintel.provider import Result, attach_confidence, log_swallowed, safe_null_result
 from codeintel.providers.none import NoneProvider
+from codeintel.redact import redact
 from codeintel.reindexer import Reindexer
 
 _KNOWN_ENGINES: frozenset[str] = frozenset({"graph", "lsp", "semantic", "auto", "both", "all"})
@@ -51,7 +52,17 @@ def _mark_reindexing(result: Result, reindexing: bool) -> Result:
 
 class Gateway:
     def __init__(self, graph=None, lsp=None, semantic=None, policy: TieringPolicy | None = None,
-                 reindexer: Reindexer | None = None):
+                 reindexer: Reindexer | None = None, oneshot: bool = False):
+        # A one-shot process (the `codeintel` CLI) must not run the long-lived server's background
+        # machinery. It used to: every query called `maybe_reindex`, which in a fresh process always
+        # passed the debounce (`_last_fired` starts empty) and submitted a pass to a DAEMON pool —
+        # then the same query asked `reindex_pending` ten lines later and was told "yes", by itself.
+        # That is why `reindexing: true` accompanied literally every answer this tool has ever
+        # produced, and why the tree was re-walked on every query. Worse, a daemon thread is killed
+        # wherever it happens to be when the process exits, so those passes never completed and wrote
+        # torn state on the way out — the most plausible source of the `.corrupt` index files found
+        # in the cache. A process that cannot finish a reindex must not start one.
+        self._oneshot = bool(oneshot)
         # Backward-compat: old tests pass a list as the first positional arg.
         if isinstance(graph, list):
             self._legacy_providers: list | None = graph
@@ -179,14 +190,32 @@ class Gateway:
                          if all_unreachable else "")),
             )
 
-        return {
+        # A fan-out answer is only as whole as its parts. This used to hand-build a six-key envelope
+        # and drop both `confidence` and `gaps` on the floor — so a `context` request (the DEFAULT
+        # fan-out op) whose graph half timed out returned the lsp half alone, unqualified, and a
+        # `partial` a provider had explicitly produced was destroyed on the way out. Worse, an engine
+        # that answered NOTHING is silently absent from `parts`: the body simply does not mention it,
+        # which reads as "that engine had nothing to add" rather than "that engine could not be asked".
+        merged_gaps: list[dict] = []
+        for eng, r in results.items():
+            merged_gaps.extend({**g, "engine": eng}
+                               for g in (r.get("gaps") or []) if isinstance(g, dict))
+            if r.get("result") is None:
+                merged_gaps.append({
+                    "section": eng,
+                    "kind": str(r.get("reason") or "no-result"),
+                    "detail": f"the {eng} engine contributed nothing to this answer "
+                              f"({r.get('reason') or 'no-result'})",
+                    "engine": eng,
+                })
+        return attach_confidence({
             "ok": True,
             "op": op_str,
             "target": target_str,
             "result": "\n\n".join(parts),
             "engine": engine_str,
             "cached": False,
-        }
+        }, merged_gaps)
 
     def _dispatch_single(
         self,
@@ -235,6 +264,28 @@ class Gateway:
         role: str = "",
         budget=None,
         project_root=None,
+    ) -> Result:
+        """Answer one question. Never raises.
+
+        A thin wrapper over `_query`, existing so that redaction has exactly ONE seam to cover.
+        Every leak found in the evaluation was in a field some renderer built and no one swept —
+        the scope note inside `result`, the "index it standalone with:" command inside `hint`. Both
+        are downstream of here, and so is anything added later."""
+        result = self._query(op, target, engine, role, budget, project_root)
+        try:
+            return redact(result)  # type: ignore[return-value]
+        except Exception as exc:
+            log_swallowed("Gateway.query.redact", exc)
+            return result
+
+    def _query(
+        self,
+        op=None,
+        target=None,
+        engine=None,
+        role: str = "",
+        budget=None,
+        project_root=None,
     ) -> Result:
         try:
             op_str = str(op or "")
@@ -258,20 +309,28 @@ class Gateway:
                                             hint="this token's role is not scoped to that "
                                                  "project_root (see the [roots] table in auth.toml)")
 
-            try:
-                self._reindexer.maybe_reindex(str(project_root or ""))
-            except Exception:
-                pass
+            if not self._oneshot:
+                try:
+                    self._reindexer.maybe_reindex(str(project_root or ""))
+                except Exception:
+                    pass
 
             # If a reindex is running, this answer comes from the PREVIOUS index. Structural
             # answers (callers/impact/hotspots) hash a symbol name, not file bytes, so nothing
             # else in the envelope can reveal that — and an agent that just edited and asked
             # "what did I break?" lands precisely here. Busting the cache would not help: the
             # index itself is behind, so re-asking refetches the same stale data.
-            try:
-                reindexing = self._reindexer.reindex_pending(str(project_root or ""))
-            except Exception:
+            # In one-shot mode this is always False and the flag is simply never emitted: no
+            # reindex was started, so there is nothing for the answer to be behind. In server mode
+            # the flag now means what it always claimed to — a pass this process did not start is
+            # genuinely still running — which is why it is fixed at the cause rather than deleted.
+            if self._oneshot:
                 reindexing = False
+            else:
+                try:
+                    reindexing = self._reindexer.reindex_pending(str(project_root or ""))
+                except Exception:
+                    reindexing = False
 
             # Legacy list-based path (backward compat with pre-Phase-2 tests)
             if self._legacy_providers is not None:

{codecortex-0.15.2 → codecortex-0.15.4}/src/codeintel/indexer.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING
 
 from codeintel.containment import contained_path, real_root
 from codeintel.source_kind import (
+    CODE_EXTS,
     load_gitattributes_globs,
     looks_generated_file,
     looks_generated_path,
@@ -31,12 +32,10 @@ _MAX_CHUNK_CHARS = 200_000
 # signal and is what `git` itself uses.
 _BINARY_SNIFF_BYTES = 8192
 
-_INDEXED_EXTS = frozenset({
-    ".py", ".md",
-    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",       # TS/JS variants
-    ".go", ".rs", ".java",
-    ".c", ".h", ".cpp", ".cc", ".cxx", ".hpp", ".hh",    # C/C++ variants
-})
+# Derived from the shared policy rather than repeated: the corpus is "code, plus markdown". Two
+# hand-typed copies of one population is how the sign-out bug in the review notes happened — one
+# copy drifts and nothing says so.
+_INDEXED_EXTS = CODE_EXTS | {".md"}
 _SKIP_DIRS = frozenset({"__pycache__", ".git", "node_modules"})
 # Directory names that mean "generated" only at the REPO ROOT. Matching them at any depth hid real
 # source: `coverage/` is the coverage.py package, `src/build/` is pypa/build's entire codebase

codecortex-0.15.4/src/codeintel/loc.py

@@ -0,0 +1,73 @@
+"""Line-number conversion for the backends whose numbering differs from ours.
+
+**This module does not apply to every backend, and the line base is data, not a rule.** An earlier
+version of this docstring asserted "the only place in codeintel permitted to format a path:line" and
+"every backend we speak to counts lines from zero". The second claim is false, and an investigation
+found that following the first would have introduced a NEW off-by-one: the graph backend
+(codebase-memory-mcp) reports 1-based line numbers, so ``graph.py`` formats its own ``path:line``
+directly and must keep doing so. Centralising a guarantee only removes a defect class when the
+implementations agree on the semantics being centralised — here they do not.
+
+    LINE BASES, verified by probing each backend — see LINE_BASES below:
+      serena / LSP          -> use loc()/span()
+      semantic chunk_start  -> use loc()      (chunk_start = max(0, start - 1), indexer.py)
+      codebase-memory-mcp   -> see LINE_BASES below; do NOT use loc(); emit as-is
+
+Use ``loc()``/``span()`` for the 0-based backends. Every human, editor and terminal that consumes
+our output counts from one, and agent hosts turn ``path:line`` into a clickable link. Each
+renderer used to do its own conversion, which meant each renderer got to forget it independently
+— and two of them did:
+
+- ``lsp.py`` emitted serena's ``body_location`` and reference markers verbatim;
+- ``semantic.py`` emitted ``chunk_start``, which is 0-based by construction in ``indexer.py``.
+
+Both shipped answers pointing one line above the truth, and both produced ``path:0`` for anything
+at the top of a file — a line number that does not exist, which is the tell that survived into the
+evaluation transcript before anyone noticed it.
+
+Centralising the conversion is what stops the next renderer from re-deciding this. If you need a
+``path:line`` string, call ``loc()``; if you need the number alone, call ``line1()``.
+"""
+
+from __future__ import annotations
+
+# The measured line base of each backend. The prose table above is the explanation; THIS is the
+# enforced form (tests/test_loc_census.py drives every provider and checks the number it emits
+# against this map). A new provider file with no entry here fails the census.
+LINE_BASES: dict[str, int] = {"lsp": 0, "semantic": 0, "graph": 1}
+
+
+def line1(line0: object) -> int | None:
+    """Convert a backend's 0-based line number to a 1-based one.
+
+    Returns None for anything that is not a usable line number, so callers render a bare path
+    rather than inventing a position. Accepts str because some backends report line numbers as
+    text inside a larger payload.
+    """
+    if line0 is None or isinstance(line0, bool):
+        return None
+    try:
+        n = int(line0)  # type: ignore[call-overload]
+    except (TypeError, ValueError):
+        return None
+    # A negative line is meaningless; clamp rather than emit `path:-1` or `path:0`.
+    return n + 1 if n >= 0 else None
+
+
+def loc(path: object, line0: object = None) -> str:
+    """Render ``path:line`` with the line converted to 1-based, or a bare path when there is no
+    usable line. ``line0`` is the backend's own 0-based number — never pre-increment it."""
+    p = str(path or "").strip() or "?"
+    n = line1(line0)
+    return f"{p}:{n}" if n is not None else p
+
+
+def span(path: object, start0: object, end0: object = None) -> str:
+    """Render ``path:start-end`` (1-based) for a symbol body, or ``path:start``/``path`` when the
+    end is absent or unusable."""
+    p = str(path or "").strip() or "?"
+    s = line1(start0)
+    if s is None:
+        return p
+    e = line1(end0)
+    return f"{p}:{s}-{e}" if e is not None else f"{p}:{s}"

codecortex-0.15.4/src/codeintel/outcome.py

@@ -0,0 +1,77 @@
+"""A typed result for internal seams, so a failure stays a failure all the way up.
+
+Every provider-internal helper used to return ``X | None``, and ``None`` there meant five
+different things: never asked · timed out · the backend errored · the payload did not parse ·
+genuinely empty. Callers could not tell them apart, so they picked the cheapest reading — and the
+cheapest reading of "no references came back" is "this symbol has no references", which is the
+permissive answer and the wrong one.
+
+That collapse is what produced the worst bug in the 2026-08-17 evaluation: a cold language server
+timed out, ``_call_tool`` returned ``None``, and four conversions later the caller rendered
+``## References\\n(none)`` — a confident false statement, with no ``reason`` and no ``hint``,
+byte-identical to a true one.
+
+``graph.py`` had already worked this out and re-invented a fix for it three separate times in one
+module (``_FAIL``/``_UNPARSABLE``, ``ProjectLookup``, and ``_search_symbols`` returning ``None``
+vs ``[]`` on purpose). ``lsp.py`` had none of them, which is exactly where the critical bug lived.
+This is that abstraction, written once.
+
+Rule: a helper returns ``Missing`` when it could not answer, and ``Ok`` when it did — including
+``Ok`` of an empty collection, which is a real and useful answer meaning "asked, and there is
+nothing". Never conflate the two.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, Literal, TypeAlias, TypeVar
+
+T = TypeVar("T")
+
+# Why a call produced no value. These strings reach the caller inside a gap note, so they are
+# written to be read by a person or an agent, not only matched by code.
+MissingKind = Literal[
+    "not-asked",      # a precondition was absent, so the call was never made
+    "timeout",        # the backend did not answer inside the budget
+    "backend-error",  # the backend answered, and the answer was an error
+    "unparsable",     # the backend answered, and the payload could not be read
+    "unsupported",    # this backend cannot answer this question at all
+]
+
+_DETAIL: dict[str, str] = {
+    "not-asked": "a precondition for this lookup was missing, so it was never requested",
+    "timeout": "the backend did not respond within the time budget",
+    "backend-error": "the backend returned an error instead of an answer",
+    "unparsable": "the backend's response could not be parsed",
+    "unsupported": "this engine cannot answer that",
+}
+
+
+@dataclass(frozen=True)
+class Ok(Generic[T]):
+    """The call answered. ``value`` may legitimately be empty."""
+
+    value: T
+
+
+@dataclass(frozen=True)
+class Missing:
+    """The call did not answer, and this is why. Never rendered as a value."""
+
+    kind: MissingKind
+    detail: str = ""
+    retry_after_s: float | None = None
+
+    def describe(self) -> str:
+        """One caller-facing sentence. Falls back to a default phrasing per kind so that every
+        Missing carries something readable even when the call site passed no detail."""
+        return self.detail or _DETAIL.get(self.kind, "this lookup did not complete")
+
+
+Outcome: TypeAlias = "Ok[T] | Missing"
+
+
+def is_missing(outcome: object) -> bool:
+    """True when an outcome represents a failure to answer. Kept as a helper so call sites read
+    as intent rather than as an isinstance check against an implementation detail."""
+    return isinstance(outcome, Missing)

{codecortex-0.15.2 → codecortex-0.15.4}/src/codeintel/provider.py

@@ -37,6 +37,17 @@ class Result(TypedDict):
     # reflects the last COMPLETED index rather than the current source. Optional, and the MCP
     # tools deliberately return plain `dict` so this never becomes a required schema field.
     reindexing: NotRequired[bool]
+    # How much of the answer the engine vouches for. A non-null `result` used to be an implicit
+    # promise of completeness, which is how a timed-out reference lookup shipped as "(none)".
+    #   "complete" — ran; the engine stands behind the whole body
+    #   "partial"  — ran; produced a body; a NAMED part of it is known to be missing (see `gaps`)
+    # Absent on null results, where `reason` already carries the whole story.
+    confidence: NotRequired[str]
+    # One entry per part of the answer that could not be retrieved:
+    # {"section": str, "kind": str, "detail": str, "retry_after_s": float?}. Emitted only when
+    # non-empty. The same fact is always rendered into `result` too, because that is the field an
+    # agent actually reads.
+    gaps: NotRequired[list[dict[str, Any]]]
 
 
 @runtime_checkable
@@ -74,3 +85,32 @@ def safe_null_result(
     if hint is not None:
         r["hint"] = hint
     return r
+
+
+def attach_confidence(result: Result, gaps: Any = ()) -> Result:
+    """Stamp an answered envelope with how much of it the engine vouches for.
+
+    Every engine must call this, and that is the point. `confidence` was introduced on the LSP
+    provider alone, which reproduced in miniature the defect it was added to fix: the instructions
+    told callers to check a field that two of three engines never set, and an ABSENT field is
+    ambiguous — "complete" and "this engine does not report" look identical. A contract that only
+    one implementation honours is not a contract.
+
+    `gaps` is a sequence of {"section", "kind", "detail", "retry_after_s"?} dicts. Empty ⇒
+    `complete`; non-empty ⇒ `partial`, and the caller is expected to have said the same thing in
+    the body text, because that is the field an agent actually reads.
+
+    Null results are left alone: `reason` already carries the whole story there, and stamping them
+    would imply a body exists to be partial about.
+    """
+    try:
+        if result.get("result") is None:
+            return result
+        items = [g for g in (gaps or ()) if isinstance(g, dict)]
+        out: Result = {**result, "confidence": "partial" if items else "complete"}
+        if items:
+            out["gaps"] = items
+        return out
+    except Exception as exc:
+        log_swallowed("attach_confidence", exc)
+        return result