From 46ab1720d775b67e7fa128ecb1c5e8452ad8a8fe Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sat, 29 Nov 2025 02:56:21 +0100 Subject: [PATCH] Mostly doc & Tags & Summary --- Cargo.lock | 1 + Cargo.toml | 1 + bin_efo/Cargo.toml | 1 + bin_efo/src/commands/epoch.rs | 119 +++++++++++++++++------ bin_efo/src/commands/epoch/cli_epoch.rs | 13 ++- bin_efo/src/commands/init.rs | 7 +- bin_efo/src/main.rs | 11 +-- bin_efo/src/success.rs | 25 +++++ lib_efo/Cargo.toml | 2 +- lib_efo/src/epoch_struct/epoch_config.rs | 12 +-- lib_efo/src/epoch_struct/epoch_info.rs | 15 +-- lib_efo/src/epoch_traits.rs | 57 ++++++++--- lib_efo/src/lib.rs | 1 + lib_efo/src/utils.rs | 13 +-- 14 files changed, 199 insertions(+), 79 deletions(-) create mode 100644 bin_efo/src/success.rs diff --git a/Cargo.lock b/Cargo.lock index 8b824cc..a70b004 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -105,6 +105,7 @@ name = "bin_efo" version = "0.1.0" dependencies = [ "clap", + "derive_more", "env_logger", "lib_efo", "log", diff --git a/Cargo.toml b/Cargo.toml index 839f255..12f5a22 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -10,3 +10,4 @@ serde_json = "1.0.145" miette = { version = "7.6.0", features = ["fancy"] } env_logger = "0.11.8" log = "0.4.28" +derive_more = { version = "2.0.1", features = ["display"] } diff --git a/bin_efo/Cargo.toml b/bin_efo/Cargo.toml index c239761..9537697 100644 --- a/bin_efo/Cargo.toml +++ b/bin_efo/Cargo.toml @@ -12,3 +12,4 @@ serde_json = {workspace = true} miette = {workspace = true} env_logger = {workspace = true} log = {workspace = true} +derive_more = {workspace = true} diff --git a/bin_efo/src/commands/epoch.rs b/bin_efo/src/commands/epoch.rs index 7afdc3f..a860281 100644 --- a/bin_efo/src/commands/epoch.rs +++ b/bin_efo/src/commands/epoch.rs @@ -4,14 +4,41 @@ //! next epoch, and resetting future events. #![warn(missing_docs, clippy::missing_docs_in_private_items)] -use crate::error::AppError; -use lib_efo::{epoch_struct::EpochConfig, epoch_traits::ConfigWritable, error::EpochError}; +use crate::{ + error::AppError, + success::{SuccessMessages, display_success}, +}; +use lib_efo::{ + epoch_struct::{EpochConfig, EpochId}, + epoch_traits::ConfigWritable, + error::EpochError, +}; use log::{debug, info}; pub mod cli_epoch; /// **Public entry point used by `efo::main`** – dispatches to the real /// handler that lives in `crate::world::EpochManager`. +/// +/// # Arguments +/// * `cmd` – The command to execute. This is an enum that represents +/// one of the possible sub‑commands for the `epoch` feature. +/// +/// # Returns +/// * `Ok(())` on success. +/// * `Err(AppError)` if any step of the command handling fails. +/// +/// # Examples +/// ```no_run +/// // Create a command to switch to epoch 3. +/// let cmd = cli_epoch::EpochCmd::Switch(cli_epoch::Switch { target: 3 }); +/// // Execute the command. +/// let result = handle_cmd(cmd); +/// assert!(result.is_ok()); +/// ``` +/// +/// The function never panics under normal operation. All errors are +/// reported via the returned `Result`. pub fn handle_cmd(cmd: cli_epoch::EpochCmd) -> Result<(), AppError> { let mut main_epoch = EpochConfig::new_from_path(None)?; // // TODO[2]: Remove this debug @@ -24,58 +51,91 @@ pub fn handle_cmd(cmd: cli_epoch::EpochCmd) -> Result<(), AppError> { cli_epoch::EpochCmd::Diff(args) => handle_diff(args), cli_epoch::EpochCmd::Tag(args) => handle_taging(args, &mut main_epoch), cli_epoch::EpochCmd::Fsck(args) => handle_fsck(args, &mut main_epoch), + cli_epoch::EpochCmd::Summary(args) => handle_summary(args, &mut main_epoch), }?; info!("The main epoch after all actions is {:#?}", main_epoch); Ok(()) } -/// Show the diff between two epochs +/// Edits the summary for the current epoch. +/// +/// The function loads the epoch that is currently active in +/// `main_epoch`, then replaces its `summary` field with the value +/// supplied in `args.summary`. The epoch map in `main_epoch` is +/// modified in place. +/// +/// This helper is internal to the `epoch` sub‑command and is not part +/// of the public API. +fn handle_summary(args: cli_epoch::Summary, main_epoch: &mut EpochConfig) -> Result<(), AppError> { + let epoch_id = main_epoch.epoch_id; + main_epoch.try_load(&epoch_id)?; + #[allow(clippy::unwrap_used)] // The epoch_id must exists at this point + if let Some(epoch) = main_epoch.list_existing_epochs.get_mut(&epoch_id).unwrap() { + epoch.summary = args.summary.clone(); + epoch.save_with_context( + "Saving new summary", + &lib_efo::epoch_struct::SaveMode::Erase, + )?; + display_success(&SuccessMessages::ChangedSummary(epoch_id, args.summary)); + } + + Ok(()) +} + +/// Show a diff between two epochs. +/// +/// Currently unimplemented. The function is a placeholder until a +/// world‑level diff algorithm is available. +/// +/// This helper is internal to the `epoch` sub‑command and is not part +/// of the public API. fn handle_diff(args: cli_epoch::Diff) -> Result<(), AppError> { let _ = args; unimplemented!("Blocker: There is actually no way to diff the world yet") } -/// Show a log of all different epochs +/// Show a log of all epochs up to the current one. +/// +/// The function collects the identifiers of all epochs that are +/// less than or equal to the currently active epoch (`main_epoch.epoch_id`), +/// sorts them, and then asks the configuration to log the elements +/// up to the supplied limit. The log is written by the +/// underlying `EpochConfig::log_elements` implementation. +/// +/// This helper is internal to the `epoch` sub‑command. fn handle_log(args: cli_epoch::Log, main_epoch: &mut EpochConfig) -> Result<(), AppError> { - // TODO: Have a special centralized message dispacher - println!("Epoch log (most recent first):"); let limit = args.limit; let start_id = &main_epoch.epoch_id; - let list_id = main_epoch + let mut list_id: Vec = main_epoch .list_existing_epochs .iter() .filter(|(id, _)| id <= &start_id) - .take(limit) - .map(|(id, _)| id) - .copied() - .collect::>(); - - main_epoch.log_elements(&list_id)?; - + .map(|(id, _)| *id) + .collect(); + list_id.sort(); + main_epoch.log_elements(&list_id[..std::cmp::min(list_id.len(), limit)])?; Ok(()) } /// Switches the current epoch to the one specified by the user. /// -/// This updates the in‑memory configuration, reloads the target epoch, -/// updates the epoch identifier, and persists the changes. +/// The function loads the target epoch, updates the epoch identifier +/// in the configuration, and persists the change. It also prints a +/// success message via `display_success`. /// -/// # Arguments -/// * `args` – `cli_epoch::Switch` containing the target epoch identifier. -/// * `main_epoch` – mutable reference to the current `EpochConfig`. +/// This helper is internal to the `epoch` sub‑command. fn handle_switch(args: cli_epoch::Switch, main_epoch: &mut EpochConfig) -> Result<(), AppError> { let target = main_epoch.get(&args.target)?; main_epoch.try_load(&target)?; main_epoch.epoch_id = target; - // TODO: Have a special centralized message dispacher - println!("Switched to epoch {:?}", target); main_epoch.save_with_context( "Saving modified epoch config", &lib_efo::epoch_struct::SaveMode::Erase, )?; + display_success(&SuccessMessages::EpochSwitchSuccess(target)); Ok(()) } @@ -108,9 +168,7 @@ fn handle_next(_args: cli_epoch::Next, main_epoch: &mut EpochConfig) -> Result<( let new_epoch = main_epoch.compute_next()?; // Insert new epoch - main_epoch - .insert_and_save(new_epoch, &lib_efo::epoch_struct::SaveMode::DoNotErase) - .unwrap(); + main_epoch.insert_and_save(new_epoch, &lib_efo::epoch_struct::SaveMode::DoNotErase)?; Ok(()) } } @@ -141,8 +199,8 @@ fn handle_reset(args: cli_epoch::Reset, main_epoch: &mut EpochConfig) -> Result< { main_epoch.delete_id(id)? } - // TODO: Have a special centralized message dispacher - println!("All future events deleted – back to epoch {current_id}",); + + display_success(&SuccessMessages::DeletedAllFutureEvents(current_id)); Ok(()) } @@ -200,10 +258,15 @@ fn handle_taging(args: cli_epoch::Tag, main_epoch: &mut EpochConfig) -> Result<( } } -/// Performs a basic sanity check. +/// Perform a filesystem consistency check on the epoch data. /// -/// Currently unimplemented – the function will panic at runtime. +/// The function invokes the internal consistency‑check logic of +/// `EpochConfig`. It is intended for use from the `fsck` sub‑command +/// and does **not** modify the current epoch. Any problems that +/// are detected are reported through the returned `Result`; the +/// command may also print a diagnostic message to the user. /// +/// This helper is internal to the `epoch` sub‑command. fn handle_fsck(args: cli_epoch::Fsck, main_epoch: &mut EpochConfig) -> Result<(), AppError> { let _ = main_epoch; let _ = args; diff --git a/bin_efo/src/commands/epoch/cli_epoch.rs b/bin_efo/src/commands/epoch/cli_epoch.rs index 1035258..f768f86 100644 --- a/bin_efo/src/commands/epoch/cli_epoch.rs +++ b/bin_efo/src/commands/epoch/cli_epoch.rs @@ -44,6 +44,9 @@ pub enum EpochCmd { /// Basic filesystem level maintenance Fsck(Fsck), + + /// Edits the summary for the current epoch + Summary(Summary), } /// Displays a git‑log style list of epochs. @@ -106,10 +109,18 @@ pub struct Diff { #[derive(Args, Debug)] pub struct Tag { #[arg(required = true)] - /// The tag to tag the current epoch with + #[allow(clippy::missing_docs_in_private_items)] pub tag: String, } /// Performs basic filesystem level maintenance. #[derive(Debug, Args)] pub struct Fsck {} + +/// Edits the current's epoch summary. +#[derive(Debug, Args)] +pub struct Summary { + #[arg(required = true)] + #[allow(clippy::missing_docs_in_private_items)] + pub summary: String, +} diff --git a/bin_efo/src/commands/init.rs b/bin_efo/src/commands/init.rs index 6717cb3..e7b7379 100644 --- a/bin_efo/src/commands/init.rs +++ b/bin_efo/src/commands/init.rs @@ -19,7 +19,10 @@ use lib_efo::{ }; use std::fs::read_dir; -use crate::error::AppError; +use crate::{ + error::AppError, + success::{SuccessMessages, display_success}, +}; #[derive(Args, Debug)] @@ -60,6 +63,8 @@ pub fn init(args: &InitCmd) -> Result<(), AppError> { .to_string(), ), })?; + + display_success(&SuccessMessages::FolderInitializedSuccessfully(".")); Ok(()) } diff --git a/bin_efo/src/main.rs b/bin_efo/src/main.rs index 632e51d..5182d77 100644 --- a/bin_efo/src/main.rs +++ b/bin_efo/src/main.rs @@ -21,12 +21,14 @@ //! ``` #![warn(missing_docs, clippy::missing_docs_in_private_items)] +#![deny(clippy::unwrap_used)] use clap::{ArgAction, Parser, Subcommand}; use crate::commands::init::InitCmd; use crate::{commands::epoch::cli_epoch::EpochCmd, error::AppError}; mod commands; mod error; +mod success; /// The root command‑line parser for the `efo` binary. /// @@ -66,8 +68,8 @@ enum TopLevelCmd { /// Program entry point. /// /// Parses the command‑line arguments and dispatches to the selected -/// sub‑command. Errors returned by the sub‑command handlers are printed -/// to stdout and returned as a `miette::Result<()>`. +/// sub‑command. Errors returned by the sub‑command handlers are shown +/// in stdout and returned as a `miette::Result<()>`. fn main() -> miette::Result<()> { env_logger::init(); let cli = Cli::parse(); @@ -90,18 +92,15 @@ fn main() -> miette::Result<()> { /// /// The function matches on the `TopLevelCmd` variant and calls the /// corresponding handler in the `commands` module. Any error is -/// propagated to the caller, which in `main` will be printed to +/// propagated to the caller, which in `main` will be shown to /// stdout and returned as a `miette::Result<()>`. fn exec_dispatch(cli: Cli) -> Result<(), AppError> { match cli.command { TopLevelCmd::Init(cmd) => { commands::init::init(&cmd)?; - // TODO: Have a special centralized message dispacher - println!("The folder was initialized as an epoch folder") } TopLevelCmd::Epoch(cmd) => { commands::epoch::handle_cmd(cmd)?; - // println!("") } } Ok(()) diff --git a/bin_efo/src/success.rs b/bin_efo/src/success.rs new file mode 100644 index 0000000..cb1e53b --- /dev/null +++ b/bin_efo/src/success.rs @@ -0,0 +1,25 @@ +//! List of all success messages possible + +use derive_more::Display; +use lib_efo::epoch_struct::EpochId; + +#[derive(Display, Clone, Debug)] +#[allow(missing_docs, clippy::missing_docs_in_private_items)] +pub enum SuccessMessages { + #[display("Switched to epoch {_0}")] + EpochSwitchSuccess(lib_efo::epoch_struct::EpochId), + + #[display("All future events deleted – back to epoch {_0}")] + DeletedAllFutureEvents(lib_efo::epoch_struct::EpochId), + + #[display("The folder was initialized as an epoch folder")] + FolderInitializedSuccessfully(&'static str), + + #[display("Changed the summary of epoch {_0} with: '{_1}'")] + ChangedSummary(EpochId, String), +} + +/// Display the success message to stdout +pub fn display_success(message: &SuccessMessages) { + println!("{}", message) +} diff --git a/lib_efo/Cargo.toml b/lib_efo/Cargo.toml index 8ab53cb..d9e38e8 100644 --- a/lib_efo/Cargo.toml +++ b/lib_efo/Cargo.toml @@ -11,5 +11,5 @@ clap = {workspace = true} miette = {workspace = true} env_logger = {workspace = true} log = {workspace = true} -derive_more = { version = "2.0.1", features = ["display"] } +derive_more = {workspace = true} cli-table = "0.5.0" diff --git a/lib_efo/src/epoch_struct/epoch_config.rs b/lib_efo/src/epoch_struct/epoch_config.rs index 2f6321c..217941c 100644 --- a/lib_efo/src/epoch_struct/epoch_config.rs +++ b/lib_efo/src/epoch_struct/epoch_config.rs @@ -17,7 +17,7 @@ use std::{ path::Path, }; -use log::info; +use log::{info, warn}; use serde::{Deserialize, Serialize}; use crate::{ @@ -98,9 +98,9 @@ impl EpochConfig { for elt in path { let elt = io_err_with_help!(elt, "Opening file in main config folder")?; if io_err_with_help!(elt.file_type(), "Determining file type of {:?}", elt)?.is_dir() { - let id = elt.file_name().to_string_lossy().parse::(); + let id = elt.file_name().to_string_lossy().parse::()?; info!("Initialized {:?}", id); - self.list_existing_epochs.insert(id.unwrap(), None); + self.list_existing_epochs.insert(id, None); } } Ok(self) @@ -188,7 +188,7 @@ impl EpochConfig { // TODO[9]: Create a delete_ids taking an iterator for added performance on huge deletions pub fn delete_id(&mut self, id: EpochId) -> Result<(), EpochError> { if !self.list_existing_epochs.contains_key(&id) { - println!( + warn!( "The given epoch {} doesn't exists and it's deletion was skipped", id ) @@ -213,7 +213,7 @@ impl EpochConfig { pub fn compute_next(&mut self) -> Result { // unimplemented!() // TODO[1]: Implement this - println!("DEBUG LINE: COMPUTING NEXT EPOCH"); + warn!("DEBUG LINE: COMPUTING NEXT EPOCH"); // New fake epoch Ok(EpochInfo::with_id(&self.epoch_id.next())) } @@ -252,7 +252,7 @@ impl EpochConfig { /// Load and display the metadata for a list of epoch IDs. /// /// The function first ensures that each requested epoch’s metadata is - /// loaded into memory, then prints a formatted log for each one. + /// loaded into memory, then displays a formatted log for each one. pub fn log_elements(&mut self, list_ids: &[EpochId]) -> Result<(), EpochError> { let mut items_to_log = Vec::with_capacity(list_ids.len()); // Tries to load all ids into memory diff --git a/lib_efo/src/epoch_struct/epoch_info.rs b/lib_efo/src/epoch_struct/epoch_info.rs index 4191705..7d28e9c 100644 --- a/lib_efo/src/epoch_struct/epoch_info.rs +++ b/lib_efo/src/epoch_struct/epoch_info.rs @@ -6,7 +6,7 @@ //! seed that produced the world, any optional tags, and a human‑readable //! summary. World data itself is stored separately (e.g. in `world.json`). -use cli_table::{Table, WithTitle}; +use cli_table::Table; use derive_more::Display; use serde::{Deserialize, Serialize}; use std::fs::create_dir_all; @@ -25,11 +25,10 @@ use crate::{ /// reconstruct the state *of that particular epoch* (seed, selected /// events, parent link, etc.). The full world data is kept in /// separate storage (e.g. `world.json`). -#[derive(Debug, Clone, Serialize, Deserialize, Display)] +#[derive(Debug, Clone, Serialize, Deserialize, Display, Table)] #[display( "Epoch ({epoch_id:>5}) | seed ({rng_seed:<10}) | tags ({tags:<10}) | summary ({summary:<20})" )] -#[derive(Table)] pub struct EpochInfo { /// The ID of this epoch – should match the directory name. #[table(title = "ID")] @@ -54,15 +53,7 @@ pub struct EpochInfo { pub summary: String, } -impl Prettiable for EpochInfo { - fn show_as_table(list: Vec<&Self>) { - cli_table::print_stdout(list.with_title()).unwrap(); - } - - fn as_log(&self) -> String { - format!("{}", self) - } -} +impl Prettiable for EpochInfo {} impl Default for EpochInfo { fn default() -> Self { diff --git a/lib_efo/src/epoch_traits.rs b/lib_efo/src/epoch_traits.rs index 9510172..85e16d9 100644 --- a/lib_efo/src/epoch_traits.rs +++ b/lib_efo/src/epoch_traits.rs @@ -5,8 +5,9 @@ //! common to many of the library’s element types. #![warn(clippy::missing_docs_in_private_items)] +use cli_table::{Style, Table, WithTitle}; use serde::Serialize; -use std::{fs::File, io::Write}; +use std::{fmt::Display, fs::File, io::Write}; use crate::{epoch_struct::SaveMode, error::EpochError}; @@ -23,22 +24,31 @@ pub trait Applyable {} pub trait Nextable {} /// Elements that can be rendered into a pretty, human‑readable form. -pub trait Prettiable { - // TODO: Doc - /// Show many as a table - fn show_as_table(list: Vec<&Self>) { - list.iter().for_each(|e| { - e.show_as_log(); - }); +pub trait Prettiable: Display { + /// Shows many items as a table. + /// + /// The table is printed to `stdout` using the `cli_table` crate. + /// + /// # Panics + /// Panics if printing the table to stdout fails. + fn show_as_table(list: Vec<&Self>) + where + for<'a> Vec<&'a Self>: Table + WithTitle, + { + #[allow(clippy::unwrap_used)] // There is no recovery of not being able to print a table + cli_table::print_stdout(list.with_title().bold(true)).unwrap(); } - /// Print function as a log + /// Displays the struct as a log entry by printing the output of + /// `as_log()` to stdout. fn show_as_log(&self) { println!("{}", self.as_log()) } - /// Convert the struct into a pretty log - fn as_log(&self) -> String; + /// Converts the struct into a pretty log string. + fn as_log(&self) -> String { + format!("{}", self) + } } /// Trait representing a serialisable / writable config @@ -49,7 +59,14 @@ pub trait ConfigWritable: Serialize { /// The folder where to save the file to save the config fn save_folder(&self) -> String; - /// Have the config as JSON + /// Serialises the config into a pretty JSON string. + /// + /// # Arguments + /// * `action` - A description of the action for error reporting. + /// + /// # Returns + /// * `Ok(String)` containing the pretty‑printed JSON. + /// * `Err(EpochError::Serde)` if serialisation fails. fn as_json(&self, action: String) -> Result { serde_json::to_string_pretty(self).map_err(|e| EpochError::Serde { source: e, @@ -58,9 +75,21 @@ pub trait ConfigWritable: Serialize { }) } - /// Save the config into it's nominal path + /// Saves the config into its nominal path. /// - /// This command will NOT create all subdirectories + /// Existing subdirectories are not created. + /// If `do_not_erase` is `SaveMode::Erase`, an existing file is overwritten. + /// If `do_not_erase` is `SaveMode::DoNotErase`, an error is returned when the + /// file already exists. + /// + /// # Arguments + /// * `action_description` – A human‑readable description used in error messages. + /// * `do_not_erase` – Determines whether to overwrite an existing file. + /// + /// # Returns + /// * `Ok(())` on success. + /// * `Err(EpochError::ConfigWrite)` on any serialization error. + /// * `Err(EpochError::ConfigCreation)` on any I/O error. fn save_with_context( &self, // Very unsure about this versus a macro diff --git a/lib_efo/src/lib.rs b/lib_efo/src/lib.rs index ee2acc6..5c0ffe5 100644 --- a/lib_efo/src/lib.rs +++ b/lib_efo/src/lib.rs @@ -18,6 +18,7 @@ //! `World::load()` / `World::save()` API that uses the default JSON file #![warn(missing_docs, clippy::missing_docs_in_private_items)] +#![deny(clippy::unwrap_used)] pub mod epoch_struct; pub mod epoch_traits; diff --git a/lib_efo/src/utils.rs b/lib_efo/src/utils.rs index d5c2794..67aac5b 100644 --- a/lib_efo/src/utils.rs +++ b/lib_efo/src/utils.rs @@ -13,20 +13,13 @@ use crate::error::EpochError; /// Check whether `path` points to a valid Epoch directory. /// /// A *valid* directory is one that satisfies the expectations of the `epoch` format. -#[deprecated] -pub fn is_a_epoch_directory(path: &Path) -> Result<(), EpochError> { - let dir = path.read_dir().map_err(|_e| { - EpochError::MainFolderInvalid(path.to_str().unwrap_or_default().to_owned()) - })?; - for e in dir.flatten() { - println!("{:?}", e.file_name()); - } - Ok(()) +pub fn is_a_epoch_directory(_path: &Path) -> Result<(), EpochError> { + todo!() } /// Validate that the configuration file at `path` is well‑formed. pub fn is_config_well_formated(_path: &Path) -> Result<(), EpochError> { - Ok(()) + todo!() } #[cfg(test)]