diffcontext 0.5.2__tar.gz → 0.5.4__tar.gz

{diffcontext-0.5.2 → diffcontext-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffcontext
-Version: 0.5.2
+Version: 0.5.4
 Summary: Static-analysis-powered repository context compiler for LLMs
 Author-email: Trakshan Mishra <trakshanmishra477@gmail.com>
 License: MIT

{diffcontext-0.5.2 → diffcontext-0.5.4}/diffcontext/__init__.py

@@ -32,7 +32,7 @@ Usage as a library:
     print(ctx.reduction_pct)    # how much code was filtered out
 """
 
-__version__ = "0.5.2"
+__version__ = "0.5.4"
 
 # Public, semver-covered API. Everything not listed here (graph_builder,
 # resolver, symbols, scanner, parser internals) is importable but carries no

{diffcontext-0.5.2 → diffcontext-0.5.4}/diffcontext/cli/__init__.py

@@ -23,6 +23,7 @@ import time
 from ..pipeline import index_repository, analyze_impact, compile, warn_unknown_symbols
 from ..diff.git_diff import find_changed_symbols
 from ..impact.visualizer import render_blast_radius, render_verification
+from .. import __version__ as DC_VERSION
 
 
 def main():
@@ -37,6 +38,7 @@ def main():
         prog="diffcontext",
         description="Static-analysis-powered repository context compiler for LLMs",
     )
+    parser.add_argument("--version", action="version", version=f"diffcontext {DC_VERSION}")
     sub = parser.add_subparsers(dest="command", help="Available commands")
 
     # --- index ---
@@ -113,14 +115,20 @@ def main():
              "reaches related files with no call or lexical connection)",
     )
     p_compile.add_argument("--notes", type=str, default=None, help="Developer notes to prepend to the context output")
+    p_compile.add_argument(
+        "--query-text", type=str, default=None,
+        help="Bug report or issue text. Biases retrieval toward symbols "
+             "semantically related to the described problem — the one "
+             "signal the graph alone can't provide.",
+    )
     p_compile.add_argument(
         "--meta", choices=["full", "compact", "off"], default="full",
         help=(
             "Disclosure-header level. 'full' (default): counts, architecture "
             "snapshot, dropped manifest, graph confidence, warnings. 'compact': "
-            "counts + dropped top-3 + warnings only (~60%% smaller — the A/B "
-            "test showed full meta costs ~10pp pass@1 at 4000 tokens by "
-            "displacing code). 'off': no meta-header, just code sections."
+            "counts + dropped top-3 + warnings only (~60%% smaller). 'off': no "
+            "meta-header, just code sections. The pass@1 effect of meta level "
+            "is UNMEASURED."
         ),
     )
     p_compile.add_argument("--json", action="store_true", help="Output as JSON")
@@ -384,9 +392,16 @@ def _cmd_compile(args):
         from ..history import CoChangeIndex
         history = CoChangeIndex(args.repo)
 
+    # Untuned default; not derived from any sweep. The query_weight controls
+    # how much the problem-description signal moves candidates relative to
+    # the graph + BM25 + same-file blend. 0.3 is a guess that "matters but
+    # doesn't dominate" — it has NOT been benchmarked or optimized. Do not
+    # cite this as a measured value; tune it with evidence when data exists.
+    query_weight = 0.3 if args.query_text else 0.0
     impact = analyze_impact(
         idx, changed, max_depth=args.depth, hybrid=not args.graph_only,
         history=history,
+        query_text=args.query_text, query_weight=query_weight,
     )
     max_tokens = args.max_tokens if args.max_tokens > 0 else None
     top_k = args.top_k * len(changed) if args.top_k > 0 else None

{diffcontext-0.5.2 → diffcontext-0.5.4}/diffcontext/context/compiler.py

@@ -167,11 +167,9 @@ def compile_context(
                         compacted so meta can't dwarf the code it annotates.
         meta:           Disclosure level: "full" (default — counts, architecture
                         snapshot, dropped manifest, graph confidence, warnings),
-                        "compact" (counts + dropped top-3 only — ~60% smaller),
-                        "off" (no meta-header at all, just code sections). The
-                        A/B test showed full meta costs ~10pp pass@1 at 4000
-                        tokens by displacing code; "compact" is the measured
-                        middle ground.
+                        "compact" (counts + dropped top-3 only — ~60% smaller,
+                        keeps warnings), "off" (no meta-header, just code). The
+                        pass@1 effect of meta level is UNMEASURED.
     """
     dropped_ids   = dropped_ids   or []
     skipped_files = skipped_files or []
@@ -421,9 +419,8 @@ def _build_meta_header(
 
     # --- Repository Architecture Snapshot ---
     # Skipped entirely in compact mode — it's the largest meta component
-    # (per-module listing + docstrings), and the A/B test showed meta
-    # displaces code under tight budgets. Compact keeps counts + dropped
-    # top-3 only.
+    # (per-module listing + docstrings). Compact keeps counts + dropped
+    # top-3 only. The pass@1 effect of meta level is UNMEASURED.
     if not compact:
         # Build rel_file -> absolute_path mapping from symbol table.
         # sym_id gives us relative path; sym.file gives us the absolute path we

{diffcontext-0.5.2 → diffcontext-0.5.4}/diffcontext/mcp_server.py

@@ -68,6 +68,8 @@ def main():
     args = parser.parse_args()
     default_repo = os.path.abspath(args.repo)
 
+    from diffcontext import __version__ as dc_version
+
     server = MCPServer(
         name="diffcontext",
         description=(
@@ -75,7 +77,7 @@ def main():
             "the code that matters for a change and packs it into a token "
             "budget. Measures whether it works on your repo."
         ),
-        version="0.5.1",
+        version=dc_version,
     )
 
     @server.tool()
@@ -83,8 +85,9 @@ def main():
         repo_path: str = "",
         changed_symbols: Optional[List[str]] = None,
         git_ref: Optional[str] = None,
+        task_description: Optional[str] = None,
         max_tokens: int = 8000,
-        meta: str = "compact",
+        meta: str = "full",
     ) -> str:
         """Compile LLM-ready context for a change.
 
@@ -93,6 +96,10 @@ def main():
         related functions the model needs to make the change safely — packed
         into max_tokens with a disclosure header showing what was dropped.
 
+        Optionally pass task_description (the bug report or issue text) to
+        bias retrieval toward symbols relevant to the described problem —
+        the one signal the graph alone can't provide.
+
         Args:
             repo_path: Absolute path to the repository. If omitted, uses
                 the --repo from server startup.
@@ -100,19 +107,38 @@ def main():
                 ["./src/auth.py:validate_jwt"]). Mutually exclusive with
                 git_ref.
             git_ref: Git ref to detect changes from (e.g. "HEAD~1").
-                Mutually exclusive with changed_symbols.
+                Mutually exclusive with changed_symbols. When only
+                task_description is given (no changed_symbols or git_ref),
+                defaults to "HEAD".
+            task_description: The bug report or issue text. Biases retrieval
+                toward symbols semantically related to the described problem,
+                not just structurally near the changed symbols.
             max_tokens: Token budget for the context (default 8000).
-            meta: Disclosure header level: "full", "compact" (default), or "off".
-                Compact saves ~60% of header tokens for code.
+            meta: Disclosure header level: "full" (default), "compact", or "off".
+                The pass@1 effect of meta level is UNMEASURED.
         """
         from diffcontext.pipeline import analyze_impact, compile
 
         repo = repo_path or default_repo
         idx = _get_index(repo)
-        changed = _resolve_changed(idx, changed_symbols, git_ref, repo)
-        if not changed:
-            return "No changed symbols found. Pass changed_symbols or git_ref."
-        impact = analyze_impact(idx, changed)
+
+        # When only task_description is given, auto-detect changes from HEAD.
+        effective_ref = git_ref
+        if not changed_symbols and not git_ref and task_description:
+            effective_ref = "HEAD"
+
+        changed = _resolve_changed(idx, changed_symbols, effective_ref, repo)
+        if not changed and not task_description:
+            return "No changed symbols found. Pass changed_symbols, git_ref, or task_description."
+
+        # Untuned default; not derived from any sweep. The query_weight controls
+        # how much the problem-description signal moves candidates relative to
+        # the graph + BM25 + same-file blend. 0.3 is a guess that "matters but
+        # doesn't dominate" — it has NOT been benchmarked or optimized.
+        query_weight = 0.3 if task_description else 0.0
+        impact = analyze_impact(
+            idx, changed, query_text=task_description, query_weight=query_weight,
+        )
         ctx = compile(idx, impact, max_tokens=max_tokens, meta=meta)
         return ctx.text
 

{diffcontext-0.5.2 → diffcontext-0.5.4}/diffcontext/pipeline.py

@@ -585,6 +585,8 @@ def _blend_hybrid(
     adaptive: bool = True,
     history_scores: Optional[Dict[str, float]] = None,
     history_weight: float = 0.15,
+    query_text: Optional[str] = None,
+    query_weight: float = 0.0,
 ) -> Dict[str, float]:
     """
     Blend graph impact scores with BM25 and same-file signals.
@@ -605,6 +607,16 @@ def _blend_hybrid(
     file that historically co-changed with the changed files gets
     `history_weight * association` added — the only signal that can reach
     co-change partners with no structural or lexical connection at all.
+
+    `query_text` (the bug report / issue text / task description) is an
+    optional fifth signal: BM25 scores the query text against every
+    symbol's source code, and `query_weight * normalized_score` is added
+    to each candidate. This is the one signal that ranks by relevance to
+    the *described problem* rather than structural nearness to the changed
+    symbols — the "thematic siblings" blind spot the graph alone cannot
+    address. Default query_weight=0.0 = no effect (backwards compatible).
+    When query_weight > 0, symbols matching the problem description get a
+    boost even with no call-graph or same-file connection.
     """
     from .lexical import get_lexical_index
 
@@ -630,6 +642,18 @@ def _blend_hybrid(
                 lex_raw[sid] = sc
     lex_norm = _normalize_scores(lex_raw)
 
+    # Query-text BM25: rank symbols by relevance to the described problem.
+    # This is the one signal that doesn't derive from the changed symbols
+    # at all — it reaches symbols semantically related to the bug report
+    # even with no structural or lexical connection to the changed code.
+    query_norm: Dict[str, float] = {}
+    if query_text and query_weight > 0:
+        query_raw: Dict[str, float] = {}
+        for sid, sc in lexical_index.scores_for(query_text).items():
+            if sid not in changed_set and sc > query_raw.get(sid, 0.0):
+                query_raw[sid] = sc
+        query_norm = _normalize_scores(query_raw)
+
     changed_files = {s.split(":")[0] for s in changed_in_index}
 
     history_files = {
@@ -647,6 +671,8 @@ def _blend_hybrid(
             sid for sid in index.symbols
             if sid.split(":")[0] in history_files and sid not in changed_set
         )
+    if query_norm:
+        candidates.update(query_norm.keys())
     for sid in candidates:
         score = w_graph * graph_norm.get(sid, 0.0) + w_lex * lex_norm.get(sid, 0.0)
         sid_file = sid.split(":")[0]
@@ -654,6 +680,8 @@ def _blend_hybrid(
             score += w_file
         if history_scores:
             score += history_weight * history_scores.get(sid_file, 0.0)
+        if query_norm:
+            score += query_weight * query_norm.get(sid, 0.0)
         blended[sid] = 100.0 * score
 
     # Changed symbols keep their unblended score so they stay ranked on top.
@@ -712,6 +740,8 @@ def analyze_impact(
     hybrid: bool = True,
     adaptive: bool = True,
     history: Optional[object] = None,
+    query_text: Optional[str] = None,
+    query_weight: float = 0.0,
 ) -> ImpactResult:
     """
     Phase 2: Given changed symbols, compute blast radius and impact scores.
@@ -729,6 +759,16 @@ def analyze_impact(
         co-change association is blended as a fourth signal — the only
         signal that can reach co-change partners with no structural or
         lexical connection (the measured cross-subsystem ceiling).
+    query_text: the bug report / issue text / task description. When given
+        with query_weight > 0, BM25 scores the query text against every
+        symbol's source code and adds query_weight * normalized_score to
+        each candidate. This is the one signal that ranks by relevance to
+        the *described problem* rather than structural nearness — the
+        "thematic siblings" blind spot. Default query_weight=0.0 = no
+        effect (backwards compatible).
+    query_weight: weight for the query_text signal (default 0.0 = off).
+        When > 0, symbols matching the problem description get a boost
+        even with no call-graph or same-file connection.
 
     Fix: expanded_deps is now passed into compute_impact_scores so those
     nodes are actually scored. Previously they were computed and discarded.
@@ -774,6 +814,7 @@ def analyze_impact(
         scores = _blend_hybrid(
             index, changed_symbols, scores,
             adaptive=adaptive, history_scores=history_scores,
+            query_text=query_text, query_weight=query_weight,
         )
 
     return ImpactResult(
@@ -836,9 +877,7 @@ def compile(
                         manifest, graph confidence, warnings), "compact"
                         (counts + dropped top-3 only — ~60% smaller, keeps
                         warnings), "off" (no meta-header, just code). The
-                        A/B test showed full meta costs ~10pp pass@1 at 4000
-                        tokens by displacing code; compact is the measured
-                        middle ground.
+                        pass@1 effect of meta level is UNMEASURED.
     """
     # Apply dependency-type boost BEFORE selection (the key experiment).
     # Boosts direct callees, callers, and siblings of changed symbols so

{diffcontext-0.5.2 → diffcontext-0.5.4}/diffcontext.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffcontext
-Version: 0.5.2
+Version: 0.5.4
 Summary: Static-analysis-powered repository context compiler for LLMs
 Author-email: Trakshan Mishra <trakshanmishra477@gmail.com>
 License: MIT

{diffcontext-0.5.2 → diffcontext-0.5.4}/tests/test_compiler_meta.py

@@ -210,8 +210,7 @@ class TestDocstringCache:
 
 class TestMetaLevels:
     """The --meta full|compact|off flag controls the disclosure header's
-    budget cost. The A/B test showed full meta costs ~10pp pass@1 at 4000
-    tokens by displacing code; compact is the measured middle ground."""
+    budget cost. The pass@1 effect of meta level is UNMEASURED."""
 
     def _make_pkg(self, meta=None):
         symbols = _make_symbols()

{diffcontext-0.5.2 → diffcontext-0.5.4}/tests/test_core.py

@@ -305,5 +305,85 @@ class TestPipeline:
         assert ctx.token_estimate > 0
 
 
+class TestQueryText:
+    """The query_text signal: BM25 scores the bug report / issue text
+    against every symbol's source code, adding a relevance-to-the-problem
+    signal the graph alone can't provide.
+
+    Two requirements the user asked for:
+    1. query_text=None reproduces current ranking byte-identically
+       (regression guard — no behavior change when the feature is off).
+    2. A non-None value measurably reorders results (the signal actually
+       changes the ranking, not just the scores).
+    """
+
+    def test_none_reproduces_baseline_byte_identically(self):
+        """The regression guard: query_text=None must not change ANY score,
+        not even by a floating-point epsilon. This is what keeps the feature
+        truly opt-in — existing users see zero behavior change."""
+        _require_fixture(MEDIUM, "medium_repo")
+        idx = index_repository(MEDIUM)
+        seed = "./service.py:onboard_user"
+
+        baseline = analyze_impact(idx, [seed])
+        with_query_kwarg = analyze_impact(
+            idx, [seed], query_text=None, query_weight=0.0,
+        )
+        # Every score must be identical — not just the set of candidates,
+        # but the actual float values. query_text=None is a true no-op.
+        assert baseline.scores == with_query_kwarg.scores, (
+            "query_text=None must reproduce baseline scores exactly; "
+            "the feature must be a true no-op when disabled."
+        )
+
+    def test_query_text_reorders_results(self):
+        """A non-None query_text must measurably change the ranking — not
+        just add candidates, but move at least one existing symbol to a
+        different rank position. This proves the signal is doing work."""
+        _require_fixture(MEDIUM, "medium_repo")
+        idx = index_repository(MEDIUM)
+        seed = "./service.py:onboard_user"
+
+        baseline = analyze_impact(idx, [seed])
+        base_ranked = sorted(baseline.scores.items(), key=lambda x: -x[1])
+        base_order = [sid for sid, _ in base_ranked]
+
+        # "email validation check" should boost is_valid_email (whose code
+        # contains "email" and "valid") above User.__init__ (which doesn't).
+        impacted = analyze_impact(
+            idx, [seed], query_text="email validation check", query_weight=0.3,
+        )
+        q_ranked = sorted(impacted.scores.items(), key=lambda x: -x[1])
+        q_order = [sid for sid, _ in q_ranked]
+
+        assert base_order != q_order, (
+            "query_text must reorder at least one symbol; if the ranking "
+            "is identical the signal has no effect."
+        )
+        # Specifically: is_valid_email should rank higher with the query
+        # "email validation check" than without it.
+        base_email_rank = base_order.index("./validators.py:is_valid_email")
+        q_email_rank = q_order.index("./validators.py:is_valid_email")
+        assert q_email_rank < base_email_rank, (
+            f"is_valid_email should rank HIGHER with query_text='email "
+            f"validation check' (baseline rank {base_email_rank} -> query "
+            f"rank {q_email_rank}), not lower or unchanged."
+        )
+
+    def test_query_weight_zero_is_noop(self):
+        """query_weight=0.0 must be a no-op even with non-None query_text."""
+        _require_fixture(MEDIUM, "medium_repo")
+        idx = index_repository(MEDIUM)
+        seed = "./service.py:onboard_user"
+
+        baseline = analyze_impact(idx, [seed])
+        with_weight_zero = analyze_impact(
+            idx, [seed], query_text="email validation", query_weight=0.0,
+        )
+        assert baseline.scores == with_weight_zero.scores, (
+            "query_weight=0.0 must be a no-op even with non-None query_text."
+        )
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])