GitGalaxy

Структурная аналитика репозитория в масштабе без компиляции.

Docs · Visualizer · Language Crucible · Raw Output

1 скан · 97 структурных сигналов · 50+ языков · без компиляции · 19 категорий риска · 6 выходных форматов

Коротко

GitGalaxy строит не зависящий от языка структурный граф всего репозитория непосредственно из исходного текста.

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

Вместо того чтобы требовать успешной сборки и отдельного парсера/инструментария для каждого языка, GitGalaxy извлекает общий словарь структурных сигнатур — функций, классов, аргументов, потоков управления, изменения состояния, ввода-вывода, API, зависимостей и других сигналов — и нормализует эти наблюдения в единую модель репозитория.

Тот же граф затем может питать:

анализ архитектуры
приоритизацию рисков
анализ зависимостей/SBOM
анализ рефакторинга и владения кодом
анализ устаревшего кода
контекст кодовой базы для ИИ
рабочие процессы CI/CD
исторический анализ рисков

Центральный тезис: полный разбор языка не всегда необходим для восстановления крайне полезной структурной информации в масштабе репозитория.

Проблема

Крупные репозитории регулярно содержат:``` text Go + C++ + Python + Java + Bash + YAML

generated code + vendored code + legacy code
half-migrated modules + broken dependencies

Традиционные языковые инструменты могут быть отличными в рамках своей целевой области,
но при этом оставляют репозиторий фрагментированным между представлениями, зависящими от конкретного языка.

GitGalaxy делает иной выбор:``` text
Source repository
       |
       v
Structural signatures
       |
       v
Normalized entities + risk signals
       |
       v
Deterministic repository graph
       |
       +---- Architecture
       +---- Risk exposure
       +---- Dependencies / SBOM
       +---- AI context
       +---- Refactoring
       +---- Git-history analysis

Цель — не воспроизвести каждую синтаксическую деталь каждого языка.

Цель — восстановить структурную информацию, которая на самом деле нужна нижестоящей аналитике репозиториев.

Один граф, множество потребителей

Ядро вывода GitGalaxy — детерминированное структурное представление репозитория.

Потребитель Вопрос

Архитектура Из чего состоит этот репозиторий?

Структурный анализ Где находятся функции, классы, API, зависимости и управляющие структуры?

Экспозиция рисков Где сосредоточены потенциально важные паттерны рисков?

Рефакторинг Какие файлы сложны, часто изменяемы или несут основную нагрузку?

Цепочка поставок Какие зависимости физически существуют на диске?

ИИ-контекст Какую архитектуру и связи должен знать агент?

Миграция легаси-кода Где находятся структурные единицы, подлежащие преобразованию?

Исторический анализ Как меняется измеренная экспозиция по мере эволюции репозитория?

Конвейер архитектуры GitGalaxy

Тезис о структурном извлечении

GitGalaxy намеренно не начинает с построения полного AST для каждого языка.

Он использует примерно 97 категорий структурных сигналов для выявления таких вещей, как:

границы функций и методов
классы и объявления
аргументы
ветвления и поток управления
мутация состояния
ввод/вывод
API и маршруты
импорты и зависимости
небезопасные операции
рефлексия и динамическое выполнение
конкурентность
замыкания
глобальные переменные
энтропия и аномалии физических файлов

Это создаёт конкретную, проверяемую гипотезу:

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

Эта гипотеза проверяется эмпирически.

Структурная валидация: GitGalaxy против Tree-sitter и Ctags

В настоящее время это одна из важнейших программ валидации в проекте.

GitGalaxy оценивается против Tree-sitter и Universal Ctags на том же корпусе Language Crucible.

Первые структурные цели:

функции
классы
аргументы

Бенчмарк намеренно не рассматривается как соревнование популярности трёх инструментов.

Когда инструменты расходятся:

расхождение фиксируется;
исходный код проверяется;
поведение каждого инструмента исследуется;
GitGalaxy исправляется, когда GitGalaxy не прав;
код компаратора/адаптера исправляется, когда компаратор не прав;
реальные ограничения инструментов документируются;
результат измеряется заново.

24 из 45 языков получают сравнение всех трёх инструментов, ещё 16 — двух, а 5 языков только для GitGalaxy (abap, dockerfile, jcl, livecode, yaml) получают ручную проверку вместо кросс-инструментального согласования. Из 180 зафиксированных на данный момент форм расхождений 87 валидированы (48%) — прочитаны, исследованы и записаны с вердиктом, а не просто подсчитаны.

Цель — завершить аудит, закрыть оставшиеся дефекты GitGalaxy, установить независимую эталонную истину там, где это необходимо, а затем опубликовать финальные измерения точности/полноты. См. документацию по методологии тройного сравнения о том, как работают сопоставление, жизненный цикл реестра и CI-контроль.

Тройное сравнение

См.:

tests/tools/tri_comparison_chart.py
docs/self_scan/tri_comparison_ledger.json — полная запись, валидированная по каждой форме
docs/self_scan/tri_comparison_points_of_interest.md — тот же реестр, отображённый и ранжированный по силе сигнала
docs/self_scan/how_to_investigate_a_discrepancy.md
docs/self_scan/manual_verification.json

Что на самом деле спрашивает бенчмарк

Не:

«Является ли GitGalaxy лучшим парсером, чем Tree-sitter?»

А:

«Для структурных сущностей, которые GitGalaxy должен построить для своего графа репозитория, насколько точно целенаправленное структурное извлечение может восстановить их по сравнению с устоявшимися системами парсинга и индексации?»

Это более узкое утверждение, которое эксперимент может поддержать.

Языки без подходящего покрытия компараторами

Некоторые языки в настоящее время не имеют подходящего независимого пути сравнения Tree-sitter/Ctags.

Они хранятся в отдельной категории доказательств и используют зафиксированную ручную проверку, а не имитируют существование кросс-инструментального согласования.

В настоящее время это включает такие языки, как:

ABAP
Dockerfile
JCL
LiveCode
YAML

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

Валидация — это лестница

Доказательства GitGalaxy организованы вокруг последовательно более сильных вопросов.

1. Структурная валидность

Корректно ли GitGalaxy идентифицирует структуры кода?

Tree-sitter + Ctags + независимо исследованные расхождения. См. «Структурная валидация» выше.

2. Регрессионная валидность

Остаётся ли реализация стабильной на реальном коде?

Тестирование golden-master против Language Crucible.

3. Валидность масштаба

Работает ли это на реальных репозиториях?

Неотредактированный сырой вывод сканирования из сотен репозиториев.

4. Валидность модели

Соответствуют ли структурные сигнатуры категориям экспозиции, которые они должны представлять?

Статистический анализ против независимо наблюдаемых результатов — а не только против собственных уравнений GitGalaxy.

5. Временная валидность

Ведёт ли себя экспозиция разумно по мере изменения программного обеспечения?

Анализ истории Git, сравнивающий состояния репозитория до и после реальных изменений.

6. Внешняя валидность

Соответствуют ли изменения экспозиции независимо задокументированным результатам безопасности или обслуживания?

Будущая работа: исправления безопасности, регрессии, бюллетени, дефекты и другие наборы данных внешних событий.

Это различие важно: оценка может быть внутренне согласованной, не будучи при этом обязательно внешне значимой.

Экспозиция рисков: что заявляет GitGalaxy

GitGalaxy производит измерения экспозиции рисков, а не вердикты об уязвимостях.

Высокая экспозиция означает:

Это место заслуживает внимания относительно остальной части репозитория.

Это не означает:

«Этот код определённо уязвим».

Текущая система производит нормализованные категории экспозиции по всему репозиторию и свёртывает информацию от структурных сущностей через файлы, папки и представления уровня репозитория.

Базовые сигнатуры охватывают паттерны, связанные с такими областями, как:

секреты
поверхность инъекций
небезопасные/памятные операции
динамическое выполнение
ввод/вывод
конкурентность
мутация состояния
рефлексия
API
зависимости
энтропия
другие структурные/защитные характеристики

Важный исследовательский вопрос — связаны ли эти сигнатуры эмпирически со значимыми классами программных рисков, а не просто коррелируют с оценкой, которую GitGalaxy сам математически сконструировал.

Это различие определяет следующий этап.

Следующая валидация: риск по истории Git

Центральный эксперимент таков:

> **Снижают ли коммиты, независимо идентифицированные как исправления
> безопасности, как правило, соответствующую экспозицию GitGalaxy?**

Негативные контроли не менее важны:

> Демонстрируют ли обычные коммиты разработки то же поведение?

В конечном счёте:

> Увеличивают ли регрессии безопасности экспозицию?

Запланированный испытательный стенд будет сохранять SHA коммита, состояние родителя, изменённые
файлы/функции, экспозицию до/после, дельты экспозиции, структурные
изменения и классификацию событий.

Это проверяет:

**структура → экспозиция → реальная эволюция ПО**

а не просто проверяет внутреннюю математику модели экспозиции.

------------------------------------------------------------------------

# Доказательства, а не просто утверждения

### Языковой тигель

Фиксированный корпус реального исходного кода, включающий такие проекты, как Godot,
Roslyn, curl, Kubernetes и полётное ПО Apollo 11.

[Language Crucible](https://github.com/squid-protocol/language-crucible)

### Регрессия по золотому эталону

Реальный исходный код повторно сканируется и сравнивается с проверенным ожидаемым выводом,
чтобы изменения парсера имели наблюдаемый diff. Регенерируется с помощью
[`tests/tools/update_golden_master.py`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/tests/tools/update_golden_master.py),
никогда не редактируется вручную.

### Тройное сравнение

Тот же корпус анализируется с помощью GitGalaxy, Tree-sitter и Ctags
там, где существует покрытие — 24 из 45 языков получают все три инструмента, 87 из
180 задокументированных расхождений проверены на данный момент. См.
[методологию](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/self_scan/tri_comparison_README.md) и
[раздел «Структурная валидация» выше](#structural-validation-gitgalaxy-vs-tree-sitter-vs-ctags)
для полной картины.

### Необработанный вывод репозиториев

Неотредактированный вывод GitGalaxy сохраняется для сотен независимо
выбранных репозиториев.

[Raw Output](https://github.com/squid-protocol/gitgalaxy-raw-output)

### Набор регрессионных тестов

**7 043 теста** в наборе по умолчанию (`python -m pytest tests/`), из
которых **6 165** — это тесты по каждой сигнатуре во всех 45 языках со структурными
сигнатурами — положительные совпадения, явные исключения и состязательные/ReDoS
входные данные. См. [`tests/README.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/tests/README.md) для разбивки и
[`docs/why_gitgalaxy_beats_ast_here.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/why_gitgalaxy_beats_ast_here.md)
для конкретных, подтверждённых случаев, где эта экстракция превосходит чтение AST.

### Историческая валидация

Следующий исследовательский слой проверит, соответствуют ли измерения экспозиции
реальным событиям безопасности и сопровождения в истории Git.

------------------------------------------------------------------------

# Что такое GitGalaxy — и чем он не является

### GitGalaxy — это

-   структурный интеллект масштаба репозитория
-   языко-независимый анализ исходного кода
-   общее структурное представление для разнородного кода
-   приоритизация риска экспозиции
-   картирование архитектуры
-   генерация доказательств, нативная для CI
-   полезен для сломанных/нескомпилированных репозиториев
-   спроектирован для локальной/офлайн-работы

### GitGalaxy — это не

-   замена глубокому анализу потоков данных CodeQL
-   замена экосистеме правил Semgrep
-   замена базам данных CVE для зависимостей
-   доказательство эксплуатируемости
-   анализатор времени выполнения
-   полный парсер языка
-   гарантия того, что высокая экспозиция является уязвимостью

  -----------------------------------------------------------------------
  Инструмент                           Основной вопрос
  ----------------------------------- -----------------------------------
  **GitGalaxy**                        Как выглядит весь этот репозиторий
                                       структурно, и куда следует
                                       направить внимание в первую очередь?

  Tree-sitter                          Какую синтаксическую структуру
                                       содержит этот исходный код?

  Ctags                                Где находятся навигируемые сущности
                                       кода?

  Semgrep                              Соответствует ли этот код заданному
                                       шаблону?

  CodeQL                               Какие отношения данных/управления
                                       может установить более глубокий
                                       анализ?

  SCA/CVE-инструменты                  Связана ли эта зависимость/версия
                                       с известным бюллетенем безопасности?
  -----------------------------------------------------------------------

------------------------------------------------------------------------

# Масштаб реального мира

GitGalaxy предназначен для репозиториев, слишком разнородных или сломанных для
традиционного однозязычного рабочего процесса «сначала сборка».

Пример: **Kubernetes**

\~1,39 млн строк на Go, YAML, JSON, Shell и Proto.

Сквозное сканирование: **50,83 секунды**.

![GitGalaxy scan
speed](https://assets.kitploit.com/production/public/readmes/7003/596585161af8eeb861f49e2968927d69059333f145c0e2b6e9bb0cb9c9d7bc36.png)

См. [репозиторий с необработанным
выводом](https://github.com/squid-protocol/gitgalaxy-raw-output) для
неотредактированных артефактов.

------------------------------------------------------------------------

# Выходные данные

  Выходные данные                   Назначение
  ---------------------------- ----------------------------------------
  **SARIF**                    Интеграция с CI/панелями безопасности
  **CycloneDX SBOM**           Инвентаризация зависимостей/соответствие
  **SQLite**                   Запрашиваемый граф знаний репозитория
  **Краткий обзор архитектуры для LLM**   Компактный контекст для машин/агентов
  **JSON-данные аудита**       Криминалистические/автоматизированные рабочие процессы
  **Данные 3D-визуализации**   Интерактивная топология репозитория

Это разные представления одного и того же детерминированного сканирования, а не
независимые механизмы анализа.

------------------------------------------------------------------------

# История Git и архитектура

GitGalaxy уже включает историю Git в такие сигналы, как:

-   изменчивость (churn)
-   концентрация контрибьюторов
-   экспозиция фактора шины (bus-factor)
-   горячие точки рефакторинга
-   владение файлами
-   временная активность

Направление исследований — расширить это от **истории как контекстуального
сигнала** до **истории как внешнего источника валидации для модели
экспозиции**.

------------------------------------------------------------------------

# Конфиденциальность и развёртывание

GitGalaxy спроектирован для локальной работы и работы в изолированной (air-gapped) среде.

-   Исходный код не отправляется в облачный сервис GitGalaxy.
-   Сканирование и векторизация выполняются локально.
-   Сканер не требует сетевого доступа во время выполнения.
-   Выполнение в CI/CD может оставаться внутри среды пользователя.
-   Визуализатор в браузере работает с локально предоставленными данными.

------------------------------------------------------------------------

# Установка``` bash
pip install gitgalaxy

См. документацию для актуальных команд и конфигурации.

CI/CD

Предоставлены шаблоны для:

GitHub Actions
GitLab CI
Bitbucket Pipelines
Azure Pipelines
универсальных CI-сред, вызываемых через shell

См. templates/ и руководство по интеграции с CI.

Изучите доказательства

Ресурс Что он содержит

Документация Архитектура, утверждения и методология

Language Crucible Кросс-языковой бенчмарк и золотой корпус

Необработанные результаты Неотредактированные сканы реальных репозиториев

tests/README.md Методология регрессионного тестирования и golden-master

tri_comparison_ledger.json Запись валидации по каждому расхождению

manual_verification.json Проверенные случаи, где покрытие компаратором недоступно

how_to_investigate_a_discrepancy.md Методология работы с расхождениями компараторов

Visualizer Локальная браузерная визуализация репозиториев

Текущее направление исследований

GitGalaxy продвигается через последовательность всё более сложных вопросов:

Можем ли мы сканировать разнородный исходный код без его компиляции?

↓

Можем ли мы надёжно восстанавливать структурные сущности, необходимые для его понимания?

↓

Соответствуют ли эти структурные измерения реальной подверженности рискам?

↓

Ведёт ли себя измеренная подверженность корректно по мере развития реального программного обеспечения?

Валидация Tree-sitter/Ctags сейчас завершена примерно наполовину. Непосредственный приоритет — завершить эту проверку, прежде чем превращать предварительные измерения в более сильные утверждения.

Следующий крупный эксперимент:

История Git → независимо идентифицированные события изменений/исправлений → сканы GitGalaxy до/после → дельты подверженности → статистический анализ.

Именно здесь GitGalaxy сможет начать проверять не только то, видит ли он структуру, но и отслеживает ли его структурная модель значимые изменения в реальном программном обеспечении.

Лицензия

GitGalaxy распространяется под PolyForm Noncommercial License 1.0.0.

Полные условия см. в лицензии репозитория.

gitgalaxy — Updated!

Категории