trane 0.28.0

//! Contains the logic to generate a Trane course based on a knowledge base of markdown files
//! representing the front and back of flashcard exercises.

use anyhow::{Context, Error, Result, anyhow};
use serde::{Deserialize, Serialize, de::DeserializeOwned};
use std::{
    collections::{BTreeMap, HashMap, HashSet},
    fs::{File, read_dir, read_to_string},
    io::BufReader,
    path::Path,
};
use ustr::{Ustr, UstrMap};

use crate::data::{
    BasicAsset, CourseManifest, ExerciseAsset, ExerciseManifest, ExerciseType, GenerateManifests,
    GeneratedCourse, LessonManifest, UserPreferences,
};

/// The suffix used to recognize a directory as a knowledge base lesson.
pub const LESSON_SUFFIX: &str = ".lesson";

/// The name of the file containing the dependencies of a lesson.
pub const LESSON_DEPENDENCIES_FILE: &str = "lesson.dependencies.json";

/// The name of the file containing the courses or lessons that a lesson supersedes.
pub const LESSON_SUPERSEDED_FILE: &str = "lesson.superseded.json";

/// The name of the file containing the courses or lessons encompassed by the lesson.
pub const LESSON_ENCOMPASSED_FILE: &str = "lesson.encompassed.json";

/// The name of the file containing the name of a lesson.
pub const LESSON_NAME_FILE: &str = "lesson.name.json";

/// The name of the file containing the description of a lesson.
pub const LESSON_DESCRIPTION_FILE: &str = "lesson.description.json";

/// The name of the file containing the metadata of a lesson.
pub const LESSON_METADATA_FILE: &str = "lesson.metadata.json";

/// The name of the file containing the lesson instructions.
pub const LESSON_INSTRUCTIONS_FILE: &str = "lesson.instructions.md";

/// The name of the file containing the lesson material.
pub const LESSON_MATERIAL_FILE: &str = "lesson.material.md";

/// The name of the file containing the default exercise type for exercises in the lesson.
pub const LESSON_DEFAULT_EXERCISE_TYPE_FILE: &str = "lesson.default_exercise_type.json";

/// The suffix of the file containing the front of the flashcard for an exercise.
pub const EXERCISE_FRONT_SUFFIX: &str = ".front.md";

/// The suffix of the file containing the back of the flashcard for an exercise.
pub const EXERCISE_BACK_SUFFIX: &str = ".back.md";

/// The suffix of the file containing the name of an exercise.
pub const EXERCISE_NAME_SUFFIX: &str = ".name.json";

/// The suffix of the file containing the description of an exercise.
pub const EXERCISE_DESCRIPTION_SUFFIX: &str = ".description.json";

/// The suffix of the file containing the metadata of an exercise.
pub const EXERCISE_TYPE_SUFFIX: &str = ".type.json";

/// An enum representing a type of file that can be found in a knowledge base lesson directory.
#[derive(Debug, Eq, PartialEq)]
pub enum KnowledgeBaseFile {
    /// The file containing the name of the lesson.
    LessonName,

    /// The file containing the description of the lesson.
    LessonDescription,

    /// The file containing the dependencies of the lesson.
    LessonDependencies,

    /// The file containing the courses or lessons that the lesson supersedes.
    LessonSuperseded,

    /// The file containing the courses or lessons encompassed by the lesson.
    LessonEncompassed,

    /// The file containing the metadata of the lesson.
    LessonMetadata,

    /// The file containing the lesson instructions.
    LessonInstructions,

    /// The file containing the lesson material.
    LessonMaterial,

    /// The file containing the default exercise type for exercises in the lesson.
    LessonDefaultExerciseType,

    /// The file containing the front of the flashcard for the exercise with the given short ID.
    ExerciseFront(String),

    /// The file containing the back of the flashcard for the exercise with the given short ID.
    ExerciseBack(String),

    /// The file containing the name of the exercise with the given short ID.
    ExerciseName(String),

    /// The file containing the description of the exercise with the given short ID.
    ExerciseDescription(String),

    /// The file containing the type of the exercise with the given short ID.
    ExerciseType(String),
}

impl KnowledgeBaseFile {
    /// Opens the knowledge base file at the given path and deserializes its contents.
    pub fn open<T: DeserializeOwned>(path: &Path) -> Result<T> {
        let display = path.display();
        let file =
            File::open(path).context(format!("cannot open knowledge base file {display}"))?;
        let reader = BufReader::new(file);
        serde_json::from_reader(reader)
            .context(format!("cannot parse knowledge base file {display}"))
    }
}

impl TryFrom<&str> for KnowledgeBaseFile {
    type Error = Error;

    /// Converts a file name to a `KnowledgeBaseFile` variant.
    fn try_from(file_name: &str) -> Result<Self> {
        match file_name {
            LESSON_DEPENDENCIES_FILE => Ok(KnowledgeBaseFile::LessonDependencies),
            LESSON_SUPERSEDED_FILE => Ok(KnowledgeBaseFile::LessonSuperseded),
            LESSON_ENCOMPASSED_FILE => Ok(KnowledgeBaseFile::LessonEncompassed),
            LESSON_NAME_FILE => Ok(KnowledgeBaseFile::LessonName),
            LESSON_DESCRIPTION_FILE => Ok(KnowledgeBaseFile::LessonDescription),
            LESSON_METADATA_FILE => Ok(KnowledgeBaseFile::LessonMetadata),
            LESSON_MATERIAL_FILE => Ok(KnowledgeBaseFile::LessonMaterial),
            LESSON_INSTRUCTIONS_FILE => Ok(KnowledgeBaseFile::LessonInstructions),
            LESSON_DEFAULT_EXERCISE_TYPE_FILE => Ok(KnowledgeBaseFile::LessonDefaultExerciseType),
            file_name if file_name.ends_with(EXERCISE_FRONT_SUFFIX) => {
                let short_id = file_name.strip_suffix(EXERCISE_FRONT_SUFFIX).unwrap();
                Ok(KnowledgeBaseFile::ExerciseFront(short_id.to_string()))
            }
            file_name if file_name.ends_with(EXERCISE_BACK_SUFFIX) => {
                let short_id = file_name.strip_suffix(EXERCISE_BACK_SUFFIX).unwrap();
                Ok(KnowledgeBaseFile::ExerciseBack(short_id.to_string()))
            }
            file_name if file_name.ends_with(EXERCISE_NAME_SUFFIX) => {
                let short_id = file_name.strip_suffix(EXERCISE_NAME_SUFFIX).unwrap();
                Ok(KnowledgeBaseFile::ExerciseName(short_id.to_string()))
            }
            file_name if file_name.ends_with(EXERCISE_DESCRIPTION_SUFFIX) => {
                let short_id = file_name.strip_suffix(EXERCISE_DESCRIPTION_SUFFIX).unwrap();
                Ok(KnowledgeBaseFile::ExerciseDescription(short_id.to_string()))
            }
            file_name if file_name.ends_with(EXERCISE_TYPE_SUFFIX) => {
                let short_id = file_name.strip_suffix(EXERCISE_TYPE_SUFFIX).unwrap();
                Ok(KnowledgeBaseFile::ExerciseType(short_id.to_string()))
            }
            _ => Err(anyhow!("Not a valid knowledge base file name: {file_name}")),
        }
    }
}

//@<knowledge-base-exercise
/// Represents a knowledge base exercise.
///
/// Inside a knowledge base lesson directory, Trane will look for matching pairs of files with names
/// `<SHORT_EXERCISE_ID>.front.md` and `<SHORT_EXERCISE_ID>.back.md`. The short ID is used to
/// generate the final exercise ID, by combining it with the lesson ID. For example, files
/// `e.front.md` and `e.back.md` in a course with ID `a::b::c` inside a lesson directory named
/// `d.lesson` will generate and exercise with ID `a::b::c::d::e`.
///
/// Each the optional fields mirror one of the fields in the [`ExerciseManifest`] and their values
/// can be set by writing a JSON file inside the lesson directory with the name
/// `<SHORT_EXERCISE_ID>.<PROPERTY_NAME>.json`. This file should contain a JSON serialization of the
/// desired value. For example, to set the exercise's name for an exercise with a short ID value of
/// `ex1`, one would write a file named `ex1.name.json` containing a JSON string with the desired
/// name.
///
/// Trane will ignore any markdown files that do not match the exercise name pattern or that do not
/// have a matching pair of front and back files.
#[derive(Clone)]
pub struct KnowledgeBaseExercise {
    /// The short ID of the lesson, which is used to easily identify the exercise and to generate
    /// the final exercise ID.
    pub short_id: String,

    /// The short ID of the lesson to which this exercise belongs.
    pub short_lesson_id: Ustr,

    /// The ID of the course to which this lesson belongs.
    pub course_id: Ustr,

    /// The path to the file containing the front of the flashcard.
    pub front_file: String,

    /// The path to the file containing the back of the flashcard. This path is optional, because a
    /// flashcard is not required to provide an answer.
    pub back_file: Option<String>,

    /// The name of the exercise to be presented to the user.
    pub name: Option<String>,

    /// An optional description of the exercise.
    pub description: Option<String>,

    /// The type of knowledge the exercise tests. Currently, Trane does not make any distinction
    /// between the types of exercises, but that will likely change in the future. The option to set
    /// the type is provided, but most users should not need to use it.
    pub exercise_type: Option<ExerciseType>,
}
//>@knowledge-base-exercise

impl KnowledgeBaseExercise {
    /// Generates the exercise manifest, using the provided default exercise type from the lesson
    /// if the exercise does not have its own type set. Falls back to `Procedural` if neither is
    /// set.
    pub fn to_exercise_manifest(
        &self,
        default_exercise_type: Option<ExerciseType>,
        inlined: bool,
    ) -> Result<ExerciseManifest> {
        let exercise_asset = if inlined {
            let front_content = read_to_string(&self.front_file).context(format!(
                "failed to read exercise front file {}",
                self.front_file
            ))?;
            let back_content = self
                .back_file
                .as_ref()
                .map(|path| {
                    read_to_string(path)
                        .context(format!("failed to read exercise back file {path}"))
                })
                .transpose()?;
            ExerciseAsset::InlineFlashcardAsset {
                front_content,
                back_content,
            }
        } else {
            ExerciseAsset::FlashcardAsset {
                front_path: self.front_file.clone(),
                back_path: self.back_file.clone(),
            }
        };

        Ok(ExerciseManifest {
            id: format!(
                "{}::{}::{}",
                self.course_id, self.short_lesson_id, self.short_id
            )
            .into(),
            lesson_id: format!("{}::{}", self.course_id, self.short_lesson_id).into(),
            course_id: self.course_id,
            name: self
                .name
                .clone()
                .unwrap_or(format!("Exercise {}", self.short_id)),
            description: self.description.clone(),
            exercise_type: self
                .exercise_type
                .clone()
                .unwrap_or(default_exercise_type.unwrap_or(ExerciseType::Procedural)),
            exercise_asset,
        })
    }

    /// Generates the exercise from a list of knowledge base files.
    fn create_exercise(
        lesson_root: &Path,
        short_id: &str,
        short_lesson_id: Ustr,
        course_manifest: &CourseManifest,
        files: &[KnowledgeBaseFile],
    ) -> Result<Self> {
        // Check if the exercise has a back file and create it accordingly.
        let has_back_file = files.iter().any(|file| match file {
            KnowledgeBaseFile::ExerciseBack(id) => id == short_id,
            _ => false,
        });
        let back_file = if has_back_file {
            Some(
                lesson_root
                    .join(format!("{short_id}{EXERCISE_BACK_SUFFIX}"))
                    .to_str()
                    .unwrap_or_default()
                    .to_string(),
            )
        } else {
            None
        };

        // Create the exercise with `None` values for all optimal fields.
        let mut exercise = KnowledgeBaseExercise {
            short_id: short_id.to_string(),
            short_lesson_id,
            course_id: course_manifest.id,
            front_file: lesson_root
                .join(format!("{short_id}{EXERCISE_FRONT_SUFFIX}"))
                .to_str()
                .unwrap_or_default()
                .to_string(),
            back_file,
            name: None,
            description: None,
            exercise_type: None,
        };

        // Iterate through the exercise files found in the lesson directory and set the
        // corresponding field in the exercise. The front and back files are ignored because the
        // correct values were already set above.
        for exercise_file in files {
            match exercise_file {
                KnowledgeBaseFile::ExerciseName(..) => {
                    let path = lesson_root.join(format!("{short_id}{EXERCISE_NAME_SUFFIX}"));
                    exercise.name = Some(KnowledgeBaseFile::open(&path)?);
                }
                KnowledgeBaseFile::ExerciseDescription(..) => {
                    let path = lesson_root.join(format!("{short_id}{EXERCISE_DESCRIPTION_SUFFIX}"));
                    exercise.description = Some(KnowledgeBaseFile::open(&path)?);
                }
                KnowledgeBaseFile::ExerciseType(..) => {
                    let path = lesson_root.join(format!("{short_id}{EXERCISE_TYPE_SUFFIX}"));
                    exercise.exercise_type = Some(KnowledgeBaseFile::open(&path)?);
                }
                _ => {}
            }
        }
        Ok(exercise)
    }
}

//@<knowledge-base-lesson
/// Represents a knowledge base lesson.
///
/// In a knowledge base course, lessons are generated by searching for all directories with a name
/// in the format `<SHORT_LESSON_ID>.lesson`. In this case, the short ID is not the entire lesson ID
/// one would use in the lesson manifest, but rather a short identifier that is combined with the
/// course ID to generate the final lesson ID. For example, a course with ID `a::b::c` which
/// contains a directory of name `d.lesson` will generate the manifest for a lesson with ID
/// `a::b::c::d`.
///
/// All the optional fields mirror one of the fields in the [`LessonManifest`] and their values can
/// be set by writing a JSON file inside the lesson directory with the name
/// `lesson.<PROPERTY_NAME>.json`. This file should contain a JSON serialization of the desired
/// value. For example, to set the lesson's dependencies one would write a file named
/// `lesson.dependencies.json` containing a JSON array of strings, each of them the ID of a
/// dependency.
///
/// The material and instructions of the lesson do not follow this convention. Instead, the files
/// `lesson.instructoins.md` and `lesson.material.md` contain the instructions and material of the
/// lesson.
///
/// None of the `<SHORT_LESSON_ID>.lesson` directories should contain a `lesson_manifest.json` file,
/// as that file would indicate to Trane that this is a regular lesson and not a generated lesson.
#[derive(Clone)]
pub struct KnowledgeBaseLesson {
    /// The short ID of the lesson, which is used to easily identify the lesson and to generate the
    /// final lesson ID.
    pub short_id: Ustr,

    /// The ID of the course to which this lesson belongs.
    pub course_id: Ustr,

    /// The IDs of all dependencies of this lesson. The values can be full lesson IDs or the short
    /// ID of one of the other lessons in the course. If Trane finds a dependency with a short ID,
    /// it will automatically generate the full lesson ID. Not setting this value will indicate that
    /// the lesson has no dependencies.
    pub dependencies: Vec<Ustr>,

    /// The IDs of all courses or lessons encompassed by this lesson and their respective weights.
    pub encompassed: Vec<(Ustr, f32)>,

    /// The IDs of all courses or lessons that this lesson supersedes. Like the dependencies, the
    /// values can be full lesson IDs or the short ID of one of the other lessons in the course. The
    /// same resolution rules apply.
    pub superseded: Vec<Ustr>,

    /// The name of the lesson to be presented to the user.
    pub name: Option<String>,

    /// An optional description of the lesson.
    pub description: Option<String>,

    //// A mapping of String keys to a list of String values used to store arbitrary metadata about
    ///the lesson. This value is set to a `BTreeMap` to ensure that the keys are sorted in a
    ///consistent order when serialized. This is an implementation detail and does not affect how
    ///the value should be written to a file. A JSON map of strings to list of strings works.
    pub metadata: Option<BTreeMap<String, Vec<String>>>,

    /// Indicates whether the `lesson.instructions.md` file is present in the lesson directory.
    pub has_instructions: bool,

    /// Indicates whether the `lesson.material.md` file is present in the lesson directory.
    pub has_material: bool,

    /// The default exercise type for exercises in this lesson.
    pub default_exercise_type: Option<ExerciseType>,
}
//>@knowledge-base-lesson

impl KnowledgeBaseLesson {
    // Filters out exercises that don't have both a front file. Exercises without a back file are
    // allowed, as it is not required to have one.
    fn filter_matching_exercises(exercise_files: &mut HashMap<String, Vec<KnowledgeBaseFile>>) {
        let mut to_remove = Vec::new();
        for (short_id, files) in &*exercise_files {
            let has_front = files
                .iter()
                .any(|file| matches!(file, KnowledgeBaseFile::ExerciseFront(_)));
            if !has_front {
                to_remove.push(short_id.clone());
            }
        }
        for short_id in to_remove {
            exercise_files.remove(&short_id);
        }
    }

    /// Generates the exercise from a list of knowledge base files.
    fn create_lesson(
        lesson_root: &Path,
        short_lesson_id: Ustr,
        course_manifest: &CourseManifest,
        files: &[KnowledgeBaseFile],
    ) -> Result<Self> {
        // Create the lesson with all the optional fields set to a default value.
        let mut lesson = Self {
            short_id: short_lesson_id,
            course_id: course_manifest.id,
            dependencies: vec![],
            encompassed: vec![],
            superseded: vec![],
            name: None,
            description: None,
            metadata: None,
            has_instructions: false,
            has_material: false,
            default_exercise_type: None,
        };

        // Iterate through the lesson files found in the lesson directory and set the corresponding
        // field in the lesson.
        for lesson_file in files {
            match lesson_file {
                KnowledgeBaseFile::LessonDependencies => {
                    let path = lesson_root.join(LESSON_DEPENDENCIES_FILE);
                    lesson.dependencies = KnowledgeBaseFile::open(&path)?;
                }
                KnowledgeBaseFile::LessonEncompassed => {
                    let path = lesson_root.join(LESSON_ENCOMPASSED_FILE);
                    lesson.encompassed = KnowledgeBaseFile::open(&path)?;
                }
                KnowledgeBaseFile::LessonSuperseded => {
                    let path = lesson_root.join(LESSON_SUPERSEDED_FILE);
                    lesson.superseded = KnowledgeBaseFile::open(&path)?;
                }
                KnowledgeBaseFile::LessonName => {
                    let path = lesson_root.join(LESSON_NAME_FILE);
                    lesson.name = Some(KnowledgeBaseFile::open(&path)?);
                }
                KnowledgeBaseFile::LessonDescription => {
                    let path = lesson_root.join(LESSON_DESCRIPTION_FILE);
                    lesson.description = Some(KnowledgeBaseFile::open(&path)?);
                }
                KnowledgeBaseFile::LessonMetadata => {
                    let path = lesson_root.join(LESSON_METADATA_FILE);
                    lesson.metadata = Some(KnowledgeBaseFile::open(&path)?);
                }
                KnowledgeBaseFile::LessonInstructions => lesson.has_instructions = true,
                KnowledgeBaseFile::LessonMaterial => lesson.has_material = true,
                KnowledgeBaseFile::LessonDefaultExerciseType => {
                    let path = lesson_root.join(LESSON_DEFAULT_EXERCISE_TYPE_FILE);
                    lesson.default_exercise_type = Some(KnowledgeBaseFile::open(&path)?);
                }
                _ => {} // grcov-excl-line
            }
        }
        Ok(lesson)
    }

    /// Opens a lesson from the knowledge base with the given root and short ID.
    fn open_lesson(
        lesson_root: &Path,
        course_manifest: &CourseManifest,
        short_lesson_id: Ustr,
    ) -> Result<(KnowledgeBaseLesson, Vec<KnowledgeBaseExercise>)> {
        // Iterate through the directory to find all the matching files in the lesson directory.
        let mut lesson_files = Vec::new();
        let mut exercise_files = HashMap::new();
        let kb_files = read_dir(lesson_root)?
            .flatten()
            .flat_map(|entry| {
                KnowledgeBaseFile::try_from(entry.file_name().to_str().unwrap_or_default())
            })
            .collect::<Vec<_>>();
        for kb_file in kb_files {
            match kb_file {
                KnowledgeBaseFile::ExerciseFront(ref short_id)
                | KnowledgeBaseFile::ExerciseBack(ref short_id)
                | KnowledgeBaseFile::ExerciseName(ref short_id)
                | KnowledgeBaseFile::ExerciseDescription(ref short_id)
                | KnowledgeBaseFile::ExerciseType(ref short_id) => {
                    exercise_files
                        .entry(short_id.clone())
                        .or_insert_with(Vec::new)
                        .push(kb_file);
                }
                _ => lesson_files.push(kb_file),
            }
        }

        // Create the knowledge base lesson.
        let lesson =
            Self::create_lesson(lesson_root, short_lesson_id, course_manifest, &lesson_files)?;

        // Remove exercises for the empty short ID. This can happen if the user has a file named
        // `.front.md`, for example.
        exercise_files.remove("");

        // Filter out exercises that don't have both a front and back file and create the knowledge
        // base exercises.
        Self::filter_matching_exercises(&mut exercise_files);
        let exercises = exercise_files
            .into_iter()
            .map(|(short_id, files)| {
                KnowledgeBaseExercise::create_exercise(
                    lesson_root,
                    &short_id,
                    short_lesson_id,
                    course_manifest,
                    &files,
                )
            })
            .collect::<Result<Vec<_>>>()?;
        Ok((lesson, exercises))
    }
}

impl From<KnowledgeBaseLesson> for LessonManifest {
    /// Generates the manifest for this lesson.
    fn from(lesson: KnowledgeBaseLesson) -> Self {
        Self {
            id: format!("{}::{}", lesson.course_id, lesson.short_id).into(),
            course_id: lesson.course_id,
            dependencies: lesson.dependencies,
            encompassed: lesson.encompassed,
            superseded: lesson.superseded,
            name: lesson.name.unwrap_or(format!("Lesson {}", lesson.short_id)),
            description: lesson.description,
            metadata: lesson.metadata,
            lesson_instructions: if lesson.has_instructions {
                Some(BasicAsset::MarkdownAsset {
                    path: LESSON_INSTRUCTIONS_FILE.into(),
                })
            } else {
                None
            },
            lesson_material: if lesson.has_material {
                Some(BasicAsset::MarkdownAsset {
                    path: LESSON_MATERIAL_FILE.into(),
                })
            } else {
                None
            },
        }
    }
}

/// The configuration for a knowledge base course.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct KnowledgeBaseConfig {
    /// If true, the front and back of the flashcards are inlined in the exercise manifests.
    /// Otherwise, the manifests point to the paths.
    #[serde(default)]
    pub inlined: bool,
}

impl KnowledgeBaseConfig {
    // Checks if the dependencies, encompassed units, and superseded units refer to another lesson
    // in the course by its short ID and updates them to refer to the full lesson ID.
    fn convert_to_full_ids(
        course_manifest: &CourseManifest,
        short_ids: &HashSet<Ustr>,
        lessons: &mut UstrMap<(KnowledgeBaseLesson, Vec<KnowledgeBaseExercise>)>,
    ) {
        for lesson in lessons.values_mut() {
            // Update dependencies.
            let updated_dependencies = lesson
                .0
                .dependencies
                .iter()
                .map(|unit_id| {
                    if short_ids.contains(unit_id) {
                        format!("{}::{}", course_manifest.id, unit_id).into()
                    } else {
                        *unit_id
                    }
                })
                .collect();
            lesson.0.dependencies = updated_dependencies;

            // Update encompassed lessons or courses.
            let updated_encompassed = lesson
                .0
                .encompassed
                .iter()
                .map(|(unit_id, weight)| {
                    if short_ids.contains(unit_id) {
                        (
                            format!("{}::{}", course_manifest.id, unit_id).into(),
                            *weight,
                        )
                    } else {
                        (*unit_id, *weight)
                    }
                })
                .collect();
            lesson.0.encompassed = updated_encompassed;

            // Update superseded lessons or courses.
            let updated_superseded = lesson
                .0
                .superseded
                .iter()
                .map(|unit_id| {
                    if short_ids.contains(unit_id) {
                        format!("{}::{}", course_manifest.id, unit_id).into()
                    } else {
                        *unit_id
                    }
                })
                .collect();
            lesson.0.superseded = updated_superseded;
        }
    }
}

impl GenerateManifests for KnowledgeBaseConfig {
    fn generate_manifests(
        &self,
        course_root: &Path,
        course_manifest: &CourseManifest,
        _preferences: &UserPreferences,
    ) -> Result<GeneratedCourse> {
        // Create the lessons by iterating through all the directories in the course root,
        // processing only those whose name fits the pattern `<SHORT_LESSON_ID>.lesson`.
        let mut lessons = UstrMap::default();
        let valid_entries = read_dir(course_root)?
            .flatten()
            .filter(|entry| {
                let path = entry.path();
                path.is_dir()
            })
            .collect::<Vec<_>>();
        for entry in valid_entries {
            // Check if the directory name is in the format `<SHORT_LESSON_ID>.lesson`. If so, read
            // the knowledge base lesson and its exercises.
            let path = entry.path();
            let dir_name = path.file_name().unwrap_or_default().to_str().unwrap();
            if let Some(short_id) = dir_name.strip_suffix(LESSON_SUFFIX) {
                lessons.insert(
                    short_id.into(),
                    KnowledgeBaseLesson::open_lesson(&path, course_manifest, short_id.into())?,
                );
            }
        }

        // Convert all the dependencies to full lesson IDs.
        let short_ids: HashSet<Ustr> = lessons.keys().copied().collect();
        KnowledgeBaseConfig::convert_to_full_ids(course_manifest, &short_ids, &mut lessons);

        // Generate the manifests for all the lessons and exercises.
        let manifests: Vec<(LessonManifest, Vec<ExerciseManifest>)> = lessons
            .into_iter()
            .map(|(_, (lesson, exercises))| {
                let lesson_manifest = LessonManifest::from(lesson.clone());
                let exercise_manifests = exercises
                    .into_iter()
                    .map(|e| {
                        e.to_exercise_manifest(lesson.default_exercise_type.clone(), self.inlined)
                    })
                    .collect::<Result<Vec<_>>>()?;
                Ok((lesson_manifest, exercise_manifests))
            })
            .collect::<Result<Vec<_>>>()?;

        Ok(GeneratedCourse {
            lessons: manifests,
            updated_instructions: None,
            updated_metadata: None,
        })
    }
}

#[cfg(test)]
#[cfg_attr(coverage, coverage(off))]
mod test {
    use anyhow::Result;
    use std::{
        fs::{self, Permissions},
        io::{BufWriter, Write},
        os::unix::prelude::PermissionsExt,
    };

    use super::*;

    /// Verifies opening a valid knowledge base file.
    #[test]
    fn open_knowledge_base_file() -> Result<()> {
        let temp_dir = tempfile::tempdir()?;
        let file_path = temp_dir.path().join("lesson.dependencies.properties");
        let mut file = File::create(&file_path)?;
        file.write_all(b"[\"lesson1\"]")?;

        let dependencies: Vec<String> = KnowledgeBaseFile::open(&file_path)?;
        assert_eq!(dependencies, vec!["lesson1".to_string()]);
        Ok(())
    }

    /// Verifies the handling of invalid knowledge base files.
    #[test]
    fn open_knowledge_base_file_bad_format() -> Result<()> {
        let temp_dir = tempfile::tempdir()?;
        let file_path = temp_dir.path().join("lesson.dependencies.properties");
        let mut file = File::create(&file_path)?;
        file.write_all(b"[\"lesson1\"")?;

        let dependencies: Result<Vec<String>> = KnowledgeBaseFile::open(&file_path);
        assert!(dependencies.is_err());
        Ok(())
    }

    /// Verifies the handling of knowledge base files that cannot be opened.
    #[test]
    fn open_knowledge_base_file_bad_permissions() -> Result<()> {
        let temp_dir = tempfile::tempdir()?;
        let file_path = temp_dir.path().join("lesson.dependencies.properties");
        let mut file = File::create(&file_path)?;
        file.write_all(b"[\"lesson1\"]")?;

        // Make the directory non-readable to test that the file can't be opened.
        std::fs::set_permissions(temp_dir.path(), Permissions::from_mode(0o000))?;

        let dependencies: Result<Vec<String>> = KnowledgeBaseFile::open(&file_path);
        assert!(dependencies.is_err());
        Ok(())
    }

    /// Verifies that the all the files with knowledge base names are detected correctly.
    #[test]
    fn to_knowledge_base_file() {
        // Parse lesson file names.
        assert_eq!(
            KnowledgeBaseFile::LessonDependencies,
            KnowledgeBaseFile::try_from(LESSON_DEPENDENCIES_FILE).unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::LessonSuperseded,
            KnowledgeBaseFile::try_from(LESSON_SUPERSEDED_FILE).unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::LessonEncompassed,
            KnowledgeBaseFile::try_from(LESSON_ENCOMPASSED_FILE).unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::LessonDescription,
            KnowledgeBaseFile::try_from(LESSON_DESCRIPTION_FILE).unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::LessonMetadata,
            KnowledgeBaseFile::try_from(LESSON_METADATA_FILE).unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::LessonInstructions,
            KnowledgeBaseFile::try_from(LESSON_INSTRUCTIONS_FILE).unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::LessonMaterial,
            KnowledgeBaseFile::try_from(LESSON_MATERIAL_FILE).unwrap(),
        );

        // Parse exercise file names.
        assert_eq!(
            KnowledgeBaseFile::ExerciseName("ex1".to_string()),
            KnowledgeBaseFile::try_from(format!("{}{}", "ex1", EXERCISE_NAME_SUFFIX).as_str())
                .unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::ExerciseFront("ex1".to_string()),
            KnowledgeBaseFile::try_from(format!("{}{}", "ex1", EXERCISE_FRONT_SUFFIX).as_str())
                .unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::ExerciseBack("ex1".to_string()),
            KnowledgeBaseFile::try_from(format!("{}{}", "ex1", EXERCISE_BACK_SUFFIX).as_str())
                .unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::ExerciseDescription("ex1".to_string()),
            KnowledgeBaseFile::try_from(
                format!("{}{}", "ex1", EXERCISE_DESCRIPTION_SUFFIX).as_str()
            )
            .unwrap(),
        );
        assert_eq!(
            KnowledgeBaseFile::ExerciseType("ex1".to_string()),
            KnowledgeBaseFile::try_from(format!("{}{}", "ex1", EXERCISE_TYPE_SUFFIX).as_str())
                .unwrap(),
        );

        // Parse exercise file names with invalid exercise names.
        assert!(KnowledgeBaseFile::try_from("ex1").is_err());
    }

    /// Verifies the conversion from a knowledge base lesson to a lesson manifest.
    #[test]
    fn lesson_to_manifest() {
        let lesson = KnowledgeBaseLesson {
            short_id: "lesson1".into(),
            course_id: "course1".into(),
            name: Some("Name".into()),
            description: Some("Description".into()),
            dependencies: vec!["lesson2".into()],
            encompassed: vec![("lesson4".into(), 0.5)],
            superseded: vec!["lesson0".into()],
            metadata: Some(BTreeMap::from([("key".into(), vec!["value".into()])])),
            has_instructions: true,
            has_material: true,
            default_exercise_type: Some(ExerciseType::Declarative),
        };
        let expected_manifest = LessonManifest {
            id: "course1::lesson1".into(),
            course_id: "course1".into(),
            name: "Name".into(),
            description: Some("Description".into()),
            dependencies: vec!["lesson2".into()],
            encompassed: vec![("lesson4".into(), 0.5)],
            superseded: vec!["lesson0".into()],
            lesson_instructions: Some(BasicAsset::MarkdownAsset {
                path: LESSON_INSTRUCTIONS_FILE.into(),
            }),
            lesson_material: Some(BasicAsset::MarkdownAsset {
                path: LESSON_MATERIAL_FILE.into(),
            }),
            metadata: Some(BTreeMap::from([("key".into(), vec!["value".into()])])),
        };
        let actual_manifest: LessonManifest = lesson.into();
        assert_eq!(actual_manifest, expected_manifest);
    }

    // Verifies the conversion from a knowledge base exercise to an exercise manifest.
    #[test]
    fn exercise_to_manifest() {
        let exercise = KnowledgeBaseExercise {
            short_id: "ex1".into(),
            short_lesson_id: "lesson1".into(),
            course_id: "course1".into(),
            front_file: "ex1.front.md".into(),
            back_file: Some("ex1.back.md".into()),
            name: Some("Name".into()),
            description: Some("Description".into()),
            exercise_type: Some(ExerciseType::Procedural),
        };
        let expected_manifest = ExerciseManifest {
            id: "course1::lesson1::ex1".into(),
            lesson_id: "course1::lesson1".into(),
            course_id: "course1".into(),
            name: "Name".into(),
            description: Some("Description".into()),
            exercise_type: ExerciseType::Procedural,
            exercise_asset: ExerciseAsset::FlashcardAsset {
                front_path: "ex1.front.md".into(),
                back_path: Some("ex1.back.md".into()),
            },
        };
        let actual_manifest = exercise.to_exercise_manifest(None, false).unwrap();
        assert_eq!(actual_manifest, expected_manifest);
    }

    /// Verifies that inlining reads markdown file content into the manifest.
    #[test]
    fn exercise_to_manifest_inlined() -> Result<()> {
        let temp_dir = tempfile::tempdir()?;
        let front_path = temp_dir.path().join("ex1.front.md");
        let back_path = temp_dir.path().join("ex1.back.md");
        fs::write(&front_path, "Front content")?;
        fs::write(&back_path, "Back content")?;

        let exercise = KnowledgeBaseExercise {
            short_id: "ex1".into(),
            short_lesson_id: "lesson1".into(),
            course_id: "course1".into(),
            front_file: front_path.to_str().unwrap().to_string(),
            back_file: Some(back_path.to_str().unwrap().to_string()),
            name: Some("Name".into()),
            description: Some("Description".into()),
            exercise_type: Some(ExerciseType::Procedural),
        };
        let manifest = exercise.to_exercise_manifest(None, true)?;
        assert_eq!(
            manifest.exercise_asset,
            ExerciseAsset::InlineFlashcardAsset {
                front_content: "Front content".into(),
                back_content: Some("Back content".into()),
            }
        );
        Ok(())
    }

    /// Verifies that inlining returns an error when the front file cannot be read.
    #[test]
    fn exercise_to_manifest_inlined_missing_front() {
        let exercise = KnowledgeBaseExercise {
            short_id: "ex1".into(),
            short_lesson_id: "lesson1".into(),
            course_id: "course1".into(),
            front_file: "/path/does/not/exist/front.md".into(),
            back_file: None,
            name: Some("Name".into()),
            description: Some("Description".into()),
            exercise_type: Some(ExerciseType::Procedural),
        };
        let manifest = exercise.to_exercise_manifest(None, true);
        assert!(manifest.is_err());
    }

    /// Verifies the exercise type resolution priority: exercise type > lesson default > Procedural.
    #[test]
    fn exercise_type_resolution() {
        let base_exercise = KnowledgeBaseExercise {
            short_id: "ex1".into(),
            short_lesson_id: "lesson1".into(),
            course_id: "course1".into(),
            front_file: "ex1.front.md".into(),
            back_file: Some("ex1.back.md".into()),
            name: Some("Name".into()),
            description: Some("Description".into()),
            exercise_type: None,
        };

        // Exercise has its own type, ignore lesson default.
        let exercise_with_type = KnowledgeBaseExercise {
            exercise_type: Some(ExerciseType::Declarative),
            ..base_exercise.clone()
        };
        let manifest = exercise_with_type
            .to_exercise_manifest(Some(ExerciseType::Procedural), false)
            .unwrap();
        assert_eq!(manifest.exercise_type, ExerciseType::Declarative);

        // Exercise has no type, use lesson default.
        let exercise_no_type = KnowledgeBaseExercise {
            exercise_type: None,
            ..base_exercise.clone()
        };
        let manifest = exercise_no_type
            .to_exercise_manifest(Some(ExerciseType::Declarative), false)
            .unwrap();
        assert_eq!(manifest.exercise_type, ExerciseType::Declarative);

        // Exercise has no type, lesson has no default, fall back to Procedural.
        let manifest = exercise_no_type.to_exercise_manifest(None, false).unwrap();
        assert_eq!(manifest.exercise_type, ExerciseType::Procedural);
    }

    /// Verifies that dependencies or superseded units referenced by their short IDs are converted
    /// to full IDs.
    #[test]
    fn convert_to_full_ids() {
        // Create an example course manifest.
        let course_manifest = CourseManifest {
            id: "course1".into(),
            name: "Course 1".into(),
            dependencies: vec![],
            encompassed: vec![],
            superseded: vec![],
            description: Some("Description".into()),
            authors: None,
            metadata: Some(BTreeMap::from([("key".into(), vec!["value".into()])])),
            course_instructions: None,
            course_material: None,
            generator_config: None,
        };

        // Create an example lesson with a dependency referred to by its short ID and an example
        // exercise.
        let short_lesson_id = Ustr::from("lesson1");
        let lesson = KnowledgeBaseLesson {
            short_id: short_lesson_id,
            course_id: "course1".into(),
            name: Some("Name".into()),
            description: Some("Description".into()),
            dependencies: vec!["lesson2".into(), "other::lesson1".into()],
            encompassed: vec![("lesson3".into(), 1.0), ("other::lesson3".into(), 0.5)],
            superseded: vec!["lesson0".into(), "other::lesson0".into()],
            metadata: Some(BTreeMap::from([("key".into(), vec!["value".into()])])),
            has_instructions: false,
            has_material: false,
            default_exercise_type: None,
        };
        let exercise = KnowledgeBaseExercise {
            short_id: "ex1".into(),
            short_lesson_id,
            course_id: "course1".into(),
            front_file: "ex1.front.md".into(),
            back_file: Some("ex1.back.md".into()),
            name: Some("Name".into()),
            description: Some("Description".into()),
            exercise_type: Some(ExerciseType::Procedural),
        };
        let mut lesson_map = UstrMap::default();
        lesson_map.insert("lesson1".into(), (lesson, vec![exercise]));

        // Convert the short IDs to full IDs.
        let short_ids = HashSet::from_iter(vec![
            "lesson0".into(),
            "lesson1".into(),
            "lesson2".into(),
            "lesson3".into(),
        ]);
        KnowledgeBaseConfig::convert_to_full_ids(&course_manifest, &short_ids, &mut lesson_map);

        assert_eq!(
            lesson_map.get(&short_lesson_id).unwrap().0.dependencies,
            vec![Ustr::from("course1::lesson2"), "other::lesson1".into()]
        );
        assert_eq!(
            lesson_map.get(&short_lesson_id).unwrap().0.encompassed,
            vec![
                (Ustr::from("course1::lesson3"), 1.0),
                ("other::lesson3".into(), 0.5)
            ]
        );
        assert_eq!(
            lesson_map.get(&short_lesson_id).unwrap().0.superseded,
            vec![Ustr::from("course1::lesson0"), "other::lesson0".into()]
        );
    }

    /// Verifies that exercises with a missing front or back files are filtered out.
    #[test]
    fn filter_matching_exercises() {
        let mut exercise_map = HashMap::default();
        // Exercise 1 has both a front and back file.
        let ex1_id: String = "ex1".into();
        let ex1_files = vec![
            KnowledgeBaseFile::ExerciseFront("ex1".into()),
            KnowledgeBaseFile::ExerciseBack("ex1".into()),
        ];
        // Exercise 2 only has a front file.
        let ex2_id: String = "ex2".into();
        let ex2_files = vec![KnowledgeBaseFile::ExerciseFront("ex2".into())];
        // Exercise 3 only has a back file.
        let ex3_id: String = "ex3".into();
        let ex3_files = vec![KnowledgeBaseFile::ExerciseBack("ex3".into())];
        exercise_map.insert(ex1_id.clone(), ex1_files);
        exercise_map.insert(ex2_id.clone(), ex2_files);
        exercise_map.insert(ex3_id.clone(), ex3_files);

        // Verify that the correct exercises were filtered out.
        KnowledgeBaseLesson::filter_matching_exercises(&mut exercise_map);
        let ex1_expected = vec![
            KnowledgeBaseFile::ExerciseFront("ex1".into()),
            KnowledgeBaseFile::ExerciseBack("ex1".into()),
        ];
        assert_eq!(exercise_map.get(&ex1_id).unwrap(), &ex1_expected);
        let ex2_expected = vec![KnowledgeBaseFile::ExerciseFront("ex2".into())];
        assert_eq!(exercise_map.get(&ex2_id).unwrap(), &ex2_expected);
        assert!(!exercise_map.contains_key(&ex3_id));
    }

    /// Serializes the object in JSON and writes it to the given file.
    fn write_json<T: Serialize>(obj: &T, file: &Path) -> Result<()> {
        let file = File::create(file)?;
        let writer = BufWriter::new(file);
        serde_json::to_writer_pretty(writer, obj)?;
        Ok(())
    }

    /// Verifies opening a lesson directory.
    #[test]
    fn open_lesson_dir() -> Result<()> {
        // Create a test course and lesson directory.
        let course_dir = tempfile::tempdir()?;
        let lesson_dir = course_dir.path().join("lesson1.lesson");
        fs::create_dir(&lesson_dir)?;

        // Create lesson files in the directory.
        let name = "Name";
        let name_path = lesson_dir.join(LESSON_NAME_FILE);
        write_json(&name, &name_path)?;

        let description = "Description";
        let description_path = lesson_dir.join(LESSON_DESCRIPTION_FILE);
        write_json(&description, &description_path)?;

        let dependencies: Vec<Ustr> = vec!["lesson2".into(), "lesson3".into()];
        let dependencies_path = lesson_dir.join(LESSON_DEPENDENCIES_FILE);
        write_json(&dependencies, &dependencies_path)?;

        let encompassed: Vec<(Ustr, f32)> =
            vec![("lesson4".into(), 0.75), ("other::lesson4".into(), 0.25)];
        let encompassed_path = lesson_dir.join(LESSON_ENCOMPASSED_FILE);
        write_json(&encompassed, &encompassed_path)?;

        let superseded: Vec<Ustr> = vec!["lesson0".into()];
        let superseded_path = lesson_dir.join(LESSON_SUPERSEDED_FILE);
        write_json(&superseded, &superseded_path)?;

        let metadata: BTreeMap<String, Vec<String>> =
            BTreeMap::from([("key".into(), vec!["value".into()])]);
        let metadata_path = lesson_dir.join(LESSON_METADATA_FILE);
        write_json(&metadata, &metadata_path)?;

        let instructions = "instructions";
        let instructions_path = lesson_dir.join(LESSON_INSTRUCTIONS_FILE);
        write_json(&instructions, &instructions_path)?;

        let material = "material";
        let material_path = lesson_dir.join(LESSON_MATERIAL_FILE);
        write_json(&material, &material_path)?;

        let default_ex_type = ExerciseType::Declarative;
        let default_ex_type_path = lesson_dir.join(LESSON_DEFAULT_EXERCISE_TYPE_FILE);
        write_json(&default_ex_type, &default_ex_type_path)?;

        // Create an example exercise and all of its files.
        let front_content = "Front content";
        let front_path = lesson_dir.join("ex1.front.md");
        fs::write(front_path, front_content)?;

        let back_content = "Back content";
        let back_path = lesson_dir.join("ex1.back.md");
        fs::write(back_path, back_content)?;

        let exercise_name = "Exercise name";
        let exercise_name_path = lesson_dir.join("ex1.name.json");
        write_json(&exercise_name, &exercise_name_path)?;

        let exercise_description = "Exercise description";
        let exercise_description_path = lesson_dir.join("ex1.description.json");
        write_json(&exercise_description, &exercise_description_path)?;

        let exercise_type = ExerciseType::Procedural;
        let exercise_type_path = lesson_dir.join("ex1.type.json");
        write_json(&exercise_type, &exercise_type_path)?;

        // Create a test course manifest.
        let course_manifest = CourseManifest {
            id: "course1".into(),
            name: "Course 1".into(),
            dependencies: vec![],
            encompassed: vec![],
            superseded: vec![],
            description: Some("Description".into()),
            authors: None,
            metadata: Some(BTreeMap::from([("key".into(), vec!["value".into()])])),
            course_instructions: None,
            course_material: None,
            generator_config: None,
        };

        // Open the lesson directory.
        let (lesson, exercises) =
            KnowledgeBaseLesson::open_lesson(&lesson_dir, &course_manifest, "lesson1".into())?;

        // Verify the lesson.
        assert_eq!(lesson.name, Some(name.into()));
        assert_eq!(lesson.description, Some(description.into()));
        assert_eq!(lesson.dependencies, dependencies);
        assert_eq!(lesson.encompassed, encompassed);
        assert_eq!(lesson.superseded, superseded);
        assert_eq!(lesson.metadata, Some(metadata));
        assert!(lesson.has_instructions);
        assert!(lesson.has_material);
        assert_eq!(lesson.default_exercise_type, Some(default_ex_type));

        // Verify the exercise.
        assert_eq!(exercises.len(), 1);
        let exercise = &exercises[0];
        assert_eq!(exercise.name, Some(exercise_name.into()));
        assert_eq!(exercise.description, Some(exercise_description.into()));
        assert_eq!(exercise.exercise_type, Some(exercise_type));
        assert_eq!(
            exercise.front_file,
            lesson_dir
                .join("ex1.front.md")
                .to_str()
                .unwrap()
                .to_string()
        );
        assert_eq!(
            exercise.back_file.clone().unwrap_or_default(),
            lesson_dir.join("ex1.back.md").to_str().unwrap().to_string()
        );
        Ok(())
    }
}