Allow to obsolete a cli option

src/Platform/Microsoft.Testing.Platform/CommandLine/CommandLineHandler.cs

@@ -112,7 +112,8 @@ async Task DisplayOptionsAsync(IOutputDevice outputDevice, IEnumerable<CommandLi
             string optionInfoIndent = new(' ', (indentLevel + 1) * 2);
             foreach (CommandLineOption option in options.OrderBy(x => x.Name))
             {
-                await outputDevice.DisplayAsync(this, new TextOutputDeviceData($"{optionNameIndent}--{option.Name}"), cancellationToken).ConfigureAwait(false);
+                string optionName = option.ObsolescenceMessage is not null ? $"{optionNameIndent}--{option.Name} [obsolete]" : $"{optionNameIndent}--{option.Name}";
+                await outputDevice.DisplayAsync(this, new TextOutputDeviceData(optionName), cancellationToken).ConfigureAwait(false);
                 if (option.Arity.Min == option.Arity.Max)
                 {
                     await outputDevice.DisplayAsync(this, new TextOutputDeviceData($"{optionInfoIndent}Arity: {option.Arity.Min}"), cancellationToken).ConfigureAwait(false);
@@ -125,6 +126,10 @@ async Task DisplayOptionsAsync(IOutputDevice outputDevice, IEnumerable<CommandLi
 
                 await outputDevice.DisplayAsync(this, new TextOutputDeviceData($"{optionInfoIndent}Hidden: {option.IsHidden}"), cancellationToken).ConfigureAwait(false);
                 await outputDevice.DisplayAsync(this, new FormattedTextOutputDeviceData($"Description: {option.Description}") { Padding = optionInfoIndent.Length }, cancellationToken).ConfigureAwait(false);
+                if (option.ObsolescenceMessage is not null)
+                {
+                    await outputDevice.DisplayAsync(this, new FormattedTextOutputDeviceData($"Obsolete: {option.ObsolescenceMessage}") { Padding = optionInfoIndent.Length }, cancellationToken).ConfigureAwait(false);
+                }
             }
         }
 
@@ -257,8 +262,14 @@ [.. optionProviders
 
             foreach (CommandLineOption? option in options)
             {
-                await outputDevice.DisplayAsync(this, new FormattedTextOutputDeviceData($"--{option.Name}") { Padding = 4 }, cancellationToken).ConfigureAwait(false);
+                string optionName = option.ObsolescenceMessage is not null ? $"--{option.Name} [obsolete]" : $"--{option.Name}";
+                await outputDevice.DisplayAsync(this, new FormattedTextOutputDeviceData(optionName) { Padding = 4 }, cancellationToken).ConfigureAwait(false);
                 await outputDevice.DisplayAsync(this, new FormattedTextOutputDeviceData(option.Description) { Padding = 8 }, cancellationToken).ConfigureAwait(false);
+                if (option.ObsolescenceMessage is not null)
+                {
+                    await outputDevice.DisplayAsync(this, new FormattedTextOutputDeviceData($"Obsolete: {option.ObsolescenceMessage}") { Padding = 8 }, cancellationToken).ConfigureAwait(false);
+                }
+
                 await outputDevice.DisplayAsync(this, new TextOutputDeviceData(string.Empty), cancellationToken).ConfigureAwait(false);
             }
 

src/Platform/Microsoft.Testing.Platform/CommandLine/CommandLineOption.cs

@@ -20,7 +20,8 @@ public sealed class CommandLineOption : IEquatable<CommandLineOption>
     /// <param name="arity">The arity of the command line option.</param>
     /// <param name="isHidden">Indicates whether the command line option is hidden.</param>
     /// <param name="isBuiltIn">Indicates whether the command line option is built-in.</param>
-    internal CommandLineOption(string name, string description, ArgumentArity arity, bool isHidden, bool isBuiltIn)
+    /// <param name="obsolescenceMessage">The obsolescence message for the command line option.</param>
+    internal CommandLineOption(string name, string description, ArgumentArity arity, bool isHidden, bool isBuiltIn, string? obsolescenceMessage = null)
     {
         Guard.NotNullOrWhiteSpace(name);
         Guard.NotNullOrWhiteSpace(description);
@@ -37,6 +38,24 @@ internal CommandLineOption(string name, string description, ArgumentArity arity,
         Arity = arity;
         IsHidden = isHidden;
         IsBuiltIn = isBuiltIn;
+        ObsolescenceMessage = obsolescenceMessage;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CommandLineOption"/> class.
+    /// </summary>
+    /// <param name="name">The name of the command line option.</param>
+    /// <param name="description">The description of the command line option.</param>
+    /// <param name="arity">The arity of the command line option.</param>
+    /// <param name="isHidden">Indicates whether the command line option is hidden.</param>
+    /// <param name="obsolescenceMessage">The obsolescence message for the command line option.</param>
+    /// <remarks>
+    /// This ctor is public and used by non built-in extension, we need to know if the extension is built-in or not
+    /// to correctly handle the --internal- prefix.
+    /// </remarks>
+    public CommandLineOption(string name, string description, ArgumentArity arity, bool isHidden, string? obsolescenceMessage = null)
+        : this(name, description, arity, isHidden, isBuiltIn: false, obsolescenceMessage)
+    {
     }
 
     /// <summary>
@@ -51,7 +70,7 @@ internal CommandLineOption(string name, string description, ArgumentArity arity,
     /// to correctly handle the --internal- prefix.
     /// </remarks>
     public CommandLineOption(string name, string description, ArgumentArity arity, bool isHidden)
-        : this(name, description, arity, isHidden, isBuiltIn: false)
+        : this(name, description, arity, isHidden, isBuiltIn: false, null)
     {
     }
 
@@ -77,6 +96,11 @@ public CommandLineOption(string name, string description, ArgumentArity arity, b
 
     internal bool IsBuiltIn { get; }
 
+    /// <summary>
+    /// Gets the obsolescence message for the command line option.
+    /// </summary>
+    public string? ObsolescenceMessage { get; }
+
     /// <inheritdoc />
     public override bool Equals(object? obj) => Equals(obj as CommandLineOption);
 
@@ -86,7 +110,8 @@ public bool Equals(CommandLineOption? other)
             Name == other.Name &&
             Description == other.Description &&
             Arity == other.Arity &&
-            IsHidden == other.IsHidden;
+            IsHidden == other.IsHidden &&
+            ObsolescenceMessage == other.ObsolescenceMessage;
 
     /// <inheritdoc />
     public override int GetHashCode()
@@ -96,6 +121,7 @@ public override int GetHashCode()
         hc.Add(Description);
         hc.Add(Arity.GetHashCode());
         hc.Add(IsHidden);
+        hc.Add(ObsolescenceMessage);
         return hc.ToHashCode();
     }
 }

src/Platform/Microsoft.Testing.Platform/CommandLine/CommandLineOptionsValidator.cs

@@ -3,7 +3,9 @@
 
 using Microsoft.Testing.Platform.Extensions;
 using Microsoft.Testing.Platform.Extensions.CommandLine;
+using Microsoft.Testing.Platform.Extensions.OutputDevice;
 using Microsoft.Testing.Platform.Helpers;
+using Microsoft.Testing.Platform.OutputDevice;
 using Microsoft.Testing.Platform.Resources;
 
 namespace Microsoft.Testing.Platform.CommandLine;
@@ -68,6 +70,30 @@ public static async Task<ValidationResult> ValidateAsync(
         return await ValidateConfigurationAsync(extensionOptionsByProvider.Keys, systemOptionsByProvider.Keys, commandLineOptions).ConfigureAwait(false);
     }
 
+    public static async Task CheckForObsoleteOptionsAsync(
+        CommandLineParseResult commandLineParseResult,
+        IEnumerable<ICommandLineOptionsProvider> systemCommandLineOptionsProviders,
+        IEnumerable<ICommandLineOptionsProvider> extensionCommandLineOptionsProviders,
+        IOutputDevice outputDevice,
+        IOutputDeviceDataProducer outputDeviceDataProducer,
+        CancellationToken cancellationToken)
+    {
+        var allOptions = systemCommandLineOptionsProviders
+            .Union(extensionCommandLineOptionsProviders)
+            .SelectMany(provider => provider.GetCommandLineOptions())
+            .Where(option => option.ObsolescenceMessage is not null)
+            .ToDictionary(option => option.Name);
+
+        foreach (CommandLineParseOption optionRecord in commandLineParseResult.Options)
+        {
+            if (allOptions.TryGetValue(optionRecord.Name, out CommandLineOption? option))
+            {
+                string warningMessage = string.Format(CultureInfo.InvariantCulture, PlatformResources.CommandLineOptionObsoleteWarning, optionRecord.Name, option.ObsolescenceMessage);
+                await outputDevice.DisplayAsync(outputDeviceDataProducer, new WarningMessageOutputDeviceData(warningMessage), cancellationToken).ConfigureAwait(false);
+            }
+        }
+    }
+
     private static ValidationResult ValidateExtensionOptionsDoNotContainReservedPrefix(
         Dictionary<ICommandLineOptionsProvider, IReadOnlyCollection<CommandLineOption>> extensionOptionsByProvider)
     {

src/Platform/Microsoft.Testing.Platform/Helpers/HashCode.cs

@@ -11,7 +11,7 @@ internal struct HashCode
 
     public HashCode() => _hash = 17;
 
-    public void Add(string value)
+    public void Add(string? value)
     {
         // Overflow is fine, just wrap
         unchecked

src/Platform/Microsoft.Testing.Platform/Hosts/TestHostBuilder.cs

@@ -139,7 +139,7 @@ public async Task<IHost> BuildAsync(
         // relies on unhandled exception.
 
         // Check the config file, by default is not specified the policy is false.
-        _ = bool.TryParse(configuration[PlatformConfigurationConstants.PlatformExitProcessOnUnhandledException]!, out bool isFileConfiguredToFailFast);
+        _ = bool.TryParse(configuration[PlatformConfigurationConstants.PlatformExitProcessOnUnhandledException], out bool isFileConfiguredToFailFast);
 
         // Check the environment variable, it wins on all the other configuration.
         string? environmentSetting = environment.GetEnvironmentVariable(EnvironmentVariableConstants.TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION);
@@ -249,6 +249,15 @@ public async Task<IHost> BuildAsync(
             return new InformativeCommandLineHost(ExitCodes.InvalidCommandLine, serviceProvider);
         }
 
+        // Check for obsolete options and display warnings
+        await CommandLineOptionsValidator.CheckForObsoleteOptionsAsync(
+            loggingState.CommandLineParseResult,
+            commandLineHandler.SystemCommandLineOptionsProviders,
+            commandLineHandler.ExtensionsCommandLineOptionsProviders,
+            proxyOutputDevice,
+            commandLineHandler,
+            testApplicationCancellationTokenSource.CancellationToken).ConfigureAwait(false);
+
         // Register as ICommandLineOptions.
         serviceProvider.TryAddService(commandLineHandler);
 

src/Platform/Microsoft.Testing.Platform/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,3 @@
 #nullable enable
+Microsoft.Testing.Platform.Extensions.CommandLine.CommandLineOption.CommandLineOption(string! name, string! description, Microsoft.Testing.Platform.Extensions.CommandLine.ArgumentArity arity, bool isHidden, string? obsolescenceMessage = null) -> void
+Microsoft.Testing.Platform.Extensions.CommandLine.CommandLineOption.ObsolescenceMessage.get -> string?

src/Platform/Microsoft.Testing.Platform/Resources/PlatformResources.resx

@@ -316,6 +316,9 @@
   <data name="CommandLineOptionIsReserved" xml:space="preserve">
     <value>Option '--{0}' is reserved and cannot be used by providers: '{0}'</value>
   </data>
+  <data name="CommandLineOptionObsoleteWarning" xml:space="preserve">
+    <value>Warning: Option '--{0}' is obsolete. {1}</value>
+  </data>
   <data name="CommandLineParserUnexpectedArgument" xml:space="preserve">
     <value>Unexpected argument {0}</value>
   </data>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.cs.xlf

@@ -117,6 +117,11 @@
         <target state="translated">Možnost --{0} je vyhrazená a nelze ji použít zprostředkovateli: {0}</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">Možnost --{0} od zprostředkovatele {1} (UID: {2}) používá vyhrazenou předponu --internal.</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.de.xlf

@@ -117,6 +117,11 @@
         <target state="translated">Die Option "--{0}" ist reserviert und kann nicht von Anbietern verwendet werden: "{0}"</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">Die Option "--{0}" vom Anbieter "{1}" (UID: {2}) verwendet das reservierte Präfix "--internal".</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.es.xlf

@@ -117,6 +117,11 @@
         <target state="translated">La opción “--{0}” está reservada y los proveedores no la pueden usar: “{0}”</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">La opción “--{0}” del proveedor “{1}” (UID: {2}) usa el prefijo reservado “--internal”</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.fr.xlf

@@ -117,6 +117,11 @@
         <target state="translated">L’option « --{0} » est réservée et ne peut pas être utilisée par les fournisseurs : « {0} »</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">L’option « --{0} » du fournisseur « {1} » (UID : {2}) utilise le préfixe réservé « --internal »</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.it.xlf

@@ -117,6 +117,11 @@
         <target state="translated">L'opzione '--{0}' è riservata e non può essere usata dai provider: '{0}'</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">L'opzione '--{0}' del provider '{1}' (UID: {2}) usa il prefisso riservato '--internal'</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.ja.xlf

@@ -117,6 +117,11 @@
         <target state="translated">オプション '--{0}' は予約されており、プロバイダーでは使用できません: '{0}'</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">プロバイダー '{1}' のオプション '--{0}' (UID:{2}) は予約済みプレフィックス '--internal' を 使用しています</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.ko.xlf

@@ -117,6 +117,11 @@
         <target state="translated">'--{0}' 옵션은 예약되어 있으므로 공급자 '{0}'이(가) 사용할 수 없습니다.</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">공급자 '{1}'(UID: {2})의 옵션 '-- {0}'이 예약된 접두사 '--internal'을 사용하고 있습니다.</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.pl.xlf

@@ -117,6 +117,11 @@
         <target state="translated">Opcja „--{0}” jest zastrzeżona i nie może być używana przez dostawców: „{0}”</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">Opcja „--{0}” od dostawcy „{1}” (UID: {2}) używa zastrzeżonego prefiksu „--internal”</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.pt-BR.xlf

@@ -117,6 +117,11 @@
         <target state="translated">A opção '--{0}' está reservada e não pode ser usada pelos provedores: '{0}'</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">A opção '--{0}' do provedor '{1}' (UID: {2}) está usando o prefixo reservado '--internal'</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.ru.xlf

@@ -117,6 +117,11 @@
         <target state="translated">Параметр "--{0}" зарезервирован и не может использоваться поставщиками: "{0}"</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">Параметр "--{0}" от поставщика "{1}" (UID: {2}) использует зарезервированный префикс "--internal"</target>

src/Platform/Microsoft.Testing.Platform/Resources/xlf/PlatformResources.tr.xlf

@@ -117,6 +117,11 @@
         <target state="translated">'--{0}' seçeneği ayrılmıştır ve şu sağlayıcılar tarafından kullanılamaz: '{0}'</target>
         <note />
       </trans-unit>
+      <trans-unit id="CommandLineOptionObsoleteWarning">
+        <source>Warning: Option '--{0}' is obsolete. {1}</source>
+        <target state="new">Warning: Option '--{0}' is obsolete. {1}</target>
+        <note />
+      </trans-unit>
       <trans-unit id="CommandLineOptionIsUsingReservedPrefix">
         <source>Option `--{0}` from provider '{1}' (UID: {2}) is using the reserved prefix '--internal'</source>
         <target state="translated">'{1}' sağlayıcısındaki (UID: {2}) `--{0}` seçeneği ayrılmış '--internal' önekini kullanıyor</target>