Skip to main content

ferrichess_study/course/
metadata.rs

1use std::{collections::BTreeMap, error::Error, fmt};
2
3use serde::{Deserialize, Deserializer, Serialize, de};
4use serde_json::Value;
5
6use crate::RepertoireSide;
7
8const CURRENT_SCHEMA_VERSION: u64 = 1;
9
10type Extensions = BTreeMap<String, Value>;
11
12/// The metadata envelope shared by all supported course kinds.
13///
14/// A missing schema version identifies the deliberately supported legacy
15/// format used by the Python converter. Version 1 manifests receive full
16/// validation through [`CourseMetadata::from_json`].
17#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
18#[serde(rename_all = "camelCase")]
19pub struct CourseMetadata {
20    #[serde(default, skip_serializing_if = "Option::is_none")]
21    pub schema_version: Option<u64>,
22    #[serde(default, skip_serializing_if = "Option::is_none")]
23    pub course: Option<CourseInfo>,
24    #[serde(default, skip_serializing_if = "Vec::is_empty")]
25    pub chapters: Vec<ChapterMetadata>,
26    #[serde(default, skip_serializing_if = "Vec::is_empty")]
27    pub classifications: Vec<CurriculumClassification>,
28    #[serde(default, skip_serializing_if = "Vec::is_empty")]
29    pub tags: Vec<String>,
30    #[serde(default, skip_serializing_if = "Option::is_none")]
31    pub repertoire: Option<RepertoireSettings>,
32    #[serde(default, skip_serializing_if = "Option::is_none")]
33    pub lichess: Option<LichessMetadata>,
34    #[serde(flatten)]
35    pub extensions: Extensions,
36}
37
38impl CourseMetadata {
39    /// Parses metadata and applies version-specific semantic validation.
40    pub fn from_json(json: &str) -> Result<Self, MetadataError> {
41        let value: Value = serde_json::from_str(json).map_err(MetadataError::Json)?;
42        let version = value.get("schemaVersion");
43        match version {
44            None => {}
45            Some(Value::Number(number)) if number.as_u64() == Some(CURRENT_SCHEMA_VERSION) => {}
46            Some(Value::Number(number)) => {
47                return Err(MetadataError::UnsupportedSchemaVersion(number.to_string()));
48            }
49            Some(_) => {
50                return Err(MetadataError::Invalid(
51                    "schemaVersion must be a positive integer".into(),
52                ));
53            }
54        }
55
56        let metadata: Self = serde_json::from_value(value).map_err(MetadataError::Json)?;
57        metadata.validate()?;
58        Ok(metadata)
59    }
60
61    /// Returns whether this is an unversioned Python-compatible manifest.
62    #[must_use]
63    pub const fn is_legacy(&self) -> bool {
64        self.schema_version.is_none()
65    }
66
67    /// Returns the course-wide repertoire side when one is configured.
68    #[must_use]
69    pub fn repertoire_side(&self) -> Option<RepertoireSide> {
70        self.repertoire.as_ref().map(|settings| settings.side)
71    }
72
73    fn validate(&self) -> Result<(), MetadataError> {
74        if self.is_legacy() {
75            return Ok(());
76        }
77
78        let course = self.course.as_ref().ok_or_else(|| {
79            MetadataError::Invalid("schema version 1 requires a course object".into())
80        })?;
81        require_text("course.id", &course.id)?;
82        require_text("course.title", &course.title)?;
83
84        if self.chapters.is_empty() {
85            return Err(MetadataError::Invalid(
86                "schema version 1 requires at least one chapter".into(),
87            ));
88        }
89
90        let mut chapter_ids = std::collections::BTreeSet::new();
91        for chapter in &self.chapters {
92            require_text("chapters[].id", &chapter.id)?;
93            require_text("chapters[].title", &chapter.title)?;
94            if !chapter_ids.insert(&chapter.id) {
95                return Err(MetadataError::Invalid(format!(
96                    "duplicate chapter id {:?}",
97                    chapter.id
98                )));
99            }
100        }
101
102        for classification in &self.classifications {
103            require_text("classifications[].scheme", &classification.scheme)?;
104            require_text("classifications[].level", &classification.level)?;
105            require_text("classifications[].authority", &classification.authority)?;
106        }
107
108        if let Some(lichess) = &self.lichess {
109            require_text("lichess.studyId", &lichess.study_id)?;
110            for (chapter_id, mapping) in &lichess.chapters {
111                if !chapter_ids.contains(chapter_id) {
112                    return Err(MetadataError::Invalid(format!(
113                        "Lichess mapping references unknown chapter {chapter_id:?}"
114                    )));
115                }
116                require_text("lichess.chapters[].id", &mapping.id)?;
117            }
118        }
119
120        match course.kind {
121            CourseKind::Repertoire if self.repertoire.is_none() => Err(MetadataError::Invalid(
122                "a repertoire course requires repertoire settings".into(),
123            )),
124            CourseKind::ProblemSet if self.repertoire.is_some() => Err(MetadataError::Invalid(
125                "problem-set courses cannot contain repertoire settings".into(),
126            )),
127            _ => Ok(()),
128        }
129    }
130}
131
132fn require_text(field: &str, value: &str) -> Result<(), MetadataError> {
133    if value.trim().is_empty() {
134        Err(MetadataError::Invalid(format!("{field} cannot be empty")))
135    } else {
136        Ok(())
137    }
138}
139
140#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
141#[serde(rename_all = "camelCase")]
142pub struct CourseInfo {
143    pub id: String,
144    pub title: String,
145    pub kind: CourseKind,
146    #[serde(default, skip_serializing_if = "Option::is_none")]
147    pub description: Option<String>,
148    #[serde(default, skip_serializing_if = "Option::is_none")]
149    pub language: Option<String>,
150    #[serde(default, skip_serializing_if = "Option::is_none")]
151    pub source: Option<SourceAttribution>,
152    #[serde(flatten)]
153    pub extensions: Extensions,
154}
155
156#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
157#[serde(rename_all = "kebab-case")]
158pub enum CourseKind {
159    Repertoire,
160    ProblemSet,
161}
162
163#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
164#[serde(rename_all = "camelCase")]
165pub struct SourceAttribution {
166    #[serde(default, skip_serializing_if = "Option::is_none")]
167    pub url: Option<String>,
168    #[serde(default, skip_serializing_if = "Option::is_none")]
169    pub attribution: Option<String>,
170    #[serde(default, skip_serializing_if = "Option::is_none")]
171    pub license: Option<String>,
172    #[serde(flatten)]
173    pub extensions: Extensions,
174}
175
176#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
177#[serde(rename_all = "camelCase")]
178pub struct ChapterMetadata {
179    pub id: String,
180    pub title: String,
181    #[serde(default, skip_serializing_if = "Option::is_none")]
182    pub description: Option<String>,
183    #[serde(flatten)]
184    pub extensions: Extensions,
185}
186
187#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
188#[serde(rename_all = "camelCase")]
189pub struct CurriculumClassification {
190    pub scheme: String,
191    pub level: String,
192    #[serde(default, skip_serializing_if = "Option::is_none")]
193    pub lesson: Option<String>,
194    #[serde(default, skip_serializing_if = "Option::is_none")]
195    pub theme: Option<String>,
196    pub authority: String,
197    #[serde(default, skip_serializing_if = "Option::is_none")]
198    pub status: Option<String>,
199    #[serde(default, skip_serializing_if = "Option::is_none")]
200    pub confidence: Option<String>,
201    #[serde(flatten)]
202    pub extensions: Extensions,
203}
204
205#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
206#[serde(rename_all = "camelCase")]
207pub struct RepertoireSettings {
208    #[serde(deserialize_with = "deserialize_repertoire_side")]
209    pub side: RepertoireSide,
210    #[serde(flatten)]
211    pub extensions: Extensions,
212}
213
214fn deserialize_repertoire_side<'de, D>(deserializer: D) -> Result<RepertoireSide, D::Error>
215where
216    D: Deserializer<'de>,
217{
218    let side = String::deserialize(deserializer)?;
219    if side.eq_ignore_ascii_case("white") {
220        Ok(RepertoireSide::White)
221    } else if side.eq_ignore_ascii_case("black") {
222        Ok(RepertoireSide::Black)
223    } else {
224        Err(de::Error::unknown_variant(&side, &["White", "Black"]))
225    }
226}
227
228#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
229#[serde(rename_all = "camelCase")]
230pub struct LichessMetadata {
231    pub study_id: String,
232    #[serde(default)]
233    pub chapters: BTreeMap<String, LichessChapter>,
234    #[serde(flatten)]
235    pub extensions: Extensions,
236}
237
238#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
239pub struct LichessChapter {
240    pub id: String,
241    #[serde(flatten)]
242    pub extensions: Extensions,
243}
244
245#[derive(Debug)]
246pub enum MetadataError {
247    Json(serde_json::Error),
248    UnsupportedSchemaVersion(String),
249    Invalid(String),
250}
251
252impl fmt::Display for MetadataError {
253    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
254        match self {
255            Self::Json(error) => write!(formatter, "invalid course metadata JSON: {error}"),
256            Self::UnsupportedSchemaVersion(version) => {
257                write!(
258                    formatter,
259                    "unsupported course metadata schema version {version}"
260                )
261            }
262            Self::Invalid(message) => formatter.write_str(message),
263        }
264    }
265}
266
267impl Error for MetadataError {
268    fn source(&self) -> Option<&(dyn Error + 'static)> {
269        match self {
270            Self::Json(error) => Some(error),
271            Self::UnsupportedSchemaVersion(_) | Self::Invalid(_) => None,
272        }
273    }
274}
275
276#[cfg(test)]
277mod tests {
278    use serde_json::json;
279
280    use super::{CourseKind, CourseMetadata, MetadataError};
281    use crate::RepertoireSide;
282
283    const VERSIONED_REPERTOIRE: &str = r#"{
284        "schemaVersion": 1,
285        "course": {
286            "id": "synthetic-black-repertoire",
287            "title": "Synthetic Black Repertoire",
288            "kind": "repertoire",
289            "source": {
290                "url": "https://example.invalid/synthetic",
291                "attribution": "Synthetic fixture",
292                "license": "CC0-1.0"
293            }
294        },
295        "chapters": [{"id": "defence", "title": "Example Defence"}],
296        "repertoire": {"side": "Black"},
297        "lichess": {
298            "studyId": "study-001",
299            "chapters": {"defence": {"id": "chapter-001"}}
300        }
301    }"#;
302
303    const SYNTHETIC_PROBLEM_SET: &str = r#"{
304        "schemaVersion": 1,
305        "course": {
306            "id": "synthetic-problems",
307            "title": "Synthetic Problems",
308            "kind": "problem-set",
309            "source": {
310                "url": "https://example.invalid/synthetic",
311                "attribution": "Synthetic fixture",
312                "license": "CC0-1.0"
313            }
314        },
315        "chapters": [{"id": "mate-in-one", "title": "Mate in One"}],
316        "problemSet": {
317            "problems": [{
318                "id": "synthetic-mate",
319                "sourceId": "synthetic",
320                "chapterId": "mate-in-one",
321                "start": {"fen": "7k/5Q2/6K1/8/8/8/8/8 b - - 0 1"},
322                "objective": {"kind": "checkmate", "moves": 1}
323            }]
324        }
325    }"#;
326
327    #[test]
328    fn parses_and_validates_versioned_repertoire_metadata() {
329        let metadata =
330            CourseMetadata::from_json(VERSIONED_REPERTOIRE).expect("synthetic fixture is valid");
331
332        assert!(!metadata.is_legacy());
333        assert_eq!(metadata.repertoire_side(), Some(RepertoireSide::Black));
334        assert_eq!(metadata.chapters[0].id, "defence");
335        assert_eq!(
336            metadata
337                .lichess
338                .as_ref()
339                .expect("lichess mappings")
340                .chapters["defence"]
341                .id,
342            "chapter-001"
343        );
344    }
345
346    #[test]
347    fn accepts_existing_unversioned_python_metadata() {
348        let metadata = CourseMetadata::from_json(r#"{"repertoire":{"side":"bLaCk"}}"#)
349            .expect("legacy metadata remains supported");
350
351        assert!(metadata.is_legacy());
352        assert_eq!(metadata.repertoire_side(), Some(RepertoireSide::Black));
353    }
354
355    #[test]
356    fn rejects_unsupported_versions_with_a_specific_error() {
357        let error = CourseMetadata::from_json(r#"{"schemaVersion":2}"#)
358            .expect_err("version 2 is not supported");
359
360        assert!(
361            matches!(error, MetadataError::UnsupportedSchemaVersion(version) if version == "2")
362        );
363    }
364
365    #[test]
366    fn validates_required_fields_and_unique_chapters() {
367        let error = CourseMetadata::from_json(
368            r#"{
369                "schemaVersion": 1,
370                "course": {"id":"course", "title":"Course", "kind":"repertoire"},
371                "chapters": [
372                    {"id":"same", "title":"One"},
373                    {"id":"same", "title":"Two"}
374                ],
375                "repertoire": {"side":"White"}
376            }"#,
377        )
378        .expect_err("duplicate chapter identifiers are ambiguous");
379
380        assert_eq!(error.to_string(), "duplicate chapter id \"same\"");
381    }
382
383    #[test]
384    fn rejects_lichess_mappings_for_undeclared_chapters() {
385        let error = CourseMetadata::from_json(
386            r#"{
387                "schemaVersion": 1,
388                "course": {"id":"course", "title":"Course", "kind":"repertoire"},
389                "chapters": [{"id":"declared", "title":"Declared"}],
390                "repertoire": {"side":"White"},
391                "lichess": {
392                    "studyId":"study",
393                    "chapters":{"missing":{"id":"chapter"}}
394                }
395            }"#,
396        )
397        .expect_err("publishing mappings must use stable declared chapter ids");
398
399        assert_eq!(
400            error.to_string(),
401            "Lichess mapping references unknown chapter \"missing\""
402        );
403    }
404
405    #[test]
406    fn future_problem_set_keeps_position_and_integer_objective_extensions() {
407        let metadata = CourseMetadata::from_json(SYNTHETIC_PROBLEM_SET)
408            .expect("synthetic fixture fits the common envelope");
409
410        assert_eq!(
411            metadata.course.as_ref().expect("course").kind,
412            CourseKind::ProblemSet
413        );
414        let problems = &metadata.extensions["problemSet"]["problems"];
415        assert_eq!(
416            problems[0]["start"]["fen"],
417            json!("7k/5Q2/6K1/8/8/8/8/8 b - - 0 1")
418        );
419        assert_eq!(problems[0]["objective"]["moves"], json!(1));
420
421        let round_trip = serde_json::to_value(&metadata).expect("metadata serializes");
422        assert_eq!(round_trip["problemSet"]["problems"], *problems);
423    }
424}