Codebase Graph Explorer

Интерактивный визуализатор графа зависимостей проекта. Сканирует кодовую базу, парсит импорты и строит интерактивный граф в браузере.

Возможности

• Рекурсивное сканирование файловой системы
• Парсинг импортов Python (AST) и JavaScript/TypeScript (regex)
• Интерактивная force-directed визуализация графа на D3.js
• Зум, панорамирование, перетаскивание узлов
• Раскрытие/сворачивание директорий (двойной клик / Enter)
• Drill-down в структуру файла (функции, классы, методы — клавиша E)
• Режим фокуса (подсветка зависимостей выбранного файла, клавиша F)
• Minimap (обзор всего графа, правый нижний угол)
• Просмотр содержимого файлов с подсветкой синтаксиса (Prism.js)
• Поиск и фильтрация узлов (Ctrl+F)
• Live-обновления через SSE при изменениях файлов на диске
• Тёмная тема
• Экспорт: SVG, PNG (растр 2x), Mermaid (текстовое описание .mmd)

Поддерживаемые языки

Язык	Парсинг импортов	Анализ структуры
Python	AST	AST (функции, классы, методы)
JavaScript	Regex	Regex
TypeScript	Regex	Regex
JSX/TSX	Regex	—
Java, Go, Rust, C/C++	Базовый	—

Установка

git clone https://github.com/your-username/codebase-graph-explorer.git
cd codebase-graph-explorer
pip install -r requirements.txt

Запуск

python app.py /path/to/your/project

Откройте http://localhost:8080 в браузере.

Опции

Флаг	Описание	По умолчанию
path	Путь к директории проекта	—
--port	Порт веб-сервера	8080

Примеры

# Анализ собственного проекта
python app.py ./my-project

# Указать порт
python app.py ./my-project --port 3000

# Анализ этого же репозитория
python app.py .

Горячие клавиши

Клавиша	Действие
Ctrl+F	Поиск файлов
F	Режим фокуса (подсветка зависимостей)
R	Сбросить масштаб
A	Раскрыть/свернуть все папки
E	Раскрыть структуру файла
H	Показать/скрыть скрытые файлы
M	Экспорт в Mermaid (.mmd)
Enter	Раскрыть папку / структуру файла
Esc	Назад / Закрыть панель
Backspace	Назад к предыдущему графу
Ctrl+R	Принудительное обновление графа
?	Справка

Управление мышью

Действие	Описание
Скролл	Зум графа
Перетаскивание фона	Панорамирование
Клик по узлу	Выбор / просмотр файла
Двойной клик по папке	Раскрыть/свернуть директорию
Двойной клик по файлу	Раскрыть структуру файла
Перетаскивание узла	Перемещение узла

Экспорт

• SVG — векторная графика, масштабируется без потери качества
• PNG — растровое изображение с удвоенным разрешением (2x)
• Mermaid — текстовое описание графа в формате .mmd для встраивания в Markdown/Mermaid-диаграммы

Структура проекта

codegraph/
├── app.py                    # Точка входа (делегирует в backend.cli)
├── requirements.txt          # Зависимости Python
├── AGENTS.md                 # Документация для AI-ассистентов
├── backend/                  # Python-бэкенд (Flask)
│   ├── __init__.py
│   ├── cli.py                # CLI-интерфейс (argparse)
│   ├── app.py                # Flask-фабрика + API-роуты
│   ├── config.py             # Конфигурация и константы
│   ├── cache.py              # Потокобезопасный кэш графа (TTL)
│   ├── sse.py                # SSE-бродкастер
│   └── file_watcher.py       # Фоновый watcher изменений ФС (mtime, 3 сек)
├── scanner/                  # Сканирование и построение графа
│   ├── __init__.py
│   ├── file_scanner.py       # Сканирование FS, сбор FileNode
│   ├── graph_builder.py      # Построение графа (nodes + edges)
│   ├── code_analyzer.py      # Анализ структуры файла (функции, классы)
│   └── parsers/
│       ├── __init__.py       # Реестр парсеров (BaseParser, register)
│       ├── python_parser.py  # Парсер Python-импортов (AST)
│       └── js_parser.py      # Парсер JS/TS-импортов (regex)
├── frontend/                 # Фронтенд (Vanilla JS + D3.js)
│   ├── index.html            # HTML-скелет SPA
│   ├── css/
│   │   └── main.css          # Все стили
│   └── js/
│       ├── state.js          # Константы и глобальное состояние
│       ├── utils.js          # Вспомогательные функции
│       ├── graph.js          # D3.js force-graph (render, rebuild, drag)
│       ├── focus.js          # Режим фокуса / подсветка зависимостей
│       ├── tooltip.js        # Тултип при наведении
│       ├── minimap.js        # Minimap-виджет
│       ├── dir-drill.js      # Раскрытие/сворачивание директорий
│       ├── file-drill.js     # Drill-down структуры файла
│       ├── sidebar.js        # Боковая панель (код, метаданные)
│       ├── controls.js       # Тулбар, хоткеи, поиск, экспорт
│       ├── help-modal.js     # Модальное окно справки
│       └── app.js            # Инициализация, SSE, бутстрап
└── tests/
    ├── __init__.py
    ├── test_scanner.py
    ├── test_graph_builder.py
    └── test_parsers.py

Архитектура

CLI (путь) → Scanner (os.walk + AST) → Graph Builder → JSON API → D3.js Force Graph
                              ↕                           ↕
                     File Watcher (mtime)          SSE /api/events

Граф строится на сервере, отдаётся как JSON через /api/graph. Фронтенд использует D3.js force-simulation для расположения узлов. При изменениях файлов на диске FileWatcher инвалидирует кэш и шлёт SSE-уведомление, фронтенд автоматически перезагружает граф.

Технологии

• Backend: Python 3, Flask
• Frontend: D3.js v7, Prism.js, Vanilla JS
• Парсинг: Python AST, Regex (JS/TS)

Лицензия

MIT