[xperiandri]

Proposed Changes

First link of the chain that implements ADR 0001 – Per-collection modules (#23): the foundation that the collection pull requests build on. It changes no public function yet.

• Helper.fs replaces ImmutableCollectionUtil.fs (same internal module, so the legacy files compile unchanged) and adds checkNotDefault, which treats a default ImmutableArray as FSharp.Core treats a null array.
• build/check-order.fsx checks every signature file: the functions are grouped under // ---- Category ---- banners in the canonical order of ADR 0001 D4, sorted ordinally inside a category (active patterns last), and the implementation file repeats the banners and the order. It reads val internal and val private declarations correctly. The FAKE target CheckOrder runs it before DotnetBuild; the README lists the target.
• The library and the tests target net8.0 and net10.0 (D10); CI and the dev container already install both runtimes.
• FSharp.Core 10.1.301 is the minimum: it is the first release with List.partitionWith, Array.partitionWith and Set.partitionWith, which the modules mirror.
• The seven placeholder test files are replaced by:
  • TestCategories.fs with one category attribute per collection and per specialized area, sorted by type name;
  • TestCategoriesTests.fs, which enforces the category rules of ADR 0001 D8 and keeps the test run non-empty: one category per attribute, named after the type, the attributes sorted, a category attribute of this project on every test class, no category on a test method and no category written as a string;
  • shared helpers of the contract tests, as root modules: Contracts/Inputs.fs, Contracts/ExceptionAssert.fs (compares an exception with the one of the mirrored FSharp.Core function: type, first line of the message and parameter name, under the invariant culture, because FSharp.Core ships localized messages), Contracts/OverrideAssert.fs, and Contracts/Mirror.fs with the FSharp.Core module that a collection mirrors.
• .github/copilot-instructions.md describes the new layout: the types files, the comparer structs, the extension modules, root modules and categories on the test classes.
• The README and the documentation pages list the collections in a table that each following pull request updates.

Types of changes

What types of changes does your code introduce to FSharp.Collections.Immutable?
Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

The package requires FSharp.Core 10.1.301 or later.

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• Build and tests pass locally
• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have added necessary documentation (if appropriate)

Further comments

One deviation from ADR 0001 D9: the contract bases arrive with the first collection that implements them (FlatList brings the sequence-like facets, HashMap the map facets, HashSet the set facets) instead of this pull request, so each base is reviewed together with an implementation that runs it.

The collection pull requests are stacked on this one. Each one merges into the branch it is based on until this one is in main.

The test helpers move to arrays and data rows (the new Testing rules on main) in a follow-up push.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new ordering and operation-category checks can silently accept violations they are intended to reject.

3 open issues

• Support or reject file-scoped module headers explicitly · New
• Compare member categories as well as names · New
• Require the specific TestCategoryAttribute annotation · New

What changed in this PR

Establishes the foundation for ADR 0001’s per-collection rewrite without changing public functions.

Changes:

• Adds shared argument checks, contract-test helpers, and convention enforcement.
• Targets .NET 8 and .NET 10 and raises the minimum FSharp.Core version.
• Updates collection documentation and build guidance.

File	Description
tests/​FSharp.Collections.Immutable.Tests/​TestCategoriesTests.fs	Adds category convention checks.
tests/​FSharp.Collections.Immutable.Tests/​TestCategories.fs	Defines centralized category attributes.
tests/​FSharp.Collections.Immutable.Tests/​Stack.fs	Removes placeholder tests.
tests/​FSharp.Collections.Immutable.Tests/​Sets.fs	Removes placeholder tests.
tests/​FSharp.Collections.Immutable.Tests/​Queue.fs	Removes placeholder tests.
tests/​FSharp.Collections.Immutable.Tests/​Maps.fs	Removes placeholder tests.
tests/​FSharp.Collections.Immutable.Tests/​IndexedSeq.fs	Removes placeholder tests.
tests/​FSharp.Collections.Immutable.Tests/​ImmutableList.fs	Removes placeholder tests.
tests/​FSharp.Collections.Immutable.Tests/​FSharp.Collections.Immutable.Tests.fsproj	Registers helpers and both target frameworks.
tests/​FSharp.Collections.Immutable.Tests/​FlatList.fs	Removes placeholder tests.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​OverrideAssert.fs	Adds representation comparison helpers.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​Inputs.fs	Adds shared contract inputs.
tests/​FSharp.Collections.Immutable.Tests/​Contracts/​ExceptionAssert.fs	Adds exception comparison helpers.
src/​FSharp.Collections.Immutable/​ImmutableCollectionUtil.fs	Removes the former helper file.
src/​FSharp.Collections.Immutable/​Helper.fs	Preserves helpers and adds default-array validation.
src/​FSharp.Collections.Immutable/​FSharp.Collections.Immutable.fsproj	Registers Helper.fs and both target frameworks.
README.md	Adds collection table and CheckOrder guidance.
docsSrc/​index.md	Adds collection table.
docsSrc/​Explanations/​Background.md	Adds collection table.
Directory.Packages.props	Raises FSharp.Core minimum version.
CHANGELOG.md	Records framework and dependency changes.
build/​check-order.fsx	Adds signature and implementation ordering checks.
build/​build.fs	Runs CheckOrder before builds.
.github/​copilot-instructions.md	Updates architecture and convention guidance.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The mandatory order checker rejects valid implementation helpers whose visibility is restricted by the signature.

1 open issue

• Signature-omitted helpers incorrectly trigger CheckOrder failures · New

3 resolved since last review

• Require the specific TestCategoryAttribute annotation
• Compare member categories as well as names
• Support or reject file-scoped module headers explicitly

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The new mandatory parser-based build gate warrants human validation against representative signatures across both target frameworks.

No open issues 🎉

1 resolved since last review

• Signature-omitted helpers incorrectly trigger CheckOrder failures

_{Review effort: Balanced}