test: contracts of IndexedList and IIndexedList, and the stable sorting contract

`StableSortContract` checks that `sort`, `sortBy`, `sortByDescending`, `sortDescending`, `sortWith` and
`sortWithComparer` keep the order of equal elements, as the `List` functions do. The pairs of `Inputs.pairs` show it for
the sorts by key; `sort` and `sortDescending` run on `KeyedItem`, whose comparison looks at a key only.

The sequence-like, creation, index-based and stable sorting contracts run for `IndexedList`, and all of them but the
creation contract for `IIndexedList`. Further tests cover null inputs, shared trees, `cons`, `uncons` and the patterns,
`binarySearch`, `blit`, the order in which the functions of two lists call their callbacks before they throw, the complete
messages of the `List` exceptions, the implementation that `IIndexedList` keeps, the builder functions,
`indexedList { }` and the `Option` and `Tuple` namespaces.

Two shared contracts now serve the modules that mirror `List` as well. `ofArray` of a null array is compared with
`Array.toList`, because `List.ofArray` reads a null array without a check. `removeManyAt` of a count that is not positive
is compared with what the mirrored function returns or throws, because `List.removeManyAt` removes nothing where
`Array.removeManyAt` copies by the count.

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

Author: xperiandri

tests/FSharp.Collections.Immutable.Tests/Contracts/IndexedContract.fs

@@ -206,14 +206,48 @@ type IndexedContract<'C> (ops : IndexedOps<'C>) =
     member this.``removeManyAt throws for a range out of range as FSharp.Core does`` () =
         let struct (collection, elements) = several ()
 
-        for struct (index, count) in [ struct (-1, 1); struct (elements.Length - 1, 2); struct (0, -1) ] do
+        for struct (index, count) in [ struct (-1, 1); struct (elements.Length - 1, 2) ] do
             this.ThrowsLikeFSharpCore (
                 (fun () -> Array.removeManyAt index count (List.toArray elements)),
                 (fun () -> List.removeManyAt index count elements),
                 (fun () -> ops.RemoveManyAt index count collection),
                 $"removeManyAt %d{index} %d{count} must throw"
             )
 
+    [<TestMethod; TestCategory(nameof FlatList.removeManyAt)>]
+    member this.``removeManyAt of a count that is not positive does what FSharp.Core does`` () =
+        let struct (collection, elements) = several ()
+
+        // List.removeManyAt removes nothing for such a count while index + count stays within the list, and throws
+        // otherwise; Array.removeManyAt copies by the count and throws or returns what the copies give
+        for struct (index, count) in [ struct (0, 0); struct (0, -1); struct (3, -2); struct (10, -5); struct (20, -5) ] do
+            let arrayOracle () =
+                Array.removeManyAt index count (List.toArray elements)
+                |> List.ofArray
+
+            let listOracle () = List.removeManyAt index count elements
+
+            let outcome =
+                try
+                    Ok (this.Mirrored (arrayOracle, listOracle))
+                with ex ->
+                    Error ex
+
+            match outcome with
+            | Ok expected ->
+                Assert.AreEqual<int list>(
+                    expected,
+                    ops.ToList (ops.RemoveManyAt index count collection),
+                    $"%s{ops.Name}.removeManyAt %d{index} %d{count} must return what FSharp.Core returns"
+                )
+            | Error _ ->
+                this.ThrowsLikeFSharpCore (
+                    arrayOracle,
+                    listOracle,
+                    (fun () -> ops.RemoveManyAt index count collection),
+                    $"removeManyAt %d{index} %d{count} must throw"
+                )
+
     [<TestMethod; TestCategory(nameof FlatList.updateAt)>]
     member _.``updateAt replaces the element at the index`` () =
         let struct (collection, elements) = several ()

tests/FSharp.Collections.Immutable.Tests/Contracts/SeqCreationContract.fs

@@ -48,9 +48,11 @@ type SeqCreationContract<'C> (ops : SeqCreationOps<'C>) =
     member this.``ofArray throws for a null array as FSharp.Core does`` () =
         let source = Unchecked.defaultof<int array>
 
+        // List.ofArray reads a null array without a check and fails with NullReferenceException, while a null input throws
+        // ArgumentNullException (ADR 0001, D6), as Array.toList does for the same conversion
         this.ThrowsLikeFSharpCore (
             (fun () -> Array.copy source),
-            (fun () -> List.ofArray source),
+            (fun () -> Array.toList source),
             (fun () -> ops.OfArray source),
             "ofArray of a null array must throw"
         )

tests/FSharp.Collections.Immutable.Tests/Contracts/StableSortContract.fs

@@ -0,0 +1,150 @@
+namespace FSharp.Collections.Immutable.Tests
+
+open System
+open System.Collections.Generic
+open FSharp.Collections.Immutable
+open Microsoft.VisualStudio.TestTools.UnitTesting
+
+/// <summary>An element whose equality and comparison look at its key only.</summary>
+/// <remarks>
+/// Elements with the same key and different tags compare equal, so a sort that compares whole elements, such as
+/// <c>sort</c>, shows on them whether it keeps the order of equal elements.
+/// </remarks>
+[<CustomEquality; CustomComparison>]
+type KeyedItem = {
+    /// The key that the equality and the comparison look at.
+    Key : int
+    /// The tag that tells the elements with the same key apart.
+    Tag : char
+} with
+
+    override this.Equals other =
+        match other with
+        | :? KeyedItem as other -> this.Key = other.Key
+        | _ -> false
+
+    override this.GetHashCode () = this.Key.GetHashCode ()
+
+    // F# generic comparison calls the non-generic interface
+    interface IComparable with
+        member this.CompareTo other =
+            match other with
+            | :? KeyedItem as other -> compare this.Key other.Key
+            | _ -> invalidArg (nameof other) "A keyed item compares with keyed items only"
+
+/// <summary>The sorting functions of a module that sorts stably, for the contract tests.</summary>
+/// <remarks>
+/// The elements are the pairs of <see cref="P:FSharp.Collections.Immutable.Tests.Inputs.pairs"/>: the functions sort them
+/// by the key in the first component, and the tag in the second component shows the order of the elements with equal keys.
+/// <c>Sort</c> and <c>SortDescending</c> compare whole elements and pairs never compare equal, so they take
+/// <see cref="T:FSharp.Collections.Immutable.Tests.KeyedItem"/> elements instead, and the instance creates and reads the
+/// collection itself, as <c>SeqOps.Unzip</c> does for its pairs.
+/// </remarks>
+type StableSortOps<'C> = {
+    /// The name of the module, for the messages of the assertions.
+    Name : string
+    /// Creates a collection that enumerates the given elements in their order.
+    OfSeq : seq<struct (int * char)> -> 'C
+    /// The elements in the order in which the collection enumerates them.
+    ToList : 'C -> struct (int * char) list
+
+    /// Sorts a collection of the given keyed items.
+    Sort : KeyedItem list -> KeyedItem list
+    SortBy : (struct (int * char) -> int) -> 'C -> 'C
+    SortByDescending : (struct (int * char) -> int) -> 'C -> 'C
+    /// Sorts a collection of the given keyed items in descending order.
+    SortDescending : KeyedItem list -> KeyedItem list
+    SortWith : (struct (int * char) -> struct (int * char) -> int) -> 'C -> 'C
+    SortWithComparer : IComparer<struct (int * char)> -> 'C -> 'C
+}
+
+/// <summary>
+/// The contract of the modules that sort stably, as <see cref="T:Microsoft.FSharp.Collections.ListModule"/> does:
+/// <c>IndexedList</c>, <c>IIndexedList</c>, <c>Queue</c>, <c>IQueue</c>, <c>Stack</c> and <c>IStack</c> (ADR 0001, D5).
+/// </summary>
+/// <remarks>
+/// The expectations come from the stable sorts of <c>List</c> over the elements in the order in which the collection
+/// enumerates them. <c>FlatList</c> sorts unstably, as <c>Array</c> does, and has no such contract.
+/// </remarks>
+[<AbstractClass>]
+type StableSortContract<'C> (ops : StableSortOps<'C>) =
+
+    static let key (struct (key : int, _ : char)) = key
+
+    static let compareKeys (left : struct (int * char)) (right : struct (int * char)) = compare (key left) (key right)
+
+    /// The keyed items of the pairs of the input, in their order.
+    static let keyedItems =
+        Inputs.pairs
+        |> List.map (fun struct (key, tag) -> { Key = key; Tag = tag })
+
+    /// The keys and the tags of keyed items, which tell apart the items that compare equal.
+    static let keysAndTags (items : KeyedItem list) = items |> List.map (fun item -> struct (item.Key, item.Tag))
+
+    /// The collection of the input pairs and the elements that it enumerates.
+    let pairs () =
+        let collection = ops.OfSeq Inputs.pairs
+        struct (collection, ops.ToList collection)
+
+    [<TestMethod; TestCategory(nameof IndexedList.sort)>]
+    member _.``sort keeps the order of the elements that compare equal`` () =
+        Assert.AreEqual<struct (int * char) list>(
+            List.sort keyedItems |> keysAndTags,
+            ops.Sort keyedItems |> keysAndTags,
+            $"%s{ops.Name}.sort must keep the order of equal elements, as List.sort does"
+        )
+
+    [<TestMethod; TestCategory(nameof IndexedList.sortBy)>]
+    member _.``sortBy keeps the order of the elements with equal keys`` () =
+        let struct (collection, elements) = pairs ()
+
+        Assert.AreEqual<struct (int * char) list>(
+            List.sortBy key elements,
+            ops.ToList (ops.SortBy key collection),
+            $"%s{ops.Name}.sortBy must keep the order of equal keys, as List.sortBy does"
+        )
+
+    [<TestMethod; TestCategory(nameof IndexedList.sortByDescending)>]
+    member _.``sortByDescending keeps the order of the elements with equal keys`` () =
+        let struct (collection, elements) = pairs ()
+
+        Assert.AreEqual<struct (int * char) list>(
+            List.sortByDescending key elements,
+            ops.ToList (ops.SortByDescending key collection),
+            $"%s{ops.Name}.sortByDescending must keep the order of equal keys, as List.sortByDescending does"
+        )
+
+    [<TestMethod; TestCategory(nameof IndexedList.sortDescending)>]
+    member _.``sortDescending keeps the order of the elements that compare equal`` () =
+        Assert.AreEqual<struct (int * char) list>(
+            List.sortDescending keyedItems |> keysAndTags,
+            ops.SortDescending keyedItems |> keysAndTags,
+            $"%s{ops.Name}.sortDescending must keep the order of equal elements, as List.sortDescending does"
+        )
+
+    [<TestMethod; TestCategory(nameof IndexedList.sortWith)>]
+    member _.``sortWith keeps the order of the elements that compare equal`` () =
+        let struct (collection, elements) = pairs ()
+
+        for struct (direction, comparer) in
+            [
+                struct ("ascending", compareKeys)
+                struct ("descending", (fun left right -> compareKeys right left))
+            ] do
+            Assert.AreEqual<struct (int * char) list>(
+                List.sortWith comparer elements,
+                ops.ToList (ops.SortWith comparer collection),
+                $"%s{ops.Name}.sortWith %s{direction} must keep the order of equal elements, as List.sortWith does"
+            )
+
+    [<TestMethod; TestCategory(nameof IndexedList.sortWithComparer)>]
+    member _.``sortWithComparer keeps the order of the elements that compare equal`` () =
+        let struct (collection, elements) = pairs ()
+
+        Assert.AreEqual<struct (int * char) list>(
+            List.sortWith compareKeys elements,
+            ops.ToList (
+                ops.SortWithComparer (Comparer<struct (int * char)>.Create (fun left right -> compareKeys left right)) collection
+            ),
+            $"%s{ops.Name}.sortWithComparer must keep the order of equal elements, as List.sortWith does"
+        )

tests/FSharp.Collections.Immutable.Tests/FSharp.Collections.Immutable.Tests.fsproj

@@ -33,6 +33,7 @@
     <Compile Include="Contracts\SeqLike\SeqLikeContract.fs" />
     <Compile Include="Contracts\SeqCreationContract.fs" />
     <Compile Include="Contracts\IndexedContract.fs" />
+    <Compile Include="Contracts\StableSortContract.fs" />
     <Compile Include="TestCategoriesTests.fs" />
     <Compile Include="FlatList\FlatListOps.fs" />
     <Compile Include="FlatList\FlatListContractTests.fs" />
@@ -41,6 +42,16 @@
     <Compile Include="FlatList\FlatListComputationExpressionTests.fs" />
     <Compile Include="FlatList\FlatListOptionTests.fs" />
     <Compile Include="FlatList\FlatListTupleTests.fs" />
+    <Compile Include="IndexedList\IndexedListOps.fs" />
+    <Compile Include="IndexedList\IndexedListContractTests.fs" />
+    <Compile Include="IndexedList\IndexedListTests.fs" />
+    <Compile Include="IndexedList\IIndexedListTests.fs" />
+    <Compile Include="IndexedList\IndexedListBuilderTests.fs" />
+    <Compile Include="IndexedList\IndexedListComputationExpressionTests.fs" />
+    <Compile Include="IndexedList\IndexedListOptionTests.fs" />
+    <Compile Include="IndexedList\IndexedListTupleTests.fs" />
+    <Compile Include="IndexedList\IIndexedListOptionTests.fs" />
+    <Compile Include="IndexedList\IIndexedListTupleTests.fs" />
   </ItemGroup>
 
   <ItemGroup>