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>
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
- Lecture files and
references.yamlcannot define glossary entries. The specification says any fragment may; the target schemas add the registries only tocourse,objective, andglossary, and I followed the schemas. A lecture file that tries gets the existing "a section belongs to a kind of file" error. - 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. - E2106 on 2.0 fields (Q2, option b). The four new prefixes are errors everywhere. An unresolved
{lo-…}or{t-…}in a reading'ssummary,focus, orskipstays a medium lint finding, because 2.0 accepted it and rule 1 says no new errors. - Note severity (Q3).
glossary-defined-elsewhereandglossary-proposedare notes.lint --min-severitynow defaults tonote, andlintexits 2 only when something is above a note, so a course with proposed entries passes a lint gate. regexcrate (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.- 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. - Three lines the preview does not have. The page prints "About 40 minutes of assigned reading." above the readings, and each reading's
summaryandskip, 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. - Anchors are
glossary-<id>, such as#glossary-term-gap, not#term-gap. Quarto reserves theeq-prefix for numbered equations, so{#eq-global-recurrence}would be read as an equation cross-reference. - Report wording. An option's own
misconceptiontext keeps its 2.0 sentence. An option with only amisconception_idprints "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. - Two existing lint rules changed.
complete-distractor-designaccepts amisconception_idas design, andcomplete-student-feedbackaccepts one that resolves, since the correction is the feedback. policy.exam_conditionsandpolicy.blueprintsare stored and validated, but nothing reads them. No phase asked for it.assemble --blueprint NAMEreadingpolicy.blueprintsis a small follow-up.- 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 inCODES.md. - Proposed entries look approved to students. Nothing on a student page says "proposed"; the rule-5 test checks the word never appears.
- The example needed one edit. The bank item had no
status, which coursebank requires; I addedstatus: draftwith a comment. Withapproved, validation would also requirecognitive_process,sources, anddesign. - The value
say: 'about 10^{59}'renders literally, caret and braces, becausesayis printed as written and the example does not put it in math markup. - The prototype was read, not run.
pyvhas no vendored PyYAML on this machine, socheck21.py --selftestcould not run. Each self-test mutation became a test, built by reading the prototype. - 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.yamlis 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.
- a value's
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
- Say which fragments may define entries: objective files,
glossary.yaml, andcourse.yaml, as the schemas already do, rather than "any fragment". - 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.
- Write down E2106's exemption for 2.0 reading fields, so rule 1 and E2106 do not contradict each other.
- Define the I-codes' effect on exit status: shown, never failing.
- Say whether
sayis plain text or markup. If markup, the example should writeabout $10^{59}$. - Give the anchors a prefix of their own (
glossary-), and note that Quarto reserveseq-,fig-,tbl-, andsec-. - Make
lecture-page-preview.mdprint target numbers (T 3) rather than raw ids, and decide whether a reading'ssummaryandskipbelong on the page. - Add
status:to the example bank item, since coursebank requires it. - Name the regular-expression dialect as the subset Python's
reand Rust'sregexshare: no look-around, no backreferences. - In the migration table, add a value's
term:(prefix it) and say what happens to unknown fields and to an existingglossary.yaml. - Decide whether
policy.blueprintsshould feedassemble, and say so; today it is data with no reader.