refactor: harden type-set dependency targets after second review

- DependsOnlyOn/DependOnlyOn/WhichDependOnlyOn with Filtered.Types targets
  return new only-on results exposing ExcludingOwnSubNamespaces, mirroring
  the namespace family (the own-sub-namespace exemption was hard-coded)
- TypeSetDependencyOptions.Resolve returns a ResolvedTypeSet that performs
  all matching, so matching against an unresolved target set is
  unrepresentable; the assertion CancellationToken is forwarded
- share the constructed-generic matching rule between MatchesType and the
  type-set matcher via TypeHelpers.GetGenericTypeDefinitionOfConstruction
- parenthesize the target description in the type-set filter suffixes, so
  the target scope no longer runs into the subject collection scope
- drop a provably dead Distinct() in GetDependencyTypeSetViolations
- make all WhichDependOn/WhichDoNotDependOn/DependOn/DoNotDependOn
  overloads adjacent (Sonar S4136)
- README: promote type dependencies and architecture rules into their own
  top-level section and avoid em-dashes

Author: vbreuss

README.md

@@ -577,5 +577,56 @@ public TypeSetDependencyFilterResult OrOn(params Filtered.Types[] targets)
 				return new TypeSetDependencyFilterResult(widened, _build);
 			}
 		}
+
+		/// <summary>
+		///     A filtered collection of <see cref="System.Type" /> from a depends-only-on filter whose allowed
+		///     targets are filtered collections of types, allowing to widen the allowed collections and to opt out
+		///     of the implicit allowance of the type's own sub-namespaces.
+		/// </summary>
+		/// <remarks>
+		///     Like all filtered collections, this is an immutable value object: <see cref="OrOn" /> and
+		///     <see cref="ExcludingOwnSubNamespaces" /> do not mutate this instance but rebuild a fresh filter from
+		///     the original base collection, so deriving multiple views from the same instance cannot corrupt each
+		///     other.
+		/// </remarks>
+		public sealed class TypeSetDependencyOnlyOnFilterResult : Types
+		{
+			private readonly Func<TypeSetDependencyOptions, Types> _build;
+			private readonly TypeSetDependencyOptions _options;
+
+			internal TypeSetDependencyOnlyOnFilterResult(
+				TypeSetDependencyOptions options,
+				Func<TypeSetDependencyOptions, Types> build)
+				: base(build(options))
+			{
+				_options = options;
+				_build = build;
+			}
+
+			/// <summary>
+			///     Widens the filter by the given <paramref name="targets" />.
+			/// </summary>
+			public TypeSetDependencyOnlyOnFilterResult OrOn(params Filtered.Types[] targets)
+			{
+				TypeSetDependencyOptions widened = _options.Copy();
+				widened.OrOn(targets);
+				return new TypeSetDependencyOnlyOnFilterResult(widened, _build);
+			}
+
+			/// <summary>
+			///     Excludes sub-namespaces of the type's own namespace from being implicitly allowed (so a <c>Foo</c>
+			///     type referencing <c>Foo.Bar</c> is filtered out unless <c>Foo.Bar</c> types are part of an allowed
+			///     collection).
+			/// </summary>
+			/// <remarks>
+			///     The type's own namespace itself is always allowed.
+			/// </remarks>
+			public TypeSetDependencyOnlyOnFilterResult ExcludingOwnSubNamespaces()
+			{
+				TypeSetDependencyOptions refined = _options.Copy();
+				refined.ExcludingOwnSubNamespaces();
+				return new TypeSetDependencyOnlyOnFilterResult(refined, _build);
+			}
+		}
 	}
 }

Source/aweXpect.Reflection/Collections/Filtered.Types.cs

@@ -18,17 +18,6 @@ public static Filtered.Types.NamespaceDependencyFilterResult WhichDependOn(
 				type => options.IsMatchedBy(type),
 				() => $"which depend on {options.Describe()} ")));
 
-	/// <summary>
-	///     Filter for types which do not depend on (do not reference in their signature) any type in one of the
-	///     <paramref name="namespaces" /> (including sub-namespaces).
-	/// </summary>
-	public static Filtered.Types.NamespaceDependencyFilterResult WhichDoNotDependOn(
-		this Filtered.Types @this, params IEnumerable<string> namespaces)
-		=> new(new NamespaceDependencyOptions(namespaces),
-			options => @this.Which(Filter.Suffix<Type>(
-				type => !options.IsMatchedBy(type),
-				() => $"which do not depend on {options.Describe()} ")));
-
 	/// <summary>
 	///     Filter for types which depend on (reference in their signature) at least one type in the filtered
 	///     collections of types <paramref name="target" /> or <paramref name="additional" />.
@@ -44,10 +33,23 @@ public static Filtered.Types.TypeSetDependencyFilterResult WhichDependOn(
 			options => @this.Which(Filter.Suffix<Type>(
 				async type =>
 				{
-					await options.Resolve();
-					return options.IsMatchedBy(type);
+					ResolvedTypeSet targetSet = await options.Resolve();
+					return targetSet.IsMatchedBy(type);
 				},
-				() => $"which depend on {options.Describe()} ")));
+				// The parentheses delimit the target description (which ends in the target's source scope,
+				// e.g. "in all loaded assemblies") from the subject collection's own source suffix.
+				() => $"which depend on ({options.Describe()}) ")));
+
+	/// <summary>
+	///     Filter for types which do not depend on (do not reference in their signature) any type in one of the
+	///     <paramref name="namespaces" /> (including sub-namespaces).
+	/// </summary>
+	public static Filtered.Types.NamespaceDependencyFilterResult WhichDoNotDependOn(
+		this Filtered.Types @this, params IEnumerable<string> namespaces)
+		=> new(new NamespaceDependencyOptions(namespaces),
+			options => @this.Which(Filter.Suffix<Type>(
+				type => !options.IsMatchedBy(type),
+				() => $"which do not depend on {options.Describe()} ")));
 
 	/// <summary>
 	///     Filter for types which do not depend on (do not reference in their signature) any type in the filtered
@@ -64,8 +66,10 @@ public static Filtered.Types.TypeSetDependencyFilterResult WhichDoNotDependOn(
 			options => @this.Which(Filter.Suffix<Type>(
 				async type =>
 				{
-					await options.Resolve();
-					return !options.IsMatchedBy(type);
+					ResolvedTypeSet targetSet = await options.Resolve();
+					return !targetSet.IsMatchedBy(type);
 				},
-				() => $"which do not depend on {options.Describe()} ")));
+				// The parentheses delimit the target description (which ends in the target's source scope,
+				// e.g. "in all loaded assemblies") from the subject collection's own source suffix.
+				() => $"which do not depend on ({options.Describe()}) ")));
 }

Source/aweXpect.Reflection/Filters/TypeFilters.WhichDependOn.cs

@@ -37,7 +37,9 @@ public static Filtered.Types.NamespaceDependencyOnlyOnFilterResult WhichDependOn
 	/// <remarks>
 	///     The target collections are resolved once per filter; a dependency is allowed when it is a member of the
 	///     union of the resolved collections (by <see cref="Type" /> identity; a generic type definition in a
-	///     collection matches any construction of it).
+	///     collection matches any construction of it). A type's own namespace is always allowed, including its
+	///     sub-namespaces unless
+	///     <see cref="Filtered.Types.TypeSetDependencyOnlyOnFilterResult.ExcludingOwnSubNamespaces" /> is used.
 	///     <para />
 	///     Dependencies on types whose assembly name matches one of the
 	///     <see cref="AwexpectCustomization.ReflectionCustomizationValue.ExcludedAssemblyPrefixes" /> at a
@@ -47,14 +49,16 @@ public static Filtered.Types.NamespaceDependencyOnlyOnFilterResult WhichDependOn
 	///     <c>Microsoft</c>, so e.g. <c>Microsoft.EntityFrameworkCore</c> is also ignored; forbid such a dependency
 	///     explicitly via <c>WhichDoNotDependOn</c> or customize the prefixes.
 	/// </remarks>
-	public static Filtered.Types.TypeSetDependencyFilterResult WhichDependOnlyOn(
+	public static Filtered.Types.TypeSetDependencyOnlyOnFilterResult WhichDependOnlyOn(
 		this Filtered.Types @this, Filtered.Types target, params Filtered.Types[] additional)
 		=> new(new TypeSetDependencyOptions(target, additional),
 			options => @this.Which(Filter.Suffix<Type>(
 				async type =>
 				{
-					await options.Resolve();
-					return !type.HasDependencyTypeSetViolations(options);
+					ResolvedTypeSet allowed = await options.Resolve();
+					return !type.HasDependencyTypeSetViolations(allowed);
 				},
-				() => $"which depend only on {options.Describe()} ")));
+				// The parentheses delimit the target description (which ends in the target's source scope,
+				// e.g. "in all loaded assemblies") from the subject collection's own source suffix.
+				() => $"which depend only on ({options.Describe()}) ")));
 }

Source/aweXpect.Reflection/Filters/TypeFilters.WhichDependOnlyOn.cs

@@ -773,16 +773,24 @@ internal static bool MatchesType(Type dependency, Type target)
 	{
 		target = StripElementTypes(target);
 
-		if (dependency == target)
-		{
-			return true;
-		}
-
-		return target.IsGenericTypeDefinition &&
-		       dependency.IsGenericType &&
-		       dependency.GetGenericTypeDefinition() == target;
+		return dependency == target ||
+		       dependency.GetGenericTypeDefinitionOfConstruction() == target;
 	}
 
+	/// <summary>
+	///     Returns the generic type definition (e.g. <c>List&lt;&gt;</c>) when the <paramref name="dependency" />
+	///     is a constructed generic type (e.g. <c>List&lt;Foo&gt;</c>), otherwise <see langword="null" />.
+	/// </summary>
+	/// <remarks>
+	///     The single encoding of the rule that a dependency on any construction also matches its generic type
+	///     definition; shared between <see cref="MatchesType" /> and <see cref="ResolvedTypeSet.Matches" />, so
+	///     that the specific-type and the type-set matchers cannot drift apart.
+	/// </remarks>
+	internal static Type? GetGenericTypeDefinitionOfConstruction(this Type dependency)
+		=> dependency is { IsGenericType: true, IsGenericTypeDefinition: false, }
+			? dependency.GetGenericTypeDefinition()
+			: null;
+
 	/// <summary>
 	///     Strips array/by-ref/pointer wrappers from the <paramref name="type" />, returning the innermost
 	///     element type.
@@ -959,16 +967,14 @@ private static bool IsOwnNamespace(string? dependencyNamespace, string? ownNames
 	///     set is a concrete set of types, so the violations are reported as formatted type names instead of
 	///     namespaces. Distinct violators sharing a formatted name (the same simple name in different namespaces)
 	///     are qualified by their namespace, so they do not collapse into one indistinguishable entry.
-	///     Requires <see cref="TypeSetDependencyOptions.Resolve" /> to have been awaited before.
 	/// </remarks>
 	internal static IReadOnlyList<string> GetDependencyTypeSetViolations(
-		this Type type, TypeSetDependencyOptions allowed)
+		this Type type, ResolvedTypeSet allowed)
 	{
 		List<string> violations = [];
 		foreach (IGrouping<string, Type> sameName in type.GetDependencyViolations(
 				         (dependency, ownNamespace, excludedPrefixes)
 					         => IsDependencyTypeSetViolation(dependency, ownNamespace, allowed, excludedPrefixes))
-			         .Distinct()
 			         .GroupBy(dependency => Formatter.Format(dependency), StringComparer.Ordinal))
 		{
 			Type[] violators = sameName.ToArray();
@@ -996,14 +1002,14 @@ internal static IReadOnlyList<string> GetDependencyTypeSetViolations(
 	///     Same rules as <see cref="GetDependencyTypeSetViolations" />, for callers (like filters) that only need
 	///     a verdict and not the violation list.
 	/// </remarks>
-	internal static bool HasDependencyTypeSetViolations(this Type type, TypeSetDependencyOptions allowed)
+	internal static bool HasDependencyTypeSetViolations(this Type type, ResolvedTypeSet allowed)
 		=> type.GetDependencyViolations(
 			(dependency, ownNamespace, excludedPrefixes)
 				=> IsDependencyTypeSetViolation(dependency, ownNamespace, allowed, excludedPrefixes)).Any();
 
 	private static bool IsDependencyTypeSetViolation(
-		Type dependency, string? ownNamespace, TypeSetDependencyOptions allowed, string[] excludedPrefixes)
-		=> !IsExemptDependency(dependency, ownNamespace, true, excludedPrefixes) &&
+		Type dependency, string? ownNamespace, ResolvedTypeSet allowed, string[] excludedPrefixes)
+		=> !IsExemptDependency(dependency, ownNamespace, allowed.IncludeOwnSubNamespaces, excludedPrefixes) &&
 		   !allowed.Matches(dependency);
 
 	/// <summary>