refactor(hardlink): introduce DeviceNumber newtype, reorder ino before dev

- Add DeviceNumber in src/device_number.rs, mirroring InodeNumber
- Reorder InodeKey fields to ino-first for faster derived PartialEq
  (ino has far more entropy than dev, so comparisons short-circuit earlier)
- Use DeviceNumber instead of raw u64 in InodeKey, ReflectionEntry, and
  all public/internal APIs
- Add dev to ConversionError::DuplicatedInode for precise error messages
- Add ConversionError::duplicated_inode(InodeKey) constructor
- Update sort keys to (ino, dev) order throughout

https://claude.ai/code/session_01QP9wZyoZcGmJsEsA66ZRok

Author: claude

src/device_number.rs

@@ -0,0 +1,23 @@
+use derive_more::{Display, From, Into, LowerHex, Octal, UpperHex};
+
+#[cfg(feature = "json")]
+use serde::{Deserialize, Serialize};
+
+/// The device number of a filesystem.
+#[derive(
+    Debug, Display, LowerHex, UpperHex, Octal, Clone, Copy, PartialEq, Eq, Hash, From, Into,
+)]
+#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
+pub struct DeviceNumber(u64);
+
+/// POSIX-exclusive functions.
+#[cfg(unix)]
+impl DeviceNumber {
+    /// Get device number of a [`std::fs::Metadata`].
+    #[inline]
+    pub fn get(stats: &std::fs::Metadata) -> Self {
+        use pipe_trait::Pipe;
+        use std::os::unix::fs::MetadataExt;
+        stats.dev().pipe(DeviceNumber)
+    }
+}

src/hardlink/aware.rs

@@ -4,6 +4,7 @@ use super::{
 };
 use crate::{
     data_tree::DataTree,
+    device_number::DeviceNumber,
     inode::InodeNumber,
     os_string_display::OsStringDisplay,
     reporter::{event::HardlinkDetection, Event, Reporter},
@@ -82,7 +83,7 @@ where
         }));
 
         let ino = InodeNumber::get(stats);
-        let dev = stats.dev();
+        let dev = DeviceNumber::get(stats);
         self.record
             .add(ino, dev, size, links, path)
             .map_err(ReportHardlinksError::AddToRecord)

src/hardlink/hardlink_list.rs

@@ -9,7 +9,7 @@ pub use summary::Summary;
 pub use Reflection as HardlinkListReflection;
 pub use Summary as SharedLinkSummary;
 
-use crate::{hardlink::LinkPathList, inode::InodeNumber, size};
+use crate::{device_number::DeviceNumber, hardlink::LinkPathList, inode::InodeNumber, size};
 use dashmap::DashMap;
 use derive_more::{Display, Error};
 use smart_default::SmartDefault;
@@ -28,10 +28,10 @@ use std::path::Path;
 /// for the same reason.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 struct InodeKey {
-    /// Device number of the filesystem the inode belongs to.
-    dev: u64,
     /// Inode number within the device.
     ino: InodeNumber,
+    /// Device number of the filesystem the inode belongs to.
+    dev: DeviceNumber,
 }
 
 /// Map value in [`HardlinkList`].
@@ -126,12 +126,12 @@ where
     pub(crate) fn add(
         &self,
         ino: InodeNumber,
-        dev: u64,
+        dev: DeviceNumber,
         size: Size,
         links: u64,
         path: &Path,
     ) -> Result<(), AddError<Size>> {
-        let key = InodeKey { dev, ino };
+        let key = InodeKey { ino, dev };
         let mut assertions = Ok(());
         self.0
             .entry(key)

src/hardlink/hardlink_list/iter.rs

@@ -1,5 +1,5 @@
 use super::{HardlinkList, InodeKey, Value};
-use crate::{hardlink::LinkPathList, inode::InodeNumber};
+use crate::{device_number::DeviceNumber, hardlink::LinkPathList, inode::InodeNumber};
 use dashmap::{iter::Iter as DashIter, mapref::multiple::RefMulti};
 use pipe_trait::Pipe;
 
@@ -30,18 +30,18 @@ impl<'a, Size> Iterator for Iter<'a, Size> {
 }
 
 impl<'a, Size> Item<'a, Size> {
-    /// The device number of the filesystem the inode belongs to.
-    #[inline]
-    pub fn dev(&self) -> u64 {
-        self.0.key().dev
-    }
-
     /// The inode number of the file.
     #[inline]
     pub fn ino(&self) -> InodeNumber {
         self.0.key().ino
     }
 
+    /// The device number of the filesystem the inode belongs to.
+    #[inline]
+    pub fn dev(&self) -> DeviceNumber {
+        self.0.key().dev
+    }
+
     /// Size of the file.
     #[inline]
     pub fn size(&self) -> &Size {

src/hardlink/hardlink_list/reflection.rs

@@ -1,5 +1,5 @@
 use super::{HardlinkList, InodeKey, Value};
-use crate::{hardlink::LinkPathListReflection, inode::InodeNumber};
+use crate::{device_number::DeviceNumber, hardlink::LinkPathListReflection, inode::InodeNumber};
 use dashmap::DashMap;
 use derive_more::{Display, Error, Into, IntoIterator};
 use into_sorted::IntoSortedUnstable;
@@ -48,10 +48,10 @@ impl<Size> Reflection<Size> {
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
 pub struct ReflectionEntry<Size> {
-    /// Device number of the filesystem the inode belongs to.
-    pub dev: u64,
     /// The inode number of the file.
     pub ino: InodeNumber,
+    /// Device number of the filesystem the inode belongs to.
+    pub dev: DeviceNumber,
     /// Size of the file.
     pub size: Size,
     /// Total number of links of the file, both listed (in [`Self::paths`]) and unlisted.
@@ -63,11 +63,11 @@ pub struct ReflectionEntry<Size> {
 impl<Size> ReflectionEntry<Size> {
     /// Create a new entry.
     #[inline]
-    fn new(InodeKey { dev, ino }: InodeKey, Value { size, links, paths }: Value<Size>) -> Self {
+    fn new(InodeKey { ino, dev }: InodeKey, Value { size, links, paths }: Value<Size>) -> Self {
         let paths = paths.into();
         ReflectionEntry {
-            dev,
             ino,
+            dev,
             size,
             links,
             paths,
@@ -78,21 +78,21 @@ impl<Size> ReflectionEntry<Size> {
     #[inline]
     fn dissolve(self) -> (InodeKey, Value<Size>) {
         let ReflectionEntry {
-            dev,
             ino,
+            dev,
             size,
             links,
             paths,
         } = self;
         let paths = paths.into();
-        (InodeKey { dev, ino }, Value { size, links, paths })
+        (InodeKey { ino, dev }, Value { size, links, paths })
     }
 }
 
 impl<Size> From<Vec<ReflectionEntry<Size>>> for Reflection<Size> {
     /// Sort the list by `(inode, device)`, then create the reflection.
     fn from(list: Vec<ReflectionEntry<Size>>) -> Self {
-        list.into_sorted_unstable_by_key(|entry| (u64::from(entry.ino), entry.dev))
+        list.into_sorted_unstable_by_key(|entry| (u64::from(entry.ino), u64::from(entry.dev)))
             .pipe(Reflection)
     }
 }
@@ -111,9 +111,20 @@ impl<Size> From<HardlinkList<Size>> for Reflection<Size> {
 #[derive(Debug, Display, Error, Clone, Copy, PartialEq, Eq)]
 #[non_exhaustive]
 pub enum ConversionError {
-    /// When the source has duplicated inode numbers.
-    #[display("Inode number {_0} is duplicated")]
-    DuplicatedInode(#[error(not(source))] InodeNumber),
+    /// When the source has a duplicated `(inode, device)` pair.
+    #[display("Inode {ino} on device {dev} is duplicated")]
+    DuplicatedInode {
+        #[error(not(source))]
+        ino: InodeNumber,
+        #[error(not(source))]
+        dev: DeviceNumber,
+    },
+}
+
+impl ConversionError {
+    fn duplicated_inode(InodeKey { ino, dev }: InodeKey) -> Self {
+        ConversionError::DuplicatedInode { ino, dev }
+    }
 }
 
 impl<Size> TryFrom<Reflection<Size>> for HardlinkList<Size> {
@@ -124,7 +135,7 @@ impl<Size> TryFrom<Reflection<Size>> for HardlinkList<Size> {
         for entry in entries {
             let (key, value) = entry.dissolve();
             if map.insert(key, value).is_some() {
-                return key.ino.pipe(ConversionError::DuplicatedInode).pipe(Err);
+                return key.pipe(ConversionError::duplicated_inode).pipe(Err);
             }
         }
 

src/hardlink/hardlink_list/test.rs

@@ -4,21 +4,21 @@ use pipe_trait::Pipe;
 use pretty_assertions::{assert_eq, assert_ne};
 
 const TABLE: &[(u64, u64, u64, u64, &str)] = &[
-    // dev, ino, size, links, path
-    (0, 241, 3652, 1, "a"),
-    (0, 569, 2210, 1, "b"),
-    (0, 110, 2350, 3, "c"),
-    (0, 110, 2350, 3, "c1"),
-    (0, 778, 1110, 1, "d"),
-    (0, 274, 6060, 2, "e"),
-    (0, 274, 6060, 2, "e1"),
-    (0, 883, 4530, 1, "f"),
+    // ino, dev, size, links, path
+    (241, 0, 3652, 1, "a"),
+    (569, 0, 2210, 1, "b"),
+    (110, 0, 2350, 3, "c"),
+    (110, 0, 2350, 3, "c1"),
+    (778, 0, 1110, 1, "d"),
+    (274, 0, 6060, 2, "e"),
+    (274, 0, 6060, 2, "e1"),
+    (883, 0, 4530, 1, "f"),
 ];
 
 fn add<const ROW: usize>(list: HardlinkList<Bytes>) -> HardlinkList<Bytes> {
     let values = TABLE[ROW];
-    let (dev, ino, size, links, path) = values;
-    if let Err(error) = list.add(ino.into(), dev, size.into(), links, path.as_ref()) {
+    let (ino, dev, size, links, path) = values;
+    if let Err(error) = list.add(ino.into(), dev.into(), size.into(), links, path.as_ref()) {
         panic!("Failed to add {values:?} (index: {ROW}) to the list: {error}");
     }
     list
@@ -120,10 +120,10 @@ fn insertion_difference_cause_inequality() {
 #[test]
 fn detect_size_change() {
     let list = HardlinkList::<Bytes>::new();
-    list.add(123.into(), 0, 100.into(), 1, "a".as_ref())
+    list.add(123.into(), 0.into(), 100.into(), 1, "a".as_ref())
         .expect("add the first path");
     let actual = list
-        .add(123.into(), 0, 110.into(), 1, "b".as_ref())
+        .add(123.into(), 0.into(), 110.into(), 1, "b".as_ref())
         .expect_err("add the second path");
     let expected = AddError::SizeConflict(SizeConflictError {
         ino: 123.into(),
@@ -136,10 +136,10 @@ fn detect_size_change() {
 #[test]
 fn detect_number_of_links_change() {
     let list = HardlinkList::<Bytes>::new();
-    list.add(123.into(), 0, 100.into(), 1, "a".as_ref())
+    list.add(123.into(), 0.into(), 100.into(), 1, "a".as_ref())
         .expect("add the first path");
     let actual = list
-        .add(123.into(), 0, 100.into(), 2, "b".as_ref())
+        .add(123.into(), 0.into(), 100.into(), 2, "b".as_ref())
         .expect_err("add the second path");
     let expected = AddError::NumberOfLinksConflict(NumberOfLinksConflictError {
         ino: 123.into(),
@@ -159,29 +159,29 @@ fn same_ino_on_different_devices_are_treated_separately() {
     let list = HardlinkList::<Bytes>::new();
 
     // dev=1, ino=100 — first filesystem
-    list.add(100.into(), 1, 50.into(), 2, "dev1/file_a".as_ref())
+    list.add(100.into(), 1.into(), 50.into(), 2, "dev1/file_a".as_ref())
         .expect("add dev1/file_a");
-    list.add(100.into(), 1, 50.into(), 2, "dev1/file_b".as_ref())
+    list.add(100.into(), 1.into(), 50.into(), 2, "dev1/file_b".as_ref())
         .expect("add dev1/file_b (same dev+ino → same inode group)");
 
     // dev=2, ino=100 — second filesystem, coincidentally same inode number
-    list.add(100.into(), 2, 80.into(), 2, "dev2/file_c".as_ref())
+    list.add(100.into(), 2.into(), 80.into(), 2, "dev2/file_c".as_ref())
         .expect("add dev2/file_c (different dev → separate inode group)");
-    list.add(100.into(), 2, 80.into(), 2, "dev2/file_d".as_ref())
+    list.add(100.into(), 2.into(), 80.into(), 2, "dev2/file_d".as_ref())
         .expect("add dev2/file_d (same dev+ino → same inode group as file_c)");
 
     // Each device should produce its own entry, so the list should have 2 entries.
-    assert_eq!(list.len(), 2, "expected one entry per (dev, ino) pair");
+    assert_eq!(list.len(), 2, "expected one entry per (ino, dev) pair");
 
     let reflection = list.into_reflection();
     assert_eq!(reflection.len(), 2);
 
     // Sorted by (ino, dev), so dev=1 comes first.
     let entries: Vec<_> = reflection.iter().collect();
-    assert_eq!(entries[0].dev, 1);
+    assert_eq!(entries[0].dev, 1.into());
     assert_eq!(entries[0].ino, 100.into());
     assert_eq!(entries[0].paths.len(), 2);
-    assert_eq!(entries[1].dev, 2);
+    assert_eq!(entries[1].dev, 2.into());
     assert_eq!(entries[1].ino, 100.into());
     assert_eq!(entries[1].paths.len(), 2);
 }

src/lib.rs

@@ -41,6 +41,7 @@ pub use clap_utilities;
 pub mod bytes_format;
 pub mod data_tree;
 pub mod device;
+pub mod device_number;
 pub mod fs_tree_builder;
 pub mod get_size;
 pub mod hardlink;

tests/_utils.rs

@@ -586,9 +586,10 @@ pub fn read_inode_number(path: &Path) -> u64 {
 
 /// Read [dev](std::os::unix::fs::MetadataExt::dev) of a path.
 #[cfg(unix)]
-pub fn read_device_number(path: &Path) -> u64 {
+pub fn read_device_number(path: &Path) -> parallel_disk_usage::device_number::DeviceNumber {
     use std::os::unix::fs::MetadataExt;
     path.pipe(symlink_metadata)
         .unwrap_or_else(|error| panic!("Can't read metadata at {path:?}: {error}"))
         .dev()
+        .into()
 }