add-analyzer

# Add Analyzer ## Overview Roslynator analyzers are metadata-driven: edit `Analyzers.xml`, codegen, implement analyzer + code fix, test, changelog. New analyzers never set `<Status>` — only `IsEnabledByDefault`. ## When to Use - New `RCS0` / `RCS1` / `RCS9` rule requested in an approved issue - Analyzer needs a new or existing `roslynator_*` config option - Picking package: `RCS0` → Formatting, `RCS1` → Analyzers, `RCS9` → CodeAnalysis.Analyzers **Not for:** deprecating rules (`deprecate-analyzer-or-refactoring`), bug fixes (`fix-analyzer-bug`), refactorings (`add-refactoring`). **Gate:** CONTRIBUTING.md requires an approved GitHub issue before implementation. **Read this skill and `references/implementation.md` before writing tests.** Published [analyzers-testing.md](https://josefpihrt.github.io/docs/roslynator/analyzers-testing) targets NuGet consumers — copying it produces code that does not compile in this repo. ## Confirm metadata parameters (hard gate) **STOP. Do NOT edit `Analyzers.xml`, run codegen, or implement until the user has confirmed every required parameter below.** Do not invent defaults when the user (or issue) did not state them. Use `AskQuestion` when available; otherwise ask conversationally. Batch related choices. | Parameter | Required? | Allowed / notes | |-----------|-----------|-----------------| | `Id` | propose | Compute next free `RCS0` / `RCS1` / `RCS9` id from `Analyzers.xml`; **do not ask** unless the issue conflicts or multiple ids are plausible | | `Identifier` | yes | PascalCase; drives generated names | | `Title` | yes | Short description | | `DefaultSeverity` | yes | `Hidden`, `Info`, `Warning`, or `Error` — **always ask** | | `IsEnabledByDefault` | yes | `true` / `false` — **always ask** (RCS0 often `false`) | | `MessageFormat` | if message has `{n}` placeholders | Otherwise omit (same as Title) | | Code fix? | yes | Strongly recommended; confirm yes/no | | `SupportsFadeOut` / fade-out analyzer | no | Ask only if unused-code style | | `MinLanguageVersion` | no | Ask only if C# version-gated | | Config option | no | See [config-options.md](references/config-options.md) | When proposing `Id`, state the chosen value in your plan/summary (e.g. “using next free **RCS9012**”). Skip asking other parameters only when the approved issue or the user's message already states the value explicitly. ## Quick Reference | Step | Location / command | |------|-------------------| | Metadata | `src/Analyzers.xml` — see [analyzer-schema.md](references/analyzer-schema.md) | | Config option | `src/ConfigOptions.xml` — see [config-options.md](references/config-options.md) | | Codegen | `cd tools && pwsh ./generate_code.ps1` | | Analyzer | RCS1 → `Analyzers/CSharp/Analysis/`; RCS0 → `Formatting.Analyzers/CSharp/`; RCS9 → `CodeAnalysis.Analyzers/CSharp/` | | Code fix | matching `*.CodeFixes/CSharp/CodeFixes/` | | Tests | `src/Tests/<Package>.Tests/RCS####IdentifierTests.cs` | | Changelog | `CHANGELOG.md` under `## [Unreleased]` | ## Implementation 1. Confirm metadata parameters (hard gate above). 2. Add `<Analyzer>` entry; schema in [references/analyzer-schema.md](references/analyzer-schema.md). Use docs-site [analyzer-metadata](https://josefpihrt.github.io/docs/roslynator/analyzer-metadata), not `Template.Analyzers.xml`. 3. Optional config option before codegen — [references/config-options.md](references/config-options.md). 4. Codegen from `tools/` (required cwd — see Common Mistakes). 5. Implement analyzer, code fix (if confirmed), tests — [references/implementation.md](references/implementation.md). Changelog line: ```markdown - Add analyzer "TITLE" ([RCS1234](https://josefpihrt.github.io/docs/roslynator/analyzers/RCS1234)) ([#PR](https://github.com/dotnet/roslynator/pull/PR)) ``` Verify: ```bash cd tools && pwsh ./generate_code.ps1 cd src && dotnet build Roslynator.sln cd src && dotnet test Roslynator.sln --no-build --filter "FullyQualifiedName~RCS####" cd src && dotnet format Roslynator.sln --no-restore --verify-no-changes --severity info ``` ## Common Mistakes | Mistake | Fix | |---------|-----| | Guess `DefaultSeverity` / `IsEnabledByDefault` | Ask — hard gate above | | Follow `analyzers-testing.md` verbatim | In-repo: `AbstractCSharpDiagnosticVerifier` + `Descriptor = DiagnosticRules.X` | | `pwsh tools/generate_code.ps1` from repo root | Run `cd tools && pwsh ./generate_code.ps1` — generator uses `../src` relative to cwd | | `<Status>` on new analyzer | Use only `IsEnabledByDefault`; lifecycle is `deprecate-analyzer-or-refactoring` | | `context.ReportDiagnostic` | Use `DiagnosticHelpers.ReportDiagnostic` | | Lazy `SupportedDiagnostics` field initializer | Use `Immutable.InterlockedInitialize` pattern |