3 files changed, 53 insertions, 15 deletions
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index b0d0bfc74b..1a7aec6cc6 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -1,3 +1,39 @@
+-- Nvim-Lua stdlib: the `vim` module (:help lua-stdlib)
+--
+-- Lua code lives in one of three places:
+--    1. The runtime (`runtime/lua/vim/`). For "nice to have" features, e.g.
+--       the `inspect` and `lpeg` modules.
+--    2. The `vim.shared` module: code shared between Nvim and its test-suite.
+--    3. Compiled-into Nvim itself (`src/nvim/lua/`).
+--
+-- Guideline: "If in doubt, put it in the runtime".
+--
+-- Most functions should live directly on `vim.`, not sub-modules. The only
+-- "forbidden" names are those claimed by legacy `if_lua`:
+--    $ vim
+--    :lua for k,v in pairs(vim) do print(k) end
+--    buffer
+--    open
+--    window
+--    lastline
+--    firstline
+--    type
+--    line
+--    eval
+--    dict
+--    beep
+--    list
+--    command
+--
+-- Reference (#6580):
+--    - https://github.com/luafun/luafun
+--    - https://github.com/rxi/lume
+--    - http://leafo.net/lapis/reference/utilities.html
+--    - https://github.com/torch/paths
+--    - https://github.com/bakpakin/Fennel (pretty print, repl)
+--    - https://github.com/howl-editor/howl/tree/master/lib/howl/util
+
+
 -- Internal-only until comments in #8107 are addressed.
 -- Returns:
 --    {errcode}, {output}
@@ -187,10 +223,14 @@ deepcopy = function(orig)
   return deepcopy_funcs[type(orig)](orig)
 end
 
-local function __index(table, key)
-  if key == "inspect" then
-    table.inspect = require("vim.inspect")
-    return table.inspect
+local function __index(t, key)
+  if key == 'inspect' then
+    t.inspect = require('vim.inspect')
+    return t.inspect
+  elseif require('vim.shared')[key] ~= nil then
+    -- Expose all `vim.shared` functions on the `vim` module.
+    t[key] = require('vim.shared')[key]
+    return t[key]
   end
 end
 
diff --git a/src/nvim/testdir/load.vim b/src/nvim/testdir/load.vim
index 2e01338dd0..6369b8f45e 100644
--- a/src/nvim/testdir/load.vim
+++ b/src/nvim/testdir/load.vim
@@ -1,3 +1,5 @@
+" Also used by: test/functional/helpers.lua
+
 function! s:load_factor() abort
   let timeout = 200
   let times = []
@@ -23,8 +25,8 @@ function! s:load_factor() abort
 endfunction
 
 " Compute load factor only once.
-let s:load_factor = s:load_factor()
+let g:test_load_factor = s:load_factor()
 
 function! LoadAdjust(num) abort
-  return float2nr(ceil(a:num * s:load_factor))
+  return float2nr(ceil(a:num * g:test_load_factor))
 endfunction
diff --git a/src/nvim/testdir/test_timers.vim b/src/nvim/testdir/test_timers.vim
index 5b5f001e6b..9384989a35 100644
--- a/src/nvim/testdir/test_timers.vim
+++ b/src/nvim/testdir/test_timers.vim
@@ -15,17 +15,13 @@ func MyHandlerWithLists(lists, timer)
   let x = string(a:lists)
 endfunc
 
-func s:assert_inrange(lower, upper, actual)
-  return assert_inrange(a:lower, LoadAdjust(a:upper), a:actual)
-endfunc
-
 func Test_oneshot()
   let g:val = 0
   let timer = timer_start(50, 'MyHandler')
   let slept = WaitFor('g:val == 1')
   call assert_equal(1, g:val)
   if has('reltime')
-    call s:assert_inrange(40, 120, slept)
+    call assert_inrange(40, LoadAdjust(120), slept)
   else
     call assert_inrange(20, 120, slept)
   endif
@@ -37,7 +33,7 @@ func Test_repeat_three()
   let slept = WaitFor('g:val == 3')
   call assert_equal(3, g:val)
   if has('reltime')
-    call s:assert_inrange(120, 250, slept)
+    call assert_inrange(120, LoadAdjust(250), slept)
   else
     call assert_inrange(80, 200, slept)
   endif
@@ -52,7 +48,7 @@ func Test_repeat_many()
   endif
   sleep 200m
   call timer_stop(timer)
-  call s:assert_inrange((has('mac') ? 1 : 2), 4, g:val)
+  call assert_inrange((has('mac') ? 1 : 2), LoadAdjust(4), g:val)
 endfunc
 
 func Test_with_partial_callback()
@@ -66,7 +62,7 @@ func Test_with_partial_callback()
   let slept = WaitFor('g:val == 1')
   call assert_equal(1, g:val)
   if has('reltime')
-    call s:assert_inrange(40, 130, slept)
+    call assert_inrange(40, LoadAdjust(130), slept)
   else
     call assert_inrange(20, 100, slept)
   endif
@@ -129,7 +125,7 @@ func Test_paused()
   let slept = WaitFor('g:val == 1')
   call assert_equal(1, g:val)
   if has('reltime')
-    call s:assert_inrange(0, 140, slept)
+    call assert_inrange(0, LoadAdjust(140), slept)
   else
     call assert_inrange(0, 10, slept)
   endif