Debian Codegraph @

lualib/lua_shape/docs.lua

raw
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