lazycodex-ai 5.0.0-beta.85 → 5.0.0-beta.87

package/packages/shared-skills/skills/programming/references/rust/api-design.md

@@ -0,0 +1,81 @@
+# Public API Design
+
+What a caller sees: names, conversions, traits, attributes, visibility, and rustdoc. Every rule here exists so a call site reads correctly without opening the implementation.
+
+## Naming says cost and ownership
+
+| Prefix / form | Meaning | Example |
+|---|---|---|
+| `as_x(&self) -> &X` | Borrowed view, no allocation | `str::as_bytes`, `PathBuf::as_path` |
+| `to_x(&self) -> X` | Builds a new owned value (may allocate or compute) | `str::to_lowercase`, `Path::to_path_buf` |
+| `into_x(self) -> X` | Consumes `self`, reuses its buffers | `String::into_bytes`, `Vec::into_boxed_slice` |
+| `x(&self)` | Plain accessor, no `get_` prefix | `len()`, `name()`, `user_id()` |
+| `get(&self, key)` | Fallible lookup that returns `Option` | `HashMap::get`, `slice::get` |
+| `iter()` / `iter_mut()` / `IntoIterator` | Borrowing, mutable, and consuming iteration | implement the ones the type actually needs |
+| `is_x()` / `has_x()` / `can_x()` | `bool` query, named for the positive state | `is_empty()`, `has_children()` |
+
+Types, traits, and enum variants are `UpperCamelCase` with acronyms as one word (`HttpClient`, `Json`, not `HTTPClient`); functions, modules, and locals `snake_case`; constants and statics `SCREAMING_SNAKE_CASE`; simple generics `T`, `E`, `K`, `V`, lifetimes short (`'a`, `'de`). Return `impl Iterator<Item = T>` instead of a named iterator struct unless callers need to name the type.
+
+## Conversions
+
+| Conversion | Trait | Rule |
+|---|---|---|
+| Always succeeds, no invariant can break | `From<T>` | Implement `From`; callers get `Into` for free. Never implement `Into` directly. |
+| Can fail | `TryFrom<T>` | `type Error` is a real error type, never `()` or `String`. |
+| Parses text | `FromStr` | Routes through the same checked constructor as `TryFrom`. |
+| Cheap borrowed view for a generic parameter | `AsRef<T>` | Accept `impl AsRef<Path>` only where callers really pass several types; a plain `&Path` is simpler otherwise. |
+
+Validated types expose `TryFrom` / `FromStr` only; an infallible `From` into them bypasses the invariant ([type-state.md](type-state.md)). Units convert through named methods (`to_feet()`), never `From`, so the conversion is visible.
+
+Generic parameters that only convert (`fn new(name: impl Into<String>)`) hide an allocation at the call site; take `&str` or `String` explicitly unless the constructor is called with both often.
+
+## Trait design
+
+- **Generic by default, `dyn` for heterogeneity.** `fn run<R: Renderer>(r: &R)` monomorphizes and inlines; `&dyn Renderer` or `Box<dyn Renderer>` is for a collection of mixed implementors or a deliberate code-size trade. `dyn` needs indirection, not necessarily a heap allocation: `&dyn Trait` borrows.
+- **Associated type vs generic parameter.** One natural output per implementor (`Iterator::Item`, a parser's `Output`) is an associated type. A generic parameter (`From<T>`) is for traits a type implements several times.
+- **Minimal required methods.** Require the few methods that carry the contract; provide the rest as default methods built on them. A default method must be correct for every implementor, not merely convenient.
+- **Blanket impls are a semver commitment.** A public `impl<T: Display> MyTrait for T` forbids downstream crates, and your own future versions, from writing a more specific impl. Add one only when it is permanently right for every `T`.
+- **Orphan rule.** You cannot implement a foreign trait for a foreign type. Wrap the type in a local newtype and implement the trait on the wrapper; do not add `Deref` to the inner type to make it convenient.
+- **Closed sets are sealed.** A public trait whose implementations only you may add uses the sealed-trait pattern ([type-state.md](type-state.md#sealed-traits)).
+- **Bounds live on impls, not structs.** `struct Cache<K, V> { .. }` stays unbounded; `impl<K: Hash + Eq, V> Cache<K, V>` carries the bounds, so every mention of `Cache` does not repeat them.
+- **Callables take the weakest bound.** `FnOnce` if called once, `FnMut` if called repeatedly with mutation, `Fn` for shared repeated calls. Return a closure as `impl Fn(..)`; box it (`Box<dyn Fn(..)>`) only to store closures of different types together.
+
+## Attributes that protect callers
+
+- **`#[must_use]`** on builder methods that return `Self` (a dropped builder silently loses configuration), on pure constructors of values whose drop is a bug, and on functions whose whole point is the return value. `Result` is already `must_use`; do not blanket-annotate every function.
+- **`#[non_exhaustive]`** on public enums and structs that will grow (error enums, config structs, event types). Downstream matches get a required `_` arm and your next variant is not a breaking change. Keep a public enum exhaustive only when its closed set is part of the contract (`Ordering`). `exhaustive_enums` / `exhaustive_structs` in [cargo-strict.md](cargo-strict.md) flag the choice.
+
+## Visibility
+
+Start private. Widen one step at a time, only for a caller that exists: private -> `pub(super)` (sibling modules) -> `pub(crate)` -> `pub`. The `unreachable_pub` lint catches `pub` items no one outside the crate can reach. Shape the public surface with deliberate re-exports (`pub use crate::parse::Parser;` in `lib.rs`), never `pub use module::*`, which exports whatever a later edit adds.
+
+## Rustdoc sections
+
+Every public item has a doc comment (`missing_docs`). Public fallible, panicking, or `unsafe` functions carry the section a caller needs:
+
+```rust
+/// Parses a `key=value` line.
+///
+/// # Errors
+///
+/// Returns [`ParseError::MissingSeparator`] when the line has no `=`.
+///
+/// # Examples
+///
+/// ```
+/// # use my_crate::{parse_pair, ParseError};
+/// # fn main() -> Result<(), ParseError> {
+/// let (key, value) = parse_pair("port=8080")?;
+/// assert_eq!((key, value), ("port", "8080"));
+/// # Ok(())
+/// # }
+/// ```
+pub fn parse_pair(line: &str) -> Result<(&str, &str), ParseError> {
+    line.split_once('=').ok_or(ParseError::MissingSeparator)
+}
+```
+
+- `# Errors` for every public `Result`-returning function (`missing_errors_doc`), `# Panics` for every reachable panic (`missing_panics_doc`), `# Safety` for every public `unsafe fn` or `unsafe trait`, listing each obligation the caller takes on.
+- Examples use `?`, never `unwrap`; lines starting with `# ` compile but stay hidden, which is where imports and the `fn main() -> Result` wrapper go.
+- Link types with intra-doc links (``[`ParseError`]``). `RUSTDOCFLAGS="-D warnings" cargo doc` fails on a broken link, and `cargo test --doc` runs every example.
+- A crate's front page can be its README: `#![doc = include_str!("../README.md")]` makes the README's code blocks doctests too.

package/packages/shared-skills/skills/programming/references/rust/async-tokio.md

@@ -5,8 +5,8 @@ Structured concurrency, cancellation, blocking-work isolation, channel selection
 ## Runtime selection
 
 ```rust
-// Default for services and CLIs that do real work
-#[tokio::main(flavor = "multi_thread", worker_threads = 8)]
+// Default for services and CLIs that do real work: multi-thread, one worker per core
+#[tokio::main]
 async fn main() -> anyhow::Result<()> { ... }
 
 // For tiny CLIs or wasm where you measured single-thread is enough
@@ -14,7 +14,7 @@ async fn main() -> anyhow::Result<()> { ... }
 async fn main() -> anyhow::Result<()> { ... }
 ```
 
-Pick worker count explicitly. The default (`num_cpus`) is fine for servers; for desktop tools you usually want 2-4.
+Keep the default worker count. Set `worker_threads` only for a measured reason or a deployment constraint (a container CPU quota the runtime cannot see, a desktop tool sharing the machine). CPU-heavy work does not get more workers; it leaves the runtime (see Blocking work).
 
 ## Spawning
 
@@ -48,13 +48,14 @@ while let Some(joined) = set.join_next().await {
 - Dropping the set aborts every still-running task.
 - Lets you handle failures one by one rather than all-or-nothing.
 
-For wait-for-all semantics with one type, `join!`:
+For a fixed set of independent futures, `join!` waits for all; for fallible ones, `try_join!` returns on the first `Err`:
 
 ```rust
-let (a, b, c) = tokio::join!(load_a(), load_b(), load_c());
-let a = a?; let b = b?; let c = c?;
+let (a, b, c) = tokio::try_join!(load_a(), load_b(), load_c())?;
 ```
 
+On that first error `try_join!` drops the other futures mid-flight. Dropping is cancellation, not rollback: side effects they already started stay started (see Cancellation).
+
 For first-of-many, `select!`:
 
 ```rust
@@ -76,19 +77,19 @@ Without `biased`, branches are polled in random order each iteration (good for f
 
 A future is cancelled when it is dropped (e.g., the `select!` arm wins another branch). **Always think: if this future is dropped mid-await, what state is left behind?**
 
-Cancel-safe futures (you can drop without lasting effect):
-- `recv()` on channels
-- `accept()` on listeners
-- `wait_for` on `watch::Receiver`
-- `read_buf`/`write_all` on streams **only when buffers are owned by the future**, otherwise no
+Cancel-safe futures (you can drop them without losing data):
+- `recv()` on channels, `accept()` on listeners
+- `changed()` / `wait_for` on `watch::Receiver`
+- `AsyncReadExt::read` / `read_buf`: bytes land in your buffer only when the call completes
 
-Cancel-unsafe futures (dropping mid-way leaves partial state):
-- Manual `read_exact` into an external buffer
-- Custom futures that perform partial side effects before suspending
+Cancel-unsafe futures (dropping mid-way loses data or leaves partial state):
+- `read_exact`, `read_to_end`, `read_to_string`: bytes already read are gone
+- `write_all` / `write_all_buf`: an unknown prefix was already written
+- Custom futures that perform side effects before suspending
 
-If a function is cancel-unsafe, document it in a rustdoc `# Cancel Safety` section.
+Tokio documents cancel safety per method; check it for every future used as a `select!` branch in a loop. When an operation is cancel-unsafe, keep its progress outside the future (a buffer that lives across loop iterations) or move it into its own task. If your own function is cancel-unsafe, document it in a rustdoc `# Cancel Safety` section.
 
-To explicitly opt out of cancellation, use `tokio_util::sync::CancellationToken`:
+Cooperative cancellation of a whole task tree uses `tokio_util::sync::CancellationToken`: tasks watch the token and exit at a point they choose, so cleanup runs.
 
 ```rust
 use tokio_util::sync::CancellationToken;
@@ -135,7 +136,7 @@ let result = tokio::task::spawn_blocking(|| {
 }).await?;
 ```
 
-Long-running blocking jobs (more than ~1 second of CPU) → use a dedicated thread pool (`rayon`), not tokio's blocking pool which is sized for short bursts.
+Sustained CPU parallelism → a dedicated pool (`rayon`), not tokio's blocking pool, which is sized for many short blocking calls. The same rule covers the blocking std APIs that look harmless inside `async fn`: `std::thread::sleep` (use `tokio::time::sleep`), `std::fs::*` (use `tokio::fs`, or batch it into one `spawn_blocking`), and `blocking_recv` / `blocking_lock` (they panic inside a runtime).
 
 ## Channels
 
@@ -199,21 +200,31 @@ serve_sse(stream).await
 ```rust
 use tokio::signal;
 
+/// Resolves on Ctrl-C or SIGTERM. A signal source that cannot be installed is
+/// logged and never fires, so the other source still works.
 async fn shutdown_signal() {
-    let ctrl_c = async { signal::ctrl_c().await.expect("ctrl_c handler") };
+    let ctrl_c = async {
+        if let Err(error) = signal::ctrl_c().await {
+            tracing::error!(%error, "cannot listen for ctrl-c");
+            std::future::pending::<()>().await;
+        }
+    };
     #[cfg(unix)]
     let terminate = async {
-        signal::unix::signal(signal::unix::SignalKind::terminate())
-            .expect("install signal handler")
-            .recv()
-            .await;
+        match signal::unix::signal(signal::unix::SignalKind::terminate()) {
+            Ok(mut sigterm) => { sigterm.recv().await; }
+            Err(error) => {
+                tracing::error!(%error, "cannot listen for SIGTERM");
+                std::future::pending::<()>().await;
+            }
+        }
     };
     #[cfg(not(unix))]
     let terminate = std::future::pending::<()>();
 
     tokio::select! {
-        _ = ctrl_c => {},
-        _ = terminate => {},
+        () = ctrl_c => {},
+        () = terminate => {},
     }
     tracing::info!("shutdown signal received");
 }
@@ -224,7 +235,10 @@ async fn main() -> anyhow::Result<()> {
     let server = tokio::spawn(run_server(token.child_token()));
     shutdown_signal().await;
     token.cancel();
-    let _ = tokio::time::timeout(Duration::from_secs(10), server).await;
+    match tokio::time::timeout(Duration::from_secs(10), server).await {
+        Ok(joined) => joined??, // JoinError (panic) and the server's own error both surface
+        Err(_elapsed) => tracing::warn!("server did not stop within 10s"),
+    }
     Ok(())
 }
 ```
@@ -235,14 +249,16 @@ Pattern: catch signal → cancel a token shared with the server → server's `se
 
 - `tokio::sync::Mutex` — async mutex. Use for state shared between async tasks. **Do not hold across `.await` without thinking** (you'll serialize the whole system).
 - `tokio::sync::RwLock` — async read-write lock. Same caveat.
-- `parking_lot::Mutex` — sync mutex, faster than `std::sync::Mutex`, no poisoning. Use when the lock is held briefly and you do not need to `.await` while holding it.
+- `std::sync::Mutex` / `parking_lot::Mutex` — sync mutex for a critical section that never spans an `.await` (see [concurrency.md](concurrency.md) for choosing between them).
+- Nothing guard-like lives across an `.await`: not a sync lock guard, not a `watch` borrow ([concurrency.md](concurrency.md)), not a `span.enter()` guard. Instrument the future instead: `fut.instrument(span).await`.
 - `tokio::sync::Semaphore` — bound concurrent operations. Perfect for "max 10 in-flight HTTP requests" or "max 3 DB writers".
 
 ```rust
 let sem = Arc::new(tokio::sync::Semaphore::new(10));
+let mut set = JoinSet::new();
 for url in urls {
-    let permit = sem.clone().acquire_owned().await?;
-    tokio::spawn(async move {
+    let permit = Arc::clone(&sem).acquire_owned().await?;
+    set.spawn(async move {
         let _permit = permit;  // released on task end
         fetch(&url).await
     });
@@ -278,6 +294,8 @@ async fn fetches_and_parses() {
 async fn parallel_work() { ... }
 ```
 
+`current_thread` is the default test runtime; it chooses a scheduler, it does not make a test deterministic. Wait on the exact event (a channel message, a `Notify`, a `watch` change) or on paused virtual time below, never on a real `sleep`.
+
 For time-sensitive tests, advance virtual time:
 
 ```rust
@@ -290,6 +308,20 @@ async fn time_travel() {
 }
 ```
 
+## Async traits and async closures
+
+`async fn` in traits is stable (1.75) and dispatches statically:
+
+```rust
+trait Store {
+    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError>;
+}
+```
+
+Two limits: callers cannot require the returned future to be `Send` (spawning a generic `S: Store` call fails), and the trait is not `dyn`-compatible. For `Send` futures, declare the method as `fn get(&self, key: &str) -> impl Future<Output = ...> + Send;`. For `dyn Store`, box the future (`Pin<Box<dyn Future<Output = T> + Send + '_>>`) or use `async-trait`; pick `dyn` only for runtime heterogeneity.
+
+A parameter that is an async callback borrowing from its caller takes `F: AsyncFn(&Request) -> Response` (1.85, `std::ops::AsyncFn`), not `F: Fn(&Request) -> Fut`: the `Fut` form cannot name a future that borrows its argument.
+
 ## When NOT to use async
 
 - Single-threaded CPU-heavy code that does no I/O — plain `fn` + `rayon` is simpler and often faster.

package/packages/shared-skills/skills/programming/references/rust/axum-stack.md

@@ -307,19 +307,7 @@ fn init_tracing() {
     fmt().with_env_filter(filter).with_target(false).json().init();
 }
 
-async fn shutdown_signal() {
-    let ctrl_c = async { tokio::signal::ctrl_c().await.expect("ctrl_c handler"); };
-    #[cfg(unix)]
-    let terminate = async {
-        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
-            .expect("signal handler").recv().await;
-    };
-    #[cfg(not(unix))]
-    let terminate = std::future::pending::<()>();
-
-    tokio::select! { _ = ctrl_c => {}, _ = terminate => {} }
-    tracing::info!("shutting down");
-}
+// shutdown_signal(): the Ctrl-C / SIGTERM future from async-tokio.md#graceful-shutdown
 ```
 
 ## Middleware: bearer auth example

package/packages/shared-skills/skills/programming/references/rust/cargo-strict.md

@@ -32,6 +32,8 @@ non_ascii_idents = "deny"
 trivial_numeric_casts = "warn"
 unused_lifetimes = "warn"
 single_use_lifetimes = "warn"
+# every custom cfg is declared here; a typo like cfg(feture = "x") fails the build
+unexpected_cfgs = { level = "deny", check-cfg = ["cfg(loom)"] }
 
 [lints.clippy]
 # Groups
@@ -66,7 +68,9 @@ mutex_atomic = "warn"
 rc_buffer = "warn"
 rc_mutex = "warn"
 exit = "warn"
-allow_attributes_without_reason = "warn"
+allow_attributes = "deny"                 # silence with #[expect(lint, reason)], never #[allow]
+allow_attributes_without_reason = "deny"
+let_underscore_must_use = "deny"          # `let _ = fallible()` drops the error
 dbg_macro = "warn"
 print_stderr = "warn"
 print_stdout = "warn"
@@ -75,10 +79,8 @@ use_debug = "warn"
 # Stylistic relaxations (project-wide opinions only)
 module_name_repetitions = "allow"
 must_use_candidate = "allow"
-missing_errors_doc = "allow"  # we use anyhow::Result with .context() everywhere; doc rule is noisy
 
 # Restriction lints - opt-in soundness rails
-unreachable = "deny"
 mod_module_files = "warn"      # prefer foo.rs over foo/mod.rs
 empty_drop = "warn"
 empty_structs_with_brackets = "warn"
@@ -89,6 +91,8 @@ exhaustive_structs = "warn"
 
 The `priority = -1` trick: group-level levels are weak; specific lints below them win. This lets us deny `unwrap_used` while still allowing `pedantic` group warnings instead of denies.
 
+A lint is silenced only with `#[expect(clippy::lint_name, reason = "...")]` on the smallest item that needs it. Unlike `#[allow]`, `#[expect]` fails the build once the lint stops firing, so stale exceptions cannot pile up; `allow_attributes` and `allow_attributes_without_reason` enforce both halves. `missing_errors_doc` / `missing_panics_doc` stay on (pedantic): public fallible APIs document their `# Errors`.
+
 ## `Cargo.toml` — release profile
 
 ```toml
@@ -116,6 +120,8 @@ opt-level = 1
 overflow-checks = true
 ```
 
+`-C target-cpu=native` and PGO are deployment decisions, not defaults: a `native` binary faults on older CPUs, and PGO only pays with a representative training workload. Apply either only with a before/after measurement.
+
 ## `Cargo.toml` — workspace level
 
 ```toml
@@ -124,15 +130,23 @@ resolver = "3"
 
 [workspace.package]
 edition = "2024"
-rust-version = "1.83"   # bump only when a needed feature lands
+rust-version = "1.85"   # the 2024 edition floor; raise only when a needed feature lands
 license = "Apache-2.0 OR MIT"
 
 [workspace.lints]
 # Then in each member crate:
 # [lints]
 # workspace = true
+
+[workspace.dependencies]
+# one version per dependency; members write `serde = { workspace = true }`
 ```
 
+## Features and build scripts
+
+- **Features are additive.** Enabling a feature never removes an API or changes another feature's behavior, and `--all-features` always builds. Optional dependencies use `dep:` (`serde = ["dep:serde"]`) so no implicit feature leaks. Truly exclusive backends fail loudly: `#[cfg(all(feature = "a", feature = "b"))] compile_error!("features `a` and `b` are mutually exclusive");`.
+- **`build.rs` is deterministic.** Declare every input with `cargo::rerun-if-changed=` / `cargo::rerun-if-env-changed=`, write only under `OUT_DIR`, and never touch the network. A build script that reads undeclared inputs produces stale builds that pass locally and fail in CI.
+
 ## `rustfmt.toml`
 
 ```toml
@@ -156,11 +170,11 @@ Most options come from stable rustfmt. `imports_granularity` and `group_imports`
 # Reduce cognitive load thresholds.
 cognitive-complexity-threshold = 25
 type-complexity-threshold = 250
-too-many-arguments-threshold = 6
+too-many-arguments-threshold = 3   # SKILL.md Smell 2: more than 3 parameters is a smell
 too-many-lines-threshold = 100
 
 # msrv - keeps clippy from suggesting features past our MSRV
-msrv = "1.83"
+msrv = "1.85"
 
 # Avoid `panic` lint complaining about derived Debug impls calling unreachable_unchecked etc.
 allow-unwrap-in-tests = true
@@ -169,7 +183,7 @@ allow-panic-in-tests = true
 allow-dbg-in-tests = true
 allow-print-in-tests = true
 
-# Force named arguments above N params
+# At most 4 single-character bindings in scope
 single-char-binding-names-threshold = 4
 ```
 
@@ -257,6 +271,25 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - uses: taiki-e/install-action@nextest
       - run: cargo nextest run --all-targets --all-features --workspace
+      - run: cargo test --doc --all-features --workspace   # nextest does not run doctests
+
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - env:
+          RUSTDOCFLAGS: "-D warnings"   # broken intra-doc links fail the build
+        run: cargo doc --no-deps --all-features --workspace
+
+  msrv:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.85   # = rust-version
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo check --all-features --workspace
 
   miri:
     runs-on: ubuntu-latest
@@ -270,6 +303,9 @@ jobs:
       - env:
           MIRIFLAGS: "-Zmiri-strict-provenance -Zmiri-symbolic-alignment-check"
         run: cargo +nightly miri nextest run --all-features --workspace
+      - env:
+          MIRIFLAGS: "-Zmiri-tree-borrows -Zmiri-strict-provenance -Zmiri-symbolic-alignment-check"
+        run: cargo +nightly miri nextest run --all-features --workspace
 
   machete:
     runs-on: ubuntu-latest
@@ -312,6 +348,6 @@ After every change:
 ```bash
 cargo fmt --all -- --check && \
 cargo clippy --all-targets --all-features -- -D warnings && \
-cargo nextest run && \
+cargo nextest run && cargo test --doc && \
 cargo +nightly miri nextest run    # only if unsafe is involved
 ```

package/packages/shared-skills/skills/programming/references/rust/clap-stack.md

@@ -280,14 +280,19 @@ For automated tests, expose a `--non-interactive` flag and gate all prompts behi
 ## Structured output
 
 ```rust
+use std::io::Write as _;
+
+// `println!` panics when stdout is closed (`mytool | head -1`); writing to a
+// locked handle returns the error instead, so a broken pipe exits cleanly.
+let mut out = std::io::stdout().lock();
 match cli.format {
     OutputFormat::Json => {
-        serde_json::to_writer(std::io::stdout().lock(), &result)?;
-        println!();
+        serde_json::to_writer(&mut out, &result)?;
+        writeln!(out)?;
     }
     OutputFormat::Plain => {
         for row in &result.rows {
-            println!("{}\t{}\t{}", row.a, row.b, row.c);
+            writeln!(out, "{}\t{}\t{}", row.a, row.b, row.c)?;
         }
     }
     OutputFormat::Pretty => {