geographdb-core 0.1.0

Geometric graph database core - 3D spatial indexing for code analysis
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# geographdb-core API

This document summarizes the public API surface. Rustdoc remains the source of truth for exact signatures.

## Crate Root

The crate root re-exports common graph-analysis and storage types:

- `CfgGraphNode`, `CfgPath`, `PathComplexity`
- `ComplexityBlock`, `ComplexityRating`, `ComplexityResult`
- `DominanceResult`, `compute_dominance`, `compute_dominance_frontier`
- `LoopAnalysisResult`, `LoopBlock`, `LoopInfo`
- `NaturalLoop`, `find_back_edges`, `find_natural_loops`
- `SccResult`, `tarjan_scc`, `find_cycles`, `has_cycles`, `condense_graph`
- `SliceResult`, `forward_slice`, `backward_slice`
- `TopoResult`, `TopoError`, `topological_sort`, `is_dag`, `critical_path_length`
- `ReachabilityResult`, `transitive_closure`, `transitive_reduction`
- Sectioned storage types and sidecar path helpers

## `spatial`

Spatial primitives for indexing code and graph entities in 3D.

Key types:

- `BoundingBox` - axis-aligned 3D bounds.
- `Octree` - spatial index for `NodePoint` values.
- `OctreeQueryStats` - traversal metrics for spatial queries.
- `MortonEncode` - Morton/Z-order encoding helper.

Common operations:

```rust
use geographdb_core::spatial::{BoundingBox, Octree};
use geographdb_core::storage::NodePoint;
use glam::Vec3;

let bounds = BoundingBox::new(Vec3::ZERO, Vec3::splat(100.0));
let mut octree = Octree::new(bounds);

octree.insert(NodePoint { id: 7, x: 1.0, y: 2.0, z: 3.0 });
let nearby = octree.query_sphere(Vec3::new(1.0, 2.0, 3.0), 4.0);
```

## `storage`

Storage primitives for `.geo` and sidecar files.

Key types:

- `NodePoint`, `NodeRec`, `EdgeRec`, `MetadataRec`
- `StorageManager`
- `SectionedStorage`, `GeoFileHeader`, `Section`, `SectionEntry`
- `GraphSectionAdapter`, `GraphData`
- `CfgSectionAdapter`, `CfgData`, `CfgEdge`, `SerializableCfgBlock`
- `SymbolMetadataSectionAdapter`, `SymbolMetadataStore`
- `Wal`, `WalEntry`, `WalEntryType`

Sidecar helpers:

- `geo_cfg_path(base_geo)`
- `geo_idx_path(base_geo)`
- `geo_complexity_path(base_geo)`
- `all_sidecar_paths(base_geo)`

## `cfg_store`

High-level storage for CFG blocks using both persistent records and an in-memory octree.

Key types:

- `CfgBlock`
- `CfgBlockMetadata`
- `CfgStore`

Common flow:

```rust
use geographdb_core::cfg_store::{CfgBlock, CfgStore};
use glam::Vec3;

let path = tempfile::tempdir().unwrap().path().join("code.geo");
let mut store = CfgStore::create(&path).unwrap();

store.insert_block(CfgBlock {
    id: 1,
    function_id: 42,
    block_kind: "entry".to_string(),
    terminator: "goto".to_string(),
    byte_start: 0,
    byte_end: 10,
    start_line: 1,
    start_col: 0,
    end_line: 1,
    end_col: 10,
    dominator_depth: 0,
    loop_nesting: 0,
    branch_count: 0,
}).unwrap();

let blocks = store.query_nearby(Vec3::new(0.0, 0.0, 42.0), 1.0);
assert_eq!(blocks.len(), 1);
```

## `algorithms`

Graph and CFG algorithms used by the geometric backend:

- `astar` - path search and path complexity primitives.
- `complexity` - block and path complexity classification.
- `dominance` - dominators and dominance frontier.
- `loop_detection` and `natural_loops` - loop analysis.
- `scc` - strongly connected components and cycle checks.
- `slicing` - forward and backward graph slicing.
- `topo_sort` - DAG checks and topological ordering.
- `transitive` - transitive closure and reduction.

## Compatibility

`geographdb-core` is independent from Magellan's SQLite schema. Magellan owns schema ingestion and can use this crate as an optional geometric backend for spatial CFG storage and analysis.