//! Pure front-matter helpers for `service::story`.
//!
//! These functions validate and inspect story front-matter field values
//! without performing any I/O. Parsing is delegated to `crate::io::story_metadata`.

#[allow(dead_code)]
/// Return `true` if `stage` is a recognised pipeline stage name.
///
/// Accepts both the clean post-934 wire form (e.g. `"backlog"`) and the
/// legacy directory-style form (e.g. `"1_backlog"`).
pub fn is_valid_stage(stage: &str) -> bool {
    crate::pipeline_state::Stage::from_dir(stage).is_some()
}

#[allow(dead_code)]
/// Map any recognised stage alias (clean wire form or legacy directory form)
/// to the canonical clean wire form. Returns `None` for unrecognised aliases.
pub fn stage_alias_to_dir(alias: &str) -> Option<&'static str> {
    crate::pipeline_state::Stage::from_dir(alias).map(|s| s.dir_name())
}

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn is_valid_stage_accepts_all_known_stages() {
        // Clean post-934 vocabulary.
        assert!(is_valid_stage("backlog"));
        assert!(is_valid_stage("coding"));
        assert!(is_valid_stage("qa"));
        assert!(is_valid_stage("merge"));
        assert!(is_valid_stage("done"));
        assert!(is_valid_stage("archived"));
    }

    #[test]
    fn is_valid_stage_rejects_unknown() {
        // Story 934 stage 6 dropped legacy directory-style aliases.
        assert!(!is_valid_stage("current")); // pre-934 short alias, no longer mapped
        assert!(!is_valid_stage("1_backlog"));
        assert!(!is_valid_stage("2_current"));
        assert!(!is_valid_stage("7_future"));
        assert!(!is_valid_stage(""));
    }

    #[test]
    fn stage_alias_maps_short_names() {
        assert_eq!(stage_alias_to_dir("backlog"), Some("backlog"));
        assert_eq!(stage_alias_to_dir("coding"), Some("coding"));
        assert_eq!(stage_alias_to_dir("qa"), Some("qa"));
        assert_eq!(stage_alias_to_dir("merge"), Some("merge"));
        assert_eq!(stage_alias_to_dir("done"), Some("done"));
        assert_eq!(stage_alias_to_dir("archived"), Some("archived"));
    }

    #[test]
    fn stage_alias_returns_none_for_legacy_dir_names() {
        // Story 934 stage 6: legacy directory-style aliases are no longer
        // recognised — startup migration rewrites stored CRDT values, and
        // user-facing aliases now use only the clean wire vocabulary.
        assert_eq!(stage_alias_to_dir("1_backlog"), None);
        assert_eq!(stage_alias_to_dir("6_archived"), None);
    }

    #[test]
    fn stage_alias_returns_none_for_unknown() {
        assert_eq!(stage_alias_to_dir("unknown"), None);
        assert_eq!(stage_alias_to_dir(""), None);
    }
}
