chore: lay the foundation for the per-collection modules

Prepares the chain of ADR 0001, one pull request per collection:

- `Helper.fs` replaces `ImmutableCollectionUtil.fs` and adds
  `checkNotDefault`, which treats a default `ImmutableArray` as
  FSharp.Core treats a `null` array.
- `build/check-order.fsx` checks that every signature file groups its
  functions under category banners in the canonical order, sorts them
  alphabetically inside a category and that the implementation file
  repeats that order. The FAKE target `CheckOrder` runs it before
  `DotnetBuild`.
- The library and the tests target `net8.0` and `net10.0`; FSharp.Core
  10.1.301 is the first release with `partitionWith`.
- The placeholder tests are replaced by the category attributes of
  every collection, tests that enforce the category rules, and the
  shared helpers of the contract tests: inputs, the comparison of an
  exception with the FSharp.Core oracle, and the comparison of the
  `Option` and `Tuple` overrides with the default functions.
- The README and the documentation pages list the collections in a
  table that each following pull request updates.

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

Author: xperiandri

.github/copilot-instructions.md

@@ -15,56 +15,71 @@
 ```text
 /
 ├── build/                                              – FAKE build scripts and release automation
+│   └── check-order.fsx                                 – checks the category order of the signature files
 ├── docsSrc/                                            – FSharp.Formatting documentation source
 ├── src/FSharp.Collections.Immutable/                    – main library
-│   ├── Helper.fs
-│   ├── ComputationExpressions.fs
+│   ├── Helper.fs                                       – argument checks and exceptions shared by the modules
 │   ├── FlatList/                                       – ImmutableArray API surface and builders
-│   │   ├── FlatList.fs / FlatList.fsi
+│   │   ├── FlatList.fs / FlatList.fsi                  – includes the nested Parallel module
+│   │   ├── FlatListOption.fs / FlatListOption.fsi      – Option namespace overrides
+│   │   ├── FlatListTuple.fs / FlatListTuple.fsi        – Tuple namespace overrides
 │   │   ├── FlatListBuilder.fs
 │   │   └── FlatListCE.fs
 │   ├── IndexedList/                                    – ImmutableList API surface and builders
-│   │   ├── IIndexedList.fs / IIndexedList.fsi
-│   │   ├── IndexedList.fs / IndexedList.fsi
+│   │   ├── IndexedList.fs / IndexedList.fsi (+ Option / Tuple)
+│   │   ├── IIndexedList.fs / IIndexedList.fsi (+ Option / Tuple)
 │   │   ├── IndexedListBuilder.fs
 │   │   └── IndexedListCE.fs
 │   ├── Queue/                                          – ImmutableQueue API surface and CE
-│   │   ├── IQueue.fs / IQueue.fsi
-│   │   ├── Queue.fs / Queue.fsi
+│   │   ├── Queue.fs / Queue.fsi (+ Option / Tuple)
+│   │   ├── IQueue.fs / IQueue.fsi (+ Option / Tuple)
 │   │   └── QueueCE.fs
 │   ├── Stack/                                          – ImmutableStack API surface and CE
-│   │   ├── IStack.fs / IStack.fsi
-│   │   ├── Stack.fs / Stack.fsi
+│   │   ├── Stack.fs / Stack.fsi (+ Option / Tuple)
+│   │   ├── IStack.fs / IStack.fsi (+ Option / Tuple)
 │   │   └── StackCE.fs
 │   ├── HashMap/                                        – ImmutableDictionary API surface and CE
-│   │   ├── IHashMap.fs / IHashMap.fsi
-│   │   ├── HashMap.fs / HashMap.fsi
+│   │   ├── HashMap.fs / HashMap.fsi (+ Option / Tuple)
+│   │   ├── IMap.fs / IMap.fsi (+ Option / Tuple)
 │   │   └── HashMapCE.fs
 │   ├── SortedMap/                                      – ImmutableSortedDictionary API surface and CE
-│   │   ├── ISortedMap.fs / ISortedMap.fsi
-│   │   ├── SortedMap.fs / SortedMap.fsi
+│   │   ├── SortedMap.fs / SortedMap.fsi (+ Option / Tuple)
 │   │   └── SortedMapCE.fs
 │   ├── HashSet/                                        – ImmutableHashSet API surface and CE
-│   │   ├── IHashSet.fs / IHashSet.fsi
-│   │   ├── HashSet.fs / HashSet.fsi
+│   │   ├── HashSet.fs / HashSet.fsi (+ Option / Tuple)
+│   │   ├── ISet.fs / ISet.fsi (+ Option / Tuple)
 │   │   └── HashSetCE.fs
-│   └── SortedSet/                                      – ImmutableSortedSet API surface and CE
-│       ├── ISortedSet.fs / ISortedSet.fsi
-│       ├── SortedSet.fs / SortedSet.fsi
-│       └── SortedSetCE.fs
+│   ├── SortedSet/                                      – ImmutableSortedSet API surface and CE
+│   │   ├── SortedSet.fs / SortedSet.fsi (+ Option / Tuple)
+│   │   └── SortedSetCE.fs
+│   ├── FrozenMap/                                      – FrozenDictionary API surface and CE
+│   │   ├── FrozenMap.fs / FrozenMap.fsi (+ Option / Tuple)
+│   │   └── FrozenMapCE.fs
+│   ├── FrozenSet/                                      – FrozenSet API surface and CE
+│   │   ├── FrozenSet.fs / FrozenSet.fsi (+ Option / Tuple)
+│   │   └── FrozenSetCE.fs
+│   └── ComputationExpressions.fs                       – the computation expression instances
 └── tests/FSharp.Collections.Immutable.Tests/            – MSTest test project
-    ├── HelperTests.fs
     ├── TestCategories.fs                               – centralized custom test category attributes
-    ├── FlatList/                                       – focused test files per operation group
-    ├── IndexedList/                                    – focused test files per operation group
-    ├── HashMap/                                        – focused test files per operation group
-    ├── SortedMap/                                      – focused test files per operation group
-    ├── HashSet/                                        – focused test files per operation group
-    ├── SortedSet/                                      – focused test files per operation group
-    ├── Queue/                                          – focused test files per operation group
-    └── Stack/                                          – focused test files per operation group
+    ├── TestCategoriesTests.fs                          – enforces the test category rules
+    ├── Contracts/                                      – shared contract bases, inputs and assertion helpers
+    └── <Collection>/                                   – ops records, contract classes, collection-specific,
+                                                          builder, computation expression, Option and Tuple tests
 ```
 
+The modules follow ADR 0001 – Per-collection modules (`docsSrc/Explanations/ADR_0001_Collection_Modules.md`):
+
+* Each module groups its functions under banner comments `// ---- Category ----` in the order `Creation`, `Builder`,
+  `Properties`, `Access`, `Search`, `Transformation`, `Folding`, `Partitioning and grouping`, `Sorting`, `Random`,
+  `Conversion`, `Type-specific`, and sorts the functions of a category alphabetically (ordinal), active patterns last.
+  The `.fs` file repeats the order of its `.fsi` file. `build/check-order.fsx` (FAKE target `CheckOrder`) enforces it.
+* `try*` functions return `voption`, tuples are struct tuples. The namespaces `FSharp.Collections.Immutable.Option` and
+  `FSharp.Collections.Immutable.Tuple` repeat these functions with `option` results and reference tuples.
+* A function throws what the FSharp.Core function of the mirrored module throws for the same input: `Array` for
+  `FlatList`, `List` for the other sequence-like modules, `Map` and `Set` for maps and sets.
+* Contract test bases in `Contracts/` take a record of the module's functions; a collection derives one test class per
+  capability that it supports. Expected values and exceptions come from FSharp.Core.
+
 ## Libraries in Use
 
 * [`System.Collections.Immutable`](https://www.nuget.org/packages/System.Collections.Immutable/) – immutable collections foundation

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+* The package targets `net8.0` and `net10.0`.
+* The package requires FSharp.Core 10.1.301 or later, the first release with `partitionWith`.
+
 ## [1.0.0] - 2020-02-23
 
 First release

Directory.Packages.props

@@ -9,7 +9,7 @@
   </ItemGroup>
   <ItemGroup Label="FSharp">
     <PackageVersion Include="FSharp.Control.Reactive" Version="6.1.2" />
-    <PackageVersion Include="FSharp.Core" Version="10.0.100" />
+    <PackageVersion Include="FSharp.Core" Version="10.1.301" />
   </ItemGroup>
   <ItemGroup Label="Build and Test">
     <PackageVersion Include="Argu" Version="6.2.5" />

README.md

@@ -10,15 +10,17 @@ Please also join the [F# Open Source Group](http://fsharp.github.com)
 
 ## Features
 
-* `FlatList` (`ImmutableArray`)
-* `ImmutableList`
-* `Stack` (`ImmutableStack`)
-* `Queue` (`ImmutableQueue`)
-* `HashMap` (`ImmutableDictionary`)
-* `SortedMap` (`ImmutableSortedDictionary`)
-* `HashSet` (`ImmutableHashSet`)
-* `SortedSet` (`ImmutableSortedSet`)
-* `IIndexedSeq` (`IReadOnlyList`)
+| Module | .NET type | Computation expression |
+|---|---|---|
+| `FlatList` | `ImmutableArray<'T>` | – |
+| `ImmutableList` | `ImmutableList<'T>` | – |
+| `Stack` | `ImmutableStack<'T>` | – |
+| `Queue` | `ImmutableQueue<'T>` | – |
+| `HashMap` | `ImmutableDictionary<'Key, 'Value>` | – |
+| `SortedMap` | `ImmutableSortedDictionary<'Key, 'Value>` | – |
+| `HashSet` | `ImmutableHashSet<'T>` | – |
+| `SortedSet` | `ImmutableSortedSet<'T>` | – |
+| `IIndexedSeq` | `IReadOnlyList<'T>` | – |
 
 [Documentation](https://fsprojects.github.io/FSharp.Collections.Immutable/)
 
@@ -85,6 +87,7 @@ or
 - `GitHubRelease` - Publishes a [GitHub Release](https://help.github.com/en/articles/creating-releases) with the Release Notes and any NuGet packages. Runs only from `Github Actions`.
 - `FormatCode` - Runs [Fantomas](https://github.com/fsprojects/fantomas) on the solution file.
 - `CheckFormatCode` - Runs [Fantomas --check](https://fsprojects.github.io/fantomas/docs/end-users/FormattingCheck.html) on the solution file.
+- `CheckOrder` - Runs `build/check-order.fsx`, which checks that every signature file groups its functions by category in the order of ADR 0001 and sorts them alphabetically inside a category. Runs before `DotnetBuild`.
 - `BuildDocs` - Generates [Documentation](https://fsprojects.github.io/FSharp.Formatting) from `docsSrc` and the [XML Documentation Comments](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/) from your libraries in `src`.
 - `WatchDocs` - Generates documentation and starts a webserver locally.  It will rebuild and hot reload if it detects any changes made to `docsSrc` files, or libraries in `src`.
 

build/build.fs

@@ -163,6 +163,8 @@ module dotnet =
 
     let fantomas args = DotNet.exec id "fantomas" args
 
+    let fsi args = tool id "fsi" args
+
 module FSharpAnalyzers =
     type Arguments =
         | Project of string
@@ -588,6 +590,12 @@ let checkFormatCode ctx =
     else
         Trace.logf "Errors while formatting: %A" result.Errors
 
+/// Checks the category banners and the alphabetical order of the functions in the signature files (ADR 0001, D4)
+let checkOrder _ =
+    let script = rootDirectory </> "build" </> "check-order.fsx"
+    let sourceDirectory = rootDirectory </> "src"
+    dotnet.fsi $"\"%s{script}\" \"%s{sourceDirectory}\""
+
 
 let cleanDocsCache _ = DocsTool.cleanDocsCache ()
 
@@ -651,6 +659,7 @@ let initTargets (ctx : Context.FakeExecutionContext) =
     Target.create "GitHubRelease" githubRelease
     Target.create "FormatCode" formatCode
     Target.create "CheckFormatCode" checkFormatCode
+    Target.create "CheckOrder" checkOrder
     Target.create "Release" ignore // For local
     Target.create "Publish" ignore //For CI
     Target.create "CleanDocsCache" cleanDocsCache
@@ -698,6 +707,7 @@ let initTargets (ctx : Context.FakeExecutionContext) =
 
 
     "DotnetRestore" =?> ("CheckFormatCode", isCI.Value)
+    ==> "CheckOrder"
     ==> "DotnetBuild"
     ==> "DotnetTest"
     ==> "DotnetPack"
@@ -708,6 +718,7 @@ let initTargets (ctx : Context.FakeExecutionContext) =
     "DotnetRestore"
     =?> ("CheckFormatCode", isCI.Value)
     =?> ("GenerateAssemblyInfo", isPublishToGitHub)
+    ==> "CheckOrder"
     ==> "DotnetBuild"
     ==> "DotnetTest"
     ==> "DotnetPack"