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

[vitali87]

Consolidating #411 and #412 into this issue

Per this issue's own description, #415 is the combined implementation of #411 (structural search) and #412 (structural rewrite). They are three issues for one deliverable, so I am closing #411 and #412 as subsumed by this issue and using #415 as the single tracker for the ast-grep toolkit.

Verified against current code: ast-grep is not integrated in any form. A whole-repo search for ast-grep / ast_grep / ast-grep-py / SgRoot returns only two hits, both in docs/reports/LANGUAGE_RECOMMENDATIONS.md, where it is cited as an architecture reference, not used. There is no tools/ast_grep_service.py, no structural_search.py / structural_editor.py, no STRUCTURAL_SEARCH / STRUCTURAL_REPLACE enum members, and no [ast-grep] extra in pyproject.toml (extras are test, treesitter-full, semantic). The existing editing tool (tools/file_editor.py) is text-based diff-match-patch, not AST-aware, which is exactly the gap this toolkit fills.

The acceptance criteria already listed on this issue cover both search and rewrite, so no changes are needed here.

Scope note

This is the foundational toolkit. The other two ast-grep issues remain open as distinct follow-ons that build on it:

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