Files
coursebank/docs/design/2.1/REPORT.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

11 KiB

coursebank 2.1: implementation report

Branch schema-2.1, six commits, one per phase, nothing pushed. Every phase ended with cargo fmt, cargo clippy --all-targets -- -D warnings, cargo test, and cargo doc --no-deps clean. The 2.1 work adds 57 integration tests (schema 7, validate 18, lint 19, render 8, migrate 5) and 14 unit tests, and every existing test still passes unchanged.

What changed, by phase

Phase Commit Files
1. Types and schemas 51a2fd2 src/model/course/glossary.rs (new: every entry type, RefKind, the brace scanner), src/model/course.rs (the four registries, new fields on objectives, targets, lectures, readings, policy; SCHEMA_VERSION = "2.1"), src/model/course/fragment.rs (four sections, Role::Glossary, glossary.yaml), src/model/layout.rs, src/model/item.rs (misconception_id), src/authoring/jsonschema.rs (Kind::Glossary and every changed builder), tests/schema_2_1.rs, tests/docs.rs
2. Validation 960cf6c src/model/course/glossary.rs (glossary_problems: E2101 to E2107 and the prefix check), src/model/bank.rs (E2108), Cargo.toml (regex), tests/validate_2_1.rs, tests/common/mod.rs
3. Lint b8fdf4d src/authoring/lint.rs (14 rules, glossary family; two existing rules accept misconception_id), src/authoring/lint/glossary.rs (new), src/model/catalog.rs (Severity::Note), src/cli.rs, src/commands/project.rs (notes never fail lint), tests/lint_2_1.rs
4. Derived data and rendering 50a1e08 src/model/course/glossary.rs (first use, teaching order, expand_refs), src/export/lecture.rs (page_markdown, glossary_markdown, brace rendering), src/cli.rs and src/commands/lectures.rs (lecture page, lecture glossary), src/analysis/students.rs, src/export/report.rs, src/analysis/diagnostic.rs, src/export/typst/diagnostic.rs, src/export/typst/templates/student-report.typ, tests/render_2_1.rs
5. Migration 6c07122 src/migrate/glossary.rs (new), src/migrate.rs, src/cli.rs, src/commands/project.rs, tests/migrate_2_1.rs
6. Documentation this commit docs/guide/glossary.md (new) and src/guide.rs, docs/guide/setup.md, README.md, CHANGELOG.md, module docs in src/lib.rs, src/model.rs, src/authoring.rs, docs/design/2.1/CODES.md, this file, one more test in tests/validate_2_1.rs

The rendered example lecture page was sent as a private artifact in Phase 4.

Code mapping

In CODES.md. In short: E2101 to E2108 are validation messages without codes, as every coursebank error is; W2101 to W2111 are the glossary-* lint rules; I2112 and I2113 are glossary-defined-elsewhere and glossary-proposed at a new note severity. Two additions: a prefix error next to E2101, and the lint rule glossary-unresolved-reference that takes E2106's place in 2.0 reading fields.

Generated versus target schemas

The schemas are not generated from the Rust types: src/authoring/jsonschema.rs writes each one by hand with serde_json::json!, and that was the case before 2.1. So rule 2 became: port every edit in build_schemas.py into those builders, with the descriptions copied word for word. Hand-written JSON can say propertyNames, so the id patterns are in the schemas; the validator also enforces them, because nothing checks YAML against the JSON Schema at load time.

tests/schema_2_1.rs compares each of the nine generated schemas with docs/design/2.1/schemas/ as JSON values. Two differences remain, both older than 2.1 and both one word:

File Path Generated Target
calibration.schema.json /properties/items/additionalProperties/properties/variants/items/properties/option_stats/description behaviour behavior
course.schema.json /properties/policy/properties/grade_scale/items/properties/group/description Colour Color

schemas-original/ has the American spellings, which no commit in this repository ever had. I kept the code's spelling; a test fails if either difference disappears or another appears.

What I did differently from the specification, and why

  1. Lecture files and references.yaml cannot define glossary entries. The specification says any fragment may; the target schemas add the registries only to course, objective, and glossary, and I followed the schemas. A lecture file that tries gets the existing "a section belongs to a kind of file" error.
  2. Teaching order is coursebank's: lectures in id order. The prototype sorts lectures by (date, id). The specification says to use the existing order, which is the lecture map's id order. They agree on the example.
  3. E2106 on 2.0 fields (Q2, option b). The four new prefixes are errors everywhere. An unresolved {lo-…} or {t-…} in a reading's summary, focus, or skip stays a medium lint finding, because 2.0 accepted it and rule 1 says no new errors.
  4. Note severity (Q3). glossary-defined-elsewhere and glossary-proposed are notes. lint --min-severity now defaults to note, and lint exits 2 only when something is above a note, so a course with proposed entries passes a lint gate.
  5. regex crate (Q1). Built without default features (std, unicode-perl, unicode-case). No look-around and no backreferences; such a pattern fails E2107 with the crate's reason.
  6. The preview's (T t-align-fill-matrix) renders as (T 3), the target's number on the page, as 2.0's readings page always did. The prototype prints the raw id.
  7. Three lines the preview does not have. The page prints "About 40 minutes of assigned reading." above the readings, and each reading's summary and skip, which the 2.0 readings page prints and the specification's "readings (with minutes)" does not rule out. The snapshot test allows exactly these three.
  8. Anchors are glossary-<id>, such as #glossary-term-gap, not #term-gap. Quarto reserves the eq- prefix for numbered equations, so {#eq-global-recurrence} would be read as an equation cross-reference.
  9. Report wording. An option's own misconception text keeps its 2.0 sentence. An option with only a misconception_id prints "This answer reflects a common mistake: belief", then the correction. Misses sharing one are grouped under "The same mistake, more than once" with their question numbers. The registry belief and correction are student-facing by design, so they print without --misconceptions; the option's own text keeps that switch.
  10. Two existing lint rules changed. complete-distractor-design accepts a misconception_id as design, and complete-student-feedback accepts one that resolves, since the correction is the feedback.
  11. policy.exam_conditions and policy.blueprints are stored and validated, but nothing reads them. No phase asked for it. assemble --blueprint NAME reading policy.blueprints is a small follow-up.
  12. More errors than E2101 to E2108. Required text that is present but empty, a material without a URL, minutes: 0, level keys outside 1 to 5, and non-positive durations. They follow from the schemas, cannot fire on 2.0 data, and are listed in CODES.md.
  13. Proposed entries look approved to students. Nothing on a student page says "proposed"; the rule-5 test checks the word never appears.
  14. The example needed one edit. The bank item had no status, which coursebank requires; I added status: draft with a comment. With approved, validation would also require cognitive_process, sources, and design.
  15. The value say: 'about 10^{59}' renders literally, caret and braces, because say is printed as written and the example does not put it in math markup.
  16. The prototype was read, not run. pyv has no vendored PyYAML on this machine, so check21.py --selftest could not run. Each self-test mutation became a test, built by reading the prototype.
  17. Migration details the specification leaves open:
    • a value's term: gains the prefix of the id it names, and is reported;
    • fields 2.1 has no place for are dropped and reported;
    • an existing glossary.yaml is added to as text, never rewritten;
    • entries declared anywhere in the course are skipped, so a second run is a no-op;
    • an id that would be invalid with its prefix, two entries that would share an id, and an id another registry already uses are refused before anything is written;
    • an entry written as a flow mapping is written by the serializer instead of copied.

On the example, coursebank lint reports the two expected glossary findings and one existing finding: cue-absolute on option o-length, which says "always".

Running the migration on your course

From the course root, with the 1.0 files wherever they are:

$ coursebank migrate glossary --terms terms.yaml --values values.yaml --dry-run
$ coursebank migrate glossary --terms terms.yaml --values values.yaml
$ coursebank validate
$ coursebank lint --only glossary-unused,glossary-defined-elsewhere,glossary-proposed

The dry run prints the report and the file it would write. The report lists renamed ids, every dropped first or lectures that the targets now contradict, entries no target lists yet, and fields dropped. Before you link any targets, every entry will be under "no target lists these yet", and every old first and lectures will be reported as contradicted, because nothing lists the new ids yet. terms.yaml and values.yaml are left in place. Then add the ids to each target's terms and values, and move each entry into the objective file that first needs it; glossary-defined-elsewhere names those files.

Suggested changes to the specification

  1. Say which fragments may define entries: objective files, glossary.yaml, and course.yaml, as the schemas already do, rather than "any fragment".
  2. Define teaching order: lectures by id or by date. The prototype and the spec's "existing order" differ for a course whose lecture ids do not sort by date.
  3. Write down E2106's exemption for 2.0 reading fields, so rule 1 and E2106 do not contradict each other.
  4. Define the I-codes' effect on exit status: shown, never failing.
  5. Say whether say is plain text or markup. If markup, the example should write about $10^{59}$.
  6. Give the anchors a prefix of their own (glossary-), and note that Quarto reserves eq-, fig-, tbl-, and sec-.
  7. Make lecture-page-preview.md print target numbers (T 3) rather than raw ids, and decide whether a reading's summary and skip belong on the page.
  8. Add status: to the example bank item, since coursebank requires it.
  9. Name the regular-expression dialect as the subset Python's re and Rust's regex share: no look-around, no backreferences.
  10. In the migration table, add a value's term: (prefix it) and say what happens to unknown fields and to an existing glossary.yaml.
  11. Decide whether policy.blueprints should feed assemble, and say so; today it is data with no reader.