Clarify ordering of auth schemes in ServiceIndex (#1915)

Updates the docs for getEffectiveAuthSchemes to clarify that the
returned auth schemes will be in alphabetical order by shape id
if there is no `auth` trait present. This was always the case due
to the usage of TreeMap, but the documentation didn't explicitly
state it.

Tests were also updated to ensure this ordering.

smithy-model/src/main/java/software/amazon/smithy/model/knowledge/ServiceIndex.java

@@ -127,7 +127,7 @@ public Map<ShapeId, Trait> getAuthSchemes(ToShapeId service) {
      *
      * <p>The returned map is provided in the same order as the values in the
      * {@code auth} trait if an auth trait is present, otherwise the result
-     * is returned in an undefined order.
+     * returned is ordered alphabetically by absolute shape id.
      *
      * <p>An empty map is returned if {@code service} cannot be found in the
      * model or is not a service shape.
@@ -167,7 +167,7 @@ public Map<ShapeId, Trait> getEffectiveAuthSchemes(ToShapeId service) {
      *
      * <p>The returned map is provided in the same order as the values in the
      * {@code auth} trait if an auth trait is present, otherwise the result
-     * is returned in an undefined order.
+     * returned is ordered alphabetically by absolute shape id.
      *
      * <p>An empty map is returned if {@code service} shape cannot be found
      * in the model or is not a service shape. An empty map is returned if

smithy-model/src/test/java/software/amazon/smithy/model/knowledge/ServiceIndexTest.java

@@ -19,7 +19,10 @@
 import static org.hamcrest.Matchers.empty;
 import static org.hamcrest.Matchers.hasKey;
 import static org.hamcrest.Matchers.hasSize;
+import static org.hamcrest.Matchers.equalTo;
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
@@ -68,10 +71,11 @@ public void returnsAuthSchemesOfService() {
         Map<ShapeId, Trait> auth = serviceIndex.getAuthSchemes(
                 ShapeId.from("smithy.example#ServiceWithNoAuthTrait"));
 
-        assertThat(auth.keySet(), hasSize(3));
-        assertThat(auth, hasKey(HttpBasicAuthTrait.ID));
-        assertThat(auth, hasKey(HttpDigestAuthTrait.ID));
-        assertThat(auth, hasKey(HttpBearerAuthTrait.ID));
+        List<ShapeId> ids = new ArrayList<>(auth.keySet());
+        assertThat(ids, hasSize(3));
+        assertThat(ids.get(0), equalTo(HttpBasicAuthTrait.ID));
+        assertThat(ids.get(1), equalTo(HttpBearerAuthTrait.ID));
+        assertThat(ids.get(2), equalTo(HttpDigestAuthTrait.ID));
     }
 
     @Test
@@ -80,10 +84,11 @@ public void getsAuthSchemesOfServiceWithNoAuthTrait() {
         Map<ShapeId, Trait> auth = serviceIndex.getEffectiveAuthSchemes(
                 ShapeId.from("smithy.example#ServiceWithNoAuthTrait"));
 
-        assertThat(auth.keySet(), hasSize(3));
-        assertThat(auth, hasKey(HttpBasicAuthTrait.ID));
-        assertThat(auth, hasKey(HttpDigestAuthTrait.ID));
-        assertThat(auth, hasKey(HttpBearerAuthTrait.ID));
+        List<ShapeId> ids = new ArrayList<>(auth.keySet());
+        assertThat(ids, hasSize(3));
+        assertThat(ids.get(0), equalTo(HttpBasicAuthTrait.ID));
+        assertThat(ids.get(1), equalTo(HttpBearerAuthTrait.ID));
+        assertThat(ids.get(2), equalTo(HttpDigestAuthTrait.ID));
     }
 
     @Test
@@ -92,9 +97,10 @@ public void getsAuthSchemesOfServiceWithAuthTrait() {
         Map<ShapeId, Trait> auth = serviceIndex.getEffectiveAuthSchemes(
                 ShapeId.from("smithy.example#ServiceWithAuthTrait"));
 
+        List<ShapeId> ids = new ArrayList<>(auth.keySet());
         assertThat(auth.keySet(), hasSize(2));
-        assertThat(auth, hasKey(HttpBasicAuthTrait.ID));
-        assertThat(auth, hasKey(HttpDigestAuthTrait.ID));
+        assertThat(ids.get(0), equalTo(HttpBasicAuthTrait.ID));
+        assertThat(ids.get(1), equalTo(HttpDigestAuthTrait.ID));
     }
 
     @Test
@@ -104,10 +110,11 @@ public void getsAuthSchemesOfOperationWithNoAuthTraitAndServiceWithNoAuthTrait()
                 ShapeId.from("smithy.example#ServiceWithNoAuthTrait"),
                 ShapeId.from("smithy.example#OperationWithNoAuthTrait"));
 
-        assertThat(auth.keySet(), hasSize(3));
-        assertThat(auth, hasKey(HttpBasicAuthTrait.ID));
-        assertThat(auth, hasKey(HttpDigestAuthTrait.ID));
-        assertThat(auth, hasKey(HttpBearerAuthTrait.ID));
+        List<ShapeId> ids = new ArrayList<>(auth.keySet());
+        assertThat(ids, hasSize(3));
+        assertThat(ids.get(0), equalTo(HttpBasicAuthTrait.ID));
+        assertThat(ids.get(1), equalTo(HttpBearerAuthTrait.ID));
+        assertThat(ids.get(2), equalTo(HttpDigestAuthTrait.ID));
     }
 
     @Test
@@ -117,9 +124,10 @@ public void getsAuthSchemesOfOperationWithNoAuthTraitAndServiceWithAuthTrait() {
                 ShapeId.from("smithy.example#ServiceWithAuthTrait"),
                 ShapeId.from("smithy.example#OperationWithNoAuthTrait"));
 
-        assertThat(auth.keySet(), hasSize(2));
-        assertThat(auth, hasKey(HttpBasicAuthTrait.ID));
-        assertThat(auth, hasKey(HttpDigestAuthTrait.ID));
+        List<ShapeId> ids = new ArrayList<>(auth.keySet());
+        assertThat(ids, hasSize(2));
+        assertThat(ids.get(0), equalTo(HttpBasicAuthTrait.ID));
+        assertThat(ids.get(1), equalTo(HttpDigestAuthTrait.ID));
     }
 
     @Test