chore(shared): add reasons to expect attributes

crates/shared/src/generator.rs

@@ -41,7 +41,11 @@ impl VoxelGenerator {
 
     /// Generates a complete voxel chunk for the specified position.
     #[must_use]
-    #[expect(clippy::cast_possible_wrap, clippy::cast_possible_truncation)]
+    #[expect(
+        clippy::cast_possible_wrap,
+        clippy::cast_possible_truncation,
+        reason = "chunk and voxel coordinates stay within the ranges these casts assume"
+    )]
     pub fn generate_chunk(&self, pos: ChunkPos) -> Chunk {
         let mut chunk = Chunk::default();
 

crates/shared/src/world/chunk.rs

@@ -89,7 +89,10 @@ impl PalettedChunk {
         let mut blocks = vec![BlockId::AIR; CHUNK_VOLUME].into_boxed_slice();
         for (voxel, slot) in blocks.iter_mut().enumerate() {
             // A stored index was produced from a palette position, so it is always in range for `palette`.
-            #[expect(clippy::cast_possible_truncation)]
+            #[expect(
+                clippy::cast_possible_truncation,
+                reason = "a packed index originates from a valid palette position and fits usize"
+            )]
             let index = Self::read_packed(&self.indices, voxel, self.bits_per_index) as usize;
             *slot = self.palette[index];
         }
@@ -158,7 +161,10 @@ mod tests {
         let mut chunk = Chunk::default();
         for (i, block) in chunk.blocks.iter_mut().enumerate() {
             // `distinct` is a small test constant, so the modulo result always fits in a u16.
-            #[expect(clippy::cast_possible_truncation)]
+            #[expect(
+                clippy::cast_possible_truncation,
+                reason = "distinct is a small test constant within u16 range"
+            )]
             let id = (i % distinct) as u16;
             *block = BlockId(id);
         }

crates/shared/src/world/chunk_data.rs

@@ -77,8 +77,10 @@ impl ChunkData {
             .enumerate()
         {
             if base != cur {
-                // `i` ranges over `0..CHUNK_VOLUME`, which fits comfortably in a `u32`.
-                #[expect(clippy::cast_possible_truncation)]
+                #[expect(
+                    clippy::cast_possible_truncation,
+                    reason = "i ranges over 0..CHUNK_VOLUME, which fits in u32"
+                )]
                 data.set(i as u32, cur);
             }
         }

crates/shared/src/world/coords.rs

@@ -25,7 +25,11 @@ impl ChunkPos {
 
     /// Initializes a new chunk position from a world-space position measured in blocks.
     #[must_use]
-    #[expect(clippy::cast_possible_truncation, clippy::cast_possible_wrap)]
+    #[expect(
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        reason = "floored world coordinates stay within i32 range for supported world sizes"
+    )]
     pub fn from_world(x: f64, y: f64, z: f64) -> Self {
         ChunkPos {
             x: (x.floor() as i32).div_euclid(CHUNK_SIZE as i32),

crates/shared/src/world/entity.rs

@@ -23,7 +23,11 @@ impl EntityPos {
     }
 
     /// Rebases the position so every component of `local` lies within `[0.0, CHUNK_SIZE)`, carrying any whole-chunk overflow into `chunk`.
-    #[expect(clippy::cast_precision_loss, clippy::cast_possible_truncation)]
+    #[expect(
+        clippy::cast_precision_loss,
+        clippy::cast_possible_truncation,
+        reason = "chunk carry values are small and within f32/i32 exact range"
+    )]
     pub fn renormalize(&mut self) {
         let size = CHUNK_SIZE as f32;
 
@@ -43,8 +47,10 @@ impl EntityPos {
 mod tests {
     use super::*;
 
-    // `CHUNK_SIZE` is 32, exactly representable, so the widening cannot lose precision here.
-    #[expect(clippy::cast_precision_loss)]
+    #[expect(
+        clippy::cast_precision_loss,
+        reason = "CHUNK_SIZE is 32, exactly representable as f32"
+    )]
     const CHUNK_SIZE_F: f32 = CHUNK_SIZE as f32;
 
     #[test]