CSharp.Refactor.Analyzers 0.1.2

CSharp.Refactor

The C# little-sister of FSharp.Refactor

Functional refactoring suggestions for C#, implemented in F# on Roslyn. The rules care about correctness, measured performance and clear functional idiom — and deliberately not about naming, layout or conventions.

• light bulb quick fixes in your editor (Visual Studio, VS Code, Rider, anything that hosts Roslyn analyzers)
• a command-line tool that applies them in bulk, build-verified

Suggestions are Info severity: they mark an opportunity, not a defect, and never gate your build.

Status: pre-release. Every rule of the v1 catalog (124 rules across families A–J) is implemented and swept over real repositories; the cross-project edit sets, the editor extensions and the publishing scripts are still open. The design and the rule catalog with its guards are in DESIGN.md; Rules.md documents every shipped rule (kept complete by tests, and the target of every finding's help link, e.g. Rules.md#cr0025--performance); CHANGELOG.md has every version's notes.

Using it

Quick start

Nothing to configure — the tool reads your project, reports what it would change, and only edits when you tell it to:

dotnet tool install --global csharp-refactor
csharp-refactor Your.csproj --dry-run

That prints every fix it would make, with file and position, and writes nothing. When the list looks right, drop the flag to apply them:

csharp-refactor Your.csproj

It refuses a compilation that does not already build, recompiles in memory after every pass, and builds the project for real at the end, putting the fixes back if that fails.

For light bulbs while you type, see VS Code / Ionide and Visual Studio IDE-plugin instructions below.

<img width="1044" height="297" alt="image" src="https://github.com/user-attachments/assets/762ff17d-2c58-4c8a-ae27-569117b88d4e" />

For agentic scenarios the dotnet tool supports MCP.

Using the tool:

Point it at whatever you have — the kind is read off the path:

Editor and CI setup

The analyzers ship as CSharp.Refactor.Analyzers, an ordinary Roslyn analyzer package. Reference it from the project you want analysed and every host — dotnet build, Visual Studio, VS Code's C# extension, Rider — loads it by itself:

<PackageReference Include="CSharp.Refactor.Analyzers" Version="*" PrivateAssets="all" />

The package is a development dependency: it only produces hints and quick fixes, and nothing from it reaches your compiled output or your bin.

Visual Studio 2022 / 2026

Install the CSharp.Refactor extension: every C# project opened in the IDE gets the suggestions and Ctrl+. fixes, with no project change and no effect on builds. Its Tools > CSharp.Refactor menu runs the csharp-refactor tool on the open solution (apply or dry run, with or without --api-changes), writes the SARIF report, opens the notes page and the .editorconfig block — the VS Code extension's commands, in Visual Studio. Or use the package reference above; both work, and a project with both sees each finding once.

VS Code

Install the CSharp.Refactor extension. It bundles the analyzers and, with your consent, wires them into every C# project on the machine through MSBuild's user ImportBefore hook (one props file under your profile, undone by a command). Or use the package reference.

CI

The analyzers run inside the compiler, so a build can write the findings as SARIF with no extra tool:

dotnet build -p:ErrorLog=findings.sarif

The tool's own report carries more — fixes as suggested changes, context snippets, stable fingerprints — and pairs with --dry-run for a lint gate:

      - run: dotnet tool install --global csharp-refactor
      - run: csharp-refactor src/Your.csproj --dry-run --report findings.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: findings.sarif
          category: csharp-refactor

A dry run exits 0 whether or not it found anything; --fail-on-findings makes it exit 3 when a finding survives the filters, and --baseline turns that into a ratchet: findings already in an earlier report are neither reported nor fixed, only new ones surface.

Applying fixes from the command line

csharp-refactor Your.csproj [--dry-run] [--codes CR0090,CR0103] [--categories correctness,performance] [--api-changes]

Projects are loaded through MSBuildWorkspace — SDK-style projects of any target, net48 included, in every framework flavour they list. A legacy project (<Project ToolsVersion="4.0" …> with explicit <Compile> items) is read from its project file when the .NET Framework build host does not answer: compile items, defines, HintPath references that exist, the targeting pack's assemblies and project references. Without the build tree (a reference a custom .targets adds, a sibling bin) some types stay unresolved; the run says how many, the typed rules stand down where a type is unknown, the in-memory check holds the error count, and the final build runs through Visual Studio's MSBuild.exe where a baseline build succeeds — otherwise the run is verified in memory only, and says so. An executable another project of the solution references (its tests) is not a leaf: its public shape stays unless --api-changes says otherwise, and every dependent of a changed project is built too. A C# script (.csx) is a compilation of its own: the file parsed as a script, the running runtime as its references, #r resolved against the script's directory, the runtime and the NuGet cache (#r "nuget: Name, Version"), #load read by the compiler for context (a loaded file is edited when it is swept as a target of its own, and a directory sweeps every loose script). Nothing builds a script, so the run is verified in memory: the error count may not grow, and a script host's globals (Args) count as errors on both sides.

Configuration

Rules are configured the way every Roslyn analyzer is, in .editorconfig, nearest section winning:

[*.cs]
dotnet_diagnostic.CR0103.severity = none          # off
dotnet_diagnostic.CR0006.severity = suggestion    # a default-off rule, on
csharp_refactor.CR0006.then_at_least = 30         # a rule's knob

csharp_refactor.public_api   = false              # nothing links to this assembly
csharp_refactor.api_changes  = true               # --api-changes as a standing decision
csharp_refactor.suppressions = no-correctness     # all | no-correctness | none
csharp_refactor.ignore_paths = generated;external/imported

csharp-refactor --create-config writes the block for you, every value at this build's default, so it changes nothing until you edit a line.

A generated file is never touched, in the editor or by the tool: one under bin, obj, node_modules or .git, one named *.g.cs, *.designer.cs, *.generated.cs or *.g.i.cs, one listed in ignore_paths, and one whose header says <auto-generated> (a T4 template's, a resx designer's, the SDK's AssemblyInfo) or "This code was generated by".

Individual findings are silenced with Roslyn's own means — #pragma warning disable CR0090, [SuppressMessage], a severity of none — and editors honour those natively. The suppressions policy governs the tool: no-correctness reports a suppressed correctness finding anyway (and never auto-fixes it), none reports every suppressed finding, --honor-suppressions overrides either for one run. The run summary counts what suppressions silenced.

A rule that shadows a Microsoft analyzer rule (CA2213, CA1031, CA2000 …) stands down for that rule's shapes wherever the Microsoft rule is enabled in the file's effective config, so nothing is reported twice and nothing oscillates. Rules.md names each rule's twins.

Improving it

Building and testing

dotnet build
dotnet test

Before committing:

dotnet tool restore
dotnet fantomas src tests
dotnet dotnet-fsharplint lint src/CSharp.Refactor.Analyzers/CSharp.Refactor.Analyzers.fsproj

The test harness compiles C# string literals against the running framework, runs the pure rules, applies every fix as text and recompiles; the host tests drive the real DiagnosticAnalyzer and CodeFixProvider through Roslyn; the tool tests sweep a synthetic project through MSBuildWorkspace. tests/run-tests.ps1 runs the lot. benchmarks/PerfClaims holds the before/after pair behind every performance claim.

Beside the example-based suite, tests/CSharp.Refactor.PropertyTests is an FsCheck suite over generated programs: a class of members each shaped for a rule, and method bodies around boolean terms over three integers, with an interpreter over the Roslyn tree as the oracle. Its properties are the invariants the rules promise - every fix, editor-only alternatives included, keeps the program compiling; no rule throws on a compilation recovered from damaged text; applying fixes one at a time reaches a fixed point; and the boolean and control-flow rewrites (CR0001, CR0005, CR0007, CR0008, CR0011) keep the method's truth table at every step. The generators reach 121 of the 124 rules (CR0017 is subsumed by CR0160 wherever both read a shape; CR0156 and CR0158 need C# 15, which the harness cannot parse), and a coverage test tries every shape on its own and all of them together: if a shape stops firing the rule it was written for, it says which. Two more properties dress the programs the way real files come — #regions around members, a #if and a comment inside a member, CRLF, tabs, a #pragma — and require every fix to compile and to leave what was there (no swallowed directive or comment, no bare LF in a CRLF file); and compile them at every language version from C# 7.3 to 13, requiring a fix to use no syntax newer than the file's own. Both run deterministically over every shape as well as over random programs. A rewrite that would compile and mean something else is out of the compile invariant's reach, so a shape carries a decoy where it can: the CR0100/CR0101 shape calls a method whose FormattableString overload is [Obsolete(error)], so an interpolation that re-binds the call is a compile error; the CR0082 shape hands one tuple to object, where a retype would not compile. What no decoy can express (a record made of a type with behaviour, a record dumped into an exception message) stays with the example suite.

Design principles

1. Never break user code. A fix is only offered when it is provably safe; the borderline case produces no suggestion. A fix must be right without a compile: the same fix runs in the editor, where nothing verifies it.
2. Guards over removal. An unsafe rewrite gets a typed proof that the shape is safe and stands down where the proof fails; the rule is never deleted or blanket-disabled.
3. Minimal edits. Fixes are range-based text edits; formatting outside the edited range is untouched.
4. Pure core, thin adapters. Each rule is a pure function from a syntax tree and semantic model to suggestions; the Roslyn analyzer, the fix provider and the tool are one-line adapters over it.
5. Hints point toward idiomatic C# only. Reversible matters of taste belong to the IDE's refactorings, not to a diagnostic.

See DESIGN.md for the full safety model, the yields-to gate, the planned catalog and the relationship to Microsoft's analyzers.