docs: complete trustworthy foundation milestone
This commit is contained in:
parent
8609816990
commit
3e18ddb870
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)) => {
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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>,
|
||||
},
|
||||
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
Loading…
Reference in New Issue