Fourmolu Checker - Formatting Diagnostics for Haskell

Display localized Fourmolu formatting differences as VS Code diagnostics without automatically modifying your Haskell source files.

Fourmolu Checker highlights each affected source block, previews both localized and full-file Fourmolu output, and lets you apply either the selected block or the complete file. It complements HLS formatting and format-on-save workflows by keeping formatting differences visible and reviewable.

Why use it?

Fourmolu Checker is useful when you want to:

• keep formatting differences visible until you explicitly apply them;
• review and apply individual formatting blocks;
• expose formatting differences in the VS Code Problems panel;
• use the same Fourmolu executable and arguments as your project or CI;
• keep editor.formatOnSave disabled.

How it differs from HLS formatting

Haskell Language Server can use Fourmolu as a formatting provider for Format Document or editor.formatOnSave.

Fourmolu Checker complements that workflow rather than replacing it. Instead of only applying formatted output, it:

• publishes each changed source block as a VS Code diagnostic;
• highlights the affected range in the editor and Problems panel;
• previews Fourmolu's formatted version when hovering the diagnostic;
• opens a side-by-side preview before applying every formatting change in a file;
• lets you apply only the selected formatting block or format the entire file;
• runs the configured Fourmolu executable and arguments, which can match the command used by your project or CI.

Use HLS formatting when you primarily want automatic or on-demand document formatting. Use Fourmolu Checker when you want formatting differences to remain visible and reviewable before applying them.

Features

• independently checks matching .hs, .hsig and .hs-boot files on save and clean files when opened;
• reports each affected Fourmolu formatting block in the Problems panel;
• identifies line-ending and final-newline normalization, import reorder/regrouping, module documentation, Haddock comments, ordinary comments and exact whitespace-only changes;
• conservatively identifies compatible pragmas, import/export lists, deriving and constraint contexts, guarded equations, lambdas, if/operator expressions, case alternatives, function types, declarations, records, lists, tuples and applications;
• falls back to a generic localized formatting diagnostic when a block cannot be classified safely;
• shows the corresponding formatted block when hovering a formatting diagnostic;
• provides Quick Fixes for the selected diagnostic block, a full-file preview, the complete file, and related Fourmolu configuration documentation;
• supports standalone files, standard workspaces and multi-root workspaces;
• provides configurable include and exclude globs;
• supports additional Fourmolu arguments and a custom executable path;
• reports the resolved Fourmolu command and result for the current file;
• creates a previewed fourmolu.yaml from Fourmolu's defaults in an explicitly selected folder;
• distinguishes formatting differences from Fourmolu parser and execution errors;
• supports local, Remote SSH, WSL and devcontainer workspaces.

Fourmolu remains the source of the formatted output. Syntax analysis is used only to describe localized changes more precisely; it never claims which Fourmolu option caused a change. When a change cannot be classified safely, Fourmolu Checker reports a generic formatting diagnostic.

The extension does not claim complete support for every Haskell construct or GHC extension.

More examples

Type signature diagnostic

Fourmolu Checker identifies the surrounding Haskell construct and displays the formatted block when hovering the diagnostic.

Do block diagnostic

When the syntax context can be identified safely, the diagnostic describes the affected construct rather than reporting only a generic formatting difference.

Preview and apply all formatting changes

Preview all Fourmolu changes opens a read-only side-by-side diff using the exact output from the current Fourmolu check. It does not run Fourmolu again or modify the source. Apply all Fourmolu changes remains the explicit action that formats the current file.

Workspace scans do not retain complete formatted output for unopened files. Open such a file and run Check Current File when an automatic check is disabled to make its full-file preview available.

Requirements

Install fourmolu in the environment where the VS Code extension runs.

For Remote SSH, WSL and devcontainer workspaces, install Fourmolu in the remote environment rather than on the local machine.

By default, the extension runs fourmolu from the PATH of the VS Code extension host. Set fourmoluChecker.executablePath when the executable is located elsewhere.

Fourmolu Checker does not bundle a Fourmolu binary. If the default executable is missing, the error notification provides actions to open the setting or the official Fourmolu installation guide. The extension validation baseline is Fourmolu 0.20.0.0, but configure the version required by your project.

Automated real-binary validation covers Fourmolu 0.19.0.0, 0.19.0.1, and 0.20.0.0, including the documented diagnostic-category fixtures. The 0.20.0.0 baseline also runs the real Extension Host suite on Linux, macOS, and Windows. Other Fourmolu versions may work, but are not a tested compatibility claim. A separate weekly Ubuntu command-contract and category check also probes the latest non-prerelease Fourmolu release after verifying the SHA-256 digest exposed by GitHub's release metadata.

The Extension Host smoke suite runs on Stable VS Code for Linux, macOS and Windows, plus the minimum declared VS Code version on Ubuntu.

Executable and project resolution

fourmoluChecker.executablePath accepts:

• an executable name;
• an absolute path;
• a workspace-relative path;
• a path containing ${workspaceFolder}.

For files inside a workspace, relative executable paths and ${workspaceFolder} are resolved from the workspace folder that owns the file. For standalone files, relative executable paths are resolved from the file's directory.

Fourmolu itself is started from the directory containing the Haskell file. This allows Fourmolu to perform its normal upward discovery of fourmolu.yaml, Cabal metadata and other project configuration, including configurations inside nested projects or monorepos.

Fourmolu Checker does not parse or reproduce Fourmolu configuration logic.

Fourmolu is started with an argument array rather than a shell command, so file and executable paths containing spaces work normally.

fourmoluChecker.extraArguments values are passed unchanged. Relative paths inside those arguments are therefore interpreted by Fourmolu relative to the Haskell file's directory; the extension does not rewrite them.

Usage

Open a Haskell file and save it.

When Fourmolu would modify the file, the extension publishes diagnostics on the affected source blocks and in the VS Code Problems panel. Hover a diagnostic to see Fourmolu's formatted output for that block.

The diagnostic Quick Fix menu can copy a report containing the file name, range, code, severity and message for an issue report. It excludes source text, formatted output and absolute paths.

View Fourmolu options affecting … is a read-only diagnostic Quick Fix. For recognized imports, import/export lists, module or Haddock documentation, indentation, declaration spacing, where bindings and common record/list/tuple layouts, it opens the related official Fourmolu option page. Other categories open the official configuration index. It never claims which option caused a particular change and never modifies source or fourmolu.yaml.

When Fourmolu itself fails, its error diagnostic offers Copy Fourmolu failure details. The report includes the failure code, operation, safe executable name, process status and duration. It never copies source text, formatted output, stderr, configured arguments or absolute paths.

For a current check-failed diagnostic, Show Fourmolu debug output reruns the resolved Fourmolu executable with --debug in the same working directory. It is read-only and opens bounded stderr in the Output channel; stdout is omitted because it can contain formatted source. The action is ignored once the diagnostic is stale.

The extension does not modify the file automatically. Use the lightbulb Quick Fix to apply Fourmolu's suggestion for the selected diagnostic block, or use one of these commands:

• Fourmolu Checker: Check Current File
• Fourmolu Checker: Check Workspace
• Fourmolu Checker: Preview All Formatting Changes
• Fourmolu Checker: Diagnose Current File
• Fourmolu Checker: Create Fourmolu Configuration
• Fourmolu Checker: Format Current File

Format Current File asks Fourmolu for read-only stdout, verifies that the document has not changed, then applies that exact full-file text through VS Code. It never asks Fourmolu to write the file directly; save the resulting editor change when ready.

Create Fourmolu Configuration prompts for the target folder; it never guesses a project directory. It resolves the executable for that folder, runs Fourmolu with --print-defaults, and opens the generated YAML in a read-only preview. Confirming creates fourmolu.yaml only if it still does not exist; an existing file is never overwritten. The command intentionally does not pass fourmoluChecker.extraArguments, so the preview is Fourmolu's defaults rather than a command-line override. On success, clean open Haskell files below the selected folder are refreshed without starting a workspace scan. Fourmolu Checker does not parse the generated YAML.

Workspace checking

Run Fourmolu Checker: Check Workspace from the Command Palette to check all matching .hs, .hsig and .hs-boot files in every open workspace folder. This explicit command does not format files and is never run automatically.

Each folder retains its own include, exclude, executable, extra-argument and severity settings. The scan reports progress, can be cancelled, and checks at most four files concurrently. A new workspace check cancels and replaces an older one.

Diagnostics may be published for unopened files. Dirty open files are skipped: the extension neither saves them nor checks a different on-disk version behind their editor buffer. Partial diagnostics already published before cancellation remain valid; late cancelled results are discarded. The Output channel records the scan summary and, when FOURMOLU_CHECKER_DEBUG_TIMINGS=1, detailed local timings.

Workspace-derived selected-block Quick Fixes are available after opening the file. They validate the complete current document fingerprint before editing. Workspace diagnostics are cleared when their unopened source changes externally or when its workspace folder is removed. A create, change or delete of fourmolu.yaml or a .cabal file clears affected results and refreshes matching clean open files; it never starts a workspace-wide check automatically or interprets either project input.

Settings

Additional Fourmolu options

{
  "fourmoluChecker.include": [
    "services/**/*.hs",
    "services/**/*.hsig",
    "services/**/*.hs-boot",
    "libs/**/*.hs"
  ],
  "fourmoluChecker.extraArguments": [
    "-o",
    "-XImportQualifiedPost",
    "-o",
    "-XOverloadedRecordDot",
    "-o",
    "-XOverloadedLabels"
  ]
}

Check only after saving

{
  "fourmoluChecker.checkOnOpen": false,
  "fourmoluChecker.checkOnSave": true
}

This checks matching files after they are saved, but not when clean files are opened.

Workspace-relative executable

Relative executable paths and ${workspaceFolder} are resolved independently for each workspace folder:

{
  "fourmoluChecker.executablePath": "tools/fourmolu"
}

Diagnostic severity

Formatting diagnostics default to warning.

Set fourmoluChecker.diagnosticSeverity to information for a less prominent Problems entry. Execution failures, parser failures and malformed Fourmolu output remain errors.

Output and troubleshooting

Use View: Output and select Fourmolu Checker to inspect execution details and failures.

Run Fourmolu Checker: Diagnose Current File to explicitly report the current file's resolved executable, workspace folder, executable base, process working directory, arguments, Fourmolu version and check result. It never saves, formats or changes diagnostics. For a dirty document it reports the execution context and version, then skips the file check rather than inspecting an older on-disk version.

The Output channel records:

• the file being checked;
• the selected workspace folder;
• the resolved executable;
• the process working directory;
• the argument array;
• the exit status;
• bounded standard-error output.

It never logs formatted source output.

When VS Code reports that the executable was not found:

1. verify that Fourmolu is installed in the environment where the extension host runs;
2. use fourmolu --version in the integrated terminal as an initial check;
3. inspect the Fourmolu Checker Output channel to see the executable and working directory actually used;
4. configure fourmoluChecker.executablePath explicitly when necessary.

The missing-executable notification also provides Configure Executable and Installation Guide actions. It never silently substitutes a bundled or downloaded Fourmolu version.

The integrated terminal and the VS Code extension host may not use exactly the same PATH.

For Remote SSH, WSL and devcontainer workspaces, install and configure Fourmolu in the remote environment rather than on the local machine.

Known limitations

• .hs source files, .hsig signature files and .hs-boot boot files are eligible; literate Haskell (.lhs) is not supported.
• A Fourmolu executable is required in the VS Code extension-host environment.
• Tree-sitter improves diagnostic wording conservatively; it is not the GHC parser. CPP, Template Haskell, quasiquotes, parser-error nodes and unfamiliar syntax may use the existing generic localized formatting diagnostic.
• Checks and formatting probes never modify source files. Only an explicit selected-block Quick Fix or Format Current File may edit a file.
• Workspace checks skip dirty open files rather than checking a different on-disk version behind the editor buffer.

Privacy and network behavior

Fourmolu Checker has no telemetry, source upload or remote formatting service. It runs the configured Fourmolu executable in the VS Code extension-host environment and keeps project source local to that environment. The optional contributor-only corpus tooling can clone public repositories when a maintainer explicitly runs it; it is excluded from the published VSIX and never runs in the extension.

Development

The fast test suite uses Node.js built-ins and a fake Fourmolu process. Separate release-validation commands use an explicitly supplied real Fourmolu executable in disposable fixtures.

Contributor technical documentation is available in the repository.

Run the complete test suite with:

npm test

Launch an Extension Development Host with:

code --new-window --extensionDevelopmentPath="$PWD" /path/to/haskell-workspace