feat(migrate): glossary from 1.0 terms.yaml and values.yaml

`coursebank migrate glossary --terms terms.yaml --values values.yaml`
writes glossary.yaml. Ids gain their term- and val- prefixes, course
becomes term and meaning becomes definition, a value's term: gains the
prefix of the id it names, and first and lectures are dropped; each one
the targets now contradict is reported, as is each entry no target lists
yet and each field 2.1 has no place for.

Like the other migrations it copies lines, so comments, block scalars,
and flow mappings survive. Every entry is read back and compared with the
same conversion done on the parsed source, falling back to the serializer
when the copy differs. An existing glossary.yaml is added to, never
rewritten, and an entry the course already declares is skipped, so a
second run is a no-op.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
alexmandClaude committed 2026-11-16 12:23:39 -05:00
1 parent 50a1e083c1
commit 6c07122fc5
5 files changed
+1221

No files matched your search

+158
View File
@@ -0,0 +1,158 @@
// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! `coursebank migrate glossary`, against `docs/design/2.1/examples/migration/`.
//!
//! The example course's own `glossary.yaml` is that migration's output after a
//! person linked the value to its term, so each test starts from the example
//! with it removed.
mod common;
use std::path::{Path, PathBuf};
use std::process::Command;
use common::{design, edit, v21_course};
use coursebank::course::fragment::Fragment;
use coursebank::migrate;
/// The example course without its glossary.
fn course(tag: &str) -> PathBuf {
let root = v21_course(tag);
std::fs::remove_file(root.join("glossary.yaml")).unwrap();
root
}
fn source(name: &str) -> PathBuf {
design().join("examples/migration").join(name)
}
fn fragment(path: &Path) -> Fragment {
serde_yaml_ng::from_str(&std::fs::read_to_string(path).unwrap()).unwrap()
}
fn run(root: &Path, write: bool) -> migrate::GlossaryMigration {
migrate::glossary(
root,
Some(&source("terms.yaml")),
Some(&source("values.yaml")),
write,
)
.unwrap()
}
#[test]
fn migration_reproduces_the_expected_glossary() {
let root = course("mig-expected");
let report = run(&root, true);
let written = fragment(&root.join("glossary.yaml"));
let expected = fragment(&source("glossary.expected.yaml"));
assert_eq!(written.terms, expected.terms);
assert_eq!(written.values, expected.values);
// The report the expected file's header comment describes.
assert_eq!(
report.renamed,
[
("decade".to_string(), "term-decade".to_string()),
("per-decade".to_string(), "val-per-decade".to_string()),
]
);
assert_eq!(report.derived.len(), 2, "{:?}", report.derived);
assert!(report.derived[0].contains("`first` was L2.1"));
assert!(report.derived[1].contains("`lectures` was [L2.1, L2.4, L2.5]"));
assert_eq!(report.unlisted, ["term-decade", "val-per-decade"]);
assert!(report.dropped.is_empty() && report.relinked.is_empty());
// The course still validates with the written file.
let issues = coursebank::Catalog::load(&root)
.unwrap()
.validate()
.unwrap();
assert!(issues.is_empty(), "{issues:#?}");
}
#[test]
fn migrating_twice_is_a_no_op() {
let root = course("mig-twice");
run(&root, true);
let before = std::fs::read(root.join("glossary.yaml")).unwrap();
let again = run(&root, true);
assert!(again.text.is_none());
assert!(again.added.is_empty() && again.renamed.is_empty());
assert_eq!(again.present.len(), 2);
assert_eq!(std::fs::read(root.join("glossary.yaml")).unwrap(), before);
// The example as shipped already holds both, linked: also a no-op.
let shipped = v21_course("mig-shipped");
assert!(run(&shipped, true).text.is_none());
}
#[test]
fn a_dropped_first_is_compared_with_the_targets() {
let root = course("mig-derived");
edit(
&root,
"objectives/lo-alignment-scoring.yaml",
"terms: [term-alignment-matrix, term-gap,",
"terms: [term-decade, term-alignment-matrix, term-gap,",
);
let report = run(&root, false);
assert!(
report.derived[0].contains("`first` was L2.1; derived from the targets: l09"),
"{:?}",
report.derived
);
assert_eq!(report.unlisted, ["val-per-decade"]);
assert!(!root.join("glossary.yaml").exists(), "a dry run wrote");
}
#[test]
fn an_existing_glossary_is_added_to_not_rewritten() {
let root = course("mig-existing");
let before = "# Cross-cutting terms.\nterms:\n term-other:\n term: other\n \
definition: Something else.\n";
std::fs::write(root.join("glossary.yaml"), before).unwrap();
let report = run(&root, true);
let after = std::fs::read_to_string(root.join("glossary.yaml")).unwrap();
assert!(after.starts_with(before), "{after}");
assert!(after.contains("\nvalues:\n val-per-decade:\n"));
assert_eq!(report.added, ["term-decade", "val-per-decade"]);
let written = fragment(&root.join("glossary.yaml"));
assert_eq!(written.terms.len(), 2);
assert_eq!(written.values.len(), 1);
}
#[test]
fn the_cli_reports_and_a_dry_run_writes_nothing() {
let root = course("mig-cli");
let terms = source("terms.yaml");
let values = source("values.yaml");
let out = Command::new(env!("CARGO_BIN_EXE_coursebank"))
.arg("-C")
.arg(&root)
.args(["migrate", "glossary", "--dry-run", "--terms"])
.arg(&terms)
.arg("--values")
.arg(&values)
.output()
.unwrap();
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(out.status.success(), "{stdout}");
assert!(stdout.contains("decade -> term-decade"));
assert!(stdout.contains("nothing written"));
assert!(!root.join("glossary.yaml").exists());
let none = Command::new(env!("CARGO_BIN_EXE_coursebank"))
.arg("-C")
.arg(&root)
.args(["migrate", "glossary"])
.output()
.unwrap();
assert!(!none.status.success());
}