Update link registry listings to include git reference (#947)

* Update link registry listings to include git reference

* fix import ordering

* GitReference can not be required while there are instances of it without it published

* Run prettier

---------

Co-authored-by: Jan Calanog <jan.calanog@elastic.co>

Author: Mpdreamz

src/Elastic.Markdown/Assets/styles.css

@@ -115,7 +115,6 @@
 			color: var(--color-yellow-80);
 		}
 
-
 		.applicable-info {
 			padding: calc(var(--spacing) * 0.5);
 			padding-left: calc(var(--spacing) * 2);

src/Elastic.Markdown/BuildContext.cs

@@ -9,6 +9,7 @@
 using Elastic.Markdown.IO;
 using Elastic.Markdown.IO.Configuration;
 using Elastic.Markdown.IO.Discovery;
+using Elastic.Markdown.IO.State;
 
 namespace Elastic.Markdown;
 

src/Elastic.Markdown/Elastic.Markdown.csproj

@@ -62,6 +62,8 @@
     <PackageReference Include="Vecc.YamlDotNet.Analyzers.StaticGenerator" Version="16.1.3" PrivateAssets="All"/>
     <PackageReference Include="YamlDotNet" Version="16.3.0" />
     <PackageReference Include="System.IO.Abstractions" Version="21.0.29" />
+    <PackageReference Include="NetEscapades.EnumGenerators" Version="1.0.0-beta12"
+                      PrivateAssets="all" ExcludeAssets="runtime" />
   </ItemGroup>
 
 </Project>

src/Elastic.Markdown/IO/State/ContentSource.cs

@@ -0,0 +1,21 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.ComponentModel.DataAnnotations;
+using System.Text.Json.Serialization;
+using NetEscapades.EnumGenerators;
+
+namespace Elastic.Markdown.IO.State;
+
+[EnumExtensions]
+public enum ContentSource
+{
+	[Display(Name = "next")]
+	[JsonStringEnumMemberName("next")]
+	Next,
+
+	[JsonStringEnumMemberName("current")]
+	[Display(Name = "current")]
+	Current
+}

src/Elastic.Markdown/IO/State/LinkReference.cs

@@ -62,9 +62,15 @@ public record LinkReference
 	public static string SerializeRedirects(Dictionary<string, LinkRedirect>? redirects) =>
 		JsonSerializer.Serialize(redirects, SourceGenerationContext.Default.DictionaryStringLinkRedirect);
 
+	public static LinkReference Deserialize(Stream json) =>
+		JsonSerializer.Deserialize(json, SourceGenerationContext.Default.LinkReference)!;
+
 	public static LinkReference Deserialize(string json) =>
 		JsonSerializer.Deserialize(json, SourceGenerationContext.Default.LinkReference)!;
 
+	public static string Serialize(LinkReference reference) =>
+		JsonSerializer.Serialize(reference, SourceGenerationContext.Default.LinkReference);
+
 	public static LinkReference Create(DocumentationSet set)
 	{
 		var redirects = set.Configuration.Redirects;

src/Elastic.Markdown/Links/CrossLinks/ConfigurationCrossLinkFetcher.cs

@@ -21,7 +21,7 @@ public override async Task<FetchedCrossLinks> Fetch(Cancel ctx)
 			_ = declaredRepositories.Add(repository);
 			try
 			{
-				var linkReference = await Fetch(repository, ctx);
+				var linkReference = await Fetch(repository, ["main", "master"], ctx);
 				linkReferences.Add(repository, linkReference);
 				var linkIndexReference = await GetLinkIndexEntry(repository, ctx);
 				linkIndexEntries.Add(repository, linkIndexReference);

src/Elastic.Markdown/Links/CrossLinks/CrossLinkFetcher.cs

@@ -57,23 +57,34 @@ protected async Task<LinkIndex> FetchLinkIndex(Cancel ctx)
 	protected async Task<LinkIndexEntry> GetLinkIndexEntry(string repository, Cancel ctx)
 	{
 		var linkIndex = await FetchLinkIndex(ctx);
-		if (linkIndex.Repositories.TryGetValue(repository, out var repositoryLinks))
-			return repositoryLinks.First().Value;
-		throw new Exception($"Repository {repository} not found in link index");
+		if (!linkIndex.Repositories.TryGetValue(repository, out var repositoryLinks))
+			throw new Exception($"Repository {repository} not found in link index");
+		return GetNextContentSourceLinkIndexEntry(repositoryLinks, repository);
 	}
 
-	protected async Task<LinkReference> Fetch(string repository, Cancel ctx)
+	protected static LinkIndexEntry GetNextContentSourceLinkIndexEntry(IDictionary<string, LinkIndexEntry> repositoryLinks, string repository)
+	{
+		var linkIndexEntry =
+			(repositoryLinks.TryGetValue("main", out var link)
+				? link
+				: repositoryLinks.TryGetValue("master", out link) ? link : null)
+				?? throw new Exception($"Repository {repository} found in link index, but no main or master branch found");
+		return linkIndexEntry;
+	}
+
+	protected async Task<LinkReference> Fetch(string repository, string[] keys, Cancel ctx)
 	{
 		var linkIndex = await FetchLinkIndex(ctx);
 		if (!linkIndex.Repositories.TryGetValue(repository, out var repositoryLinks))
 			throw new Exception($"Repository {repository} not found in link index");
 
-		if (repositoryLinks.TryGetValue("main", out var linkIndexEntry))
-			return await FetchLinkIndexEntry(repository, linkIndexEntry, ctx);
-		if (repositoryLinks.TryGetValue("master", out linkIndexEntry))
-			return await FetchLinkIndexEntry(repository, linkIndexEntry, ctx);
-		throw new Exception($"Repository {repository} not found in link index");
+		foreach (var key in keys)
+		{
+			if (repositoryLinks.TryGetValue(key, out var linkIndexEntry))
+				return await FetchLinkIndexEntry(repository, linkIndexEntry, ctx);
+		}
 
+		throw new Exception($"Repository found in link index however none of: '{string.Join(", ", keys)}' branches found");
 	}
 
 	protected async Task<LinkReference> FetchLinkIndexEntry(string repository, LinkIndexEntry linkIndexEntry, Cancel ctx)

src/Elastic.Markdown/Links/CrossLinks/CrossLinkResolver.cs

@@ -14,6 +14,9 @@ public record LinkIndex
 {
 	[JsonPropertyName("repositories")] public required Dictionary<string, Dictionary<string, LinkIndexEntry>> Repositories { get; init; }
 
+	public static LinkIndex Deserialize(Stream json) =>
+		JsonSerializer.Deserialize(json, SourceGenerationContext.Default.LinkIndex)!;
+
 	public static LinkIndex Deserialize(string json) =>
 		JsonSerializer.Deserialize(json, SourceGenerationContext.Default.LinkIndex)!;
 
@@ -34,6 +37,10 @@ public record LinkIndexEntry
 
 	[JsonPropertyName("etag")]
 	public required string ETag { get; init; }
+
+	// TODO can be made required after all doc_sets have published again
+	[JsonPropertyName("ref")]
+	public string GitReference { get; init; } = "unknown";
 }
 
 public interface ICrossLinkResolver

src/Elastic.Markdown/Links/InboundLinks/LinkIndexCrossLinkFetcher.cs

@@ -19,7 +19,8 @@ public override async Task<FetchedCrossLinks> Fetch(Cancel ctx)
 		var linkIndex = await FetchLinkIndex(ctx);
 		foreach (var (repository, value) in linkIndex.Repositories)
 		{
-			var linkIndexEntry = value.First().Value;
+			var linkIndexEntry = GetNextContentSourceLinkIndexEntry(value, repository);
+
 			linkEntries.Add(repository, linkIndexEntry);
 			var linkReference = await FetchLinkIndexEntry(repository, linkIndexEntry, ctx);
 			linkReferences.Add(repository, linkReference);
@@ -34,4 +35,5 @@ public override async Task<FetchedCrossLinks> Fetch(Cancel ctx)
 			FromConfiguration = false
 		};
 	}
+
 }

src/Elastic.Markdown/SourceGenerationContext.cs

@@ -11,7 +11,7 @@ namespace Elastic.Markdown;
 
 // This configures the source generation for json (de)serialization.
 
-[JsonSourceGenerationOptions(WriteIndented = true)]
+[JsonSourceGenerationOptions(WriteIndented = true, UseStringEnumConverter = true)]
 [JsonSerializable(typeof(GenerationState))]
 [JsonSerializable(typeof(LinkReference))]
 [JsonSerializable(typeof(GitCheckoutInformation))]