Centralize shell documentation

Author: skovhus

server/src/__tests__/builtins.test.ts

@@ -27,13 +27,6 @@ describe('list', () => {
   })
 })
 
-describe('documentation', () => {
-  it('uses `man` so it disregards the PATH it has been initialized with', async () => {
-    const result = await executables.documentation('ls')
-    expect(result).toBeTruthy()
-  })
-})
-
 describe('isExecutableOnPATH', () => {
   it('looks at the PATH it has been initialized with', async () => {
     const result = executables.isExecutableOnPATH('ls')

server/src/__tests__/executables.test.ts

@@ -71,7 +71,7 @@ describe('server', () => {
     expect(result).toEqual({
       contents: {
         kind: 'markdown',
-        value: expect.stringContaining('RM(1)'),
+        value: expect.stringContaining('remove directory'),
       },
     })
   })

server/src/__tests__/server.test.ts

@@ -1,5 +1,3 @@
-import * as ShUtil from './util/sh'
-
 // You can generate this list by running `compgen -b` in a bash session
 export const LIST = [
   '.',
@@ -68,13 +66,3 @@ const SET = new Set(LIST)
 export function isBuiltin(word: string): boolean {
   return SET.has(word)
 }
-
-export async function documentation(builtin: string): Promise<string> {
-  const errorMessage = `No help page for ${builtin}`
-  try {
-    const doc = await ShUtil.execShellScript(`help ${builtin}`)
-    return doc || errorMessage
-  } catch (error) {
-    return errorMessage
-  }
-}

server/src/builtins.ts

@@ -4,7 +4,6 @@ import { promisify } from 'util'
 
 import * as ArrayUtil from './util/array'
 import * as FsUtil from './util/fs'
-import * as ShUtil from './util/sh'
 
 const lstatAsync = promisify(fs.lstat)
 const readdirAsync = promisify(fs.readdir)
@@ -44,19 +43,6 @@ export default class Executables {
   public isExecutableOnPATH(executable: string): boolean {
     return this.executables.has(executable)
   }
-
-  /**
-   * Look up documentation for the given executable.
-   *
-   * For now it simply tries to look up the MAN documentation.
-   */
-  public documentation(executable: string): Promise<string> {
-    return ShUtil.execShellScript(`man ${executable} | col -b`).then(doc => {
-      return !doc
-        ? Promise.resolve(`No MAN page for ${executable}`)
-        : Promise.resolve(doc)
-    })
-  }
 }
 
 /**

server/src/executables.ts

@@ -1,5 +1,3 @@
-import * as ShUtil from './util/sh'
-
 // https://www.gnu.org/software/bash/manual/html_node/Reserved-Word-Index.html
 
 export const LIST = [
@@ -31,12 +29,3 @@ const SET = new Set(LIST)
 export function isReservedWord(word: string): boolean {
   return SET.has(word)
 }
-
-export async function documentation(reservedWord: string): Promise<string> {
-  try {
-    const doc = await ShUtil.execShellScript(`help ${reservedWord}`)
-    return doc || ''
-  } catch (error) {
-    return ''
-  }
-}

server/src/reservedWords.ts

@@ -11,6 +11,7 @@ import { initializeParser } from './parser'
 import * as ReservedWords from './reservedWords'
 import { BashCompletionItem, CompletionItemDataType } from './types'
 import { uniqueBasedOnHash } from './util/array'
+import { getShellDocumentation } from './util/sh'
 
 /**
  * The BashServer glues together the separate components to implement
@@ -138,6 +139,7 @@ export default class BashServer {
     params: LSP.TextDocumentPositionParams,
   ): Promise<LSP.Hover | null> {
     const word = this.getWordAtPoint(params)
+    const currentUri = params.textDocument.uri
 
     this.logRequest({ request: 'onHover', params, word })
 
@@ -167,29 +169,16 @@ export default class BashServer {
       }
     }
 
-    const getMarkdownHoverItem = (doc: string) => ({
-      // LSP.MarkupContent
-      value: ['``` man', doc, '```'].join('\n'),
-      // Passed as markdown for syntax highlighting
-      kind: 'markdown' as const,
-    })
-
-    if (Builtins.isBuiltin(word)) {
-      return Builtins.documentation(word).then(doc => ({
-        contents: getMarkdownHoverItem(doc),
-      }))
-    }
-
-    if (ReservedWords.isReservedWord(word)) {
-      return ReservedWords.documentation(word).then(doc => ({
-        contents: getMarkdownHoverItem(doc),
-      }))
-    }
-
-    if (this.executables.isExecutableOnPATH(word)) {
-      return this.executables.documentation(word).then(doc => ({
-        contents: getMarkdownHoverItem(doc),
-      }))
+    if (
+      ReservedWords.isReservedWord(word) ||
+      Builtins.isBuiltin(word) ||
+      this.executables.isExecutableOnPATH(word)
+    ) {
+      const shellDocumentation = await getShellDocumentation({ word })
+      if (shellDocumentation) {
+        // eslint-disable-next-line no-console
+        return { contents: getMarkdownContent(shellDocumentation) }
+      }
     }
 
     // FIXME: could also be a symbol