Jobs and Timers in neovim: How to watch your builds fail

If you’re like me (and for your own sake, I truly hope you are not), you probably tend to have a lot of builds fail. Even worse, if you really are like me, you spend most of your time in vim.

If that is not the case, you’re in the clear, there’s nothing wrong with you, feel free to go, end this blog post now, be free, happy, enjoy the sunlight and the birds and the trees. Life is good.

.

.

.

.

.

.

.

.

.

.

.

.

… Are we, the sadists, all alone now? Cool. Ok, so you use vim a lot and you make builds fail. Chances are you would like to know when that happens without ever leaving vim. It’s alright. I got you, mate.

Here’s an asciicast of my nvim. Notice how the status bar includes, on the bottom right, the status of the CI. Notice how it updates. Damn, that’s neat. You want that.

First things first, either make an API wrapper, preferably in Rust or Go, something compiled and fancy, that allows you to check the GitHub checks API. Got it? Good. Now stop being a muppet and use hub instead.

Now that you have `hub`, you can make use of the `hub ci-status` command.

$ hub ci-status
success

Coolio.

Now let’s change our custom status bar.

First, we want to check if we’re in a git project:

let s:in_git = system(“git rev-parse — git-dir 2> /dev/null”)
if s:in_git == 0
 “ call hub
endif

So now we need to call `hub`. However just doing a `system` call to `hub` would be a blocking operation and we don’t want our vim to block every few moments for like 5 seconds. So let’s use `jobstart`.

Start by calling `:h jobstart` from your (n)vim. You can see that it runs an asynchronous job and it supports shell commands.

So let’s create a `CiStatus` function that looks like this:

function! CiStatus()
 let l:callbacks = {
 \ ‘on_stdout’: function(‘OnCiStatus’),
 \ }
call jobstart(‘hub ci-status’, l:callbacks)
endfunction

We define a map of callbacks for `stdout` and delegate that to a new function called `OnCiStatus`. This is a very simple function that gets the output from `hub` and converts it to whatever we want, storing it in a `g:ci_status` variable. We will later use this variable in our statusline.

function! OnCiStatus(job_id, data, event) dict
 if a:event == “stdout” && a:data[0] != ‘’
 let g:ci_status = ParseCiStatus(a:data[0])
 endif
endfunction
function! ParseCiStatus(out)
 let l:states = {
 \ ‘success’: “ci passed”,
 \ ‘failure’: “ci failed”,
 \ ‘neutral’: “ci yet to run”,
 \ ‘error’: “ci errored”,
 \ ‘cancelled’: “ci cancelled”,
 \ ‘action_required’: “ci requires action”,
 \ ‘pending’: “ci running”,
 \ ‘timed_out’: “ci timed out”,
 \ ‘no status’: “no ci”,
 \ }
return l:states[a:out] . “, “
endfunction

There are a couple of things missing though. This runs the `hub ci-status` job only once. We want to have it perform constant checks. If we do `:h timers`, we can see the new `time` API in neovim. Theres a `timer_start` that takes a period and a callback to run after that period.

We can then change our `OnCiStatus` function to call `timer_start` with that first `CiStatus` function again:

function! OnCiStatus(job_id, data, event) dict
 if a:event == “stdout” && a:data[0] != ‘’
 let g:ci_status = ParseCiStatus(a:data[0])
 call timer_start(30000, ‘CiStatus’) “ relevant new part
 endif
endfunction

Now `CiStatus` gets called by `timer_start` every 3 seconds. `timer_start`, however, passes the `timer_id` as an argument to the callback. So we will need to modify `CiStatus` to accept an argument (that we can safely ignore):

function! CiStatus(timer_id)
 let l:callbacks = {
 \ ‘on_stdout’: function(‘OnCiStatus’),
 \ }
call jobstart(‘hub ci-status’, l:callbacks)
endfunction
“ We also need to change the first CiStatus call to receive an int
“ Since we don’t care about it, let’s just use 0
let s:in_git = system(“git rev-parse — git-dir 2> /dev/null”)
if s:in_git == 0
 call CiStatus(0)
endif

All that’s missing now is to take the value of `g:ci_status` and put into the statusline. That’s pretty simple, using some code borrowed from Kade Killary.

set statusline=
set statusline+=\ \ \ “ Empty space
set statusline+=%< “ Where to truncate line
set statusline+=%f “ Path to the file in the buffer, as typed or relative to current directory
set statusline+=%{&modified?’\ +’:’’}
set statusline+=%{&readonly?’\ ’:’’}
set statusline+=%= “ Separation point between left and right aligned items
set statusline+=\ %{g:ci_status} “ Our custom CI status check
set statusline+=col:\ %c
set statusline+=\ \ \ “ Empty space

And that’s that. Find a lot more goodies in my dotfiles. Cheerios. Hugs n kisses and all that.