feat(lint): glossary rules for terms, equations, values, misconceptions

Fourteen rules in a new `glossary` family (src/authoring/lint/glossary.rs):
unused entries, renamed or coined terms with no textbook name, coined
terms with no exam wording, circular definitions, coined terms in items,
unsourced values, value variants in prose or items, policy-forbidden
target wording, explanation terms a target does not list, recall values
printed in items, deep targets on equations with no implications, and
unresolved {lo-}/{t-} references in 2.0 prose fields. Two of them are
notes: entries defined away from the objective that first needs them,
and the count of proposed entries.

Adds Severity::Note. `coursebank lint` prints notes by default and does
not fail on them, so a course with proposed entries still passes a lint
gate. A distractor that names a registry misconception counts as designed
and as having student feedback.

On the example the glossary rules report exactly glossary-unused on
val-per-decade and glossary-proposed for two entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
alexmandClaude committed 2026-11-16 12:02:50 -05:00
1 parent 960cf6cbd3
commit b8fdf4d6a8
7 files changed
+1105 -7

No files matched your search

+5
View File
@@ -809,6 +809,10 @@ impl Gap {
/// How much attention a finding deserves.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Severity {
/// Information, not a problem: a count of entries waiting for approval, or
/// a convention that is reported but not enforced. `coursebank lint`
/// prints notes and does not fail on them.
Note,
/// Worth knowing.
Low,
/// Worth scheduling.
@@ -821,6 +825,7 @@ impl Severity {
/// A short label for report output.
pub fn label(self) -> &'static str {
match self {
Severity::Note => "note",
Severity::Low => "low",
Severity::Medium => "medium",
Severity::High => "high",
+112
View File
@@ -818,6 +818,118 @@ impl super::CourseFile {
out
}
/// A lecture's targets in teaching order: its objectives in the order the
/// lecture page prints them, each objective's targets by ceiling and then
/// id, and then any target the lecture covers whose objective it does not
/// teach.
///
/// # Arguments
///
/// * `lecture` - the lecture id.
///
/// # Returns
///
/// Target ids, each once.
pub fn lecture_targets_in_order(&self, lecture: &str) -> Vec<&str> {
let covered = self.lecture_targets(lecture);
let mut out: Vec<&str> = Vec::new();
for objective in self.lecture_objectives(lecture) {
for target in self.targets(objective) {
if covered.contains(&target) && !out.contains(&target) {
out.push(target);
}
}
}
for target in covered {
if !out.contains(&target) {
out.push(target);
}
}
out
}
/// Where each glossary entry is first needed: the first lecture, in
/// teaching order, with a target that lists it, and that target.
///
/// Teaching order is the course's own: lectures in order, objectives in
/// each lecture's `teaches` order, and an objective's targets by ceiling
/// and then id, which is the order the lecture page prints them in. An
/// entry no target lists, or that only targets outside any lecture list,
/// has no first use.
///
/// # Returns
///
/// Entry id to `(lecture id, target id)`.
pub fn glossary_first_use(&self) -> std::collections::BTreeMap<&str, (&str, &str)> {
let mut first = std::collections::BTreeMap::new();
for lecture in self.lectures.keys() {
for target_id in self.lecture_targets_in_order(lecture) {
let Some(target) = self.learning_targets.get(target_id) else {
continue;
};
let lists = [
&target.terms,
&target.equations,
&target.values,
&target.misconceptions,
];
for id in lists.into_iter().flatten() {
first
.entry(id.as_str())
.or_insert((lecture.as_str(), target_id));
}
}
}
first
}
/// The lecture that introduces a glossary entry.
///
/// # Arguments
///
/// * `id` - a term, equation, value, or misconception id.
///
/// # Returns
///
/// The first lecture, in teaching order, with a target that lists it.
pub fn first_lecture(&self, id: &str) -> Option<&str> {
self.glossary_first_use()
.get(id)
.map(|(lecture, _)| *lecture)
}
/// Whether a glossary entry is waiting for approval.
///
/// # Arguments
///
/// * `id` - a term, equation, value, or misconception id.
///
/// # Returns
///
/// `true` for an entry marked `status: proposed`.
pub fn is_proposed(&self, id: &str) -> bool {
let status = match RefKind::of(id) {
Some(RefKind::Term) => self.terms.get(id).and_then(|e| e.status),
Some(RefKind::Equation) => self.equations.get(id).and_then(|e| e.status),
Some(RefKind::Value) => self.values.get(id).and_then(|e| e.status),
Some(RefKind::Misconception) => self.misconceptions.get(id).and_then(|e| e.status),
_ => None,
};
status == Some(EntryStatus::Proposed)
}
/// Every glossary id, terms first, then equations, values, and
/// misconceptions.
pub fn glossary_ids(&self) -> Vec<&str> {
self.terms
.keys()
.chain(self.equations.keys())
.chain(self.values.keys())
.chain(self.misconceptions.keys())
.map(String::as_str)
.collect()
}
/// The validation messages for everything 2.1 adds.
///
/// Each message names the id it is about first, in backticks, so