fix: make reference equality consistent and fail clearly on unresolved references

Directory.Build.props

@@ -0,0 +1,6 @@
+<Project>
+  <PropertyGroup>
+    <!-- Overriding Equals or == without GetHashCode breaks hash-based collections and LINQ Distinct. -->
+    <WarningsAsErrors>$(WarningsAsErrors);CS0659;CS0661</WarningsAsErrors>
+  </PropertyGroup>
+</Project>

src/ByteBard.AsyncAPI.Bindings/Sns/Statement.cs

@@ -26,7 +26,7 @@ public class Statement : IAsyncApiExtensible
         /// <summary>
         /// The resource(s) that this policy applies to.
         /// </summary>
-        public StringOrStringList? Resource { get; set; }
+        public StringOrStringList Resource { get; set; }
 
         /// <summary>
         /// Specific circumstances under which the policy grants permission.

src/ByteBard.AsyncAPI.Bindings/Sqs/Statement.cs

@@ -26,7 +26,7 @@ public class Statement : IAsyncApiExtensible
         /// <summary>
         /// The resource(s) that this policy applies to.
         /// </summary>
-        public StringOrStringList? Resource { get; set; }
+        public StringOrStringList Resource { get; set; }
 
         /// <summary>
         /// Specific circumstances under which the policy grants permission.

src/ByteBard.AsyncAPI.Readers/AsyncApiReaderSettings.cs

@@ -73,7 +73,7 @@ public ICollection<IBindingParser<IBinding>>
         /// <summary>
         /// Uri where relative references should be resolved from when using the External Reference Loader.
         /// </summary>
-        public Uri? BaseUri { get; set; }
+        public Uri BaseUri { get; set; }
 
         /// <summary>
         /// External reference reader implementation provided by users for reading external resources.

src/ByteBard.AsyncAPI/Models/AsyncApiChannel.cs

@@ -15,7 +15,7 @@ public class AsyncApiChannel : IAsyncApiSerializable, IAsyncApiExtensible
         /// <summary>
         /// An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When null or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain Channel Address Expressions. Query parameters and fragments SHALL NOT be used, instead use bindings to define them.
         /// </summary>
-        public virtual string? Address { get; set; }
+        public virtual string Address { get; set; }
 
         /// <summary>
         /// A map of the messages that will be sent to this channel by any application at any time. Every message sent to this channel MUST be valid against one, and only one, of the message objects defined in this map.

src/ByteBard.AsyncAPI/Models/AsyncApiReference.cs

@@ -151,6 +151,19 @@ public override bool Equals(object obj)
             return this.Equals(reference);
         }
 
+        public override int GetHashCode()
+        {
+            return this.Reference?.GetHashCode() ?? 0;
+        }
+
+        /// <summary>
+        /// Creates the exception thrown when the referenced element is needed but the reference cannot be resolved.
+        /// </summary>
+        internal InvalidOperationException CreateUnresolvedException()
+        {
+            return new InvalidOperationException($"The reference '{this.Reference}' is not resolved, so the element it points to is not available.");
+        }
+
         /// <summary>
         /// Serialize <see cref="AsyncApiReference"/> to Async Api.
         /// </summary>

src/ByteBard.AsyncAPI/Models/References/AsyncApiAvroSchemaReference.cs

@@ -11,6 +11,8 @@ public class AsyncApiAvroSchemaReference : AsyncApiAvroSchema, IAsyncApiReferenc
     {
         private AsyncApiAvroSchema target;
 
+        private AsyncApiAvroSchema Resolved => this.Target ?? throw this.Reference.CreateUnresolvedException();
+
         private AsyncApiAvroSchema Target
         {
             get
@@ -27,7 +29,7 @@ public AsyncApiAvroSchemaReference(string reference)
 
         public override string Type => this.Target?.Type;
 
-        public override IDictionary<string, AsyncApiAny> Metadata { get => this.Target?.Metadata; set => this.Target.Metadata = value; }
+        public override IDictionary<string, AsyncApiAny> Metadata { get => this.Target?.Metadata; set => this.Resolved.Metadata = value; }
 
         public bool UnresolvedReference { get { return this.Target == null; } }
 
@@ -40,7 +42,7 @@ public override T As<T>()
                 return null;
             }
 
-            return this.Target.As<T>();
+            return this.Resolved.As<T>();
         }
 
         public override bool Is<T>()
@@ -50,7 +52,7 @@ public override bool Is<T>()
                 return false;
             }
 
-            return this.Target.Is<T>();
+            return this.Resolved.Is<T>();
         }
 
         public override bool TryGetAs<T>(out T result)
@@ -61,7 +63,7 @@ public override bool TryGetAs<T>(out T result)
                 return false;
             }
 
-            return this.Target.TryGetAs(out result);
+            return this.Resolved.TryGetAs(out result);
         }
 
         public override void SerializeV2(IAsyncApiWriter writer)
@@ -77,7 +79,7 @@ public override void SerializeV2(IAsyncApiWriter writer)
                 return;
             }
 
-            this.Target.SerializeV2(writer);
+            this.Resolved.SerializeV2(writer);
         }
 
         public override void SerializeV3(IAsyncApiWriter writer)
@@ -93,7 +95,7 @@ public override void SerializeV3(IAsyncApiWriter writer)
                 return;
             }
 
-            this.Target.SerializeV3(writer);
+            this.Resolved.SerializeV3(writer);
         }
     }
 }

src/ByteBard.AsyncAPI/Models/References/AsyncApiBindingsReference{TBinding}.cs

@@ -21,7 +21,7 @@ private AsyncApiBindings<TBinding> Target
             get
             {
                 this.target ??= this.Reference.Workspace?.ResolveReference<AsyncApiBindings<TBinding>>(this.Reference);
-                return this.target;
+                return this.target ?? throw this.Reference.CreateUnresolvedException();
             }
         }
 
@@ -34,7 +34,7 @@ public override void Add(TBinding binding)
 
         public override ICollection<TBinding> Values => this.Target.Values;
 
-        public override IDictionary<string, IAsyncApiExtension> Extensions => this.target.Extensions;
+        public override IDictionary<string, IAsyncApiExtension> Extensions => this.Target.Extensions;
 
         public override int Count => this.Target.Count;
 

src/ByteBard.AsyncAPI/Models/References/AsyncApiChannelReference.cs

@@ -11,6 +11,8 @@ public class AsyncApiChannelReference : AsyncApiChannel, IAsyncApiReferenceable,
     {
         private AsyncApiChannel target;
 
+        private AsyncApiChannel Resolved => this.Target ?? throw this.Reference.CreateUnresolvedException();
+
         private AsyncApiChannel Target
         {
             get
@@ -25,27 +27,27 @@ public AsyncApiChannelReference(string reference)
             this.Reference = new AsyncApiReference(reference, ReferenceType.Channel);
         }
 
-        public override string Address { get => this.Target?.Address; set => this.Target.Address = value; }
+        public override string Address { get => this.Target?.Address; set => this.Resolved.Address = value; }
 
-        public override IDictionary<string, AsyncApiMessage> Messages { get => this.Target?.Messages; set => this.Target.Messages = value; }
+        public override IDictionary<string, AsyncApiMessage> Messages { get => this.Target?.Messages; set => this.Resolved.Messages = value; }
 
-        public override string Title { get => this.Target?.Title; set => this.Target.Title = value; }
+        public override string Title { get => this.Target?.Title; set => this.Resolved.Title = value; }
 
-        public override string Summary { get => this.Target?.Summary; set => this.Target.Summary = value; }
+        public override string Summary { get => this.Target?.Summary; set => this.Resolved.Summary = value; }
 
-        public override string Description { get => this.Target?.Description; set => this.Target.Description = value; }
+        public override string Description { get => this.Target?.Description; set => this.Resolved.Description = value; }
 
-        public override IList<AsyncApiServerReference> Servers { get => this.Target?.Servers; set => this.Target.Servers = value; }
+        public override IList<AsyncApiServerReference> Servers { get => this.Target?.Servers; set => this.Resolved.Servers = value; }
 
-        public override IDictionary<string, AsyncApiParameter> Parameters { get => this.Target?.Parameters; set => this.Target.Parameters = value; }
+        public override IDictionary<string, AsyncApiParameter> Parameters { get => this.Target?.Parameters; set => this.Resolved.Parameters = value; }
 
-        public override IList<AsyncApiTag> Tags { get => this.Target?.Tags; set => this.Target.Tags = value; }
+        public override IList<AsyncApiTag> Tags { get => this.Target?.Tags; set => this.Resolved.Tags = value; }
 
-        public override AsyncApiExternalDocumentation ExternalDocs { get => this.Target?.ExternalDocs; set => this.Target.ExternalDocs = value; }
+        public override AsyncApiExternalDocumentation ExternalDocs { get => this.Target?.ExternalDocs; set => this.Resolved.ExternalDocs = value; }
 
-        public override AsyncApiBindings<IChannelBinding> Bindings { get => this.Target?.Bindings; set => this.Target.Bindings = value; }
+        public override AsyncApiBindings<IChannelBinding> Bindings { get => this.Target?.Bindings; set => this.Resolved.Bindings = value; }
 
-        public override IDictionary<string, IAsyncApiExtension> Extensions { get => this.Target?.Extensions; set => this.Target.Extensions = value; }
+        public override IDictionary<string, IAsyncApiExtension> Extensions { get => this.Target?.Extensions; set => this.Resolved.Extensions = value; }
 
         public AsyncApiReference Reference { get; set; }
 
@@ -61,7 +63,7 @@ public override void SerializeV2(IAsyncApiWriter writer)
             else
             {
                 this.Reference.Workspace = writer.Workspace;
-                this.Target.SerializeV2(writer);
+                this.Resolved.SerializeV2(writer);
             }
         }
 
@@ -75,7 +77,7 @@ public override void SerializeV3(IAsyncApiWriter writer)
             else
             {
                 this.Reference.Workspace = writer.Workspace;
-                this.Target.SerializeV3(writer);
+                this.Resolved.SerializeV3(writer);
             }
         }
 
@@ -98,6 +100,11 @@ public bool Equals(AsyncApiChannelReference other)
                 return this.Equals(reference);
             }
 
+            if (this.Target is null || other.Target is null)
+            {
+                return this.Target is null && other.Target is null && this.Reference == other.Reference;
+            }
+
             return this.Target == other.Target;
         }
 
@@ -118,7 +125,12 @@ public override bool Equals(object obj)
 
         public bool Equals(AsyncApiChannel other)
         {
-            return this.Target == other;
+            return other is not null && this.Target == other;
+        }
+
+        public override int GetHashCode()
+        {
+            return this.Target?.GetHashCode() ?? this.Reference?.GetHashCode() ?? 0;
         }
     }
 }

src/ByteBard.AsyncAPI/Models/References/AsyncApiCorrelationIdReference.cs

@@ -2,9 +2,9 @@
 {
     using System;
     using System.Collections.Generic;
     /// <summary>
     /// The definition of a correlation ID this application MAY use.
     /// </summary>
 
     using System.Diagnostics;
     using ByteBard.AsyncAPI.Models.Interfaces;
@@ -15,6 +15,8 @@
     {
         private AsyncApiCorrelationId target;
 
+        private AsyncApiCorrelationId Resolved => this.Target ?? throw this.Reference.CreateUnresolvedException();
+
         private AsyncApiCorrelationId Target
         {
             get
@@ -29,11 +31,11 @@
             this.Reference = new AsyncApiReference(reference, ReferenceType.CorrelationId);
         }
 
-        public override string Description { get => this.Target?.Description; set => this.Target.Description = value; }
+        public override string Description { get => this.Target?.Description; set => this.Resolved.Description = value; }
 
-        public override string Location { get => this.Target?.Location; set => this.Target.Location = value; }
+        public override string Location { get => this.Target?.Location; set => this.Resolved.Location = value; }
 
-        public override IDictionary<string, IAsyncApiExtension> Extensions { get => this.Target?.Extensions; set => this.Target.Extensions = value; }
+        public override IDictionary<string, IAsyncApiExtension> Extensions { get => this.Target?.Extensions; set => this.Resolved.Extensions = value; }
 
         public AsyncApiReference Reference { get; set; }
 
@@ -58,6 +60,11 @@
                 return this.Equals(reference);
             }
 
+            if (this.Target is null || other.Target is null)
+            {
+                return this.Target is null && other.Target is null && this.Reference == other.Reference;
+            }
+
             return this.Target == other.Target;
         }
 
@@ -78,7 +85,12 @@
 
         public bool Equals(AsyncApiCorrelationId other)
         {
-            return this.Target == other;
+            return other is not null && this.Target == other;
+        }
+
+        public override int GetHashCode()
+        {
+            return this.Target?.GetHashCode() ?? this.Reference?.GetHashCode() ?? 0;
         }
 
         public override void SerializeV2(IAsyncApiWriter writer)
@@ -91,7 +103,7 @@
             else
             {
                 this.Reference.Workspace = writer.Workspace;
-                this.Target.SerializeV2(writer);
+                this.Resolved.SerializeV2(writer);
             }
         }
 
@@ -105,7 +117,7 @@
             else
             {
                 this.Reference.Workspace = writer.Workspace;
-                this.Target.SerializeV3(writer);
+                this.Resolved.SerializeV3(writer);
             }
         }
     }

src/ByteBard.AsyncAPI/Models/References/AsyncApiExternalDocumentationReference.cs

@@ -11,6 +11,8 @@ public class AsyncApiExternalDocumentationReference : AsyncApiExternalDocumentat
     {
         private AsyncApiExternalDocumentation target;
 
+        private AsyncApiExternalDocumentation Resolved => this.Target ?? throw this.Reference.CreateUnresolvedException();
+
         private AsyncApiExternalDocumentation Target
         {
             get
@@ -25,11 +27,11 @@ public AsyncApiExternalDocumentationReference(string reference)
             this.Reference = new AsyncApiReference(reference, ReferenceType.ExternalDocs);
         }
 
-        public override string Description { get => this.Target?.Description; set => this.Target.Description = value; }
+        public override string Description { get => this.Target?.Description; set => this.Resolved.Description = value; }
 
-        public override Uri Url { get => this.Target?.Url; set => this.Target.Url = value; }
+        public override Uri Url { get => this.Target?.Url; set => this.Resolved.Url = value; }
 
-        public override IDictionary<string, IAsyncApiExtension> Extensions { get => this.Target?.Extensions; set => this.Target.Extensions = value; }
+        public override IDictionary<string, IAsyncApiExtension> Extensions { get => this.Target?.Extensions; set => this.Resolved.Extensions = value; }
 
         public AsyncApiReference Reference { get; set; }
 
@@ -54,6 +56,11 @@ public bool Equals(AsyncApiExternalDocumentationReference other)
                 return this.Equals(reference);
             }
 
+            if (this.Target is null || other.Target is null)
+            {
+                return this.Target is null && other.Target is null && this.Reference == other.Reference;
+            }
+
             return this.Target == other.Target;
         }
 
@@ -74,7 +81,12 @@ public override bool Equals(object obj)
 
         public bool Equals(AsyncApiExternalDocumentation other)
         {
-            return this.Target == other;
+            return other is not null && this.Target == other;
+        }
+
+        public override int GetHashCode()
+        {
+            return this.Target?.GetHashCode() ?? this.Reference?.GetHashCode() ?? 0;
         }
 
         /// <summary>
@@ -94,7 +106,7 @@ public override void SerializeV2(IAsyncApiWriter writer)
             else
             {
                 this.Reference.Workspace = writer.Workspace;
-                this.Target.SerializeV2(writer);
+                this.Resolved.SerializeV2(writer);
             }
         }
 
@@ -108,7 +120,7 @@ public override void SerializeV3(IAsyncApiWriter writer)
             else
             {
                 this.Reference.Workspace = writer.Workspace;
-                this.Target.SerializeV3(writer);
+                this.Resolved.SerializeV3(writer);
             }
         }
     }