@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/rust/references/chapter_07.md

@@ -0,0 +1,226 @@
+# Chapter 7 - Type State Pattern
+
+Models state at compile time, preventing bugs by making illegal states unrepresentable. It takes advantage of the Rust generics and type system to create sub-types that can only be reached if a certain condition is achieved, making some operations illegal at compile time. 
+
+> Recently it became the standard design pattern of Rust programming. However, it is not exclusive to Rust, as it is achievable and has inspired other languages to do the same [swift](https://swiftology.io/articles/typestate/) and [typescript](https://catchts.com/type-state).
+
+## 7.1 What is Type State Pattern?
+
+**Type State Pattern** is a design pattern where you encode different **states** of the system as **types**, not as runtime flags or enums. This allows the compiler to enforce state transitions and prevent illegal actions at compile time. It also improves the developer experience, as developers only have access to certain functions based on the state of the type.
+
+> Invalid states become compile errors instead of runtime bugs.
+
+## 7.2 Why use it?
+
+* Avoids runtime checks for state validity. If you reach certain states, you can make certain assumptions of the data you have.
+* Models state transitions as type transitions. This is similar to a state machine, but in compile time.
+* Prevents data misuse, e.g. using uninitialized objects.
+* Improves API safety and correctness.
+* The phantom data field is removed after compilation so no extra memory is allocated.
+
+## 7.3 Simple Example: File State
+
+[Github Example](https://github.com/apollographql/rust-best-practices/tree/main/examples/simple-type-state)
+```rust
+use std::{io, path::{Path, PathBuf}};
+
+struct FileNotOpened;
+struct FileOpened;
+
+#[derive(Debug)]
+struct File<State> {
+    /// Path to the opened file
+    path: PathBuf,
+    /// Open `File` handler
+    handle: Option<std::fs::File>,
+    /// Type state manager
+    _state: std::marker::PhantomData<State>
+}
+
+impl File<FileNotOpened> {
+    /// `open` is the only entry point for this struct.
+    /// * When called with a valid path, it will return a `File<FileOpened>` with a valid `handler` and `path`
+    /// * `open` serves as an alternative to `new` and `defaults` methods (usable when your struct needs valid data to exist).
+    fn open(path: &Path) -> io::Result<File<FileOpened>> {
+        // If file is invalid, it will return `std::io::Error`
+        let file = std::fs::File::open(path)?;
+        Ok(
+            File {
+                path: path.to_path_buf(),
+                // Always valid
+                handle: Some(file),
+                _state: std::marker::PhantomData::<FileOpened>
+            }
+        )
+    }
+}
+
+impl File<FileOpened> {
+    /// Reads the content of the `File` as a `String`.
+    /// `read` can only be called by state `File<FileOpened>`
+    fn read(&mut self) -> io::Result<String> {
+        use io::Read;
+
+        let mut content = String::new();
+        let Some(handle)= self.handle.as_mut() else {
+            unreachable!("Safe to unwrap as state can only be reached when file is open");
+        };
+        handle.read_to_string(&mut content)?;
+        Ok(content)
+    }
+
+    /// Returns the valid path buffer.
+    fn path(&self) -> &PathBuf {
+        &self.path
+    }
+}
+```
+
+## 7.4 Real-World Examples
+
+### Builder Pattern with Compile-Time Guarantees
+
+> Forces the user to **set required fields** before calling `.build()`.
+
+[Github Example](https://github.com/apollographql/rust-best-practices/tree/main/examples/type-state-builder)
+
+A type-state pattern can have more than one associated states:
+
+```rust
+use std::marker::PhantomData;
+
+struct MissingName;
+struct NameSet;
+struct MissingAge;
+struct AgeSet;
+
+#[derive(Debug)]
+struct Person {
+    name: String,
+    age: u8,
+    email: Option<String>,
+}
+
+struct Builder<NameState, AgeState> {
+    name: Option<String>,
+    age: u8,
+    email: Option<String>,
+    _name_marker: PhantomData<NameState>,
+    _age_marker: PhantomData<AgeState>,
+}
+
+impl Builder<MissingName, MissingAge> {
+    fn new() -> Self {
+        Builder { name: None, age: 0, _name_marker: PhantomData, _age_marker: PhantomData, email: None }
+    }
+
+    fn name(self, name: String) -> Builder<NameSet, MissingAge> {
+        Builder { name: Some(name), _name_marker: PhantomData::<NameSet>, age: self.age, _age_marker: PhantomData, email: None }
+    }
+
+    fn age(self, age: u8) -> Builder<MissingName, AgeSet> {
+        Builder { age, _age_marker: PhantomData::<AgeSet>, name: None, _name_marker: PhantomData, email: None }
+    }
+}
+
+impl Builder<NameSet, MissingAge> {
+    fn age(self, age: u8) -> Builder<NameSet, AgeSet> {
+        Builder { age, _age_marker: PhantomData::<AgeSet>, name: self.name, _name_marker: PhantomData::<NameSet>, email: None }
+    }
+}
+
+impl Builder<MissingName, AgeSet> {
+    fn email(self, email: String) -> Self {
+        Self { name: self.name , age: self.age , email: Some(email) , _name_marker: self._name_marker , _age_marker: self._age_marker }
+    }
+
+    fn name(self, name: String) -> Builder<NameSet, AgeSet> {
+        Builder { name: Some(name), _name_marker: PhantomData::<NameSet>, age: self.age, _age_marker: PhantomData::<AgeSet>, email: self.email }
+    }
+}
+
+impl Builder<NameSet, AgeSet> {
+    fn build(self) -> Person {
+        Person { 
+            name: self.name.unwrap_or_else(|| unreachable!("Name is guarantee to be set")), 
+            age: self.age,
+            email: self.email,
+        }
+    }
+}
+```
+
+Although a bit more verbose than a usual builder, this guarantees that all necessary fields are present (note that e-mail is optional field only present in the final builder).
+
+#### Usage:
+```rust
+// ✅ Valid cases
+let person: Person = Builder::new().name("name".to_string()).age(30).build();
+let person: Person = Builder::new().age(30).name("name".to_string()).build();
+let person: Person = Builder::new().age(30).name("name".to_string()).email("myself@email.com".to_string()).build();
+
+// ❌ Invalid cases
+let person: Person = Builder::new().name("name".to_string()).build(); // ❌ Compile error: Age required to `build`
+let person: Person = Builder::new().age(30).build(); // ❌ Compile error: Name required to `build`
+let person: Person = Builder::new().age(30).email("myself@email.com".to_string()).build(); // ❌ Compile error: Name required to `build`
+let person: Person = Builder::new().build();// ❌ Compile error: Name and Age required to `build`
+```
+
+### Network Protocol State Machine
+
+Illegal transitions like sending a message before connecting **simply don't compile**:
+
+```rust
+// Mock example
+struct Disconnected;
+struct Connected;
+
+struct Client<State> {
+    stream: Option<std::net::TcpStream>,
+    _state: std::marker::PhantomData<State>
+}
+
+impl Client<Disconnected> {
+    fn connect(addr: &str) -> std::io::Result<Client<Connected>> {
+        let stream = std::net::TcpStream::connect(addr)?;
+        Ok(Client {
+            stream: Some(stream),
+            _state: std::marker::PhantomData::<Connected>
+        })
+    }
+}
+
+impl Client<Connected> {
+    fn send(&mut self, msg: &str) -> std::io::Result<()> {
+        use std::io::Write;
+        let Some(stream) = self.stream.as_mut() else {
+            unreachable!("Stream is guaranteed to be set in the `Connected` state");
+        };
+        stream.write_all(msg.as_bytes())
+    }
+}
+```
+
+## 7.5 Pros and Cons
+
+### ✅ Use Type-State Pattern When:
+* Your want **compile-time state safety**.
+* You need to enforce **API constraints**.
+* You are writing a library/crate that is heavy dependent on variants.
+* Your want to replace runtime booleans or enums with **type-safe code paths**.
+* You need compile time correctness.
+
+### ❌ Avoid it when:
+* Writing trivial states like enums.
+* Don't need type-safety.
+* When it leads to overcomplicated generics.
+* When runtime flexibility is required.
+
+### 🚨 Downsides and Cautions
+* Can lead to more **verbose solutions**.
+* Can lead to **complex type signatures**.
+* May require **unsafe** to return **variant outputs** based on different states.
+* May required a bunch of duplication (e.g. same struct field reused).
+* PhantomData is not intuitive for beginners and can feel a bit hacky.
+
+> Use this pattern when it **saves bugs, increases safety or simplifies logic**, not just for cleverness.

package/skills/rust/references/chapter_08.md

@@ -0,0 +1,257 @@
+# Chapter 8 - Comments vs Documentation
+
+> Clear code beats clear comments. However, when the why isn't obvious, comment it plainly - or link to where you can read more context.
+
+## 8.1 Comments vs Documentation: Know the Difference
+
+| Purpose | Use `// comment` | Use `/// doc` or `//! crate doc` |
+|-------------- |------------------------------------------- |---------------------------------------------------------------- |
+| Describe Why | ✅ Yes - explains tricky reasoning | ❌ Not for documentation |
+| Describe API | ❌ Not useful | ✅ Yes - public interfaces, usage, details, errors, panics |
+| Maintainable | 🚨 Often becomes obsolete and hard to reason | ✅ Tied to code, appears in generated docs and can run test cases |
+| Visibility | Local development only | Exported to users and tools like `cargo doc` |
+
+## 8.2 When to use comments
+
+Use `//` comments (double slashed) when something can't be expressed clearly in code, like:
+* **Safety Guarantees**, some of which can be better expressed with code conditionals.
+* Workarounds or **Optimizations**.
+* Legacy or **platform-specific** behaviors. Some of them can be expressed with `#[cfg(..)]`.
+* Links to **Design Docs** or **ADRs**.
+* Assumptions or **gotchas** that aren't obvious.
+
+> Name your comments! For example, a comment regarding a safety guarantee should start with `// SAFETY: ...`.
+
+### ✅ Good comment:
+```rust
+// SAFETY: `ptr` is guaranteed to be non-null and aligned by caller
+unsafe { std::ptr::copy_nonoverlapping(src, dst, len); }
+```
+
+### ✅ Design context comment:
+```rust
+// CONTEXT: Reuse root cert store across subgraphs to avoid duplicate OS calls:
+// [ADR-12](link/to/adr-12): TLS Performance on MacOS
+```
+
+## 8.3 When comments get in the way
+
+Avoid comments that:
+* Restate obvious things (`// increment i by 1 for the next loop`).
+* Can grow stale over time.
+* `TODO`s without actions (links to some versioned issue).
+* Could be replaced by better naming or smaller functions.
+
+### ❌ Bad comment:
+```rust
+fn compute(counter: &mut usize) {
+    // increment by 1
+    *counter += 1;
+}
+```
+
+### ❌ Too long or outdated
+```rust
+// Originally written in 2018 for some now-defunct platform
+```
+
+## 8.4 Don't Write Living Documentation (living comments)
+
+Comments as a "living documentation" is a **dangerous myth**, as comments are **not free**:
+* They **rot** - nobody compiles comments.
+* They **mislead** - readers usually assume they are true with no critique, e.g. "the other developer knows this code better than I do".
+* They **go stale** - unless maintained with the code, they become irrelevant.
+* They are **noisy** - comments can clutter your code with multiple unnecessary lines.
+
+If something deserves to live beyond a PR, put it in:
+* An **ADR** (Architectural Design Record).
+* A Design Document.
+* Document it **in code** by using types, doc comments, examples, renaming code blocks into cleaner functions.
+* Add tests to cover and explain the change.
+
+> ### 🚨 If you find a comment, **read it in context**. Does it still make sense? If not, remove or update it, or ask for help. Comments should bother you.
+
+## 8.5 Replace Comments with Code
+
+Instead of long commented blocks, break logic into named helper functions:
+
+#### ❌ Commented code block:
+```rust
+fn save_user(&self) -> Result<(), MyError> {
+    // check if the user is authenticated
+    if self.is_authenticated() {
+        // serialize user data
+        let data = serde_json::to_string(self)?;
+        // write to file
+        std::fs::write(self.path(), data)?;
+    }
+    Ok(())
+}
+```
+**✅ Extract for clarity**:
+
+```rust
+fn save_auth_user(&self) -> Result<PathBuf, MyError> {
+    if self.is_authenticated() {
+        let path = self.path();
+        let serialized_user = serde_json::to_string(self)?;
+        std::fs::write(&path, serialized_user)?; // borrow: `path` is returned below
+        Ok(path)
+    } else {
+        Err(MyError::UserNotAuthenticated)
+    }
+}
+```
+
+> ❗ Extract when the **name adds meaning** -- not to deduplicate a couple of similar-looking lines. See [Chapter 1, §1.8](./chapter_01.md#18-when-to-extract-a-function-and-when-not-to) for when duplication is the better trade-off.
+
+## 8.6 `TODO` should become issues
+
+Don't leave `// TODO:` scattered around the codebase with no owner. Instead:
+1. File Github Issue or Jira Ticket. (Prefer github issues on public repositories).
+2. Reference the issue in the code:
+
+```rust
+// TODO(issue #42): Remove workaround after bugfix
+```
+
+This makes `TODO`s trackable, actionable and visible to everyone.
+
+## 8.7 When to use doc comments
+
+Use `///` doc comments to document:
+* All **public functions, structs, traits, enums**.
+* Their purpose, their usage and their behaviors.
+* Anything developers need to understand how to use it correctly.
+* Add context that related to `Errors` and `Panics`.
+* Plenty of examples.
+
+### ✅ Good doc comment:
+
+```rust
+/// Loads [`User`] profile from disk
+/// 
+/// # Error
+/// - Returns [`MyError`] if the file is missing [`MyError::FileNotFound`].
+/// - Returns [`MyError`] if the content is an invalid Json, [`MyError::InvalidJson`].
+fn load_user(path: &Path) -> Result<User, MyError> {...}
+```
+
+**Doc comments can also include examples, links and even tests:**
+
+```rust
+/// Returns the square of the integer part of any number.
+/// Square is limited to `u128`.
+/// 
+/// # Examples
+/// 
+/// ```rust
+/// assert_eq!(square(4.3), 16)
+/// ```
+fn square(x: impl ToInt) -> u128 { ... }
+```
+
+## 8.8 Documentation in Rust: How, When and Why
+
+Rust provides **first-class documentation tooling** via rustdoc, which makes documenting your code a key part of writing idiomatic and maintainable rust. There are doc specific lints to help with documentation, like:
+
+| Lint | Description |
+|-------------- |------------------------------------------- |
+| [missing_docs](https://doc.rust-lang.org/rustdoc/lints.html#missing_docs) | Warns that a public functions, struct, const, enum has missing documentation |
+| [broken_intra_doc_links](https://doc.rust-lang.org/rustdoc/lints.html#broken_intra_doc_links) | Detects if an internal documentation link is broken. Specially useful when things are renamed. |
+| [empty_docs](https://rust-lang.github.io/rust-clippy/master/#empty_docs) | Disallow empty docs - preventing bypass of `missing_docs` |
+| [missing_panics_doc](https://rust-lang.github.io/rust-clippy/master/#missing_panics_doc) | Warns that documentation should have a `# Panics` section if function can panic |
+| [missing_errors_doc](https://rust-lang.github.io/rust-clippy/master/#missing_errors_doc) | Warns that documentation should have a `# Errors` section if function returns a `Result` explaining `Err` conditions |
+| [missing_safety_doc](https://rust-lang.github.io/rust-clippy/master/#missing_safety_doc) | Warns that documentation should have a `# Safety` section if public facing functions have visible unsafe blocks |
+
+
+### Difference between `///` and `//!`
+
+| Style | Used for | Scope |Example |
+|---------- |------------------------------ |------------------------------------------- |---------------------------------------------------------------- |
+| `///` | Line doc comment | Public items like struct, fn, enum, consts | Documenting, giving context and usage to `fn`, `struct`, `enum`, etc |
+| `//!` | Module level doc comment | Modules or entire crates | Explaining crate/module purpose with common use cases and quickstart |
+
+### `///` Item level documentation
+
+Use `///` for functions, structs, traits, enums, const, etc:
+
+```rust
+/// Adds two numbers together.
+///
+/// # Examples
+///
+/// ```
+/// let result = my_crate::add(2, 3);
+/// assert_eq!(result, 5);
+/// ```
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+```
+* ✅ Write clear and descriptive **What it does** and **how to use it**.
+* ✅ Use `# Examples` section to better explain **how to use it**.
+* ✅ Prefer writing examples that can be tested via `cargo test`, even if you have to hide their output with starting `#`:
+```rust
+/// ```
+/// let result = my_crate::add(2, 3);
+/// # assert_eq!(result, 5);
+/// ```
+```
+* ✅ Use `# Panics`, `# Errors` and `# Safety` sections when relevant.
+* Add relevant context to the type.
+
+### `//!` Module/Crate level Documentation
+
+Use `//!` when you want to document the **purpose of a module or a crate**. It is places at the top of a `lib.rs` or `mod.rs` file, for example `engine/mod.rs`:
+```rust
+//! This module implements a custom chess engine.
+//! 
+//! It handles board state, move generation and check detection.
+//! 
+//! # Example
+//! ```
+//! let board = chess::engine::Board::default();
+//! assert!(board.is_valid());
+//! ```
+```
+
+## 8.9 Checklist for Documentation coverage
+
+📦 Crate-Level (lib.rs)
+- [ ] `//!` doc at top explains **what the crate does**, and **what problems it solves**.
+- [ ] Includes crate-level `# Examples` or pointers to modules.
+
+📁 Modules (mod.rs or inline)
+- [ ] `//!` doc explains **what this module is for**, its **exports**, and **invariants**.
+- [ ] Avoid repeating doc comments on re-exported items unless clarification is needed.
+
+🧱 Structs, Enums, Traits
+- `///` doc explains:
+    - [ ] The role this type plays.
+    - [ ] Invariants or expectations.
+    - [ ] Example construction or usage.
+- [ ] Consider using [`#[non_exhaustive]`](https://doc.rust-lang.org/reference/attributes/type_system.html#the-non_exhaustive-attribute) if external users may match on it.
+
+🔧 Functions and Methods
+- `///` doc covers:
+    - [ ] What it does.
+    - [ ] Parameters and their meaning.
+    - [ ] Return value behavior.
+    - [ ] Edge cases (`# Panics`, `# Errors`).
+    - [ ] Usage example, `# Examples`.
+
+📑 Traits
+- [ ] Explain the **purpose** of the trait (marker? dynamic dispatch?).
+- [ ] Doc for each method — include **when/why** to implement it.
+- [ ] Document clearly default implemented methods and when to override.
+
+📦 Public Constants
+- [ ] Document what they configure and when you'd want to use them.
+
+### 📌 Best Practices
+* ✅ Use examples generously — they double as test cases.
+* ✅ Prefer clarity over formality — it's for humans, not machines.
+* ✅ Prefer doc comments to explain usage, and leave implementation details to code comments if needed.
+* ✅ Use `cargo doc --open` to check your output often.
+* ✅ Add `#![deny(missing_docs)]` and other relevant doc lints in top-level modules if you want to enforce full doc coverage.