JetBrainsFindReferencingSymbolsTool: Add computation of context lines

based on line number now returned by plugin

src/serena/jetbrains/jetbrains_types.py

@@ -1,5 +1,10 @@
 from typing import Literal, NotRequired, TypedDict
 
+JB_EXTERNAL_FILE_PREFIX = "<ext:"
+"""
+Prefix used for in relative paths of symbols that are from external libraries (i.e., not defined in the user's codebase).
+"""
+
 
 class PluginStatusDTO(TypedDict):
     project_root: str
@@ -22,15 +27,48 @@ class SymbolDTO(TypedDict):
     type: str
     body: NotRequired[str]
     quick_info: NotRequired[str]
-    """Quick info text (e.g., type signature) for the symbol, as HTML string."""
+    """quick info text (e.g., type signature) for the symbol, as HTML string."""
     documentation: NotRequired[str]
-    """Documentation text for the symbol (if available), as HTML string."""
+    """documentation text for the symbol (if available), as HTML string."""
     text_range: NotRequired[TextRangeDTO]
     children: NotRequired[list["SymbolDTO"]]
     num_usages: NotRequired[int]
+    reference_line_no: NotRequired[int]
+    """
+    for the case where this is a reference, the line number of the reference (0-based, relative to the file where the symbol is defined).
+    """
+
+    # --- Python-side extensions, i.e. fields that are not returned by the plugin but set later by the Python code ---
+
+    context: NotRequired[str]
+    """
+    context around the symbol/reference, e.g., a few lines of code before and after the symbol definition or reference, 
+    to provide additional context for the LLM.
+    """
 
 
-SymbolDTOKey = Literal["name_path", "relative_path", "type", "body", "quick_info", "documentation", "text_range", "children", "num_usages"]
+SymbolDTOKey = Literal[
+    "name_path",
+    "relative_path",
+    "type",
+    "body",
+    "quick_info",
+    "documentation",
+    "text_range",
+    "children",
+    "num_usages",
+    "reference_line_no",
+    "context",
+]
+
+
+class SymbolDTOUtil:
+    @staticmethod
+    def is_external_symbol(symbol_dto: SymbolDTO) -> bool:
+        """
+        Checks if a symbol is an external symbol (i.e., from a library) based on its relative path.
+        """
+        return symbol_dto["relative_path"].startswith(JB_EXTERNAL_FILE_PREFIX)
 
 
 class SymbolCollectionResponse(TypedDict):

src/serena/tools/jetbrains_tools.py

@@ -5,7 +5,7 @@ from typing import Any, Literal
 import serena.jetbrains.jetbrains_types as jb
 from serena.code_editor import JetBrainsCodeEditor
 from serena.jetbrains.jetbrains_plugin_client import JetBrainsPluginClient
-from serena.jetbrains.jetbrains_types import SymbolDTO
+from serena.jetbrains.jetbrains_types import SymbolDTO, SymbolDTOUtil
 from serena.symbol import JetBrainsSymbolDictGrouper
 from serena.tools import Tool, ToolMarkerBeta, ToolMarkerOptional, ToolMarkerSymbolicEdit, ToolMarkerSymbolicRead
 from serena.util.text_utils import find_text_coordinates
@@ -259,7 +259,19 @@ class JetBrainsFindReferencingSymbolsTool(Tool, ToolMarkerSymbolicRead, ToolMark
             )
         symbol_dicts = response_dict["symbols"]
 
-        # capture file paths before grouping, which mutates the dicts
+        # replace reference line number (if present) by actual line/context
+        for symbol_dict in symbol_dicts:
+            if "reference_line_no" in symbol_dict:
+                ref_line = symbol_dict["reference_line_no"]
+                ref_relative_path = symbol_dict["relative_path"]
+                if not SymbolDTOUtil.is_external_symbol(symbol_dict) and ref_line is not None and ref_line >= 0:
+                    content_around_ref = self.project.retrieve_content_around_line(
+                        relative_file_path=ref_relative_path, line=ref_line, context_lines_before=1, context_lines_after=1
+                    )
+                    symbol_dict["context"] = content_around_ref.to_display_string()
+                    del symbol_dict["reference_line_no"]
+
+        # capture file paths before grouping
         ref_paths = [s.get("relative_path", "unknown") for s in symbol_dicts]
 
         result = self.symbol_dict_grouper.group(symbol_dicts)

src/serena/tools/symbol_tools.py

@@ -290,7 +290,7 @@ class FindReferencingSymbolsTool(Tool, ToolMarkerSymbolicRead):
                 ref_dict["content_around_reference"] = content_around_ref.to_display_string()
             reference_dicts.append(ref_dict)
 
-        # capture lightweight reference data before grouping, which mutates the dicts
+        # capture lightweight reference data before grouping
         ref_summaries = []
         for ref, d in zip(references_in_symbols, reference_dicts, strict=True):
             ref_summaries.append(