@canonical/code-standards 0.1.0 → 0.1.2

package/docs/rust.md

@@ -6,15 +6,9 @@ Standards for rust development.
 
 Use monadic Result chaining with the ? operator and combinators like and_then, map, and or_else for clean, composable error handling. This is the Rust equivalent of Haskell's do-notation for the Either monad.
 
-**Ratings:**
-- Impact: A (cleaner control flow, eliminates nested matches)
-- Feasibility: S (already natural in Rust)
-- Idiomaticity: S (idiomatic Rust; ? operator is standard)
-- FP Purity: S (direct monadic composition / Kleisli arrows)
-
 ### Do
 
-(Do) Use the ? operator for clean Result propagation.
+Use the ? operator for clean Result propagation.
 ```rust
 fn load_project_graph() -> Result<(SemStore, Vec<PackageGraph>), GraphError> {
     let project_root = find_project_root()
@@ -38,7 +32,7 @@ fn load_project_graph() -> Result<(SemStore, Vec<PackageGraph>), GraphError> {
 }
 ```
 
-(Do) Use and_then for dependent computations.
+Use and_then for dependent computations.
 ```rust
 fn process_user_input(input: &str) -> Result<Output, ProcessError> {
     parse_input(input)
@@ -48,7 +42,7 @@ fn process_user_input(input: &str) -> Result<Output, ProcessError> {
 }
 ```
 
-(Do) Use map for infallible transformations within Result.
+Use map for infallible transformations within Result.
 ```rust
 fn get_package_names(path: &Path) -> Result<Vec<String>, IoError> {
     fs::read_dir(path)?
@@ -67,7 +61,7 @@ fn get_config_value(key: &str) -> Result<String, ConfigError> {
 }
 ```
 
-(Do) Use or_else for fallback computations.
+Use or_else for fallback computations.
 ```rust
 fn find_config() -> Result<Config, ConfigError> {
     load_config_from_env()
@@ -76,7 +70,7 @@ fn find_config() -> Result<Config, ConfigError> {
 }
 ```
 
-(Do) Combine multiple Results with the ? operator in sequence.
+Combine multiple Results with the ? operator in sequence.
 ```rust
 fn setup_application() -> Result<App, SetupError> {
     let config = load_config()?;
@@ -90,7 +84,7 @@ fn setup_application() -> Result<App, SetupError> {
 
 ### Don't
 
-(Don't) Use nested match expressions for Result handling.
+Use nested match expressions for Result handling.
 ```rust
 // Bad: Deeply nested, hard to follow
 fn process(input: &str) -> Result<Output, Error> {
@@ -111,7 +105,7 @@ fn process(input: &str) -> Result<Output, Error> {
 }
 ```
 
-(Don't) Use unwrap() or expect() to bypass error handling.
+Use unwrap() or expect() to bypass error handling.
 ```rust
 // Bad: Panics on error
 fn load_data() -> Data {
@@ -120,7 +114,7 @@ fn load_data() -> Data {
 }
 ```
 
-(Don't) Ignore errors silently.
+Ignore errors silently.
 ```rust
 // Bad: Errors are silently dropped
 fn try_save(data: &Data) {
@@ -128,7 +122,7 @@ fn try_save(data: &Data) {
 }
 ```
 
-(Don't) Convert all errors to strings early in the chain.
+Convert all errors to strings early in the chain.
 ```rust
 // Bad: Loses error type information
 fn process() -> Result<(), String> {
@@ -144,15 +138,9 @@ fn process() -> Result<(), String> {
 
 Always enrich errors with contextual information such as file paths, operation names, and relevant state. This dramatically improves debugging experience and follows the principle of errors as values.
 
-**Ratings:**
-- Impact: S (dramatically improves debugging experience)
-- Feasibility: A (thiserror + map_err pattern already established)
-- Idiomaticity: S (Rust community best practice)
-- FP Purity: B (error as value; monadic error propagation)
-
 ### Do
 
-(Do) Use thiserror to create structured, contextual error types.
+Use thiserror to create structured, contextual error types.
 ```rust
 use thiserror::Error;
 use std::path::PathBuf;
@@ -183,7 +171,7 @@ pub enum GraphError {
 }
 ```
 
-(Do) Use map_err to add context when propagating errors.
+Use map_err to add context when propagating errors.
 ```rust
 fn load_package(path: &Path) -> Result<Package, GraphError> {
     let content = fs::read_to_string(path)
@@ -202,7 +190,7 @@ fn load_package(path: &Path) -> Result<Package, GraphError> {
 }
 ```
 
-(Do) Chain errors to preserve the full error trail.
+Chain errors to preserve the full error trail.
 ```rust
 #[derive(Error, Debug)]
 pub enum AppError {
@@ -221,7 +209,7 @@ pub enum AppError {
 }
 ```
 
-(Do) Include actionable information in error messages.
+Include actionable information in error messages.
 ```rust
 #[derive(Error, Debug)]
 pub enum ValidationError {
@@ -235,7 +223,7 @@ pub enum ValidationError {
 
 ### Don't
 
-(Don't) Use generic string errors that lose context.
+Use generic string errors that lose context.
 ```rust
 // Bad: Loses type information and context
 fn load_config(path: &Path) -> Result<Config, String> {
@@ -247,7 +235,7 @@ fn load_config(path: &Path) -> Result<Config, String> {
 }
 ```
 
-(Don't) Discard error information with unwrap or expect in library code.
+Discard error information with unwrap or expect in library code.
 ```rust
 // Bad: Panics instead of propagating
 fn parse_uri(s: &str) -> Uri {
@@ -258,7 +246,7 @@ fn parse_uri(s: &str) -> Uri {
 let file = File::open(path).expect("failed");  // Which path?
 ```
 
-(Don't) Create error types without Display or Debug.
+Create error types without Display or Debug.
 ```rust
 // Bad: Unusable error type
 pub struct MyError {
@@ -267,7 +255,7 @@ pub struct MyError {
 }
 ```
 
-(Don't) Use anyhow/eyre in library code (ok for applications).
+Use anyhow/eyre in library code (ok for applications).
 ```rust
 // Bad in libraries: Erases type information
 pub fn process() -> anyhow::Result<()> {
@@ -286,15 +274,9 @@ pub fn process() -> Result<(), ProcessError> {
 
 Structure functions as `A -> Result<B, E>` (Kleisli arrows) for composable, chainable transformations. This enables powerful composition patterns where each step can fail, following the monadic composition style from Haskell.
 
-**Ratings:**
-- Impact: B (enables powerful composition patterns)
-- Feasibility: B (requires thinking in terms of monadic pipelines)
-- Idiomaticity: A (natural with ? and and_then)
-- FP Purity: S (direct Kleisli arrow pattern)
-
 ### Do
 
-(Do) Design functions as Kleisli arrows: `A -> Result<B, E>`.
+Design functions as Kleisli arrows: `A -> Result<B, E>`.
 ```rust
 // Each function is a Kleisli arrow that can be composed
 fn parse_config(input: &str) -> Result<RawConfig, ParseError> { /* ... */ }
@@ -320,7 +302,7 @@ fn process_input(s: &str) -> Result<Output, ProcessError> {
 }
 ```
 
-(Do) Use combinators to compose fallible operations.
+Use combinators to compose fallible operations.
 ```rust
 impl DepSpec {
     pub fn from_value(value: &DependencyValue) -> Result<Self, ParseError> {
@@ -340,7 +322,7 @@ impl DepSpec {
 }
 ```
 
-(Do) Create helper traits for method chaining when needed.
+Create helper traits for method chaining when needed.
 ```rust
 trait ResultExt<T, E> {
     fn and_try<U, F>(self, f: F) -> Result<U, E>
@@ -364,7 +346,7 @@ let result = input
     .and_try(step3);
 ```
 
-(Do) Use the pipe pattern for readability.
+Use the pipe pattern for readability.
 ```rust
 // With a pipe trait or tap crate
 trait Pipe: Sized {
@@ -383,7 +365,7 @@ let result = input
 
 ### Don't
 
-(Don't) Mix side effects into pure transformation chains.
+Mix side effects into pure transformation chains.
 ```rust
 // Bad: Side effects hidden in chain
 fn process(input: &str) -> Result<Output, Error> {
@@ -406,7 +388,7 @@ fn process(input: &str) -> Result<Output, Error> {
 }
 ```
 
-(Don't) Break the chain with early returns when and_then works.
+Break the chain with early returns when and_then works.
 ```rust
 // Bad: Breaks the monadic flow
 fn process(input: &str) -> Result<Output, Error> {
@@ -431,7 +413,7 @@ fn process(input: &str) -> Result<Output, Error> {
 }
 ```
 
-(Don't) Use unwrap in the middle of a chain.
+Use unwrap in the middle of a chain.
 ```rust
 // Bad: Panics break the monadic abstraction
 let result = items.iter()
@@ -446,15 +428,9 @@ let result = items.iter()
 
 Prefer iterator combinators (map, filter, flat_map, collect) over imperative loops for data transformations. This functional style is more declarative, composable, and often more performant due to lazy evaluation and compiler optimizations.
 
-**Ratings:**
-- Impact: A (more declarative, composable, often faster)
-- Feasibility: A (Rust iterators are excellent)
-- Idiomaticity: S (core Rust idiom)
-- FP Purity: S (direct FP; lazy evaluation, composable)
-
 ### Do
 
-(Do) Use iterator chains for data transformations.
+Use iterator chains for data transformations.
 ```rust
 fn get_installed_packages() -> Result<Vec<String>, IoError> {
     let packages_path = sem_packages_dir()?;
@@ -478,7 +454,7 @@ fn get_installed_packages() -> Result<Vec<String>, IoError> {
 }
 ```
 
-(Do) Use flat_map for one-to-many transformations.
+Use flat_map for one-to-many transformations.
 ```rust
 fn get_all_dependencies(packages: &[Package]) -> Vec<Dependency> {
     packages.iter()
@@ -487,7 +463,7 @@ fn get_all_dependencies(packages: &[Package]) -> Vec<Dependency> {
 }
 ```
 
-(Do) Use filter_map to combine filter and map operations.
+Use filter_map to combine filter and map operations.
 ```rust
 fn parse_valid_numbers(strings: &[&str]) -> Vec<i32> {
     strings.iter()
@@ -496,7 +472,7 @@ fn parse_valid_numbers(strings: &[&str]) -> Vec<i32> {
 }
 ```
 
-(Do) Use fold/reduce for accumulating results.
+Use fold/reduce for accumulating results.
 ```rust
 fn total_size(files: &[PathBuf]) -> u64 {
     files.iter()
@@ -511,7 +487,7 @@ fn merge_configs(configs: &[Config]) -> Config {
 }
 ```
 
-(Do) Chain multiple operations for complex transformations.
+Chain multiple operations for complex transformations.
 ```rust
 fn process_log_entries(entries: &[LogEntry]) -> HashMap<String, Vec<&LogEntry>> {
     entries.iter()
@@ -526,7 +502,7 @@ fn process_log_entries(entries: &[LogEntry]) -> HashMap<String, Vec<&LogEntry>>
 }
 ```
 
-(Do) Use collect with turbofish for type-driven collection.
+Use collect with turbofish for type-driven collection.
 ```rust
 // Collect into different types based on need
 let vec: Vec<_> = iter.collect();
@@ -541,7 +517,7 @@ let results: Result<Vec<_>, _> = items.iter()
 
 ### Don't
 
-(Don't) Use imperative loops when combinators are clearer.
+Use imperative loops when combinators are clearer.
 ```rust
 // Bad: Imperative style obscures intent
 fn get_names(users: &[User]) -> Vec<String> {
@@ -563,7 +539,7 @@ fn get_names(users: &[User]) -> Vec<String> {
 }
 ```
 
-(Don't) Collect intermediate results unnecessarily.
+Collect intermediate results unnecessarily.
 ```rust
 // Bad: Unnecessary allocation
 let filtered: Vec<_> = items.iter().filter(|x| x.valid).collect();
@@ -577,7 +553,7 @@ let result: i32 = items.iter()
     .sum();
 ```
 
-(Don't) Use for loops just to build up a Vec.
+Use for loops just to build up a Vec.
 ```rust
 // Bad: Manual Vec building
 let mut results = Vec::new();
@@ -589,7 +565,7 @@ for item in items {
 let results: Vec<_> = items.iter().map(transform).collect();
 ```
 
-(Don't) Nest loops when flat_map works.
+Nest loops when flat_map works.
 ```rust
 // Bad: Nested loops
 let mut all_items = Vec::new();
@@ -611,15 +587,9 @@ let all_items: Vec<_> = containers.iter()
 
 Use Option explicitly and idiomatically; prefer Option<T> combinators (map, and_then, unwrap_or, ok_or) over null-like patterns. Option is Rust's Maybe monad - use it as such.
 
-**Ratings:**
-- Impact: A (eliminates null-related bugs)
-- Feasibility: S (Rust enforces this)
-- Idiomaticity: S (fundamental Rust pattern)
-- FP Purity: S (Maybe monad equivalent)
-
 ### Do
 
-(Do) Use Option combinators for clean transformations.
+Use Option combinators for clean transformations.
 ```rust
 impl Manifest {
     pub fn display_name(&self) -> Option<String> {
@@ -638,7 +608,7 @@ impl Manifest {
 }
 ```
 
-(Do) Use unwrap_or and unwrap_or_else for defaults.
+Use unwrap_or and unwrap_or_else for defaults.
 ```rust
 fn get_config_value(key: &str) -> String {
     config.get(key)
@@ -654,7 +624,7 @@ fn get_timeout() -> Duration {
 }
 ```
 
-(Do) Use ok_or to convert Option to Result.
+Use ok_or to convert Option to Result.
 ```rust
 fn find_package(name: &str) -> Result<&Package, PackageError> {
     packages.get(name)
@@ -667,7 +637,7 @@ fn get_required_field<'a>(map: &'a HashMap<String, Value>, key: &str) -> Result<
 }
 ```
 
-(Do) Use filter and filter_map for conditional processing.
+Use filter and filter_map for conditional processing.
 ```rust
 fn find_active_user(id: UserId) -> Option<User> {
     users.get(&id).filter(|u| u.is_active)
@@ -680,7 +650,7 @@ fn get_valid_entries(entries: &[Entry]) -> Vec<&Entry> {
 }
 ```
 
-(Do) Use the ? operator with Option in functions returning Option.
+Use the ? operator with Option in functions returning Option.
 ```rust
 fn get_nested_value(data: &Data) -> Option<&str> {
     let section = data.sections.get("main")?;
@@ -691,7 +661,7 @@ fn get_nested_value(data: &Data) -> Option<&str> {
 
 ### Don't
 
-(Don't) Use sentinel values instead of Option.
+Use sentinel values instead of Option.
 ```rust
 // Bad: Magic values
 fn find_index(items: &[Item], target: &Item) -> i32 {
@@ -705,7 +675,7 @@ fn find_index(items: &[Item], target: &Item) -> Option<usize> {
 }
 ```
 
-(Don't) Overuse unwrap() or expect() outside of tests.
+Overuse unwrap() or expect() outside of tests.
 ```rust
 // Bad: Panics on None
 let user = users.get(id).unwrap();
@@ -716,7 +686,7 @@ let user = users.get(id).ok_or(UserError::NotFound(id))?;
 let name = user.name.as_deref().unwrap_or("Anonymous");
 ```
 
-(Don't) Check is_some/is_none then unwrap.
+Check is_some/is_none then unwrap.
 ```rust
 // Bad: Redundant check
 if value.is_some() {
@@ -733,7 +703,7 @@ if let Some(v) = value {
 value.map(process);
 ```
 
-(Don't) Create deeply nested Option chains without combinators.
+Create deeply nested Option chains without combinators.
 ```rust
 // Bad: Nested matching
 match outer {
@@ -760,15 +730,9 @@ outer
 
 Complement unit tests with property-based testing to verify invariants across many generated inputs. This QuickCheck-inspired approach catches edge cases that example-based tests miss.
 
-**Ratings:**
-- Impact: A (catches edge cases unit tests miss)
-- Feasibility: B (requires proptest/quickcheck; learning curve)
-- Idiomaticity: A (growing Rust practice)
-- FP Purity: S (QuickCheck heritage; declarative testing)
-
 ### Do
 
-(Do) Use proptest for property-based testing.
+Use proptest for property-based testing.
 ```rust
 use proptest::prelude::*;
 
@@ -794,7 +758,7 @@ proptest! {
 }
 ```
 
-(Do) Test algebraic properties (identity, associativity, commutativity).
+Test algebraic properties (identity, associativity, commutativity).
 ```rust
 proptest! {
     #[test]
@@ -814,7 +778,7 @@ proptest! {
 }
 ```
 
-(Do) Test invariants that should hold for all valid inputs.
+Test invariants that should hold for all valid inputs.
 ```rust
 proptest! {
     #[test]
@@ -838,7 +802,7 @@ proptest! {
 }
 ```
 
-(Do) Use custom strategies for domain-specific types.
+Use custom strategies for domain-specific types.
 ```rust
 fn valid_package_name() -> impl Strategy<Value = String> {
     "[a-z][a-z0-9-]{0,62}[a-z0-9]?"
@@ -860,7 +824,7 @@ proptest! {
 
 ### Don't
 
-(Don't) Only write example-based unit tests for complex logic.
+Only write example-based unit tests for complex logic.
 ```rust
 // Incomplete: Only tests a few examples
 #[test]
@@ -873,7 +837,7 @@ fn test_merge() {
 }
 ```
 
-(Don't) Ignore test failures without understanding the counterexample.
+Ignore test failures without understanding the counterexample.
 ```rust
 // Bad: Ignoring failures
 proptest! {
@@ -885,7 +849,7 @@ proptest! {
 }
 ```
 
-(Don't) Write properties that are too weak or tautological.
+Write properties that are too weak or tautological.
 ```rust
 // Bad: This always passes, tests nothing useful
 proptest! {
@@ -905,7 +869,7 @@ proptest! {
 }
 ```
 
-(Don't) Generate invalid inputs without proper filtering.
+Generate invalid inputs without proper filtering.
 ```rust
 // Bad: Generates invalid UTF-8 and panics
 proptest! {
@@ -930,15 +894,9 @@ proptest! {
 
 Follow the strict TDD cycle: write a failing test first (red), implement minimally to pass (green), then refactor. This discipline ensures testability, prevents regression, and drives better design.
 
-**Ratings:**
-- Impact: S (ensures testability, prevents regression)
-- Feasibility: A (Rust's cargo test makes this easy)
-- Idiomaticity: A (industry best practice)
-- FP Purity: B (supports referential transparency goals)
-
 ### Do
 
-(Do) Write the test first, watch it fail.
+Write the test first, watch it fail.
 ```rust
 // Step 1: RED - Write failing test
 #[cfg(test)]
@@ -957,7 +915,7 @@ mod tests {
 // At this point: cargo test fails - Version doesn't exist yet!
 ```
 
-(Do) Implement the minimum code to pass.
+Implement the minimum code to pass.
 ```rust
 // Step 2: GREEN - Minimal implementation
 pub struct Version {
@@ -983,7 +941,7 @@ impl Version {
 // cargo test passes!
 ```
 
-(Do) Refactor while keeping tests green.
+Refactor while keeping tests green.
 ```rust
 // Step 3: REFACTOR - Improve design
 impl Version {
@@ -1011,7 +969,7 @@ impl Version {
 // Tests still pass after refactoring!
 ```
 
-(Do) Add tests for edge cases incrementally.
+Add tests for edge cases incrementally.
 ```rust
 #[test]
 fn parse_rejects_empty_string() {
@@ -1035,7 +993,7 @@ fn parse_handles_leading_zeros() {
 }
 ```
 
-(Do) Use test modules colocated with implementation.
+Use test modules colocated with implementation.
 ```rust
 // src/version.rs
 pub struct Version { /* ... */ }
@@ -1056,7 +1014,7 @@ mod tests {
 
 ### Don't
 
-(Don't) Write implementation before tests.
+Write implementation before tests.
 ```rust
 // Bad: Implementation without tests
 pub fn complex_algorithm(input: &str) -> Result<Output, Error> {
@@ -1066,7 +1024,7 @@ pub fn complex_algorithm(input: &str) -> Result<Output, Error> {
 }
 ```
 
-(Don't) Write tests that pass trivially or test nothing.
+Write tests that pass trivially or test nothing.
 ```rust
 // Bad: Test that always passes
 #[test]
@@ -1081,7 +1039,7 @@ fn test_without_assertions() {
 }
 ```
 
-(Don't) Skip the refactor step.
+Skip the refactor step.
 ```rust
 // Bad: "It works, ship it!"
 impl Version {
@@ -1099,7 +1057,7 @@ impl Version {
 }
 ```
 
-(Don't) Write tests after the fact that just confirm current behavior.
+Write tests after the fact that just confirm current behavior.
 ```rust
 // Bad: "Characterization tests" without understanding intent
 #[test]
@@ -1109,7 +1067,7 @@ fn test_weird_behavior() {
 }
 ```
 
-(Don't) Test private implementation details.
+Test private implementation details.
 ```rust
 // Bad: Testing internals that may change
 #[test]
@@ -1135,15 +1093,9 @@ fn test_caching_behavior() {
 
 Prefer small, focused traits that compose well over large monolithic interfaces. This Haskell typeclass-inspired approach enables better abstraction, easier testing, and more flexible code reuse.
 
-**Ratings:**
-- Impact: A (better abstraction, easier testing)
-- Feasibility: B (requires careful API design)
-- Idiomaticity: S (Rust's trait system shines here)
-- FP Purity: A (typeclass-inspired composition)
-
 ### Do
 
-(Do) Design small, single-purpose traits.
+Design small, single-purpose traits.
 ```rust
 /// Can be resolved from a prefixed form to a full URI
 trait Resolvable {
@@ -1168,7 +1120,7 @@ trait Loadable: Sized {
 }
 ```
 
-(Do) Compose traits using supertraits and bounds.
+Compose traits using supertraits and bounds.
 ```rust
 // Compose small traits into larger capabilities
 trait UriHandler: Resolvable + Compactable {}
@@ -1182,7 +1134,7 @@ fn process_uri<T: Resolvable + Display>(uri: &T, map: &PrefixMap) -> String {
 }
 ```
 
-(Do) Use extension traits to add methods to existing types.
+Use extension traits to add methods to existing types.
 ```rust
 trait ResultExt<T, E> {
     fn context(self, msg: &str) -> Result<T, ContextError<E>>;
@@ -1204,7 +1156,7 @@ let data = fs::read_to_string(path)
     .context("failed to read config")?;
 ```
 
-(Do) Implement standard library traits for interoperability.
+Implement standard library traits for interoperability.
 ```rust
 impl Default for SemStore {
     fn default() -> Self {
@@ -1229,7 +1181,7 @@ impl FromStr for Version {
 
 ### Don't
 
-(Don't) Create large, monolithic traits.
+Create large, monolithic traits.
 ```rust
 // Bad: Too many responsibilities
 trait Repository {
@@ -1247,7 +1199,7 @@ trait Repository {
 }
 ```
 
-(Don't) Use trait objects when generics suffice.
+Use trait objects when generics suffice.
 ```rust
 // Bad: Unnecessary dynamic dispatch
 fn process(items: &[Box<dyn Processable>]) {
@@ -1264,7 +1216,7 @@ fn process<T: Processable>(items: &[T]) {
 }
 ```
 
-(Don't) Require unused trait methods via blanket requirements.
+Require unused trait methods via blanket requirements.
 ```rust
 // Bad: Forces implementers to provide unused methods
 trait DataStore: Connect + Query + Mutate + Transaction + Cache + Log {
@@ -1277,7 +1229,7 @@ fn process<T: Query + Mutate>(store: &mut T) {
 }
 ```
 
-(Don't) Use associated types when generic parameters work better.
+Use associated types when generic parameters work better.
 ```rust
 // Bad: Can only have one implementation per type
 trait Container {
@@ -1298,15 +1250,9 @@ trait Container<T> {
 
 Model state and variants with enums (algebraic sum types) rather than flags, inheritance, or stringly-typed values. Exhaustive pattern matching ensures all cases are handled at compile time - Rust's killer feature borrowed from ML/Haskell.
 
-**Ratings:**
-- Impact: S (exhaustive matching prevents bugs)
-- Feasibility: A (native Rust feature)
-- Idiomaticity: S (Rust's killer feature)
-- FP Purity: S (algebraic data types; Haskell-equivalent)
-
 ### Do
 
-(Do) Use enums to model mutually exclusive states.
+Use enums to model mutually exclusive states.
 ```rust
 #[derive(Debug, Clone, PartialEq)]
 pub enum DepSpec {
@@ -1333,7 +1279,7 @@ impl DepSpec {
 }
 ```
 
-(Do) Use enums for state machines with compile-time guarantees.
+Use enums for state machines with compile-time guarantees.
 ```rust
 enum ConnectionState {
     Disconnected,
@@ -1363,7 +1309,7 @@ impl ConnectionState {
 }
 ```
 
-(Do) Use enums to make invalid states unrepresentable.
+Use enums to make invalid states unrepresentable.
 ```rust
 // User can be either anonymous or authenticated, never both
 enum User {
@@ -1383,7 +1329,7 @@ enum FieldState<T> {
 }
 ```
 
-(Do) Leverage exhaustive matching for safety.
+Leverage exhaustive matching for safety.
 ```rust
 fn handle_result(result: QueryResult) -> Response {
     match result {
@@ -1400,7 +1346,7 @@ fn handle_result(result: QueryResult) -> Response {
 
 ### Don't
 
-(Don't) Use boolean flags for mutually exclusive states.
+Use boolean flags for mutually exclusive states.
 ```rust
 // Bad: Multiple bools can have invalid combinations
 struct User {
@@ -1415,7 +1361,7 @@ struct Connection {
 }
 ```
 
-(Don't) Use Option when you need more than two states.
+Use Option when you need more than two states.
 ```rust
 // Bad: Option doesn't capture "loading" vs "error" vs "empty"
 struct DataView {
@@ -1431,7 +1377,7 @@ enum DataState {
 }
 ```
 
-(Don't) Use inheritance-like patterns with trait objects when enums suffice.
+Use inheritance-like patterns with trait objects when enums suffice.
 ```rust
 // Bad: Runtime dispatch when compile-time would work
 trait Shape {
@@ -1456,7 +1402,7 @@ impl Shape {
 }
 ```
 
-(Don't) Use integers or strings as type discriminators.
+Use integers or strings as type discriminators.
 ```rust
 // Bad: Magic numbers
 const USER_TYPE_ADMIN: i32 = 1;
@@ -1473,15 +1419,9 @@ struct Message { msg_type: String }  // "request", "response", typos!
 
 Use the newtype pattern to create distinct types for domain-specific values, preventing accidental mixing of semantically different data. This Haskell-inspired pattern provides compile-time safety with zero runtime cost.
 
-**Ratings:**
-- Impact: A (prevents mixing semantically different values)
-- Feasibility: B (requires discipline; some boilerplate)
-- Idiomaticity: S (core Rust pattern, zero-cost abstraction)
-- FP Purity: A (Haskell-inspired; phantom types possible)
-
 ### Do
 
-(Do) Wrap primitive types in newtypes for domain semantics.
+Wrap primitive types in newtypes for domain semantics.
 ```rust
 /// A validated package name following sem conventions
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
@@ -1505,7 +1445,7 @@ impl PackageName {
 }
 ```
 
-(Do) Use newtypes to distinguish semantically different IDs.
+Use newtypes to distinguish semantically different IDs.
 ```rust
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct UserId(u64);
@@ -1520,14 +1460,14 @@ fn process_order(user: UserId, order: OrderId) { /* ... */ }
 // process_order(order_id, user_id);  // Error: expected UserId, found OrderId
 ```
 
-(Do) Derive common traits to maintain ergonomics.
+Derive common traits to maintain ergonomics.
 ```rust
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(transparent)]
 pub struct Uri(String);
 ```
 
-(Do) Use phantom types for compile-time state tracking.
+Use phantom types for compile-time state tracking.
 ```rust
 use std::marker::PhantomData;
 
@@ -1555,7 +1495,7 @@ impl Input<Validated> {
 
 ### Don't
 
-(Don't) Use raw primitive types for domain concepts.
+Use raw primitive types for domain concepts.
 ```rust
 // Bad: Raw strings lose semantic meaning
 fn load_package(name: String, path: String, uri: String) {
@@ -1566,7 +1506,7 @@ fn load_package(name: String, path: String, uri: String) {
 load_package(uri, name, path);  // Compiles but wrong!
 ```
 
-(Don't) Create newtypes without validation when invariants exist.
+Create newtypes without validation when invariants exist.
 ```rust
 // Bad: Allows invalid state
 pub struct Email(pub String);  // pub field allows any string
@@ -1584,7 +1524,7 @@ impl Email {
 }
 ```
 
-(Don't) Over-wrap types that don't need semantic distinction.
+Over-wrap types that don't need semantic distinction.
 ```rust
 // Bad: Unnecessary wrapping of implementation details
 struct LoopCounter(usize);  // Just use usize
@@ -1597,15 +1537,9 @@ struct TempBuffer(Vec<u8>);  // Just use Vec<u8>
 
 Use constructor validation to ensure only valid states can exist. Follow the 'parse, don't validate' principle: transform unvalidated data into validated types at system boundaries, making invalid states unrepresentable.
 
-**Ratings:**
-- Impact: S (invalid states become unrepresentable)
-- Feasibility: B (requires upfront design thinking)
-- Idiomaticity: A (recommended Rust pattern)
-- FP Purity: A (Haskell-inspired 'make illegal states unrepresentable')
-
 ### Do
 
-(Do) Validate in constructors to ensure type invariants.
+Validate in constructors to ensure type invariants.
 ```rust
 impl Manifest {
     pub fn from_path(path: &Path) -> Result<Self, ManifestError> {
@@ -1631,7 +1565,7 @@ impl Manifest {
 }
 ```
 
-(Do) Use the typestate pattern for compile-time state enforcement.
+Use the typestate pattern for compile-time state enforcement.
 ```rust
 // States as zero-sized types
 struct Draft;
@@ -1670,7 +1604,7 @@ impl Article<Published> {
 // article_published.publish();  // Error: method not found
 ```
 
-(Do) Parse into validated types at system boundaries.
+Parse into validated types at system boundaries.
 ```rust
 // Raw input from external source
 struct RawUserInput {
@@ -1705,7 +1639,7 @@ impl Email {
 }
 ```
 
-(Do) Make the validated state obvious in function signatures.
+Make the validated state obvious in function signatures.
 ```rust
 // Functions that require validation communicate it via types
 fn send_email(to: &Email, subject: &str, body: &str) -> Result<(), SendError> {
@@ -1719,7 +1653,7 @@ fn create_account(user: ValidatedUser) -> Result<Account, AccountError> {
 
 ### Don't
 
-(Don't) Scatter validation logic throughout the codebase.
+Scatter validation logic throughout the codebase.
 ```rust
 // Bad: Validation repeated everywhere
 fn send_email(to: &str, subject: &str, body: &str) -> Result<(), Error> {
@@ -1737,7 +1671,7 @@ fn save_user(email: &str) -> Result<(), Error> {
 }
 ```
 
-(Don't) Allow construction of invalid objects.
+Allow construction of invalid objects.
 ```rust
 // Bad: Public fields allow invalid state
 pub struct Email {
@@ -1752,7 +1686,7 @@ impl User {
 }
 ```
 
-(Don't) Use validation functions that return bool.
+Use validation functions that return bool.
 ```rust
 // Bad: Caller can ignore the result
 fn is_valid_email(s: &str) -> bool {
@@ -1769,7 +1703,7 @@ fn parse_email(s: &str) -> Result<Email, ValidationError>
 // Caller must handle the Result
 ```
 
-(Don't) Re-validate already-validated data.
+Re-validate already-validated data.
 ```rust
 // Bad: Redundant validation
 fn process(user: ValidatedUser) -> Result<(), Error> {