feat(#2415): add :NvimTreeHiTest (#2664)

* feat(#2415): add :NvimTreeHiTest

* feat(#2415): split out appearance diagnostics

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -10,6 +10,7 @@ CONTENTS                                                           *nvim-tree*
   2.1  Quickstart: Setup                        |nvim-tree-quickstart-setup|
   2.2  Quickstart: Help                         |nvim-tree-quickstart-help|
   2.3  Quickstart: Custom Mappings              |nvim-tree-quickstart-custom-mappings|
+  2.4  Quickstart: Highlight                    |nvim-tree-quickstart-highlight|
   3. Commands                                 |nvim-tree-commands|
   4. Setup                                    |nvim-tree-setup|
   5. Opts                                     |nvim-tree-opts|
@@ -43,6 +44,7 @@ CONTENTS                                                           *nvim-tree*
   6.7  API Marks                                |nvim-tree-api.marks|
   6.8  API Config                               |nvim-tree-api.config|
   6.9  API Commands                             |nvim-tree-api.commands|
+  6.10 API Diagnostics                          |nvim-tree-api.diagnostics|
   7. Mappings                                 |nvim-tree-mappings|
   7.1  Mappings: Default                        |nvim-tree-mappings-default|
   8. Highlight                                |nvim-tree-highlight|
@@ -230,6 +232,16 @@ via |nvim-tree.on_attach| e.g. >
     ---
   }
 <
+==============================================================================
+ 2.4 QUICKSTART: HIGHLIGHT                    *nvim-tree-quickstart-highlight*
+
+Run |:NvimTreeHiTest| to show all the highlights that nvim-tree uses.
+
+They can be customised before or after setup is called and will be immediately
+applied at runtime.
+
+See |nvim-tree-highlight| for details.
+
 ==============================================================================
  3. COMMANDS                                              *nvim-tree-commands*
 
@@ -324,6 +336,14 @@ via |nvim-tree.on_attach| e.g. >
 
     Calls: `api.tree.collapse_all(true)`
 
+*:NvimTreeHiTest*
+
+    Show nvim-tree highlight groups similar to `:so $VIMRUNTIME/syntax/hitest.vim`
+
+    See |nvim-tree-api.diagnostics.hi_test()|
+
+    Calls: `api.diagnostics.hi_test()`
+
 ==============================================================================
  4. SETUP                                                    *nvim-tree-setup*
 
@@ -2077,7 +2097,7 @@ config.mappings.get_keymap_default()
         (table) as per |nvim_buf_get_keymap()|
 
 ==============================================================================
- 6.8 API COMMANDS                                     *nvim-tree-api.commands*
+ 6.9 API COMMANDS                                     *nvim-tree-api.commands*
 
 commands.get()                                  *nvim-tree-api.commands.get()*
     Retrieve all commands, see |nvim-tree-commands|
@@ -2088,6 +2108,15 @@ commands.get()                                  *nvim-tree-api.commands.get()*
         • {command} (function)
         • {opts}    (table)
 
+==============================================================================
+ 6.10 DIAGNOSTICS                                  *nvim-tree-api.diagnostics*
+
+diagnostics.hi_test()                    *nvim-tree-api.diagnostics.hi_test()*
+    Open a new buffer displaying all nvim-tree highlight groups, their link
+    chain and concrete definition.
+
+    Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight|
+
 ==============================================================================
  7. MAPPINGS                                              *nvim-tree-mappings*
 
@@ -2253,7 +2282,9 @@ Example |:highlight| >
 It is recommended to enable 'termguicolors' for the more pleasant 24-bit
 colours.
 
-To view the active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim`
+To view the nvim-tree highlight groups run |:NvimTreeHiTest|
+
+To view all active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim`
 as per |:highlight|
 
 The `*HL` groups are additive as per |nvim-tree-opts-renderer| precedence.

lua/nvim-tree/api.lua

@@ -2,6 +2,7 @@ local lib = require "nvim-tree.lib"
 local view = require "nvim-tree.view"
 local utils = require "nvim-tree.utils"
 local actions = require "nvim-tree.actions"
+local appearance_diagnostics = require "nvim-tree.appearance.diagnostics"
 local events = require "nvim-tree.events"
 local help = require "nvim-tree.help"
 local live_filter = require "nvim-tree.live-filter"
@@ -39,6 +40,7 @@ local Api = {
     mappings = {},
   },
   commands = {},
+  diagnostics = {},
 }
 
 --- Do nothing when setup not called.
@@ -245,6 +247,8 @@ Api.config.mappings.get_keymap = wrap(keymap.get_keymap)
 Api.config.mappings.get_keymap_default = wrap(keymap.get_keymap_default)
 Api.config.mappings.default_on_attach = keymap.default_on_attach
 
+Api.diagnostics.hi_test = wrap(appearance_diagnostics.hi_test)
+
 Api.commands.get = wrap(function()
   return require("nvim-tree.commands").get()
 end)

lua/nvim-tree/appearance.lua

@@ -0,0 +1,80 @@
+local appearance = require "nvim-tree.appearance"
+
+local M = {}
+
+---@class HighlightDisplay for :NvimTreeHiTest
+---@field group string nvim-tree highlight group name
+---@field links string link chain to a concretely defined group
+---@field def string :hi concrete definition after following any links
+local HighlightDisplay = {}
+
+---@param group string nvim-tree highlight group
+---@return HighlightDisplay
+function HighlightDisplay:new(group)
+  local o = {}
+  setmetatable(o, self)
+  self.__index = self
+
+  o.group = group
+  local concrete = o.group
+
+  -- maybe follow links
+  local links = {}
+  local link = vim.api.nvim_get_hl(0, { name = o.group }).link
+  while link do
+    table.insert(links, link)
+    concrete = link
+    link = vim.api.nvim_get_hl(0, { name = link }).link
+  end
+  o.links = table.concat(links, " ")
+
+  -- concrete definition
+  local ok, res = pcall(vim.api.nvim_cmd, { cmd = "highlight", args = { concrete } }, { output = true })
+  if ok and type(res) == "string" then
+    o.def = res:gsub(".*xxx *", "")
+  else
+    o.def = ""
+  end
+
+  return o
+end
+
+function HighlightDisplay:render(bufnr, fmt, l)
+  local text = string.format(fmt, self.group, self.links, self.def)
+
+  vim.api.nvim_buf_set_lines(bufnr, l, -1, true, { text })
+  vim.api.nvim_buf_add_highlight(bufnr, -1, self.group, l, 0, #self.group)
+end
+
+---Run a test similar to :so $VIMRUNTIME/syntax/hitest.vim
+---Display all nvim-tree highlight groups, their link chain and actual definition
+function M.hi_test()
+  local displays = {}
+  local max_group_len = 0
+  local max_links_len = 0
+
+  -- build all highlight groups, name only
+  for _, highlight_group in ipairs(appearance.HIGHLIGHT_GROUPS) do
+    local display = HighlightDisplay:new(highlight_group.group)
+    table.insert(displays, display)
+    max_group_len = math.max(max_group_len, #display.group)
+    max_links_len = math.max(max_links_len, #display.links)
+  end
+
+  -- create a buffer
+  local bufnr = vim.api.nvim_create_buf(false, true)
+
+  -- render and highlight
+  local l = 0
+  local fmt = string.format("%%-%d.%ds %%-%d.%ds %%s", max_group_len, max_group_len, max_links_len, max_links_len)
+  for _, display in ipairs(displays) do
+    display:render(bufnr, fmt, l)
+    l = l + 1
+  end
+
+  -- finalise and focus the buffer
+  vim.api.nvim_buf_set_option(bufnr, "modifiable", false)
+  vim.cmd.buffer(bufnr)
+end
+
+return M