From 3e18ddb8701107dec759294971a79d95a63085ac Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 20 Sep 2026 21:02:27 +0200 Subject: [PATCH] docs: complete trustworthy foundation milestone --- AGENTS-TASKS.md | 11 ++++--- bin_efo/src/commands/entity_generic.rs | 8 ++--- bin_efo/src/commands/epoch.rs | 5 ++-- bin_efo/src/commands/init.rs | 3 +- docs/roadmap.md | 11 +++++-- .../src/entity/implementations/accesors.rs | 2 +- lib_efo/src/epoch/epoch_config.rs | 25 ++++------------ lib_efo/src/epoch/epoch_info.rs | 18 +++++------ lib_efo/src/error.rs | 20 ++++++------- lib_efo/src/stats/implementations.rs | 30 ++++++++++++------- 10 files changed, 64 insertions(+), 69 deletions(-) diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 97b2c83..085fb7b 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -4,6 +4,9 @@ This is the working backlog for bringing the current CLI to a trustworthy early-alpha release. Checkboxes describe completion, not intention. Newly found work belongs here before implementation. +**Milestone 1 — trustworthy foundation: complete.** Phases 0–2 passed their +acceptance gates on 2026-09-20. Phase 3 is the next active milestone. + ## Phase 0 — audit and guardrails - [x] Inventory workspace crates, commands, persistence files, CI, and tests. @@ -27,7 +30,7 @@ work belongs here before implementation. - [x] Add a compatibility policy for stored data and CLI scripts. - [x] Add a roadmap that distinguishes implemented, current-release, planned, and stretch work. -- [ ] Correct typos, stale rustdoc examples, and misleading comments. +- [x] Correct typos, stale rustdoc examples, and misleading comments. ## Phase 2 — test and harden the existing product @@ -117,7 +120,7 @@ These require user approval and are not part of the current implementation: several optional Nerd Font glyphs for labels. - Name generation used to create `naming.json` in the working directory; this was removed in favor of read-only embedded defaults. -- The binary now has four integration tests; broad lifecycle and failure-path - coverage remains on the backlog. -- All 62 tests and the release build passed on 2026-09-20. Tarpaulin was intentionally not +- The binary now has nine integration tests covering every exposed entity type, + timeline workflows, invalid input, and corrupted repositories. +- All 70 tests and the release build passed on 2026-09-20. Tarpaulin was intentionally not run because badges are release-only by project policy. diff --git a/bin_efo/src/commands/entity_generic.rs b/bin_efo/src/commands/entity_generic.rs index f75e0b0..b46cd57 100644 --- a/bin_efo/src/commands/entity_generic.rs +++ b/bin_efo/src/commands/entity_generic.rs @@ -210,7 +210,7 @@ pub struct CommonArgs { pub faction: Option, #[arg(short = 'N', long, action = clap::ArgAction::SetTrue, default_value_t = false, group="faction_group")] - /// The entity doens't belong to any faction. + /// The entity does not belong to any faction. pub no_faction: bool, /// Updates the reach of the entity @@ -226,14 +226,14 @@ pub struct CommonArgs { pub governor: Option, #[arg(long, action = clap::ArgAction::SetTrue, default_value_t = false, group="governor_group")] - /// The entity doens't belong to any faction. + /// The entity does not have a governor. pub no_governor: bool, /// Link to a town to set as capital #[arg(long, short = 'c', group = "capital_group")] pub capital: Option, - /// The entity doens't have a capital. + /// The entity does not have a capital. #[arg(long, action = clap::ArgAction::SetTrue, default_value_t = false, group="capital_group")] pub no_capital: bool, @@ -396,7 +396,7 @@ fn handle_delete_entity( let entity = vec_entities.swap_remove(index); entity.remove_all_links(epoch_info)?; - // TODO: Clean all the links from it's presence + // TODO: Clean every bidirectional link referencing the removed entity. // for l in entity.links(){ // // Figure out what the link is diff --git a/bin_efo/src/commands/epoch.rs b/bin_efo/src/commands/epoch.rs index d0b03f8..660721d 100644 --- a/bin_efo/src/commands/epoch.rs +++ b/bin_efo/src/commands/epoch.rs @@ -84,8 +84,7 @@ pub mod cli_epoch; /// 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 - debug!("The main epoch befor any action is {:#?}", main_epoch); + debug!("The main epoch before any action is {:#?}", main_epoch); match cmd { cli_epoch::EpochCmd::Log(args) => handle_log(args, &mut main_epoch), cli_epoch::EpochCmd::Switch(args) => handle_switch(args, &mut main_epoch), @@ -341,7 +340,7 @@ fn handle_taging(args: &cli_epoch::Tag, main_epoch: &mut EpochConfig) -> Result< // Load into memory the current epoch main_epoch.try_load(&main_epoch.epoch_id.clone())?; - // Check if the tag doens't exists + // Reject duplicate tags before modifying either persisted file. if main_epoch.tags.contains_key(&args.tag) { Err(AppError::Epoch(EpochError::TagAlreadyExists( main_epoch.epoch_id, diff --git a/bin_efo/src/commands/init.rs b/bin_efo/src/commands/init.rs index 590f5e1..165ff95 100644 --- a/bin_efo/src/commands/init.rs +++ b/bin_efo/src/commands/init.rs @@ -59,7 +59,6 @@ pub struct InitCmd { /// /// Creates the default `EpochConfig`, verifies that the target directory /// is empty, and writes the initial configuration and epoch data. -//TODO(5): Upholster the logic behind force and empty detection pub fn init(args: &InitCmd) -> Result<(), AppError> { let epoch_config = EpochConfig::default(); let root = epoch_config.save_folder(); @@ -85,7 +84,7 @@ pub fn init(args: &InitCmd) -> Result<(), AppError> { init_epoch()?; epoch_config .save_with_context( - "Creatig initial config", + "Creating initial config", &lib_efo::epoch::SaveMode::DoNotErase, ) .map_err(|_| EpochError::AlreadyInitialized { diff --git a/docs/roadmap.md b/docs/roadmap.md index 66df486..5e34eda 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -12,9 +12,14 @@ The detailed backlog is [AGENTS-TASKS.md](../AGENTS-TASKS.md). ## Current release target -The immediate release prioritises trust: truthful help/docs, no user-triggerable -panics, safe initialisation, real `show`, useful read-only `fsck`, world diff, -atomic persistence, CLI workflow tests, accessible output, and clear recovery. +The trustworthy-foundation milestone is complete: documentation now reflects +the executable, user-triggerable panic paths found in the audit are guarded, +initialisation is safe, `show`, read-only `fsck`, and world diff are real, +individual files are persisted atomically, and CLI workflows are covered. + +The next milestone focuses on the remaining daily-use polish: consistent naming +and aliases, richer self-documenting help, accessible output, type-specific +validation, and a tested reversal path for every mutation. Next comes a reviewed Git-like model for working changes, pseudo-staging, committed epochs, restore, and revert. Organisation-agnostic custom fields and diff --git a/lib_efo/src/entity/implementations/accesors.rs b/lib_efo/src/entity/implementations/accesors.rs index 413d9bf..1347013 100644 --- a/lib_efo/src/entity/implementations/accesors.rs +++ b/lib_efo/src/entity/implementations/accesors.rs @@ -255,7 +255,7 @@ impl Entity { self.stats.update(); } - /// Returns whether the entity match an optionnal identifier + /// Return whether the entity matches an optional identifier. pub fn match_identifier(&self, entity_identifier: &Option) -> bool { match entity_identifier { Some(EntityIdentifier::Name(name)) => { diff --git a/lib_efo/src/epoch/epoch_config.rs b/lib_efo/src/epoch/epoch_config.rs index 8d1643c..def5b97 100644 --- a/lib_efo/src/epoch/epoch_config.rs +++ b/lib_efo/src/epoch/epoch_config.rs @@ -70,7 +70,7 @@ impl Default for EpochConfig { } impl EpochConfig { - /// Create a new config from an existig path + /// Load and initialise a configuration from the current repository. pub fn new_from_path(_path: Option<&Path>) -> Result { let path = Path::new(MAIN_NAME); @@ -294,10 +294,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) { - warn!( - "The given epoch {} doesn't exists and it's deletion was skipped", - id - ) + warn!("Epoch {} does not exist; deletion was skipped", id) } else { io_err_with_help!( remove_dir_all(EpochInfo::with_id(&id).save_folder()), @@ -313,19 +310,9 @@ impl EpochConfig { /// Compute the next epoch. /// - /// Currently this function is a placeholder that creates a new epoch - /// with the ID immediately following the current one. The actual logic - /// is deferred to the `EpochInfo -> World` subsystem. + /// Clone the current world into its next time step. pub fn compute_next(&mut self) -> Result { - // unimplemented!(); - // Iter on events, increment time - // Iter on character, increment time - // - // create a new_towns_values vector, update it with base stats, then all events modifying underlying value - // create_new_character_base_v vector, do the same - // calculate the temps values (via function) - // TODO(1): Implement this - warn!("DEBUG LINE: COMPUTING NEXT EPOCH"); + info!("Computing the epoch after {}", self.epoch_id); // Set base for new epoch let mut new_epoch = self.try_load_current()?.clone(); let _ = self.increment_time(&mut new_epoch); @@ -403,9 +390,7 @@ impl EpochConfig { new_epoch.create_subfolders()?; new_epoch.save_with_context("Saving new epoch", save_mode)?; - // Add the epoch to the list of epochs, not doing so will still have it added - // at the next iteration since the command always parse the files to determine it's state rater that the list - // not doing so would likely create errors if insert is used before another command + // Keep the in-memory index coherent for subsequent operations in this process. let new_id = new_epoch.epoch_id; self.list_existing_epochs.insert(new_id, Some(new_epoch)); self.epoch_id = new_id; diff --git a/lib_efo/src/epoch/epoch_info.rs b/lib_efo/src/epoch/epoch_info.rs index ce48a66..ca99933 100644 --- a/lib_efo/src/epoch/epoch_info.rs +++ b/lib_efo/src/epoch/epoch_info.rs @@ -2,9 +2,8 @@ //! //! The `EpochInfo` struct holds all information that the engine needs to //! reconstruct a particular epoch. -//! It is persisted to `epoch//.epochinfo`. The file contains the epoch ID, the RNG -//! seed that produced the world, any optional tags, and a human-readable -//! summary. World data itself is stored separately (e.g. in `world.json`). +//! It is persisted to `epoch//epochinfo.json`. The file contains the +//! epoch ID, RNG seed, tags, summary, and the complete entity collections. use cli_table::Table; use derive_more::Display; @@ -25,10 +24,8 @@ use crate::{ /// The metadata file stored inside each epoch directory /// (`epoch//.epochinfo`). /// -/// It contains only the information that is needed for the engine to -/// reconstruct the state *of that particular epoch* (seed, selected -/// events, parent link, etc.). The full world data will be kept in -/// separate storage (e.g. `world.json`) but is for stored here. +/// It contains the information needed to reconstruct that epoch, including the +/// complete world entity collections. #[derive(Debug, Clone, Serialize, Deserialize, Display, Table)] #[display( "Epoch ({epoch_id:>5}) | seed ({rng_seed:<10}) | tags ({tags:<10}) | summary ({summary:<20})" @@ -252,7 +249,7 @@ impl EpochInfo { } } /// Find an entity from an Uuid - // TODO: Siplify this with the better iterator + // TODO: Simplify this by sharing a single all-entity iterator. pub fn find_entity_strict_as_mut( &mut self, id: Uuid, @@ -284,8 +281,7 @@ impl EpochInfo { /// Returns a slice over the entities of the requested type from the given `EpochInfo`. /// /// The function matches the supplied `e_type` to the appropriate collection - /// inside `epoch_info`. For unimplemented entity types the call will panic - /// because of the `todo!()` placeholder. + /// inside `epoch_info`. The internal-only player type is not stored yet. pub fn vec_entities(&self, e_type: &EntityType) -> &Vec { match e_type { EntityType::Character => &self.characters, @@ -324,7 +320,7 @@ impl EpochInfo { /// `EpochInfo`. /// /// Like `vec_entities`, this function selects the appropriate collection - /// based on `e_type`. Unimplemented variants will panic due to the `todo!()`. + /// based on `e_type`. The internal-only player type is not stored yet. pub fn vec_entities_mut(&mut self, e_type: &EntityType) -> &mut Vec { match e_type { EntityType::Character => &mut self.characters, diff --git a/lib_efo/src/error.rs b/lib_efo/src/error.rs index 686c51e..921827a 100644 --- a/lib_efo/src/error.rs +++ b/lib_efo/src/error.rs @@ -88,7 +88,7 @@ pub enum EpochError { /// Name of the file causing problem name: String, /// Trick used to have a cute line showing the following error message - #[label("This file is present and forbid the command to execute properly")] + #[label("This file prevents the command from executing safely")] show_label: Option<(usize, usize)>, }, @@ -105,7 +105,7 @@ pub enum EpochError { id: EpochId, /// The path of the epoch path: PathBuf, - /// An optionnal help message + /// An optional help message #[help] help: Option, /// The source error @@ -131,15 +131,15 @@ pub enum EpochError { ))] EpochFolderMissing(EpochId, PathBuf), - /// A future epoch exists, forbidding you to compute `next` and overriding them. + /// A future epoch exists, so computing `next` would overwrite history. #[diagnostic(help("Use epoch reset if you want to erase all future epochs first"))] #[error("Cannot compute `next` because future epoch exists")] #[diagnostic(code(EpochError::FutureEpochExist))] FutureEpochExist, - /// A specific epoch exists, forbidding the further execution of the command. + /// A specific epoch already exists, preventing the requested operation. #[diagnostic(help("Use epoch reset or manually delete the epoch {0}"))] - #[error("The epoch {0} exists forbidding the execution of the command")] + #[error("Epoch {0} already exists, so the operation was not performed")] #[diagnostic(code(EpochError::EpochAlreadyExists))] EpochAlreadyExists(EpochId), @@ -170,7 +170,7 @@ pub enum EpochError { /// The source error #[source] source: std::io::Error, - /// An optionnal help message + /// An optional help message #[help] help: Option, /// Where the error originated from @@ -216,7 +216,7 @@ pub enum EpochError { #[diagnostic(code(EpochError::Unknown))] Unknown(String), - /// The user tried to parse an acronim that doen't match any stats known to the system. + /// The user supplied an acronym that does not match a known statistic. #[error("Unknown stat acronym: {0}")] #[diagnostic(code(EpochError::UnknownStatAcronim))] UnknownStatAcronim(String), @@ -234,8 +234,8 @@ pub enum EpochError { ))] UnsupportedStat(String), - /// User error, meant to be very explicit over what happened and what to do. - #[error("An user facing error")] + /// User error with explicit guidance about what happened and what to do. + #[error("A user-facing error occurred")] #[diagnostic(code(EpochError::UserError))] UserError(#[help] UserErrors), @@ -246,7 +246,7 @@ pub enum EpochError { /// The root cause originating the error cause: String, #[help] - /// Optionnal help + /// Optional help help: Option, }, diff --git a/lib_efo/src/stats/implementations.rs b/lib_efo/src/stats/implementations.rs index a1f3f7a..919e6ae 100644 --- a/lib_efo/src/stats/implementations.rs +++ b/lib_efo/src/stats/implementations.rs @@ -1,4 +1,4 @@ -//! All traits implementatition for the main structs are deffered here +//! Trait implementations for the primary statistics structures. #![allow(dead_code)] use crate::stats::{GameStat, GenericStat, ListStats, OverallStats}; @@ -113,11 +113,15 @@ impl OverallStats { ListStats::Industry => &self.industry, ListStats::Science => &self.science, ListStats::Trade => &self.trade, - ListStats::Social => unimplemented!("This version doens't implement this stat"), //&self.social, - ListStats::Culture => unimplemented!("This version doens't implement this stat"), //&self.culture, - ListStats::Education => unimplemented!("This version doens't implement this stat"), //&self.education, - ListStats::Tourism => unimplemented!("This version doens't implement this stat"), //&self.tourism, - ListStats::Influence => unimplemented!("This version doens't implement this stat"), //&self.influence, + ListStats::Social => unimplemented!("this release does not store the social stat"), + ListStats::Culture => unimplemented!("this release does not store the culture stat"), + ListStats::Education => { + unimplemented!("this release does not store the education stat") + } + ListStats::Tourism => unimplemented!("this release does not store the tourism stat"), + ListStats::Influence => { + unimplemented!("this release does not store the influence stat") + } ListStats::Military => &self.military, ListStats::Army => &self.army, ListStats::Strength => &self.strength, @@ -157,11 +161,15 @@ impl OverallStats { ListStats::Industry => &mut self.industry, ListStats::Science => &mut self.science, ListStats::Trade => &mut self.trade, - ListStats::Social => unimplemented!("This version doens't implement this stat"), //&mut self.social, - ListStats::Culture => unimplemented!("This version doens't implement this stat"), //&mut self.culture, - ListStats::Education => unimplemented!("This version doens't implement this stat"), //&mut self.education, - ListStats::Tourism => unimplemented!("This version doens't implement this stat"), //&mut self.tourism, - ListStats::Influence => unimplemented!("This version doens't implement this stat"), //&mut self.influence, + ListStats::Social => unimplemented!("this release does not store the social stat"), + ListStats::Culture => unimplemented!("this release does not store the culture stat"), + ListStats::Education => { + unimplemented!("this release does not store the education stat") + } + ListStats::Tourism => unimplemented!("this release does not store the tourism stat"), + ListStats::Influence => { + unimplemented!("this release does not store the influence stat") + } ListStats::Military => &mut self.military, ListStats::Army => &mut self.army, ListStats::Strength => &mut self.strength,