feat: add learning objective targets
Pipeline / check (pull_request) Failing after 3m25s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped

This commit is contained in:
alexm committed 2026-09-21 14:02:34 -04:00
1 parent 9755417899
commit 8ec48fb185
32 files changed
+2396 -448

No files matched your search

+7 -3
View File
@@ -268,9 +268,13 @@ pub struct Placement {
/// The level as administered, denormalized so a record reads standalone.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub level: Option<Level>,
/// Objectives as administered, denormalized for the same reason.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub learning_objectives: Vec<String>,
/// Targets as administered, denormalized for the same reason.
#[serde(
default,
alias = "learning_objectives",
skip_serializing_if = "Vec::is_empty"
)]
pub learning_targets: Vec<String>,
/// Credit awarded to non-keyed options after the fact, keyed by letter.
///
/// When item analysis or a student challenge leads you to credit a
+126 -33
View File
@@ -79,7 +79,7 @@ pub struct BankMeta {
/// What a bank is scoped to.
///
/// A bank may be scoped by lecture, by objective, by topic, or by none of them.
/// A bank may be scoped by lecture, by learning target, by topic, or by none of them.
/// Declaring the scope is what lets the catalog report *gaps*: it can only tell
/// you that lecture 12 has no Apply-level items if it knows lecture 12 is
/// supposed to be covered here.
@@ -89,9 +89,13 @@ pub struct Scope {
/// Lectures this bank draws from.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub lectures: Vec<String>,
/// Objectives this bank is responsible for covering.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub learning_objectives: Vec<String>,
/// Learning targets this bank is responsible for covering.
#[serde(
default,
alias = "learning_objectives",
skip_serializing_if = "Vec::is_empty"
)]
pub learning_targets: Vec<String>,
/// Units this bank belongs to.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub units: Vec<String>,
@@ -254,9 +258,9 @@ impl BankFile {
issues.push(format!("bank.scope: unknown lecture `{lec}`"));
}
}
for lo in &self.bank.scope.learning_objectives {
if !c.learning_objectives.contains_key(lo) {
issues.push(format!("bank.scope: unknown learning objective `{lo}`"));
for target in &self.bank.scope.learning_targets {
if !c.is_target(target) && !c.is_objective(target) {
issues.push(format!("bank.scope: unknown learning target `{target}`"));
}
}
}
@@ -563,8 +567,8 @@ fn validate_item(
if it.cognitive_process.is_none() {
issues.push("approved items must declare a cognitive_process".into());
}
if it.learning_objectives.is_empty() {
issues.push("approved items must reference at least one learning objective".into());
if it.learning_targets.is_empty() {
issues.push("approved items must reference at least one learning target".into());
}
if it.sources.is_empty() {
issues.push("approved items must cite at least one source".into());
@@ -590,26 +594,64 @@ fn validate_item(
// --- cross-file references ----
if let Some(c) = course {
for lo in &it.learning_objectives {
match c.learning_objectives.get(lo) {
None => issues.push(format!("unknown learning objective `{lo}`")),
Some(obj) => {
if let Some(ceiling) = obj.level_ceiling {
if it.level > ceiling {
issues.push(format!(
"level {} exceeds the ceiling {} declared for objective `{lo}`",
it.level.code(),
ceiling.code()
));
}
}
if !obj.assessed {
issues.push(format!(
"objective `{lo}` is marked `assessed: false` but this item measures it"
));
}
for tag in &it.learning_targets {
let is_target = c.is_target(tag);
if !is_target && !c.is_objective(tag) {
issues.push(format!("unknown learning target `{tag}`"));
continue;
}
// Items are tagged at the target tier. Tagging an objective that has
// targets would put the item in that objective's denominator without
// recording which performance the question actually asked for, and
// that record is what a report drills into and what coverage
// analysis counts. An objective with no targets stands as its own.
let its_targets = c.targets(tag);
if !its_targets.is_empty() {
issues.push(format!(
"`{tag}` is an objective with {} learning target(s); tag the specific \
target this item measures instead",
its_targets.len()
));
}
// The ceiling may be inherited from the objective, so a target that
// declares none of its own is still bounded.
if let Some(ceiling) = c.effective_level_ceiling(tag) {
if it.level > ceiling {
let declares_its_own = if is_target {
c.learning_targets
.get(tag)
.is_some_and(|t| t.level_ceiling.is_some())
} else {
true
};
let source = if declares_its_own {
format!("declared for `{tag}`")
} else {
format!(
"inherited by `{tag}` from its objective `{}`",
c.objective_for(tag)
)
};
issues.push(format!(
"level {} exceeds the ceiling {} {source}",
it.level.code(),
ceiling.code()
));
}
}
if !c.is_assessed(tag) {
let parked_above =
is_target && c.learning_targets.get(tag).is_some_and(|t| t.assessed);
let which = if parked_above {
format!(
"its objective `{}` is marked `assessed: false`",
c.objective_for(tag)
)
} else {
format!("`{tag}` is marked `assessed: false`")
};
issues.push(format!("{which} but this item measures it"));
}
}
for s in &it.sources {
if !c.lectures.contains_key(&s.lecture) {
@@ -707,7 +749,7 @@ mod tests {
level: 2
format: open_response
cognitive_process: explain
learning_objectives: [lo-x]
learning_targets: [lo-x]
sources: [{ lecture: L1.1 }]
design: { rationale: r }
stem: Explain the first law.
@@ -827,7 +869,7 @@ mod tests {
let issues = b.validate(None);
for want in [
"cognitive_process",
"learning objective",
"learning target",
"source",
"design block",
] {
@@ -914,7 +956,7 @@ learning_objectives:
status: draft
level: 4
stem: s
learning_objectives: [lo-known, lo-unknown]
learning_targets: [lo-known, lo-unknown]
sources: [{ lecture: L99 }]
options:
- { id: A, text: a, correct: true }
@@ -925,7 +967,7 @@ learning_objectives:
assert!(
issues
.iter()
.any(|i| i.contains("unknown learning objective `lo-unknown`"))
.any(|i| i.contains("unknown learning target `lo-unknown`"))
);
assert!(issues.iter().any(|i| i.contains("unknown lecture `L99`")));
assert!(
@@ -934,6 +976,57 @@ learning_objectives:
);
}
#[test]
fn an_item_must_tag_a_target_not_an_objective_that_has_them() {
let course: CourseFile = serde_yaml_ng::from_str(
r#"
course: { code: X, title: Y, term: Z }
learning_objectives:
lo-binding: { text: Quantify binding., level_ceiling: 3 }
lo-solo: { text: An objective with no targets. }
learning_targets:
t-kd: { text: Write the expression., objective: lo-binding }
"#,
)
.unwrap();
let b = bank(
r#"
- id: q-a-001
status: draft
level: 1
stem: s
learning_targets: [lo-binding]
options:
- { id: A, text: a, correct: true }
- { id: B, text: b }
- id: q-a-002
status: draft
level: 1
stem: s
learning_targets: [t-kd, lo-solo]
options:
- { id: A, text: a, correct: true }
- { id: B, text: b }
"#,
);
let issues = b.validate(Some(&course));
assert!(
issues
.iter()
.any(|i| i.contains("`lo-binding` is an objective with 1 learning target(s)")),
"got {issues:?}"
);
// A target is fine, and so is an objective that has no targets: it
// stands as its own, which is what lets a course migrate a unit at a
// time.
assert!(
!issues
.iter()
.any(|i| i.contains("`t-kd`") || i.contains("`lo-solo`")),
"got {issues:?}"
);
}
#[test]
fn history_versions_must_increase() {
let b = bank(
@@ -964,7 +1057,7 @@ learning_objectives:
level: 1
cognitive_process: recall
stem: s
learning_objectives: [lo]
learning_targets: [lo]
sources: [{ lecture: L1 }]
design: { expected_difficulty: 0.8 }
options:
@@ -983,7 +1076,7 @@ learning_objectives:
cognitive_process: generate
bonus: true
stem: s
learning_objectives: [lo]
learning_targets: [lo]
sources: [{ lecture: L1 }]
design: { expected_difficulty: 0.3 }
options:
+168 -33
View File
@@ -26,7 +26,7 @@ use crate::course::CourseFile;
use crate::error::{Error, Result};
use crate::item::Item;
use crate::layout::Layout;
use crate::taxonomy::{Level, Status};
use crate::taxonomy::{Level, Status, Tier};
use crate::yaml;
/// One item plus everything needed to locate it again.
@@ -321,19 +321,19 @@ impl Catalog {
out
}
/// Items that measure a given objective.
/// Items tagged with a given learning target.
///
/// # Arguments
///
/// * `objective` - the objective id.
/// * `target` - the target id.
///
/// # Returns
///
/// Matching entries.
pub fn by_objective(&self, objective: &str) -> Vec<&Entry> {
pub fn by_target(&self, target: &str) -> Vec<&Entry> {
self.entries
.iter()
.filter(|e| e.item.learning_objectives.iter().any(|o| o == objective))
.filter(|e| e.item.learning_targets.iter().any(|t| t == target))
.collect()
}
@@ -384,55 +384,124 @@ impl Catalog {
out
}
/// Builds the coverage report.
/// Items that measure a given objective, through any of its targets.
///
/// # Arguments
///
/// * `objective` - the objective id.
///
/// # Returns
///
/// One row per assessed objective plus a list of course-wide gaps.
/// Entries tagged with the objective itself or with any of its targets,
/// each appearing once even when it is tagged with two of them.
pub fn by_objective(&self, objective: &str) -> Vec<&Entry> {
self.entries
.iter()
.filter(|e| {
e.item
.learning_targets
.iter()
.any(|t| t == objective || self.course.objective_for(t) == objective)
})
.collect()
}
/// Builds the coverage report.
///
/// Rows cover both tiers, because the two answer different questions. An
/// objective row answers "can I build an exam that reports on this
/// objective", and aggregates every item under it. A target row answers
/// "which specific things have I written items for", which is the
/// authoring queue, and a target with no items is the most common and least
/// visible hole in a bank: the objective looks well covered while a third of
/// what it claims has never been asked.
///
/// # Returns
///
/// One row per assessed entry plus a list of course-wide gaps.
pub fn coverage(&self) -> Coverage {
let mut rows = Vec::new();
for id in self.course.objectives_in_order() {
let obj = &self.course.learning_objectives[&id];
if !obj.assessed {
for id in self.course.registry_in_order() {
if !self.course.is_objective(&id) && !self.course.is_target(&id) {
continue;
}
let items = self.by_objective(&id);
if !self.course.is_assessed(&id) {
continue;
}
let targets = self.course.targets(&id);
let tier = if self.course.is_objective(&id) {
Tier::Objective
} else {
Tier::Target
};
// An objective's pool is everything under it; a target's is what is
// tagged to it directly. An objective with no targets is its own
// target, so the two agree there.
let items = if targets.is_empty() {
self.by_target(&id)
} else {
self.by_objective(&id)
};
let usable: Vec<&&Entry> = items.iter().filter(|e| e.item.is_assemblable()).collect();
let mut levels: BTreeSet<Level> = BTreeSet::new();
for e in &usable {
levels.insert(e.item.level);
}
let targets_covered = targets
.iter()
.filter(|target| {
self.by_target(target)
.iter()
.any(|e| e.item.is_assemblable())
})
.count();
rows.push(CoverageRow {
objective: id.clone(),
text: obj.text.clone(),
unit: obj.unit.clone(),
id: id.clone(),
text: self.course.text_for(&id),
tier,
objective: self
.course
.is_target(&id)
.then(|| self.course.objective_for(&id).to_string()),
unit: self.course.objective_unit(&id).map(str::to_string),
targets: targets.len(),
targets_covered,
total: items.len(),
assemblable: usable.len(),
max_level: levels.iter().next_back().copied(),
levels: levels.into_iter().collect(),
ceiling: obj.level_ceiling,
ceiling: self.course.effective_level_ceiling(&id),
});
}
let mut gaps = Vec::new();
for row in &rows {
// Gaps are raised against the tier that can be acted on. "No items
// at all" is worth saying about a target, because writing one is the
// fix. "Resting on a single item" is worth saying about an
// objective, because a target resting on one item is the normal and
// intended case, and flagging two hundred of them would bury the
// rows that matter.
if row.total == 0 {
gaps.push(Gap::Uncovered(row.objective.clone()));
gaps.push(Gap::Uncovered(row.id.clone()));
} else if row.assemblable == 0 {
gaps.push(Gap::NoApprovedItems(row.objective.clone()));
} else if row.assemblable == 1 {
gaps.push(Gap::SingleItem(row.objective.clone()));
gaps.push(Gap::NoApprovedItems(row.id.clone()));
} else if row.assemblable == 1 && row.tier == Tier::Objective {
gaps.push(Gap::SingleItem(row.id.clone()));
}
// An objective assessed only at the recall level is the most common
// and most consequential blind spot: it looks covered in a count and
// is not covered in fact.
if row.assemblable > 0 && row.max_level == Some(Level::Remember) {
if row.tier == Tier::Objective
&& row.assemblable > 0
&& row.max_level == Some(Level::Remember)
{
if let Some(ceiling) = row.ceiling {
if ceiling > Level::Remember {
gaps.push(Gap::RecallOnly(row.objective.clone()));
gaps.push(Gap::RecallOnly(row.id.clone()));
}
} else {
gaps.push(Gap::RecallOnly(row.objective.clone()));
gaps.push(Gap::RecallOnly(row.id.clone()));
}
}
}
@@ -451,7 +520,7 @@ impl Catalog {
// Items with no objective at all cannot appear in any student report.
for e in &self.entries {
if e.item.learning_objectives.is_empty() && e.item.is_assemblable() {
if e.item.learning_targets.is_empty() && e.item.is_assemblable() {
gaps.push(Gap::ItemWithoutObjective(e.uid.clone()));
}
}
@@ -463,21 +532,35 @@ impl Catalog {
/// The coverage report.
#[derive(Debug, Clone)]
pub struct Coverage {
/// One row per assessed objective.
/// One row per assessed registry entry, objectives first with their targets
/// following each.
pub rows: Vec<CoverageRow>,
/// Course-wide gaps worth acting on.
pub gaps: Vec<Gap>,
}
/// Coverage of one objective.
/// Coverage of one registry entry, at either tier.
#[derive(Debug, Clone)]
pub struct CoverageRow {
/// The objective id.
pub objective: String,
/// The objective text.
/// The registry id.
pub id: String,
/// Its text.
pub text: String,
/// The unit it belongs to.
/// Whether this is an objective, whose counts aggregate every item under it,
/// or a target, whose counts are its own items.
pub tier: Tier,
/// The objective this row sits under, for a target.
pub objective: Option<String>,
/// The unit it belongs to, inherited from the objective when not declared.
pub unit: Option<String>,
/// Targets in the registry, for an objective row.
pub targets: usize,
/// Targets with at least one usable item.
///
/// The number to look at when an objective looks well covered: twenty items
/// spread over four of its nine targets is a different bank from twenty
/// items spread over all nine.
pub targets_covered: usize,
/// Items referencing it, at any status.
pub total: usize,
/// Items that could actually be used.
@@ -486,16 +569,16 @@ pub struct CoverageRow {
pub max_level: Option<Level>,
/// Every level assessed.
pub levels: Vec<Level>,
/// The declared ceiling, when set.
/// The ceiling in force, inherited from the objective when not declared.
pub ceiling: Option<Level>,
}
/// A specific, actionable hole in the item pool.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Gap {
/// An assessed objective with no items at all.
/// An assessed objective or target with no items at all.
Uncovered(String),
/// An objective whose items are all drafts or retired.
/// An entry whose items are all drafts or retired.
NoApprovedItems(String),
/// An objective resting on a single item, so one bad item hides it entirely.
SingleItem(String),
@@ -606,7 +689,7 @@ items:
level: 1
cognitive_process: recall
stem: What is x?
learning_objectives: [lo-covered]
learning_targets: [lo-covered]
sources: [{ lecture: L01 }]
design: { expected_difficulty: 0.8 }
options:
@@ -672,6 +755,58 @@ items:
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn coverage_aggregates_targets_and_names_the_untested_ones() {
let dir = tmp("tiered-coverage");
std::fs::create_dir_all(dir.join("banks")).unwrap();
std::fs::write(
dir.join("course.yaml"),
r#"
course: { code: TEST 101, title: Testing, term: Fall 2026 }
lectures:
L01: { title: One }
learning_objectives:
lo-binding: { text: Quantify binding., lectures: [L01], order: 1, level_ceiling: 3 }
learning_targets:
t-kd: { text: Write the expression., objective: lo-binding, order: 1 }
t-plot: { text: Read a plot., objective: lo-binding, order: 2 }
"#,
)
.unwrap();
// Two items, both on the same target.
let bank = APPROVED.replace("lo-covered", "t-kd").replace(
" - { id: B, text: wrong }\n",
" - { id: B, text: wrong }\n - id: q-x-002\n status: approved\n level: 3\n \
cognitive_process: implement\n stem: And again?\n learning_targets: [t-kd]\n \
sources: [{ lecture: L01 }]\n design: { expected_difficulty: 0.5 }\n options:\n \
- { id: A, text: right, correct: true }\n - { id: B, text: wrong }\n",
);
write_bank(&dir, "b1.yaml", &bank);
let cat = Catalog::load(&dir).unwrap();
let cov = cat.coverage();
let objective = cov
.rows
.iter()
.find(|r| r.id == "lo-binding")
.expect("the objective row");
assert_eq!(objective.tier, Tier::Objective);
assert_eq!(
objective.assemblable, 2,
"the objective aggregates its targets"
);
assert_eq!(
(objective.targets_covered, objective.targets),
(1, 2),
"two items, but only one of the two targets has been asked about"
);
// Resting on one item is the normal case for a target, so it is not a
// gap; never having been asked about at all is.
assert!(!cov.gaps.contains(&Gap::SingleItem("t-kd".into())));
assert!(cov.gaps.contains(&Gap::Uncovered("t-plot".into())));
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn recall_only_respects_a_recall_ceiling() {
let dir = tmp("ceiling");
+993 -81
View File
File diff suppressed because it is too large. Load diff
+18 -8
View File
@@ -102,9 +102,19 @@ pub struct Item {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub solution: Option<Solution>,
/// Objectives this item measures, as ids into the course registry.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub learning_objectives: Vec<String>,
/// The learning targets this item measures, as ids into the course
/// registry.
///
/// Targets rather than objectives: an item measures one specific
/// performance, and recording which one is what lets a report explain an
/// objective's result instead of only stating it. The objective follows from
/// the target, so it is never recorded twice.
#[serde(
default,
alias = "learning_objectives",
skip_serializing_if = "Vec::is_empty"
)]
pub learning_targets: Vec<String>,
/// Where the material was taught.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
@@ -114,7 +124,7 @@ pub struct Item {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub topics: Vec<String>,
/// Item ids or objective ids a student needs before this is fair.
/// Item ids or registry ids a student needs before this is fair.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub prerequisites: Vec<String>,
@@ -671,7 +681,7 @@ impl Item {
/// the only way to get a half-built `Item` is deliberately.
///
/// The result is `Status::Draft` and deliberately will not pass
/// [`Item::is_assemblable`] — it still needs learning objectives, sources, and
/// [`Item::is_assemblable`] — it still needs learning targets, sources, and
/// a cognitive process before it can be drawn onto an assessment.
///
/// # Arguments
@@ -703,7 +713,7 @@ impl Item {
stem: stem.to_string(),
options,
solution: None,
learning_objectives: Vec::new(),
learning_targets: Vec::new(),
sources: Vec::new(),
topics: Vec::new(),
prerequisites: Vec::new(),
@@ -798,7 +808,7 @@ impl Item {
/// A content fingerprint over everything that affects what a student sees.
///
/// Metadata deliberately does not contribute: retagging an objective must not
/// Metadata deliberately does not contribute: retagging a target must not
/// invalidate pooled statistics, but rewording an option must.
///
/// # Returns
@@ -964,7 +974,7 @@ options:
let base = item(MINIMAL);
let mut retagged = base.clone();
retagged.topics = vec!["kinetics".into()];
retagged.learning_objectives = vec!["lo-a".into()];
retagged.learning_targets = vec!["lo-a".into()];
retagged.author = Some("someone".into());
assert_eq!(
base.fingerprint(),
+6 -6
View File
@@ -161,7 +161,7 @@ pub struct SealedItem {
pub level: Option<Level>,
/// Objectives as administered.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub learning_objectives: Vec<String>,
pub learning_targets: Vec<String>,
/// The keyed letters in the bank's own lettering, before any shuffle.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub key: Vec<String>,
@@ -491,10 +491,10 @@ fn sealed_item(
.unwrap_or_else(|| item.points(default_points)),
bonus: placement.bonus,
level: placement.level.or(Some(item.level)),
learning_objectives: if placement.learning_objectives.is_empty() {
item.learning_objectives.clone()
learning_targets: if placement.learning_targets.is_empty() {
item.learning_targets.clone()
} else {
placement.learning_objectives.clone()
placement.learning_targets.clone()
},
key: if placement.key.is_empty() {
item.key_letters()
@@ -903,7 +903,7 @@ impl SealFile {
),
));
}
if was.learning_objectives != now.learning_objectives {
if was.learning_targets != now.learning_targets {
out.push(Drift::new(
Severity::Low,
"objectives-retagged",
@@ -1160,7 +1160,7 @@ mod tests {
points: 1.0,
bonus: false,
level: Some(Level::Remember),
learning_objectives: vec!["lo-a".into()],
learning_targets: vec!["lo-a".into()],
key: vec!["B".into()],
stem: Some("Stem.".into()),
options: vec![
+38
View File
@@ -9,6 +9,44 @@ use std::fmt;
use serde::{Deserialize, Serialize};
/// Which tier of the objective registry an entry or a reported row belongs to.
///
/// The two words come from the assessment literature and name two different
/// jobs, not two sizes of the same thing. A **learning objective** is what a
/// syllabus lists and what a report classifies as met: the unit a claim is made
/// about. A **learning target** is the specific performance an item is written
/// against and tagged to: what a student aims at in one class, and the evidence
/// a claim about an objective rests on.
///
/// It lives here rather than beside the registry because every layer that
/// reports needs it, and a `bool` named for one of the two tiers leaves the
/// reader guessing which way round it points.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Tier {
/// A learning objective: the tier a mastery claim is made about.
Objective,
/// A learning target: the tier items are tagged to, and evidence for the
/// objective above it.
Target,
}
impl Tier {
/// The snake_case token used in YAML and in flat storage.
pub fn as_str(self) -> &'static str {
match self {
Tier::Objective => "objective",
Tier::Target => "target",
}
}
}
impl fmt::Display for Tier {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
/// Cognitive demand, following the revised Bloom taxonomy.
///
/// Serialized as the integers 1 through 5 so YAML reads `level: 3`. The derived