diff --git a/src/authoring/lint.rs b/src/authoring/lint.rs index a6e41ea..c6653ed 100644 --- a/src/authoring/lint.rs +++ b/src/authoring/lint.rs @@ -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 { 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 Vec { + /// 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> { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + let patterns: Vec = 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 { + 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 { + 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 { + 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 { + 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 { + 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() +} diff --git a/src/cli.rs b/src/cli.rs index 4a6ff5a..60354d5 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -282,8 +282,9 @@ pub(crate) struct LintArgs { /// Skip these rule codes. #[arg(long, value_delimiter = ',')] pub(crate) ignore: Vec, - /// 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, diff --git a/src/commands/project.rs b/src/commands/project.rs index e70d971..ce1aa4c 100644 --- a/src/commands/project.rs +++ b/src/commands/project.rs @@ -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 { /// `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 { 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 { ); println!("Silence a rule with --ignore , 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) diff --git a/src/model/catalog.rs b/src/model/catalog.rs index 909fffa..bd73359 100644 --- a/src/model/catalog.rs +++ b/src/model/catalog.rs @@ -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", diff --git a/src/model/course/glossary.rs b/src/model/course/glossary.rs index 3f8bb2a..d27b535 100644 --- a/src/model/course/glossary.rs +++ b/src/model/course/glossary.rs @@ -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 diff --git a/tests/lint_2_1.rs b/tests/lint_2_1.rs new file mode 100644 index 0000000..934b2c5 --- /dev/null +++ b/tests/lint_2_1.rs @@ -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 { + 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::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()); +}