GitGalaxy

Repository-scale structural intelligence without compilation.

Docs · Visualizer · Language Crucible · Raw Output

1 scan · 97 structural signals · 50+ languages · no compilation · 19 risk-exposure categories · 6 outputs

The short version

GitGalaxy builds a language-agnostic structural graph of an entire repository directly from source text.

It is designed for repositories that are polyglot, partially broken, legacy, vendor-heavy, or otherwise difficult to analyze through a build-first workflow.

Instead of requiring a successful build and a separate parser/toolchain for every language, GitGalaxy extracts a common vocabulary of structural signatures---functions, classes, arguments, control flow, state mutation, I/O, APIs, dependencies, and other signals---and normalizes those observations into one repository model.

The same graph can then feed:

• architecture analysis
• risk-exposure prioritization
• dependency/SBOM analysis
• refactoring and ownership analysis
• legacy-code analysis
• AI-oriented codebase context
• CI/CD workflows
• historical risk analysis

Central thesis: complete language parsing is not always necessary to recover highly useful structural information at repository scale.

The problem

Large repositories routinely contain:

Go + C++ + Python + Java + Bash + YAML
+ generated code + vendored code + legacy code
+ half-migrated modules + broken dependencies

Traditional language tooling can be excellent within its intended scope while still leaving the repository fragmented across language-specific representations.

GitGalaxy makes a different trade:

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

The objective is not to reproduce every syntactic detail of every language.

The objective is to recover the structural information downstream repository intelligence actually needs.

One graph, many consumers

GitGalaxy's core output is a deterministic structural representation of the repository.

Consumer Question

Architecture What is this repository made of?

Structural analysis Where are the functions, classes, APIs, dependencies and control structures?

Risk exposure Where are potentially important risk patterns concentrated?

Refactoring Which files are complex, high-churn or load-bearing?

Supply chain What dependencies physically exist on disk?

AI context What architecture and relationships should an agent know?

Legacy migration Where are the structural units to transform?

Historical analysis How does measured exposure change as the repository evolves?

The structural-extraction thesis

GitGalaxy deliberately does not begin by constructing a complete AST for every language.

It uses approximately 97 structural-signal categories to identify things such as:

• function and method boundaries
• classes and declarations
• arguments
• branches and control flow
• state mutation
• I/O
• APIs and routes
• imports and dependencies
• unsafe operations
• reflection and dynamic execution
• concurrency
• closures
• globals
• entropy and physical-file anomalies

This creates a specific, testable hypothesis:

For repository-scale intelligence, targeted structural extraction can recover the entities required for useful code intelligence without requiring a complete language parser for every file.

That hypothesis is being tested empirically.

Structural validation: GitGalaxy vs Tree-sitter vs Ctags

This is currently one of the most important validation programs in the project.

GitGalaxy is being evaluated against Tree-sitter and Universal Ctags on the same Language Crucible corpus.

The first structural targets are:

• functions
• classes
• arguments

The benchmark is deliberately not treated as a three-tool popularity contest.

When tools disagree:

1. the disagreement is recorded;
2. the source is inspected;
3. each tool's behavior is investigated;
4. GitGalaxy is fixed when GitGalaxy is wrong;
5. comparator/adaptor code is fixed when the comparator is wrong;
6. genuine tool limitations are documented;
7. the result is re-measured.

24 of 45 languages get all three tools compared, 16 more get two, and 5 GitGalaxy-only languages (abap, dockerfile, jcl, livecode, yaml) get hand-reviewed manual verification instead of cross-tool agreement. Of the 180 discrepancy shapes logged so far, 87 are validated (48%) — read, investigated, and recorded with a verdict, not just counted.

The goal is to finish the audit, close remaining GitGalaxy defects, establish independent ground truth where necessary, and then publish final precision/recall measurements. See the tri-comparison methodology doc for how matching, the ledger lifecycle, and CI enforcement work.

See:

• tests/tools/tri_comparison_chart.py
• docs/self_scan/tri_comparison_ledger.json — the full, per-shape validated record
• docs/self_scan/tri_comparison_points_of_interest.md — the same ledger, rendered and ranked by signal strength
• docs/self_scan/how_to_investigate_a_discrepancy.md
• docs/self_scan/manual_verification.json

What the benchmark is actually asking

Not:

"Is GitGalaxy a better parser than Tree-sitter?"

But:

"For the structural entities GitGalaxy needs to build its repository graph, how accurately can targeted structural extraction recover them compared with established parsing and indexing systems?"

That is the narrower claim the experiment can support.

Languages without suitable comparator coverage

Some languages do not currently have a suitable independent Tree-sitter/Ctags comparison path.

Those are kept in a separate evidentiary category and use committed manual verification rather than pretending cross-tool agreement exists.

This currently includes languages such as:

• ABAP
• Dockerfile
• JCL
• LiveCode
• YAML

Where practical, the next step is to add independent lexical, grammar-based, or domain-specific comparators. Where no credible independent comparator exists, human-verified ground truth remains the appropriate category.

Validation is a ladder

GitGalaxy's evidence is being organized around progressively stronger questions.

1. Structural validity

Does GitGalaxy correctly identify code structures?

Tree-sitter + Ctags + independently investigated disagreements. See "Structural validation" above.

2. Regression validity

Does the implementation remain stable on real code?

Golden-master testing against Language Crucible.

3. Scale validity

Does it work on real repositories?

Unedited raw scan output from hundreds of repositories.

4. Model validity

Do structural signatures correspond to the exposure categories they are intended to represent?

Statistical analysis against independently observable outcomes---not merely against GitGalaxy's own equations.

5. Temporal validity

Does exposure behave sensibly as software changes?

Git-history analysis comparing repository states before and after real changes.

6. External validity

Do exposure changes correspond to independently documented security or maintenance outcomes?

Future work: security fixes, regressions, advisories, defects and other external event datasets.

This distinction matters: a score can be internally consistent without necessarily being externally meaningful.

Risk exposure: what GitGalaxy claims

GitGalaxy produces risk-exposure measurements, not vulnerability verdicts.

A high exposure means:

This location deserves attention relative to the rest of the repository.

It does not mean:

"This code is definitely vulnerable."

The current system produces normalized exposure categories across the repository and rolls information from structural entities through files, folders and repository-level views.

The underlying signatures cover patterns involving areas such as:

• secrets
• injection surface
• unsafe/memory operations
• dynamic execution
• I/O
• concurrency
• state mutation
• reflection
• APIs
• dependencies
• entropy
• other structural/security characteristics

The important research question is whether these signatures are empirically associated with meaningful classes of software risk, rather than merely correlated with a score that GitGalaxy itself mathematically constructed.

That distinction drives the next phase.

The next validation: risk over Git history

Once structural validation is sufficiently mature, GitGalaxy can test its exposure model longitudinally.

Git history
    |
    v
security-relevant event
    |
    +-------------------+
    |                   |
    v                   v
parent state        changed state
    |                   |
    v                   v
GitGalaxy scan      GitGalaxy scan
    |                   |
    +---------+---------+
              |
              v
        exposure delta
              |
              v
     independent event class

The central experiment is:

Do commits independently identified as security fixes typically reduce the corresponding GitGalaxy exposure?

Negative controls are equally important:

Do ordinary development commits show the same behavior?

Eventually:

Do security regressions increase exposure?

The planned harness will preserve commit SHA, parent state, changed files/functions, exposure before/after, exposure deltas, structural changes and event classification.

That tests:

structure → exposure → real software evolution

rather than merely testing the internal mathematics of the exposure model.

Evidence, not just claims

Language Crucible

A pinned corpus of real-world source including projects such as Godot, Roslyn, curl, Kubernetes and Apollo 11 flight software.

Language Crucible

Golden-master regression

Real source is rescanned and compared against checked-in expected output so parser changes have an observable diff. Regenerated with tests/tools/update_golden_master.py, never hand-edited.

Tri-comparison

The same corpus is analyzed against GitGalaxy, Tree-sitter and Ctags where coverage exists — 24 of 45 languages get all three tools, 87 of 180 logged discrepancies validated so far. See the methodology and the "structural validation" section above for the full picture.

Raw repository output

Unedited GitGalaxy output is retained for hundreds of independently selected repositories.

Raw Output

Regression suite

7,043 tests in the default suite (python -m pytest tests/), of which 6,165 are per-signature tests across all 45 structurally-signatured languages — positive matches, explicit exclusions, and adversarial/ReDoS inputs. See tests/README.md for the breakdown, and docs/why_gitgalaxy_beats_ast_here.md for specific, evidenced cases where this extraction beats an AST read.

Historical validation

The next research layer will test whether exposure measurements correspond to real security and maintenance events over Git history.

What GitGalaxy is --- and isn't

GitGalaxy is

• repository-scale structural intelligence
• language-agnostic source analysis
• a common structural representation across heterogeneous code
• risk-exposure prioritization
• architecture mapping
• CI-native evidence generation
• useful on broken/uncompiled repositories
• designed for local/offline operation

GitGalaxy is not

• a replacement for CodeQL's deep dataflow analysis
• a replacement for Semgrep's rule ecosystem
• a replacement for dependency CVE databases
• a proof of exploitability
• a runtime analyzer
• a complete language parser
• a guarantee that a high exposure is a vulnerability

Tool Primary question

GitGalaxy What does this entire repository look like, structurally, and where should attention go first?

Tree-sitter What syntactic structure does this source contain?

Ctags Where are the navigable code entities?

Semgrep Does this code match a specified pattern?

CodeQL What data/control relationships can deeper analysis establish?

SCA/CVE tools Is this dependency/version associated with a known advisory?

Real-world scale

GitGalaxy is intended for repositories too heterogeneous or broken for a traditional single-language build-first workflow.

Example: Kubernetes

~1.39M lines across Go, YAML, JSON, Shell and Proto.

End-to-end scan: 50.83 seconds.

See the raw output repository for unedited artifacts.

Outputs

Output Purpose

SARIF CI/security dashboard integration CycloneDX SBOM Dependency inventory/compliance SQLite Queryable repository knowledge graph LLM architecture brief Compact machine/agent-oriented context JSON audit data Forensic/automation workflows 3D visualization data Interactive repository topology

These are different views of the same deterministic scan, rather than independent analysis engines.

Git history and architecture

GitGalaxy already incorporates Git history into signals such as:

• churn
• contributor concentration
• bus-factor exposure
• refactoring hotspots
• file ownership
• temporal activity

The research direction is to extend this from history as a contextual signal to history as an external validation source for the exposure model.

Privacy and deployment

GitGalaxy is designed for local and air-gapped operation.

• Source code is not sent to a GitGalaxy cloud service.
• Scanning and vectorization occur locally.
• The scanner has no runtime network requirement.
• CI/CD execution can remain inside the user's environment.
• The browser visualizer operates on locally supplied data.

Installation

pip install gitgalaxy

See the documentation for current commands and configuration.

CI/CD

Templates are provided for:

• GitHub Actions
• GitLab CI
• Bitbucket Pipelines
• Azure Pipelines
• generic shell-invocable CI environments

See templates/ and the CI integration guide.

Explore the evidence

Resource What it contains

Documentation Architecture, claims and methodology

Language Crucible Cross-language benchmark and golden corpus

Raw Output Unedited scans of real repositories

tests/README.md Regression and golden-master methodology

tri_comparison_ledger.json Disagreement-by-disagreement validation record

manual_verification.json Reviewed cases where comparator coverage is unavailable

how_to_investigate_a_discrepancy.md Comparator-disagreement methodology

Visualizer Local browser-based repository visualization

Current research direction

GitGalaxy is moving through a sequence of increasingly difficult questions:

Can we scan heterogeneous source without compiling it?

↓

Can we reliably recover the structural entities needed to understand it?

↓

Do those structural measurements correspond to meaningful risk exposure?

↓

Does measured exposure behave correctly as real software evolves?

The Tree-sitter/Ctags validation is currently about halfway complete. The immediate priority is to finish that audit before turning preliminary measurements into stronger claims.

The next major experiment is:

Git history → independently identified change/fix events → GitGalaxy before/after scans → exposure deltas → statistical analysis.

That is where GitGalaxy can begin testing not only whether it sees structure, but whether its structural model tracks meaningful changes in real software.

License

Copyright (c) 2026 Joe Esquibel

GitGalaxy is distributed under the PolyForm Noncommercial License 1.0.0.

See the repository license for full terms.