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]