feat: splitting
This commit is contained in:
29 files changed
+4843
-234
No files matched your search
+19
-2
@@ -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
@@ -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
@@ -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
@@ -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(
|
||||
|
||||
@@ -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
@@ -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]
|
||||
|
||||
@@ -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
@@ -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,
|
||||
|
||||
Reference in new issue
Block a user