feat(validate): 2.1 errors for the glossary registries
Validation now checks what 2.1 adds: registry ids carry their prefix and
are unique across all registries (E2101); a target's terms, equations,
values, and misconceptions name declared entries (E2102); equation
symbols resolve (E2103); values give a value or an ordered range and a
declared term (E2104); citation keys in the new registries resolve
(E2105); brace references in student-facing prose resolve (E2106);
`conflicts` and `target_text_forbid` patterns compile (E2107); and a bank
option's misconception_id is declared (E2108).
An unresolved {lo-...} or {t-...} in a field 2.0 already had (objective
and target text, reading notes) is left to the linter, because 2.0
accepted it and rendered it literally; the new reference kinds and the
new fields are checked everywhere.
Adds the `regex` crate, with default features off, for the course's own
patterns. Each error has a test built from the prototype's self-test.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
7 files changed
+915
-36
No files matched your search
@@ -606,6 +606,552 @@ pub fn brace_refs(prose: &str) -> Vec<(std::ops::Range<usize>, &str)> {
|
||||
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::Regex, String> {
|
||||
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<Prose<'_>> {
|
||||
/// Adds one field when it holds text.
|
||||
fn push<'a>(
|
||||
out: &mut Vec<Prose<'a>>,
|
||||
(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<String> {
|
||||
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<String> {
|
||||
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<String> {
|
||||
let mut issues = Vec::new();
|
||||
let empty = |s: &str| s.trim().is_empty();
|
||||
let cite = |issues: &mut Vec<String>, 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<String> {
|
||||
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<String> {
|
||||
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<String> {
|
||||
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<String> {
|
||||
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::*;
|
||||
@@ -639,6 +1185,29 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
#[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}")
|
||||
|
||||
Reference in new issue
Block a user