split validation tests and fix readme

Author: feored

README.md

@@ -1,33 +1,37 @@
 # Halbu
 
-A Rust library for reading and modifying Diablo II: Resurrected `.d2s` save files.
+A Rust library for parsing, editing, and safely re-encoding Diablo II: Resurrected `.d2s` save files.
 
-This library serves as the backend for **[Halbu Editor](https://github.com/feored/halbu-editor)**.
+It serves as the backend for **[Halbu Editor](https://github.com/feored/halbu-editor)**.
 
 ---
 
 ## Features
 
+
 - Parse and modify `.d2s` save files
-- Supports both D2R Legacy and RotW save format versions (v99/v105)
-- Edit:
+- Supports D2R Legacy and RotW formats (`v99`, `v105`)
+- Editable sections:
   - character data
   - attributes
   - skills
   - quests
   - waypoints
-  - mercenary information
+  - mercenary data
+- Partial parsing via summary API
 - Strict or tolerant parsing modes
-- Optional validation reports to ensure the game loads the save
+- Validation for post-edit sanity checks
+- Compatibility checks for format conversion
+
 
 ## Limitations
 
-Some sections of the save format are not yet modeled:
+Some parts of the save format are not yet modeled:
 
 - Items
 - NPC section
 
-These sections are stored as raw bytes. The library preserves them when writing, but exact round-tripping is not guaranteed.
+These sections are preserved as raw bytes when possible, but may not round-trip identically after modifications.
 
 
 ## Installation
@@ -36,10 +40,10 @@ These sections are stored as raw bytes. The library preserves them when writing,
 cargo add halbu
 ```
 
-## Quick start
 
-More examples can be found in `examples/`.
+## Basic usage
 
+Parse, modify, and write a save:
 
 ```rust
 use halbu::{CompatibilityChecks, Save, Strictness};
@@ -49,176 +53,143 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     let parsed = Save::parse(&bytes, Strictness::Strict)?;
     let mut save = parsed.save;
-    let target_format = save.format();
 
     save.character.name = "Halbu".to_string();
     save.skills.set_all(20);
 
-    std::fs::write(
-        "Halbu.d2s",
-        save.encode_for(target_format, CompatibilityChecks::Enforce)?,
-    )?;
+    let encoded = save.encode_for(save.format(), CompatibilityChecks::Enforce)?;
+    std::fs::write("Halbu.d2s", encoded)?;
 
     Ok(())
 }
 ```
 
-If you want tolerant parsing with diagnostics:
+
+## Parsing modes
+
+Strict parsing fails on inconsistencies:
 
 ```rust
-use halbu::{Save, Strictness};
+let parsed = Save::parse(&bytes, Strictness::Strict)?;
+```
+
+Lax parsing continues and reports issues:
 
+```rust
 let parsed = Save::parse(&bytes, Strictness::Lax)?;
 if !parsed.issues.is_empty() {
     eprintln!("Parse issues: {:?}", parsed.issues);
 }
 ```
 
 
-Typed attribute access:
-
-```rust
-use halbu::attributes::AttributeId;
-
-let strength = save.attributes.stat(AttributeId::Strength).value;
-let experience = save.attributes.stat(AttributeId::Experience).value;
-```
-
-## Fast summary
+## Validation
 
-Use the summary API for file lists and quick metadata reads without a full parse:
+Validation is an optional step to check the save for inconsistencies that may prevent the game from loading the save (e.g. invalid character name or mercenary level).
 
 ```rust
-use halbu::{Save, Strictness};
-
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let bytes = std::fs::read("Hero.d2s")?;
-    let summary = Save::summarize(&bytes, Strictness::Lax)?;
-
-    println!(
-        "name={:?} class={:?} level={:?} expansion={:?}",
-        summary.name, summary.class, summary.level, summary.expansion_type
-    );
-
-    Ok(())
+let report = save.validate();
+if !report.is_valid() {
+    eprintln!("Validation issues: {:?}", report.issues);
 }
 ```
 
 
-## Compatibility and forced encode
+## Compatibility and encoding
 
-Use compatibility checks before conversion.  
-They only apply when you are encoding to a target format.  
-`encode_for(..., CompatibilityChecks::Enforce)` blocks on incompatible conversions.  
-`encode_for(..., CompatibilityChecks::Ignore)` bypasses those checks and should only be used intentionally.
+Compatibility checks apply when converting between formats during encoding.
 
 ```rust
 use halbu::{CompatibilityChecks, Save, Strictness};
 use halbu::format::FormatId;
 
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let bytes = std::fs::read("Hero.d2s")?;
-    let parsed = Save::parse(&bytes, Strictness::Strict)?;
-    let save = parsed.save;
+let parsed = Save::parse(&bytes, Strictness::Strict)?;
+let save = parsed.save;
 
-    let target = FormatId::V99;
-    let issues = save.check_compatibility(target);
-    if !issues.is_empty() {
-        eprintln!("Compatibility issues: {issues:?}");
-    }
+let target = FormatId::V99;
+let issues = save.check_compatibility(target);
 
-    let forced = save.encode_for(target, CompatibilityChecks::Ignore)?;
-    std::fs::write("Hero.d2s", forced)?;
-
-    Ok(())
+if !issues.is_empty() {
+    eprintln!("Compatibility issues: {issues:?}");
 }
-```
 
-## Validation
+// Safe (blocks on incompatibility)
+let encoded = save.encode_for(target, CompatibilityChecks::Enforce)?;
 
-Use validation when you want a quick sanity check after editing a save.
+// Unsafe (bypasses checks)
+let forced = save.encode_for(target, CompatibilityChecks::Ignore)?;
+```
 
-`save.validate()` reports issues in the current save model.  
-Validation is separate from encoding.
 
-```rust
-use halbu::Save;
-
-let report = save.validate();
-if !report.is_valid() {
-    eprintln!("Validation issues: {:?}", report.issues);
-}
-```
+## Summary API
 
-If you prefer the free function:
+Read metadata without fully parsing the file:
 
 ```rust
-use halbu::validate_save;
-
-let report = validate_save(&save);
+let summary = Save::summarize(&bytes, Strictness::Lax)?;
+
+println!(
+    "name={:?} class={:?} level={:?} expansion={:?}",
+    summary.name,
+    summary.class,
+    summary.level,
+    summary.expansion_type
+);
 ```
 
-## Edition guess
+## Edition detection
 
-If a file has an unknown/unsupported version, you can still ask Halbu for a best-effort
-game edition hint (`D2RLegacy` vs `RotW`).
-The hint compares v99/v105 layout coherence (character decode + attributes/skills/items headers)
-and uses reserved markers as a tie-breaker.
+For unknown versions, Halbu can try to guess which edition the save layout matches most closely:
 
 ```rust
 use halbu::format::detect_edition_hint;
 use halbu::GameEdition;
 
 let hint = detect_edition_hint(&bytes);
+
 if hint == Some(GameEdition::RotW) {
-    // likely RotW edition (v105-family layout)
+    // likely RotW (v105-style layout)
 }
 ```
 
 
-## Documentation
-
-API documentation is available on docs.rs:
+## Model overview
 
-https://docs.rs/halbu
+Halbu distinguishes between three related concepts:
 
-Project history and release notes are in [CHANGELOG.md](CHANGELOG.md).
- 
-## Notes
+- `FormatId` — concrete file format (`V99`, `V105`, or unknown)
+- `GameEdition` — edition family (`D2RLegacy`, `RotW`)
+- `ExpansionType` — in-game expansion mode (`Classic`, `Expansion`, `RotW`)
 
+Typical usage:
 
-Halbu models three related concepts:
+- `save.format()` → file format
+- `save.game_edition()` → edition family
+- `save.expansion_type()` → in-game expansion
 
-- `FormatId`: concrete file format version/layout (`V99`, `V105`, or `Unknown(version)`)
-- `GameEdition`: edition family (`D2RLegacy` or `RotW`), derived from known `FormatId` values
-- `ExpansionType`: `Classic`, `Expansion`, or `RotW` (canonical on `Save` as `save.expansion_type()`)
 
-Known layout versions mapped by this crate:
+## Compatibility rules (examples)
 
-- `v99` -> `D2RLegacy`
-- `v105` -> `RotW`
+- Warlock requires RotW edition and expansion
+- RotW expansion cannot be encoded to non-RotW formats
+- Druid/Assassin cannot be encoded as Classic
+- Unknown class IDs cannot be safely converted
 
-Use `save.expansion_type()` / `save.set_expansion_type(...)` to read/write expansion mode.
-Use `save.game_edition()` to inspect the edition family.
-Use `save.character.status()` to inspect status bits, and `save.character.set_hardcore(...)` / `set_ladder(...)` / `set_died(...)` for status mutations.
-Use `save.validate()` when you want to check the current save state without writing it.
 
-Current blocking rules (compatibility checks) include:
-- Warlock requires RotW edition and RotW expansion type.
-- RotW expansion type cannot be encoded to non-RotW editions.
-- Druid/Assassin cannot be encoded as Classic.
-- Unknown class ids cannot be safely converted to known target formats.
+## Notes
 
-Level is stored in both the character section and the attributes section. Use `save.set_level(...)` to keep them in sync.
+- Level is stored in multiple sections; use `save.set_level(...)` to keep it consistent
+- Additional reverse-engineering notes are available in `NOTES.md`
 
-Additional notes about the format, quest flags, and general reverse-engineering work can be found in `NOTES.md`.
 
-This repository also contains several example .d2s files used in tests to verify that parsing and round-trip encoding work correctly.
+## Documentation
 
+API docs: https://docs.rs/halbu  
+Changelog: [CHANGELOG.md](CHANGELOG.md)
 
 ## References
 
-These resources have helped me understand the .d2s format. Many thanks to their authors.
+These resources helped me understand the .d2s format. Many thanks to their authors.
 
 * http://user.xmission.com/~trevin/DiabloIIv1.09_File_Format.shtml
 * https://github.com/dschu012/D2SLib
@@ -228,4 +199,4 @@ These resources have helped me understand the .d2s format. Many thanks to their
 * https://github.com/krisives/d2s-format
 * https://github.com/nokka/d2s/
 * https://github.com/ThePhrozenKeep/D2MOO
-* https://d2mods.info/forum/kb/index?c=4
+* https://d2mods.info/forum/kb/index?c=4