implement diagnostic deduplication

Author: mcy

experimental/incremental/executor.go

@@ -164,7 +164,7 @@ func Run[T any](ctx context.Context, e *Executor, queries ...Query[T]) ([]Result
 			record(dep)
 		}
 	}
-	report.Sort()
+	report.Canonicalize()
 
 	return results, report, nil
 }

experimental/parser/parse_test.go

@@ -45,7 +45,7 @@ func TestParse(t *testing.T) {
 		errs := &report.Report{Options: report.Options{Tracing: 10}}
 		file, _ := Parse(report.NewFile(path, text), errs)
 
-		errs.Sort()
+		errs.Canonicalize()
 		stderr, _, _ := report.Renderer{
 			Colorize:  true,
 			ShowDebug: true,

experimental/report/report.go

@@ -23,6 +23,8 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
+	"github.com/bufbuild/protocompile/internal/ext/cmpx"
+	"github.com/bufbuild/protocompile/internal/ext/slicesx"
 	compilerpb "github.com/bufbuild/protocompile/internal/gen/buf/compiler/v1alpha1"
 )
 
@@ -54,6 +56,10 @@ type Options struct {
 	// Higher values mean more debugging information. What debugging information
 	// is actually provided is subject to change.
 	Tracing int
+
+	// If set, [Report.Sort] will not discard duplicate diagnostics, as defined
+	// in that function's contract.
+	KeepDuplicates bool
 }
 
 // Diagnose is a type that can be rendered as a diagnostic.
@@ -141,41 +147,63 @@ func (r *Report) CatchICE(resume bool, diagnose func(*Diagnostic)) {
 	}
 }
 
-// Sort canonicalizes this report's diagnostic order according to an specific
-// ordering criteria. Diagnostics are sorted by, in order;
+// Canonicalize sorts this report's diagnostics according to an specific
+// ordering criteria. Diagnostics are sorted by, in order:
 //
-// File name of primary span, SortOrder value, start offset of primary snippet,
-// end offset of primary snippet, content of error message.
+// 1. File name of primary span.
+// 2. SortOrder value.
+// 3. Start offset of primary snippet.
+// 4. End offset of primary snippet.
+// 5. Diagnostic tag.
+// 6. Textual content of error message.
 //
 // Where diagnostics have no primary span, the file is treated as empty and the
 // offsets are treated as zero.
 //
 // These criteria ensure that diagnostics for the same file go together,
 // diagnostics for the same sort order (lex, parse, etc) go together, and they
 // are otherwise ordered by where they occur in the file.
-func (r *Report) Sort() {
-	slices.SortFunc(r.Diagnostics, func(a, b Diagnostic) int {
-		aPrime := a.Primary()
-		bPrime := b.Primary()
-
-		if diff := strings.Compare(aPrime.Path(), bPrime.Path()); diff != 0 {
-			return diff
-		}
-
-		if diff := a.sortOrder - b.sortOrder; diff != 0 {
-			return diff
-		}
+//
+// Canonicalize will deduplicate diagnostics whose primary span and (nonempty)
+// diagnostic tags are equal, selecting the diagnostic that sorts as greatest
+// as the canonical value. This allows later diagnostics to replace earlier
+// diagnostics, so long as they cooperate by using the same tag. Deduplication
+// can be suppressed using [Options].KeepDuplicates.
+func (r *Report) Canonicalize() {
+	slices.SortFunc(r.Diagnostics, cmpx.Join(
+		cmpx.Key(func(d Diagnostic) string { return d.Primary().Path() }),
+		cmpx.Key(func(d Diagnostic) int { return d.sortOrder }),
+		cmpx.Key(func(d Diagnostic) int { return d.Primary().Start }),
+		cmpx.Key(func(d Diagnostic) int { return d.Primary().End }),
+		cmpx.Key(func(d Diagnostic) string { return d.tag }),
+		cmpx.Key(func(d Diagnostic) string { return d.message }),
+	))
+
+	if r.KeepDuplicates {
+		return
+	}
 
-		if diff := aPrime.Start - bPrime.Start; diff != 0 {
-			return diff
+	type key struct {
+		span Span
+		tag  string
+	}
+	var cur key
+	slicesx.Backward(r.Diagnostics)(func(i int, d Diagnostic) bool {
+		if d.tag == "" {
+			return true
 		}
 
-		if diff := aPrime.End - bPrime.End; diff != 0 {
-			return diff
+		key := key{d.Primary().Span(), d.tag}
+		if cur.tag != "" && cur == key {
+			r.Diagnostics[i].level = -1 // Use this to mark which diagnostics to delete.
+		} else {
+			cur = key
 		}
 
-		return strings.Compare(a.message, b.message)
+		return true
 	})
+
+	r.Diagnostics = slices.DeleteFunc(r.Diagnostics, func(d Diagnostic) bool { return d.level == -1 })
 }
 
 // ToProto converts this report into a Protobuf message for serialization.

internal/ext/cmpx/cmpx.go

@@ -0,0 +1,52 @@
+// Copyright 2020-2025 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// package cmpx contains extensions to Go's package cmp.
+package cmpx
+
+import "cmp"
+
+// Result is the type returned by an [Ordering], and in particular
+// [cmp.Compare].
+type Result = int
+
+const (
+	// [cmp.Compare] guarantees these return values.
+	Less    Result = -1
+	Equal   Result = 0
+	Greater Result = 1
+)
+
+// Ordering is an ordering for the type T, which is any function with the same
+// signature as [Compare].
+type Ordering[T any] func(T, T) Result
+
+// Key returns an ordering for T according to a key function, which must return
+// a [cmp.Ordered] value.
+func Key[T any, U cmp.Ordered](key func(T) U) Ordering[T] {
+	return func(a, b T) Result { return cmp.Compare(key(a), key(b)) }
+}
+
+// Join returns an ordering for T which returns the first of cmps returns a
+// non-[Equal] value.
+func Join[T any](cmps ...Ordering[T]) Ordering[T] {
+	return func(a, b T) Result {
+		for _, cmp := range cmps {
+			if n := cmp(a, b); n != Equal {
+				return n
+			}
+		}
+		return Equal
+	}
+}

internal/ext/slicesx/iter.go

@@ -119,3 +119,14 @@ func Values[S ~[]E, E any](s S) iter.Seq[E] {
 		}
 	}
 }
+
+// Backward is a polyfill for [slices.Backward].
+func Backward[S ~[]E, E any](s S) iter.Seq2[int, E] {
+	return func(yield func(int, E) bool) {
+		for i := len(s) - 1; i > 0; i-- {
+			if !yield(i, s[i]) {
+				return
+			}
+		}
+	}
+}