Proposal: upstream this project to nixpkgs

[jfly]

nixpkgs recently landed treefmt.withConfig. It's difficult to explain to people when they should use treefmt.withConfig vs treefmt-nix.

For example, see this difficult-to-write nix.dev doc on autoformatting, this revert of that doc, and this conversation.

I think we could address this confusion by upstreaming treefmt-nix to nixpkgs. When we do so, we could either re-implement it with treefmt.withConfig under the hood, or (my preference) just merge it with treefmt.withConfig.

Thoughts?

[MattSturgeon]

Programs

I believe the primary value-add of this project compared to treefmt.withConfig is the bank of pre-configured programs modules.

I don't see any reason why these modules couldn't be upstreamed somewhere like pkgs/by-name/tr/treefmt/programs.

Ideally, it might make sense to have the program modules defined as passthru attrs on the respective program packages. However with that approach I don't know a good way to collect all the packages that have treefmt-program modules without recursively iterating through all of nixpkgs or having a centrally maintained list anyway.

It's worth noting that we aren't just dealing with top-level packages: e.g. package sets like nodePackages contain formatters like prettier.

Other ideas

(Notes adapted from discussion on matrix)

My initial idea was to recursively collect derivations with treefmtModule attrs:

let
  # A list of all derivations found recursively in `pkgs`
  packages = collect isDerivation (removeAttrs pkgs [
    # Avoid inf-rec
    "pkgs"
    "pkgsStatic"
    # ...
  ]);

  # A list of all treefmt modules found in `packages`
  modules = catAttrs "treefmtModule" packages;
in

The above would be somewhat expensive and inefficient, and avoiding infinite recursion would be more complex then my example here.

It could be simplified and made more efficient by avoiding the recursion; instead we would maintain a list of package sets known to contain formatters and not recurse into them beyond their top-level:

let
  # A list of package sets to search, in addition to top-level `pkgs`
  setNames = [
    "nodePackages"
    # ...
  ];

  # A list of all derivations found in top-level `pkgs` & each package set
  packages = pipe setNames [
    # Get each package set
    (map (name: pkgs.${name}))
    # Also get the top-level packages
    (sets: [ pkgs ] ++ sets)
    # Flatten to a list of packages
    (concatMap attrValues)
    (filter isDerivation)
  ];

  # A list of all treefmt modules found in `packages`
  modules = catAttrs "treefmtModule" packages;
in

Alternatively, instead of maintaining a list of all package sets manually, we could take all attr names that end with "Packages":

# A list of package sets to search, in addition to top-level `pkgs`
setNames = filter (hasSuffix "Packages") (attrNames pkgs);

...but that's an implementation detail and I'm getting ahead of myself.

---

Another idea proposed is to use a standard pkgs/by-name file path, which could be discovered via builtins.readDir:

there's also the idea of standardising pkgs/by-name/fo/foo/treefmt.nix for each package to declare a treefmt-specific submodule, which can then be automatically discovered :)
— @infinisil

This sounds like it'd be slightly more efficient for top-level packages, since you don't need to iterate through pkgs. However I'm unsure how you'd handle package sets and other packages that aren't yet in by-name.

---

treefmt.withConfig currently only treats settings as a module eval (with a freeform rfc42 style), however it could be extended to treat its entire argument as a module, with its current args being converted to options.

Its worth noting that this could be upstreamed to nixpkgs and then used by both treefmt-nix and treefmt.withConfig. Assuming the upstreamed option keeps to the same structure currently used here.

Option docs

The second major value-add of this project is its documentation. Currently I don't know where the best place would be to put module/option docs for withConfig. Ideally this would be somewhere within the nixpkgs manual, maybe in the packages chapter?

From a technical perspective, the nixpkgs manual doesn't currently have a good way to add additional option-docs...

Currently the top-level pkgs config is the only option-set with generated docs (other options are usually part of NixOS, so are documented in the NixOS manual).

Currently generating docs for the top-level pkgs config options is hardcoded:

Details

https://github.com/NixOS/nixpkgs/blob/937626a85dfeb7046196d65b13d8ae6082f00e88/doc/doc-support/options-doc.nix#L5-L8

https://github.com/NixOS/nixpkgs/blob/937626a85dfeb7046196d65b13d8ae6082f00e88/doc/doc-support/package.nix#L118

https://github.com/NixOS/nixpkgs/blob/937626a85dfeb7046196d65b13d8ae6082f00e88/doc/doc-support/package.nix#L22C38-L22C48

https://github.com/NixOS/nixpkgs/blob/937626a85dfeb7046196d65b13d8ae6082f00e88/doc/doc-support/package.nix#L48-L50

https://github.com/NixOS/nixpkgs/blob/688122cd5d3f78c45c6dbdeb2d72de41070f12ff/doc/using/configuration.chapter.md?plain=1#L197-L201

I guess we could also hard-code option docs in the same way. In this way treefmt.withConfig would become the second thing in the nixpkgs manual to have generated option docs. 😅

Other

There's a few other things that treefmt-nix provides that treefmt.withConfig currently does not. I'm not too familiar with these so IDK how/if they can be upstreamed.

• build.check
• build.devShell
• flakeCheck
• flakeFormatter
• Others?

[MattSturgeon]

It'd be good to hear thoughts from maintainers and contributors, even if just (👍 👎) acknowledging the concept; or brief comments raising any concerns/benefits/ideas/etc.

CC some contributors: @brianmcgee @Mic92 @zimbatm @phanirithvij

[phanirithvij]

these are my concerns

1. it slows down the development velocity for treefmt-nix's frequent contributors compared to how it is now.
2. nixpkgs' ever growing tarball size, its decompression time and frequent copying to nix store. (treefmt-nix adds ~912KB uncompressed, making it the 2nd biggest package by size on nixpkgs)

[mightyiam]

2. nixpkgs' ever growing tarball size, its decompression time and frequent copying to nix store. (treefmt-nix adds ~912KB uncompressed, making it the 2nd biggest package by size on nixpkgs)

This sounds like a concern

[brianmcgee]

1. it slows down the development velocity for treefmt-nix's frequent contributors compared to how it is now.

This is my main concern.

[zimbatm]

If treefmt.withConfig is causing confusion, we should also consider all the options available.

1. Remove treefmt.withConfig. If I am not mistaken that option was added to serve the nixpkgs internal formatter. This could be a premature generalization.
2. Use a formatter sub-flake in nixpkgs that points to treefmt-nix.
3. Upstream treefmt-nix.

Pros for upstreaming:

1. Formatter config can evolve at the same time as the packages. This is a friction we have in this repo sometimes.
2. Removes the cyclic dependency for the internal nixpkgs formatter.

Cons:
a. Brian and Jeremy don't have commit access.
b. Issues are gertting drowned in the nixpkgs issue tracker.
b. The project goes from having a dedicated space to being hidden in nixpkgs. We would have to restore some sort of landing page and manual somehow.
c. Nixpkgs gets larger.

[MattSturgeon]

If treefmt.withConfig is causing confusion,

I'm not aware of it causing confusion yet, but it has lead to challenges writing documentation that is itself simple and not confusing 😁

While on the topic, even the split between treefmt and treefmt-nix has the same potential for confusion, so it could be argued that upstreaming treefmt-nix to nixpkgs is killing two birds with one stone 😉

we should also consider all the options available.

👍

1. Remove `treefmt.withConfig`. If I am not mistaken that option was added to serve the nixpkgs internal formatter. This could be a premature generalization.

It was inspired by nixfmt-tree, and used for its refactored impl, but my main motivation for writing it was allowing users to wrap treefmt with a nix-based config without needing additional dependencies or flakes.

2. Use a formatter sub-flake in nixpkgs that points to treefmt-nix.

We can't really rely on flakes in nixpkgs, but we could fetch a pinned version of treefmt-nix using fetchFromGitHub.

3. Upstream treefmt-nix.

This is my preference

Cons:
a. Brian and Jeremy don't have commit access.

Currently, yes. Anecdotally, have they had any friction getting their previous nixpkgs PRs merged? E.g. Brian does most of the treefmt package bumps IIUC

b. Issues are getting drowned in the nixpkgs issue tracker.

That could be a valid concern.

b. The project goes from having a dedicated space to being hidden in nixpkgs. We would have to restore some sort of landing page and manual somehow.

You could argue that treefmt as a whole is already split across treefmt and treefmt-nix.

Currently treefmt recommends nix users look at treefmt-nix, this could be updated to point nix users to the relevant nixpkgs manual section and/or nix.dev pages.

c. Nixpkgs gets larger.

IMO this is not a major concern, no more than with any addition to nixpkgs.

Currently treefmt-nix checked out is 1MB (excl .git), with the majority of it being 450kB of programs and 390kB of examples.

For comparison, a checked out nixpkgs worktree is 307MB, principally made up of 274MB of pkgs and 28MB of nixos modules.

[jfly]

We discussed this at today's formatting team meeting along with @zimbatm and @brianmcgee. We agreed not to put this in nixpkgs (the size of nixpkgs, who has commit access, etc).

We discussed various ways for nixpkgs itself to consume treefmt-nix:

• yarn2nix was vendored, let’s not do that again.
• Would this cause IFD? Not-necessarily. See https://github.com/NixOS/nixpkgs/blob/0784176a58ee388089e90134750ce963fd812a74/ci/default.nix#L27-L31 for one way to avoid IFD, but you'd want to avoid Hydra evaluating this, perhaps with a passthru. But nixfmt-tree currently uses treefmt.withConfig, and if we re-implemented treefmt.withConfig to use treefmt-nix under the hood (with the fetchTarball above), then we’d have trouble with Hydra.

If somebody wants to come up with good ideas to these questions, please go ahead. In the meantime, we're just going to let nixpkg’s treefmt.withConfig and treefmt-nix evolve in parallel.