Merge pull request #30 from oraios/feature/new_tool_request_referencing_code_chunks

New tool: GetReferencingCodeExtractsTool

CHANGELOG.md

@@ -1,3 +1,7 @@
 # Changelog
 
+## 06.04.2025
+- New tool: FindReferencingCodeSnippets
+- Adjusted prompt in CreateTextFileTool to prevent writing partial content (see [here](https://www.reddit.com/r/ClaudeAI/comments/1jpavtm/comment/mloek1x/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button)).
+
 ## 01.04.2025: Initial Release

README.md

@@ -560,6 +560,7 @@ Here the full list of Serena's default tools with a short description (the outpu
  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
  * `get_dir_overview`: Gets an overview of the top-level symbols defined in all files within a given directory.
  * `get_document_overview`: Gets an overview of the top-level symbols defined in a given file.
+ * `get_referencing_code_extracts`: Gets the code blocks that reference the symbol at the given location.
  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
  * `insert_at_line`: Inserts content at a given line in a file.
  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
@@ -569,6 +570,7 @@ Here the full list of Serena's default tools with a short description (the outpu
  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
  * `read_file`: Reads a file within the project directory.
  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+ * `replace_lines`: Replaces a range of lines within a file with new content.
  * `replace_symbol_body`: Replaces the full definition of a symbol.
  * `search_in_all_code`: Performs a search for a pattern in all code files (and only in code files) in the project.
  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
@@ -576,4 +578,3 @@ Here the full list of Serena's default tools with a short description (the outpu
  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
-

src/serena/agent.py

@@ -332,6 +332,10 @@ class CreateTextFileTool(Tool):
         You can also use insert_at_line to insert content at a specific line for existing files if the symbolic operations
         are not the right choice for what you want to do.
 
+        If ever used on an existing file, the content has to be the complete content of that file (so it
+        may never end with something like "The remaining content of the file is left unchanged.").
+        For operations that just replace a part of a file, use the replace_lines or the symbolic editing tools instead.
+
         :param relative_path: the relative path to the file to create
         :param content: the (utf-8-encoded) content to write to the file
         :return: a message indicating success or failure
@@ -536,6 +540,50 @@ class FindReferencingSymbolsTool(Tool):
         return self._limit_length(result, max_answer_chars)
 
 
+class FindReferencingCodeSnippetsTool(Tool):
+    """
+    Finds code snippets in which the symbol at the given location is referenced.
+    """
+
+    def apply(
+        self,
+        relative_path: str,
+        line: int,
+        column: int,
+        context_lines_before: int = 0,
+        context_lines_after: int = 0,
+        max_answer_chars: int = _DEFAULT_MAX_ANSWER_LENGTH,
+    ) -> str:
+        """
+        Returns short code snippets where the symbol at the given location is referenced.
+
+        Contrary to the `find_referencing_symbols` tool, this tool returns references that are not symbols but instead
+        code snippets that may or may not be contained in a symbol (for example, file-level calls).
+        It may make sense to use this tool to get a quick overview of the code that references
+        the symbol. Usually, just looking at code snippets is not enough to understand the full context,
+        unless the case you are investigating is very simple,
+        or you already have read the relevant symbols using the find_referencing_symbols tool and
+        now want to get an overview of how the referenced symbol (at the given location) is used in them.
+        The size of the snippets is controlled by the context_lines_before and context_lines_after parameters.
+
+        :param relative_path: the relative path to the file containing the symbol
+        :param line: the line number of the symbol to find references for
+        :param column: the column of the symbol to find references for
+        :param context_lines_before: the number of lines to include before the line containing the reference
+        :param context_lines_after: the number of lines to include after the line containing the reference
+        :param max_answer_chars: if the output is longer than this number of characters,
+            no content will be returned. Don't adjust unless there is really no other way to get the content
+            required for the task. Instead, if the output is too long, you should
+            make a stricter query.
+        """
+        matches = self.language_server.request_references_with_content(
+            relative_path, line, column, context_lines_before, context_lines_after
+        )
+        result = [match.to_display_string() for match in matches]
+        result_json_str = json.dumps(result)
+        return self._limit_length(result_json_str, max_answer_chars)
+
+
 class ReplaceSymbolBodyTool(Tool):
     """
     Replaces the full definition of a symbol.