feat: add new unified model structure

- Create src/models directory with unified terminology
- Add new models: Chunk, Challenge, Stage, Session, Total
- Rename RankingTier -> Rank for consistency
- Rename GitRepositoryInfo -> GitRepository
- Establish XXXResult pattern for consistency
- Maintain backward compatibility during transition

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: unhappychoice

src/lib.rs

@@ -2,6 +2,7 @@ pub mod cli;
 pub mod error;
 pub mod extractor;
 pub mod game;
+pub mod models;
 pub mod repo_manager;
 pub mod scoring;
 pub mod sharing;

src/models/challenge.rs

@@ -0,0 +1,117 @@
+use super::git_repository::GitRepository;
+use crate::game::stage_builder::DifficultyLevel;
+
+#[derive(Debug, Clone)]
+pub struct Challenge {
+    pub id: String,
+    pub source_file_path: Option<String>,
+    pub code_content: String,
+    pub start_line: Option<usize>,
+    pub end_line: Option<usize>,
+    pub language: Option<String>,
+    pub comment_ranges: Vec<(usize, usize)>, // Character-based ranges for comments
+    pub difficulty_level: Option<DifficultyLevel>,
+}
+
+impl Challenge {
+    pub fn new(id: String, code_content: String) -> Self {
+        Self {
+            id,
+            source_file_path: None,
+            code_content,
+            start_line: None,
+            end_line: None,
+            language: None,
+            comment_ranges: Vec::new(),
+            difficulty_level: None,
+        }
+    }
+
+    pub fn with_source_info(
+        mut self,
+        file_path: String,
+        start_line: usize,
+        end_line: usize,
+    ) -> Self {
+        self.source_file_path = Some(file_path);
+        self.start_line = Some(start_line);
+        self.end_line = Some(end_line);
+        self
+    }
+
+    pub fn with_language(mut self, language: String) -> Self {
+        self.language = Some(language);
+        self
+    }
+
+    pub fn with_comment_ranges(mut self, comment_ranges: Vec<(usize, usize)>) -> Self {
+        self.comment_ranges = comment_ranges;
+        self
+    }
+
+    pub fn with_difficulty_level(mut self, difficulty_level: DifficultyLevel) -> Self {
+        self.difficulty_level = Some(difficulty_level);
+        self
+    }
+
+    pub fn get_display_title(&self) -> String {
+        if let Some(ref path) = self.source_file_path {
+            // Convert absolute path to relative path for cleaner display
+            let relative_path = self.get_relative_path(path);
+            if let (Some(start), Some(end)) = (self.start_line, self.end_line) {
+                format!("{}:{}-{}", relative_path, start, end)
+            } else {
+                relative_path
+            }
+        } else {
+            format!("Challenge {}", self.id)
+        }
+    }
+
+    pub fn get_display_title_with_repo(&self, repo_info: &Option<GitRepository>) -> String {
+        if let Some(ref path) = self.source_file_path {
+            let relative_path = self.get_relative_path(path);
+            let file_info = if let (Some(start), Some(end)) = (self.start_line, self.end_line) {
+                format!("{}:{}-{}", relative_path, start, end)
+            } else {
+                relative_path
+            };
+
+            if let Some(repo) = repo_info {
+                format!(
+                    "[{}/{}] {}",
+                    repo.user_name, repo.repository_name, file_info
+                )
+            } else {
+                file_info
+            }
+        } else {
+            format!("Challenge {}", self.id)
+        }
+    }
+
+    fn get_relative_path(&self, path: &str) -> String {
+        use std::path::Path;
+
+        // Try to extract just the filename if it's a full path
+        if let Some(file_name) = Path::new(path).file_name() {
+            if let Some(parent) = Path::new(path).parent() {
+                if let Some(parent_name) = parent.file_name() {
+                    // Show parent_dir/filename for better context
+                    format!(
+                        "{}/{}",
+                        parent_name.to_string_lossy(),
+                        file_name.to_string_lossy()
+                    )
+                } else {
+                    file_name.to_string_lossy().to_string()
+                }
+            } else {
+                file_name.to_string_lossy().to_string()
+            }
+        } else {
+            // Fallback to original path if extraction fails
+            path.to_string()
+        }
+    }
+}

src/models/chunk.rs

@@ -0,0 +1,31 @@
+use std::path::PathBuf;
+
+#[derive(Debug, Clone)]
+pub enum ChunkType {
+    Function,
+    Class,
+    Method,
+    Struct,
+    Enum,
+    Trait,
+    TypeAlias,
+    Interface,
+    Module,
+    Const,
+    Variable,
+    Component, // JSX/TSX React components
+    Namespace, // For C# namespaces
+}
+
+#[derive(Debug, Clone)]
+pub struct CodeChunk {
+    pub content: String,
+    pub file_path: PathBuf,
+    pub start_line: usize,
+    pub end_line: usize,
+    pub language: String,
+    pub chunk_type: ChunkType,
+    pub name: String,
+    pub comment_ranges: Vec<(usize, usize)>, // Character-based ranges for comments relative to content
+    pub original_indentation: usize,         // Column position of the first character in source
+}

src/models/git_repository.rs

@@ -0,0 +1,11 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct GitRepository {
+    pub user_name: String,
+    pub repository_name: String,
+    pub remote_url: String,
+    pub branch: Option<String>,
+    pub commit_hash: Option<String>,
+    pub is_dirty: bool,
+}

src/models/mod.rs

@@ -0,0 +1,16 @@
+pub mod chunk;
+pub mod challenge;
+pub mod stage;
+pub mod session;
+pub mod total;
+pub mod rank;
+pub mod git_repository;
+
+// Re-export main types for easy access
+pub use chunk::{ChunkType, CodeChunk};
+pub use challenge::Challenge;
+pub use stage::{Stage, StageResult};
+pub use session::{Session, SessionResult};
+pub use total::{Total, TotalResult};
+pub use rank::{Rank, RankingTitle};
+pub use git_repository::GitRepository;

src/models/rank.rs

@@ -0,0 +1,168 @@
+/// Represents a ranking title with associated metadata
+#[derive(Debug, Clone, PartialEq)]
+pub struct RankingTitle {
+    pub name: String,
+    pub tier: Rank,
+    pub min_score: u32,
+    pub max_score: u32,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum Rank {
+    Beginner,
+    Intermediate,
+    Advanced,
+    Expert,
+    Legendary,
+}
+
+impl Rank {
+    /// Get the color palette name for ASCII art generation
+    pub fn color_palette(&self) -> &'static str {
+        match self {
+            Rank::Beginner => "grad-blue",
+            Rank::Intermediate => "dawn",
+            Rank::Advanced => "forest",
+            Rank::Expert => "gold",
+            Rank::Legendary => "fire",
+        }
+    }
+
+    /// Get the terminal color for this tier
+    pub fn terminal_color(&self) -> crossterm::style::Color {
+        use crossterm::style::Color;
+        match self {
+            Rank::Beginner => Color::Cyan,
+            Rank::Intermediate => Color::Blue,
+            Rank::Advanced => Color::Green,
+            Rank::Expert => Color::Yellow,
+            Rank::Legendary => Color::Red,
+        }
+    }
+}
+
+impl RankingTitle {
+    /// Create a new ranking title
+    pub fn new(name: impl Into<String>, tier: Rank, min_score: u32, max_score: u32) -> Self {
+        Self {
+            name: name.into(),
+            tier,
+            min_score,
+            max_score,
+        }
+    }
+
+    /// Get the display name of the ranking title
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// Get the tier of the ranking title
+    #[allow(dead_code)]
+    pub fn tier(&self) -> &Rank {
+        &self.tier
+    }
+
+    /// Check if a score falls within this ranking title's range
+    #[allow(dead_code)]
+    pub fn contains_score(&self, score: f64) -> bool {
+        let score = score as u32;
+        score >= self.min_score && score <= self.max_score
+    }
+
+    /// Get the color palette name for ASCII art generation
+    pub fn color_palette(&self) -> &'static str {
+        self.tier.color_palette()
+    }
+
+    /// Get the terminal color for this ranking title
+    pub fn terminal_color(&self) -> crossterm::style::Color {
+        self.tier.terminal_color()
+    }
+
+    /// Get all ranking titles in order from lowest to highest score
+    pub fn all_titles() -> Vec<RankingTitle> {
+        vec![
+            // Beginner Level (clean boundaries, ~even progression)
+            RankingTitle::new("Hello World", Rank::Beginner, 0, 800),
+            RankingTitle::new("Syntax Error", Rank::Beginner, 801, 1200),
+            RankingTitle::new("Rubber Duck", Rank::Beginner, 1201, 1600),
+            RankingTitle::new("Script Kid", Rank::Beginner, 1601, 2000),
+            RankingTitle::new("Bash Newbie", Rank::Beginner, 2001, 2450),
+            RankingTitle::new("CLI Wanderer", Rank::Beginner, 2451, 2900),
+            RankingTitle::new("Tab Tamer", Rank::Beginner, 2901, 3300),
+            RankingTitle::new("Bracket Juggler", Rank::Beginner, 3301, 3700),
+            RankingTitle::new("Copy-Paste Engineer", Rank::Beginner, 3701, 4150),
+            RankingTitle::new("Linter Apprentice", Rank::Beginner, 4151, 4550),
+            RankingTitle::new("Unit Test Trainee", Rank::Beginner, 4551, 5000),
+            RankingTitle::new("Code Monkey", Rank::Beginner, 5001, 5600),
+            // Intermediate Level
+            RankingTitle::new("Ticket Picker", Rank::Intermediate, 5601, 5850),
+            RankingTitle::new("Junior Dev", Rank::Intermediate, 5851, 6000),
+            RankingTitle::new("Git Ninja", Rank::Intermediate, 6001, 6100),
+            RankingTitle::new("Merge Wrangler", Rank::Intermediate, 6101, 6250),
+            RankingTitle::new("API Crafter", Rank::Intermediate, 6251, 6400),
+            RankingTitle::new("Frontend Dev", Rank::Intermediate, 6401, 6550),
+            RankingTitle::new("Backend Dev", Rank::Intermediate, 6551, 6700),
+            RankingTitle::new("CI Tinkerer", Rank::Intermediate, 6701, 6850),
+            RankingTitle::new("Test Pilot", Rank::Intermediate, 6851, 7000),
+            RankingTitle::new("Build Tamer", Rank::Intermediate, 7001, 7100),
+            RankingTitle::new("Code Reviewer", Rank::Intermediate, 7101, 7250),
+            RankingTitle::new("Release Handler", Rank::Intermediate, 7251, 7500),
+            // Advanced Level
+            RankingTitle::new("Refactorer", Rank::Advanced, 7501, 7800),
+            RankingTitle::new("Senior Dev", Rank::Advanced, 7801, 8000),
+            RankingTitle::new("DevOps Engineer", Rank::Advanced, 8001, 8100),
+            RankingTitle::new("Incident Responder", Rank::Advanced, 8101, 8250),
+            RankingTitle::new("Reliability Guardian", Rank::Advanced, 8251, 8400),
+            RankingTitle::new("Security Engineer", Rank::Advanced, 8401, 8500),
+            RankingTitle::new("Performance Alchemist", Rank::Advanced, 8501, 8650),
+            RankingTitle::new("Data Pipeline Master", Rank::Advanced, 8651, 8800),
+            RankingTitle::new("Tech Lead", Rank::Advanced, 8801, 8950),
+            RankingTitle::new("Architect", Rank::Advanced, 8951, 9100),
+            RankingTitle::new("Protocol Artisan", Rank::Advanced, 9101, 9250),
+            RankingTitle::new("Kernel Hacker", Rank::Advanced, 9251, 9500),
+            // Expert Level
+            RankingTitle::new("Compiler", Rank::Expert, 9501, 9800),
+            RankingTitle::new("Bytecode Interpreter", Rank::Expert, 9801, 9950),
+            RankingTitle::new("Virtual Machine", Rank::Expert, 9951, 10100),
+            RankingTitle::new("Operating System", Rank::Expert, 10101, 10200),
+            RankingTitle::new("Filesystem", Rank::Expert, 10201, 10350),
+            RankingTitle::new("Network Stack", Rank::Expert, 10351, 10500),
+            RankingTitle::new("Database Engine", Rank::Expert, 10501, 10650),
+            RankingTitle::new("Query Optimizer", Rank::Expert, 10651, 10800),
+            RankingTitle::new("Cloud Platform", Rank::Expert, 10801, 10950),
+            RankingTitle::new("Container Orchestrator", Rank::Expert, 10951, 11100),
+            RankingTitle::new("Stream Processor", Rank::Expert, 11101, 11200),
+            RankingTitle::new("Quantum Computer", Rank::Expert, 11201, 11400),
+            // Legendary Level
+            RankingTitle::new("GPU Cluster", Rank::Legendary, 11401, 11700),
+            RankingTitle::new("DNS Overlord", Rank::Legendary, 11701, 12250),
+            RankingTitle::new("CDN Sentinel", Rank::Legendary, 12251, 12800),
+            RankingTitle::new("Load Balancer Primarch", Rank::Legendary, 12801, 13400),
+            RankingTitle::new("Singularity", Rank::Legendary, 13401, 13950),
+            RankingTitle::new("The Machine", Rank::Legendary, 13951, 14500),
+            RankingTitle::new("Origin", Rank::Legendary, 14501, 15100),
+            RankingTitle::new("SegFault", Rank::Legendary, 15101, 15650),
+            RankingTitle::new("Buffer Overflow", Rank::Legendary, 15651, 16200),
+            RankingTitle::new("Memory Leak", Rank::Legendary, 16201, 16800),
+            RankingTitle::new("Null Pointer Exception", Rank::Legendary, 16801, 17350),
+            RankingTitle::new("Undefined Behavior", Rank::Legendary, 17351, 17900),
+            RankingTitle::new("Heisenbug", Rank::Legendary, 17901, 18500),
+            RankingTitle::new("Blue Screen", Rank::Legendary, 18501, 19100),
+            RankingTitle::new("Kernel Panic", Rank::Legendary, 19101, u32::MAX),
+        ]
+    }
+
+    /// Find the ranking title for a given score
+    #[allow(dead_code)]
+    pub fn for_score(score: f64) -> RankingTitle {
+        Self::all_titles()
+            .into_iter()
+            .find(|title| title.contains_score(score))
+            .unwrap_or_else(|| {
+                // Fallback to highest title if score exceeds all ranges
+                RankingTitle::new("Kernel Panic", Rank::Legendary, 40001, u32::MAX)
+            })
+    }
+}