# Best Practices Audit — Cleanup Findings

> Generated by monkey swarm on 2026-06-30. Four specialist auditors reviewed `runtime`, `codegen`, `roto-tonic`, and project-level structure.

## Summary

| Severity | Count |
|----------|-------|
| Critical | 9 |
| Major | 17 |
| Minor | ~40 |

---

## Critical Issues

### 1. `BufMutBuilder` panics instead of returning `Err` (`runtime`)
- **File:** `runtime/src/lib.rs:1038-1119`
- **Issue:** `BufMutBuilder` returns `Result<()>` on all write methods, but calls `put_slice` which panics if the underlying `BufMut` has no remaining capacity. Unlike `ProtoBuilder`, which checks bounds before every write, `BufMutBuilder` never actually produces an `Err`.
- **Fix:** Check `self.buf.remaining_mut()` before each `put_slice` and return `Err(RotoError::BufferOverflow)`, or remove the `Result` return type and document the panic contract.

### 2. `#![no_std]` + feature flags don't match reality (`runtime`)
- **File:** `runtime/src/lib.rs:1`, `runtime/Cargo.toml:9-12`
- **Issue:** Crate declares `#![no_std]` but has unconditional `use bytes::BufMut`. The `bytes` crate requires `alloc` (and transitively `std`). The `alloc` and `std` feature flags exist but don't gate any code. The crate can't compile in `no_std` mode.
- **Fix:** Gate `bytes` behind `#[cfg(feature = "alloc")]` or remove the feature flags and document that the crate requires `std`.

### 3. `types.rs` file corruption (`codegen`)
- **File:** `codegen/src/generator/types.rs:76`
- **Issue:** Line 76 contains a shell artifact (`EOF > /opt/workspace/codegen/src/generator/types.rs`) followed by a duplicated function body. The file likely won't compile.
- **Fix:** Clean up the file immediately.

### 4. Massive code duplication in generator module (`codegen`)
- **File:** `codegen/src/generator/` (all files)
- **Issue:** `mod.rs` contains full implementations of `write_message`, `write_enum`, `write_service`, `map_type_to_rust_accessor`, `to_pascal_case`, `to_snake_case`, `DATA_IMPORTS` — all of which also exist in `messages.rs`, `services.rs`, `types.rs`, and `utils.rs`. Only the `mod.rs` versions appear to be used.
- **Fix:** Either delete the split files (if `mod.rs` is the single source of truth) or complete the refactor so `mod.rs` re-exports the split modules.

### 5. ~50 `.expect()` panics in library generator code (`codegen`)
- **File:** `codegen/src/generator/mod.rs` (all generator functions)
- **Issue:** Malformed protos will crash the process instead of returning errors.
- **Fix:** Introduce a `GeneratorError` enum and return `Result<Vec<…>, GeneratorError>` from all generator functions.

### 6. Seven unused heavy dependencies in codegen (`codegen`)
- **File:** `codegen/Cargo.toml`
- **Issue:** `tonic`, `tower`, `bytes`, `http-body`, `http-body-util`, `tokio-stream`, `futures-util` are listed as dependencies but never used in the codegen library. They generate code that references these types via string literals — the generator itself doesn't need them.
- **Fix:** Remove these from `Cargo.toml`. This eliminates ~30+ transitive dependencies.

### 7. Edition 2024 / resolver = "3" requires nightly (`workspace`)
- **File:** `Cargo.toml:16`, all crate `Cargo.toml`
- **Issue:** `resolver = "3"` is only valid for Edition 2024, which is not yet stable. No `rust-toolchain.toml` exists. This blocks adoption with stable Rust.
- **Fix:** Add `rust-toolchain.toml` with `channel = "nightly"`, or switch to `edition = "2021"` + `resolver = "2"`.

### 8. No LICENSE file (`workspace`)
- **Issue:** The project cannot legally be used by others without a license.
- **Fix:** Add an MIT or Apache-2.0 license file.

### 9. `StatusBody::new` dead parameter (`roto-tonic`)
- **File:** `roto-tonic/src/lib.rs:118-125`
- **Issue:** `StatusBody::new(data, status)` takes `status: u8` but never uses it. The code hardcodes `"0"` into the `grpc-status` trailer.
- **Fix:** Wire `status` into the trailer value, or remove the parameter.

---

## Major Issues

### Runtime

| # | Issue | File | Fix |
|---|-------|------|-----|
| 1 | `RotoMessage::decode(bytes::Bytes)` forces heap allocation and blocks `no_std` | `lib.rs:74-77` | Accept `&[u8]` instead |
| 2 | 7 core public types lack doc comments (`MapFieldIterator`, `RotoOwned`, `RotoMessage`, `ProtoAccessor`, `ProtoBuilder`, `BufMutBuilder`, `FieldIterator`, `RepeatedFieldIterator`) | `lib.rs` | Add `///` doc comments |

### Codegen

| # | Issue | File | Fix |
|---|-------|------|-----|
| 3 | `codegen/src/runtime/mod.rs` duplicates `roto-runtime` types (RotoError, Tag, WireType, read_varint, etc.) | `src/runtime/mod.rs` | Remove the duplicate; depend on `roto-runtime` |
| 4 | `to_pascal_case` has two implementations with different case-handling behavior | `mod.rs:28-38` vs `utils.rs` | Consolidate to single canonical version |
| 5 | `test_oneofs.rs` is completely empty — tests nothing | `tests/test_oneofs.rs` | Implement or remove |
| 6 | All integration tests use hardcoded `/tmp/` paths — won't run in parallel or on Windows | `tests/` | Use `std::env::temp_dir()` or `tempfile` |

### Roto-tonic

| # | Issue | File | Fix |
|---|-------|------|-----|
| 7 | `BufferPool::get()` / `put()` call `.unwrap()` on `Mutex::lock()` — aborts on poison | `src/lib.rs:96-109` | Handle poison state or use `tokio::sync::Mutex` |
| 8 | Generated traits use native async (Edition 2024), but test impls use `#[tonic::async_trait]` — ABI mismatch | `src/generated/` + `tests/` | Remove `#[tonic::async_trait]` from test impls |
| 9 | `.unwrap()` on `Response::builder().body()` in 7+ places — panics in hot path | `src/generated/` | Use `.expect()` or extract a helper |
| 10 | Missing `cargo:rerun-if-changed` for `.proto` files — changes don't trigger rebuild | `build.rs` | Add rerun directives |
| 11 | `build.rs` hardcodes `target/debug/protoc-gen-roto` — breaks release and cross-compile | `build.rs` | Use `OUT_DIR` or workspace-level coordination |
| 12 | `tokio = { features = ["full"] }` pulls all subsystems for a library that only needs `net` | `Cargo.toml` | Move to `[dev-dependencies]` |
| 13 | `RotoDecoder::decode` converts all errors to `Status::internal()` — no mapping of error variants | `src/lib.rs:78` | Match `RotoError` variants to specific gRPC status codes |
| 14 | `StatusBody` fields are `pub` — breaks encapsulation | `src/lib.rs:112-126` | Make fields private; add consumer methods |

### Project Structure

| # | Issue | File | Fix |
|---|-------|------|-----|
| 15 | No `[workspace.dependencies]` — shared deps duplicated across crates, risking version drift | `Cargo.toml` | Define workspace-level dependency table |
| 16 | `interop_test.rs` asserts `is_ok()` on `UNIMPLEMENTED` call — tests wrong behavior | `tests/interop_test.rs` | Assert `is_err()` with `UNIMPLEMENTED` status |
| 17 | No CI configuration, no `clippy.toml`, no `.rustfmt.toml` — code quality not enforced | Project root | Add GitHub Actions + config files |
| 18 | `roto/roto/` stray directory and `grpc_bench/` empty submodule | Project root | Clean up stale directories |
| 19 | `panic = "abort"` in `[profile.dev]` is too aggressive for a library | `Cargo.toml` | Remove from dev profile; keep only in release |
| 20 | `protos/` crate has no purpose (single `hello()` function) | `protos/` | Remove or give it a real purpose |

---

## Minor Issues (Selected)

### Runtime
- `ProtoAccessor::new` returns `Result` but never fails — change to direct constructor
- `write_int32` doesn't use zigzag encoding — document this or add `write_sint32`
- `RepeatedFieldIterator::new_range` silently tolerates out-of-bounds ranges
- Tests gated behind `#[cfg(feature = "alloc")]` may be silently skipped
- `RotoError` lacks `source()` chaining — consider `thiserror`

### Codegen
- Missing `#[must_use]` on public generator functions
- No crate-level or function-level documentation
- Magic numbers for protobuf field types/labels (1-18)
- `env_logger::init()` is deprecated — use `init_from_env()`
- `edition = "2024"` without `rust-version` key
- Utility functions (`to_pascal_case`, `to_snake_case`) are `pub` but should be `pub(crate)`

### Roto-tonic
- `#![allow(unused, ...)]` blanket suppresses important lints in generated code
- `tokio::time::sleep(100ms)` race condition in `test_server_start`
- Server task spawned but never joined/aborted in `interop_test.rs`
- Missing `#[derive(Debug)]` on `BufferPool`, `StatusBody`
- Error response body `[0, 0, 0, 0, 0]` should be a named constant
- `Infallible` error type hides panic sites

### Project
- `exclude` list incomplete — test temp dirs not listed
- `Cargo.lock` should be committed (it is, but no `.gitignore` exception)
- `.desc` files may be generated artifacts that should be regenerated, not checked in
- No `rust-toolchain.toml` despite Edition 2024 requirement
- No `[workspace.metadata]` for crates.io readiness
- `alloc` feature flag on `codegen` and `benches` is meaningless for CLI/benchmark crates

---

## Positive Observations

The project has several strengths:

- **Zero `unsafe` code** — all memory operations in the runtime use safe slice indexing
- **Consistent error handling** — all fallible operations return `Result<T, RotoError>`
- **No panics in library code** — `unwrap()`/`expect()` appear only in tests
- **RevBuilder** is a creative, well-implemented design for reverse-direction encoding
- **18 unit tests** in the runtime with good edge-case coverage
- **Comprehensive README** with design rationale, API examples, and benchmark comparisons
- **Well-structured workspace** with clear crate boundaries