Add support for diagnostic hints and track unused substitution keys

[Mpdreamz]

Introduced a "Hint" severity level to diagnostics for improvement suggestions. Enhanced substitution tracking to collect unused keys and provide hints, optimizing substitution usage. Updated console and GitHub outputs to display diagnostic hints alongside errors and warnings for better feedback.

Hints have no bearing on the exit code of docs-builder.

If there are too many variables it will be emitted as a single hint.

Built to aid with the work ongoing at: elastic/docs-content#811

[Copilot]

Pull Request Overview

This PR adds support for diagnostic hints and tracks unused substitution keys to improve feedback and optimize substitution usage in documentation generation. Key changes include:

• Introducing a new Hint severity level and the HintUnusedSubstitutionKeys() method in DocumentationGenerator.
• Updating diagnostics logging, console and GitHub outputs to handle hints alongside errors and warnings.
• Modifying substitution replacement calls throughout the codebase to pass the diagnostics collector for tracking key usage.

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Elastic.Markdown/DocumentationGenerator.cs	Added HintUnusedSubstitutionKeys() to emit hints for unused substitution keys.
src/Elastic.Documentation.Tooling/Diagnostics/Console/ErrataFileSourceRepository.cs	Updated WriteDiagnosticsToConsole to process hints along with errors and warnings.
src/Elastic.Markdown/Diagnostics/DiagnosticsChannel.cs	Introduced new Severity enum values and refactored emission methods to support the Hint level.
src/Elastic.Documentation.Tooling/Diagnostics/Console/GithubAnnotationOutput.cs	Mapped Hint severity to WriteNotice for GitHub output.
src/Elastic.Documentation.Tooling/Diagnostics/Log.cs	Adjusted logging implementation to account for the new Hint severity.
src/Elastic.Markdown/Helpers/Interpolation.cs	Updated substitution replacement calls to pass the DiagnosticsCollector for tracking key usage.
src/Elastic.Documentation.Tooling/Diagnostics/Console/ConsoleDiagnosticsCollector.cs	Collected and displayed diagnostic hints in the console output.
src/Elastic.Markdown/IO/MarkdownFile.cs	Updated substitution replacement usage to include the collector.
tests/Elastic.Markdown.Tests/Interpolation/InterpolationTests.cs	Revised tests to support the updated substitution method signature.
src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlockParser.cs	Updated substitution replacements within code block processing to pass the collector.

Comments suppressed due to low confidence (2)

src/Elastic.Markdown/DocumentationGenerator.cs:90

• [nitpick] Consider clarifying the threshold logic for unused substitution keys. The current condition groups keys if there are 20 or more unused keys; if this behavior is intentional, a brief comment would help future maintainers.

HintUnusedSubstitutionKeys();

src/Elastic.Markdown/Helpers/Interpolation.cs:26

• [nitpick] Consider updating the method's documentation (or comments) to reflect the new collector parameter to assist other developers in understanding that substitution key usage is now being tracked.

return span.ReplaceSubstitutions([context.Substitutions, context.ContextSubstitutions], context.Build.Collector, out var replacement)