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

+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");