Feature/readonly collections and adapters

Directory.Packages.props

@@ -10,6 +10,13 @@
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="MinVer" Version="7.0.0" />
     <PackageVersion Include="System.Text.Json" Version="10.0.8" />
+    <PackageVersion Include="FsCheck" Version="3.3.3" />
+    <PackageVersion Include="FsCheck.Xunit.v3" Version="3.3.3" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
+    <PackageVersion Include="MessagePack.Annotations" Version="2.5.108" />
+
     <PackageVersion Include="Verify.XunitV3" Version="31.16.3" />
     <PackageVersion Include="xunit.v3.mtp-v2" Version="3.2.2" />
   </ItemGroup>

Equatable.Generator.slnx

@@ -12,5 +12,9 @@
   </Folder>
   <Project Path="src/Equatable.Comparers/Equatable.Comparers.csproj" />
   <Project Path="src/Equatable.Generator/Equatable.Generator.csproj" />
+  <Project Path="src/Equatable.Generator.DataContract/Equatable.Generator.DataContract.csproj" />
+  <Project Path="src/Equatable.Generator.MessagePack/Equatable.Generator.MessagePack.csproj" />
   <Project Path="src/Equatable.SourceGenerator/Equatable.SourceGenerator.csproj" />
+  <Project Path="src/Equatable.SourceGenerator.DataContract/Equatable.SourceGenerator.DataContract.csproj" />
+  <Project Path="src/Equatable.SourceGenerator.MessagePack/Equatable.SourceGenerator.MessagePack.csproj" />
 </Solution>

src/Equatable.Comparers/DictionaryEqualityComparer.cs

@@ -53,9 +53,14 @@ public bool Equals(IDictionary<TKey, TValue>? x, IDictionary<TKey, TValue>? y)
         if (x.Count != y.Count)
             return false;
 
+        // y.TryGetValue uses y's own internal comparer, not this.KeyComparer.
+        // Build a lookup keyed by KeyComparer so the same comparer governs both
+        // Equals and GetHashCode — required for the hash contract to hold.
+        var yLookup = new Dictionary<TKey, TValue>(y, KeyComparer);
+
         foreach (var pair in x)
         {
-            if (!y.TryGetValue(pair.Key, out var value))
+            if (!yLookup.TryGetValue(pair.Key, out var value))
                 return false;
 
             if (!ValueComparer.Equals(pair.Value, value))
@@ -71,15 +76,21 @@ public int GetHashCode(IDictionary<TKey, TValue> obj)
         if (obj == null)
             return 0;
 
-        var hash = new HashCode();
+        // Start at 1, not 0: an empty dictionary must not hash the same as null.
+        // Equals correctly returns false for (null, empty), so GetHashCode must also
+        // differ — otherwise a hash table would bucket them together and force an Equals
+        // call that returns false, producing unnecessary collisions. null returns 0 above;
+        // 1 here ensures an empty collection is always distinguishable.
+        int hashCode = 1;
 
-        // sort by key to ensure dictionary with different order are the same
-        foreach (var pair in obj.OrderBy(d => d.Key))
-        {
-            hash.Add(pair.Key, KeyComparer);
-            hash.Add(pair.Value, ValueComparer);
-        }
+        // Commutative SUM ensures hash is insertion-order independent, consistent with
+        // Equals which uses TryGetValue (also order-independent). Previously GetHashCode
+        // used OrderBy + sequential HashCode.Add, which was order-dependent and violated
+        // the contract: two equal dictionaries (same keys/values, different insertion order)
+        // would produce different hash codes.
+        foreach (var pair in obj)
+            hashCode += HashCode.Combine(KeyComparer.GetHashCode(pair.Key!), ValueComparer.GetHashCode(pair.Value!));
 
-        return hash.ToHashCode();
+        return hashCode;
     }
 }

src/Equatable.Comparers/HashSetEqualityComparer.cs

@@ -56,12 +56,21 @@ public int GetHashCode(IEnumerable<TValue> obj)
         if (obj == null)
             return 0;
 
-        var hashCode = new HashCode();
+        // Start at 1, not 0: an empty set must not hash the same as null.
+        // Equals correctly returns false for (null, empty), so GetHashCode must also
+        // differ — otherwise a hash table would bucket them together and force an Equals
+        // call that returns false, producing unnecessary collisions. null returns 0 above;
+        // 1 here ensures an empty collection is always distinguishable.
+        int hashCode = 1;
 
-        // sort to ensure set with different order are the same
-        foreach (var item in obj.OrderBy(s => s))
-            hashCode.Add(item, Comparer);
+        // Commutative SUM ensures hash is iteration-order independent, consistent with
+        // Equals which uses SetEquals (also order-independent). Previously GetHashCode
+        // used OrderBy + sequential HashCode.Add, which was order-dependent and violated
+        // the contract: two equal sets (same elements, different insertion order) could
+        // produce different hash codes.
+        foreach (var item in obj)
+            hashCode += Comparer.GetHashCode(item!);
 
-        return hashCode.ToHashCode();
+        return hashCode;
     }
 }

src/Equatable.Comparers/MultiDimensionalArrayEqualityComparer.cs

@@ -0,0 +1,78 @@
+namespace Equatable.Comparers;
+
+/// <summary>
+/// Structural equality comparer for multi-dimensional arrays (T[,], T[,,], etc.).
+/// Compares element-by-element in row-major order without LINQ or intermediate allocations.
+/// </summary>
+/// <typeparam name="TValue">The element type of the array.</typeparam>
+public class MultiDimensionalArrayEqualityComparer<TValue> : IEqualityComparer<Array?>
+{
+    /// <summary>
+    /// Gets the default equality comparer for the specified element type.
+    /// </summary>
+    public static MultiDimensionalArrayEqualityComparer<TValue> Default { get; } = new();
+
+    /// <summary>
+    /// Initializes a new instance using the default element comparer.
+    /// </summary>
+    public MultiDimensionalArrayEqualityComparer() : this(EqualityComparer<TValue>.Default)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance using the specified element comparer.
+    /// </summary>
+    public MultiDimensionalArrayEqualityComparer(IEqualityComparer<TValue> comparer)
+    {
+        Comparer = comparer ?? throw new ArgumentNullException(nameof(comparer));
+    }
+
+    /// <summary>
+    /// Gets the element comparer.
+    /// </summary>
+    public IEqualityComparer<TValue> Comparer { get; }
+
+    /// <inheritdoc />
+    public bool Equals(Array? x, Array? y)
+    {
+        if (ReferenceEquals(x, y))
+            return true;
+
+        if (x is null || y is null)
+            return false;
+
+        if (x.Rank != y.Rank)
+            return false;
+
+        for (int dim = 0; dim < x.Rank; dim++)
+        {
+            if (x.GetLength(dim) != y.GetLength(dim))
+                return false;
+        }
+
+        var ex = x.GetEnumerator();
+        var ey = y.GetEnumerator();
+        while (ex.MoveNext())
+        {
+            ey.MoveNext();
+            if (!Comparer.Equals((TValue)ex.Current!, (TValue)ey.Current!))
+                return false;
+        }
+
+        return true;
+    }
+
+    /// <inheritdoc />
+    public int GetHashCode(Array? obj)
+    {
+        if (obj is null)
+            return 0;
+
+        var hashCode = new HashCode();
+        var e = obj.GetEnumerator();
+        while (e.MoveNext())
+            hashCode.Add((TValue)e.Current!, Comparer);
+
+        return hashCode.ToHashCode();
+    }
+}

src/Equatable.Comparers/ReadOnlyDictionaryEqualityComparer.cs

@@ -0,0 +1,91 @@
+namespace Equatable.Comparers;
+
+/// <summary>
+/// <see cref="IReadOnlyDictionary{TKey, TValue}"/> equality comparer instance
+/// </summary>
+/// <typeparam name="TKey">The type of the keys in the dictionary.</typeparam>
+/// <typeparam name="TValue">The type of the values in the dictionary.</typeparam>
+public class ReadOnlyDictionaryEqualityComparer<TKey, TValue> : IEqualityComparer<IReadOnlyDictionary<TKey, TValue>>
+{
+    /// <summary>
+    /// Gets the default equality comparer for specified generic argument.
+    /// </summary>
+    public static ReadOnlyDictionaryEqualityComparer<TKey, TValue> Default { get; } = new();
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ReadOnlyDictionaryEqualityComparer{TKey, TValue}" /> class.
+    /// </summary>
+    public ReadOnlyDictionaryEqualityComparer() : this(EqualityComparer<TKey>.Default, EqualityComparer<TValue>.Default)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ReadOnlyDictionaryEqualityComparer{TKey, TValue}" /> class.
+    /// </summary>
+    /// <param name="keyComparer">The <see cref="IEqualityComparer{TKey}"/> that is used to determine equality of keys in a dictionary</param>
+    /// <param name="valueComparer">The <see cref="IEqualityComparer{TValue}"/> that is used to determine equality of values in a dictionary</param>
+    /// <exception cref="ArgumentNullException"><paramref name="keyComparer"/> or <paramref name="valueComparer"/> is null</exception>
+    public ReadOnlyDictionaryEqualityComparer(IEqualityComparer<TKey> keyComparer, IEqualityComparer<TValue> valueComparer)
+    {
+        KeyComparer = keyComparer ?? throw new ArgumentNullException(nameof(keyComparer));
+        ValueComparer = valueComparer ?? throw new ArgumentNullException(nameof(valueComparer));
+    }
+
+    /// <summary>
+    /// Gets the <see cref="IEqualityComparer{TKey}"/> that is used to determine equality of keys in a dictionary
+    /// </summary>
+    public IEqualityComparer<TKey> KeyComparer { get; }
+
+    /// <summary>
+    /// Gets the <see cref="IEqualityComparer{TValue}"/> that is used to determine equality of values in a dictionary
+    /// </summary>
+    public IEqualityComparer<TValue> ValueComparer { get; }
+
+    /// <inheritdoc />
+    public bool Equals(IReadOnlyDictionary<TKey, TValue>? x, IReadOnlyDictionary<TKey, TValue>? y)
+    {
+        if (ReferenceEquals(x, y))
+            return true;
+
+        if (x is null || y is null)
+            return false;
+
+        if (x.Count != y.Count)
+            return false;
+
+        // y.TryGetValue uses y's own internal comparer, not this.KeyComparer.
+        // Build a lookup keyed by KeyComparer so the same comparer governs both
+        // Equals and GetHashCode — required for the hash contract to hold.
+        var yLookup = new Dictionary<TKey, TValue>(y, KeyComparer);
+
+        foreach (var pair in x)
+        {
+            if (!yLookup.TryGetValue(pair.Key, out var value))
+                return false;
+
+            if (!ValueComparer.Equals(pair.Value, value))
+                return false;
+        }
+
+        return true;
+    }
+
+    /// <inheritdoc />
+    public int GetHashCode(IReadOnlyDictionary<TKey, TValue> obj)
+    {
+        if (obj == null)
+            return 0;
+
+        // Start at 1, not 0: an empty dictionary must not hash the same as null.
+        // Equals correctly returns false for (null, empty), so GetHashCode must also
+        // differ — otherwise a hash table would bucket them together and force an Equals
+        // call that returns false, producing unnecessary collisions. null returns 0 above;
+        // 1 here ensures an empty collection is always distinguishable.
+        int hashCode = 1;
+
+        foreach (var pair in obj)
+            hashCode += HashCode.Combine(KeyComparer.GetHashCode(pair.Key!), ValueComparer.GetHashCode(pair.Value!));
+
+        return hashCode;
+    }
+}

src/Equatable.Generator.DataContract/Attributes/DataContractEquatableAttribute.cs

@@ -0,0 +1,12 @@
+using System.Diagnostics;
+
+namespace Equatable.Attributes.DataContract;
+
+/// <summary>
+/// Marks the class to source generate overrides for Equals and GetHashCode,
+/// including only properties decorated with <see cref="System.Runtime.Serialization.DataMemberAttribute"/>
+/// and excluding properties decorated with <see cref="System.Runtime.Serialization.IgnoreDataMemberAttribute"/>.
+/// </summary>
+[Conditional("EQUATABLE_GENERATOR")]
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
+public class DataContractEquatableAttribute : Attribute;

src/Equatable.Generator.DataContract/Equatable.Generator.DataContract.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>netstandard2.0;net8.0;net9.0;net10.0</TargetFrameworks>
+    <RootNamespace>Equatable</RootNamespace>
+    <Description>Source generator for Equals and GetHashCode for types using System.Runtime.Serialization DataMember attributes</Description>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="..\Equatable.SourceGenerator\bin\$(Configuration)\netstandard2.0\Equatable.SourceGenerator.dll" PackagePath="analyzers/dotnet/roslyn4.8/cs" Pack="true" Visible="false" />
+    <None Include="..\Equatable.SourceGenerator.DataContract\bin\$(Configuration)\netstandard2.0\Equatable.SourceGenerator.DataContract.dll" PackagePath="analyzers/dotnet/roslyn4.8/cs" Pack="true" Visible="false" />
+    <None Include="..\Equatable.SourceGenerator\Equatable.Generator.targets" PackagePath="build" Pack="true" Visible="false" />
+  </ItemGroup>
+
+</Project>

src/Equatable.Generator.MessagePack/Attributes/MessagePackEquatableAttribute.cs

@@ -0,0 +1,12 @@
+using System.Diagnostics;
+
+namespace Equatable.Attributes.MessagePack;
+
+/// <summary>
+/// Marks the class to source generate overrides for Equals and GetHashCode,
+/// including only properties decorated with <c>MessagePack.KeyAttribute</c>
+/// and excluding properties decorated with <c>MessagePack.IgnoreMemberAttribute</c>.
+/// </summary>
+[Conditional("EQUATABLE_GENERATOR")]
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
+public class MessagePackEquatableAttribute : Attribute;

src/Equatable.Generator.MessagePack/Equatable.Generator.MessagePack.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>netstandard2.0;net8.0;net9.0;net10.0</TargetFrameworks>
+    <RootNamespace>Equatable</RootNamespace>
+    <Description>Source generator for Equals and GetHashCode for types using MessagePack Key attributes</Description>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="..\Equatable.SourceGenerator\bin\$(Configuration)\netstandard2.0\Equatable.SourceGenerator.dll" PackagePath="analyzers/dotnet/roslyn4.8/cs" Pack="true" Visible="false" />
+    <None Include="..\Equatable.SourceGenerator.MessagePack\bin\$(Configuration)\netstandard2.0\Equatable.SourceGenerator.MessagePack.dll" PackagePath="analyzers/dotnet/roslyn4.8/cs" Pack="true" Visible="false" />
+    <None Include="..\Equatable.SourceGenerator\Equatable.Generator.targets" PackagePath="build" Pack="true" Visible="false" />
+  </ItemGroup>
+
+</Project>

src/Equatable.Generator/Attributes/DictionaryEqualityAttribute.cs

@@ -3,8 +3,11 @@
 namespace Equatable.Attributes;
 
 /// <summary>
-/// Use a dictionary based comparer to determine if dictionaries are equal
+/// Use a dictionary based comparer to determine if dictionaries are equal.
+/// Two dictionaries are equal when they contain the same key/value pairs, regardless of insertion order.
 /// </summary>
 [Conditional("EQUATABLE_GENERATOR")]
 [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field)]
-public class DictionaryEqualityAttribute : Attribute;
+public class DictionaryEqualityAttribute : Attribute
+{
+}

src/Equatable.Generator/Attributes/HashSetEqualityAttribute.cs

@@ -3,7 +3,8 @@
 namespace Equatable.Attributes;
 
 /// <summary>
-/// Use <see cref="ISet{T}.SetEquals(IEnumerable{T})"/> in Equals and GetHashCode implementations
+/// Use <see cref="ISet{T}.SetEquals(IEnumerable{T})"/> in Equals and GetHashCode implementations.
+/// Comparison is order-independent — use <see cref="SequenceEqualityAttribute"/> for order-sensitive comparison.
 /// </summary>
 [Conditional("EQUATABLE_GENERATOR")]
 [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field)]

src/Equatable.SourceGenerator.DataContract/AnalyzerReleases.Shipped.md

@@ -0,0 +1,2 @@
+; Shipped analyzer releases
+; https://github.com/dotnet/roslyn-analyzers/blob/master/src/Microsoft.CodeAnalysis.Analyzers/ReleaseTrackingAnalyzers.Help.md

src/Equatable.SourceGenerator.DataContract/AnalyzerReleases.Unshipped.md

@@ -0,0 +1,8 @@
+; Unshipped analyzer release
+; https://github.com/dotnet/roslyn-analyzers/blob/master/src/Microsoft.CodeAnalysis.Analyzers/ReleaseTrackingAnalyzers.Help.md
+
+### New Rules
+
+Rule ID | Category | Severity | Notes
+--------|----------|----------|------------------
+EQ0020  | Usage    | Warning  | DataContractEquatableAnalyzer