feat(schema): 2.1 types, fragments, and JSON Schemas
Add the term, equation, value, and misconception registries (src/model/course/glossary.rs) and the new optional fields on objectives, targets, lectures, readings, bank options, and policy. Load registry entries from objective files, glossary.yaml, and course.yaml, with one definition site per id as for every other registry. Port every edit in docs/design/2.1/build_schemas.py into the hand-written schema builders, add glossary.schema.json, and test the generated schemas against the targets; the only differences are two 2.0 spellings the code already had. The 2.0 example fragments load and validate unchanged. The 2.1 example bank gains `status: draft`, which every coursebank item requires. tests/docs.rs skips docs/design/, which holds design records rather than guide pages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
47 files changed
+10568
-55
No files matched your search
@@ -38,6 +38,10 @@ fn root() -> PathBuf {
|
||||
|
||||
/// Every `.md` file under `docs/`, sorted so failures are reported in a stable
|
||||
/// order.
|
||||
///
|
||||
/// `docs/design/` is skipped. It holds design records (a specification, its
|
||||
/// examples, an implementation plan), which are read in the repository rather
|
||||
/// than compiled into the guide, and whose example output is quoted as written.
|
||||
fn markdown_files(dir: &Path, out: &mut Vec<PathBuf>) {
|
||||
let Ok(entries) = std::fs::read_dir(dir) else {
|
||||
return;
|
||||
@@ -45,6 +49,9 @@ fn markdown_files(dir: &Path, out: &mut Vec<PathBuf>) {
|
||||
let mut paths: Vec<PathBuf> = entries.filter_map(|e| e.ok()).map(|e| e.path()).collect();
|
||||
paths.sort();
|
||||
for path in paths {
|
||||
if path.ends_with("docs/design") {
|
||||
continue;
|
||||
}
|
||||
if path.is_dir() {
|
||||
markdown_files(&path, out);
|
||||
} else if path.extension().is_some_and(|e| e == "md") {
|
||||
|
||||
@@ -0,0 +1,275 @@
|
||||
// SPDX-License-Identifier: Prosperity-3.0.0
|
||||
// Copyright Scienting
|
||||
// Source: https://git.scient.ing/education/coursebank
|
||||
|
||||
//! The 2.1 schema against its specification in `docs/design/2.1/`.
|
||||
//!
|
||||
//! The examples there are the fixtures, read in place, so the specification and
|
||||
//! these tests cannot drift apart: `examples/v20/` must load unchanged,
|
||||
//! `examples/v21/` uses every new field, and `schemas/` is the JSON Schema each
|
||||
//! generated file must equal.
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use coursebank::catalog::Catalog;
|
||||
use coursebank::course::CourseFile;
|
||||
use coursebank::jsonschema::{self, Kind};
|
||||
use serde_json::Value;
|
||||
|
||||
/// `docs/design/2.1/`.
|
||||
fn design() -> PathBuf {
|
||||
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("docs/design/2.1")
|
||||
}
|
||||
|
||||
/// A fresh, empty directory under the system temp dir.
|
||||
fn scratch(tag: &str) -> PathBuf {
|
||||
let dir = std::env::temp_dir().join(format!("coursebank-2-1-{tag}-{}", std::process::id()));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
dir
|
||||
}
|
||||
|
||||
/// Copies a directory tree.
|
||||
fn copy_tree(from: &Path, to: &Path) {
|
||||
std::fs::create_dir_all(to).unwrap();
|
||||
for entry in std::fs::read_dir(from).unwrap() {
|
||||
let path = entry.unwrap().path();
|
||||
let target = to.join(path.file_name().unwrap());
|
||||
if path.is_dir() {
|
||||
copy_tree(&path, &target);
|
||||
} else {
|
||||
std::fs::copy(&path, &target).unwrap();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The JSON pointers at which two values differ.
|
||||
fn differences(path: &str, generated: &Value, target: &Value, out: &mut Vec<String>) {
|
||||
match (generated, target) {
|
||||
(Value::Object(a), Value::Object(b)) => {
|
||||
for key in a.keys().chain(b.keys().filter(|k| !a.contains_key(*k))) {
|
||||
let here = format!("{path}/{}", key.replace('~', "~0").replace('/', "~1"));
|
||||
match (a.get(key), b.get(key)) {
|
||||
(Some(x), Some(y)) => differences(&here, x, y, out),
|
||||
(Some(_), None) => out.push(format!("{here} (only generated)")),
|
||||
(None, Some(_)) => out.push(format!("{here} (only in the target)")),
|
||||
(None, None) => {}
|
||||
}
|
||||
}
|
||||
}
|
||||
(Value::Array(a), Value::Array(b)) if a.len() == b.len() => {
|
||||
for (i, (x, y)) in a.iter().zip(b).enumerate() {
|
||||
differences(&format!("{path}/{i}"), x, y, out);
|
||||
}
|
||||
}
|
||||
_ if generated == target => {}
|
||||
_ => out.push(path.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Differences that are known and kept, with the reason.
|
||||
///
|
||||
/// Both are spellings in 2.0 descriptions that the code already had before 2.1:
|
||||
/// `schemas-original/` was generated by a build that spelled them the American
|
||||
/// way, and the 2.1 targets were built from it.
|
||||
const KNOWN: &[(&str, &str)] = &[
|
||||
(
|
||||
"calibration.schema.json",
|
||||
"/properties/items/additionalProperties/properties/variants/items/properties/option_stats\
|
||||
/description",
|
||||
),
|
||||
(
|
||||
"course.schema.json",
|
||||
"/properties/policy/properties/grade_scale/items/properties/group/description",
|
||||
),
|
||||
];
|
||||
|
||||
#[test]
|
||||
fn every_generated_schema_matches_its_target() {
|
||||
let mut unexpected = Vec::new();
|
||||
for kind in Kind::ALL {
|
||||
let name = kind.filename();
|
||||
let text = std::fs::read_to_string(design().join("schemas").join(name))
|
||||
.unwrap_or_else(|e| panic!("{name}: {e}"));
|
||||
let target: Value = serde_json::from_str(&text).unwrap();
|
||||
let mut found = Vec::new();
|
||||
differences("", &jsonschema::schema(kind), &target, &mut found);
|
||||
for pointer in found {
|
||||
if !KNOWN.iter().any(|(file, p)| *file == name && *p == pointer) {
|
||||
unexpected.push(format!("{name}: {pointer}"));
|
||||
}
|
||||
}
|
||||
}
|
||||
assert!(
|
||||
unexpected.is_empty(),
|
||||
"generated schemas differ from docs/design/2.1/schemas:\n {}",
|
||||
unexpected.join("\n ")
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_known_differences_are_still_there() {
|
||||
// If one of these is fixed, the allow-list should shrink with it.
|
||||
for (file, pointer) in KNOWN {
|
||||
let kind = Kind::ALL
|
||||
.into_iter()
|
||||
.find(|k| k.filename() == *file)
|
||||
.unwrap();
|
||||
let generated = jsonschema::schema(kind);
|
||||
let text = std::fs::read_to_string(design().join("schemas").join(file)).unwrap();
|
||||
let target: Value = serde_json::from_str(&text).unwrap();
|
||||
assert_ne!(
|
||||
generated.pointer(pointer),
|
||||
target.pointer(pointer),
|
||||
"{file}{pointer}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// The 2.0 fragments, completed into a course with the ids they cite.
|
||||
fn v20_course(tag: &str) -> PathBuf {
|
||||
let root = scratch(tag);
|
||||
std::fs::write(
|
||||
root.join("course.yaml"),
|
||||
"schema_version: '2.0'\ncourse: { code: BIOSC 1540, title: Computational Biology, term: \
|
||||
2026f }\nunits: [{ id: u1, title: Sequences and alignment }]\nreferences:\n \
|
||||
durbin1998biological: { title: Biological Sequence Analysis }\n",
|
||||
)
|
||||
.unwrap();
|
||||
std::fs::create_dir_all(root.join("lectures")).unwrap();
|
||||
std::fs::create_dir_all(root.join("objectives")).unwrap();
|
||||
let v20 = design().join("examples/v20");
|
||||
std::fs::copy(v20.join("l09.yaml"), root.join("lectures/l09.yaml")).unwrap();
|
||||
std::fs::copy(
|
||||
v20.join("lo-alignment-recurrence.yaml"),
|
||||
root.join("objectives/lo-alignment-recurrence.yaml"),
|
||||
)
|
||||
.unwrap();
|
||||
std::fs::write(
|
||||
root.join("objectives/lo-alignment-scoring.yaml"),
|
||||
"learning_objectives:\n lo-alignment-scoring: { text: Score an alignment., unit: u1, \
|
||||
level_ceiling: 3 }\nlearning_targets:\n t-align-matrix-terms: { text: Define the \
|
||||
matrix., objective: lo-alignment-scoring, level_ceiling: 1 }\n \
|
||||
t-align-local-vs-global: { text: Compare local and global., objective: \
|
||||
lo-alignment-scoring, level_ceiling: 2 }\n",
|
||||
)
|
||||
.unwrap();
|
||||
root
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_2_0_fragments_load_and_validate_unchanged() {
|
||||
let root = v20_course("v20-load");
|
||||
let course = CourseFile::load_dir(&root).expect("2.0 fragments load");
|
||||
let issues = course.validate();
|
||||
assert!(issues.is_empty(), "{issues:#?}");
|
||||
assert!(course.terms.is_empty() && course.equations.is_empty());
|
||||
}
|
||||
|
||||
/// The 2.1 example course, copied so a test may change it.
|
||||
pub fn v21_course(tag: &str) -> PathBuf {
|
||||
let root = scratch(tag);
|
||||
copy_tree(&design().join("examples/v21"), &root);
|
||||
let _ = std::fs::remove_file(root.join("lecture-page-preview.md"));
|
||||
root
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_2_1_example_loads_every_new_field() {
|
||||
let root = v21_course("v21-load");
|
||||
let catalog = Catalog::load(&root).expect("the 2.1 example loads");
|
||||
let course = &catalog.course;
|
||||
|
||||
assert_eq!(course.terms.len(), 8);
|
||||
assert_eq!(course.equations.len(), 1);
|
||||
assert_eq!(course.values.len(), 2);
|
||||
assert_eq!(course.misconceptions.len(), 2);
|
||||
|
||||
// Where each entry came from: the objective file, or glossary.yaml.
|
||||
assert_eq!(
|
||||
course.origin("term-gap").map(|(_, p)| p.to_path_buf()),
|
||||
Some(PathBuf::from("objectives/lo-alignment-scoring.yaml"))
|
||||
);
|
||||
assert_eq!(
|
||||
course
|
||||
.origin("val-per-decade")
|
||||
.map(|(_, p)| p.to_path_buf()),
|
||||
Some(PathBuf::from("glossary.yaml"))
|
||||
);
|
||||
|
||||
let target = &course.learning_targets["t-align-fill-matrix"];
|
||||
assert!(target.explanation.is_some());
|
||||
assert_eq!(target.equations, vec!["eq-global-recurrence".to_string()]);
|
||||
assert!(target.authoring.as_ref().unwrap().ceiling_item.is_some());
|
||||
|
||||
let lecture = &course.lectures["l09"];
|
||||
assert!(lecture.description.is_some());
|
||||
assert_eq!(lecture.materials.len(), 3);
|
||||
assert_eq!(lecture.readings[0].minutes, Some(40));
|
||||
|
||||
let policy = &course.policy;
|
||||
assert_eq!(policy.levels["3"].name, "Application");
|
||||
assert_eq!(policy.blueprints["module"].level_counts["2"], 18);
|
||||
assert_eq!(policy.target_text_forbid.len(), 3);
|
||||
assert_eq!(
|
||||
policy.exam_conditions.as_ref().unwrap().seconds_per_item,
|
||||
Some(120.0)
|
||||
);
|
||||
|
||||
let item = catalog.get("q-align-which-scores-higher").expect("item");
|
||||
assert_eq!(
|
||||
item.item.options[1].misconception_id.as_deref(),
|
||||
Some("mis-only-matches-count")
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_migration_output_loads_as_a_glossary_fragment() {
|
||||
let root = scratch("migration-output");
|
||||
std::fs::write(
|
||||
root.join("course.yaml"),
|
||||
"course: { code: X, title: Y, term: Z }\nreferences:\n KKW: { title: The Molecules of \
|
||||
Life }\n",
|
||||
)
|
||||
.unwrap();
|
||||
std::fs::copy(
|
||||
design().join("examples/migration/glossary.expected.yaml"),
|
||||
root.join("glossary.yaml"),
|
||||
)
|
||||
.unwrap();
|
||||
let course = CourseFile::load_dir(&root).expect("loads");
|
||||
assert!(course.terms.contains_key("term-decade"));
|
||||
assert!(course.values.contains_key("val-per-decade"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_lecture_file_may_not_define_glossary_entries() {
|
||||
let root = v20_course("v20-lecture-glossary");
|
||||
std::fs::write(
|
||||
root.join("lectures/l10.yaml"),
|
||||
"lectures:\n l10: { title: Ten }\nterms:\n term-x: { term: x, definition: An x. }\n",
|
||||
)
|
||||
.unwrap();
|
||||
let message = CourseFile::load_dir(&root).unwrap_err().to_string();
|
||||
assert!(message.contains("may not define `terms`"), "{message}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_glossary_id_defined_twice_names_both_files() {
|
||||
let root = v21_course("v21-dup");
|
||||
std::fs::write(
|
||||
root.join("glossary.yaml"),
|
||||
"terms:\n term-gap: { term: gap, definition: A dash. }\n",
|
||||
)
|
||||
.unwrap();
|
||||
let message = CourseFile::load_dir(&root).unwrap_err().to_string();
|
||||
assert!(
|
||||
message.contains("term `term-gap` is defined in two places"),
|
||||
"{message}"
|
||||
);
|
||||
assert!(message.contains("glossary.yaml"), "{message}");
|
||||
assert!(
|
||||
message.contains("objectives/lo-alignment-scoring.yaml"),
|
||||
"{message}"
|
||||
);
|
||||
}
|
||||
Reference in new issue
Block a user