GitGalaxy

Inteligência estrutural em escala de repositório, sem compilação.

Docs · Visualizer · Language Crucible · Raw Output

1 varredura · 97 sinais estruturais · 50+ linguagens · sem compilação · 19 categorias de exposição a risco · 6 saídas

A versão resumida

O GitGalaxy constrói um grafo estrutural agnóstico de linguagem de um repositório inteiro diretamente do texto-fonte.

Ele foi projetado para repositórios que são poliglotas, parcialmente quebrados, legados, com muitos fornecedores ou, de outra forma, difíceis de analisar por meio de um fluxo de trabalho baseado em build.

Em vez de exigir um build bem-sucedido e um parser/toolchain separado para cada linguagem, o GitGalaxy extrai um vocabulário comum de assinaturas estruturais---funções, classes, argumentos, fluxo de controle, mutação de estado, I/O, APIs, dependências e outros sinais---e normaliza essas observações em um único modelo de repositório.

O mesmo grafo pode então alimentar:

análise de arquitetura
priorização de exposição a risco
análise de dependências/SBOM
análise de refatoração e propriedade
análise de código legado
contexto de base de código orientado a IA
fluxos de trabalho de CI/CD
análise histórica de risco

Tese central: o parsing completo de linguagem nem sempre é necessário para recuperar informações estruturais altamente úteis em escala de repositório.

O problema

Repositórios grandes rotineiramente contêm:``` text Go + C++ + Python + Java + Bash + YAML

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

Ferramentas de linguagem tradicionais podem ser excelentes dentro do seu escopo pretendido,
ao mesmo tempo em que deixam o repositório fragmentado entre representações específicas de cada linguagem.

O GitGalaxy faz uma troca diferente:``` 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

O objetivo não é reproduzir cada detalhe sintático de cada linguagem.

O objetivo é recuperar a informação estrutural de que a inteligência de repositórios a jusante realmente precisa.

Um grafo, muitos consumidores

A saída central do GitGalaxy é uma representação estrutural determinística do repositório.

Consumidor Pergunta

Arquitetura Do que é feito este repositório?

Análise estrutural Onde estão as funções, classes, APIs, dependências e estruturas de controlo?

Exposição ao risco Onde estão concentrados os padrões de risco potencialmente importantes?

Refatoração Quais ficheiros são complexos, com elevada rotatividade ou estruturais?

Cadeia de fornecimento Que dependências existem fisicamente em disco?

Contexto de IA Que arquitetura e relações deve um agente conhecer?

Migração de legado Onde estão as unidades estruturais a transformar?

Análise histórica Como é que a exposição medida muda à medida que o repositório evolui?

Pipeline de arquitetura do GitGalaxy

A tese da extração estrutural

O GitGalaxy deliberadamente não começa por construir uma AST completa para cada linguagem.

Utiliza aproximadamente 97 categorias de sinais estruturais para identificar coisas como:

limites de funções e métodos
classes e declarações
argumentos
ramificações e fluxo de controlo
mutação de estado
I/O
APIs e rotas
importações e dependências
operações inseguras
reflexão e execução dinâmica
concorrência
closures
globais
entropia e anomalias físicas de ficheiros

Isto cria uma hipótese específica e testável:

Para inteligência à escala de repositório, a extração estrutural direcionada pode recuperar as entidades necessárias para inteligência de código útil sem exigir um parser de linguagem completo para cada ficheiro.

Essa hipótese está a ser testada empiricamente.

Validação estrutural: GitGalaxy vs Tree-sitter vs Ctags

Este é atualmente um dos programas de validação mais importantes do projeto.

O GitGalaxy está a ser avaliado contra Tree-sitter e Universal Ctags no mesmo corpus Language Crucible.

Os primeiros alvos estruturais são:

funções
classes
argumentos

O benchmark é deliberadamente não tratado como um concurso de popularidade entre três ferramentas.

Quando as ferramentas discordam:

o desacordo é registado;
o código-fonte é inspecionado;
o comportamento de cada ferramenta é investigado;
o GitGalaxy é corrigido quando o GitGalaxy está errado;
o código do comparador/adaptador é corrigido quando o comparador está errado;
limitações genuínas das ferramentas são documentadas;
o resultado é medido novamente.

24 de 45 linguagens têm as três ferramentas comparadas, mais 16 têm duas, e 5 linguagens apenas do GitGalaxy (abap, dockerfile, jcl, livecode, yaml) recebem verificação manual revista em vez de acordo entre ferramentas. Dos 180 formatos de discrepância registados até agora, 87 estão validados (48%) — lidos, investigados e registados com um veredito, não apenas contados.

O objetivo é terminar a auditoria, fechar os defeitos restantes do GitGalaxy, estabelecer verdade fundamental independente onde necessário e depois publicar medições finais de precisão/revocação. Consulte o documento de metodologia de tri-comparação para saber como funcionam a correspondência, o ciclo de vida do registo e a aplicação de CI.

Tri-comparação

Consulte:

tests/tools/tri_comparison_chart.py
docs/self_scan/tri_comparison_ledger.json — o registo completo e validado por formato
docs/self_scan/tri_comparison_points_of_interest.md — o mesmo registo, apresentado e classificado por intensidade de sinal
docs/self_scan/how_to_investigate_a_discrepancy.md
docs/self_scan/manual_verification.json

O que o benchmark está realmente a perguntar

Não:

"É o GitGalaxy um parser melhor do que o Tree-sitter?"

Mas:

"Para as entidades estruturais de que o GitGalaxy precisa para construir o seu grafo de repositório, com que precisão consegue a extração estrutural direcionada recuperá-las em comparação com sistemas estabelecidos de parsing e indexação?"

Essa é a afirmação mais restrita que a experiência pode suportar.

Linguagens sem cobertura de comparador adequada

Algumas linguagens não têm atualmente um caminho de comparação independente adequado com Tree-sitter/Ctags.

Essas são mantidas numa categoria probatória separada e utilizam verificação manual consolidada em vez de fingir que existe acordo entre ferramentas.

Isto inclui atualmente linguagens como:

ABAP
Dockerfile
JCL
LiveCode
YAML

Quando prático, o próximo passo é adicionar comparadores lexicais, baseados em gramática ou específicos de domínio independentes. Quando não existe nenhum comparador independente credível, a verdade fundamental verificada por humanos permanece a categoria apropriada.

A validação é uma escada

As evidências do GitGalaxy estão a ser organizadas em torno de perguntas progressivamente mais fortes.

1. Validade estrutural

Identifica o GitGalaxy corretamente as estruturas de código?

Tree-sitter + Ctags + desacordos investigados independentemente. Consulte "Validação estrutural" acima.

2. Validade de regressão

A implementação permanece estável em código real?

Testes golden-master contra Language Crucible.

3. Validade de escala

Funciona em repositórios reais?

Saída de análise bruta não editada de centenas de repositórios.

4. Validade do modelo

Correspondem as assinaturas estruturais às categorias de exposição que pretendem representar?

Análise estatística contra resultados observáveis independentes---não apenas contra as próprias equações do GitGalaxy.

5. Validade temporal

Comporta-se a exposição de forma sensata à medida que o software muda?

Análise do histórico de Git comparando estados de repositório antes e depois de alterações reais.

6. Validade externa

Correspondem as alterações de exposição a resultados de segurança ou manutenção documentados independentemente?

Trabalho futuro: correções de segurança, regressões, avisos, defeitos e outros conjuntos de dados de eventos externos.

Esta distinção é importante: uma pontuação pode ser internamente consistente sem ser necessariamente significativa externamente.

Exposição ao risco: o que o GitGalaxy afirma

O GitGalaxy produz medições de exposição ao risco, não veredictos de vulnerabilidade.

Uma exposição elevada significa:

Este local merece atenção em relação ao resto do repositório.

Não significa:

"Este código está definitivamente vulnerável."

O sistema atual produz categorias de exposição normalizadas em todo o repositório e agrega informação de entidades estruturais através de ficheiros, pastas e vistas ao nível do repositório.

As assinaturas subjacentes cobrem padrões que envolvem áreas como:

segredos
superfície de injeção
operações inseguras/de memória
execução dinâmica
I/O
concorrência
mutação de estado
reflexão
APIs
dependências
entropia
outras características estruturais/segurança

A questão de investigação importante é se estas assinaturas estão empiricamente associadas a classes significativas de risco de software, em vez de meramente correlacionadas com uma pontuação que o próprio GitGalaxy construiu matematicamente.

Essa distinção impulsiona a próxima fase.

A próxima validação: risco ao longo do histórico de Git

O experimento central é:

> **Commits identificados de forma independente como correções de segurança
> normalmente reduzem a exposição GitGalaxy correspondente?**

Controles negativos são igualmente importantes:

> Commits de desenvolvimento comuns apresentam o mesmo comportamento?

Eventualmente:

> Regressões de segurança aumentam a exposição?

O harness planejado preservará o SHA do commit, o estado do pai, os
arquivos/funções alterados, a exposição antes/depois, os deltas de exposição,
as mudanças estruturais e a classificação de eventos.

Isso testa:

**estrutura → exposição → evolução real de software**

em vez de apenas testar a matemática interna do modelo de exposição.

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

# Evidências, não apenas alegações

### Language Crucible

Um corpus fixado de código-fonte do mundo real, incluindo projetos como Godot,
Roslyn, curl, Kubernetes e o software de voo da Apollo 11.

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

### Regressão golden-master

O código-fonte real é reescaneado e comparado com a saída esperada verificada
no repositório, para que mudanças no parser tenham um diff observável.
Regenerado com
[`tests/tools/update_golden_master.py`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/tests/tools/update_golden_master.py),
nunca editado manualmente.

### Tri-comparação

O mesmo corpus é analisado com GitGalaxy, Tree-sitter e Ctags onde houver
cobertura — 24 de 45 linguagens recebem as três ferramentas, 87 de
180 discrepâncias registradas validadas até agora. Consulte
[a metodologia](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/self_scan/tri_comparison_README.md) e a
["seção de validação estrutural acima"](#structural-validation-gitgalaxy-vs-tree-sitter-vs-ctags)
para o panorama completo.

### Saída bruta do repositório

A saída não editada do GitGalaxy é retida para centenas de repositórios
selecionados de forma independente.

[Saída Bruta](https://github.com/squid-protocol/gitgalaxy-raw-output)

### Suíte de regressão

**7.043 testes** na suíte padrão (`python -m pytest tests/`), dos quais
**6.165** são testes por assinatura em todas as 45 linguagens com assinatura
estrutural — correspondências positivas, exclusões explícitas e entradas
adversariais/ReDoS. Consulte [`tests/README.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/tests/README.md) para o
detalhamento, e
[`docs/why_gitgalaxy_beats_ast_here.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/why_gitgalaxy_beats_ast_here.md)
para casos específicos e evidenciados em que esta extração supera uma leitura
via AST.

### Validação histórica

A próxima camada de pesquisa testará se as medições de exposição
correspondem a eventos reais de segurança e manutenção ao longo do histórico
do Git.

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

# O que o GitGalaxy é — e não é

### GitGalaxy é

-   inteligência estrutural em escala de repositório
-   análise de código-fonte agnóstica de linguagem
-   uma representação estrutural comum entre código heterogêneo
-   priorização de exposição a risco
-   mapeamento de arquitetura
-   geração de evidências nativa para CI
-   útil em repositórios quebrados/não compilados
-   projetado para operação local/offline

### GitGalaxy não é

-   um substituto para a análise profunda de fluxo de dados do CodeQL
-   um substituto para o ecossistema de regras do Semgrep
-   um substituto para bancos de dados de CVE de dependências
-   uma prova de explorabilidade
-   um analisador em tempo de execução
-   um parser de linguagem completo
-   uma garantia de que alta exposição é uma vulnerabilidade

  -----------------------------------------------------------------------
  Ferramenta                           Pergunta principal
  ----------------------------------- -----------------------------------
  **GitGalaxy**                        Como este repositório inteiro se
                                       parece, estruturalmente, e para onde
                                       a atenção deve ir primeiro?

  Tree-sitter                          Que estrutura sintática este
                                       código-fonte contém?

  Ctags                                Onde estão as entidades de código
                                       navegáveis?

  Semgrep                              Este código corresponde a um padrão
                                       especificado?

  CodeQL                               Que relações de dados/controle uma
                                       análise mais profunda pode
                                       estabelecer?

  Ferramentas SCA/CVE                  Esta dependência/versão está
                                       associada a um advisory conhecido?
  -----------------------------------------------------------------------

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

# Escala no mundo real

O GitGalaxy é destinado a repositórios heterogêneos ou quebrados demais para
um fluxo de trabalho tradicional de construção-primeiro com uma única
linguagem.

Exemplo: **Kubernetes**

\~1,39M de linhas em Go, YAML, JSON, Shell e Proto.

Varredura de ponta a ponta: **50,83 segundos**.

![Velocidade de varredura do
GitGalaxy](https://assets.kitploit.com/production/public/readmes/7003/596585161af8eeb861f49e2968927d69059333f145c0e2b6e9bb0cb9c9d7bc36.png)

Consulte o [repositório de saída
bruta](https://github.com/squid-protocol/gitgalaxy-raw-output) para
artefatos não editados.

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

# Saídas

  Saída                          Finalidade
  ---------------------------- ----------------------------------------
  **SARIF**                      Integração com painéis de CI/segurança
  **SBOM CycloneDX**             Inventário/conformidade de dependências
  **SQLite**                     Grafo de conhecimento do repositório
                                 consultável
  **Brief de arquitetura para LLM**  Contexto compacto orientado a
                                 máquinas/agentes
  **Dados de auditoria JSON**    Fluxos de trabalho forenses/automação
  **Dados de visualização 3D**   Topologia interativa do repositório

Estas são diferentes visões da mesma varredura determinística, e não
mecanismos de análise independentes.

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

# Histórico do Git e arquitetura

O GitGalaxy já incorpora o histórico do Git em sinais como:

-   churn
-   concentração de contribuidores
-   exposição a bus-factor
-   hotspots de refatoração
-   propriedade de arquivos
-   atividade temporal

A direção da pesquisa é estender isso de **histórico como sinal contextual**
para **histórico como fonte externa de validação do modelo de exposição**.

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

# Privacidade e implantação

O GitGalaxy é projetado para operação local e em ambientes isolados
(air-gapped).

-   O código-fonte não é enviado a um serviço em nuvem do GitGalaxy.
-   A varredura e a vetorização ocorrem localmente.
-   O scanner não tem requisito de rede em tempo de execução.
-   A execução em CI/CD pode permanecer dentro do ambiente do usuário.
-   O visualizador em navegador opera com dados fornecidos localmente.

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

# Instalação``` bash
pip install gitgalaxy

Consulte a documentação para comandos e configurações atuais.

CI/CD

Modelos são fornecidos para:

GitHub Actions
GitLab CI
Bitbucket Pipelines
Azure Pipelines
ambientes de CI genéricos invocáveis por shell

Consulte templates/ e o guia de integração com CI.

Explore as evidências

Recurso O que contém

Documentação Arquitetura, afirmações e metodologia

Language Crucible Benchmark multilíngue e corpus dourado

Saída Bruta Varreduras não editadas de repositórios reais

tests/README.md Metodologia de regressão e golden-master

tri_comparison_ledger.json Registro de validação discordância por discordância

manual_verification.json Casos revisados onde a cobertura do comparador não está disponível

how_to_investigate_a_discrepancy.md Metodologia de discordância entre comparadores

Visualizador Visualização de repositório baseada em navegador local

Direção atual da pesquisa

O GitGalaxy está avançando por uma sequência de perguntas cada vez mais difíceis:

Podemos escanear código-fonte heterogêneo sem compilá-lo?

↓

Podemos recuperar de forma confiável as entidades estruturais necessárias para compreendê-lo?

↓

Essas medições estruturais correspondem a uma exposição de risco significativa?

↓

A exposição medida se comporta corretamente à medida que o software real evolui?

A validação Tree-sitter/Ctags está atualmente cerca de metade concluída. A prioridade imediata é concluir essa auditoria antes de transformar medições preliminares em afirmações mais fortes.

O próximo grande experimento é:

Histórico do Git → eventos de alteração/correção identificados de forma independente → varreduras antes/depois do GitGalaxy → deltas de exposição → análise estatística.

É aí que o GitGalaxy pode começar a testar não apenas se ele vê estrutura, mas se seu modelo estrutural acompanha mudanças significativas em software real.

Licença

O GitGalaxy é distribuído sob a Licença Não Comercial PolyForm 1.0.0.

Consulte a licença do repositório para os termos completos.

Ler mais

gitgalaxy — Updated!

Categorias