feat(tools): add structural pattern search via ast-grep

[vitali87]

Summary

Add ast-grep as a new search tool alongside Cypher queries and semantic search, giving the LLM agent the ability to find code by structural AST patterns.

Motivation

Cypher finds graph relationships and semantic search finds similar code, but neither can find structural patterns like "all functions that call logger.info with exactly 2 arguments" or "all try/except blocks that catch Exception". ast-grep fills this gap with real-time, pattern-based structural search that requires no pre-indexing.

The LLM agent can compose ast-grep patterns on the fly, enabling a new class of code queries that complement the existing tools.

Implementation

• codebase_rag/tools/structural_search.py (~80 lines) agentic tool wrapper
• codebase_rag/tools/ast_grep_service.py (shared service, search portion)
• Add STRUCTURAL_SEARCH to AgenticToolName enum in tool_descriptions.py
• Add STRUCTURAL_SEARCH to MCPToolName enum in constants.py
• Add StructuralSearchMatch type to types_defs.py
• Register tool in main.py (_initialize_services_and_agent) and mcp/tools.py (MCPToolsRegistry)
• Add ast-grep-py as optional dependency in pyproject.toml under [ast-grep] extra

Acceptance Criteria

• ast-grep-py added as optional dependency (uv sync --extra ast-grep)
• Structural search tool callable by agentic chat and MCP server
• LLM agent can compose patterns and receive matched code with file paths and line numbers
• Graceful degradation when ast-grep-py is not installed
• Works on raw source files without requiring prior graph indexing
• Unit tests covering pattern matching for at least Python and JavaScript

Related

Part of the ast-grep integration initiative:

• feat(tools): add AST-aware code rewriting via ast-grep #412 structural rewrite tool
• 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
• feat(tools): full ast-grep toolkit with structural search and rewrite #415 combined search + rewrite toolkit