fix: percent-encode keys in local reference pointers (#62)

* fix: percent-encode keys in local reference pointers

The workspace registered keys escaped with only "~0" / "~1", while names recovered
from references were percent-decoded (RFC 6901 section 6). Keys containing "%" or
characters that are percent-encoded in a URI fragment did not round-trip:

- A 2.x server named "a%20b" was written back as "a b", and upgraded to a 3.x
  "#/servers/a%20b" reference that points at a server named "a b".
- A 3.x "$ref: '#/servers/a%20b'" missed the workspace entry for "a b" and was
  resolved from the raw document into a separate copy of the server.

The workspace now normalizes every location's fragment into one percent-encoded
form, so encoded and unencoded references find the same entry, and registrations
and the 2.x reader's references are built with JsonPointer.EscapeUriFragmentToken.

Registry keys are now compared as strings instead of Uris. Uri equality ignores
the fragment of absolute URIs, so "https://x/s.json#/A" and "https://x/s.json#/B"
shared an entry and the second reference silently resolved to the first schema.

Fixes #61

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

* fix: percent-encode 2.x channel references written by address

AsyncApiChannelReference.SerializeV2 writes a reference to a root channel with
the channel's address, escaped with EscapeToken only. A channel addressed
"a%20b" was written as "#/channels/a%20b", which decodes to "a b" and no longer
resolves. It now uses EscapeUriFragmentToken, as does the 2.x reader when it
points such a reference at the normalized channel key.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: bielu

src/ByteBard.AsyncAPI.Readers/V2/AsyncApiChannelDeserializer.cs

@@ -21,7 +21,7 @@ internal static partial class AsyncApiV2Deserializer
         private static string GetServerReferenceKey(ValueNode valueNode)
         {
             var stringValue = valueNode.GetScalarValue();
-            return stringValue.StartsWith("#/servers/") ? stringValue : "#/servers/" + JsonPointer.EscapeToken(stringValue);
+            return stringValue.StartsWith("#/servers/") ? stringValue : "#/servers/" + JsonPointer.EscapeUriFragmentToken(stringValue);
         }
 
         private static readonly PatternFieldMap<AsyncApiChannel> ChannelPatternFields =
@@ -67,7 +67,7 @@ private static string NormalizeChannelPointer(string pointer)
                 return pointer;
             }
 
-            return channelsPrefix + JsonPointer.EscapeToken(NormalizeChannelKey(parsed.Tokens[1]));
+            return channelsPrefix + JsonPointer.EscapeUriFragmentToken(NormalizeChannelKey(parsed.Tokens[1]));
         }
 
         public static string NormalizeChannelKey(string channelKey, ParseNode node = null)
@@ -101,7 +101,7 @@ private static void LoadV2Operation(ParseNode node, AsyncApiChannel instance, As
             var operation = LoadOperation(node);
             var operationKey = node.CheckMapNode("operation")?["operationId"]?.Value.GetScalarValue() ?? "anonymous-operation-" + Interlocked.Increment(ref node.Context.OperationCounter).ToString();
             operation.Action = action;
-            operation.Channel = new AsyncApiChannelReference("#/channels/" + NormalizeChannelKey(instance.Address));
+            operation.Channel = new AsyncApiChannelReference("#/channels/" + JsonPointer.EscapeUriFragmentToken(NormalizeChannelKey(instance.Address)));
 
             var globalOperations = node.Context.GetFromTempStorage<Dictionary<string, AsyncApiOperation>>(TempStorageKeys.Operations) ?? new Dictionary<string, AsyncApiOperation>();
 

src/ByteBard.AsyncAPI.Readers/V2/AsyncApiDocumentDeserializer.cs

@@ -127,16 +127,16 @@ private static void SetOperations(ParsingContext context, AsyncApiDocument docum
                 if (operation.Value.Channel != null)
                 {
                     var messages = context.GetFromTempStorage<Dictionary<string, AsyncApiMessageReference>>(TempStorageKeys.OperationMessageReferences, operation.Value);
-                    var operationChannelFragmentKey = operation.Value.Channel.Reference.Reference.Split('/').Last();
+                    var operationChannelFragmentKey = GetLastReferenceToken(operation.Value.Channel.Reference);
                     var channel = document.Channels.FirstOrDefault(channel => channel.Key == operationChannelFragmentKey);
                     if (channel.Value == null)
                     {
                         // it most likely came from a components channel, so the reference will be wrong.
                         // Find the channel that references this operations channel, and move the reference.
-                        var correctChannelReference = document.Channels.FirstOrDefault(channel => channel.Value is AsyncApiChannelReference reference && reference.Reference.Reference.EndsWith(operationChannelFragmentKey));
+                        var correctChannelReference = document.Channels.FirstOrDefault(channel => channel.Value is AsyncApiChannelReference reference && GetLastReferenceToken(reference.Reference) == operationChannelFragmentKey);
                         if (correctChannelReference.Key != null)
                         {
-                            operation.Value.Channel = new AsyncApiChannelReference("#/channels/" + JsonPointer.EscapeToken(correctChannelReference.Key));
+                            operation.Value.Channel = new AsyncApiChannelReference("#/channels/" + JsonPointer.EscapeUriFragmentToken(correctChannelReference.Key));
                             channel = correctChannelReference;
                         }
                         else
@@ -161,10 +161,20 @@ private static void SetOperations(ParsingContext context, AsyncApiDocument docum
                     foreach (var message in messages)
                     {
                         channel.Value.Messages.TryAdd(message.Key, message.Value);
-                        operation.Value.Messages.Add(new AsyncApiMessageReference($"#/channels/{JsonPointer.EscapeToken(channel.Key)}/messages/{JsonPointer.EscapeToken(message.Key)}"));
+                        operation.Value.Messages.Add(new AsyncApiMessageReference($"#/channels/{JsonPointer.EscapeUriFragmentToken(channel.Key)}/messages/{JsonPointer.EscapeUriFragmentToken(message.Key)}"));
                     }
                 }
             }
         }
+
+        /// <summary>
+        /// Gets the unescaped last pointer token of a reference, so it can be compared with a map key.
+        /// </summary>
+        private static string GetLastReferenceToken(AsyncApiReference reference)
+        {
+            return reference.IsFragment && JsonPointer.TryFromUriFragment(reference.FragmentId, out var pointer) && pointer.Tokens.Length > 0
+                ? pointer.Tokens.Last()
+                : reference.Reference.Split('/').Last();
+        }
     }
 }

src/ByteBard.AsyncAPI.Readers/V2/AsyncApiOperationDeserializer.cs

@@ -49,9 +49,7 @@ private static KeyValuePair<string, AsyncApiMessage> GetMessage(ParseNode node)
             if (message is AsyncApiMessageReference reference)
             {
                 // Use the unescaped last pointer token, so the key matches the referenced component's key.
-                key = reference.Reference.IsFragment && JsonPointer.TryFromUriFragment(reference.Reference.FragmentId, out var pointer) && pointer.Tokens.Length > 0
-                    ? pointer.Tokens.Last()
-                    : reference.Reference.Reference.Split('/').Last();
+                key = GetLastReferenceToken(reference.Reference);
             }
             else if (messageNode["messageId"] != null)
             {
@@ -90,7 +88,7 @@ private static void LoadMessages(ParseNode n, AsyncApiOperation instance)
             {
                 if (message.Value is not AsyncApiMessageReference messageReference)
                 {
-                    var componentReference = "#/components/messages/" + JsonPointer.EscapeToken(message.Key);
+                    var componentReference = "#/components/messages/" + JsonPointer.EscapeUriFragmentToken(message.Key);
                     componentMessages.Add(message.Key, message.Value);
                     componentMessageReferences.Add(message.Key, new AsyncApiMessageReference(componentReference));
                     continue;

src/ByteBard.AsyncAPI.Readers/V2/AsyncApiSecurityRequirementDeserializer.cs

@@ -38,7 +38,7 @@ private static AsyncApiSecuritySchemeReference LoadSecuritySchemeByReference(
             ParsingContext context,
             string schemeName)
         {
-            var securitySchemeObject = new AsyncApiSecuritySchemeReference("#/components/securitySchemes/" + JsonPointer.EscapeToken(schemeName));
+            var securitySchemeObject = new AsyncApiSecuritySchemeReference("#/components/securitySchemes/" + JsonPointer.EscapeUriFragmentToken(schemeName));
 
             return securitySchemeObject;
         }