Enhance completion details for builtins if Nix 2.4 is available (#27)

A hidden feature of Nix 2.4+ (a.k.a. `nixUnstable`) is `nix
__dump-builtins` which returns a JSON giving details about built in
functions.

This change basically does the following things:

* It checks whether Nix 2.4 is available on `$PATH`[1]. In that case
  built-in functions are retrieved via `nix __dump-builtins`[2].

  If not, the hard-coded list of builtins is used as a fallback.

* If builtins can be retrieved from Nix, the following additional things
  are added to `CompletionItem`:

  * The `documentation`[3] field containing markdown documentation for the
    function is added. This will be shown in editors as one is used to
    it from e.g. doc-block comments in other languages.

  * A very basic parameter info is provided. E.g. for
    `builtins.removeAttrs` the popup shows `Lambda: set -> list ->
    Result`. While this is fairly basic, it's IMHO a small benefit to
    make sure one's not forgetting the order of parameters.

    Please note that this will currently display *wrong* info if
    a built-in is called via `lib.flip`.

  * If `**DEPRECATED.**` is at the beginning of `documentation`, the
    built-in is marked in the LSP response as `deprecated`. While this
    is a gross hack, it ensures that the only deprecated builtin
    (`builtins.toPath`) is actually marked as such.

[1] Please note that this means that you can wrap `$PATH` for `rnix-lsp`
    to have this feature without being forced to use `nixUnstable` on
    your system.
[2] As this is only an optional feature (and hence a loose dependency to
    Nix) I decided against using an FFI and thus keeping the build
    process rather simple.
[3] https://microsoft.github.io/language-server-protocol/specification#textDocument_completion

Co-authored-by: jD91mZM2 <[email protected]>

Author: Ma27

Cargo.lock

@@ -19,6 +19,7 @@ log = "0.4.8"
 lsp-server = "0.3.1"
 lsp-types = { version = "0.68.1", features = ["proposed"] }
 nixpkgs-fmt = "1.1.0"
+regex = "1"
 rnix = "0.9.0"
 rowan = "0.12.6"
 serde = "1.0.104"

Cargo.toml

@@ -12,8 +12,9 @@ use std::{
 
 use lazy_static::lazy_static;
 
-// FIXME use Nix bindings to dynamically extract existing builtins.
-// e.g. use API behind `nix __dump-builtins`.
+use std::{process, str};
+use regex;
+
 lazy_static! {
     static ref BUILTINS: Vec<String> = vec![
       // `nix __dump-builtins | jq 'keys'
@@ -29,34 +30,80 @@ lazy_static! {
     ].into_iter().map(String::from).collect::<Vec<_>>();
 }
 
+#[derive(Debug)]
+pub struct LSPDetails {
+    pub datatype: Datatype,
+    pub var: Option<Var>,
+    pub documentation: Option<String>,
+    pub deprecated: bool,
+    pub params: Option<String>,
+}
+
+impl LSPDetails {
+    fn builtin_fallback() -> LSPDetails {
+        LSPDetails {
+            datatype: Datatype::Lambda,
+            var: None,
+            documentation: None,
+            deprecated: false,
+            params: None,
+        }
+    }
+
+    fn builtin_with_doc(deprecated: bool, params: Option<String>, documentation: String) -> LSPDetails {
+        LSPDetails {
+            datatype: Datatype::Lambda,
+            var: None,
+            documentation: Some(documentation),
+            deprecated,
+            params,
+        }
+    }
+
+    fn from_scope(datatype: Datatype, var: Var) -> LSPDetails {
+        LSPDetails {
+            datatype,
+            var: Some(var),
+            documentation: None,
+            deprecated: false,
+            params: None,
+        }
+    }
+
+    pub fn render_detail(&self) -> String {
+        match &self.params {
+            None => self.datatype.to_string(),
+            Some(params) => format!("{}: {} -> Result", self.datatype.to_string(), params),
+        }
+    }
+}
+
 impl App {
     pub fn scope_for_ident(
         &mut self,
         file: Url,
         root: &SyntaxNode,
         offset: usize,
-    ) -> Option<(Ident, HashMap<String, (Datatype, Option<Var>)>, String)> {
+    ) -> Option<(Ident, HashMap<String, LSPDetails>, String)> {
+
         let mut file = Rc::new(file);
         let info = utils::ident_at(&root, offset)?;
         let ident = info.ident;
         let mut entries = utils::scope_for(&file, ident.node().clone())?
             .into_iter()
-            .map(|(x, var)| (x.to_owned(), (var.datatype, Some(var))))
+            .map(|(x, var)| (x.to_owned(), LSPDetails::from_scope(var.datatype, var)))
             .collect::<HashMap<_, _>>();
         for var in info.path {
             if !entries.contains_key(&var) && var == "builtins" {
-                entries = BUILTINS
-                    .iter()
-                    .map(|x| (x.to_owned(), (Datatype::Lambda, None)))
-                    .collect::<HashMap<_, _>>();
+                entries = self.load_builtins();
             } else {
                 let node_entry = entries.get(&var)?;
-                if let (_, Some(var)) = node_entry {
+                if let Some(var) = &node_entry.var {
                     let node = var.value.clone()?;
                     entries = self
                         .scope_from_node(&mut file, node)?
                         .into_iter()
-                        .map(|(x, var)| (x.to_owned(), (var.datatype, Some(var))))
+                        .map(|(x, var)| (x.to_owned(), LSPDetails::from_scope(var.datatype, var)))
                         .collect::<HashMap<_, _>>();
                 }
             }
@@ -118,4 +165,49 @@ impl App {
         }
         Some(scope)
     }
+
+    fn fallback_builtins(&self, list: Vec<String>) -> HashMap<String, LSPDetails> {
+        list.into_iter().map(|x| (x, LSPDetails::builtin_fallback())).collect::<HashMap<_, _>>()
+    }
+
+    fn load_builtins(&self) -> HashMap<String, LSPDetails> {
+        let nixver = process::Command::new("nix").args(&["--version"]).output();
+
+        // `nix __dump-builtins` is only supported on `nixUnstable` a.k.a. Nix 2.4.
+        // Thus, we have to check if this is actually available. If not, `rnix-lsp` will fall
+        // back to a hard-coded list of builtins which is missing additional info such as documentation
+        // or parameter names though.
+        match nixver {
+            Ok(out) => {
+                match str::from_utf8(&out.stdout) {
+                    Ok(v) => {
+                        let re = regex::Regex::new(r"^nix \(Nix\) (?P<major>\d)\.(?P<minor>\d).*").unwrap();
+                        let m = re.captures(v).unwrap();
+                        let major = m.name("major").map_or(1, |m| m.as_str().parse::<u8>().unwrap());
+                        let minor = m.name("minor").map_or(1, |m| m.as_str().parse::<u8>().unwrap());
+                        if major == 2 && minor >= 4 || major > 2 {
+                            let builtins_raw = process::Command::new("nix").args(&["__dump-builtins"]).output().unwrap();
+                            let v: serde_json::Value = serde_json::from_str(str::from_utf8(&builtins_raw.stdout).unwrap()).unwrap();
+
+                            v.as_object().unwrap()
+                                .iter().map(|(x, v)| {
+                                    let doc = String::from(v["doc"].as_str().unwrap());
+                                    (String::from(x), LSPDetails::builtin_with_doc(
+                                        doc.starts_with("**DEPRECATED.**"),
+                                        // FIXME make sure that `lib.flip` is taken into account here
+                                        v["args"].as_array().map(|x| x.iter().map(|y| y.as_str().unwrap()).collect::<Vec<_>>().join(" -> ")),
+                                        doc
+                                    ))
+                                })
+                                .collect::<HashMap<_, _>>()
+                        } else {
+                            self.fallback_builtins(BUILTINS.to_vec())
+                        }
+                    },
+                    Err(_) => self.fallback_builtins(BUILTINS.to_vec()),
+                }
+            },
+            Err(_) => self.fallback_builtins(BUILTINS.to_vec()),
+        }
+    }
 }

src/lookup.rs

@@ -249,7 +249,7 @@ impl App {
         let (name, scope, _) = self.scope_for_ident(params.text_document.uri, &node, offset)?;
 
         let var_e = scope.get(name.as_str())?;
-        if let (_, Some(var)) = var_e {
+        if let Some(var) = &var_e.var {
             let (_definition_ast, definition_content) = self.files.get(&var.file)?;
             Some(Location {
                 uri: (*var.file).clone(),
@@ -272,15 +272,18 @@ impl App {
         let (_, content) = self.files.get(&params.text_document.uri)?;
 
         let mut completions = Vec::new();
-        for (var, (datatype, _)) in scope {
+        for (var, data) in scope {
             if var.starts_with(&name.as_str()) {
+                let det = data.render_detail();
                 completions.push(CompletionItem {
                     label: var.clone(),
+                    documentation: data.documentation.map(|x| lsp_types::Documentation::String(x)),
+                    deprecated: Some(data.deprecated),
                     text_edit: Some(TextEdit {
                         range: utils::range(content, node.node().text_range()),
                         new_text: var.clone(),
                     }),
-                    detail: Some(datatype.to_string()),
+                    detail: Some(det),
                     ..CompletionItem::default()
                 });
             }