Cargo.toml: add workspace-level clippy config

Adds a set of workspace-level lints including common ones we've used in
the past and others collected via running `clippy::pedantic` on several
of our crates and looking for interesting ones.

Workspace-level lints require explict opt-in from each crate's
Cargo.toml, so there's nothing forcing any crate to use them:

    [lints]
    workspace = true

That said, I have opted every crate in the workspace into these lints
and gotten them all to pass except for `wycheproof2blb` which is an
internal utility tool and I didn't feel like it was worth the hassle.

Even then, the lints are all set to `"warn"`, so they can be easily
overridden by `#[allow(...)]` attributes, including `#![allow(...)]`
to shut them off at the granularity of an entire crate.

I managed to fix most of the issues that `cargo clippy --fix` didn't fix
automatically including some missing documentation and documentation
formatting issues.

The main thing I didn't fix was adding missing `SAFETY` comments,
which is a problem with a few of the crates in this repo. I disabled a
lint at the crate level and added a TODO where we're missing them and it
wasn't easily corrected.

Author: tarcieri

Cargo.toml

@@ -29,3 +29,43 @@ opt-level = 2
 
 [patch.crates-io]
 cmov = { path = "cmov" }
+
+[workspace.lints.clippy]
+borrow_as_ptr = "warn"
+cast_lossless = "warn"
+cast_possible_truncation = "warn"
+cast_possible_wrap = "warn"
+cast_precision_loss = "warn"
+cast_sign_loss = "warn"
+checked_conversions = "warn"
+doc_markdown = "warn"
+from_iter_instead_of_collect = "warn"
+manual_assert = "warn"
+map_unwrap_or = "warn"
+missing_errors_doc = "warn"
+missing_panics_doc = "warn"
+mod_module_files = "warn"
+must_use_candidate = "warn"
+implicit_saturating_sub = "warn"
+panic_in_result_fn = "warn"
+ptr_as_ptr = "warn"
+redundant_closure_for_method_calls = "warn"
+ref_as_ptr = "warn"
+return_self_not_must_use = "warn"
+semicolon_if_nothing_returned = "warn"
+trivially_copy_pass_by_ref = "warn"
+std_instead_of_alloc = "warn"
+std_instead_of_core = "warn"
+undocumented_unsafe_blocks = "warn"
+unnecessary_safety_comment = "warn"
+unwrap_in_result = "warn"
+unwrap_used = "warn"
+
+[workspace.lints.rust]
+missing_copy_implementations = "warn"
+missing_debug_implementations = "warn"
+missing_docs = "warn"
+trivial_casts = "warn"
+trivial_numeric_casts = "warn"
+unused_lifetimes = "warn"
+unused_qualifications = "warn"

blobby/Cargo.toml

@@ -13,3 +13,6 @@ description = "Iterator over simple binary blob storage"
 
 [features]
 alloc = []
+
+[lints]
+workspace = true

blobby/src/bin/decode.rs

@@ -1,5 +1,5 @@
 //! Encoding utility
-use std::error::Error;
+use core::error::Error;
 
 #[cfg(not(feature = "alloc"))]
 fn main() -> Result<(), Box<dyn Error>> {

blobby/src/bin/encode.rs

@@ -1,5 +1,5 @@
 //! Encoding utility
-use std::error::Error;
+use core::error::Error;
 
 #[cfg(not(feature = "alloc"))]
 fn main() -> Result<(), Box<dyn Error>> {

blobby/src/decode.rs

@@ -51,6 +51,7 @@ macro_rules! try_read_vlq {
 }
 
 /// Blobby file header
+#[derive(Clone, Copy, Debug)]
 pub struct Header {
     /// Number of blobs stored in the file
     pub items_len: usize,
@@ -59,7 +60,10 @@ pub struct Header {
 }
 
 impl Header {
-    /// Parse blobby header
+    /// Parse blobby header.
+    ///
+    /// # Errors
+    /// - If data could not be parsed successfully.
     pub const fn parse(data: &mut &[u8]) -> Result<Self, Error> {
         match (read_vlq(data), read_vlq(data)) {
             (Ok(items_len), Ok(dedup_len)) => Ok(Header {
@@ -72,6 +76,9 @@ impl Header {
 }
 
 /// Parse blobby data into an array.
+///
+/// # Errors
+/// - If data could not be parsed successfully.
 pub const fn parse_into_array<const ITEMS_LEN: usize, const DEDUP_LEN: usize>(
     mut data: &[u8],
 ) -> Result<[&[u8]; ITEMS_LEN], Error> {
@@ -127,7 +134,11 @@ pub const fn parse_into_array<const ITEMS_LEN: usize, const DEDUP_LEN: usize>(
 }
 
 /// Parse blobby data into a vector of slices.
+///
+/// # Errors
+/// - if data failed to parse successfully
 #[cfg(feature = "alloc")]
+#[allow(clippy::missing_panics_doc, clippy::panic_in_result_fn)]
 pub fn parse_into_vec(mut data: &[u8]) -> Result<alloc::vec::Vec<&[u8]>, Error> {
     use alloc::{vec, vec::Vec};
 
@@ -175,6 +186,7 @@ pub fn parse_into_vec(mut data: &[u8]) -> Result<alloc::vec::Vec<&[u8]>, Error>
     Ok(res)
 }
 
+/// Parse data into a slice.
 #[macro_export]
 macro_rules! parse_into_slice {
     ($data:expr) => {{
@@ -195,6 +207,7 @@ macro_rules! parse_into_slice {
     }};
 }
 
+/// Parse data into structs.
 #[macro_export]
 macro_rules! parse_into_structs {
     (

blobby/src/encode.rs

@@ -3,6 +3,7 @@ use super::{NEXT_MASK, VAL_MASK};
 /// Write a git-flavoured VLQ value into `buf`.
 ///
 /// Returns the slice within `buf` that holds the value.
+#[allow(clippy::cast_possible_truncation)]
 fn encode_vlq(mut val: usize, buf: &mut [u8; 4]) -> &[u8] {
     macro_rules! step {
         ($n:expr) => {
@@ -40,6 +41,7 @@ fn encode_vlq(mut val: usize, buf: &mut [u8; 4]) -> &[u8] {
 ///         - (J << 1) & 0x01: indicates this blob is index entry J
 ///         - (L << 1) & 0x00: indicates an explicit blob of len L
 ///      - (in the latter case) explicit blob contents (L bytes)
+#[allow(clippy::missing_panics_doc, clippy::unwrap_used)]
 pub fn encode_blobs<T>(blobs: &[T]) -> (alloc::vec::Vec<u8>, usize)
 where
     T: AsRef<[u8]>,
@@ -49,7 +51,7 @@ where
     let mut dedup_map = BTreeMap::new();
     blobs
         .iter()
-        .map(|v| v.as_ref())
+        .map(AsRef::as_ref)
         .filter(|blob| !blob.is_empty())
         .for_each(|blob| {
             let v = dedup_map.entry(blob.as_ref()).or_insert(0);
@@ -89,7 +91,7 @@ where
         out_buf.extend_from_slice(e);
     }
 
-    for blob in blobs.iter().map(|v| v.as_ref()) {
+    for blob in blobs.iter().map(AsRef::as_ref) {
         if let Some(dup_pos) = rev_idx.get(blob) {
             let n = (dup_pos << 1) + 1usize;
             out_buf.extend_from_slice(encode_vlq(n, &mut buf));
@@ -104,6 +106,7 @@ where
 }
 
 #[cfg(test)]
+#[allow(clippy::cast_possible_truncation, clippy::unwrap_used)]
 mod tests {
     use crate::{Error, NEXT_MASK, VAL_MASK, decode::read_vlq};
 

blobby/tests/mod.rs

@@ -1,4 +1,5 @@
 #![cfg(feature = "alloc")]
+#![allow(missing_docs, clippy::panic_in_result_fn)]
 
 const ITEMS_LEN: usize = 10;
 const DEDUP_LEN: usize = 3;

block-buffer/Cargo.toml

@@ -18,3 +18,6 @@ zeroize = { version = "1.4", optional = true, default-features = false }
 
 [dev-dependencies]
 hex-literal = "1"
+
+[lints]
+workspace = true

block-buffer/src/lib.rs

@@ -38,7 +38,7 @@
     html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
     html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
 )]
-#![warn(missing_docs)]
+#![allow(clippy::undocumented_unsafe_blocks)] // TODO(tarcieri): document all unsafe blocks
 
 pub use hybrid_array as array;
 
@@ -94,12 +94,8 @@ pub struct BlockBuffer<BS: ArraySize, K: BufferKind> {
 impl<BS: ArraySize, K: BufferKind> BlockBuffer<BS, K> {
     /// This associated constant is used to assert block size correctness at compile time.
     const BLOCK_SIZE_ASSERT: bool = {
-        if BS::USIZE == 0 {
-            panic!("Block size can not be equal to zero!");
-        }
-        if BS::USIZE > 255 {
-            panic!("Block size can not be bigger than 255!");
-        }
+        assert!(BS::USIZE != 0, "Block size can not be equal to zero!");
+        assert!(BS::USIZE <= 255, "Block size can not be bigger than 255!");
         true
     };
 }
@@ -140,16 +136,22 @@ impl<BS: ArraySize, K: BufferKind> BlockBuffer<BS, K> {
     /// # Panics
     /// If slice length is not valid for used buffer kind.
     #[inline(always)]
+    #[must_use]
+    #[track_caller]
     pub fn new(buf: &[u8]) -> Self {
-        Self::try_new(buf).unwrap()
+        Self::try_new(buf).expect("invalid slice length for buffer kind")
     }
 
     /// Create new buffer from slice.
     ///
-    /// Returns an error if slice length is not valid for used buffer kind.
+    /// # Errors
+    /// - if slice length is not valid for used buffer kind.
     #[inline(always)]
     pub fn try_new(buf: &[u8]) -> Result<Self, Error> {
-        assert!(Self::BLOCK_SIZE_ASSERT);
+        const {
+            assert!(Self::BLOCK_SIZE_ASSERT);
+        }
+
         if !K::invariant(buf.len(), BS::USIZE) {
             return Err(Error);
         }
@@ -292,7 +294,7 @@ impl<BS: ArraySize, K: BufferKind> BlockBuffer<BS, K> {
     #[inline(always)]
     unsafe fn set_pos_unchecked(&mut self, pos: usize) {
         debug_assert!(K::invariant(pos, BS::USIZE));
-        K::set_pos(&mut self.buffer, &mut self.pos, pos)
+        K::set_pos(&mut self.buffer, &mut self.pos, pos);
     }
 
     /// Set buffer data.
@@ -322,6 +324,7 @@ where
     Sum<BS, K::Overhead>: ArraySize,
 {
     /// Serialize buffer into a byte array.
+    #[allow(clippy::missing_panics_doc)]
     pub fn serialize(&self) -> SerializedBuffer<BS, K> {
         let mut buf = SerializedBuffer::<BS, K>::default();
         let data = self.get_data();
@@ -332,6 +335,9 @@ where
     }
 
     /// Deserialize buffer from a byte array.
+    ///
+    /// # Errors
+    /// - If algorithm-specific invariant fails to hold
     pub fn deserialize(buf: &SerializedBuffer<BS, K>) -> Result<Self, Error> {
         let (pos, block) = buf.split_at(1);
         let pos = usize::from(pos[0]);
@@ -366,9 +372,7 @@ impl<BS: ArraySize> BlockBuffer<BS, Eager> {
         suffix: &[u8],
         mut compress: impl FnMut(&Array<u8, BS>),
     ) {
-        if suffix.len() > BS::USIZE {
-            panic!("suffix is too long");
-        }
+        assert!(suffix.len() <= BS::USIZE, "suffix is too long");
         let pos = self.get_pos();
         let mut buf = self.pad_with_zeros();
         buf[pos] = delim;

block-buffer/src/read.rs

@@ -73,6 +73,7 @@ impl<BS: ArraySize> ReadBuffer<BS> {
     /// # Safety
     /// `pos` must be smaller than or equal to the buffer block size and be bigger than zero.
     #[inline(always)]
+    #[allow(clippy::cast_possible_truncation)]
     unsafe fn set_pos_unchecked(&mut self, pos: usize) {
         debug_assert!(pos != 0 && pos <= BS::USIZE);
         self.buffer[0] = pos as u8;
@@ -141,7 +142,7 @@ impl<BS: ArraySize> ReadBuffer<BS> {
         }
 
         self.write_block(tail.len(), gen_block, |tail_ks| {
-            tail.copy_from_slice(tail_ks)
+            tail.copy_from_slice(tail_ks);
         });
     }
 
@@ -158,6 +159,10 @@ impl<BS: ArraySize> ReadBuffer<BS> {
     }
 
     /// Deserialize buffer from a byte array.
+    ///
+    /// # Errors
+    /// - If the first byte is `0`.
+    /// - If the first byte is bigger than `BS`.
     #[inline]
     pub fn deserialize(buffer: &Array<u8, BS>) -> Result<Self, Error> {
         let pos = usize::from(buffer[0]);