Add explainshell integration

README.md

@@ -1,7 +1,7 @@
 # Bash Language Server
 
 Bash language server implementation based on [Tree Sitter][tree-sitter] and its
-[grammar for Bash][tree-sitter-bash].
+[grammar for Bash][tree-sitter-bash] with [explainshell][explainshell] integration.
 
 ## Features
 
@@ -11,6 +11,7 @@ Bash language server implementation based on [Tree Sitter][tree-sitter] and its
 - [x] Highlight occurrences
 - [x] Code completion
 - [x] Simple diagnostics reporting
+- [x] Documentation for flags on hover
 - [ ] Rename symbol
 
 ## Installation
@@ -44,3 +45,4 @@ Please see [docs/development-guide][dev-guide] for more information.
 [vscode-marketplace]: https://marketplace.visualstudio.com/items?itemName=mads-hartmann.bash-ide-vscode
 [dev-guide]: https://github.com/mads-hartmann/bash-language-server/blob/master/docs/development-guide.md
 [ide-bash]: https://atom.io/packages/ide-bash
+[explainshell]: https://explainshell.com/

server/package.json

@@ -18,8 +18,11 @@
   },
   "dependencies": {
     "glob": "^7.1.2",
+    "request-promise-native": "^1.0.5",
     "tree-sitter": "^0.11.0",
     "tree-sitter-bash": "^0.11.0",
+    "turndown": "^4.0.2",
+    "urijs": "^1.19.1",
     "vscode-languageserver": "^4.1.1"
   },
   "scripts": {

server/src/analyser.ts

@@ -3,8 +3,10 @@ import * as fs from 'fs'
 import * as glob from 'glob'
 import * as Path from 'path'
 
+import * as request from 'request-promise-native'
 import { Document } from 'tree-sitter'
 import * as bash from 'tree-sitter-bash'
+import * as URI from 'urijs'
 import * as LSP from 'vscode-languageserver'
 
 import { uniqueBasedOnHash } from './util/array'
@@ -51,14 +53,19 @@ export default class Analyzer {
             const absolute = Path.join(rootPath, p)
             const uri = 'file://' + absolute
             connection.console.log('Analyzing ' + uri)
-            analyzer.analyze(uri, fs.readFileSync(absolute, 'utf8'))
+            analyzer.analyze(
+              uri,
+              LSP.TextDocument.create(uri, 'shell', 1, fs.readFileSync(absolute, 'utf8')),
+            )
           })
           resolve(analyzer)
         }
       })
     })
   }
 
+  private uriToTextDocument: { [uri: string]: LSP.TextDocument } = {}
+
   private uriToTreeSitterDocument: Documents = {}
 
   // We need this to find the word at a given point etc.
@@ -84,6 +91,69 @@ export default class Analyzer {
     return symbols.map(s => s.location)
   }
 
+  public async getExplainshellDocumentation({
+    pos,
+    endpoint,
+  }: {
+    pos: LSP.TextDocumentPositionParams
+    endpoint: string
+  }): Promise<any> {
+    const leafNode = this.uriToTreeSitterDocument[
+      pos.textDocument.uri
+    ].rootNode.descendantForPosition({
+      row: pos.position.line,
+      column: pos.position.character,
+    })
+
+    // explainshell needs the whole command, not just the "word" (tree-sitter
+    // parlance) that the user hovered over. A relatively successful heuristic
+    // is to simply go up one level in the AST. If you go up too far, you'll
+    // start to include newlines, and explainshell completely balks when it
+    // encounters newlines.
+    const interestingNode = leafNode.type === 'word' ? leafNode.parent : leafNode
+
+    const cmd = this.uriToFileContent[pos.textDocument.uri].slice(
+      interestingNode.startIndex,
+      interestingNode.endIndex,
+    )
+
+    const explainshellResponse = await request({
+      uri: URI(endpoint)
+        .path('/api/explain')
+        .addQuery('cmd', cmd)
+        .toString(),
+      json: true,
+    })
+
+    // Attaches debugging information to the return value (useful for logging to
+    // VS Code output).
+    const response = { ...explainshellResponse, cmd, cmdType: interestingNode.type }
+
+    if (explainshellResponse.status === 'error') {
+      return response
+    } else if (!explainshellResponse.matches) {
+      return { ...response, status: 'error' }
+    } else {
+      const offsetOfMousePointerInCommand =
+        this.uriToTextDocument[pos.textDocument.uri].offsetAt(pos.position) -
+        interestingNode.startIndex
+
+      const match = explainshellResponse.matches.find(
+        helpItem =>
+          helpItem.start <= offsetOfMousePointerInCommand &&
+          offsetOfMousePointerInCommand < helpItem.end,
+      )
+
+      const helpHTML = match && match.helpHTML
+
+      if (!helpHTML) {
+        return { ...response, status: 'error' }
+      }
+
+      return { ...response, helpHTML }
+    }
+  }
+
   /**
    * Find all the locations where something named name has been defined.
    */
@@ -157,12 +227,15 @@ export default class Analyzer {
    * Returns all, if any, syntax errors that occurred while parsing the file.
    *
    */
-  public analyze(uri: string, contents: string): LSP.Diagnostic[] {
+  public analyze(uri: string, document: LSP.TextDocument): LSP.Diagnostic[] {
+    const contents = document.getText()
+
     const d = new Document()
     d.setLanguage(bash)
     d.setInputString(contents)
     d.parse()
 
+    this.uriToTextDocument[uri] = document
     this.uriToTreeSitterDocument[uri] = d
     this.uriToDeclarations[uri] = {}
     this.uriToFileContent[uri] = contents

server/src/server.ts

@@ -1,5 +1,6 @@
 import * as LSP from 'vscode-languageserver'
 
+import * as TurndownService from 'turndown'
 import Analyzer from './analyser'
 import * as Builtins from './builtins'
 import Executables from './executables'
@@ -53,8 +54,7 @@ export default class BashServer {
     this.documents.listen(this.connection)
     this.documents.onDidChangeContent(change => {
       const uri = change.document.uri
-      const contents = change.document.getText()
-      const diagnostics = this.analyzer.analyze(uri, contents)
+      const diagnostics = this.analyzer.analyze(uri, change.document)
       connection.sendDiagnostics({
         uri: change.document.uri,
         diagnostics,
@@ -100,7 +100,7 @@ export default class BashServer {
     )
   }
 
-  private onHover(pos: LSP.TextDocumentPositionParams): Promise<LSP.Hover> {
+  private async onHover(pos: LSP.TextDocumentPositionParams): Promise<LSP.Hover> {
     this.connection.console.log(
       `Hovering over ${pos.position.line}:${pos.position.character}`,
     )
@@ -121,6 +121,26 @@ export default class BashServer {
           value: doc,
         },
       }))
+    } else if (process.env.EXPLAINSHELL_ENDPOINT !== '') {
+      const response = await this.analyzer.getExplainshellDocumentation({
+        pos,
+        endpoint: process.env.EXPLAINSHELL_ENDPOINT,
+      })
+
+      if (response.status === 'error') {
+        this.connection.console.log(
+          'getExplainshellDocumentation returned: ' + JSON.stringify(response, null, 4),
+        )
+
+        return null
+      }
+
+      return {
+        contents: {
+          kind: 'markdown',
+          value: new TurndownService().turndown(response.helpHTML),
+        },
+      }
     } else {
       return null
     }

vscode-client/README.md

@@ -1,7 +1,7 @@
 # Bash IDE
 
 Bash language server. Uses [Tree Sitter][tree-sitter] and its
-[grammar for Bash][tree-sitter-bash].
+[grammar for Bash][tree-sitter-bash] with [explainshell][explainshell] integration.
 
 ## System Requirements
 
@@ -20,7 +20,13 @@ npm i -g bash-language-server
 - [x] Highlight occurrences
 - [x] Code completion
 - [x] Simple diagnostics reporting
+- [x] Documentation for flags on hover
 - [ ] Rename symbol
 
+## Configuration
+
+<lsp-adapter>
+
 [tree-sitter]: https://github.com/tree-sitter/tree-sitter
 [tree-sitter-bash]: https://github.com/tree-sitter/tree-sitter-bash
+[explainshell]: https://explainshell.com/

vscode-client/package.json

@@ -26,7 +26,19 @@
     "onLanguage:shellscript"
   ],
   "main": "./out/src/extension",
-  "contributes": {},
+  "contributes": {
+      "configuration": {
+          "type": "object",
+          "title": "Bash IDE configuration",
+          "properties": {
+              "bash.explainshellEndpoint": {
+                  "type": "string",
+                  "default": "",
+                  "description": "Set this to https://explainshell.com (once https://github.com/idank/explainshell/pull/125 is merged in) in order to get hover documentation on flags and options."
+              }
+          }
+      }
+  },
   "scripts": {
     "vscode:prepublish": "yarn run compile",
     "compile": "rm -rf out && tsc -p ./",

vscode-client/src/extension.ts

@@ -18,21 +18,36 @@ export async function activate(context: ExtensionContext) {
     if (semverCompare(version, MINIMUM_SERVER_VERSION) === -1) {
       return handleOutdatedExecutable()
     }
-    start(context, command)
+    start(
+      context,
+      command,
+      workspace.getConfiguration('bash').get('explainshellEndpoint', ''),
+    )
   } catch (error) {
     handleMissingExecutable()
   }
 }
 
-function start(context: ExtensionContext, command: string) {
+function start(context: ExtensionContext, command: string, explainshellEndpoint: string) {
+  const env: any = {
+    ...process.env,
+    EXPLAINSHELL_ENDPOINT: explainshellEndpoint,
+  }
+
   const serverOptions: ServerOptions = {
     run: {
       command,
       args: ['start'],
+      options: {
+        env,
+      },
     },
     debug: {
       command,
       args: ['start'],
+      options: {
+        env,
+      },
     },
   }