@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/rust/references/chapter_01.md

@@ -0,0 +1,564 @@
+# Chapter 1 - Coding Styles and Idioms
+
+## 1.1 Borrowing Over Cloning
+
+Rust's ownership system encourages **borrow** (`&T`) instead of **cloning** (`T.clone()`). 
+> ❗ Performance recommendation
+
+### ✅ When to `Clone`:
+
+* You need to change the object AND preserve the original object (immutable snapshots).
+* When you have `Arc` or `Rc` pointers.
+* When data is shared across threads, usually `Arc`.
+* Avoid massive refactoring of non performance critical code.
+* When caching results (dummy example below):
+```rust
+fn get_config(&self) -> Config {
+    self.cached_config.clone()
+}
+```
+* When the underlying API expects Owned Data.
+
+### 🚨 `Clone` traps to avoid:
+
+* Auto-cloning inside loops `.map(|x| x.clone)`, prefer to call `.cloned()` or `.copied()` at the end of the iterator.
+* Cloning large data structures like `Vec<T>` or `HashMap<K, V>`.
+* Clone because of bad API design instead of adjusting lifetimes.
+* Prefer `&[T]` instead of `Vec<T>` or `&Vec<T>` - Clippy's [`ptr_arg`](https://rust-lang.github.io/rust-clippy/master/#ptr_arg) flags `&Vec<T>` parameters.
+* Prefer `&str` instead of `String` **and instead of `&String`**. `&String` is a pointer to a pointer that also rejects `&str` callers; take it only when you need a `String`-only method such as `.capacity()`.
+* Prefer `&T` instead of `T`.
+* Clone a reference argument, if you need ownership, make it explicit in the arguments for the caller. Example:
+```rust
+fn take_a_borrow(thing: &Thing) {
+    let thing_cloned = thing.clone(); // the caller should have passed ownership instead
+}
+```
+
+### ✅ Prefer borrowing:
+```rust
+fn process(name: &str) {
+    println!("Hello {name}");
+}
+
+let user = String::from("foo");
+process(&user);
+```
+
+### ❌ Avoid redundant cloning:
+```rust
+fn process_string(name: String) {
+    println!("Hello {name}");
+}
+
+let user = String::from("foo");
+process(user.clone()); // Unnecessary clone
+```
+
+## 1.2 When to pass by value? (Copy trait)
+
+Not all types should be passed by reference (`&T`). If a type is **small** and it is **cheap to copy**, it is often better to **pass it by value**. Rust makes it explicit via the `Copy` trait.
+
+### ✅ When to pass by value, `Copy`:
+* The type **implements** `Copy` (`u32`, `bool`, `f32`, small structs).
+* The cost of moving the value is negligible.
+
+```rust
+fn increment(x: u32) -> u32 {
+    x + 1
+}
+
+let num = 1;
+let new_num = increment(num); // `num` still usable after this point
+```
+
+### ❓ Which structs should be `Copy`?
+* When to consider declaring `Copy` on your own types:
+* All fields are `Copy` themselves.
+* The struct is `small`, up to 2 (maybe 3) words of memory or 24 bytes (each word is 64 bits/8bytes).
+* The struct **represents a "plain data object"**, without resourcing to ownership (no heap allocations. Example: `Vec` and `Strings`).
+* ❗**The type does not also implement `Iterator`.** Even if every field is `Copy`, never put `Copy` and `Iterator` on the same type (see [§1.5](#15-iterator-iter-vs-for)).
+
+❗**Rust Arrays are stack allocated.** Which means they can be copied if their underlying type is `Copy`, but this will be allocated in the program stack which can easily become a stack overflow. More on [Chapter 3 - Stack vs Heap](./chapter_03.md#33-stack-vs-heap-be-size-smart)
+
+For reference, each primitive type size in bytes:
+
+#### Integers:
+
+| Type | Size |
+|------------- |---------- |
+| i8 u8 | 1 byte |
+| i16 u16 | 2 bytes |
+| i32 u32 | 4 bytes |
+| i64 u64 | 8 bytes |
+| isize usize | Arch |
+| i128 u128 | 16 bytes |
+
+#### Floating Point:
+
+| Type | Size |
+|---------- |---------- |
+| f32 | 4 bytes |
+| f64 | 8 bytes |
+
+
+#### Other:
+
+| Type | Size |
+|---------- |---------- |
+| bool | 1 byte |
+| char | 4 bytes |
+
+
+### ✅ Good struct to derive `Copy`:
+```rust
+#[derive(Debug, Copy, Clone)]
+struct Point {
+    x: f32,
+    y: f32,
+    z: f32
+}
+```
+
+### ❌ Bad struct to derive `Copy`:
+```rust
+#[derive(Debug, Clone)]
+struct BadIdea {
+    age: i32,
+    name: String, // String is not `Copy`
+}
+```
+
+### ❓Which Enums should be `Copy`?
+* If your enum acts like tags and atoms.
+* The enum payloads are all `Copy`.
+* **❗Enums size are based on their largest element.**
+
+### ✅ Good Enum to derive
+```rust
+#[derive(Debug, Copy, Clone)]
+enum Direction {
+    North,
+    South,
+    East,
+    West,
+}
+```
+
+## 1.3 Handling `Option<T>` and `Result<T, E>`
+Rust 1.65 introduced a better way to safely unpack Option and Result types with the `let Some(x) = … else { … }` or `let Ok(x) = … else { … }` when you have a default `return` value, `continue` or `break` default else case. It allows early returns when the missing case is **expected and normal**, not exceptional.
+
+### ✅ Cases to use each pattern matching for Option and Return
+* Use `match` when you want to pattern match against the inner types `T` and `E`
+```rust
+match self {
+    Ok(Direction::South) => { … },
+    Ok(Direction::North) => { … },
+    Ok(Direction::East) => { … },
+    Ok(Direction::West) => { … },
+    Err(E::One) => { … },
+    Err(E::Two) => { … },
+}
+
+match self {
+    Some(3|5) => { … }
+    Some(x) if x > 10 => { … }
+    Some(x) => { … }
+    None => { … }
+}
+```
+
+* Use `match` when your type is transformed into something more complex Like `Result<T, E>` becoming `Result<Option<T>, E>`.
+```rust
+match self {
+    Ok(t) => Ok(Some(t)),
+    Err(E::Empty) => Ok(None),
+    Err(err) => Err(err),
+}
+```
+
+* Use `let PATTERN = EXPRESSION else { DIVERGING_CODE; }` when the divergent code doesn't need to know about the failed pattern matches or doesn't need extra computation:
+```rust
+let Some(&Direction::North) = self.direction.as_ref() else {
+    return Err(DirectionNotAvailable(self.direction));
+}; // `let ... else` is a statement: the `;` is required
+```
+
+* Use `let PATTERN = EXPRESSION else { DIVERGING_CODE; }` when you want to break or continue a pattern match
+```rust
+for x in self {
+    let Some(x) = x else {
+        continue;
+    };
+}
+```
+
+* Use `if let PATTERN = EXPRESSION else { DIVERGING_CODE; }` when `DIVERGING_CODE` needs extra computation:
+```rust
+if let Some(x) = self.next() {
+    // computation
+} else {
+    // computation when `None/Err` or not matched
+}
+```
+
+❗**If you don't care about the value of the `Err` case, please use `?` to propagate the `Err` to the caller.**
+
+### ❌ Bad Option/Return pattern matching:
+
+* Conversion between Result and Option (prefer `.ok()`,`.ok_or()`, and `ok_or_else()`)
+```rust
+match self {
+    Ok(t) => Some(t),
+    Err(_) => None
+}
+```
+
+* `if let PATTERN = EXPRESSION else { DIVERGING_CODE; }` when divergent code is a default or pre-computed value (prefer `let PATTERN = EXPRESSION else { DIVERGING_CODE; }`):
+```rust
+if let Some(values) = self.next() {
+    // computation
+    (Some(..), values)
+} else {
+    (None, Vec::new())
+}
+```
+
+* Using `unwrap` or `expect` outside tests:
+```rust
+let port = config.port.unwrap();
+```
+
+## 1.4 Prevent Early Allocation
+
+When dealing with functions like `or`, `map_or`, `unwrap_or`, `ok_or`, consider that they have special cases for when memory allocation is required, like creating a new string, creating a collection or even calling functions that manage some state, so they can be replaced with their `_else` counter-part:
+
+### ✅ Good cases
+
+```rust
+let x = None;
+assert_eq!(x.ok_or(ParseError::ValueAbsent), Err(ParseError::ValueAbsent));
+
+let x = None;
+assert_eq!(x.ok_or_else(|| ParseError::ValueAbsent(format!("this is a value {x}"))), Err(ParseError::ValueAbsent));
+
+
+let x: Result<_, &str> = Ok("foo");
+assert_eq!(x.map_or(42, |v| v.len()), 3);
+
+
+let x : Result<_, String> = Ok("foo");
+assert_eq!(x.map_or_else(|e|format!("Error: {e}"), |v| v.len()), 3);
+
+let x = "1,2,3,4";
+assert_eq!(x.parse_to_option_vec.unwrap_or_else(Vec::new), Ok(vec![1, 2, 3, 4]));
+```
+
+### ❌ Bad cases
+
+```rust
+let x : Result<_, String> = Ok("foo");
+assert_eq!(x.map_or(format!("Error with uninformed content"), |v| v.len()), 3);
+
+let x = "1,2,3,4";
+assert_eq!(x.parse_to_option_vec.unwrap_or(Vec::new()), Ok(vec![1, 2, 3, 4])); // could be replaced with `.unwrap_or_default`
+
+let x = None;
+assert_eq!(x.ok_or(ParseError::ValueAbsent(format!("this is a value {x}"))), Err(ParseError::ValueAbsent));
+```
+
+### Mapping Err
+
+When dealing with Result::Err, sometimes is necessary to log and transform the Err into a more abstract or more detailed error, this can be done with `inspect_err` and `map_err`:
+
+```rust
+let x = Err(ParseError::InvalidContent(...));
+
+x
+    .inspect_err(|err| tracing::error!("function_name: {err}"))
+    .map_err(|err| GeneralError::from(("function_name", err)))?;
+```
+
+## 1.5 Iterator, `.iter` vs `for`
+
+First we need to understand a basic loop with each one of them. Let's consider the following problem, we need to sum all even numbers between 0 and 10 incremented by 1:
+
+* `for`:
+```rust
+let mut sum = 0;
+for x in 0..=10 {
+    if x % 2 == 0 {
+        sum += x + 1;
+    }
+}
+```
+
+* `iter`:
+```rust
+let sum: i32 = (0..=10)
+    .filter(|x| x % 2 == 0)
+    .map(|x| x + 1)
+    .sum();
+```
+
+> Both versions do the same thing and are correct and idiomatic, but each shines in different contexts.
+
+### When to prefer `for` loops
+* When you need **early exits** (`break`, `continue`, `return`).
+* **Simple iteration** with side-effects (e.g., logging, IO)
+    * logging can be done correctly in `Iterators` using `inspect` and `inspect_err` functions.
+* When readability matters more than simplicity or chaining.
+
+#### Example:
+```rust
+for value in &mut value {
+    if *value == 0 {
+        break;
+    }
+    *value += fancy_equation();
+}
+```
+
+### When to prefer `iterators` loops (`.iter()` and `.into_iter()`)
+* When you are `transforming collections` or `Option/Results`.
+* You can **compose multiple steps** elegantly.
+* No need for early exits.
+* You need support for indexed values with `.enumerate`.
+```rust
+let values: Vec<_> = vec.into_iter()
+    .enumerate()
+    .filter(|(_index, value)| value % 2 == 0)
+    .map(|(index, value)| value % index)
+    .collect()
+```
+* You need to use collections functions like `.windows` or `chunks`.
+* You need to combine data from multiple sources and don't want to allocate multiple collections.
+* Iterators can be combined with `for` loops:
+```rust
+for value in vec.iter().enumerate()
+    .filter(|(index, value)| value % index == 0) {
+    // ...
+}
+```
+
+> #### ❗REMEMBER: Iterators are Lazy
+>
+> * `.iter`, `.map`, `.filter` don't do anything until you call its consumer, e.g. `.collect`, `.sum`, `.for_each`.
+> * **Lazy Evaluation** means that iterator chains are fused into one loop at compile time.
+
+### 🚨 Anti-patterns to AVOID
+
+* Don't chain without formatting. Prefer each chained function on its own line with the correct indentation (`rustfmt` should take care of this).
+* Don't chain if it makes the code unreadable.
+* Avoid needlessly collect/allocate of a collection (e.g. vector) just to throw it away later by some larger operation or by another iteration.
+* Prefer `iter` over `into_iter` unless you don't need the ownership of the collection.
+* Prefer `iter` over `into_iter` for collections that inner type implements `Copy`, e.g. `Vec<i32>`.
+* **Never implement (or derive) both `Copy` and `Iterator` on the same type.** Copying an iterator and advancing one copy leaves the other untouched, which silently yields wrong results -- it is a well-known footgun. The standard library hit exactly this: it is why `Range` historically could not be `Copy`, and why the new `core::range` types (stabilized in Rust 1.96) implement `IntoIterator` instead of `Iterator` so they *can* be `Copy`. If you need an iterator on a `Copy` type, implement `IntoIterator` and return a separate iterator struct.
+* For summing numbers prefer `.sum` over `.fold`. `.sum` is specialized for summing values, so the compiler knows it can make optimizations on that front, while fold has a blackbox closure that needs to be applied at every step. If you need to sum by an initial value, just added in the expression `let my_sum = [1, 2, 3].sum() + 3`.
+
+## 1.6 Comments: Context, not Clutter
+
+> "Context is for why, not what or how"
+
+Well-written Rust code, with expressive types and good naming, often speaks for itself. Many high-quality codebases thrive on **few or no comments** - and that is a good thing. Where code alone isn't enough (performance quirks, external constraints, non-obvious tradeoffs), a concise comment prevents hours of head-scratching.
+
+The idiom that belongs in *this* chapter is the structural one: **when a comment wants to narrate a function, split the function instead**. For everything else about comments - what makes one good or bad, `SAFETY:`/`CONTEXT:` prefixes, why "living documentation" in comments is a myth, and turning `TODO`s into issues - see [Chapter 8](./chapter_08.md), which owns that topic end to end.
+
+### ✅ Breaking up long functions over commenting them
+
+If you find yourself writing a long comment explaining "what", "how" or "each step" in a function, it might be time to split it. So the suggestion is to refactor. This can be beneficial not only for readability, but testability:
+
+#### ❌ Instead of:
+```rust
+fn process_request(request: T) {
+    // We first need to validate request, because of corner case x, y, z
+    // As the payload can only be decoded when they are valid
+    // Then we can perform authorization on the payload
+    // lastly with the authorized payload we can dispatch to handler
+}
+```
+
+#### ✅ Prefer
+```rust
+fn process_request(request: T) -> Result<(), Error> {
+    validate_request_headers(&request)?;
+    let payload = decode_payload(&request);
+    authorize(&payload)?;
+    dispatch_to_handler(payload)
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn validate_request_happy_path() { ... }
+
+    #[test]
+    fn validate_request_fails_on_x() { ... }
+
+    #[test]
+    fn validate_request_fails_on_y() { ... }
+
+    #[test]
+    fn decode_validated_request() { ... }
+
+    #[test]
+    fn authorize_payload_xyz() { ... }
+}
+```
+
+Let **structure** and **naming** replace commentary, and enhance its documentation with **tests as living documentation**.
+
+> ❗ Splitting is about **naming and clarity**, not deduplication. Before extracting a helper to remove *duplicated* lines, check [§1.8](#18-when-to-extract-a-function-and-when-not-to).
+
+> Doc-comments and doc-testing, `///` and `//!`, are covered in [Chapter 8 - Comments vs Documentation](./chapter_08.md).
+
+## 1.7 Use Declarations - "imports"
+
+Different languages have different ways of sorting their imports, in the Rust ecosystem the [standard way](https://github.com/rust-lang/rustfmt/issues/4107) is:
+
+- `std` (`core`, `alloc` would also fit here).
+- External crates (what is in your Cargo.toml `[dependencies]`).
+- Workspace crates (workspace member crates).
+- This module `super::`.
+- This module `crate::`.
+
+```rust
+// std
+use std::sync::Arc;
+
+// external crates
+use chrono::Utc;
+use juniper::{FieldError, FieldResult};
+use uuid::Uuid;
+
+// crate code lives in workspace
+use broker::database::PooledConnection;
+
+// super:: / crate::
+use super::schema::{Context, Payload};
+use super::update::convert_publish_payload;
+use crate::models::Event;
+```
+
+Some enterprise solutions opt to include their core packages after `std`, so all external packages that start with enterprise name are located before the others:
+
+```rust
+// std
+use std::sync::Arc;
+
+// enterprise external crates
+use enterprise_crate_name::some_module::SomeThing;
+
+// external crates
+use chrono::Utc;
+use juniper::{FieldError, FieldResult};
+use uuid::Uuid;
+
+// crate code lives in workspace
+use broker::database::PooledConnection;
+
+// super:: / crate::
+use super::schema::{Context, Payload};
+use super::update::convert_publish_payload;
+use crate::models::Event;
+```
+
+One way of not having to manually control this is using the following arguments in your `rustfmt.toml`:
+
+```toml
+reorder_imports = true
+imports_granularity = "Crate"
+group_imports = "StdExternalCrate"
+```
+
+> ❗ `group_imports` and `imports_granularity` are **nightly-only** rustfmt options - still unstable as of 1.96. On stable they are ignored with the warning *"can't set `group_imports = StdExternalCrate`, unstable features are only available in nightly channel"*, so the grouping only applies when you run `cargo +nightly fmt`.
+
+## 1.8 When to Extract a Function (and When Not To)
+
+This chapter ([§1.6](#-breaking-up-long-functions-over-commenting-them)) and [Chapter 8](./chapter_08.md#85-replace-comments-with-code) recommend splitting long functions and replacing narrative comments with named helpers. That advice is about **naming and clarity** -- it is *not* a license to hunt down every repeated line. Extraction has a cost: every helper adds indirection, and a **wrong abstraction is much harder to remove than a little duplication**.
+
+> "Duplication is far cheaper than the wrong abstraction." -- [Sandi Metz, The Wrong Abstraction](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction)
+
+### 📏 The Rule of Three
+
+From [Martin Fowler's *Refactoring*](https://martinfowler.com/books/refactoring.html), attributed to Don Roberts:
+
+> The first time you do something, you just do it. The second time you do something similar, you wince at the duplication, but you do the duplicate thing anyway. The third time you do something similar, you refactor.
+
+Two occurrences of a couple of lines are usually **fine**. Wait for the third before reaching for a helper -- by then you will know what the abstraction actually *is*, instead of guessing at it.
+
+### 🧠 DRY is about knowledge, not text
+
+[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) (*The Pragmatic Programmer*) says every piece of **knowledge** should have a single representation. It does **not** say "no two code fragments may look alike". Two blocks that *happen* to look the same today, but represent **different decisions**, will evolve in different directions. Forcing them into one helper couples code that should be free to diverge -- this is **coincidental duplication**, and deduplicating it is how wrong abstractions are born.
+
+### 🧪 Examples
+
+How these principles play out in code:
+
+#### ✅ Coincidental duplication -- leave it inline:
+```rust
+// Similar-looking lines, but the `.env` and `.toml` formats are
+// unrelated decisions that will evolve independently:
+writeln!(env_file, "{key}={value}")?;
+// ... elsewhere ...
+writeln!(toml_file, "{key} = \"{value}\"")?;
+```
+
+#### ❌ Deduplicating it forces a flag parameter -- the classic smell:
+```rust
+// One helper, two behaviors, and a `bool` to pick between them:
+fn write_entry(out: &mut impl Write, key: &str, value: &str, quoted: bool) -> io::Result<()> {
+    if quoted {
+        writeln!(out, "{key} = \"{value}\"")
+    } else {
+        writeln!(out, "{key}={value}")
+    }
+}
+```
+
+Every new variant will grow another parameter or branch. And the `bool` is a smell in its own right: `write_entry(out, key, value, true)` tells the reader nothing at the call site -- Martin Fowler calls this a [Flag Argument](https://martinfowler.com/bliki/FlagArgument.html). When a mode selector is genuinely warranted, a two-variant enum (`Quoting::Quoted`) keeps call sites readable, and Clippy's [`fn_params_excessive_bools`](https://rust-lang.github.io/rust-clippy/master/index.html#fn_params_excessive_bools) lints against accumulating them. No enum rescues *this* design, though: its variants would exist only to encode the callers' differences.
+
+#### ✅ Shared knowledge -- extract it:
+```rust
+// The definition of "retryable" is ONE business decision used in many
+// places. If it changes, it must change everywhere at once:
+fn is_retryable(status: StatusCode) -> bool {
+    status == StatusCode::TOO_MANY_REQUESTS || status.is_server_error()
+}
+```
+
+### 🔧 Unwinding a wrong abstraction
+
+If you find yourself maintaining an abstraction like `write_entry`, [Sandi Metz's advice](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction) is to **unwind it, not patch it**:
+
+1. **Re-inline** the helper's body into every caller, substituting each call site's concrete arguments.
+2. **Reduce** each call site -- with the parameters now literal, dead branches and unused generality fall away.
+3. **Reevaluate** what the callers *actually* share, now that every one of them is explicit.
+4. **Reconstruct** one or more abstractions from what remains -- or none, if the sharing turns out to be coincidental.
+
+> 🤖 Doing this by hand is tedious, which is why wrong abstractions survive on sunk cost. For an AI coding agent, unwinding is fast, mechanical work -- ask for it explicitly instead of letting the agent keep patching a helper that fights back.
+
+### ✅ Extract a function when:
+* The logic appears in **3+ places** *and* represents the **same decision** (Rule of Three).
+* The name **adds meaning** the code alone does not (`is_retryable`, `authorize`) -- rather than restating it (`add_one_to_counter`).
+* It produces a **unit worth testing** in isolation (see [§1.6](#-breaking-up-long-functions-over-commenting-them)).
+* It hides genuine complexity behind a **small, honest signature** -- few parameters, no flags.
+
+### ❌ Don't extract when:
+* It is **1-2 lines used in fewer than 3 places** -- the helper is pure indirection.
+* The call sites are only *almost* identical, and unifying them requires **flag parameters** or extra branches.
+* The only motivation is **line count**. A single-caller helper pays off when its *name* clarifies intent ([§1.6](#-breaking-up-long-functions-over-commenting-them), [§8.5](./chapter_08.md#85-replace-comments-with-code)) -- not when it merely relocates code.
+* You are **guessing** at a future abstraction. Wait for the third usage to reveal its real shape.
+
+### 🧫 Test code: readability beats DRY
+
+In tests, be **even more tolerant of duplication**. The Google Testing Blog calls this [DAMP -- "Descriptive And Meaningful Phrases"](https://testing.googleblog.com/2019/12/testing-on-toilet-tests-too-dry-make.html) ([*Software Engineering at Google*, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html)): each test should read as a **self-contained story** -- setup, action, assertion -- without the reader chasing helpers to reconstruct what actually happened.
+
+* **Tests have no tests.** Logic moved into a shared helper (loops, branches, clever parametrization) is itself untested -- a bug there silently weakens every test built on it.
+* **A failing test should be diagnosable on sight.** The reader is usually debugging a broken build; make the expected behavior visible in the test body, not three helpers away.
+* **Shared test helpers couple unrelated tests.** Change one behavior and dozens of tests fail at once -- for the helper's sake, not the behavior's.
+
+Where to draw the line:
+* ✅ Share **setup and fixtures** -- a shared setup function or `rstest` cases, as [Chapter 5](./chapter_05.md#51-tests-as-living-documentation) recommends. Constructing a test server twice is boilerplate, not knowledge.
+* ❌ Keep each test's **action and assertion inline**, even when they look repetitive across tests.
+
+> 🚨 When in doubt, **prefer duplication**. A duplicated line is trivially fixed later; a wrong abstraction accretes parameters and conditionals, because each maintainer keeps patching it instead of undoing it.

package/skills/rust/references/chapter_02.md

@@ -0,0 +1,117 @@
+# Chapter 2 - Clippy and Linting Discipline
+
+Be sure to have `cargo clippy` installed with your rust compiler, run `cargo clippy -V` in your terminal for a rust project and you should get a line like `clippy 0.1.xx (<hash> <date>)`, whose minor version tracks your `rustc`. If terminal fails to show a clippy version, please run the following code `rustup update && rustup component add clippy`.
+
+Clippy documentation can be found [here](https://doc.rust-lang.org/clippy/usage.html).
+
+## 2.1 Why care about linting?
+
+Rust compiler is a powerful tool that catches many mistakes. However, some more in-depth analysis require extra tools, that is where `cargo clippy` clippy comes into to play. Clippy checks for:
+* Performance pitfalls.
+* Style issues.
+* Redundant code.
+* Potential bugs.
+* Non-idiomatic Rust.
+
+## 2.2 Always run `cargo clippy`
+
+Add the following to your daily workflow:
+
+```shell
+$ cargo clippy --all-targets --all-features --locked -- -D warnings
+```
+
+* `--all-targets`: checks library, tests, benches and examples.
+* `--all-features`: checks code for all features enabled, auto solves conflicting features.
+* `--locked`: Requires `Cargo.lock` to be up-to-date, can be solved with `$ cargo update`.
+* `-D warnings`: treats warnings as errors
+
+Potential additions elements to add:
+
+* `-- -W clippy::pedantic`: lints which are rather strict or have occasional false positives.
+* `-- -W clippy::nursery`: Optionally can be added to check for new lints that are still under development.
+* ❗ Add this to your Makefile, Justfile, xtask or CI Pipeline.
+
+> Example at ApolloGraphQL
+>
+> In the `Router` project there is a `xtask` configured for linting that can be executed with `cargo xtask lint`. 
+
+## 2.3 Important Clippy Lints to Respect
+
+| Lint Name | Why | Link |
+| --------- | ----| -----|
+| `redundant_clone` | Detects unnecessary `clones`, has performance impact | [link (nursery + perf)](https://rust-lang.github.io/rust-clippy/master/#redundant_clone) |
+| `needless_borrow` group | Removes redundant `&` borrowing | [link (style)](https://rust-lang.github.io/rust-clippy/master/#needless_borrow) |
+| `map_unwrap_or` / `map_or` | Simplifies nested `Option/Result` handling | [`map_unwrap_or`](https://rust-lang.github.io/rust-clippy/master/#map_unwrap_or) [`unnecessary_map_or`](https://rust-lang.github.io/rust-clippy/master/#unnecessary_map_or) [`unnecessary_result_map_or_else`](https://rust-lang.github.io/rust-clippy/master/#unnecessary_result_map_or_else) |
+| `manual_ok_or` | Suggest using `.ok_or_else` instead of `match` | [link (style)](https://rust-lang.github.io/rust-clippy/master/#manual_ok_or) |
+| `large_enum_variant` | Warns if an enum has very large variant which is bad for memory. Suggests `Boxing` it | [link (perf)](https://rust-lang.github.io/rust-clippy/master/#large_enum_variant) |
+| `unnecessary_wraps` | If your function always returns `Some` or `Ok`, you don't need `Option`/`Result` | [link (pedantic)](https://rust-lang.github.io/rust-clippy/master/#unnecessary_wraps) |
+| `clone_on_copy` | Catches accidental `.clone()` on `Copy` types like `u32` and `bool` | [link (complexity)](https://rust-lang.github.io/rust-clippy/master/#clone_on_copy) |
+| `needless_collect` | Prevents collecting and allocating an iterator, when allocation is not needed | [link (nursery)](https://rust-lang.github.io/rust-clippy/master/#needless_collect) |
+
+## 2.4 Fix warnings, don't silence them!
+
+**NEVER** just `#[allow(clippy::lint_something)]` unless:
+
+* You **truly understand** why the warning happens and you have a reason why it is better that way.
+* You **document** why it is being ignored.
+* ❗ Don't use `allow`, but `expect`, it will give a warning in case the lint is not true anymore, `#[expect(clippy::lint_something)]`.
+
+### Example:
+
+```rust
+// Faster matching is preferred over size efficiency
+#[expect(clippy::large_enum_variant)]
+enum Message {
+    Code(u8),
+    Content([u8; 1024]),
+}
+```
+
+> The fix would be:
+> 
+> ```rust
+> // Faster matching is preferred over size efficiency
+> #[expect(clippy::large_enum_variant)]
+> enum Message {
+>     Code(u8),
+>     Content(Box<[u8; 1024]>),
+> }
+> ```
+
+### Handling false positives
+
+Sometimes Clippy complains even when your code is correct, in those cases there are two solutions:
+1. Try to refactor the code, so it improves the warning.
+2. **Locally** override the lint with `#[expect(clippy::lint_name)]` and a comment with the reason.
+3. Avoid global overrides, unless it is core crate issue, a good example of this is the Bevy Engine that has a set of lints that should be allowed by default.
+
+## 2.5 Configure workspace/package lints
+
+In your `Cargo.toml` file it is possible to determine which lints and their priorities over each other. In case of 2 or more conflicting lints, the higher priority one will be chosen. Example configuration for a package:
+
+```toml
+[lints.rust]
+future-incompatible = "warn"
+nonstandard_style = "deny"
+
+[lints.clippy]
+all = { level = "deny", priority = 10 }
+redundant_clone = { level = "deny", priority = 9 }
+manual_while_let_some = { level = "deny", priority = 4 }
+pedantic = { level = "warn", priority = 3 }
+```
+
+And for a workspace:
+
+```toml
+[workspace.lints.rust]
+future-incompatible = "warn"
+nonstandard_style = "deny"
+
+[workspace.lints.clippy]
+all = { level = "deny", priority = 10 }
+redundant_clone = { level = "deny", priority = 9 }
+manual_while_let_some = { level = "deny", priority = 4 }
+pedantic = { level = "warn", priority = 3 }
+```