fix: refuse to write clashing binding names in AsyncAPI 3

A custom binding "my" is written as "x-my" in AsyncAPI 3, which can clash with
an extension or another binding of that name. Throw an AsyncApiWriterException
instead of writing a duplicate property.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: bielu

src/ByteBard.AsyncAPI/Models/AsyncApiBindings{TBinding}.cs

@@ -42,11 +42,31 @@ public virtual void SerializeV3(IAsyncApiWriter writer)
                 throw new ArgumentNullException(nameof(writer));
             }
 
+            // AsyncAPI 3 only allows the specification's binding names, so a custom binding is written as an extension.
+            // Its x- name can then clash with an extension (or another binding) of the same name; refuse to write a
+            // document with a duplicate property rather than silently dropping one of them.
+            var names = new Dictionary<string, string>(StringComparer.Ordinal);
+            foreach (var extension in this.Extensions.Keys)
+            {
+                names[extension] = $"extension '{extension}'";
+            }
+
+            foreach (var binding in this)
+            {
+                var name = AsyncApiBindingKeys.ToV3Key(binding.Key);
+                if (names.TryGetValue(name, out var existing))
+                {
+                    throw new AsyncApiWriterException(
+                        $"Binding '{binding.Key}' is written as '{name}' in AsyncAPI 3, which clashes with {existing}.");
+                }
+
+                names[name] = $"binding '{binding.Key}'";
+            }
+
             writer.WriteStartObject();
 
             foreach (var binding in this)
             {
-                // AsyncAPI 3 only allows the specification's binding names, so a custom binding is written as an extension.
                 writer.WritePropertyName(AsyncApiBindingKeys.ToV3Key(binding.Key));
 
                 binding.Value.SerializeV3(writer);

test/ByteBard.AsyncAPI.Tests/Bindings/CustomBindingKey_Should.cs

@@ -64,6 +64,52 @@ public void V2_CustomBinding_SerializesUnderItsOwnKey()
             actual.Should().NotContain("x-my");
         }
 
+        [Test]
+        public void V3_CustomBindingClashingWithExtension_Throws()
+        {
+            // Arrange
+            var channel = new AsyncApiChannel();
+            channel.Bindings.Add(new MyBinding { Custom = "someValue" });
+            channel.Bindings.Extensions.Add("x-my", new AsyncApiAny("extensionValue"));
+
+            // Act
+            var act = () => channel.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0);
+
+            // Assert
+            act.Should().Throw<AsyncApiWriterException>().WithMessage("*'my'*'x-my'*extension 'x-my'*");
+        }
+
+        [Test]
+        public void V3_CustomBindingClashingWithPrefixedBinding_Throws()
+        {
+            // Arrange
+            var channel = new AsyncApiChannel();
+            channel.Bindings.Add(new MyBinding { Custom = "someValue" });
+            channel.Bindings.Add("x-my", new MyBinding { Custom = "otherValue" });
+
+            // Act
+            var act = () => channel.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0);
+
+            // Assert
+            act.Should().Throw<AsyncApiWriterException>().WithMessage("*clashes with binding*");
+        }
+
+        [Test]
+        public void V2_CustomBindingAndSameNamedExtension_SerializesBoth()
+        {
+            // Arrange
+            var channel = new AsyncApiChannel();
+            channel.Bindings.Add(new MyBinding { Custom = "someValue" });
+            channel.Bindings.Extensions.Add("x-my", new AsyncApiAny("extensionValue"));
+
+            // Act
+            var actual = channel.SerializeAsYaml(AsyncApiVersion.AsyncApi2_0);
+
+            // Assert
+            actual.Should().Contain("  my:");
+            actual.Should().Contain("x-my: extensionValue");
+        }
+
         [Test]
         public void V3_CustomBindingUnderExtensionKey_ReadsAsBindingWithoutDiagnostics()
         {