Serena

Instructions

Implementation Reference

• src/serena/tools/symbol_tools.py:288-312 (handler)

  Core handler for the 'rename_symbol' MCP tool. The RenameSymbolTool.apply method implements the tool logic by creating a CodeEditor and invoking its rename_symbol method to perform the refactoring.

  class RenameSymbolTool(Tool, ToolMarkerSymbolicEdit):
      """
      Renames a symbol throughout the codebase using language server refactoring capabilities.
      """
  
      def apply(
          self,
          name_path: str,
          relative_path: str,
          new_name: str,
      ) -> str:
          """
          Renames the symbol with the given `name_path` to `new_name` throughout the entire codebase.
          Note: for languages with method overloading, like Java, name_path may have to include a method's
          signature to uniquely identify a method.
  
          :param name_path: name path of the symbol to rename (definitions in the `find_symbol` tool apply)
          :param relative_path: the relative path to the file containing the symbol to rename
          :param new_name: the new name for the symbol
          :return: result summary indicating success or failure
          """
          code_editor = self.create_code_editor()
          status_message = code_editor.rename_symbol(name_path, relative_file_path=relative_path, new_name=new_name)
          return status_message

• src/serena/tools/tools_base.py:358-367 (registration)

  ToolRegistry.__init__ automatically discovers all subclasses of Tool (including RenameSymbolTool) in serena.tools packages and registers them with snake_case names derived from class names (RenameSymbolTool -> 'rename_symbol').

  self._tool_dict: dict[str, RegisteredTool] = {}
  for cls in iter_subclasses(Tool):
      if not any(cls.__module__.startswith(pkg) for pkg in tool_packages):
          continue
      is_optional = issubclass(cls, ToolMarkerOptional)
      name = cls.get_name_from_cls()
      if name in self._tool_dict:
          raise ValueError(f"Duplicate tool name found: {name}. Tool classes must have unique names.")
      self._tool_dict[name] = RegisteredTool(tool_class=cls, is_optional=is_optional, tool_name=name)

• src/serena/tools/tools_base.py:119-125 (helper)

  Tool.get_name_from_cls derives the MCP tool name 'rename_symbol' from the class name 'RenameSymbolTool'.

  def get_name_from_cls(cls) -> str:
      name = cls.__name__
      if name.endswith("Tool"):
          name = name[:-4]
      # convert to snake_case
      name = "".join(["_" + c.lower() if c.isupper() else c for c in name]).lstrip("_")
      return name

• src/serena/code_editor.py:351-377 (helper)

  LanguageServerCodeEditor.rename_symbol performs the actual renaming using LSP 'rename' request and applies the resulting workspace edit across the codebase.

  def rename_symbol(self, name_path: str, relative_file_path: str, new_name: str) -> str:
      symbol = self._find_unique_symbol(name_path, relative_file_path)
      if not symbol.location.has_position_in_file():
          raise ValueError(f"Symbol '{name_path}' does not have a valid position in file for renaming")
  
      # After has_position_in_file check, line and column are guaranteed to be non-None
      assert symbol.location.line is not None
      assert symbol.location.column is not None
  
      lang_server = self._get_language_server(relative_file_path)
      rename_result = lang_server.request_rename_symbol_edit(
          relative_file_path=relative_file_path, line=symbol.location.line, column=symbol.location.column, new_name=new_name
      )
      if rename_result is None:
          raise ValueError(
              f"Language server for {lang_server.language_id} returned no rename edits for symbol '{name_path}'. "
              f"The symbol might not support renaming."
          )
      num_changes = self._apply_workspace_edit(rename_result)
  
      if num_changes == 0:
          raise ValueError(
              f"Renaming symbol '{name_path}' to '{new_name}' resulted in no changes being applied; renaming may not be supported."
          )
  
      msg = f"Successfully renamed '{name_path}' to '{new_name}' ({num_changes} changes applied)"
      return msg

• src/serena/code_editor.py:429-439 (helper)

  JetBrainsCodeEditor.rename_symbol delegates to JetBrainsPluginClient for IDE-based refactoring support.

  def rename_symbol(self, name_path: str, relative_file_path: str, new_name: str) -> str:
      with JetBrainsPluginClient.from_project(self._project) as client:
          client.rename_symbol(
              name_path=name_path,
              relative_path=relative_file_path,
              new_name=new_name,
              rename_in_comments=False,
              rename_in_text_occurrences=False,
          )
          return "Success"