ChangelogConfigurationLoader.cs

// 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.IO.Abstractions;
using Elastic.Changelog.Serialization;
using Elastic.Documentation;
using Elastic.Documentation.Configuration;
using Elastic.Documentation.Configuration.Changelog;
using Elastic.Documentation.Configuration.Products;
using Elastic.Documentation.Diagnostics;
using Elastic.Documentation.ReleaseNotes;
using Microsoft.Extensions.Logging;
using YamlDotNet.Core;
using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;

namespace Elastic.Changelog.Configuration;

/// <summary>
/// Service for loading and validating changelog configuration
/// </summary>
public class ChangelogConfigurationLoader(ILoggerFactory logFactory, IConfigurationContext configurationContext, IFileSystem fileSystem)
{
	private readonly ILogger _logger = logFactory.CreateLogger<ChangelogConfigurationLoader>();

	private static readonly IDeserializer ConfigurationDeserializer =
		new StaticDeserializerBuilder(new ChangelogYamlStaticContext())
			.WithNamingConvention(UnderscoredNamingConvention.Instance)
			.WithTypeConverter(new YamlLenientListConverter())
			.WithTypeConverter(new TypeEntryYamlConverter())
			.Build();

	/// <summary>
	/// Deserializes changelog configuration YAML content.
	/// </summary>
	internal static ChangelogConfigurationYaml DeserializeConfiguration(string yaml) =>
		ConfigurationDeserializer.Deserialize<ChangelogConfigurationYaml>(yaml);

	/// <summary>
	/// Loads the publish blocker configuration from a changelog.
	/// </summary>
	/// <param name="fileSystem">The file system to read from.</param>
	/// <param name="configPath">The path to the changelog.yml configuration file.</param>
	/// <returns>The publish blocker configuration, or null if not found.</returns>
	public static PublishBlocker? LoadPublishBlocker(IFileSystem fileSystem, string configPath)
	{
		if (!fileSystem.File.Exists(configPath))
			return null;

		var yamlContent = fileSystem.File.ReadAllText(configPath);
		var yamlConfig = DeserializeConfiguration(yamlContent);

		if (yamlConfig.Rules?.Publish == null)
			return null;

		var globalMatch = ParseMatchMode(yamlConfig.Rules.Match) ?? MatchMode.Any;
		var publishMatchAreas = ParseMatchMode(yamlConfig.Rules.Publish.MatchAreas) ?? globalMatch;

		return ParsePublishBlocker(yamlConfig.Rules.Publish, publishMatchAreas);
	}

	/// <summary>
	/// Loads changelog configuration from file or returns default configuration
	/// </summary>
	public async Task<ChangelogConfiguration?> LoadChangelogConfiguration(IDiagnosticsCollector collector, string? configPath, Cancel ctx)
	{
		// Determine config file path
		var finalConfigPath = configPath ?? fileSystem.Path.Join(fileSystem.Directory.GetCurrentDirectory(), "docs", "changelog.yml");

		if (!fileSystem.File.Exists(finalConfigPath))
		{
			// Use default configuration if file doesn't exist
			_logger.LogWarning("Changelog configuration not found at {ConfigPath}, using defaults", finalConfigPath);
			return ChangelogConfiguration.Default;
		}

		try
		{
			var yamlContent = await fileSystem.File.ReadAllTextAsync(finalConfigPath, ctx);
			var yamlConfig = DeserializeConfiguration(yamlContent);

			return ParseConfiguration(collector, yamlConfig, finalConfigPath);
		}
		catch (IOException ex)
		{
			collector.EmitError(finalConfigPath, $"I/O error loading changelog configuration: {ex.Message}", ex);
			return null;
		}
		catch (UnauthorizedAccessException ex)
		{
			collector.EmitError(finalConfigPath, $"Access denied loading changelog configuration: {ex.Message}", ex);
			return null;
		}
		catch (YamlException ex)
		{
			collector.EmitError(finalConfigPath, $"YAML parsing error in changelog configuration: {ex.Message}", ex);
			return null;
		}
	}

	private ChangelogConfiguration? ParseConfiguration(IDiagnosticsCollector collector, ChangelogConfigurationYaml yamlConfig, string configPath)
	{
		var validProductIds = configurationContext.ProductsConfiguration.Products.Keys.ToHashSet(StringComparer.OrdinalIgnoreCase);

		// Detect old 'block:' key
		if (yamlConfig.Block != null)
		{
			collector.EmitError(configPath, "'block' is no longer supported. Rename to 'rules'. See changelog.example.yml.");
			return null;
		}

		// Compute values from pivot configuration
		IReadOnlyList<string> availableTypes;
		IReadOnlyList<string> availableSubtypes;
		IReadOnlyList<string>? availableAreas;
		Dictionary<string, string>? labelToType;
		Dictionary<string, List<string>>? labelToAreas;
		Dictionary<string, string>? labelToProducts;
		PivotConfiguration? pivot = null;

		if (yamlConfig.Pivot != null)
		{
			// Convert YAML pivot to domain pivot
			pivot = ConvertPivot(yamlConfig.Pivot);

			// Compute available types from pivot.types keys
			if (yamlConfig.Pivot.Types is { Count: > 0 })
			{
				// Validate types against enum values using TryParse
				foreach (var typeName in yamlConfig.Pivot.Types.Keys)
				{
					if (ChangelogEntryTypeExtensions.TryParse(typeName, out _, ignoreCase: true, allowMatchingMetadataAttribute: true))
						continue;
					collector.EmitError(configPath, $"Type '{typeName}' in pivot.types is not a valid type. Valid types: {string.Join(", ", ChangelogConfiguration.DefaultTypes)}");
					return null;
				}

				// Validate required types are present
				foreach (var requiredType in ChangelogConfiguration.RequiredTypes)
				{
					var requiredTypeName = requiredType.ToStringFast(true);
					if (yamlConfig.Pivot.Types.Keys.Any(k => k.Equals(requiredTypeName, StringComparison.OrdinalIgnoreCase)))
						continue;
					collector.EmitError(configPath, $"Required type '{requiredTypeName}' is missing from pivot.types. Required types: {string.Join(", ", ChangelogConfiguration.RequiredTypes.Select(t => t.ToStringFast(true)))}");
					return null;
				}

				// Validate subtypes only appear under breaking-change
				foreach (var (typeName, typeEntry) in yamlConfig.Pivot.Types)
				{
					if (typeEntry?.Subtypes is not { Count: > 0 })
						continue;
					if (!typeName.Equals(ChangelogEntryType.BreakingChange.ToStringFast(true), StringComparison.OrdinalIgnoreCase))
					{
						collector.EmitError(configPath, $"Type '{typeName}' has subtypes defined, but subtypes are only allowed for 'breaking-change' type.");
						return null;
					}

					// Validate subtype values against enum
					foreach (var subtypeName in typeEntry.Subtypes.Keys)
					{
						if (ChangelogEntrySubtypeExtensions.TryParse(subtypeName, out _, ignoreCase: true, allowMatchingMetadataAttribute: true))
							continue;
						collector.EmitError(configPath, $"Subtype '{subtypeName}' in pivot.types.{typeName}.subtypes is not a valid subtype. Valid subtypes: {string.Join(", ", ChangelogConfiguration.DefaultSubtypes)}");
						return null;
					}
				}

				availableTypes = yamlConfig.Pivot.Types.Keys.ToList();
			}
			else
				availableTypes = ChangelogConfiguration.DefaultTypes;

			// Compute available subtypes from pivot.subtypes keys
			if (yamlConfig.Pivot.Subtypes != null && yamlConfig.Pivot.Subtypes.Count > 0)
			{
				// Validate subtypes against enum values using TryParse
				foreach (var subtypeName in yamlConfig.Pivot.Subtypes.Keys)
				{
					if (!ChangelogEntrySubtypeExtensions.TryParse(subtypeName, out _, ignoreCase: true, allowMatchingMetadataAttribute: true))
					{
						collector.EmitError(configPath, $"Subtype '{subtypeName}' in pivot.subtypes is not a valid subtype. Valid subtypes: {string.Join(", ", ChangelogConfiguration.DefaultSubtypes)}");
						return null;
					}
				}
				availableSubtypes = yamlConfig.Pivot.Subtypes.Keys.ToList();
			}
			else
				availableSubtypes = ChangelogConfiguration.DefaultSubtypes;

			// Compute available areas from pivot.areas keys
			availableAreas = yamlConfig.Pivot.Areas != null && yamlConfig.Pivot.Areas.Count > 0
				? yamlConfig.Pivot.Areas.Keys.ToList()
				: null;

			// Build LabelToType mapping (inverted from pivot.types)
			labelToType = BuildLabelToTypeMapping(yamlConfig.Pivot.Types);

			// Build LabelToAreas mapping (inverted from pivot.areas)
			labelToAreas = BuildLabelToAreasMapping(yamlConfig.Pivot.Areas);

			// Validate product IDs in pivot.products keys and build LabelToProducts mapping
			if (yamlConfig.Pivot.Products is { Count: > 0 })
			{
				foreach (var productSpec in yamlConfig.Pivot.Products.Keys)
				{
					var specParts = productSpec.Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
					if (specParts.Length == 0)
						continue;
					var productId = specParts[0].Replace('_', '-');
					if (validProductIds.Contains(productId))
						continue;
					var availableProducts = string.Join(", ", validProductIds.OrderBy(p => p));
					collector.EmitError(configPath, $"Product '{specParts[0]}' in pivot.products is not in the list of available products from config/products.yml. Available products: {availableProducts}");
					return null;
				}
			}
			labelToProducts = BuildLabelToProductsMapping(yamlConfig.Pivot.Products);
		}
		else
		{
			// No pivot configuration - use defaults
			availableTypes = ChangelogConfiguration.DefaultTypes;
			availableSubtypes = ChangelogConfiguration.DefaultSubtypes;
			availableAreas = null;
			labelToType = null;
			labelToAreas = null;
			labelToProducts = null;
		}

		// Process lifecycles
		IReadOnlyList<Lifecycle> lifecycles;
		var lifecycleValues = yamlConfig.Lifecycles?.Values;
		if (lifecycleValues == null || lifecycleValues.Count == 0)
			lifecycles = ChangelogConfiguration.DefaultLifecycles;
		else
		{
			var parsedLifecycles = new List<Lifecycle>();
			foreach (var lifecycleStr in lifecycleValues)
			{
				if (!LifecycleExtensions.TryParse(lifecycleStr, out var lifecycle, ignoreCase: true, allowMatchingMetadataAttribute: true))
				{
					collector.EmitError(configPath, $"Lifecycle '{lifecycleStr}' in changelog.yml is not valid. Valid lifecycles: {string.Join(", ", ChangelogConfiguration.DefaultLifecycles.Select(l => l.ToStringFast(true)))}");
					return null;
				}
				parsedLifecycles.Add(lifecycle);
			}
			lifecycles = parsedLifecycles;
		}

		// Process products from products.available
		IReadOnlyList<Product>? products = null;
		var productIdList = yamlConfig.Products?.Available?.Values;
		if (productIdList is { Count: > 0 })
		{
			var resolvedProducts = new List<Product>();
			foreach (var productId in productIdList)
			{
				var normalizedProductId = productId.Replace('_', '-');
				if (!validProductIds.Contains(normalizedProductId))
				{
					var availableProducts = string.Join(", ", validProductIds.OrderBy(p => p));
					collector.EmitError(configPath, $"Product '{productId}' in changelog.yml is not in the list of available products from config/products.yml. Available products: {availableProducts}");
					return null;
				}
				if (configurationContext.ProductsConfiguration.Products.TryGetValue(normalizedProductId, out var product))
					resolvedProducts.Add(product);
			}
			products = resolvedProducts;
		}

		// Process rules configuration
		var rules = ParseRulesConfiguration(collector, yamlConfig.Rules, configPath, validProductIds);
		if (rules == null && collector.Errors > 0)
			return null;

		// Process highlight labels from pivot configuration
		var highlightLabels = yamlConfig.Pivot?.Highlight?.Values;

		// Process products configuration
		ProductsConfig? productsConfig = null;
		if (yamlConfig.Products != null)
			productsConfig = ParseProductsConfig(collector, yamlConfig.Products, configPath, validProductIds);

		// Process bundle configuration
		BundleConfiguration? bundleConfig = null;
		if (yamlConfig.Bundle != null)
		{
			bundleConfig = ParseBundleConfiguration(collector, configPath, yamlConfig.Bundle);
			if (bundleConfig == null)
				return null;
		}

		// Process extract configuration
		var extract = new ExtractConfiguration
		{
			ReleaseNotes = yamlConfig.Extract?.ReleaseNotes ?? true,
			Issues = yamlConfig.Extract?.Issues ?? true,
			StripTitlePrefix = yamlConfig.Extract?.StripTitlePrefix ?? false
		};

		// Process filename strategy
		var filenameStrategy = FilenameStrategy.Timestamp;
		if (!string.IsNullOrWhiteSpace(yamlConfig.Filename))
		{
			if (!FilenameStrategyExtensions.TryParse(yamlConfig.Filename, out var parsed, ignoreCase: true, allowMatchingMetadataAttribute: true))
			{
				var valid = string.Join(", ", FilenameStrategyExtensions.GetValues().Select(v => v.ToStringFast(true)));
				collector.EmitError(configPath, $"filename: '{yamlConfig.Filename}' is not valid. Use one of: {valid}");
				return null;
			}
			filenameStrategy = parsed;
		}

		var labelToAreasReadOnly = labelToAreas?.ToDictionary(
			kvp => kvp.Key,
			kvp => (IReadOnlyList<string>)kvp.Value,
			StringComparer.OrdinalIgnoreCase);

		return new ChangelogConfiguration
		{
			Pivot = pivot,
			Types = availableTypes,
			SubTypes = availableSubtypes,
			Lifecycles = lifecycles,
			Areas = availableAreas,
			Products = products,
			LabelToType = labelToType,
			LabelToAreas = labelToAreasReadOnly,
			LabelToProducts = labelToProducts,
			Rules = rules,
			HighlightLabels = highlightLabels,
			ProductsConfiguration = productsConfig,
			Bundle = bundleConfig,
			Extract = extract,
			Filename = filenameStrategy
		};
	}

	private static PivotConfiguration ConvertPivot(PivotConfigurationYaml yamlPivot)
	{
		Dictionary<string, TypeEntry?>? types = null;
		if (yamlPivot.Types != null)
		{
			types = yamlPivot.Types.ToDictionary(
				kvp => kvp.Key,
				kvp => kvp.Value == null
					? null
					: new TypeEntry
					{
						Labels = kvp.Value.Labels,
						Subtypes = ConvertLenientDictToStringDict(kvp.Value.Subtypes)
					});
		}

		return new PivotConfiguration
		{
			Types = types,
			Subtypes = ConvertLenientDictToStringDict(yamlPivot.Subtypes),
			Areas = ConvertLenientDictToStringDict(yamlPivot.Areas),
			Products = ConvertLenientDictToStringDict(yamlPivot.Products),
			Highlight = JoinLenientList(yamlPivot.Highlight)
		};
	}

	/// <summary>
	/// Converts a dictionary with YamlLenientList values to a dictionary with comma-joined string values.
	/// </summary>
	private static Dictionary<string, string?>? ConvertLenientDictToStringDict(Dictionary<string, YamlLenientList?>? source)
	{
		if (source == null || source.Count == 0)
			return null;

		return source.ToDictionary(
			kvp => kvp.Key,
			kvp => JoinLenientList(kvp.Value)
		);
	}

	/// <summary>
	/// Joins a YamlLenientList into a comma-separated string, or returns null.
	/// </summary>
	private static string? JoinLenientList(YamlLenientList? list) =>
		list?.Values is { Count: > 0 } values ? string.Join(", ", values) : null;

	private ProductsConfig? ParseProductsConfig(
		IDiagnosticsCollector collector,
		ProductsConfigYaml yaml,
		string configPath,
		HashSet<string> validProductIds)
	{
		// Validate available products
		List<string>? available = null;
		var availableValues = yaml.Available?.Values;
		if (availableValues is { Count: > 0 })
		{
			available = [];
			foreach (var productId in availableValues)
			{
				var normalizedProductId = productId.Replace('_', '-');
				if (!validProductIds.Contains(normalizedProductId))
				{
					var availableProducts = string.Join(", ", validProductIds.OrderBy(p => p));
					collector.EmitError(configPath, $"Product '{productId}' in products_config.available is not in the list of available products from config/products.yml. Available products: {availableProducts}");
					return null;
				}
				available.Add(normalizedProductId);
			}
		}

		// Parse default products
		List<DefaultProduct>? defaultProducts = null;
		if (yaml.Default is { Count: > 0 })
		{
			defaultProducts = [];
			foreach (var defaultYaml in yaml.Default)
			{
				if (string.IsNullOrWhiteSpace(defaultYaml.Product))
				{
					collector.EmitError(configPath, "Default product in products_config.default must have a product ID");
					return null;
				}

				var normalizedProductId = defaultYaml.Product.Replace('_', '-');
				if (!validProductIds.Contains(normalizedProductId))
				{
					var availableProducts = string.Join(", ", validProductIds.OrderBy(p => p));
					collector.EmitError(configPath, $"Product '{defaultYaml.Product}' in products_config.default is not in the list of available products from config/products.yml. Available products: {availableProducts}");
					return null;
				}

				defaultProducts.Add(new DefaultProduct
				{
					Product = normalizedProductId,
					Lifecycle = defaultYaml.Lifecycle ?? "ga"
				});
			}
		}

		return new ProductsConfig
		{
			Available = available,
			Default = defaultProducts
		};
	}

	private static BundleConfiguration? ParseBundleConfiguration(IDiagnosticsCollector collector, string configPath, BundleConfigurationYaml yaml)
	{
		if (!string.IsNullOrWhiteSpace(yaml.Repo) && yaml.Repo.Contains('+', StringComparison.Ordinal))
		{
			collector.EmitError(
				configPath,
				"bundle.repo must name a single GitHub repository. Remove '+' merged-repo syntax from bundle.repo.");
			return null;
		}

		if (yaml.Profiles is { Count: > 0 })
		{
			foreach (var kvp in yaml.Profiles)
			{
				var profileRepo = kvp.Value?.Repo;
				if (!string.IsNullOrWhiteSpace(profileRepo) && profileRepo.Contains('+', StringComparison.Ordinal))
				{
					collector.EmitError(
						configPath,
						$"bundle.profiles.{kvp.Key}.repo must name a single GitHub repository. Remove '+' merged-repo syntax.");
					return null;
				}
			}
		}

		IReadOnlyList<string>? linkAllowRepos = null;
		if (yaml.LinkAllowRepos != null)
		{
			var raw = yaml.LinkAllowRepos.Values ?? [];
			var list = new List<string>();
			foreach (var v in raw)
			{
				if (string.IsNullOrWhiteSpace(v))
					continue;

				var trimmed = v.Trim();
				if (trimmed.IndexOf('/') < 0 ||
					trimmed.IndexOf('/') != trimmed.LastIndexOf('/'))
				{
					collector.EmitError(
						configPath,
						$"bundle.link_allow_repos: each entry must be exactly 'owner/repo' (one slash). Invalid: '{v}'.");
					return null;
				}

				var slash = trimmed.IndexOf('/');
				if (slash <= 0 || slash >= trimmed.Length - 1)
				{
					collector.EmitError(
						configPath,
						$"bundle.link_allow_repos: each entry must be exactly 'owner/repo' (one slash). Invalid: '{v}'.");
					return null;
				}

				list.Add(trimmed);
			}

			linkAllowRepos = list;
		}

		Dictionary<string, BundleProfile>? profiles = null;
		if (yaml.Profiles is { Count: > 0 })
		{
			profiles = yaml.Profiles.ToDictionary(
				kvp => kvp.Key,
				kvp => kvp.Value is null
					? new BundleProfile()
					: new BundleProfile
					{
						Products = kvp.Value.Products,
						Output = kvp.Value.Output,
						OutputProducts = kvp.Value.OutputProducts,
						Description = kvp.Value.Description,
						Repo = kvp.Value.Repo,
						Owner = kvp.Value.Owner,
						HideFeatures = kvp.Value.HideFeatures?.Values,
						ShowReleaseDates = kvp.Value.ShowReleaseDates,
						Source = kvp.Value.Source
					});
		}

		return new BundleConfiguration
		{
			Directory = yaml.Directory,
			OutputDirectory = yaml.OutputDirectory,
			Resolve = yaml.Resolve ?? true,
			Description = yaml.Description,
			Repo = yaml.Repo,
			Owner = yaml.Owner,
			LinkAllowRepos = linkAllowRepos,
			ShowReleaseDates = yaml.ShowReleaseDates ?? false,
			Profiles = profiles
		};
	}

	/// <summary>
	/// Loads changelog configuration from a specific path, treating a missing file as a hard error.
	/// Used in profile mode when an explicit config path was provided (e.g. in tests).
	/// </summary>
	public async Task<ChangelogConfiguration?> LoadChangelogConfigurationRequired(IDiagnosticsCollector collector, string configPath, Cancel ctx)
	{
		if (!fileSystem.File.Exists(configPath))
		{
			collector.EmitError(
				configPath,
				$"Changelog configuration file not found at '{configPath}'. " +
				"Either run 'docs-builder changelog init' to create one, " +
				"or re-run from the folder where changelog.yml exists."
			);
			return null;
		}

		try
		{
			var yamlContent = await fileSystem.File.ReadAllTextAsync(configPath, ctx);
			var yamlConfig = DeserializeConfiguration(yamlContent);
			return ParseConfiguration(collector, yamlConfig, configPath);
		}
		catch (IOException ex)
		{
			collector.EmitError(configPath, $"I/O error loading changelog configuration: {ex.Message}", ex);
			return null;
		}
		catch (UnauthorizedAccessException ex)
		{
			collector.EmitError(configPath, $"Access denied loading changelog configuration: {ex.Message}", ex);
			return null;
		}
		catch (YamlDotNet.Core.YamlException ex)
		{
			collector.EmitError(configPath, $"YAML parsing error in changelog configuration: {ex.Message}", ex);
			return null;
		}
	}

	/// <summary>
	/// Discovers and loads the changelog configuration for profile mode.
	/// Unlike <see cref="LoadChangelogConfiguration"/>, this method treats a missing config file as a
	/// hard error. It searches for <c>changelog.yml</c> then <c>docs/changelog.yml</c> relative to the
	/// current working directory, so the command works when run from any folder that contains the file.
	/// </summary>
	public async Task<ChangelogConfiguration?> LoadChangelogConfigurationForProfileMode(IDiagnosticsCollector collector, Cancel ctx)
	{
		var cwd = fileSystem.Directory.GetCurrentDirectory();
		var candidates = new[]
		{
			fileSystem.Path.Join(cwd, "changelog.yml"),
			fileSystem.Path.Join(cwd, "docs", "changelog.yml")
		};

		var foundPath = candidates.FirstOrDefault(fileSystem.File.Exists);

		if (foundPath == null)
		{
			collector.EmitError(
				string.Empty,
				"changelog.yml not found. Profile-based commands require a changelog configuration file. " +
				"Either run 'docs-builder changelog init' to create one, " +
				"or re-run this command from the folder where changelog.yml exists " +
				"(e.g. the project root if the file is at docs/changelog.yml)."
			);
			return null;
		}

		try
		{
			var yamlContent = await fileSystem.File.ReadAllTextAsync(foundPath, ctx);
			var yamlConfig = DeserializeConfiguration(yamlContent);
			return ParseConfiguration(collector, yamlConfig, foundPath);
		}
		catch (IOException ex)
		{
			collector.EmitError(foundPath, $"I/O error loading changelog configuration: {ex.Message}", ex);
			return null;
		}
		catch (UnauthorizedAccessException ex)
		{
			collector.EmitError(foundPath, $"Access denied loading changelog configuration: {ex.Message}", ex);
			return null;
		}
		catch (YamlDotNet.Core.YamlException ex)
		{
			collector.EmitError(foundPath, $"YAML parsing error in changelog configuration: {ex.Message}", ex);
			return null;
		}
	}

	private RulesConfiguration? ParseRulesConfiguration(
		IDiagnosticsCollector collector,
		RulesConfigurationYaml? rulesYaml,
		string configPath,
		HashSet<string> validProductIds)
	{
		if (rulesYaml == null)
			return null;

		// Parse global match mode
		var globalMatch = MatchMode.Any;
		if (!string.IsNullOrWhiteSpace(rulesYaml.Match))
		{
			var parsed = ParseMatchMode(rulesYaml.Match);
			if (parsed == null)
			{
				collector.EmitError(configPath, $"rules.match: '{rulesYaml.Match}' is not valid. Use 'any', 'all', or 'conjunction'.");
				return null;
			}
			globalMatch = parsed.Value;
		}

		// Parse create rules
		var createRules = ParseCreateRules(collector, rulesYaml.Create, configPath, validProductIds, "rules.create", globalMatch);
		if (createRules == null && collector.Errors > 0)
			return null;

		// Parse bundle rules
		var bundleRules = ParseBundleRules(collector, rulesYaml.Bundle, configPath, validProductIds, globalMatch);
		if (bundleRules == null && collector.Errors > 0)
			return null;

		// Parse publish rules — emit deprecation warning when present
		if (rulesYaml.Publish != null)
			collector.EmitWarning(configPath, "rules.publish is deprecated and no longer used by the changelog render command. Move type/area filtering to rules.bundle, which applies at bundle time instead of render time.");

		// Note: rules.publish is no longer used by changelog render; set to null so it's never applied
		// The warning above alerts users they need to migrate to rules.bundle

		return new RulesConfiguration
		{
			Match = globalMatch,
			Create = createRules,
			Bundle = bundleRules,
			Publish = null  // rules.publish is retired; filtering happens at bundle time via rules.bundle
		};
	}

	private BundleRules? ParseBundleRules(
		IDiagnosticsCollector collector,
		BundleRulesYaml? yaml,
		string configPath,
		HashSet<string> validProductIds,
		MatchMode inheritedMatch)
	{
		if (yaml == null)
			return null;

		// Validate mutual exclusivity for products
		if (yaml.ExcludeProducts?.Values is { Count: > 0 } && yaml.IncludeProducts?.Values is { Count: > 0 })
		{
			collector.EmitError(configPath, "rules.bundle: cannot have both 'exclude_products' and 'include_products'. Use one or the other.");
			return null;
		}

		// Parse and validate product lists
		var excludeProducts = ParseAndValidateProductList(collector, yaml.ExcludeProducts, configPath, validProductIds, "rules.bundle.exclude_products");
		if (excludeProducts == null && collector.Errors > 0)
			return null;

		var includeProducts = ParseAndValidateProductList(collector, yaml.IncludeProducts, configPath, validProductIds, "rules.bundle.include_products");
		if (includeProducts == null && collector.Errors > 0)
			return null;

		// Parse match_products
		var matchProducts = inheritedMatch;
		if (!string.IsNullOrWhiteSpace(yaml.MatchProducts))
		{
			var parsed = ParseMatchMode(yaml.MatchProducts);
			if (parsed == null)
			{
				collector.EmitError(configPath, $"rules.bundle.match_products: '{yaml.MatchProducts}' is not valid. Use 'any', 'all', or 'conjunction'.");
				return null;
			}
			matchProducts = parsed.Value;
		}

		// Parse match_areas (inherited from globalMatch if omitted)
		var matchAreas = inheritedMatch;
		if (!string.IsNullOrWhiteSpace(yaml.MatchAreas))
		{
			var parsed = ParseMatchMode(yaml.MatchAreas);
			if (parsed == null)
			{
				collector.EmitError(configPath, $"rules.bundle.match_areas: '{yaml.MatchAreas}' is not valid. Use 'any', 'all', or 'conjunction'.");
				return null;
			}
			matchAreas = parsed.Value;
		}

		// Parse global type/area blocker (reusing PublishRulesYaml parsing logic)
		var blockerYaml = new PublishRulesYaml
		{
			MatchAreas = yaml.MatchAreas,
			ExcludeTypes = yaml.ExcludeTypes,
			IncludeTypes = yaml.IncludeTypes,
			ExcludeAreas = yaml.ExcludeAreas,
			IncludeAreas = yaml.IncludeAreas
		};
		var blocker = ParsePublishBlockerFromYaml(collector, blockerYaml, configPath, "rules.bundle", matchAreas);
		if (blocker == null && collector.Errors > 0)
			return null;

		// Parse per-product overrides
		Dictionary<string, BundlePerProductRule>? byProduct = null;
		if (yaml.Products is { Count: > 0 })
		{
			byProduct = new Dictionary<string, BundlePerProductRule>(StringComparer.OrdinalIgnoreCase);
			foreach (var (productKey, productYaml) in yaml.Products)
			{
				var productIds = productKey.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
				foreach (var productId in productIds)
				{
					var normalizedProductId = productId.Replace('_', '-');
					if (!validProductIds.Contains(normalizedProductId))
					{
						var availableProducts = string.Join(", ", validProductIds.OrderBy(p => p));
						collector.EmitError(configPath, $"rules.bundle.products: '{productId}' not in available products. Available: {availableProducts}");
						return null;
					}

					if (productYaml == null)
						continue;

					// Validate mutual exclusivity for products within this context
					if (productYaml.ExcludeProducts?.Values is { Count: > 0 } && productYaml.IncludeProducts?.Values is { Count: > 0 })
					{
						collector.EmitError(configPath, $"rules.bundle.products.{normalizedProductId}: cannot have both 'exclude_products' and 'include_products'. Use one or the other.");
						return null;
					}

					// Parse product lists for this context
					var contextExcludeProducts = ParseAndValidateProductList(collector, productYaml.ExcludeProducts, configPath, validProductIds, $"rules.bundle.products.{normalizedProductId}.exclude_products");
					if (contextExcludeProducts == null && collector.Errors > 0)
						return null;

					var contextIncludeProducts = ParseAndValidateProductList(collector, productYaml.IncludeProducts, configPath, validProductIds, $"rules.bundle.products.{normalizedProductId}.include_products");
					if (contextIncludeProducts == null && collector.Errors > 0)
						return null;

					// Mode 3: global rules.bundle product lists are not used for filtering — do not warn about
					// subset relationships between global and per-product include/exclude lists (would mislead authors).

					// Parse match_products for this context
					var contextMatchProducts = matchProducts;
					if (!string.IsNullOrWhiteSpace(productYaml.MatchProducts))
					{
						var parsed = ParseMatchMode(productYaml.MatchProducts);
						if (parsed == null)
						{
							collector.EmitError(configPath, $"rules.bundle.products.{normalizedProductId}.match_products: '{productYaml.MatchProducts}' is not valid. Use 'any', 'all', or 'conjunction'.");
							return null;
						}
						contextMatchProducts = parsed.Value;
					}

					// Validate per-product ineffective patterns
					if (contextMatchProducts == MatchMode.Any && contextIncludeProducts is { Count: > 0 })
					{
						collector.EmitWarning(configPath,
							$"Configuration pattern 'match_products: any' with 'include_products' in per-product rule '{normalizedProductId}' provides no selective filtering. " +
							"Consider 'match_products: all' for strict filtering or 'exclude_products' for exclusion-based filtering. " +
							"See: https://elastic.github.io/docs-builder/contribute/changelog/#ineffective-configuration-patterns");
					}

					// Detect disjoint products in per-product include_products
					if (contextIncludeProducts is { Count: > 1 })
					{
						var disjointProducts = contextIncludeProducts.Where(p =>
							!string.Equals(p, normalizedProductId, StringComparison.OrdinalIgnoreCase)).ToList();

						if (disjointProducts.Count > 0)
						{
							collector.EmitHint(configPath,
								$"Per-product rule '{normalizedProductId}' includes disjoint products [{string.Join(", ", disjointProducts)}] " +
								"which cannot be included due to single-product rule resolution. " +
								"Use separate bundles (each with a single product in output_products or profile output_products), or multi-product changelogs instead. " +
								"See: https://elastic.github.io/docs-builder/contribute/changelog/#ineffective-configuration-patterns");
						}
					}

					// Parse type/area blocker
					var productMatchAreas = matchAreas;
					if (!string.IsNullOrWhiteSpace(productYaml.MatchAreas))
					{
						var parsedMode = ParseMatchMode(productYaml.MatchAreas);
						if (parsedMode == null)
						{
							collector.EmitError(configPath, $"rules.bundle.products.{normalizedProductId}.match_areas: '{productYaml.MatchAreas}' is not valid. Use 'any', 'all', or 'conjunction'.");
							return null;
						}
						productMatchAreas = parsedMode.Value;
					}

					var productBlockerYaml = new PublishRulesYaml
					{
						MatchAreas = productYaml.MatchAreas,
						ExcludeTypes = productYaml.ExcludeTypes,
						IncludeTypes = productYaml.IncludeTypes,
						ExcludeAreas = productYaml.ExcludeAreas,
						IncludeAreas = productYaml.IncludeAreas
					};
					var productBlocker = ParsePublishBlockerFromYaml(collector, productBlockerYaml, configPath, $"rules.bundle.products.{normalizedProductId}", productMatchAreas);
					if (productBlocker == null && collector.Errors > 0)
						return null;

					// Create per-product rule if any rules are defined (product filtering OR type/area blocking)
					if (productBlocker != null || contextIncludeProducts != null || contextExcludeProducts != null)
					{
						byProduct[normalizedProductId] = new BundlePerProductRule
						{
							Blocker = productBlocker,
							IncludeProducts = contextIncludeProducts,
							ExcludeProducts = contextExcludeProducts,
							MatchProducts = contextMatchProducts
						};
					}
				}
			}
		}

		if (yaml.Products is { Count: > 0 })
		{
			var hasGlobalProductFilters = (excludeProducts?.Count ?? 0) > 0 || (includeProducts?.Count ?? 0) > 0;
			if (hasGlobalProductFilters || blocker != null)
			{
				collector.EmitHint(configPath,
					"rules.bundle: When 'products' is present, global include_products, exclude_products, and type/area rules are not applied for filtering; configure filters under each product key or use global-only rules.bundle (no 'products' section). " +
					"See: https://elastic.github.io/docs-builder/contribute/changelog/#bundle-rule-modes");
			}
		}

		return new BundleRules
		{
			ExcludeProducts = excludeProducts,
			IncludeProducts = includeProducts,
			MatchProducts = matchProducts,
			Blocker = blocker,
			ByProduct = byProduct?.Count > 0 ? byProduct : null
		};
	}

	private static IReadOnlyList<string>? ParseAndValidateProductList(
		IDiagnosticsCollector collector,
		YamlLenientList? list,
		string configPath,
		HashSet<string> validProductIds,
		string fieldPath)
	{
		if (list?.Values is not { Count: > 0 } values)
			return null;

		var result = new List<string>();
		foreach (var rawId in values)
		{
			var normalizedId = rawId.Replace('_', '-');
			if (!validProductIds.Contains(normalizedId))
			{
				var availableProducts = string.Join(", ", validProductIds.OrderBy(p => p));
				collector.EmitError(configPath, $"{fieldPath}: '{rawId}' is not in the list of available products. Available products: {availableProducts}");
				return null;
			}
			result.Add(normalizedId);
		}
		return result;
	}

	private CreateRules? ParseCreateRules(
		IDiagnosticsCollector collector,
		CreateRulesYaml? yaml,
		string configPath,
		HashSet<string> validProductIds,
		string path,
		MatchMode inheritedMatch)
	{
		if (yaml == null)
			return null;

		// Validate mutual exclusivity
		if (yaml.Exclude?.Values is { Count: > 0 } && yaml.Include?.Values is { Count: > 0 })
		{
			collector.EmitError(configPath, $"{path}: cannot have both 'exclude' and 'include'. Use one or the other.");
			return null;
		}

		// Parse match mode
		var match = inheritedMatch;
		if (!string.IsNullOrWhiteSpace(yaml.Match))
		{
			var parsed = ParseMatchMode(yaml.Match);
			if (parsed == null)
			{
				collector.EmitError(configPath, $"{path}.match: '{yaml.Match}' is not valid. Use 'any', 'all', or 'conjunction'.");
				return null;
			}
			match = parsed.Value;
		}

		var mode = yaml.Include?.Values is { Count: > 0 } ? FieldMode.Include : FieldMode.Exclude;
		var labels = mode == FieldMode.Include ? yaml.Include?.Values : yaml.Exclude?.Values;

		// Parse per-product overrides
		Dictionary<string, CreateRules>? byProduct = null;
		if (yaml.Products is { Count: > 0 })
		{
			byProduct = new Dictionary<string, CreateRules>(StringComparer.OrdinalIgnoreCase);
			foreach (var (productKey, productYaml) in yaml.Products)
			{
				var productIds = productKey.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
				foreach (var productId in productIds)
				{
					var normalizedProductId = productId.Replace('_', '-');
					if (!validProductIds.Contains(normalizedProductId))
					{
						var availableProducts = string.Join(", ", validProductIds.OrderBy(p => p));
						collector.EmitError(configPath, $"{path}.products: '{productId}' not in available products. Available: {availableProducts}");
						return null;
					}

					var productRules = ParseCreateRules(collector, productYaml, configPath, validProductIds, $"{path}.products.{normalizedProductId}", match);
					if (productRules == null && collector.Errors > 0)
						return null;
					if (productRules != null)
						byProduct[normalizedProductId] = productRules;
				}
			}
		}

		return new CreateRules
		{
			Labels = labels,
			Mode = mode,
			Match = match,
			ByProduct = byProduct
		};
	}

	private PublishRules? ParsePublishRules(
		IDiagnosticsCollector collector,
		PublishRulesYaml? yaml,
		string configPath,
		HashSet<string> validProductIds,
		string path,
		MatchMode inheritedMatch)
	{
		if (yaml == null)
			return null;

		// Parse match_areas
		var matchAreas = inheritedMatch;
		if (!string.IsNullOrWhiteSpace(yaml.MatchAreas))
		{
			var parsed = ParseMatchMode(yaml.MatchAreas);
			if (parsed == null)
			{
				collector.EmitError(configPath, $"{path}.match_areas: '{yaml.MatchAreas}' is not valid. Use 'any', 'all', or 'conjunction'.");
				return null;
			}
			matchAreas = parsed.Value;
		}

		// Parse global publish blocker
		var blocker = ParsePublishBlockerFromYaml(collector, yaml, configPath, path, matchAreas);
		if (blocker == null && collector.Errors > 0)
			return null;

		// Parse per-product overrides
		Dictionary<string, PublishBlocker>? byProduct = null;
		if (yaml.Products is { Count: > 0 })
		{
			byProduct = new Dictionary<string, PublishBlocker>(StringComparer.OrdinalIgnoreCase);
			foreach (var (productKey, productYaml) in yaml.Products)
			{
				var productIds = productKey.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
				foreach (var productId in productIds)
				{
					var normalizedProductId = productId.Replace('_', '-');
					if (!validProductIds.Contains(normalizedProductId))
					{
						var availableProducts = string.Join(", ", validProductIds.OrderBy(p => p));
						collector.EmitError(configPath, $"{path}.products: '{productId}' not in available products. Available: {availableProducts}");
						return null;
					}

					if (productYaml == null)
						continue;

					var productMatchAreas = matchAreas;
					if (!string.IsNullOrWhiteSpace(productYaml.MatchAreas))
					{
						var parsed = ParseMatchMode(productYaml.MatchAreas);
						if (parsed == null)
						{
							collector.EmitError(configPath, $"{path}.products.{normalizedProductId}.match_areas: '{productYaml.MatchAreas}' is not valid. Use 'any', 'all', or 'conjunction'.");
							return null;
						}
						productMatchAreas = parsed.Value;
					}

					var productBlocker = ParsePublishBlockerFromYaml(collector, productYaml, configPath, $"{path}.products.{normalizedProductId}", productMatchAreas);
					if (productBlocker == null && collector.Errors > 0)
						return null;
					if (productBlocker != null)
						byProduct[normalizedProductId] = productBlocker;
				}
			}
		}

		return new PublishRules
		{
			Blocker = blocker,
			ByProduct = byProduct
		};
	}

	private static PublishBlocker? ParsePublishBlockerFromYaml(
		IDiagnosticsCollector collector,
		PublishRulesYaml yaml,
		string configPath,
		string path,
		MatchMode matchAreas)
	{
		// Validate mutual exclusivity for types
		var excludeTypes = yaml.ExcludeTypes?.Values;
		var includeTypes = yaml.IncludeTypes?.Values;
		if (excludeTypes is { Count: > 0 } && includeTypes is { Count: > 0 })
		{
			collector.EmitError(configPath, $"{path}: cannot have both 'exclude_types' and 'include_types'. Use one or the other.");
			return null;
		}

		// Validate mutual exclusivity for areas
		var excludeAreas = yaml.ExcludeAreas?.Values;
		var includeAreas = yaml.IncludeAreas?.Values;
		if (excludeAreas is { Count: > 0 } && includeAreas is { Count: > 0 })
		{
			collector.EmitError(configPath, $"{path}: cannot have both 'exclude_areas' and 'include_areas'. Use one or the other.");
			return null;
		}

		var types = excludeTypes ?? includeTypes;
		var areas = excludeAreas ?? includeAreas;

		if ((types == null || types.Count == 0) && (areas == null || areas.Count == 0))
			return null;

		var typesMode = includeTypes is { Count: > 0 } ? FieldMode.Include : FieldMode.Exclude;
		var areasMode = includeAreas is { Count: > 0 } ? FieldMode.Include : FieldMode.Exclude;

		return new PublishBlocker
		{
			Types = types?.Count > 0 ? types.ToList() : null,
			TypesMode = typesMode,
			Areas = areas?.Count > 0 ? areas.ToList() : null,
			AreasMode = areasMode,
			MatchAreas = matchAreas
		};
	}

	private static PublishBlocker? ParsePublishBlocker(PublishRulesYaml? yaml, MatchMode matchAreas)
	{
		if (yaml == null)
			return null;

		var excludeTypes = yaml.ExcludeTypes?.Values;
		var includeTypes = yaml.IncludeTypes?.Values;
		var excludeAreas = yaml.ExcludeAreas?.Values;
		var includeAreas = yaml.IncludeAreas?.Values;

		var types = excludeTypes ?? includeTypes;
		var areas = excludeAreas ?? includeAreas;

		if ((types == null || types.Count == 0) && (areas == null || areas.Count == 0))
			return null;

		return new PublishBlocker
		{
			Types = types?.Count > 0 ? types.ToList() : null,
			TypesMode = includeTypes is { Count: > 0 } ? FieldMode.Include : FieldMode.Exclude,
			Areas = areas?.Count > 0 ? areas.ToList() : null,
			AreasMode = includeAreas is { Count: > 0 } ? FieldMode.Include : FieldMode.Exclude,
			MatchAreas = matchAreas
		};
	}

	private static MatchMode? ParseMatchMode(string? value) =>
		value?.ToLowerInvariant() switch
		{
			"any" => MatchMode.Any,
			"all" => MatchMode.All,
			"conjunction" => MatchMode.Conjunction,
			_ => string.IsNullOrWhiteSpace(value) ? null : null
		};

	/// <summary>
	/// Builds LabelToType mapping by inverting pivot.types entries.
	/// Each label in a type entry maps to that type name.
	/// </summary>
	private static Dictionary<string, string>? BuildLabelToTypeMapping(Dictionary<string, TypeEntryYaml?>? types)
	{
		if (types == null || types.Count == 0)
			return null;

		var labelToType = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);

		foreach (var (typeName, entry) in types)
		{
			if (entry?.Labels == null)
				continue;

			var labels = entry.Labels.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
			foreach (var label in labels)
				labelToType[label] = typeName;
		}

		return labelToType.Count > 0 ? labelToType : null;
	}

	/// <summary>
	/// Builds LabelToAreas mapping by inverting pivot.areas entries.
	/// Each label in an area entry maps to that area name. The same label may appear under multiple areas; all area names are collected.
	/// </summary>
	private static Dictionary<string, List<string>>? BuildLabelToAreasMapping(Dictionary<string, YamlLenientList?>? areas)
	{
		if (areas == null || areas.Count == 0)
			return null;

		var labelToAreas = new Dictionary<string, List<string>>(StringComparer.OrdinalIgnoreCase);

		foreach (var (areaName, labelList) in areas)
		{
			if (labelList?.Values == null)
				continue;

			foreach (var label in labelList.Values)
			{
				if (!labelToAreas.TryGetValue(label, out var areaNames))
				{
					areaNames = [];
					labelToAreas[label] = areaNames;
				}

				if (!areaNames.Exists(a => a.Equals(areaName, StringComparison.OrdinalIgnoreCase)))
					areaNames.Add(areaName);
			}
		}

		return labelToAreas.Count > 0 ? labelToAreas : null;
	}

	/// <summary>
	/// Builds LabelToProducts mapping by inverting pivot.products entries.
	/// Each label in a product entry maps to that product spec string.
	/// </summary>
	private static Dictionary<string, string>? BuildLabelToProductsMapping(Dictionary<string, YamlLenientList?>? products)
	{
		if (products == null || products.Count == 0)
			return null;

		var labelToProducts = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);

		foreach (var (productSpec, labelList) in products)
		{
			if (labelList?.Values == null)
				continue;

			foreach (var label in labelList.Values)
				labelToProducts[label] = productSpec;
		}

		return labelToProducts.Count > 0 ? labelToProducts : null;
	}
}