feat(tools): full ast-grep toolkit with structural search and rewrite

[vitali87]

Summary

Add both structural search AND structural rewrite as new tools, creating a complete "ast-grep toolkit" within CGR. This combines Options 1 and 2 into a single cohesive implementation that delivers the most user-facing value with the least architectural risk.

Motivation

Search + rewrite is the natural pair (find pattern, then fix it). This requires no changes to the graph schema, parser infrastructure, or indexing pipeline. It is purely additive: new tools alongside existing ones with zero regression risk. Both the agentic chat and MCP server get new capabilities, and the LLM agent can chain: structural_search -> review matches -> structural_replace.

Implementation

Files to Create

• codebase_rag/tools/ast_grep_service.py (~200 lines) wrapping ast-grep-py with search() and replace() methods
• codebase_rag/tools/structural_search.py (~80 lines) agentic tool wrapper
• codebase_rag/tools/structural_editor.py (~80 lines) agentic tool wrapper

Files to Modify

• Add enums: STRUCTURAL_SEARCH, STRUCTURAL_REPLACE to AgenticToolName and MCPToolName
• Add descriptions to tool_descriptions.py
• Add types to types_defs.py: StructuralSearchMatch, StructuralReplaceChange
• Register in main.py and mcp/tools.py
• Add ast-grep-py as optional dependency ([ast-grep] extra) in pyproject.toml

Design Decisions

• Shared service layer (ast_grep_service.py) avoids code duplication between search and replace tools
• Optional dependency with graceful degradation
• Dry-run mode for replace operations with diff preview
• Integration with existing approval workflow

Acceptance Criteria

• ast-grep-py added as optional dependency under [ast-grep] extra
• Structural search tool: find code by AST patterns, returns file paths + line numbers + matched code
• Structural replace tool: rewrite code by AST patterns, with dry-run and approval workflow
• Both tools registered for agentic chat and MCP server
• LLM agent can chain search -> review -> replace in a single conversation
• Graceful degradation when ast-grep-py is not installed
• TypedDict types for search matches and replace changes
• Unit tests for both search and replace operations
• Works across all languages supported by ast-grep

Related

This is the combined implementation of:

• feat(tools): add structural pattern search via ast-grep #411 structural search tool
• feat(tools): add AST-aware code rewriting via ast-grep #412 structural rewrite tool

Serves as foundation for:

• feat(graph): enrich knowledge graph with pattern/smell/vulnerability detection via ast-grep rules #413 graph enrichment via ast-grep rules
• feat(parsers): accelerate new language support using ast-grep patterns #414 accelerated language support