// SPDX-License-Identifier: Prosperity-3.0.0 // Copyright Scienting // Source: https://git.scient.ing/education/coursebank //! The four registries 2.1 adds: terms, equations, values, and misconceptions. //! //! A lecture was specified by its objectives, its targets, and its readings. //! Everything else it provides lived in files coursebank could not see: the //! course's vocabulary in `terms.yaml`, its numbers in `values.yaml`, its named //! mistakes in each pipeline's notes, and its equations nowhere at all. The //! lecture page showed students half of what they study from, and the slide, //! brief, and item pipelines each kept a copy of the rest that drifted. //! //! These registries are keyed by id like [`CourseFile::learning_targets`], and //! they follow the same rule: an id has one definition site. Each id carries a //! prefix, `term-`, `eq-`, `val-`, or `mis-`, so an id in an item, a reading, a //! report, or a brace reference says which registry it belongs to without a //! lookup. //! //! The direction of every edge matters. A [`Target`] lists the entries it needs, //! and nothing points back: which lecture introduces a term is derived from the //! first target, in teaching order, that lists it, the same way an objective's //! lectures are derived from `teaches`. There is no `introduced_in` field to //! keep in step. //! //! Each prose field is either student-facing or instructor-facing, and the //! difference is enforced by what the renderers read. `notes_private`, //! `evidence`, `conflicts`, `status`, and a target's [`Authoring`] notes never //! reach a student page or a student-visible export. //! //! [`CourseFile::learning_targets`]: super::CourseFile::learning_targets //! [`Target`]: super::Target use serde::{Deserialize, Serialize}; use crate::taxonomy::ErrorType; /// The id prefix of a term. pub const TERM_PREFIX: &str = "term-"; /// The id prefix of an equation. pub const EQUATION_PREFIX: &str = "eq-"; /// The id prefix of a value. pub const VALUE_PREFIX: &str = "val-"; /// The id prefix of a misconception. pub const MISCONCEPTION_PREFIX: &str = "mis-"; /// Whether an entry is waiting for the instructor. /// /// A pipeline that adds an entry marks it proposed, and the instructor approves /// it by deleting the line. Checks treat proposed entries exactly like approved /// ones, so a new entry is checked from the day it is written; the linter only /// counts how many are waiting. This is the `terms.yaml` convention, kept. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum EntryStatus { /// Added by a pipeline or a collaborator, not yet approved. Proposed, /// Approved. The same as leaving the field out. Approved, } /// A citation into `references`, with a location inside the work. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct SourceRef { /// Citation key into [`super::CourseFile::references`]. #[serde(rename = "ref")] pub reference: String, /// Where inside the work: `ยง6.1`, `pp. 4-9`, `eq. 3.12`. #[serde(default, skip_serializing_if = "Option::is_none")] pub locator: Option, } /// Whether a student can look a term up under the name the course uses. #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum TermKind { /// The textbooks use this name for this idea. #[default] Standard, /// A standard idea under the course's own name or notation. A student can /// look it up only if told the textbook name. Renamed, /// A label or metaphor the course invented. No textbook uses it. Coined, } impl TermKind { /// Whether this is the default, so serializing can leave it out. fn is_standard(&self) -> bool { *self == TermKind::Standard } /// The YAML spelling. pub fn as_str(self) -> &'static str { match self { TermKind::Standard => "standard", TermKind::Renamed => "renamed", TermKind::Coined => "coined", } } } /// A name an assigned text uses for a term. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct TextbookName { /// The name the text uses. pub term: String, /// Citation key into `references`; absent for a plain-English equivalent. #[serde(rename = "ref", default, skip_serializing_if = "Option::is_none")] pub reference: Option, /// Where that text uses it. #[serde(default, skip_serializing_if = "Option::is_none")] pub locator: Option, } /// One term students meet in this course. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Term { /// The word or phrase as this course writes it. Student-facing. pub term: String, /// One plain sentence that defines the term without using it. /// Student-facing; may hold brace references. pub definition: String, /// Whether a student can look it up under this name. #[serde(default, skip_serializing_if = "TermKind::is_standard")] pub kind: TermKind, /// What the assigned texts call it, the first-listed text first. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub textbook: Vec, /// Other surface forms that count as a use of the term: plurals, /// abbreviations. Matching is case-insensitive and whole-word. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub variants: Vec, /// The notation, when the term names a quantity, in coursebank markup. #[serde(default, skip_serializing_if = "Option::is_none")] pub symbol: Option, /// Units of the quantity the term names. #[serde(default, skip_serializing_if = "Option::is_none")] pub units: Option, /// Coined terms only: the plain wording items write instead of the label. #[serde(default, skip_serializing_if = "Option::is_none")] pub exam_wording: Option, /// Whether the entry is waiting for approval. Instructor-facing. #[serde(default, skip_serializing_if = "Option::is_none")] pub status: Option, /// Free-form tags. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub tags: Vec, /// Instructor-facing notes. Never rendered for students. #[serde(default, skip_serializing_if = "Option::is_none")] pub notes_private: Option, } impl Term { /// The term and every variant: the surface forms that count as a use. /// /// # Returns /// /// Non-empty forms, the term first. pub fn forms(&self) -> Vec<&str> { std::iter::once(self.term.as_str()) .chain(self.variants.iter().map(String::as_str)) .filter(|w| !w.trim().is_empty()) .collect() } } /// The six things a question can ask about a relation without evaluating it. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum RelationForm { /// Which way the output moves when one input rises. Direction, /// What the relation gives at a boundary. Limit, /// Whether a stated difference is large or negligible on the relation's /// own scale. Scale, /// Which term governs an observation. DominantTerm, /// The reference state or normalizer. HeldFixed, /// A result the relation cannot support. Misuse, } impl RelationForm { /// Every form, in the order the objectives prompt lists them. pub const ALL: [RelationForm; 6] = [ RelationForm::Direction, RelationForm::Limit, RelationForm::Scale, RelationForm::DominantTerm, RelationForm::HeldFixed, RelationForm::Misuse, ]; /// The YAML spelling. pub fn as_str(self) -> &'static str { match self { RelationForm::Direction => "direction", RelationForm::Limit => "limit", RelationForm::Scale => "scale", RelationForm::DominantTerm => "dominant_term", RelationForm::HeldFixed => "held_fixed", RelationForm::Misuse => "misuse", } } /// The form as a student reads it on a lecture page. pub fn label(self) -> &'static str { match self { RelationForm::Direction => "direction", RelationForm::Limit => "limit", RelationForm::Scale => "scale", RelationForm::DominantTerm => "dominant term", RelationForm::HeldFixed => "held fixed", RelationForm::Misuse => "misuse", } } } /// One symbol in an equation. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Symbol { /// The symbol as it appears in `tex`. pub symbol: String, /// Term id, when the quantity has a glossary entry. #[serde(default, skip_serializing_if = "Option::is_none")] pub term: Option, /// What the symbol stands for, when it has no term. #[serde(default, skip_serializing_if = "Option::is_none")] pub meaning: Option, /// Units, when the symbol has no term or the term gives none. #[serde(default, skip_serializing_if = "Option::is_none")] pub units: Option, } /// Something a relation says that a question can test without evaluating it. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Implication { /// Which of the six forms it takes. pub form: RelationForm, /// The implication as one student-facing sentence; may hold brace /// references. pub statement: String, } /// One relation students meet in this course. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Equation { /// The name students would use. Student-facing. pub name: String, /// The relation in LaTeX, without surrounding dollar signs. pub tex: String, /// What the relation claims, in words. Student-facing; may hold brace /// references. pub says: String, /// Every symbol in `tex`, in order of first appearance. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub symbols: Vec, /// What the relation says that a question can test without evaluating it. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub implications: Vec, /// Conditions that must hold for the relation to apply. Student-facing. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub assumes: Vec, /// Cases where the relation breaks or misleads. Student-facing. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub fails_when: Vec, /// Students are expected to know it from memory. #[serde(default, skip_serializing_if = "Option::is_none")] pub recall: Option, /// Where the course's own source states it. #[serde(default, skip_serializing_if = "Option::is_none")] pub source: Option, /// Whether the entry is waiting for approval. Instructor-facing. #[serde(default, skip_serializing_if = "Option::is_none")] pub status: Option, /// Free-form tags. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub tags: Vec, /// Instructor-facing notes. Never rendered for students. #[serde(default, skip_serializing_if = "Option::is_none")] pub notes_private: Option, } /// One number students are taught. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Value { /// The quantity, specifically. pub name: String, /// The value as taught, rounded as students learn it. #[serde(default, skip_serializing_if = "Option::is_none")] pub value: Option, /// Low and high, when the course teaches a range rather than one value. #[serde(default, skip_serializing_if = "Option::is_none")] pub range: Option<[f64; 2]>, /// Units, as printed. #[serde(default, skip_serializing_if = "Option::is_none")] pub units: Option, /// The one wording every material uses. `{val-...}` in prose renders this. pub say: String, /// The unrounded value, for explanations and solutions. #[serde(default, skip_serializing_if = "Option::is_none")] pub exact: Option, /// Term id of the quantity, when it has a glossary entry. #[serde(default, skip_serializing_if = "Option::is_none")] pub term: Option, /// Where the number comes from. #[serde(default, skip_serializing_if = "Option::is_none")] pub source: Option, /// Regular expressions for variants that must not appear in student-facing /// text or items. Instructor-facing. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub conflicts: Vec, /// Students are expected to know it, so no item may print it. #[serde(default, skip_serializing_if = "Option::is_none")] pub recall: Option, /// Whether the entry is waiting for approval. Instructor-facing. #[serde(default, skip_serializing_if = "Option::is_none")] pub status: Option, /// Free-form tags. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub tags: Vec, /// Instructor-facing notes. Never rendered for students. #[serde(default, skip_serializing_if = "Option::is_none")] pub notes_private: Option, } /// Where a misconception has been seen. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum EvidenceKind { /// An exam item drew it. Exam, /// A homework item drew it. Homework, /// An in-class poll drew it. Poll, /// The instructor has seen it. Instructor, /// The education literature reports it. Literature, /// An assigned text states or implies it, so the correction must name the /// framing it replaces rather than contradict the text silently. Textbook, /// A simulated student, the weakest evidence. Persona, } /// One sighting of a misconception. Instructor-facing. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Evidence { /// Where it was seen. pub kind: EvidenceKind, /// What was seen: `Exam 2 Q23, 22% chose it.` #[serde(default, skip_serializing_if = "Option::is_none")] pub detail: Option, /// Citation key, for literature or textbook evidence. #[serde(rename = "ref", default, skip_serializing_if = "Option::is_none")] pub reference: Option, /// Where in that work. #[serde(default, skip_serializing_if = "Option::is_none")] pub locator: Option, } /// One named mistake. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Misconception { /// The wrong idea as a student holds it. Student-facing. pub belief: String, /// Why it fails and what is true instead. Student-facing. pub correction: String, /// What kind of mistake it is, in the bank's terms. #[serde(default, skip_serializing_if = "Option::is_none")] pub error_type: Option, /// Where it has been seen, strongest first. Instructor-facing. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub evidence: Vec, /// Whether the entry is waiting for approval. Instructor-facing. #[serde(default, skip_serializing_if = "Option::is_none")] pub status: Option, /// Free-form tags. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub tags: Vec, /// Instructor-facing notes. Never rendered for students. #[serde(default, skip_serializing_if = "Option::is_none")] pub notes_private: Option, } /// Notes for whoever writes items, slides, or the brief from a target. /// /// These are the per-target judgments the objectives prompt asks for and then /// loses in chat output. Instructor-facing: never rendered for students. #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Authoring { /// The most demanding fair item at the ceiling: the evidence for it. #[serde(default, skip_serializing_if = "Option::is_none")] pub ceiling_item: Option, /// What an item on this target hands the student. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub supplied: Vec, /// Conditions an item's stem must meet to stay fair. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub constraints: Vec, /// The arithmetic an item needs, and roughly how long it takes. #[serde(default, skip_serializing_if = "Option::is_none")] pub number_work: Option, /// When the target tests a relation without evaluating it, which form. #[serde(default, skip_serializing_if = "Option::is_none")] pub relation_form: Option, /// Named cases that teach this target, kept out of the target text. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub examples: Vec, } /// What a lecture material link points at. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum MaterialKind { /// The slide deck. Slides, /// The lecture brief. Brief, /// Notes. Notes, /// A notebook. Notebook, /// A recording. Recording, /// A homework set. Homework, /// Anything else. Other, } impl MaterialKind { /// The YAML spelling, which is also the default link text. pub fn as_str(self) -> &'static str { match self { MaterialKind::Slides => "slides", MaterialKind::Brief => "brief", MaterialKind::Notes => "notes", MaterialKind::Notebook => "notebook", MaterialKind::Recording => "recording", MaterialKind::Homework => "homework", MaterialKind::Other => "other", } } } /// A link a lecture page lists beside the readings. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Material { /// What it is. pub kind: MaterialKind, /// Link text. Defaults to the kind. #[serde(default, skip_serializing_if = "Option::is_none")] pub title: Option, /// Where it lives. pub url: String, } impl Material { /// The link text: the title, else the kind. pub fn label(&self) -> &str { self.title.as_deref().unwrap_or(self.kind.as_str()) } } /// Which registry an id belongs to, read from its prefix. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] pub enum RefKind { /// `term-...` Term, /// `eq-...` Equation, /// `val-...` Value, /// `mis-...` Misconception, /// `lo-...` Objective, /// `t-...` Target, } impl RefKind { /// The registry an id names by its prefix. /// /// `term-` is tested before `t-`, since every term id also starts with `t`. /// /// # Arguments /// /// * `id` - the id. /// /// # Returns /// /// The kind, or `None` for an id with no registry prefix. pub fn of(id: &str) -> Option { [ (TERM_PREFIX, RefKind::Term), (EQUATION_PREFIX, RefKind::Equation), (VALUE_PREFIX, RefKind::Value), (MISCONCEPTION_PREFIX, RefKind::Misconception), ("lo-", RefKind::Objective), ("t-", RefKind::Target), ] .into_iter() .find(|(prefix, _)| id.starts_with(prefix)) .map(|(_, kind)| kind) } /// What one entry is called in a message. pub fn noun(self) -> &'static str { match self { RefKind::Term => "term", RefKind::Equation => "equation", RefKind::Value => "value", RefKind::Misconception => "misconception", RefKind::Objective => "objective", RefKind::Target => "target", } } } /// Whether an id is a prefix followed by lowercase words joined by single /// hyphens: the `^prefix-[a-z0-9]+(-[a-z0-9]+)*$` pattern the schemas state. /// /// # Arguments /// /// * `id` - the id to test. /// * `prefix` - the prefix it must carry, hyphen included. /// /// # Returns /// /// `true` when the id matches. pub fn is_prefixed_id(id: &str, prefix: &str) -> bool { id.strip_prefix(prefix).is_some_and(|rest| { !rest.is_empty() && !rest.starts_with('-') && !rest.ends_with('-') && !rest.contains("--") && rest .chars() .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-') }) } /// Every brace reference in a piece of prose: `{term-...}`, `{eq-...}`, /// `{val-...}`, `{mis-...}`, `{lo-...}`, or `{t-...}`. /// /// Only a brace whose content is a prefixed id counts, so `10^{59}` and /// `\text{final}` are never references. That is the same pattern the prototype /// states as `\{((?:lo|t|term|eq|val|mis)-[a-z0-9]+(?:-[a-z0-9]+)*)\}`. /// /// # Arguments /// /// * `prose` - the text to scan. /// /// # Returns /// /// The ids in order of appearance, with the byte span of each brace pair. pub fn brace_refs(prose: &str) -> Vec<(std::ops::Range, &str)> { let mut out = Vec::new(); let mut from = 0; while let Some(open) = prose[from..].find('{').map(|i| i + from) { let Some(close) = prose[open..].find('}').map(|i| i + open) else { break; }; let inner = &prose[open + 1..close]; // A second `{` before the close means this opener was not a reference; // resume at the inner one. if let Some(nested) = inner.rfind('{') { from = open + 1 + nested; continue; } let referenced = RefKind::of(inner).is_some_and(|kind| { let prefix = match kind { RefKind::Term => TERM_PREFIX, RefKind::Equation => EQUATION_PREFIX, RefKind::Value => VALUE_PREFIX, RefKind::Misconception => MISCONCEPTION_PREFIX, RefKind::Objective => "lo-", RefKind::Target => "t-", }; is_prefixed_id(inner, prefix) }); if referenced { out.push((open..close + 1, inner)); } from = close + 1; } out } /// Compiles one of the course's regular expressions. /// /// The syntax is the `regex` crate's, which matches Python's `re` for /// everything the patterns in a course need (classes, `\b`, `\s`, escapes, /// quantifiers) but has no look-around and no backreferences. /// /// # Arguments /// /// * `pattern` - the pattern as written in YAML. /// * `ignore_case` - whether to match case-insensitively. /// /// # Returns /// /// The compiled pattern. /// /// # Errors /// /// The parser's own one-line reason when the pattern does not compile. pub fn compile(pattern: &str, ignore_case: bool) -> std::result::Result { regex::RegexBuilder::new(pattern) .case_insensitive(ignore_case) .build() .map_err(|e| { let text = e.to_string(); // The parser's message spans several lines with a caret under the // offending character; its last line says what is wrong. text.lines() .rev() .find_map(|l| l.trim().strip_prefix("error: ")) .unwrap_or(text.trim()) .to_string() }) } /// Whether a word or phrase appears in text as a whole word, ignoring case. /// /// # Arguments /// /// * `haystack` - the text to search. /// * `needle` - the word or phrase. /// /// # Returns /// /// `true` when found with a non-alphanumeric character, or the end of the text, /// on both sides. pub fn contains_word(haystack: &str, needle: &str) -> bool { let needle = needle.trim(); if needle.is_empty() { return false; } let pattern = format!(r"\b{}\b", regex::escape(needle)); compile(&pattern, true).is_ok_and(|re| re.is_match(haystack)) } /// One student-facing prose field, for the checks that read every one. #[derive(Debug, Clone)] pub struct Prose<'a> { /// What owns it, as a message names it: ``target `t-x` ``. pub owner: String, /// The owning id. pub id: &'a str, /// The field, with its position for a list: `implications[2]`. pub field: String, /// The text. pub text: &'a str, /// Whether the field existed before 2.1. An unresolved `{lo-...}` or /// `{t-...}` in one of these rendered literally under 2.0, so it is a lint /// warning rather than an error; see `docs/design/2.1/CODES.md`. pub legacy: bool, } impl super::CourseFile { /// Whether a brace reference names a declared entry of its registry. /// /// An objective or target reference resolves against either tier, as the /// 2.0 placeholder rule did. /// /// # Arguments /// /// * `id` - the referenced id. /// /// # Returns /// /// `true` when declared. pub fn resolves(&self, id: &str) -> bool { match RefKind::of(id) { Some(RefKind::Term) => self.terms.contains_key(id), Some(RefKind::Equation) => self.equations.contains_key(id), Some(RefKind::Value) => self.values.contains_key(id), Some(RefKind::Misconception) => self.misconceptions.contains_key(id), Some(RefKind::Objective | RefKind::Target) => { self.learning_objectives.contains_key(id) || self.learning_targets.contains_key(id) } None => false, } } /// Every student-facing prose field in the course, in registry order. /// /// This is the list brace references are resolved in and `conflicts` /// patterns are matched against: objective and target text, descriptions /// and explanations, definitions, what an equation says and implies, /// beliefs and corrections, and a lecture's description and reading notes. /// /// # Returns /// /// One entry per non-empty field. pub fn student_prose(&self) -> Vec> { /// Adds one field when it holds text. fn push<'a>( out: &mut Vec>, (noun, id): (&str, &'a str), field: String, text: Option<&'a str>, legacy: bool, ) { if let Some(text) = text.filter(|t| !t.trim().is_empty()) { out.push(Prose { owner: format!("{noun} `{id}`"), id, field, text, legacy, }); } } let mut out = Vec::new(); for (id, o) in &self.learning_objectives { let at = ("objective", id.as_str()); push(&mut out, at, "text".into(), Some(&o.text), true); push( &mut out, at, "description".into(), o.description.as_deref(), false, ); } for (id, t) in &self.learning_targets { let at = ("target", id.as_str()); push(&mut out, at, "text".into(), Some(&t.text), true); push( &mut out, at, "explanation".into(), t.explanation.as_deref(), false, ); } for (id, t) in &self.terms { push( &mut out, ("term", id), "definition".into(), Some(&t.definition), false, ); } for (id, e) in &self.equations { let at = ("equation", id.as_str()); push(&mut out, at, "says".into(), Some(&e.says), false); for (k, imp) in e.implications.iter().enumerate() { push( &mut out, at, format!("implications[{k}]"), Some(&imp.statement), false, ); } for (k, a) in e.assumes.iter().enumerate() { push(&mut out, at, format!("assumes[{k}]"), Some(a), false); } for (k, a) in e.fails_when.iter().enumerate() { push(&mut out, at, format!("fails_when[{k}]"), Some(a), false); } } for (id, m) in &self.misconceptions { let at = ("misconception", id.as_str()); push(&mut out, at, "belief".into(), Some(&m.belief), false); push( &mut out, at, "correction".into(), Some(&m.correction), false, ); } for (id, lecture) in &self.lectures { let at = ("lecture", id.as_str()); push( &mut out, at, "description".into(), lecture.description.as_deref(), false, ); for (k, r) in lecture.readings.iter().enumerate() { for (name, text) in [ ("summary", &r.summary), ("focus", &r.focus), ("skip", &r.skip), ] { let field = format!("reading {} {name}", k + 1); push(&mut out, at, field, text.as_deref(), true); } } } out } /// The validation messages for everything 2.1 adds. /// /// Each message names the id it is about first, in backticks, so /// [`CourseFile::validate`](super::CourseFile::validate) can prefix it /// with the file that defined the id. `docs/design/2.1/CODES.md` maps each /// message to the specification's error code. /// /// # Returns /// /// One message per problem. pub(super) fn glossary_problems(&self) -> Vec { let mut issues = Vec::new(); issues.extend(self.registry_id_problems()); issues.extend(self.entry_problems()); issues.extend(self.target_link_problems()); issues.extend(self.brace_problems()); issues.extend(self.pattern_problems()); issues.extend(self.policy_problems()); issues } /// Ids that lack their registry's prefix, and ids declared in two /// registries (E2101, and the `propertyNames` patterns of the schemas). fn registry_id_problems(&self) -> Vec { let mut issues = Vec::new(); let prefixed: [(&str, &str, Vec<&String>); 4] = [ ("term", TERM_PREFIX, self.terms.keys().collect()), ("equation", EQUATION_PREFIX, self.equations.keys().collect()), ("value", VALUE_PREFIX, self.values.keys().collect()), ( "misconception", MISCONCEPTION_PREFIX, self.misconceptions.keys().collect(), ), ]; for (noun, prefix, ids) in &prefixed { for id in ids { if !is_prefixed_id(id, prefix) { issues.push(format!( "{noun} `{id}`: a {noun} id is `{prefix}` followed by lowercase words \ joined by hyphens, such as `{prefix}{}`", super::slugify(id.trim_start_matches(prefix)) )); } } } // The objective/target pair is checked in `problems`, as it was in 2.0. // Every other pair is checked here, so an id says which registry it // belongs to and a brace reference cannot be ambiguous. let registries: [(&str, Vec<&String>); 6] = [ ( "learning objective", self.learning_objectives.keys().collect(), ), ("learning target", self.learning_targets.keys().collect()), ("term", self.terms.keys().collect()), ("equation", self.equations.keys().collect()), ("value", self.values.keys().collect()), ("misconception", self.misconceptions.keys().collect()), ]; for (i, (first, ids)) in registries.iter().enumerate() { for (second, others) in registries.iter().skip(i + 1) { if i == 0 && *second == "learning target" { continue; } for id in ids.iter().filter(|id| others.contains(id)) { issues.push(format!( "`{id}` is declared as both a {first} and a {second}; an id is unique \ across all registries" )); } } } issues } /// Fields within one entry: required text, equation symbols (E2103), /// values (E2104), and citation keys (E2105). fn entry_problems(&self) -> Vec { let mut issues = Vec::new(); let empty = |s: &str| s.trim().is_empty(); let cite = |issues: &mut Vec, owner: String, field: &str, key: &str| { if !self.references.contains_key(key) { issues.push(format!( "{owner}: {field} cites `{key}`, which is not in references" )); } }; for (id, t) in &self.terms { if empty(&t.term) { issues.push(format!("term `{id}`: empty term")); } if empty(&t.definition) { issues.push(format!("term `{id}`: empty definition")); } for (k, name) in t.textbook.iter().enumerate() { if empty(&name.term) { issues.push(format!("term `{id}`: textbook name {} is empty", k + 1)); } if let Some(key) = &name.reference { cite(&mut issues, format!("term `{id}`"), "textbook", key); } } } for (id, e) in &self.equations { for (field, value) in [("name", &e.name), ("tex", &e.tex), ("says", &e.says)] { if empty(value) { issues.push(format!("equation `{id}`: empty {field}")); } } for s in &e.symbols { if empty(&s.symbol) { issues.push(format!("equation `{id}`: a symbol has no `symbol`")); } match (&s.term, &s.meaning) { (Some(term), _) if !self.terms.contains_key(term) => issues.push(format!( "equation `{id}`: symbol `{}` names the term `{term}`, which is not \ declared", s.symbol )), (None, None) => issues.push(format!( "equation `{id}`: symbol `{}` needs a `term` or a `meaning`", s.symbol )), _ => {} } } for imp in &e.implications { if empty(&imp.statement) { issues.push(format!( "equation `{id}`: a {} implication has no statement", imp.form.as_str() )); } } if let Some(source) = &e.source { cite( &mut issues, format!("equation `{id}`"), "source", &source.reference, ); } } for (id, v) in &self.values { if empty(&v.name) { issues.push(format!("value `{id}`: empty name")); } if empty(&v.say) { issues.push(format!("value `{id}`: empty say")); } if v.value.is_none() && v.range.is_none() { issues.push(format!("value `{id}`: give a `value` or a `range`")); } if let Some([low, high]) = v.range { if low > high { issues.push(format!( "value `{id}`: range runs from {low} down to {high}; write the low end \ first" )); } } if let Some(term) = &v.term { if !self.terms.contains_key(term) { issues.push(format!("value `{id}`: term `{term}` is not declared")); } } if let Some(source) = &v.source { cite( &mut issues, format!("value `{id}`"), "source", &source.reference, ); } } for (id, m) in &self.misconceptions { if empty(&m.belief) { issues.push(format!("misconception `{id}`: empty belief")); } if empty(&m.correction) { issues.push(format!("misconception `{id}`: empty correction")); } for evidence in &m.evidence { if let Some(key) = &evidence.reference { cite( &mut issues, format!("misconception `{id}`"), "evidence", key, ); } } } for (id, lecture) in &self.lectures { for (k, material) in lecture.materials.iter().enumerate() { if empty(&material.url) { issues.push(format!("lecture `{id}`: material {} has no url", k + 1)); } } for (k, reading) in lecture.readings.iter().enumerate() { if reading.minutes == Some(0) { issues.push(format!( "lecture `{id}` reading {}: minutes must be at least 1", k + 1 )); } } } issues } /// A target's `terms`, `equations`, `values`, and `misconceptions` each /// name a declared entry of that registry (E2102). fn target_link_problems(&self) -> Vec { let mut issues = Vec::new(); for (id, target) in &self.learning_targets { let lists = [ ("terms", &target.terms, RefKind::Term), ("equations", &target.equations, RefKind::Equation), ("values", &target.values, RefKind::Value), ( "misconceptions", &target.misconceptions, RefKind::Misconception, ), ]; for (field, ids, kind) in lists { for x in ids { if RefKind::of(x) != Some(kind) || !self.resolves(x) { issues.push(format!( "target `{id}`: `{field}` names `{x}`, which is not a declared {}", kind.noun() )); } } } } issues } /// Brace references in student-facing prose resolve (E2106). /// /// An unresolved `{lo-...}` or `{t-...}` in a field 2.0 already had is /// left to the linter, since 2.0 rendered it literally and accepted the /// course; every other unresolved reference is an error. fn brace_problems(&self) -> Vec { let mut issues = Vec::new(); for prose in self.student_prose() { for (_, id) in brace_refs(prose.text) { let kind = RefKind::of(id); let legacy_kind = matches!(kind, Some(RefKind::Objective | RefKind::Target)); if self.resolves(id) || (prose.legacy && legacy_kind) { continue; } issues.push(format!( "{}: {} refers to `{{{id}}}`, which is not a declared {}", prose.owner, prose.field, kind.map(RefKind::noun).unwrap_or("entry") )); } } issues } /// `conflicts` and `target_text_forbid` patterns compile (E2107). fn pattern_problems(&self) -> Vec { let mut issues = Vec::new(); for (id, v) in &self.values { for pattern in &v.conflicts { if let Err(reason) = compile(pattern, false) { issues.push(format!( "value `{id}`: conflicts pattern `{pattern}` does not compile: {reason}" )); } } } for pattern in &self.policy.target_text_forbid { if let Err(reason) = compile(pattern, true) { issues.push(format!( "policy.target_text_forbid: pattern `{pattern}` does not compile: {reason}" )); } } issues } /// The policy blocks 2.1 adds: level keys run 1 to 5, and durations are /// positive. fn policy_problems(&self) -> Vec { let mut issues = Vec::new(); let is_level = |k: &str| matches!(k, "1" | "2" | "3" | "4" | "5"); for key in self.policy.levels.keys().filter(|k| !is_level(k)) { issues.push(format!( "policy.levels: `{key}` is not a level; levels run from 1 to 5" )); } for (name, level) in &self.policy.levels { if level.name.trim().is_empty() { issues.push(format!("policy.levels: level {name} has an empty name")); } } for (name, blueprint) in &self.policy.blueprints { let keys = blueprint .level_counts .keys() .chain(blueprint.bonus_counts.keys()); for key in keys.filter(|k| !is_level(k)) { issues.push(format!( "policy.blueprints: `{name}` counts items at `{key}`, which is not a level" )); } if blueprint.minutes.is_some_and(|m| m <= 0.0) { issues.push(format!( "policy.blueprints: `{name}` gives no time; minutes must be above 0" )); } } if let Some(conditions) = &self.policy.exam_conditions { if conditions.seconds_per_item.is_some_and(|s| s <= 0.0) { issues.push("policy.exam_conditions: seconds_per_item must be above 0".to_string()); } } issues } } #[cfg(test)] mod tests { use super::*; #[test] fn a_term_id_is_not_read_as_a_target_id() { assert_eq!(RefKind::of("term-gap"), Some(RefKind::Term)); assert_eq!(RefKind::of("t-gap"), Some(RefKind::Target)); assert_eq!(RefKind::of("lo-x"), Some(RefKind::Objective)); assert_eq!(RefKind::of("gap"), None); } #[test] fn prefixed_ids_follow_the_schema_pattern() { assert!(is_prefixed_id("term-gap-penalty", TERM_PREFIX)); assert!(is_prefixed_id("val-alignment-count-100", VALUE_PREFIX)); assert!(!is_prefixed_id("term-", TERM_PREFIX)); assert!(!is_prefixed_id("term-Gap", TERM_PREFIX)); assert!(!is_prefixed_id("term--gap", TERM_PREFIX)); assert!(!is_prefixed_id("gap", TERM_PREFIX)); } #[test] fn only_prefixed_ids_in_braces_are_references() { let prose = "About 10^{59}, see {term-gap} and {eq-global-recurrence}; \ $U_\\text{final}$ and {t-align-fill-matrix}."; let ids: Vec<&str> = brace_refs(prose).into_iter().map(|(_, id)| id).collect(); assert_eq!( ids, vec!["term-gap", "eq-global-recurrence", "t-align-fill-matrix"] ); } #[test] fn the_example_patterns_compile_and_a_bad_one_says_why() { for pattern in [r"5\.7\s*kJ", r"\bcomput", r"10\^\{?100\}?\s*alignments"] { assert!(compile(pattern, false).is_ok(), "{pattern}"); } let reason = compile("5.7(", false).unwrap_err(); assert!(reason.contains("unclosed group"), "{reason}"); assert!(!reason.contains('\n')); assert!( compile(r"\bcalculat", true) .unwrap() .is_match("Calculate it.") ); } #[test] fn whole_words_match_regardless_of_case() { assert!(contains_word("Think in Decades.", "decades")); assert!(!contains_word("decadent", "decade")); assert!(contains_word("a gap penalty", "gap penalty")); assert!(!contains_word("anything", "")); } #[test] fn a_reference_inside_latex_braces_is_still_found() { let ids: Vec<&str> = brace_refs("\\frac{a}{b} {val-x}") .into_iter() .map(|(_, id)| id) .collect(); assert_eq!(ids, vec!["val-x"]); } }