# Usecases for a nix lsp

This document describes a bunch of usecases where LSP support would be helpful.

## Completion when editing existing package definitions in a nixpkgs checkout

Usecase: I edit an existing package definition `baz` in a nixpkgs checkout.
I want to fix a build failure by adding a missing build dependency `newdep`.

  { pkgs
  , stdenv
  , ...
  }: stdenv.mkDerivation {
    name = "baz";

    buildInputs = [
      pkgs.foo
      pkgs.bar
      pkgs.new<TAB>
    ];

    # …
  }

I'd expect the LSP to help me complete `pkgs.new`, provide a list of available packages starting with `new`, alongside with descriptions of what that package does. For packages, it could potentially just be `meta.description` of the
package.

Challenges:

- This file itself is simply defining a function accepting `pkgs` and `stdenv` as arguments.
We don't *know* `pkgs` is pointing to the nixpkgs package set, and we don't
know what `stdenv` is pointing to either.
- Because this is an existing file, already imported from `all-packages.nix`
or similar, we could try to find how it is being called, or have some
heuristics.

## Completing `lib` (docstrings)
Take the same example, but extend the build script with an optional string.

You add `lib` to the toplevel argument list, and expect to be able to complete `lib.optionalString`. It should show the docstring of that function (defined in
nixpkgs' `lib/strings.nix`).

The format of docstrings (and if they look like the ones currently in there or not) is still TBD.

## Adding a new package definition into nixpkgs

Take the same "baz package" example, but assume it's a new package, with the file not yet being called from `all-packages.nix` yet.

Do we want to have some heuristics, and map `pkgs` to one from `<nixpkgs>`?

Do we want to fail completing alltogether (similar to how `rust-anaylyzer` doesn't give completion if you don't add a `.rs` file via `mod` from `{lib,mod}.rs`).

## Adding a new package definition in a monorepo

In these cases, heuristics might work even less, because `pkgs` in the context of that repo is often pointing to an (old) nixpkgs checkout, with a lot of
local overrides.

If you look at the TVL monorepo, there's also a different calling convention, there's also `third_party` as a toplevel argument, with `nixpkgs` as a lower
element.

We might have to do some "reachability analysis" to determine the what `third_party` etc. is.