How src-d/hercules works
Hercules analyzes Git commit history through a configurable Go pipeline of analysis tasks, then emits YAML or Protocol Buffers for Labours, its Python plotting tool. The graph shows the documented workflow and major analysis capabilities, plus selected internal processing and embedding layers. Some analysis modules and CLI/reader wiring are unsampled; those subsystems are represented by their existing directories, and undocumented calls are omitted.
Main entry points: pipeline.go Analysis pipeline · root.go Hercules CLI · plumbing Git plumbing · cli.py Labours CLI
Components 22
Repository analysis
- Hercules CLI
cmd/hercules/root.go - Analysis pipeline
internal/core/pipeline.go
Analysis tasks
- Project burndown
leaves/burndown.go - File couples
leaves/couples.go - Structural hotness
leaves/shotness.go - Other analyses
leaves - Typo analysis
leaves/research/typos.go
Results and plots
- Result serialization
internal/pb - Labours CLI
python/labours/cli.py - Result readers
python/labours/readers.py - Plot modes
python/labours/modes - Plot rendering
python/labours/plotting.py - Embedding export
python/labours/embeddings.py - Swivel trainer
python/labours/_vendor/swivel.py - Local web server
python/labours/cors_web_server.py
Processing internals
- Git plumbing
internal/plumbing - Identity detection
internal/plumbing/identity/identity.go - Rename analysis
internal/plumbing/renames.go - UAST processing
internal/plumbing/uast/uast.go - File burndown state
internal/burndown/file.go
Other components
- Engineer
- Git repository
Connections 21
- Engineer → Hercules CLI: runs
- Git repository → Hercules CLI: provides history
- Hercules CLI → Analysis pipeline: configures and runs
cmd/hercules/root.go - Analysis pipeline → Git plumbing: analyzes commits
- Analysis pipeline → Project burndown: dispatches tasks
- Analysis pipeline → File couples: dispatches tasks
- Analysis pipeline → Structural hotness: dispatches tasks
- Analysis pipeline → Other analyses: dispatches tasks
- Analysis pipeline → Typo analysis: dispatches tasks
- Git plumbing → Identity detection: detects authors
- Git plumbing → Rename analysis: detects renames
- Git plumbing → UAST processing: extracts syntax
internal/plumbing/uast/uast.go - Project burndown → File burndown state: updates file history
leaves/burndown.go - Typo analysis → UAST processing: uses syntax changes
leaves/research/typos.go - Hercules CLI → Labours CLI: pipes results
- Labours CLI → Result readers: reads result data
python/labours/readers.py - Labours CLI → Plot modes: selects plot mode
- Plot modes → Plot rendering: renders plots
python/labours/modes/burndown.py - Hercules CLI → Result serialization: writes protobuf
cmd/hercules/root.go - Embedding export → Swivel trainer: trains embeddings
python/labours/embeddings.py - Embedding export → Local web server: starts server
python/labours/embeddings.py