Define Formatter Command Line Interface spec

[oxalica]

Motivation

Currently nix fmt is just like arbitrary nix run. The CLI can vary between different formatters. This PR formalize and defines the formatter CLI to make it more portable. This allows us and downstream to integrate formatting or format checking in a portable command line call. Eg. call nix fmt -- --check . in nix flake check.

The interface defined in this PR is compatible with all of nixpkgs-fmt, alejanda and nixfmt, with the exception that nixfmt requires git master version to support recursive formatting.

Context

Fixes #6918
Related oxalica/nil#70

Checklist for maintainers

Maintainers: tick if completed or explain if not relevant

• agreed on idea
• agreed on implementation strategy
• tests, as appropriate
  • functional tests - tests/**.sh
  • unit tests - src/*/tests
  • integration tests - tests/nixos/*
• documentation in the manual
• code and comments are self-explanatory
• commit message explains why the change was made
• new feature or incompatible change: updated release notes

Priorities

Add 👍 to pull requests you find important.

[emilazy]

From a language server perspective it would also be good to also specify an interface for range formatting (textDocument/rangeFormatting), to allow for formatting pasted text and the like. I don't expect any existing Nix formatter to support this, but formatters for other languages do (e.g. rustfmt has it as an unstable WIP and rust-analyzer supports using it).

[emilazy]

Additionally, perhaps there should be an exposed CLI interface to get the formatting command used by nix fmt for a given flake, so that language servers can cache it to avoid the overhead of a full invocation? (I don't know if this is always as simple as just reading the formatter entry out of the flake, but maybe it is?)

[nyabinary]

Any update on this?

[sellout]

@emilazy

Additionally, perhaps there should be an exposed CLI interface to get the formatting command used by nix fmt for a given flake, so that language servers can cache it to avoid the overhead of a full invocation? (I don't know if this is always as simple as just reading the formatter entry out of the flake, but maybe it is?)

Obviously not standard enough, but I have some flake tooling that roughly adds shellHook = ''__PM_FORMATTER="${lib.getExe self.formatter.${system}}"'' to the devShell, then allows me to run project-manager fmt, which first checks for that var and either runs it or prints a warning (“Not in a Project Manager environment …”) and then falls back to nix fmt.

Is this the kind of CLI interface you mean, or something different?