code review instructions for flutter + rust

codereview.md

check @AGENTS.md

Code Review Guidelines: Flutter + Rust (FRB) Bridge

This guide is designed for AI Agents performing automated code reviews on a Flutter library that utilizes flutter_rust_bridge (FRB). The goal is to ensure safety, performance, and seamless DX (Developer Experience) across the FFI boundary.

---

🛠 Review Methodology

1. Context: Compare the current branch against main.
2. Scope: Focus on lib/src/rust/, rust/src/, and the generated bridge_generated.dart / bridge_generated.rs files (to ensure they match).
3. Action: Categorize findings and provide a Fix Prompt that the agent can use to auto-remediate the issue.

---

🚦 Categorized Review Checklist

1. Critical Bugs & Safety

Priority: 🔴 High Focus on memory safety, panic handling, and async deadlocks.

• Rust Panics: Ensure no unwrap() or expect() is used in the Rust code. FRB handles Result types gracefully; panics can crash the Dart VM.
• Pointer Safety: Check for raw pointer manipulation without unsafe blocks or proper encapsulation.
• Async Overlap: Ensure DartAbi types are not being accessed across thread boundaries illegally.

Agent Fix Prompt: "Rewrite this Rust function to return a Result<T, anyhow::Error> instead of using .unwrap(), and ensure the Dart side handles the potential error."

---

2. Lints & Static Analysis

Priority: 🟡 Medium Adherence to the idiomatic styles of both languages.

• Crate Organization: Check if pub mod is exposed correctly for FRB discovery.
• Naming Conventions: Ensure Rust uses snake_case and Flutter uses lowerCamelCase, even for bridge-exposed methods.
• Unused Dependencies: Check Cargo.toml and pubspec.yaml for bloat.

Agent Fix Prompt: "Run cargo clippy --fix and dart fix --apply on the changed files and commit the suggestions."

---

3. Code Smells

Priority: 🟡 Medium Architectural issues that lead to technical debt.

• Large Data Transfers: Sending massive Vec<u8> or large strings across the bridge frequently. Suggest Stream or ExternalObject if applicable.
• Duplicate Logic: Validations happening in both Dart and Rust. Validation should ideally live in the "Source of Truth" (Rust).
• Generated File Tampering: Manual edits inside bridge_generated.dart. These will be overwritten.

Agent Fix Prompt: "Move this validation logic from the Dart wrapper into the Rust implementation to ensure a single source of truth and reduce bridge chatter."

---

4. DX (Developer Experience)

Priority: 🔵 Low How easy it is for a human to use this library.

• Missing Documentation: Exported Rust functions must have /// doc comments, which FRB carries over to Dart.
• Opaque Errors: Ensure String errors are replaced with specific Enums for better pattern matching in Dart.

Agent Fix Prompt: "Generate Dart-compatible doc comments for this Rust function based on its logic and parameters."

---

5. UX & Performance

Priority: 🟡 Medium Impact on the end-user application.

• Blocking the UI Thread: Long-running Rust functions should be async in Rust or called via an isolate-heavy task to prevent frame drops in Flutter.
• Initialization Latency: Check if the Rust library initialization (RustLib.init()) is blocking the app startup unnecessarily.

---

📊 Summary Table for Agents

Category	Priority	Focus Area	Fix Strategy
Bugs	🔴 High	Panics, Memory, Sync	Wrap in Result, avoid unwrap
Smells	🟡 Medium	Data Bloat, Duplication	Use Streams, move logic to Rust
Lints	🟡 Medium	Naming, Formatting	clippy, dart format
DX	🔵 Low	Docs, Error Enums	Add /// comments, use Enums
UX	🟡 Medium	UI Jank, Latency	Move to async Rust functions

---

screen-20260304-085017.mp4