sqlite_graphrag/commands/

history.rs

//! Handler for the `history` CLI subcommand.

use crate::errors::AppError;
use crate::i18n::errors_msg;
use crate::output;
use crate::paths::AppPaths;
use crate::storage::connection::open_ro;
use rusqlite::params;
use rusqlite::OptionalExtension;
use serde::Serialize;

#[derive(clap::Args)]
#[command(after_long_help = "EXAMPLES:\n  \
    # List all versions of a memory (positional form)\n  \
    sqlite-graphrag history onboarding\n\n  \
    # List versions using the named flag form\n  \
    sqlite-graphrag history --name onboarding\n\n  \
    # Omit body content to reduce response size\n  \
    sqlite-graphrag history onboarding --no-body\n\n  \
    # Include character-level change summary between versions\n  \
    sqlite-graphrag history onboarding --diff\n\n\
DIFF OUTPUT:\n  \
    When --diff is active, each version (except the first) includes a `changes`\n  \
    object with `added_chars` and `removed_chars` — the character count difference\n  \
    between that version and its predecessor.")]
/// History args.
pub struct HistoryArgs {
    /// Memory name as a positional argument. Alternative to `--name`.
    #[arg(
        value_name = "NAME",
        conflicts_with = "name",
        help = "Memory name whose version history to return; alternative to --name"
    )]
    pub name_positional: Option<String>,
    /// Memory name whose version history will be returned. Includes soft-deleted memories
    /// so that `restore --version <V>` workflow remains discoverable after `forget`.
    #[arg(long)]
    pub name: Option<String>,
    #[arg(
        long,
        help = "Namespace (flag / XDG namespace.default / global)"
    )]
    /// Namespace scope.
    pub namespace: Option<String>,
    /// Omit body content from each version to reduce response size.
    #[arg(
        long,
        default_value_t = false,
        help = "Omit body content from response"
    )]
    pub no_body: bool,
    /// Include character-level change summary between consecutive versions.
    #[arg(
        long,
        default_value_t = false,
        help = "Include character-level change summary between consecutive versions"
    )]
    pub diff: bool,
    /// Emit machine-readable JSON on stdout.
    #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
    pub json: bool,
    /// Path to graphrag.sqlite. Overrides the XDG `db.path` setting.
    #[arg(
        long,
                help = "Path to graphrag.sqlite"
    )]
    pub db: Option<String>,
}

/// Character-level change summary between two consecutive versions.
#[derive(Serialize)]
struct VersionChanges {
    added_chars: usize,
    removed_chars: usize,
}

#[derive(Serialize)]
struct HistoryVersion {
    version: i64,
    name: String,
    #[serde(rename = "type")]
    memory_type: String,
    description: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    body: Option<String>,
    metadata: serde_json::Value,
    /// Past-tense action label derived from `change_reason`; always populated
    /// so consumers do not see `null` for the documented `action` contract
    /// (M-A6 fix in v1.0.40). Known mappings: `create→created`, `edit→edited`,
    /// `rename→renamed`, `restore→restored`, `merge→merged`, `forget→forgotten`.
    /// Unknown verbs are passed through unchanged.
    action: String,
    change_reason: String,
    changed_by: Option<String>,
    created_at: i64,
    created_at_iso: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub changes: Option<VersionChanges>,
}

/// Maps the raw `change_reason` stored in `memory_versions` to the past-tense
/// `action` exposed in the JSON contract. Centralized so future call sites
/// (e.g. `read --include-history`) reuse the same mapping.
fn change_reason_to_action(reason: &str) -> String {
    match reason {
        "create" => "created",
        "edit" => "edited",
        "update" => "updated",
        "rename" => "renamed",
        "restore" => "restored",
        "merge" => "merged",
        "forget" => "forgotten",
        other => other,
    }
    .to_string()
}

#[derive(Serialize)]
struct HistoryResponse {
    name: String,
    namespace: String,
    /// True when the memory is currently soft-deleted (forgotten).
    /// Allows the user to discover the version for `restore` even after `forget`.
    deleted: bool,
    versions: Vec<HistoryVersion>,
    /// Total execution time in milliseconds from handler start to serialisation.
    elapsed_ms: u64,
}

/// Run.
pub fn run(args: HistoryArgs) -> Result<(), AppError> {
    let start = std::time::Instant::now();
    // Resolve name from positional or --name flag; both are optional, at least one is required.
    let name = args.name_positional.or(args.name).ok_or_else(|| {
        AppError::Validation(crate::i18n::validation::name_required_positional_or_flag())
    })?;
    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
    let paths = AppPaths::resolve(args.db.as_deref())?;
    crate::storage::connection::ensure_db_ready(&paths)?;
    let conn = open_ro(&paths.db)?;

    // v1.0.22 P0: direct query WITHOUT deleted_at filter — history MUST return versions
    // of forgotten memories so the user can discover the version to use in `restore`.
    // The old find_by_name filtered deleted_at IS NULL and was a dead-end in the forget+restore workflow.
    let row: Option<(i64, Option<i64>)> = conn
        .query_row(
            "SELECT id, deleted_at FROM memories WHERE namespace = ?1 AND name = ?2",
            params![namespace, name],
            |r| Ok((r.get(0)?, r.get(1)?)),
        )
        .optional()?;
    let (memory_id, deleted_at) =
        row.ok_or_else(|| AppError::NotFound(errors_msg::memory_not_found(&name, &namespace)))?;
    let deleted = deleted_at.is_some();

    let mut stmt = conn.prepare_cached(
        "SELECT version, name, type, description, body, metadata,
                change_reason, changed_by, created_at
         FROM memory_versions
         WHERE memory_id = ?1
         ORDER BY version ASC",
    )?;

    let no_body = args.no_body;
    let want_diff = args.diff;
    let mut versions = stmt
        .query_map(params![memory_id], |r| {
            let created_at: i64 = r.get(8)?;
            let created_at_iso = crate::tz::epoch_to_iso(created_at);
            let body_str: String = r.get(4)?;
            let metadata_str: String = r.get(5)?;
            let metadata_value: serde_json::Value = serde_json::from_str(&metadata_str)
                .unwrap_or(serde_json::Value::Object(serde_json::Map::new()));
            let change_reason: String = r.get(6)?;
            let action = change_reason_to_action(&change_reason);
            Ok(HistoryVersion {
                version: r.get(0)?,
                name: r.get(1)?,
                memory_type: r.get(2)?,
                description: r.get(3)?,
                body: if no_body { None } else { Some(body_str) },
                metadata: metadata_value,
                action,
                change_reason,
                changed_by: r.get(7)?,
                created_at,
                created_at_iso,
                changes: None,
            })
        })?
        .collect::<Result<Vec<_>, _>>()?;

    if want_diff && !versions.is_empty() {
        let body_lens: Vec<usize> = versions
            .iter()
            .map(|v| v.body.as_deref().map_or(0, str::len))
            .collect();

        versions[0].changes = Some(VersionChanges {
            added_chars: body_lens[0],
            removed_chars: 0,
        });

        for i in 1..versions.len() {
            let old_len = body_lens[i - 1];
            let new_len = body_lens[i];
            versions[i].changes = Some(VersionChanges {
                added_chars: new_len.saturating_sub(old_len),
                removed_chars: old_len.saturating_sub(new_len),
            });
        }
    }

    output::emit_json(&HistoryResponse {
        name,
        namespace,
        deleted,
        versions,
        elapsed_ms: start.elapsed().as_millis() as u64,
    })?;

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::{change_reason_to_action, VersionChanges};

    // Bug M-A6: action is always populated and maps known reasons to past tense.
    #[test]
    fn version_changes_serializes_correctly() {
        let changes = VersionChanges {
            added_chars: 10,
            removed_chars: 3,
        };
        let json = serde_json::to_value(&changes).expect("serialization failed");
        assert_eq!(json["added_chars"], 10u64);
        assert_eq!(json["removed_chars"], 3u64);
    }

    #[test]
    fn added_chars_saturating_sub_no_underflow() {
        // new body shorter than old — added_chars must be 0, not wrapping
        let old_len: usize = 100;
        let new_len: usize = 40;
        let added = new_len.saturating_sub(old_len);
        let removed = old_len.saturating_sub(new_len);
        assert_eq!(added, 0);
        assert_eq!(removed, 60);
    }

    #[test]
    fn removed_chars_saturating_sub_no_underflow() {
        // new body longer than old — removed_chars must be 0
        let old_len: usize = 20;
        let new_len: usize = 80;
        let added = new_len.saturating_sub(old_len);
        let removed = old_len.saturating_sub(new_len);
        assert_eq!(added, 60);
        assert_eq!(removed, 0);
    }

    #[test]
    fn change_reason_create_maps_to_created() {
        assert_eq!(change_reason_to_action("create"), "created");
    }

    #[test]
    fn change_reason_edit_maps_to_edited() {
        assert_eq!(change_reason_to_action("edit"), "edited");
    }

    #[test]
    fn change_reason_rename_maps_to_renamed() {
        assert_eq!(change_reason_to_action("rename"), "renamed");
    }

    #[test]
    fn change_reason_restore_maps_to_restored() {
        assert_eq!(change_reason_to_action("restore"), "restored");
    }

    #[test]
    fn change_reason_merge_maps_to_merged() {
        assert_eq!(change_reason_to_action("merge"), "merged");
    }

    #[test]
    fn change_reason_forget_maps_to_forgotten() {
        assert_eq!(change_reason_to_action("forget"), "forgotten");
    }

    #[test]
    fn change_reason_unknown_passes_through() {
        assert_eq!(change_reason_to_action("custom-action"), "custom-action");
    }

    #[test]
    fn epoch_zero_yields_valid_iso() {
        // v1.0.68 (test fix): timezone-agnostic — parse the ISO and compare
        // the instant with the Unix epoch.  The previous starts_with check
        // leaked the SQLITE_GRAPHRAG_DISPLAY_TZ env var from sibling tests
        // and failed on hosts whose default display timezone is not UTC.
        let iso = crate::tz::epoch_to_iso(0);
        let parsed = chrono::DateTime::parse_from_rfc3339(&iso)
            .unwrap_or_else(|e| panic!("expected RFC3339, got `{iso}`: {e}"));
        assert_eq!(
            parsed.timestamp(),
            chrono::DateTime::UNIX_EPOCH.timestamp(),
            "epoch 0 must map to the Unix epoch instant, got: {iso}"
        );
    }

    #[test]
    fn typical_epoch_yields_iso_rfc3339() {
        let iso = crate::tz::epoch_to_iso(1_745_000_000);
        assert!(!iso.is_empty(), "created_at_iso must not be empty");
        assert!(iso.contains('T'), "created_at_iso must contain T separator");
        // With UTC the offset is +00:00; verifies general format without relying on the global tz
        assert!(
            iso.contains('+') || iso.contains('-'),
            "must contain offset sign, got: {iso}"
        );
    }

    #[test]
    fn invalid_epoch_returns_fallback() {
        let iso = crate::tz::epoch_to_iso(i64::MIN);
        assert!(
            !iso.is_empty(),
            "invalid epoch must return non-empty fallback"
        );
    }
}