Debian Codegraph @

lualib/lua_shape/registry.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 - Registry module
18 -- Provides schema registration and reference resolution
19
20 local Registry = {}
21 Registry.__index = Registry
22
23 -- Simple utility functions
24 local function shallowcopy(t)
25 local result = {}
26 for k, v in pairs(t) do
27 result[k] = v
28 end
29 -- Preserve metatable if present
30 local mt = getmetatable(t)
31 if mt then
32 setmetatable(result, mt)
33 end
34 return result
35 end
36
37 -- Global registry instance
38 local global_registry = nil
39
40 -- Create a new registry
41 local function new()
42 return setmetatable({
43 schemas = {},
44 resolved_cache = {}
45 }, Registry)
46 end
47
48 -- Get or create global registry
49 function Registry.global()
50 if not global_registry then
51 global_registry = new()
52 end
53 return global_registry
54 end
55
56 -- Define a schema with an ID
57 function Registry:define(id, schema)
58 if self.schemas[id] then
59 error("Schema already defined: " .. id)
60 end
61
62 -- Set schema_id in opts if not already set
63 if not schema.opts then
64 schema.opts = {}
65 end
66 if not schema.opts.schema_id then
67 schema.opts.schema_id = id
68 end
69
70 -- Resolve mixins if this is a table schema
71 local resolved = self:resolve_schema(schema)
72
73 self.schemas[id] = {
74 id = id,
75 original = schema,
76 resolved = resolved
77 }
78
79 return resolved
80 end
81
82 -- Get a schema by ID
83 function Registry:get(id)
84 local entry = self.schemas[id]
85 if not entry then
86 return nil
87 end
88 return entry.resolved
89 end
90
91 -- Resolve references and mixins in a schema
92 function Registry:resolve_schema(schema)
93 if not schema then
94 return nil
95 end
96
97 local tag = schema.tag
98
99 -- If already resolved, return from cache
100 -- Use the schema table itself as key (works with weak tables)
101 if self.resolved_cache[schema] then
102 return self.resolved_cache[schema]
103 end
104
105 -- Handle reference nodes
106 if tag == "ref" then
107 local ref_id = schema.ref_id
108 local target = self.schemas[ref_id]
109 if not target then
110 -- Return schema as-is with unresolved reference
111 -- It will error during validation, not during schema registration
112 return schema
113 end
114 return target.resolved
115 end
116
117 -- Handle table nodes with mixins and/or extra schema
118 if tag == "table" then
119 local opts = schema.opts or {}
120 local mixins = opts.mixins or {}
121 local has_mixins = #mixins > 0
122 local has_extra = opts.extra ~= nil
123
124 -- First, recursively resolve all field schemas
125 local fields = schema.fields or {}
126 local resolved_fields = nil
127 local fields_changed = false
128
129 for field_name, field_spec in pairs(fields) do
130 local field_schema = field_spec.schema
131 local resolved_field_schema = self:resolve_schema(field_schema)
132 if resolved_field_schema ~= field_schema then
133 if not resolved_fields then
134 resolved_fields = shallowcopy(fields)
135 end
136 local resolved_field_spec = shallowcopy(field_spec)
137 resolved_field_spec.schema = resolved_field_schema
138 resolved_fields[field_name] = resolved_field_spec
139 fields_changed = true
140 end
141 end
142
143 local merged_fields = resolved_fields or fields
144 local resolved_extra = opts.extra
145
146 -- Merge mixin fields if present
147 if has_mixins then
148 if not resolved_fields then
149 merged_fields = shallowcopy(fields)
150 end
151
152 for _, mixin_def in ipairs(mixins) do
153 if mixin_def._is_mixin then
154 local mixin_schema = mixin_def.schema
155
156 -- Resolve mixin schema if it's a reference
157 if mixin_schema.tag == "ref" then
158 mixin_schema = self:resolve_schema(mixin_schema)
159 end
160
161 -- Extract fields from mixin
162 if mixin_schema.tag == "table" then
163 local mixin_fields = mixin_schema.fields or {}
164 local mixin_name = mixin_def.as or mixin_schema.opts.doc and
165 mixin_schema.opts.doc.summary or
166 "unknown"
167
168 for field_name, field_spec in pairs(mixin_fields) do
169 if merged_fields[field_name] then
170 -- Conflict: host field overrides mixin
171 merged_fields[field_name] = merged_fields[field_name] -- Keep host field
172 -- TODO: Add warning/logging
173 else
174 -- Add field from mixin with origin tracking
175 local field_copy = shallowcopy(field_spec)
176 field_copy.origin = {
177 mixin_name = mixin_name,
178 schema_id = mixin_schema.opts.schema_id
179 }
180 merged_fields[field_name] = field_copy
181 end
182 end
183 end
184 end
185 end
186 end
187
188 -- Resolve extra schema if present
189 if has_extra then
190 resolved_extra = self:resolve_schema(opts.extra)
191 end
192
193 -- Create new table schema if anything changed
194 if fields_changed or has_mixins or (has_extra and resolved_extra ~= opts.extra) then
195 local resolved = shallowcopy(schema)
196 resolved.fields = merged_fields
197 if resolved_extra ~= opts.extra then
198 local resolved_opts = shallowcopy(opts)
199 resolved_opts.extra = resolved_extra
200 resolved.opts = resolved_opts
201 end
202 self.resolved_cache[schema] = resolved
203 return resolved
204 end
205 end
206
207 -- Handle array nodes - resolve item schema
208 if tag == "array" then
209 local resolved_item = self:resolve_schema(schema.item_schema)
210 if resolved_item ~= schema.item_schema then
211 local resolved = shallowcopy(schema)
212 resolved.item_schema = resolved_item
213 self.resolved_cache[schema] = resolved
214 return resolved
215 end
216 end
217
218 -- Handle one_of nodes - resolve variant schemas
219 if tag == "one_of" then
220 local variants = schema.variants or {}
221 local resolved_variants = {}
222 local changed = false
223
224 for i, variant in ipairs(variants) do
225 local resolved_variant_schema = self:resolve_schema(variant.schema)
226 if resolved_variant_schema ~= variant.schema then
227 changed = true
228 end
229 resolved_variants[i] = {
230 name = variant.name,
231 schema = resolved_variant_schema
232 }
233 end
234
235 if changed then
236 local resolved = shallowcopy(schema)
237 resolved.variants = resolved_variants
238 self.resolved_cache[schema] = resolved
239 return resolved
240 end
241 end
242
243 -- Handle optional/transform wrappers - resolve inner schema
244 if tag == "optional" or tag == "transform" then
245 local resolved_inner = self:resolve_schema(schema.inner)
246 if resolved_inner ~= schema.inner then
247 local resolved = shallowcopy(schema)
248 resolved.inner = resolved_inner
249 self.resolved_cache[schema] = resolved
250 return resolved
251 end
252 end
253
254 -- No changes needed
255 return schema
256 end
257
258 -- List all registered schema IDs
259 function Registry:list()
260 local ids = {}
261 for id, _ in pairs(self.schemas) do
262 table.insert(ids, id)
263 end
264 table.sort(ids)
265 return ids
266 end
267
268 -- Export all schemas (for documentation or JSON Schema generation)
269 function Registry:export_all()
270 local result = {}
271 for id, entry in pairs(self.schemas) do
272 result[id] = entry.resolved
273 end
274 return result
275 end
276
277 return Registry