docs: complete trustworthy foundation milestone

This commit is contained in:
Dandaedre 2026-09-20 21:02:27 +02:00
parent 8609816990
commit 3e18ddb870
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
10 changed files with 64 additions and 69 deletions

View File

@ -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.

View File

@ -210,7 +210,7 @@ pub struct CommonArgs {
pub faction: Option<stats::FactionId>,
#[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<EntityIdentifier>,
#[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<EntityIdentifier>,
/// 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

View File

@ -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,

View File

@ -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 {

View File

@ -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

View File

@ -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<EntityIdentifier>) -> bool {
match entity_identifier {
Some(EntityIdentifier::Name(name)) => {

View File

@ -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<Self, EpochError> {
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<EpochInfo, EpochError> {
// 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;

View File

@ -2,9 +2,8 @@
//!
//! The `EpochInfo` struct holds all information that the engine needs to
//! reconstruct a particular epoch.
//! It is persisted to `epoch/<epoch_id>/.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/<epoch_id>/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/<epoch_id>/.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<Entity> {
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<Entity> {
match e_type {
EntityType::Character => &mut self.characters,

View File

@ -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<String>,
/// 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<String>,
/// 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<String>,
},

View File

@ -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,