Add a way for diagnostics to sort on more than last_byte_offset. (#6687)

The intent is that `last_byte_offset` is still the main sorting key.
Diagnostics issued normally (e.g. in an expression) will keep sorting
the same, and come before the new diagnostic sort. Diagnostics issued at
the end of a scope (e.g. `unused`) can request sorting by their start
location, and would become interleaved through that.

Choosing "on scope" because I think that's the main way we'll use this
functionality (on scope changes); can always rename later if usage
expands.

Assisted-by: Google Antigravity with Gemini 3 Flash

toolchain/diagnostics/sorting_consumer_test.cpp

@@ -16,47 +16,127 @@ namespace {
 
 using ::Carbon::Testing::IsSingleDiagnostic;
 using ::testing::_;
-using ::testing::InSequence;
+using ::testing::ElementsAreArray;
 
-CARBON_DIAGNOSTIC(TestDiagnostic, Error, "M{0}", int);
+CARBON_DIAGNOSTIC(TestDiagnostic, Error, "Diag{0}", int);
+CARBON_DIAGNOSTIC_ON_SCOPE(TestDiagnosticOnScope, Error, "DiagOnScope{0}", int);
 
-class FakeEmitter : public Emitter<int32_t> {
+// Sorting-related locations, consumed by `FakeEmitter::ConvertLoc`.
+struct TestLoc {
+  int32_t last_byte_offset;
+  int32_t line_number;
+  int32_t column_number;
+};
+
+// Emits a diagnostic with the requested location.
+class FakeEmitter : public Emitter<TestLoc> {
  public:
   using Emitter::Emitter;
 
  protected:
-  auto ConvertLoc(int32_t last_byte_offset, ContextFnT /*context_fn*/) const
+  auto ConvertLoc(TestLoc test_loc, ContextFnT /*context_fn*/) const
       -> ConvertedLoc override {
-    return {.loc = {}, .last_byte_offset = last_byte_offset};
+    return {.loc = {.line_number = test_loc.line_number,
+                    .column_number = test_loc.column_number},
+            .last_byte_offset = test_loc.last_byte_offset};
   }
 };
 
+// Stores diagnostics in a vector for `ElementsArray` matching.
+class VectorConsumer : public Consumer {
+ public:
+  auto HandleDiagnostic(Diagnostic diagnostic) -> void override {
+    diagnostics_.push_back(std::move(diagnostic));
+  }
+
+  auto Flush() -> void override {}
+
+  auto diagnostics() const -> llvm::ArrayRef<Diagnostic> {
+    return diagnostics_;
+  }
+
+ private:
+  llvm::SmallVector<Diagnostic> diagnostics_;
+};
+
 TEST(SortedEmitterTest, SortErrors) {
-  Testing::MockDiagnosticConsumer consumer;
+  VectorConsumer consumer;
   SortingConsumer sorting_consumer(consumer);
   FakeEmitter emitter(&sorting_consumer);
 
-  emitter.Emit(1, TestDiagnostic, 1);
-  emitter.Emit(-1, TestDiagnostic, 2);
-  emitter.Emit(0, TestDiagnostic, 3);
-  emitter.Emit(4, TestDiagnostic, 4);
-  emitter.Emit(3, TestDiagnostic, 5);
-  emitter.Emit(3, TestDiagnostic, 6);
+  emitter.Emit({1, 10, 1}, TestDiagnostic, 1);
+  emitter.Emit({-1, 11, 1}, TestDiagnostic, 2);
+  emitter.Emit({0, 12, 1}, TestDiagnostic, 3);
+  emitter.Emit({4, 13, 1}, TestDiagnostic, 4);
+  emitter.Emit({3, 14, 1}, TestDiagnostic, 5);
+  emitter.Emit({3, 15, 1}, TestDiagnostic, 6);
 
-  InSequence s;
-  EXPECT_CALL(consumer, HandleDiagnostic(IsSingleDiagnostic(
-                            Kind::TestDiagnostic, Level::Error, _, _, "M2")));
-  EXPECT_CALL(consumer, HandleDiagnostic(IsSingleDiagnostic(
-                            Kind::TestDiagnostic, Level::Error, _, _, "M3")));
-  EXPECT_CALL(consumer, HandleDiagnostic(IsSingleDiagnostic(
-                            Kind::TestDiagnostic, Level::Error, _, _, "M1")));
-  EXPECT_CALL(consumer, HandleDiagnostic(IsSingleDiagnostic(
-                            Kind::TestDiagnostic, Level::Error, _, _, "M5")));
-  EXPECT_CALL(consumer, HandleDiagnostic(IsSingleDiagnostic(
-                            Kind::TestDiagnostic, Level::Error, _, _, "M6")));
-  EXPECT_CALL(consumer, HandleDiagnostic(IsSingleDiagnostic(
-                            Kind::TestDiagnostic, Level::Error, _, _, "M4")));
+  EXPECT_TRUE(consumer.diagnostics().empty());
   sorting_consumer.Flush();
+  EXPECT_THAT(
+      consumer.diagnostics(),
+      ElementsAreArray({
+          IsSingleDiagnostic(Kind::TestDiagnostic, Level::Error, _, _, "Diag2"),
+          IsSingleDiagnostic(Kind::TestDiagnostic, Level::Error, _, _, "Diag3"),
+          IsSingleDiagnostic(Kind::TestDiagnostic, Level::Error, _, _, "Diag1"),
+          IsSingleDiagnostic(Kind::TestDiagnostic, Level::Error, _, _, "Diag5"),
+          IsSingleDiagnostic(Kind::TestDiagnostic, Level::Error, _, _, "Diag6"),
+          IsSingleDiagnostic(Kind::TestDiagnostic, Level::Error, _, _, "Diag4"),
+      }));
+}
+
+TEST(SortedEmitterTest, SortOnScope) {
+  VectorConsumer consumer;
+  SortingConsumer sorting_consumer(consumer);
+  FakeEmitter emitter(&sorting_consumer);
+
+  emitter.Emit({2, 15, 1}, TestDiagnosticOnScope, 1);
+  emitter.Emit({4, 1, 1}, TestDiagnosticOnScope, 2);
+  // Same `last_byte_offset`, should sort by line/column.
+  emitter.Emit({3, 10, 5}, TestDiagnosticOnScope, 3);
+  emitter.Emit({3, 10, 1}, TestDiagnosticOnScope, 4);
+  emitter.Emit({3, 5, 20}, TestDiagnosticOnScope, 5);
+  emitter.Emit({3, 10, 3}, TestDiagnosticOnScope, 6);
+
+  EXPECT_TRUE(consumer.diagnostics().empty());
+  sorting_consumer.Flush();
+
+  EXPECT_THAT(consumer.diagnostics(),
+              ElementsAreArray({
+                  IsSingleDiagnostic(Kind::TestDiagnosticOnScope, Level::Error,
+                                     _, _, "DiagOnScope1"),
+                  IsSingleDiagnostic(Kind::TestDiagnosticOnScope, Level::Error,
+                                     _, _, "DiagOnScope5"),
+                  IsSingleDiagnostic(Kind::TestDiagnosticOnScope, Level::Error,
+                                     _, _, "DiagOnScope4"),
+                  IsSingleDiagnostic(Kind::TestDiagnosticOnScope, Level::Error,
+                                     _, _, "DiagOnScope6"),
+                  IsSingleDiagnostic(Kind::TestDiagnosticOnScope, Level::Error,
+                                     _, _, "DiagOnScope3"),
+                  IsSingleDiagnostic(Kind::TestDiagnosticOnScope, Level::Error,
+                                     _, _, "DiagOnScope2"),
+              }));
+}
+
+TEST(SortedEmitterTest, MixedScope) {
+  VectorConsumer consumer;
+  SortingConsumer sorting_consumer(consumer);
+  FakeEmitter emitter(&sorting_consumer);
+
+  // Difference in on-scope means only `last_byte_offset` is used.
+  emitter.Emit({3, 3, 1}, TestDiagnosticOnScope, 1);
+  emitter.Emit({3, 10, 1}, TestDiagnostic, 2);
+
+  EXPECT_TRUE(consumer.diagnostics().empty());
+  sorting_consumer.Flush();
+
+  EXPECT_THAT(
+      consumer.diagnostics(),
+      ElementsAreArray({
+          IsSingleDiagnostic(Kind::TestDiagnostic, Level::Error, _, _, "Diag2"),
+          IsSingleDiagnostic(Kind::TestDiagnosticOnScope, Level::Error, _, _,
+                             "DiagOnScope1"),
+      }));
 }
 
 }  // namespace