Refactor unwrap and expect propagation; pluggable server plumbing

.markdownlint-cli2.jsonc

@@ -1,12 +1,14 @@
 {
-  // Ignore MD013 (line length) inside tables since reflowing
-  // Markdown tables often breaks formatting and readability.
   "config": {
+    "MD004": { "style": "dash" },
+    "MD010": { "code_blocks": false },
     "MD013": {
       "line_length": 80,
       "code_block_line_length": 120,
-      "tables": false
+      "tables": false,
+      "headings": false
     },
-    "MD040": false
-  }
+    "MD029": { "style": "ordered" }
+  },
+  "ignores": ["**/.venv/**", ".node_modules/**", "**/node_modules/**", "**/target/**"]
 }

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Code Style and Structure
 
-- **Code is for humans.** Write your code with clarity and empathy—assume a
+- **Code is for humans.** Write code with clarity and empathy—assume a
   tired teammate will need to debug it at 3 a.m.
 - **Comment *why*, not *what*.** Explain assumptions, edge cases, trade-offs, or
   complexity. Don't echo the obvious.
@@ -43,8 +43,10 @@
   relevant file(s) in the `docs/` directory to reflect the latest state.
   **Ensure the documentation remains accurate and current.**
 - Documentation must use en-GB-oxendict ("-ize" / "-yse" / "-our") spelling
-  and grammar. (EXCEPTION: the naming of the "LICENSE" file, which is to be
-  left unchanged for community consistency.)
+ and grammar. (EXCEPTION: the filename `LICENSE` is left unchanged for
+ community consistency.)
+- A documentation style guide is provided at
+  `docs/documentation-style-guide.md`.
 
 ## Change Quality & Committing
 
@@ -68,7 +70,7 @@
     - **Imperative Mood:** Use the imperative mood in the subject line (e.g.,
       "Fix bug", "Add feature" instead of "Fixed bug", "Added feature").
     - **Subject Line:** The first line should be a concise summary of the change
-      (ideally 50 characters or less).
+      (ideally 50 characters or fewer).
     - **Body:** Separate the subject from the body with a blank line. Subsequent
       lines should explain the *what* and *why* of the change in more detail,
       including rationale, goals, and scope. Wrap the body at 72 characters.
@@ -79,7 +81,7 @@
 ## Refactoring Heuristics & Workflow
 
 - **Recognizing Refactoring Needs:** Regularly assess the codebase for potential
-  refactoring opportunities. Consider refactoring when you observe:
+  refactoring opportunities. Perform refactoring when you observe:
   - **Long Methods/Functions:** Functions or methods that are excessively long
     or try to do too many things.
   - **Duplicated Code:** Identical or very similar code blocks appearing in
@@ -103,7 +105,7 @@
 - **Separate Atomic Refactors:** If refactoring is deemed necessary:
   - Perform the refactoring as a **separate, atomic commit** *after* the
     functional change commit.
-  - Ensure the refactoring adheres to the testing guidelines (behavioral tests
+  - Ensure refactoring adheres to the testing guidelines (behavioural tests
     pass before and after, unit tests added for new units).
   - Ensure the refactoring commit itself passes all quality gates.
 
@@ -114,26 +116,26 @@ management. Contributors should follow these best practices when working on the
 project:
 
 - Run `make check-fmt`, `make lint`, and `make test` before committing. These
-  targets wrap the following commands so contributors understand the exact
+  targets wrap the following commands, so contributors understand the exact
   behaviour and policy enforced:
   - `make check-fmt` executes:
 
-    ```
+    ```sh
     cargo fmt --workspace -- --check
     ```
 
     validating formatting across the entire workspace without modifying files.
   - `make lint` executes:
 
-    ```
+    ```sh
     cargo clippy --workspace --all-targets --all-features -- -D warnings
     ```
 
     linting every target with all features enabled and denying all Clippy
     warnings.
   - `make test` executes:
 
-    ```
+    ```sh
     cargo test --workspace
     ```
 
@@ -147,40 +149,34 @@ project:
   adhering to separation of concerns and CQRS.
 - Where a function has too many parameters, group related parameters in
   meaningfully named structs.
-- Where a function is returning a large error consider using `Arc` to reduce the
-  amount of data returned.
+- Where a function is returning a large error, consider using `Arc` to reduce
+  the amount of data returned.
 - Write unit and behavioural tests for new functionality. Run both before and
   after making any change.
 - Every module **must** begin with a module level (`//!`) comment explaining the
   module's purpose and utility.
 - Document public APIs using Rustdoc comments (`///`) so documentation can be
   generated with cargo doc.
 - Prefer immutable data and avoid unnecessary `mut` bindings.
-- Handle errors with the `Result` type instead of panicking where feasible.
 - Use explicit version ranges in `Cargo.toml` and keep dependencies up-to-date.
-- Avoid `unsafe` code unless absolutely necessary and document any usage
-  clearly.
+- Avoid `unsafe` code unless absolutely necessary, and document any usage
+  clearly with a "SAFETY" comment.
 - Place function attributes **after** doc comments.
 - Do not use `return` in single-line functions.
 - Use predicate functions for conditional criteria with more than two branches.
 - Lints must not be silenced except as a **last resort**.
 - Lint rule suppressions must be tightly scoped and include a clear reason.
-- Prefer `expect` over `allow`.
-- Use `rstest` fixtures for shared setup.
-- Replace duplicated tests with `#[rstest(...)]` parameterised cases.
-- Prefer `mockall` for mocks/stubs.
-- Prefer `.expect()` over `.unwrap()`.
 - Use `concat!()` to combine long string literals rather than escaping newlines
   with a backslash.
-- Prefer single line versions of functions where appropriate. I.e.,
+- Prefer single line versions of functions where appropriate. i.e.,
 
-  ```
+  ```rust
   pub fn new(id: u64) -> Self { Self(id) }
   ```
 
   Instead of:
 
-  ```
+  ```rust
   pub fn new(id: u64) -> Self {
       Self(id)
   }
@@ -190,16 +186,30 @@ project:
   `newt-hype` when introducing many homogeneous wrappers that share behaviour;
   add small shims such as `From<&str>` and `AsRef<str>` for string-backed
   wrappers. For path-centric wrappers implement `AsRef<Path>` alongside
-  `into_inner()` and `to_path_buf()`; avoid attempting
+  `into_inner()` and `to_path_buf()`, avoid attempting
   `impl From<Wrapper> for PathBuf` because of the orphan rule. Prefer explicit
   tuple structs whenever bespoke validation or tailored trait surfaces are
-  required, customising `Deref`, `AsRef`, and `TryFrom` per type. Use
+  required, customizing `Deref`, `AsRef`, and `TryFrom` per type. Use
   `the-newtype` when defining traits and needing blanket implementations that
   apply across wrappers satisfying `Newtype + AsRef/AsMut<Inner>`, or when
   establishing a coherent internal convention that keeps trait forwarding
   consistent without per-type boilerplate. Combine approaches: lean on
   `newt-hype` for the common case, tuple structs for outliers, and
-  `the-newtype` to unify behaviour when you own the trait definitions.
+  `the-newtype` to unify behaviour when owning the trait definitions.
+- Use `cap_std` and `cap_std::fs_utf8` / `camino` in place of `std::fs` and
+  `std::path` for enhanced cross-platform support and capability-oriented
+  filesystem access.
+
+### Testing
+
+- Use `rstest` fixtures for shared setup.
+- Replace duplicated tests with `#[rstest(...)]` parameterized cases.
+- Prefer `mockall` for ad hoc mocks/stubs.
+- For testing of functionality depending upon environment variables, dependency
+  injection and the `mockable` crate are the preferred option.
+- If mockable cannot be used, env mutations in tests MUST be wrapped in shared
+  guards and mutexes placed in a shared `test_utils` or `test_helpers` crate.
+  Direct environment mutation is FORBIDDEN in tests.
 
 ### Dependency Management
 
@@ -225,6 +235,18 @@ project:
 - **Never export the opaque type from a library**. Convert to domain enums at
   API boundaries, and to `eyre` only in the main `main()` entrypoint or
   top-level async task.
+- In tests, prefer `.expect(...)` over `.unwrap()` to surface clearer failure
+  diagnostics.
+- In production code and shared fixtures, avoid `.expect()` entirely: return
+  `Result` and use `?` to propagate errors instead of panicking.
+- Keep `expect_used` **strict**; do not suppress the lint.
+- Recognize that `allow-expect-in-tests = true` **doesn’t cover** helpers
+  outside `#[cfg(test)]` or `#[test]`; avoid `expect` in such fixtures.
+- Use `anyhow`/`eyre` with `.context(...)` to **preserve backtraces** and
+  provide clear, typed failure paths.
+- Update helpers (e.g., `set_dir`) to **return errors** rather than panicking.
+- Consume fallible fixtures in `rstest` by **making the test return `Result`**
+  and applying `?` to the fixture.
 
 ## Markdown Guidance
 
@@ -243,39 +265,39 @@ project:
 
 The following tooling is available in this environment:
 
-- `mbake` – A Makefile validator. Run using `mbake validate Makefile`.
-- `strace` – Traces system calls and signals made by a process; useful for
+- `mbake` — A Makefile validator. Run using `mbake validate Makefile`.
+- `strace` — Traces system calls and signals made by a process; useful for
   debugging runtime behaviour and syscalls.
-- `gdb` – The GNU Debugger, for inspecting and controlling programs as they
+- `gdb` — The GNU Debugger, for inspecting and controlling programs as they
   execute (or post-mortem via core dumps).
-- `ripgrep` – Fast, recursive text search tool (`grep` alternative) that
+- `ripgrep` — Fast, recursive text search tool (`grep` alternative) that
   respects `.gitignore` files.
-- `ltrace` – Traces calls to dynamic library functions made by a process.
-- `valgrind` – Suite for detecting memory leaks, profiling, and debugging
+- `ltrace` — Traces calls to dynamic library functions made by a process.
+- `valgrind` — Suite for detecting memory leaks, profiling, and debugging
   low-level memory errors.
-- `bpftrace` – High-level tracing tool for eBPF, using a custom scripting
+- `bpftrace` — High-level tracing tool for eBPF, using a custom scripting
   language for kernel and application tracing.
-- `lsof` – Lists open files and the processes using them.
-- `htop` – Interactive process viewer (visual upgrade to `top`).
-- `iotop` – Displays and monitors I/O usage by processes.
-- `ncdu` – NCurses-based disk usage viewer for finding large files/folders.
-- `tree` – Displays directory structure as a tree.
-- `bat` – `cat` clone with syntax highlighting, Git integration, and paging.
-- `delta` – Syntax-highlighted pager for Git and diff output.
-- `tcpdump` – Captures and analyses network traffic at the packet level.
-- `nmap` – Network scanner for host discovery, port scanning, and service
+- `lsof` — Lists open files and the processes using them.
+- `htop` — Interactive process viewer (visual upgrade to `top`).
+- `iotop` — Displays and monitors I/O usage by processes.
+- `ncdu` — NCurses-based disk usage viewer for finding large files/folders.
+- `tree` — Displays directory structure as a tree.
+- `bat` — `cat` clone with syntax highlighting, Git integration, and paging.
+- `delta` — Syntax-highlighted pager for Git and diff output.
+- `tcpdump` — Captures and analyses network traffic at the packet level.
+- `nmap` — Network scanner for host discovery, port scanning, and service
   identification.
-- `lldb` – LLVM debugger, alternative to `gdb`.
-- `eza` – Modern `ls` replacement with more features and better defaults.
-- `fzf` – Interactive fuzzy finder for selecting files, commands, etc.
-- `hyperfine` – Command-line benchmarking tool with statistical output.
-- `shellcheck` – Linter for shell scripts, identifying errors and bad practices.
-- `fd` – Fast, user-friendly `find` alternative with sensible defaults.
-- `checkmake` – Linter for `Makefile`s, ensuring they follow best practices and
+- `lldb` — LLVM debugger, alternative to `gdb`.
+- `eza` — Modern `ls` replacement with more features and better defaults.
+- `fzf` — Interactive fuzzy finder for selecting files, commands, etc.
+- `hyperfine` — Command-line benchmarking tool with statistical output.
+- `shellcheck` — Linter for shell scripts, identifying errors and bad practices.
+- `fd` — Fast, user-friendly `find` alternative with sensible defaults.
+- `checkmake` — Linter for `Makefile`s, ensuring they follow best practices and
   conventions.
-- `srgn` – [Structural grep](https://github.com/alexpovel/srgn), searches code
+- `srgn` — [Structural grep](https://github.com/alexpovel/srgn), searches code
   and enables editing by syntax tree patterns.
-- `difft` **(Difftastic)** – Semantic diff tool that compares code structure
+- `difft` **(Difftastic)** — Semantic diff tool that compares code structure
   rather than just text differences.
 
 ## Key Takeaway

Cargo.toml

@@ -39,10 +39,10 @@ log = "0.4.28"
 dashmap = "6.1.0"
 leaky-bucket = "1.1.2"
 tracing = { version = "0.1.41", features = ["log", "log-always"] }
-tracing-subscriber = "0.3"
+tracing-subscriber = "0.3.18"
 metrics = { version = "0.24.2", optional = true }
 thiserror = "2.0.16"
-static_assertions = "1"
+static_assertions = "1.1.0"
 derive_more = { version = "2.0.1", features = ["display", "from"] }
 
 [dev-dependencies]
@@ -85,11 +85,45 @@ cucumber-tests = []
 test-support = []
 
 [lints.clippy]
-pedantic = "warn"
+pedantic = { level = "warn", priority = -1 }
+
+# 1. hygiene
+allow_attributes = "deny"
+allow_attributes_without_reason = "deny"
+blanket_clippy_restriction_lints = "deny"
+cognitive_complexity = "deny"
+needless_pass_by_value = "deny"
+implicit_hasher = "deny"
+
+# 2. debugging leftovers
+dbg_macro = "deny"
+print_stdout = "deny"
+print_stderr = "deny"
+
+# 3. panic-prone operations
+unwrap_used = "deny"
+expect_used = "deny"
+indexing_slicing = "deny"
+string_slice = "deny"
+integer_division = "deny"
+integer_division_remainder_used = "deny"
+panic_in_result_fn = "deny"
+unreachable = "deny"
 
 [lints.rust]
+unknown_lints = "deny"
+renamed_and_removed_lints = "deny"
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(loom)'] }
 
+[lints.rustdoc]
+missing_crate_level_docs = "deny"
+broken_intra_doc_links = "deny"
+private_intra_doc_links = "deny"
+bare_urls = "deny"
+invalid_html_tags = "deny"
+invalid_codeblock_attributes = "deny"
+unescaped_backticks = "deny"
+
 [[example]]
 name = "echo"
 path = "examples/echo.rs"

Makefile

@@ -4,6 +4,7 @@ CRATE ?= wireframe
 CARGO ?= cargo
 BUILD_JOBS ?=
 CLIPPY_FLAGS ?= --all-targets --all-features -- -D warnings
+RUSTDOC_FLAGS ?= --cfg docsrs -D warnings
 MDLINT ?= markdownlint
 NIXIE ?= nixie
 
@@ -29,6 +30,7 @@ target/%/lib$(CRATE).rlib: ## Build library in debug or release
 	  $@
 
 lint: ## Run Clippy with warnings denied
+	RUSTDOCFLAGS="$(RUSTDOC_FLAGS)" $(CARGO) doc --no-deps
 	$(CARGO) clippy $(CLIPPY_FLAGS)
 
 fmt: ## Format Rust and Markdown sources

clippy.toml

@@ -0,0 +1,7 @@
+# Align with CodeScene’s ceiling
+cognitive-complexity-threshold = 9     # default is 25 
+too-many-arguments-threshold = 4       # default is 7
+too-many-lines-threshold = 70          # default is 100
+excessive-nesting-threshold = 4        # default is off
+
+allow-expect-in-tests = true

examples/async_stream.rs

@@ -6,6 +6,7 @@
 
 use async_stream::try_stream;
 use futures::StreamExt;
+use tracing::info;
 use wireframe::response::Response;
 
 #[derive(bincode::Encode, bincode::BorrowDecode, Debug, PartialEq)]
@@ -22,10 +23,12 @@ fn stream_response() -> Response<Frame> {
 
 #[tokio::main]
 async fn main() {
+    tracing_subscriber::fmt::init();
+
     let Response::Stream(mut stream) = stream_response() else {
         return;
     };
     while let Some(Ok(frame)) = stream.next().await {
-        println!("received frame: {frame:?}");
+        info!(?frame, "received frame");
     }
 }