fix(cross-links): use codex path shape in fallback error URL

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

@@ -28,6 +28,12 @@ public record FetchedCrossLinks
 	/// </summary>
 	public FrozenDictionary<string, string>? RegistryUrlsByRepository { get; init; }
 
+	/// <summary>
+	/// Optional map of repository name to the declared <see cref="DocSetRegistry"/> for that cross-link entry.
+	/// Used to pick the correct links.json path shape in error messages when the index could not be fetched.
+	/// </summary>
+	public FrozenDictionary<string, DocSetRegistry>? RegistryByRepository { get; init; }
+
 	/// <summary>
 	/// Set of repository names that belong to a codex (non-public) registry.
 	/// Used by the URI resolver to generate codex URLs instead of public preview URLs.
@@ -40,6 +46,7 @@ public record FetchedCrossLinks
 		LinkReferences = new Dictionary<string, RepositoryLinks>().ToFrozenDictionary(),
 		LinkIndexEntries = new Dictionary<string, LinkRegistryEntry>().ToFrozenDictionary(),
 		RegistryUrlsByRepository = null,
+		RegistryByRepository = null,
 		CodexRepositories = null
 	};
 }

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

@@ -4,6 +4,7 @@
 
 using System.Collections.Frozen;
 using System.Diagnostics.CodeAnalysis;
+using Elastic.Documentation.Configuration;
 
 namespace Elastic.Documentation.Links.CrossLinks;
 
@@ -107,7 +108,7 @@ public static bool TryResolve(
 		var baseUrl = GetLinksJsonBaseUrl(registryUrl);
 		var linksJson = fetchedCrossLinks.LinkIndexEntries.TryGetValue(crossLinkUri.Scheme, out var indexEntry)
 			? $"{baseUrl}/{indexEntry.Path}"
-			: $"{baseUrl}/elastic/{crossLinkUri.Scheme}/main/links.json";
+			: BuildFallbackLinksJsonUrl(baseUrl, crossLinkUri.Scheme, fetchedCrossLinks);
 
 		errorEmitter($"'{originalLookupPath}' is not a valid link in the '{crossLinkUri.Scheme}' cross link index: {linksJson}");
 		resolvedUri = null;
@@ -257,4 +258,21 @@ private static string GetLinksJsonBaseUrl(string registryUrl)
 			return registryUrl.Replace("/link-index.json", "", StringComparison.OrdinalIgnoreCase).TrimEnd('/');
 		return registryUrl.TrimEnd('/');
 	}
+
+	/// <summary>
+	/// Builds a best-effort links.json URL to show in error messages when the index could not be fetched
+	/// and no <see cref="LinkRegistryEntry"/> is available. Codex/internal indexes use
+	/// <c>{env}/elastic/{scheme}/links.json</c>; the public S3 index uses <c>elastic/{scheme}/main/links.json</c>.
+	/// </summary>
+	private static string BuildFallbackLinksJsonUrl(string baseUrl, string scheme, FetchedCrossLinks fetchedCrossLinks)
+	{
+		if (fetchedCrossLinks.RegistryByRepository is not null
+			&& fetchedCrossLinks.RegistryByRepository.TryGetValue(scheme, out var registry)
+			&& registry != DocSetRegistry.Public)
+		{
+			return $"{baseUrl}/{registry.ToStringFast(true)}/elastic/{scheme}/links.json";
+		}
+
+		return $"{baseUrl}/elastic/{scheme}/main/links.json";
+	}
 }

src/Elastic.Documentation.Links/CrossLinks/DocSetConfigurationCrossLinkFetcher.cs

@@ -27,6 +27,7 @@ public override async Task<FetchedCrossLinks> FetchCrossLinks(Cancel ctx)
 		var linkReferences = new Dictionary<string, RepositoryLinks>();
 		var linkIndexEntries = new Dictionary<string, LinkRegistryEntry>();
 		var registryUrlsByRepository = new Dictionary<string, string>();
+		var registryByRepository = new Dictionary<string, DocSetRegistry>();
 		var codexRepositories = new HashSet<string>();
 		var declaredRepositories = new HashSet<string>();
 
@@ -36,6 +37,7 @@ public override async Task<FetchedCrossLinks> FetchCrossLinks(Cancel ctx)
 		foreach (var entry in configuration.CrossLinkEntries)
 		{
 			_ = declaredRepositories.Add(entry.Repository);
+			registryByRepository[entry.Repository] = entry.Registry;
 			var isCodexEntry = useDualRegistry && entry.Registry != DocSetRegistry.Public;
 			var reader = isCodexEntry ? _codexReader! : publicReader;
 
@@ -85,6 +87,7 @@ public override async Task<FetchedCrossLinks> FetchCrossLinks(Cancel ctx)
 			LinkReferences = linkReferences.ToFrozenDictionary(),
 			LinkIndexEntries = linkIndexEntries.ToFrozenDictionary(),
 			RegistryUrlsByRepository = registryUrlsByRepository.ToFrozenDictionary(),
+			RegistryByRepository = registryByRepository.ToFrozenDictionary(),
 			CodexRepositories = codexRepositories.Count > 0 ? codexRepositories.ToFrozenSet() : null,
 		};
 	}

tests/Elastic.Markdown.Tests/CrossLinks/UriEnvironmentResolverTests.cs

@@ -4,6 +4,9 @@
 
 using System.Collections.Frozen;
 using AwesomeAssertions;
+using Elastic.Documentation;
+using Elastic.Documentation.Configuration;
+using Elastic.Documentation.Links;
 using Elastic.Documentation.Links.CrossLinks;
 
 namespace Elastic.Markdown.Tests.CrossLinks;
@@ -223,3 +226,80 @@ public void CrossRepoRedirect_TargetInCodexRepo_ResolvesToCodexPath()
 		resolvedUri.ToString().Should().Be("/r/kibana/get-started");
 	}
 }
+
+public class CrossLinkResolverFallbackUrlTests
+{
+	private static FetchedCrossLinks BuildFallbackOnlyCrossLinks(string repository, string registryUrl, DocSetRegistry registry)
+	{
+		var emptyRepositoryLinks = new RepositoryLinks
+		{
+			Links = [],
+			Origin = new GitCheckoutInformation
+			{
+				Branch = "main",
+				RepositoryName = repository,
+				Remote = "origin",
+				Ref = "refs/heads/main"
+			},
+			UrlPathPrefix = "",
+			CrossLinks = []
+		};
+		return new FetchedCrossLinks
+		{
+			DeclaredRepositories = [repository],
+			LinkReferences = new Dictionary<string, RepositoryLinks> { [repository] = emptyRepositoryLinks }.ToFrozenDictionary(),
+			LinkIndexEntries = new Dictionary<string, LinkRegistryEntry>().ToFrozenDictionary(),
+			RegistryUrlsByRepository = new Dictionary<string, string> { [repository] = registryUrl }.ToFrozenDictionary(),
+			RegistryByRepository = new Dictionary<string, DocSetRegistry> { [repository] = registry }.ToFrozenDictionary()
+		};
+	}
+
+	[Fact]
+	public void InternalRegistry_NoIndexEntry_UsesCodexInternalPath()
+	{
+		var crossLinks = BuildFallbackOnlyCrossLinks(
+			"platform-observability-team",
+			"https://github.com/elastic/codex-link-index",
+			DocSetRegistry.Internal
+		);
+
+		string? emittedError = null;
+		var resolver = new IsolatedBuildEnvironmentUriResolver();
+		var success = CrossLinkResolver.TryResolve(
+			s => emittedError = s,
+			crossLinks,
+			resolver,
+			new Uri("platform-observability-team://index.md", UriKind.Absolute),
+			out _
+		);
+
+		success.Should().BeFalse();
+		emittedError.Should().NotBeNull();
+		emittedError.Should().Contain("https://github.com/elastic/codex-link-index/blob/main/internal/elastic/platform-observability-team/links.json");
+		emittedError.Should().NotContain("/main/links.json");
+	}
+
+	[Fact]
+	public void PublicRegistry_NoIndexEntry_UsesPublicS3Path()
+	{
+		var crossLinks = BuildFallbackOnlyCrossLinks(
+			"docs-content",
+			"https://elastic-docs-link-index.s3.us-east-2.amazonaws.com",
+			DocSetRegistry.Public
+		);
+
+		string? emittedError = null;
+		var resolver = new IsolatedBuildEnvironmentUriResolver();
+		var success = CrossLinkResolver.TryResolve(
+			s => emittedError = s,
+			crossLinks,
+			resolver,
+			new Uri("docs-content://index.md", UriKind.Absolute),
+			out _
+		);
+
+		success.Should().BeFalse();
+		emittedError.Should().NotBeNull();
+		emittedError.Should().Contain("https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/docs-content/main/links.json");
+	}
+}