// SPDX-License-Identifier: Prosperity-3.0.0 // Copyright Scienting // Source: https://git.scient.ing/education/coursebank //! The usage history of a course, derived by scanning assessment records. //! //! There is deliberately no separate ledger file. A ledger duplicates //! information the records already hold and then drifts away from it; this //! derives the same answers from the one artifact that has to be right anyway. //! An item was used exactly when it appears on a record. //! //! This is an aggregate over the records, the same kind of thing as //! [`crate::catalog::Catalog`], which is why it sits beside the schema rather //! than inside [`crate::assessment`]. use std::path::Path; use crate::assessment::{AssessmentFile, Kind}; use crate::date::Date; use crate::error::Result; /// One recorded appearance of an item, derived from the assessment records. #[derive(Debug, Clone)] pub struct Usage { /// The item's global id. pub item: String, /// The assessment id it appeared on. pub assessment: String, /// The assessment title. pub title: String, /// The kind of assessment. pub kind: Kind, /// When it was administered, when recorded. pub date: Option, /// The printed question number. pub number: u32, /// The fingerprint as used. pub fingerprint: Option, } /// The usage history of a course, built by scanning assessment records. #[derive(Debug, Clone, Default)] pub struct History { /// Every recorded appearance, newest last. pub usages: Vec, } impl History { /// Builds the history from a directory of assessment records. /// /// # Arguments /// /// * `dir` - the assessments directory. /// /// # Returns /// /// The history. /// /// # Errors /// /// Propagates load errors. pub fn load(dir: &Path) -> Result { let mut usages = Vec::new(); for file in AssessmentFile::load_all(dir)? { for p in &file.items { usages.push(Usage { item: p.item.clone(), assessment: file.assessment.id.clone(), title: file.assessment.title.clone(), kind: file.assessment.kind, date: file.assessment.date, number: p.number, fingerprint: p.fingerprint.clone(), }); } } usages.sort_by(|a, b| { a.date .cmp(&b.date) .then(a.assessment.cmp(&b.assessment)) .then(a.number.cmp(&b.number)) }); Ok(History { usages }) } /// Every appearance of one item, oldest first. /// /// # Arguments /// /// * `uid` - the item's global id. /// /// # Returns /// /// Matching usages. pub fn for_item(&self, uid: &str) -> Vec<&Usage> { self.usages.iter().filter(|u| u.item == uid).collect() } /// The most recent date an item was used. /// /// # Arguments /// /// * `uid` - the item's global id. /// /// # Returns /// /// The date, or `None` when never used or never dated. pub fn last_used(&self, uid: &str) -> Option { self.for_item(uid).iter().filter_map(|u| u.date).max() } /// How many times an item has been used. /// /// # Arguments /// /// * `uid` - the item's global id. /// /// # Returns /// /// The count. pub fn use_count(&self, uid: &str) -> usize { self.for_item(uid).len() } /// Whether an item is still inside its reuse cooldown. /// /// # Arguments /// /// * `uid` - the item's global id. /// * `cooldown_days` - the minimum gap between uses. /// * `as_of` - the date of the assessment being assembled. /// /// # Returns /// /// `true` when the item was used too recently to reuse. pub fn in_cooldown(&self, uid: &str, cooldown_days: i64, as_of: Date) -> bool { match self.last_used(uid) { Some(last) => last.days_until(as_of) < cooldown_days, None => false, } } } #[cfg(test)] mod tests { use super::*; #[test] fn history_tracks_last_use_and_cooldown() { let h = History { usages: vec![ Usage { item: "b::q-1".into(), assessment: "exam-1".into(), title: "Exam 1".into(), kind: Kind::Exam, date: Some("2025-09-15".parse().unwrap()), number: 4, fingerprint: None, }, Usage { item: "b::q-1".into(), assessment: "exam-3".into(), title: "Exam 3".into(), kind: Kind::Exam, date: Some("2026-02-10".parse().unwrap()), number: 7, fingerprint: None, }, ], }; assert_eq!(h.use_count("b::q-1"), 2); assert_eq!(h.use_count("b::q-2"), 0); assert_eq!(h.last_used("b::q-1").unwrap().to_string(), "2026-02-10"); let exam_date: Date = "2026-04-23".parse().unwrap(); // 72 days elapsed, so a 90-day cooldown still blocks it and a 60-day one // does not. assert!(h.in_cooldown("b::q-1", 90, exam_date)); assert!(!h.in_cooldown("b::q-1", 60, exam_date)); assert!(!h.in_cooldown("b::never-used", 3650, exam_date)); } }