docs: add architecture and testing documentation

CaffeinatedCoder · CaffeinatedCoder · commit 882ce66a60b4 · 2026-06-19T14:08:44.000+02:00
Added detailed `architecture.md` to explain core concepts, design patterns, and internal structure of range types and `RangeSet`. Introduced `testing.md` to outline test organization, patterns, and guidelines, ensuring consistent and efficient testing practices.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,37 @@
+# CodoMetis.ValueRanges
+
+In-memory range and multirange types for .NET 10, mirroring PostgreSQL's six built-in range domains (`int4range`, `int8range`, `numrange`, `daterange`, `tsrange`, `tstzrange`). Each type is a discriminated union of five sealed variants with exhaustive pattern matching.
+
+## Stack
+.NET 10 · C# 14 (extension methods) · MSTest 4.x · EF Core + Npgsql (PostgreSQL bridge)
+
+## Structure
+- `CodoMetis.ValueRanges/` — Core library: range types, interfaces, set ops
+- `CodoMetis.ValueRanges.EFCore.PostgreSQL/` — EF Core provider for LINQ-to-SQL translation
+- `CodoMetis.ValueRanges.Tests/` — Unit tests (one file per operation)
+- `CodoMetis.ValueRanges.EFCore.PostgreSQL.Tests/` — EF Core integration tests
+- `docs/` — Agent docs (read relevant doc before starting work)
+
+## Commands
+```bash
+dotnet build                          # Build everything
+dotnet test                           # Run all tests
+dotnet test --filter "ClassName=RangeContainsTests"   # Single test class
+dotnet test --filter "FullyQualifiedName~Contains_FiniteRange"  # Single method
+dotnet pack                           # Pack NuGet packages
+```
+
+## Workflow
+1. Read `docs/architecture.md` before modifying range types or interfaces
+2. Explore the codebase — range operations are per-shape (Finite, UnboundedStart, etc.)
+3. Run `dotnet test` after each change; tests are method-level parallel
+4. Commit with conventional format: `feat:`, `fix:`, `refactor:`, `docs:`
+
+## Docs
+- `docs/architecture.md` — Discriminated union pattern, interface hierarchy, RangeSet internals
+- `docs/testing.md` — Test organization, patterns, shape-combination matrix
+
+## Critical Rules
+- **NEVER** create external subtypes of range base records — the private constructor enforces exhaustive pattern matching; breaking this removes compiler guarantees
+- **ALWAYS** preserve RangeSet's invariant (sorted, disjoint, non-adjacent, no empties) on every code path that constructs or mutates a set
+- **Do NOT** add new range types without adding corresponding `IntersectEngine`/`MergeEngine` per-shape implementations in `Internals/`
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -0,0 +1,86 @@
+# Architecture
+
+## Overview
+
+CodoMetis.ValueRanges is a .NET 10 class library providing type-safe range types that mirror PostgreSQL's six built-in range domains. Each range is a discriminated union of five sealed variants, making invalid states unrepresentable and pattern matching exhaustive by contract. A companion EF Core package (`CodoMetis.ValueRanges.EFCore.PostgreSQL`) bridges these types to `NpgsqlRange<T>` for LINQ-to-SQL translation.
+
+## Range Types
+
+| C# Type | PostgreSQL | Element Type | Discrete |
+|---|---|---|---|
+| `Int32Range` | `int4range` | `int` | ✓ |
+| `Int64Range` | `int8range` | `long` | ✓ |
+| `DateRange` | `daterange` | `DateOnly` | ✓ |
+| `DecimalRange` | `numrange` | `decimal` | — |
+| `DateTimeRange` | `tsrange` | `DateTime` | — |
+| `DateTimeOffsetRange` | `tstzrange` | `DateTimeOffset` | — |
+
+Discrete types (int, long, DateOnly) implement `NextValueAfter`/`PreviousValueBefore` to return the adjacent value. Continuous types leave them returning `null`. Discrete ranges canonicalize to closed `[lower, upper]` at construction (`Internals/DiscreteCanonical.cs`); continuous ranges default to half-open `[lower, upper)`.
+
+## Discriminated Union Pattern
+
+Every range type is an abstract record with five sealed nested variants:
+
+```
+RangeType (abstract, private ctor)
+├── EmptyRange     : IEmptyRange<T>       — contains no values
+├── Finite         : IFiniteRange<T>      — [start, end] (bounded both sides)
+├── UnboundedStart : IUnboundedStartRange<T> — (-∞, end]
+├── UnboundedEnd   : IUnboundedEndRange<T>   — [start, +∞)
+└── Infinity       : IInfinityRange<T>    — (-∞, +∞)
+```
+
+The private base constructor prevents external subtyping, so the compiler guarantees exhaustive switch expressions. Invalid ranges (inverted bounds, degenerate half-open) normalize to `EmptyRange` at construction time.
+
+## Interface Hierarchy (`Core/`)
+
+- **`IRange<T>`** — Marker interface. Carries `internal default methods` `IntersectWith<TRange>()` and `MergeWith<TRange>()` that dispatch per-shape to the engines in `Internals/`.
+- **`IRangeFactory<TRange, T>`** — Abstract static factory: `Empty`, `Infinite`, `CreateFinite()`, `CreateUnboundedStart()`, `CreateUnboundedEnd()`, plus virtual `NextValueAfter`/`PreviousValueBefore`. Also implements `IParsable<TRange>` and `IFormattable` with PostgreSQL range literal syntax.
+- **Structural interfaces** — `IFiniteRange<T>`, `IUnboundedStartRange<T>`, `IUnboundedEndRange<T>`, `IEmptyRange<T>`, `IInfinityRange<T>` — each provides its own concrete `IntersectWith`/`MergeWith` implementations (e.g., `IInfinityRange<T>` always returns the other operand for intersection, always returns `Infinite` for merge).
+
+All type parameters are constrained to `struct, IComparable<T>, IEquatable<T>`.
+
+## Extension Methods (`RangeExtensions.cs`)
+
+Uses the C# 14 `extension` keyword. Two `extension<T>` blocks:
+
+1. **Query operations** on `IRange<T>` — state checks (`IsEmpty`, `IsInfinity`, etc.), containment, overlap, adjacency, directional comparisons
+2. **Set operations** on `IRangeFactory<TRange, T>` — `Intersect` (returns `TRange`), `Union`/`Except` (return `RangeSet<TRange, T>`)
+
+See `CodoMetis.ValueRanges/RangeExtensions.cs` for the full implementation.
+
+## RangeSet<TRange, T> (`RangeSet.cs`)
+
+Immutable multirange counterpart of PostgreSQL's `int4multirange`, etc. A sealed class over `ImmutableArray<TRange>` with a strict invariant:
+
+- Sorted by lower bound
+- Pairwise disjoint, pairwise non-adjacent
+- No empty elements
+- Any `Infinity` input collapses the set to `Infinite` singleton
+
+Key methods:
+- `From(IEnumerable<TRange>)` — normalizes (filter → sort via `Internals/RangeSetHelpers.CompareByLowerBound` → greedy merge)
+- Bulk ops (`Union`, `Intersect`, `Except`) use O(n+m) merge-join instead of nested loops
+- Operators: `\|` for union, `&` for intersect, `-` for except
+- `LowerBoundComparer` — static `IComparer<TRange>` for external sorting
+
+See `CodoMetis.ValueRanges/RangeSet.cs` and `CodoMetis.ValueRanges/RangeLowerBoundComparer.cs`.
+
+## JSON Serialization (`Serialization/`)
+
+- `RangeJsonConverter<TRange, T>` — serializes to/from PostgreSQL range literal strings
+- `RangeJsonConverterFactory` — auto-registers for any type implementing `IRangeFactory<TRange, T>` or `RangeSet<TRange, T>`
+- Extension: `AddRangeConverters()` registers all at once
+
+## EF Core PostgreSQL (`CodoMetis.ValueRanges.EFCore.PostgreSQL/`)
+
+- **`ValueRangesMethodCallTranslator`** — translates LINQ methods to PostgreSQL operators (`@>`, `&&`, `<@`, `<<`, `>>`, `&<`, `&>`, `-|-`, `*`, `+`, `-`)
+- **Type mapping** — maps range types to PostgreSQL range columns, RangeSet to multirange columns
+- **Enable**: `options.UseNpgsql(connectionString, npgsql => npgsql.UseValueRanges());`
+
+## Engine Internals (`Internals/`)
+
+- `IntersectEngine.cs`, `MergeEngine.cs` — per-shape intersection and merge logic
+- `ExceptEngine.cs` — set difference with boundary inversion at cut points
+- `DiscreteCanonical.cs` — canonicalizes discrete ranges to closed form
+- `RangeBoundHelpers.cs`, `RangeFormat.cs`, `RangeSetHelpers.cs` — shared utilities
diff --git a/docs/testing.md b/docs/testing.md
@@ -0,0 +1,85 @@
+# Testing
+
+## Running Tests
+
+```bash
+dotnet test                          # All tests (method-level parallel)
+dotnet test --filter "ClassName=RangeContainsTests"   # Single class
+dotnet test --filter "FullyQualifiedName~Contains_FiniteRange"  # Single method
+```
+
+Tests run in parallel at the **method level** (`MSTestSettings.cs`). No shared state between tests.
+
+## Organization
+
+One test file per operation, named `Range[Operation]Tests.cs`:
+
+| File | Covers |
+|---|---|
+| `RangeContainsTests.cs` | Point and range containment |
+| `RangeOverlapsTests.cs` | Overlap detection |
+| `RangeIsAdjacentTests.cs` | Adjacency (discrete step-aware, continuous complementary inclusiveness) |
+| `RangeIntersectTests.cs` | Intersection across all shape combinations |
+| `RangeUnionTests.cs` | Union (merge overlapping, keep disjoint) |
+| `RangeExceptTests.cs` | Set difference (0/1/2 element results) |
+| `RangeContainedByTests.cs` | Symmetric containment alias |
+| `RangeDoesNotExtendLeftOfTests.cs` / `RightOfTests.cs` | PostgreSQL `&<`/`&>` |
+| `RangeStrictlyLeftOrRightOfTests.cs` | PostgreSQL `<<`/`>>` |
+| `RangeParseFormatTests.cs` | PostgreSQL range literal round-trips |
+| `RangeSetTests.cs` | RangeSet construction, normalization, bulk ops |
+| `RangeSetOptimizationTests.cs` | Performance-critical invariants |
+| `RangeJsonConverterTests.cs` | JSON serialization round-trips |
+
+EF Core tests live in `CodoMetis.ValueRanges.EFCore.PostgreSQL.Tests/`.
+
+## Patterns
+
+### Shape-Combination Matrix
+
+Every binary operation test must cover all five range shapes: `Finite`, `UnboundedStart`, `UnboundedEnd`, `EmptyRange`, `Infinity`. Tests instantiate the "other" operand in each shape and verify the result type and value.
+
+Example from `RangeContainsTests.cs`:
+```csharp
+// Tests Finite vs each shape of "other" — interior, left-of, right-of, overlapping
+```
+
+### Boundary Inclusiveness Permutations
+
+For `Finite` ranges, tests cover all four inclusiveness combinations:
+- `[start, end]` — both inclusive (default for discrete)
+- `(start, end)` — both exclusive
+- `[start, end)` — lower inclusive (default for continuous)
+- `(start, end]` — upper inclusive
+
+### Discrete vs Continuous Split
+
+Tests are parameterized by range type:
+- **Discrete** (`Int32Range`, `Int64Range`, `DateRange`) — canonicalization, adjacency with step awareness
+- **Continuous** (`DecimalRange`, `DateTimeRange`, `DateTimeOffsetRange`) — half-open defaults, equality via `IEquatable`
+
+### Assertion Style
+
+Use MSTest assertions (`Assert.IsTrue`, `Assert.IsFalse`, `Assert.AreEqual`, `Assert.AreSame`). For structural shape checks, cast to the specific interface (e.g., `IFiniteRange<int>`) and verify properties.
+
+### RangeSet Type Aliases
+
+Use local type aliases for readability in tests:
+```csharp
+using IntSet = CodoMetis.ValueRanges.RangeSet<CodoMetis.ValueRanges.Int32Range, int>;
+using DecimalSet = CodoMetis.ValueRanges.RangeSet<CodoMetis.ValueRanges.DecimalRange, decimal>;
+```
+
+## What to Test
+
+- **Every public method** on range types and `RangeSet`
+- **All shape combinations** for binary operations (5×5 = 25 cases per operation)
+- **Boundary inclusiveness** permutations for `Finite` ranges
+- **Normalization invariants**: empty filtering, overlap merging, adjacency merging, Infinity collapse
+- **Round-trips**: parse → format should produce equivalent ranges (exact string match for same-shape inputs)
+- **Edge cases**: empty input to `RangeSet.From()`, single-element fast path, `Infinite.Except()` complement
+
+## What Not to Test
+
+- Framework internals (MSTest, System.Text.Json)
+- Simple property getters on range variants
+- Code paths that are provably unreachable (private constructors, sealed subtypes)
