Stream Guards

[feO2x]

Closes #156

[github-actions]

Package	Line Rate	Branch Rate	Complexity	Health
Light.GuardClauses	95%	88%	2372	✔
Light.GuardClauses.InternalRoslynAnalyzers	96%	86%	52	✔
Light.GuardClauses.InternalRoslynAnalyzers.CodeFixes	95%	100%	8	✔
Light.GuardClauses.SourceCodeTransformation	92%	83%	663	✔
Summary	94% (4476 / 4746)	87% (2430 / 2793)	3095	✔

[Copilot]

Pull request overview

Adds first-class stream capability guard clauses to Light.GuardClauses so API boundaries can enforce Stream readability/writability/seekability early, while preserving fluent chaining, concrete stream types, and the single-file distribution pipeline.

Changes:

• Introduces MustBeReadable, MustBeWritable, and MustBeSeekable guards (default + exception-factory overloads) plus matching Throw.* helpers.
• Adds comprehensive tests for capability semantics, expression capture, exception behavior, allocation-free success paths, and source-export whitelist reachability/trimming.
• Updates source-export configuration, regenerated single-file artifact, and documentation to include the new stream assertions.

Reviewed changes

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

Show a summary per file

File	Description
tools/source-export/Light.GuardClauses.SourceCodeTransformation/SourceFileMerger.cs	Ensures the merged single-file template includes System.IO for Stream-based guards.
tools/source-export/Light.GuardClauses.SourceCodeTransformation/settings.json	Whitelists the three new stream assertions (including exception-factory overloads) for source export.
tools/source-export/Light.GuardClauses.SourceCodeTransformation/AssertionWhitelist.cs	Adds MustBeReadable/Writable/Seekable entries to the whitelist model.
tests/Light.GuardClauses.Tests/StreamAssertions/StreamGuardTests.cs	Adds coverage for capability-only checks, exception contracts, type preservation, and allocation-free success paths.
tests/Light.GuardClauses.SourceCodeTransformation.Tests/SourceFileMergerWhitelistTests.cs	Adds focused source-export tests validating inclusion/trimming of stream guards and related throw/helpers/factory paths.
src/Light.GuardClauses/ExceptionFactory/Throw.Stream.cs	Adds dedicated Throw.MustBeReadable/Writable/Seekable helpers producing capability-specific ArgumentExceptions without formatting streams.
src/Light.GuardClauses/Check.MustBeReadable.cs	Implements MustBeReadable<TStream> guard (default + factory overload) with property-only validation.
src/Light.GuardClauses/Check.MustBeWritable.cs	Implements MustBeWritable<TStream> guard (default + factory overload) with property-only validation.
src/Light.GuardClauses/Check.MustBeSeekable.cs	Implements MustBeSeekable<TStream> guard (default + factory overload) with property-only validation.
Light.GuardClauses.SingleFile.cs	Regenerates the .NET Standard 2.0 single-file distribution to include stream guards and throw helpers.
docs/assertion-overview.md	Documents the new stream assertions and their property-only, non-mutating semantics and exception behavior.
ai-plans/0156-stream-guards.md	Adds the completed plan capturing rationale and acceptance-criteria completion for issue #156.

---

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