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
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.
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.
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?
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.
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:
- the disagreement is recorded;
- the source is inspected;
- each tool's behavior is investigated;
- GitGalaxy is fixed when GitGalaxy is wrong;
- comparator/adaptor code is fixed when the comparator is wrong;
- genuine tool limitations are documented;
- 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.pydocs/self_scan/tri_comparison_ledger.json— the full, per-shape validated recorddocs/self_scan/tri_comparison_points_of_interest.md— the same ledger, rendered and ranked by signal strengthdocs/self_scan/how_to_investigate_a_discrepancy.mddocs/self_scan/manual_verification.json
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.
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.
GitGalaxy's evidence is being organized around progressively stronger questions.
Does GitGalaxy correctly identify code structures?
Tree-sitter + Ctags + independently investigated disagreements. See "Structural validation" above.
Does the implementation remain stable on real code?
Golden-master testing against Language Crucible.
Does it work on real repositories?
Unedited raw scan output from hundreds of repositories.
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.
Does exposure behave sensibly as software changes?
Git-history analysis comparing repository states before and after real changes.
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.
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.
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.
A pinned corpus of real-world source including projects such as Godot, Roslyn, curl, Kubernetes and Apollo 11 flight software.
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.
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.
Unedited GitGalaxy output is retained for hundreds of independently selected repositories.
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.
The next research layer will test whether exposure measurements correspond to real security and maintenance events over Git history.
- 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
- 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?
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.
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.
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.
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.
pip install gitgalaxySee the documentation for current commands and configuration.
Templates are provided for:
- GitHub Actions
- GitLab CI
- Bitbucket Pipelines
- Azure Pipelines
- generic shell-invocable CI environments
See templates/ and the CI integration
guide.
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
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.
Copyright (c) 2026 Joe Esquibel
GitGalaxy is distributed under the PolyForm Noncommercial License 1.0.0.
See the repository license for full terms.