feat: splitting
This commit is contained in:
29 files changed
+4843
-234
No files matched your search
+120
-55
@@ -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");
|
||||
|
||||
Reference in new issue
Block a user