WIP: Prelim use #2
No files matched your search
+145
-3
@@ -35,6 +35,10 @@ use crate::course::CourseFile;
|
|||||||
use crate::item::Item;
|
use crate::item::Item;
|
||||||
use crate::taxonomy::{Discrimination, Format, Level, Status};
|
use crate::taxonomy::{Discrimination, Format, Level, Status};
|
||||||
|
|
||||||
|
mod glossary;
|
||||||
|
|
||||||
|
pub use glossary::lint_glossary;
|
||||||
|
|
||||||
/// A lint rule.
|
/// A lint rule.
|
||||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
|
||||||
pub enum Rule {
|
pub enum Rule {
|
||||||
@@ -107,6 +111,36 @@ pub enum Rule {
|
|||||||
DiscriminationMissed,
|
DiscriminationMissed,
|
||||||
/// Two items in the course have nearly the same stem.
|
/// Two items in the course have nearly the same stem.
|
||||||
DuplicateStem,
|
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 {
|
impl Rule {
|
||||||
@@ -114,7 +148,7 @@ impl Rule {
|
|||||||
///
|
///
|
||||||
/// Used by `--list-rules`, and by the test that keeps this list in step with
|
/// Used by `--list-rules`, and by the test that keeps this list in step with
|
||||||
/// the enum.
|
/// the enum.
|
||||||
pub const ALL: [Rule; 30] = [
|
pub const ALL: [Rule; 44] = [
|
||||||
Rule::KeyIsLongest,
|
Rule::KeyIsLongest,
|
||||||
Rule::UnevenOptionLength,
|
Rule::UnevenOptionLength,
|
||||||
Rule::WordRepeatCue,
|
Rule::WordRepeatCue,
|
||||||
@@ -145,6 +179,20 @@ impl Rule {
|
|||||||
Rule::DifficultyMissed,
|
Rule::DifficultyMissed,
|
||||||
Rule::DiscriminationMissed,
|
Rule::DiscriminationMissed,
|
||||||
Rule::DuplicateStem,
|
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`.
|
/// 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
|
// Both are tidiness: the item still works, but its pool is
|
||||||
// carrying something nobody has accounted for.
|
// carrying something nobody has accounted for.
|
||||||
R::UnusedOption | R::UnjustifiedRetirement => Severity::Low,
|
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::DifficultyMissed => "evidence-difficulty",
|
||||||
Rule::DiscriminationMissed => "evidence-discrimination",
|
Rule::DiscriminationMissed => "evidence-discrimination",
|
||||||
Rule::DuplicateStem => "evidence-duplicate-stem",
|
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::DiscriminationMissed
|
||||||
| Rule::NonfunctioningDistractor
|
| Rule::NonfunctioningDistractor
|
||||||
| Rule::DuplicateStem => "evidence",
|
| 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::DifficultyMissed,
|
||||||
Rule::DiscriminationMissed,
|
Rule::DiscriminationMissed,
|
||||||
Rule::DuplicateStem,
|
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::DifficultyMissed => "observed difficulty was far from predicted",
|
||||||
Rule::DiscriminationMissed => "observed discrimination contradicted the prediction",
|
Rule::DiscriminationMissed => "observed discrimination contradicted the prediction",
|
||||||
Rule::DuplicateStem => "two items have nearly the same stem",
|
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_key_positions(catalog, t));
|
||||||
out.extend(lint_option_counts(catalog));
|
out.extend(lint_option_counts(catalog));
|
||||||
out.extend(lint_duplicate_stems(catalog, t));
|
out.extend(lint_duplicate_stems(catalog, t));
|
||||||
|
out.extend(lint_glossary(catalog));
|
||||||
|
|
||||||
out.sort_by(|a, b| {
|
out.sort_by(|a, b| {
|
||||||
b.severity
|
b.severity
|
||||||
@@ -705,7 +836,12 @@ pub fn lint_item(entry: &Entry, course: &CourseFile, t: &Thresholds) -> Vec<Find
|
|||||||
if is_ready {
|
if is_ready {
|
||||||
for o in &it.options {
|
for o in &it.options {
|
||||||
if !o.correct {
|
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(
|
push(
|
||||||
Rule::UndesignedDistractor,
|
Rule::UndesignedDistractor,
|
||||||
Severity::Medium,
|
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(
|
push(
|
||||||
Rule::NoStudentFeedback,
|
Rule::NoStudentFeedback,
|
||||||
Severity::Low,
|
Severity::Low,
|
||||||
|
|||||||
@@ -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
@@ -282,8 +282,9 @@ pub(crate) struct LintArgs {
|
|||||||
/// Skip these rule codes.
|
/// Skip these rule codes.
|
||||||
#[arg(long, value_delimiter = ',')]
|
#[arg(long, value_delimiter = ',')]
|
||||||
pub(crate) ignore: Vec<String>,
|
pub(crate) ignore: Vec<String>,
|
||||||
/// Only report findings at this severity or above.
|
/// Only report findings at this severity or above. Notes are printed but
|
||||||
#[arg(long, value_enum, default_value = "low")]
|
/// never make lint fail.
|
||||||
|
#[arg(long, value_enum, default_value = "note")]
|
||||||
pub(crate) min_severity: SeverityArg,
|
pub(crate) min_severity: SeverityArg,
|
||||||
/// Exit 0 even when findings exist.
|
/// Exit 0 even when findings exist.
|
||||||
#[arg(long)]
|
#[arg(long)]
|
||||||
@@ -354,6 +355,7 @@ impl StyleArg {
|
|||||||
|
|
||||||
#[derive(Debug, Clone, Copy, ValueEnum)]
|
#[derive(Debug, Clone, Copy, ValueEnum)]
|
||||||
pub(crate) enum SeverityArg {
|
pub(crate) enum SeverityArg {
|
||||||
|
Note,
|
||||||
Low,
|
Low,
|
||||||
Medium,
|
Medium,
|
||||||
High,
|
High,
|
||||||
@@ -363,6 +365,7 @@ impl SeverityArg {
|
|||||||
/// Converts the CLI value into the library's [`Severity`].
|
/// Converts the CLI value into the library's [`Severity`].
|
||||||
pub(crate) fn as_severity(self) -> Severity {
|
pub(crate) fn as_severity(self) -> Severity {
|
||||||
match self {
|
match self {
|
||||||
|
SeverityArg::Note => Severity::Note,
|
||||||
SeverityArg::Low => Severity::Low,
|
SeverityArg::Low => Severity::Low,
|
||||||
SeverityArg::Medium => Severity::Medium,
|
SeverityArg::Medium => Severity::Medium,
|
||||||
SeverityArg::High => Severity::High,
|
SeverityArg::High => Severity::High,
|
||||||
|
|||||||
@@ -16,6 +16,7 @@ use std::path::Path;
|
|||||||
|
|
||||||
use coursebank::assessment::AssessmentFile;
|
use coursebank::assessment::AssessmentFile;
|
||||||
use coursebank::bank::BankFile;
|
use coursebank::bank::BankFile;
|
||||||
|
use coursebank::catalog::Severity;
|
||||||
use coursebank::course::fragment::{self, Section};
|
use coursebank::course::fragment::{self, Section};
|
||||||
use coursebank::course::{COURSE_FILE, CourseFile};
|
use coursebank::course::{COURSE_FILE, CourseFile};
|
||||||
use coursebank::error::{Error, Result};
|
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.
|
/// `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
|
/// 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> {
|
pub(crate) fn lint(cli: &Cli, args: &LintArgs) -> Result<Outcome> {
|
||||||
if args.list_rules {
|
if args.list_rules {
|
||||||
println!("{:<32} {:<8} WHAT IT CATCHES", "CODE", "SEVERITY");
|
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.");
|
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)
|
Ok(Outcome::Ok)
|
||||||
} else {
|
} else {
|
||||||
Ok(Outcome::Findings)
|
Ok(Outcome::Findings)
|
||||||
|
|||||||
@@ -809,6 +809,10 @@ impl Gap {
|
|||||||
/// How much attention a finding deserves.
|
/// How much attention a finding deserves.
|
||||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
|
||||||
pub enum Severity {
|
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.
|
/// Worth knowing.
|
||||||
Low,
|
Low,
|
||||||
/// Worth scheduling.
|
/// Worth scheduling.
|
||||||
@@ -821,6 +825,7 @@ impl Severity {
|
|||||||
/// A short label for report output.
|
/// A short label for report output.
|
||||||
pub fn label(self) -> &'static str {
|
pub fn label(self) -> &'static str {
|
||||||
match self {
|
match self {
|
||||||
|
Severity::Note => "note",
|
||||||
Severity::Low => "low",
|
Severity::Low => "low",
|
||||||
Severity::Medium => "medium",
|
Severity::Medium => "medium",
|
||||||
Severity::High => "high",
|
Severity::High => "high",
|
||||||
|
|||||||
@@ -818,6 +818,118 @@ impl super::CourseFile {
|
|||||||
out
|
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.
|
/// The validation messages for everything 2.1 adds.
|
||||||
///
|
///
|
||||||
/// Each message names the id it is about first, in backticks, so
|
/// Each message names the id it is about first, in backticks, so
|
||||||
|
|||||||
@@ -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());
|
||||||
|
}
|
||||||
Reference in new issue
Block a user