Collection Content Guards

[feO2x]

Closes #151

The plan was changed so that allocations are prevented by the new assertions when iterating the collections.l

[Copilot]

Pull request overview

Adds two new collection-content guard clauses to Light.GuardClauses—MustNotContainNull and MustNotContainNullOrWhiteSpace—with single-pass, short-circuiting validation that preserves receiver shapes (including dedicated ImmutableArray<T> overloads) and integrates with the project’s source-export single-file distribution.

Changes:

• Introduces Check.MustNotContainNull and Check.MustNotContainNullOrWhiteSpace assertion families, plus dedicated throw helpers for consistent ExistingItemException messaging.
• Adds comprehensive tests for shape preservation, caller expressions, custom messages/factories, single enumeration + disposal, early termination, and immutable-array handling.
• Updates source-export whitelist/settings, single-file distribution, docs overview, and adds microbenchmarks for the indexable fast path.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tools/source-export/Light.GuardClauses.SourceCodeTransformation/settings.json	Adds both new assertion families to the source-export inclusion catalog.
tools/source-export/Light.GuardClauses.SourceCodeTransformation/AssertionWhitelist.cs	Extends the whitelist model with entries for the new assertion families.
src/Light.GuardClauses/Check.MustNotContainNull.cs	Adds MustNotContainNull guards (default + factory + ImmutableArray<T> overloads) with indexable fast path and single-pass fallback.
src/Light.GuardClauses/Check.MustNotContainNullOrWhiteSpace.cs	Adds MustNotContainNullOrWhiteSpace guards (default + factory + ImmutableArray<string?> overloads) with indexable fast paths and single-pass fallback.
src/Light.GuardClauses/ExceptionFactory/Throw.NullItem.cs	Adds focused throw helper for null-item failures without re-enumerating or rendering collection contents.
src/Light.GuardClauses/ExceptionFactory/Throw.NullOrWhiteSpaceItem.cs	Adds focused throw helper that reports failure category and offending position.
tests/Light.GuardClauses.Tests/CollectionAssertions/TrackingEnumerable.cs	Introduces test helpers for verifying single enumeration, disposal, and indexable fast-path behavior.
tests/Light.GuardClauses.Tests/CollectionAssertions/MustNotContainNullTests.cs	Adds unit tests validating null-item rejection, shape preservation, factories/messages, and enumeration behavior.
tests/Light.GuardClauses.Tests/CollectionAssertions/MustNotContainNullOrWhiteSpaceTests.cs	Adds unit tests for null/empty/whitespace rejection (including Unicode whitespace), plus enumeration behavior and shape preservation.
tests/Light.GuardClauses.SourceCodeTransformation.Tests/SourceFileMergerWhitelistTests.cs	Adds source-export trimming/reachability tests for both new assertion families.
Light.GuardClauses.SingleFile.cs	Regenerates the committed .NET Standard 2.0 single-file distribution to include the new guards and helpers.
docs/assertion-overview.md	Documents the new guard families and their single-pass, constant-space, short-circuiting behavior and boxing implications.
benchmarks/Light.GuardClauses.Performance/CollectionAssertions/CollectionContentGuardBenchmark.cs	Adds microbenchmarks comparing imperative loops vs guard fast paths and allocation behavior.
ai-plans/0151-collection-content-guards.md	Captures the implementation plan and acceptance-criteria checklist for the feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.