Add support for finding references using LSP servers or tsserver

README.md

@@ -27,6 +27,7 @@ formatting tools, and some Language Server Protocol and `tsserver` features.
     2. [Fixing](#usage-fixing)
     3. [Completion](#usage-completion)
     4. [Go To Definition](#usage-go-to-definition)
+    5. [Find References](#usage-find-references)
 3. [Installation](#installation)
     1. [Installation with Vim package management](#standard-installation)
     2. [Installation with Pathogen](#installation-with-pathogen)
@@ -240,6 +241,15 @@ ALE supports jumping to the definition of words under your cursor with the
 
 See `:help ale-go-to-definition` for more information.
 
+<a name="usage-find-references"></a>
+
+### 2.v Find References
+
+ALE supports finding references for words under your cursor with the
+`:ALEFindReferences` command using any enabled LSP linters and `tsserver`.
+
+See `:help ale-find-references` for more information.
+
 <a name="installation"></a>
 
 ## 3. Installation

autoload/ale/lsp/message.vim

@@ -116,3 +116,13 @@ function! ale#lsp#message#Definition(buffer, line, column) abort
     \   'position': {'line': a:line - 1, 'character': a:column},
     \}]
 endfunction
+
+function! ale#lsp#message#References(buffer, line, column) abort
+    return [0, 'textDocument/references', {
+    \   'textDocument': {
+    \       'uri': ale#path#ToURI(expand('#' . a:buffer . ':p')),
+    \   },
+    \   'position': {'line': a:line - 1, 'character': a:column},
+    \   'context': {'includeDeclaration': v:false},
+    \}]
+endfunction

autoload/ale/lsp/tsserver_message.vim

@@ -61,3 +61,11 @@ function! ale#lsp#tsserver_message#Definition(buffer, line, column) abort
     \   'file': expand('#' . a:buffer . ':p'),
     \}]
 endfunction
+
+function! ale#lsp#tsserver_message#References(buffer, line, column) abort
+    return [0, 'ts@references', {
+    \   'line': a:line,
+    \   'offset': a:column,
+    \   'file': expand('#' . a:buffer . ':p'),
+    \}]
+endfunction

autoload/ale/references.vim

@@ -0,0 +1,111 @@
+let s:references_map = {}
+
+" Used to get the references map in tests.
+function! ale#references#GetMap() abort
+    return deepcopy(s:references_map)
+endfunction
+
+" Used to set the references map in tests.
+function! ale#references#SetMap(map) abort
+    let s:references_map = a:map
+endfunction
+
+function! ale#references#ClearLSPData() abort
+    let s:references_map = {}
+endfunction
+
+function! ale#references#HandleTSServerResponse(conn_id, response) abort
+    if get(a:response, 'command', '') is# 'references'
+    \&& has_key(s:references_map, a:response.request_seq)
+        call remove(s:references_map, a:response.request_seq)
+
+        if get(a:response, 'success', v:false) is v:true
+            let l:item_list = []
+
+            for l:response_item in a:response.body.refs
+                call add(l:item_list, {
+                \ 'filename': l:response_item.file,
+                \ 'line': l:response_item.start.line,
+                \ 'column': l:response_item.start.offset,
+                \})
+            endfor
+
+            if empty(l:item_list)
+                call ale#util#Execute('echom ''No references found.''')
+            else
+                call ale#preview#ShowSelection(l:item_list)
+            endif
+        endif
+    endif
+endfunction
+
+function! ale#references#HandleLSPResponse(conn_id, response) abort
+    if has_key(a:response, 'id')
+    \&& has_key(s:references_map, a:response.id)
+        call remove(s:references_map, a:response.id)
+
+        " The result can be a Dictionary item, a List of the same, or null.
+        let l:result = get(a:response, 'result', [])
+        let l:item_list = []
+
+        for l:response_item in l:result
+            call add(l:item_list, {
+            \ 'filename': ale#path#FromURI(l:response_item.uri),
+            \ 'line': l:response_item.range.start.line + 1,
+            \ 'column': l:response_item.range.start.character + 1,
+            \})
+        endfor
+
+        if empty(l:item_list)
+            call ale#util#Execute('echom ''No references found.''')
+        else
+            call ale#preview#ShowSelection(l:item_list)
+        endif
+    endif
+endfunction
+
+function! s:FindReferences(linter) abort
+    let l:buffer = bufnr('')
+    let [l:line, l:column] = getcurpos()[1:2]
+
+    let l:Callback = a:linter.lsp is# 'tsserver'
+    \   ? function('ale#references#HandleTSServerResponse')
+    \   : function('ale#references#HandleLSPResponse')
+
+    let l:lsp_details = ale#linter#StartLSP(l:buffer, a:linter, l:Callback)
+
+    if empty(l:lsp_details)
+        return 0
+    endif
+
+    let l:id = l:lsp_details.connection_id
+    let l:root = l:lsp_details.project_root
+
+    if a:linter.lsp is# 'tsserver'
+        let l:message = ale#lsp#tsserver_message#References(
+        \   l:buffer,
+        \   l:line,
+        \   l:column
+        \)
+    else
+        " Send a message saying the buffer has changed first, or the
+        " references position probably won't make sense.
+        call ale#lsp#Send(l:id, ale#lsp#message#DidChange(l:buffer), l:root)
+
+        let l:column = min([l:column, len(getline(l:line))])
+
+        let l:message = ale#lsp#message#References(l:buffer, l:line, l:column)
+    endif
+
+    let l:request_id = ale#lsp#Send(l:id, l:message, l:root)
+
+    let s:references_map[l:request_id] = {}
+endfunction
+
+function! ale#references#Find() abort
+    for l:linter in ale#linter#Get(&filetype)
+        if !empty(l:linter.lsp)
+            call s:FindReferences(l:linter)
+        endif
+    endfor
+endfunction

doc/ale.txt

@@ -13,6 +13,7 @@ CONTENTS                                                         *ale-contents*
   5. Language Server Protocol Support.....|ale-lsp|
     5.1 Completion........................|ale-completion|
     5.2 Go To Definition..................|ale-go-to-definition|
+    5.3 Find References...................|ale-find-references|
   6. Global Options.......................|ale-options|
     6.1 Highlights........................|ale-highlights|
     6.2 Options for write-good Linter.....|ale-write-good-options|
@@ -642,6 +643,17 @@ information returned by LSP servers. The following commands are supported:
 |ALEGoToDefinitionInTab| - The same, but for opening the file in a new tab.
 
 
+-------------------------------------------------------------------------------
+5.3 Find References                                       *ale-find-references*
+
+ALE supports finding references for symbols though any enabled LSP linters.
+ALE will display a preview window showing the places where a symbol is
+referenced in a codebase when a command is run. The following commands are
+supporte3:
+
+|ALEFindReferences| - Find references for the word under the cursor.
+
+
 ===============================================================================
 6. Global Options                                                 *ale-options*
 
@@ -1746,6 +1758,18 @@ ALE will use to search for Python executables.
 ===============================================================================
 8. Commands/Keybinds                                             *ale-commands*
 
+ALEFindReferences                                           *ALEFindReferences*
+
+  Find references in the codebase for the symbol under the cursor using the
+  enabled LSP linters for the buffer. ALE will display a preview window
+  containing the results if some references are found.
+
+  The window can be navigated using the usual Vim navigation commands. The
+  Enter key (`<CR>`) can be used to jump to a referencing location, or the `t`
+  key can be used to jump to the location in a new tab.
+
+  A plug mapping `<Plug>(ale_find_references)` is defined for this command.
+
 ALEFix                                                                 *ALEFix*
 
   Fix problems with the current buffer. See |ale-fix| for more information.

plugin/ale.vim

@@ -271,6 +271,9 @@ command! -bar ALEFixSuggest :call ale#fix#registry#Suggest(&filetype)
 command! -bar ALEGoToDefinition :call ale#definition#GoTo({})
 command! -bar ALEGoToDefinitionInTab :call ale#definition#GoTo({'open_in_tab': 1})
 
+" Find references for tsserver and LSP
+command! -bar ALEFindReferences :call ale#references#Find()
+
 " <Plug> mappings for commands
 nnoremap <silent> <Plug>(ale_previous) :ALEPrevious<Return>
 nnoremap <silent> <Plug>(ale_previous_wrap) :ALEPreviousWrap<Return>
@@ -291,6 +294,7 @@ nnoremap <silent> <Plug>(ale_detail) :ALEDetail<Return>
 nnoremap <silent> <Plug>(ale_fix) :ALEFix<Return>
 nnoremap <silent> <Plug>(ale_go_to_definition) :ALEGoToDefinition<Return>
 nnoremap <silent> <Plug>(ale_go_to_definition_in_tab) :ALEGoToDefinitionInTab<Return>
+nnoremap <silent> <Plug>(ale_find_references) :ALEFindReferences<Return>
 
 " Set up autocmd groups now.
 call ale#toggle#InitAuGroups()

test/lsp/test_lsp_client_messages.vader

@@ -144,6 +144,21 @@ Execute(ale#lsp#message#Definition() should return correct messages):
   \ ],
   \ ale#lsp#message#Definition(bufnr(''), 12, 34)
 
+Execute(ale#lsp#message#References() should return correct messages):
+  AssertEqual
+  \ [
+  \   0,
+  \   'textDocument/references',
+  \   {
+  \     'textDocument': {
+  \         'uri': ale#path#ToURI(g:dir . '/foo/bar.ts'),
+  \     },
+  \     'position': {'line': 11, 'character': 34},
+  \     'context': {'includeDeclaration': v:false},
+  \   }
+  \ ],
+  \ ale#lsp#message#References(bufnr(''), 12, 34)
+
 Execute(ale#lsp#tsserver_message#Open() should return correct messages):
   AssertEqual
   \ [
@@ -233,3 +248,16 @@ Execute(ale#lsp#tsserver_message#Definition() should return correct messages):
   \   }
   \ ],
   \ ale#lsp#tsserver_message#Definition(bufnr(''), 347, 12)
+
+Execute(ale#lsp#tsserver_message#References() should return correct messages):
+  AssertEqual
+  \ [
+  \   0,
+  \   'ts@references',
+  \   {
+  \     'file': ale#path#Simplify(g:dir . '/foo/bar.ts'),
+  \     'line': 347,
+  \     'offset': 12,
+  \   }
+  \ ],
+  \ ale#lsp#tsserver_message#References(bufnr(''), 347, 12)

test/test_find_references.vader

@@ -0,0 +1,243 @@
+Before:
+  call ale#test#SetDirectory('/testplugin/test')
+  call ale#test#SetFilename('dummy.txt')
+
+  let g:old_filename = expand('%:p')
+  let g:Callback = 0
+  let g:expr_list = []
+  let g:message_list = []
+  let g:preview_called = 0
+  let g:item_list = []
+
+  runtime autoload/ale/linter.vim
+  runtime autoload/ale/lsp.vim
+  runtime autoload/ale/util.vim
+  runtime autoload/ale/preview.vim
+
+  function! ale#linter#StartLSP(buffer, linter, callback) abort
+    let g:Callback = a:callback
+
+    return {
+    \ 'connection_id': 347,
+    \ 'project_root': '/foo/bar',
+    \}
+  endfunction
+
+  function! ale#lsp#Send(conn_id, message, root) abort
+    call add(g:message_list, a:message)
+
+    return 42
+  endfunction
+
+  function! ale#util#Execute(expr) abort
+    call add(g:expr_list, a:expr)
+  endfunction
+
+  function! ale#preview#ShowSelection(item_list) abort
+    let g:preview_called = 1
+    let g:item_list = a:item_list
+  endfunction
+
+After:
+  call ale#references#SetMap({})
+  call ale#test#RestoreDirectory()
+  call ale#linter#Reset()
+
+  unlet! g:old_filename
+  unlet! g:Callback
+  unlet! g:message_list
+  unlet! g:expr_list
+  unlet! b:ale_linters
+  unlet! g:item_list
+  unlet! g:preview_called
+
+  runtime autoload/ale/linter.vim
+  runtime autoload/ale/lsp.vim
+  runtime autoload/ale/util.vim
+  runtime autoload/ale/preview.vim
+
+Execute(Other messages for the tsserver handler should be ignored):
+  call ale#references#HandleTSServerResponse(1, {'command': 'foo'})
+
+Execute(Failed reference responses should be handled correctly):
+  call ale#references#SetMap({3: {}})
+  call ale#references#HandleTSServerResponse(
+  \ 1,
+  \ {'command': 'references', 'request_seq': 3}
+  \)
+  AssertEqual {}, ale#references#GetMap()
+
+Given typescript(Some typescript file):
+  foo
+  somelongerline
+  bazxyzxyzxyz
+
+Execute(Results should be shown for tsserver responses):
+  call ale#references#SetMap({3: {}})
+  call ale#references#HandleTSServerResponse(1, {
+  \ 'command': 'references',
+  \ 'request_seq': 3,
+  \ 'success': v:true,
+  \ 'body': {
+  \   'symbolStartOffset': 9,
+  \   'refs': [
+  \     {
+  \       'file': '/foo/bar/app.ts',
+  \       'isWriteAccess': v:true,
+  \       'lineText': 'import {doSomething} from ''./whatever''',
+  \       'end': {'offset': 24, 'line': 9},
+  \       'start': {'offset': 9, 'line': 9},
+  \       'isDefinition': v:true,
+  \     },
+  \     {
+  \       'file': '/foo/bar/app.ts',
+  \       'isWriteAccess': v:false,
+  \       'lineText': '  doSomething()',
+  \       'end': {'offset': 18, 'line': 804},
+  \       'start': {'offset': 3, 'line': 804},
+  \       'isDefinition': v:false,
+  \     },
+  \     {
+  \       'file': '/foo/bar/other/app.ts',
+  \       'isWriteAccess': v:false,
+  \       'lineText': '  doSomething()',
+  \       'end': {'offset': 18, 'line': 51},
+  \       'start': {'offset': 3, 'line': 51},
+  \       'isDefinition': v:false,
+  \     },
+  \   ],
+  \   'symbolDisplayString': 'import doSomething',
+  \   'symbolName': 'doSomething()',
+  \ },
+  \})
+
+  AssertEqual
+  \ [
+  \   {'filename': '/foo/bar/app.ts', 'column': 9, 'line': 9},
+  \   {'filename': '/foo/bar/app.ts', 'column': 3, 'line': 804},
+  \   {'filename': '/foo/bar/other/app.ts', 'column': 3, 'line': 51},
+  \ ],
+  \ g:item_list
+  AssertEqual {}, ale#references#GetMap()
+
+Execute(The preview window should not be opened for empty tsserver responses):
+  call ale#references#SetMap({3: {}})
+  call ale#references#HandleTSServerResponse(1, {
+  \ 'command': 'references',
+  \ 'request_seq': 3,
+  \ 'success': v:true,
+  \ 'body': {
+  \   'symbolStartOffset': 9,
+  \   'refs': [
+  \   ],
+  \   'symbolDisplayString': 'import doSomething',
+  \   'symbolName': 'doSomething()',
+  \ },
+  \})
+
+  Assert !g:preview_called
+  AssertEqual {}, ale#references#GetMap()
+  AssertEqual ['echom ''No references found.'''], g:expr_list
+
+Execute(tsserver reference requests should be sent):
+  runtime ale_linters/typescript/tsserver.vim
+  call setpos('.', [bufnr(''), 2, 5, 0])
+
+  ALEFindReferences
+
+  AssertEqual
+  \ 'function(''ale#references#HandleTSServerResponse'')',
+  \ string(g:Callback)
+  AssertEqual
+  \ [[0, 'ts@references', {'file': expand('%:p'), 'line': 2, 'offset': 5}]],
+  \ g:message_list
+  AssertEqual {'42': {}}, ale#references#GetMap()
+
+Given python(Some Python file):
+  foo
+  somelongerline
+  bazxyzxyzxyz
+
+Execute(LSP reference responses should be handled):
+  call ale#references#SetMap({3: {}})
+  call ale#references#HandleLSPResponse(
+  \ 1,
+  \ {
+  \   'id': 3,
+  \   'result': [
+  \     {
+  \       'uri': ale#path#ToURI(ale#path#Simplify(g:dir . '/completion_dummy_file')),
+  \       'range': {
+  \         'start': {'line': 2, 'character': 7},
+  \       },
+  \     },
+  \     {
+  \       'uri': ale#path#ToURI(ale#path#Simplify(g:dir . '/other_file')),
+  \       'range': {
+  \         'start': {'line': 7, 'character': 15},
+  \       },
+  \     },
+  \   ],
+  \ }
+  \)
+
+  AssertEqual
+  \ [
+  \   {
+  \     'filename': ale#path#Simplify(g:dir . '/completion_dummy_file'),
+  \     'line': 3,
+  \     'column': 8,
+  \   },
+  \   {
+  \     'filename': ale#path#Simplify(g:dir . '/other_file'),
+  \     'line': 8,
+  \     'column': 16,
+  \   },
+  \ ],
+  \ g:item_list
+  AssertEqual {}, ale#references#GetMap()
+
+Execute(Preview windows should not be opened for empty LSP reference responses):
+  call ale#references#SetMap({3: {}})
+  call ale#references#HandleLSPResponse(
+  \ 1,
+  \ {
+  \   'id': 3,
+  \   'result': [
+  \   ],
+  \ }
+  \)
+
+  Assert !g:preview_called
+  AssertEqual {}, ale#references#GetMap()
+  AssertEqual ['echom ''No references found.'''], g:expr_list
+
+Execute(LSP reference requests should be sent):
+  runtime ale_linters/python/pyls.vim
+  let b:ale_linters = ['pyls']
+  call setpos('.', [bufnr(''), 1, 5, 0])
+
+  ALEFindReferences
+
+  AssertEqual
+  \ 'function(''ale#references#HandleLSPResponse'')',
+  \ string(g:Callback)
+
+  AssertEqual
+  \ [
+  \   [1, 'textDocument/didChange', {
+  \     'textDocument': {
+  \         'uri': ale#path#ToURI(expand('%:p')),
+  \         'version': g:ale_lsp_next_version_id - 1,
+  \     },
+  \     'contentChanges': [{'text': join(getline(1, '$'), "\n") . "\n"}]
+  \   }],
+  \   [0, 'textDocument/references', {
+  \   'textDocument': {'uri': ale#path#ToURI(expand('%:p'))},
+  \   'position': {'line': 0, 'character': 3},
+  \   'context': {'includeDeclaration': v:false},
+  \   }],
+  \ ],
+  \ g:message_list
+
+  AssertEqual {'42': {}}, ale#references#GetMap()