huskies/server/src/crdt_state/write/migrations.rs

//! Name and story-ID migration helpers for pipeline items.
//!
//! Contains one-time startup migrations that backfill the `name` field from
//! story ID slugs and rewrite slug-form story IDs to numeric-only form.

use bft_json_crdt::json_crdt::{CrdtNode, JsonValue};

use super::super::state::{apply_and_persist, get_crdt, rebuild_index};
use crate::slog;

/// Derive a human-readable name from a story ID's slug component.
///
/// Strips the numeric prefix and item-type prefix (story/bug/spike/refactor),
/// replaces underscores with spaces, and capitalises the first letter.
///
/// Examples:
/// - `"729_story_store_story_name"` → `"Store story name"`
/// - `"4_bug_login_crash"` → `"Login crash"`
/// - `"10_spike_arch_review"` → `"Arch review"`
pub fn name_from_story_id(story_id: &str) -> String {
    // Strip the leading digits then the first underscore: "729_story_..." → "story_..."
    let after_num = story_id.trim_start_matches(|c: char| c.is_ascii_digit());
    let after_num = after_num.strip_prefix('_').unwrap_or(after_num);

    // Strip the item-type prefix.
    let slug = after_num
        .strip_prefix("story_")
        .or_else(|| after_num.strip_prefix("bug_"))
        .or_else(|| after_num.strip_prefix("spike_"))
        .or_else(|| after_num.strip_prefix("refactor_"))
        .unwrap_or(after_num);

    // Replace underscores with spaces.
    let spaced = slug.replace('_', " ");

    // Capitalise the first character.
    let mut chars = spaced.chars();
    match chars.next() {
        None => String::new(),
        Some(first) => {
            let mut name = first.to_uppercase().to_string();
            name.push_str(chars.as_str());
            name
        }
    }
}

/// Extract the numeric-only ID from a slug-form story ID, if applicable.
///
/// Returns `Some("664")` for `"664_story_my_feature"`, and `None` for IDs
/// that are already numeric-only (`"664"`) or have no valid numeric prefix.
#[allow(clippy::string_slice)] // idx comes from find('_') → always a char boundary
pub(super) fn numeric_id_from_slug(story_id: &str) -> Option<String> {
    // Already numeric-only — no migration needed.
    if story_id.chars().all(|c: char| c.is_ascii_digit()) {
        return None;
    }
    // Must have a non-empty numeric segment before the first underscore.
    let idx = story_id.find('_')?;
    let prefix = &story_id[..idx];
    if prefix.is_empty() || !prefix.chars().all(|c| c.is_ascii_digit()) {
        return None;
    }
    Some(prefix.to_string())
}

/// Migrate existing story IDs from slug form (`664_story_my_feature`) to
/// numeric-only form (`664`) in the in-memory CRDT, persisting a signed op
/// for each updated register so the change survives restarts.
///
/// Returns the list of `(old_id, new_id)` pairs that were actually migrated.
/// Callers should use this list to rename downstream filesystem artifacts
/// (worktree directories, git branches, log directories).
///
/// Items whose `story_id` is already numeric-only are left untouched.
/// Items where the target numeric ID is already in use are skipped to avoid
/// conflicts.  Running this migration repeatedly is safe — subsequent calls
/// on already-migrated state are no-ops.
pub fn migrate_story_ids_to_numeric() -> Vec<(String, String)> {
    let Some(state_mutex) = get_crdt() else {
        return Vec::new();
    };

    // First pass: collect (index, old_id, new_id) while holding the lock.
    let migrations: Vec<(usize, String, String)> = {
        let Ok(state) = state_mutex.lock() else {
            return Vec::new();
        };

        let existing_ids: std::collections::HashSet<String> = state.index.keys().cloned().collect();

        state
            .index
            .iter()
            .filter_map(|(story_id, &idx)| {
                let numeric = numeric_id_from_slug(story_id)?;
                // Skip if the target numeric ID is already occupied.
                if existing_ids.contains(&numeric) {
                    return None;
                }
                Some((idx, story_id.clone(), numeric))
            })
            .collect()
    };

    if migrations.is_empty() {
        return Vec::new();
    }

    // Second pass: apply story_id register updates.
    let Ok(mut state) = state_mutex.lock() else {
        return Vec::new();
    };

    let mut result = Vec::new();
    for (idx, old_id, new_id) in migrations {
        apply_and_persist(&mut state, |s| {
            s.crdt.doc.items[idx].story_id.set(new_id.clone())
        });
        result.push((old_id, new_id));
    }

    // Rebuild the index so all downstream reads use the new numeric IDs.
    state.index = rebuild_index(&state.crdt);

    let count = result.len();
    slog!("[crdt] Migrated {count} story IDs from slug form to numeric");
    result
}

/// Backfill the `name` CRDT field for pipeline items that have an empty name.
///
/// Iterates over all items in the in-memory CRDT.  For each item whose `name`
/// register is empty, derives a human-readable name from the story ID slug
/// (see [`name_from_story_id`]) and writes it via a signed CRDT op.
///
/// This is a one-time startup migration: items created before the `name` field
/// was consistently populated will gain a name on the next server start.
/// Items that already have a non-empty name are left untouched.
pub fn migrate_names_from_slugs() {
    let Some(state_mutex) = get_crdt() else {
        return;
    };

    // First pass: collect (index, derived_name) pairs for items missing a name.
    let migrations: Vec<(usize, String)> = {
        let Ok(state) = state_mutex.lock() else {
            return;
        };
        state
            .index
            .iter()
            .filter_map(|(story_id, &idx)| {
                let item = &state.crdt.doc.items[idx];
                // Skip items that already have a name.
                let already_named =
                    matches!(item.name.view(), JsonValue::String(ref s) if !s.is_empty());
                if already_named {
                    return None;
                }
                let name = name_from_story_id(story_id);
                if name.is_empty() {
                    return None;
                }
                Some((idx, name))
            })
            .collect()
    };

    if migrations.is_empty() {
        return;
    }

    // Second pass: apply all name writes while holding the lock.
    let Ok(mut state) = state_mutex.lock() else {
        return;
    };
    let count = migrations.len();
    for (idx, name) in migrations {
        apply_and_persist(&mut state, |s| s.crdt.doc.items[idx].name.set(name.clone()));
    }
    slog!("[crdt] Migrated names for {count} items from story ID slugs");
}

/// Map a pre-934 legacy directory-style stage string to its clean wire form.
///
/// Returns `None` if `s` is already in clean wire form (or is genuinely
/// unknown), so the migration can quickly skip already-clean items.
fn legacy_stage_to_clean(s: &str) -> Option<&'static str> {
    match s {
        "0_upcoming" => Some("upcoming"),
        "1_backlog" => Some("backlog"),
        "2_current" => Some("coding"),
        "2_blocked" => Some("blocked"),
        "3_qa" => Some("qa"),
        "4_merge" => Some("merge"),
        "4_merge_failure" => Some("merge_failure"),
        "5_done" => Some("done"),
        "6_archived" => Some("archived"),
        // Story 934, stage 4: `Stage::Frozen` no longer exists.  Items that
        // were previously frozen become orthogonal-flag-frozen: their stage
        // register collapses to `backlog` (a safe "not progressing" default
        // since the original resume_to payload was lost when the variant was
        // dropped) and a separate write sets `frozen = true`.
        "7_frozen" => Some("backlog"),
        _ => None,
    }
}

/// Rewrite every pipeline item whose `stage` register still carries a pre-934
/// directory-style string (`"2_current"`, `"4_merge"`, etc.) to the clean wire
/// vocabulary (`"coding"`, `"merge"`, etc.).
///
/// Items that were at `"7_frozen"` additionally get the new `frozen` flag set
/// Story 945: the `Frozen` variant returns as `Stage::Frozen { resume_to }`,
/// replacing the orthogonal CRDT register that briefly existed in 934 stage 4.
///
/// One-time startup migration: items that have transitioned at least once
/// since story 934 stage 1 (which made writes emit clean form) are no-ops.
pub fn migrate_legacy_stage_strings() {
    let Some(state_mutex) = get_crdt() else {
        return;
    };

    // First pass: collect (index, clean_stage, was_frozen) for items that
    // still carry legacy stage strings.  `was_frozen` triggers writing
    // `resume_to = "backlog"` so the post-945 typed projection reads back as
    // `Stage::Frozen { resume_to: Stage::Backlog }`.
    let migrations: Vec<(usize, &'static str, bool)> = {
        let Ok(state) = state_mutex.lock() else {
            return;
        };
        state
            .index
            .iter()
            .filter_map(|(_story_id, &idx)| {
                let item = &state.crdt.doc.items[idx];
                let current = match item.stage.view() {
                    JsonValue::String(s) => s,
                    _ => return None,
                };
                let clean = legacy_stage_to_clean(&current)?;
                let was_frozen = current == "7_frozen";
                // For legacy frozen items, store the post-945 stage as
                // "frozen" rather than "backlog" so the typed projection
                // produces `Stage::Frozen` again.
                let stage_out = if was_frozen { "frozen" } else { clean };
                Some((idx, stage_out, was_frozen))
            })
            .collect()
    };

    if migrations.is_empty() {
        return;
    }

    let Ok(mut state) = state_mutex.lock() else {
        return;
    };
    let count = migrations.len();
    let frozen_count = migrations.iter().filter(|(_, _, f)| *f).count();
    for (idx, clean, was_frozen) in migrations {
        apply_and_persist(&mut state, |s| {
            s.crdt.doc.items[idx].stage.set(clean.to_string())
        });
        if was_frozen {
            apply_and_persist(&mut state, |s| {
                s.crdt.doc.items[idx].resume_to.set("backlog".to_string())
            });
        }
    }
    slog!(
        "[crdt] Migrated {count} legacy stage strings to clean wire form \
         ({frozen_count} of which were '7_frozen' → frozen + resume_to=backlog)"
    );
}

#[cfg(test)]
mod stage_migration_tests {
    use super::super::super::state::init_for_test;
    use super::super::item::write_item;
    use super::*;
    use crate::crdt_state::read_item;
    use crate::pipeline_state::{BranchName, Stage};
    use std::num::NonZeroU32;

    /// Seed a pipeline item with a raw, possibly-legacy stage register value,
    /// bypassing the boundary normalisers that production write APIs apply.
    /// Inserts via the typed API first so the item is indexed, then directly
    /// rewrites the `stage` register to the legacy string.
    fn seed_with_raw_stage(story_id: &str, raw_stage: &str) {
        // Insert via the typed API so the item exists in state.index.
        write_item(
            story_id,
            &Stage::Backlog,
            Some("Migration Test"),
            None,
            None,
            None,
            None,
            None,
            None,
        );
        // Then overwrite the stage register with the raw legacy string,
        // bypassing `db::normalise_stage_str` / `write_item_str`'s mapping.
        let state_mutex = get_crdt().expect("CRDT initialised in test");
        let mut state = state_mutex.lock().unwrap();
        let idx = *state.index.get(story_id).expect("item indexed");
        let raw = raw_stage.to_string();
        apply_and_persist(&mut state, |s| s.crdt.doc.items[idx].stage.set(raw.clone()));
    }

    #[test]
    fn migrate_rewrites_legacy_directory_strings_to_clean_wire() {
        init_for_test();
        // High-numbered IDs to avoid colliding with other tests' globals.
        let cases: &[(&str, &str, Stage)] = &[
            ("9501_legacy_upcoming", "0_upcoming", Stage::Upcoming),
            ("9502_legacy_backlog", "1_backlog", Stage::Backlog),
            ("9503_legacy_coding", "2_current", Stage::Coding),
            (
                "9504_legacy_blocked",
                "2_blocked",
                Stage::Blocked {
                    reason: String::new(),
                },
            ),
            ("9505_legacy_qa", "3_qa", Stage::Qa),
            (
                "9506_legacy_merge",
                "4_merge",
                Stage::Merge {
                    feature_branch: BranchName(String::new()),
                    commits_ahead: NonZeroU32::new(1).unwrap(),
                },
            ),
            (
                "9507_legacy_merge_failure",
                "4_merge_failure",
                Stage::MergeFailure {
                    reason: String::new(),
                },
            ),
        ];
        for (id, raw, _) in cases {
            seed_with_raw_stage(id, raw);
        }

        migrate_legacy_stage_strings();

        for (id, _, expected_variant) in cases {
            let view = read_item(id).expect("item must still exist after migration");
            let projected: &Stage = view.stage();
            assert_eq!(
                std::mem::discriminant(projected),
                std::mem::discriminant(expected_variant),
                "stage for {id} should project to {expected_variant:?} after migration, got {projected:?}",
            );
        }
    }

    #[test]
    fn migrate_promotes_7_frozen_to_typed_frozen_variant() {
        init_for_test();
        let story_id = "9510_legacy_frozen";
        seed_with_raw_stage(story_id, "7_frozen");

        // Sanity: before migration, the projection's legacy fallback maps
        // raw `"7_frozen"` → `Stage::Backlog` (frozen state is lost without the
        // migration's resume_to write).
        let before = read_item(story_id).expect("legacy 7_frozen should still project");
        assert!(
            matches!(before.stage(), crate::pipeline_state::Stage::Backlog),
            "raw 7_frozen should fall back to Backlog before migration; got {:?}",
            before.stage()
        );

        migrate_legacy_stage_strings();

        let after = read_item(story_id).expect("item must still exist after migration");
        match after.stage() {
            crate::pipeline_state::Stage::Frozen { resume_to } => {
                assert!(
                    matches!(**resume_to, crate::pipeline_state::Stage::Backlog),
                    "resume_to should default to Backlog for migrated 7_frozen items"
                );
            }
            other => panic!("7_frozen should migrate to Stage::Frozen; got {other:?}"),
        }
    }

    #[test]
    fn migrate_leaves_clean_wire_items_untouched() {
        init_for_test();
        // Seed two items: one already in clean form, one in legacy form.
        write_item(
            "9520_already_clean",
            &Stage::Coding,
            Some("Already Clean"),
            None,
            None,
            None,
            None,
            None,
            None,
        );
        seed_with_raw_stage("9521_needs_migration", "2_current");

        migrate_legacy_stage_strings();

        // Clean item is unchanged; legacy item is now clean too.
        let clean = read_item("9520_already_clean").unwrap();
        let migrated = read_item("9521_needs_migration").unwrap();
        assert!(matches!(
            clean.stage(),
            crate::pipeline_state::Stage::Coding
        ));
        assert!(matches!(
            migrated.stage(),
            crate::pipeline_state::Stage::Coding
        ));
    }

    #[test]
    fn migrate_is_idempotent() {
        init_for_test();
        seed_with_raw_stage("9530_idempotent", "4_merge");

        migrate_legacy_stage_strings();
        let after_first = read_item("9530_idempotent").unwrap();
        assert!(matches!(
            after_first.stage(),
            crate::pipeline_state::Stage::Merge { .. }
        ));

        // Second call must be a no-op — the filter pass returns empty.
        migrate_legacy_stage_strings();
        let after_second = read_item("9530_idempotent").unwrap();
        assert!(matches!(
            after_second.stage(),
            crate::pipeline_state::Stage::Merge { .. }
        ));
    }

    #[test]
    fn migrate_is_noop_when_crdt_not_initialised() {
        // Calling before init_for_test should not panic.
        migrate_legacy_stage_strings();
    }
}