Correct answer ", + ); + out.push_str(&keyed.join("; ")); + out.push_str("
\n"); + + if let Some(solution) = item.solution.as_ref() { + if let Some(model) = &solution.model_answer { + out.push_str(&format!( + "{}
\n", + inline_html(explanation) + )); + } + } + + let distractors: Vec<(usize, &Choice)> = printed + .iter() + .copied() + .filter(|(_, c)| !c.correct) + .collect(); + if distractors + .iter() + .any(|(_, c)| c.misconception.is_some() || why_wrong(c).is_some()) + { + out.push_str("Why the other options miss
\n"); + out.push_str("| Pts | Criterion |
|---|---|
| {pts} | {} |
Also accepted {joined}
\n" + )); + } + + push_reference(&mut out, course, Some(solution)); + Some(out) +} + +/// The student-facing reason a distractor is wrong: the instructor explanation +/// first, then any student feedback. +fn why_wrong(choice: &Choice) -> Option<&str> { + choice + .explanation + .as_deref() + .or(choice.feedback_student.as_deref()) +} + +/// Appends the `Source:` line when the solution carries review citations. +fn push_reference(out: &mut String, course: &CourseFile, solution: Option<&Solution>) { + let Some(solution) = solution else { return }; + if solution.review.is_empty() { + return; + } + let sources = solution + .review + .iter() + .map(|c| cite_html(course, c)) + .collect::Source: {sources}
\n")); +} + +/// Renders one citation to HTML, linking it when a URL resolves. +fn cite_html(course: &CourseFile, citation: &Citation) -> String { + if let Some(text) = &citation.text { + if citation.reference.is_none() { + return markup::escape_html(text); + } + } + let Some(key) = &citation.reference else { + return markup::escape_html(&citation.display()); + }; + let Some(reference) = course.references.get(key) else { + return markup::escape_html(&citation.display()); + }; + let label = reference.label.as_deref().unwrap_or(key); + let locator = citation.locator.as_deref().unwrap_or(""); + let body = if locator.is_empty() { + markup::escape_html(label) + } else { + format!( + "{} {}", + markup::escape_html(label), + markup::escape_html(locator) + ) + }; + match resolve_url(citation, reference) { + Some(url) => format!("{body}", markup::escape_html(&url)), + None => body, + } +} + +/// Resolves a citation's link, from an explicit URL or a path joined to the +/// reference's base URL. +fn resolve_url(citation: &Citation, reference: &Reference) -> Option`. +fn block_html(src: &str) -> String { + src.split("\n\n") + .map(str::trim) + .filter(|p| !p.is_empty()) + .map(|p| format!("
{}
", inline_html(p))) + .collect::The change in enthalpy, $\\Delta H$.
Source: KKW §6.3
")); + } + + #[test] + fn an_open_fragment_has_a_rubric_table_with_a_total() { + let cat = catalog("open"); + let rec = record(); + let frags = solution_fragments(&cat, &rec, &form()).unwrap(); + let open = &frags.iter().find(|(id, _)| id == "q-open").unwrap().1; + assert!(open.contains("alpha
".to_string()), + ("q-open".to_string(), "beta
".to_string()), + ]; + let bundle = build_bundle("a1.1", "enthalpy2026", &fragments).unwrap(); + assert_eq!(bundle.v, 1); + assert_eq!(bundle.page, "a1.1"); + assert_eq!(bundle.cipher, "AES-GCM"); + assert_eq!(bundle.kdf.iterations, ITERATIONS); + // Insertion order is preserved in the serialized object. + let json = serde_json::to_string(&bundle).unwrap(); + assert!(json.find("q-mcq").unwrap() < json.find("q-open").unwrap()); + + // Decrypt the first item the way the browser would and check the plaintext. + let salt = B64.decode(&bundle.kdf.salt).unwrap(); + let key = derive_key("enthalpy2026", &salt); + let cipher = Aes256Gcm::new_from_slice(&key).unwrap(); + let (_, enc) = &bundle.items.0[0]; + let iv = B64.decode(&enc.iv).unwrap(); + let ct = B64.decode(&enc.ct).unwrap(); + let pt = cipher + .decrypt(GenericArray::from_slice(&iv), ct.as_ref()) + .unwrap(); + assert_eq!(String::from_utf8(pt).unwrap(), "alpha
"); + } + + #[test] + fn a_generated_password_has_the_expected_shape() { + let pw = gen_password().unwrap(); + assert_eq!(pw.len(), 19); // 16 symbols + 3 dashes + assert_eq!(pw.matches('-').count(), 3); + assert!( + pw.chars() + .all(|c| c == '-' || PW_ALPHABET.contains(&(c as u8))) + ); + } + + #[test] + fn the_two_browser_assets_are_bundled() { + let assets = assets(); + assert_eq!(assets[0].0, "questions.css"); + assert_eq!(assets[1].0, "solutions.js"); + assert!(assets[0].1.contains(".qsol")); + assert!(assets[1].1.contains("AES-GCM")); + } +} diff --git a/src/guide.rs b/src/guide.rs index b0b99a8..490a0aa 100644 --- a/src/guide.rs +++ b/src/guide.rs @@ -21,7 +21,9 @@ //! 3. [`first_exam`] runs one exam end to end: assemble, export, administer, //! ingest, analyze, report. //! 4. [`typst_export`] covers printed output, template markers, and render config. -//! 5. [`recipes`] holds short answers to specific questions, for when you already +//! 5. [`assignment`] publishes a homework to the course website, with solutions +//! gated behind a password. +//! 6. [`recipes`] holds short answers to specific questions, for when you already //! know the shape of the tool. //! //! ## Why the tutorials are in here rather than a wiki @@ -55,6 +57,10 @@ pub mod first_exam {} #[doc = include_str!("../docs/TYPST.md")] pub mod typst_export {} +/// Publishing an assignment to the website, with solutions gated behind a password. +#[doc = include_str!("../docs/guide/assignment.md")] +pub mod assignment {} + /// Short answers to specific questions. #[doc = include_str!("../docs/guide/recipes.md")] pub mod recipes {} diff --git a/src/lib.rs b/src/lib.rs index 766de78..4782d67 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -104,12 +104,12 @@ pub use model::{assessment, bank, catalog, course, history, item, layout, taxono pub use authoring::{jsonschema, lint, select}; -#[cfg(feature = "parquet")] pub use data::store_parquet; pub use data::{canvas, gradescope, responses, store}; pub use analysis::{calibrate, classical, irt, students}; +pub use export::site; pub use export::{lecture, practice, qti, report, typst}; pub use catalog::Catalog; diff --git a/src/model/bank.rs b/src/model/bank.rs index a09b58d..9efd32f 100644 --- a/src/model/bank.rs +++ b/src/model/bank.rs @@ -352,7 +352,7 @@ fn validate_item( issues.push("version must be at least 1".into()); } - // --- options --- + // --- options ---- // An open-response item takes no options; its answer lives in `solution`. // Every other format needs at least two things to choose between. if it.format.has_options() { @@ -428,7 +428,7 @@ fn validate_item( } } - // --- key ----- + // --- key --- let keys = it.key_indices(); match it.format { Format::SingleBestAnswer => { @@ -465,7 +465,7 @@ fn validate_item( } } - // --- level and process must agree -------- + // --- level and process must agree ------- if let Some(p) = it.cognitive_process { if !it.level.allows(p) { issues.push(format!( @@ -476,7 +476,7 @@ fn validate_item( } } - // --- design plausibility ----------- + // --- design plausibility ------ if let Some(d) = &it.design { if let Some(x) = d.expected_difficulty { if !(0.0..=1.0).contains(&x) { @@ -548,7 +548,7 @@ fn validate_item( )); } - // --- retirement ---- + // --- retirement ----- if it.retired.is_some() && it.status != Status::Retired { issues.push(format!( "has a `retired` block but status is `{}`", @@ -588,7 +588,7 @@ fn validate_item( } } - // --- cross-file references --------- + // --- cross-file references ---- if let Some(c) = course { for lo in &it.learning_objectives { match c.learning_objectives.get(lo) { diff --git a/src/util/markup.rs b/src/util/markup.rs index 2a32663..ea99217 100644 --- a/src/util/markup.rs +++ b/src/util/markup.rs @@ -199,7 +199,7 @@ pub fn escape_html(s: &str) -> String { /// # Returns /// /// The substituted text. -fn apply_symbols(s: &str, html: bool) -> String { +pub(crate) fn apply_symbols(s: &str, html: bool) -> String { let mut out = s.to_string(); for (token, entity, plain) in SYMBOLS { if out.contains(token) { @@ -218,7 +218,7 @@ fn apply_symbols(s: &str, html: bool) -> String { /// # Returns /// /// The text with inline markup converted. -fn apply_inline(s: &str) -> String { +pub(crate) fn apply_inline(s: &str) -> String { let mut out = s.to_string(); // Bracketed forms first: their contents may contain other markup characters. out = wrap_bracket(&out, "#sub[", "", "");