@withgateway/sdk 0.2.6 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/README.md +24 -8
  2. package/dist/cli.js +15468 -11263
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +15233 -11028
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.d.mts +1 -1
  7. package/dist/files/index.d.ts +1 -1
  8. package/dist/files/index.js +291 -40
  9. package/dist/files/index.js.map +1 -1
  10. package/dist/files/index.mjs +284 -37
  11. package/dist/files/index.mjs.map +1 -1
  12. package/dist/hooks/index.d.mts +1 -1
  13. package/dist/hooks/index.d.ts +1 -1
  14. package/dist/hooks/index.js +203 -47
  15. package/dist/hooks/index.js.map +1 -1
  16. package/dist/hooks/index.mjs +198 -42
  17. package/dist/hooks/index.mjs.map +1 -1
  18. package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
  19. package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
  20. package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
  21. package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
  22. package/dist/index.d.mts +3 -3
  23. package/dist/index.d.ts +3 -3
  24. package/dist/index.js +2149 -615
  25. package/dist/index.js.map +1 -1
  26. package/dist/index.mjs +2053 -566
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/traces/index.js +268 -31
  29. package/dist/traces/index.js.map +1 -1
  30. package/dist/traces/index.mjs +262 -28
  31. package/dist/traces/index.mjs.map +1 -1
  32. package/dist/tracing/index.js +19 -11
  33. package/dist/tracing/index.js.map +1 -1
  34. package/dist/tracing/index.mjs +19 -11
  35. package/dist/tracing/index.mjs.map +1 -1
  36. package/dist/worlds/index.d.mts +886 -117
  37. package/dist/worlds/index.d.ts +886 -117
  38. package/dist/worlds/index.js +1770 -452
  39. package/dist/worlds/index.js.map +1 -1
  40. package/dist/worlds/index.mjs +1752 -434
  41. package/dist/worlds/index.mjs.map +1 -1
  42. package/package.json +14 -10
  43. package/runtime/gatewaysdk/environment/_toml.py +3 -10
  44. package/runtime/gatewaysdk/environment/_world.py +95 -28
  45. package/runtime/gatewaysdk/environment/runtime.py +10 -6
  46. package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
  47. package/runtime/gatewaysdk/environment/schema/api.py +19 -23
  48. package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
  49. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
  50. package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
  51. package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
  52. package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
  53. package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
  54. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
  55. package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
  56. package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
  57. package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
  58. package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
  59. package/runtime/gatewaysdk/environment/schema/data.py +21 -5
  60. package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
  61. package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
  62. package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
  63. package/runtime/gatewaysdk/environment/schema/host.py +68 -115
  64. package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
  65. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
  66. package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
  67. package/runtime/gatewaysdk/environment/schema/local.py +7 -10
  68. package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
  69. package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
  70. package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
  71. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
  72. package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
  73. package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
  74. package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
  75. package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
  76. package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
  77. package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
  78. package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
  79. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
  80. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
  81. package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
  82. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
  83. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
  84. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
  85. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  86. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
  87. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  88. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
  89. package/runtime/gatewaysdk/environment/schema/store.py +15 -6
  90. package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
  91. package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
  92. package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
  93. package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
  94. package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
  95. package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
  96. package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
  97. package/runtime/gatewaysdk/environment/world.py +42 -3
  98. package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
  99. package/skills/benchmarks-getting-started/SKILL.md +70 -22
  100. package/skills/connector-schema-authoring/SKILL.md +54 -4
  101. package/skills/connector-schema-authoring/connector-worlds.md +21 -7
  102. package/skills/connector-schema-authoring/world-schema.md +144 -83
  103. package/skills/hooks-getting-started/SKILL.md +27 -2
  104. package/skills/world-data-ingestion/ROWS.md +62 -0
  105. package/skills/world-data-ingestion/SKILL.md +91 -54
  106. package/skills/worlds-getting-started/SKILL.md +146 -146
  107. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
  108. package/skills/worlds-getting-started/references/gotchas.md +30 -0
  109. package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
  110. package/skills/worlds-getting-started/references/openapi-import.md +90 -0
@@ -0,0 +1,629 @@
1
+ """OpenAPI schemas to world.json ``$defs``: names, keys and the JSON Schema dialect.
2
+
3
+ Three concerns live here, each a class:
4
+
5
+ - :class:`Names` turns the vendor's spelling (``findPetsByStatus``,
6
+ ``nullable-simple-user``) into the identifiers the compiler accepts
7
+ (snake_case entity and operation names, plural entity names, legal field
8
+ names) and :class:`Namespace` keeps them unique with a numeric suffix.
9
+ - :class:`EntityKey` picks a schema's primary key: ``id``, then ``<name>Id`` /
10
+ ``<name>_id``, then a ``readOnly`` field the vendor marks unique in an ``x-``
11
+ extension, then the first required string or integer.
12
+ - :class:`SchemaConverter` rewrites the vendor's schemas into the subset
13
+ ``validation.py`` accepts: ``allOf`` merged, ``nullable`` folded into the
14
+ type, ``$ref`` re-pointed at ``#/$defs``, keywords the validator does not know
15
+ dropped and counted. Every top-level schema converts once, iteratively over a
16
+ worklist, so a document with a thousand schemas costs one pass over them; a
17
+ schema whose root reaches itself through ``$ref``/``allOf`` before it reaches
18
+ a property is refused with its pointer, because such a root has no shape.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import re
24
+ from collections import Counter, deque
25
+ from dataclasses import dataclass, field
26
+ from typing import Any
27
+
28
+ from .compiler import FIELD_RESERVED, RESERVED, RESERVED_STATE_KEYS
29
+ from .openapi_document import OpenApiDocument
30
+ from .validation import fail, pointer
31
+
32
+ IDENTIFIER = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
33
+ FIELD_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
34
+ RESERVED_FIELDS = frozenset({"_key", "payload"})
35
+ #: A ``$def`` for a value the vendor leaves untyped (``{}``, ``additionalProperties: true``
36
+ #: at the top). Not recursive on purpose: the validator wants recursive targets typed.
37
+ ANY_JSON = {
38
+ "anyOf": [
39
+ {"type": "string"},
40
+ {"type": "number"},
41
+ {"type": "boolean"},
42
+ {"type": "null"},
43
+ {"type": "object", "additionalProperties": True},
44
+ {
45
+ "type": "array",
46
+ "items": {
47
+ "anyOf": [
48
+ {"type": "string"},
49
+ {"type": "number"},
50
+ {"type": "boolean"},
51
+ {"type": "null"},
52
+ {"type": "object", "additionalProperties": True},
53
+ ]
54
+ },
55
+ },
56
+ ]
57
+ }
58
+ _STRING_FORMATS = frozenset({"date", "time", "date-time"})
59
+ _DOC_KEYS = ("title", "description")
60
+ _FLAG_KEYS = ("deprecated", "readOnly", "writeOnly")
61
+ _SCALARS = frozenset({"string", "integer", "number", "boolean", "null"})
62
+ _TYPES = _SCALARS | {"object", "array"}
63
+
64
+
65
+ class Names:
66
+ """The vendor's spelling, made legal for the compiler."""
67
+
68
+ @staticmethod
69
+ def snake(text: str) -> str:
70
+ text = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", text)
71
+ text = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", text)
72
+ text = re.sub(r"[^A-Za-z0-9]+", "_", text).strip("_").lower()
73
+ return re.sub(r"_+", "_", text)
74
+
75
+ @staticmethod
76
+ def plural(word: str) -> str:
77
+ if word.endswith(("ss", "x", "z", "ch", "sh")):
78
+ return word + "es"
79
+ if word.endswith("s"):
80
+ return word
81
+ if re.search(r"[^aeiou]y$", word):
82
+ return word[:-1] + "ies"
83
+ return word + "s"
84
+
85
+ @classmethod
86
+ def entity(cls, source: str, limit: int) -> str:
87
+ """``Pet`` → ``pets``, ``nullable-simple-user`` → ``nullable_simple_users``; at most ``limit`` long."""
88
+ name = cls.plural(cls.snake(source)) or "entity"
89
+ if not name[0].isalpha():
90
+ name = "e_" + name
91
+ if name.startswith(RESERVED) or name in RESERVED_STATE_KEYS:
92
+ name = "x_" + name
93
+ return name[:limit].rstrip("_") or "entity"
94
+
95
+ @classmethod
96
+ def operation(cls, source: str, limit: int) -> str:
97
+ """An ``operationId`` as a bounded snake_case operation name."""
98
+ name = cls.snake(source) or "operation"
99
+ if not name[0].isalpha():
100
+ name = "op_" + name
101
+ return name[:limit].rstrip("_") or "operation"
102
+
103
+ @staticmethod
104
+ def field(source: str) -> str:
105
+ """A property name the compiler accepts; the source name when it already is one."""
106
+ name = re.sub(r"[^A-Za-z0-9_]", "_", source)
107
+ if not name or not FIELD_IDENTIFIER.match(name):
108
+ name = "f_" + name
109
+ if name in RESERVED_FIELDS or name.startswith(FIELD_RESERVED):
110
+ name = "f_" + name
111
+ return name
112
+
113
+ @classmethod
114
+ def fields(cls, properties: dict[str, Any]) -> dict[str, str]:
115
+ """Source property -> the field name it is stored under, collisions suffixed."""
116
+ names = Namespace()
117
+ return {source: names.claim(cls.field(source))[0] for source in properties}
118
+
119
+
120
+ @dataclass
121
+ class Namespace:
122
+ """Names claimed so far (case-insensitively); a taken name gets ``_2``, ``_3``…"""
123
+
124
+ limit: int | None = None
125
+ taken: set[str] = field(default_factory=set)
126
+ #: Where the probe for a base resumes, so n claims of one name cost n, not n².
127
+ next_suffix: dict[str, int] = field(default_factory=dict)
128
+
129
+ def claim(self, base: str) -> tuple[str, bool]:
130
+ """(the name granted, whether it had to be suffixed)."""
131
+ if base.lower() not in self.taken:
132
+ self.taken.add(base.lower())
133
+ return base, False
134
+ suffix = self.next_suffix.get(base.lower(), 2)
135
+ while True:
136
+ stem = base if self.limit is None else base[: self.limit - len(str(suffix)) - 1].rstrip("_")
137
+ candidate = f"{stem}_{suffix}"
138
+ suffix += 1
139
+ if candidate.lower() not in self.taken:
140
+ self.taken.add(candidate.lower())
141
+ self.next_suffix[base.lower()] = suffix
142
+ return candidate, True
143
+
144
+
145
+ SCALARS = frozenset({"string", "integer", "number", "boolean"})
146
+
147
+
148
+ class EntityKey:
149
+ """Which property is a schema's primary key, and whether it is fit to be one."""
150
+
151
+ UNIQUE_EXTENSIONS = ("x-unique", "x-primary-key", "x-primaryKey", "x-identifier")
152
+
153
+ def __init__(self, document: OpenApiDocument, source: str, properties: dict[str, Any], required: set[str]):
154
+ self.document = document
155
+ self.source = source
156
+ self.properties = properties
157
+ self.required = required
158
+
159
+ def detect(self, *, fallback: bool = True) -> str | None:
160
+ """``id``, ``<name>Id``/``<name>_id``, a ``readOnly`` property marked unique by an
161
+ ``x-`` extension, else (when ``fallback``) the first required scalar."""
162
+ for name in self._id_like():
163
+ if self._keyable(name):
164
+ return name
165
+ for name, schema in self.properties.items():
166
+ resolved = self._resolved(schema)
167
+ if (
168
+ resolved.get("readOnly") is True
169
+ and any(resolved.get(x) is True for x in self.UNIQUE_EXTENSIONS)
170
+ and self._keyable(name)
171
+ ):
172
+ return name
173
+ if not fallback:
174
+ return None
175
+ for name in self.properties:
176
+ if name in self.required and self._keyable(name):
177
+ return name
178
+ return None
179
+
180
+ def scalars(self) -> frozenset[str]:
181
+ """Properties a filter can compare: string, integer, number or boolean."""
182
+ return frozenset(name for name in self.properties if self._scalar_type(name) in SCALARS)
183
+
184
+ def _scalar_type(self, name: str) -> str | None:
185
+ resolved = self._resolved(self.properties[name])
186
+ types = resolved.get("type")
187
+ if isinstance(types, list):
188
+ types = [t for t in types if t != "null"]
189
+ types = types[0] if len(types) == 1 else None
190
+ return types if isinstance(types, str) and not resolved.get("properties") else None
191
+
192
+ def _id_like(self) -> list[str]:
193
+ singular = Names.snake(self.source)
194
+ camel = re.sub(r"_([a-z0-9])", lambda m: m.group(1).upper(), singular)
195
+ candidates = ["id", "ID", "Id", f"{camel}Id", f"{camel}_id", f"{singular}_id", f"{singular}Id", f"{camel}ID"]
196
+ return [c for c in dict.fromkeys(candidates) if c in self.properties]
197
+
198
+ def _keyable(self, name: str) -> bool:
199
+ """A key is a string or integer that is never null."""
200
+ resolved = self._resolved(self.properties[name])
201
+ types = resolved.get("type")
202
+ nullable = resolved.get("nullable") is True or (isinstance(types, list) and "null" in types)
203
+ return not nullable and self._scalar_type(name) in ("string", "integer")
204
+
205
+ def _resolved(self, schema: Any) -> dict:
206
+ resolved = self.document.resolve(schema, f"{self.document.schemas_pointer}/{pointer(self.source)}/properties")
207
+ return resolved if isinstance(resolved, dict) else {}
208
+
209
+
210
+ @dataclass
211
+ class ConvertedDef:
212
+ name: str
213
+ schema: dict
214
+ fields: dict[str, str] # entity roots: source property → field name
215
+
216
+
217
+ class SchemaConverter:
218
+ """The document's schemas as world.json ``$defs``, converted once each."""
219
+
220
+ def __init__(self, document: OpenApiDocument, roots: dict[str, str]):
221
+ """``roots`` maps the source names that become entities to their key property."""
222
+ self.document = document
223
+ self.roots = roots
224
+ self.defs: dict[str, dict] = {}
225
+ self.fields: dict[str, dict[str, str]] = {}
226
+ self.dropped: Counter[str] = Counter()
227
+ self.renamed: list[tuple[str, str, str]] = []
228
+ self.warnings: list[str] = []
229
+ self._queue: deque[str] = deque()
230
+ self._any_json: str | None = None
231
+ self._merged: dict[str, dict] = {}
232
+ self._alias_of: dict[str, str] = {}
233
+ #: name → (the node its ``$ref`` chain ends at, the names walked from it inclusive).
234
+ self._tails: dict[str, tuple[Any, tuple[str, ...]]] = {}
235
+ self._names = Namespace()
236
+ for name in self.document.schemas:
237
+ self._names.claim(name)
238
+
239
+ # ------------------------------------------------------------- public
240
+
241
+ def convert_all(self, wanted: set[str]) -> dict[str, dict]:
242
+ """Convert ``wanted`` and everything they reference, in order of discovery."""
243
+ for name in sorted(wanted):
244
+ self._want(name)
245
+ while self._queue:
246
+ name = self._queue.popleft()
247
+ if name in self.defs:
248
+ continue
249
+ self.defs[name] = self._convert_def(name)
250
+ return dict(sorted(self.defs.items()))
251
+
252
+ def reference(self, name: str) -> str:
253
+ """The ``$ref`` a world.json node uses for a top-level schema."""
254
+ self._want(name)
255
+ return f"#/$defs/{pointer(name)}"
256
+
257
+ def any_json(self) -> dict:
258
+ if self._any_json is None:
259
+ self._any_json, _ = self._names.claim("AnyJson")
260
+ self.defs[self._any_json] = ANY_JSON
261
+ return {"$ref": f"#/$defs/{pointer(self._any_json)}"}
262
+
263
+ def _want(self, name: str) -> None:
264
+ if name not in self.defs and name not in self._queue:
265
+ self._queue.append(name)
266
+
267
+ # ------------------------------------------------------------- one top-level schema
268
+
269
+ def _convert_def(self, name: str) -> dict:
270
+ at = f"{self.document.schemas_pointer}/{pointer(name)}"
271
+ raw = self.document.schemas[name]
272
+ if not isinstance(raw, dict):
273
+ fail("spec", f"Schema {name} must be an object", at)
274
+ key = self.roots.get(name)
275
+ if key is None and isinstance(raw.get("$ref"), str):
276
+ return self._alias(name, raw, at)
277
+ resolved, chain = self.resolve_named(raw, at, (name,))
278
+ if not isinstance(resolved, dict):
279
+ fail("spec", f"Schema {name} must be an object", at)
280
+ merged = self.merged(resolved, at, chain)
281
+ if key is None:
282
+ return self.convert(merged, at, chain, resolve_root=False)
283
+ return self._entity_root(name, merged, at, key)
284
+
285
+ def _entity_root(self, name: str, merged: dict, at: str, key: str) -> dict:
286
+ converted = self.convert(merged, at, (name,), resolve_root=False)
287
+ properties = converted.get("properties")
288
+ if "object" not in _type_list(converted.get("type")) or not isinstance(properties, dict):
289
+ fail("spec", f"Schema {name} is not an object schema, so it cannot be an entity", at)
290
+ converted["type"] = "object"
291
+ converted.setdefault("title", name)
292
+ converted["$comment"] = f"source: {at}"
293
+ renamed = Names.fields(properties)
294
+ self.renamed.extend((f"{at}/properties/{pointer(src)}", src, dst) for src, dst in renamed.items() if src != dst)
295
+ converted["properties"] = {renamed[k]: v for k, v in properties.items()}
296
+ required = [renamed[r] for r in converted.get("required", []) if r in renamed]
297
+ if renamed[key] not in required:
298
+ required.append(renamed[key])
299
+ converted["required"] = required
300
+ converted["additionalProperties"] = False
301
+ converted.pop("anyOf", None)
302
+ converted.pop("oneOf", None)
303
+ self.fields[name] = renamed
304
+ return converted
305
+
306
+ def _alias(self, name: str, raw: dict, at: str) -> dict:
307
+ """A ``$ref``-only schema: a def that points straight at the end of its
308
+ chain, so a thousand chained aliases cost one walk, not a thousand."""
309
+ target = self._alias_of.get(name)
310
+ if target is None:
311
+ _, chain = self.resolve_named(raw, at, (name,))
312
+ target = chain[-1]
313
+ for alias in chain[:-1]:
314
+ self._alias_of.setdefault(alias, target)
315
+ if target == name:
316
+ return self.convert(self.document.lookup(raw["$ref"], at), at, (name,))
317
+ out: dict = {"$ref": self.reference(target)}
318
+ for key in _DOC_KEYS:
319
+ if isinstance(raw.get(key), str):
320
+ out[key] = raw[key]
321
+ return {"anyOf": [out, {"type": "null"}]} if _nullable(raw) else out
322
+
323
+ # ------------------------------------------------------------- allOf
324
+
325
+ def merged(self, resolved: dict, at: str, chain: tuple[str, ...]) -> dict:
326
+ """:meth:`merge` of a named schema, computed once: a diamond of ``allOf``
327
+ members (``A → B, C → D``) costs one merge of ``D``, not one per path."""
328
+ name = chain[-1]
329
+ if name not in self._merged:
330
+ self._merged[name] = self.merge(resolved, at, chain)
331
+ return self._merged[name]
332
+
333
+ def merge(self, raw: dict, at: str, stack: tuple[str, ...]) -> dict:
334
+ """``allOf`` of object members folded into one object schema; other
335
+ compositions are left for :meth:`convert`."""
336
+ members = raw.get("allOf")
337
+ if not isinstance(members, list) or not members:
338
+ return raw
339
+ flat: list[dict] = []
340
+ for index, member in enumerate(members):
341
+ here = f"{at}/allOf/{index}"
342
+ resolved, chain = self.resolve_named(member, here, stack)
343
+ if not isinstance(resolved, dict):
344
+ fail("spec", "allOf members must be schemas", here)
345
+ flat.append(
346
+ self.merged(resolved, here, chain) if len(chain) > len(stack) else self.merge(resolved, here, chain)
347
+ )
348
+ if not all(_object_like(m) for m in flat):
349
+ return raw
350
+ merged: dict = {k: v for k, v in raw.items() if k != "allOf"}
351
+ properties: dict = {}
352
+ required: list[str] = []
353
+ closed = False
354
+ for member in flat:
355
+ properties.update(member.get("properties") or {})
356
+ required.extend(r for r in member.get("required", []) if isinstance(r, str))
357
+ closed = closed or member.get("additionalProperties") is False
358
+ for doc in (k for k in _DOC_KEYS if isinstance(member.get(k), str)):
359
+ merged.setdefault(doc, member[doc])
360
+ properties.update(merged.get("properties") or {})
361
+ required.extend(r for r in merged.get("required", []) if isinstance(r, str))
362
+ merged.update({"type": "object", "properties": properties, "required": list(dict.fromkeys(required))})
363
+ if closed and "additionalProperties" not in merged:
364
+ merged["additionalProperties"] = False
365
+ return merged
366
+
367
+ def resolve_named(self, node: Any, at: str, stack: tuple[str, ...]) -> tuple[Any, tuple[str, ...]]:
368
+ """Resolve a node whose ``$ref`` chain must not come back to a schema on
369
+ ``stack``: that would make a root out of itself."""
370
+ chain = stack
371
+ fresh: list[str] = [] # names walked for the first time; a known tail ends the walk
372
+ tail: tuple[str, ...] = ()
373
+ while isinstance(node, dict) and isinstance(node.get("$ref"), str):
374
+ name = self.document.schema_name(node["$ref"])
375
+ known = self._tails.get(name) if name is not None else None
376
+ if known is not None:
377
+ node, tail = known
378
+ self._refuse_cycle(chain, tail, at)
379
+ chain = (*chain, *tail)
380
+ break
381
+ if name is not None:
382
+ self._refuse_cycle(chain, (name,), at)
383
+ chain, fresh = (*chain, name), [*fresh, name]
384
+ node = self.document.lookup(node["$ref"], at)
385
+ walked = (*fresh, *tail)
386
+ for index in range(len(fresh)):
387
+ self._tails[fresh[index]] = (node, walked[index:])
388
+ return node, chain
389
+
390
+ @staticmethod
391
+ def _refuse_cycle(chain: tuple[str, ...], tail: tuple[str, ...], at: str) -> None:
392
+ back = next((name for name in tail if name in chain), None)
393
+ if back is None:
394
+ return
395
+ fail(
396
+ "cycle",
397
+ f"Schema {chain[0]} reaches itself through {' -> '.join([*chain, back])} before any property: "
398
+ "an entity root cannot contain itself; reference it from a field instead",
399
+ at,
400
+ )
401
+
402
+ # ------------------------------------------------------------- one schema node
403
+
404
+ def convert(self, raw: Any, at: str, stack: tuple[str, ...], *, resolve_root: bool = True) -> dict:
405
+ if raw is True or raw == {}:
406
+ return self.any_json()
407
+ if not isinstance(raw, dict):
408
+ fail("spec", "A schema must be an object", at)
409
+ if resolve_root and isinstance(raw.get("$ref"), str):
410
+ return self._reference(raw, at, stack)
411
+ raw = self.merge(raw, at, stack)
412
+ if "allOf" in raw:
413
+ return self._composition(raw, "allOf", at, stack)
414
+ types, nullable = self._types(raw, at)
415
+ out: dict = {}
416
+ for key in _DOC_KEYS:
417
+ if isinstance(raw.get(key), str):
418
+ out[key] = raw[key]
419
+ for key in _FLAG_KEYS:
420
+ if raw.get(key) is True:
421
+ out[key] = True
422
+ if not types:
423
+ return self._untyped(raw, out, nullable, at, stack)
424
+ if len(types) > 1:
425
+ variants = [
426
+ self.convert({**raw, "type": t, "nullable": False, "x-nullable": False}, at, stack, resolve_root=False)
427
+ for t in types
428
+ ]
429
+ out["anyOf"] = variants + ([{"type": "null"}] if nullable else [])
430
+ return out
431
+ kind = types[0]
432
+ out["type"] = [kind, "null"] if nullable and kind != "null" else kind
433
+ getattr(self, f"_convert_{kind}")(raw, out, at, stack)
434
+ for composition in ("oneOf", "anyOf"):
435
+ if composition in raw:
436
+ out[composition] = self._members(raw[composition], f"{at}/{composition}", stack)
437
+ self._count_dropped(raw, out)
438
+ return out
439
+
440
+ def _reference(self, raw: dict, at: str, stack: tuple[str, ...]) -> dict:
441
+ ref = raw["$ref"]
442
+ name = self.document.schema_name(ref)
443
+ nullable = _nullable(raw)
444
+ if name is None:
445
+ return self.convert(self.document.lookup(ref, at), at, stack)
446
+ if name not in self.document.schemas:
447
+ fail("reference", f"Unknown $ref {ref}", at)
448
+ out: dict = {"$ref": self.reference(name)}
449
+ for key in _DOC_KEYS:
450
+ if isinstance(raw.get(key), str):
451
+ out[key] = raw[key]
452
+ return {"anyOf": [out, {"type": "null"}]} if nullable else out
453
+
454
+ def _composition(self, raw: dict, keyword: str, at: str, stack: tuple[str, ...]) -> dict:
455
+ out: dict = {k: raw[k] for k in _DOC_KEYS if isinstance(raw.get(k), str)}
456
+ out["allOf" if keyword == "allOf" else keyword] = self._members(raw[keyword], f"{at}/{keyword}", stack)
457
+ return out
458
+
459
+ def _members(self, members: Any, at: str, stack: tuple[str, ...]) -> list[dict]:
460
+ if not isinstance(members, list) or not members:
461
+ fail("spec", "A composition needs a non-empty array of schemas", at)
462
+ return [self.convert(m, f"{at}/{i}", stack) for i, m in enumerate(members)]
463
+
464
+ def _types(self, raw: dict, at: str) -> tuple[list[str], bool]:
465
+ declared = raw.get("type")
466
+ types = ["string" if t == "file" else t for t in _type_list(declared)]
467
+ unknown = [t for t in types if t not in _TYPES]
468
+ if unknown:
469
+ fail("spec", f"Unknown type {unknown[0]!r}", f"{at}/type")
470
+ nullable = "null" in types or raw.get("nullable") is True or raw.get("x-nullable") is True
471
+ types = [t for t in dict.fromkeys(types) if t != "null"]
472
+ if not types and declared is not None and "null" in (declared if isinstance(declared, list) else [declared]):
473
+ return ["null"], False
474
+ if not types:
475
+ types = self._infer(raw)
476
+ if isinstance(raw.get("enum"), list) and None in raw["enum"]:
477
+ nullable = True
478
+ return types, nullable
479
+
480
+ @staticmethod
481
+ def _infer(raw: dict) -> list[str]:
482
+ if (
483
+ isinstance(raw.get("properties"), dict)
484
+ or isinstance(raw.get("additionalProperties"), dict)
485
+ or raw.get("additionalProperties") is False
486
+ ):
487
+ return ["object"]
488
+ if "items" in raw:
489
+ return ["array"]
490
+ enum = raw.get("enum")
491
+ if isinstance(enum, list) and enum:
492
+ kinds = {_json_type(v) for v in enum if v is not None}
493
+ return sorted(kinds) if kinds and kinds <= _SCALARS else []
494
+ return []
495
+
496
+ def _untyped(self, raw: dict, out: dict, nullable: bool, at: str, stack: tuple[str, ...]) -> dict:
497
+ for composition in ("oneOf", "anyOf"):
498
+ if composition in raw:
499
+ members = self._members(raw[composition], f"{at}/{composition}", stack)
500
+ out[composition] = members + ([{"type": "null"}] if nullable else [])
501
+ return out
502
+ return self.any_json()
503
+
504
+ # ------------------------------------------------------------- per type
505
+
506
+ def _convert_object(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
507
+ self._object_properties(raw, out, at, stack)
508
+ extra = raw.get("additionalProperties")
509
+ if extra is False or extra is True:
510
+ out["additionalProperties"] = extra
511
+ elif isinstance(extra, dict):
512
+ out["additionalProperties"] = (
513
+ True if extra == {} else self.convert(extra, f"{at}/additionalProperties", stack)
514
+ )
515
+ elif "properties" not in out:
516
+ out["additionalProperties"] = True
517
+
518
+ def _object_properties(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
519
+ properties = raw.get("properties")
520
+ if properties is None:
521
+ return
522
+ if not isinstance(properties, dict):
523
+ fail("spec", "properties must be an object", f"{at}/properties")
524
+ out["properties"] = {
525
+ str(name): self.convert(schema, f"{at}/properties/{pointer(name)}", stack)
526
+ for name, schema in properties.items()
527
+ }
528
+ declared = raw.get("required") if isinstance(raw.get("required"), list) else []
529
+ required = [r for r in declared if isinstance(r, str) and r in properties]
530
+ if required:
531
+ out["required"] = list(dict.fromkeys(required))
532
+
533
+ def _convert_array(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
534
+ items = raw.get("items")
535
+ out["items"] = self.convert(items, f"{at}/items", stack) if isinstance(items, dict) else self.any_json()
536
+ for key in ("minItems", "maxItems"):
537
+ if isinstance(raw.get(key), int) and not isinstance(raw[key], bool):
538
+ out[key] = raw[key]
539
+ if raw.get("uniqueItems") is True:
540
+ out["uniqueItems"] = True
541
+
542
+ def _convert_string(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
543
+ if raw.get("format") in _STRING_FORMATS:
544
+ out["format"] = raw["format"]
545
+ for key in ("minLength", "maxLength"):
546
+ if isinstance(raw.get(key), int) and not isinstance(raw[key], bool):
547
+ out[key] = raw[key]
548
+ self._enum(raw, out, "string")
549
+
550
+ def _convert_integer(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
551
+ self._numeric(raw, out)
552
+ self._enum(raw, out, "integer")
553
+
554
+ def _convert_number(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
555
+ self._numeric(raw, out)
556
+ self._enum(raw, out, "number")
557
+
558
+ def _convert_boolean(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
559
+ self._enum(raw, out, "boolean")
560
+
561
+ def _convert_null(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
562
+ return None
563
+
564
+ @staticmethod
565
+ def _numeric(raw: dict, out: dict) -> None:
566
+ for key in ("minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"):
567
+ value = raw.get(key)
568
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
569
+ out[key] = value
570
+
571
+ @staticmethod
572
+ def _enum(raw: dict, out: dict, kind: str) -> None:
573
+ enum = raw.get("enum")
574
+ if not isinstance(enum, list) or not enum:
575
+ return
576
+ keep = [
577
+ v
578
+ for v in dict.fromkeys(_hashable(v) for v in enum)
579
+ if v is None or _json_type(v) == kind or (kind == "number" and _json_type(v) == "integer")
580
+ ]
581
+ if keep:
582
+ out["enum"] = keep
583
+
584
+ def _count_dropped(self, raw: dict, out: dict) -> None:
585
+ for key in raw:
586
+ if key in out or key in ("type", "nullable", "x-nullable", "required", "allOf", "$ref"):
587
+ continue
588
+ self.dropped[key] += 1
589
+
590
+
591
+ def _nullable(raw: dict) -> bool:
592
+ return raw.get("nullable") is True or raw.get("x-nullable") is True
593
+
594
+
595
+ def _object_like(schema: dict) -> bool:
596
+ declared = schema.get("type")
597
+ if declared not in (None, "object"):
598
+ return False
599
+ return (
600
+ declared == "object"
601
+ or isinstance(schema.get("properties"), dict)
602
+ or ("allOf" not in schema and not any(k in schema for k in ("oneOf", "anyOf", "items", "enum")))
603
+ )
604
+
605
+
606
+ def _type_list(declared: Any) -> list[str]:
607
+ if isinstance(declared, str):
608
+ return [declared]
609
+ return [t for t in declared if isinstance(t, str)] if isinstance(declared, list) else []
610
+
611
+
612
+ def _json_type(value: Any) -> str:
613
+ if isinstance(value, bool):
614
+ return "boolean"
615
+ if isinstance(value, int):
616
+ return "integer"
617
+ if isinstance(value, float):
618
+ return "number"
619
+ if isinstance(value, str):
620
+ return "string"
621
+ if isinstance(value, dict):
622
+ return "object"
623
+ if isinstance(value, list):
624
+ return "array"
625
+ return "null"
626
+
627
+
628
+ def _hashable(value: Any) -> Any:
629
+ return value if isinstance(value, (str, int, float, bool)) or value is None else repr(value)