Serena

Instructions

Implementation Reference

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

  Handler implementation: FindReferencingSymbolsTool.apply() method executes the core tool logic, finding references via LanguageServerSymbolRetriever and formatting the JSON output with code snippets.
  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:526-606 (helper)

  Core helper methods in LanguageServerSymbolRetriever: find_referencing_symbols locates the target symbol and delegates to find_referencing_symbols_by_location, which queries the LSP for references and filters by kinds.
  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 symbol with the given name. If multiple symbols fit the name (e.g. for variables that are overwritten), will use the first one. :param name_path: the name path of the symbol to find :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_candidates = self.find_by_name(name_path, substring_matching=False, within_relative_path=relative_file_path) if len(symbol_candidates) == 0: log.warning(f"No symbol with name {name_path} found in file {relative_file_path}") return [] if len(symbol_candidates) > 1: log.error( f"Found {len(symbol_candidates)} symbols with name {name_path} in file {relative_file_path}." f"May be an overwritten variable, in which case you can ignore this error. Proceeding with the first one. " f"Found symbols for {name_path=} in {relative_file_path=}: \n" f"{json.dumps([s.location.to_dict() for s in symbol_candidates], indent=2)}" ) symbol = symbol_candidates[0] return self.find_referencing_symbols_by_location( symbol.location, include_body=include_body, include_kinds=include_kinds, exclude_kinds=exclude_kinds ) 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]
• src/serena/agent.py:214-214 (registration)

  Tools including FindReferencingSymbolsTool are automatically registered by subclassing Tool and collected via ToolRegistry.get_all_tool_classes() in SerenaAgent initialization.
  self._all_tools: dict[type[Tool], Tool] = {tool_class: tool_class(self) for tool_class in ToolRegistry().get_all_tool_classes()}