stabilizaiton work - projects rework for maintenanceability and ui livening

src/__Libraries/StellaOps.Provenance/ProvenanceJsonParser.Helpers.cs

@@ -0,0 +1,82 @@
+using System;
+using System.Text.Json;
+
+namespace StellaOps.Provenance;
+
+public static partial class ProvenanceJsonParser
+{
+    private static JsonElement GetRequiredProperty(JsonElement parent, string name)
+    {
+        if (!parent.TryGetProperty(name, out var property) || property.ValueKind == JsonValueKind.Null)
+        {
+            throw new InvalidOperationException($"Provenance metadata missing required property {name}.");
+        }
+
+        return property;
+    }
+
+    private static string GetRequiredString(JsonElement parent, string name)
+    {
+        var element = GetRequiredProperty(parent, name);
+        if (element.ValueKind is JsonValueKind.String)
+        {
+            var value = element.GetString();
+            if (!string.IsNullOrWhiteSpace(value))
+            {
+                return value;
+            }
+        }
+
+        throw new InvalidOperationException($"Provenance metadata property {name} must be a non-empty string.");
+    }
+
+    private static string? GetOptionalString(JsonElement parent, string name)
+    {
+        if (!parent.TryGetProperty(name, out var element))
+        {
+            return null;
+        }
+
+        return element.ValueKind == JsonValueKind.String ? element.GetString() : null;
+    }
+
+    private static long GetInt64(JsonElement parent, string name)
+    {
+        if (!parent.TryGetProperty(name, out var element))
+        {
+            throw new InvalidOperationException($"Provenance metadata missing {name}.");
+        }
+
+        if (element.ValueKind == JsonValueKind.Number && element.TryGetInt64(out var value))
+        {
+            return value;
+        }
+
+        if (element.ValueKind == JsonValueKind.String && long.TryParse(element.GetString(), out var parsed))
+        {
+            return parsed;
+        }
+
+        throw new InvalidOperationException($"Provenance metadata property {name} must be an integer.");
+    }
+
+    private static long? GetOptionalInt64(JsonElement parent, string name)
+    {
+        if (!parent.TryGetProperty(name, out var element))
+        {
+            return null;
+        }
+
+        if (element.ValueKind == JsonValueKind.Number && element.TryGetInt64(out var value))
+        {
+            return value;
+        }
+
+        if (element.ValueKind == JsonValueKind.String && long.TryParse(element.GetString(), out var parsed))
+        {
+            return parsed;
+        }
+
+        return null;
+    }
+}