Карта кодовой базы Graphify

Graphify строит из репозитория постоянный knowledge graph: код разбирается через AST, документация и медиа добавляются как семантические узлы, а связи помечаются как найденные или выведенные. Для этого проекта результат хранится в graphify-out/.

Основные файлы graphify-out/ закоммичены намеренно: они помогают быстро понять связи между backend, frontend, документацией, контрактами и generated-артефактами без полного перечитывания репозитория. При этом каталог помечен в .gitattributes как linguist-generated=true, поэтому GitHub Linguist не должен учитывать его в языках кодовой базы. graphify-out/graph.json дополнительно исключён из обычного текстового diff, чтобы ревью не тонуло в машинном JSON.

Что внутри

• graphify-out/graph.html - интерактивная визуализация графа.
• graphify-out/GRAPH_REPORT.md - текстовый отчёт: крупные узлы, сообщества, мосты между подсистемами и предупреждения диагностики.
• graphify-out/graph.json - машинный граф для запросов, путей и повторного анализа.
• graphify-out/manifest.json и cost.json - метаданные сборки.
• graphify-out/cache/ - локальный кэш извлечения, чтобы повторные запуски не начинались с нуля. Он остаётся в .gitignore и не коммитится.

Не правьте эти файлы вручную. Если карта устарела, перегенерируйте её из корня репозитория и коммитьте изменившиеся файлы graphify-out/, кроме graphify-out/cache/, вместе с изменением, из-за которого граф поменялся.

Когда обновлять

Обновляйте graphify-out/, когда меняется архитектура проекта или появляются новые связи, которые полезно видеть при ревью:

• крупный рефакторинг backend, frontend или worker;
• новые payment-провайдеры, plugin hooks, доменные события или HTTP-контракты;
• перенос документации, изменение dev stand или pipeline generated-артефактов;
• подготовка к security/architecture review, где важны пути между подсистемами.

Для мелкой правки текста, локали или изолированного теста граф обычно не нужен.

Установка

Вариант через uv:

uv tool install graphifyy
graphify install

Вариант через pipx:

pipx install graphifyy
graphify install

Код Graphify умеет разбирать локально через tree-sitter. Для расширенной семантической обработки документации и медиа можно задать ключ Gemini:

$env:GEMINI_API_KEY = "..."

Перегенерация

Запускайте из корня репозитория:

graphify .

После запуска проверьте результат:

Start-Process .\graphify-out\graph.html
Get-Content .\graphify-out\GRAPH_REPORT.md -Encoding UTF8 -TotalCount 80

Если отчёт показывает предупреждения диагностики, сначала оцените их контекст: для большого репозитория часть предупреждений может быть шумом от сгенерированных или агрегированных связей. Важны повторяющиеся подозрительные узлы, неожиданные циклы и связи между подсистемами, которые не должны знать друг о друге.

Полезные запросы

graphify query "как устроена авторизация?"
graphify query "что связывает платежных провайдеров с вебхуками?"
graphify explain "PaymentProviderSpec"
graphify path "TelegramAuth" "UserSubscription"

query удобен для обзорных вопросов, explain - для разбора конкретного узла, а path - для проверки, через какие файлы и сущности связаны две части системы. Ответы Graphify помогают ориентироваться, но не заменяют чтение исходников и контрактных тестов: связи INFERRED нужно воспринимать как гипотезы для проверки.

Как ревьюить изменения графа

1. Сначала смотрите обычный кодовый diff.
2. Затем открывайте graphify-out/GRAPH_REPORT.md и проверяйте, не появились ли неожиданные god nodes, новые мосты между несвязанными областями или резкий рост предупреждений.
3. graphify-out/graph.html используйте для визуальной проверки крупных архитектурных изменений.
4. Не требуйте ручных правок в graphify-out/: все замечания исправляются в исходниках или документации, после чего Graphify запускается заново.