@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/lit-code/references/rust-ub/ub-taxonomy.md

@@ -0,0 +1,269 @@
+# Rust Undefined Behavior Taxonomy
+
+Every category of UB the Rust compiler, Miri, and the language specification recognize. The agent must know the full surface to hunt systematically. Each entry names the UB class, its root cause, canonical trigger, Miri detection status, and the canonical fix.
+
+## 1. Aliasing Violations (Stacked Borrows / Tree Borrows)
+
+**Root cause:** Two pointers access the same memory in ways that violate Rust's borrowing model — even through raw pointers inside `unsafe`.
+
+**Canonical triggers:**
+- Creating a `&mut T` while another `&T` or `&mut T` to the same location exists.
+- Dereferencing a raw pointer derived from a reference after that reference was invalidated (e.g., `&mut` was retaken).
+- Calling `slice::from_raw_parts_mut` on overlapping regions.
+- Interior mutability through `UnsafeCell` without going through the `UnsafeCell` API.
+- Casting `&T` to `*mut T` and writing through it (even via FFI).
+
+**Miri detection:** YES — Stacked Borrows is the default model. Tree Borrows (`-Zmiri-tree-borrows`) is the newer, more permissive model. Run both:
+```bash
+cargo +nightly miri test                          # Stacked Borrows (stricter)
+MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test  # Tree Borrows (relaxed)
+```
+If code passes Tree Borrows but fails Stacked Borrows, it is *likely* sound but *possibly* relying on unspecified behavior. Fix it anyway — Stacked Borrows is the conservative bet.
+
+**Fix pattern:** Use `UnsafeCell` for all interior mutability. Never cast `&T` to `*mut T`. Derive mutable pointers from `*mut T` obtained via `UnsafeCell::get()` or `addr_of_mut!()`.
+
+---
+
+## 2. Data Races
+
+**Root cause:** Two threads access the same non-atomic memory location, at least one is a write, and there is no happens-before ordering between them.
+
+**Canonical triggers:**
+- `unsafe impl Send for T` on a type containing `*mut U` without synchronization.
+- `unsafe impl Sync for T` on a type containing `Cell<T>` or `UnsafeCell<T>` without a lock.
+- Using `std::ptr::write` from multiple threads to the same allocation.
+- Shared `&T` where `T` has interior mutability but no atomic/lock guard.
+
+**Miri detection:** YES — Miri's data-race detector is on by default. It detects races on non-atomic accesses. For **preemptive scheduling** stress, use:
+```bash
+MIRIFLAGS="-Zmiri-preemption-rate=0.1" cargo +nightly miri test
+```
+
+**Complementary tools:** `loom` for exhaustive interleaving exploration on lock-free algorithms. ThreadSanitizer (TSAN) for integration tests Miri cannot run (I/O, FFI).
+
+**Fix pattern:** Wrap in `Mutex`/`RwLock`/`AtomicXxx`. Never `unsafe impl Sync` unless you can name the synchronization primitive guarding every mutable field.
+
+---
+
+## 3. Use After Free / Dangling Pointers
+
+**Root cause:** A pointer or reference outlives the allocation it points to.
+
+**Canonical triggers:**
+- Returning a reference to a local variable (compiler catches most, but raw pointers escape).
+- `Box::into_raw` → manual `Box::from_raw` with wrong lifetime.
+- `Vec` reallocation invalidating raw pointers obtained from `as_ptr()` / `as_mut_ptr()`.
+- `Pin<Box<T>>` unpinned and moved after self-referential pointers were set up.
+
+**Miri detection:** YES — allocation tracking catches use-after-free on the exact operation.
+
+**Fix pattern:** Borrow checker for references. For raw pointers: tie pointer validity to an explicit lifetime via a `PhantomData<&'a T>` in the wrapper, or use arena allocation (`bumpalo`) so all pointers share one lifetime.
+
+---
+
+## 4. Uninitialized Memory
+
+**Root cause:** Reading a value from memory that was never written to.
+
+**Canonical triggers:**
+- `MaybeUninit::assume_init()` before all bytes are written.
+- `mem::uninitialized()` (deprecated, still compiles).
+- `alloc::alloc(layout)` returns uninitialized memory — reading it before writing is UB.
+- Padding bytes in structs read via `transmute` or raw pointer casts.
+- `read_unaligned` on uninitialized memory.
+
+**Miri detection:** YES — tracks initialization state per byte. Catches partial-init structs, padding reads, and premature `assume_init`.
+
+**Fix pattern:** Use `MaybeUninit::zeroed()` when zero-init is acceptable. Write every field before calling `assume_init()`. Use `MaybeUninit::write()` instead of raw pointer writes. Never `transmute` structs with padding unless you zeroed the padding.
+
+---
+
+## 5. Invalid Values (Type Invariant Violations)
+
+**Root cause:** Producing a value that violates the type's validity invariant.
+
+**Canonical triggers:**
+- `bool` not 0 or 1.
+- `char` outside Unicode scalar range.
+- Enum discriminant not matching any variant.
+- `NonZeroU32` containing 0.
+- `&T` or `&mut T` that is null or dangling.
+- `str` containing non-UTF-8 bytes.
+- `fn` pointer that is null.
+
+**Miri detection:** YES — validity checks are on by default. Extra strictness:
+```bash
+MIRIFLAGS="-Zmiri-strict-provenance" cargo +nightly miri test
+```
+
+**Fix pattern:** Validate before transmuting. Use `TryFrom` at boundaries. Never `transmute` to enum types — use a checked conversion function.
+
+---
+
+## 6. Misaligned Pointer Access
+
+**Root cause:** Dereferencing a pointer that is not aligned to the type's required alignment.
+
+**Canonical triggers:**
+- Casting `*const u8` to `*const u64` and dereferencing (alignment goes from 1 to 8).
+- `#[repr(packed)]` struct field references (the compiler warns, but raw pointers bypass the warning).
+- Network buffer parsing where offsets are arbitrary.
+
+**Miri detection:** YES — immediate trap on misaligned read/write.
+
+**Fix pattern:** Use `read_unaligned` / `write_unaligned` for packed data. Use `bytemuck` or `zerocopy` for safe reinterpretation with alignment checks.
+
+---
+
+## 7. Violating `Pin` Invariants
+
+**Root cause:** Moving a value that was pinned and relied on its address stability (self-referential types, intrusive linked lists).
+
+**Canonical triggers:**
+- `mem::swap` on a `Pin<&mut T>` after `unsafe` deref.
+- Implementing `Unpin` for a type that contains self-referential pointers.
+- Manually calling `Pin::new_unchecked` on a movable allocation.
+
+**Miri detection:** PARTIAL — Miri detects the resulting aliasing/use-after-free if the self-referential pointer is actually used. It does not detect "Pin contract violated but pointer was never dereferenced."
+
+**Fix pattern:** Never `impl Unpin` for self-referential types. Use `pin_project` or `pin_project_lite` for safe pin projections. Review every `Pin::new_unchecked` call.
+
+---
+
+## 8. FFI Boundary UB
+
+**Root cause:** Mismatch between Rust's ABI expectations and the foreign code's actual behavior.
+
+**Canonical triggers:**
+- C function returning uninitialized memory into a Rust `&T`.
+- Wrong `#[repr(C)]` layout (padding differs between platforms).
+- Passing a Rust `enum` to C without `#[repr(C)]` or `#[repr(i32)]`.
+- Null pointer passed where C expects non-null (and Rust wraps it in `&T`).
+- C code writing to Rust-owned memory through a pointer Rust considers immutable.
+- Forgetting to mark FFI functions as `unsafe extern "C"`.
+- longjmp/setjmp across Rust frames (unwinding UB).
+
+**Miri detection:** LIMITED — Miri cannot execute foreign code. It detects UB in the Rust-side handling of FFI return values.
+
+**Complementary tools:** AddressSanitizer (ASAN), MemorySanitizer (MSAN) for detecting actual FFI-side corruption. Valgrind as a last resort.
+
+**Fix pattern:** Validate every FFI return at the boundary. Use `Option<NonNull<T>>` for nullable pointers. Use `CStr`/`CString` for strings. Add `cbindgen` to CI to verify layout agreement. Wrap every FFI call in a safe Rust function that checks preconditions.
+
+---
+
+## 9. Incorrect `Send` / `Sync` Implementations
+
+**Root cause:** Manually implementing `Send` or `Sync` for a type that does not actually uphold the required invariant.
+
+**Canonical triggers:**
+- `unsafe impl Send for Wrapper(*mut T)` when `T` is not `Send`.
+- `unsafe impl Sync for Wrapper(UnsafeCell<T>)` without a lock, atomic, or other synchronization.
+- Types containing `Rc<T>` with a manual `Send` impl (Rc is explicitly !Send).
+
+**Miri detection:** YES for the *resulting* data race if exercised. Miri's data-race detector will fire when two threads access the same location unsynchronized.
+
+**Fix pattern:** Never manually implement `Send`/`Sync` unless you can write a SAFETY proof naming the synchronization mechanism. Use `PhantomData<*const ()>` to opt-out of auto-`Send`/`Sync` when in doubt.
+
+---
+
+## 10. Out-of-Bounds Memory Access
+
+**Root cause:** Pointer arithmetic or indexing that escapes the allocation.
+
+**Canonical triggers:**
+- `ptr.offset(n)` where `n` exceeds the allocation size.
+- `slice::from_raw_parts(ptr, len)` where `len` is too large.
+- Off-by-one in manual buffer management.
+- Integer overflow in size calculations leading to undersized allocation.
+
+**Miri detection:** YES — allocation-precise bounds checking.
+
+**Fix pattern:** Use checked arithmetic (`checked_add`, `checked_mul`) for size calculations. Use `slice::from_raw_parts` only with validated lengths. Prefer safe indexing (`get()`, iterators) over raw pointer arithmetic.
+
+---
+
+## 11. Provenance Violations
+
+**Root cause:** Using a pointer whose provenance does not grant access to the target memory, even if the address is numerically correct.
+
+**Canonical triggers:**
+- Casting an integer to a pointer and dereferencing it (`addr as *const T`).
+- Roundtripping a pointer through `usize` and back (`ptr as usize as *const T`) — the provenance is lost.
+- Using `ptr::from_exposed_addr` without a corresponding `ptr.expose_provenance()`.
+
+**Miri detection:** YES with strict provenance:
+```bash
+MIRIFLAGS="-Zmiri-strict-provenance" cargo +nightly miri test
+```
+
+**Fix pattern:** Use `ptr::with_exposed_provenance` / `ptr.expose_provenance()` for legitimate int-to-ptr roundtrips. Avoid `as usize as *const T` entirely. Use `sptr` crate for provenance-safe pointer manipulation on stable.
+
+---
+
+## 12. Double Free / Invalid Free
+
+**Root cause:** Freeing the same allocation twice, or freeing memory not obtained from the allocator.
+
+**Canonical triggers:**
+- `Box::from_raw` called twice on the same pointer.
+- Manual `dealloc` on a pointer already freed.
+- `ManuallyDrop` dropped explicitly then the outer type also drops it.
+
+**Miri detection:** YES — immediate trap.
+
+**Fix pattern:** Enforce single ownership via RAII. Use `ManuallyDrop` with extreme care — document who is responsible for the drop. Never clone a raw pointer and `Box::from_raw` both copies.
+
+---
+
+## 13. Library / Unsafe Contract Violations
+
+**Root cause:** Violating the documented safety invariant of a safe or unsafe API, where the library author relied on the invariant for soundness.
+
+**Canonical triggers:**
+- `Vec::set_len(n)` where the first `n` elements are not initialized.
+- `String::from_utf8_unchecked` on non-UTF-8 bytes.
+- `HashMap` key mutated after insertion (violates hash invariant — not UB per se, but unsound and Miri may detect downstream effects).
+- `BTreeMap` key with broken `Ord` impl (the standard library assumes a total order).
+
+**Miri detection:** DEPENDS — Miri catches the downstream UB (e.g., reading uninitialized bytes from a `Vec` with inflated len). It does not catch "you violated the documented contract" if no memory-level UB results.
+
+**Fix pattern:** Read the `# Safety` section of every `unsafe fn` you call. Document the invariant in your SAFETY comment. When in doubt, use the safe API and pay the cost.
+
+---
+
+## 14. Unwinding Across `extern "C"` Boundaries
+
+**Root cause:** A Rust panic unwinding through a frame that uses the C calling convention.
+
+**Canonical triggers:**
+- `panic!()` inside a `#[no_mangle] extern "C" fn` callback passed to C code.
+- `unwrap()` inside FFI callbacks.
+
+**Miri detection:** PARTIAL — Miri does not model foreign unwinding, but it can detect the immediate UB if the panic reaches the FFI boundary.
+
+**Fix pattern:** Use `std::panic::catch_unwind` at every FFI entry point. Mark FFI callbacks as `extern "C-unwind"` when panic propagation is intentional (nightly). Prefer returning `Result`-like error codes from FFI callbacks.
+
+---
+
+## Summary Table
+
+| # | Category | Miri Detects? | Complementary Tool |
+|---|----------|--------------|-------------------|
+| 1 | Aliasing (Stacked/Tree Borrows) | YES | — |
+| 2 | Data races | YES | loom, TSAN |
+| 3 | Use-after-free / dangling | YES | ASAN |
+| 4 | Uninitialized memory | YES | MSAN |
+| 5 | Invalid values | YES | — |
+| 6 | Misaligned access | YES | UBSAN |
+| 7 | Pin invariant violation | PARTIAL | manual review |
+| 8 | FFI boundary UB | LIMITED | ASAN, MSAN, Valgrind |
+| 9 | Incorrect Send/Sync | YES (via race) | loom |
+| 10 | Out-of-bounds access | YES | ASAN |
+| 11 | Provenance violations | YES (strict mode) | — |
+| 12 | Double free | YES | ASAN |
+| 13 | Library contract violations | PARTIAL | proptest, fuzzing |
+| 14 | Unwinding across FFI | PARTIAL | — |
+
+## Miri Coverage Assessment
+
+Miri catches categories 1-6, 9-12 with high confidence. Categories 7, 8, 13, 14 require supplementary tools or manual audit. **Miri is the single highest-leverage tool** — it should run on every PR that touches `unsafe`, and ideally on the full test suite regularly.

package/marketplace/plugins/litcodex/skills/lit-code/references/typescript/README.md

@@ -0,0 +1,195 @@
+
+# TypeScript Programmer
+
+Modern TypeScript. Type-strict, stack-first, async-correct.
+
+## Philosophy
+
+The compiler is your proof system. Make illegal states unrepresentable. Parse at boundaries. Every function has a contract; the type system enforces it.
+
+## Hard rules
+
+These are deliberate project choices. Violations are always wrong, not "style preferences".
+
+### Tooling
+
+| Category | Use | Never |
+|---|---|---|
+| Runtime | Bun (native TS, single binary) | ts-node, tsx |
+| Package manager | `pnpm` | npm, yarn (unless workspace requires it) |
+| Linter + formatter | Biome | ESLint, Prettier |
+| Type checker | `tsc --noEmit` with strict config | skip type checking |
+| Web framework | Hono | Express |
+| Validation | Zod | joi, yup, class-validator |
+| Testing | `bun test` or vitest | jest |
+| ORM | Drizzle | TypeORM, Prisma (unless already in project) |
+
+### The iron list
+
+1. **Readonly by default** — all `type`/`interface` properties are `readonly`. Arrays are `readonly T[]`. Mutable only when mutation is the documented purpose.
+2. **Branded types for distinct IDs** — `type UserId = Brand<string, "UserId">`. Never pass raw `string` where a branded type exists.
+3. **Exhaustive switch** — every `switch` on a discriminated union ends with `default: assertNever(x)`. No fall-through.
+4. **No any** — `any` is banned in annotations, returns, and parameters. Use `unknown` and narrow.
+5. **No type assertions** — `as any`, `as unknown` banned. `as const` and `satisfies` are fine.
+6. **No non-null assertion** — `x!` is banned. Use narrowing or optional chaining (`x?.y`).
+7. **No @ts-ignore / @ts-expect-error** — fix the type.
+8. **No enum** — use `as const` objects + literal union types.
+9. **Zod at boundaries** — external input (API, user, file) → Zod schema. Internal → plain types.
+10. **Typed errors** — Error subclasses with typed fields. No `throw new Error("bare string")` for domain errors. Use Result for expected failures within 1-2 call levels; throw for propagation across many layers.
+11. **as const for constants** — module-level constant objects and arrays use `as const`.
+12. **import type** — type-only imports use `import type`. Enforced by `verbatimModuleSyntax`.
+13. **Named exports only** — no `export default`. Exception: framework requirement (Next.js pages, etc.).
+14. **No empty catch, no catch-and-swallow** — every `catch` block must either (a) narrow the error with `instanceof` and handle each case, or (b) re-throw. Empty catch blocks and `catch (e) { console.error(e) }` without narrowing or re-throw are banned — they hide bugs. At top-level boundaries (CLI entry, HTTP handler), opt out with `// no-excuse-ok: catch`.
+
+### Data modeling — which construct, when
+
+| Situation | Use |
+|---|---|
+| User input, API request/response | Zod schema + `z.infer` |
+| Internal value object | `type` with `readonly` properties |
+| Function with multiple outcomes | Discriminated union (`kind` field) |
+| Contract for implementations | `interface` |
+| Fixed constants | `as const` + literal union |
+| Distinct primitive (UserId vs OrderId) | Branded type |
+| Key-value map | `Record<K, V>` or index signature |
+
+**The one rule**: data crosses trust boundary → Zod. Everything else → plain `type` with `readonly`.
+
+Load `data-modeling.md` for the full decision flowchart and comparison.
+
+### When readonly does not apply
+
+- **Framework state** (React `useState`, signals) — managed by framework.
+- **Builder / accumulator** — object exists to be mutated (buffer, cache). Document why.
+- **ORM mutations** — Drizzle insert/update objects.
+
+### Why empty/unhandled catch is banned
+
+In TypeScript, every `catch` receives `unknown`. The language gives you no type safety in catch blocks — you must earn it with `instanceof`. A bare `catch (e) { console.error(e) }` swallows `TypeError`, `RangeError`, and your domain errors identically. When a new error type appears, nothing warns you.
+
+```typescript
+// BANNED — empty catch
+try { await fetchData() } catch {}
+try { await fetchData() } catch (e) { /* will fix later */ }
+
+// BANNED — catch-and-swallow (no narrowing, no rethrow)
+try {
+  const data = await api.get("/users")
+} catch (e) {
+  console.error("failed", e)
+}
+
+// GOOD — narrow with instanceof
+try {
+  const data = await api.get("/users")
+} catch (e) {
+  if (e instanceof HttpError) {
+    logger.warn(`API ${e.status}: ${e.message}`)
+    return fallback
+  }
+  throw e  // unknown errors propagate
+}
+
+// GOOD — top-level boundary (only place catch-all is acceptable)
+async function main(): Promise<void> {  // no-excuse-ok: catch
+  try {
+    await run()
+  } catch (e) {
+    console.error("unhandled:", e)
+    process.exit(1)
+  }
+}
+```
+
+### Libraries
+
+| Domain | Library | Why |
+|---|---|---|
+| HTTP framework | Hono | Lightweight, multi-runtime, middleware, OpenAPI |
+| Validation | Zod | Runtime validation + type inference |
+| ORM | Drizzle | Type-safe SQL, no codegen |
+| HTTP client | `ky` | Thin fetch wrapper (5KB); auto-throw on non-2xx, retry, timeout, hooks, prefixUrl. Browser + Node + Bun + Deno |
+| HTTP client (perf) | `undici` (direct API) | When a Node backend needs connection pooling, HTTP/2, or pipelining |
+
+> **HTTP client rule** - production code must not use bare `fetch()`. It has no retry, timeout, or error-handling policy and causes silent failures during incidents. Install **`ky`** by default, and use the **`undici`** direct API when a Node backend needs high-volume requests, connection pooling, HTTP/2, or pipelining. ~~`axios`~~ is forbidden after the supply-chain compromise (2026-03). `node-fetch` is unnecessary because Node 18+ includes built-in fetch.
+| Testing | `bun test` / vitest | Fast, ESM-native |
+| Logging | `pino` | Structured JSON, fast |
+| CLI | `@clack/prompts` + `commander` | Interactive + parsing |
+
+## tsconfig — the one true config
+
+Scaffold a new project with all strict defaults pre-configured:
+
+```bash
+bun run ../../scripts/typescript/new-project.ts my-api
+bun run ../../scripts/typescript/new-project.ts my-api --path ./projects
+```
+
+Creates: `package.json` (Hono + Zod + Biome), `tsconfig.json` (ultra-strict), `biome.json`, `src/index.ts`, `.gitignore`. Works on macOS, Linux, Windows.
+
+For manual setup: `bunx tsc --init`, then load `tsconfig-strict.md` for the full strict config.
+
+Key flags beyond `"strict": true`:
+
+| Flag | What it catches |
+|---|---|
+| `noUncheckedIndexedAccess` | `arr[0]` is `T \| undefined`, forces check |
+| `exactOptionalPropertyTypes` | `{ x?: string }` ≠ `{ x: string \| undefined }` |
+| `verbatimModuleSyntax` | Forces `import type` for type-only imports |
+| `noFallthroughCasesInSwitch` | Forgotten `break` / `return` |
+| `noPropertyAccessFromIndexSignature` | `.key` on index sig → bracket notation |
+
+## Reference loading
+
+Load on demand — not all at once.
+
+| Need | Load |
+|---|---|
+| Strict tsconfig + Biome config | `tsconfig-strict.md` |
+| Type patterns (branded, as const, satisfies, narrowing, assertNever) | `type-patterns.md` |
+| Data modeling (type vs interface vs Zod, readonly, parse-don't-validate) | `data-modeling.md` |
+| Error handling (Result, typed errors, union vs throw) | `error-handling.md` |
+| Bootstrapping a new project (Bun, pnpm, Hono, Vite) | `bootstrap.md` |
+| Hono backend stack (hono-openapi, Scalar, Swagger) | `backend-hono.md` |
+
+## No-excuse audit
+
+Violations caught by `../../scripts/typescript/check-no-excuse-rules.ts`. Run after every edit session.
+
+| Rule ID | Catches | Opt-out |
+|---|---|---|
+| `no-any-assertion` | `as any` | None — redesign types |
+| `no-unknown-assertion` | `as unknown` | None — redesign types |
+| `no-ts-ignore` | `@ts-ignore` | None — fix the type |
+| `no-ts-expect-error` | `@ts-expect-error` | None — fix the type |
+| `no-enum` | `enum` declarations | None — use `as const` |
+| `no-non-null-assertion` | `x!` postfix | None — narrow or `?.` |
+| `no-throw-literal` | `throw "string"` / `throw 123` | None — throw Error subclass |
+| `no-mutable-export` | `export let` / `export var` | None — use `export const` |
+| `no-any-annotation` | `: any` in parameter/return/variable types | `// no-excuse-ok: any` |
+| `no-explicit-any-return` | `(): any` or `(): Promise<any>` return types | `// no-excuse-ok: any` |
+| `empty-catch` | `catch { }` or `catch (e) { }` with empty body | `// no-excuse-ok: catch` |
+| `catch-without-narrowing` | `catch (e)` used without `instanceof` or re-throw | `// no-excuse-ok: catch` |
+
+Biome enforces additional rules (noExplicitAny, noNonNullAssertion, noDefaultExport, useImportType). The script catches what Biome cannot.
+
+## In tests
+
+Tests are strict too, with these exceptions (configure in `biome.jsonc` overrides):
+
+| In tests you may | Why |
+|---|---|
+| Use `expect()` assertions | That's how testing works |
+| Use magic numbers | Test data |
+| Access private members via bracket notation | Testing internals |
+| Skip readonly on test fixtures | Mutable setup/teardown |
+
+Tests still follow the iron list — branded types, typed errors, exhaustive switch.
+
+## Existing codebases
+
+When editing an existing file that doesn't follow these rules: **write new code in strict style, don't refactor existing code in the same change.**
+
+## Activation
+
+This skill activates whenever you are writing or modifying any `.ts` or `.tsx` file. Even one-off scripts get the strict treatment.