| 1 |
--[[ |
| 2 |
Copyright (c) 2025, Vsevolod Stakhov <[email protected]> |
| 3 |
|
| 4 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 |
you may not use this file except in compliance with the License. |
| 6 |
You may obtain a copy of the License at |
| 7 |
|
| 8 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
|
| 10 |
Unless required by applicable law or agreed to in writing, software |
| 11 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
See the License for the specific language governing permissions and |
| 14 |
limitations under the License. |
| 15 |
]]-- |
| 16 |
|
| 17 |
-- Lua shape validation library - Documentation IR generator |
| 18 |
-- Generates structured documentation from schemas |
| 19 |
|
| 20 |
local exports = {} |
| 21 |
|
| 22 |
-- Extract documentation from opts |
| 23 |
local function get_doc(opts) |
| 24 |
if not opts or not opts.doc then |
| 25 |
return {} |
| 26 |
end |
| 27 |
return opts.doc |
| 28 |
end |
| 29 |
|
| 30 |
-- Generate doc IR for a schema node |
| 31 |
local function generate_doc_impl(schema, path) |
| 32 |
path = path or "(root)" |
| 33 |
|
| 34 |
if not schema or not schema.tag then |
| 35 |
return { |
| 36 |
type = "unknown", |
| 37 |
path = path |
| 38 |
} |
| 39 |
end |
| 40 |
|
| 41 |
local doc = get_doc(schema.opts) |
| 42 |
local result = { |
| 43 |
type = schema.tag, |
| 44 |
path = path, |
| 45 |
summary = doc.summary, |
| 46 |
description = doc.description, |
| 47 |
examples = doc.examples |
| 48 |
} |
| 49 |
|
| 50 |
local tag = schema.tag |
| 51 |
|
| 52 |
-- Scalar types |
| 53 |
if tag == "scalar" then |
| 54 |
result.kind = schema.kind |
| 55 |
result.constraints = {} |
| 56 |
|
| 57 |
local opts = schema.opts or {} |
| 58 |
|
| 59 |
if schema.kind == "string" then |
| 60 |
if opts.min_len then result.constraints.min_length = opts.min_len end |
| 61 |
if opts.max_len then result.constraints.max_length = opts.max_len end |
| 62 |
if opts.pattern then result.constraints.pattern = opts.pattern end |
| 63 |
|
| 64 |
elseif schema.kind == "number" or schema.kind == "integer" then |
| 65 |
if opts.min then result.constraints.minimum = opts.min end |
| 66 |
if opts.max then result.constraints.maximum = opts.max end |
| 67 |
if opts.integer then result.constraints.integer = true end |
| 68 |
|
| 69 |
elseif schema.kind == "enum" then |
| 70 |
if opts.enum then result.constraints.values = opts.enum end |
| 71 |
|
| 72 |
elseif schema.kind == "literal" then |
| 73 |
result.constraints.value = opts.literal |
| 74 |
end |
| 75 |
|
| 76 |
-- Array type |
| 77 |
elseif tag == "array" then |
| 78 |
result.item_schema = generate_doc_impl(schema.item_schema, path .. "[]") |
| 79 |
|
| 80 |
local opts = schema.opts or {} |
| 81 |
result.constraints = {} |
| 82 |
if opts.min_items then result.constraints.min_items = opts.min_items end |
| 83 |
if opts.max_items then result.constraints.max_items = opts.max_items end |
| 84 |
|
| 85 |
-- Table type |
| 86 |
elseif tag == "table" then |
| 87 |
result.fields = {} |
| 88 |
result.mixin_groups = {} |
| 89 |
|
| 90 |
local opts = schema.opts or {} |
| 91 |
result.open = opts.open ~= false |
| 92 |
result.extra_schema = opts.extra and generate_doc_impl(opts.extra, path .. ".*") or nil |
| 93 |
|
| 94 |
-- Group fields by origin (mixins) |
| 95 |
local origin_groups = {} |
| 96 |
local no_origin_fields = {} |
| 97 |
|
| 98 |
for field_name, field_spec in pairs(schema.fields or {}) do |
| 99 |
local field_doc = { |
| 100 |
name = field_name, |
| 101 |
optional = field_spec.optional or false, |
| 102 |
default = field_spec.default, |
| 103 |
schema = generate_doc_impl(field_spec.schema, path .. "." .. field_name) |
| 104 |
} |
| 105 |
|
| 106 |
if field_spec.origin then |
| 107 |
local origin_key = field_spec.origin.mixin_name or "unknown" |
| 108 |
if not origin_groups[origin_key] then |
| 109 |
origin_groups[origin_key] = { |
| 110 |
mixin_name = field_spec.origin.mixin_name, |
| 111 |
schema_id = field_spec.origin.schema_id, |
| 112 |
fields = {} |
| 113 |
} |
| 114 |
end |
| 115 |
table.insert(origin_groups[origin_key].fields, field_doc) |
| 116 |
else |
| 117 |
table.insert(no_origin_fields, field_doc) |
| 118 |
end |
| 119 |
end |
| 120 |
|
| 121 |
-- Add direct fields first |
| 122 |
result.fields = no_origin_fields |
| 123 |
|
| 124 |
-- Add mixin groups |
| 125 |
for _, group in pairs(origin_groups) do |
| 126 |
table.insert(result.mixin_groups, group) |
| 127 |
end |
| 128 |
|
| 129 |
-- one_of type |
| 130 |
elseif tag == "one_of" then |
| 131 |
result.variants = {} |
| 132 |
|
| 133 |
for i, variant in ipairs(schema.variants or {}) do |
| 134 |
local variant_doc = generate_doc_impl(variant.schema, path .. "::variant" .. i) |
| 135 |
variant_doc.name = variant.name or ("variant_" .. i) |
| 136 |
table.insert(result.variants, variant_doc) |
| 137 |
end |
| 138 |
|
| 139 |
-- Optional wrapper |
| 140 |
elseif tag == "optional" then |
| 141 |
result = generate_doc_impl(schema.inner, path) |
| 142 |
result.optional = true |
| 143 |
if schema.default ~= nil then |
| 144 |
result.default = schema.default |
| 145 |
end |
| 146 |
-- Preserve doc from optional wrapper |
| 147 |
local wrapper_doc = get_doc(schema.opts) |
| 148 |
if wrapper_doc.summary and not result.summary then |
| 149 |
result.summary = wrapper_doc.summary |
| 150 |
end |
| 151 |
if wrapper_doc.description and not result.description then |
| 152 |
result.description = wrapper_doc.description |
| 153 |
end |
| 154 |
if wrapper_doc.examples and not result.examples then |
| 155 |
result.examples = wrapper_doc.examples |
| 156 |
end |
| 157 |
|
| 158 |
-- Transform wrapper |
| 159 |
elseif tag == "transform" then |
| 160 |
result = generate_doc_impl(schema.inner, path) |
| 161 |
result.has_transform = true |
| 162 |
|
| 163 |
-- Reference |
| 164 |
elseif tag == "ref" then |
| 165 |
result.ref_id = schema.ref_id |
| 166 |
end |
| 167 |
|
| 168 |
return result |
| 169 |
end |
| 170 |
|
| 171 |
-- Generate documentation IR for a schema |
| 172 |
function exports.for_schema(schema, opts) |
| 173 |
opts = opts or {} |
| 174 |
|
| 175 |
local doc_tree = generate_doc_impl(schema, opts.root_path or "(root)") |
| 176 |
|
| 177 |
return { |
| 178 |
schema_doc = doc_tree, |
| 179 |
metadata = { |
| 180 |
generated_at = os.date("%Y-%m-%d %H:%M:%S"), |
| 181 |
generator = "rspamd_schema v1.0" |
| 182 |
} |
| 183 |
} |
| 184 |
end |
| 185 |
|
| 186 |
-- Generate documentation for all schemas in a registry |
| 187 |
function exports.for_registry(registry, opts) |
| 188 |
opts = opts or {} |
| 189 |
|
| 190 |
local schemas = registry:export_all() |
| 191 |
local result = { |
| 192 |
schemas = {}, |
| 193 |
metadata = { |
| 194 |
generated_at = os.date("%Y-%m-%d %H:%M:%S"), |
| 195 |
generator = "rspamd_schema v1.0" |
| 196 |
} |
| 197 |
} |
| 198 |
|
| 199 |
for id, schema in pairs(schemas) do |
| 200 |
result.schemas[id] = generate_doc_impl(schema, id) |
| 201 |
end |
| 202 |
|
| 203 |
return result |
| 204 |
end |
| 205 |
|
| 206 |
-- Simple markdown renderer (optional helper) |
| 207 |
function exports.render_markdown(doc_tree, indent) |
| 208 |
indent = indent or 0 |
| 209 |
local lines = {} |
| 210 |
local prefix = string.rep(" ", indent) |
| 211 |
|
| 212 |
if doc_tree.summary then |
| 213 |
table.insert(lines, prefix .. "**" .. doc_tree.summary .. "**") |
| 214 |
end |
| 215 |
|
| 216 |
if doc_tree.description then |
| 217 |
table.insert(lines, prefix .. doc_tree.description) |
| 218 |
end |
| 219 |
|
| 220 |
if doc_tree.type == "scalar" then |
| 221 |
local type_str = doc_tree.kind or "unknown" |
| 222 |
local constraint_strs = {} |
| 223 |
|
| 224 |
for k, v in pairs(doc_tree.constraints or {}) do |
| 225 |
table.insert(constraint_strs, k .. "=" .. tostring(v)) |
| 226 |
end |
| 227 |
|
| 228 |
if #constraint_strs > 0 then |
| 229 |
type_str = type_str .. " (" .. table.concat(constraint_strs, ", ") .. ")" |
| 230 |
end |
| 231 |
|
| 232 |
table.insert(lines, prefix .. "Type: `" .. type_str .. "`") |
| 233 |
|
| 234 |
elseif doc_tree.type == "array" then |
| 235 |
table.insert(lines, prefix .. "Type: `array`") |
| 236 |
table.insert(lines, prefix .. "Items:") |
| 237 |
local item_lines = exports.render_markdown(doc_tree.item_schema, indent + 1) |
| 238 |
for _, line in ipairs(item_lines) do |
| 239 |
table.insert(lines, line) |
| 240 |
end |
| 241 |
|
| 242 |
elseif doc_tree.type == "table" then |
| 243 |
table.insert(lines, prefix .. "Type: `table`") |
| 244 |
|
| 245 |
if #doc_tree.fields > 0 then |
| 246 |
table.insert(lines, prefix .. "Fields:") |
| 247 |
for _, field in ipairs(doc_tree.fields) do |
| 248 |
local opt_str = field.optional and " (optional)" or " (required)" |
| 249 |
if field.default ~= nil then |
| 250 |
opt_str = opt_str .. ", default: " .. tostring(field.default) |
| 251 |
end |
| 252 |
table.insert(lines, prefix .. " - **" .. field.name .. "**" .. opt_str) |
| 253 |
local field_lines = exports.render_markdown(field.schema, indent + 2) |
| 254 |
for _, line in ipairs(field_lines) do |
| 255 |
table.insert(lines, line) |
| 256 |
end |
| 257 |
end |
| 258 |
end |
| 259 |
|
| 260 |
if #doc_tree.mixin_groups > 0 then |
| 261 |
table.insert(lines, prefix .. "Mixins:") |
| 262 |
for _, group in ipairs(doc_tree.mixin_groups) do |
| 263 |
table.insert(lines, prefix .. " - **" .. (group.mixin_name or "unknown") .. "**") |
| 264 |
for _, field in ipairs(group.fields) do |
| 265 |
local opt_str = field.optional and " (optional)" or " (required)" |
| 266 |
table.insert(lines, prefix .. " - **" .. field.name .. "**" .. opt_str) |
| 267 |
end |
| 268 |
end |
| 269 |
end |
| 270 |
|
| 271 |
elseif doc_tree.type == "one_of" then |
| 272 |
table.insert(lines, prefix .. "Type: `one_of` (must match exactly one alternative)") |
| 273 |
table.insert(lines, prefix .. "Alternatives:") |
| 274 |
for _, variant in ipairs(doc_tree.variants or {}) do |
| 275 |
table.insert(lines, prefix .. " - **" .. variant.name .. "**") |
| 276 |
local variant_lines = exports.render_markdown(variant, indent + 2) |
| 277 |
for _, line in ipairs(variant_lines) do |
| 278 |
table.insert(lines, line) |
| 279 |
end |
| 280 |
end |
| 281 |
end |
| 282 |
|
| 283 |
if doc_tree.examples then |
| 284 |
table.insert(lines, prefix .. "Examples:") |
| 285 |
for _, example in ipairs(doc_tree.examples) do |
| 286 |
table.insert(lines, prefix .. " - `" .. tostring(example) .. "`") |
| 287 |
end |
| 288 |
end |
| 289 |
|
| 290 |
return lines |
| 291 |
end |
| 292 |
|
| 293 |
return exports |