# tools-ast-grep

## Назначение

`tools-ast-grep` дает агенту read-only структурный поиск по JavaScript, TypeScript, TSX и Python. В отличие от текстового `grep`, tool ищет AST-паттерны и возвращает места, где кодовая структура совпала с запросом.

## Почему он есть в проекте

Extension нужен как безопасная разведка перед изменениями кода. Агент может проверить, где в проекте встречается нужная конструкция, не открывая write-доступ и не запуская subprocess.

## Пользовательская поверхность

Агент вызывает tool `ast_grep`, когда ему нужен структурный поиск по коду. Обязательные параметры: `pat` с AST-паттерном и `paths` со списком файлов, директорий или простых path/glob-выражений. Optional параметр `language` задает язык явно; без него язык определяется по расширению файла.

## Как работает по коду

Entrypoint валидирует параметры через TypeBox, расширяет `paths` относительно project root через `_shared/files.expandPaths`, а затем передает файлы и паттерн в `_shared/ast-engine.astSearch`. Для Python движок один раз регистрирует dynamic language из `@ast-grep/lang-python`, а для JS/TS/TSX использует языки `@ast-grep/napi`.

Tool возвращает текстовый список совпадений в формате `file:line:column: text` и структурные details с количеством совпадений, числом файлов с совпадениями, числом просмотренных файлов и признаком truncation. Вывод дополнительно ограничивается через `safeToolText`, чтобы большой search не раздувал ответ агента.

- Entrypoint: `./extensions/tools-ast-grep/index.ts`
- Manifest: `extensions/tools-ast-grep/manifest.json`
- Commands: none
- Tools: `ast_grep`
- Hooks: none
- Permissions: fs.read=`.`, fs.write=none, subprocess=none, network=none, browser=false, models=false, ui=none
- State: Extension не хранит состояние между вызовами; каждый search заново читает разрешенные файлы.
- Review: status=reviewed, source=write-from-scratch, reviewedBy=pi-dev-extensions, reviewedAt=2026-05-31, risk=medium

## Ограничения и риски

Tool остается read-only, поэтому основной риск связан не с записью файлов, а с точностью поиска и размером результата. `expandPaths` ограничивает количество файлов, а `ast_grep` дополнительно режет список совпадений до bounded output.

Поддержка path/glob-выражений минимальная и не заменяет полноценный glob matcher. Если файл имеет неподдержанное расширение или паттерн не парсится как AST-паттерн выбранного языка, tool вернет ошибку вместо частичного результата.

## Решение

Решение: оставить `tools-ast-grep`. Это реальный development tool с read-only моделью, тестами для TypeScript и Python и ограниченным выводом.