Fix command order in root help usage

src/docfx/Extensions/DocfxHelpProvider.cs

@@ -0,0 +1,50 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Spectre.Console;
+using Spectre.Console.Cli;
+using Spectre.Console.Cli.Help;
+using Spectre.Console.Rendering;
+
+#nullable enable
+
+namespace Docfx;
+
+internal sealed class DocfxHelpProvider : HelpProvider
+{
+    private readonly UsageStyle? _usageStyle;
+
+    public DocfxHelpProvider(ICommandAppSettings settings)
+        : base(settings)
+    {
+        _usageStyle = settings.HelpProviderStyles?.Usage;
+    }
+
+    public override IEnumerable<IRenderable> GetUsage(ICommandModel model, ICommandInfo? command)
+    {
+        if (command is not { IsDefaultCommand: true, Parent: null }
+            || !model.Commands.Any(command => !command.IsHidden && !command.IsDefaultCommand))
+        {
+            return base.GetUsage(model, command);
+        }
+
+        var usage = new Paragraph()
+            .Append("USAGE:", _usageStyle?.Header)
+            .Append("\n    ")
+            .Append(model.ApplicationName)
+            .Append(" [COMMAND]", _usageStyle?.Command);
+
+        foreach (var argument in command.Parameters.OfType<ICommandArgument>().Where(argument => argument.IsRequired).OrderBy(argument => argument.Position))
+        {
+            usage.Append($" <{argument.Value}>", _usageStyle?.RequiredArgument);
+        }
+
+        foreach (var argument in command.Parameters.OfType<ICommandArgument>().Where(argument => !argument.IsRequired).OrderBy(argument => argument.Position))
+        {
+            usage.Append($" [{argument.Value}]", _usageStyle?.OptionalArgument);
+        }
+
+        usage.Append(" [OPTIONS]\n", _usageStyle?.Options);
+        return [usage];
+    }
+}

src/docfx/Program.cs

@@ -12,16 +12,25 @@ namespace Docfx;
 internal class Program
 {
     internal static int Main(string[] args)
+    {
+        return Run(args);
+    }
+
+    internal static int Run(string[] args, IAnsiConsole? console = null)
     {
         var app = new CommandApp();
 
         app.SetDefaultCommand<DefaultCommand>();
         app.Configure(config =>
         {
             config.SetApplicationName("docfx");
+            config.SetHelpProvider(new DocfxHelpProvider(config.Settings));
             config.UseStrictParsing();
             config.SetExceptionHandler(OnException);
 
+            if (console is not null)
+                config.ConfigureConsole(console);
+
             config.AddCommand<InitCommand>("init");
             config.AddCommand<BuildCommand>("build");
             config.AddCommand<MetadataCommand>("metadata");

test/docfx.Tests/CommandLineTest.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using Docfx.Common;
+using Spectre.Console;
 
 namespace Docfx.Tests;
 
@@ -30,6 +31,24 @@ public static void PrintsHelp()
         Assert.Equal(0, Program.Main(["template", "--help"]));
     }
 
+    [Fact]
+    public static void PrintsRootUsageInCommandFirstOrder()
+    {
+        using var writer = new StringWriter();
+        var console = AnsiConsole.Create(new()
+        {
+            Ansi = AnsiSupport.No,
+            ColorSystem = ColorSystemSupport.NoColors,
+            Out = new AnsiConsoleOutput(writer),
+        });
+
+        Assert.Equal(0, Program.Run(["-?"], console));
+
+        var output = writer.ToString();
+        Assert.Contains("docfx [COMMAND] [config] [OPTIONS]", output);
+        Assert.DoesNotContain("docfx [config] [OPTIONS] [COMMAND]", output);
+    }
+
     [Fact]
     public static void FailForUnknownArgs()
     {