feat(justdummies): guard public/internal arguments against null

JustDummies.UnitTests/JustDummies.UnitTests.csproj

@@ -47,6 +47,9 @@
     <Compile Remove="AnyModernTypeTests.cs" />
     <Compile Remove="CrossEngineReachabilityTests.cs" />
     <Compile Remove="ContinuousExclusionNudgeTests.cs" />
+    <!-- Uses System.Reflection nullability metadata (NullabilityInfoContext, .NET 6+) to read parameter annotations,
+         which the net472 floor does not carry; the null-argument guards it enforces are themselves netstandard2.0. -->
+    <Compile Remove="NullArgumentGuardConventionTests.cs" />
   </ItemGroup>
 
 </Project>

JustDummies/Any.cs

@@ -550,6 +550,8 @@ public static void Reproducibly(int seed, Action body, Action<string>? report =
     /// <returns>A task that completes when <paramref name="body" /> completes, and faults with the body's exception.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="body" /> is <c>null</c>.</exception>
     public static Task ReproduciblyAsync(Func<Task> body, Action<string>? report = null) {
+        if (body is null) { throw new ArgumentNullException(nameof(body)); }
+
         return ReproduciblyAsync(AmbientRandomSource.NewSeed(), body, report);
     }
 
@@ -562,9 +564,15 @@ public static Task ReproduciblyAsync(Func<Task> body, Action<string>? report = n
     /// <param name="report">The sink the seed is written to on failure. Defaults to <see cref="Console.Error" /> when <c>null</c>.</param>
     /// <returns>A task that completes when <paramref name="body" /> completes.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="body" /> is <c>null</c>.</exception>
-    public static async Task ReproduciblyAsync(int seed, Func<Task> body, Action<string>? report = null) {
+    public static Task ReproduciblyAsync(int seed, Func<Task> body, Action<string>? report = null) {
         if (body is null) { throw new ArgumentNullException(nameof(body)); }
 
+        return RunReproduciblyAsync(seed, body, report);
+    }
+
+    // Kept separate from the public entry so the null-argument guard above throws synchronously at the call site,
+    // rather than being deferred into the returned task's fault — which a caller who forgets to await would miss.
+    private static async Task RunReproduciblyAsync(int seed, Func<Task> body, Action<string>? report) {
         using (AmbientRandomSource.UseSeed(seed)) {
             try {
                 await body().ConfigureAwait(false);

JustDummies/AnyArray.cs

@@ -29,10 +29,14 @@ public AnyArray<T> Distinct(IEqualityComparer<T> comparer) {
     }
 
     private protected override AnyArray<T> With(CollectionState<T> state) {
+        if (state is null) { throw new ArgumentNullException(nameof(state)); }
+
         return new AnyArray<T>(SourceOrNull, state);
     }
 
     private protected override T[] Build(List<T> items) {
+        if (items is null) { throw new ArgumentNullException(nameof(items)); }
+
         return items.ToArray();
     }
 

JustDummies/AnyBoolean.cs

@@ -10,6 +10,8 @@ public sealed class AnyBoolean : IAny<bool>, IHasRandomSource, ICardinalityHint<
     #region Statics members declarations
 
     internal static AnyBoolean Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyBoolean(source, null, null);
     }
 

JustDummies/AnyByte.cs

@@ -17,6 +17,8 @@ public sealed class AnyByte : IAny<byte>, IHasRandomSource, ICardinalityHint<byt
     #region Statics members declarations
 
     internal static AnyByte Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyByte(source, OrdinalIntervalSpec.Unconstrained("Byte", ordinal => V(Val(ordinal)), Ord(byte.MinValue), Ord(byte.MaxValue)));
     }
 

JustDummies/AnyChar.cs

@@ -13,6 +13,8 @@ public sealed class AnyChar : IAny<char>, IHasRandomSource, ICardinalityHint<cha
     #region Statics members declarations
 
     internal static AnyChar Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyChar(source, null, null, null, null, null, null, []);
     }
 

JustDummies/AnyCollection.cs

@@ -16,7 +16,7 @@
 /// <typeparam name="TItem">The element type.</typeparam>
 /// <typeparam name="TResult">The collection type <see cref="Generate" /> produces.</typeparam>
 /// <typeparam name="TSelf">The concrete generator type, so the fluent methods return it.</typeparam>
 public abstract class AnyCollection<TItem, TResult, TSelf> : IAny<TResult>, IHasRandomSource
     where TSelf : AnyCollection<TItem, TResult, TSelf> {
 
     #region Fields declarations
@@ -27,6 +27,8 @@
     #endregion
 
     private protected AnyCollection(RandomSource? source, CollectionState<TItem> state) {
+        if (state is null) { throw new ArgumentNullException(nameof(state)); }
+
         SourceOrNull = source;
         State        = state;
     }

JustDummies/AnyDateOnly.cs

@@ -21,6 +21,8 @@ public sealed class AnyDateOnly : IAny<DateOnly>, IHasRandomSource, ICardinality
     #region Statics members declarations
 
     internal static AnyDateOnly Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyDateOnly(source, OrdinalIntervalSpec.Unconstrained("DateOnly", ordinal => V(Val(ordinal)), Ord(DateOnly.MinValue), Ord(DateOnly.MaxValue)));
     }
 

JustDummies/AnyDateTime.cs

@@ -24,6 +24,8 @@ public sealed class AnyDateTime : IAny<DateTime>, IHasRandomSource, ICardinality
     #region Statics members declarations
 
     internal static AnyDateTime Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyDateTime(source, OrdinalIntervalSpec.Unconstrained("DateTime", ordinal => V(Val(ordinal)), Ord(DateTime.MinValue), Ord(DateTime.MaxValue)));
     }
 

JustDummies/AnyDateTimeOffset.cs

@@ -30,6 +30,8 @@
     #region Statics members declarations
 
     internal static AnyDateTimeOffset Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyDateTimeOffset(source, OrdinalIntervalSpec.Unconstrained("DateTimeOffset", ordinal => V(Val(ordinal)), Ord(DateTimeOffset.MinValue), Ord(DateTimeOffset.MaxValue)), null, false, 0, 0);
     }
 
@@ -267,7 +269,7 @@
             throw new ConflictingAnyConstraintException($"Cannot apply {applying} because an offset constraint is already defined.");
         }
 
         // Tighten the instant so local ticks = UtcTicks + offset stay in [0, MaxTicks] for every offset in the range;
         // the offset can then be drawn independently, never producing an out-of-range DateTimeOffset.
         long  minOffsetTicks = minMinutes * TimeSpan.TicksPerMinute;
         long  maxOffsetTicks = maxMinutes * TimeSpan.TicksPerMinute;

JustDummies/AnyDecimal.cs

@@ -18,6 +18,8 @@ public sealed class AnyDecimal : IAny<decimal>, IHasRandomSource, ICardinalityHi
     #region Statics members declarations
 
     internal static AnyDecimal Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyDecimal(source, DecimalIntervalSpec.Unconstrained("Decimal", V));
     }
 

JustDummies/AnyDerivation.cs

@@ -25,6 +25,8 @@ internal sealed class DerivedAny<T> : IAny<T>, IHasRandomSource, IReproducibilit
     #endregion
 
     internal DerivedAny(RandomSource? source, bool drawsOnlyFromSource, Func<T> generate) {
+        if (generate is null) { throw new ArgumentNullException(nameof(generate)); }
+
         _source              = source;
         _drawsOnlyFromSource = drawsOnlyFromSource;
         _generate            = generate;
@@ -46,6 +48,8 @@ internal static class AnyDerivation {
 
     /// <summary>The random context of <paramref name="generator" />, when it is one of the library's own.</summary>
     internal static RandomSource? SourceOf<T>(IAny<T> generator) {
+        if (generator is null) { throw new ArgumentNullException(nameof(generator)); }
+
         return (generator as IHasRandomSource)?.Source;
     }
 
@@ -58,6 +62,8 @@ internal static class AnyDerivation {
     ///     replayed from that seed.
     /// </summary>
     internal static bool IsReproducible<T>(IAny<T> generator) {
+        if (generator is null) { throw new ArgumentNullException(nameof(generator)); }
+
         if (generator is IReproducibilityHint hint) { return hint.DrawsOnlyFromSource; }
 
         return SourceOf(generator) is not null;
@@ -68,6 +74,8 @@ internal static bool IsReproducible<T>(IAny<T> generator) {
     ///     advertises one through <see cref="ICardinalityHint{T}" />; <c>null</c> when the domain is unbounded or unknown.
     /// </summary>
     internal static long? CardinalityOf<T>(IAny<T> generator) {
+        if (generator is null) { throw new ArgumentNullException(nameof(generator)); }
+
         return (generator as ICardinalityHint<T>)?.DistinctCardinality;
     }
 
@@ -79,6 +87,9 @@ internal static bool IsReproducible<T>(IAny<T> generator) {
     ///     promising a full replay the seed cannot deliver. The library's own exceptions pass through untouched.
     /// </summary>
     internal static T Invoke<T>(Func<T> invoke, RandomSource? source, bool reproducible, string failure) {
+        if (invoke is null) { throw new ArgumentNullException(nameof(invoke)); }
+        if (failure is null) { throw new ArgumentNullException(nameof(failure)); }
+
         try {
             return invoke();
         } catch (AnyException) {

JustDummies/AnyDictionary.cs

@@ -28,7 +28,10 @@ public sealed class AnyDictionary<TKey, TValue> : IAny<Dictionary<TKey, TValue>>
     #endregion
 
     internal AnyDictionary(RandomSource? source, CollectionState<TKey> keys, IAny<TValue> values)
-        : this(source, keys, values, NoPinnedValues) { }
+        : this(source, keys, values, NoPinnedValues) {
+        if (keys is null) { throw new ArgumentNullException(nameof(keys)); }
+        if (values is null) { throw new ArgumentNullException(nameof(values)); }
+    }
 
     private AnyDictionary(RandomSource? source, CollectionState<TKey> keys, IAny<TValue> values, IReadOnlyDictionary<TKey, TValue> pinnedValues) {
         _source       = source;

JustDummies/AnyDouble.cs

@@ -17,6 +17,8 @@ public sealed class AnyDouble : IAny<double>, IHasRandomSource, ICardinalityHint
     #region Statics members declarations
 
     internal static AnyDouble Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyDouble(source, ContinuousIntervalSpec.Unconstrained("Double", V, value => value, ContinuousIntervalSpec.NextUp, -double.MaxValue, double.MaxValue));
     }
 

JustDummies/AnyEnum.cs

@@ -43,6 +43,7 @@ public sealed class AnyEnum<TEnum> : IAny<TEnum>, IHasRandomSource, ICardinality
     private static TEnum[]? _combinations;
 
     internal static AnyEnum<TEnum> Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
         if (Declared.Length == 0) {
             throw new AnyGenerationException($"Cannot generate an arbitrary {typeof(TEnum).Name} value because the enum declares no members.");
         }

JustDummies/AnyFtpUri.cs

@@ -14,6 +14,8 @@ public sealed class AnyFtpUri : IAny<Uri>, IHasRandomSource {
     #endregion
 
     internal AnyFtpUri(RandomSource source, UriSpec spec) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+        if (spec is null) { throw new ArgumentNullException(nameof(spec)); }
         _source = source;
         _spec   = spec;
     }

JustDummies/AnyGuid.cs

@@ -13,6 +13,8 @@ public sealed class AnyGuid : IAny<Guid>, IHasRandomSource, ICardinalityHint<Gui
     #region Statics members declarations
 
     internal static AnyGuid Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyGuid(source, null, null, null, null, []);
     }
 

JustDummies/AnyHalf.cs

@@ -19,6 +19,8 @@ public sealed class AnyHalf : IAny<Half>, IHasRandomSource, ICardinalityHint<Hal
     #region Statics members declarations
 
     internal static AnyHalf Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyHalf(source, ContinuousIntervalSpec.Unconstrained("Half", value => V((Half)value), value => (double)(Half)value, value => NextUp((Half)value), -(double)Half.MaxValue, (double)Half.MaxValue));
     }
 

JustDummies/AnyInt128.cs

@@ -19,6 +19,8 @@ public sealed class AnyInt128 : IAny<Int128>, IHasRandomSource, ICardinalityHint
     #region Statics members declarations
 
     internal static AnyInt128 Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyInt128(source, WideIntervalSpec.Unconstrained("Int128", ordinal => V(Val(ordinal)), Ord(Int128.MinValue), Ord(Int128.MaxValue)));
     }
 

JustDummies/AnyInt16.cs

@@ -17,6 +17,8 @@ public sealed class AnyInt16 : IAny<short>, IHasRandomSource, ICardinalityHint<s
     #region Statics members declarations
 
     internal static AnyInt16 Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyInt16(source, OrdinalIntervalSpec.Unconstrained("Int16", ordinal => V(Val(ordinal)), Ord(short.MinValue), Ord(short.MaxValue)));
     }
 

JustDummies/AnyInt32.cs

@@ -33,6 +33,8 @@ public sealed class AnyInt32 : IAny<int>, IHasRandomSource, ICardinalityHint<int
     #region Statics members declarations
 
     internal static AnyInt32 Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyInt32(source, OrdinalIntervalSpec.Unconstrained("Int32", ordinal => V(Val(ordinal)), Ord(int.MinValue), Ord(int.MaxValue)));
     }
 

JustDummies/AnyInt64.cs

@@ -17,6 +17,8 @@ public sealed class AnyInt64 : IAny<long>, IHasRandomSource, ICardinalityHint<lo
     #region Statics members declarations
 
     internal static AnyInt64 Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnyInt64(source, OrdinalIntervalSpec.Unconstrained("Int64", ordinal => V(Val(ordinal)), Ord(long.MinValue), Ord(long.MaxValue)));
     }
 

JustDummies/AnyList.cs

@@ -29,10 +29,14 @@ public AnyList<T> Distinct(IEqualityComparer<T> comparer) {
     }
 
     private protected override AnyList<T> With(CollectionState<T> state) {
+        if (state is null) { throw new ArgumentNullException(nameof(state)); }
+
         return new AnyList<T>(SourceOrNull, state);
     }
 
     private protected override List<T> Build(List<T> items) {
+        if (items is null) { throw new ArgumentNullException(nameof(items)); }
+
         return items;
     }
 

JustDummies/AnyMailtoUri.cs

@@ -16,6 +16,8 @@ public sealed class AnyMailtoUri : IAny<Uri>, IHasRandomSource {
     #endregion
 
     internal AnyMailtoUri(RandomSource source, UriSpec spec) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+        if (spec is null) { throw new ArgumentNullException(nameof(spec)); }
         _source = source;
         _spec   = spec;
     }

JustDummies/AnyOneOf.cs

@@ -34,9 +34,12 @@ public sealed class AnyOneOf<T> : IAny<T>, IHasRandomSource, ICardinalityHint<T>
 
     #region Statics members declarations
 
-    // Validates and deduplicates the caller's pool, then builds the generator. The array-null check belongs to the
-    // public factories (they own the parameter name); by the time we get here the pool is non-null and materialized.
+    // Validates and deduplicates the caller's pool, then builds the generator. As an internal boundary it guards its
+    // own arguments per the null-argument convention (ADR-0045); the public factories additionally reject a null
+    // array first, under the caller-facing parameter name, before delegating here.
     internal static AnyOneOf<T> FromPool(RandomSource source, IReadOnlyList<T> values) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+        if (values is null) { throw new ArgumentNullException(nameof(values)); }
         if (values.Count == 0) { throw new ArgumentException("At least one value is required.", nameof(values)); }
         if (values.Any(value => value is null)) { throw new ArgumentException("The values must not contain a null element; use OrNull() to make the whole generator nullable.", nameof(values)); }
 

JustDummies/AnyPattern.cs

@@ -36,6 +36,8 @@ public sealed class AnyPattern : IAny<string>, IHasRandomSource {
     private const int GenerationLimit = 65536;
 
     internal static AnyPattern FromPattern(RandomSource source, string pattern, bool ignoreCase) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+        if (pattern is null) { throw new ArgumentNullException(nameof(pattern)); }
         return new AnyPattern(source, RegexParser.Parse(pattern, ignoreCase));
     }
 
@@ -49,6 +51,8 @@ internal static AnyPattern FromPattern(RandomSource source, string pattern, bool
     #endregion
 
     internal AnyPattern(RandomSource source, RegexNode root) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+        if (root is null) { throw new ArgumentNullException(nameof(root)); }
         _source = source;
         _root   = root;
     }

JustDummies/AnyRelativeUri.cs

@@ -16,6 +16,8 @@ public sealed class AnyRelativeUri : IAny<Uri>, IHasRandomSource {
     #endregion
 
     internal AnyRelativeUri(RandomSource source, UriSpec spec) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+        if (spec is null) { throw new ArgumentNullException(nameof(spec)); }
         _source = source;
         _spec   = spec;
     }

JustDummies/AnySByte.cs

@@ -17,6 +17,8 @@ public sealed class AnySByte : IAny<sbyte>, IHasRandomSource, ICardinalityHint<s
     #region Statics members declarations
 
     internal static AnySByte Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnySByte(source, OrdinalIntervalSpec.Unconstrained("SByte", ordinal => V(Val(ordinal)), Ord(sbyte.MinValue), Ord(sbyte.MaxValue)));
     }
 

JustDummies/AnySequence.cs

@@ -35,10 +35,14 @@ public AnySequence<T> Distinct(IEqualityComparer<T> comparer) {
     }
 
     private protected override AnySequence<T> With(CollectionState<T> state) {
+        if (state is null) { throw new ArgumentNullException(nameof(state)); }
+
         return new AnySequence<T>(SourceOrNull, state);
     }
 
     private protected override IEnumerable<T> Build(List<T> items) {
+        if (items is null) { throw new ArgumentNullException(nameof(items)); }
+
         return items;
     }
 

JustDummies/AnySet.cs

@@ -14,10 +14,14 @@ public sealed class AnySet<T> : AnyCollection<T, HashSet<T>, AnySet<T>> {
     internal AnySet(RandomSource? source, CollectionState<T> state) : base(source, state) { }
 
     private protected override AnySet<T> With(CollectionState<T> state) {
+        if (state is null) { throw new ArgumentNullException(nameof(state)); }
+
         return new AnySet<T>(SourceOrNull, state);
     }
 
     private protected override HashSet<T> Build(List<T> items) {
+        if (items is null) { throw new ArgumentNullException(nameof(items)); }
+
         // The state already deduplicated under the comparer; the set carries the same comparer so later lookups
         // by the caller behave identically.
         return new HashSet<T>(items, State.Comparer);

JustDummies/AnySingle.cs

@@ -17,6 +17,8 @@ public sealed class AnySingle : IAny<float>, IHasRandomSource, ICardinalityHint<
     #region Statics members declarations
 
     internal static AnySingle Create(RandomSource source) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+
         return new AnySingle(source, ContinuousIntervalSpec.Unconstrained("Single", value => V((float)value), value => (float)value, value => NextUp((float)value), -float.MaxValue, float.MaxValue));
     }
 

JustDummies/AnyString.cs

@@ -46,7 +46,7 @@
         return string.Join(", ", values.Select(value => $"\"{value}\""));
     }
 
     private static string RequireText(string value, string parameterName) {
         if (value is null) { throw new ArgumentNullException(parameterName); }
         if (value.Length == 0) { throw new ArgumentException("The value must not be empty.", parameterName); }
 
@@ -69,6 +69,8 @@
     #endregion
 
     internal AnyString(RandomSource source, StringSpec spec) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+        if (spec is null) { throw new ArgumentNullException(nameof(spec)); }
         _source = source;
         _spec   = spec;
     }

JustDummies/AnyStringOneOf.cs

@@ -33,6 +33,8 @@ public sealed class AnyStringOneOf : IAny<string>, IHasRandomSource, ICardinalit
     #endregion
 
     internal AnyStringOneOf(RandomSource source, IReadOnlyList<string> values) {
+        if (source is null) { throw new ArgumentNullException(nameof(source)); }
+        if (values is null) { throw new ArgumentNullException(nameof(values)); }
         _source = source;
         _values = values;
     }