Code Atlas

Локальный генератор интерактивной карты программного проекта. Он сканирует исходники без исполнения кода, определяет сервисы, языки, технологии и базы данных, строит связи импортов и позволяет проваливаться от сервиса к модулю, классу и методам.

Что уже работает

• интерактивная 2D-карта с Figma-навигацией: обычный drag перемещает узел или выделенную группу, рамка и Shift собирают множественное выделение, Space + drag и колесо панорамируют холст, а Ctrl/Cmd + колесо меняет масштаб;
• сворачиваемая левая панель с запоминанием состояния: карта и конструктор могут занимать всю ширину окна;
• две 2D-раскладки: контейнеры по границам сервисов и архитектурные колонки Project → Services → Endpoints → Handlers → Domain → Data;
• полноценная 3D-карта с orbit-навигацией, глубиной, перемещением узлов, фокусировкой камеры и общим инспектором;
• импорт проекта по абсолютному локальному пути;
• desktop-режим Tauri 2 для macOS, Windows x64 и Linux с системным выбором папки проекта;
• автономный production-sidecar: Tauri запускает упакованный Node.js-анализатор, отдельный worker и SQLite без установленного у пользователя Node.js;
• фоновая очередь анализа: API сразу возвращает идентификатор задания, а интерфейс показывает фазу, процент и число обработанных файлов;
• управляемый пул до двух изолированных worker_thread: тяжёлый AST-разбор не блокирует HTTP API;
• отмена ожидающего или активного анализа и высокий приоритет, который перемещает задание перед обычными заданиями без прерывания уже запущенной работы;
• сохранение до 50 последних снимков в локальную SQLite-базу и повторное открытие карты без сканирования проекта;
• инкрементальный SHA-256-кэш AST: неизменённые файлы не парсятся повторно, а доля переиспользования показывается в боковой панели;
• поиск, компактный всплывающий фильтр слоёв карты и меню архитектурной диагностики с фильтрацией по важности;
• открытие проекта, исходного файла, класса, функции или метода прямо из карты в VS Code, Cursor, системном приложении либо Notepad/TextEdit с переходом на нужную строку;
• Architecture Blueprint: визуальный конструктор целевой архитектуры с палитрой систем, сервисов, frontend, gateway, контроллеров, модулей, компонентов, классов, абстрактных классов, интерфейсов, баз, кэшей, очередей и внешних систем;
• локальная библиотека именованных Blueprint: создание, повторное открытие, переименование, копирование и удаление нескольких схем одного проекта;
• Runtime Preview для Blueprint: старт с выбранного компонента, JSON-вход, пошаговая подсветка пути и базовые действия pass, transform, validate, delay, fail и respond без исполнения кода анализируемого проекта;
• настройка шаблона каждого компонента и безопасный scaffold TypeScript, Python, Java или Kotlin в отдельную папку проекта; генератор создаёт только новые файлы и никогда не перезаписывает существующие;
• drag-and-drop узлов, ручные архитектурные и OOP-связи с созданием и переподключением стрелок, инспектор свойств, статусы, владелец, undo/redo и сохранение blueprint отдельно от исходного проекта;
• библиотека из 36 готовых пресетов: 12 архитектурных шаблонов, все 23 классических GoF-паттерна (порождающие, структурные и поведенческие) и Repository;
• дополнительные архитектурные пресеты: Layered и Clean Architecture, Backend for Frontend, Serverless, Saga Orchestration, Plugin Architecture, Streaming Data Pipeline и Multi-tenant SaaS;
• загрузка пресета вместо карты или добавление шаблона в существующую архитектуру с мини-превью до применения;
• визуальное сравнение «план ↔ факт»: импорт найденной архитектуры, включаемый переключателем «Фоновый факт» ghost-overlay и счётчики совпавших, ещё не реализованных и не описанных в плане компонентов; при открытии конструктора фактический проект скрыт, чтобы не мешать проектированию;
• умные подсказки сопоставления плановых узлов с фактическими модулями и явное подтверждение связи пользователем;
• blast radius выбранного компонента: прямые зависимости, потребители и транзитивно затронутые узлы с оценкой уровня влияния;
• Request Trace: отправка HTTP-запроса на локальный сервис, показ фактического ответа, сопоставление endpoint с route и подсветка вероятного пути/точки отказа на 2D- и 3D-карте;
• анимированный Request Trace: движущиеся маркеры вызова, подсветка затронутых зон и пульсирующая точка вероятного падения с поддержкой prefers-reduced-motion;
• Runtime Trace Debugger: локальный OTLP/HTTP JSON collector, поиск и фильтры по сессиям, проигрывание со скоростью 0.5–4×, пошаговая навигация, breakpoints, масштабируемый timeline, фактический exception/stack trace и синхронная подсветка измеренного пути на 2D- и 3D-карте;
• сервисы по manifest-файлам (package.json, pyproject.toml, go.mod, Cargo.toml, Maven/Gradle и другие);
• языковая статистика для TypeScript/JavaScript, Python, Java/Kotlin, Go, Rust, C#, PHP, Ruby, Swift, Dart и web-файлов;
• глубокий разбор классов, интерфейсов, функций, методов, контроллеров и HTTP-маршрутов для TypeScript/JavaScript и Python;
• Tree-sitter WASM AST-разбор типов, функций и методов для Java, Kotlin (.kt/.kts), Go, Rust, C# и PHP;
• разрешение локальных импортов для TypeScript/JavaScript, Python, Java/Kotlin, Go modules, Rust crate/self/super, C# namespaces и PHP namespaces;
• консервативный граф вызовов/создания объектов для TypeScript/JavaScript, Java, Kotlin, Go, Rust, C# и PHP;
• статическое разрешение целей через imports, namespaces, Go packages, Rust use, типы переменных и уникальные символы того же package без запуска language server или build-системы проекта;
• архитектурная диагностика циклов импортов, высокой связанности, межсервисных зависимостей, изолированных модулей и общей базы нескольких сервисов;
• Git-история модулей: число изменений, churn строк, авторы и дата последнего изменения;
• hotspots часто меняющихся файлов и сравнение текущей карты с веткой, тегом или commit hash;
• подсветка добавленных и изменённых узлов после Git-сравнения в 2D и 3D;
• структурный архитектурный diff: добавленные, изменённые и удалённые сервисы, модули, символы и связи;
• ghost-узлы и пунктирные связи для элементов, существовавших только в базовом Git-снимке;
• подробный diff структуры выбранного узла: добавленные/удалённые методы, свойства и HTTP-маршруты, а также изменённые сигнатуры;
• раскрываемый построчный source diff для изменённых, добавленных и удалённых методов, свойств и маршрутов, включая изменения только в теле метода;
• сигнатуры TypeScript включают типы параметров и возвращаемый тип; Python и Tree-sitter-адаптеры показывают return type, когда он доступен;
• переход из списка диагностик к затронутому узлу и показ замечаний в инспекторе;
• структурный fallback для остальных распознаваемых языков;
• проваливание в подграф сервиса или модуля с breadcrumbs и сохранением внешних зависимостей;
• обнаружение PostgreSQL, MySQL/MariaDB, MongoDB, Redis, SQLite, Elasticsearch и DynamoDB;
• безопасные ограничения: локальный bind, CORS/HTTP-заголовки, rate limit, игнорирование зависимостей/сборок, симлинков и больших файлов, лимит на размер снимка и фрагменты исходника до 200 строк/12 000 символов.

Request Trace

Откройте «Запрос» над картой, выберите HTTP-метод и укажите URL запущенного локального сервиса, например http://127.0.0.1:3000/products. Code Atlas покажет статус и ограниченный preview ответа, сопоставит URL с найденным route и подсветит вероятную цепочку до контроллеров, вызываемых классов, репозиториев и инфраструктуры.

В 2D переключатель «Сервисы / Слои» меняет представление той же карты: первое группирует код в границы приложений, второе раскладывает узлы по архитектурной ответственности. Во время Request Trace активные зоны подсвечиваются, по связям движутся маркеры запроса, а карта автоматически фокусирует весь путь и резервирует место под правую панель.

Это гибрид фактического HTTP-ответа и статического анализа: пока приложение не присылает OpenTelemetry spans, точка падения остаётся вероятной. Из соображений безопасности разрешены только localhost, 127.0.0.1 и ::1; redirects, URL credentials и транспортные заголовки запрещены, тело и preview ответа ограничены, запросы не сохраняются.

Runtime Trace

Кнопка «Трейсы» открывает локальный OTLP collector и отладчик сессий. Список поддерживает поиск и фильтрацию по статусу, а после выбора trace компактно сворачивается, освобождая место для инспектора. Воспроизведение можно поставить на паузу, пройти по span пошагово, ускорить от 0.5× до 4× или остановить breakpoint-ом на нужном span. Scrubber и timeline с масштабом 1×/2×/4× синхронно показывают достигнутый путь на карте. Ошибка вынесена в отдельный блок с сервисом, span, исходным файлом/строкой и раскрываемым stack trace.

Панель также показывает endpoint и отдельный одноразовый заголовок x-code-atlas-otlp-token, который можно скопировать в JSON-совместимый OpenTelemetry exporter или локальный collector/agent. projectPath уже включён в endpoint и связывает spans с открытой картой. При поступлении данных Code Atlas сохраняет trace-сессии в SQLite и сопоставляет service.name, http.route, db.system и semantic conventions code.* с узлами статического графа.

Сейчас принимается OTLP/HTTP JSON до 1 МБ и 500 spans за пакет; protobuf и gRPC будут добавлены следующим транспортным адаптером. Секретные атрибуты (authorization, cookies, passwords, tokens и API keys) заменяются на [REDACTED], строки и stack trace ограничены. Для быстрой проверки кнопка «Демо-трасса с ошибкой» создаёт локальную сессию без запуска анализируемого проекта.

Конструктор архитектуры

Переключитесь из «Карта» в «Конструктор». Компонент можно перетащить из левой палитры или добавить кликом, затем соединить выходную точку одного узла со входной точкой другого и настроить тип связи в правом инспекторе. Кроме HTTP/gRPC/event/read/write/dependency доступны OOP-связи implements, extends, creates и calls. Cmd/Ctrl+Z отменяет изменение, Shift+Cmd/Ctrl+Z повторяет его, Delete удаляет выбранный элемент.

Кнопка «Пресеты» открывает каталог готовых архитектур и паттернов проектирования с поиском, категориями и мини-картой. Шаблон можно загрузить как новый blueprint либо добавить к уже собранной карте; применение остаётся частью истории undo/redo.

Кнопка с названием текущей схемы открывает локальную библиотеку Blueprint. Там можно создать новую схему, открыть ранее сохранённую, переименовать, скопировать или удалить её. Кнопка «Запустить» открывает Runtime Preview: выберите стартовый узел и JSON-запрос, затем просмотрите подсвеченный путь, результат каждого шага и вероятное место ошибки. Логика настраивается у узла справа и является безопасной декларативной симуляцией — код проекта не исполняется.

В секции «Шаблонный код» инспектора задаются язык, вид шаблона и необязательное имя файла. Кнопка «Код» создаёт scaffold в выбранной относительной папке внутри проекта. Запись происходит только после явного подтверждения; выход за корень проекта, симлинки и имена с путём отклоняются, существующие файлы пропускаются. Это стартовые заготовки, а не двусторонняя синхронизация с исходниками.

Кнопка «Импортировать факт» превращает текущий результат статического анализа в редактируемый blueprint. После этого можно добавить целевые сервисы или удалить устаревающие части. Индикаторы drift показывают: зелёным — элемент связан с текущим кодом, синим — существует только в плане, красным пунктиром — найден в коде, но отсутствует в плане. Для планового элемента инспектор предлагает наиболее вероятные фактические соответствия, но создаёт связь только после подтверждения. Там же рассчитывается радиус влияния и доступны переходы к затронутым узлам. Переключатель «Факт» скрывает или показывает overlay. Все Blueprint хранятся в локальной SQLite; в анализируемый репозиторий попадает только scaffold, который пользователь явно запросил через генератор.

Запуск

Требуется Node.js 22.5+ — хранилище использует встроенный модуль node:sqlite.

npm install
npm run dev

Откройте http://localhost:5173. При первом запуске появится демонстрационная карта. В верхней строке укажите абсолютный путь к любому локальному проекту и нажмите «Построить карту».

Для запуска собранной версии одним локальным сервером:

npm run serve

После сборки откройте http://127.0.0.1:4310.

Desktop-режим

Для оболочки Tauri 2 дополнительно нужны Rust и системные зависимости платформы. На macOS достаточно установленного Xcode Command Line Tools. После npm install запустите:

npm run desktop:dev

Откроется отдельное desktop-окно. В нём рядом с полем пути доступна кнопка «Папка», которая вызывает системный выбор каталога. Оболочка имеет только разрешение на открытие этого диалога: доступ к shell и filesystem-плагину ей не выдан.

Для автономной сборки под текущую платформу:

npm run desktop:build

Команда собирает web-интерфейс, два backend-бандла, WASM-грамматики и копию Node runtime с суффиксом Rust target triple, после чего создаёт системные пакеты Tauri. На macOS результат находится в src-tauri/target/release/bundle/macos/Code Atlas.app и src-tauri/target/release/bundle/dmg/. Пользователю готового приложения Node.js и Rust не нужны.

На Windows x64 сборку нужно выполнять нативно из PowerShell на Windows 10/11 с Node.js, Rust MSVC toolchain и Visual Studio Build Tools (Desktop development with C++):

npm ci
npm run test:windows-contract
npm run desktop:build -- --bundles msi,nsis
npm run verify:windows-bundle

Готовые установщики появятся в src-tauri\target\release\bundle\msi\ и src-tauri\target\release\bundle\nsis\. Установленному приложению Node.js и Rust не нужны: Node runtime, анализатор, worker и WASM-грамматики находятся внутри пакета. NSIS устанавливается для текущего пользователя без обязательных прав администратора; при отсутствии Microsoft Edge WebView2 установщик тихо запускает официальный bootstrapper.

Sidecar слушает случайный порт только на 127.0.0.1. Tauri передаёт ему одноразовый 256-битный токен через окружение и хранит токен только в памяти окна; API отклоняет запросы без него. Shell-команды не открыты frontend-коду, sidecar автоматически завершается вместе с приложением, а SQLite лежит в системном app-data каталоге. dist-sidecar/build-manifest.json содержит SHA-256 и размер каждого runtime-ресурса. Сборка выполняется нативно для текущей платформы и намеренно отклоняет попытку вложить host Node runtime в чужой target triple.

Локальный macOS-бандл без настроенного Developer ID подходит для разработки. Для внешнего распространения необходимо выполнить signing и notarization в release-пайплайне.

Нативная CI-матрица собирает DMG для macOS arm64/x64, AppImage/DEB для Linux x64 и MSI/NSIS для Windows x64. Проверочные артефакты остаются неподписанными; ручной release workflow требует Apple Developer ID, выполняет notarization и создаёт только черновик GitHub Release. Настройка секретов, Windows signing и безопасное подключение updater описаны в docs/releasing.md.

Проверка

npm run typecheck
npm test
npm run build
npm run build:sidecar
npm run test:sidecar
npm run test:windows-contract

Архитектура

Browser / Tauri WebView / React Flow
        │  POST job · poll progress · open snapshot
        ▼
token-protected Fastify loopback API ──► priority queue ──► worker pool (max 2)
        │  └─ safe request probe │                 │
        │                         ▲                 │
        │                         └── progress ─────┤
        └── SQLite snapshots + AST cache + blueprints ◄── IPC ──┤
                                                  ▼
                                           static analyzer
                                                  │
                                      normalized graph ──┬─► 2D renderer
                                                  │      └─► lazy 3D renderer
                                                  ├─ manifests
                                                  ├─ source parsers
                                                  └─ infra detectors

Сервер слушает только 127.0.0.1, не запускает код анализируемого проекта и не переходит по симлинкам. Семантические связи строятся статически: внешние language servers намеренно не запускаются автоматически, поскольку некоторые из них способны активировать build-плагины и proc macros проекта. Kotlin-грамматика закреплена точной версией, а её SHA-256 проверяется перед первой загрузкой. Каждый фоновый worker ограничен 512 МБ old-generation heap и десятью минутами; при отмене задания или остановке сервера поток принудительно завершается. SQLite остаётся только в основном процессе; worker обращается к AST-кэшу через валидируемый IPC-протокол, который не принимает абсолютные пути и выходы за корень проекта. По умолчанию снимки и кэш лежат в .code-atlas/code-atlas.sqlite; путь можно переопределить переменной CODE_ATLAS_DATABASE. Кэш ограничен 15 000 результатами парсинга, валидируется при чтении и автоматически инвалидируется при смене версии парсера.

Фоновый API:

• POST /api/analysis-jobs — поставить анализ в очередь; необязательный priority принимает только normal или high;
• GET /api/analysis-jobs/:id — получить состояние задания;
• DELETE /api/analysis-jobs/:id — отменить ожидающее или активное задание;
• GET /api/snapshots — список сохранённых снимков;
• GET /api/snapshots/:id — открыть готовую карту.
• POST /api/request-probes — выполнить ограниченный HTTP-запрос только к loopback и вернуть фактический результат для Request Trace.
• GET /api/blueprints/documents?projectPath=... и GET /api/blueprints/documents/:id — список и открытие именованных Blueprint;
• POST/PATCH/DELETE /api/blueprints/documents... — сохранить, переименовать, скопировать или удалить Blueprint (до 200 узлов, 400 связей и 256 КБ);
• POST /api/blueprints/generate — безопасно создать выбранные scaffold-файлы внутри проекта без перезаписи;
• GET /api/runtime-traces/collector?projectPath=... — получить локальный endpoint и отдельный OTLP-токен;
• POST /v1/traces?projectPath=... — принять аутентифицированный OTLP/HTTP JSON пакет;
• GET /api/runtime-traces?projectPath=... и GET /api/runtime-traces/:id — история и детали runtime-трассировок.

Следующий этап

1. Добавить OTLP/HTTP protobuf и gRPC transport, чтобы подключать стандартные SDK без JSON-адаптера.
2. Подключить Windows Authenticode и Tauri updater после создания GitHub remote и выпуска ключей подписи.
3. Опциональный sandboxed LSP-режим с явным согласием пользователя для более точного разрешения динамических вызовов.
4. Swift Tree-sitter WASM-адаптер.