From f477bdd911aacffc10cdb9ca46645a54545d6d3f Mon Sep 17 00:00:00 2001
From: Nate Bosch <nbosch@google.com>
Date: Fri, 17 Jan 2025 00:14:13 +0000
Subject: [PATCH] Remove sorting of allowedHelp maps

Closes #845

It is idiomatic to treat the key order of a Dart map as meaningful
given that map literals and default Map type preserve key insertion
order. It is more useful to allow the caller to decide this order than
to mandate an alpha sorting by key. Callers which need this order can
construct the map appropriately, and callers which prefer a different
order now have the capability.

Releasing as a non-breaking change since specific usage output is
considered an implementation detail. This is expected to impact some CI
statuf for packages with tests hardcoding a strict dependency on the
output.

No additional tests are necessary since updating the order in existing
tests demonstrates the same behavior as adding a non-sorting specific
test.
---
 pkgs/args/CHANGELOG.md         | 2 ++
 pkgs/args/lib/src/usage.dart   | 3 +--
 pkgs/args/test/usage_test.dart | 6 +++---
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/pkgs/args/CHANGELOG.md b/pkgs/args/CHANGELOG.md
index b97daf57..ec6bd011 100644
--- a/pkgs/args/CHANGELOG.md
+++ b/pkgs/args/CHANGELOG.md
@@ -1,5 +1,7 @@
 ## 2.6.1-wip
 
+* Remove sorting of the `allowedHelp` argument in usage output. Ordering will
+  depend on key order for the passed `Map`.
 * Fix the repository URL in `pubspec.yaml`.
 * Added option `hideNegatedUsage` to `ArgParser.flag()` allowing a flag to be
   `negatable` without showing it in the usage text.
diff --git a/pkgs/args/lib/src/usage.dart b/pkgs/args/lib/src/usage.dart
index bd39f112..27c85cd5 100644
--- a/pkgs/args/lib/src/usage.dart
+++ b/pkgs/args/lib/src/usage.dart
@@ -90,8 +90,7 @@ class _Usage {
     if (option.help != null) _write(2, option.help!);
 
     if (option.allowedHelp != null) {
-      var allowedNames = option.allowedHelp!.keys.toList();
-      allowedNames.sort();
+      var allowedNames = [...option.allowedHelp!.keys];
       _newline();
       for (var name in allowedNames) {
         _write(1, _allowedTitle(option, name));
diff --git a/pkgs/args/test/usage_test.dart b/pkgs/args/test/usage_test.dart
index 6f5315b5..95a5ef17 100644
--- a/pkgs/args/test/usage_test.dart
+++ b/pkgs/args/test/usage_test.dart
@@ -216,10 +216,10 @@ void main() {
       validateUsage(parser, '''
           --suit              Like in cards
 
+                [spades]      Swords of a soldier
                 [clubs]       Weapons of war
                 [diamonds]    Money for this art
                 [hearts]      The shape of my heart
-                [spades]      Swords of a soldier
           ''');
     });
 
@@ -244,10 +244,10 @@ void main() {
       validateUsage(parser, '''
           --suit                     Like in cards
 
+                [spades]             Swords of a soldier
                 [clubs] (default)    Weapons of war
                 [diamonds]           Money for this art
                 [hearts]             The shape of my heart
-                [spades]             Swords of a soldier
           ''');
     });
 
@@ -271,10 +271,10 @@ void main() {
       validateUsage(parser, '''
           --suit                      Like in cards
 
+                [spades]              Swords of a soldier
                 [clubs] (default)     Weapons of war
                 [diamonds]            Money for this art
                 [hearts] (default)    The shape of my heart
-                [spades]              Swords of a soldier
           ''');
     });