fix clippy errors in fspy_detours_sys and fspy_seccomp_unotify

- Move wildcard_imports allow to crate-level in fspy_detours_sys to
  avoid unfulfilled expect on test target and bindgen test failure
- Fix all clippy warnings in fspy_seccomp_unotify: add SAFETY comments,
  feature-gate bindings module, fix unreadable literals, add missing
  docs, and address pedantic/nursery lints

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: wan9chi

crates/fspy_detours_sys/src/generated_bindings.rs

@@ -1,5 +1,3 @@
-#![allow(clippy::wildcard_imports, reason = "generated FFI bindings")]
-
 use winapi::{
     shared::{guiddef::*, minwindef::*, windef::*},
     um::{

crates/fspy_detours_sys/src/lib.rs

@@ -3,7 +3,8 @@
     clippy::disallowed_types,
     clippy::disallowed_methods,
     clippy::disallowed_macros,
-    reason = "non-vite crate"
+    clippy::wildcard_imports,
+    reason = "non-vite crate; generated FFI bindings use wildcard imports"
 )]
 
 #[expect(non_camel_case_types, non_snake_case, reason = "generated FFI bindings")]

crates/fspy_seccomp_unotify/src/bindings/alloc.rs

@@ -38,15 +38,25 @@ pub struct Alloced<T> {
 }
 
 impl<T> Alloced<T> {
+    /// Allocates a zero-initialized buffer with the given layout.
+    ///
+    /// # Safety
+    /// The `layout` must have a size large enough to hold a value of type `T` and
+    /// must have proper alignment for `T`.
     pub(crate) unsafe fn alloc(layout: Layout) -> Self {
+        // SAFETY: layout is non-zero-sized (guaranteed by caller) and properly aligned
         let ptr = unsafe { alloc::alloc_zeroed(layout) };
 
         let ptr = NonNull::new(ptr).unwrap();
         Self { ptr: ptr.cast(), layout }
     }
 
-    pub(crate) fn zeroed(&mut self) -> &mut T {
+    pub(crate) const fn zeroed(&mut self) -> &mut T {
+        // SAFETY: `self.ptr` was allocated with `self.layout.size()` bytes,
+        // so writing that many zero bytes is within bounds
         unsafe { self.ptr.cast::<u8>().write_bytes(0, self.layout.size()) };
+        // SAFETY: the pointer is valid, properly aligned, and the buffer has just
+        // been zero-initialized, which is valid for the kernel structs used here
         unsafe { self.ptr.as_mut() }
     }
 }
@@ -55,25 +65,42 @@ impl<T> Deref for Alloced<T> {
     type Target = T;
 
     fn deref(&self) -> &Self::Target {
+        // SAFETY: the pointer is valid and properly aligned, allocated in `alloc()`
         unsafe { self.ptr.as_ref() }
     }
 }
 
 impl<T> Drop for Alloced<T> {
     fn drop(&mut self) {
+        // SAFETY: `self.ptr` was allocated with `alloc::alloc_zeroed` using `self.layout`,
+        // so it is safe to deallocate with the same layout
         unsafe {
             alloc::dealloc(self.ptr.as_ptr().cast(), self.layout);
         }
     }
 }
 
+// SAFETY: `Alloced<T>` owns a heap allocation and does not use thread-local storage.
+// It is safe to send across threads when `T` itself is `Send + Sync`.
 unsafe impl<T: Send + Sync> Send for Alloced<T> {}
+// SAFETY: `Alloced<T>` only provides shared access via `Deref`, which is safe
+// when `T` is `Send + Sync`.
 unsafe impl<T: Send + Sync> Sync for Alloced<T> {}
 
+/// Allocates a zero-initialized buffer for a `seccomp_notif` struct, sized to at least
+/// what the kernel requires.
+#[must_use]
 pub fn alloc_seccomp_notif() -> Alloced<libc::seccomp_notif> {
+    // SAFETY: `BUF_SIZES.req_layout` is computed from `get_notif_sizes()` and
+    // `size_of::<seccomp_notif>()`, guaranteeing sufficient size and alignment
     unsafe { Alloced::alloc(BUF_SIZES.req_layout) }
 }
 
+/// Allocates a zero-initialized buffer for a `seccomp_notif_resp` struct, sized to at least
+/// what the kernel requires.
+#[must_use]
 pub fn alloc_seccomp_notif_resp() -> Alloced<libc::seccomp_notif_resp> {
+    // SAFETY: `BUF_SIZES.resp_layout` is computed from `get_notif_sizes()` and
+    // `size_of::<seccomp_notif_resp>()`, guaranteeing sufficient size and alignment
     unsafe { Alloced::alloc(BUF_SIZES.resp_layout) }
 }

crates/fspy_seccomp_unotify/src/bindings/mod.rs

@@ -1,36 +1,53 @@
+#[cfg(feature = "supervisor")]
 pub mod alloc;
 
+#[cfg(feature = "supervisor")]
 use alloc::Alloced;
-use std::{
-    mem::zeroed,
-    os::{
-        fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd},
-        raw::c_int,
-    },
-};
+use std::os::raw::c_int;
 
-use libc::{SECCOMP_GET_NOTIF_SIZES, seccomp_notif, syscall};
+use libc::syscall;
 
+/// # Safety
+/// The `args` pointer must be valid for the given `operation`, or null if the operation
+/// does not require arguments.
 unsafe fn seccomp(
     operation: libc::c_uint,
     flags: libc::c_uint,
     args: *mut libc::c_void,
 ) -> nix::Result<libc::c_int> {
+    // SAFETY: caller guarantees `args` is valid for the given seccomp operation
     let ret = unsafe { syscall(libc::SYS_seccomp, operation, flags, args) };
     if ret < 0 {
         return Err(nix::Error::last());
     }
     Ok(c_int::try_from(ret).unwrap())
 }
 
+#[cfg(feature = "supervisor")]
 fn get_notif_sizes() -> nix::Result<libc::seccomp_notif_sizes> {
+    use std::mem::zeroed;
+    // SAFETY: `seccomp_notif_sizes` is a plain data struct safe to zero-initialize
     let mut sizes = unsafe { zeroed::<libc::seccomp_notif_sizes>() };
-    unsafe { seccomp(SECCOMP_GET_NOTIF_SIZES, 0, (&raw mut sizes).cast()) }?;
+    // SAFETY: `sizes` is a valid mutable pointer to a `seccomp_notif_sizes` struct,
+    // which is the expected argument for `SECCOMP_GET_NOTIF_SIZES`
+    unsafe { seccomp(libc::SECCOMP_GET_NOTIF_SIZES, 0, (&raw mut sizes).cast()) }?;
     Ok(sizes)
 }
 
-pub fn notif_recv(fd: BorrowedFd<'_>, notif_buf: &mut Alloced<seccomp_notif>) -> nix::Result<()> {
-    const SECCOMP_IOCTL_NOTIF_RECV: libc::c_ulong = 3226476800;
+/// Receives a seccomp notification from the given file descriptor into the provided buffer.
+///
+/// # Errors
+/// Returns an error if the ioctl call fails (e.g., the fd is invalid or the kernel
+/// returns an error).
+#[cfg(feature = "supervisor")]
+pub fn notif_recv(
+    fd: std::os::fd::BorrowedFd<'_>,
+    notif_buf: &mut Alloced<libc::seccomp_notif>,
+) -> nix::Result<()> {
+    use std::os::fd::AsRawFd;
+    const SECCOMP_IOCTL_NOTIF_RECV: libc::c_ulong = 3_226_476_800;
+    // SAFETY: `notif_buf.zeroed()` returns a valid mutable pointer to a zeroed
+    // `seccomp_notif` buffer with sufficient size for the kernel's notification struct
     let ret = unsafe {
         libc::ioctl(fd.as_raw_fd(), SECCOMP_IOCTL_NOTIF_RECV, (&raw mut *notif_buf.zeroed()))
     };
@@ -40,12 +57,22 @@ pub fn notif_recv(fd: BorrowedFd<'_>, notif_buf: &mut Alloced<seccomp_notif>) ->
     Ok(())
 }
 
-pub fn install_unotify_filter(prog: &[libc::sock_filter]) -> nix::Result<OwnedFd> {
+/// Installs a seccomp user notification filter and returns the notification file descriptor.
+///
+/// # Errors
+/// Returns an error if the seccomp syscall fails (e.g., invalid filter program or
+/// insufficient privileges).
+#[cfg(feature = "target")]
+pub fn install_unotify_filter(prog: &[libc::sock_filter]) -> nix::Result<std::os::fd::OwnedFd> {
+    use std::os::fd::FromRawFd;
     let mut filter = libc::sock_fprog {
         len: prog.len().try_into().unwrap(),
         filter: prog.as_ptr().cast_mut().cast(),
     };
 
+    // SAFETY: `filter` is a valid `sock_fprog` pointing to the BPF program slice,
+    // and `SECCOMP_FILTER_FLAG_NEW_LISTENER` requests a notification fd
+    #[expect(clippy::cast_possible_truncation, reason = "flag value fits in u32")]
     let fd = unsafe {
         seccomp(
             libc::SECCOMP_SET_MODE_FILTER,
@@ -54,5 +81,7 @@ pub fn install_unotify_filter(prog: &[libc::sock_filter]) -> nix::Result<OwnedFd
         )
     }?;
 
-    Ok(unsafe { OwnedFd::from_raw_fd(fd) })
+    // SAFETY: the seccomp syscall with `SECCOMP_FILTER_FLAG_NEW_LISTENER` returns
+    // a valid, owned file descriptor on success
+    Ok(unsafe { std::os::fd::OwnedFd::from_raw_fd(fd) })
 }

crates/fspy_seccomp_unotify/src/lib.rs

@@ -1,5 +1,12 @@
 #![cfg(target_os = "linux")]
+#![allow(
+    clippy::disallowed_types,
+    clippy::disallowed_methods,
+    clippy::disallowed_macros,
+    reason = "non-vite crate"
+)]
 
+#[cfg(any(feature = "supervisor", feature = "target"))]
 mod bindings;
 pub mod payload;
 #[cfg(feature = "target")]

crates/fspy_seccomp_unotify/src/payload/filter.rs

@@ -1,7 +1,7 @@
 use bincode::{Decode, Encode};
 
 #[derive(Debug, Encode, Decode, Clone, Copy)]
-pub(crate) struct CodableSockFilter {
+pub struct CodableSockFilter {
     code: u16,
     jt: u8,
     jf: u8,
@@ -20,7 +20,7 @@ impl From<seccompiler::sock_filter> for CodableSockFilter {
 impl From<CodableSockFilter> for libc::sock_filter {
     fn from(filter: CodableSockFilter) -> Self {
         let CodableSockFilter { code, jt, jf, k } = filter;
-        libc::sock_filter { code, jt, jf, k }
+        Self { code, jt, jf, k }
     }
 }
 

crates/fspy_seccomp_unotify/src/supervisor/handler/arg.rs

@@ -10,6 +10,10 @@ use libc::{pid_t, seccomp_notif};
 use nix::sys::uio::{RemoteIoVec, process_vm_readv};
 
 pub trait FromSyscallArg: Sized {
+    /// Converts a raw syscall argument into this type.
+    ///
+    /// # Errors
+    /// Returns an error if the argument value cannot be interpreted as this type.
     fn from_syscall_arg(arg: u64) -> io::Result<Self>;
 }
 /// Represents the caller of a syscall. Needed to read memory from the caller's address space.
@@ -26,7 +30,8 @@ impl<'a> Caller<'a> {
         f(Self { pid, _marker: std::marker::PhantomData })
     }
 
-    pub fn read_vm(self, starting_addr: usize) -> ProcessVmReader<'a> {
+    #[must_use]
+    pub const fn read_vm(self, starting_addr: usize) -> ProcessVmReader<'a> {
         ProcessVmReader { caller: self, current_addr: starting_addr }
     }
 }
@@ -36,17 +41,18 @@ pub struct ProcessVmReader<'a> {
     current_addr: usize,
 }
 
-impl<'a> io::Read for ProcessVmReader<'a> {
+impl io::Read for ProcessVmReader<'_> {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
         let buf_len = buf.len();
         let read_len = process_vm_readv(
             nix::unistd::Pid::from_raw(self.caller.pid),
             &mut [IoSliceMut::new(buf)],
             &[RemoteIoVec { base: self.current_addr, len: buf_len }],
         )?;
-        self.current_addr = self.current_addr.checked_add(read_len).ok_or_else(|| {
-            io::Error::new(io::ErrorKind::Other, "address overflow while reading remote process")
-        })?;
+        self.current_addr = self
+            .current_addr
+            .checked_add(read_len)
+            .ok_or_else(|| io::Error::other("address overflow while reading remote process"))?;
         Ok(read_len)
     }
 }
@@ -63,7 +69,10 @@ impl CStrPtr {
     /// - `Ok(None)` if the buffer was filled without encountering a null-terminator.
     /// - `Err(UnexpectedEof)` if Eof was reached without encountering a null-terminator.
     /// - `Err(other_err)` on other errors from reading the remote process memory.
-    pub fn read(&self, caller: Caller<'_>, buf: &mut [u8]) -> io::Result<Option<usize>> {
+    ///
+    /// # Errors
+    /// Returns an error if reading from the remote process memory fails.
+    pub fn read(self, caller: Caller<'_>, buf: &mut [u8]) -> io::Result<Option<usize>> {
         let mut reader = caller.read_vm(self.remote_ptr);
         let mut pos = 0;
         while let Some((_, unfilled)) = buf.split_at_mut_checked(pos) {
@@ -87,8 +96,9 @@ impl CStrPtr {
 }
 
 impl FromSyscallArg for CStrPtr {
+    #[expect(clippy::cast_possible_truncation, reason = "syscall arg represents a pointer address")]
     fn from_syscall_arg(arg: u64) -> io::Result<Self> {
-        Ok(Self { remote_ptr: arg as _ })
+        Ok(Self { remote_ptr: arg as usize })
     }
 }
 
@@ -98,20 +108,28 @@ pub struct Ptr<T> {
 }
 impl<T> FromSyscallArg for Ptr<T> {
     fn from_syscall_arg(arg: u64) -> io::Result<Self> {
-        Ok(Self { remote_ptr: arg as _, _marker: PhantomData })
+        Ok(Self { remote_ptr: arg as *mut c_void, _marker: PhantomData })
     }
 }
 impl<T> Ptr<T> {
     /// Reads the value of type T from the remote process memory.
-    /// # Safety:
+    ///
+    /// # Safety
     /// The remote pointer must be valid and point to a value of type T in the remote process memory.
+    ///
+    /// # Errors
+    /// Returns an error if reading from the remote process memory fails.
     pub unsafe fn read(&self, caller: Caller<'_>) -> io::Result<T> {
         let mut reader = caller.read_vm(self.remote_ptr as usize);
         let mut buf = MaybeUninit::<T>::zeroed();
+        // SAFETY: `MaybeUninit<T>` has the same layout as `T`, so casting to a
+        // byte slice of `size_of::<T>()` bytes is valid for writing into
         let buf_slice = unsafe {
-            std::slice::from_raw_parts_mut(buf.as_mut_ptr() as *mut u8, std::mem::size_of::<T>())
+            std::slice::from_raw_parts_mut(buf.as_mut_ptr().cast::<u8>(), std::mem::size_of::<T>())
         };
         reader.read_exact(buf_slice)?;
+        // SAFETY: all bytes of `buf` have been initialized by `read_exact`,
+        // and the caller guarantees the remote pointer points to a valid `T`
         Ok(unsafe { buf.assume_init() })
     }
 }
@@ -120,7 +138,7 @@ impl<T> Ptr<T> {
 pub struct Ignored(());
 impl FromSyscallArg for Ignored {
     fn from_syscall_arg(_arg: u64) -> io::Result<Self> {
-        Ok(Ignored(()))
+        Ok(Self(()))
     }
 }
 
@@ -130,20 +148,26 @@ pub struct Fd {
 }
 
 impl Fd {
-    pub fn cwd() -> Self {
+    #[must_use]
+    pub const fn cwd() -> Self {
         Self { fd: libc::AT_FDCWD }
     }
 }
 
 impl FromSyscallArg for Fd {
+    #[expect(clippy::cast_possible_truncation, reason = "syscall arg represents a file descriptor")]
     fn from_syscall_arg(arg: u64) -> io::Result<Self> {
-        Ok(Self { fd: arg as _ })
+        Ok(Self { fd: arg as RawFd })
     }
 }
 
 impl Fd {
     // TODO: allocate in arena
-    pub fn get_path(&self, caller: Caller<'_>) -> nix::Result<OsString> {
+    /// Returns the filesystem path associated with this file descriptor.
+    ///
+    /// # Errors
+    /// Returns an error if the `/proc` readlink fails (e.g., the process has exited).
+    pub fn get_path(self, caller: Caller<'_>) -> nix::Result<OsString> {
         nix::fcntl::readlink(
             if self.fd == libc::AT_FDCWD {
                 format!("/proc/{}/cwd", caller.pid)
@@ -156,12 +180,17 @@ impl Fd {
 }
 
 impl FromSyscallArg for c_int {
+    #[expect(clippy::cast_possible_truncation, reason = "syscall arg represents a c_int value")]
     fn from_syscall_arg(arg: u64) -> io::Result<Self> {
-        Ok(arg as _)
+        Ok(arg as Self)
     }
 }
 
 pub trait FromNotify: Sized {
+    /// Parses syscall arguments from a seccomp notification.
+    ///
+    /// # Errors
+    /// Returns an error if any argument cannot be parsed.
     fn from_notify(notif: &seccomp_notif) -> io::Result<Self>;
 }
 

crates/fspy_seccomp_unotify/src/supervisor/handler/mod.rs

@@ -4,8 +4,13 @@ use std::io;
 
 use libc::seccomp_notif;
 
+#[expect(clippy::module_name_repetitions, reason = "clearer as a standalone export")]
 pub trait SeccompNotifyHandler {
     fn syscalls() -> &'static [syscalls::Sysno];
+    /// Handles a seccomp notification for an intercepted syscall.
+    ///
+    /// # Errors
+    /// Returns an error if the handler fails to process the notification.
     fn handle_notify(&mut self, notify: &seccomp_notif) -> io::Result<()>;
 }