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

+19 -2
View File
@@ -248,11 +248,28 @@ pub struct Placement {
/// Printed question number. This is the join key to grading exports, which
/// is the entire reason this record exists.
pub number: u32,
/// The item's global id, `bank::item`.
/// The item's id, which names it course-wide. A pre-2.0 `bank::item`
/// value still resolves; `coursebank migrate ids` rewrites it.
pub item: String,
/// The item version used.
#[serde(default, skip_serializing_if = "Option::is_none")]
/// Retained only so a pre-2.0 record still loads. Ignored.
///
/// What it was for — knowing whether the item has changed since this
/// administration — is [`Placement::stem_digest`] and
/// [`Placement::fingerprint`], which say *what* changed rather than that
/// something did.
#[serde(default, skip_serializing)]
pub version: Option<u32>,
/// The stem's digest as administered. See [`crate::item::Item::stem_digest`].
///
/// Distinct from `fingerprint`, which covers the options too. A changed
/// fingerprint means the pooled statistics describe an older wording; a
/// changed stem digest means this is no longer the same question, which
/// [`crate::catalog::Catalog::validate_record`] treats as an error rather
/// than a note.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub stem_digest: Option<String>,
/// The content fingerprint as used, so later edits are detectable.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub fingerprint: Option<String>,
+22 -53
View File
@@ -352,8 +352,10 @@ fn validate_item(
if it.stem.trim().is_empty() {
issues.push("empty stem".into());
}
if it.version == 0 {
issues.push("version must be at least 1".into());
if let Some(replaced) = &it.supersedes {
if *replaced == it.id {
issues.push("supersedes names this item".into());
}
}
// --- options ----
@@ -379,15 +381,22 @@ fn validate_item(
if o.text.trim().is_empty() {
issues.push(format!("option {pos}: empty text"));
}
let letter_ok = o.id.len() == 1
&& o.id
.chars()
.next()
.map(|c| c.is_ascii_uppercase() && c <= 'H')
.unwrap_or(false);
if !letter_ok {
// Two forms are accepted: the 2.0 name, and the letter that preceded
// it. A bank migrates when `coursebank migrate options` is run on it,
// not when the tool is upgraded, so a course mid-migration still loads.
let slug_ok = o.id.strip_prefix("o-").is_some_and(|rest| {
!rest.is_empty()
&& !rest.starts_with('-')
&& !rest.ends_with('-')
&& !rest.contains("--")
&& rest
.chars()
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
});
if !slug_ok && !Item::is_legacy_option_id(&o.id) {
issues.push(format!(
"option {pos}: id `{}` must be a single letter A through H",
"option {pos}: id `{}` is neither a name such as `o-fourth-line` nor a pre-2.0 \
letter A through H",
o.id
));
}
@@ -514,10 +523,10 @@ fn validate_item(
));
}
}
for letter in c.option_stats.keys() {
if it.option(letter).is_none() {
for option in c.option_stats.keys() {
if it.option(option).is_none() {
issues.push(format!(
"calibration.option_stats has `{letter}`, which is not an option of this item"
"calibration.option_stats has `{option}`, which is not an option of this item"
));
}
}
@@ -533,25 +542,6 @@ fn validate_item(
}
}
// --- history must be coherent ------
let mut last_version = 0u32;
for (i, h) in it.history.iter().enumerate() {
if h.version <= last_version {
issues.push(format!(
"history entry {} has version {} which does not increase",
i + 1,
h.version
));
}
last_version = h.version;
}
if !it.history.is_empty() && last_version > it.version {
issues.push(format!(
"history records version {last_version} but the item says version {}",
it.version
));
}
// --- retirement -----
if it.retired.is_some() && it.status != Status::Retired {
issues.push(format!(
@@ -1027,27 +1017,6 @@ learning_targets:
);
}
#[test]
fn history_versions_must_increase() {
let b = bank(
r#"
- id: q-a-001
version: 2
status: draft
level: 1
stem: s
options:
- { id: A, text: a, correct: true }
- { id: B, text: b }
history:
- { version: 2, date: 2026-01-01, change: second }
- { version: 1, date: 2026-01-02, change: first }
"#,
);
let issues = b.validate(None);
assert!(issues.iter().any(|i| i.contains("does not increase")));
}
#[test]
fn level_counts_exclude_drafts_and_bonuses() {
let b = bank(
+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");
+455 -23
View File
@@ -4,20 +4,29 @@
//! The course file: identity plus the registries every bank references.
//!
//! Learning objectives, their learning targets, and lectures are declared once,
//! in `course.yaml`, and referenced by id from items. That is the single most load-bearing decision in
//! Learning objectives, their learning targets, and lectures are declared once
//! and referenced by id from items. That is the single most load-bearing decision in
//! the schema. It means an objective's wording lives in exactly one place, so
//! rewording it updates every report; it means a report can name what a student
//! missed by objective rather than by question number; and it means a dangling
//! reference is a hard error instead of a silently misspelled string that splits
//! your coverage table into two near-identical rows.
//!
//! "Once" is a claim about ids, not about files. [`CourseFile`] is the resolved
//! model, and it may be assembled from a directory of fragments — one file per
//! lecture, one per objective — as well as from a single `course.yaml`. Either
//! way an id has exactly one definition site, and [`CourseFile::origins`]
//! records which file that was. See [`fragment`] for the merge and the rules
//! that keep it honest.
//!
//! The course file also declares the term. Items live across terms, so the term
//! belongs to the course and the administration, never to the item.
pub mod fragment;
use std::collections::BTreeMap;
use std::fmt;
use std::path::Path;
use std::path::{Path, PathBuf};
use serde::de::{self, MapAccess, Visitor};
use serde::ser::SerializeMap;
@@ -28,8 +37,19 @@ use crate::error::{Error, Result};
use crate::taxonomy::Level;
use crate::yaml;
use fragment::Section;
/// The schema version this build of the tool writes.
pub const SCHEMA_VERSION: &str = "1.0";
pub const SCHEMA_VERSION: &str = "2.0";
/// The schema major versions this build can read.
///
/// A 1.0 repository loads unchanged. What 2.0 changes is the shape of two
/// things, and both are tolerated on the way in: a course file may be split
/// into fragments, and an item is named course-wide rather than as
/// `bank::item`. `coursebank migrate` rewrites files into the 2.0 form when you
/// are ready; nothing forces it.
pub const SUPPORTED_MAJORS: [&str; 2] = ["1", "2"];
/// The canonical file name inside a course directory.
pub const COURSE_FILE: &str = "course.yaml";
@@ -91,6 +111,16 @@ pub struct CourseFile {
/// Shared stimuli for case-based testlets, keyed by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub stimuli: BTreeMap<String, Stimulus>,
/// Which file defined each id, relative to the course root.
///
/// Populated by [`fragment::assemble`] and empty for a course parsed
/// straight out of one file by [`CourseFile::load`]. It is what makes a
/// validation message able to name the file to open, which matters rather a
/// lot once one course is forty files. Not serialized: it describes where
/// the model came from, not what it says.
#[serde(skip)]
pub origins: BTreeMap<(Section, String), PathBuf>,
}
/// Course identity.
@@ -285,6 +315,15 @@ pub struct Lecture {
/// Where the slides live, for study guidance in student reports.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub slides_url: Option<String>,
/// The objectives this session develops.
///
/// The registration direction: you write what a lecture covers while
/// planning the lecture, and each named objective gains this lecture in its
/// [`Objective::lectures`] list during [`fragment::assemble`]. Declaring the
/// pair from the objective's side instead is equivalent, and declaring it
/// from both is redundant rather than contradictory — the two are unioned.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub teaches: Vec<String>,
/// Assigned readings for the session, in the order you assign them.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub readings: Vec<Reading>,
@@ -335,8 +374,21 @@ pub struct Reference {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub pages: Option<String>,
/// DOI, bare: `10.1038/nature12373`.
///
/// For a manuscript this is usually the only link worth storing: it is the
/// identifier of the work rather than of one copy of it, and [`Reference::href`]
/// turns it into a URL.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub doi: Option<String>,
/// arXiv id, bare: `2301.00001` or `q-bio/0501001`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub arxiv: Option<String>,
/// PubMed Central id, which hosts the full text: `PMC3084216`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub pmcid: Option<String>,
/// PubMed id, which hosts a record about the work: `21471563`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub pmid: Option<String>,
/// ISBN, for a book.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub isbn: Option<String>,
@@ -353,6 +405,123 @@ pub struct Reference {
pub note: Option<String>,
}
impl Reference {
/// Where to send a reader, most specific first.
///
/// The one link resolution in the crate. Every exporter used to carry its
/// own copy of the `base_url` join, which meant a reading list, a printed
/// key, a practice sheet, and a student report could disagree about where a
/// citation points — and that none of them linked a journal article, since
/// an article has no `base_url` to join a path to.
///
/// The order is from the exact location outward: a link to §1.4 beats a link
/// to the work, and a link to the work beats nothing.
///
/// # Arguments
///
/// * `url` - a full URL for the exact location, from a reading or citation.
/// * `path` - a location under this work's `base_url`.
///
/// # Returns
///
/// The most specific link available, or `None` for a work with no online
/// location at all.
pub fn href(&self, url: Option<&str>, path: Option<&str>) -> Option<String> {
if let Some(url) = url {
return Some(url.to_string());
}
if let (Some(base), Some(path)) = (self.base_url.as_deref(), path) {
return Some(join_url(base, path));
}
if let Some(url) = &self.url {
return Some(url.clone());
}
self.identifier_url()
}
/// The link this work's identifiers resolve to, ignoring any location inside
/// it.
///
/// DOI first, because it names the work rather than one copy of it. Then
/// arXiv and PubMed Central, which host the article itself, before PubMed,
/// which hosts a record about it.
///
/// # Returns
///
/// A URL, or `None` when the work carries no identifier.
pub fn identifier_url(&self) -> Option<String> {
if let Some(doi) = self.doi.as_deref().map(bare_doi) {
return Some(format!("https://doi.org/{doi}"));
}
if let Some(id) = self.arxiv.as_deref().map(bare_arxiv) {
return Some(format!("https://arxiv.org/abs/{id}"));
}
if let Some(id) = self.pmcid.as_deref().map(str::trim) {
let id = if id.starts_with("PMC") {
id.to_string()
} else {
format!("PMC{id}")
};
return Some(format!("https://www.ncbi.nlm.nih.gov/pmc/articles/{id}/"));
}
if let Some(id) = self.pmid.as_deref().map(str::trim) {
return Some(format!("https://pubmed.ncbi.nlm.nih.gov/{id}/"));
}
None
}
/// The short form a reading list shows: the label, or the citation key.
///
/// # Arguments
///
/// * `key` - the citation key, used when the work declares no label.
///
/// # Returns
///
/// The label to print.
pub fn label_or<'a>(&'a self, key: &'a str) -> &'a str {
self.label.as_deref().unwrap_or(key)
}
}
/// A DOI with any resolver prefix stripped, so `href` cannot produce
/// `https://doi.org/https://doi.org/10...`.
fn bare_doi(doi: &str) -> &str {
let doi = doi.trim();
for prefix in [
"https://doi.org/",
"http://doi.org/",
"https://dx.doi.org/",
"http://dx.doi.org/",
"doi:",
] {
if let Some(rest) = doi.strip_prefix(prefix) {
return rest;
}
}
doi
}
/// An arXiv id with the `arXiv:` prefix stripped.
fn bare_arxiv(id: &str) -> &str {
let id = id.trim();
for prefix in ["arXiv:", "arxiv:", "https://arxiv.org/abs/"] {
if let Some(rest) = id.strip_prefix(prefix) {
return rest;
}
}
id
}
/// Joins a base URL and a path without doubling or dropping the separator.
fn join_url(base: &str, path: &str) -> String {
match (base.ends_with('/'), path.starts_with('/')) {
(true, true) => format!("{base}{}", &path[1..]),
(false, false) => format!("{base}/{path}"),
_ => format!("{base}{path}"),
}
}
/// The kind of work, chosen to map onto BibTeX entry types.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
@@ -447,19 +616,10 @@ impl Reading {
///
/// # Returns
///
/// `url` when given, otherwise the reference's `base_url` joined with `path`,
/// otherwise `None`.
/// The most specific link available, which for a manuscript with a DOI and
/// no `path` is the DOI. See [`Reference::href`].
pub fn resolve_url(&self, reference: &Reference) -> Option<String> {
if let Some(url) = &self.url {
return Some(url.clone());
}
let path = self.path.as_deref()?;
let base = reference.base_url.as_deref()?;
Some(match (base.ends_with('/'), path.starts_with('/')) {
(true, true) => format!("{base}{}", &path[1..]),
(false, false) => format!("{base}/{path}"),
_ => format!("{base}{path}"),
})
reference.href(self.url.as_deref(), self.path.as_deref())
}
/// A short citation for a report: `KKW §6.1`.
@@ -476,7 +636,7 @@ impl Reading {
if let Some(text) = &self.text {
return text.clone();
}
let label = reference.label.as_deref().unwrap_or(key);
let label = reference.label_or(key);
match &self.locator {
Some(locator) => format!("{label} {locator}"),
None => label.to_string(),
@@ -761,7 +921,12 @@ impl CourseFile {
yaml::read(path)
}
/// Finds and loads the course file for a course directory.
/// Loads the course for a course directory, merging every fragment it holds.
///
/// This is the entry point every command uses. A directory holding only
/// `course.yaml` gives the same result it always did; one that also holds
/// `lectures/`, `objectives/`, or `references.yaml` gets them merged in. See
/// [`fragment::assemble`].
///
/// # Arguments
///
@@ -769,34 +934,167 @@ impl CourseFile {
///
/// # Returns
///
/// The parsed course file.
/// The merged course file.
///
/// # Errors
///
/// Propagates load errors, including absence of `course.yaml`.
/// Propagates load errors, including absence of `course.yaml`, and returns
/// [`Error::Invalid`] when two files define the same id.
pub fn load_dir(dir: &Path) -> Result<CourseFile> {
CourseFile::load(&dir.join(COURSE_FILE))
fragment::assemble(dir)
}
/// Which file defined an id, and which registry it was in.
///
/// # Arguments
///
/// * `id` - a unit, lecture, objective, target, reference, or stimulus id.
///
/// # Returns
///
/// The section and the path relative to the course root, or `None` for an
/// unknown id or a course that was not assembled from fragments.
pub fn origin(&self, id: &str) -> Option<(Section, &Path)> {
Section::ALL.iter().find_map(|section| {
self.origins
.get(&(*section, id.to_string()))
.map(|path| (*section, path.as_path()))
})
}
/// Every file this course was assembled from, in sorted order.
///
/// # Returns
///
/// The paths relative to the course root, empty for a course parsed from a
/// single file by [`CourseFile::load`].
pub fn fragment_paths(&self) -> Vec<&Path> {
let mut paths: Vec<&Path> = self.origins.values().map(PathBuf::as_path).collect();
paths.sort_unstable();
paths.dedup();
paths
}
/// Writes the course file back out as YAML.
///
/// Refuses to write a course that was assembled from more than one file,
/// because the merged model has no home on disk: writing it to
/// `course.yaml` would leave every fragment defining ids the root file also
/// defines, which is the one thing [`fragment::assemble`] treats as an
/// error. Use [`CourseFile::write_resolved`] for an inspection copy.
///
/// # Arguments
///
/// * `path` - destination path.
///
/// # Errors
///
/// Returns [`Error::Io`] on a write failure.
/// Returns [`Error::Usage`] for a fragmented course and [`Error::Io`] on a
/// write failure.
pub fn save(&self, path: &Path) -> Result<()> {
let sources = self.fragment_paths();
if sources.len() > 1 {
return Err(Error::usage(format!(
"this course is assembled from {} files, so it cannot be written back to one. \
Edit the fragment that owns what you are changing, or use `coursebank course \
build` for a merged copy.",
sources.len()
)));
}
yaml::write(path, self)
}
/// Writes the merged course as YAML, for reading rather than for loading.
///
/// The output carries a banner saying so. It is what `coursebank course
/// build` writes, and nothing in the tool reads it back: a generated file
/// that commands depend on is a file that goes stale.
///
/// # Arguments
///
/// * `path` - destination path.
///
/// # Errors
///
/// Returns [`Error::Io`] on a write failure, or [`Error::Other`] if the
/// model cannot be represented as YAML.
pub fn write_resolved(&self, path: &Path) -> Result<()> {
let body = yaml::to_string(self)?;
let banner = format!(
"# Generated by `coursebank course build` from {} file(s). Do not edit: nothing\n\
# reads this, and the next build overwrites it. Edit the fragments instead.\n",
self.fragment_paths().len().max(1)
);
yaml::write_text(path, &format!("{banner}{body}"))
}
/// Checks internal consistency of the registries.
///
/// Each message is prefixed with the file that defined the id it is about,
/// when that is known. For an unsplit course that is always `course.yaml`,
/// which is what the messages used to say.
///
/// # Returns
///
/// Every problem found, empty when the file is sound.
pub fn validate(&self) -> Vec<String> {
self.problems()
.into_iter()
.map(|issue| self.attribute(issue))
.collect()
}
/// Prefixes one validation message with the fragment it concerns.
///
/// The id is taken from the first backticked token in the message, since
/// every message that is about a registry entry names it first. Messages
/// about `course`, `policy`, or `units` are attributed by section instead,
/// because the first thing they quote is a field or a grade letter.
///
/// # Arguments
///
/// * `issue` - the message.
///
/// # Returns
///
/// The message, prefixed with a path when one is known.
fn attribute(&self, issue: String) -> String {
let section = if issue.starts_with("course.") {
Some(Section::Course)
} else if issue.starts_with("policy.") {
Some(Section::Policy)
} else if issue.starts_with("units") {
Some(Section::Units)
} else {
None
};
let path = match section {
Some(section) => self.section_origin(section),
None => issue
.split('`')
.nth(1)
.and_then(|id| self.origin(id))
.map(|(_, path)| path),
};
match path {
Some(path) => format!("{}: {issue}", path.display()),
None => issue,
}
}
/// The file that declared a whole section, for the sections that are not
/// keyed by id.
fn section_origin(&self, section: Section) -> Option<&Path> {
self.origins
.iter()
.find(|((s, _), _)| *s == section)
.map(|(_, path)| path.as_path())
}
/// The validation messages, before they are attributed to files.
fn problems(&self) -> Vec<String> {
let mut issues = Vec::new();
if self.course.code.trim().is_empty() {
@@ -874,6 +1172,25 @@ impl CourseFile {
if reference.title.trim().is_empty() {
issues.push(format!("reference `{key}`: empty title"));
}
// Checked rather than silently coerced: `href` strips a resolver
// prefix, but something that is not a DOI at all would become a
// link that 404s on a student's reading list.
if let Some(doi) = &reference.doi {
if !bare_doi(doi).starts_with("10.") {
issues.push(format!(
"reference `{key}`: `{doi}` is not a DOI. Write it bare, as \
10.1038/nature12373."
));
}
}
if let Some(pmid) = &reference.pmid {
if !pmid.trim().chars().all(|c| c.is_ascii_digit()) {
issues.push(format!(
"reference `{key}`: pmid `{pmid}` is not a number. A `PMC...` id goes in \
`pmcid`."
));
}
}
if let Some(label) = &reference.label {
labels.entry(label.as_str()).or_default().push(key);
}
@@ -897,6 +1214,20 @@ impl CourseFile {
issues.push(format!("lecture `{id}`: unknown unit `{u}`"));
}
}
for objective in &lec.teaches {
if !self.learning_objectives.contains_key(objective) {
if self.learning_targets.contains_key(objective) {
issues.push(format!(
"lecture `{id}`: `teaches` names the target `{objective}`, but it \
registers objectives. A target is reached through its objective."
));
} else {
issues.push(format!(
"lecture `{id}`: `teaches` names an unknown objective `{objective}`"
));
}
}
}
let mut seen: Vec<(&str, &str)> = Vec::new();
for (index, reading) in lec.readings.iter().enumerate() {
issues.extend(self.reading_issues(id, index, reading, &mut seen));
@@ -1770,6 +2101,7 @@ impl CourseFile {
date: None,
unit: Some("u-intro".to_string()),
slides_url: None,
teaches: Vec::new(),
readings: Vec::new(),
},
);
@@ -1825,6 +2157,7 @@ impl CourseFile {
learning_targets: targets,
references: BTreeMap::new(),
stimuli: BTreeMap::new(),
origins: BTreeMap::new(),
}
}
}
@@ -1893,7 +2226,7 @@ course:
term: Spring 2026
"#,
);
assert_eq!(c.schema_version, "1.0");
assert_eq!(c.schema_version, SCHEMA_VERSION);
assert_eq!(c.policy.options_per_item, 4);
assert_eq!(c.course.slug(), "biosc-1540");
assert!(c.validate().is_empty());
@@ -2040,6 +2373,105 @@ learning_objectives:
assert_eq!(reading.cite("kuriyan2013molecules", reference), "KKW §6.1");
}
#[test]
fn a_link_resolves_from_the_exact_location_outward() {
let mut reference = Reference {
title: "Basic local alignment search tool".into(),
kind: ReferenceKind::Article,
..Reference::default()
};
// Nothing at all to link to.
assert_eq!(reference.href(None, None), None);
// A DOI is a link to the work, which beats nothing.
reference.doi = Some("10.1016/S0022-2836(05)80360-2".into());
assert_eq!(
reference.href(None, None).as_deref(),
Some("https://doi.org/10.1016/S0022-2836(05)80360-2")
);
// The work's own URL is more use than its identifier.
reference.url = Some("https://example.org/blast".into());
assert_eq!(
reference.href(None, None).as_deref(),
Some("https://example.org/blast")
);
// A location inside the work beats the work.
reference.base_url = Some("https://example.org/blast/".into());
assert_eq!(
reference.href(None, Some("/§2")).as_deref(),
Some("https://example.org/blast/§2")
);
assert_eq!(
reference
.href(Some("https://example.org/exact"), Some("§2"))
.as_deref(),
Some("https://example.org/exact")
);
}
#[test]
fn identifiers_are_normalized_before_they_become_links() {
let doi_as_url = Reference {
title: "T".into(),
doi: Some("https://doi.org/10.1/x".into()),
..Reference::default()
};
assert_eq!(
doi_as_url.href(None, None).as_deref(),
Some("https://doi.org/10.1/x")
);
let preprint = Reference {
title: "T".into(),
kind: ReferenceKind::Preprint,
arxiv: Some("arXiv:2301.00001".into()),
..Reference::default()
};
assert_eq!(
preprint.href(None, None).as_deref(),
Some("https://arxiv.org/abs/2301.00001")
);
// A bare number is still a PMC id.
let open_access = Reference {
title: "T".into(),
pmcid: Some("3084216".into()),
..Reference::default()
};
assert_eq!(
open_access.href(None, None).as_deref(),
Some("https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3084216/")
);
}
#[test]
fn something_that_is_not_a_doi_is_reported() {
let c = parse(
r#"
course: { code: X, title: Y, term: Z }
references:
bad:
title: A work
doi: nature12373
worse:
title: Another work
pmid: PMC3084216
"#,
);
let issues = c.validate();
assert!(
issues.iter().any(|i| i.contains("is not a DOI")),
"{issues:?}"
);
assert!(
issues.iter().any(|i| i.contains("is not a number")),
"{issues:?}"
);
}
#[test]
fn a_bare_string_reading_still_parses_and_round_trips() {
let c = parse(
+866
View File
@@ -0,0 +1,866 @@
// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scientific Computing Studio
// Source: https://git.scient.ing/education/coursebank
//! One course, several files.
//!
//! A course of forty lectures does not fit in a file anyone wants to scroll. So
//! the registries [`CourseFile`] holds may be spread across a directory and
//! merged on load:
//!
//! ```text
//! course.yaml course, policy, units
//! references.yaml references
//! lectures/l-1-2.yaml one lecture, its readings, and what it teaches
//! objectives/lo-x.yaml one objective and its targets
//! ```
//!
//! The merge happens in memory on every command. Nothing is generated on disk
//! and no command depends on a build step, because a generated file that other
//! commands read is a file that goes stale. `coursebank course build` exists to
//! show you the merged result, and nothing reads what it writes.
//!
//! # What this does not relax
//!
//! Splitting a file is only worth doing if it cannot introduce a second
//! definition of the same thing. Two rules keep that true, and both are enforced
//! here rather than left to convention:
//!
//! * **One definition site per id.** Two files defining `lo-read-file-formats`
//! is an error naming both paths. The winner is not the last file loaded,
//! because there is no winner.
//! * **A section belongs to a kind of file.** A file under `lectures/` may not
//! define `learning_objectives`. Otherwise the layout decays into forty files
//! that each might hold anything, which is the same navigation problem in a
//! worse shape.
//!
//! `course.yaml` is exempt from the second rule: a course that has not been
//! split is a single fragment that happens to define everything, and it keeps
//! loading unchanged.
//!
//! # Two derivations
//!
//! Splitting by lecture makes two fields tedious to maintain by hand, so they
//! are derived instead:
//!
//! * A lecture's `teaches:` list adds that lecture to each named objective's
//! `lectures`. You write what a lecture covers while planning the lecture,
//! which is when you know.
//! * A target with no `lectures` of its own inherits its objective's, the same
//! way it already inherits `level_ceiling`.
//!
//! Both are unions and both are idempotent, so declaring a pair on both sides
//! is redundant rather than contradictory.
use std::collections::BTreeMap;
use std::fmt;
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use super::{
COURSE_FILE, Course, CourseFile, Lecture, Objective, Policy, Reference, SCHEMA_VERSION,
SUPPORTED_MAJORS, Stimulus, Target, Unit,
};
use crate::error::{Error, Result};
use crate::layout::Layout;
use crate::yaml;
/// The file holding the bibliography when it is kept out of `course.yaml`.
pub const REFERENCES_FILE: &str = "references.yaml";
/// One registry section of a course.
///
/// Used to say which file a fact came from, and to keep a fragment from
/// defining something that belongs somewhere else.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Section {
/// Course identity.
Course,
/// Course-wide policy.
Policy,
/// Units.
Units,
/// Lectures.
Lectures,
/// Learning objectives.
Objectives,
/// Learning targets.
Targets,
/// Works the course cites.
References,
/// Shared stimuli.
Stimuli,
}
impl Section {
/// Every section, in the order a merged course lists them.
pub const ALL: [Section; 8] = [
Section::Course,
Section::Policy,
Section::Units,
Section::Lectures,
Section::Objectives,
Section::Targets,
Section::References,
Section::Stimuli,
];
/// The YAML key this section is written under.
pub fn key(self) -> &'static str {
match self {
Section::Course => "course",
Section::Policy => "policy",
Section::Units => "units",
Section::Lectures => "lectures",
Section::Objectives => "learning_objectives",
Section::Targets => "learning_targets",
Section::References => "references",
Section::Stimuli => "stimuli",
}
}
/// What one of its entries is called in a message.
pub fn noun(self) -> &'static str {
match self {
Section::Course => "course identity",
Section::Policy => "policy",
Section::Units => "unit",
Section::Lectures => "lecture",
Section::Objectives => "objective",
Section::Targets => "target",
Section::References => "reference",
Section::Stimuli => "stimulus",
}
}
/// Where a file defining this section is expected to live.
pub fn home(self) -> &'static str {
match self {
Section::Course | Section::Policy | Section::Units => COURSE_FILE,
Section::Lectures => "lectures/*.yaml",
Section::Objectives | Section::Targets | Section::Stimuli => "objectives/*.yaml",
Section::References => REFERENCES_FILE,
}
}
}
impl fmt::Display for Section {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.key())
}
}
/// What kind of file a fragment is, which fixes what it may define.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Role {
/// `course.yaml`. May define anything, so an unsplit course still loads.
Root,
/// `references.yaml`.
References,
/// A file under `lectures/`.
Lecture,
/// A file under `objectives/`.
Objective,
}
impl Role {
/// Whether a file in this role may define a section.
pub fn allows(self, section: Section) -> bool {
match self {
Role::Root => true,
Role::References => section == Section::References,
Role::Lecture => section == Section::Lectures,
Role::Objective => matches!(
section,
Section::Objectives | Section::Targets | Section::Stimuli
),
}
}
/// A short name for a message.
pub fn label(self) -> &'static str {
match self {
Role::Root => "course",
Role::References => "references",
Role::Lecture => "lecture",
Role::Objective => "objective",
}
}
}
/// One file's worth of course registries.
///
/// Every section is optional, which is what makes this both the fragment schema
/// and — with every section filled in — the schema of an unsplit `course.yaml`.
/// [`CourseFile`] is the resolved model the rest of the crate reads; this is
/// only what one file on disk is allowed to say.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Fragment {
/// Schema version this file targets.
#[serde(
default,
deserialize_with = "yaml::flexible_string_opt",
skip_serializing_if = "Option::is_none"
)]
pub schema_version: Option<String>,
/// Course identity. Exactly one fragment must carry it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub course: Option<Course>,
/// Course-wide policy.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub policy: Option<Policy>,
/// Units, in teaching order.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub units: Vec<Unit>,
/// Lectures by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub lectures: BTreeMap<String, Lecture>,
/// Learning objectives by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub learning_objectives: BTreeMap<String, Objective>,
/// Learning targets by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub learning_targets: BTreeMap<String, Target>,
/// Works the course cites, by citation key.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub references: BTreeMap<String, Reference>,
/// Shared stimuli by id.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub stimuli: BTreeMap<String, Stimulus>,
}
impl Fragment {
/// Loads one fragment from disk.
///
/// # Arguments
///
/// * `path` - the file to read.
///
/// # Returns
///
/// The parsed fragment.
///
/// # Errors
///
/// Returns [`Error::Io`] if unreadable and [`Error::Yaml`] if it does not
/// match the schema. Unknown keys are errors, so a misspelled section name
/// is caught here rather than silently contributing nothing.
pub fn load(path: &Path) -> Result<Fragment> {
yaml::read(path)
}
/// Which sections this fragment actually defines.
pub fn sections(&self) -> Vec<Section> {
let mut out = Vec::new();
if self.course.is_some() {
out.push(Section::Course);
}
if self.policy.is_some() {
out.push(Section::Policy);
}
if !self.units.is_empty() {
out.push(Section::Units);
}
if !self.lectures.is_empty() {
out.push(Section::Lectures);
}
if !self.learning_objectives.is_empty() {
out.push(Section::Objectives);
}
if !self.learning_targets.is_empty() {
out.push(Section::Targets);
}
if !self.references.is_empty() {
out.push(Section::References);
}
if !self.stimuli.is_empty() {
out.push(Section::Stimuli);
}
out
}
}
/// The fragment files of a course directory, in load order, with their roles.
///
/// `course.yaml` is listed whether or not it exists, so a directory that is not
/// a course fails with a message naming the file it wanted rather than an empty
/// merge. Directory contents are sorted, which is what makes the merged course
/// independent of filesystem order.
///
/// # Arguments
///
/// * `layout` - the resolved course layout.
///
/// # Returns
///
/// Paths paired with what each file is allowed to define.
///
/// # Errors
///
/// Returns [`Error::Io`] when a fragment directory exists but cannot be read.
pub fn files(layout: &Layout) -> Result<Vec<(PathBuf, Role)>> {
let mut out = vec![(layout.course_file(), Role::Root)];
let references = layout.references_file();
if references.is_file() {
out.push((references, Role::References));
}
for path in yaml::list_yaml(&layout.lectures())? {
out.push((path, Role::Lecture));
}
for path in yaml::list_yaml(&layout.objectives())? {
out.push((path, Role::Objective));
}
Ok(out)
}
/// Loads every fragment in a course directory and merges them into one course.
///
/// # Arguments
///
/// * `root` - the course directory.
///
/// # Returns
///
/// The merged course, with [`CourseFile::origins`] recording which file defined
/// each id.
///
/// # Errors
///
/// Propagates load errors, and returns [`Error::Invalid`] with every merge
/// problem at once: an id defined twice, a section in the wrong kind of file, a
/// fragment written against another major schema version, or no `course:`
/// section anywhere.
///
/// Cross-references are *not* checked here. A dangling objective id is a
/// content problem, and content problems are [`CourseFile::validate`]'s, so that
/// they are reported the same way whether or not the course is split.
pub fn assemble(root: &Path) -> Result<CourseFile> {
let layout = Layout::new(root);
let mut merge = Merge::default();
for (path, role) in files(&layout)? {
let fragment = Fragment::load(&path)?;
let shown = path.strip_prefix(root).unwrap_or(&path).to_path_buf();
merge.take(&shown, role, fragment);
}
merge.resolve();
merge.finish(root)
}
/// Accumulates fragments, remembering where each id came from.
#[derive(Debug, Default)]
struct Merge {
schema_version: Option<String>,
course: Option<Course>,
policy: Option<Policy>,
units: Vec<Unit>,
lectures: BTreeMap<String, Lecture>,
objectives: BTreeMap<String, Objective>,
targets: BTreeMap<String, Target>,
references: BTreeMap<String, Reference>,
stimuli: BTreeMap<String, Stimulus>,
origins: BTreeMap<(Section, String), PathBuf>,
issues: Vec<String>,
}
impl Merge {
/// Folds one fragment in.
///
/// # Arguments
///
/// * `path` - the fragment's path relative to the course root, for messages.
/// * `role` - what this file is allowed to define.
/// * `fragment` - the parsed fragment.
fn take(&mut self, path: &Path, role: Role, fragment: Fragment) {
for section in fragment.sections() {
if !role.allows(section) {
self.issues.push(format!(
"{}: a {} file may not define `{}`; that section belongs in {}",
path.display(),
role.label(),
section.key(),
section.home()
));
}
}
if let Some(declared) = &fragment.schema_version {
if !SUPPORTED_MAJORS.contains(&major(declared)) {
self.issues.push(format!(
"{}: declares schema_version {declared}, which this build cannot read. It \
writes {SCHEMA_VERSION} and reads {}.",
path.display(),
SUPPORTED_MAJORS
.iter()
.map(|m| format!("{m}.x"))
.collect::<Vec<_>>()
.join(" and ")
));
}
if self.schema_version.is_none() {
self.schema_version = Some(declared.clone());
}
}
if role.allows(Section::Course) {
if let Some(course) = fragment.course {
if self.claim(Section::Course, path) {
self.course = Some(course);
}
}
}
if role.allows(Section::Policy) {
if let Some(policy) = fragment.policy {
if self.claim(Section::Policy, path) {
self.policy = Some(policy);
}
}
}
if role.allows(Section::Units) {
for unit in fragment.units {
let key = (Section::Units, unit.id.clone());
if let Some(first) = self.origins.get(&key) {
let message = duplicate(Section::Units, &unit.id, first.as_path(), path);
self.issues.push(message);
continue;
}
self.origins.insert(key, path.to_path_buf());
self.units.push(unit);
}
}
if role.allows(Section::Lectures) {
absorb(
&mut self.lectures,
fragment.lectures,
Section::Lectures,
path,
&mut self.origins,
&mut self.issues,
);
}
if role.allows(Section::Objectives) {
absorb(
&mut self.objectives,
fragment.learning_objectives,
Section::Objectives,
path,
&mut self.origins,
&mut self.issues,
);
}
if role.allows(Section::Targets) {
absorb(
&mut self.targets,
fragment.learning_targets,
Section::Targets,
path,
&mut self.origins,
&mut self.issues,
);
}
if role.allows(Section::References) {
absorb(
&mut self.references,
fragment.references,
Section::References,
path,
&mut self.origins,
&mut self.issues,
);
}
if role.allows(Section::Stimuli) {
absorb(
&mut self.stimuli,
fragment.stimuli,
Section::Stimuli,
path,
&mut self.origins,
&mut self.issues,
);
}
}
/// Records a section that may only be declared once.
///
/// # Arguments
///
/// * `section` - the section being claimed.
/// * `path` - the file claiming it.
///
/// # Returns
///
/// Whether the claim was the first, and so whether the caller should store
/// what it parsed.
fn claim(&mut self, section: Section, path: &Path) -> bool {
let key = (section, String::new());
if let Some(first) = self.origins.get(&key) {
let message = format!(
"`{}` is declared twice: {} and {}. It applies to the whole course, so it has \
one definition site.",
section.key(),
first.display(),
path.display()
);
self.issues.push(message);
return false;
}
self.origins.insert(key, path.to_path_buf());
true
}
/// Fills in the two fields a split layout would otherwise duplicate.
fn resolve(&mut self) {
// A lecture says what it teaches; the objective's lecture list follows.
for (lecture_id, lecture) in &self.lectures {
for objective_id in &lecture.teaches {
if let Some(objective) = self.objectives.get_mut(objective_id) {
if !objective.lectures.iter().any(|l| l == lecture_id) {
objective.lectures.push(lecture_id.clone());
}
}
}
}
// A target with no lecture of its own is taught wherever its objective
// is. Collected first: the read of `objectives` and the write to
// `targets` cannot overlap in one pass.
let inherited: Vec<(String, Vec<String>)> = self
.targets
.iter()
.filter(|(_, target)| target.lectures.is_empty())
.filter_map(|(id, target)| {
self.objectives
.get(&target.objective)
.map(|objective| (id.clone(), objective.lectures.clone()))
})
.collect();
for (id, lectures) in inherited {
if let Some(target) = self.targets.get_mut(&id) {
target.lectures = lectures;
}
}
}
/// Builds the course, or reports every merge problem at once.
fn finish(self, root: &Path) -> Result<CourseFile> {
let mut issues = self.issues;
let course = match self.course {
Some(course) => course,
None => {
issues.push(format!(
"no file in {} declares a `course:` section, so the course has no code, \
title, or term",
root.display()
));
return Err(Error::Invalid(issues));
}
};
if !issues.is_empty() {
return Err(Error::Invalid(issues));
}
Ok(CourseFile {
schema_version: self
.schema_version
.unwrap_or_else(|| SCHEMA_VERSION.to_string()),
course,
policy: self.policy.unwrap_or_default(),
units: self.units,
lectures: self.lectures,
learning_objectives: self.objectives,
learning_targets: self.targets,
references: self.references,
stimuli: self.stimuli,
origins: self.origins,
})
}
}
/// Moves one section's entries across, refusing a second definition.
fn absorb<T>(
into: &mut BTreeMap<String, T>,
from: BTreeMap<String, T>,
section: Section,
path: &Path,
origins: &mut BTreeMap<(Section, String), PathBuf>,
issues: &mut Vec<String>,
) {
for (id, value) in from {
let key = (section, id.clone());
if let Some(first) = origins.get(&key) {
issues.push(duplicate(section, &id, first.as_path(), path));
continue;
}
origins.insert(key, path.to_path_buf());
into.insert(id, value);
}
}
/// The message for an id defined in two files.
fn duplicate(section: Section, id: &str, first: &Path, second: &Path) -> String {
format!(
"{} `{id}` is defined in two places: {} and {}. An id has one definition site; delete \
one or rename it.",
section.noun(),
first.display(),
second.display()
)
}
/// The part of a schema version before the first dot.
fn major(version: &str) -> &str {
version.split('.').next().unwrap_or(version)
}
#[cfg(test)]
mod tests {
use super::*;
fn tmp(tag: &str) -> PathBuf {
let p = std::env::temp_dir().join(format!("coursebank-frag-{tag}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&p);
std::fs::create_dir_all(&p).unwrap();
p
}
fn write(root: &Path, relative: &str, body: &str) {
let path = root.join(relative);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, body).unwrap();
}
const ROOT: &str = r#"
course:
code: BIOSC 1540
title: Computational Biology
term: 2026f
policy:
points_per_item: 1.0
units:
- id: u1
title: Search and Similarity
"#;
#[test]
fn a_split_course_merges_into_one_model() {
let root = tmp("merge");
write(&root, "course.yaml", ROOT);
write(
&root,
"references.yaml",
"references:\n ismail2023:\n title: Bioinformatics\n",
);
write(
&root,
"lectures/l-1-2.yaml",
"lectures:\n L1.2:\n title: The Digital Genome\n unit: u1\n \
teaches: [lo-read-file-formats]\n",
);
write(
&root,
"objectives/lo-read-file-formats.yaml",
"learning_objectives:\n lo-read-file-formats:\n text: Read the text formats.\n \
unit: u1\nlearning_targets:\n t-fastq-structure:\n text: Identify the four \
lines.\n objective: lo-read-file-formats\n",
);
let course = assemble(&root).unwrap();
assert_eq!(course.course.code, "BIOSC 1540");
assert_eq!(course.units.len(), 1);
assert_eq!(course.references.len(), 1);
assert!(course.validate().is_empty(), "{:?}", course.validate());
// Derived: the lecture registered the objective, and the target
// inherited the objective's lecture.
assert_eq!(
course.learning_objectives["lo-read-file-formats"].lectures,
vec!["L1.2".to_string()]
);
assert_eq!(
course.learning_targets["t-fastq-structure"].lectures,
vec!["L1.2".to_string()]
);
assert_eq!(course.lecture_targets("L1.2"), vec!["t-fastq-structure"]);
}
#[test]
fn an_unsplit_course_file_still_loads() {
let root = tmp("monolith");
write(
&root,
"course.yaml",
&format!(
"{ROOT}lectures:\n L1.2:\n title: The Digital Genome\nlearning_objectives:\n \
lo-x:\n text: Do the thing.\n lectures: [L1.2]\nlearning_targets:\n \
t-x:\n text: Do the smaller thing.\n objective: lo-x\nreferences:\n \
ismail2023:\n title: Bioinformatics\n"
),
);
let course = assemble(&root).unwrap();
assert!(course.validate().is_empty(), "{:?}", course.validate());
assert_eq!(course.lecture_objectives("L1.2"), vec!["lo-x"]);
assert_eq!(
course.origin("lo-x").map(|(_, p)| p.to_path_buf()),
Some(PathBuf::from(COURSE_FILE))
);
}
#[test]
fn an_id_defined_twice_names_both_files() {
let root = tmp("dup");
write(&root, "course.yaml", ROOT);
let body = "learning_objectives:\n lo-x:\n text: Do the thing.\n";
write(&root, "objectives/lo-x.yaml", body);
write(&root, "objectives/lo-x-old.yaml", body);
let err = assemble(&root).unwrap_err();
let message = err.to_string();
assert!(message.contains("objectives/lo-x.yaml"), "{message}");
assert!(message.contains("objectives/lo-x-old.yaml"), "{message}");
assert!(message.contains("one definition site"), "{message}");
}
#[test]
fn a_section_in_the_wrong_kind_of_file_is_rejected() {
let root = tmp("misplaced");
write(&root, "course.yaml", ROOT);
write(
&root,
"lectures/l-1-2.yaml",
"lectures:\n L1.2:\n title: The Digital Genome\nlearning_objectives:\n lo-x:\n \
text: Do the thing.\n",
);
let message = assemble(&root).unwrap_err().to_string();
assert!(
message.contains("may not define `learning_objectives`"),
"{message}"
);
assert!(message.contains("objectives/*.yaml"), "{message}");
}
#[test]
fn a_course_with_no_identity_says_so() {
let root = tmp("no-course");
write(&root, "course.yaml", "units:\n - id: u1\n title: One\n");
let message = assemble(&root).unwrap_err().to_string();
assert!(message.contains("`course:` section"), "{message}");
}
#[test]
fn a_fragment_from_another_major_version_is_refused() {
let root = tmp("version");
write(&root, "course.yaml", ROOT);
write(
&root,
"objectives/lo-x.yaml",
"schema_version: '9.0'\nlearning_objectives:\n lo-x:\n text: Do the thing.\n",
);
let message = assemble(&root).unwrap_err().to_string();
assert!(message.contains("schema_version 9.0"), "{message}");
}
#[test]
fn origins_point_at_the_fragment_that_defined_each_id() {
let root = tmp("origins");
write(&root, "course.yaml", ROOT);
write(
&root,
"lectures/l-1-2.yaml",
"lectures:\n L1.2:\n title: The Digital Genome\n",
);
write(
&root,
"objectives/lo-x.yaml",
"learning_objectives:\n lo-x:\n text: Do the thing.\n",
);
let course = assemble(&root).unwrap();
let (section, path) = course.origin("lo-x").unwrap();
assert_eq!(section, Section::Objectives);
assert_eq!(path, Path::new("objectives/lo-x.yaml"));
let (section, path) = course.origin("L1.2").unwrap();
assert_eq!(section, Section::Lectures);
assert_eq!(path, Path::new("lectures/l-1-2.yaml"));
assert!(course.origin("nothing-like-this").is_none());
}
#[test]
fn teaching_the_same_objective_from_two_lectures_unions() {
let root = tmp("union");
write(&root, "course.yaml", ROOT);
write(
&root,
"lectures/l-1-2.yaml",
"lectures:\n L1.2:\n title: One\n teaches: [lo-x]\n",
);
write(
&root,
"lectures/l-1-3.yaml",
"lectures:\n L1.3:\n title: Two\n teaches: [lo-x]\n",
);
write(
&root,
"objectives/lo-x.yaml",
"learning_objectives:\n lo-x:\n text: Do the thing.\n",
);
let course = assemble(&root).unwrap();
assert_eq!(
course.learning_objectives["lo-x"].lectures,
vec!["L1.2".to_string(), "L1.3".to_string()]
);
}
#[test]
fn a_declaration_on_both_sides_is_not_duplicated() {
let root = tmp("both-sides");
write(&root, "course.yaml", ROOT);
write(
&root,
"lectures/l-1-2.yaml",
"lectures:\n L1.2:\n title: One\n teaches: [lo-x]\n",
);
write(
&root,
"objectives/lo-x.yaml",
"learning_objectives:\n lo-x:\n text: Do the thing.\n lectures: [L1.2]\n",
);
let course = assemble(&root).unwrap();
assert_eq!(
course.learning_objectives["lo-x"].lectures,
vec!["L1.2".to_string()]
);
}
#[test]
fn teaching_an_unknown_objective_is_a_validation_problem_not_a_merge_one() {
let root = tmp("unknown-teaches");
write(&root, "course.yaml", ROOT);
write(
&root,
"lectures/l-1-2.yaml",
"lectures:\n L1.2:\n title: One\n teaches: [lo-nope]\n",
);
let course = assemble(&root).unwrap();
let issues = course.validate();
assert!(issues.iter().any(|i| i.contains("lo-nope")), "{issues:?}");
}
}
+151 -18
View File
@@ -25,6 +25,7 @@ use serde::de::{self, MapAccess, Visitor};
use serde::ser::SerializeMap;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use crate::course::Reference;
use crate::date::Date;
use crate::hash::fingerprint;
use crate::taxonomy::{
@@ -44,9 +45,28 @@ pub struct Item {
/// Revision counter, bumped whenever the content changes in a way that
/// invalidates pooled statistics.
#[serde(default = "one_u32")]
/// Retained only so a pre-2.0 bank still loads. Ignored.
///
/// A version number on a question answered the wrong question. It recorded
/// that *something* changed without constraining what, which meant an item
/// at version 3 might have a reworded distractor — fair, the statistics
/// still describe the same question — or a reworded stem, which makes it a
/// different question wearing the same id. Since 2.0 the stem *is* the
/// identity: reword it and you have a new item, with a new id and
/// [`Item::supersedes`] pointing back. [`Item::stem_digest`] is what
/// enforces that, against the seals of every administration.
///
/// `coursebank migrate stems` removes it.
#[serde(default, skip_serializing)]
pub version: u32,
/// The item this one replaces, when it is a rewording of an earlier stem.
///
/// Lineage rather than versioning: both items stay in the bank, each with
/// its own statistics, and a report can say which one a cohort answered.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub supersedes: Option<String>,
/// Workflow state; only [`Status::Approved`] items may be assembled.
pub status: Status,
@@ -145,7 +165,16 @@ pub struct Item {
pub review: Option<Review>,
/// Append-only change log.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
/// Retained only so a pre-2.0 bank still loads. Ignored.
///
/// A hand-maintained change log inside a version-controlled file, every
/// entry of which duplicated what `git log -p` already knew, with no
/// guarantee of agreeing with it. What git cannot express is a claim about
/// the item rather than a record of an edit, and that has its own fields:
/// [`Item::retired`] and [`Item::supersedes`].
///
/// `coursebank migrate stems` removes it.
#[serde(default, skip_serializing)]
pub history: Vec<HistoryEntry>,
/// The author of record.
@@ -170,7 +199,17 @@ pub struct Item {
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Choice {
/// Option letter, `A` through `H`.
/// The option's id, unique within its item: `o-fourth-line`.
///
/// A name rather than a position. Until 2.0 this was a letter, which put a
/// position in a field that pooled statistics, student feedback, and
/// `credit_overrides` all join on — so reordering a YAML block silently
/// moved the misconception recorded against one option onto another. The
/// letter a student sees is derived per form from the form's seed and lives
/// in the seal; see [`crate::seal::printed_letter`].
///
/// A single letter `A` through `H` still loads, so a bank migrates when you
/// run `coursebank migrate options` rather than when you upgrade.
pub id: String,
/// The option text.
@@ -319,6 +358,19 @@ impl Citation {
(None, None) => String::new(),
}
}
/// The link for this location, resolved against the work it points into.
///
/// # Arguments
///
/// * `reference` - the work, looked up from the citation key.
///
/// # Returns
///
/// The most specific link available. See [`Reference::href`].
pub fn href(&self, reference: &Reference) -> Option<String> {
reference.href(self.url.as_deref(), self.path.as_deref())
}
}
/// Writes a citation as a mapping, or as a bare string when that is all it holds.
@@ -661,7 +713,7 @@ pub struct Retirement {
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HistoryEntry {
/// The version this change produced.
/// The version this change produced. Ignored since 2.0.
pub version: u32,
/// When it was made.
pub date: Date,
@@ -672,6 +724,32 @@ pub struct HistoryEntry {
pub change: String,
}
/// The separator a pre-2.0 bank-qualified item id used: `b-1-2::q-fastq-line`.
pub const LEGACY_QUALIFIER: &str = "::";
/// An item id with any pre-2.0 bank qualifier removed.
///
/// Until 2.0 an item was named `bank::item`, which made the file it happened to
/// live in part of its identity — and therefore part of the join key on every
/// row of response data ever collected. Moving a question between banks renamed
/// it. Since 2.0 the id names the item course-wide and the bank is only where it
/// is kept, so anything reading an old id strips the qualifier rather than
/// failing to match.
///
/// # Arguments
///
/// * `id` - an item id in either form.
///
/// # Returns
///
/// The part after the qualifier, or the whole id when there is none.
pub fn canonical_id(id: &str) -> &str {
match id.split_once(LEGACY_QUALIFIER) {
Some((_, rest)) => rest,
None => id,
}
}
impl Item {
/// Builds a draft item with everything optional left empty.
///
@@ -725,6 +803,7 @@ impl Item {
author: None,
notes_private: None,
retired: None,
supersedes: None,
}
}
@@ -758,19 +837,38 @@ impl Item {
out
}
/// Looks up an option by letter.
/// Looks up an option by id.
///
/// # Arguments
///
/// * `letter` - the option id, case insensitive.
/// * `id` - the option id. A pre-2.0 letter matches case-insensitively,
/// which a slug never needs but a hand-typed `d` does.
///
/// # Returns
///
/// The option, or `None`.
pub fn option(&self, letter: &str) -> Option<&Choice> {
pub fn option(&self, id: &str) -> Option<&Choice> {
self.options
.iter()
.find(|o| o.id.eq_ignore_ascii_case(letter))
.find(|o| o.id == id)
.or_else(|| self.options.iter().find(|o| o.id.eq_ignore_ascii_case(id)))
}
/// Whether an option id is a pre-2.0 letter rather than a name.
///
/// # Arguments
///
/// * `id` - the option id.
///
/// # Returns
///
/// `true` for `A` through `H`.
pub fn is_legacy_option_id(id: &str) -> bool {
id.len() == 1
&& id
.chars()
.next()
.is_some_and(|c| c.is_ascii_uppercase() && c <= 'H')
}
/// Whether the item keys more than one option.
@@ -834,6 +932,29 @@ impl Item {
fingerprint(parts.iter().map(|s| s.as_str()))
}
/// A digest of what the item asks, without its options.
///
/// The identity check. [`Item::fingerprint`] covers the options too, which
/// is right for calibration — reword a distractor and the pooled selection
/// rates no longer describe what students saw — but wrong for identity,
/// because a question whose distractors changed is still the same question.
/// This covers the stem and the stimulus, and nothing else.
///
/// Compared against the digest each seal recorded, which is what makes
/// "a reworded stem is a new stem" a rule the tool enforces rather than a
/// convention that decays.
///
/// # Returns
///
/// The digest as hex.
pub fn stem_digest(&self) -> String {
let mut parts: Vec<String> = vec![self.stem.trim().to_string()];
if let Some(s) = &self.stimulus {
parts.push(format!("stimulus:{s}"));
}
fingerprint(parts.iter().map(|s| s.as_str()))
}
/// Whether the recorded calibration matches the current content.
///
/// # Returns
@@ -889,16 +1010,20 @@ impl Item {
}
}
/// Appends a change-log entry and bumps the version.
/// Appends a change-log entry.
///
/// Kept for the pre-2.0 banks that still carry a `history:` block, so
/// reading one and writing it back does not silently drop entries. New
/// entries belong in a commit message.
///
/// # Arguments
///
/// * `change` - a description of what changed.
/// * `author` - who made the change.
pub fn record_change(&mut self, change: &str, author: Option<&str>) {
self.version += 1;
let version = self.history.iter().map(|h| h.version).max().unwrap_or(0) + 1;
self.history.push(HistoryEntry {
version: self.version,
version,
date: Date::today(),
author: author.map(|a| a.to_string()),
change: change.to_string(),
@@ -906,9 +1031,6 @@ impl Item {
}
}
fn one_u32() -> u32 {
1
}
fn default_format() -> Format {
Format::SingleBestAnswer
}
@@ -938,7 +1060,6 @@ options:
#[test]
fn minimal_item_parses_with_defaults() {
let it = item(MINIMAL);
assert_eq!(it.version, 1);
assert_eq!(it.format, Format::SingleBestAnswer);
assert!(!it.bonus);
assert_eq!(it.key_letters(), vec!["A"]);
@@ -1053,12 +1174,24 @@ options:
}
#[test]
fn record_change_bumps_version_and_logs() {
fn the_stem_is_the_identity_rather_than_a_version_number() {
let mut it = item(MINIMAL);
let before = it.stem_digest();
// A change log entry numbers itself and leaves the item alone: since
// 2.0 nothing reads `version`, and rewording a stem is not a version
// bump but a new item.
it.record_change("clarified the stem", Some("Alex"));
assert_eq!(it.version, 2);
assert_eq!(it.version, 0);
assert_eq!(it.history.len(), 1);
assert_eq!(it.history[0].version, 2);
assert_eq!(it.history[0].version, 1);
assert_eq!(it.stem_digest(), before);
// The options are the fingerprint's business, not the stem's.
it.options[1].text = "a different distractor".into();
assert_eq!(it.stem_digest(), before);
it.stem = "What is y?".into();
assert_ne!(it.stem_digest(), before);
}
#[test]
+26
View File
@@ -3,6 +3,11 @@
// Source: https://git.scient.ing/education/coursebank
//! The on-disk layout of a course directory.
//!
//! Two of these directories hold fragments of the course file rather than files
//! of their own kind: `lectures/` and `objectives/` are merged into one
//! [`crate::course::CourseFile`] on load, along with `references.yaml`. See
//! [`crate::course::fragment`].
use std::path::PathBuf;
@@ -35,6 +40,25 @@ impl Layout {
self.root.join(COURSE_FILE)
}
/// Path to `references.yaml`, the bibliography when it is kept out of
/// `course.yaml`.
///
/// Optional: absent means the course keeps its `references:` section in the
/// course file, which is how an unsplit course is arranged.
pub fn references_file(&self) -> PathBuf {
self.root.join(crate::course::fragment::REFERENCES_FILE)
}
/// Directory holding one file per lecture.
pub fn lectures(&self) -> PathBuf {
self.root.join("lectures")
}
/// Directory holding one file per learning objective.
pub fn objectives(&self) -> PathBuf {
self.root.join("objectives")
}
/// Directory holding item bank YAML files.
pub fn banks(&self) -> PathBuf {
self.root.join("banks")
@@ -93,6 +117,8 @@ impl Layout {
pub fn create_all(&self) -> Result<()> {
for dir in [
self.root.clone(),
self.lectures(),
self.objectives(),
self.banks(),
self.assessments(),
self.data(),
+44 -1
View File
@@ -145,8 +145,16 @@ pub struct SealedItem {
/// The item's global id.
pub item: String,
/// The item version as administered.
/// Retained only so a pre-2.0 seal still loads. Ignored when reasoning
/// about the item, but still written: [`SealFile::digest_input`] covers it,
/// so dropping it on a round trip would invalidate the digest of every
/// administration sealed before 2.0.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub version: Option<u32>,
/// The stem's digest as administered.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub stem_digest: Option<String>,
/// The item's content fingerprint, the same one
/// [`crate::item::Item::fingerprint`] computes, so a seal and a bank can be
/// compared without re-hashing either by hand.
@@ -484,7 +492,8 @@ fn sealed_item(
SealedItem {
number: placement.number,
item: placement.item.clone(),
version: placement.version.or(Some(item.version)),
version: None,
stem_digest: Some(item.stem_digest()),
fingerprint: item.fingerprint(),
points: placement
.points
@@ -638,6 +647,33 @@ impl SealFile {
yaml::read(path)
}
/// Loads every seal in a directory, oldest administration first.
///
/// # Arguments
///
/// * `dir` - the seals directory.
///
/// # Returns
///
/// The seals, empty when the directory does not exist.
///
/// # Errors
///
/// Propagates load failures, including a seal that does not parse.
pub fn load_all(dir: &Path) -> Result<Vec<SealFile>> {
let mut out = Vec::new();
for path in crate::yaml::list_yaml(dir)? {
out.push(SealFile::load(&path)?);
}
out.sort_by(|a, b| {
a.seal
.date
.cmp(&b.seal.date)
.then(a.seal.assessment.cmp(&b.seal.assessment))
});
Ok(out)
}
/// Loads the seal for an assessment, if one has been written.
///
/// Absence is not an error. A course that has never sealed anything should
@@ -719,6 +755,12 @@ impl SealFile {
self.schema_version, self.seal.assessment, self.seal.course, self.seal.term
));
for item in &self.items {
// Appended only when present: a seal written before 2.0 has to keep
// producing the input it was digested from, or every older
// administration fails verification.
if let Some(stem) = &item.stem_digest {
buf.push_str(&format!("stem\u{1f}{}\u{1f}{stem}\n", item.number));
}
buf.push_str(&format!(
"item\u{1f}{}\u{1f}{}\u{1f}{}\u{1f}{}\u{1f}{}\u{1f}{}\u{1f}{}\u{1f}{}\u{1f}",
item.number,
@@ -1157,6 +1199,7 @@ mod tests {
number: 1,
item: "b::q-1".into(),
version: Some(1),
stem_digest: None,
fingerprint: "abc".into(),
points: 1.0,
bonus: false,