feat(DevConsole): implement enhanced autocomplete functionality

- Introduced a new system for dev-console autocomplete enhancements, allowing for improved command argument matching and display.
- Added multiple classes for managing autocomplete bindings, context, and enhancements, including DevConsoleAutocomplete, DevConsoleAutocompleteBinding, and DevConsoleAutocompleteRegistry.
- Implemented functionality for localized title matching and display, enabling more user-friendly autocomplete suggestions.
- Registered new patches to apply these enhancements during dev-console command execution, improving overall usability and flexibility.
- Created a catalog for mapping model entry IDs to localized titles, enhancing the autocomplete experience with contextual information.

Author: BAKAOLC

Diagnostics/DevConsole/DevConsoleAutocomplete.cs

@@ -0,0 +1,79 @@
+using MegaCrit.Sts2.Core.DevConsole;
+using MegaCrit.Sts2.Core.DevConsole.ConsoleCommands;
+
+namespace STS2RitsuLib.Diagnostics.DevConsole
+{
+    /// <summary>
+    ///     Public entry point for registering and applying dev-console autocomplete enhancements.
+    /// </summary>
+    public static class DevConsoleAutocomplete
+    {
+        /// <summary>
+        ///     Registers a command-argument autocomplete binding.
+        /// </summary>
+        public static void Register(DevConsoleAutocompleteBinding binding)
+        {
+            DevConsoleAutocompleteRegistry.Register(binding);
+        }
+
+        /// <summary>
+        ///     Registers enhancements for a fixed argument index on a command.
+        /// </summary>
+        public static void Register(
+            string commandName,
+            int argumentIndex,
+            DevConsoleAutocompleteEnhancements enhancements,
+            Func<DevConsoleAutocompleteContext, bool>? appliesWhen = null)
+        {
+            DevConsoleAutocompleteRegistry.Register(commandName, argumentIndex, enhancements, appliesWhen);
+        }
+
+        /// <summary>
+        ///     Registers enhancements selected by <paramref name="appliesWhen" />.
+        /// </summary>
+        public static void Register(
+            string commandName,
+            DevConsoleAutocompleteEnhancements enhancements,
+            Func<DevConsoleAutocompleteContext, bool> appliesWhen)
+        {
+            DevConsoleAutocompleteRegistry.Register(commandName, enhancements, appliesWhen);
+        }
+
+        /// <summary>
+        ///     Resolves enhancements for a completion call.
+        /// </summary>
+        public static DevConsoleAutocompleteEnhancements Resolve(
+            AbstractConsoleCmd command,
+            string[] completedArgs,
+            int argumentIndex)
+        {
+            return DevConsoleAutocompleteRegistry.Resolve(command, completedArgs, argumentIndex);
+        }
+
+        /// <summary>
+        ///     Builds the match predicate chain for manual <c>CompleteArgument</c> usage in mod commands.
+        /// </summary>
+        public static Func<string, string, bool>? BuildMatchPredicate(
+            AbstractConsoleCmd command,
+            string[] completedArgs,
+            Func<string, string, bool>? inner = null)
+        {
+            return DevConsoleAutocompleteEnhancer.BuildMatchPredicate(
+                Resolve(command, completedArgs, completedArgs.Length),
+                inner);
+        }
+
+        /// <summary>
+        ///     Applies result enhancements for manual <c>CompleteArgument</c> usage in mod commands.
+        /// </summary>
+        public static void ApplyToResult(
+            AbstractConsoleCmd command,
+            string[] completedArgs,
+            ref CompletionResult result)
+        {
+            DevConsoleAutocompleteEnhancer.ApplyToResult(
+                ref result,
+                Resolve(command, completedArgs, result.ArgumentIndex));
+        }
+    }
+}

Diagnostics/DevConsole/DevConsoleAutocompleteBinding.cs

@@ -0,0 +1,28 @@
+namespace STS2RitsuLib.Diagnostics.DevConsole
+{
+    /// <summary>
+    ///     Binds autocomplete enhancements to a command argument slot.
+    /// </summary>
+    public sealed class DevConsoleAutocompleteBinding
+    {
+        /// <summary>
+        ///     Dev-console command name (for example <c>card</c>).
+        /// </summary>
+        public required string CommandName { get; init; }
+
+        /// <summary>
+        ///     When set, only this argument index receives the enhancements.
+        /// </summary>
+        public int? ArgumentIndex { get; init; }
+
+        /// <summary>
+        ///     Optional extra guard based on completed arguments and command state.
+        /// </summary>
+        public Func<DevConsoleAutocompleteContext, bool>? AppliesWhen { get; init; }
+
+        /// <summary>
+        ///     Enhancements applied when this binding matches.
+        /// </summary>
+        public DevConsoleAutocompleteEnhancements Enhancements { get; init; }
+    }
+}

Diagnostics/DevConsole/DevConsoleAutocompleteContext.cs

@@ -0,0 +1,43 @@
+using MegaCrit.Sts2.Core.DevConsole.ConsoleCommands;
+
+namespace STS2RitsuLib.Diagnostics.DevConsole
+{
+    /// <summary>
+    ///     Identifies a dev-console <see cref="AbstractConsoleCmd.CompleteArgument" /> invocation.
+    /// </summary>
+    public sealed class DevConsoleAutocompleteContext
+    {
+        /// <summary>
+        ///     Creates a context for the active completion call.
+        /// </summary>
+        public DevConsoleAutocompleteContext(
+            AbstractConsoleCmd command,
+            string[] completedArgs,
+            int argumentIndex)
+        {
+            Command = command ?? throw new ArgumentNullException(nameof(command));
+            CompletedArgs = completedArgs ?? throw new ArgumentNullException(nameof(completedArgs));
+            ArgumentIndex = argumentIndex;
+        }
+
+        /// <summary>
+        ///     Console command producing completions.
+        /// </summary>
+        public AbstractConsoleCmd Command { get; }
+
+        /// <summary>
+        ///     Arguments already present before the token being completed.
+        /// </summary>
+        public IReadOnlyList<string> CompletedArgs { get; }
+
+        /// <summary>
+        ///     Zero-based index of the argument being completed.
+        /// </summary>
+        public int ArgumentIndex { get; }
+
+        /// <summary>
+        ///     Dev-console command name.
+        /// </summary>
+        public string CommandName => Command.CmdName;
+    }
+}

Diagnostics/DevConsole/DevConsoleAutocompleteDefaults.cs

@@ -0,0 +1,58 @@
+namespace STS2RitsuLib.Diagnostics.DevConsole
+{
+    /// <summary>
+    ///     Built-in dev-console autocomplete bindings for vanilla model-entry-id arguments.
+    /// </summary>
+    internal static class DevConsoleAutocompleteDefaults
+    {
+        public static void Register()
+        {
+            RegisterFirstModelEntryId("card");
+            RegisterFirstModelEntryId("potion");
+            RegisterFirstModelEntryId("event");
+            RegisterFirstModelEntryId("ancient");
+            RegisterFirstModelEntryId("fight");
+            RegisterFirstModelEntryId("afflict");
+            RegisterFirstModelEntryId("enchant");
+            RegisterFirstModelEntryId("remove_card");
+
+            DevConsoleAutocompleteRegistry.Register(
+                "relic",
+                DevConsoleAutocompleteEnhancements.RitsuLibModEntryId,
+                IsDirectRelicIdArgument);
+
+            DevConsoleAutocompleteRegistry.Register(
+                "relic",
+                DevConsoleAutocompleteEnhancements.RitsuLibModEntryId,
+                IsRelicIdAfterSubcommand);
+        }
+
+        private static void RegisterFirstModelEntryId(string commandName)
+        {
+            DevConsoleAutocompleteRegistry.Register(
+                commandName,
+                DevConsoleAutocompleteEnhancements.RitsuLibModEntryId,
+                IsFirstModelEntryIdArgument);
+        }
+
+        private static bool IsFirstModelEntryIdArgument(DevConsoleAutocompleteContext context)
+        {
+            return context is { ArgumentIndex: 0, CompletedArgs.Count: 0 };
+        }
+
+        private static bool IsDirectRelicIdArgument(DevConsoleAutocompleteContext context)
+        {
+            return context is { ArgumentIndex: 0, CompletedArgs.Count: 0 };
+        }
+
+        private static bool IsRelicIdAfterSubcommand(DevConsoleAutocompleteContext context)
+        {
+            if (context.ArgumentIndex != 1 || context.CompletedArgs.Count != 1)
+                return false;
+
+            var subcommand = context.CompletedArgs[0];
+            return subcommand.Equals("add", StringComparison.OrdinalIgnoreCase) ||
+                   subcommand.Equals("remove", StringComparison.OrdinalIgnoreCase);
+        }
+    }
+}

Diagnostics/DevConsole/DevConsoleAutocompleteDisplay.cs

@@ -0,0 +1,71 @@
+namespace STS2RitsuLib.Diagnostics.DevConsole
+{
+    /// <summary>
+    ///     Formats dev-console autocomplete candidates with optional localized suffix labels.
+    /// </summary>
+    public static class DevConsoleAutocompleteDisplay
+    {
+        internal const string SuffixOpener = " (";
+
+        /// <summary>
+        ///     Appends <c> (localized-title)</c> to <paramref name="entryId" /> when a localized title exists.
+        /// </summary>
+        public static string FormatCandidate(string entryId)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(entryId);
+
+            var title = DevConsoleModelIdAutocompleteCatalog.TryGetLocalizedTitle(entryId);
+            return string.IsNullOrWhiteSpace(title)
+                ? entryId
+                : $"{entryId}{SuffixOpener}{SanitizeSuffix(title)})";
+        }
+
+        /// <summary>
+        ///     Strips a trailing localized suffix from a decorated autocomplete candidate.
+        /// </summary>
+        public static string StripLocalizedSuffix(string candidate)
+        {
+            if (string.IsNullOrWhiteSpace(candidate))
+                return candidate;
+
+            var suffixStart = candidate.LastIndexOf(SuffixOpener, StringComparison.Ordinal);
+            if (suffixStart < 0 || !candidate.EndsWith(')'))
+                return candidate;
+
+            return candidate[..suffixStart];
+        }
+
+        internal static string SanitizeSuffix(string title)
+        {
+            return title.Replace(')', '\uFF09').Trim();
+        }
+
+        internal static string ComputeCommonPrefix(IReadOnlyList<string> entryIds, string commandPrefix)
+        {
+            switch (entryIds.Count)
+            {
+                case 0:
+                    return string.Empty;
+                case 1:
+                    return commandPrefix + entryIds[0] + " ";
+            }
+
+            var minLength = entryIds.Min(static id => id.Length);
+            var first = entryIds[0];
+            var sharedLength = 0;
+
+            for (var i = 0; i < minLength; i++)
+            {
+                var ch = first[i];
+                if (entryIds.Any(id => char.ToLowerInvariant(id[i]) != char.ToLowerInvariant(ch)))
+                    break;
+
+                sharedLength = i + 1;
+            }
+
+            return sharedLength > 0
+                ? commandPrefix + first[..sharedLength]
+                : string.Empty;
+        }
+    }
+}

Diagnostics/DevConsole/DevConsoleAutocompleteEnhancements.cs

@@ -0,0 +1,45 @@
+namespace STS2RitsuLib.Diagnostics.DevConsole
+{
+    /// <summary>
+    ///     Dev-console autocomplete behaviors that can be bound per command argument.
+    /// </summary>
+    [Flags]
+    public enum DevConsoleAutocompleteEnhancements
+    {
+        /// <summary>
+        ///     No enhancements.
+        /// </summary>
+        None = 0,
+
+        /// <summary>
+        ///     Allows matching candidates by localized title text, not only entry id prefix.
+        /// </summary>
+        LocalizedTitleMatch = 1 << 0,
+
+        /// <summary>
+        ///     Appends <c> (localized-title)</c> to displayed candidates and keeps
+        ///     <see cref="MegaCrit.Sts2.Core.DevConsole.CompletionResult.CommonPrefix" /> canonical.
+        /// </summary>
+        LocalizedDisplayLabels = 1 << 1,
+
+        /// <summary>
+        ///     Enables tail shorthand matching for ritsulib-registered mod entry ids when no custom matcher is supplied.
+        /// </summary>
+        RitsuLibOwnedIdShorthandMatch = 1 << 2,
+
+        /// <summary>
+        ///     Removes duplicate candidates while preserving order.
+        /// </summary>
+        DeduplicateCandidates = 1 << 3,
+
+        /// <summary>
+        ///     Localized title matching and display labels for model entry ids.
+        /// </summary>
+        ModelEntryId = LocalizedTitleMatch | LocalizedDisplayLabels | DeduplicateCandidates,
+
+        /// <summary>
+        ///     <see cref="ModelEntryId" /> plus ritsulib-owned id shorthand matching.
+        /// </summary>
+        RitsuLibModEntryId = ModelEntryId | RitsuLibOwnedIdShorthandMatch,
+    }
+}

Diagnostics/DevConsole/DevConsoleAutocompleteEnhancer.cs

@@ -0,0 +1,51 @@
+using MegaCrit.Sts2.Core.DevConsole;
+
+namespace STS2RitsuLib.Diagnostics.DevConsole
+{
+    /// <summary>
+    ///     Applies registered dev-console autocomplete enhancements to matchers and results.
+    /// </summary>
+    public static class DevConsoleAutocompleteEnhancer
+    {
+        /// <summary>
+        ///     Builds a match predicate chain for <paramref name="enhancements" />.
+        /// </summary>
+        public static Func<string, string, bool>? BuildMatchPredicate(
+            DevConsoleAutocompleteEnhancements enhancements,
+            Func<string, string, bool>? inner = null)
+        {
+            if (enhancements == DevConsoleAutocompleteEnhancements.None)
+                return inner;
+
+            var predicate = inner;
+
+            if (enhancements.HasFlag(DevConsoleAutocompleteEnhancements.RitsuLibOwnedIdShorthandMatch) &&
+                predicate == null)
+                predicate = DevConsoleAutocompleteOwnedIdMatch.Match;
+
+            if (enhancements.HasFlag(DevConsoleAutocompleteEnhancements.LocalizedTitleMatch))
+                predicate = DevConsoleAutocompleteMatchExtensions.WithLocalizedModelTitleMatch(predicate);
+
+            return predicate;
+        }
+
+        /// <summary>
+        ///     Applies result-side enhancements such as localized labels and de-duplication.
+        /// </summary>
+        public static void ApplyToResult(
+            ref CompletionResult result,
+            DevConsoleAutocompleteEnhancements enhancements)
+        {
+            if (enhancements == DevConsoleAutocompleteEnhancements.None || result.Candidates.Count == 0)
+                return;
+
+            if (enhancements.HasFlag(DevConsoleAutocompleteEnhancements.LocalizedDisplayLabels))
+                DevConsoleAutocompleteMatchExtensions.ApplyLocalizedDisplayLabels(ref result);
+
+            if (enhancements.HasFlag(DevConsoleAutocompleteEnhancements.DeduplicateCandidates))
+                result.Candidates = result.Candidates
+                    .Distinct(StringComparer.OrdinalIgnoreCase)
+                    .ToList();
+        }
+    }
+}