Replace 'Scientific Computing Studio' in the source headers, the Cargo.toml authors, and the LICENSE contributor line. pixi.toml still has the old authors line. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014zNf4shD4zaCKLucZWPYL9
184 lines
5.5 KiB
Rust
184 lines
5.5 KiB
Rust
// 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<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));
|
|
}
|
|
}
|