Add support for gazelle:resolve directives (#127)

Addresses #117.

Add support for `gazelle:resolve buf` directives in the buf gazelle
plugin's `CrossResolve` function. This allows users to override the
default `@buf_deps//` resolution for proto imports, enabling proper
integration with `local_path_override` modules in bzlmod monorepos.

The `CrossResolve` function now first checks for `gazelle:resolve buf`
directives using the standard `resolve.FindRuleWithOverride` function.
If a matching directive is found, return that label. Otherwise, fall
back to the default `@buf_deps//` resolution.

Example Usage

```python
# gazelle:resolve buf proto/foo/bar.proto @com_example//proto/foo:bar_proto
```

This directive goes in a BUILD file (typically root or parent directory)
and tells gazelle to resolve imports of proto/foo/bar.proto to the label
@com_example//proto/foo:bar_proto instead of the default @buf_deps//...
resolution.


Test Coverage

```
bazel test //...
```

Additionally, in the repository cited in #117, this patch addresses one
(of two) issues uncovered.

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Sri Krishna <93153132+srikrsna-buf@users.noreply.github.com>

Author: 3 people

gazelle/buf/buf_test.go

@@ -65,6 +65,11 @@ func TestCrossResolve(t *testing.T) {
 	testRunGazelle(t, "v2/cross_resolve")
 }
 
+func TestCrossResolveOverride(t *testing.T) {
+	t.Parallel()
+	testRunGazelle(t, "cross_resolve_override")
+}
+
 func TestMerge(t *testing.T) {
 	t.Parallel()
 	testRunGazelle(t, "merge")

gazelle/buf/cross_resolve.go

@@ -33,6 +33,17 @@ func (*bufLang) CrossResolve(gazelleConfig *config.Config, ruleIndex *resolve.Ru
 	if langWithDep != "proto" || importSpec.Lang != "proto" {
 		return nil
 	}
+	// First, check for gazelle:resolve buf directives
+	// This allows users to override the default buf_deps resolution
+	// Example: # gazelle:resolve buf proto/foo/bar.proto @com_example//proto/foo:bar_proto
+	bufImportSpec := resolve.ImportSpec{
+		Lang: "buf",
+		Imp:  importSpec.Imp,
+	}
+	if override, ok := resolve.FindRuleWithOverride(gazelleConfig, bufImportSpec, "buf"); ok {
+		return []resolve.FindResult{{Label: override}}
+	}
+	// Fall back to default buf_deps resolution
 	config := GetConfigForGazelleConfig(gazelleConfig)
 	depRepo := getRepoNameForPath(config.BufConfigFile.Pkg)
 	return []resolve.FindResult{

gazelle/buf/testdata/cross_resolve_override/buf.work.yaml

@@ -0,0 +1,4 @@
+version: v1
+directories:
+  - fooapis
+  - petapis

gazelle/buf/testdata/cross_resolve_override/fooapis/BUILD.in

@@ -0,0 +1 @@
+# gazelle:buf_breaking_against //:against_file

gazelle/buf/testdata/cross_resolve_override/fooapis/BUILD.out

@@ -0,0 +1,10 @@
+load("@rules_buf//buf:defs.bzl", "buf_breaking_test")
+
+# gazelle:buf_breaking_against //:against_file
+
+buf_breaking_test(
+    name = "buf_breaking",
+    against = "//:against_file",
+    config = "//fooapis:buf.yaml",
+    targets = ["//fooapis/foo/v1:foo_v1_proto"],
+)

gazelle/buf/testdata/cross_resolve_override/fooapis/buf.yaml

@@ -0,0 +1,7 @@
+version: v1
+breaking:
+  use:
+    - FILE
+lint:
+  use:
+    - DEFAULT

gazelle/buf/testdata/cross_resolve_override/fooapis/foo/v1/BUILD.in

@@ -0,0 +1,15 @@
+load("@rules_proto//proto:defs.bzl", "proto_library")
+load("@rules_buf//buf:defs.bzl", "buf_lint_test")
+
+proto_library(
+    name = "foo_v1_proto",
+    srcs = ["foo.proto"],
+    strip_import_prefix = "/fooapis",
+    visibility = ["//visibility:public"],
+)
+
+buf_lint_test(
+    name = "foo_v1_proto_lint",
+    config = "//fooapis:buf.yaml",
+    targets = [":foo_v1_proto"],
+)

gazelle/buf/testdata/cross_resolve_override/fooapis/foo/v1/BUILD.out

@@ -0,0 +1,5 @@
+syntax = "proto3";
+
+package foo.v1;
+
+message Foo {}

gazelle/buf/testdata/cross_resolve_override/fooapis/foo/v1/foo.proto

@@ -0,0 +1,2 @@
+# gazelle:buf_breaking_against //:against_file
+# gazelle:resolve buf validate/validate.proto @custom_validate//validate:validate_proto