Skip to main content

ferrichess_study/course/
documents.rs

1use std::{cmp::Ordering, error::Error, fmt};
2
3use shakmaty::Chess;
4
5use crate::{
6    PgnDocument, PgnError, RepertoireRole, RepertoireSide, SingleRawMetadata, SourceId,
7    convert_single_raw,
8    pgn::Headers,
9    tree::{MergeConflict, MoveTree, MoveTreeMerger},
10};
11
12use super::{CourseKind, CourseMetadata};
13
14/// One raw source supplied to the pure course-conversion boundary.
15#[derive(Clone, Debug, Eq, PartialEq)]
16pub struct RawCourseLine {
17    pub source: SourceId,
18    pub chapter_id: String,
19    pub index: String,
20    pub text: String,
21}
22
23/// A generated document and the stable name used by output adapters.
24#[derive(Clone, Debug, Eq, PartialEq)]
25pub struct NamedDocument {
26    pub name: String,
27    pub document: PgnDocument,
28}
29
30/// Merge diagnostics associated with one aggregate output.
31#[derive(Clone, Debug, Eq, PartialEq)]
32pub struct DocumentMerge {
33    pub name: String,
34    pub conflicts: Vec<MergeConflict>,
35}
36
37/// All local aggregate documents for a repertoire course.
38///
39/// `chapters` are also the games in the multi-game course PGN, in declared
40/// metadata order. `full` is ordered Black then White, matching the Python
41/// converter's output order.
42#[derive(Clone, Debug, Eq, PartialEq)]
43pub struct CourseDocuments {
44    pub course_id: String,
45    pub chapters: Vec<NamedDocument>,
46    pub full: Vec<NamedDocument>,
47    pub merges: Vec<DocumentMerge>,
48}
49
50impl CourseDocuments {
51    /// Returns the chapter games that make up the course PGN.
52    pub fn course_games(&self) -> impl ExactSizeIterator<Item = &PgnDocument> {
53        self.chapters.iter().map(|chapter| &chapter.document)
54    }
55}
56
57/// Converts raw text to chapter, side-full, and ordered course documents.
58///
59/// This boundary performs no discovery, filesystem writes, or rendering. Raw
60/// lines are sorted by their Python-compatible numeric index within each
61/// chapter; chapter order comes from `course.json` metadata.
62pub fn generate_course_documents(
63    metadata: &CourseMetadata,
64    raw_lines: &[RawCourseLine],
65) -> Result<CourseDocuments, CourseDocumentError> {
66    let course = metadata
67        .course
68        .as_ref()
69        .ok_or(CourseDocumentError::MissingCourse)?;
70    if course.kind != CourseKind::Repertoire {
71        return Err(CourseDocumentError::UnsupportedCourseKind(course.kind));
72    }
73    let default_side = metadata
74        .repertoire_side()
75        .ok_or(CourseDocumentError::MissingRepertoireSide)?;
76
77    for raw in raw_lines {
78        if !metadata
79            .chapters
80            .iter()
81            .any(|chapter| chapter.id == raw.chapter_id)
82        {
83            return Err(CourseDocumentError::UnknownChapter(raw.chapter_id.clone()));
84        }
85    }
86
87    let mut chapters = Vec::new();
88    let mut merges = Vec::new();
89    for chapter in &metadata.chapters {
90        let mut sources: Vec<_> = raw_lines
91            .iter()
92            .filter(|raw| raw.chapter_id == chapter.id)
93            .collect();
94        sources.sort_by(|left, right| compare_indexes(&left.index, &right.index));
95        if sources.is_empty() {
96            continue;
97        }
98
99        let side = side_for_chapter(&chapter.id).unwrap_or(default_side);
100        let role = role_for_chapter(&chapter.id);
101        let title = title_from_slug(&chapter.id);
102        let mut tree = MoveTree::new();
103        let mut merger = MoveTreeMerger::new(side);
104        let mut conflicts = Vec::new();
105        for raw in sources {
106            let line = convert_single_raw(
107                &raw.text,
108                &SingleRawMetadata {
109                    course_title: course.title.clone(),
110                    event: title.clone(),
111                    chapter_slug: chapter.id.clone(),
112                    index: raw.index.clone(),
113                    repertoire_side: side,
114                    repertoire_role: role,
115                },
116            )?;
117            conflicts.extend(
118                merger
119                    .merge(&mut tree, line.tree(), raw.source.clone())?
120                    .conflicts,
121            );
122        }
123
124        let name = chapter.id.clone();
125        chapters.push(NamedDocument {
126            name: name.clone(),
127            document: PgnDocument::new(
128                aggregate_headers(&title, &course.title, side, role),
129                tree,
130                "*",
131            ),
132        });
133        merges.push(DocumentMerge { name, conflicts });
134    }
135
136    let mut full = Vec::new();
137    for side in [RepertoireSide::Black, RepertoireSide::White] {
138        let selected: Vec<_> = chapters
139            .iter()
140            .filter(|chapter| document_side(&chapter.document) == Some(side))
141            .collect();
142        if selected.is_empty() {
143            continue;
144        }
145        let mut tree = MoveTree::from_position(Chess::default());
146        let mut merger = MoveTreeMerger::new(side);
147        let mut conflicts = Vec::new();
148        for chapter in selected {
149            conflicts.extend(
150                merger
151                    .merge(
152                        &mut tree,
153                        chapter.document.tree(),
154                        SourceId::from(chapter.name.clone()),
155                    )?
156                    .conflicts,
157            );
158        }
159        let side_name = side_text(side);
160        let name = format!("{}-full", side_name.to_lowercase());
161        full.push(NamedDocument {
162            name: name.clone(),
163            document: PgnDocument::new(
164                aggregate_headers(
165                    &format!("{side_name} Full"),
166                    &course.title,
167                    side,
168                    RepertoireRole::Main,
169                ),
170                tree,
171                "*",
172            ),
173        });
174        merges.push(DocumentMerge { name, conflicts });
175    }
176
177    Ok(CourseDocuments {
178        course_id: course.id.clone(),
179        chapters,
180        full,
181        merges,
182    })
183}
184
185fn aggregate_headers(
186    title: &str,
187    course_title: &str,
188    side: RepertoireSide,
189    role: RepertoireRole,
190) -> Headers {
191    let mut headers = Headers::new();
192    headers.insert("Event", title);
193    headers.insert("Site", "?");
194    headers.insert("Date", "????.??.??");
195    headers.insert("Round", "-");
196    headers.insert("White", "Lines");
197    headers.insert("Black", course_title);
198    headers.insert("Result", "*");
199    headers.insert("Chapter", title);
200    headers.insert("SourceCourse", course_title);
201    headers.insert("Orientation", side_text(side));
202    headers.insert("RepertoireSide", side_text(side));
203    headers.insert("RepertoireRole", role_text(role));
204    headers
205}
206
207fn document_side(document: &PgnDocument) -> Option<RepertoireSide> {
208    match document.headers().get("RepertoireSide") {
209        Some("White") => Some(RepertoireSide::White),
210        Some("Black") => Some(RepertoireSide::Black),
211        _ => None,
212    }
213}
214
215const fn side_text(side: RepertoireSide) -> &'static str {
216    match side {
217        RepertoireSide::White => "White",
218        RepertoireSide::Black => "Black",
219    }
220}
221
222const fn role_text(role: RepertoireRole) -> &'static str {
223    match role {
224        RepertoireRole::Main => "Main",
225        RepertoireRole::Variant => "Variant",
226    }
227}
228
229fn side_for_chapter(chapter: &str) -> Option<RepertoireSide> {
230    match chapter.split('-').next() {
231        Some(prefix) if prefix.eq_ignore_ascii_case("white") => Some(RepertoireSide::White),
232        Some(prefix) if prefix.eq_ignore_ascii_case("black") => Some(RepertoireSide::Black),
233        _ => None,
234    }
235}
236
237fn role_for_chapter(chapter: &str) -> RepertoireRole {
238    if chapter.ends_with("-variant") {
239        RepertoireRole::Variant
240    } else {
241        RepertoireRole::Main
242    }
243}
244
245fn compare_indexes(left: &str, right: &str) -> Ordering {
246    match (left.parse::<u64>(), right.parse::<u64>()) {
247        (Ok(left), Ok(right)) => left.cmp(&right),
248        _ => left.cmp(right),
249    }
250}
251
252fn title_from_slug(slug: &str) -> String {
253    slug.replace('_', "-")
254        .split('-')
255        .filter(|part| !part.is_empty())
256        .map(|part| {
257            let lowercase = part.to_lowercase();
258            let mut characters = lowercase.chars();
259            characters.next().map_or_else(String::new, |first| {
260                first.to_uppercase().chain(characters).collect()
261            })
262        })
263        .collect::<Vec<_>>()
264        .join(" ")
265}
266
267#[derive(Clone, Debug, Eq, PartialEq)]
268pub enum CourseDocumentError {
269    MissingCourse,
270    MissingRepertoireSide,
271    UnsupportedCourseKind(CourseKind),
272    UnknownChapter(String),
273    Pgn(PgnError),
274}
275
276impl fmt::Display for CourseDocumentError {
277    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
278        match self {
279            Self::MissingCourse => {
280                formatter.write_str("course document generation requires course metadata")
281            }
282            Self::MissingRepertoireSide => {
283                formatter.write_str("repertoire course metadata has no side")
284            }
285            Self::UnsupportedCourseKind(kind) => {
286                write!(formatter, "cannot generate repertoire PGNs for {kind:?}")
287            }
288            Self::UnknownChapter(chapter) => write!(
289                formatter,
290                "raw source references unknown chapter {chapter:?}"
291            ),
292            Self::Pgn(error) => error.fmt(formatter),
293        }
294    }
295}
296
297impl Error for CourseDocumentError {
298    fn source(&self) -> Option<&(dyn Error + 'static)> {
299        match self {
300            Self::Pgn(error) => Some(error),
301            _ => None,
302        }
303    }
304}
305
306impl From<PgnError> for CourseDocumentError {
307    fn from(error: PgnError) -> Self {
308        Self::Pgn(error)
309    }
310}
311
312impl From<crate::tree::MergeError> for CourseDocumentError {
313    fn from(error: crate::tree::MergeError) -> Self {
314        Self::Pgn(PgnError::from(error))
315    }
316}
317
318#[cfg(test)]
319mod tests {
320    use crate::{CourseMetadata, PgnWriter, SourceId};
321
322    use super::{RawCourseLine, generate_course_documents};
323
324    fn metadata() -> CourseMetadata {
325        CourseMetadata::from_json(
326            r#"{
327                "schemaVersion": 1,
328                "course": {"id":"sample", "title":"Sample Course", "kind":"repertoire"},
329                "chapters": [
330                    {"id":"white-second", "title":"Declared second"},
331                    {"id":"black-first", "title":"Declared first"}
332                ],
333                "repertoire": {"side":"White"}
334            }"#,
335        )
336        .unwrap()
337    }
338
339    fn raw(chapter: &str, index: &str, text: &str) -> RawCourseLine {
340        RawCourseLine {
341            source: SourceId::from(format!("{chapter}/{index}.raw")),
342            chapter_id: chapter.to_owned(),
343            index: index.to_owned(),
344            text: text.to_owned(),
345        }
346    }
347
348    #[test]
349    fn generates_declared_chapters_side_full_documents_and_course_order() {
350        let documents = generate_course_documents(
351            &metadata(),
352            &[
353                raw("black-first", "010", "1. e4c5"),
354                raw("white-second", "010", "1. d4d5"),
355                raw("white-second", "002", "1. d4Nf6"),
356            ],
357        )
358        .unwrap();
359
360        assert_eq!(
361            documents
362                .chapters
363                .iter()
364                .map(|document| document.name.as_str())
365                .collect::<Vec<_>>(),
366            ["white-second", "black-first"]
367        );
368        assert_eq!(
369            documents
370                .full
371                .iter()
372                .map(|document| document.name.as_str())
373                .collect::<Vec<_>>(),
374            ["black-full", "white-full"]
375        );
376        assert_eq!(documents.course_games().len(), 2);
377
378        let white = &documents.chapters[0].document;
379        assert_eq!(white.headers().get("Event"), Some("White Second"));
380        assert_eq!(white.headers().get("White"), Some("Lines"));
381        assert_eq!(white.headers().get("SourceCourse"), Some("Sample Course"));
382        let rendered = PgnWriter::render(white).unwrap();
383        assert!(rendered.ends_with("1. d4 d5 ( 1... Nf6 ) *"));
384
385        let course_games: Vec<_> = documents.course_games().cloned().collect();
386        let course = PgnWriter::render_documents(&course_games).unwrap();
387        assert!(course.starts_with(b"[Event \"White Second\"]"));
388        assert!(
389            course
390                .windows(21)
391                .any(|window| window == b"[Event \"Black First\"]")
392        );
393    }
394
395    #[test]
396    fn reports_cross_line_repertoire_conflicts_without_dropping_opponent_branches() {
397        let documents = generate_course_documents(
398            &metadata(),
399            &[
400                raw("white-second", "001", "1. e4c5"),
401                raw("white-second", "002", "1. d4d5"),
402            ],
403        )
404        .unwrap();
405
406        let chapter_merge = documents
407            .merges
408            .iter()
409            .find(|merge| merge.name == "white-second")
410            .unwrap();
411        assert_eq!(chapter_merge.conflicts.len(), 1);
412        assert_eq!(documents.chapters[0].document.tree().len(), 3);
413    }
414}