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

+145 -3
View File
@@ -35,6 +35,10 @@ use crate::course::CourseFile;
use crate::item::Item;
use crate::taxonomy::{Discrimination, Format, Level, Status};
mod glossary;
pub use glossary::lint_glossary;
/// A lint rule.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Rule {
@@ -107,6 +111,36 @@ pub enum Rule {
DiscriminationMissed,
/// Two items in the course have nearly the same stem.
DuplicateStem,
// --- glossary ---
/// A glossary entry nothing needs.
GlossaryUnused,
/// A renamed or coined term with no textbook name.
NoTextbookName,
/// A coined term with no exam wording.
NoExamWording,
/// A definition that uses the term it defines.
CircularDefinition,
/// A coined term in an item's stem or option.
CoinedTermInItem,
/// A taught value with no source.
UnsourcedValue,
/// A variant of a taught value in student-facing text.
ValueConflict,
/// Objective or target text the course's policy forbids.
ForbiddenTargetWording,
/// A term an explanation uses that its target does not list.
UnlistedTerm,
/// An item that prints a value students must recall.
RecallValuePrinted,
/// A ceiling-3 target turning on an equation with no implications.
EquationWithoutImplications,
/// A 2.0 prose field refers to an objective or target that does not exist.
UnresolvedReference,
/// A glossary entry defined away from the objective that first needs it.
DefinedElsewhere,
/// Glossary entries waiting for the instructor's approval.
ProposedEntries,
}
impl Rule {
@@ -114,7 +148,7 @@ impl Rule {
///
/// Used by `--list-rules`, and by the test that keeps this list in step with
/// the enum.
pub const ALL: [Rule; 30] = [
pub const ALL: [Rule; 44] = [
Rule::KeyIsLongest,
Rule::UnevenOptionLength,
Rule::WordRepeatCue,
@@ -145,6 +179,20 @@ impl Rule {
Rule::DifficultyMissed,
Rule::DiscriminationMissed,
Rule::DuplicateStem,
Rule::GlossaryUnused,
Rule::NoTextbookName,
Rule::NoExamWording,
Rule::CircularDefinition,
Rule::CoinedTermInItem,
Rule::UnsourcedValue,
Rule::ValueConflict,
Rule::ForbiddenTargetWording,
Rule::UnlistedTerm,
Rule::RecallValuePrinted,
Rule::EquationWithoutImplications,
Rule::UnresolvedReference,
Rule::DefinedElsewhere,
Rule::ProposedEntries,
];
/// The rule's nominal severity, for `--list-rules` and `--min-severity`.
@@ -202,6 +250,20 @@ impl Rule {
// Both are tidiness: the item still works, but its pool is
// carrying something nobody has accounted for.
R::UnusedOption | R::UnjustifiedRetirement => Severity::Low,
R::GlossaryUnused
| R::NoExamWording
| R::CircularDefinition
| R::UnsourcedValue
| R::UnlistedTerm
| R::EquationWithoutImplications => Severity::Low,
R::NoTextbookName
| R::CoinedTermInItem
| R::ValueConflict
| R::ForbiddenTargetWording
| R::RecallValuePrinted
| R::UnresolvedReference => Severity::Medium,
R::DefinedElsewhere | R::ProposedEntries => Severity::Note,
}
}
@@ -238,6 +300,20 @@ impl Rule {
Rule::DifficultyMissed => "evidence-difficulty",
Rule::DiscriminationMissed => "evidence-discrimination",
Rule::DuplicateStem => "evidence-duplicate-stem",
Rule::GlossaryUnused => "glossary-unused",
Rule::NoTextbookName => "glossary-no-textbook-name",
Rule::NoExamWording => "glossary-no-exam-wording",
Rule::CircularDefinition => "glossary-circular-definition",
Rule::CoinedTermInItem => "glossary-coined-in-item",
Rule::UnsourcedValue => "glossary-value-unsourced",
Rule::ValueConflict => "glossary-value-conflict",
Rule::ForbiddenTargetWording => "glossary-forbidden-target-wording",
Rule::UnlistedTerm => "glossary-unlisted-term",
Rule::RecallValuePrinted => "glossary-recall-value-printed",
Rule::EquationWithoutImplications => "glossary-equation-no-implications",
Rule::UnresolvedReference => "glossary-unresolved-reference",
Rule::DefinedElsewhere => "glossary-defined-elsewhere",
Rule::ProposedEntries => "glossary-proposed",
}
}
@@ -272,6 +348,20 @@ impl Rule {
| Rule::DiscriminationMissed
| Rule::NonfunctioningDistractor
| Rule::DuplicateStem => "evidence",
Rule::GlossaryUnused
| Rule::NoTextbookName
| Rule::NoExamWording
| Rule::CircularDefinition
| Rule::CoinedTermInItem
| Rule::UnsourcedValue
| Rule::ValueConflict
| Rule::ForbiddenTargetWording
| Rule::UnlistedTerm
| Rule::RecallValuePrinted
| Rule::EquationWithoutImplications
| Rule::UnresolvedReference
| Rule::DefinedElsewhere
| Rule::ProposedEntries => "glossary",
}
}
@@ -308,6 +398,20 @@ impl Rule {
Rule::DifficultyMissed,
Rule::DiscriminationMissed,
Rule::DuplicateStem,
Rule::GlossaryUnused,
Rule::NoTextbookName,
Rule::NoExamWording,
Rule::CircularDefinition,
Rule::CoinedTermInItem,
Rule::UnsourcedValue,
Rule::ValueConflict,
Rule::ForbiddenTargetWording,
Rule::UnlistedTerm,
Rule::RecallValuePrinted,
Rule::EquationWithoutImplications,
Rule::UnresolvedReference,
Rule::DefinedElsewhere,
Rule::ProposedEntries,
]
}
@@ -346,6 +450,32 @@ impl Rule {
Rule::DifficultyMissed => "observed difficulty was far from predicted",
Rule::DiscriminationMissed => "observed discrimination contradicted the prediction",
Rule::DuplicateStem => "two items have nearly the same stem",
Rule::GlossaryUnused => "a glossary entry no target, equation, value, or option needs",
Rule::NoTextbookName => "a renamed or coined term gives no textbook name to look up",
Rule::NoExamWording => "a coined term gives no exam_wording for items to use",
Rule::CircularDefinition => "a definition uses the term it defines",
Rule::CoinedTermInItem => "a coined term appears in an item stem or option",
Rule::UnsourcedValue => "a taught value has no source",
Rule::ValueConflict => {
"a value's conflicts pattern matches student-facing text or an item"
}
Rule::ForbiddenTargetWording => {
"objective or target text matches policy.target_text_forbid"
}
Rule::UnlistedTerm => {
"an explanation names a term its target neither lists nor inherits"
}
Rule::RecallValuePrinted => "an item stem or option prints a recall value",
Rule::EquationWithoutImplications => {
"a target at ceiling 3 or above turns on an equation with no implications"
}
Rule::UnresolvedReference => {
"an old prose field refers to an undeclared objective or target"
}
Rule::DefinedElsewhere => {
"an entry is defined in an objective file other than the first to need it"
}
Rule::ProposedEntries => "proposed glossary entries are waiting for approval",
}
}
}
@@ -427,6 +557,7 @@ pub fn lint_catalog(catalog: &Catalog, t: &Thresholds) -> Vec<Finding> {
out.extend(lint_key_positions(catalog, t));
out.extend(lint_option_counts(catalog));
out.extend(lint_duplicate_stems(catalog, t));
out.extend(lint_glossary(catalog));
out.sort_by(|a, b| {
b.severity
@@ -705,7 +836,12 @@ pub fn lint_item(entry: &Entry, course: &CourseFile, t: &Thresholds) -> Vec<Find
if is_ready {
for o in &it.options {
if !o.correct {
if o.misconception.is_none() && o.error_type.is_none() {
// A registry misconception named by id designs the distractor
// as well as its own text does.
if o.misconception.is_none()
&& o.misconception_id.is_none()
&& o.error_type.is_none()
{
push(
Rule::UndesignedDistractor,
Severity::Medium,
@@ -725,7 +861,13 @@ pub fn lint_item(entry: &Entry, course: &CourseFile, t: &Thresholds) -> Vec<Find
);
}
}
if o.student_text().is_none() {
// The registry's correction is what a report shows for an option
// that names a declared misconception and says nothing itself.
let registry_feedback = o
.misconception_id
.as_ref()
.is_some_and(|id| course.misconceptions.contains_key(id));
if o.student_text().is_none() && !registry_feedback {
push(
Rule::NoStudentFeedback,
Severity::Low,
+493
View File
@@ -0,0 +1,493 @@
// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! The glossary rules: advice about terms, equations, values, and
//! misconceptions, and about how prose and items use them.
//!
//! These replace checks the authoring pipelines each ran on their own copy of
//! `terms.yaml` and `values.yaml` (the slide linter's W374 and W375, the bank
//! linter's W334, W804, and W805, the brief linter's terms and values checks),
//! so every pipeline can call `coursebank lint` instead.
//!
//! `docs/design/2.1/CODES.md` maps each rule to the specification's code.
use std::collections::BTreeSet;
use std::path::Path;
use super::{Finding, Rule};
use crate::catalog::Catalog;
use crate::course::CourseFile;
use crate::course::glossary::{RefKind, TermKind, brace_refs, compile, contains_word};
use crate::taxonomy::{Level, Status};
/// One piece of item text a student reads, for the rules that scan items.
struct ItemText<'a> {
/// The item's global id.
uid: &'a str,
/// Which part: `stem`, ``option `o-x` ``, ``option `o-x` feedback``,
/// `solution`.
field: String,
/// Whether it is the stem or an option's text, the two places a printed
/// value gives an answer away.
stem_or_option: bool,
/// The text.
text: &'a str,
}
/// Every student-visible piece of every live item.
fn item_texts(catalog: &Catalog) -> Vec<ItemText<'_>> {
let mut out = Vec::new();
for entry in &catalog.entries {
let it = &entry.item;
if it.status == Status::Retired {
continue;
}
let uid = entry.uid.as_str();
out.push(ItemText {
uid,
field: "stem".into(),
stem_or_option: true,
text: &it.stem,
});
for o in &it.options {
out.push(ItemText {
uid,
field: format!("option `{}`", o.id),
stem_or_option: true,
text: &o.text,
});
if let Some(feedback) = &o.feedback_student {
out.push(ItemText {
uid,
field: format!("option `{}` feedback", o.id),
stem_or_option: false,
text: feedback,
});
}
}
if let Some(explanation) = it.solution.as_ref().and_then(|s| s.explanation.as_ref()) {
out.push(ItemText {
uid,
field: "solution".into(),
stem_or_option: false,
text: explanation,
});
}
}
out
}
/// A finding at its rule's own severity.
fn finding(rule: Rule, subject: &str, message: String) -> Finding {
Finding {
subject: subject.to_string(),
rule,
severity: rule.severity(),
message,
}
}
/// Runs every glossary rule over a course and its banks.
///
/// # Arguments
///
/// * `catalog` - the loaded course.
///
/// # Returns
///
/// Findings, in rule order.
pub fn lint_glossary(catalog: &Catalog) -> Vec<Finding> {
let course = &catalog.course;
let items = item_texts(catalog);
let mut out = Vec::new();
out.extend(unused(catalog));
out.extend(terms(course));
out.extend(coined_in_items(course, &items));
out.extend(values(course, &items));
out.extend(forbidden_wording(course));
out.extend(unlisted_terms(course));
out.extend(equations_without_implications(course));
out.extend(unresolved_references(course));
out.extend(defined_elsewhere(course));
out.extend(proposed(course));
out
}
/// `glossary-unused`: an entry no target, equation symbol, value, or item
/// option needs (W2101).
fn unused(catalog: &Catalog) -> Vec<Finding> {
let course = &catalog.course;
let mut used: BTreeSet<&str> = BTreeSet::new();
for target in course.learning_targets.values() {
for list in [
&target.terms,
&target.equations,
&target.values,
&target.misconceptions,
] {
used.extend(list.iter().map(String::as_str));
}
}
for equation in course.equations.values() {
used.extend(equation.symbols.iter().filter_map(|s| s.term.as_deref()));
}
for value in course.values.values() {
used.extend(value.term.as_deref());
}
for entry in &catalog.entries {
for option in &entry.item.options {
used.extend(option.misconception_id.as_deref());
}
}
course
.glossary_ids()
.into_iter()
.filter(|id| !used.contains(id))
.map(|id| {
let noun = RefKind::of(id).map(RefKind::noun).unwrap_or("entry");
finding(
Rule::GlossaryUnused,
id,
format!(
"no target lists this {noun}, and no equation symbol, value, or item option \
names it; list it on the targets that need it, or remove it"
),
)
})
.collect()
}
/// The rules about one term at a time: `glossary-no-textbook-name` (W2102),
/// `glossary-no-exam-wording` (W2103), and `glossary-circular-definition`
/// (W2104).
fn terms(course: &CourseFile) -> Vec<Finding> {
let mut out = Vec::new();
for (id, term) in &course.terms {
if matches!(term.kind, TermKind::Renamed | TermKind::Coined) && term.textbook.is_empty() {
out.push(finding(
Rule::NoTextbookName,
id,
format!(
"a {} term with no textbook name, so a student has nothing a search will \
find; add `textbook`",
term.kind.as_str()
),
));
}
if term.kind == TermKind::Coined && term.exam_wording.is_none() {
out.push(finding(
Rule::NoExamWording,
id,
"a coined term with no `exam_wording`, so an item writer has no plain wording to \
use instead"
.into(),
));
}
if let Some(form) = term
.forms()
.into_iter()
.find(|form| contains_word(&term.definition, form))
{
out.push(finding(
Rule::CircularDefinition,
id,
format!(
"the definition uses '{form}', the term it defines; define it in other words"
),
));
}
}
out
}
/// `glossary-coined-in-item`: a coined label, a teaching aid rather than tested
/// vocabulary, in what an item shows a student (W2105).
fn coined_in_items(course: &CourseFile, items: &[ItemText<'_>]) -> Vec<Finding> {
let mut out = Vec::new();
for (id, term) in course
.terms
.iter()
.filter(|(_, t)| t.kind == TermKind::Coined)
{
for text in items {
if let Some(form) = term
.forms()
.into_iter()
.find(|form| contains_word(text.text, form))
{
let instead = term
.exam_wording
.as_deref()
.map(|w| format!("write '{w}'"))
.unwrap_or_else(|| "write its textbook name".into());
out.push(finding(
Rule::CoinedTermInItem,
text.uid,
format!(
"{} uses the coined term '{form}' ({id}); {instead}",
text.field
),
));
}
}
}
out
}
/// The rules about taught values: `glossary-value-unsourced` (W2106),
/// `glossary-value-conflict` (W2107), and `glossary-recall-value-printed`
/// (W2110).
fn values(course: &CourseFile, items: &[ItemText<'_>]) -> Vec<Finding> {
let mut out = Vec::new();
for (id, value) in &course.values {
if value.source.is_none() {
out.push(finding(
Rule::UnsourcedValue,
id,
"no `source`, so nobody can check the number against the text it came from".into(),
));
}
}
// Patterns that do not compile are a validation error already.
let patterns: Vec<(&str, regex::Regex)> = course
.values
.iter()
.flat_map(|(id, v)| {
v.conflicts
.iter()
.filter_map(|p| compile(p, false).ok())
.map(move |re| (id.as_str(), re))
})
.collect();
for prose in course.student_prose() {
for (id, re) in &patterns {
if let Some(m) = re.find(prose.text) {
out.push(finding(
Rule::ValueConflict,
prose.id,
format!(
"{} writes '{}', a variant of {id}; write {{{id}}} so every page says it \
one way",
prose.field,
m.as_str()
),
));
}
}
}
for text in items {
for (id, re) in &patterns {
if let Some(m) = re.find(text.text) {
out.push(finding(
Rule::ValueConflict,
text.uid,
format!(
"{} writes '{}', a variant of {id}; state it as '{}'",
text.field,
m.as_str(),
course.values[*id].say
),
));
}
}
}
for (id, value) in course.values.iter().filter(|(_, v)| v.recall == Some(true)) {
let say = value.say.trim().to_lowercase();
if say.is_empty() {
continue;
}
for text in items.iter().filter(|t| t.stem_or_option) {
if text.text.to_lowercase().contains(&say) {
out.push(finding(
Rule::RecallValuePrinted,
text.uid,
format!(
"{} prints '{}' ({id}), a value students are expected to recall",
text.field, value.say
),
));
}
}
}
out
}
/// `glossary-forbidden-target-wording`: objective or target text that matches
/// one of the course's `target_text_forbid` patterns (W2108).
fn forbidden_wording(course: &CourseFile) -> Vec<Finding> {
let patterns: Vec<regex::Regex> = course
.policy
.target_text_forbid
.iter()
.filter_map(|p| compile(p, true).ok())
.collect();
let texts = course
.learning_objectives
.iter()
.map(|(id, o)| (id, &o.text))
.chain(course.learning_targets.iter().map(|(id, t)| (id, &t.text)));
let mut out = Vec::new();
for (id, text) in texts {
for re in &patterns {
if let Some(m) = re.find(text) {
out.push(finding(
Rule::ForbiddenTargetWording,
id,
format!(
"the text says '{}', which the course's policy forbids (`{}`)",
m.as_str(),
re.as_str()
),
));
}
}
}
out
}
/// `glossary-unlisted-term`: an explanation names a term in braces that its
/// target neither lists nor inherits from a prerequisite target (W2109).
fn unlisted_terms(course: &CourseFile) -> Vec<Finding> {
let mut out = Vec::new();
for (id, target) in &course.learning_targets {
let Some(explanation) = &target.explanation else {
continue;
};
let mut listed: BTreeSet<&str> = target.terms.iter().map(String::as_str).collect();
for prerequisite in &target.prerequisites {
if let Some(p) = course.learning_targets.get(prerequisite) {
listed.extend(p.terms.iter().map(String::as_str));
}
}
for (_, term) in brace_refs(explanation) {
if RefKind::of(term) == Some(RefKind::Term) && !listed.contains(term) {
out.push(finding(
Rule::UnlistedTerm,
id,
format!(
"the explanation uses {{{term}}}, which the target does not list in \
`terms` and no prerequisite target lists either"
),
));
}
}
}
out
}
/// `glossary-equation-no-implications`: a target at ceiling 3 or above turns on
/// an equation that lists nothing a question could test (W2111).
fn equations_without_implications(course: &CourseFile) -> Vec<Finding> {
let mut out = Vec::new();
for (id, target) in &course.learning_targets {
let deep = course
.effective_level_ceiling(id)
.is_some_and(|l| l >= Level::Apply);
if !deep {
continue;
}
for eq in &target.equations {
if course
.equations
.get(eq)
.is_some_and(|e| e.implications.is_empty())
{
out.push(finding(
Rule::EquationWithoutImplications,
id,
format!(
"turns on {eq}, which lists no `implications`, so a level 3 item has \
nothing written down to test"
),
));
}
}
}
out
}
/// `glossary-unresolved-reference`: a `{lo-...}` or `{t-...}` in a field 2.0
/// already had that names nothing. Validation leaves it alone because 2.0
/// accepted it; it still renders as literal braces.
fn unresolved_references(course: &CourseFile) -> Vec<Finding> {
let mut out = Vec::new();
for prose in course.student_prose().into_iter().filter(|p| p.legacy) {
for (_, id) in brace_refs(prose.text) {
if !course.resolves(id) {
out.push(finding(
Rule::UnresolvedReference,
prose.id,
format!(
"{} refers to {{{id}}}, which is not a declared objective or target; a \
student sees the braces",
prose.field
),
));
}
}
}
out
}
/// `glossary-defined-elsewhere`: an entry defined in an objective file other
/// than the one whose targets first need it (I2112). A convention, reported as
/// a note.
fn defined_elsewhere(course: &CourseFile) -> Vec<Finding> {
let mut out = Vec::new();
for (id, (lecture, target)) in course.glossary_first_use() {
let Some((_, defined)) = course.origin(id) else {
continue;
};
if !defined.starts_with("objectives") {
continue;
}
let objective = course.objective_for(target);
let Some((_, home)) = course.origin(objective) else {
continue;
};
if defined != home {
out.push(finding(
Rule::DefinedElsewhere,
id,
format!(
"defined in {}; first needed by {target} in {lecture}, whose objective is in \
{}",
shown(defined),
shown(home)
),
));
}
}
out
}
/// `glossary-proposed`: how many entries are waiting for approval (I2113).
fn proposed(course: &CourseFile) -> Vec<Finding> {
let waiting: Vec<&str> = course
.glossary_ids()
.into_iter()
.filter(|id| course.is_proposed(id))
.collect();
if waiting.is_empty() {
return Vec::new();
}
vec![finding(
Rule::ProposedEntries,
"glossary",
format!(
"{} proposed entr{} waiting for the instructor: {}",
waiting.len(),
if waiting.len() == 1 { "y" } else { "ies" },
waiting.join(", ")
),
)]
}
/// A path as a message shows it.
fn shown(path: &Path) -> String {
path.display().to_string()
}
+5 -2
View File
@@ -282,8 +282,9 @@ pub(crate) struct LintArgs {
/// Skip these rule codes.
#[arg(long, value_delimiter = ',')]
pub(crate) ignore: Vec<String>,
/// Only report findings at this severity or above.
#[arg(long, value_enum, default_value = "low")]
/// Only report findings at this severity or above. Notes are printed but
/// never make lint fail.
#[arg(long, value_enum, default_value = "note")]
pub(crate) min_severity: SeverityArg,
/// Exit 0 even when findings exist.
#[arg(long)]
@@ -354,6 +355,7 @@ impl StyleArg {
#[derive(Debug, Clone, Copy, ValueEnum)]
pub(crate) enum SeverityArg {
Note,
Low,
Medium,
High,
@@ -363,6 +365,7 @@ impl SeverityArg {
/// Converts the CLI value into the library's [`Severity`].
pub(crate) fn as_severity(self) -> Severity {
match self {
SeverityArg::Note => Severity::Note,
SeverityArg::Low => Severity::Low,
SeverityArg::Medium => Severity::Medium,
SeverityArg::High => Severity::High,
+7 -2
View File
@@ -16,6 +16,7 @@ use std::path::Path;
use coursebank::assessment::AssessmentFile;
use coursebank::bank::BankFile;
use coursebank::catalog::Severity;
use coursebank::course::fragment::{self, Section};
use coursebank::course::{COURSE_FILE, CourseFile};
use coursebank::error::{Error, Result};
@@ -717,7 +718,8 @@ pub(crate) fn validate(cli: &Cli) -> Result<Outcome> {
/// `lint`: run item-writing rules, grouped by subject, honoring the filter flags.
///
/// With `--list-rules` it prints the rule table and stops. Otherwise it returns
/// [`Outcome::Findings`] when anything fires, unless `--no-fail` was given.
/// [`Outcome::Findings`] when anything above a note fires, unless `--no-fail`
/// was given.
pub(crate) fn lint(cli: &Cli, args: &LintArgs) -> Result<Outcome> {
if args.list_rules {
println!("{:<32} {:<8} WHAT IT CATCHES", "CODE", "SEVERITY");
@@ -777,7 +779,10 @@ pub(crate) fn lint(cli: &Cli, args: &LintArgs) -> Result<Outcome> {
);
println!("Silence a rule with --ignore <code>, or see them all with --list-rules.");
if args.no_fail {
// A note is information, not a problem: a course with entries waiting for
// approval still passes a pipeline's lint gate.
let problems = findings.iter().any(|f| f.severity > Severity::Note);
if args.no_fail || !problems {
Ok(Outcome::Ok)
} else {
Ok(Outcome::Findings)
+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
+338
View File
@@ -0,0 +1,338 @@
// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! The lint rules 2.1 adds, one test each.
//!
//! Each test breaks the example course the way the prototype's self-test does
//! (`docs/design/2.1/prototype/check21.py --selftest`) and checks that the rule
//! fires. `docs/design/2.1/CODES.md` maps the specification's codes to these
//! rule codes.
mod common;
use std::path::PathBuf;
use std::process::Command;
use common::v21_course;
use coursebank::catalog::{Catalog, Severity};
use coursebank::course::fragment::Section;
use coursebank::course::glossary::{Term, TermKind};
use coursebank::lint::{self, Finding, Rule, Thresholds};
/// The example course, loaded.
fn catalog(tag: &str) -> Catalog {
Catalog::load(&v21_course(tag)).expect("the example loads")
}
/// The glossary findings for a rule.
fn fired(catalog: &Catalog, rule: Rule) -> Vec<Finding> {
lint::lint_glossary(catalog)
.into_iter()
.filter(|f| f.rule == rule)
.collect()
}
/// Asserts a rule fires once, on `subject`, with `needle` in its message.
fn fires(catalog: &Catalog, rule: Rule, subject: &str, needle: &str) {
let found = fired(catalog, rule);
assert!(
found
.iter()
.any(|f| f.subject == subject && f.message.contains(needle)),
"{} did not fire on {subject} with {needle:?}: {found:#?}",
rule.code()
);
}
/// The example item, for the rules that read items.
fn item(catalog: &mut Catalog) -> &mut coursebank::item::Item {
&mut catalog.entries[0].item
}
#[test]
fn the_example_draws_exactly_the_two_expected_glossary_findings() {
let findings = lint::lint_glossary(&catalog("baseline"));
let summary: Vec<(String, &str)> = findings
.iter()
.map(|f| (f.subject.clone(), f.rule.code()))
.collect();
assert_eq!(
summary,
vec![
("val-per-decade".to_string(), "glossary-unused"),
("glossary".to_string(), "glossary-proposed"),
],
"{findings:#?}"
);
let proposed = &findings[1];
assert_eq!(proposed.severity, Severity::Note);
assert!(proposed.message.starts_with("2 proposed entries"));
}
#[test]
fn w2101_an_entry_nothing_needs() {
let mut c = catalog("w2101");
c.course.terms.insert(
"term-unused".into(),
Term {
term: "unused".into(),
definition: "Not needed.".into(),
kind: TermKind::Standard,
textbook: Vec::new(),
variants: Vec::new(),
symbol: None,
units: None,
exam_wording: None,
status: None,
tags: Vec::new(),
notes_private: None,
},
);
fires(
&c,
Rule::GlossaryUnused,
"term-unused",
"no target lists this term",
);
}
#[test]
fn w2102_a_renamed_term_with_no_textbook_name() {
let mut c = catalog("w2102");
c.course.terms.get_mut("term-gap").unwrap().kind = TermKind::Renamed;
fires(&c, Rule::NoTextbookName, "term-gap", "a renamed term");
}
#[test]
fn w2103_a_coined_term_with_no_exam_wording() {
let mut c = catalog("w2103");
c.course.terms.get_mut("term-decade").unwrap().exam_wording = None;
fires(&c, Rule::NoExamWording, "term-decade", "exam_wording");
}
#[test]
fn w2104_a_definition_that_uses_its_term() {
let mut c = catalog("w2104");
c.course.terms.get_mut("term-gap").unwrap().definition = "A gap is a dash.".into();
fires(&c, Rule::CircularDefinition, "term-gap", "uses 'gap'");
}
#[test]
fn w2105_a_coined_term_in_an_item() {
let mut c = catalog("w2105");
item(&mut c).stem.push_str(" Think in decades.");
fires(
&c,
Rule::CoinedTermInItem,
"q-align-which-scores-higher",
"stem uses the coined term 'decades' (term-decade); write 'ten-fold'",
);
}
#[test]
fn w2106_a_value_with_no_source() {
let mut c = catalog("w2106");
c.course
.values
.get_mut("val-alignment-count-100")
.unwrap()
.source = None;
fires(
&c,
Rule::UnsourcedValue,
"val-alignment-count-100",
"no `source`",
);
}
#[test]
fn w2107_a_value_variant_in_student_prose_and_in_an_item() {
let mut c = catalog("w2107");
c.course
.learning_targets
.get_mut("t-align-fill-matrix")
.unwrap()
.explanation = Some("It costs 5.7 kJ.".into());
item(&mut c).options[0].text = "About 5.8 kJ per decade.".into();
fires(
&c,
Rule::ValueConflict,
"t-align-fill-matrix",
"explanation writes '5.7 kJ', a variant of val-per-decade",
);
fires(
&c,
Rule::ValueConflict,
"q-align-which-scores-higher",
"state it as 'about 6 kJ/mol'",
);
}
#[test]
fn w2108_target_text_the_policy_forbids() {
let mut c = catalog("w2108");
c.course
.learning_targets
.get_mut("t-align-fill-matrix")
.unwrap()
.text = "Calculate the score.".into();
fires(
&c,
Rule::ForbiddenTargetWording,
"t-align-fill-matrix",
"the text says 'Calculat'",
);
}
#[test]
fn w2109_an_explanation_using_a_term_its_target_does_not_list() {
let mut c = catalog("w2109");
c.course
.learning_targets
.get_mut("t-align-gap-penalty-effect")
.unwrap()
.explanation = Some("Unlike a {term-local-alignment}, the path changes.".into());
fires(
&c,
Rule::UnlistedTerm,
"t-align-gap-penalty-effect",
"{term-local-alignment}",
);
}
#[test]
fn w2109_a_term_inherited_from_a_prerequisite_target_is_listed() {
// t-align-gap-penalty-effect has t-align-fill-matrix as a prerequisite,
// which lists the traceback.
let mut c = catalog("w2109-inherited");
c.course
.learning_targets
.get_mut("t-align-gap-penalty-effect")
.unwrap()
.explanation = Some("Follow the {term-traceback}.".into());
assert!(fired(&c, Rule::UnlistedTerm).is_empty());
}
#[test]
fn w2110_an_item_prints_a_recall_value() {
let mut c = catalog("w2110");
item(&mut c).stem = "Given about 6 kJ/mol per ten-fold ratio, which is larger?".into();
fires(
&c,
Rule::RecallValuePrinted,
"q-align-which-scores-higher",
"stem prints 'about 6 kJ/mol' (val-per-decade)",
);
}
#[test]
fn w2111_a_deep_target_on_an_equation_with_no_implications() {
let mut c = catalog("w2111");
c.course
.equations
.get_mut("eq-global-recurrence")
.unwrap()
.implications
.clear();
fires(
&c,
Rule::EquationWithoutImplications,
"t-align-fill-matrix",
"turns on eq-global-recurrence",
);
}
#[test]
fn i2112_an_entry_defined_away_from_the_objective_that_first_needs_it() {
let mut c = catalog("i2112");
c.course.origins.insert(
(Section::Terms, "term-gap".into()),
PathBuf::from("objectives/lo-alignment-recurrence.yaml"),
);
let found = fired(&c, Rule::DefinedElsewhere);
assert_eq!(found.len(), 1, "{found:#?}");
assert_eq!(found[0].subject, "term-gap");
assert_eq!(found[0].severity, Severity::Note);
assert!(
found[0]
.message
.contains("first needed by t-align-matrix-terms in l09"),
"{found:#?}"
);
}
#[test]
fn i2113_counts_proposed_entries() {
let mut c = catalog("i2113");
c.course.terms.get_mut("term-decade").unwrap().status = None;
fires(
&c,
Rule::ProposedEntries,
"glossary",
"1 proposed entry waiting for the instructor: val-per-decade",
);
}
#[test]
fn an_unresolved_target_reference_in_an_old_reading_field_is_a_warning() {
let mut c = catalog("legacy-ref");
c.course.lectures.get_mut("l09").unwrap().readings[0].focus = Some("See {t-typo}.".into());
fires(
&c,
Rule::UnresolvedReference,
"l09",
"reading 1 focus refers to {t-typo}",
);
}
#[test]
fn a_registry_misconception_designs_a_distractor_and_gives_it_feedback() {
// Approved items are held to the completeness rules. The option that names
// a registry misconception and nothing else passes both of them.
let mut c = catalog("misconception-id");
item(&mut c).status = coursebank::taxonomy::Status::InReview;
let findings = lint::lint_catalog(&c, &Thresholds::default());
let about_option = |rule: Rule| {
findings
.iter()
.any(|f| f.rule == rule && f.message.contains("o-matches-only"))
};
assert!(!about_option(Rule::UndesignedDistractor), "{findings:#?}");
assert!(!about_option(Rule::NoStudentFeedback), "{findings:#?}");
}
#[test]
fn every_glossary_rule_has_a_glossary_code() {
let glossary: Vec<Rule> = Rule::ALL
.into_iter()
.filter(|r| r.family() == "glossary")
.collect();
assert_eq!(glossary.len(), 14);
assert!(glossary.iter().all(|r| r.code().starts_with("glossary-")));
}
/// Runs the binary on a course.
fn coursebank(root: &std::path::Path, args: &[&str]) -> std::process::Output {
Command::new(env!("CARGO_BIN_EXE_coursebank"))
.arg("-C")
.arg(root)
.args(args)
.output()
.expect("the binary runs")
}
#[test]
fn notes_are_printed_but_do_not_fail_lint() {
let root = v21_course("cli-notes");
let only_notes = coursebank(&root, &["lint", "--only", "glossary-proposed"]);
let stdout = String::from_utf8_lossy(&only_notes.stdout);
assert!(stdout.contains("[note] glossary-proposed"), "{stdout}");
assert!(only_notes.status.success(), "{stdout}");
let with_a_warning = coursebank(
&root,
&["lint", "--only", "glossary-proposed,glossary-unused"],
);
assert!(!with_a_warning.status.success());
}