lean_ctx/core/property_graph/
snapshot.rs

1//! Versioned, committable graph snapshots — Context-as-Code (GL#451).
2//!
3//! Exports the property graph as deterministic JSON Lines: one header, one
4//! line per node, one line per edge, all stably sorted and free of local
5//! AUTOINCREMENT ids (edges reference nodes by their (kind, name, file)
6//! identity). The same graph always serializes to the same bytes, so the
7//! snapshot can live in git, diff cleanly, and merge across team members.
8
9use std::collections::HashMap;
10
11use rusqlite::params;
12use serde::{Deserialize, Serialize};
13
14use super::{CodeGraph, Edge, EdgeKind, Node, NodeKind};
15
16pub const SNAPSHOT_VERSION: u32 = 1;
17
18#[derive(Debug, Serialize, Deserialize)]
19struct SnapshotHeader {
20    leanctx_graph_snapshot: u32,
21    nodes: usize,
22    edges: usize,
23}
24
25/// Node identity + payload, id-free. Field order = serialization order.
26#[derive(Debug, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
27struct SnapNode {
28    kind: String,
29    file: String,
30    name: String,
31    #[serde(skip_serializing_if = "Option::is_none")]
32    line_start: Option<usize>,
33    #[serde(skip_serializing_if = "Option::is_none")]
34    line_end: Option<usize>,
35    #[serde(skip_serializing_if = "Option::is_none")]
36    meta: Option<String>,
37}
38
39/// Edge with endpoints referenced by node identity, id-free.
40#[derive(Debug, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
41struct SnapEdge {
42    kind: String,
43    source: (String, String, String),
44    target: (String, String, String),
45    #[serde(skip_serializing_if = "Option::is_none")]
46    meta: Option<String>,
47}
48
49#[derive(Debug, Default)]
50pub struct ImportStats {
51    pub nodes: usize,
52    pub edges: usize,
53    pub skipped_edges: usize,
54}
55
56#[derive(Debug, Default)]
57pub struct DriftReport {
58    pub only_local: usize,
59    pub only_snapshot: usize,
60    pub common: usize,
61}
62
63impl DriftReport {
64    pub fn in_sync(&self) -> bool {
65        self.only_local == 0 && self.only_snapshot == 0
66    }
67}
68
69fn collect_nodes(graph: &CodeGraph) -> anyhow::Result<Vec<SnapNode>> {
70    let conn = graph.connection();
71    let mut stmt =
72        conn.prepare("SELECT kind, file_path, name, line_start, line_end, metadata FROM nodes")?;
73    let mut nodes: Vec<SnapNode> = stmt
74        .query_map([], |row| {
75            Ok(SnapNode {
76                kind: row.get(0)?,
77                file: row.get(1)?,
78                name: row.get(2)?,
79                line_start: row.get::<_, Option<i64>>(3)?.map(|v| v as usize),
80                line_end: row.get::<_, Option<i64>>(4)?.map(|v| v as usize),
81                meta: row.get(5)?,
82            })
83        })?
84        .collect::<Result<_, _>>()?;
85    nodes.sort();
86    Ok(nodes)
87}
88
89fn collect_edges(graph: &CodeGraph) -> anyhow::Result<Vec<SnapEdge>> {
90    let conn = graph.connection();
91    let mut stmt = conn.prepare(
92        "SELECT e.kind, e.metadata,
93                s.kind, s.file_path, s.name,
94                t.kind, t.file_path, t.name
95         FROM edges e
96         JOIN nodes s ON s.id = e.source_id
97         JOIN nodes t ON t.id = e.target_id",
98    )?;
99    let mut edges: Vec<SnapEdge> = stmt
100        .query_map([], |row| {
101            Ok(SnapEdge {
102                kind: row.get(0)?,
103                meta: row.get(1)?,
104                source: (row.get(2)?, row.get(3)?, row.get(4)?),
105                target: (row.get(5)?, row.get(6)?, row.get(7)?),
106            })
107        })?
108        .collect::<Result<_, _>>()?;
109    edges.sort();
110    Ok(edges)
111}
112
113/// Serialize the whole graph as deterministic JSON Lines.
114pub fn export_snapshot(graph: &CodeGraph) -> anyhow::Result<String> {
115    let nodes = collect_nodes(graph)?;
116    let edges = collect_edges(graph)?;
117
118    let mut out = String::new();
119    out.push_str(&serde_json::to_string(&SnapshotHeader {
120        leanctx_graph_snapshot: SNAPSHOT_VERSION,
121        nodes: nodes.len(),
122        edges: edges.len(),
123    })?);
124    out.push('\n');
125    for n in &nodes {
126        out.push_str(&format!("{{\"n\":{}}}\n", serde_json::to_string(n)?));
127    }
128    for e in &edges {
129        out.push_str(&format!("{{\"e\":{}}}\n", serde_json::to_string(e)?));
130    }
131    Ok(out)
132}
133
134/// Merge a snapshot into the local graph: nodes and edges are upserted, the
135/// local graph is never truncated (local-first merge — newer local scan data
136/// wins on conflicting node payloads via the upsert).
137pub fn import_snapshot(graph: &CodeGraph, content: &str) -> anyhow::Result<ImportStats> {
138    let (nodes, edges) = parse_snapshot(content)?;
139    let mut stats = ImportStats::default();
140    let mut id_by_identity: HashMap<(String, String, String), i64> = HashMap::new();
141
142    for n in &nodes {
143        let node = Node {
144            id: None,
145            kind: NodeKind::parse(&n.kind),
146            name: n.name.clone(),
147            file_path: n.file.clone(),
148            line_start: n.line_start,
149            line_end: n.line_end,
150            metadata: n.meta.clone(),
151        };
152        let id = graph.upsert_node(&node)?;
153        id_by_identity.insert((n.kind.clone(), n.file.clone(), n.name.clone()), id);
154        stats.nodes += 1;
155    }
156
157    for e in &edges {
158        let source = resolve_endpoint(graph, &mut id_by_identity, &e.source);
159        let target = resolve_endpoint(graph, &mut id_by_identity, &e.target);
160        match (source, target) {
161            (Some(s), Some(t)) => {
162                graph.upsert_edge(&Edge {
163                    id: None,
164                    source_id: s,
165                    target_id: t,
166                    kind: EdgeKind::parse(&e.kind),
167                    metadata: e.meta.clone(),
168                })?;
169                stats.edges += 1;
170            }
171            _ => stats.skipped_edges += 1,
172        }
173    }
174
175    Ok(stats)
176}
177
178/// Compare the local graph against a snapshot, line-set based.
179pub fn check_snapshot(graph: &CodeGraph, content: &str) -> anyhow::Result<DriftReport> {
180    let local = export_snapshot(graph)?;
181    let local_set: std::collections::HashSet<&str> =
182        local.lines().skip(1).filter(|l| !l.is_empty()).collect();
183    let snap_set: std::collections::HashSet<&str> =
184        content.lines().skip(1).filter(|l| !l.is_empty()).collect();
185
186    Ok(DriftReport {
187        only_local: local_set.difference(&snap_set).count(),
188        only_snapshot: snap_set.difference(&local_set).count(),
189        common: local_set.intersection(&snap_set).count(),
190    })
191}
192
193fn resolve_endpoint(
194    graph: &CodeGraph,
195    cache: &mut HashMap<(String, String, String), i64>,
196    identity: &(String, String, String),
197) -> Option<i64> {
198    if let Some(&id) = cache.get(identity) {
199        return Some(id);
200    }
201    // Endpoint may already exist locally without being part of the snapshot.
202    let conn = graph.connection();
203    let found: Option<i64> = conn
204        .query_row(
205            "SELECT id FROM nodes WHERE kind = ?1 AND file_path = ?2 AND name = ?3",
206            params![identity.0, identity.1, identity.2],
207            |row| row.get(0),
208        )
209        .ok();
210    if let Some(id) = found {
211        cache.insert(identity.clone(), id);
212    }
213    found
214}
215
216fn parse_snapshot(content: &str) -> anyhow::Result<(Vec<SnapNode>, Vec<SnapEdge>)> {
217    let mut lines = content.lines().filter(|l| !l.trim().is_empty());
218    let header_line = lines
219        .next()
220        .ok_or_else(|| anyhow::anyhow!("empty snapshot"))?;
221    let header: SnapshotHeader = serde_json::from_str(header_line)
222        .map_err(|e| anyhow::anyhow!("invalid snapshot header: {e}"))?;
223    if header.leanctx_graph_snapshot != SNAPSHOT_VERSION {
224        anyhow::bail!(
225            "unsupported snapshot version {} (supported: {SNAPSHOT_VERSION})",
226            header.leanctx_graph_snapshot
227        );
228    }
229
230    let mut nodes = Vec::new();
231    let mut edges = Vec::new();
232    for line in lines {
233        let v: serde_json::Value = serde_json::from_str(line)
234            .map_err(|e| anyhow::anyhow!("invalid snapshot line: {e}"))?;
235        if let Some(n) = v.get("n") {
236            nodes.push(serde_json::from_value::<SnapNode>(n.clone())?);
237        } else if let Some(e) = v.get("e") {
238            edges.push(serde_json::from_value::<SnapEdge>(e.clone())?);
239        } else {
240            anyhow::bail!("unknown snapshot line shape: {line}");
241        }
242    }
243    Ok((nodes, edges))
244}
245
246#[cfg(test)]
247mod tests {
248    use super::*;
249
250    fn graph_with_data() -> CodeGraph {
251        let g = CodeGraph::open_in_memory().unwrap();
252        let a = g.upsert_node(&Node::file("src/auth.rs")).expect("node a");
253        let b = g.upsert_node(&Node::file("src/db.rs")).expect("node b");
254        g.upsert_edge(&Edge::new(a, b, EdgeKind::Imports))
255            .expect("edge");
256        g
257    }
258
259    #[test]
260    fn export_is_deterministic_and_id_free() {
261        let g = graph_with_data();
262        let s1 = export_snapshot(&g).unwrap();
263        let s2 = export_snapshot(&g).unwrap();
264        assert_eq!(s1, s2);
265        assert!(!s1.contains("\"id\""), "snapshot must not leak local ids");
266        assert!(s1.starts_with("{\"leanctx_graph_snapshot\":1"));
267    }
268
269    #[test]
270    fn roundtrip_export_import_is_lossless() {
271        let g = graph_with_data();
272        let snapshot = export_snapshot(&g).unwrap();
273
274        let fresh = CodeGraph::open_in_memory().unwrap();
275        let stats = import_snapshot(&fresh, &snapshot).unwrap();
276        assert_eq!(stats.nodes, 2);
277        assert_eq!(stats.edges, 1);
278        assert_eq!(stats.skipped_edges, 0);
279
280        let reexported = export_snapshot(&fresh).unwrap();
281        assert_eq!(snapshot, reexported, "roundtrip must be lossless");
282    }
283
284    #[test]
285    fn import_merges_instead_of_replacing() {
286        let g = graph_with_data();
287        let snapshot = export_snapshot(&g).unwrap();
288
289        let local = CodeGraph::open_in_memory().unwrap();
290        local
291            .upsert_node(&Node::file("src/local_only.rs"))
292            .expect("local node");
293
294        import_snapshot(&local, &snapshot).unwrap();
295        let merged = export_snapshot(&local).unwrap();
296        assert!(merged.contains("local_only.rs"), "local data must survive");
297        assert!(merged.contains("auth.rs"), "snapshot data must be merged");
298    }
299
300    #[test]
301    fn check_reports_drift_and_sync() {
302        let g = graph_with_data();
303        let snapshot = export_snapshot(&g).unwrap();
304
305        let synced = check_snapshot(&g, &snapshot).unwrap();
306        assert!(synced.in_sync());
307
308        g.upsert_node(&Node::file("src/new_file.rs")).unwrap();
309        let drifted = check_snapshot(&g, &snapshot).unwrap();
310        assert!(!drifted.in_sync());
311        assert_eq!(drifted.only_local, 1);
312        assert_eq!(drifted.only_snapshot, 0);
313    }
314
315    #[test]
316    fn rejects_wrong_version() {
317        let g = CodeGraph::open_in_memory().unwrap();
318        let err = import_snapshot(
319            &g,
320            "{\"leanctx_graph_snapshot\":99,\"nodes\":0,\"edges\":0}\n",
321        )
322        .unwrap_err();
323        assert!(err.to_string().contains("unsupported snapshot version"));
324    }
325}
lean_ctx/core/property_graph/snapshot.rs

lean_ctx/core/property_graph/
snapshot.rs
