Add SnippetValidator tool to check code example introductions match referenced snippets

[Copilot]

This PR introduces a new validation tool that automatically checks if code example introductions in XML documentation files accurately match the content of their referenced code snippets.

Problem

The .NET API documentation contains thousands of code examples with introductory text that describes what the code demonstrates. However, there's currently no automated way to verify that these introductions actually match the code being shown. This can lead to documentation inconsistencies where:

• Introduction mentions LoadAsync but the snippet uses synchronous Load()
• Documentation describes synchronous operations but the code shows async patterns
• Introduction references methods or classes not actually demonstrated in the snippet

Solution

The SnippetValidator tool provides automated validation by:

1. Scanning XML files for snippet references like :::code language="csharp" source="~/snippets/..." id="Snippet1":::
2. Extracting introduction text from the lines preceding each snippet reference
3. Parsing snippet files to extract the actual code within specific snippet boundaries (<snippet1> to </snippet1>)
4. Analyzing mismatches using intelligent pattern matching to identify legitimate inconsistencies

Usage

The tool supports multiple operation modes:

# Quick demonstration on sample files
dotnet run -- --sample

# Test specific known files
dotnet run -- --test

# Full repository validation (18,000+ XML files)
dotnet run

Example Issues Found

The tool successfully identifies real documentation problems:

LoadAsync vs Load Method Mismatch:

• File: System.Media/SoundPlayer.xml:348
• Issue: Introduction mentions LoadAsync method but snippet uses synchronous Load() method

Async/Sync Operation Mismatch:

• File: System.Media/SoundPlayer.xml:855
• Issue: Introduction mentions synchronous PlaySync operations but snippet contains async loading code

Features

• Smart filtering to minimize false positives while catching real issues
• Detailed reporting with file names, line numbers, and specific mismatch descriptions
• Scalable processing with progress indicators for large-scale validation
• Multiple output formats suitable for CI/CD integration

This tool helps maintain documentation quality by automatically detecting when code example descriptions drift from their actual implementations.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.