FSharp.Refactor.Analyzers 0.6.2

FSharp.Refactor

ReSharper-style functional refactoring suggestions for F# — light-bulb quick fixes in your editor, and a command-line tool that applies them in bulk. Built on FSharp.Analyzers.SDK.

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

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 fsharp-refactor
fsharp-refactor Your.fsproj --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:

fsharp-refactor Your.fsproj

It refuses a compilation that does not already build, and fails loudly if applying ever introduces an error. For light bulbs while you type, see VS Code / Ionide below.

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

What it changes

Examples:

A spread of what the 100-odd rules do — the full list is in Refactorings:

Editor and CI setup

The analyzers ship as FSharp.Refactor.Analyzers. The package is a development dependency: it only produces hints and quick fixes — nothing from it flows into your compiled output.

NOTE: EVEN WHEN ADDING A NUGET REFERENCE, THIS ANALYSER WILL NOT COME TO OUTPUT PATH (BIN) AND WILL NOT BE PART OF YOUR PROJECT.

VS Code / Ionide

Reference the package from the project you want analyzed:

<PackageReference Include="FSharp.Refactor.Analyzers" Version="0.6.1" PrivateAssets="all" />

then point Ionide at the restored analyzers in .vscode/settings.json:

{
  "FSharp.enableAnalyzers": true,
  "FSharp.analyzersPath": [
    "~/.nuget/packages/fsharp.refactor.analyzers/0.6.1/analyzers/dotnet/fs"
  ]
}

(on Windows the cache lives under %USERPROFILE%\.nuget\packages). Suggestions appear as Hint-severity diagnostics with a light-bulb one-click fix.

CLI / CI

dotnet tool install --global fsharp-analyzers
fsharp-analyzers --project src/YourProject.fsproj --analyzers-path ~/.nuget/packages/fsharp.refactor.analyzers/0.6.1/analyzers/dotnet/fs --code-root . --report analysis.sarif

fsharp-analyzers is the analyzer HOST, and it is the dotnet tool you install. This package is not a tool: it is a library of analyzer assemblies the host loads, so it is passed as a directory rather than installed. That directory sits in the NuGet cache because an analyzer package deliberately has no lib/ folder and is marked a development dependency — a PackageReference therefore puts nothing in your bin, and after a restore the cache is where the assemblies live. --analyzers-path takes any folder holding them and searches it recursively.

The CLI only REPORTS; it never edits your files, which is what you want in CI (SARIF output works in GitHub code scanning). To apply the fixes, use our own tool below. Individual rules can be turned off per repository with a fsharprefactor.json — see Configuration below.

Applying fixes from the command line

The fsharp-refactor dotnet tool applies the quick fixes directly to your files:

dotnet tool install --global fsharp-refactor
fsharp-refactor Your.fsproj [--dry-run] [--codes FR0002,FR0031] [--api-changes] [--jobs 4] [--max-passes 5]

(or from this repository: dotnet run --project src/FSharp.Refactor.Tool -c Release -- Your.fsproj ...)

For a project it takes the exact compiler arguments from MSBuild; for a script FCS resolves the references itself and MSBuild never runs. Either way it then runs every analyzer, applies non-overlapping fixes bottom-up, and re-analyzes until a pass applies nothing — a fix can enable further fixes. It refuses a compilation that already has errors, and fails loudly if applying ever introduces one.

Someone else's codebase

Every rule is one of four kinds, shown in the last column of Refactorings:

This matters when the repository is not yours. Running everything over a project you do not maintain and opening a pull request from the result is a good way to waste an afternoon of someone's life: no maintainer wants "removed an empty attribute argument list" across two hundred files, and a diff that size buries anything that mattered. A disposable that is never disposed is a different conversation entirely.

So for a codebase you are a guest in:

fsharp-refactor Their.fsproj --categories correctness,performance --dry-run

That is the set that earns its review time. For your own code, run the lot.

The category claims are measured, not assumed:

dotnet run -c Release --project benchmarks/PerfClaims

re-checks them on your machine, on BOTH axes — wall clock and allocation (GC pressure is performance too). The contract: a performance rule's rewrite must win on at least one axis, and an idiom rule's must hold parity. FR0050 once emitted Seq.sum for a list — ~50%% slower than the mutable loop it replaced, plus an enumerator allocation — which is how the benchmark file, the rule's module-resolved output, and its idiom recategorization all came to exist.

Multi-targeted projects

Nothing extra to do: a multi-targeted project is worked through framework by framework, narrowest first.

That is not busywork. A rule gated on what the target can resolve behaves differently per framework — s.Contains 'x' is offered under net8.0, where the char overload exists, and does not compile for a netstandard2.0 target that lacks it. And each framework activates its own #if branches, so code behind another one's is not in the parse tree at all. One pass could only ever see part of the code.

Narrowest first means the fixes valid everywhere land before any that suit only a wider surface, and every pass ends by building all the frameworks, so a fix that does not generalise fails loudly instead of passing as success.

Given this, one plain fsharp-refactor Your.fsproj produces:

let has (s: string) =
#if NETSTANDARD2_0
    s.Contains "x"      // still a string: no char overload here
#else
    s.Contains 'x'      // rewritten under the net8.0 pass
#endif

--framework <tfm> restricts a run to one framework if you want it.

--api-changes opts into rewrites that change internal or public signatures — currying a tupled function (FR0090) and reordering its parameters data-last (FR0091) — rewriting every call site in the project. Without it those are held back and only counted. It also widens the contained-type hints (FR0022, FR0069, FR0070, FR0093) to public types. Consumers outside the project are why this is opt-in: their call sites cannot be rewritten, so each rule only fires where a missed one would fail to compile rather than change behaviour silently. Naming a single source file skips these entirely — asking for one file and getting edits in its callers would be a surprise.

Refactorings

Roadmap based on "F# refactoring possibilities":

Configuration

Rules can be disabled per repository with an optional fsharprefactor.json, searched upward from each analyzed file, stopping at the repository root (the nearest file wins). Keys are rule codes or analyzer names, case-insensitive; a malformed file fails open so it can never break the editor. Comments and trailing commas are tolerated:

{
  "rules": {
    "FR0003": false,
    "conversionMove": { "enabled": false }
  }
}

A disabled rule skips its analysis entirely, so the file also works as a performance lever on large codebases. Internally all analyzers share one memoized AST traversal per file version, so the editor pays for a single walk per keystroke regardless of how many rules are active.

Every rule defaults to enabled except two:

• FR0099 (line-ending semicolons) lexes every file containing one and rarely finds anything — cost out of proportion to a cosmetic default.
• FR0002 (match option → Option combinators) is the one measured rewrite that makes YOUR code slower — +53% and a closure allocation per call on its benchmark pair. Nice to read, costs to run; opt in when that trade suits the codebase.

Turn either on with "FR0099": true / "FR0002": true, or ask explicitly: the apply tool treats --codes FR0002 as outranking both the default-off status and a config disable — naming a rule is an ask. A --categories filter deliberately is not one: --categories idiom runs the idiom rules that are on, and does not quietly wake the default-off ones.

The same file can add custom FR0012 term-rewriting rules using FSharpLint's hint syntax (single-letter identifiers are metavariables):

{
  "hints": {
    "add": [
      "Option.isSome x |> not ===> Option.isNone x"
    ]
  }
}

Custom rules get the same safety treatment as the built-ins: bindings are parenthesized as needed, and a rule whose right side drops or duplicates a metavariable only fires on pure atoms (never discarding a side effect).

Improving it

Contributions welcome. This section is for working ON the analyzers; everything above is for using them.

Trying your changes

Build the analyzers, then point either host at the build output instead of the NuGet cache.

In an editor, via the target repo's .vscode/settings.json:

{
  "FSharp.enableAnalyzers": true,
  "FSharp.analyzersPath": ["<path-to>/FSharp.Refactor.Analyzers/bin/Debug/net8.0"]
}

Open an F# file containing e.g. match x with | true -> 1 | false -> 2 — a hint appears offering if x then 1 else 2.

Or from the CLI:

fsharp-analyzers --project YourProject.fsproj --analyzers-path src/FSharp.Refactor.Analyzers/bin/Debug/net8.0 --code-root .

Note: analyzers must be built against an FSharp.Compiler.Service compatible with the host FsAutoComplete. This project currently pins FSharp.Analyzers.SDK 0.37.2 (FCS 43.12.201). See the SDK's version-pairing table when updating.

Building and testing

dotnet build
dotnet test

This project eats its own dog food. Before committing:

dotnet tool restore
dotnet fantomas src tests
dotnet dotnet-fsharplint lint src/FSharp.Refactor.Analyzers/FSharp.Refactor.Analyzers.fsproj
dotnet dotnet-fsharplint lint src/FSharp.Refactor.Tool/FSharp.Refactor.Tool.fsproj
dotnet dotnet-fsharplint lint tests/FSharp.Refactor.Tests/FSharp.Refactor.Tests.fsproj

and the analyzers are run against their own source, expecting zero findings. Both projects, not just the analyzers — the apply tool is F# we ship too, and it went a long time unchecked:

dotnet tool run fsharp-analyzers --project src/FSharp.Refactor.Analyzers/FSharp.Refactor.Analyzers.fsproj --analyzers-path src/FSharp.Refactor.Analyzers/bin/Debug/net8.0 --code-root .
dotnet tool run fsharp-analyzers --project src/FSharp.Refactor.Tool/FSharp.Refactor.Tool.fsproj --analyzers-path src/FSharp.Refactor.Analyzers/bin/Debug/net8.0 --code-root .

Test inputs are string literals, so formatting tools never touch the deliberately-shaped source fragments the tests exercise.

Design principles

1. Never break user code. A fix is only offered when it is provably safe to apply; borderline cases simply don't produce a suggestion. Fixes are minimal range-based text edits applied by the editor, so they are always a single native undo step.
2. Minimal edits. Original formatting outside the edited range is untouched — no whole-file reformatting.
3. Pure core, thin adapters. Each refactoring is a pure function ParsedInput -> ISourceText -> Suggestion list, unit-tested directly against source strings. The SDK analyzer entry points in Analyzers.fs are one-liners.
4. Hints point toward idiomatic F# only. Every analyzer rewrites a → b where b is the more idiomatic form; we never ship a hint that moves code away from idiomatic F#. That is why suggestions are Hint severity, not warnings: they mark an opportunity, not a defect, and they never gate CI. Genuinely reversible rewrites where neither direction is more idiomatic (if ↔ match, tupled ↔ curried) belong in FsAutoComplete's codefix infrastructure as user-invoked refactor.rewrite actions, and should be contributed there rather than here.

Our Vision, and Other projects in the same field

AI Agent compatibility: This project does distinct the F# code from generated Python smell. Meanwhile, some past rules (like function length and cyclomatic complexity) are expected to gains less attention in the future. This project has focus on idiomatic F#, code performance and best practices, and less interest on code structure/naming/maintainability.

This project aims to be compatible with other products, so you won't end-up having oscillation/fight between suggested changes.