feat: splitting

This commit is contained in:
alexm committed 2026-09-26 01:15:12 -04:00
1 parent 220363d4d3
commit eabc98ad31
29 files changed
+4843 -234

No files matched your search

+120 -55
View File
@@ -5,7 +5,7 @@
//! Loading a whole course at once, and reporting on what it contains.
//!
//! A [`Catalog`] is every bank in a course, indexed so that an item can be found
//! by its global id (`bank::item`), and so that questions like "how many Apply
//! by its id, and so that questions like "how many Apply
//! level items do I have on lecture 12" have a cheap answer.
//!
//! The global id is the join key for everything downstream: assessment records
@@ -32,7 +32,12 @@ use crate::yaml;
/// One item plus everything needed to locate it again.
#[derive(Debug, Clone)]
pub struct Entry {
/// The globally unique id, `bank::item`.
/// The item's id, which names it course-wide.
///
/// The bank is in [`Entry::bank`] and the file in [`Entry::path`], neither
/// of which is part of the identity: this is the join key that response
/// data carries, and a join key with a file name in it renames itself every
/// time the files are reorganized.
pub uid: String,
/// The bank id.
pub bank: String,
@@ -92,7 +97,7 @@ impl Catalog {
/// id, since either makes the join key ambiguous.
pub fn load(root: &Path) -> Result<Catalog> {
let layout = Layout::new(root);
let course = CourseFile::load(&layout.course_file())?;
let course = CourseFile::load_dir(root)?;
let mut catalog = Catalog {
course,
layout,
@@ -117,9 +122,13 @@ impl Catalog {
}
catalog.banks.insert(bank_id.clone(), bank.bank.clone());
for (i, item) in bank.items.into_iter().enumerate() {
let uid = format!("{bank_id}::{}", item.id);
if catalog.index.contains_key(&uid) {
problems.push(format!("duplicate global item id `{uid}`"));
let uid = item.id.clone();
if let Some(first) = catalog.index.get(&uid) {
problems.push(format!(
"item id `{uid}` is used twice: in bank `{}` and in bank `{bank_id}`. An \
id names one question course-wide, because response data joins on it.",
catalog.entries[*first].bank
));
continue;
}
catalog.index.insert(uid.clone(), catalog.entries.len());
@@ -141,15 +150,22 @@ impl Catalog {
/// Looks up an item by global id.
///
/// A pre-2.0 `bank::item` id resolves to the item it used to name, so an
/// assessment record or a parquet file written before the change still
/// joins. See [`crate::item::canonical_id`].
///
/// # Arguments
///
/// * `uid` - the global id, `bank::item`.
/// * `uid` - the item id, in either form.
///
/// # Returns
///
/// The entry, or `None`.
pub fn get(&self, uid: &str) -> Option<&Entry> {
self.index.get(uid).map(|i| &self.entries[*i])
self.index
.get(uid)
.or_else(|| self.index.get(crate::item::canonical_id(uid)))
.map(|i| &self.entries[*i])
}
/// Looks up an item by global id, erroring when absent.
@@ -173,45 +189,37 @@ impl Catalog {
})
}
/// Resolves a possibly-unqualified id to a global id.
/// Resolves an id written in either form to the canonical one.
///
/// Typing `q-mm-kinetics-001` on the command line should work when that id is
/// unambiguous across the course, because remembering which bank a question
/// lives in is exactly the sort of bookkeeping this tool exists to remove.
/// Since 2.0 an item id is already course-wide, so this is the identity for
/// anything current. What it is still for is the old `bank::item` form,
/// which appears in assessment records, seals, and response files written
/// before the change, and which a person may well still type.
///
/// # Arguments
///
/// * `id` - a global id, or a bare item id.
/// * `id` - an item id, in either form.
///
/// # Returns
///
/// The global id.
/// The canonical id.
///
/// # Errors
///
/// Returns [`Error::Unresolved`] when nothing matches, or [`Error::Usage`]
/// when a bare id matches items in more than one bank.
/// Returns [`Error::Unresolved`] when nothing matches.
pub fn resolve(&self, id: &str) -> Result<String> {
if self.index.contains_key(id) {
return Ok(id.to_string());
}
let matches: Vec<&Entry> = self.entries.iter().filter(|e| e.item.id == id).collect();
match matches.len() {
0 => Err(Error::Unresolved {
kind: "item",
id: id.to_string(),
context: None,
}),
1 => Ok(matches[0].uid.clone()),
_ => Err(Error::usage(format!(
"`{id}` is ambiguous; it exists in {}. Use the full `bank::item` form.",
matches
.iter()
.map(|e| e.bank.as_str())
.collect::<Vec<_>>()
.join(", ")
))),
let canonical = crate::item::canonical_id(id);
if self.index.contains_key(canonical) {
return Ok(canonical.to_string());
}
Err(Error::Unresolved {
kind: "item",
id: id.to_string(),
context: None,
})
}
/// Every item that may be placed on a graded assessment.
@@ -232,12 +240,10 @@ impl Catalog {
///
/// Problems, prefixed with the file they came from.
pub fn validate(&self) -> Result<Vec<String>> {
let mut issues: Vec<String> = self
.course
.validate()
.into_iter()
.map(|m| format!("course.yaml: {m}"))
.collect();
// Not prefixed here: `CourseFile::validate` attributes each message to
// the fragment that defined the id, which for an unsplit course is
// `course.yaml` and for a split one is the file worth opening.
let mut issues: Vec<String> = self.course.validate();
for path in yaml::list_yaml(&self.layout.banks())? {
let bank = BankFile::load_resolved(&path)?;
@@ -255,6 +261,45 @@ impl Catalog {
Ok(issues)
}
/// Checks every sealed administration's stems against the bank.
///
/// The seal is the authority on what was administered, so this is the
/// comparison that matters: a record can be edited, but a seal is written
/// before the exam is printed and digested against tampering. A stem that
/// no longer matches the one a cohort answered means the id now names a
/// different question, and every statistic pooled under it is describing
/// two things at once.
///
/// # Arguments
///
/// * `seals` - the sealed administrations to check.
///
/// # Returns
///
/// One message per stem that has moved out from under its seal.
pub fn validate_seals(&self, seals: &[crate::seal::SealFile]) -> Vec<String> {
let mut issues = Vec::new();
for seal in seals {
for item in &seal.items {
let Some(digest) = &item.stem_digest else {
continue;
};
let Some(entry) = self.get(&item.item) else {
continue;
};
if *digest != entry.item.stem_digest() {
issues.push(format!(
"{}: question {} (`{}`) was administered with a different stem than the \
bank now holds. Statistics from that administration describe the older \
wording; give the new wording its own id.",
seal.seal.assessment, item.number, item.item
));
}
}
}
issues
}
/// Validates a record's internal invariants, then its references against this
/// catalog: unknown items, keys that drifted, and fingerprints showing the
/// item was reworded since it was administered.
@@ -264,6 +309,22 @@ impl Catalog {
match self.get(&p.item) {
None => issues.push(format!("question {}: unknown item `{}`", p.number, p.item)),
Some(entry) => {
// The rule the stem digest exists to enforce. A changed
// fingerprint is a note: the statistics describe an older
// wording. A changed stem is an error: whatever was
// administered is not the question the bank now holds, so
// the id is being reused for two different questions.
if let Some(digest) = &p.stem_digest {
if *digest != entry.item.stem_digest() {
issues.push(format!(
"question {} ({}): the stem has been reworded since this \
assessment. A reworded stem is a new question: give the new \
wording a new id with `supersedes: {}`, and leave this one as \
it was administered.",
p.number, p.item, p.item
));
}
}
if let Some(fp) = &p.fingerprint {
if *fp != entry.item.fingerprint() {
issues.push(format!(
@@ -705,13 +766,32 @@ items:
let cat = Catalog::load(&dir).expect("catalog loads");
assert_eq!(cat.entries.len(), 1);
assert_eq!(cat.entries[0].uid, "b1::q-x-001");
// The id names the item course-wide; the bank is where it is kept.
assert_eq!(cat.entries[0].uid, "q-x-001");
assert_eq!(cat.entries[0].bank, "b1");
assert!(cat.get("q-x-001").is_some());
assert_eq!(cat.resolve("q-x-001").unwrap(), "q-x-001");
// A record or a parquet file written before 2.0 still joins.
assert!(cat.get("b1::q-x-001").is_some());
assert_eq!(cat.resolve("q-x-001").unwrap(), "b1::q-x-001");
assert_eq!(cat.resolve("b1::q-x-001").unwrap(), "q-x-001");
assert!(cat.get("b1::q-nonexistent").is_none());
assert!(cat.validate().unwrap().is_empty());
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn one_item_id_in_two_banks_is_fatal() {
let dir = tmp("dupitem");
write_course(&dir, "");
write_bank(&dir, "b1.yaml", APPROVED);
write_bank(&dir, "b2.yaml", &APPROVED.replace("id: b1", "id: b2"));
let message = Catalog::load(&dir).unwrap_err().to_string();
assert!(message.contains("`q-x-001` is used twice"), "{message}");
assert!(message.contains("course-wide"), "{message}");
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn duplicate_bank_ids_are_fatal() {
let dir = tmp("dupbank");
@@ -723,21 +803,6 @@ items:
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn ambiguous_bare_ids_are_rejected() {
let dir = tmp("ambig");
write_course(&dir, "");
write_bank(&dir, "a.yaml", APPROVED);
write_bank(&dir, "b.yaml", &APPROVED.replace("id: b1", "id: b2"));
let cat = Catalog::load(&dir).expect("distinct banks load");
assert_eq!(cat.entries.len(), 2);
let err = cat.resolve("q-x-001").expect_err("bare id is ambiguous");
assert!(format!("{err}").contains("ambiguous"));
// The fully qualified form still works.
assert_eq!(cat.resolve("b2::q-x-001").unwrap(), "b2::q-x-001");
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn coverage_finds_real_gaps() {
let dir = tmp("coverage");