1 parent
228a0da47f
commit
abc0bdf621
79 files changed
+31370
No files matched your search
@@ -0,0 +1,183 @@
|
||||
// SPDX-License-Identifier: Prosperity-3.0.0
|
||||
// Copyright Scientific Computing Studio
|
||||
// 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<Date>,
|
||||
/// The printed question number.
|
||||
pub number: u32,
|
||||
/// The fingerprint as used.
|
||||
pub fingerprint: Option<String>,
|
||||
}
|
||||
|
||||
/// 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<Usage>,
|
||||
}
|
||||
|
||||
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<History> {
|
||||
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<Date> {
|
||||
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));
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user