Refactor JTokenComparer and update documentation

Moves JTokenComparer to its own file in the Utilities namespace for better code organization. Updates the README to improve documentation clarity and user examples, and increments the package version to 1.0.10.

The changes include:
- Relocating JTokenComparer class to Core/Utilities with proper namespace
- Adding suppression for SonarLint rule S4055 for the Compare method
- Enhancing README with more detailed usage examples and better formatting
- Updating roadmap and feature status tables for better clarity
- Incrementing package version in the project file

Author: fadhly.permata

Core/JsonQueryEngine.cs

@@ -1,3 +1,4 @@
+using JQL.Net.Core.Utilities;
 using JQL.Net.Exceptions;
 using Newtonsoft.Json.Linq;
 
@@ -691,59 +692,3 @@ private static bool IsAggregateQuery(JsonQueryRequest request)
         );
     }
 }
-
-internal class JTokenComparer : IComparer<JToken?>
-{
-    public int Compare(JToken? x, JToken? y)
-    {
-        if (ReferenceEquals(objA: x, objB: y))
-            return 0;
-        if (x == null)
-            return -1;
-        if (y == null)
-            return 1;
-
-        if (x is JValue vx && y is JValue vy)
-        {
-            var valX = vx.Value;
-            var valY = vy.Value;
-
-            if (valX == null && valY == null)
-                return 0;
-            if (valX == null)
-                return -1;
-            if (valY == null)
-                return 1;
-
-            if (IsNumeric(obj: valX) && IsNumeric(obj: valY))
-                return Convert
-                    .ToDouble(value: valX)
-                    .CompareTo(value: Convert.ToDouble(value: valY));
-
-            return string.Compare(
-                strA: valX.ToString(),
-                strB: valY.ToString(),
-                comparisonType: StringComparison.OrdinalIgnoreCase
-            );
-        }
-        return string.Compare(
-            strA: x.ToString(),
-            strB: y.ToString(),
-            comparisonType: StringComparison.OrdinalIgnoreCase
-        );
-    }
-
-    private static bool IsNumeric(object obj) =>
-        obj
-            is sbyte
-                or byte
-                or short
-                or ushort
-                or int
-                or uint
-                or long
-                or ulong
-                or float
-                or double
-                or decimal;
-}

Core/Utilities/JTokenComparer.cs

@@ -0,0 +1,60 @@
+using Newtonsoft.Json.Linq;
+
+namespace JQL.Net.Core.Utilities;
+
+internal class JTokenComparer : IComparer<JToken?>
+{
+    public int Compare(JToken? x, JToken? y)
+    {
+        if (ReferenceEquals(objA: x, objB: y))
+            return 0;
+        if (x == null)
+            return -1;
+        if (y == null)
+            return 1;
+
+        if (x is not JValue vx || y is not JValue vy)
+            return string.Compare(
+                strA: x.ToString(),
+                strB: y.ToString(),
+                comparisonType: StringComparison.OrdinalIgnoreCase
+            );
+
+        var valX = vx.Value;
+        var valY = vy.Value;
+
+        switch (valX)
+        {
+            case null when valY == null:
+                return 0;
+            case null:
+                return -1;
+        }
+
+        if (valY == null)
+            return 1;
+
+        if (IsNumeric(obj: valX) && IsNumeric(obj: valY))
+            return Convert.ToDouble(value: valX).CompareTo(value: Convert.ToDouble(value: valY));
+
+        return string.Compare(
+            strA: valX.ToString(),
+            strB: valY.ToString(),
+            comparisonType: StringComparison.OrdinalIgnoreCase
+        );
+    }
+
+    private static bool IsNumeric(object obj) =>
+        obj
+            is sbyte
+                or byte
+                or short
+                or ushort
+                or int
+                or uint
+                or long
+                or ulong
+                or float
+                or double
+                or decimal;
+}

GlobalSuppressions.cs

@@ -7,3 +7,11 @@
     Scope = "member",
     Target = "~M:JQL.Net.JsonQueryRequest.Parse(System.String)"
 )]
+
+[assembly: SuppressMessage(
+    category: "SonarLint",
+    checkId: "S4055",
+    Justification = "Static method required for IComparer implementation",
+    Scope = "member",
+    Target = "~M:JQL.Net.Core.Utilities.JTokenComparer.Compare(Newtonsoft.Json.Linq.JToken,Newtonsoft.Json.Linq.JToken)"
+)]

JQL.Net.csproj

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
     <PackageId>JQL.Net</PackageId>
-    <Version>1.0.6</Version>
+    <Version>1.0.10</Version>
     <Authors>Fadhly Permata</Authors>
     <Company>Fadhly Permata</Company>
     <Description>JQL.Net: A lightweight SQL-inspired engine to query, join, and aggregate JSON in .NET. No database? No problem!</Description>
@@ -13,20 +13,18 @@
     <Nullable>enable</Nullable>
     <NoWarn>$(NoWarn);S1192</NoWarn>
   </PropertyGroup>
-
-  <PropertyGroup>
+  <!-- <PropertyGroup>
     <PackageId>JQL.Net</PackageId>
-    <Version>1.0.0</Version> <Authors>Fadhly Permata</Authors>
+    <Version>1.0.0</Version>
+    <Authors>Fadhly Permata</Authors>
     <Description>Lightweight SQL-inspired engine to query JSON in .NET</Description>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <RepositoryUrl>https://github.com/fadhly-permata/JQL.Net</RepositoryUrl>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
-  </PropertyGroup>
-  
+  </PropertyGroup> -->
   <ItemGroup>
     <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
   </ItemGroup>
-  
   <ItemGroup>
     <None Include="README.md" Pack="true" PackagePath="\" />
     <None Include="LICENSE" Pack="true" PackagePath="\" />