Add System.CommandLine.StaticCompletions project

Directory.Packages.props

@@ -19,6 +19,8 @@
     <PackageVersion Include="Microsoft.DotNet.PlatformAbstractions" Version="3.1.6" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageVersion Include="System.Memory" Version="4.5.5" />
+    <PackageVersion Include="Verify.Xunit" Version="28.13.0" />
+    <PackageVersion Include="Verify.DiffPlex" Version="3.1.2" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(DisableArcade)' == '1'">

System.CommandLine.sln

@@ -31,6 +31,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "dotnet-suggest.Tests", "src
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "System.CommandLine.ApiCompatibility.Tests", "src\System.CommandLine.ApiCompatibility.Tests\System.CommandLine.ApiCompatibility.Tests.csproj", "{A54EE328-D456-4BAF-A180-84E77E6409AC}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "System.CommandLine.StaticCompletions", "src\System.CommandLine.StaticCompletions\System.CommandLine.StaticCompletions.csproj", "{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "System.CommandLine.StaticCompletions.Tests", "src\System.CommandLine.StaticCompletions.Tests\System.CommandLine.StaticCompletions.Tests.csproj", "{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -101,6 +105,30 @@ Global
 		{A54EE328-D456-4BAF-A180-84E77E6409AC}.Release|x64.Build.0 = Release|Any CPU
 		{A54EE328-D456-4BAF-A180-84E77E6409AC}.Release|x86.ActiveCfg = Release|Any CPU
 		{A54EE328-D456-4BAF-A180-84E77E6409AC}.Release|x86.Build.0 = Release|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Debug|x64.Build.0 = Debug|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Debug|x86.Build.0 = Debug|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Release|x64.ActiveCfg = Release|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Release|x64.Build.0 = Release|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Release|x86.ActiveCfg = Release|Any CPU
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C}.Release|x86.Build.0 = Release|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Debug|x64.Build.0 = Debug|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Debug|x86.Build.0 = Debug|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Release|x64.ActiveCfg = Release|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Release|x64.Build.0 = Release|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Release|x86.ActiveCfg = Release|Any CPU
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -111,6 +139,8 @@ Global
 		{E23C760E-B826-4B4F-BE76-916D86BAD2DB} = {E5B1EC71-0FC4-4FAA-9C65-32D5016FBC45}
 		{E41F0471-B14D-4FA0-9D8B-1E7750695AE9} = {E5B1EC71-0FC4-4FAA-9C65-32D5016FBC45}
 		{A54EE328-D456-4BAF-A180-84E77E6409AC} = {E5B1EC71-0FC4-4FAA-9C65-32D5016FBC45}
+		{B1C3A2F4-5D6E-7F8A-9B0C-1D2E3F4A5B6C} = {E5B1EC71-0FC4-4FAA-9C65-32D5016FBC45}
+		{C2D3E4F5-6A7B-8C9D-0E1F-2A3B4C5D6E7F} = {E5B1EC71-0FC4-4FAA-9C65-32D5016FBC45}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {5C159F93-800B-49E7-9905-EE09F8B8434A}

src/System.CommandLine.StaticCompletions.Tests/BashShellProviderTests.cs

@@ -0,0 +1,53 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+namespace System.CommandLine.StaticCompletions.Tests;
+
+using System.CommandLine.StaticCompletions.Shells;
+
+public class BashShellProviderTests(ITestOutputHelper log)
+{
+    private IShellProvider provider = new BashShellProvider();
+    [Fact]
+    public async Task GenericCompletions()
+    {
+        await provider.Verify(new("mycommand"), log);
+    }
+
+    [Fact]
+    public async Task SimpleOptionCompletion()
+    {
+        await provider.Verify(new("mycommand") {
+            new Option<string>("--name")
+        }, log);
+    }
+
+    [Fact]
+    public async Task SubcommandAndOptionInTopLevelList()
+    {
+        await provider.Verify(new("mycommand") {
+                new Option<string>("--name"),
+                new Command("subcommand")
+            }, log);
+    }
+
+    [Fact]
+    public async Task NestedSubcommandCompletion()
+    {
+        await provider.Verify(new("mycommand") {
+            new Command("subcommand") {
+                new Command("nested")
+            }
+        }, log);
+    }
+
+    [Fact]
+    public async Task DynamicCompletionsGeneration()
+    {
+        var dynamicOption = new Option<string>("--name") { IsDynamic = true };
+        var dynamicArg = new Argument<string>("target") { IsDynamic = true };
+        await provider.Verify(new("mycommand") { dynamicOption, dynamicArg }, log);
+    }
+}

src/System.CommandLine.StaticCompletions.Tests/CompletionsCommandParserTests.cs

@@ -0,0 +1,76 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+namespace System.CommandLine.StaticCompletions.Tests;
+
+using System.CommandLine.Completions;
+
+public class CompletionsCommandParserTests
+{
+    private static RootCommand CreateRootCommandWithCompletions(bool withDynamicSymbol)
+    {
+        var rootCommand = new RootCommand("my test app");
+        if (withDynamicSymbol)
+        {
+            rootCommand.Options.Add(new Option<string>("--name") { IsDynamic = true });
+        }
+
+        var completionsCommand = new CompletionsCommandDefinition();
+        CompletionsCommandParser.ConfigureCommand(completionsCommand);
+        rootCommand.Subcommands.Add(completionsCommand);
+        return rootCommand;
+    }
+
+    private static (int exitCode, string output, string error) GenerateScript(RootCommand rootCommand)
+    {
+        var output = new StringWriter();
+        var error = new StringWriter();
+        var exitCode = rootCommand.Parse(["completions", "script", "bash"]).Invoke(new InvocationConfiguration
+        {
+            Output = output,
+            Error = error
+        });
+        return (exitCode, output.ToString(), error.ToString());
+    }
+
+    [Fact]
+    public void NoWarningWhenSuggestDirectiveIsEnabled()
+    {
+        var rootCommand = CreateRootCommandWithCompletions(withDynamicSymbol: true);
+
+        var (exitCode, output, error) = GenerateScript(rootCommand);
+
+        exitCode.Should().Be(0);
+        output.Should().NotBeEmpty();
+        error.Should().BeEmpty();
+    }
+
+    [Fact]
+    public void WarnsWhenSuggestDirectiveIsDisabledAndDynamicSymbolsArePresent()
+    {
+        var rootCommand = CreateRootCommandWithCompletions(withDynamicSymbol: true);
+        rootCommand.Directives.Remove(rootCommand.Directives.OfType<SuggestDirective>().Single());
+
+        var (exitCode, output, error) = GenerateScript(rootCommand);
+
+        // the script is still generated, but the user is warned that dynamic completions won't resolve
+        exitCode.Should().Be(0);
+        output.Should().NotBeEmpty();
+        error.Should().Contain("[suggest]");
+    }
+
+    [Fact]
+    public void NoWarningWhenSuggestDirectiveIsDisabledButNoDynamicSymbolsArePresent()
+    {
+        var rootCommand = CreateRootCommandWithCompletions(withDynamicSymbol: false);
+        rootCommand.Directives.Remove(rootCommand.Directives.OfType<SuggestDirective>().Single());
+
+        var (exitCode, output, error) = GenerateScript(rootCommand);
+
+        exitCode.Should().Be(0);
+        output.Should().NotBeEmpty();
+        error.Should().BeEmpty();
+    }
+}

src/System.CommandLine.StaticCompletions.Tests/Directory.Build.targets

@@ -0,0 +1,11 @@
+<Project>
+
+  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.targets', '$(MSBuildThisFileDirectory)../'))" />
+
+  <!-- Microsoft.NET.Test.Sdk unconditionally sets OutputType=Exe, but this project uses
+       Arcade's xunit console runner (which invokes the DLL directly), so Library is correct. -->
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+  </PropertyGroup>
+
+</Project>

src/System.CommandLine.StaticCompletions.Tests/FishShellProviderTests.cs

@@ -0,0 +1,118 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+namespace System.CommandLine.StaticCompletions.Tests;
+
+using System.CommandLine.StaticCompletions.Shells;
+
+public class FishShellProviderTests(ITestOutputHelper log)
+{
+    private IShellProvider provider = new FishShellProvider();
+
+    [Fact]
+    public async Task GenericCompletions()
+    {
+        await provider.Verify(new("mycommand"), log);
+    }
+
+    [Fact]
+    public async Task SimpleOptionCompletion()
+    {
+        await provider.Verify(new("mycommand") {
+            new Option<string>("--name")
+        }, log);
+    }
+
+    [Fact]
+    public async Task SubcommandAndOptionInTopLevelList()
+    {
+        await provider.Verify(new("mycommand") {
+                new Option<string>("--name"),
+                new Command("subcommand")
+            }, log);
+    }
+
+    [Fact]
+    public async Task NestedSubcommandCompletion()
+    {
+        await provider.Verify(new("mycommand") {
+            new Command("subcommand") {
+                new Command("nested")
+            }
+        }, log);
+    }
+
+    [Fact]
+    public async Task DynamicCompletionsGeneration()
+    {
+        var dynamicOption = new Option<string>("--name") { IsDynamic = true };
+        var dynamicArg = new Argument<string>("target") { IsDynamic = true };
+        await provider.Verify(new("mycommand") { dynamicOption, dynamicArg }, log);
+    }
+
+    [Fact]
+    public async Task StaticOptionValues()
+    {
+        var staticOption = new Option<int>("--verbosity");
+        staticOption.AcceptOnlyFromAmong("quiet", "minimal", "normal", "detailed", "diagnostic");
+        await provider.Verify(new("mycommand") {
+            staticOption
+        }, log);
+    }
+
+    [Fact]
+    public async Task BoundedMultiValueOption()
+    {
+        var multiOption = new Option<string[]>("--sources")
+        {
+            Arity = new ArgumentArity(1, 3)
+        };
+        multiOption.AcceptOnlyFromAmong("src1", "src2", "src3", "src4");
+        await provider.Verify(new("mycommand") {
+            multiOption,
+            new Command("subcommand")
+        }, log);
+    }
+
+    [Fact]
+    public async Task UnboundedMultiValueOption()
+    {
+        var unboundedOption = new Option<string[]>("--items")
+        {
+            Arity = ArgumentArity.ZeroOrMore
+        };
+        unboundedOption.AcceptOnlyFromAmong("a", "b", "c");
+        await provider.Verify(new("mycommand") {
+            unboundedOption,
+            new Option<string>("--name"),
+            new Command("subcommand")
+        }, log);
+    }
+
+    [Fact]
+    public async Task MixedArityOptions()
+    {
+        var singleOption = new Option<string>("--config");
+        singleOption.AcceptOnlyFromAmong("debug", "release");
+
+        var multiOption = new Option<string[]>("--framework", "-f")
+        {
+            Arity = new ArgumentArity(1, 3)
+        };
+        multiOption.AcceptOnlyFromAmong("net8.0", "net9.0", "net10.0");
+
+        var unboundedOption = new Option<string[]>("--sources")
+        {
+            Arity = ArgumentArity.OneOrMore
+        };
+
+        await provider.Verify(new("mycommand") {
+            singleOption,
+            multiOption,
+            unboundedOption,
+            new Command("build")
+        }, log);
+    }
+}

src/System.CommandLine.StaticCompletions.Tests/GlobalUsings.cs

@@ -0,0 +1,6 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+global using Xunit;
+global using Xunit.Abstractions;
+global using FluentAssertions;

src/System.CommandLine.StaticCompletions.Tests/HelpExtensionsTests.cs

@@ -0,0 +1,47 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+namespace System.CommandLine.StaticCompletions.Tests;
+
+using System.CommandLine.Help;
+using System.CommandLine.StaticCompletions;
+
+public class HelpExtensionsTests
+{
+    [Fact]
+    public void HelpOptionOnlyShowsUsefulNames()
+    {
+        new HelpOption().Names().Should().BeEquivalentTo(["--help", "-h"]);
+    }
+
+    [Fact]
+    public void OptionNamesListNameThenAliases()
+    {
+        new Option<string>("--name", "-n", "--nombre").Names().Should().Equal(["--name", "-n", "--nombre"]);
+    }
+
+    [Fact]
+    public void OptionsWithNoAliasesHaveOnlyOneName()
+    {
+        new Option<string>("--name").Names().Should().Equal(["--name"]);
+    }
+
+    [Fact]
+    public void HeirarchicalOptionsAreFlattened()
+    {
+        var parentCommand = new Command("parent");
+        var childCommand = new Command("child");
+        parentCommand.Subcommands.Add(childCommand);
+        parentCommand.Options.Add(new Option<string>("--parent-global") { Recursive = true });
+        parentCommand.Options.Add(new Option<string>("--parent-local") { Recursive = false });
+        parentCommand.Options.Add(new Option<string>("--parent-global-but-hidden") { Recursive = true, Hidden = true });
+
+        childCommand.Options.Add(new Option<string>("--child-local"));
+        childCommand.Options.Add(new Option<string>("--child-hidden") { Hidden = true });
+
+        // note: no parent-local or parent-global-but-hidden options, and no locally hidden options
+        childCommand.HierarchicalOptions().Select(c => c.Name).Should().Equal(["--child-local", "--parent-global"]);
+    }
+}

src/System.CommandLine.StaticCompletions.Tests/NushellShellProviderTests.cs

@@ -0,0 +1,19 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+namespace System.CommandLine.StaticCompletions.Tests;
+
+using System.CommandLine.StaticCompletions.Shells;
+
+public class NushellShellProviderTests(ITestOutputHelper log)
+{
+    private IShellProvider provider = new NushellShellProvider();
+
+    [Fact]
+    public async Task GenericCompletions()
+    {
+        await provider.Verify(new("mycommand"), log);
+    }
+}