fsharp-refactor 0.6.7

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="*" PrivateAssets="all" />

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

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

replacing <version> with the version restore actually picked (the NuGet cache always keys folders by version, so this one path cannot float; check with ls ~/.nuget/packages/fsharp.refactor.analyzers/). 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/<version>/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.

CI setup (SARIF)

A dry run plus --report gives CI the full findings list without touching a file; uploading the SARIF turns each finding into an inline annotation on the pull request. Paths in the report are relative to the working directory, so run the tool from the repository root (that is what code scanning matches blobs by):

  refactor-lint:
    runs-on: ubuntu-latest
    permissions:
      security-events: write     # required by upload-sarif
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
      - run: dotnet tool install --global fsharp-refactor
      - run: fsharp-refactor src/Your.fsproj --dry-run --report findings.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: findings.sarif
          category: fsharp-refactor

Two honest notes. First, a dry run exits 0 whether or not it found anything — findings are hints, not errors, and only a broken build or a crashed run fails the step. Annotations therefore inform without blocking; to make findings HARD-fail the job, add an explicit check:

jq -e '.runs[0].results | length == 0' findings.sarif

Second, scope the gate before turning it on: --categories correctness,performance keeps the signal defensible on a shared repository (see Someone else's codebase), and a fsharprefactor.json turns off anything the team has decided against. The suppression comments described under Configuration silence individual findings at the line, for both the gate and editors, in one place.

Running alongside other analyzer packages

The fsharp-analyzers host loads every analyzer assembly it is pointed at, so one invocation — and one FCS typecheck, the expensive part — can run this package together with others built on the same SDK, all findings landing in one report. With G-Research's analyzers, whose current release pins the same FSharp.Analyzers.SDK as this package (0.37.2):

fsharp-analyzers --project src/Your.fsproj \
  --analyzers-path ~/.nuget/packages/fsharp.refactor.analyzers/<version>/analyzers/dotnet/fs \
                   ~/.nuget/packages/g-research.fsharp.analyzers/<version>/analyzers/dotnet/fs \
  --code-root . --report findings.sarif

Rule codes are disjoint (FR* here, GRA* there), and the fsharpanalyzer: ignore-line suppression comments work for their codes too — the machinery lives in the shared SDK, not in any one package.

The SDK is strict about version agreement between the host and every analyzer assembly it loads; a mismatch means analyzers silently fail to load rather than erroring loudly. The day the two packages pin different SDK minors, fall back to separate CI jobs — each producing its own SARIF and uploading under its own category: (code scanning keeps the streams apart) — at the cost of typechecking the project once per job. Applying fixes stays this package's own tool either way: fsharp-refactor applies only its own rules, and report-only analyzers have nothing to collide with.

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.

Capability fixes get both worlds — using the project's own vocabulary. When a project also targets frameworks older than an overload (net4x, netstandard2.0), the tool reads the fsproj's DefineConstants and looks for a framework-shaped constant — NETSTANDARD21, NET8, digits required — whose '$(TargetFramework)' == '...' conditions cover only the modern frameworks. Names denoting a legacy framework (NET48, NET451, NETSTANDARD2_0) are refused outright whatever their conditions say: the SDK defines exactly those constants during the legacy compilations themselves, where no fsproj parse can see them. Flavor names sharing the same condition (SQLProvider defines MICROSOFTSQL right beside NETSTANDARD21) are passed over: their meaning is the flavor, and a sibling project compiling the same shared file may define them on legacy frameworks too. If a constant qualifies and the file already uses conditional compilation, FR0038 and FR0106 emit a pair instead of a fix the legacy half cannot compile:

#if NETSTANDARD21
let orderNumber (s: string) = Int32.Parse(s.AsSpan(6, 5))
#else
let orderNumber (s: string) = Int32.Parse(s.Substring(6, 5))
#endif

No invented constants, ever: a project defining no such constant gets the plain fix, and the final all-frameworks build stays the arbiter (a fix the legacy half rejects is put back). Constants appearing in a DefineConstants element whose condition the tool cannot fully read (anything beyond '$(TargetFramework)' == 'X' chained with Or) are disqualified rather than guessed at. A line already inside a positive region of the chosen constant — or a hand-written NET*_OR_GREATER — gets the plain fix (nothing legacy compiles it), a file with no #if anywhere stays free of them, and editors always suggest the plain form. --no-if-defs turns the pairing off entirely for a run that should never add conditional compilation, whatever the project defines.

Large solutions stay affordable through three levers: one FCS checker serves the whole run (twenty projects share nearly all their reference assemblies, parsed once); a shared source file swept under one set of conditional-compilation defines is never re-swept by the next project that compiles it identically; and a multi-targeted project whose sources contain no #if at all gets a single-framework sweep, with the final all-frameworks build still verifying the rest.

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.

Allow changes to public API like types

Public types and function signature changes are not done by default. Sometimes they would make the program more efficient:

Changing type Item = { X: Option System.Guid } to type Item = { X: VOption System.Guid } would often make sense because Guid is already a struct, so ValueOption is better here. But that could affect to external users and serialization.

--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 }
  }
}

Rules with tunable thresholds read numeric properties from the same object-valued entries. FR0114 is the first: thenAtLeast (default 20) is how long a then-branch must be before flipping is suggested, and elseAtMost (default 3) is how short the else must stay:

{
  "rules": {
    "FR0114": { "enabled": true, "thenAtLeast": 30, "elseAtMost": 2 }
  }
}

Paths can be excluded too — additively over the built-in defaults (paket-files, .paket, node_modules), which cover generated and vendored code a compilation nonetheless includes:

{
  "ignorePaths": [ "generated", "external/imported" ]
}

A bare name matches as a whole path segment; an entry containing a slash matches anywhere in the normalized path; an entry containing * is a glob — * stays within a segment, ** crosses them (*.g.fs, src/generated/**). Ignored files are neither analyzed nor even type-checked by the apply tool's sweep — on a paket-heavy solution that is a lot of vendored source nobody wants "fixed". Files opening with the conventional // <auto-generated> marker are skipped automatically wherever they sit, as is everything under obj/.

Individual findings can be silenced in place with the F# analyzer SDK's own suppression comments — the same ones editors honor, so one comment silences both the light bulb and the apply tool (a suppressed finding is neither reported nor fixed):

// fsharpanalyzer: ignore-line-next FR0106
let orderNumber (s: string) = Int32.Parse(s.Substring(6, 5))

let inline dodgy (s: string) = s.Substring(0, 3) // fsharpanalyzer: ignore-line FR0106

// fsharpanalyzer: ignore-file FR0031, FR0038
// fsharpanalyzer: ignore-region-start FR0002
// fsharpanalyzer: ignore-region-end

Suppression comments are also easy to reach for, and a team may not want a correctness finding silenceable with one line of punctuation the way a naming nit is. The "suppressions" policy draws that line:

{ "suppressions": "no-correctness" }

• "all" (default) — every suppression comment silences its finding.
• "no-correctness" — comments on correctness-category rules are reported anyway; idiom, cosmetic, and performance suppressions still work. An overridden finding is never auto-FIXED — the tool does not rewrite code over someone's explicit comment — it is reported (and fails --fail-on-findings) until addressed or the comment is judged worth honoring.
• "none" — every suppression comment is reported anyway.

--honor-suppressions on the command line overrides the policy to "all" for that run. A repo that wants suppressions inert on developer machines but honored by the pipeline commits "no-correctness" (or "none") in its config and passes the flag in CI only. Whatever the policy, the run summary counts what comments silenced — suppression is never silent. Note the policy only governs this tool: editors honor the SDK's comments natively, so the light bulb stays silenceable regardless.

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.