affogato

affogato is a suite of tools for the Nix language, written in Java:

a formatter, a port of nixfmt that leaves all of nixpkgs unchanged;
a linter, with rules drawn from deadnix, statix and nixd, many with an automatic fix;
a syntax highlighter, which works from the lexer alone and so copes with syntax errors;
an evaluator on GraalVM, as a Truffle AST interpreter, which evaluates nixpkgs unmodified and computes store paths and .drv paths in memory, without writing anything to /nix/store;
a playground that runs the formatter, linter and highlighter in the browser, compiled to JavaScript.

Getting started

Build it with Nix, either on the JVM or as a static native binary (linked against musl), which starts in milliseconds rather than half a second:

nix build .#affogato-truffle          # on OpenJDK 25
nix build .#affogato-truffle-native   # native image, built with GraalVM

To format and lint only, affogato and affogato-native provide a affogato command with only format, check and fix, without the evaluator and Truffle.

Each package installs bash and zsh completions; affogato generate-completion prints the script, to source in a shell where it is not installed.

To try the formatter and linter in a browser, open the playground; they run in the page, compiled to JavaScript. To build it locally, then open result/index.html in a browser:

nix build .#playground

Evaluate an expression:

$ ./result/bin/affogato eval --strict -E 'builtins.map (x: x * 2) [ 1 2 3 ]'
[ 2 4 6 ]

Compute the derivation path of a nixpkgs attribute:

./result/bin/affogato drv-path -I nixpkgs=/path/to/nixpkgs -E 'import <nixpkgs> {}' -A hello

Command line

Each command has its own page, generated from the command line itself; -h or --help after any command prints the same.

Synopsis

affogato [-h] [COMMAND]

Options

-h, --help: Show this help and exit.

Commands

format: Format Nix files in place, as nixfmt does.
check: Report the linter’s findings in Nix files without changing them.
fix: Apply the linter’s fixes to Nix files in place, then format them.
eval: Evaluate an expression and print the result, like nix-instantiate --eval.
drv-path: Evaluate an expression to a derivation and print its drvPath.

treefmt

format and fix follow the treefmt formatter spec:

[formatter.affogato]
command = "affogato"
options = ["fix"]
includes = ["*.nix"]

Status

Checked against Nix 2.34.9 and nixpkgs 31ecbaca1bde on x86_64-linux.

Language tests: affogato passes NixOS/nix’s tests/functional/lang suite (303 tests) and Tvix’s eval/src/tests/tvix_tests, apart from the cases listed with reasons in language/src/test/java/lang-skip.txt.
Top-level packages: For every top-level nixpkgs attribute (scripts/toplevel-drvpaths.nix), affogato and nix-instantiate produce 24,268 identical drvPaths. 680 attributes fail in both, and none differ or fail in only one evaluator. The run takes 1 min 40 s on the JVM, against 2 min 08 s for Nix.
Heavier attributes: scripts/parity.sh finds identical drvPaths for firefox, chromium, libreoffice, texliveFull, haskellPackages.pandoc, nixosTests.firefox, pkgsCross.aarch64-multiplatform.hello and pkgsStatic.hello.

Not supported

Fetchers (fetchurl, fetchTarball, fetchGit, fetchTree) and flakes.
Import from derivation.
Content-addressed and impure derivations.
--xml output.
The --lint-* flags.
Rejection of NUL bytes in strings, and UTF-8 validation in toJSON.

Architecture

Each top-level folder is a Java module.

parser/

A hand-written lexer and parser. It builds a concrete syntax tree that keeps every token, then lowers it to the evaluator’s AST.

store/

NAR hashing, Nix base32 and store-path computation.

language/

The Truffle language:

Translator: static scope resolution into Truffle nodes.
nodes/ and runtime/: the evaluator and its values.
builtins/: the builtins.
corepkgs/: Nix’s derivation.nix and fetchurl.nix, vendored from NixOS/nix.

launcher/

The command line, built on the polyglot API, plus its native-image build.

format/

The formatter.

lint/

The linter.

Formatter

org.affogato.format.Formatter ports nixfmt 1.5.0 (MPL-2.0) to the parser’s concrete syntax tree. Formatter.format(src) formats with nixfmt’s defaults. format(src, width, indent, strict) sets the line width, the indentation and nixfmt’s strict mode.

Linter

org.affogato.lint.Linter runs checks in the spirit of deadnix (unused bindings), statix (simpler forms) and nixd (undefined variables, unknown builtins, unused with and rec). Linter.lint(src) returns the diagnostics, and Linter.fix(src) applies the fixes that come with most of them. Both take an optional set of Rule values to restrict the checks. Lint rules lists the rules.

Tests

language/src/test/java/

The evaluator’s test module. Its data are packaged with it, so the tests rerun whenever the data change.

lang/: NixOS/nix’s tests/functional/lang (LGPL-2.1).
tvix/: Tvix’s eval/src/tests/tvix_tests.
affogato/: affogato’s own regression tests.

format/src/test/java/nixfmt/

nixfmt’s own test suite.

lint/src/test/java/cases/

The linter’s cases.

The upstream suites are kept in sync with vendir. To follow a new Nix release, change ref in vendir.yml, run vendir sync, and update lang-symlinks.txt if upstream added symlinks (the jar cannot hold them).

Lint rules

Each rule shows a case from the linter’s tests: the original code, what the rule’s fixes make of it, and what the rule reports, with [fix] after the findings that come with a fix.

Rule Severity Description

Rule	Severity	Description
`syntax-error`	❌ error	The code does not parse, or breaks a rule Nix checks while parsing, such as defining an attribute twice. No other rule runs then.
`unused-let-binding`	⚠️ warning	A `let` binding that the body never reaches. A binding used only by itself, or by other unused bindings, counts as unused too. The fix removes it.
`unused-lambda-arg`	⚠️ warning	A function argument that the body never uses. The fix renames it to , unless the body uses an outer .
`unused-formal`	⚠️ warning	An attribute of a function’s pattern that the body never uses. It is not reported when the `@` binding is used, as that may pass it on. The fix removes it only when the pattern has `...`, so that callers passing it still work.
`unused-at-pattern`	⚠️ warning	An `@` binding that the body never uses. The fix removes it.
`bool-comparison`	⚠️ warning	A comparison with `true` or `false`. There is no fix: `v == true` is also a type test, where `v` alone fails on other types.
`bool-simplification`	⚠️ warning	`!(a == b)`, which is `a != b`, and `!(a != b)`, which is `a == b`.
`empty-let-in`	⚠️ warning	A `let` with no bindings.
`collapsible-let-in`	⚠️ warning	A `let` right in the body of another. The fix merges them unless the outer bindings use or bind a name of the inner ones.
`legacy-let-syntax`	⚠️ warning	The deprecated `let { ...; body = ...; }`. The fix turns it into `rec { ...; body = ...; }.body`.
`empty-inherit`	⚠️ warning	An `inherit` with no names.
`empty-pattern`	⚠️ warning	A function taking `{ }`. There is no fix: `_:` would also accept arguments that are not an empty attribute set.
`redundant-pattern-bind`	⚠️ warning	`{ ... }@x: body`, which can be written `x: body`.
`manual-inherit`	⚠️ warning	`a = a;` in an attribute set that is not recursive, which is `inherit a;`.
`manual-inherit-from`	⚠️ warning	`a = e.a;`, which is `inherit (e) a;`.
`eta-reduction`	💡 hint	`x: f x`, which is `f` when `f` is a name or an attribute path that does not use `x`.
`useless-parens`	⚠️ warning	Parentheses around a simple expression, or around a whole binding value, `let` body, interpolation or file.
`unquoted-uri`	⚠️ warning	A URI literal, which is deprecated. The fix quotes it.
`deprecated-is-null`	⚠️ warning	`isNull e`, which is `e == null`.
`deprecated-to-path`	⚠️ warning	`builtins.toPath`, which is deprecated. There is no fix.
`empty-list-concat`	⚠️ warning	A concatenation with `[ ]`.
`useless-has-attr`	⚠️ warning	`if x ? a then x.a else d`, which is `x.a or d`.
`faster-builtin`	💡 hint	`lib.groupBy` and `lib.zipAttrsWith`, which the builtins of the same names implement natively.
`repeated-keys`	💡 hint	Three or more bindings that start with the same attribute, such as `a.b`, `a.c` and `a.d`, which could form one nested attribute set. The fix moves them into `a = { ... };` in place of the first, with the comments on their lines; `a.b.c`, `a.b.d` and `a.b.e` go into `a.b = { ... };`. It is withheld when the set also binds `a` whole, or when bindings over several lines do not each start a line.
`undefined-variable`	❌ error	A variable that no binding defines, outside any `with`. Nix rejects the file before evaluating it.
`unknown-builtin`	❌ error	`builtins.x` where `x` is not a builtin, unless the file tests `builtins ? x` or gives an `or` fallback.
`prefixed-builtin`	⚠️ warning	`__x` for the builtin `builtins.x`.
`shadowed-builtin`	⚠️ warning	A binding that hides a global such as `map`, `true` or `builtins`. Attributes of a `rec` set and names inherited from an expression are not reported.
`extra-rec`	⚠️ warning	A `rec` attribute set whose attributes never refer to each other.
`extra-with`	⚠️ warning	A `with` that no variable can come from.
`missing-phase-hooks`	⚠️ warning	A phase such as `installPhase` set to a string that does not run its hooks: nixpkgs expects `runHook preInstall` first and `runHook postInstall` last, so that `preInstall` and `postInstall` still work. The fix adds the missing calls to strings of several lines.
`missing-final-attrs`	⚠️ warning	A derivation built from a `rec` set whose attributes refer to each other, such as `stdenv.mkDerivation rec { ... }`. With `finalAttrs: { ... }`, an override of `version` through `overrideAttrs` also reaches the attributes that use it. The fix rewrites the references to `finalAttrs.version` and the like. For builders other than `stdenv.mkDerivation`, `finalAttrs` holds the attributes the builder made, so the fix is only offered when the references are to `pname`, `version` and `src`.
`missing-structured-attrs`	💡 hint	A derivation that does not set `structuredAttrs`, which nixpkgs expects to be `true` for new packages. The builders that default it to `true`, such as those for Python, are not reported. The fix adds `structuredAttrs = true;` after `pname` and `version`; it changes the build, since phases then see lists as Bash arrays, so check that the package still builds.
`missing-strict-deps`	💡 hint	A derivation that does not set `strictDeps`, which nixpkgs expects to be `true` for new packages. The builders that set it already, such as those for Python, Go and Rust, are not reported. The fix adds `strictDeps = true;` after `pname` and `version`, or under `__structuredAttrs`; it changes the build, since tools must then be in `nativeBuildInputs` and libraries in `buildInputs`, so check that the package still builds.
`deprecated-replace`	⚠️ warning	`substituteInPlace` and the other `substitute` functions called with `--replace`, which is deprecated and behaves as `--replace-warn`: a pattern that no longer matches only prints a warning. The fix uses `--replace-fail`, which makes such a build fail instead, so check that the package still builds.
`sri-hash`	⚠️ warning	A fetcher given `sha256`, where nixpkgs uses `hash` with an SRI hash such as `sha256-…=`. The fix renames it and converts a literal in Nix base32, hex or base64; `lib.fakeSha256` becomes `lib.fakeHash`. Fetchers that take only `sha256`, such as `fetchHex`, are not reported.
`env-variable`	⚠️ warning	A `NIX_` variable such as `NIX_CFLAGS_COMPILE` set beside the attributes of a derivation: with `__structuredAttrs`, only `env` is exported, so the compiler wrapper would not see it. The fix moves it to `env`, through `toString` unless it is a string already. It is withheld when `env` is not an attribute set written in place, or the file refers to the variable elsewhere, as `finalAttrs.NIX_LDFLAGS`.

syntax-error

❌ error

The code does not parse, or breaks a rule Nix checks while parsing, such as defining an attribute twice. No other rule runs then.

unused-let-binding

⚠️ warning

A let binding that the body never reaches. A binding used only by itself, or by other unused bindings, counts as unused too. The fix removes it.

unused-lambda-arg

⚠️ warning

A function argument that the body never uses. The fix renames it to , unless the body uses an outer .

unused-formal

⚠️ warning

An attribute of a function’s pattern that the body never uses. It is not reported when the @ binding is used, as that may pass it on. The fix removes it only when the pattern has ..., so that callers passing it still work.

unused-at-pattern

⚠️ warning

An @ binding that the body never uses. The fix removes it.

bool-comparison

⚠️ warning

A comparison with true or false. There is no fix: v == true is also a type test, where v alone fails on other types.

bool-simplification

⚠️ warning

!(a == b), which is a != b, and !(a != b), which is a == b.

empty-let-in

⚠️ warning

A let with no bindings.

collapsible-let-in

⚠️ warning

A let right in the body of another. The fix merges them unless the outer bindings use or bind a name of the inner ones.

legacy-let-syntax

⚠️ warning

The deprecated let { ...; body = ...; }. The fix turns it into rec { ...; body = ...; }.body.

empty-inherit

⚠️ warning

An inherit with no names.

empty-pattern

⚠️ warning

A function taking { }. There is no fix: _: would also accept arguments that are not an empty attribute set.

redundant-pattern-bind

⚠️ warning

{ ... }@x: body, which can be written x: body.

manual-inherit

⚠️ warning

a = a; in an attribute set that is not recursive, which is inherit a;.

manual-inherit-from

⚠️ warning

a = e.a;, which is inherit (e) a;.

eta-reduction

💡 hint

x: f x, which is f when f is a name or an attribute path that does not use x.

useless-parens

⚠️ warning

Parentheses around a simple expression, or around a whole binding value, let body, interpolation or file.

unquoted-uri

⚠️ warning

A URI literal, which is deprecated. The fix quotes it.

deprecated-is-null

⚠️ warning

isNull e, which is e == null.

deprecated-to-path

⚠️ warning

builtins.toPath, which is deprecated. There is no fix.

empty-list-concat

⚠️ warning

A concatenation with [ ].

useless-has-attr

⚠️ warning

if x ? a then x.a else d, which is x.a or d.

faster-builtin

💡 hint

lib.groupBy and lib.zipAttrsWith, which the builtins of the same names implement natively.

repeated-keys

💡 hint

Three or more bindings that start with the same attribute, such as a.b, a.c and a.d, which could form one nested attribute set. The fix moves them into a = { ... }; in place of the first, with the comments on their lines; a.b.c, a.b.d and a.b.e go into a.b = { ... };. It is withheld when the set also binds a whole, or when bindings over several lines do not each start a line.

undefined-variable

❌ error

A variable that no binding defines, outside any with. Nix rejects the file before evaluating it.

unknown-builtin

❌ error

builtins.x where x is not a builtin, unless the file tests builtins ? x or gives an or fallback.

prefixed-builtin

⚠️ warning

__x for the builtin builtins.x.

shadowed-builtin

⚠️ warning

A binding that hides a global such as map, true or builtins. Attributes of a rec set and names inherited from an expression are not reported.

extra-rec

⚠️ warning

A rec attribute set whose attributes never refer to each other.

extra-with

⚠️ warning

A with that no variable can come from.

missing-phase-hooks

⚠️ warning

A phase such as installPhase set to a string that does not run its hooks: nixpkgs expects runHook preInstall first and runHook postInstall last, so that preInstall and postInstall still work. The fix adds the missing calls to strings of several lines.

missing-final-attrs

⚠️ warning

A derivation built from a rec set whose attributes refer to each other, such as stdenv.mkDerivation rec { ... }. With finalAttrs: { ... }, an override of version through overrideAttrs also reaches the attributes that use it. The fix rewrites the references to finalAttrs.version and the like. For builders other than stdenv.mkDerivation, finalAttrs holds the attributes the builder made, so the fix is only offered when the references are to pname, version and src.

missing-structured-attrs

💡 hint

A derivation that does not set structuredAttrs, which nixpkgs expects to be true for new packages. The builders that default it to true, such as those for Python, are not reported. The fix adds structuredAttrs = true; after pname and version; it changes the build, since phases then see lists as Bash arrays, so check that the package still builds.

missing-strict-deps

💡 hint

A derivation that does not set strictDeps, which nixpkgs expects to be true for new packages. The builders that set it already, such as those for Python, Go and Rust, are not reported. The fix adds strictDeps = true; after pname and version, or under __structuredAttrs; it changes the build, since tools must then be in nativeBuildInputs and libraries in buildInputs, so check that the package still builds.

deprecated-replace

⚠️ warning

substituteInPlace and the other substitute functions called with --replace, which is deprecated and behaves as --replace-warn: a pattern that no longer matches only prints a warning. The fix uses --replace-fail, which makes such a build fail instead, so check that the package still builds.

sri-hash

⚠️ warning

A fetcher given sha256, where nixpkgs uses hash with an SRI hash such as sha256-…=. The fix renames it and converts a literal in Nix base32, hex or base64; lib.fakeSha256 becomes lib.fakeHash. Fetchers that take only sha256, such as fetchHex, are not reported.

env-variable

⚠️ warning

A NIX_ variable such as NIX_CFLAGS_COMPILE set beside the attributes of a derivation: with __structuredAttrs, only env is exported, so the compiler wrapper would not see it. The fix moves it to env, through toString unless it is a string already. It is withheld when env is not an attribute set written in place, or the file refers to the variable elsewhere, as finalAttrs.NIX_LDFLAGS.

Syntax errors

`syntax-error`

Severity: ❌ error. The code does not parse, or breaks a rule Nix checks while parsing, such as defining an attribute twice. No other rule runs then.

Original

{
  a = 1;
  a = 2;
}

Diagnostics

syntax-error.nix:3:3: error[syntax-error]: attribute 'a' already defined

Dead code

Bindings that nothing uses, as deadnix finds them. Names starting with _ are never reported.

`unused-let-binding`

Severity: ⚠️ warning. A let binding that the body never reaches. A binding used only by itself, or by other unused bindings, counts as unused too. The fix removes it.

affogato

Getting started

Command line

Synopsis

Options

Commands

treefmt

Status

Not supported

Architecture

Formatter

Linter

Tests

Lint rules

Syntax errors

syntax-error

Dead code

unused-let-binding

unused-lambda-arg

unused-formal

unused-at-pattern

Simpler forms

bool-comparison

bool-simplification

empty-let-in

collapsible-let-in

legacy-let-syntax

empty-inherit

empty-pattern

redundant-pattern-bind

manual-inherit

manual-inherit-from

eta-reduction

useless-parens

unquoted-uri

deprecated-is-null

deprecated-to-path

empty-list-concat

useless-has-attr

faster-builtin

repeated-keys

Semantics

undefined-variable

unknown-builtin

prefixed-builtin

shadowed-builtin

extra-rec

extra-with

Packaging

missing-phase-hooks

missing-final-attrs

missing-structured-attrs

missing-strict-deps

deprecated-replace

sri-hash

env-variable

Building

Playground

Documentation

Dependencies

Nix

`syntax-error`

`unused-let-binding`

`unused-lambda-arg`

`unused-formal`

`unused-at-pattern`

`bool-comparison`

`bool-simplification`

`empty-let-in`

`collapsible-let-in`

`legacy-let-syntax`

`empty-inherit`

`empty-pattern`

`redundant-pattern-bind`

`manual-inherit`

`manual-inherit-from`

`eta-reduction`

`useless-parens`

`unquoted-uri`

`deprecated-is-null`

`deprecated-to-path`

`empty-list-concat`

`useless-has-attr`

`faster-builtin`

`repeated-keys`

`undefined-variable`

`unknown-builtin`

`prefixed-builtin`

`shadowed-builtin`

`extra-rec`

`extra-with`

`missing-phase-hooks`

`missing-final-attrs`

`missing-structured-attrs`

`missing-strict-deps`

`deprecated-replace`

`sri-hash`

`env-variable`