(dotnet) Migrate gherkin messages to cucumber messages (#426)

This PR enhances the .Net implementation such that the Message events
and pickles that are generated use the Cucumber/Messages types instead
of the Gherkin.Cucumber.Messages.Types which had been embedded in the
Gherkin project.


* Add test data for star keywords

The starkey word is kinda special because its step type is unknown.
How different implementations handle this seems to be inconsistent. This
should highlight some problems.

Co-authored-by: M.P. Korstanje <[email protected]>

Author: clrudolphi

CHANGELOG.md

@@ -16,6 +16,7 @@ This document is formatted according to the principles of [Keep A CHANGELOG](htt
 
 ### Changed
 - Fixed Afrikaans translation for "rule" ([#428](https://github.com/cucumber/gherkin/pull/428))
+- [.NET] Migrated to the use of Cucumber/Messages. Eliminated the built-in Gherkin.CucumberMessages.Types ([#426](https://github.com/cucumber/gherkin/pull/426))
 
 ### Removed
 - [Python] Dropped legacy `.egg-info` metadata distribution artifacts
@@ -28,6 +29,7 @@ This document is formatted according to the principles of [Keep A CHANGELOG](htt
 - [Go] Trim trailing tab characters from title and step lines ([#441](https://github.com/cucumber/gherkin/pull/441))
 - [Java] Use a more consistent definition of whitespace ([#442](https://github.com/cucumber/gherkin/pull/442))
 
+
 ## [33.0.0] - 2025-07-07
 ### Changed
 - [Elixir, Go, JavaScript, Java, Perl, Php, Ruby] Update dependency messages to v28 ([#420](https://github.com/cucumber/gherkin/pull/420))

dotnet/Gherkin.Specs/AstBuildingTests.cs

@@ -1,5 +1,5 @@
 using FluentAssertions;
-using Gherkin.CucumberMessages.Types;
+using Io.Cucumber.Messages.Types;
 using Gherkin.Specs.Helper;
 using Xunit;
 

dotnet/Gherkin.Specs/CLI/Program.cs

@@ -1,5 +1,6 @@
 using Gherkin.CucumberMessages;
 using Gherkin.Specs.EventStubs;
+using Gherkin.Specs.Helper;
 using Gherkin.Specs.Tokens;
 using System.Text.Json;
 using System.Text.Json.Serialization;
@@ -100,11 +101,8 @@ private static int PrintEvents(PrintEventsArgs args)
         {
             foreach (var evt in gherkinEventsProvider.GetEvents(sourceEventEvent))
             {
-                var jsonString = JsonSerializer.Serialize(evt, new JsonSerializerOptions(JsonSerializerDefaults.Web)
-                {
-                    Converters = { new JsonStringEnumConverter() },
-                    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
-                });
+                var jsonString = JsonSerializer.Serialize(evt, NDJsonParser.SerializerOptions);
+
                 Console.WriteLine(jsonString);
             }
         }

dotnet/Gherkin.Specs/EventStubs/GherkinEventsProvider.cs

@@ -1,6 +1,6 @@
 using Gherkin.CucumberMessages;
 using Gherkin.CucumberMessages.Pickles;
-using Gherkin.CucumberMessages.Types;
+using Io.Cucumber.Messages.Types;
 
 namespace Gherkin.Specs.EventStubs;
 
@@ -20,28 +20,18 @@ public IEnumerable<Envelope> GetEvents(Source source)
 
             if (printSource)
             {
-                events.Add(new Envelope
-                {
-                    Source = source
-                });
+                events.Add(Envelope.Create(source));
             }
             if (printAst)
             {
-                events.Add(new Envelope
-                {
-                    GherkinDocument =
-                        _astMessagesConverter.ConvertGherkinDocumentToEventArgs(gherkinDocument, source.Uri)
-                });
+                events.Add(Envelope.Create(_astMessagesConverter.ConvertGherkinDocumentToEventArgs(gherkinDocument, source.Uri)));
             }
             if (printPickles)
             {
                 var pickles = _pickleCompiler.Compile(_astMessagesConverter.ConvertGherkinDocumentToEventArgs(gherkinDocument, source.Uri));
                 foreach (Pickle pickle in pickles)
                 {
-                    events.Add(new Envelope
-                    {
-                        Pickle = pickle
-                    });
+                    events.Add(Envelope.Create(pickle));
                 }
             }
         }
@@ -62,17 +52,21 @@ public IEnumerable<Envelope> GetEvents(Source source)
 
     private void AddParseError(List<Envelope> events, ParserException e, String uri)
     {
-        events.Add(new Envelope
-        {
-            ParseError = new ParseError()
-            {
-                Message = e.Message,
-                Source = new SourceReference()
-                {
-                    Location = e.Location.HasValue ? new Location(e.Location.GetValueOrDefault().Column, e.Location.GetValueOrDefault().Line) : null,
-                    Uri = uri
-                }
-            }
-        });
+        // This forces the suppression of the Column value in the Location when the Location is zero (the default)
+        long? col = null;
+        if (e.Location.HasValue && e.Location.Value.Column != 0)
+            col = e.Location.Value.Column;
+
+        events.Add(Envelope.Create(
+                new ParseError(
+                    new SourceReference(
+                        uri, // Add the missing 'uri' parameter here
+                        null, // Assuming JavaMethod is not needed
+                        null, // Assuming JavaStackTraceElement is not needed
+                        e.Location.HasValue ? new Location(e.Location.GetValueOrDefault().Line, col) : null
+                    ),
+                    e.Message
+            )
+        ));
     }
 }

dotnet/Gherkin.Specs/EventStubs/SourceProvider.cs

@@ -1,23 +1,15 @@
-using Gherkin.CucumberMessages.Types;
+using Io.Cucumber.Messages.Types;   
 
 namespace Gherkin.Specs.EventStubs;
 
 public class SourceProvider
 {
-    private const string GherkinMediaType = "text/x.cucumber.gherkin+plain";
-
     public IEnumerable<Source> GetSources(IEnumerable<string> paths)
     {
         foreach (var path in paths)
         {
             string data = File.ReadAllText(path);
-            yield return new Source
-            {
-                Data = data,
-                Uri = path,
-                MediaType = GherkinMediaType
-            };
+            yield return new Source(path, data, SourceMediaType.TEXT_X_CUCUMBER_GHERKIN_PLAIN);
         }
     }
-
 }

dotnet/Gherkin.Specs/EventTestBase.cs

@@ -2,7 +2,7 @@
 using System.Text;
 using FluentAssertions;
 using Gherkin.CucumberMessages;
-using Gherkin.CucumberMessages.Types;
+using Io.Cucumber.Messages.Types;
 using Gherkin.Specs.EventStubs;
 using Gherkin.Specs.Helper;
 
@@ -18,7 +18,35 @@ protected void AssertEvents(string testFeatureFile, List<Envelope> actualGherkin
            config => config
                .AllowingInfiniteRecursion()
                .IgnoringCyclicReferences()
-               .Excluding(ghe => ghe.Path.EndsWith("Uri"))
+                .ComparingByMembers<Background>()
+                .ComparingByMembers<Comment>()
+                .ComparingByMembers<Io.Cucumber.Messages.Types.DataTable>()
+                .ComparingByMembers<DocString>()
+                .ComparingByMembers<Envelope>()
+                .ComparingByMembers<Examples>()
+                .ComparingByMembers<Feature>()
+                .ComparingByMembers<FeatureChild>()
+                .ComparingByMembers<GherkinDocument>()
+                .ComparingByMembers<Location>()
+                .ComparingByMembers<ParseError>()
+                .ComparingByMembers<Pickle>()
+                .ComparingByMembers<PickleDocString>()
+                .ComparingByMembers<PickleStep>()
+                .ComparingByMembers<PickleStepArgument>()
+                .ComparingByMembers<PickleTable>()
+                .ComparingByMembers<PickleTableCell>()
+                .ComparingByMembers<PickleTableRow>()
+                .ComparingByMembers<PickleTag>()
+                .ComparingByMembers<Rule>()
+                .ComparingByMembers<RuleChild>()
+                .ComparingByMembers<Scenario>()
+                .ComparingByMembers<Source>()
+                .ComparingByMembers<SourceReference>()
+                .ComparingByMembers<Step>()
+                .ComparingByMembers<TableCell>()
+                .ComparingByMembers<TableRow>()
+                .ComparingByMembers<Tag>()
+                .Excluding(ghe => ghe.Path.EndsWith("uri", StringComparison.InvariantCultureIgnoreCase))
                .Using<string>(ctx =>
                                 {
                                     var replacedSubject = NormalizeNewLines(ctx.Subject);

dotnet/Gherkin.Specs/Helper/CucumberMessagesEnumConverterFactory.cs

@@ -0,0 +1,45 @@
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Gherkin.Specs.Helper
+{
+    public class CucumberMessagesEnumConverterFactory : JsonConverterFactory
+    {
+        private static readonly ConcurrentDictionary<Type, JsonConverter> _cache = new();
+        private static readonly HashSet<Type> _enumTypes;
+
+        static CucumberMessagesEnumConverterFactory()
+        {
+            // Discover all enums in Io.Cucumber.Messages.Types
+            var typesNamespace = "Io.Cucumber.Messages.Types";
+            _enumTypes = AppDomain.CurrentDomain.GetAssemblies()
+                .SelectMany(a => SafeGetTypes(a))
+                .Where(t => t.IsEnum && t.Namespace == typesNamespace)
+                .ToHashSet();
+        }
+
+        private static IEnumerable<Type> SafeGetTypes(Assembly assembly)
+        {
+            try { return assembly.GetTypes(); } catch { return Array.Empty<Type>(); }
+        }
+
+        public override bool CanConvert(Type typeToConvert)
+        {
+            return _enumTypes.Contains(typeToConvert);
+        }
+
+        public override JsonConverter CreateConverter(Type typeToConvert, JsonSerializerOptions options)
+        {
+            return _cache.GetOrAdd(typeToConvert, t =>
+            {
+                var converterType = typeof(DescriptionEnumConverter<>).MakeGenericType(t);
+                return (JsonConverter)Activator.CreateInstance(converterType);
+            });
+        }
+    }
+}

dotnet/Gherkin.Specs/Helper/DescriptionEnumConverter.cs

@@ -0,0 +1,44 @@
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Reflection;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Gherkin.Specs.Helper
+{
+    public class DescriptionEnumConverter<T> : JsonConverter<T> where T : struct, Enum
+    {
+        private readonly Dictionary<T, string> _enumToString = new();
+        private readonly Dictionary<string, T> _stringToEnum = new();
+
+        public DescriptionEnumConverter()
+        {
+            var type = typeof(T);
+            foreach (var field in type.GetFields(BindingFlags.Public | BindingFlags.Static))
+            {
+#pragma warning disable CS8605 // Unboxing a possibly null value.
+                var value = (T)field.GetValue(null);
+#pragma warning restore CS8605 // Unboxing a possibly null value.
+                var attribute = field.GetCustomAttribute<DescriptionAttribute>();
+                if (attribute == null || string.IsNullOrEmpty(attribute.Description))
+                    throw new InvalidOperationException($"Enum {type.Name} field {field.Name} does not have a Description attribute or the Description attribute is empty.");
+                var name = attribute.Description;
+                _enumToString[value] = name;
+                _stringToEnum[name] = value;
+            }
+        }
+
+        public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            var stringValue = reader.GetString();
+            return _stringToEnum.TryGetValue(stringValue!, out var enumValue) ? enumValue : default;
+        }
+
+        public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options)
+        {
+            writer.WriteStringValue(_enumToString.TryGetValue(value, out var stringValue) ? stringValue : value.ToString());
+        }
+    }
+
+}

dotnet/Gherkin.Specs/Helper/NDJsonParser.cs

@@ -1,24 +1,29 @@
+using MessageTypes = Io.Cucumber.Messages.Types;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 
 namespace Gherkin.Specs.Helper;
 
 public class NDJsonParser
 {
-    static readonly JsonSerializerOptions s_SerializerOptions = new(JsonSerializerDefaults.Web)
+    private static readonly Lazy<JsonSerializerOptions> _serializerOptions = new(() =>
     {
-        Converters =
-        {
-            new JsonStringEnumConverter(JsonNamingPolicy.CamelCase)
-        }
-    };
+        var options = new JsonSerializerOptions();
+        options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
+        options.Converters.Add(new CucumberMessagesEnumConverterFactory());
+        options.DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull;
+        options.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping;
+        return options;
+    });
+
+    public static JsonSerializerOptions SerializerOptions => _serializerOptions.Value;
 
     public static async Task<List<T>> DeserializeAsync<T>(string expectedFile)
     {
         var result = new List<T>();
         using var contentStream = File.OpenRead(expectedFile);
 
-        await foreach (var deserializedObject in JsonSerializer.DeserializeAsyncEnumerable<T>(contentStream, true, s_SerializerOptions))
+        await foreach (var deserializedObject in JsonSerializer.DeserializeAsyncEnumerable<T>(contentStream, true, SerializerOptions))
         {
             result.Add(deserializedObject);
         }

dotnet/Gherkin.Specs/PicklesTests.cs

@@ -1,5 +1,5 @@
 using FluentAssertions;
-using Gherkin.CucumberMessages.Types;
+using Io.Cucumber.Messages.Types;
 using Gherkin.Specs.Helper;
 using Xunit;