WIP: Prelim use #2

Draft
alexm wants to merge 40 commits from prelim-use into main
pull from: prelim-use
7 changed files with 1105 additions and 7 deletions
Showing only changes of commit b8fdf4d6a8 - Show all commits

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());
}