Track Option placement within a priority category.

An option has precedence over previous options at the same enum-valued priority. Track its placement in this ordering explicitly.

This will allow after-the-fact expansion of expansion options such that they correctly take precedence or not compared to other mentions of the same flag. This is needed to fix --config's expansion.

RELNOTES: None.
PiperOrigin-RevId: 172367996

6 files changed, 164 insertions, 91 deletions

diff --git a/src/test/java/com/google/devtools/build/lib/runtime/CommandLineEventTest.java b/src/test/java/com/google/devtools/build/lib/runtime/CommandLineEventTest.java
index 44724f1166..aaeec5b094 100644
--- a/src/test/java/com/google/devtools/build/lib/runtime/CommandLineEventTest.java
+++ b/src/test/java/com/google/devtools/build/lib/runtime/CommandLineEventTest.java
@@ -27,7 +27,7 @@ import com.google.devtools.build.lib.runtime.proto.CommandLineOuterClass.Command
 import com.google.devtools.build.lib.runtime.proto.CommandLineOuterClass.CommandLineSection.SectionTypeCase;
 import com.google.devtools.build.lib.runtime.proto.CommandLineOuterClass.OptionList;
 import com.google.devtools.build.lib.util.Pair;
-import com.google.devtools.common.options.OptionPriority;
+import com.google.devtools.common.options.OptionPriority.PriorityCategory;
 import com.google.devtools.common.options.OptionsParser;
 import com.google.devtools.common.options.OptionsParsingException;
 import com.google.devtools.common.options.TestOptions;
@@ -217,15 +217,15 @@ public class CommandLineEventTest {
         OptionsParser.newOptionsParser(BlazeServerStartupOptions.class);
     OptionsParser fakeCommandOptions = OptionsParser.newOptionsParser(TestOptions.class);
     fakeCommandOptions.parse(
-        OptionPriority.COMMAND_LINE,
+        PriorityCategory.COMMAND_LINE,
         "command line",
         ImmutableList.of("--test_string=foo", "--test_multiple_string=bar"));
     fakeCommandOptions.parse(
-        OptionPriority.INVOCATION_POLICY,
+        PriorityCategory.INVOCATION_POLICY,
         "fake invocation policy",
         ImmutableList.of("--expanded_c=2"));
     fakeCommandOptions.parse(
-        OptionPriority.RC_FILE, "fake rc file", ImmutableList.of("--test_multiple_string=baz"));
+        PriorityCategory.RC_FILE, "fake rc file", ImmutableList.of("--test_multiple_string=baz"));
 
     CommandLine line =
         new OriginalCommandLineEvent(
@@ -260,15 +260,15 @@ public class CommandLineEventTest {
         OptionsParser.newOptionsParser(BlazeServerStartupOptions.class);
     OptionsParser fakeCommandOptions = OptionsParser.newOptionsParser(TestOptions.class);
     fakeCommandOptions.parse(
-        OptionPriority.COMMAND_LINE,
+        PriorityCategory.COMMAND_LINE,
         "command line",
         ImmutableList.of("--test_string=foo", "--test_multiple_string=bar"));
     fakeCommandOptions.parse(
-        OptionPriority.INVOCATION_POLICY,
+        PriorityCategory.INVOCATION_POLICY,
         "fake invocation policy",
         ImmutableList.of("--expanded_c=2"));
     fakeCommandOptions.parse(
-        OptionPriority.RC_FILE, "fake rc file", ImmutableList.of("--test_multiple_string=baz"));
+        PriorityCategory.RC_FILE, "fake rc file", ImmutableList.of("--test_multiple_string=baz"));
 
     CommandLine line =
         new CanonicalCommandLineEvent(
@@ -303,7 +303,7 @@ public class CommandLineEventTest {
         OptionsParser.newOptionsParser(BlazeServerStartupOptions.class);
     OptionsParser fakeCommandOptions = OptionsParser.newOptionsParser(TestOptions.class);
     fakeCommandOptions.parse(
-        OptionPriority.COMMAND_LINE, "command line", ImmutableList.of("--test_expansion"));
+        PriorityCategory.COMMAND_LINE, "command line", ImmutableList.of("--test_expansion"));
 
     CommandLine line =
         new OriginalCommandLineEvent(
@@ -335,7 +335,7 @@ public class CommandLineEventTest {
         OptionsParser.newOptionsParser(BlazeServerStartupOptions.class);
     OptionsParser fakeCommandOptions = OptionsParser.newOptionsParser(TestOptions.class);
     fakeCommandOptions.parse(
-        OptionPriority.COMMAND_LINE, "command line", ImmutableList.of("--test_expansion"));
+        PriorityCategory.COMMAND_LINE, "command line", ImmutableList.of("--test_expansion"));
 
     CommandLine line =
         new CanonicalCommandLineEvent(
@@ -375,7 +375,7 @@ public class CommandLineEventTest {
         OptionsParser.newOptionsParser(BlazeServerStartupOptions.class);
     OptionsParser fakeCommandOptions = OptionsParser.newOptionsParser(TestOptions.class);
     fakeCommandOptions.parse(
-        OptionPriority.COMMAND_LINE,
+        PriorityCategory.COMMAND_LINE,
         "command line",
         ImmutableList.of("--test_implicit_requirement=foo"));
 
@@ -409,7 +409,7 @@ public class CommandLineEventTest {
         OptionsParser.newOptionsParser(BlazeServerStartupOptions.class);
     OptionsParser fakeCommandOptions = OptionsParser.newOptionsParser(TestOptions.class);
     fakeCommandOptions.parse(
-        OptionPriority.COMMAND_LINE,
+        PriorityCategory.COMMAND_LINE,
         "command line",
         ImmutableList.of("--test_implicit_requirement=foo"));
 
diff --git a/src/test/java/com/google/devtools/build/lib/util/OptionsUtilsTest.java b/src/test/java/com/google/devtools/build/lib/util/OptionsUtilsTest.java
index aa23d2a581..ddf8dadda9 100644
--- a/src/test/java/com/google/devtools/build/lib/util/OptionsUtilsTest.java
+++ b/src/test/java/com/google/devtools/build/lib/util/OptionsUtilsTest.java
@@ -23,7 +23,7 @@ import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionDocumentationCategory;
 import com.google.devtools.common.options.OptionEffectTag;
 import com.google.devtools.common.options.OptionMetadataTag;
-import com.google.devtools.common.options.OptionPriority;
+import com.google.devtools.common.options.OptionPriority.PriorityCategory;
 import com.google.devtools.common.options.OptionsBase;
 import com.google.devtools.common.options.OptionsParser;
 import java.util.Arrays;
@@ -96,8 +96,8 @@ public class OptionsUtilsTest {
   @Test
   public void asStringOfExplicitOptionsCorrectSortingByPriority() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(IntrospectionExample.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--alpha=no"));
-    parser.parse(OptionPriority.COMPUTED_DEFAULT, null, Arrays.asList("--beta=no"));
+    parser.parse(PriorityCategory.COMMAND_LINE, null, Arrays.asList("--alpha=no"));
+    parser.parse(PriorityCategory.COMPUTED_DEFAULT, null, Arrays.asList("--beta=no"));
     assertThat(OptionsUtils.asShellEscapedString(parser)).isEqualTo("--beta=no --alpha=no");
     assertThat(OptionsUtils.asArgumentList(parser))
         .containsExactly("--beta=no", "--alpha=no")
@@ -127,14 +127,14 @@ public class OptionsUtilsTest {
   @Test
   public void asStringOfExplicitOptionsWithBooleans() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(BooleanOpts.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--b_one", "--nob_two"));
+    parser.parse(PriorityCategory.COMMAND_LINE, null, Arrays.asList("--b_one", "--nob_two"));
     assertThat(OptionsUtils.asShellEscapedString(parser)).isEqualTo("--b_one --nob_two");
     assertThat(OptionsUtils.asArgumentList(parser))
         .containsExactly("--b_one", "--nob_two")
         .inOrder();
 
     parser = OptionsParser.newOptionsParser(BooleanOpts.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--b_one=true", "--b_two=0"));
+    parser.parse(PriorityCategory.COMMAND_LINE, null, Arrays.asList("--b_one=true", "--b_two=0"));
     assertThat(parser.getOptions(BooleanOpts.class).bOne).isTrue();
     assertThat(parser.getOptions(BooleanOpts.class).bTwo).isFalse();
     assertThat(OptionsUtils.asShellEscapedString(parser)).isEqualTo("--b_one --nob_two");
@@ -146,8 +146,8 @@ public class OptionsUtilsTest {
   @Test
   public void asStringOfExplicitOptionsMultipleOptionsAreMultipleTimes() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(IntrospectionExample.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--alpha=one"));
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--alpha=two"));
+    parser.parse(PriorityCategory.COMMAND_LINE, null, Arrays.asList("--alpha=one"));
+    parser.parse(PriorityCategory.COMMAND_LINE, null, Arrays.asList("--alpha=two"));
     assertThat(OptionsUtils.asShellEscapedString(parser)).isEqualTo("--alpha=one --alpha=two");
     assertThat(OptionsUtils.asArgumentList(parser))
         .containsExactly("--alpha=one", "--alpha=two")
diff --git a/src/test/java/com/google/devtools/common/options/InvocationPolicyAllowValuesTest.java b/src/test/java/com/google/devtools/common/options/InvocationPolicyAllowValuesTest.java
index d9112d080d..b8625883fa 100644
--- a/src/test/java/com/google/devtools/common/options/InvocationPolicyAllowValuesTest.java
+++ b/src/test/java/com/google/devtools/common/options/InvocationPolicyAllowValuesTest.java
@@ -266,7 +266,8 @@ public class InvocationPolicyAllowValuesTest extends InvocationPolicyEnforcerTes
       assertThat(e)
           .hasMessageThat()
           .contains(
-              "Flag value 'b' for flag 'test_list_converters' is not allowed by invocation policy");
+              "Flag value 'b' for option '--test_list_converters' is not allowed by invocation "
+                  + "policy");
     }
   }
 }
diff --git a/src/test/java/com/google/devtools/common/options/InvocationPolicyDisallowValuesTest.java b/src/test/java/com/google/devtools/common/options/InvocationPolicyDisallowValuesTest.java
index 9aa2fc9596..2cfaccd41d 100644
--- a/src/test/java/com/google/devtools/common/options/InvocationPolicyDisallowValuesTest.java
+++ b/src/test/java/com/google/devtools/common/options/InvocationPolicyDisallowValuesTest.java
@@ -268,7 +268,8 @@ public class InvocationPolicyDisallowValuesTest extends InvocationPolicyEnforcer
       assertThat(e)
           .hasMessageThat()
           .contains(
-              "Flag value 'a' for flag 'test_list_converters' is not allowed by invocation policy");
+              "Flag value 'a' for option '--test_list_converters' is not allowed by invocation "
+                  + "policy");
     }
   }
 }
diff --git a/src/test/java/com/google/devtools/common/options/OptionsParserTest.java b/src/test/java/com/google/devtools/common/options/OptionsParserTest.java
index dccc44b503..79ac532476 100644
--- a/src/test/java/com/google/devtools/common/options/OptionsParserTest.java
+++ b/src/test/java/com/google/devtools/common/options/OptionsParserTest.java
@@ -19,9 +19,12 @@ import static com.google.devtools.common.options.OptionsParser.newOptionsParser;
 import static java.util.Arrays.asList;
 import static org.junit.Assert.fail;
 
+import com.google.common.collect.ArrayListMultimap;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.ListMultimap;
 import com.google.devtools.common.options.Converters.CommaSeparatedOptionListConverter;
+import com.google.devtools.common.options.OptionPriority.PriorityCategory;
 import com.google.devtools.common.options.OptionValueDescription.RepeatableOptionValueDescription;
 import com.google.devtools.common.options.OptionValueDescription.SingleOptionValueDescription;
 import java.io.ByteArrayInputStream;
@@ -36,11 +39,13 @@ import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardOpenOption;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
+import java.util.Map.Entry;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
 import org.junit.Test;
@@ -914,7 +919,8 @@ public class OptionsParserTest {
   @Test
   public void implicitDependencyHasImplicitDependency() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(ImplicitDependencyOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--first=first"));
+    parser.parse(
+        OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--first=first"));
     assertThat(parser.getOptions(ImplicitDependencyOptions.class).first).isEqualTo("first");
     assertThat(parser.getOptions(ImplicitDependencyOptions.class).second).isEqualTo("second");
     assertThat(parser.getOptions(ImplicitDependencyOptions.class).third).isEqualTo("third");
@@ -935,7 +941,8 @@ public class OptionsParserTest {
   public void badImplicitDependency() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(BadImplicitDependencyOptions.class);
     try {
-      parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--first=first"));
+      parser.parse(
+          OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--first=first"));
     } catch (AssertionError e) {
       /* Expected error. */
       return;
@@ -958,7 +965,7 @@ public class OptionsParserTest {
   public void badExpansionOptions() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(BadExpansionOptions.class);
     try {
-      parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--first"));
+      parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--first"));
     } catch (AssertionError e) {
       /* Expected error. */
       return;
@@ -1029,7 +1036,7 @@ public class OptionsParserTest {
     } catch (OptionsParser.ConstructionException e) {
       assertThat(e)
           .hasMessageThat()
-          .isEqualTo("Error calling expansion function for option: badness");
+          .isEqualTo("Error calling expansion function for option '--badness'");
     }
   }
 
@@ -1121,7 +1128,9 @@ public class OptionsParserTest {
   public void overrideExpansionWithExplicit() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(ExpansionOptions.class);
     parser.parse(
-        OptionPriority.COMMAND_LINE, null, Arrays.asList("--expands", "--underlying=direct_value"));
+        OptionPriority.PriorityCategory.COMMAND_LINE,
+        null,
+        Arrays.asList("--expands", "--underlying=direct_value"));
     ExpansionOptions options = parser.getOptions(ExpansionOptions.class);
     assertThat(options.underlying).isEqualTo("direct_value");
     assertThat(parser.getWarnings()).isEmpty();
@@ -1130,7 +1139,7 @@ public class OptionsParserTest {
   @Test
   public void testExpansionOriginIsPropagatedToOption() throws OptionsParsingException {
     OptionsParser parser = OptionsParser.newOptionsParser(ExpansionOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--expands"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--expands"));
     OptionValueDescription expansionDescription = parser.getOptionValueDescription("expands");
     assertThat(expansionDescription).isNotNull();
 
@@ -1150,7 +1159,9 @@ public class OptionsParserTest {
   public void overrideExplicitWithExpansion() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(ExpansionOptions.class);
     parser.parse(
-        OptionPriority.COMMAND_LINE, null, Arrays.asList("--underlying=direct_value", "--expands"));
+        OptionPriority.PriorityCategory.COMMAND_LINE,
+        null,
+        Arrays.asList("--underlying=direct_value", "--expands"));
     ExpansionOptions options = parser.getOptions(ExpansionOptions.class);
     assertThat(options.underlying).isEqualTo("from_expansion");
   }
@@ -1161,7 +1172,7 @@ public class OptionsParserTest {
   public void multipleExpansionOptionsWithValue() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(ExpansionMultipleOptions.class);
     parser.parse(
-        OptionPriority.COMMAND_LINE,
+        OptionPriority.PriorityCategory.COMMAND_LINE,
         null,
         Arrays.asList("--expands_by_function=a", "--expands_by_function=b"));
     ExpansionMultipleOptions options = parser.getOptions(ExpansionMultipleOptions.class);
@@ -1171,18 +1182,18 @@ public class OptionsParserTest {
   @Test
   public void overrideWithHigherPriority() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(NullTestOptions.class);
-    parser.parse(OptionPriority.RC_FILE, null, Arrays.asList("--simple=a"));
+    parser.parse(OptionPriority.PriorityCategory.RC_FILE, null, Arrays.asList("--simple=a"));
     assertThat(parser.getOptions(NullTestOptions.class).simple).isEqualTo("a");
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--simple=b"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--simple=b"));
     assertThat(parser.getOptions(NullTestOptions.class).simple).isEqualTo("b");
   }
 
   @Test
   public void overrideWithLowerPriority() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(NullTestOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--simple=a"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--simple=a"));
     assertThat(parser.getOptions(NullTestOptions.class).simple).isEqualTo("a");
-    parser.parse(OptionPriority.RC_FILE, null, Arrays.asList("--simple=b"));
+    parser.parse(OptionPriority.PriorityCategory.RC_FILE, null, Arrays.asList("--simple=b"));
     assertThat(parser.getOptions(NullTestOptions.class).simple).isEqualTo("a");
   }
 
@@ -1206,7 +1217,9 @@ public class OptionsParserTest {
   @Test
   public void getOptionValueDescriptionWithValue() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(NullTestOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, "my description",
+    parser.parse(
+        OptionPriority.PriorityCategory.COMMAND_LINE,
+        "my description",
         Arrays.asList("--simple=abc"));
     OptionValueDescription result = parser.getOptionValueDescription("simple");
     assertThat(result).isNotNull();
@@ -1218,7 +1231,8 @@ public class OptionsParserTest {
     // specific to a single-valued option.
     SingleOptionValueDescription singleOptionResult = (SingleOptionValueDescription) result;
     ParsedOptionDescription singleOptionInstance = singleOptionResult.getEffectiveOptionInstance();
-    assertThat(singleOptionInstance.getPriority()).isEqualTo(OptionPriority.COMMAND_LINE);
+    assertThat(singleOptionInstance.getPriority().getPriorityCategory())
+        .isEqualTo(OptionPriority.PriorityCategory.COMMAND_LINE);
     assertThat(singleOptionInstance.getOptionDefinition().isExpansionOption()).isFalse();
     assertThat(singleOptionInstance.getImplicitDependent()).isNull();
     assertThat(singleOptionInstance.getExpandedFrom()).isNull();
@@ -1258,7 +1272,7 @@ public class OptionsParserTest {
     parser.parse("--second=second", "--first=first");
     assertThat(parser.getWarnings())
         .containsExactly(
-            "Option 'second' is implicitly defined by option 'first'; the implicitly set value "
+            "option '--second' is implicitly defined by option '--first'; the implicitly set value "
                 + "overrides the previous one");
   }
 
@@ -1270,8 +1284,8 @@ public class OptionsParserTest {
     parser.parse("--second=second");
     assertThat(parser.getWarnings())
         .containsExactly(
-            "A new value for option 'second' overrides a previous implicit setting of that option "
-                + "by option 'first'");
+            "A new value for option '--second' overrides a previous implicit setting of that "
+                + "option by option '--first'");
   }
 
   @Test
@@ -1280,8 +1294,8 @@ public class OptionsParserTest {
     parser.parse("--first=first", "--second=second");
     assertThat(parser.getWarnings())
         .containsExactly(
-            "A new value for option 'second' overrides a previous implicit setting of that "
-                + "option by option 'first'");
+            "A new value for option '--second' overrides a previous implicit setting of that "
+                + "option by option '--first'");
   }
 
   @Test
@@ -1292,13 +1306,15 @@ public class OptionsParserTest {
     parser.parse("--third=third");
     assertThat(parser.getWarnings())
         .containsExactly(
-            "Option 'second' is implicitly defined by both option 'first' and option 'third'");
+            "option '--second' is implicitly defined by both option '--first' and "
+                + "option '--third'");
   }
 
   @Test
   public void tesDependentOriginIsPropagatedToOption() throws OptionsParsingException {
     OptionsParser parser = OptionsParser.newOptionsParser(ImplicitDependencyWarningOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--first=first"));
+    parser.parse(
+        OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--first=first"));
     OptionValueDescription originalOption = parser.getOptionValueDescription("first");
     assertThat(originalOption).isNotNull();
 
@@ -1357,21 +1373,21 @@ public class OptionsParserTest {
   @Test
   public void deprecationWarning() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(WarningOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--first"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--first"));
     assertThat(parser.getWarnings()).isEqualTo(Arrays.asList("Option 'first' is deprecated"));
   }
 
   @Test
   public void deprecationWarningForListOption() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(WarningOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--second=a"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--second=a"));
     assertThat(parser.getWarnings()).isEqualTo(Arrays.asList("Option 'second' is deprecated"));
   }
 
   @Test
   public void deprecationWarningForExpansionOption() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(WarningOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--third"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--third"));
     assertThat(parser.getWarnings()).isEqualTo(Arrays.asList("Option 'third' is deprecated"));
     assertThat(parser.getOptions(WarningOptions.class).fourth).isTrue();
   }
@@ -1379,7 +1395,7 @@ public class OptionsParserTest {
   @Test
   public void deprecationWarningForAbbreviatedExpansionOption() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(WarningOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("-t"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("-t"));
     assertThat(parser.getWarnings()).isEqualTo(Arrays.asList("Option 'third' is deprecated"));
     assertThat(parser.getOptions(WarningOptions.class).fourth).isTrue();
   }
@@ -1426,7 +1442,7 @@ public class OptionsParserTest {
   @Test
   public void newDeprecationWarning() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(NewWarningOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--first"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--first"));
     assertThat(parser.getWarnings())
         .isEqualTo(Arrays.asList("Option 'first' is deprecated: it's gone"));
   }
@@ -1434,7 +1450,7 @@ public class OptionsParserTest {
   @Test
   public void newDeprecationWarningForListOption() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(NewWarningOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--second=a"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--second=a"));
     assertThat(parser.getWarnings())
         .isEqualTo(Arrays.asList("Option 'second' is deprecated: sorry, no replacement"));
   }
@@ -1442,7 +1458,7 @@ public class OptionsParserTest {
   @Test
   public void newDeprecationWarningForExpansionOption() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(NewWarningOptions.class);
-    parser.parse(OptionPriority.COMMAND_LINE, null, Arrays.asList("--third"));
+    parser.parse(OptionPriority.PriorityCategory.COMMAND_LINE, null, Arrays.asList("--third"));
     assertThat(parser.getWarnings())
         .isEqualTo(Arrays.asList("Option 'third' is deprecated: use --forth instead"));
     assertThat(parser.getOptions(NewWarningOptions.class).fourth).isTrue();
@@ -1482,16 +1498,18 @@ public class OptionsParserTest {
     parser.parse("--underlying=underlying", "--first");
     assertThat(parser.getWarnings())
         .containsExactly(
-            "The option 'first' was expanded and now overrides a previous explicitly specified "
-                + "option 'underlying'");
+            "option '--first' was expanded and now overrides a previous explicitly specified "
+                + "option '--underlying'");
   }
 
   @Test
   public void warningForTwoConflictingExpansionOptions() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(ExpansionWarningOptions.class);
     parser.parse("--first", "--second");
-    assertThat(parser.getWarnings()).containsExactly(
-        "The option 'underlying' was expanded to from both options 'first' " + "and 'second'");
+    assertThat(parser.getWarnings())
+        .containsExactly(
+            "option '--underlying' was expanded to from both option '--first' and option "
+                + "'--second'");
   }
 
   // This test is here to make sure that nobody accidentally changes the
@@ -1499,12 +1517,17 @@ public class OptionsParserTest {
   // in the code.
   @Test
   public void optionPrioritiesAreCorrectlyOrdered() throws Exception {
-    assertThat(OptionPriority.values()).hasLength(6);
-    assertThat(OptionPriority.DEFAULT).isLessThan(OptionPriority.COMPUTED_DEFAULT);
-    assertThat(OptionPriority.COMPUTED_DEFAULT).isLessThan(OptionPriority.RC_FILE);
-    assertThat(OptionPriority.RC_FILE).isLessThan(OptionPriority.COMMAND_LINE);
-    assertThat(OptionPriority.COMMAND_LINE).isLessThan(OptionPriority.INVOCATION_POLICY);
-    assertThat(OptionPriority.INVOCATION_POLICY).isLessThan(OptionPriority.SOFTWARE_REQUIREMENT);
+    assertThat(OptionPriority.PriorityCategory.values()).hasLength(6);
+    assertThat(OptionPriority.PriorityCategory.DEFAULT)
+        .isLessThan(OptionPriority.PriorityCategory.COMPUTED_DEFAULT);
+    assertThat(OptionPriority.PriorityCategory.COMPUTED_DEFAULT)
+        .isLessThan(OptionPriority.PriorityCategory.RC_FILE);
+    assertThat(OptionPriority.PriorityCategory.RC_FILE)
+        .isLessThan(OptionPriority.PriorityCategory.COMMAND_LINE);
+    assertThat(OptionPriority.PriorityCategory.COMMAND_LINE)
+        .isLessThan(OptionPriority.PriorityCategory.INVOCATION_POLICY);
+    assertThat(OptionPriority.PriorityCategory.INVOCATION_POLICY)
+        .isLessThan(OptionPriority.PriorityCategory.SOFTWARE_REQUIREMENT);
   }
 
   public static class IntrospectionExample extends OptionsBase {
@@ -1555,7 +1578,9 @@ public class OptionsParserTest {
   @Test
   public void asListOfUnparsedOptions() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(IntrospectionExample.class);
-    parser.parse(OptionPriority.COMMAND_LINE, "source",
+    parser.parse(
+        OptionPriority.PriorityCategory.COMMAND_LINE,
+        "source",
         Arrays.asList("--alpha=one", "--gamma=two", "--echo=three"));
     List<ParsedOptionDescription> result = parser.asCompleteListOfParsedOptions();
     assertThat(result).isNotNull();
@@ -1566,27 +1591,32 @@ public class OptionsParserTest {
     assertThat(result.get(0).isHidden()).isFalse();
     assertThat(result.get(0).getUnconvertedValue()).isEqualTo("one");
     assertThat(result.get(0).getSource()).isEqualTo("source");
-    assertThat(result.get(0).getPriority()).isEqualTo(OptionPriority.COMMAND_LINE);
+    assertThat(result.get(0).getPriority().getPriorityCategory())
+        .isEqualTo(OptionPriority.PriorityCategory.COMMAND_LINE);
 
     assertThat(result.get(1).getOptionDefinition().getOptionName()).isEqualTo("gamma");
     assertThat(result.get(1).isDocumented()).isFalse();
     assertThat(result.get(1).isHidden()).isFalse();
     assertThat(result.get(1).getUnconvertedValue()).isEqualTo("two");
     assertThat(result.get(1).getSource()).isEqualTo("source");
-    assertThat(result.get(1).getPriority()).isEqualTo(OptionPriority.COMMAND_LINE);
+    assertThat(result.get(1).getPriority().getPriorityCategory())
+        .isEqualTo(OptionPriority.PriorityCategory.COMMAND_LINE);
 
     assertThat(result.get(2).getOptionDefinition().getOptionName()).isEqualTo("echo");
     assertThat(result.get(2).isDocumented()).isFalse();
     assertThat(result.get(2).isHidden()).isTrue();
     assertThat(result.get(2).getUnconvertedValue()).isEqualTo("three");
     assertThat(result.get(2).getSource()).isEqualTo("source");
-    assertThat(result.get(2).getPriority()).isEqualTo(OptionPriority.COMMAND_LINE);
+    assertThat(result.get(2).getPriority().getPriorityCategory())
+        .isEqualTo(OptionPriority.PriorityCategory.COMMAND_LINE);
   }
 
   @Test
   public void asListOfExplicitOptions() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(IntrospectionExample.class);
-    parser.parse(OptionPriority.COMMAND_LINE, "source",
+    parser.parse(
+        OptionPriority.PriorityCategory.COMMAND_LINE,
+        "source",
         Arrays.asList("--alpha=one", "--gamma=two"));
     List<ParsedOptionDescription> result = parser.asListOfExplicitOptions();
     assertThat(result).isNotNull();
@@ -1596,13 +1626,15 @@ public class OptionsParserTest {
     assertThat(result.get(0).isDocumented()).isTrue();
     assertThat(result.get(0).getUnconvertedValue()).isEqualTo("one");
     assertThat(result.get(0).getSource()).isEqualTo("source");
-    assertThat(result.get(0).getPriority()).isEqualTo(OptionPriority.COMMAND_LINE);
+    assertThat(result.get(0).getPriority().getPriorityCategory())
+        .isEqualTo(OptionPriority.PriorityCategory.COMMAND_LINE);
 
     assertThat(result.get(1).getOptionDefinition().getOptionName()).isEqualTo("gamma");
     assertThat(result.get(1).isDocumented()).isFalse();
     assertThat(result.get(1).getUnconvertedValue()).isEqualTo("two");
     assertThat(result.get(1).getSource()).isEqualTo("source");
-    assertThat(result.get(1).getPriority()).isEqualTo(OptionPriority.COMMAND_LINE);
+    assertThat(result.get(1).getPriority().getPriorityCategory())
+        .isEqualTo(OptionPriority.PriorityCategory.COMMAND_LINE);
   }
 
   private void assertOptionValue(
@@ -1615,18 +1647,21 @@ public class OptionsParserTest {
   private void assertOptionValue(
       String expectedName,
       Object expectedValue,
-      OptionPriority expectedPriority,
+      OptionPriority.PriorityCategory expectedPriority,
       String expectedSource,
       SingleOptionValueDescription actual) {
     assertOptionValue(expectedName, expectedValue, actual);
     assertThat(actual.getSourceString()).isEqualTo(expectedSource);
-    assertThat(actual.getEffectiveOptionInstance().getPriority()).isEqualTo(expectedPriority);
+    assertThat(actual.getEffectiveOptionInstance().getPriority().getPriorityCategory())
+        .isEqualTo(expectedPriority);
   }
 
   @Test
   public void asListOfEffectiveOptions() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(IntrospectionExample.class);
-    parser.parse(OptionPriority.COMMAND_LINE, "command line source",
+    parser.parse(
+        OptionPriority.PriorityCategory.COMMAND_LINE,
+        "command line source",
         Arrays.asList("--alpha=alphaValueSetOnCommandLine", "--gamma=gammaValueSetOnCommandLine"));
     List<OptionValueDescription> result = parser.asListOfEffectiveOptions();
     assertThat(result).isNotNull();
@@ -1641,13 +1676,13 @@ public class OptionsParserTest {
     assertOptionValue(
         "alpha",
         "alphaValueSetOnCommandLine",
-        OptionPriority.COMMAND_LINE,
+        OptionPriority.PriorityCategory.COMMAND_LINE,
         "command line source",
         (SingleOptionValueDescription) map.get("alpha"));
     assertOptionValue(
         "gamma",
         "gammaValueSetOnCommandLine",
-        OptionPriority.COMMAND_LINE,
+        OptionPriority.PriorityCategory.COMMAND_LINE,
         "command line source",
         (SingleOptionValueDescription) map.get("gamma"));
     assertOptionValue("beta", "betaDefaultValue", map.get("beta"));
@@ -1672,9 +1707,14 @@ public class OptionsParserTest {
   @Test
   public void overrideListOptions() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(ListExample.class);
-    parser.parse(OptionPriority.COMMAND_LINE, "command line source", Arrays.asList("--alpha=cli"));
     parser.parse(
-        OptionPriority.RC_FILE, "rc file origin", Arrays.asList("--alpha=rc1", "--alpha=rc2"));
+        OptionPriority.PriorityCategory.COMMAND_LINE,
+        "command line source",
+        Arrays.asList("--alpha=cli"));
+    parser.parse(
+        OptionPriority.PriorityCategory.RC_FILE,
+        "rc file origin",
+        Arrays.asList("--alpha=rc1", "--alpha=rc2"));
     assertThat(parser.getOptions(ListExample.class).alpha)
         .isEqualTo(Arrays.asList("rc1", "rc2", "cli"));
   }
@@ -1682,18 +1722,33 @@ public class OptionsParserTest {
   @Test
   public void listOptionsHaveCorrectPriorities() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(ListExample.class);
-    parser.parse(OptionPriority.COMMAND_LINE, "command line source", Arrays.asList("--alpha=cli"));
     parser.parse(
-        OptionPriority.RC_FILE, "rc file origin", Arrays.asList("--alpha=rc1", "--alpha=rc2"));
+        OptionPriority.PriorityCategory.COMMAND_LINE,
+        "command line source",
+        Arrays.asList("--alpha=cli"));
+    parser.parse(
+        OptionPriority.PriorityCategory.RC_FILE,
+        "rc file origin",
+        Arrays.asList("--alpha=rc1", "--alpha=rc2"));
 
     OptionValueDescription alphaValue = parser.getOptionValueDescription("alpha");
     assertThat(alphaValue).isInstanceOf(RepeatableOptionValueDescription.class);
 
+    // Rearrange the parsed options so we can group them by PriorityCategory.
     RepeatableOptionValueDescription alpha = (RepeatableOptionValueDescription) alphaValue;
-    assertThat(alpha.parsedOptions).containsKey(OptionPriority.RC_FILE);
-    assertThat(alpha.parsedOptions).containsKey(OptionPriority.COMMAND_LINE);
-    List<ParsedOptionDescription> rcOptions = alpha.parsedOptions.get(OptionPriority.RC_FILE);
-    List<ParsedOptionDescription> cliOptions = alpha.parsedOptions.get(OptionPriority.COMMAND_LINE);
+
+    ListMultimap<PriorityCategory, ParsedOptionDescription> parsedOptions =
+        ArrayListMultimap.create();
+    for (Entry<OptionPriority, Collection<ParsedOptionDescription>> entry :
+        alpha.parsedOptions.asMap().entrySet()) {
+      parsedOptions.putAll(entry.getKey().getPriorityCategory(), entry.getValue());
+    }
+    assertThat(parsedOptions).containsKey(OptionPriority.PriorityCategory.RC_FILE);
+    assertThat(parsedOptions).containsKey(OptionPriority.PriorityCategory.COMMAND_LINE);
+    List<ParsedOptionDescription> rcOptions =
+        parsedOptions.get(OptionPriority.PriorityCategory.RC_FILE);
+    List<ParsedOptionDescription> cliOptions =
+        parsedOptions.get(OptionPriority.PriorityCategory.COMMAND_LINE);
 
     assertThat(rcOptions).hasSize(2);
     assertThat(rcOptions.get(0).getSource()).matches("rc file origin");
@@ -1721,10 +1776,13 @@ public class OptionsParserTest {
   public void commaSeparatedOptionsWithAllowMultiple() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(CommaSeparatedOptionsExample.class);
     parser.parse(
-        OptionPriority.COMMAND_LINE,
+        OptionPriority.PriorityCategory.COMMAND_LINE,
         "command line source",
         Arrays.asList("--alpha=one", "--alpha=two,three"));
-    parser.parse(OptionPriority.RC_FILE, "rc file origin", Arrays.asList("--alpha=rc1,rc2"));
+    parser.parse(
+        OptionPriority.PriorityCategory.RC_FILE,
+        "rc file origin",
+        Arrays.asList("--alpha=rc1,rc2"));
     assertThat(parser.getOptions(CommaSeparatedOptionsExample.class).alpha)
         .isEqualTo(Arrays.asList("rc1", "rc2", "one", "two", "three"));
   }
@@ -1733,19 +1791,32 @@ public class OptionsParserTest {
   public void commaSeparatedListOptionsHaveCorrectPriorities() throws Exception {
     OptionsParser parser = OptionsParser.newOptionsParser(CommaSeparatedOptionsExample.class);
     parser.parse(
-        OptionPriority.COMMAND_LINE,
+        OptionPriority.PriorityCategory.COMMAND_LINE,
         "command line source",
         Arrays.asList("--alpha=one", "--alpha=two,three"));
-    parser.parse(OptionPriority.RC_FILE, "rc file origin", Arrays.asList("--alpha=rc1,rc2,rc3"));
+    parser.parse(
+        OptionPriority.PriorityCategory.RC_FILE,
+        "rc file origin",
+        Arrays.asList("--alpha=rc1,rc2,rc3"));
 
     OptionValueDescription alphaValue = parser.getOptionValueDescription("alpha");
     assertThat(alphaValue).isInstanceOf(RepeatableOptionValueDescription.class);
 
+    // Rearrange the parsed options so we can group them by PriorityCategory.
     RepeatableOptionValueDescription alpha = (RepeatableOptionValueDescription) alphaValue;
-    assertThat(alpha.parsedOptions).containsKey(OptionPriority.RC_FILE);
-    assertThat(alpha.parsedOptions).containsKey(OptionPriority.COMMAND_LINE);
-    List<ParsedOptionDescription> rcOptions = alpha.parsedOptions.get(OptionPriority.RC_FILE);
-    List<ParsedOptionDescription> cliOptions = alpha.parsedOptions.get(OptionPriority.COMMAND_LINE);
+    ListMultimap<PriorityCategory, ParsedOptionDescription> parsedOptions =
+        ArrayListMultimap.create();
+    for (Entry<OptionPriority, Collection<ParsedOptionDescription>> entry :
+        alpha.parsedOptions.asMap().entrySet()) {
+      parsedOptions.putAll(entry.getKey().getPriorityCategory(), entry.getValue());
+    }
+
+    assertThat(parsedOptions).containsKey(OptionPriority.PriorityCategory.RC_FILE);
+    assertThat(parsedOptions).containsKey(OptionPriority.PriorityCategory.COMMAND_LINE);
+    List<ParsedOptionDescription> rcOptions =
+        parsedOptions.get(OptionPriority.PriorityCategory.RC_FILE);
+    List<ParsedOptionDescription> cliOptions =
+        parsedOptions.get(OptionPriority.PriorityCategory.COMMAND_LINE);
 
     assertThat(rcOptions).hasSize(1);
     assertThat(rcOptions.get(0).getSource()).matches("rc file origin");
diff --git a/src/test/shell/integration/incompatible_changes_conflict_test.sh b/src/test/shell/integration/incompatible_changes_conflict_test.sh
index 0b0ed5081f..af3bad3b85 100755
--- a/src/test/shell/integration/incompatible_changes_conflict_test.sh
+++ b/src/test/shell/integration/incompatible_changes_conflict_test.sh
@@ -26,9 +26,9 @@ source "${CURRENT_DIR}/../integration_test_setup.sh" \
 
 # The clash canary flags are built into the canonicalize-flags command
 # specifically for this test suite.
-canary_clash_error="The option 'flag_clash_canary' was expanded to from both "
-canary_clash_error+="options 'flag_clash_canary_expander1' and "
-canary_clash_error+="'flag_clash_canary_expander2'."
+canary_clash_error="option '--flag_clash_canary' was expanded to from both "
+canary_clash_error+="option '--flag_clash_canary_expander1' and "
+canary_clash_error+="option '--flag_clash_canary_expander2'."
 
 # Ensures that we didn't change the formatting of the warning message or
 # disable the warning.
@@ -53,8 +53,8 @@ function test_canonicalize_flags_suppresses_warnings() {
 function test_no_conflicts_among_incompatible_changes() {
   bazel canonicalize-flags --show_warnings -- --all_incompatible_changes \
     &>$TEST_log || fail "bazel canonicalize-flags failed";
-  expected="The option '.*' was expanded to from both options "
-  expected+="'.*' and '.*'."
+  expected="The option '.*' was expanded to from both option "
+  expected+="'.*' and option '.*'."
   fail_msg="Options conflict in expansion of --all_incompatible_changes"
   expect_not_log "$expected" "$fail_msg"
 }