feat(DynamicEnumValidation): implement dynamic enum value collision detection

- Added a new method to validate and log collisions between BaseLib and RitsuLib dynamic enum values, enhancing error detection for mod developers.
- Integrated collision detection into the model database initialization process to ensure early detection of potential conflicts.
- Introduced utility methods for retrieving minted dynamic enum values, improving the overall management of dynamic enums within the system.

Author: BAKAOLC

Combat/CardTargeting/Patches/ModelDbInitCustomTargetTypeRegistrationPatch.cs

@@ -1,4 +1,5 @@
 using MegaCrit.Sts2.Core.Models;
+using STS2RitsuLib.Diagnostics;
 using STS2RitsuLib.Patching.Models;
 
 namespace STS2RitsuLib.Combat.CardTargeting.Patches
@@ -31,6 +32,8 @@ public static ModPatchTarget[] GetTargets()
         public static void Postfix()
         {
             CustomTargetTypeRegistry.RegisterBuiltIns();
+            RitsuLibStartupAudit.Measure("modelDb.validateBaseLibDynamicEnums",
+                RegistrationConflictDetector.ValidateAndLogBaseLibDynamicEnumValueCollisions);
         }
     }
 }

Diagnostics/RegistrationConflictDetector.cs

@@ -1,14 +1,19 @@
+using System.Collections;
 using System.Reflection;
+using MegaCrit.Sts2.Core.Entities.Cards;
 using MegaCrit.Sts2.Core.Helpers;
 using MegaCrit.Sts2.Core.Models;
+using MegaCrit.Sts2.Core.Rewards;
 using MegaCrit.Sts2.Core.Timeline;
+using STS2RitsuLib.Utils;
 
 namespace STS2RitsuLib.Diagnostics
 {
     internal static class RegistrationConflictDetector
     {
         private static readonly Lock IndexGate = new();
         private static Dictionary<ModelId, List<Type>>? _gameModelIdIndex;
+        private static bool _baseLibDynamicEnumCollisionCheckCompleted;
 
         private static Dictionary<ModelId, List<Type>> GetGameModelIdIndex()
         {
@@ -79,6 +84,48 @@ internal static void ValidateAndLogModelIdCollisions()
             InvalidateModelIdIndex();
         }
 
+        internal static void ValidateAndLogBaseLibDynamicEnumValueCollisions()
+        {
+            if (_baseLibDynamicEnumCollisionCheckCompleted)
+                return;
+
+            _baseLibDynamicEnumCollisionCheckCompleted = true;
+
+            var baseLibEntries = GetBaseLibCustomEnumEntries();
+            if (baseLibEntries.Length == 0)
+                return;
+
+            var ritsuEntries = GetRitsuDynamicEnumEntries()
+                .GroupBy(static entry => (entry.EnumType, entry.Value))
+                .ToDictionary(
+                    static group => group.Key,
+                    static group => group
+                        .OrderBy(static entry => entry.Id, StringComparer.Ordinal)
+                        .ToArray());
+
+            var conflicts = baseLibEntries
+                .SelectMany(entry => ritsuEntries.TryGetValue((entry.EnumType, entry.Value), out var ritsu)
+                    ? ritsu.Select(ritsuEntry => new DynamicEnumValueCollision(entry, ritsuEntry))
+                    : [])
+                .OrderBy(static collision => collision.BaseLibEntry.EnumType.FullName, StringComparer.Ordinal)
+                .ThenBy(static collision => collision.BaseLibEntry.Value)
+                .ThenBy(static collision => collision.RitsuEntry.Id, StringComparer.Ordinal)
+                .ToArray();
+
+            foreach (var collision in conflicts)
+                RitsuLibFramework.Logger.ErrorNoTrace(
+                    "[DynamicEnum] BaseLib/RitsuLib value collision detected: "
+                    + $"{collision.BaseLibEntry.EnumType.FullName} value 0x{collision.BaseLibEntry.Value:X8} "
+                    + $"is used by BaseLib '{collision.BaseLibEntry.DisplayName}' and RitsuLib "
+                    + $"'{collision.RitsuEntry.DisplayName}'.");
+
+            if (conflicts.Length > 0)
+                RitsuLibFramework.Logger.ErrorNoTrace(
+                    "[DynamicEnum] BaseLib/RitsuLib dynamic enum value collisions are unsafe. "
+                    + "RitsuLib does not remap minted values automatically; change the colliding RitsuLib id or "
+                    + "the BaseLib CustomEnum field/name source.");
+        }
+
         internal static void ThrowIfEpochIdConflicts(string epochId, Type candidateType,
             IEnumerable<Type> knownEpochTypes)
         {
@@ -132,5 +179,138 @@ private static string GetStoryId(Type type)
                             throw new InvalidOperationException(
                                 $"Story type '{type.FullName}' does not expose an Id property."));
         }
+
+        private static BaseLibCustomEnumEntry[] GetBaseLibCustomEnumEntries()
+        {
+            var customEnumsType = ResolveLoadedType("BaseLib.Patches.Content.CustomEnums");
+            var generatedEntriesField = customEnumsType?.GetField(
+                "GeneratedCustomEnumEntries",
+                BindingFlags.Static | BindingFlags.Public);
+
+            if (generatedEntriesField?.GetValue(null) is not IDictionary byEnumType)
+                return [];
+
+            var result = new List<BaseLibCustomEnumEntry>();
+            foreach (DictionaryEntry enumGroup in byEnumType)
+            {
+                if (enumGroup.Key is not Type enumType || enumGroup.Value is not IDictionary entriesByValue)
+                    continue;
+
+                foreach (DictionaryEntry entry in entriesByValue)
+                {
+                    if (!TryConvertToInt32(entry.Key, out var value))
+                        continue;
+
+                    var (prefix, name) = ReadBaseLibGeneratedName(entry.Value);
+                    result.Add(new(enumType, value, prefix, name));
+                }
+            }
+
+            return result.ToArray();
+        }
+
+        private static IEnumerable<RitsuDynamicEnumEntry> GetRitsuDynamicEnumEntries()
+        {
+            foreach (var entry in GetRitsuDynamicEnumEntries<CardKeyword>())
+                yield return entry;
+            foreach (var entry in GetRitsuDynamicEnumEntries<PileType>())
+                yield return entry;
+            foreach (var entry in GetRitsuDynamicEnumEntries<CardTag>())
+                yield return entry;
+            foreach (var entry in GetRitsuDynamicEnumEntries<RewardType>())
+                yield return entry;
+            foreach (var entry in GetRitsuDynamicEnumEntries<TargetType>())
+                yield return entry;
+        }
+
+        private static IEnumerable<RitsuDynamicEnumEntry> GetRitsuDynamicEnumEntries<TEnum>()
+            where TEnum : struct, Enum
+        {
+            var entriesByValue = new Dictionary<int, RitsuDynamicEnumEntry>();
+            foreach (var definition in DynamicEnumValueRegistry<TEnum>.GetDefinitionsSnapshot())
+            {
+                var value = Convert.ToInt32(definition.Value);
+                entriesByValue[value] = new(typeof(TEnum), value, definition.Id, definition.ModId, true);
+            }
+
+            foreach (var (id, value) in DynamicEnumValueRegistry<TEnum>.GetMintedValuesSnapshot())
+            {
+                var numericValue = Convert.ToInt32(value);
+                entriesByValue.TryAdd(numericValue, new(typeof(TEnum), numericValue, id, null, false));
+            }
+
+            return entriesByValue.Values;
+        }
+
+        private static Type? ResolveLoadedType(string fullTypeName)
+        {
+            foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
+            {
+                Type? type = null;
+                try
+                {
+                    type = assembly.GetType(fullTypeName, false);
+                }
+                catch
+                {
+                    // ignored
+                }
+
+                if (type != null)
+                    return type;
+            }
+
+            return null;
+        }
+
+        private static (string Prefix, string Name) ReadBaseLibGeneratedName(object? generatedName)
+        {
+            if (generatedName == null)
+                return ("", "<unknown>");
+
+            var type = generatedName.GetType();
+            var prefix = type.GetField("Item1")?.GetValue(generatedName) as string ?? "";
+            var name = type.GetField("Item2")?.GetValue(generatedName) as string ?? "<unknown>";
+            return (prefix, name);
+        }
+
+        private static bool TryConvertToInt32(object key, out int value)
+        {
+            try
+            {
+                value = Convert.ToInt32(key);
+                return true;
+            }
+            catch
+            {
+                value = 0;
+                return false;
+            }
+        }
+
+        private readonly record struct BaseLibCustomEnumEntry(
+            Type EnumType,
+            int Value,
+            string Prefix,
+            string Name)
+        {
+            public string DisplayName => $"{Prefix}{Name}";
+        }
+
+        private readonly record struct RitsuDynamicEnumEntry(
+            Type EnumType,
+            int Value,
+            string Id,
+            string? ModId,
+            bool Registered)
+        {
+            public string DisplayName => Registered && !string.IsNullOrWhiteSpace(ModId)
+                ? $"{Id} (mod {ModId})"
+                : $"{Id} (minted lookup)";
+        }
+
+        private readonly record struct DynamicEnumValueCollision(
+            BaseLibCustomEnumEntry BaseLibEntry,
+            RitsuDynamicEnumEntry RitsuEntry);
     }
 }

Utils/DynamicEnumValueMinter.cs

@@ -185,6 +185,17 @@ public bool IsDynamic(TEnum value)
             }
         }
 
+        internal (string Id, TEnum Value)[] GetMintedValuesSnapshot()
+        {
+            lock (_sync)
+            {
+                return _byId
+                    .OrderBy(static pair => pair.Key, StringComparer.Ordinal)
+                    .Select(static pair => (pair.Key, pair.Value))
+                    .ToArray();
+            }
+        }
+
         private TEnum Compute(string normalizedId)
         {
             var bytes = Encoding.UTF8.GetBytes(normalizedId);

Utils/DynamicEnumValueRegistry.cs

@@ -293,6 +293,11 @@ public static bool IsMinted(TEnum value)
             return Minter.IsDynamic(value);
         }
 
+        internal static (string Id, TEnum Value)[] GetMintedValuesSnapshot()
+        {
+            return Minter.GetMintedValuesSnapshot();
+        }
+
         /// <summary>
         ///     Snapshot of all registered dynamic enum definitions, stable-ordered by id.
         ///     获取所有已注册动态枚举定义的快照，并按 ID 稳定排序。