Roslyn-Analyzers

# Roslyn Analyzers and Source Generators

Use this workflow when adding or changing a Roslyn analyzer, code fix, source generator, tests, dependencies, or package layout. First inspect the repository's target frameworks, central package management, test framework, analyzer and generator conventions, diagnostic ID allocation, localization, and packaging. Preserve established conventions unless they conflict with the compatibility rules below.

Non-negotiable design rules

- Prefer `IOperation`-based analysis wherever possible. Register the narrowest applicable `OperationKind` and inspect typed operations such as `IInvocationOperation`, `IAwaitOperation`, or `IObjectCreationOperation`. This usually supports C# and VB with one analyzer and gives direct access to symbols and conversions.

- Use syntax analysis only for inherently syntactic rules or syntax not represented adequately by `IOperation`. A syntax-node callback already has a `SemanticModel`; do not call `Compilation.GetSemanticModel` or fetch another semantic model from it. Repeated semantic-model creation is expensive and often indicates that an operation or symbol action is the better abstraction.

- Every analyzer must support C#. VB.NET support is optional until requested or established repository precedent requires it. A language-neutral operation analyzer may declare both languages. If VB support is promised, include equivalent C# and VB snippets in tests; do not infer VB correctness from shared implementation alone.

- Keep analyzer and code-fix providers in distinct assemblies. The analyzer project must never reference Roslyn Workspaces packages. Workspaces dependencies belong only in the code-fix and test projects.

- Analyzer callbacks must be stateless or concurrency-safe. Call `EnableConcurrentExecution()`. Make an explicit generated-code choice with `ConfigureGeneratedCodeAnalysis(...)`; follow repository policy rather than silently accepting the default.

- Respect cancellation where APIs expose a token. Do not retain compilations, operations, syntax trees, symbols, or semantic models in static state.

- Avoid `InternalsVisibleTo`. Test analyzers through their public `DiagnosticAnalyzer` and `CodeFixProvider` APIs and the Roslyn test harness. A small analyzer helper may be public when direct testing is genuinely useful, but most behavior should be tested end to end.

- Centralize metadata names and member names instead of propagating magic strings. Use one shared static catalog for fully qualified type names, namespaces, and API member names.

- Document every diagnostic ID. When the repository uses Docfx, put analyzer documentation under its Docfx tree, typically `docfx/analyzers`, and include each page in the relevant table of contents.

- Set every analyzer assembly's version precisely enough that each commit produces a unique assembly version. When using Nerdbank.GitVersioning, give each analyzer project its own `version.json` with `assemblyVersion.precision` set to `revision` and ensure that repository-wide MSBuild properties do not prevent that file from being discovered.

- Source generators must implement `IIncrementalGenerator`, not `ISourceGenerator`. Design the provider graph so unchanged inputs remain cached and do not regenerate output.

- Source generators must use a small `SourceWriter` abstraction for deterministic newlines, indentation, encoding, and balanced output. Start from [SourceWriter.cs](./references/SourceWriter.cs) and tailor its namespace and target-framework details to the receiving repository.

Implementation workflow

1. Write down examples that must report and near-misses that must not report. Decide the exact diagnostic span and message arguments before implementation.

2. Determine whether the rule is semantic. Prefer, in order, operation actions, operation-block actions, symbol actions, compilation-start actions that register one of those actions, and finally syntax actions.

3. Resolve well-known types once in a compilation-star