Skip to main content

os/grading/
mod.rs

1//! AhRightOS Grading Framework
2//!
3//! Unified grading system for all chapters. Each chapter module provides
4//! a Grader struct implementing the Grade trait. Graders test task points
5//! and produce standardised reports.
6//!
7//! Output format:
8//! ```text
9//! ========================================
10//!    Chapter N <name> - Grading Report
11//! ========================================
12//! [PASS] Task 1: <description> (N points)
13//!     + <detail>
14//! [FAIL] Task 2: <description> (N points)
15//!     x <error detail>
16//! ...
17//! ========================================
18//! Completed: X/Y tasks
19//! Score: P/100
20//! ========================================
21//! ```
22
23use alloc::string::String;
24use alloc::vec::Vec;
25
26// ── Grading result types ──────────────────────────────────────────
27
28#[derive(Clone)]
29pub enum GradeStatus {
30    Pass,
31    Fail,
32}
33
34#[derive(Clone)]
35pub struct GradeDetail {
36    pub status: GradeStatus,
37    pub prefix: &'static str, // "+" for pass, "x" for fail
38    pub message: String,
39}
40
41#[derive(Clone)]
42pub struct TaskResult {
43    pub task_id: usize,
44    pub name: &'static str,
45    pub points: u32,
46    pub details: Vec<GradeDetail>,
47}
48
49impl TaskResult {
50    pub fn passed(&self) -> bool {
51        self.details
52            .iter()
53            .all(|d| matches!(d.status, GradeStatus::Pass))
54    }
55
56    pub fn score(&self) -> u32 {
57        if self.passed() {
58            self.points
59        } else {
60            0
61        }
62    }
63}
64
65// ── Trait & runner ────────────────────────────────────────────────
66
67/// Each chapter grader implements this trait.
68pub trait Grade {
69    fn chapter_number(&self) -> u32;
70    fn chapter_name(&self) -> &'static str;
71    fn total_tasks(&self) -> usize;
72    fn total_points(&self) -> u32;
73
74    /// Run every task check in order.
75    fn check_all(&mut self);
76    /// The collected results.
77    fn results(&self) -> &[TaskResult];
78
79    /// Print a standardised report to the serial console.
80    fn show_report(&self) {
81        use crate::serial_println;
82
83        serial_println!();
84        serial_println!("========================================");
85        serial_println!(
86            "   Chapter {} {} - Grading Report",
87            self.chapter_number(),
88            self.chapter_name()
89        );
90        serial_println!("========================================");
91
92        for r in self.results() {
93            for d in &r.details {
94                let mark = match d.status {
95                    GradeStatus::Pass => "[PASS]",
96                    GradeStatus::Fail => "[FAIL]",
97                };
98                serial_println!(
99                    "{} Task {}: {} ({} points)",
100                    mark,
101                    r.task_id,
102                    r.name,
103                    r.points
104                );
105                serial_println!("    {} {}", d.prefix, d.message);
106            }
107        }
108
109        let completed = self.results().iter().filter(|r| r.passed()).count();
110        let total = self.total_tasks();
111        let score: u32 = self.results().iter().map(|r| r.score()).sum();
112
113        serial_println!();
114        serial_println!("========================================");
115        serial_println!("Completed: {}/{} tasks", completed, total);
116        serial_println!("Score: {}/{}", score, self.total_points());
117        serial_println!("========================================");
118        serial_println!();
119    }
120}
121
122/// Convenience: run every registered grader and print summaries.
123pub fn run_all_graders(graders: &mut [&mut dyn Grade]) {
124    for grader in graders.iter_mut() {
125        grader.check_all();
126        grader.show_report();
127    }
128}
129
130// ── Helpers for graders ───────────────────────────────────────────
131
132pub fn pass(msg: impl Into<String>) -> GradeDetail {
133    GradeDetail {
134        status: GradeStatus::Pass,
135        prefix: "+",
136        message: msg.into(),
137    }
138}
139
140pub fn fail(msg: impl Into<String>) -> GradeDetail {
141    GradeDetail {
142        status: GradeStatus::Fail,
143        prefix: "x",
144        message: msg.into(),
145    }
146}
147
148pub fn check_condition(
149    cond: bool,
150    pass_msg: impl Into<String>,
151    fail_msg: impl Into<String>,
152) -> GradeDetail {
153    if cond {
154        pass(pass_msg)
155    } else {
156        fail(fail_msg)
157    }
158}
159
160pub mod chapter5_syscall;
161pub mod chapter6_process;
162pub mod chapter8_elf;
163pub mod chapter9_shell;