refactor(palette, spec): cleanup, DRY, add types (#328)

Refactor palette.lua and spec.lua

Author: tmillr

lua/github-theme/init.lua

@@ -58,7 +58,7 @@ function M.compile(force)
     local themes = require('github-theme.palette').themes
     local current_theme = config.theme
 
-    for _, theme in ipairs(themes) do
+    for theme in pairs(themes) do
       -- Compile current theme last (see discussion in #290)
       if theme ~= current_theme then
         compiler.compile({ theme = theme })

lua/github-theme/palette.lua

@@ -1,60 +1,54 @@
-local collect = require('github-theme.lib.collect')
-local config = require('github-theme.config')
-
 local M = {}
 
+---@enum GhTheme.Theme
 M.themes = {
-  'github_dark',
-  'github_dark_colorblind',
-  'github_dark_default',
-  'github_dark_dimmed',
-  'github_dark_high_contrast',
-  'github_dark_tritanopia',
-  'github_light',
-  'github_light_colorblind',
-  'github_light_default',
-  'github_light_high_contrast',
-  'github_light_tritanopia',
+  github_dark = 'github_dark',
+  github_dark_colorblind = 'github_dark_colorblind',
+  github_dark_default = 'github_dark_default',
+  github_dark_dimmed = 'github_dark_dimmed',
+  github_dark_high_contrast = 'github_dark_high_contrast',
+  github_dark_tritanopia = 'github_dark_tritanopia',
+  github_light = 'github_light',
+  github_light_colorblind = 'github_light_colorblind',
+  github_light_default = 'github_light_default',
+  github_light_high_contrast = 'github_light_high_contrast',
+  github_light_tritanopia = 'github_light_tritanopia',
 }
 
-local function override(color, ovr)
-  for key, value in pairs(ovr) do
-    color[key] = value
-  end
-  return color
-end
-
-function M.load(name)
+---@param theme GhTheme.Theme
+local function get_palette(theme)
   local ovr = require('github-theme.override').palettes
-
-  local function apply_ovr(key, palette)
-    return ovr[key] and override(palette, ovr[key]) or palette
+  local raw = require('github-theme.palette.' .. theme)
+  local pal = raw.palette
+  if ovr.all then
+    pal = vim.tbl_deep_extend('force', pal, ovr.all)
   end
+  if ovr[theme] then
+    pal = vim.tbl_deep_extend('force', pal, ovr[theme])
+  end
+  pal.meta, pal.generate_spec = raw.meta, raw.generate_spec
+  return pal
+end
 
-  if name then
-    local valid = collect.contains(M.themes, name)
-    local raw = valid and require('github-theme.palette.' .. name)
-      or require('github-theme.palette.' .. config.theme)
-    local palette = raw.palette
-    palette = apply_ovr('all', palette)
-    palette = apply_ovr(name, palette)
-    palette.meta = raw.meta
-    palette.generate_spec = raw.generate_spec
+---Returns the palette for the given `theme`, or all themes (i.e. a map from
+---theme name to palette) if `theme` is `nil`.
+---@param theme? GhTheme.Theme
+function M.load(theme)
+  if theme ~= nil then
+    if not M.themes[theme] then
+      error('invalid theme provided: ' .. theme)
+    end
 
-    return palette
+    return get_palette(theme)
   else
-    local result = {}
-    for _, mod in ipairs(M.themes) do
-      local raw = require('github-theme.palette.' .. mod)
-      local palette = raw.palette
-      palette = apply_ovr('all', palette)
-      palette = apply_ovr(mod, palette)
-      palette.meta = raw.meta
-      palette.generate_spec = raw.generate_spec
-      result[mod] = palette
+    local all = {}
+
+    ---@diagnostic disable-next-line: redefined-local
+    for theme in pairs(M.themes) do
+      all[theme] = get_palette(theme)
     end
 
-    return result
+    return all
   end
 end
 

lua/github-theme/spec.lua

@@ -1,9 +1,8 @@
-local collect = require('github-theme.lib.collect')
-local template = require('github-theme.util.template')
+local M = {}
 
 --#region Types
 
----@class Spec
+---@class GhTheme.Spec
 ---@field bg0 string
 ---@field bg1 string
 ---@field bg2 string
@@ -16,18 +15,17 @@ local template = require('github-theme.util.template')
 ---@field sel0 string
 ---@field sel1 string
 ---@field sel2 string
----@field syntax SpecSyntax
----@field diag SpecDiagnostic
----@field diag_bg SpecDiagnosticBg
----@field diff SpecDiff
----@field git SpecGit
+---@field syntax GhTheme.Spec.Syntax
+---@field diag GhTheme.Spec.Diagnostic
+---@field diag_bg GhTheme.Spec.DiagnosticBg
+---@field diff GhTheme.Spec.Diff
+---@field git GhTheme.Spec.Git
 
----@class SpecSyntax
+---@class GhTheme.Spec.Syntax
 ---@field bracket string
 ---@field builtin0 string
 ---@field builtin1 string
 ---@field builtin2 string
----@field builtin3 string
 ---@field comment string
 ---@field conditional string
 ---@field const string
@@ -47,64 +45,62 @@ local template = require('github-theme.util.template')
 ---@field type string
 ---@field variable string
 
----@class SpecDiagnostic
+---@class GhTheme.Spec.Diagnostic
 ---@field error string
 ---@field warn string
 ---@field info string
 ---@field hint string
 
----@class SpecDiagnosticBg
+---@class GhTheme.Spec.DiagnosticBg
 ---@field error string
 ---@field warn string
 ---@field info string
 ---@field hint string
 
----@class SpecDiff
+---@class GhTheme.Spec.Diff
 ---@field add string
 ---@field delete string
 ---@field change string
 ---@field text string
 
----@class SpecGit
+---@class GhTheme.Spec.Git
 ---@field add string
 ---@field removed string
 ---@field changed string
 
 --#endregion
 
-local M = {}
-
-local function override(spec, palette, ovr)
-  ovr = template.parse(ovr, palette)
-  return collect.deep_extend(spec, ovr)
-end
-
-function M.load(name)
+---@param theme GhTheme.Theme
+local function get_spec(theme)
+  local template = require('github-theme.util.template')
   local ovr = require('github-theme.override').specs
-
-  local function apply_ovr(key, spec, palette)
-    return ovr[key] and override(spec, palette, ovr[key]) or spec
+  local pal = require('github-theme.palette').load(theme)
+  local spec = pal.generate_spec(pal)
+  if ovr.all then
+    pal = vim.tbl_deep_extend('force', pal, template.parse(ovr.all, pal))
+  end
+  if ovr[theme] then
+    pal = vim.tbl_deep_extend('force', pal, template.parse(ovr[theme], pal))
   end
+  spec.palette = pal
+  return spec
+end
 
-  if name then
-    local palette = require('github-theme.palette').load(name)
-    local spec = palette.generate_spec(palette)
-    spec = apply_ovr('all', spec, palette)
-    spec = apply_ovr(name, spec, palette)
-    spec.palette = palette
-    return spec
+---Returns the spec for the given `theme`, or all themes (i.e. a map from theme
+---name to spec) if `theme` is `nil`.
+---@param theme? GhTheme.Theme
+function M.load(theme)
+  if theme ~= nil then
+    return get_spec(theme)
   else
-    local result = {}
-    local themes = require('github-theme.palette').themes
-    for _, mod in ipairs(themes) do
-      local palette = require('github-theme.palette').load(mod)
-      local spec = palette.generate_spec(palette)
-      spec = apply_ovr('all', spec, palette)
-      spec = apply_ovr(mod, spec, palette)
-      spec.palette = palette
-      result[mod] = spec
+    local all = {}
+
+    ---@diagnostic disable-next-line: redefined-local
+    for theme in pairs(M.themes) do
+      all[theme] = get_spec(theme)
     end
-    return result
+
+    return all
   end
 end
 

lua/github-theme/util/template.lua

@@ -18,7 +18,7 @@ end
 
 ---Parses and resolves keypath string for configuration template.
 ---@param str string
----@param spec Spec
+---@param spec GhTheme.Spec
 ---@return any
 local function parse_keypath(str, spec)
   if type(str) ~= 'string' or str == '' or str:find('^#') then

test/github-theme/config/darken_spec.lua

@@ -14,7 +14,7 @@ describe('config > options > darken', function()
   end)
 
   describe('> floats', function()
-    for _, variant in ipairs(require('github-theme.palette').themes) do
+    for variant in pairs(require('github-theme.palette').themes) do
       -- TODO: see #324
       local it_or_pending = variant:find('high[-_]*contrast') and pending or it
 
@@ -49,7 +49,7 @@ describe('config > options > darken', function()
 
   describe('> sidebars', function()
     describe('> enable', function()
-      for _, variant in ipairs(require('github-theme.palette').themes) do
+      for variant in pairs(require('github-theme.palette').themes) do
         -- TODO: see #324
         local it_or_pending = variant:find('high[-_]*contrast') and pending or it