chore(refactor): improve configuration validation

## Details

Takes a much more schema centric approach to validating that the current
configuration is valid according to our type definitions. Easier to add
more complex types compared to previous approach which required creating
another custom validator implementation. Some error messages may be less
specific than before, primarily around errors in union types, but should
still generally point users in the right direction.

There is a kind of special hack to make everything under `overrides`
optional instead of mandatory, but I honestly prefer it to the previous
version of passing around random bits of state to make everything work.

Author: MeanderingProgrammer

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*       For NVIM v0.11.3       Last change: 2025 August 24
+*render-markdown.txt*       For NVIM v0.11.3       Last change: 2025 August 25
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*

lua/render-markdown/config/anti_conceal.lua

@@ -64,19 +64,22 @@ M.default = {
     },
 }
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    spec:type('enabled', 'boolean')
-    spec:list('disabled_modes', 'string', 'boolean')
-    spec:type('above', 'number')
-    spec:type('below', 'number')
-    spec:nested('ignore', function(ignore)
-        for _, element in pairs(Element) do
-            ignore:list(element, 'string', { 'boolean', 'nil' })
-        end
-        ignore:check()
-    end)
-    spec:check()
+---@return render.md.Schema
+function M.schema()
+    ---@type render.md.Schema
+    local modes = {
+        union = { { list = { type = 'string' } }, { type = 'boolean' } },
+    }
+    ---@type render.md.Schema
+    return {
+        record = {
+            enabled = { type = 'boolean' },
+            disabled_modes = modes,
+            above = { type = 'number' },
+            below = { type = 'number' },
+            ignore = { map = { key = { enum = Element }, value = modes } },
+        },
+    }
 end
 
 return M

lua/render-markdown/config/base.lua

@@ -7,10 +7,18 @@
 ---@class render.md.base.Cfg
 local M = {}
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    spec:type('enabled', 'boolean')
-    spec:list('render_modes', 'string', 'boolean')
+---@param additional_fields render.md.schema.Fields
+---@return render.md.Schema
+function M.schema(additional_fields)
+    ---@type render.md.schema.Fields
+    local fields = {
+        enabled = { type = 'boolean' },
+        render_modes = {
+            union = { { list = { type = 'string' } }, { type = 'boolean' } },
+        },
+    }
+    ---@type render.md.Schema
+    return { record = vim.tbl_deep_extend('error', fields, additional_fields) }
 end
 
 return M

lua/render-markdown/config/bullet.lua

@@ -66,16 +66,29 @@ M.default = {
     scope_highlight = {},
 }
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    require('render-markdown.config.base').validate(spec)
-    spec:nested_list('icons', 'string', 'function')
-    spec:nested_list('ordered_icons', 'string', 'function')
-    spec:type('left_pad', { 'number', 'function' })
-    spec:type('right_pad', { 'number', 'function' })
-    spec:nested_list('highlight', 'string', 'function')
-    spec:nested_list('scope_highlight', 'string', 'function')
-    spec:check()
+---@return render.md.Schema
+function M.schema()
+    ---@type render.md.Schema
+    local string_provider = {
+        union = {
+            { type = 'string' },
+            { list = { type = 'string' } },
+            { list = { list = { type = 'string' } } },
+            { type = 'function' },
+        },
+    }
+    ---@type render.md.Schema
+    local integer_provider = {
+        union = { { type = 'number' }, { type = 'function' } },
+    }
+    return require('render-markdown.config.base').schema({
+        icons = string_provider,
+        ordered_icons = string_provider,
+        left_pad = integer_provider,
+        right_pad = integer_provider,
+        highlight = string_provider,
+        scope_highlight = string_provider,
+    })
 end
 
 return M

lua/render-markdown/config/callout.lua

@@ -51,17 +51,20 @@ M.default = {
     cite      = { raw = '[!CITE]',      rendered = '󱆨 Cite',      highlight = 'RenderMarkdownQuote',   category = 'obsidian' },
 }
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    spec:each(function(callout)
-        callout:type('raw', 'string')
-        callout:type('rendered', 'string')
-        callout:type('highlight', 'string')
-        callout:type('quote_icon', { 'string', 'nil' })
-        callout:type('category', { 'string', 'nil' })
-        callout:check()
-    end, false)
-    spec:check()
+---@return render.md.Schema
+function M.schema()
+    ---@type render.md.Schema
+    local callout = {
+        record = {
+            raw = { type = 'string' },
+            rendered = { type = 'string' },
+            highlight = { type = 'string' },
+            quote_icon = { optional = true, type = 'string' },
+            category = { optional = true, type = 'string' },
+        },
+    }
+    ---@type render.md.Schema
+    return { map = { key = { type = 'string' }, value = callout } }
 end
 
 return M

lua/render-markdown/config/checkbox.lua

@@ -61,28 +61,32 @@ M.default = {
     },
 }
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    require('render-markdown.config.base').validate(spec)
-    spec:type('bullet', 'boolean')
-    spec:type('right_pad', 'number')
-    spec:nested({ 'unchecked', 'checked' }, function(box)
-        box:type('icon', 'string')
-        box:type('highlight', 'string')
-        box:type('scope_highlight', { 'string', 'nil' })
-        box:check()
-    end)
-    spec:nested('custom', function(boxes)
-        boxes:each(function(box)
-            box:type('raw', 'string')
-            box:type('rendered', 'string')
-            box:type('highlight', 'string')
-            box:type('scope_highlight', { 'string', 'nil' })
-            box:check()
-        end)
-        boxes:check()
-    end)
-    spec:check()
+---@return render.md.Schema
+function M.schema()
+    ---@type render.md.Schema
+    local component = {
+        record = {
+            icon = { type = 'string' },
+            highlight = { type = 'string' },
+            scope_highlight = { optional = true, type = 'string' },
+        },
+    }
+    ---@type render.md.Schema
+    local custom = {
+        record = {
+            raw = { type = 'string' },
+            rendered = { type = 'string' },
+            highlight = { type = 'string' },
+            scope_highlight = { optional = true, type = 'string' },
+        },
+    }
+    return require('render-markdown.config.base').schema({
+        bullet = { type = 'boolean' },
+        right_pad = { type = 'number' },
+        unchecked = component,
+        checked = component,
+        custom = { map = { key = { type = 'string' }, value = custom } },
+    })
 end
 
 return M

lua/render-markdown/config/code.lua

@@ -152,41 +152,45 @@ M.default = {
     style = 'full',
 }
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    require('render-markdown.config.base').validate(spec)
-    spec:type('sign', 'boolean')
-    spec:type('conceal_delimiters', 'boolean')
-    spec:type('language', 'boolean')
-    spec:one_of('position', vim.tbl_values(Position))
-    spec:type('language_icon', 'boolean')
-    spec:type('language_name', 'boolean')
-    spec:type('language_info', 'boolean')
-    spec:type('language_pad', 'number')
-    spec:list('disable_background', 'string', 'boolean')
-    spec:one_of('width', vim.tbl_values(Width))
-    spec:type('left_margin', 'number')
-    spec:type('left_pad', 'number')
-    spec:type('right_pad', 'number')
-    spec:type('min_width', 'number')
-    spec:one_of('border', vim.tbl_values(Border))
-    spec:type('language_border', 'string')
-    spec:type('language_left', 'string')
-    spec:type('language_right', 'string')
-    spec:type('above', 'string')
-    spec:type('below', 'string')
-    spec:type('inline', 'boolean')
-    spec:type('inline_left', 'string')
-    spec:type('inline_right', 'string')
-    spec:type('inline_pad', 'number')
-    spec:type('highlight', 'string')
-    spec:type('highlight_info', 'string')
-    spec:type('highlight_language', { 'string', 'nil' })
-    spec:one_of('highlight_border', { false }, 'string')
-    spec:type('highlight_fallback', 'string')
-    spec:type('highlight_inline', 'string')
-    spec:one_of('style', vim.tbl_values(Style))
-    spec:check()
+---@return render.md.Schema
+function M.schema()
+    return require('render-markdown.config.base').schema({
+        sign = { type = 'boolean' },
+        conceal_delimiters = { type = 'boolean' },
+        language = { type = 'boolean' },
+        position = { enum = Position },
+        language_icon = { type = 'boolean' },
+        language_name = { type = 'boolean' },
+        language_info = { type = 'boolean' },
+        language_pad = { type = 'number' },
+        disable_background = {
+            union = { { list = { type = 'string' } }, { type = 'boolean' } },
+        },
+        width = { enum = Width },
+        left_margin = { type = 'number' },
+        left_pad = { type = 'number' },
+        right_pad = { type = 'number' },
+        min_width = { type = 'number' },
+        border = { enum = Border },
+        language_border = { type = 'string' },
+        language_left = { type = 'string' },
+        language_right = { type = 'string' },
+        above = { type = 'string' },
+        below = { type = 'string' },
+        inline = { type = 'boolean' },
+        inline_left = { type = 'string' },
+        inline_right = { type = 'string' },
+        inline_pad = { type = 'number' },
+        highlight = { type = 'string' },
+        highlight_info = { type = 'string' },
+        highlight_language = { optional = true, type = 'string' },
+        highlight_border = {
+            union = { { enum = { false } }, { type = 'string' } },
+        },
+        highlight_fallback = { type = 'string' },
+        highlight_inline = { type = 'string' },
+        style = { enum = Style },
+    })
 end
 
 return M

lua/render-markdown/config/completions.lua

@@ -34,18 +34,24 @@ M.default = {
     },
 }
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    spec:nested({ 'blink', 'coq', 'lsp' }, function(completion)
-        completion:type('enabled', 'boolean')
-        completion:check()
-    end)
-    spec:nested('filter', function(filter)
-        filter:type('callout', 'function')
-        filter:type('checkbox', 'function')
-        filter:check()
-    end)
-    spec:check()
+---@return render.md.Schema
+function M.schema()
+    ---@type render.md.Schema
+    local completion = { record = { enabled = { type = 'boolean' } } }
+    ---@type render.md.Schema
+    return {
+        record = {
+            blink = completion,
+            coq = completion,
+            lsp = completion,
+            filter = {
+                record = {
+                    callout = { type = 'function' },
+                    checkbox = { type = 'function' },
+                },
+            },
+        },
+    }
 end
 
 return M

lua/render-markdown/config/dash.lua

@@ -30,14 +30,16 @@ M.default = {
     highlight = 'RenderMarkdownDash',
 }
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    require('render-markdown.config.base').validate(spec)
-    spec:type('icon', 'string')
-    spec:one_of('width', { 'full' }, 'number')
-    spec:type('left_margin', 'number')
-    spec:type('highlight', 'string')
-    spec:check()
+---@return render.md.Schema
+function M.schema()
+    return require('render-markdown.config.base').schema({
+        icon = { type = 'string' },
+        width = {
+            union = { { enum = { 'full' } }, { type = 'number' } },
+        },
+        left_margin = { type = 'number' },
+        highlight = { type = 'string' },
+    })
 end
 
 return M

lua/render-markdown/config/document.lua

@@ -24,15 +24,16 @@ M.default = {
     },
 }
 
----@param spec render.md.debug.ValidatorSpec
-function M.validate(spec)
-    require('render-markdown.config.base').validate(spec)
-    spec:nested('conceal', function(conceal)
-        conceal:list('char_patterns', 'string')
-        conceal:list('line_patterns', 'string')
-        conceal:check()
-    end)
-    spec:check()
+---@return render.md.Schema
+function M.schema()
+    return require('render-markdown.config.base').schema({
+        conceal = {
+            record = {
+                char_patterns = { list = { type = 'string' } },
+                line_patterns = { list = { type = 'string' } },
+            },
+        },
+    })
 end
 
 return M