Skip to main content

khive_pack_session/mirror/
parse.rs

1//! Parsers for CLI transcripts and provider conversation exports.
2//!
3//! Every function here is deterministic and side-effect-free so the unit tests
4//! can run without any runtime or DB setup.
5
6use std::collections::{HashMap, HashSet};
7
8use chrono::DateTime;
9use khive_runtime::secret_gate;
10use serde_json::{Map, Value};
11
12fn mask_session_mirror(text: &str) -> std::borrow::Cow<'_, str> {
13    secret_gate::mask_for_redaction_surface(secret_gate::RedactionSurface::SessionMirror, text)
14}
15
16/// Bound the masker's own input window (see `secret_gate::mask_bounded`)
17/// before capping display text to `output_cap_chars`, rather than masking
18/// the full, unbounded text: cost stays proportional to the shared window
19/// regardless of input length, and a token straddling the window is dropped
20/// whole rather than echoed unmasked.
21fn mask_session_mirror_bounded(text: &str, output_cap_chars: usize) -> String {
22    secret_gate::mask_bounded(
23        secret_gate::RedactionSurface::SessionMirror,
24        text,
25        secret_gate::MASK_WINDOW_CHARS,
26        output_cap_chars,
27    )
28    .text
29}
30
31/// A single parsed event, source-agnostic.
32#[derive(Debug, Clone, PartialEq)]
33pub struct ParsedEvent {
34    /// Event UUID — the primary key for idempotency.
35    ///
36    /// For Claude Code events this is the top-level `uuid` field.
37    /// For Codex events (which carry no per-message uuid) this is synthesised
38    /// as `"{session_id}:{abs_byte_offset}"`.
39    /// For ChatGPT export events this is the mapping node's `message.id`.
40    /// For Claude.ai export events this is `chat_messages[].uuid`.
41    pub uuid: String,
42    /// Session UUID.
43    pub session_id: String,
44    /// Parent event UUID if present.
45    pub parent_uuid: Option<String>,
46    /// Whether this event is on a sidechain.
47    pub is_sidechain: bool,
48    /// Normalized provider role when present.
49    pub role: Option<String>,
50    /// Source event or content type.
51    pub msg_type: String,
52    /// Extracted display text, secrets masked; `None` for non-message events.
53    pub text: Option<String>,
54    /// Original line or serialized export message/node with secrets masked.
55    pub raw: String,
56    /// Source timestamp as microseconds since the Unix epoch; 0 if absent or unparseable.
57    pub created_at_micros: i64,
58    /// `cwd` if present, secrets masked.
59    pub cwd: Option<String>,
60    /// `gitBranch` (CC) or `payload.git.branch` (Codex) if present, secrets masked.
61    pub git_branch: Option<String>,
62    /// `slug` if present (CC: project slug; ChatGPT/Claude.ai export:
63    /// conversation title; Codex files carry no slug concept).
64    pub slug: Option<String>,
65}
66
67/// Session metadata parsed independently of retained message events.
68///
69/// Whole-file exports can contain valid conversations with no displayable
70/// messages. Keeping this record separate from [`ParsedEvent`] lets the
71/// ingester create the required `sessions` row without inventing a synthetic
72/// `session_messages` row.
73#[derive(Debug, Clone, PartialEq)]
74pub(crate) struct ParsedSession {
75    /// Provider conversation/session identifier.
76    pub(crate) session_id: String,
77    /// Source timestamp as microseconds since the Unix epoch; 0 if absent or unparseable.
78    pub(crate) created_at_micros: i64,
79    /// `cwd` if present.
80    pub(crate) cwd: Option<String>,
81    /// Source git branch if present.
82    pub(crate) git_branch: Option<String>,
83    /// Provider conversation title or project slug if present.
84    pub(crate) slug: Option<String>,
85}
86
87/// Parsed whole-file export payload used by the ingest layer.
88#[derive(Debug, Clone, PartialEq)]
89pub(crate) struct ParsedExport {
90    pub(crate) sessions: Vec<ParsedSession>,
91    pub(crate) events: Vec<ParsedEvent>,
92}
93
94/// Parse one Claude Code JSONL line.
95///
96/// Returns `None` for:
97/// - blank or whitespace-only lines
98/// - lines that are not valid JSON objects
99/// - lines that lack a top-level `uuid` field
100/// - lines that lack a top-level `sessionId` field
101///
102/// The returned `raw` and `text` fields have secrets masked.
103pub fn parse_cc_line(line: &str) -> Option<ParsedEvent> {
104    let trimmed = line.trim();
105    if trimmed.is_empty() {
106        return None;
107    }
108
109    let obj: Value = serde_json::from_str(trimmed).ok()?;
110    let map = obj.as_object()?;
111
112    // Both uuid and sessionId are required for idempotency and routing.
113    let uuid = map.get("uuid")?.as_str()?.to_string();
114    if uuid.is_empty() {
115        return None;
116    }
117    let session_id = map.get("sessionId")?.as_str()?.to_string();
118    if session_id.is_empty() {
119        return None;
120    }
121
122    let parent_uuid = map
123        .get("parentUuid")
124        .and_then(|v| v.as_str())
125        .filter(|s| !s.is_empty())
126        .map(str::to_string);
127
128    let is_sidechain = map
129        .get("isSidechain")
130        .and_then(|v| v.as_bool())
131        .unwrap_or(false);
132
133    let msg_type = map
134        .get("type")
135        .and_then(|v| v.as_str())
136        .unwrap_or("unknown")
137        .to_string();
138
139    let cwd = map
140        .get("cwd")
141        .and_then(|v| v.as_str())
142        .map(|s| mask_session_mirror(s).into_owned());
143
144    let git_branch = map
145        .get("gitBranch")
146        .and_then(|v| v.as_str())
147        .map(|s| mask_session_mirror(s).into_owned());
148
149    let slug = map
150        .get("slug")
151        .and_then(|v| v.as_str())
152        .map(|s| mask_session_mirror(s).into_owned());
153
154    let created_at_micros = map
155        .get("timestamp")
156        .and_then(|v| v.as_str())
157        .and_then(|ts| DateTime::parse_from_rfc3339(ts).ok())
158        .map(|dt| dt.timestamp_micros())
159        .unwrap_or(0);
160
161    // Extract role and text from message when present.
162    let (role, text) = match map.get("message").and_then(|m| m.as_object()) {
163        None => (None, None),
164        Some(msg) => {
165            let role = msg.get("role").and_then(|v| v.as_str()).map(str::to_string);
166            let text = extract_text(msg.get("content"));
167            (role, text)
168        }
169    };
170
171    // Apply masking to the raw line and the extracted text, reusing the
172    // canonical write-time secret detector (khive-runtime) — never a second,
173    // weaker masker.
174    let raw = mask_session_mirror(trimmed).into_owned();
175    let text = text.map(|t| mask_session_mirror(&t).into_owned());
176
177    Some(ParsedEvent {
178        uuid,
179        session_id,
180        parent_uuid,
181        is_sidechain,
182        role,
183        msg_type,
184        text,
185        raw,
186        created_at_micros,
187        cwd,
188        git_branch,
189        slug,
190    })
191}
192
193/// Parse one Codex CLI JSONL line.
194///
195/// `session_id` must be derived from the filename before calling this function
196/// (e.g. from `rollout-<timestamp>-<uuid>.jsonl`).  `abs_byte_offset` is the
197/// file byte offset of the **start** of this line; it is embedded in the
198/// synthesised event UUID so that `INSERT OR IGNORE` on `session_messages.id`
199/// is idempotent across re-tails of an append-only file.
200///
201/// Returns `None` for:
202/// - blank or whitespace-only lines
203/// - lines that are not valid JSON objects
204/// - lines whose top-level `type` is `"event_msg"` — these are duplicate
205///   event-stream representations of messages and must not be double-stored
206/// - any other line type that carries no useful message content
207///
208/// The returned `raw` and `text` fields have secrets masked.
209pub fn parse_codex_line(line: &str, session_id: &str, abs_byte_offset: u64) -> Option<ParsedEvent> {
210    let trimmed = line.trim();
211    if trimmed.is_empty() {
212        return None;
213    }
214
215    let obj: Value = serde_json::from_str(trimmed).ok()?;
216    let map = obj.as_object()?;
217
218    let line_type = map.get("type")?.as_str()?;
219
220    // event_msg lines are duplicate event-stream representations — skip them.
221    if line_type == "event_msg" {
222        return None;
223    }
224
225    let created_at_micros = map
226        .get("timestamp")
227        .and_then(|v| v.as_str())
228        .and_then(|ts| DateTime::parse_from_rfc3339(ts).ok())
229        .map(|dt| dt.timestamp_micros())
230        .unwrap_or(0);
231
232    match line_type {
233        "session_meta" => {
234            // session_meta carries cwd and git metadata; the session UUID in
235            // payload.id should match the filename-derived session_id, but we
236            // do NOT use it as the event id — use the synthesised offset key so
237            // the message row is unique and idempotent.
238            let payload = map.get("payload").and_then(|v| v.as_object());
239
240            let cwd = payload
241                .and_then(|p| p.get("cwd"))
242                .and_then(|v| v.as_str())
243                .map(|s| mask_session_mirror(s).into_owned());
244
245            let git_branch = payload
246                .and_then(|p| p.get("git"))
247                .and_then(|g| g.as_object())
248                .and_then(|g| g.get("branch"))
249                .and_then(|v| v.as_str())
250                .map(|s| mask_session_mirror(s).into_owned());
251
252            let uuid = format!("{session_id}:{abs_byte_offset}");
253            let raw = mask_session_mirror(trimmed).into_owned();
254
255            Some(ParsedEvent {
256                uuid,
257                session_id: session_id.to_string(),
258                parent_uuid: None,
259                is_sidechain: false,
260                role: None,
261                msg_type: "session_meta".to_string(),
262                text: None,
263                raw,
264                created_at_micros,
265                cwd,
266                git_branch,
267                slug: None,
268            })
269        }
270        "response_item" => {
271            let payload = map.get("payload").and_then(|v| v.as_object())?;
272
273            // Only ingest message items; skip tool_call, completion, etc.
274            if payload.get("type").and_then(|v| v.as_str()) != Some("message") {
275                return None;
276            }
277
278            let role = payload
279                .get("role")
280                .and_then(|v| v.as_str())
281                .map(str::to_string);
282
283            let text = extract_text(payload.get("content"));
284            let text = text.map(|t| mask_session_mirror_bounded(&t, 500));
285
286            let uuid = format!("{session_id}:{abs_byte_offset}");
287            let raw = mask_session_mirror(trimmed).into_owned();
288
289            Some(ParsedEvent {
290                uuid,
291                session_id: session_id.to_string(),
292                parent_uuid: None,
293                is_sidechain: false,
294                role,
295                msg_type: "response_item".to_string(),
296                text,
297                raw,
298                created_at_micros,
299                cwd: None,
300                git_branch: None,
301                slug: None,
302            })
303        }
304        // Unknown line types are silently skipped.
305        _ => None,
306    }
307}
308
309/// Parse a ChatGPT data-export `conversations.json` file: parses the whole
310/// file at once (unlike the line-at-a-time `parse_cc_line`/`parse_codex_line`)
311/// and returns every message-bearing event across every conversation, in
312/// deterministic DFS preorder per conversation.
313///
314/// Returns `None` when `content` is not valid JSON or the top level is not a
315/// JSON array — the caller treats that as a per-file error so the mirror
316/// cursor does not advance. A malformed *conversation* inside an otherwise-
317/// valid array is skipped individually, not the whole file. The returned
318/// `raw` and `text` fields have secrets masked, exactly like
319/// `parse_cc_line`/`parse_codex_line`. See
320/// `crates/khive-pack-session/docs/api/mirror-parse.md` for the DFS/sidechain
321/// algorithm detail.
322pub fn parse_chatgpt_export(content: &str) -> Option<Vec<ParsedEvent>> {
323    let value: Value = serde_json::from_str(content).ok()?;
324    let conversations = value.as_array()?;
325
326    // Both providers use the filename `conversations.json`. If operators point
327    // both roots at the same directory, rejecting an unmistakable Claude.ai
328    // file here prevents the ChatGPT ingester from consuming its cursor first.
329    if conversations.iter().any(is_claude_ai_conversation) {
330        return None;
331    }
332
333    let mut events = Vec::new();
334    for conv in conversations {
335        parse_conversation(conv, &mut events);
336    }
337    Some(events)
338}
339
340/// Parse a claude.ai data-export `conversations.json` file.
341///
342/// Claude.ai exports are a top-level JSON array whose conversation objects
343/// carry `uuid`, `name`, and `chat_messages`. Message UUIDs and conversation
344/// UUIDs are preserved as the idempotency and provider-session anchors. When
345/// `current_leaf_message_uuid` is present, messages outside its parent chain
346/// are retained with `is_sidechain = true`; older flat exports without that
347/// field keep every message on the main path.
348///
349/// Returns `None` when `content` is not valid JSON or the top level is not an
350/// array. Malformed conversation objects inside a valid array are skipped.
351pub fn parse_claude_ai_export(content: &str) -> Option<Vec<ParsedEvent>> {
352    parse_claude_ai_export_with_sessions(content).map(|parsed| parsed.events)
353}
354
355/// Parse a claude.ai export while retaining conversation metadata even when a
356/// conversation has no displayable messages.
357pub(crate) fn parse_claude_ai_export_with_sessions(content: &str) -> Option<ParsedExport> {
358    let value: Value = serde_json::from_str(content).ok()?;
359    let conversations = value.as_array()?;
360
361    // Symmetric source-shape check for accidentally overlapping export roots.
362    // Empty and wholly malformed arrays remain valid so per-conversation
363    // isolation keeps its existing semantics.
364    if conversations.iter().any(is_chatgpt_conversation) {
365        return None;
366    }
367
368    let mut sessions = Vec::new();
369    let mut events = Vec::new();
370    for conversation in conversations {
371        if let Some(session) = parse_claude_ai_conversation(conversation, &mut events) {
372            sessions.push(session);
373        }
374    }
375    Some(ParsedExport { sessions, events })
376}
377
378fn is_chatgpt_conversation(conversation: &Value) -> bool {
379    conversation.as_object().is_some_and(|conversation| {
380        conversation
381            .get("id")
382            .and_then(Value::as_str)
383            .is_some_and(|id| !id.is_empty())
384            && conversation.get("mapping").is_some_and(Value::is_object)
385    })
386}
387
388fn is_claude_ai_conversation(conversation: &Value) -> bool {
389    conversation.as_object().is_some_and(|conversation| {
390        conversation
391            .get("uuid")
392            .and_then(Value::as_str)
393            .is_some_and(|id| !id.is_empty())
394            && conversation
395                .get("chat_messages")
396                .is_some_and(Value::is_array)
397    })
398}
399
400fn parse_claude_ai_conversation(
401    conversation: &Value,
402    out: &mut Vec<ParsedEvent>,
403) -> Option<ParsedSession> {
404    let conversation = conversation.as_object()?;
405    let session_id = conversation
406        .get("uuid")
407        .and_then(Value::as_str)
408        .filter(|id| !id.is_empty())?;
409    let messages = conversation
410        .get("chat_messages")
411        .and_then(Value::as_array)?;
412
413    let slug = conversation
414        .get("name")
415        .and_then(Value::as_str)
416        .filter(|name| !name.is_empty())
417        .or_else(|| {
418            conversation
419                .get("summary")
420                .and_then(Value::as_str)
421                .filter(|summary| !summary.is_empty())
422        })
423        .map(|title| mask_session_mirror(title).into_owned());
424    let conversation_created_at_micros = conversation
425        .get("created_at")
426        .and_then(parse_rfc3339_micros)
427        .or_else(|| {
428            conversation
429                .get("updated_at")
430                .and_then(parse_rfc3339_micros)
431        })
432        .unwrap_or(0);
433
434    let mut parent_by_id: HashMap<String, Option<String>> = HashMap::new();
435    for message in messages {
436        let Some(message) = message.as_object() else {
437            continue;
438        };
439        let Some(uuid) = message
440            .get("uuid")
441            .and_then(Value::as_str)
442            .filter(|id| !id.is_empty())
443        else {
444            continue;
445        };
446        parent_by_id
447            .entry(uuid.to_string())
448            .or_insert_with(|| claude_ai_parent_uuid(message));
449    }
450
451    let current_path = claude_ai_current_path(conversation, &parent_by_id);
452    let mut order: Vec<usize> = (0..messages.len()).collect();
453    order.sort_by_key(|&position| {
454        let source_index = messages[position]
455            .as_object()
456            .and_then(|message| message.get("index"))
457            .and_then(Value::as_i64)
458            .unwrap_or(position as i64);
459        (source_index, position)
460    });
461
462    let mut emitted = HashSet::new();
463    let start = out.len();
464    for position in order {
465        let Some(message) = messages[position].as_object() else {
466            continue;
467        };
468        let Some(uuid) = message
469            .get("uuid")
470            .and_then(Value::as_str)
471            .filter(|id| !id.is_empty())
472        else {
473            continue;
474        };
475        if !emitted.insert(uuid.to_string()) {
476            continue;
477        }
478        if let Some(event) = build_claude_ai_event(
479            message,
480            session_id,
481            slug.as_deref(),
482            conversation_created_at_micros,
483            &current_path,
484        ) {
485            out.push(event);
486        }
487    }
488
489    let stored_ids: HashSet<String> = out[start..]
490        .iter()
491        .map(|event| event.uuid.clone())
492        .collect();
493    for event in &mut out[start..] {
494        if event
495            .parent_uuid
496            .as_ref()
497            .is_some_and(|parent| !stored_ids.contains(parent))
498        {
499            event.parent_uuid = None;
500        }
501    }
502
503    Some(ParsedSession {
504        session_id: session_id.to_string(),
505        created_at_micros: conversation_created_at_micros,
506        cwd: None,
507        git_branch: None,
508        slug,
509    })
510}
511
512fn claude_ai_current_path(
513    conversation: &Map<String, Value>,
514    parent_by_id: &HashMap<String, Option<String>>,
515) -> HashSet<String> {
516    let Some(current_leaf) = conversation
517        .get("current_leaf_message_uuid")
518        .and_then(Value::as_str)
519        .filter(|id| parent_by_id.contains_key(*id))
520    else {
521        return parent_by_id.keys().cloned().collect();
522    };
523
524    let mut path = HashSet::new();
525    let mut cursor = Some(current_leaf.to_string());
526    while let Some(message_id) = cursor {
527        if !path.insert(message_id.clone()) {
528            break;
529        }
530        cursor = parent_by_id.get(&message_id).cloned().flatten();
531    }
532    path
533}
534
535fn build_claude_ai_event(
536    message: &Map<String, Value>,
537    session_id: &str,
538    slug: Option<&str>,
539    conversation_created_at_micros: i64,
540    current_path: &HashSet<String>,
541) -> Option<ParsedEvent> {
542    let uuid = message
543        .get("uuid")
544        .and_then(Value::as_str)
545        .filter(|id| !id.is_empty())?
546        .to_string();
547
548    let role = message
549        .get("sender")
550        .or_else(|| message.get("role"))
551        .and_then(Value::as_str)
552        .filter(|sender| !sender.is_empty())
553        .map(|sender| match sender {
554            "human" | "user" => "user".to_string(),
555            other => other.to_string(),
556        });
557    let text = extract_claude_ai_text(message)?;
558    if text.trim().is_empty() {
559        return None;
560    }
561
562    let created_at_micros = message
563        .get("created_at")
564        .and_then(parse_rfc3339_micros)
565        .or_else(|| message.get("updated_at").and_then(parse_rfc3339_micros))
566        .unwrap_or(conversation_created_at_micros);
567    let parent_uuid = claude_ai_parent_uuid(message);
568    let raw_json = serde_json::to_string(message).unwrap_or_default();
569
570    Some(ParsedEvent {
571        uuid: uuid.clone(),
572        session_id: session_id.to_string(),
573        parent_uuid,
574        is_sidechain: !current_path.contains(&uuid),
575        role,
576        msg_type: "message".to_string(),
577        text: Some(mask_session_mirror(&text).into_owned()),
578        raw: mask_session_mirror(&raw_json).into_owned(),
579        created_at_micros,
580        cwd: None,
581        git_branch: None,
582        slug: slug.map(str::to_string),
583    })
584}
585
586fn claude_ai_parent_uuid(message: &Map<String, Value>) -> Option<String> {
587    message
588        .get("parent_message_uuid")
589        .and_then(Value::as_str)
590        .filter(|parent| !parent.is_empty() && *parent != "00000000-0000-4000-8000-000000000000")
591        .map(str::to_string)
592}
593
594fn extract_claude_ai_text(message: &Map<String, Value>) -> Option<String> {
595    let top_level_text = message
596        .get("text")
597        .and_then(Value::as_str)
598        .filter(|text| !text.trim().is_empty());
599    let mut parts = Vec::new();
600
601    match message.get("content") {
602        Some(Value::Array(blocks)) => {
603            for part in blocks
604                .iter()
605                .filter_map(extract_block)
606                .filter(|part| !part.trim().is_empty())
607            {
608                parts.push(part);
609            }
610        }
611        Some(Value::String(text)) if !text.trim().is_empty() => parts.push(text.clone()),
612        Some(_) | None => {}
613    }
614
615    if let Some(text) = top_level_text {
616        if !parts.iter().any(|part| part == text) {
617            parts.push(text.to_string());
618        }
619    }
620
621    (!parts.is_empty()).then(|| parts.join("\n"))
622}
623
624fn parse_rfc3339_micros(value: &Value) -> Option<i64> {
625    value
626        .as_str()
627        .and_then(|timestamp| DateTime::parse_from_rfc3339(timestamp).ok())
628        .map(|timestamp| timestamp.timestamp_micros())
629}
630
631/// Extract a display-friendly text string from a message `content` value
632/// (string form or structured-block array form).
633fn extract_text(content: Option<&Value>) -> Option<String> {
634    match content? {
635        Value::String(s) => Some(s.clone()),
636        Value::Array(blocks) => {
637            let parts: Vec<String> = blocks.iter().filter_map(extract_block).collect();
638            if parts.is_empty() {
639                None
640            } else {
641                Some(parts.join("\n"))
642            }
643        }
644        _ => None,
645    }
646}
647
648/// Extract a display string from a single content block (`"text"` /
649/// `"input_text"` / `"output_text"` / `"voice_note"` / `"tool_use"` /
650/// `"tool_result"`). See
651/// `crates/khive-pack-session/docs/api/mirror-parse.md#extract_text--extract_block-claude-code-codex-and-claudeai-blocks`.
652fn extract_block(block: &Value) -> Option<String> {
653    let map = block.as_object()?;
654    match map.get("type")?.as_str()? {
655        // Claude Code text block and Codex user/assistant text blocks all carry
656        // their display text in a "text" field — same extraction logic.
657        "text" | "input_text" | "output_text" | "voice_note" => {
658            map.get("text").and_then(|v| v.as_str()).map(str::to_string)
659        }
660        "tool_use" => {
661            let name = map
662                .get("name")
663                .and_then(|v| v.as_str())
664                .unwrap_or("unknown");
665            let input = map.get("input").cloned().unwrap_or(Value::Null);
666            let input_json = serde_json::to_string(&input).unwrap_or_default();
667            let input_str = mask_session_mirror_bounded(&input_json, 500);
668            Some(format!("[tool_use: {name}] {input_str}"))
669        }
670        "tool_result" => {
671            let content_val = map.get("content").cloned().unwrap_or(Value::Null);
672            let content_str = match &content_val {
673                Value::String(s) => s.clone(),
674                other => serde_json::to_string(other).unwrap_or_default(),
675            };
676            Some(format!(
677                "[tool_result] {}",
678                mask_session_mirror_bounded(&content_str, 500)
679            ))
680        }
681        _ => None,
682    }
683}
684
685/// Context threaded through one conversation's DFS walk. See
686/// `crates/khive-pack-session/docs/api/mirror-parse.md#convcontext`.
687struct ConvContext<'a> {
688    mapping: &'a Map<String, Value>,
689    current_path: &'a HashSet<String>,
690    session_id: &'a str,
691    conv_created_at_micros: i64,
692    slug: Option<&'a str>,
693}
694
695/// Parse one ChatGPT export conversation object (skips the whole
696/// conversation on a missing/empty `id` or missing `mapping`), appending its
697/// message-bearing nodes to `out` in deterministic DFS preorder. See
698/// `crates/khive-pack-session/docs/api/mirror-parse.md#parse_conversation`.
699fn parse_conversation(conv: &Value, out: &mut Vec<ParsedEvent>) {
700    let Some(conv_obj) = conv.as_object() else {
701        return;
702    };
703    let Some(session_id) = conv_obj
704        .get("id")
705        .and_then(|v| v.as_str())
706        .filter(|s| !s.is_empty())
707    else {
708        return;
709    };
710    let Some(mapping) = conv_obj.get("mapping").and_then(|v| v.as_object()) else {
711        return;
712    };
713
714    let slug = conv_obj
715        .get("title")
716        .and_then(|v| v.as_str())
717        .filter(|s| !s.is_empty())
718        .map(|title| mask_session_mirror(title).into_owned());
719
720    let conv_created_at_micros = conv_obj
721        .get("create_time")
722        .and_then(|v| v.as_f64())
723        .map(|secs| (secs * 1_000_000.0) as i64)
724        .unwrap_or(0);
725
726    // current-path set: walk current_node -> parent -> ... -> root; off-path
727    // nodes are flagged is_sidechain (see docs guide).
728    let mut current_path: HashSet<String> = HashSet::new();
729    if let Some(current_node) = conv_obj.get("current_node").and_then(|v| v.as_str()) {
730        let mut cursor = Some(current_node.to_string());
731        while let Some(node_id) = cursor {
732            if !current_path.insert(node_id.clone()) {
733                break; // cycle guard against malformed mapping data
734            }
735            cursor = mapping
736                .get(&node_id)
737                .and_then(|n| n.as_object())
738                .and_then(|n| n.get("parent"))
739                .and_then(|v| v.as_str())
740                .map(str::to_string);
741        }
742    }
743
744    let root_id = mapping.iter().find_map(|(id, node)| {
745        let node_obj = node.as_object()?;
746        let parent_is_null = node_obj.get("parent").map(|v| v.is_null()).unwrap_or(true);
747        parent_is_null.then(|| id.clone())
748    });
749    let Some(root_id) = root_id else {
750        return;
751    };
752
753    let ctx = ConvContext {
754        mapping,
755        current_path: &current_path,
756        session_id,
757        conv_created_at_micros,
758        slug: slug.as_deref(),
759    };
760
761    // Deterministic DFS preorder, explicit stack (not recursion — see docs guide).
762    let mut stack: Vec<String> = vec![root_id];
763    let mut visited: HashSet<String> = HashSet::new();
764
765    while let Some(node_id) = stack.pop() {
766        if !visited.insert(node_id.clone()) {
767            continue; // cycle guard
768        }
769        let Some(node) = mapping.get(&node_id).and_then(|n| n.as_object()) else {
770            continue;
771        };
772
773        if let Some(message) = node.get("message").filter(|m| !m.is_null()) {
774            if let Some(message_obj) = message.as_object() {
775                if let Some(ev) = build_chatgpt_event(&node_id, node, message_obj, &ctx) {
776                    out.push(ev);
777                }
778            }
779        }
780
781        if let Some(children) = node.get("children").and_then(|c| c.as_array()) {
782            // Push in reverse so the first child in the array is popped (and
783            // thus visited) first — preorder must follow children order.
784            for child in children.iter().rev() {
785                if let Some(child_id) = child.as_str() {
786                    stack.push(child_id.to_string());
787                }
788            }
789        }
790    }
791}
792
793/// Build a `ParsedEvent` for a single message-bearing mapping node; `None`
794/// on a missing `id` or empty/whitespace-only extracted text (ChatGPT
795/// scaffolding nodes). See
796/// `crates/khive-pack-session/docs/api/mirror-parse.md#build_chatgpt_event`.
797fn build_chatgpt_event(
798    node_id: &str,
799    node: &Map<String, Value>,
800    message: &Map<String, Value>,
801    ctx: &ConvContext,
802) -> Option<ParsedEvent> {
803    let uuid = message
804        .get("id")
805        .and_then(|v| v.as_str())
806        .filter(|s| !s.is_empty())?
807        .to_string();
808
809    let role = message
810        .get("author")
811        .and_then(|a| a.as_object())
812        .and_then(|a| a.get("role"))
813        .and_then(|v| v.as_str())
814        .map(str::to_string);
815
816    let content = message.get("content").and_then(|c| c.as_object());
817    let content_type = content
818        .and_then(|c| c.get("content_type"))
819        .and_then(|v| v.as_str())
820        .unwrap_or("unknown")
821        .to_string();
822
823    let text = extract_chatgpt_text(&content_type, content)?;
824    if text.trim().is_empty() {
825        return None;
826    }
827
828    let created_at_micros = message
829        .get("create_time")
830        .and_then(|v| v.as_f64())
831        .map(|secs| (secs * 1_000_000.0) as i64)
832        .unwrap_or(ctx.conv_created_at_micros);
833
834    // parent_uuid is Some only when the parent node itself carries a message
835    // (provenance linkage — see docs guide).
836    let parent_uuid = node
837        .get("parent")
838        .and_then(|v| v.as_str())
839        .filter(|pid| {
840            ctx.mapping
841                .get(*pid)
842                .and_then(|p| p.as_object())
843                .and_then(|p| p.get("message"))
844                .map(|m| !m.is_null())
845                .unwrap_or(false)
846        })
847        .map(str::to_string);
848
849    let is_sidechain = !ctx.current_path.contains(node_id);
850
851    let raw_json = serde_json::to_string(node).unwrap_or_default();
852    let raw = mask_session_mirror(&raw_json).into_owned();
853    let text = mask_session_mirror(&text).into_owned();
854
855    Some(ParsedEvent {
856        uuid,
857        session_id: ctx.session_id.to_string(),
858        parent_uuid,
859        is_sidechain,
860        role,
861        msg_type: content_type,
862        text: Some(text),
863        raw,
864        created_at_micros,
865        cwd: None,
866        git_branch: None,
867        slug: ctx.slug.map(str::to_string),
868    })
869}
870
871/// Extract display text from a ChatGPT message `content` object per its
872/// `content_type`. See
873/// `crates/khive-pack-session/docs/api/mirror-parse.md#extract_chatgpt_text`.
874fn extract_chatgpt_text(
875    content_type: &str,
876    content: Option<&Map<String, Value>>,
877) -> Option<String> {
878    let content = content?;
879
880    if content_type == "text" {
881        return extract_chatgpt_parts(content);
882    }
883
884    if let Some(text) = content.get("text").and_then(|v| v.as_str()) {
885        return Some(text.to_string());
886    }
887
888    extract_chatgpt_parts(content)
889}
890
891fn extract_chatgpt_parts(content: &Map<String, Value>) -> Option<String> {
892    let parts = content.get("parts")?.as_array()?;
893    let joined: Vec<String> = parts
894        .iter()
895        .filter_map(|p| p.as_str().map(str::to_string))
896        .collect();
897    if joined.is_empty() {
898        None
899    } else {
900        Some(joined.join("\n"))
901    }
902}
903
904// ── unit tests ────────────────────────────────────────────────────────────────
905
906#[cfg(test)]
907#[path = "parse_tests.rs"]
908mod tests;