feat(conflict): file-overlap analyzer using changeset resolver

Add submitqueue/extension/conflict/fileoverlap, a conflict.Analyzer that flags two batches as conflicting when they change a common file. It is the first analyzer to use the capability the extension contract unblocks: it takes only batch identity and resolves each batch's changed files itself through an injected changeset.Resolver, derived from each change's provider details.

A shared file is the concrete notion of target overlap, so it reports the existing conflict.ConflictTypeTargetOverlap — the type the contract named but for which no implementation could be written against an identity-only batch. No change to the conflict.Analyzer interface. The example wires a file-overlap-queue to it.

Author: behinddwalls

example/submitqueue/orchestrator/server/BUILD.bazel

@@ -30,6 +30,7 @@ go_library(
         "//submitqueue/extension/conflict",
         "//submitqueue/extension/conflict/all",
         "//submitqueue/extension/conflict/fake",
+        "//submitqueue/extension/conflict/fileoverlap",
         "//submitqueue/extension/conflict/none",
         "//submitqueue/extension/mergechecker",
         "//submitqueue/extension/mergechecker/fake",

example/submitqueue/orchestrator/server/main.go

@@ -49,6 +49,7 @@ import (
 	"github.com/uber/submitqueue/submitqueue/extension/conflict"
 	"github.com/uber/submitqueue/submitqueue/extension/conflict/all"
 	conflictfake "github.com/uber/submitqueue/submitqueue/extension/conflict/fake"
+	"github.com/uber/submitqueue/submitqueue/extension/conflict/fileoverlap"
 	"github.com/uber/submitqueue/submitqueue/extension/conflict/none"
 	"github.com/uber/submitqueue/submitqueue/extension/mergechecker"
 	mcfake "github.com/uber/submitqueue/submitqueue/extension/mergechecker/fake"
@@ -875,12 +876,18 @@ func newQueueRegistry(logger *zap.Logger, scope tally.Scope, resolver changeset.
 	conflictErrQueue := base
 	conflictErrQueue.analyzer = conflictfake.New(all.New(), conflictfake.FailAlways)
 
+	// file-overlap-queue: a real analyzer that serializes only batches sharing
+	// a changed file, resolving each batch's files itself via the resolver.
+	fileOverlapQueue := base
+	fileOverlapQueue.analyzer = fileoverlap.New(resolver)
+
 	return queueRegistry{
 		def: base,
 		byQueue: map[string]queueExtensions{
 			"test-queue":               testQueue,
 			"e2e-test-queue":           e2eQueue,
 			"e2e-conflict-error-queue": conflictErrQueue,
+			"file-overlap-queue":       fileOverlapQueue,
 		},
 	}, nil
 }

submitqueue/extension/conflict/fileoverlap/BUILD.bazel

@@ -0,0 +1,26 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "fileoverlap",
+    srcs = ["fileoverlap.go"],
+    importpath = "github.com/uber/submitqueue/submitqueue/extension/conflict/fileoverlap",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//submitqueue/core/changeset",
+        "//submitqueue/entity",
+        "//submitqueue/extension/conflict",
+    ],
+)
+
+go_test(
+    name = "fileoverlap_test",
+    srcs = ["fileoverlap_test.go"],
+    embed = [":fileoverlap"],
+    deps = [
+        "//submitqueue/core/changeset/fake",
+        "//submitqueue/entity",
+        "//submitqueue/extension/conflict",
+        "@com_github_stretchr_testify//assert",
+        "@com_github_stretchr_testify//require",
+    ],
+)

submitqueue/extension/conflict/fileoverlap/README.md

@@ -0,0 +1,11 @@
+# fileoverlap
+
+`fileoverlap` is a `conflict.Analyzer` that reports a conflict between two batches when they change one or more of the same files.
+
+It is the first analyzer to exercise the capability the [extension contract](../../../../doc/rfc/submitqueue/extension-contract.md) unblocks: it is handed only batch identity (the candidate batch and the in-flight batches) and resolves each batch's changed files itself through an injected `changeset.Resolver`, rather than depending on a controller to pre-compute them. This is why the `conflict.Analyzer` contract takes identity and resolves internally — a file-overlap analyzer could not be written against a controller-resolved, identity-only batch.
+
+## Behavior
+
+The files a batch changes are drawn from each change's provider-supplied details. The candidate batch conflicts with an in-flight batch when their changed-file sets intersect; each such in-flight batch is reported once, preserving the in-flight order. A shared file is the concrete notion of *target overlap*, so conflicts are classified as `ConflictTypeTargetOverlap`. A batch that changes no files conflicts with nothing, and an empty in-flight list yields no conflicts. A failure to resolve a batch's changes is returned as a (retryable) error.
+
+File-path intersection is a deliberately simple notion of overlap. A richer one (build targets, ownership boundaries) would be a separate analyzer rather than a change to this one.

submitqueue/extension/conflict/fileoverlap/fileoverlap.go

@@ -0,0 +1,105 @@
+// Copyright (c) 2025 Uber 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 fileoverlap provides a conflict.Analyzer that reports a conflict
+// between two batches when they change one or more of the same files. It is the
+// first analyzer to use the capability the extension contract unblocks: it takes
+// only batch identity and resolves each batch's changed files itself through an
+// injected changeset resolver, rather than depending on the controller to
+// pre-compute them. A shared file is the concrete notion of target overlap, so
+// it reports conflict.ConflictTypeTargetOverlap.
+package fileoverlap
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/uber/submitqueue/submitqueue/core/changeset"
+	"github.com/uber/submitqueue/submitqueue/entity"
+	"github.com/uber/submitqueue/submitqueue/extension/conflict"
+)
+
+// analyzer reports a conflict between batches that change a common file. The
+// files a batch changes are resolved from each batch's change details.
+type analyzer struct {
+	resolver changeset.Resolver
+}
+
+// New returns a conflict.Analyzer that flags an in-flight batch as conflicting
+// when it changes a file the candidate batch also changes. The resolver
+// resolves each batch's changed files.
+func New(resolver changeset.Resolver) conflict.Analyzer {
+	return analyzer{resolver: resolver}
+}
+
+// Analyze returns one ConflictTypeTargetOverlap Conflict per in-flight batch
+// that shares a changed file with batch, preserving the in-flight order. A batch
+// that changes no files conflicts with nothing.
+func (a analyzer) Analyze(ctx context.Context, batch entity.Batch, inFlight []entity.Batch) ([]conflict.Conflict, error) {
+	if len(inFlight) == 0 {
+		return nil, nil
+	}
+
+	candidate, err := a.files(ctx, batch)
+	if err != nil {
+		return nil, fmt.Errorf("failed to resolve files for batch %s: %w", batch.ID, err)
+	}
+	if len(candidate) == 0 {
+		return nil, nil
+	}
+
+	var conflicts []conflict.Conflict
+	for _, other := range inFlight {
+		files, err := a.files(ctx, other)
+		if err != nil {
+			return nil, fmt.Errorf("failed to resolve files for batch %s: %w", other.ID, err)
+		}
+		if intersects(candidate, files) {
+			conflicts = append(conflicts, conflict.Conflict{
+				BatchID: other.ID,
+				Type:    conflict.ConflictTypeTargetOverlap,
+			})
+		}
+	}
+	return conflicts, nil
+}
+
+// files resolves the set of file paths the batch changes.
+func (a analyzer) files(ctx context.Context, batch entity.Batch) (map[string]struct{}, error) {
+	changes, err := a.resolver.DetailedForBatch(ctx, batch)
+	if err != nil {
+		return nil, err
+	}
+	files := make(map[string]struct{})
+	for _, change := range changes.Changes {
+		for _, file := range change.Details.ChangedFiles {
+			files[file.Path] = struct{}{}
+		}
+	}
+	return files, nil
+}
+
+// intersects reports whether the two sets share any element.
+func intersects(a, b map[string]struct{}) bool {
+	// Iterate the smaller set for fewer lookups.
+	if len(b) < len(a) {
+		a, b = b, a
+	}
+	for k := range a {
+		if _, ok := b[k]; ok {
+			return true
+		}
+	}
+	return false
+}

submitqueue/extension/conflict/fileoverlap/fileoverlap_test.go

@@ -0,0 +1,124 @@
+// Copyright (c) 2025 Uber 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 fileoverlap
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	changesetfake "github.com/uber/submitqueue/submitqueue/core/changeset/fake"
+	"github.com/uber/submitqueue/submitqueue/entity"
+	"github.com/uber/submitqueue/submitqueue/extension/conflict"
+)
+
+// detailed builds a BatchChanges whose single change touches the given files.
+func detailed(batchID string, files ...string) entity.BatchChanges {
+	changed := make([]entity.ChangedFile, 0, len(files))
+	for _, f := range files {
+		changed = append(changed, entity.ChangedFile{Path: f})
+	}
+	return entity.BatchChanges{
+		BatchID: batchID,
+		Changes: []entity.ChangeInfo{{Details: entity.ChangeDetails{ChangedFiles: changed}}},
+	}
+}
+
+func TestAnalyze(t *testing.T) {
+	tests := []struct {
+		name        string
+		candidate   entity.BatchChanges
+		inFlight    map[string]entity.BatchChanges
+		inFlightIDs []string
+		wantBatches []string
+	}{
+		{
+			name:      "overlap on a shared file conflicts",
+			candidate: detailed("cand", "a.go", "b.go"),
+			inFlight: map[string]entity.BatchChanges{
+				"x": detailed("x", "b.go", "c.go"),
+			},
+			inFlightIDs: []string{"x"},
+			wantBatches: []string{"x"},
+		},
+		{
+			name:      "disjoint files do not conflict",
+			candidate: detailed("cand", "a.go"),
+			inFlight: map[string]entity.BatchChanges{
+				"x": detailed("x", "z.go"),
+			},
+			inFlightIDs: []string{"x"},
+			wantBatches: nil,
+		},
+		{
+			name:      "only overlapping in-flight batches are reported, in order",
+			candidate: detailed("cand", "a.go"),
+			inFlight: map[string]entity.BatchChanges{
+				"x": detailed("x", "a.go"),
+				"y": detailed("y", "q.go"),
+				"z": detailed("z", "a.go"),
+			},
+			inFlightIDs: []string{"x", "y", "z"},
+			wantBatches: []string{"x", "z"},
+		},
+		{
+			name:      "candidate with no targets conflicts with nothing",
+			candidate: detailed("cand"),
+			inFlight: map[string]entity.BatchChanges{
+				"x": detailed("x", "a.go"),
+			},
+			inFlightIDs: []string{"x"},
+			wantBatches: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			resolver := changesetfake.New().SetDetailed("cand", tt.candidate)
+			inFlight := make([]entity.Batch, 0, len(tt.inFlightIDs))
+			for _, id := range tt.inFlightIDs {
+				resolver.SetDetailed(id, tt.inFlight[id])
+				inFlight = append(inFlight, entity.Batch{ID: id})
+			}
+
+			got, err := New(resolver).Analyze(context.Background(), entity.Batch{ID: "cand"}, inFlight)
+			require.NoError(t, err)
+
+			var ids []string
+			for _, c := range got {
+				assert.Equal(t, conflict.ConflictTypeTargetOverlap, c.Type)
+				ids = append(ids, c.BatchID)
+			}
+			assert.Equal(t, tt.wantBatches, ids)
+		})
+	}
+}
+
+func TestAnalyze_EmptyInFlight(t *testing.T) {
+	got, err := New(changesetfake.New()).Analyze(context.Background(), entity.Batch{ID: "cand"}, nil)
+	require.NoError(t, err)
+	assert.Empty(t, got)
+}
+
+func TestAnalyze_ResolverError(t *testing.T) {
+	sentinel := errors.New("resolve failed")
+	resolver := changesetfake.New().FailWith(sentinel)
+
+	_, err := New(resolver).Analyze(context.Background(), entity.Batch{ID: "cand"}, []entity.Batch{{ID: "x"}})
+	require.ErrorIs(t, err, sentinel)
+}