@booklib/skills 1.3.2 → 1.4.0

package/skills/rust-in-action/references/practices-catalog.md

@@ -0,0 +1,346 @@
+# Rust in Action — Practices Catalog
+
+Systems-focused before/after examples from each chapter group.
+
+---
+
+## Ownership: Use References, Not Moves (Ch 4)
+
+**Before:**
+```rust
+fn print_log(data: Vec<u8>) {  // consumes — caller loses data
+    println!("{} bytes", data.len());
+}
+let log = vec![1u8, 2, 3];
+print_log(log);
+// log is gone — can't use it again
+```
+**After:**
+```rust
+fn print_log(data: &[u8]) {  // borrows a slice — Vec<u8> derefs to &[u8]
+    println!("{} bytes", data.len());
+}
+let log = vec![1u8, 2, 3];
+print_log(&log);
+println!("{log:?}");  // still valid
+```
+
+---
+
+## Ownership: Resolving Lifetime Issues (Ch 4)
+
+**Before:**
+```rust
+struct Config {
+    name: String,  // owned — always heap-allocates
+}
+```
+**After (borrow when caller controls data):**
+```rust
+struct Config<'a> {
+    name: &'a str,  // borrows — zero allocation if caller has the string
+}
+// Use when Config doesn't outlive the string it references
+```
+**Or (own when Config must be independent):**
+```rust
+struct Config {
+    name: String,  // owned — correct when Config outlives the source string
+}
+```
+
+---
+
+## Smart Pointers: Choosing the Right Type (Ch 6)
+
+```rust
+// Box<T>: heap allocation, single owner
+let boxed: Box<[u8]> = vec![1, 2, 3].into_boxed_slice();
+
+// Rc<T>: shared ownership, single thread only
+use std::rc::Rc;
+let shared = Rc::new(vec![1, 2, 3]);
+let clone1 = Rc::clone(&shared);  // cheap — increments refcount
+// let _ = thread::spawn(move || { clone1; });  // COMPILE ERROR: Rc is not Send
+
+// Arc<T>: shared ownership, multi-thread safe
+use std::sync::Arc;
+let arc = Arc::new(vec![1, 2, 3]);
+let arc2 = Arc::clone(&arc);  // idiomatic — explicit about cheapness
+thread::spawn(move || println!("{arc2:?}")).join().unwrap();
+
+// RefCell<T>: interior mutability, single thread, runtime checks
+use std::cell::RefCell;
+let cache: RefCell<Option<String>> = RefCell::new(None);
+*cache.borrow_mut() = Some("computed".into());
+
+// Cow<T>: clone-on-write — avoids allocation when only reading
+use std::borrow::Cow;
+fn process(input: &str) -> Cow<str> {
+    if input.contains("bad") {
+        Cow::Owned(input.replace("bad", "good"))  // allocates only when needed
+    } else {
+        Cow::Borrowed(input)  // zero allocation
+    }
+}
+```
+
+---
+
+## Data: Explicit Endianness (Ch 5, 7)
+
+**Before:**
+```rust
+fn parse_id(bytes: &[u8]) -> u32 {
+    u32::from_ne_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])  // native — wrong on BE hosts
+}
+fn write_id(id: u32) -> [u8; 4] {
+    id.to_ne_bytes()  // corrupts protocol on big-endian
+}
+```
+**After:**
+```rust
+// Protocol says: little-endian. Be explicit regardless of host.
+fn parse_id(bytes: &[u8], offset: usize) -> Result<u32, &'static str> {
+    bytes.get(offset..offset + 4)
+        .ok_or("buffer too short")
+        .map(|b| u32::from_le_bytes(b.try_into().unwrap()))
+}
+
+fn write_id(id: u32) -> [u8; 4] {
+    id.to_le_bytes()  // always little-endian — deterministic on all hosts
+}
+```
+
+---
+
+## Data: Bit Manipulation (Ch 5)
+
+```rust
+// Named constants for masks — self-documenting (Ch 5)
+const SIGN_BIT: u32      = 0x8000_0000;
+const EXPONENT_MASK: u32 = 0x7F80_0000;
+const MANTISSA_MASK: u32 = 0x007F_FFFF;
+
+fn dissect_f32(n: f32) -> (u32, u32, u32) {
+    let bits = n.to_bits();
+    let sign     = (bits & SIGN_BIT) >> 31;
+    let exponent = (bits & EXPONENT_MASK) >> 23;
+    let mantissa =  bits & MANTISSA_MASK;
+    (sign, exponent, mantissa)
+}
+```
+
+---
+
+## Files: Buffered I/O + serde (Ch 7)
+
+**Before:**
+```rust
+use std::fs::File;
+use std::io::Read;
+let mut f = File::open("data.bin").unwrap();
+let mut buf = vec![];
+f.read_to_end(&mut buf).unwrap();  // unbuffered + panics
+```
+**After:**
+```rust
+use std::fs::File;
+use std::io::{BufReader, Read};
+use std::path::Path;
+
+fn read_file(path: &Path) -> Result<Vec<u8>, std::io::Error> {
+    let f = File::open(path)?;
+    let mut reader = BufReader::new(f);  // batched syscalls
+    let mut buf = Vec::new();
+    reader.read_to_end(&mut buf)?;
+    Ok(buf)
+}
+
+// Structured serialization with serde + bincode (Ch 7)
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Record {
+    id: u64,
+    payload: Vec<u8>,
+}
+
+fn write_record(rec: &Record, path: &Path) -> Result<(), Box<dyn std::error::Error>> {
+    let f = File::create(path)?;
+    let writer = std::io::BufWriter::new(f);
+    bincode::serialize_into(writer, rec)?;
+    Ok(())
+}
+```
+
+---
+
+## Error Handling: Library Error Wrapping (Ch 8)
+
+```rust
+// Wrapping multiple downstream error types in one domain error (Ch 8)
+#[derive(Debug)]
+pub enum NetworkError {
+    Io(std::io::Error),
+    AddrParse(std::net::AddrParseError),
+    Timeout,
+}
+
+impl std::fmt::Display for NetworkError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            NetworkError::Io(e) => write!(f, "I/O: {e}"),
+            NetworkError::AddrParse(e) => write!(f, "address parse: {e}"),
+            NetworkError::Timeout => write!(f, "connection timed out"),
+        }
+    }
+}
+
+impl std::error::Error for NetworkError {}
+
+impl From<std::io::Error> for NetworkError {
+    fn from(e: std::io::Error) -> Self { NetworkError::Io(e) }
+}
+impl From<std::net::AddrParseError> for NetworkError {
+    fn from(e: std::net::AddrParseError) -> Self { NetworkError::AddrParse(e) }
+}
+
+fn connect(addr: &str) -> Result<std::net::TcpStream, NetworkError> {
+    let addr: std::net::SocketAddr = addr.parse()?;  // AddrParseError → NetworkError
+    let stream = std::net::TcpStream::connect(addr)?;  // io::Error → NetworkError
+    Ok(stream)
+}
+```
+
+---
+
+## Networking: State Machines with Enums (Ch 8)
+
+```rust
+#[derive(Debug, Clone, PartialEq)]
+enum TcpState {
+    Closed,
+    Listen,
+    SynReceived,
+    Established,
+    FinWait1,
+    Closed_,
+}
+
+impl TcpState {
+    fn on_syn(self) -> Result<Self, &'static str> {
+        match self {
+            TcpState::Listen => Ok(TcpState::SynReceived),
+            other => Err("SYN received in invalid state"),
+        }
+    }
+
+    fn on_ack(self) -> Result<Self, &'static str> {
+        match self {
+            TcpState::SynReceived => Ok(TcpState::Established),
+            other => Err("ACK received in invalid state"),
+        }
+    }
+}
+```
+
+---
+
+## Concurrency: Thread Pool via Channels (Ch 10)
+
+```rust
+use std::sync::{Arc, Mutex, mpsc};
+use std::thread;
+
+// move closure required — captures must be 'static (Ch 10)
+fn spawn_worker(id: usize, rx: Arc<Mutex<mpsc::Receiver<String>>>) {
+    thread::spawn(move || loop {  // move transfers rx into thread
+        let msg = rx.lock().expect("mutex poisoned").recv();
+        match msg {
+            Ok(s) => println!("worker {id}: {s}"),
+            Err(_) => break,
+        }
+    });
+}
+
+fn main() {
+    let (tx, rx) = mpsc::channel::<String>();
+    let rx = Arc::new(Mutex::new(rx));
+
+    for i in 0..4 {
+        spawn_worker(i, Arc::clone(&rx));
+    }
+
+    tx.send("hello".into()).unwrap();
+    tx.send("world".into()).unwrap();
+    drop(tx);  // close channel — workers will exit their loops
+    thread::sleep(std::time::Duration::from_millis(10));
+}
+```
+
+---
+
+## Time: Instant vs SystemTime + NTP Offset (Ch 9)
+
+```rust
+use std::time::{Instant, SystemTime, UNIX_EPOCH};
+
+// Instant for elapsed — monotonic, cannot go backwards (Ch 9)
+let start = Instant::now();
+do_work();
+println!("elapsed: {:?}", start.elapsed());
+
+// SystemTime for wall clock (can go backwards — don't use for elapsed)
+let unix_ts = SystemTime::now()
+    .duration_since(UNIX_EPOCH)
+    .expect("system clock before Unix epoch")
+    .as_secs();
+
+// NTP epoch conversion (Ch 9)
+// NTP counts from 1900-01-01; Unix counts from 1970-01-01
+const NTP_UNIX_OFFSET: u64 = 2_208_988_800;
+
+fn ntp_to_unix(ntp_seconds: u64) -> u64 {
+    ntp_seconds.saturating_sub(NTP_UNIX_OFFSET)
+}
+
+fn unix_to_ntp(unix_seconds: u64) -> u64 {
+    unix_seconds + NTP_UNIX_OFFSET
+}
+```
+
+---
+
+## Unsafe: Safe Abstraction Pattern (Ch 6)
+
+```rust
+// Wrap unsafe in a safe API — callers need not use unsafe (Ch 6)
+pub struct AlignedBuffer {
+    ptr: *mut u8,
+    len: usize,
+}
+
+impl AlignedBuffer {
+    pub fn new(len: usize) -> Self {
+        // SAFETY: len > 0, alignment is a power of 2, ptr checked for null
+        let layout = std::alloc::Layout::from_size_align(len, 64).unwrap();
+        let ptr = unsafe { std::alloc::alloc_zeroed(layout) };
+        assert!(!ptr.is_null(), "allocation failed");
+        AlignedBuffer { ptr, len }
+    }
+
+    pub fn as_slice(&self) -> &[u8] {
+        // SAFETY: ptr valid, len accurate, no mutable alias exists
+        unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
+    }
+}
+
+impl Drop for AlignedBuffer {
+    fn drop(&mut self) {
+        // SAFETY: same layout as alloc, ptr not yet freed
+        let layout = std::alloc::Layout::from_size_align(self.len, 64).unwrap();
+        unsafe { std::alloc::dealloc(self.ptr, layout) }
+    }
+}
+```

package/skills/rust-in-action/scripts/review.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+review.py — Pre-analysis script for Rust in Action reviews.
+Usage: python review.py <file.rs>
+
+Scans a Rust source file for systems-programming anti-patterns from the book:
+endianness issues, unsafe shared state, missing buffered I/O, unwrap misuse,
+unbounded thread spawning, and incorrect smart pointer choices.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+CHECKS = [
+    (
+        r"from_ne_bytes|to_ne_bytes",
+        "Ch 5/7: Native endianness",
+        "use from_le_bytes/to_le_bytes or from_be_bytes/to_be_bytes to match the protocol spec",
+    ),
+    (
+        r"static\s+mut\s+\w+",
+        "Ch 6/10: static mut",
+        "data race risk — replace with Arc<Mutex<T>> or std::sync::atomic",
+    ),
+    (
+        r"\.unwrap\(\)",
+        "Ch 3: .unwrap()",
+        "panics on failure — use ?, .expect(\"reason\"), or match in production paths",
+    ),
+    (
+        r"unsafe\s*\{",
+        "Ch 6: unsafe block",
+        "ensure a safe abstraction wraps this; add a // SAFETY: comment explaining invariants",
+    ),
+    (
+        r"File::open|File::create",
+        "Ch 7: Unbuffered file I/O",
+        "wrap in BufReader::new()/BufWriter::new() to batch syscalls",
+    ),
+    (
+        r"thread::spawn",
+        "Ch 10: thread::spawn",
+        "if inside a loop, consider a thread pool (channel + Arc<Mutex<Receiver>>) instead of one thread per task",
+    ),
+    (
+        r"\bRc\s*::\s*(new|clone)\b",
+        "Ch 6: Rc usage",
+        "Rc is not Send — if shared across threads, replace with Arc",
+    ),
+    (
+        r"Box::new\(Vec\b|Box::new\(vec!",
+        "Ch 6: Box<Vec<T>>",
+        "Vec already heap-allocates — Box<Vec<T>> is double-indirection with no benefit; return Vec directly",
+    ),
+    (
+        r"\bexpect\s*\(\s*\)",
+        "Ch 3: .expect() with empty string",
+        "add a meaningful reason: .expect(\"what invariant was violated\")",
+    ),
+]
+
+
+def scan(source: str) -> list[dict]:
+    findings = []
+    lines = source.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if stripped.startswith("//"):
+            continue  # skip comments
+        for pattern, label, advice in CHECKS:
+            if re.search(pattern, line):
+                findings.append({
+                    "line": lineno,
+                    "text": line.rstrip(),
+                    "label": label,
+                    "advice": advice,
+                })
+    return findings
+
+
+def group_by_label(findings: list[dict]) -> dict:
+    groups: dict[str, list] = {}
+    for f in findings:
+        groups.setdefault(f["label"], []).append(f)
+    return groups
+
+
+def sep(char="-", width=70) -> str:
+    return char * width
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python review.py <file.rs>")
+        sys.exit(1)
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+
+    if path.suffix.lower() != ".rs":
+        print(f"Warning: expected a .rs file, got '{path.suffix}' — continuing anyway")
+
+    source = path.read_text(encoding="utf-8", errors="replace")
+    findings = scan(source)
+    groups = group_by_label(findings)
+
+    print(sep("="))
+    print("RUST IN ACTION — PRE-REVIEW REPORT")
+    print(sep("="))
+    print(f"File   : {path}")
+    print(f"Lines  : {len(source.splitlines())}")
+    print(f"Issues : {len(findings)} potential anti-patterns across {len(groups)} categories")
+    print()
+
+    if not findings:
+        print("  [OK] No common anti-patterns detected.")
+        print()
+    else:
+        for label, items in groups.items():
+            print(sep())
+            print(f"  {label}  ({len(items)} occurrence{'s' if len(items) != 1 else ''})")
+            print(sep())
+            print(f"  Advice: {items[0]['advice']}")
+            print()
+            for item in items[:5]:  # cap display at 5 per category
+                print(f"  line {item['line']:>4}:  {item['text'][:100]}")
+            if len(items) > 5:
+                print(f"  ... and {len(items) - 5} more occurrence(s)")
+            print()
+
+    severity = (
+        "HIGH" if len(findings) >= 5
+        else "MEDIUM" if len(findings) >= 2
+        else "LOW" if findings
+        else "NONE"
+    )
+    print(sep("="))
+    print(f"SEVERITY: {severity}  |  Review chapters: Ch 3 (errors), Ch 5-7 (data/files), Ch 6 (pointers), Ch 10 (concurrency)")
+    print(sep("="))
+
+
+if __name__ == "__main__":
+    main()

package/skills/skill-router/SKILL.md

@@ -10,7 +10,7 @@ description: >
 
 # Skill Router
 
-You are a skill selector for the `@booklib/skills` library — a collection of 17 book-based AI skills covering code quality, architecture, language best practices, and design. Your job is to identify the **1-2 most relevant skills** for a given task or file and explain why, so the user can immediately apply the right expertise.
+You are a skill selector for the `@booklib/skills` library — a collection of 19 book-based AI skills covering code quality, architecture, language best practices, and design. Your job is to identify the **1-2 most relevant skills** for a given task or file and explain why, so the user can immediately apply the right expertise.
 
 ## When You're Triggered
 
@@ -41,7 +41,7 @@ Identify what the user is trying to do:
 
 From the file extension, imports, description, or code provided:
 
-- **Language signals:** `.py` → Python skills; `.java` → `effective-java` or `clean-code-reviewer`; `.kt` → `effective-kotlin` or `kotlin-in-action`; `.js`/`.ts` → `clean-code-reviewer` or `design-patterns`
+- **Language signals:** `.py` → Python skills; `.java` → `effective-java` or `clean-code-reviewer`; `.kt` → `effective-kotlin` or `kotlin-in-action`; `.ts`/`.tsx` → `effective-typescript`; `.rs` → `programming-with-rust`; `.js` → `clean-code-reviewer` or `design-patterns`
 - **Domain signals:** "microservice", "saga" → microservices-patterns; "bounded context", "aggregate" → domain-driven-design; "chart", "visualization" → storytelling-with-data; "UI", "layout", "typography" → refactoring-ui; "web scraping", "BeautifulSoup" → web-scraping-python; "asyncio", "coroutine" → using-asyncio-python; "data pipeline", "ETL" → data-pipelines; "replication", "partitioning", "database internals" → data-intensive-patterns
 - **Architecture signals:** "monolith decomposition", "distributed systems" → microservices-patterns or system-design-interview
 
@@ -57,17 +57,19 @@ Apply these primary routing rules:
 4. **Python best practices** → `effective-python`
 5. **Python asyncio/concurrency** → `using-asyncio-python` (overrides effective-python for async topics)
 6. **Python web scraping** → `web-scraping-python`
-7. **OO design patterns (GoF)** → `design-patterns`
-8. **Domain modeling, DDD** → `domain-driven-design`
-9. **Microservices, sagas, decomposition** → `microservices-patterns`
-10. **System scalability, estimation** → `system-design-interview`
-11. **Data storage internals, replication** → `data-intensive-patterns`
-12. **Data pipelines, ETL** → `data-pipelines`
-13. **UI design, visual hierarchy** → `refactoring-ui`
-14. **Charts, data visualization** → `storytelling-with-data`
-15. **Web animation** → `animation-at-work`
-16. **Startup strategy, MVP** → `lean-startup`
-17. **Routing help** → `skill-router` (this skill)
+7. **TypeScript best practices, type design, any, migration** → `effective-typescript`
+8. **Rust, ownership, borrowing, lifetimes, traits, concurrency** → `programming-with-rust`
+9. **OO design patterns (GoF)** → `design-patterns`
+10. **Domain modeling, DDD** → `domain-driven-design`
+11. **Microservices, sagas, decomposition** → `microservices-patterns`
+12. **System scalability, estimation** → `system-design-interview`
+13. **Data storage internals, replication** → `data-intensive-patterns`
+14. **Data pipelines, ETL** → `data-pipelines`
+15. **UI design, visual hierarchy** → `refactoring-ui`
+16. **Charts, data visualization** → `storytelling-with-data`
+17. **Web animation** → `animation-at-work`
+18. **Startup strategy, MVP** → `lean-startup`
+19. **Routing help** → `skill-router` (this skill)
 
 Read `references/routing-heuristics.md` for detailed decision rules and conflict resolution.
 
@@ -77,6 +79,7 @@ Some skill pairs can conflict. Resolve using these rules:
 
 | Conflict | Resolution |
 |----------|------------|
+| `effective-typescript` vs `clean-code-reviewer` | Use `effective-typescript` for TypeScript-specific concerns (type system, any, type design); use `clean-code-reviewer` for naming/functions/readability which applies cross-language |
 | `clean-code-reviewer` vs `effective-java` | Use `effective-java` for Java-specific idioms (generics, enums, builders); use `clean-code-reviewer` for naming/functions/readability which applies cross-language |
 | `effective-kotlin` vs `kotlin-in-action` | `effective-kotlin` for best practices and pitfall avoidance; `kotlin-in-action` for learning Kotlin language features |
 | `domain-driven-design` vs `microservices-patterns` | `domain-driven-design` for domain model design; `microservices-patterns` for service decomposition and inter-service communication. Apply both if designing a new microservice with rich domain model |

package/skills/skill-router/references/skill-catalog.md

@@ -1,6 +1,6 @@
 # Skill Catalog
 
-All 17 skills in the `@booklib/skills` library with routing metadata.
+All 19 skills in the `@booklib/skills` library with routing metadata.
 
 ## animation-at-work
 - **Source:** *Animation at Work* by Rachel Nabors
@@ -74,6 +74,24 @@ All 17 skills in the `@booklib/skills` library with routing metadata.
 - **Works well with:** kotlin-in-action (best practices + language features), clean-code-reviewer (Kotlin idioms + readability)
 - **Conflicts with:** kotlin-in-action (effective-kotlin for best practices; kotlin-in-action for language learning — if user knows Kotlin and wants advice, use effective-kotlin)
 
+## effective-typescript
+- **Source:** *Effective TypeScript* by Dan Vanderkam
+- **Domain:** TypeScript best practices, type system, type design, any, migration
+- **Language:** TypeScript only
+- **Trigger keywords:** "effective typescript", "typescript best practices", "type safety", "any type", "type assertions", "type design", "strict mode", "typescript review", "migrate to typescript", "unknown vs any", "type declarations", "tagged union", "branded types", "typescript item"
+- **Anti-triggers:** Non-TypeScript code, plain JavaScript without types, architecture concerns
+- **Works well with:** clean-code-reviewer (TypeScript idioms + readability), design-patterns (type-safe pattern implementations)
+- **Conflicts with:** clean-code-reviewer (effective-typescript wins for TypeScript-specific type system concerns; clean-code-reviewer for general readability)
+
+## programming-with-rust
+- **Source:** *Programming with Rust* by Donis Marshall
+- **Domain:** Rust language, ownership, borrowing, lifetimes, error handling, traits, concurrency
+- **Language:** Rust only
+- **Trigger keywords:** "rust", "ownership", "borrow checker", "lifetimes", "Result", "Option", "traits", "fearless concurrency", "cargo", "crate", "unwrap", "move semantics", "Arc", "Mutex", "pattern matching rust", ".rs"
+- **Anti-triggers:** Non-Rust code, architecture concerns, domain modeling
+- **Works well with:** clean-code-reviewer (Rust idioms + readability), design-patterns (Rust implementation of patterns)
+- **Conflicts with:** clean-code-reviewer (programming-with-rust wins for Rust-specific concerns like ownership, lifetimes, and the borrow checker)
+
 ## effective-python
 - **Source:** *Effective Python* (2nd Edition) by Brett Slatkin
 - **Domain:** Python best practices, Pythonic idioms