refactor(config, modules): add types

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Assigning `false` to groups/specs/palettes clears previous settings from the config store
 -   Loading/sourcing colorscheme now causes recompilation if config or overrides changed, even if `setup()` was called before
 -   Refactored and improved `Color` lib (LSP types and descriptions, code-dedupe, stricter ctor, etc.) (#352)
+-   Added and improved types (LSP) for groups, config, and modules (#354)
 
 ### Changes
 

lua/github-theme/config.lua

@@ -1,8 +1,54 @@
 local collect = require('github-theme.lib.collect')
 local util = require('github-theme.util')
-
 local M = { theme = 'github_dark', has_options = false }
 
+-- TODO: improve type of `specs` and `palettes`
+---@class (exact) GhTheme.Config
+---@field options? GhTheme.Config.Options
+---@field palettes? table
+---@field specs? table
+---@field groups? table<GhTheme.Theme|"all", table<string, GhTheme.HighlightGroup>>
+
+---@class (exact) GhTheme.Config.Module
+---@field enable? boolean whether to set plugin-specific highlights for this module/plugin
+
+---@class (exact) GhTheme.Config.Module.Coc: GhTheme.Config.Module
+---@field background? boolean whether to set background color of virtual text
+
+---@class (exact) GhTheme.Config.Module.Diagnostic: GhTheme.Config.Module
+---@field background? boolean whether to set background color of virtual text
+
+---@class (exact) GhTheme.Config.Module.NativeLSP: GhTheme.Config.Module
+---@field background? boolean whether to set background color of virtual text
+
+---Config for external modules/plugins.
+---@class (exact) GhTheme.Config.Options.Modules
+---@field cmp? boolean|GhTheme.Config.Module
+---@field coc? boolean|GhTheme.Config.Module.Coc
+---@field coc_explorer? boolean|GhTheme.Config.Module
+---@field dapui? boolean|GhTheme.Config.Module
+---@field diffchar? boolean|GhTheme.Config.Module
+---@field dashboard? boolean|GhTheme.Config.Module
+---@field diagnostic? boolean|GhTheme.Config.Module.Diagnostic
+---@field fidget? boolean|GhTheme.Config.Module
+---@field fzf? boolean|GhTheme.Config.Module
+---@field gitgutter? boolean|GhTheme.Config.Module
+---@field gitsigns? boolean|GhTheme.Config.Module
+---@field indent_blankline? boolean|GhTheme.Config.Module
+---@field lsp_semantic_tokens? boolean|GhTheme.Config.Module
+---@field lsp_trouble? boolean|GhTheme.Config.Module
+---@field mini? boolean|GhTheme.Config.Module
+---@field native_lsp? boolean|GhTheme.Config.Module.NativeLSP
+---@field neogit? boolean|GhTheme.Config.Module
+---@field neotree? boolean|GhTheme.Config.Module
+---@field notify? boolean|GhTheme.Config.Module
+---@field nvimtree? boolean|GhTheme.Config.Module
+---@field telescope? boolean|GhTheme.Config.Module
+---@field treesitter? boolean|GhTheme.Config.Module
+---@field treesitter_context? boolean|GhTheme.Config.Module
+---@field whichkey? boolean|GhTheme.Config.Module
+
+---@class GhTheme.Config.Options
 local defaults = {
   compile_file_suffix = '_compiled',
   compile_path = util.join_paths(util.cache_home, 'github-theme'),
@@ -13,15 +59,34 @@ local defaults = {
   dim_inactive = false,
   module_default = true,
   styles = {
+    ---@type GhTheme.HighlightGroup.Style
     comments = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     functions = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     keywords = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     variables = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     conditionals = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     constants = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     numbers = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     operators = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     strings = 'NONE',
+
+    ---@type GhTheme.HighlightGroup.Style
     types = 'NONE',
   },
   inverse = {
@@ -33,9 +98,12 @@ local defaults = {
     floats = true,
     sidebars = {
       enable = true,
+      ---List of (filetype or `'terminal'`) whose bg will be darkened.
       list = {},
     },
   },
+
+  ---@type GhTheme.Config.Options.Modules
   modules = {
     coc = {
       background = true,
@@ -55,6 +123,12 @@ local defaults = {
   },
 }
 
+-- The following is done to disallow the addition of any more fields.
+
+---@type GhTheme.Config.Options
+---@diagnostic disable-next-line: redefined-local
+local defaults = defaults
+
 M.options = collect.deep_copy(defaults)
 
 M.module_names = {
@@ -84,10 +158,12 @@ M.module_names = {
   'whichkey',
 }
 
+---@param name GhTheme.Theme
 function M.set_theme(name)
   M.theme = name
 end
 
+---@param opts GhTheme.Config.Options
 function M.set_options(opts)
   opts = opts or {}
   M.options = collect.deep_extend(M.options, opts)
@@ -107,7 +183,7 @@ end
 
 function M.hash()
   local hash = require('github-theme.lib.hash')(M.options)
-  return hash and hash or 0
+  return hash or 0
 end
 
 return M

lua/github-theme/group.lua

@@ -3,6 +3,41 @@ local template = require('github-theme.util.template')
 local override = require('github-theme.override')
 local M = {}
 
+---A string whose contents is a comma-separated list of styles.
+---
+---## Examples
+---```lua
+---group.style = "bold,italic,underline"
+---group.style = "NONE"
+---```
+---@alias GhTheme.HighlightGroup.Style
+---| "NONE"
+---| "bold"
+---| "standout"
+---| "underline"
+---| "undercurl"
+---| "underdouble"
+---| "underdotted"
+---| "underdashed"
+---| "strikethrough"
+---| "italic"
+---| "reverse"
+---| "nocombine"
+---| string
+
+---A Neovim highlight-group definition.
+---@class (exact) GhTheme.HighlightGroup
+---@field fg? GhTheme.Color.CSSHexString
+---@field bg? GhTheme.Color.CSSHexString
+---@field sp? GhTheme.Color.CSSHexString
+---@field style? GhTheme.HighlightGroup.Style
+---@field blend? integer
+---@field nocombine? boolean
+---@field link? string
+---@field force? boolean
+
+---@param spec GhTheme.Spec
+---@return table<string, GhTheme.HighlightGroup>
 function M.from(spec)
   local config = require('github-theme.config').options
 
@@ -44,9 +79,11 @@ function M.from(spec)
   return res
 end
 
-function M.load(name)
-  name = name or require('github-theme.config').theme
-  return M.from(require('github-theme.spec').load(name))
+---@param theme? GhTheme.Theme
+---@return table<string, GhTheme.HighlightGroup>
+function M.load(theme)
+  theme = theme or require('github-theme.config').theme
+  return M.from(require('github-theme.spec').load(theme))
 end
 
 return M

lua/github-theme/group/modules/cmp.lua

@@ -2,11 +2,16 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
-  local has_ts = config.modules.treesitter
+---@param spec GhTheme.Spec
+---@param config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(spec, config, _opts)
+  local has_ts = config.modules.treesitter == true
+    or type(config.modules.treesitter) == 'table' and config.modules.treesitter.enable
   local syn = spec.syntax
 
   -- stylua: ignore
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     CmpDocumentation         = { fg = spec.fg1, bg = spec.bg0 },
     CmpDocumentationBorder   = { fg = spec.sel0, bg = spec.bg0 },

lua/github-theme/group/modules/coc.lua

@@ -2,9 +2,13 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param opts GhTheme.Config.Module.Coc
+function M.get(spec, _config, opts)
   local syn = spec.syntax
 
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     CocInlayHint = { fg = syn.comment, bg = opts.background and spec.bg2 or 'NONE' },
   }

lua/github-theme/group/modules/coc_explorer.lua

@@ -2,7 +2,11 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(spec, _config, _opts)
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     CocExplorerNormalFloat = { link = 'NormalSB' },
 

lua/github-theme/group/modules/dapui.lua

@@ -2,10 +2,14 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(spec, _config, _opts)
   local c = spec.palette
 
   -- stylua: ignore
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     DapUIScope                   = { fg = c.cyan.base },
     DapUIType                    = { fg = c.magenta.base },

lua/github-theme/group/modules/dashboard.lua

@@ -2,8 +2,12 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(spec, _config, _opts)
   -- stylua: ignore
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     DashboardShortCut = { link = 'Identifier' },
     DashboardHeader   = { link = 'Title' },

lua/github-theme/group/modules/diagnostic.lua

@@ -1,10 +1,14 @@
 local M = {}
 
-function M.get(spec, config, opts)
+---@param spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param opts GhTheme.Config.Module.Diagnostic
+function M.get(spec, _config, opts)
   local d = spec.diag
   local dbg = spec.diag_bg
 
   -- stylua: ignore
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     DiagnosticError            = { fg = d.error },
     DiagnosticWarn             = { fg = d.warn },
@@ -17,9 +21,9 @@ function M.get(spec, config, opts)
     DiagnosticSignHint         = { link = 'DiagnosticHint' },
 
     DiagnosticVirtualTextError = { fg = d.error, bg = opts.background and dbg.error or 'NONE' },
-    DiagnosticVirtualTextWarn  = { fg = d.warn, bg = opts.background and dbg.warn or 'NONE' },
-    DiagnosticVirtualTextInfo  = { fg = d.info, bg = opts.background and dbg.info or 'NONE' },
-    DiagnosticVirtualTextHint  = { fg = d.hint, bg = opts.background and dbg.hint or 'NONE' },
+    DiagnosticVirtualTextWarn  = { fg = d.warn,  bg = opts.background and dbg.warn  or 'NONE' },
+    DiagnosticVirtualTextInfo  = { fg = d.info,  bg = opts.background and dbg.info  or 'NONE' },
+    DiagnosticVirtualTextHint  = { fg = d.hint,  bg = opts.background and dbg.hint  or 'NONE' },
 
     DiagnosticUnderlineError   = { style = 'undercurl', sp = d.error },
     DiagnosticUnderlineWarn    = { style = 'undercurl', sp = d.warn },

lua/github-theme/group/modules/diffchar.lua

@@ -2,7 +2,11 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(spec, _config, _opts)
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     DiffAdd = { link = 'diffAdded' },
     DiffChange = { link = 'diffChanged' },

lua/github-theme/group/modules/fidget.lua

@@ -2,11 +2,15 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param _spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(_spec, _config, _opts)
   -- stylua: ignore
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     FidgetTitle = { link = 'Title' },
-    FidgetTask = { link = 'LineNr' },
+    FidgetTask  = { link = 'LineNr' },
   }
 end
 

lua/github-theme/group/modules/fzf.lua

@@ -2,8 +2,12 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param _spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(_spec, _config, _opts)
   -- stylua: ignore
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     FzfLuaNormal            = { link = 'Normal' },
     FzfLuaBorder            = { link = 'Normal' },

lua/github-theme/group/modules/gitgutter.lua

@@ -2,10 +2,14 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(spec, _config, _opts)
   local git = spec.git
 
   -- stylua: ignore
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     GitGutterAdd    = { fg = git.add }, -- diff mode: Added line |diff.txt|
     GitGutterChange = { fg = git.changed }, -- diff mode: Changed line |diff.txt|

lua/github-theme/group/modules/gitsigns.lua

@@ -2,10 +2,14 @@
 
 local M = {}
 
-function M.get(spec, config, opts)
+---@param spec GhTheme.Spec
+---@param _config GhTheme.Config.Options
+---@param _opts GhTheme.Config.Module
+function M.get(spec, _config, _opts)
   local git = spec.git
 
   -- stylua: ignore
+  ---@type table<string, GhTheme.HighlightGroup>
   return {
     GitSignsAdd    = { fg = git.add }, -- diff mode: Added line |diff.txt|
     GitSignsChange = { fg = git.changed }, -- diff mode: Changed line |diff.txt|