feat: Add automated compilation validation for C# code examples

[currantw]

Summary

Add automated compilation validation for C# code examples in XML doc comments:

• Python script that extract and validates examples.
• New task check-examples command and GitHub check-examples workflow.
• Fixed existing failures.

NOTE: This pull request is only intended to add validation of examples. Add new examples and ensuring examples are consistent will be completed in #340.

Issue Link

Closes #347

Features and Behaviour Changes

• New scripts/check_examples.py script with two classes:
  • ExampleExtractor: scans .cs files under sources/ and extracts code examples from XML doc comments using multi-line regex.
  • ExampleChecker: generates a temporary .NET project referencing the built Valkey.Glide.dll, wraps each example in a compilable C# class, runs dotnet build, and reports compilation errors mapped back to source file and line number.
• New task check-examples Taskfile entry for local execution.
• New check-examples GitHub Actions workflow that runs on push/PR to validate examples in CI.
• Script supports an optional --examples flag to load examples from a JSON file instead of extracting from source.

Implementation

• Examples are extracted using a multi-line regex that matches code examples.
• Each example is wrapped in a class, including default using directives for common Valkey GLIDE namespaces and types.
• The temporary .NET project references the built DLL directly.
• Build errors are parsed using the MSBuild canonical error format regex and mapped back to source files via generated filenames.

Limitations

• The script requires the Valkey.Glide project to be built first (dotnet build).

Testing

• All 314 extracted examples compile successfully with task check-examples.
• Verified error detection works correctly with intentionally broken examples.

Related Issues

• valkey-glide-docs#193: Add automated compilation validation for C# code examples
• task(docs): clean up public command API documentation #340

Checklist

• This Pull Request is related to one issue.
• Commit message has a detailed description of what changed and why.
• Tests are added or updated and all checks pass.
• CHANGELOG.md, README.md, DEVELOPER.md, and other documentation files are updated.
• Destination branch is correct - main or release
• Create merge commit if merging release branch into main, squash otherwise.

[Copilot]

Pull request overview

Adds CI/local tooling to automatically extract C# XML-doc <example><code> snippets from sources/ and validate them by compiling against the built Valkey.Glide.dll, while updating existing doc examples to compile cleanly under the new validator.

Changes:

• Added scripts/check_examples.py to extract examples and compile-check them via a temporary .NET project.
• Added task check-examples and a new check-examples GitHub Actions workflow to run the validator in CI.
• Updated numerous XML doc examples and a few small internal/formatting items to eliminate compilation failures.

Reviewed changes

Copilot reviewed 31 out of 32 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
sources/Valkey.Glide/PubSubSubscriptionConfig.cs	Fixes an XML doc comment formatting issue that would break example extraction/parsing.
sources/Valkey.Glide/Internals/GuardClauses.cs	Removes a stream trim-mode guard helper (moved elsewhere).
sources/Valkey.Glide/Internals/FFI.structs.cs	Adds TODO notes on struct immutability/constructors (no functional change).
sources/Valkey.Glide/Commands/ITransactionClusterCommands.cs	Updates doc example variable names to align with cluster client usage.
sources/Valkey.Glide/Commands/ISortedSetBaseCommands.cs	Updates doc examples to use concrete keys/values so they compile.
sources/Valkey.Glide/Commands/ISetBaseCommands.cs	Updates doc examples to use concrete keys/values so they compile.
sources/Valkey.Glide/Commands/IListBaseCommands.cs	Updates doc examples (types/keys) to compile under validation harness.
sources/Valkey.Glide/Commands/IHashBaseCommands.cs	Updates hash command examples to compile (concrete values; fixes malformed tags).
sources/Valkey.Glide/Commands/IGenericCommands.cs	Updates batch/pipeline examples to match current async batch APIs/options.
sources/Valkey.Glide/Commands/IGenericClusterCommands.cs	Updates cluster batch/custom command examples to match current APIs and compile.
sources/Valkey.Glide/Client/IGlideClusterClient.cs	Adjusts cluster client examples to match ClusterValue API and null handling.
sources/Valkey.Glide/Client/IGlideClusterClient.ServerManagementCommands.cs	Updates Info/server-management examples for compilation and correct LINQ usage.
sources/Valkey.Glide/Client/IGlideClusterClient.ScriptingAndFunctionCommands.cs	Updates scripting/function examples (routes, payload variables) for compilation.
sources/Valkey.Glide/Client/IGlideClient.cs	Updates examples to define typed keys used by APIs.
sources/Valkey.Glide/Client/IGlideClient.ServerManagementCommands.cs	Updates example to avoid unsupported syntax and compile reliably.
sources/Valkey.Glide/Client/IBaseClient.SortedSetCommands.cs	Updates scan example to define a key variable for compilation.
sources/Valkey.Glide/Client/IBaseClient.SetCommands.cs	Updates scan example to define a key variable for compilation.
sources/Valkey.Glide/Client/IBaseClient.ServerManagementCommands.cs	Updates examples to declare locals/arrays explicitly for compilation.
sources/Valkey.Glide/Client/IBaseClient.ScriptingAndFunctionCommands.cs	Updates scripting/function examples to include required local variables.
sources/Valkey.Glide/Client/IBaseClient.PubSubCommands.cs	Updates pub/sub examples to use ValkeyKey[] where required.
sources/Valkey.Glide/Client/IBaseClient.ListCommands.cs	Updates list command examples with concrete keys/values and compilable literals.
sources/Valkey.Glide/Client/IBaseClient.GenericCommands.cs	Updates generic command examples to be compilable and more explicit in outputs.
sources/Valkey.Glide/Client/IBaseClient.BitmapCommands.cs	Updates bitmap/bitfield examples to match current option/type names and compile.
sources/Valkey.Glide/Client/GlideClusterClient.cs	Updates client-creation example to avoid removed using static pattern and compile.
sources/Valkey.Glide/Client/GlideClient.cs	Updates client-creation example to avoid removed using static pattern and compile.
sources/Valkey.Glide/Abstract/IServer.cs	Updates IServer examples to use correct receiver/return types and compile.
sources/Valkey.Glide/Abstract/IDatabaseAsync.ListCommands.cs	Splits/adjusts examples and updates inheritdoc references to compile and resolve correctly.
sources/Valkey.Glide/Abstract/Database.StreamCommands.cs	Moves trim-mode guard into Database and adds helper documentation.
scripts/check_examples.py	Adds extractor + compiler harness generator to validate examples via dotnet build.
Taskfile.yml	Adds check-examples task for local execution.
.gitignore	Ignores Python bytecode artifacts for the new script.
.github/workflows/check-examples.yml	Adds CI workflow to build GLIDE and run task check-examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.