feat(atc): add Enum<T>.ToReadOnlyDictionary mapping enum to underlying int

- New EnumHelper.ConvertEnumToReadOnlyDictionary<T>() returns
  IReadOnlyDictionary<TEnum, int> keyed by typed enum value with each
  member's underlying int as the value, replacing hand-rolled rank /
  threshold dictionaries at call sites
- Reuses ShouldEnumValueBeSkipped so includeDefault, byFlagIncludeBase
  and byFlagIncludeCombined behave identically to ToDictionary
- Uses Convert.ToInt32 with InvariantCulture so non-int-backed enums
  (byte, short, long) work correctly — a small improvement over the
  existing (int)box cast in ToDictionary
- Add Enum<T>.ToReadOnlyDictionary wrapper next to ToDictionary
- Add EnumHelper tests for happy path, includeDefault=false, [Flags]
  base/combined matrix, and a byte-backed fixture; add Enum<T> theory
  test exercising the wrapper through DayOfWeek

Author: davidkallesen

src/Atc/Enum.cs

@@ -220,6 +220,29 @@ public static Dictionary<int, string> ToDictionary(
             byFlagIncludeBase,
             byFlagIncludeCombined);
 
+    /// <summary>
+    /// Builds a read-only map from each defined enum member to its underlying <see cref="int"/>
+    /// value. Useful for severity-rank or threshold lookup tables that previously required a
+    /// hand-rolled <c>Dictionary&lt;TEnum, int&gt;</c> literal.
+    /// </summary>
+    /// <param name="includeDefault">If set to <see langword="true"/> the <c>0</c>-valued member is included.</param>
+    /// <param name="byFlagIncludeBase">For <see cref="FlagsAttribute"/> enums, include the single-bit base values.</param>
+    /// <param name="byFlagIncludeCombined">For <see cref="FlagsAttribute"/> enums, include the multi-bit combined values.</param>
+    /// <returns>An <see cref="IReadOnlyDictionary{TKey, TValue}"/> keyed by the typed enum value with its underlying <see cref="int"/> as the value.</returns>
+    /// <code><![CDATA[IReadOnlyDictionary<DayOfWeek, int> map = Enum<DayOfWeek>.ToReadOnlyDictionary();]]></code>
+    /// <example><![CDATA[
+    /// IReadOnlyDictionary<DayOfWeek, int> map = Enum<DayOfWeek>.ToReadOnlyDictionary();
+    /// Assert.Equal(0, map[DayOfWeek.Sunday]);
+    /// ]]></example>
+    public static IReadOnlyDictionary<T, int> ToReadOnlyDictionary(
+        bool includeDefault = true,
+        bool byFlagIncludeBase = true,
+        bool byFlagIncludeCombined = true)
+        => EnumHelper.ConvertEnumToReadOnlyDictionary<T>(
+            includeDefault,
+            byFlagIncludeBase,
+            byFlagIncludeCombined);
+
     /// <summary>Converts the enum to dictionary with key as string.</summary>
     /// <param name="dropDownFirstItemType">Type of the dropdown first item.</param>
     /// <param name="useDescriptionAttribute">true to use the display/description/localizeddescription attribute value if exist, default value is name; false to just use the name value.</param>

src/Atc/Helpers/Enums/EnumHelper.cs

@@ -282,6 +282,47 @@ public static Dictionary<int, string> ConvertEnumToDictionary(
         return orderList.ToDictionary(x => x.Key, x => x.Value);
     }
 
+    /// <summary>
+    /// Builds a read-only map from each defined enum member to its underlying <see cref="int"/> value.
+    /// </summary>
+    /// <typeparam name="T">The enum type.</typeparam>
+    /// <param name="includeDefault">If set to <see langword="true"/> the <c>0</c>-valued member is included.</param>
+    /// <param name="byFlagIncludeBase">For <see cref="FlagsAttribute"/> enums, include the single-bit base values.</param>
+    /// <param name="byFlagIncludeCombined">For <see cref="FlagsAttribute"/> enums, include the multi-bit combined values.</param>
+    /// <returns>
+    /// An <see cref="IReadOnlyDictionary{TKey, TValue}"/> keyed by the typed enum value with its
+    /// underlying <see cref="int"/> as the value. Suitable for severity-rank or threshold lookup
+    /// tables that previously required a hand-rolled <c>Dictionary&lt;TEnum, int&gt;</c> literal.
+    /// </returns>
+    public static IReadOnlyDictionary<T, int> ConvertEnumToReadOnlyDictionary<T>(
+        bool includeDefault = true,
+        bool byFlagIncludeBase = true,
+        bool byFlagIncludeCombined = true)
+        where T : Enum
+    {
+        var enumType = typeof(T);
+        var hasFlagAttribute = enumType.IsDefined(typeof(FlagsAttribute), inherit: false);
+
+        var map = new Dictionary<T, int>();
+        foreach (var raw in Enum.GetValues(enumType))
+        {
+            if (ShouldEnumValueBeSkipped(
+                    raw,
+                    includeDefault,
+                    hasFlagAttribute,
+                    byFlagIncludeBase,
+                    byFlagIncludeCombined))
+            {
+                continue;
+            }
+
+            var typed = (T)raw!;
+            map[typed] = Convert.ToInt32(typed, GlobalizationConstants.EnglishCultureInfo);
+        }
+
+        return map;
+    }
+
     /// <summary>
     /// Converts the enum to dictionary with string key.
     /// </summary>

test/Atc.Tests/EnumTests.cs

@@ -242,4 +242,21 @@ public void ToKeyValuePairsWithStringKey<T>(
             .Should().NotBeNull()
             .And.HaveCount(expectedCount);
     }
+
+    [Theory]
+    [InlineData(true, 7)]
+    [InlineData(false, 6)]
+    public void ToReadOnlyDictionary(
+        bool includeDefault,
+        int expectedCount)
+    {
+        // Act
+        var actual = Enum<DayOfWeek>.ToReadOnlyDictionary(includeDefault);
+
+        // Assert
+        actual
+            .Should().NotBeNull()
+            .And.HaveCount(expectedCount);
+        actual[DayOfWeek.Monday].Should().Be(1);
+    }
 }

test/Atc.Tests/Helpers/Enums/EnumHelperTests.cs

@@ -242,4 +242,73 @@ public void GetIndividualValuesFromEnum_DayOfWeek(
         // Assert
         Assert.Equal(expected, actual.Count);
     }
+
+    [Fact]
+    public void ConvertEnumToReadOnlyDictionary_ContainsAllDefinedMembers_WithUnderlyingIntValues()
+    {
+        // Act
+        var actual = EnumHelper.ConvertEnumToReadOnlyDictionary<DayOfWeek>();
+
+        // Assert
+        actual.Should().HaveCount(7);
+        actual[DayOfWeek.Sunday].Should().Be(0);
+        actual[DayOfWeek.Monday].Should().Be(1);
+        actual[DayOfWeek.Tuesday].Should().Be(2);
+        actual[DayOfWeek.Wednesday].Should().Be(3);
+        actual[DayOfWeek.Thursday].Should().Be(4);
+        actual[DayOfWeek.Friday].Should().Be(5);
+        actual[DayOfWeek.Saturday].Should().Be(6);
+    }
+
+    [Fact]
+    public void ConvertEnumToReadOnlyDictionary_ExcludesZeroValue_WhenIncludeDefaultFalse()
+    {
+        // Act
+        var actual = EnumHelper.ConvertEnumToReadOnlyDictionary<DayOfWeek>(includeDefault: false);
+
+        // Assert
+        actual.Should().HaveCount(6);
+        actual.ContainsKey(DayOfWeek.Sunday).Should().BeFalse();
+        actual[DayOfWeek.Monday].Should().Be(1);
+    }
+
+    [Theory]
+    [InlineData(true, true, 20)] // 1 default + 16 single-bit + 3 combined
+    [InlineData(true, false, 17)] // 1 default + 16 single-bit
+    [InlineData(false, true, 4)] // 1 default + 3 combined
+    public void ConvertEnumToReadOnlyDictionary_FlagsEnum_RespectsByFlagIncludeBaseAndCombined(
+        bool byFlagIncludeBase,
+        bool byFlagIncludeCombined,
+        int expectedCount)
+    {
+        // Act
+        var actual = EnumHelper.ConvertEnumToReadOnlyDictionary<CardinalDirectionType>(
+            includeDefault: true,
+            byFlagIncludeBase,
+            byFlagIncludeCombined);
+
+        // Assert
+        actual.Should().HaveCount(expectedCount);
+    }
+
+    [Fact]
+    public void ConvertEnumToReadOnlyDictionary_NonIntUnderlyingType_StillReturnsCorrectIntValues()
+    {
+        // Act
+        var actual = EnumHelper.ConvertEnumToReadOnlyDictionary<ByteBackedTest>();
+
+        // Assert
+        actual.Should().HaveCount(3);
+        actual[ByteBackedTest.Zero].Should().Be(0);
+        actual[ByteBackedTest.One].Should().Be(1);
+        actual[ByteBackedTest.TwoHundred].Should().Be(200);
+    }
+
+    [SuppressMessage("Minor Code Smell", "S4022:Enumerations should have \"Int32\" storage", Justification = "Test fixture verifying non-int underlying-type support.")]
+    private enum ByteBackedTest : byte
+    {
+        Zero = 0,
+        One = 1,
+        TwoHundred = 200,
+    }
 }