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>
This commit is contained in:
alexmandClaude committed 2026-11-16 12:31:01 -05:00
1 parent 6c07122fc5
commit b5cae6afac
11 files changed
+535 -29

No files matched your search

+67
View File
@@ -0,0 +1,67 @@
# 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.