35 lines
1.8 KiB
Markdown
35 lines
1.8 KiB
Markdown
# Reachability Callgraph Formats (richgraph-v1)
|
|
|
|
## Purpose
|
|
Normalize static callgraphs across languages so Signals can merge them with runtime traces and replay bundles deterministically.
|
|
|
|
## Core fields (per node/edge)
|
|
- `nodes[].id` — canonical SymbolID (language-specific, stable, lowercase where applicable).
|
|
- `nodes[].kind` — e.g., method/function/class/file.
|
|
- `edges[].sourceId` / `edges[].targetId` — SymbolIDs; edge types include `call`, `import`, `inherit`, `reference`.
|
|
- `artifact` — CAS paths for source graph files; include `sha256`, `uri`, optional `generator` (analyzer name/version).
|
|
|
|
## Language-specific notes
|
|
- **JVM**: use JVM internal names; include signature for overloads.
|
|
- **.NET/Roslyn**: fully-qualified method token; include assembly and module for cross-assembly edges.
|
|
- **Go SSA**: package path + function; include receiver for methods.
|
|
- **Node/Deno TS**: module path + exported symbol; ES module graph only.
|
|
- **Rust MIR**: crate::module::symbol; monomorphized forms allowed if stable.
|
|
- **Swift SIL**: mangled name; demangled kept in metadata only.
|
|
- **Shell/binaries**: when present, use ELF/PE symbol+offset; mark `kind=binary`.
|
|
|
|
## CAS layout
|
|
- Store graph bundles under `reachability_graphs/<hh>/<sha>.tar.zst`.
|
|
- Bundle SHOULD contain `meta.json` with analyzer, version, language, component, and entry points (array).
|
|
- File order inside tar must be lexicographic to keep hashes stable.
|
|
|
|
## Validation rules
|
|
- No duplicate node IDs; edges must reference existing nodes.
|
|
- Entry points list must be present (even if empty) for Signals recompute.
|
|
- Graph SHA256 must match tar content; Signals rejects mismatched SHA.
|
|
- Only ASCII; UTF-8 paths are allowed but must be normalized (NFC).
|
|
|
|
## References
|
|
- Union schema: `docs/reachability/runtime-static-union-schema.md`
|
|
- Delivery guide: `docs/reachability/DELIVERY_GUIDE.md`
|