Serena

Instructions

Implementation Reference

• src/serena/tools/file_tools.py:125-159 (handler)

  The FindFileTool class provides the core handler logic for the 'find_file' tool, implementing the apply method that searches for files matching a given mask in a directory using fnmatch and scan_directory, returning a JSON list of matches.

  class FindFileTool(Tool):
      """
      Finds files in the given relative paths
      """
  
      def apply(self, file_mask: str, relative_path: str) -> str:
          """
          Finds non-gitignored files matching the given file mask within the given relative path
  
          :param file_mask: the filename or file mask (using the wildcards * or ?) to search for
          :param relative_path: the relative path to the directory to search in; pass "." to scan the project root
          :return: a JSON object with the list of matching files
          """
          self.project.validate_relative_path(relative_path, require_not_ignored=True)
  
          dir_to_scan = os.path.join(self.get_project_root(), relative_path)
  
          # find the files by ignoring everything that doesn't match
          def is_ignored_file(abs_path: str) -> bool:
              if self.project.is_ignored_path(abs_path):
                  return True
              filename = os.path.basename(abs_path)
              return not fnmatch(filename, file_mask)
  
          _dirs, files = scan_directory(
              path=dir_to_scan,
              recursive=True,
              is_ignored_dir=self.project.is_ignored_path,
              is_ignored_file=is_ignored_file,
              relative_to=self.get_project_root(),
          )
  
          result = self._to_json({"files": files})
          return result

• src/serena/tools/tools_base.py:118-125 (registration)

  The get_name_from_cls method in the Tool base class derives the tool name 'find_file' from the class name 'FindFileTool' by removing 'Tool' suffix and converting to snake_case.

  @classmethod
  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/tools/tools_base.py:360-367 (registration)

  The ToolRegistry scans all subclasses of Tool in the serena.tools package and registers them by their derived name, including FindFileTool as 'find_file'.

  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/__init__.py:1-9 (helper)

  The __init__.py file imports all tool modules, exposing FindFileTool for use and discovery by the ToolRegistry.

  # ruff: noqa
  from .tools_base import *
  from .file_tools import *
  from .symbol_tools import *
  from .memory_tools import *
  from .cmd_tools import *
  from .config_tools import *
  from .workflow_tools import *
  from .jetbrains_tools import *