|
| 1 | +// Licensed to Elasticsearch B.V under one or more agreements. |
| 2 | +// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. |
| 3 | +// See the LICENSE file in the project root for more information |
| 4 | + |
| 5 | +using System.Text.Json.Nodes; |
| 6 | +using System.Text.RegularExpressions; |
| 7 | +using Elastic.Documentation; |
| 8 | +using Elastic.Documentation.AppliesTo; |
| 9 | +using Elastic.Documentation.Configuration.Versions; |
| 10 | +using Elastic.Documentation.Diagnostics; |
| 11 | +using Microsoft.OpenApi; |
| 12 | + |
| 13 | +namespace Elastic.ApiExplorer.Operations; |
| 14 | + |
| 15 | +/// <summary> |
| 16 | +/// Badge data needed by the applies-to-popover web component. |
| 17 | +/// </summary> |
| 18 | +public sealed record AvailabilityBadgeData( |
| 19 | + string BadgeKey, |
| 20 | + string BadgeLifecycleText, |
| 21 | + string BadgeVersion, |
| 22 | + string LifecycleClass, |
| 23 | + string LifecycleName, |
| 24 | + bool ShowLifecycleName, |
| 25 | + bool ShowVersion |
| 26 | +); |
| 27 | + |
| 28 | +/// <summary> |
| 29 | +/// Parses x-state extension values into structured badge data for the applies-to-popover web component. |
| 30 | +/// Projects x-state into the applies_to lifecycle format and delegates parsing to <see cref="AppliesCollection"/>. |
| 31 | +/// </summary> |
| 32 | +public static partial class AvailabilityBadgeHelper |
| 33 | +{ |
| 34 | + [GeneratedRegex(@"(\d+\.\d+\.\d+)")] |
| 35 | + private static partial Regex SemVersionRegex(); |
| 36 | + |
| 37 | + /// <summary> |
| 38 | + /// Extracts badge data from an OpenAPI operation's x-state extension. |
| 39 | + /// Returns null when no displayable availability information exists. |
| 40 | + /// </summary> |
| 41 | + public static AvailabilityBadgeData? FromOperation(OpenApiOperation operation, VersionsConfiguration? versionsConfig) => |
| 42 | + FromExtensions(operation.Extensions, versionsConfig); |
| 43 | + |
| 44 | + /// <summary> |
| 45 | + /// Extracts badge data from an OpenAPI schema's x-state extension. |
| 46 | + /// Returns null when no displayable availability information exists. |
| 47 | + /// </summary> |
| 48 | + public static AvailabilityBadgeData? FromSchema(IOpenApiSchema schema, VersionsConfiguration? versionsConfig) => |
| 49 | + FromExtensions(schema.Extensions, versionsConfig); |
| 50 | + |
| 51 | + private static AvailabilityBadgeData? FromExtensions( |
| 52 | + IDictionary<string, IOpenApiExtension>? extensions, |
| 53 | + VersionsConfiguration? versionsConfig) |
| 54 | + { |
| 55 | + if (extensions is null || !extensions.TryGetValue("x-state", out var stateExtension)) |
| 56 | + return null; |
| 57 | + |
| 58 | + if (stateExtension is not JsonNodeExtension jsonNodeExtension) |
| 59 | + return null; |
| 60 | + |
| 61 | + if (jsonNodeExtension.Node is not JsonValue jsonValue |
| 62 | + || !jsonValue.TryGetValue<string>(out var stateValue) |
| 63 | + || string.IsNullOrEmpty(stateValue)) |
| 64 | + return null; |
| 65 | + |
| 66 | + var lifecycleString = ProjectToLifecycleFormat(stateValue); |
| 67 | + if (lifecycleString is null) |
| 68 | + return null; |
| 69 | + |
| 70 | + var diagnostics = new List<(Severity, string)>(); |
| 71 | + if (!AppliesCollection.TryParse(lifecycleString, diagnostics, out var appliesCollection) || appliesCollection is null) |
| 72 | + return null; |
| 73 | + |
| 74 | + var applicableTo = new ApplicableTo { Stack = appliesCollection }; |
| 75 | + |
| 76 | + return BuildBadgeData(applicableTo, versionsConfig); |
| 77 | + } |
| 78 | + |
| 79 | + /// <summary> |
| 80 | + /// Converts an x-state string (e.g. "Added in 7.7.0", "Technical preview", |
| 81 | + /// "Generally available; added in 9.1.0") into the lifecycle format |
| 82 | + /// understood by <see cref="AppliesCollection.TryParse"/> (e.g. "ga 7.7.0", "preview"). |
| 83 | + /// </summary> |
| 84 | + internal static string? ProjectToLifecycleFormat(string xState) |
| 85 | + { |
| 86 | + var lower = xState.ToLowerInvariant(); |
| 87 | + |
| 88 | + var lifecycle = lower switch |
| 89 | + { |
| 90 | + _ when lower.Contains("removed") => "removed", |
| 91 | + _ when lower.Contains("deprecated") => "deprecated", |
| 92 | + _ when lower.Contains("beta") => "beta", |
| 93 | + _ when lower.Contains("preview") => "preview", |
| 94 | + _ when lower.Contains("generally available") => "ga", |
| 95 | + _ => null |
| 96 | + }; |
| 97 | + |
| 98 | + var versionMatch = SemVersionRegex().Match(xState); |
| 99 | + if (versionMatch.Success) |
| 100 | + return $"{lifecycle ?? "ga"} {versionMatch.Groups[1].Value}"; |
| 101 | + |
| 102 | + return lifecycle; |
| 103 | + } |
| 104 | + |
| 105 | + private static AvailabilityBadgeData? BuildBadgeData( |
| 106 | + ApplicableTo applicableTo, |
| 107 | + VersionsConfiguration? versionsConfig) |
| 108 | + { |
| 109 | + if (applicableTo.Stack is null) |
| 110 | + return null; |
| 111 | + |
| 112 | + var applicability = applicableTo.Stack.First(); |
| 113 | + var lifecycleClass = applicability.GetLifeCycleName().ToLowerInvariant().Replace(" ", "-"); |
| 114 | + var lifecycleName = applicability.GetLifeCycleName(); |
| 115 | + |
| 116 | + var versionDisplay = ""; |
| 117 | + var showVersion = false; |
| 118 | + var showLifecycleName = applicability.Lifecycle != ProductLifecycle.GenerallyAvailable; |
| 119 | + var badgeLifecycleText = ""; |
| 120 | + |
| 121 | + var version = applicability.Version; |
| 122 | + if (version is not null && version != AllVersionsSpec.Instance) |
| 123 | + { |
| 124 | + var currentVersion = GetCurrentStackVersion(versionsConfig); |
| 125 | + var isReleased = currentVersion is null || version.Min <= currentVersion; |
| 126 | + |
| 127 | + if (isReleased) |
| 128 | + { |
| 129 | + versionDisplay = FormatVersion(version); |
| 130 | + showVersion = !string.IsNullOrEmpty(versionDisplay); |
| 131 | + |
| 132 | + if (applicability.Lifecycle == ProductLifecycle.Removed && versionDisplay.EndsWith('+')) |
| 133 | + versionDisplay = versionDisplay.TrimEnd('+'); |
| 134 | + } |
| 135 | + else |
| 136 | + { |
| 137 | + badgeLifecycleText = applicability.Lifecycle switch |
| 138 | + { |
| 139 | + ProductLifecycle.Deprecated => "Deprecation planned", |
| 140 | + ProductLifecycle.Removed => "Removal planned", |
| 141 | + _ => "Planned" |
| 142 | + }; |
| 143 | + showLifecycleName = false; |
| 144 | + } |
| 145 | + } |
| 146 | + |
| 147 | + return new AvailabilityBadgeData( |
| 148 | + BadgeKey: "Stack", |
| 149 | + BadgeLifecycleText: badgeLifecycleText, |
| 150 | + BadgeVersion: versionDisplay, |
| 151 | + LifecycleClass: lifecycleClass, |
| 152 | + LifecycleName: lifecycleName, |
| 153 | + ShowLifecycleName: showLifecycleName, |
| 154 | + ShowVersion: showVersion |
| 155 | + ); |
| 156 | + } |
| 157 | + |
| 158 | + private static SemVersion? GetCurrentStackVersion(VersionsConfiguration? versionsConfig) |
| 159 | + { |
| 160 | + if (versionsConfig is null) |
| 161 | + return null; |
| 162 | + |
| 163 | + try |
| 164 | + { |
| 165 | + var versioningSystem = versionsConfig.GetVersioningSystem(VersioningSystemId.Stack); |
| 166 | + return versioningSystem.Current; |
| 167 | + } |
| 168 | + catch (ArgumentException) |
| 169 | + { |
| 170 | + return null; |
| 171 | + } |
| 172 | + } |
| 173 | + |
| 174 | + private static string FormatVersion(VersionSpec versionSpec) |
| 175 | + { |
| 176 | + var min = versionSpec.Min; |
| 177 | + var minVersion = versionSpec.ShowMinPatch |
| 178 | + ? $"{min.Major}.{min.Minor}.{min.Patch}" |
| 179 | + : $"{min.Major}.{min.Minor}"; |
| 180 | + |
| 181 | + return versionSpec.Kind switch |
| 182 | + { |
| 183 | + VersionSpecKind.GreaterThanOrEqual => $"{minVersion}+", |
| 184 | + VersionSpecKind.Exact => minVersion, |
| 185 | + VersionSpecKind.Range when versionSpec.Max is { } max => |
| 186 | + $"{minVersion}-{(versionSpec.ShowMaxPatch ? $"{max.Major}.{max.Minor}.{max.Patch}" : $"{max.Major}.{max.Minor}")}", |
| 187 | + _ => minVersion |
| 188 | + }; |
| 189 | + } |
| 190 | +} |
0 commit comments