Serena

Instructions

Implementation Reference

• src/serena/tools/symbol_tools.py:152-202 (handler)

  The handler implementation for the 'find_referencing_symbols' tool. The apply method orchestrates the retrieval of referencing symbols using the LanguageServerSymbolRetriever, processes the results, adds context snippets, and returns JSON.
  class FindReferencingSymbolsTool(Tool, ToolMarkerSymbolicRead): """ Finds symbols that reference the given symbol using the language server backend """ # noinspection PyDefaultArgument def apply( self, name_path: str, relative_path: str, include_kinds: list[int] = [], # noqa: B006 exclude_kinds: list[int] = [], # noqa: B006 max_answer_chars: int = -1, ) -> str: """ Finds references to the symbol at the given `name_path`. The result will contain metadata about the referencing symbols as well as a short code snippet around the reference. :param name_path: for finding the symbol to find references for, same logic as in the `find_symbol` tool. :param relative_path: the relative path to the file containing the symbol for which to find references. Note that here you can't pass a directory but must pass a file. :param include_kinds: same as in the `find_symbol` tool. :param exclude_kinds: same as in the `find_symbol` tool. :param max_answer_chars: same as in the `find_symbol` tool. :return: a list of JSON objects with the symbols referencing the requested symbol """ include_body = False # It is probably never a good idea to include the body of the referencing symbols parsed_include_kinds: Sequence[SymbolKind] | None = [SymbolKind(k) for k in include_kinds] if include_kinds else None parsed_exclude_kinds: Sequence[SymbolKind] | None = [SymbolKind(k) for k in exclude_kinds] if exclude_kinds else None symbol_retriever = self.create_language_server_symbol_retriever() references_in_symbols = symbol_retriever.find_referencing_symbols( name_path, relative_file_path=relative_path, include_body=include_body, include_kinds=parsed_include_kinds, exclude_kinds=parsed_exclude_kinds, ) reference_dicts = [] for ref in references_in_symbols: ref_dict = ref.symbol.to_dict(kind=True, location=True, depth=0, include_body=include_body) ref_dict = _sanitize_symbol_dict(ref_dict) if not include_body: ref_relative_path = ref.symbol.location.relative_path assert ref_relative_path is not None, f"Referencing symbol {ref.symbol.name} has no relative path, this is likely a bug." 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 ) ref_dict["content_around_reference"] = content_around_ref.to_display_string() reference_dicts.append(ref_dict) result = self._to_json(reference_dicts) return self._limit_length(result, max_answer_chars)
• src/serena/symbol.py:572-594 (helper)

  Helper method in LanguageServerSymbolRetriever that resolves the symbol by name_path and calls find_referencing_symbols_by_location.
  def find_referencing_symbols( self, name_path: str, relative_file_path: str, include_body: bool = False, include_kinds: Sequence[SymbolKind] | None = None, exclude_kinds: Sequence[SymbolKind] | None = None, ) -> list[ReferenceInLanguageServerSymbol]: """ Find all symbols that reference the specified symbol, which is assumed to be unique. :param name_path: the name path of the symbol to find. (While this can be a matching pattern, it should usually be the full path to ensure uniqueness.) :param relative_file_path: the relative path of the file in which the referenced symbol is defined. :param include_body: whether to include the body of all symbols in the result. Not recommended, as the referencing symbols will often be files, and thus the bodies will be very long. :param include_kinds: which kinds of symbols to include in the result. :param exclude_kinds: which kinds of symbols to exclude from the result. """ symbol = self.find_unique(name_path, substring_matching=False, within_relative_path=relative_file_path) return self.find_referencing_symbols_by_location( symbol.location, include_body=include_body, include_kinds=include_kinds, exclude_kinds=exclude_kinds )
• src/serena/symbol.py:596-641 (helper)

  Core helper method in LanguageServerSymbolRetriever that performs the actual language server request_referencing_symbols call to fetch references, applies kind filters, and returns processed references.
  def find_referencing_symbols_by_location( self, symbol_location: LanguageServerSymbolLocation, include_body: bool = False, include_kinds: Sequence[SymbolKind] | None = None, exclude_kinds: Sequence[SymbolKind] | None = None, ) -> list[ReferenceInLanguageServerSymbol]: """ Find all symbols that reference the symbol at the given location. :param symbol_location: the location of the symbol for which to find references. Does not need to include an end_line, as it is unused in the search. :param include_body: whether to include the body of all symbols in the result. Not recommended, as the referencing symbols will often be files, and thus the bodies will be very long. Note: you can filter out the bodies of the children if you set include_children_body=False in the to_dict method. :param include_kinds: an optional sequence of ints representing the LSP symbol kind. If provided, only symbols of the given kinds will be included in the result. :param exclude_kinds: If provided, symbols of the given kinds will be excluded from the result. Takes precedence over include_kinds. :return: a list of symbols that reference the given symbol """ if not symbol_location.has_position_in_file(): raise ValueError("Symbol location does not contain a valid position in a file") assert symbol_location.relative_path is not None assert symbol_location.line is not None assert symbol_location.column is not None lang_server = self.get_language_server(symbol_location.relative_path) references = lang_server.request_referencing_symbols( relative_file_path=symbol_location.relative_path, line=symbol_location.line, column=symbol_location.column, include_imports=False, include_self=False, include_body=include_body, include_file_symbols=True, ) if include_kinds is not None: references = [s for s in references if s.symbol["kind"] in include_kinds] if exclude_kinds is not None: references = [s for s in references if s.symbol["kind"] not in exclude_kinds] return [ReferenceInLanguageServerSymbol.from_lsp_reference(r) for r in references]