diffcontext 0.5.3__tar.gz → 0.5.5__tar.gz

{diffcontext-0.5.3 → diffcontext-0.5.5}/PKG-INFO

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

{diffcontext-0.5.3 → diffcontext-0.5.5}/diffcontext/__init__.py

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

{diffcontext-0.5.3 → diffcontext-0.5.5}/diffcontext/cache.py

@@ -1,21 +1,36 @@
 """
 cache.py — SQLite-backed persistent caching for AST parsed symbols and the
 repository call graph.
+
+Cache path resolution (cascade, in order):
+1. DIFFCONTEXT_CACHE_DIR env var (if set)
+2. repo_path/.diffcontext_cache.db (current behaviour, keeps cache locality)
+3. $XDG_CACHE_HOME/diffcontext/<sha256 of abs repo_path>.db
+   or ~/.cache/diffcontext/<sha256>.db
+4. sqlite ':memory:' (degraded — no persistence across calls, but working)
+
+The cascade ensures DiffContext works on read-only repos (Glama sandbox,
+CI checkouts, containers with read-only rootfs, repos the user doesn't own).
+Do NOT fail the call because of cache — a stale or missing cache only costs
+a re-parse, never correctness.
 """
 
 import hashlib
 import json
+import logging
+import os
 import sqlite3
 from typing import Dict, Callable, List, Optional, Tuple
 
 from .models import Symbol
 
+logger = logging.getLogger(__name__)
+
 
 def get_file_hash(filepath: str) -> str:
-    """Compute SHA-256 hash of a file."""
+    """Compute SHA-256 of a file."""
     hasher = hashlib.sha256()
     with open(filepath, "rb") as f:
-        # Python files are small enough to read into memory safely
         hasher.update(f.read())
     return hasher.hexdigest()
 
@@ -26,11 +41,7 @@ def hash_source(source_bytes: bytes) -> str:
 
 
 def repo_state_hash(file_hashes: Dict[str, str]) -> str:
-    """
-    Single hash summarizing the content state of every Python file in the
-    repo. Keyed on (relative_path, content_hash) pairs, order-independent.
-    Any file added, removed, or edited changes this hash.
-    """
+    """Single hash summarizing the content state of every Python file."""
     hasher = hashlib.sha256()
     for path in sorted(file_hashes):
         hasher.update(path.encode("utf-8"))
@@ -40,17 +51,84 @@ def repo_state_hash(file_hashes: Dict[str, str]) -> str:
     return hasher.hexdigest()
 
 
+def _resolve_cache_path(
+    repo_path: Optional[str] = None,
+    cache_dir: Optional[str] = None,
+) -> str:
+    """
+    Resolve the SQLite cache database path via a cascade.
+
+    1. If `cache_dir` is explicitly passed (from --cache-dir CLI flag), use it.
+    2. If DIFFCONTEXT_CACHE_DIR env var is set, use it.
+    3. Try repo_path/.diffcontext_cache.db (keeps cache locality with the repo).
+    4. Fall back to $XDG_CACHE_HOME/diffcontext/<hash>.db or ~/.cache/diffcontext/<hash>.db
+    5. Fall back to ':memory:' (degraded — no persistence, but working).
+
+    Steps 3 and 4 try to create the file/dir; if they fail (read-only
+    filesystem, permission denied), the cascade continues. Step 5 always
+    works.
+
+    Returns a path string (or ':memory:').
+    """
+    # 1. Explicit override (highest priority)
+    if cache_dir:
+        try:
+            os.makedirs(cache_dir, exist_ok=True)
+        except OSError:
+            pass
+        return os.path.join(cache_dir, ".diffcontext_cache.db")
+
+    # 2. Env var override
+    env_cache_dir = os.environ.get("DIFFCONTEXT_CACHE_DIR")
+    if env_cache_dir:
+        try:
+            os.makedirs(env_cache_dir, exist_ok=True)
+        except OSError:
+            pass
+        return os.path.join(env_cache_dir, ".diffcontext_cache.db")
+
+    # 3. In-repo path (current behaviour, keeps cache locality)
+    if repo_path:
+        in_repo = os.path.join(repo_path, ".diffcontext_cache.db")
+        # Try to create/test writability. If it works, use it.
+        try:
+            # Touch to test writability (file may already exist)
+            fd = os.open(in_repo, os.O_CREAT | os.O_WRONLY | os.O_APPEND, 0o644)
+            os.close(fd)
+            return in_repo
+        except OSError:
+            logger.debug("cache: repo_path not writable (%s), falling back", in_repo)
+
+    # 4. XDG cache dir
+    xdg_cache = os.environ.get("XDG_CACHE_HOME", os.path.join(os.path.expanduser("~"), ".cache"))
+    # Hash the abs repo path so different repos don't collide
+    repo_hash = hashlib.sha256(os.path.abspath(repo_path or "").encode()).hexdigest()[:16]
+    cache_subdir = os.path.join(xdg_cache, "diffcontext")
+    xdg_path = os.path.join(cache_subdir, f"{repo_hash}.db")
+    try:
+        os.makedirs(cache_subdir, exist_ok=True)
+        fd = os.open(xdg_path, os.O_CREAT | os.O_WRONLY | os.O_APPEND, 0o644)
+        os.close(fd)
+        logger.debug("cache: using XDG cache at %s", xdg_path)
+        return xdg_path
+    except OSError:
+        logger.debug("cache: XDG cache dir not writable (%s), falling back to :memory:", xdg_path)
+
+    # 5. In-memory (always works, but no persistence)
+    logger.debug("cache: all disk locations failed, using :memory:")
+    return ":memory:"
+
+
 class SymbolCache:
     """
     Persistent SQLite cache for parsed AST symbols and the call graph.
 
-    Safe for concurrent use from multiple threads within one process: the
-    connection is created with check_same_thread=False and every public
-    operation holds an internal lock (SQLite serializes at the file level
-    across processes on its own via WAL).
+    The cache path is resolved via _resolve_cache_path(). On read-only
+    repos, the cascade falls back to XDG cache or :memory: — the call
+    never fails because of cache.
     """
 
-    def __init__(self, db_path: str = ".diffcontext_cache.db"):
+    def __init__(self, db_path: str = ":memory:"):
         import threading
         self.db_path = db_path
         self._conn = None
@@ -61,10 +139,6 @@ class SymbolCache:
         if self._conn is None:
             self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
             self._conn.execute("PRAGMA journal_mode=WAL")
-            # Cache contents are rebuildable from source; NORMAL skips the
-            # per-commit fsync (a measurable cost at one commit per file on
-            # a cold index) and risks nothing worse than a stale cache row
-            # after power loss, which the content hash then invalidates.
             self._conn.execute("PRAGMA synchronous=NORMAL")
             self._conn.execute("PRAGMA foreign_keys=ON")
             self._init_db()

{diffcontext-0.5.3 → diffcontext-0.5.5}/diffcontext/cli/__init__.py

@@ -50,6 +50,12 @@ def main():
              "(tests/, benchmarks/, docs/, ...). Useful when a change "
              "spans an excluded dir; .gitignore still applies.",
     )
+    p_index.add_argument(
+        "--cache-dir", default=None, metavar="DIR",
+        help="Cache database location (default: repo/.diffcontext_cache.db, "
+             "falls back to XDG cache or :memory: on read-only repos). "
+             "Also settable via DIFFCONTEXT_CACHE_DIR env var.",
+    )
 
     # --- impact ---
     p_impact = sub.add_parser("impact", help="Analyze impact of a symbol change")
@@ -83,6 +89,12 @@ def main():
     p_compile.add_argument("--changed", nargs="+", help="Changed symbol IDs")
     p_compile.add_argument("--ref", default=None, help="Git ref (auto-detect changes)")
     p_compile.add_argument("--repo", default=".", help="Repository path")
+    p_compile.add_argument(
+        "--cache-dir", default=None, metavar="DIR",
+        help="Cache database location (default: repo/.diffcontext_cache.db, "
+             "falls back to XDG cache or :memory: on read-only repos). "
+             "Also settable via DIFFCONTEXT_CACHE_DIR env var.",
+    )
     p_compile.add_argument(
         "--include", nargs="*", default=[], metavar="DIR",
         help="Directory names to index despite default exclusions (tests/, "
@@ -270,7 +282,7 @@ def _cmd_index(args):
     """Index repository: show stats."""
     t0 = time.perf_counter()
     include = set(args.include or [])
-    idx = index_repository(args.repo, include=include)
+    idx = index_repository(args.repo, include=include, cache_dir=args.cache_dir)
     elapsed = (time.perf_counter() - t0) * 1000
 
     print(f"Symbols : {len(idx.symbols)}")
@@ -368,7 +380,10 @@ def _cmd_diff(args):
 
 def _cmd_compile(args):
     """Build full context package."""
-    idx = index_repository(args.repo, include=set(args.include or []))
+    idx = index_repository(
+        args.repo, include=set(args.include or []),
+        cache_dir=getattr(args, "cache_dir", None),
+    )
 
     # Determine changed symbols
     if args.changed:
@@ -392,6 +407,11 @@ 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,

{diffcontext-0.5.3 → diffcontext-0.5.5}/diffcontext/mcp_server.py

@@ -131,8 +131,10 @@ def main():
         if not changed and not task_description:
             return "No changed symbols found. Pass changed_symbols, git_ref, or task_description."
 
-        # query_weight > 0 only when task_description is provided — the
-        # signal is opt-in and has no effect when absent (backwards compat).
+        # 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,

{diffcontext-0.5.3 → diffcontext-0.5.5}/diffcontext/parser.py

@@ -166,12 +166,12 @@ def extract_all_symbols(
     that failed to parse (SyntaxError) are appended to it.
     """
     from .scanner import find_python_files
-    from .cache import SymbolCache
+    from .cache import SymbolCache, _resolve_cache_path
 
     repo_path = os.path.abspath(repo_path)
     all_symbols: Dict[str, Symbol] = {}
     
-    db_path = os.path.join(repo_path, ".diffcontext_cache.db")
+    db_path = _resolve_cache_path(repo_path)
 
     with SymbolCache(db_path) as cache:
         for filepath in find_python_files(repo_path):

{diffcontext-0.5.3 → diffcontext-0.5.5}/diffcontext/pipeline.py

@@ -24,7 +24,7 @@ from .models import (
 from .languages import available_adapters, discover_files
 from .parser import extract_symbols
 from .scanner import find_python_files, first_excluded_dir
-from .cache import SymbolCache, get_file_hash, hash_source, repo_state_hash
+from .cache import SymbolCache, get_file_hash, hash_source, repo_state_hash, _resolve_cache_path
 from .resolver import build_import_map
 from .graph_builder import build_repository_graph
 from ._warn_once import warn_syntax_error_once, check_and_warn_encoding, WarnState
@@ -104,6 +104,7 @@ def _read_and_parse(
 
 def index_repository(
     repo_path: str, include: Optional[Set[str]] = None,
+    cache_dir: Optional[str] = None,
 ) -> RepositoryIndex:
     """
     Phase 1: Parse repository and build dependency graph.
@@ -123,9 +124,14 @@ def index_repository(
     list of files (if any) that failed to parse due to a SyntaxError. The
     returned index supports in-process incremental updates via
     `index.update([...])`.
+
+    `cache_dir` overrides the cache location. If None, the cascade in
+    `_resolve_cache_path` is used: repo_path/.diffcontext_cache.db →
+    XDG cache → :memory:. Pass a path to force a specific location (also
+    settable via DIFFCONTEXT_CACHE_DIR env var).
     """
     repo_path = os.path.abspath(repo_path)
-    db_path = os.path.join(repo_path, ".diffcontext_cache.db")
+    db_path = _resolve_cache_path(repo_path, cache_dir)
 
     files = find_python_files(repo_path, include)
 
@@ -258,6 +264,7 @@ def index_repository(
     index._lang_graphs = lang_graphs    # None on graph-cache hit (lazy)
     index._warn_state = warn_state
     index._include = include            # scanner dirs to keep despite defaults
+    index._cache_dir = cache_dir         # cache location override for update_index
     return index
 
 
@@ -442,7 +449,8 @@ def update_index(index: RepositoryIndex, changed_files: List[str]) -> Repository
             "index_repository()."
         )
     repo_path = index._repo_path
-    db_path = os.path.join(repo_path, ".diffcontext_cache.db")
+    cache_dir = getattr(index, "_cache_dir", None)
+    db_path = _resolve_cache_path(repo_path, cache_dir)
 
     _ensure_trees(index)
 

{diffcontext-0.5.3 → diffcontext-0.5.5}/diffcontext.egg-info/PKG-INFO

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

{diffcontext-0.5.3 → diffcontext-0.5.5}/diffcontext.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ diffcontext/verify/cases.py
 diffcontext/verify/history.py
 diffcontext/verify/sufficiency.py
 tests/test_cache.py
+tests/test_cache_fallback.py
 tests/test_compiler_meta.py
 tests/test_core.py
 tests/test_cutoff.py

diffcontext-0.5.5/tests/test_cache_fallback.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+tests/test_cache_fallback.py — Tests for the cache path cascade.
+
+The cascade: repo_path/.diffcontext_cache.db → XDG cache → :memory:.
+Ensures DiffContext works on read-only repos (Glama sandbox, CI checkouts,
+containers with read-only rootfs, repos the user doesn't own).
+"""
+
+import os
+import shutil
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from diffcontext.cache import _resolve_cache_path
+from diffcontext.pipeline import index_repository
+
+FIXTURES = os.path.join(os.path.dirname(os.path.dirname(__file__)), "tests", "fixtures")
+SIMPLE = os.path.join(FIXTURES, "simple_repo")
+
+
+class TestResolveCachePath:
+    def test_explicit_cache_dir_takes_priority(self, tmp_path):
+        """--cache-dir / env var overrides everything."""
+        path = _resolve_cache_path("/some/repo", cache_dir=str(tmp_path))
+        assert path == os.path.join(str(tmp_path), ".diffcontext_cache.db")
+
+    def test_env_var_takes_priority(self, tmp_path, monkeypatch):
+        """DIFFCONTEXT_CACHE_DIR env var is used when no explicit override."""
+        monkeypatch.setenv("DIFFCONTEXT_CACHE_DIR", str(tmp_path))
+        path = _resolve_cache_path("/some/repo")
+        assert path == os.path.join(str(tmp_path), ".diffcontext_cache.db")
+
+    def test_readonly_repo_falls_back_to_xdg(self, tmp_path, monkeypatch):
+        """Read-only repo dir falls back to XDG cache."""
+        monkeypatch.delenv("DIFFCONTEXT_CACHE_DIR", raising=False)
+        xdg = tmp_path / "xdg"
+        monkeypatch.setenv("XDG_CACHE_HOME", str(xdg))
+
+        # Make repo dir read-only
+        ro_repo = tmp_path / "ro_repo"
+        ro_repo.mkdir()
+        (ro_repo / "main.py").write_text("def f():\n    return 1\n")
+        os.chmod(str(ro_repo), 0o555)  # read-only
+
+        path = _resolve_cache_path(str(ro_repo))
+        assert ".cache" in path or "xdg" in path
+        assert path != os.path.join(str(ro_repo), ".diffcontext_cache.db")
+
+        os.chmod(str(ro_repo), 0o755)  # cleanup
+
+    def test_memory_fallback_when_all_disk_fails(self, monkeypatch):
+        """When repo is read-only AND XDG cache is not writable, fall to :memory:."""
+        monkeypatch.delenv("DIFFCONTEXT_CACHE_DIR", raising=False)
+        monkeypatch.setenv("XDG_CACHE_HOME", "/nonexistent/path/that/does/not/exist")
+
+        path = _resolve_cache_path("/also/nonexistent")
+        assert path == ":memory:", f"expected :memory:, got {path}"
+
+
+class TestReadOnlyRepoIndexing:
+    def test_readonly_repo_still_indexes(self, tmp_path):
+        """The Glama sandbox / CI checkout use case: repo is read-only."""
+        # Copy the fixture to a temp dir, make it read-only
+        ro = tmp_path / "ro_repo"
+        shutil.copytree(SIMPLE, str(ro))
+        # Remove any existing cache
+        cache = ro / ".diffcontext_cache.db"
+        if cache.exists():
+            cache.unlink()
+
+        # Make the entire repo read-only
+        for root, dirs, files in os.walk(str(ro)):
+            os.chmod(root, 0o555)
+            for f in files:
+                os.chmod(os.path.join(root, f), 0o444)
+
+        # This must not raise — the cascade falls back to XDG or :memory:
+        idx = index_repository(str(ro))
+        assert len(idx.symbols) > 0, "indexing must succeed on read-only repo"
+
+        # Restore permissions for cleanup
+        for root, dirs, files in os.walk(str(ro)):
+            os.chmod(root, 0o755)
+            for f in files:
+                os.chmod(os.path.join(root, f), 0o644)
+
+    def test_env_var_override_honored(self, tmp_path, monkeypatch):
+        """DIFFCONTEXT_CACHE_DIR forces the cache location."""
+        cache_dir = tmp_path / "custom_cache"
+        monkeypatch.setenv("DIFFCONTEXT_CACHE_DIR", str(cache_dir))
+
+        idx = index_repository(SIMPLE)
+        assert len(idx.symbols) > 0
+        assert cache_dir.exists(), "custom cache dir must be created"
+        assert (cache_dir / ".diffcontext_cache.db").exists(), "cache db must be in the custom dir"
+
+    def test_memory_cache_works_when_both_fail(self, tmp_path, monkeypatch):
+        """When both repo and XDG are unwritable, :memory: still indexes."""
+        ro = tmp_path / "ro_repo"
+        shutil.copytree(SIMPLE, str(ro))
+        cache = ro / ".diffcontext_cache.db"
+        if cache.exists():
+            cache.unlink()
+
+        for root, dirs, files in os.walk(str(ro)):
+            os.chmod(root, 0o555)
+            for f in files:
+                os.chmod(os.path.join(root, f), 0o444)
+
+        monkeypatch.delenv("DIFFCONTEXT_CACHE_DIR", raising=False)
+        monkeypatch.setenv("XDG_CACHE_HOME", "/nonexistent")
+
+        idx = index_repository(str(ro))
+        assert len(idx.symbols) > 0, "indexing must succeed even with :memory: cache"
+
+        for root, dirs, files in os.walk(str(ro)):
+            os.chmod(root, 0o755)
+            for f in files:
+                os.chmod(os.path.join(root, f), 0o644)

{diffcontext-0.5.3 → diffcontext-0.5.5}/tests/test_core.py

@@ -308,55 +308,80 @@ class TestPipeline:
 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."""
+    signal the graph alone can't provide.
 
-    def test_query_text_adds_candidates(self):
+    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)
-        sym_id = "./service.py:onboard_user"
-        assert sym_id in idx.graph
-
-        # Without query_text: baseline scores
-        impact_base = analyze_impact(idx, [sym_id])
-        base_sids = set(impact_base.scores)
+        seed = "./service.py:onboard_user"
 
-        # With query_text: should surface additional candidates whose code
-        # matches the described problem but may have no call-graph connection.
-        # Use a query that matches symbols in the medium repo.
-        impact_q = analyze_impact(
-            idx, [sym_id], query_text="create user order onboard", query_weight=0.3,
+        baseline = analyze_impact(idx, [seed])
+        with_query_kwarg = analyze_impact(
+            idx, [seed], query_text=None, query_weight=0.0,
         )
-        query_sids = set(impact_q.scores)
-
-        # Query-text candidates can add symbols the graph didn't reach.
-        # At minimum, the query should not REMOVE any baseline candidates.
-        assert base_sids.issubset(query_sids), (
-            "query_text must not remove baseline candidates, only add them"
+        # 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_weight_zero_is_noop(self):
+    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)
-        sym_id = "./service.py:onboard_user"
+        seed = "./service.py:onboard_user"
 
-        # query_weight=0.0 = no effect (backwards compatible)
-        impact_off = analyze_impact(idx, [sym_id], query_text="anything", query_weight=0.0)
-        impact_none = analyze_impact(idx, [sym_id])
-        # Same scores (query_text with weight 0 is a no-op)
-        assert impact_off.scores == impact_none.scores, (
-            "query_weight=0.0 must be a no-op"
+        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_no_query_text_is_noop(self):
+    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)
-        sym_id = "./service.py:onboard_user"
+        seed = "./service.py:onboard_user"
 
-        # No query_text = no effect even if query_weight > 0
-        impact_off = analyze_impact(idx, [sym_id], query_weight=0.3)
-        impact_none = analyze_impact(idx, [sym_id])
-        assert impact_off.scores == impact_none.scores, (
-            "no query_text with query_weight > 0 must be a no-op"
+        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."
         )