Hints and suppresshints

Author: Mpdreamz

src/Elastic.Documentation.Configuration/ConfigurationFileProvider.cs

@@ -5,6 +5,7 @@
 using System.IO.Abstractions;
 using System.Text.RegularExpressions;
 using Elastic.Documentation.Configuration.Assembler;
+using Elastic.Documentation.Configuration.Converters;
 using Elastic.Documentation.Configuration.DocSet;
 using Elastic.Documentation.Configuration.Serialization;
 using Microsoft.Extensions.DependencyInjection;
@@ -22,6 +23,7 @@ public partial class ConfigurationFileProvider
 
 	public static IDeserializer Deserializer { get; } = new StaticDeserializerBuilder(new YamlStaticContext())
 		.WithNamingConvention(UnderscoredNamingConvention.Instance)
+		.WithTypeConverter(new HintTypeSetConverter())
 		.WithTypeConverter(new TocItemCollectionYamlConverter())
 		.WithTypeConverter(new TocItemYamlConverter())
 		.WithTypeConverter(new SiteTableOfContentsCollectionYamlConverter())

src/Elastic.Documentation.Configuration/Converters/HintTypeSetConverter.cs

@@ -0,0 +1,67 @@
+// 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 Elastic.Documentation.Diagnostics;
+using YamlDotNet.Core;
+using YamlDotNet.Core.Events;
+using YamlDotNet.Serialization;
+
+namespace Elastic.Documentation.Configuration.Converters;
+
+/// <summary>
+/// YAML converter for deserializing a list of strings into a HashSet of HintType enums.
+/// </summary>
+public class HintTypeSetConverter : IYamlTypeConverter
+{
+	public bool Accepts(Type type) => type == typeof(HashSet<HintType>);
+
+	public object? ReadYaml(IParser parser, Type type, ObjectDeserializer rootDeserializer)
+	{
+		var result = new HashSet<HintType>();
+
+		// Handle null/empty case
+		if (parser.Current is not SequenceStart)
+		{
+			_ = parser.MoveNext();
+			return result;
+		}
+
+		_ = parser.MoveNext(); // Skip SequenceStart
+
+		while (parser.Current is not SequenceEnd)
+		{
+			if (parser.Current is Scalar scalar)
+			{
+				var value = scalar.Value;
+				if (!string.IsNullOrWhiteSpace(value) &&
+					Enum.TryParse<HintType>(value, ignoreCase: true, out var hintType))
+				{
+					_ = result.Add(hintType);
+				}
+			}
+			_ = parser.MoveNext();
+		}
+
+		_ = parser.MoveNext(); // Skip SequenceEnd
+
+		return result;
+	}
+
+	public void WriteYaml(IEmitter emitter, object? value, Type type, ObjectSerializer serializer)
+	{
+		if (value is not HashSet<HintType> set)
+		{
+			emitter.Emit(new SequenceStart(null, null, false, SequenceStyle.Block));
+			emitter.Emit(new SequenceEnd());
+			return;
+		}
+
+		emitter.Emit(new SequenceStart(null, null, false, SequenceStyle.Block));
+		foreach (var hint in set)
+		{
+			emitter.Emit(new Scalar(hint.ToString()));
+		}
+		emitter.Emit(new SequenceEnd());
+	}
+}

src/Elastic.Documentation.Configuration/DocSet/DocumentationSetFile.cs

@@ -5,6 +5,7 @@
 using System.IO.Abstractions;
 using Elastic.Documentation.Configuration.Products;
 using Elastic.Documentation.Diagnostics;
+using Elastic.Documentation.Extensions;
 using YamlDotNet.Core;
 using YamlDotNet.Core.Events;
 using YamlDotNet.Serialization;
@@ -20,6 +21,13 @@ public class TableOfContentsFile
 	[YamlMember(Alias = "toc")]
 	public TableOfContents TableOfContents { get; set; } = [];
 
+	/// <summary>
+	/// Set of diagnostic hint types to suppress. Deserialized directly from YAML list of strings.
+	/// Valid values: "DeepLinkingVirtualFile", "FolderFileNameMismatch"
+	/// </summary>
+	[YamlMember(Alias = "suppress")]
+	public HashSet<HintType> SuppressDiagnostics { get; set; } = [];
+
 	public static TableOfContentsFile Deserialize(string json) =>
 		ConfigurationFileProvider.Deserializer.Deserialize<TableOfContentsFile>(json);
 }
@@ -93,8 +101,8 @@ public static DocumentationSetFile LoadAndResolve(IDiagnosticsCollector collecto
 	{
 		fileSystem ??= sourceDirectory.FileSystem;
 		var docSet = Deserialize(yaml);
-		var docsetPath = fileSystem.Path.Combine(sourceDirectory.FullName, "docset.yml");
-		docSet.TableOfContents = ResolveTableOfContents(collector, docSet.TableOfContents, sourceDirectory, fileSystem, parentPath: "", context: docsetPath);
+		var docsetPath = fileSystem.Path.Combine(sourceDirectory.FullName, "docset.yml").OptionalWindowsReplace();
+		docSet.TableOfContents = ResolveTableOfContents(collector, docSet.TableOfContents, sourceDirectory, fileSystem, parentPath: "", context: docsetPath, docSet.SuppressDiagnostics);
 		return docSet;
 	}
 
@@ -111,7 +119,8 @@ private static TableOfContents ResolveTableOfContents(
 		IDirectoryInfo baseDirectory,
 		IFileSystem fileSystem,
 		string parentPath,
-		string context
+		string context,
+		HashSet<HintType>? suppressDiagnostics = null
 	)
 	{
 		var resolved = new TableOfContents();
@@ -120,9 +129,9 @@ string context
 		{
 			var resolvedItem = item switch
 			{
-				IsolatedTableOfContentsRef tocRef => ResolveIsolatedToc(collector, tocRef, baseDirectory, fileSystem, parentPath, context),
-				FileRef fileRef => ResolveFileRef(collector, fileRef, baseDirectory, fileSystem, parentPath, context),
-				FolderRef folderRef => ResolveFolderRef(collector, folderRef, baseDirectory, fileSystem, parentPath, context),
+				IsolatedTableOfContentsRef tocRef => ResolveIsolatedToc(collector, tocRef, baseDirectory, fileSystem, parentPath, context, suppressDiagnostics),
+				FileRef fileRef => ResolveFileRef(collector, fileRef, baseDirectory, fileSystem, parentPath, context, suppressDiagnostics),
+				FolderRef folderRef => ResolveFolderRef(collector, folderRef, baseDirectory, fileSystem, parentPath, context, suppressDiagnostics),
 				CrossLinkRef crossLink => ResolveCrossLinkRef(collector, crossLink, baseDirectory, fileSystem, parentPath, context),
 				_ => null
 			};
@@ -139,14 +148,17 @@ string context
 	/// Validates that the TOC has no children in parent YAML and that toc.yml exists.
 	/// The TOC's path is set to the full path (including parent path) for consistency with files and folders.
 	/// </summary>
+#pragma warning disable IDE0060 // Remove unused parameter - suppressDiagnostics is for consistency, nested TOCs use their own suppression config
 	private static ITableOfContentsItem? ResolveIsolatedToc(
 		IDiagnosticsCollector collector,
 		IsolatedTableOfContentsRef tocRef,
 		IDirectoryInfo baseDirectory,
 		IFileSystem fileSystem,
 		string parentPath,
-		string parentContext
+		string parentContext,
+		HashSet<HintType>? suppressDiagnostics = null
 	)
+#pragma warning restore IDE0060
 	{
 		// TOC paths containing '/' are treated as relative to the context file's directory (full paths).
 		// Simple TOC names (no '/') are resolved relative to the parent path in the navigation hierarchy.
@@ -190,12 +202,31 @@ string parentContext
 		}
 
 		var tocYaml = fileSystem.File.ReadAllText(tocFilePath);
-		var tocFile = TableOfContentsFile.Deserialize(tocYaml);
+		var nestedTocFile = TableOfContentsFile.Deserialize(tocYaml);
+
+		// this is temporary after this lands in main we can update these files to include
+		// suppress:
+		//	- DeepLinkingVirtualFile
+		string[] skip = [
+			"docs-content/solutions/toc.yml",
+			"docs-content/manage-data/toc.yml",
+			"docs-content/explore-analyze/toc.yml",
+			"docs-content/deploy-manage/toc.yml",
+			"docs-content/troubleshoot/toc.yml",
+			"docs-content/troubleshoot/ingest/opentelemetry/toc.yml",
+			"docs-content/reference/security/toc.yml"
+		];
+
+		var path = tocFilePath.OptionalWindowsReplace();
+		// Hardcode suppression for known problematic files
+		if (skip.Any(f => path.Contains(f, StringComparison.OrdinalIgnoreCase)))
+			_ = nestedTocFile.SuppressDiagnostics.Add(HintType.DeepLinkingVirtualFile);
+
 
 		// Recursively resolve children with the FULL TOC path as the parent path
 		// This ensures all file paths within the TOC include the TOC directory path
 		// The context for children is the toc.yml file that defines them
-		var resolvedChildren = ResolveTableOfContents(collector, tocFile.TableOfContents, baseDirectory, fileSystem, fullTocPath, tocFilePath);
+		var resolvedChildren = ResolveTableOfContents(collector, nestedTocFile.TableOfContents, baseDirectory, fileSystem, fullTocPath, tocFilePath, nestedTocFile.SuppressDiagnostics);
 
 		// Validate: TOC must have at least one child
 		if (resolvedChildren.Count == 0)
@@ -218,7 +249,8 @@ private static ITableOfContentsItem ResolveFileRef(
 		IDirectoryInfo baseDirectory,
 		IFileSystem fileSystem,
 		string parentPath,
-		string context)
+		string context,
+		HashSet<HintType>? suppressDiagnostics = null)
 	{
 		var fullPath = string.IsNullOrEmpty(parentPath) ? fileRef.Path : $"{parentPath}/{fileRef.Path}";
 
@@ -241,18 +273,22 @@ private static ITableOfContentsItem ResolveFileRef(
 			// Only check if we're in a folder context (parentPath is not empty)
 			if (!string.IsNullOrEmpty(parentPath) && fileName != "index.md")
 			{
-				// Extract just the folder name from parentPath (in case it's nested like "guides/getting-started")
-				var folderName = parentPath.Contains('/') ? parentPath.Split('/')[^1] : parentPath;
+				// Check if this hint type should be suppressed
+				if (!suppressDiagnostics.ShouldSuppress(HintType.FolderFileNameMismatch))
+				{
+					// Extract just the folder name from parentPath (in case it's nested like "guides/getting-started")
+					var folderName = parentPath.Contains('/') ? parentPath.Split('/')[^1] : parentPath;
 
-				// Normalize for comparison: remove hyphens, underscores, and lowercase
-				// This allows "getting-started" to match "GettingStarted" or "getting_started"
-				var normalizedFile = fileWithoutExtension.Replace("-", "", StringComparison.Ordinal).Replace("_", "", StringComparison.Ordinal).ToLowerInvariant();
-				var normalizedFolder = folderName.Replace("-", "", StringComparison.Ordinal).Replace("_", "", StringComparison.Ordinal).ToLowerInvariant();
+					// Normalize for comparison: remove hyphens, underscores, and lowercase
+					// This allows "getting-started" to match "GettingStarted" or "getting_started"
+					var normalizedFile = fileWithoutExtension.Replace("-", "", StringComparison.Ordinal).Replace("_", "", StringComparison.Ordinal).ToLowerInvariant();
+					var normalizedFolder = folderName.Replace("-", "", StringComparison.Ordinal).Replace("_", "", StringComparison.Ordinal).ToLowerInvariant();
 
-				if (!normalizedFile.Equals(normalizedFolder, StringComparison.Ordinal))
-				{
-					collector.EmitHint(context,
-						$"File name '{fileName}' does not match folder name '{folderName}'. Best practice is to name the file the same as the folder (e.g., 'folder: {folderName}, file: {folderName}.md').");
+					if (!normalizedFile.Equals(normalizedFolder, StringComparison.Ordinal))
+					{
+						collector.EmitHint(context,
+							$"File name '{fileName}' does not match folder name '{folderName}'. Best practice is to name the file the same as the folder (e.g., 'folder: {folderName}, file: {folderName}.md').");
+					}
 				}
 			}
 		}
@@ -272,8 +308,12 @@ private static ITableOfContentsItem ResolveFileRef(
 		// This suggests using 'folder' instead of 'file' would be better
 		if (fileRef.Path.Contains('/') && fileRef.Children.Count > 0 && fileRef is not FolderIndexFileRef)
 		{
-			collector.EmitHint(context,
-				$"File '{fileRef.Path}' uses deep-linking with children. Consider using 'folder' instead of 'file' for better navigation structure. Virtual files are primarily intended to group sibling files together.");
+			// Check if this hint type should be suppressed
+			if (!suppressDiagnostics.ShouldSuppress(HintType.DeepLinkingVirtualFile))
+			{
+				collector.EmitHint(context,
+					$"File '{fileRef.Path}' uses deep-linking with children. Consider using 'folder' instead of 'file' for better navigation structure. Virtual files are primarily intended to group sibling files together.");
+			}
 		}
 
 		// Children of a file should be resolved in the same directory as the parent file.
@@ -304,7 +344,7 @@ private static ITableOfContentsItem ResolveFileRef(
 			parentPathForChildren = parentPath;
 		}
 
-		var resolvedChildren = ResolveTableOfContents(collector, fileRef.Children, baseDirectory, fileSystem, parentPathForChildren, context);
+		var resolvedChildren = ResolveTableOfContents(collector, fileRef.Children, baseDirectory, fileSystem, parentPathForChildren, context, suppressDiagnostics);
 
 		// Preserve the specific type when creating the resolved reference
 		return fileRef switch
@@ -325,7 +365,8 @@ private static ITableOfContentsItem ResolveFolderRef(
 		IDirectoryInfo baseDirectory,
 		IFileSystem fileSystem,
 		string parentPath,
-		string context)
+		string context,
+		HashSet<HintType>? suppressDiagnostics = null)
 	{
 		// Folder paths containing '/' are treated as relative to the context file's directory (full paths).
 		// Simple folder names (no '/') are resolved relative to the parent path in the navigation hierarchy.
@@ -351,7 +392,7 @@ private static ITableOfContentsItem ResolveFolderRef(
 		// If children are explicitly defined, resolve them
 		if (folderRef.Children.Count > 0)
 		{
-			var resolvedChildren = ResolveTableOfContents(collector, folderRef.Children, baseDirectory, fileSystem, fullPath, context);
+			var resolvedChildren = ResolveTableOfContents(collector, folderRef.Children, baseDirectory, fileSystem, fullPath, context, suppressDiagnostics);
 			return new FolderRef(fullPath, resolvedChildren, context);
 		}