java-codebase-rag 0.9.7__py3-none-any.whl → 0.10.0__py3-none-any.whl

java_codebase_rag/search/search_lancedb.py

@@ -7,8 +7,11 @@ import argparse
 import json
 import os
 import sys
+import tempfile
 import threading
+import warnings
 from collections.abc import Callable
+from contextlib import contextmanager
 from pathlib import Path
 
 import lancedb
@@ -44,8 +47,10 @@ from java_codebase_rag.search.search_scoring import (  # noqa: F401
     _role_weight,
     _split_identifier,
     _symbol_bonus,
+    declaration_line_number,
     explain_score_components,
     l2_distance_to_score,
+    vector_display_score,
 )
 
 TABLES: dict[str, str] = {
@@ -296,6 +301,117 @@ def _combine_predicates(parts: list[str | None]) -> str | None:
     return " AND ".join(f"({p})" for p in clean)
 
 
+# LanceDB (0.30.x) emits two Rust `tracing` WARN lines per hybrid query to stderr
+# — "specified output columns but did not include `_score`/`_distance` ... Call
+# `disable_scoring_autoprojection`". They are noise on the agent's stderr, not
+# Python warnings (so `warnings.filterwarnings` can't catch them), and the fluent
+# query builder exposes no `disable_scoring_autoprojection()` (the lower-level
+# `to_lance().scanner(...)` path needs `pylance`, which isn't installed on the
+# PEP 508 graph-only profile). We match them by stable substring so anything that
+# is a REAL error still reaches stderr.
+_LANCE_AUTOPROJ_MARKERS: tuple[str, ...] = (
+    "disable_scoring_autoprojection",
+    "did not include `_distance`",
+    "did not include `_score`",
+)
+
+# The fd-2 redirect below mutates the PROCESS-GLOBAL fd 2 (and
+# ``warnings.catch_warnings`` mutates global warning state). The MCP server
+# dispatches every tool call through ``asyncio.to_thread`` on a thread pool
+# (server.py), so two concurrent hybrid/auto-hybrid searches would race on the
+# dup2 bookkeeping — corrupting the saved fd and crashing the whole server with
+# ``Bad file descriptor``. Serialize the redirect so only one thread mutates fd
+# 2 / warning state at a time. Concurrent hybrid queries therefore serialize
+# their ``to_list()`` (correctness over throughput); a Rust-tracing-level
+# suppression would remove the fd hijack entirely (follow-up).
+_LANCE_WARN_REDIRECT_LOCK = threading.Lock()
+
+
+def _is_autoproj_noise(line: str) -> bool:
+    """True for a LanceDB autoprojection-deprecation line (to drop).
+
+    Preserves genuine errors/tracebacks even if they happen to reference the API
+    name — only the bare deprecation log lines (no Error/Traceback/Exception) are
+    treated as noise.
+    """
+    if not any(marker in line for marker in _LANCE_AUTOPROJ_MARKERS):
+        return False
+    return not any(seg in line for seg in ("Traceback", "Error:", "error:", "Exception"))
+
+
+@contextmanager
+def _silence_lance_autoproj_warnings():
+    """Swallow LanceDB's `_score`/`_distance` autoprojection deprecation warnings.
+
+    Redirects fd 2 to a temp buffer for the duration of the wrapped call, drops
+    only the autoprojection deprecation lines, and re-emits everything else to
+    the real stderr so genuine errors stay visible. No-op if the caller opted
+    back in via ``JAVA_CODEBASE_RAG_KEEP_LANCE_WARNINGS`` (debugging).
+
+    Thread-safety: the redirect is serialized under ``_LANCE_WARN_REDIRECT_LOCK``
+    because it mutates process-global fd 2 and warning state — the MCP server
+    runs tool calls concurrently on a thread pool.
+    """
+    if os.environ.get("JAVA_CODEBASE_RAG_KEEP_LANCE_WARNINGS"):
+        yield
+        return
+    # Also catch the (unlikely) Python-warning form defensively.
+    with _LANCE_WARN_REDIRECT_LOCK, warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message=r".*(disable_scoring_autoprojection|did not include `(_distance|_score)`).*",
+        )
+        with tempfile.TemporaryFile(mode="w+", encoding="utf-8", errors="replace") as captured:
+            saved = os.dup(2)
+            try:
+                os.dup2(captured.fileno(), 2)
+                yield
+            finally:
+                # Restore fd 2 FIRST so the re-emit below reaches real stderr.
+                os.dup2(saved, 2)
+                os.close(saved)
+            captured.seek(0)
+            kept = "".join(line for line in captured if not _is_autoproj_noise(line))
+        if kept:
+            sys.stderr.write(kept)
+            sys.stderr.flush()
+
+
+def _simple_type_name(fqn: str | None) -> str | None:
+    """``com.foo.Bar`` -> ``Bar``; None/empty -> None."""
+    if not fqn:
+        return None
+    return str(fqn).rsplit(".", 1)[-1] or None
+
+
+def _refine_java_start_lines(rows: list[dict]) -> None:
+    """Point each java row's ``start.line`` at the type declaration, not the chunk anchor.
+
+    LanceDB chunks are anchored at the chunk's first source line — for a
+    file-spanning chunk that's the package/import line (``start.line`` = 1)
+    while the ``class``/``interface`` declaration sits several lines down. The
+    chunk anchor is a poor display line for a symbol hit (renders as
+    ``File.java:1``); derive the real declaration line from the chunk text
+    (pinned to the primary type) so a hit shows ``File.java:<decl>`` instead
+    (F8). Method-only chunks whose range doesn't include a type declaration
+    keep their chunk anchor unchanged.
+    """
+    for r in rows:
+        if str(r.get("_kind", "")) != "java":
+            continue
+        start = r.get("start")
+        if not isinstance(start, dict):
+            continue
+        anchor = start.get("line")
+        if anchor is None:
+            continue
+        hints = r.get("_hints") or {}
+        type_name = hints.get("primary_type_hint") or _simple_type_name(r.get("primary_type_fqn"))
+        decl = declaration_line_number(r.get("text"), int(anchor), type_name)
+        if decl is not None:
+            start["line"] = decl
+
+
 def _search_one_table(
     table_name: str,
     *,
@@ -342,7 +458,11 @@ def _search_one_table(
         )
         if combined_pred:
             q = q.where(combined_pred, prefilter=True)
-        rows = q.to_list()
+        # Hybrid selects explicit output columns without `_score`/`_distance`, so
+        # LanceDB (0.30.x) emits two Rust autoprojection deprecation WARNs to
+        # stderr per query. Silence just those lines; real errors still surface.
+        with _silence_lance_autoproj_warnings():
+            rows = q.to_list()
         for r in rows:
             r["_kind"] = kind
             rs = r.pop("_relevance_score", None)
@@ -375,7 +495,11 @@ def _search_one_table(
         # exposed score was always 0.0, making results look unranked.
         d = r.get("_distance")
         if d is not None:
-            r["_score"] = l2_distance_to_score(float(d))
+            # Use the same non-clamping map as the display sites so graph-expand
+            # rows (which run_search does NOT overwrite) never carry the old
+            # 1-d²/2 value that collapses to 0 past √2. (The main single/multi
+            # paths overwrite this with the bonus-adjusted effective distance.)
+            r["_score"] = vector_display_score(float(d))
         r["start"] = coerce_position_field(r.get("start"))
         r["end"] = coerce_position_field(r.get("end"))
     return rows
@@ -575,6 +699,7 @@ def _graph_expand_merge(
     except Exception:
         return vector_rows
     _apply_chunk_hints(graph_rows)
+    _refine_java_start_lines(graph_rows)
     graph_rows.sort(key=_vector_sort_key)
     for r in graph_rows:
         r["_graph_expanded"] = True
@@ -737,6 +862,9 @@ def run_search(
             extra_predicates=preds,
         )
         _apply_chunk_hints(rows)
+        # Anchor each java row's start.line on the type declaration instead of
+        # the chunk's first source line (often the package/import line = 1).
+        _refine_java_start_lines(rows)
         if skip_role_weight:
             for r in rows:
                 r["_skip_role_weight"] = True
@@ -747,11 +875,14 @@ def run_search(
             _hybrid_post_sort_normalization(rows)
         else:
             rows.sort(key=_vector_sort_key)
-            # Vector: set honest displayed score from adjusted distance, clamped to [0,1]
+            # Vector: displayed score from the effective (bonus-adjusted) distance,
+            # normalized over the unit-embedding range so a correctly-ranked top
+            # hit never collapses to 0.000 (the cosine map 1 - d²/2 clamps to 0
+            # past √2; weak-but-best matches commonly sit at d ≈ 1.5).
             for r in rows:
                 comps = r.setdefault("_score_components", {})
                 effective_dist = _effective_distance(comps)
-                r["_score"] = _clamp01(l2_distance_to_score(effective_dist))
+                r["_score"] = vector_display_score(effective_dist)
 
         if graph_expand and key == "java" and expand_depth > 0:
             rows = _graph_expand_merge(
@@ -792,16 +923,17 @@ def run_search(
             )
         )
     _apply_chunk_hints(merged)
+    _refine_java_start_lines(merged)
     if skip_role_weight:
         for r in merged:
             r["_skip_role_weight"] = True
     _apply_symbol_bonus(merged, query_toks)
     merged.sort(key=_vector_sort_key)
-    # Vector: set honest displayed score from adjusted distance, clamped to [0,1]
+    # Vector: displayed score from the effective (bonus-adjusted) distance.
     for r in merged:
         comps = r.setdefault("_score_components", {})
         effective_dist = _effective_distance(comps)
-        r["_score"] = _clamp01(l2_distance_to_score(effective_dist))
+        r["_score"] = vector_display_score(effective_dist)
 
     # Dedup by primary_type_fqn after all sorting/merging, before windowing
     merged = _dedup_by_fqn(merged, dedup_by_fqn=dedup_by_fqn)

java_codebase_rag/search/search_lexical.py

@@ -18,11 +18,13 @@ guarded by a parity unit test.
 from __future__ import annotations
 
 import os
+import weakref
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from java_codebase_rag.graph.ladybug_queries import LadybugGraph
 from java_codebase_rag.search.search_scoring import (
+    SYMBOL_FTS_INDEX,
     _ROLE_SCORE_WEIGHTS,
     _TYPE_MATCH_BONUS_CAP,
     _TYPE_MATCH_BONUS_PER_HIT,
@@ -170,6 +172,88 @@ def _token_overlap(haystack_toks: set[str], needle_toks: set[str]) -> float:
     return len(needle_toks & haystack_toks) / len(needle_toks)
 
 
+# BM25 candidate fetch via the LadybugDB FTS index (fork A). DB-side indexed ranking
+# replaces the heuristic's bounded Python scan; the heuristic below still scores the
+# fetched candidates (name/type/fqn/role) and is the fallback when the FTS index or
+# extension is unavailable (older graph, offline first run).
+_FTS_CANDIDATE_K = 200  # top-K BM25 candidates; re-filtered by NodeFilter before ranking
+# Connections that have run LOAD EXTENSION FTS. Keyed by the connection OBJECT (WeakSet),
+# NOT id() — id() is reused after GC, which would let a fresh connection skip LOAD and then
+# fail at QUERY_FTS_INDEX under test batching. Entries die with the connection.
+_FTS_LOADED_CONNS: "weakref.WeakSet[object]" = weakref.WeakSet()
+
+
+def _ensure_fts_loaded(g: LadybugGraph) -> bool:
+    """LOAD EXTENSION FTS on the graph's (read-only) connection, once per connection.
+
+    Returns False if the extension can't be loaded (absent / offline) so the caller
+    falls back to the heuristic scan.
+    """
+    conn = g._conn  # noqa: SLF001
+    try:
+        if conn in _FTS_LOADED_CONNS:
+            return True
+    except Exception:  # connection not weakref-able → LOAD every call (correct, slow)
+        pass
+    try:
+        g._rows("LOAD EXTENSION FTS")  # noqa: SLF001
+        try:
+            _FTS_LOADED_CONNS.add(conn)
+        except Exception:
+            pass
+        return True
+    except Exception:
+        return False
+
+
+def _try_fts_candidates(
+    g: LadybugGraph,
+    query: str,
+    filter: NodeFilter | None,
+    path_contains: str | None,
+) -> dict | None:
+    """Fetch BM25-ranked Symbol candidates via the FTS index; re-apply NodeFilter.
+
+    Returns ``{"rows": [...], "scores": {id: bm25}}`` (rows are the same shape the
+    heuristic scan yields), or ``None`` when FTS is unavailable (extension won't load,
+    or the index isn't present on this graph) so the caller falls back.
+
+    Two-step: (1) ``QUERY_FTS_INDEX`` returns the top-K node ids by Okapi BM25 over
+    ``Symbol.search_text``; (2) re-MATCH those ids with the full ``_lexical_where``
+    predicates (role / module / path / kind≠file,package) so the filter logic stays
+    defined in one place. ``search_text`` is built at index time by ``build_ast_graph``
+    from the same ``_split_identifier`` the re-rank below uses, so index- and query-time
+    tokenization agree.
+    """
+    if not _ensure_fts_loaded(g):
+        return None
+    idx_rows = g._rows("CALL SHOW_INDEXES() RETURN index_name")  # noqa: SLF001
+    names = {row.get("index_name") for row in idx_rows}
+    if SYMBOL_FTS_INDEX not in names:
+        return None
+    fts = g._rows(  # noqa: SLF001
+        f"CALL QUERY_FTS_INDEX('Symbol', '{SYMBOL_FTS_INDEX}', $q, top := $k) "
+        "RETURN node.id AS id, score",
+        {"q": query, "k": _FTS_CANDIDATE_K},
+    )
+    if not fts:
+        return {"rows": [], "scores": {}}
+    scores = {row["id"]: float(row.get("score") or 0.0) for row in fts}
+    ids = list(scores.keys())
+
+    # Re-MATCH the K ids with the SAME predicates the heuristic pushes down, so
+    # NodeFilter / path / structural-kind filtering is defined exactly once.
+    where, params = _lexical_where(filter, path_contains=path_contains)
+    struct_pred = "(s.kind <> 'file' AND s.kind <> 'package')"
+    if not where:
+        where = f"WHERE s.id IN $ids AND {struct_pred}"
+    else:
+        where = where.replace("WHERE ", f"WHERE s.id IN $ids AND {struct_pred} AND ", 1)
+    params["ids"] = ids
+    rows = g._rows(f"MATCH (s:Symbol) {where} RETURN {_SYMBOL_RETURN}", params)  # noqa: SLF001
+    return {"rows": rows, "scores": scores}
+
+
 def run_lexical_search(
     query: str,
     *,
@@ -185,6 +269,12 @@ def run_lexical_search(
 ) -> list[dict]:
     """Keyword search over Symbol nodes; returns ``run_search``-shaped row-dicts.
 
+    BM25-first (fork A): when the LadybugDB ``sym_fts`` index exists, candidates are
+    fetched DB-side via Okapi BM25 over ``Symbol.search_text`` (killing the bounded
+    Python scan that silently missed matches past the cap on large repos) and then
+    re-ranked here by the name/type/fqn/role heuristic. Falls back to that heuristic
+    scan when the FTS index or extension is unavailable (older graph, offline first run).
+
     Raises ``RuntimeError`` (message contains "lexical search unavailable") if no
     symbol graph exists — the caller maps that to a clean failure envelope. Returns
     ``[]`` for ``table in ("sql", "yaml")`` (those LanceDB tables aren't built in
@@ -201,33 +291,38 @@ def run_lexical_search(
         )
     g = graph or LadybugGraph.get()
 
-    where, params = _lexical_where(filter, path_contains=path_contains)
-    # Always exclude structural Symbol nodes. Files and packages are :Symbol-labeled
-    # (kind='file'/'package') but aren't searchable code declarations — without this
-    # a token that appears in a filename (e.g. 'distribution' in
-    # 'DistributionChunkService.java') would surface the file node as a hit.
-    struct_pred = "(s.kind <> 'file' AND s.kind <> 'package')"
-    where = f"WHERE {struct_pred}" if not where else where.replace("WHERE ", f"WHERE {struct_pred} AND ", 1)
-    # Lexical ranking is done in Python (LadybugDB/kuzu has no keyword ranking without
-    # FTS5, which is deferred), and the MATCH scan returns rows in storage order — there
-    # is NO DB-side relevance ORDER BY. So fetch the FULL candidate pool up to the safety
-    # cap and rank here. A pagination-derived LIMIT (4x the page) is correct on the vector
-    # path where LanceDB returns rows pre-ranked by similarity, but on this unordered scan
-    # it would return only the first ~N symbols in arbitrary storage order and silently
-    # miss the best match on any non-trivial repo.
-    params["lim"] = _CANDIDATE_LIMIT_CAP
-    cypher = f"MATCH (s:Symbol) {where} RETURN {_SYMBOL_RETURN} LIMIT $lim"
-    rows = g._rows(cypher, params)  # noqa: SLF001 — de facto public read API (see find_v2)
-    # If the fetch hit the safety cap, deeper matches were never ranked (the scan has no
-    # ORDER BY — kuzu returns an arbitrary, storage-order-dependent subset). Surface it so
-    # a user on a large repo isn't silently shown an incomplete result set; refining the
-    # query or adding a filter narrows the pool below the cap. Raising the cap / FTS5 is
-    # the deferred long-term fix (see the plan's "Out of scope" note).
-    if advisories is not None and len(rows) >= _CANDIDATE_LIMIT_CAP:
-        advisories.append(
-            f"lexical search scanned the first {_CANDIDATE_LIMIT_CAP} matching symbols "
-            "(repo cap); deeper matches were not ranked — refine the query or add a filter"
-        )
+    # --- candidate fetch: BM25 (FTS) preferred, heuristic scan fallback ---
+    bm25_scores: dict[str, float] = {}
+    use_fts = False
+    fts = _try_fts_candidates(g, query, filter, path_contains)
+    if fts is not None:
+        rows = fts["rows"]
+        bm25_scores = fts["scores"]
+        use_fts = True
+    else:
+        where, params = _lexical_where(filter, path_contains=path_contains)
+        # Always exclude structural Symbol nodes. Files and packages are :Symbol-labeled
+        # (kind='file'/'package') but aren't searchable code declarations — without this
+        # a token that appears in a filename (e.g. 'distribution' in
+        # 'DistributionChunkService.java') would surface the file node as a hit.
+        struct_pred = "(s.kind <> 'file' AND s.kind <> 'package')"
+        where = f"WHERE {struct_pred}" if not where else where.replace("WHERE ", f"WHERE {struct_pred} AND ", 1)
+        # The heuristic scan returns rows in storage order — there is NO DB-side relevance
+        # ORDER BY without the FTS index — so fetch the FULL candidate pool up to the safety
+        # cap and rank here. A pagination-derived LIMIT (4x the page) is correct on the
+        # vector path where LanceDB returns rows pre-ranked, but on this unordered scan it
+        # would return only the first ~N symbols in arbitrary storage order and silently
+        # miss the best match on any non-trivial repo. The BM25 (FTS) path above has no cap.
+        params["lim"] = _CANDIDATE_LIMIT_CAP
+        cypher = f"MATCH (s:Symbol) {where} RETURN {_SYMBOL_RETURN} LIMIT $lim"
+        rows = g._rows(cypher, params)  # noqa: SLF001 — de facto public read API (see find_v2)
+        # If the fetch hit the safety cap, deeper matches were never ranked. Surface it so
+        # a user on a large repo isn't silently shown an incomplete result set.
+        if advisories is not None and len(rows) >= _CANDIDATE_LIMIT_CAP:
+            advisories.append(
+                f"lexical search scanned the first {_CANDIDATE_LIMIT_CAP} matching symbols "
+                "(repo cap); deeper matches were not ranked — refine the query or add a filter"
+            )
 
     query_toks = _query_tokens(query)
     source_root = _resolve_source_root(g)
@@ -265,9 +360,10 @@ def run_lexical_search(
         text_match = text_overlap * _TEXT_MATCH_WEIGHT
 
         # A keyword search must require at least one lexical hit — role alone never
-        # qualifies a row (it only boosts/reorders matches). Degenerate queries with
-        # no usable tokens fall through to role-ranked listing.
-        if query_toks and not (name_overlap or type_hits or fqn_match or text_overlap):
+        # qualifies a row (it only boosts/reorders matches). On the BM25 path the FTS
+        # index already established textual relevance, so the qualifier is heuristic-only.
+        # Degenerate queries with no usable tokens fall through to role-ranked listing.
+        if query_toks and not use_fts and not (name_overlap or type_hits or fqn_match or text_overlap):
             continue
 
         role_w = 0.0 if role_locked else _ROLE_SCORE_WEIGHTS.get(role_raw.upper(), 0.0)
@@ -291,6 +387,8 @@ def run_lexical_search(
             "lexical_relevance": round(raw, 4),
             "role_weight": role_w,
         }
+        if use_fts:
+            comps["bm25"] = round(float(bm25_scores.get(r.get("id"), 0.0)), 4)
 
         sl, el, sb, eb = r.get("start_line"), r.get("end_line"), r.get("start_byte"), r.get("end_byte")
         out.append(

java_codebase_rag/search/search_scoring.py

@@ -12,6 +12,12 @@ Everything here is pure-Python dict/list math with no third-party deps.
 from __future__ import annotations
 
 import json
+import re
+
+# Name of the LadybugDB FTS (Okapi BM25) index over Symbol.search_text (fork A).
+# Shared by the build path (build_ast_graph._ensure_symbol_fts_index) and the
+# query path (search_lexical.run_lexical_search) so the two never drift.
+SYMBOL_FTS_INDEX = "sym_fts"
 
 # Over-fetch multiplier for dedup: fetch 4x to absorb per-FQN chunk multiplicity
 # so that after collapsing by primary_type_fqn, a page stays full and the +1
@@ -210,6 +216,29 @@ def l2_distance_to_score(distance: float) -> float:
     return 1.0 - distance * distance / 2.0
 
 
+# Display-score denominator for the vector backend. Unit-normalized embeddings
+# have L2 distance in [0, 2]; the cosine map ``l2_distance_to_score`` (1 - d²/2)
+# goes NEGATIVE past √2 ≈ 1.414 and clamps to 0. Weak-but-best semantic matches
+# (e.g. a lone keyword like "controller") commonly sit at d ≈ 1.5, so EVERY hit
+# clamps to score=0.000 even though the ranking is correct. ``vector_display_score``
+# instead normalizes the effective (bonus-adjusted) distance over the full
+# unit-embedding range, so a top-ranked hit stays visibly non-zero. Role/symbol
+# bonuses reduce the effective distance and so raise the displayed score,
+# keeping it rank-monotonic with the distance-based sort key.
+_VECTOR_DISTANCE_REF = 2.0
+
+
+def vector_display_score(effective_distance: float) -> float:
+    """Displayed vector score in [0, 1] from the effective (bonus-adjusted) distance.
+
+    Bounded linear normalization over the unit-embedding L2 range [0, 2]: lower
+    distance → higher score. Unlike ``l2_distance_to_score`` (which goes
+    negative past √2 and clamps a correctly-ranked top hit to 0.000), this keeps
+    a top result visibly non-zero while staying rank-monotonic with the sort key.
+    """
+    return _clamp01(1.0 - effective_distance / _VECTOR_DISTANCE_REF)
+
+
 def _effective_distance(comps: dict[str, float]) -> float:
     """Compute the adjusted distance used for sorting.
 
@@ -231,6 +260,59 @@ def _clamp01(x: float) -> float:
     return x
 
 
+# Matches a Java top-level type declaration and captures its simple name. Mirrors
+# the heuristic in ``ast.chunk_heuristics._JAVA_TYPE`` but is duplicated here so
+# this module stays dependency-free (importable on graph-only Intel installs).
+_JAVA_TYPE_DECL_RE = re.compile(
+    r"\b(?:public\s+|private\s+|protected\s+|sealed\s+|non-sealed\s+|final\s+|"
+    r"abstract\s+|static\s+)*"
+    r"(?:class|interface|enum|record)\s+([A-Za-z_][A-Za-z0-9_]*)"
+)
+
+
+def declaration_line_number(
+    text: str | None, anchor_line: int | None, type_name: str | None = None
+) -> int | None:
+    """Absolute 1-based line of the Java type declaration within chunk ``text``.
+
+    LanceDB chunks are anchored at the chunk's first source line, which for a
+    file-spanning chunk is the package/import line (``anchor_line`` = 1) while
+    the ``class``/``interface`` declaration sits several lines down. Without
+    this, hits render as ``File.java:1`` even though the symbol is declared
+    later (F8). Returns ``anchor_line + i`` for the first matching declaration
+    (pinned to ``type_name`` when given, so a nested type doesn't win), or
+    ``anchor_line`` unchanged when no declaration is found in the chunk.
+
+    Comment-aware: Javadoc/line/block-comment lines that merely MENTION the type
+    name (e.g. ``* This class Bar handles...``) are skipped so the returned line
+    is the real declaration, not a comment above it.
+    """
+    if not text or anchor_line is None:
+        return anchor_line
+    in_block = False
+    for i, raw in enumerate(text.splitlines()):
+        # Drop a trailing ``// ...`` line comment before any matching (a ``//``
+        # inside a string literal is unrealistic for a declaration line).
+        code = raw.split("//", 1)[0]
+        stripped = code.strip()
+        if in_block:
+            if "*/" in stripped:
+                in_block = False
+            continue
+        if stripped.startswith("/*"):
+            # Single-line ``/* ... */`` -> skip without entering block state.
+            if "*/" not in stripped[2:]:
+                in_block = True
+            continue
+        if not stripped or stripped.startswith("*"):
+            # Blank or a Javadoc continuation line (`` * ...``).
+            continue
+        m = _JAVA_TYPE_DECL_RE.search(code)
+        if m and (not type_name or m.group(1) == type_name):
+            return anchor_line + i
+    return anchor_line
+
+
 def explain_score_components(
     comps: dict[str, float] | None,
     *,