Files
coursebank/docs/design/2.1/CODES.md
T
alexmandClaude b5cae6afac docs: schema 2.1 guide, codes, changelog, and report
A guide page for the four registries: where entries live, how targets
point at them, the other new fields, the brace-reference table, what
students never see, the lecture and glossary pages, every new error and
lint rule, and the migration from terms.yaml and values.yaml. The setup
guide points at it.

The README covers glossary.yaml, the nine schemas, the 2.1 checks, the
glossary lint family and the note severity, the new lecture commands and
report sections, migrate glossary, and schema version 2.1. Module docs
and the changelog follow.

docs/design/2.1/CODES.md maps the specification's E, W, and I codes to
coursebank's messages and lint codes, each with its test, and REPORT.md
records what changed, the two remaining schema differences, every choice
made where the specification left room, and suggested changes to it. A
new test covers the validation messages the specification does not
number.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 12:31:01 -05:00

7.6 KiB

Codes: the specification's placeholders, mapped onto coursebank

coursebank's validation errors are plain messages with no code, and its lint rules have kebab-case codes prefixed by family (cue-, clarity-, complete-, pool-, evidence-). The specification's codes map onto those as below. An error is identified by its message, which starts with the entry it is about in backticks, so validate can prefix it with the file that defines that entry. The message wording is stable: the tests in tests/validate_2_1.rs assert it.

Errors (coursebank validate, exit 2)

Spec Message (x stands for the id) Where Test
E2101 term `x` is defined in two places: A and B. An id has one definition site; delete one or rename it. (two files, one registry; the 2.0 message, now for the four new registries too) fragment.rs, duplicate schema_2_1.rs: a_glossary_id_defined_twice_names_both_files
E2101 `x` is declared as both a term and a value; an id is unique across all registries (any two of objectives, targets, terms, equations, values, misconceptions) glossary.rs, registry_id_problems e2101_an_id_in_two_registries
E2101 (added) term `x`: a term id is `term-` followed by lowercase words joined by hyphens, such as `term-…` (the schemas' propertyNames patterns, enforced at load since nothing validates YAML against the JSON Schema) glossary.rs, registry_id_problems e2101_a_registry_id_without_its_prefix
E2102 target `t`: `terms` names `x`, which is not a declared term (also when the id belongs to another registry) glossary.rs, target_link_problems e2102_a_target_lists_an_undeclared_entry, e2102_an_id_listed_under_the_wrong_registry
E2103 equation `eq-x`: symbol `d` names the term `term-y`, which is not declared glossary.rs, entry_problems e2103_a_symbol_naming_an_undeclared_term
E2103 equation `eq-x`: symbol `d` needs a `term` or a `meaning` glossary.rs, entry_problems e2103_a_symbol_with_neither_term_nor_meaning
E2104 value `val-x`: give a `value` or a `range` glossary.rs, entry_problems e2104_a_value_with_neither_value_nor_range
E2104 value `val-x`: range runs from 9 down to 1; write the low end first glossary.rs, entry_problems e2104_a_range_that_runs_high_to_low_and_an_undeclared_term
E2104 value `val-x`: term `term-y` is not declared glossary.rs, entry_problems the same test
E2105 term `x`: textbook cites `KEY`, which is not in references (also source on equations and values, evidence on misconceptions) glossary.rs, entry_problems e2105_a_citation_key_not_in_references
E2106 lecture `l09`: description refers to `{term-x}`, which is not a declared term (owner and field vary; every student-facing prose field) glossary.rs, brace_problems e2106_a_brace_reference_that_does_not_resolve, e2106_a_new_field_checks_every_kind
E2106 (narrowed) an unresolved {lo-…} or {t-…} in a reading's summary, focus, or skip is not an error but the lint rule glossary-unresolved-reference, because 2.0 accepted it (Q2, option b) lint/glossary.rs e2106_an_old_reading_keeps_its_2_0_behaviour_for_targets, an_unresolved_target_reference_in_an_old_reading_field_is_a_warning
E2107 value `val-x`: conflicts pattern `…` does not compile: … glossary.rs, pattern_problems e2107_a_pattern_that_does_not_compile
E2107 policy.target_text_forbid: pattern `…` does not compile: … glossary.rs, pattern_problems the same test
E2108 option o-x: misconception_id `mis-x` is not a declared misconception bank.rs, validate_item e2108_an_option_names_an_undeclared_misconception

Errors the specification does not number, added because the schemas imply them (required, non-empty, or in a range) and the loader would otherwise accept the file:

Message Test (tests/validate_2_1.rs)
term `x`: empty term, empty definition, textbook name N is empty; equation `eq-x`: empty name (or tex, says), a symbol has no `symbol` , a direction implication has no statement; value `val-x`: empty name, empty say; misconception `mis-x`: empty belief, empty correction empty_required_text_and_out_of_range_numbers_are_errors (one of each kind)
lecture `l09`: material 2 has no url; lecture `l09` reading 1: minutes must be at least 1 the same test
policy.levels: `7` is not a level; levels run from 1 to 5; policy.blueprints: `module` counts items at `6`, which is not a level policy_levels_and_blueprints_are_keyed_by_level
policy.levels: level 3 has an empty name; policy.blueprints: `module` gives no time; minutes must be above 0; policy.exam_conditions: seconds_per_item must be above 0 empty_required_text_and_out_of_range_numbers_are_errors

Lint (coursebank lint)

Every 2.1 rule is in a new glossary family.

Spec Code Severity Test (tests/lint_2_1.rs)
W2101 glossary-unused low w2101_an_entry_nothing_needs
W2102 glossary-no-textbook-name medium w2102_a_renamed_term_with_no_textbook_name
W2103 glossary-no-exam-wording low w2103_a_coined_term_with_no_exam_wording
W2104 glossary-circular-definition low w2104_a_definition_that_uses_its_term
W2105 glossary-coined-in-item medium w2105_a_coined_term_in_an_item
W2106 glossary-value-unsourced low w2106_a_value_with_no_source
W2107 glossary-value-conflict medium w2107_a_value_variant_in_student_prose_and_in_an_item
W2108 glossary-forbidden-target-wording medium w2108_target_text_the_policy_forbids
W2109 glossary-unlisted-term low w2109_an_explanation_using_a_term_its_target_does_not_list, w2109_a_term_inherited_from_a_prerequisite_target_is_listed
W2110 glossary-recall-value-printed medium w2110_an_item_prints_a_recall_value
W2111 glossary-equation-no-implications low w2111_a_deep_target_on_an_equation_with_no_implications
(added) glossary-unresolved-reference medium an_unresolved_target_reference_in_an_old_reading_field_is_a_warning
I2112 glossary-defined-elsewhere note i2112_an_entry_defined_away_from_the_objective_that_first_needs_it
I2113 glossary-proposed note i2113_counts_proposed_entries

note is a new severity below low (Q3). Notes print by default, --min-severity low hides them, and lint never exits non-zero for notes alone (notes_are_printed_but_do_not_fail_lint). On the example course the glossary family reports exactly glossary-unused on val-per-decade and one glossary-proposed finding counting two entries (the_example_draws_exactly_the_two_expected_glossary_findings).

Two existing rules changed with 2.1: complete-distractor-design accepts a misconception_id as the distractor's design, and complete-student-feedback accepts a misconception_id that resolves, since the registry's correction is the feedback (a_registry_misconception_designs_a_distractor_and_gives_it_feedback).

Regular expressions

conflicts and target_text_forbid use the Rust regex crate (1.x, std, unicode-perl, unicode-case). Its syntax matches Python's re for everything the examples use (\b, \s, \., \^, \{?), and it has no look-around and no backreferences; a pattern that uses them fails E2107 with the crate's reason. target_text_forbid matches case-insensitively, as the prototype's re.I does; conflicts matches as written.