Coverage for packages/workshop/src/livery/workshop/_schema.py: 97%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""Each contract's JSON Schema, composed from its owners' keys, and its judge.
2
3Every key a contract may have is declared as a record
4([livery.workshop._contract_keys.Declared][]): the base's own, and each
5installed extension's from its declaration file. The records compose
6into one JSON Schema per contract, for the base and the extensions the
7root contract lists. The contract judge validates a contract against
8that schema, in its own words, and `fm sync` writes it under
9``.workshop/schema/``, where the composed ``.taplo.toml`` points Taplo,
10the language server behind an editor's TOML support: the judge and the
11editor read one statement of each contract's shape.
12
13A key's types become JSON Schema types, its values an ``enum`` and its
14doc the ``description``; a list of strings with values takes each of
15them at most once. A table whose keys the author names (``*`` in
16a declared path) takes ``additionalProperties`` with the entry's
17schema, and a key the table declares by name wins over that entry;
18every other table refuses a key it does not declare. A key of an
19installed extension the root does not list stays in the schema as a
20key that takes no value, carrying its owner, so the judge and the
21editor both name the extension to list.
22"""
23
24from __future__ import annotations
25
26import difflib
27import json
28from dataclasses import dataclass, field
29from pathlib import Path
30from typing import TYPE_CHECKING, Any, cast
31
32if TYPE_CHECKING:
33 from livery.workshop._contract_keys import ContractKind, Declared
34
35#: Where the composed schemas live: this checkout's own, written by the
36#: sync and never committed, since they follow what is installed.
37DIRECTORY = ".workshop/schema"
38
39#: Each contract's schema file, by contract.
40FILES: dict[ContractKind, str] = {
41 "root": "workshop.json",
42 "package": "package.json",
43 "extension": "extension.json",
44}
45
46#: The JSON Schema draft the files declare: the newest Taplo validates.
47DRAFT = "http://json-schema.org/draft-07/schema#"
48
49#: The keyword naming the extension that owns a key the root does not
50#: list; a validator that does not know it ignores it, as the draft says.
51OWNER = "x-owner"
52
53#: The keyword saying which list leaves that owner out, for the refusal.
54UNLISTED_BY = "x-unlisted-by"
55
56#: What each file describes, for its title.
57_TITLES: dict[ContractKind, str] = {
58 "root": "workshop.toml at a workspace's root",
59 "package": "workshop.toml in a package's directory",
60 "extension": "extension.toml beside an extension's package",
61}
62
63#: The schema of a list of strings: the one array the judge names whole.
64_STRINGS: dict[str, Any] = {"type": "array", "items": {"type": "string"}}
65
66
67@dataclass
68class _Node:
69 """One key of a contract, with what is declared beneath it.
70
71 Attributes:
72 declared: The key's record; None for a table only its keys declare.
73 unlisted: The owner of a key the contract's lists leave out;
74 empty for a key the composed schema takes.
75 unlisted_by: Which list leaves the owner out, as the refusal says
76 it: ``[workspace] extensions does not list``.
77 children: The keys declared beneath it, ``*`` for the author's.
78 items: A list's entries, when the list declares them.
79 """
80
81 declared: Declared | None = None
82 unlisted: str = ""
83 unlisted_by: str = ""
84 children: dict[str, _Node] = field(default_factory=dict[str, "_Node"])
85 items: _Node | None = None
86
87
88def _tree(keys: list[tuple[Declared, str, str]]) -> _Node:
89 """The contract's keys as a tree: ``*`` a child, ``[]`` a list's entries."""
90 root = _Node()
91 for declared, unlisted, unlisted_by in keys:
92 node = root
93 for segment in declared.path.split("."):
94 name = segment.removesuffix("[]")
95 node = node.children.setdefault(name, _Node())
96 if segment.endswith("[]"):
97 if node.items is None:
98 node.items = _Node()
99 node = node.items
100 node.declared = declared
101 node.unlisted = unlisted
102 node.unlisted_by = unlisted_by
103 return root
104
105
106def _object(node: _Node) -> dict[str, Any]:
107 """A table: its declared keys, and its author-named ones when it has them."""
108 found: dict[str, Any] = {"type": "object"}
109 properties = {
110 name: _schema(child)
111 for name, child in sorted(node.children.items())
112 if name != "*"
113 }
114 if properties:
115 found["properties"] = properties
116 wild = node.children.get("*")
117 found["additionalProperties"] = _schema(wild) if wild is not None else False
118 return found
119
120
121def _branch(kind: str, node: _Node) -> dict[str, Any]:
122 """The schema of one of a key's types."""
123 values = node.declared.values if node.declared is not None else ()
124 if kind == "str":
125 return (
126 {"type": "string", "enum": list(values)} if values else {"type": "string"}
127 )
128 if kind == "int":
129 return {"type": "integer"}
130 if kind == "number":
131 return {"type": "number"}
132 if kind == "bool":
133 return {"type": "boolean"}
134 if kind == "strs":
135 if not values:
136 return dict(_STRINGS)
137 return {
138 "type": "array",
139 "items": {"type": "string", "enum": list(values)},
140 "uniqueItems": True,
141 }
142 if kind == "list":
143 entries = _schema(node.items) if node.items is not None else {}
144 return {"type": "array", "items": entries}
145 if kind == "table":
146 return _object(node)
147 return {}
148
149
150def _schema(node: _Node) -> dict[str, Any]:
151 """A key's schema: each of its types, any one of them, and its doc."""
152 if node.unlisted:
153 return {
154 "description": f"a key of {node.unlisted}, which {node.unlisted_by}",
155 "not": {},
156 OWNER: node.unlisted,
157 UNLISTED_BY: node.unlisted_by,
158 }
159 types = node.declared.types if node.declared is not None else ("table",)
160 branches = [_branch(kind, node) for kind in types]
161 found = branches[0] if len(branches) == 1 else {"anyOf": branches}
162 if node.declared is not None and node.declared.doc:
163 found = {"description": node.declared.doc, **found}
164 return found
165
166
167def compose(contract: ContractKind, listed: frozenset[str] | None) -> dict[str, Any]:
168 """The JSON Schema of *contract* for the base and the *listed* extensions.
169
170 *listed* holds the names the contract's lists name the extensions by,
171 the base among them; None takes every installed owner as listed. A
172 key of an owner they leave out says which lists would take it.
173 The owners in [livery.workshop._contract_keys.ALWAYS][], the base
174 and the tool store, count as listed in every workspace. The
175 ``extension`` contract is the base's and the tool store's alone,
176 since an extension declares keys in a workspace's contracts and
177 never in another extension's file: composing it reads no other
178 owner's declarations, which a mount would otherwise read for every
179 installed extension.
180 """
181 from livery.workshop._contract_keys import ALWAYS, declarations, extension_keys
182
183 if contract == "extension":
184 keys = [(declared, "", "") for declared in extension_keys()]
185 else:
186 keys = []
187 for (kind, _path), owned in sorted(declarations().items()):
188 if kind != contract:
189 continue
190 if listed is None or owned.owner in ALWAYS or owned.owner in listed:
191 keys.append((owned.declared, "", ""))
192 else:
193 keys.append((owned.declared, owned.owner, _unlisted_by(contract)))
194 return {
195 "$schema": DRAFT,
196 "$comment": (
197 "Composed by the workshop's sync from the keys the base, the tool"
198 " store and the listed extensions declare; written again by every"
199 " sync, never edited."
200 ),
201 "title": _TITLES[contract],
202 **_object(_tree(keys)),
203 }
204
205
206def _unlisted_by(contract: ContractKind) -> str:
207 """Which lists leave an owner out, as a refusal of its key in *contract* says it.
208
209 A package's contract takes the keys of what the root's list or the
210 package's own list holds; the root's, those of what any list holds.
211 """
212 if contract == "package":
213 return "neither [workspace] extensions nor this package's `extensions` lists"
214 return "neither [workspace] extensions nor a package's `extensions` lists"
215
216
217_COMPOSED: dict[tuple[ContractKind, frozenset[str] | None], tuple[object, Any]] = {}
218
219
220def composed(contract: ContractKind, listed: frozenset[str] | None) -> dict[str, Any]:
221 """`compose`, once per set of declarations: what the judge validates against.
222
223 The judge reads the composition the schema files are written from,
224 never the files, so a file written before an extension was
225 installed or listed cannot misjudge a key until the next sync.
226 """
227 from livery.workshop._contract_keys import declarations, extension_keys
228
229 known: object = extension_keys() if contract == "extension" else declarations()
230 held = _COMPOSED.get((contract, listed))
231 if held is None or held[0] is not known:
232 held = (known, compose(contract, listed))
233 _COMPOSED[(contract, listed)] = held
234 return cast("dict[str, Any]", held[1])
235
236
237def contract_of(root: Path, relative: Path) -> ContractKind | None:
238 """Which contract the file at *relative* is; None for a file that is no contract.
239
240 The root's ``workshop.toml``, a package's beneath ``packages/``, or
241 any ``extension.toml``.
242 """
243 from livery.workshop._contract import _package_workspace
244
245 if relative.name == "extension.toml":
246 return "extension"
247 if relative.name != "workshop.toml":
248 return None
249 if relative == Path("workshop.toml"):
250 return "root"
251 return "package" if _package_workspace(root / relative) == root else None
252
253
254def judged_by(root: Path, relative: Path) -> str:
255 """The line naming the schema the file at *relative* is judged by; empty for none.
256
257 The file under ``.workshop/schema/``, and the owners whose keys it
258 holds: the base and the tool store, then the installed set, in
259 composition order. An ``extension.toml`` is judged by the base's
260 and the tool store's keys alone.
261 """
262 from livery.workshop._contract_keys import ALWAYS
263
264 contract = contract_of(root, relative)
265 if contract is None:
266 return ""
267 owners = list(ALWAYS)
268 if contract != "extension":
269 from livery.workshop._extensions import extension_names
270
271 owners += extension_names(root)
272 return f"schema: {DIRECTORY}/{FILES[contract]} ({', '.join(owners)})"
273
274
275def schema_files(root: Path) -> dict[str, bytes]:
276 """Each contract's composed schema for *root*, by its path under the root."""
277 from livery.workshop._contract import _root_tables
278 from livery.workshop._contract_keys import listed_extensions
279 from livery.workshop._extensions import installed_set
280
281 listed = listed_extensions(_root_tables(root / "workshop.toml")) | set(
282 installed_set(root)
283 )
284 return {
285 f"{DIRECTORY}/{name}": (
286 json.dumps(composed(contract, listed), indent=2) + "\n"
287 ).encode("utf-8")
288 for contract, name in FILES.items()
289 }
290
291
292# The judge: a contract against its schema, refused in the judge's words.
293
294
295def problems(schema: dict[str, Any], data: dict[str, Any]) -> list[str]:
296 """Each refusal *data* earns against *schema*, in the contract's order.
297
298 An unknown key names its table, the keys the table takes and the
299 nearest spelling; a key of an extension the contract's lists leave
300 out names the extension and the list that would take it; a value of
301 the wrong type names what the key takes; a value outside its set
302 names the set and the nearest. A key that takes any value is judged
303 by its reader, and nothing beneath it here.
304 """
305 found: list[str] = []
306 _table(schema, data, (), found)
307 return found
308
309
310def _table(
311 schema: dict[str, Any],
312 data: dict[str, Any],
313 parent: tuple[str, ...],
314 found: list[str],
315) -> None:
316 from livery.workshop._contract_keys import shown
317
318 properties = cast("dict[str, dict[str, Any]]", schema.get("properties", {}))
319 named = schema.get("additionalProperties", False)
320 for key, value in data.items():
321 path = (*parent, key)
322 child = properties.get(key)
323 if child is None and isinstance(named, dict):
324 child = cast("dict[str, Any]", named)
325 if child is None:
326 found.append(_unknown(key, parent, sorted(properties)))
327 continue
328 owner = child.get(OWNER)
329 if owner is not None:
330 found.append(
331 f"{shown(path)} is a key of {owner}, which {child.get(UNLISTED_BY)};"
332 " list the extension, or remove the key"
333 )
334 continue
335 _value(child, value, path, found)
336
337
338def _unknown(key: str, parent: tuple[str, ...], known: list[str]) -> str:
339 from livery.workshop._contract_keys import shown
340
341 named = shown(tuple(part.removesuffix("[]") for part in parent))
342 table = f"[{named}]" if parent else "the top level"
343 near = difflib.get_close_matches(key, known, n=1)
344 hint = f"; did you mean {near[0]!r}?" if near else ""
345 takes = ", ".join(known) if known else "no keys"
346 return f"{table} has no key {key!r}: it takes {takes}{hint}"
347
348
349def _value(
350 schema: dict[str, Any], value: object, path: tuple[str, ...], found: list[str]
351) -> None:
352 from livery.workshop._contract_keys import shown
353
354 branches = cast("list[dict[str, Any]]", schema.get("anyOf", [schema]))
355 named = shown(path)
356 fitting = [branch for branch in branches if _fits(branch, value)]
357 if not fitting:
358 actual = _type_of(value)
359 found.append(
360 f"{named} is {_ACTUAL.get(actual, actual)} ({value!r});"
361 f" it takes {' or '.join(_spoken(branch) for branch in branches)}"
362 )
363 return
364 if isinstance(value, str):
365 allowed = next((branch["enum"] for branch in fitting if "enum" in branch), None)
366 if allowed is not None and value not in allowed:
367 near = difflib.get_close_matches(value, allowed, n=1)
368 hint = f"; did you mean {near[0]!r}?" if near else ""
369 found.append(
370 f"{named} is {value!r}; it takes one of {', '.join(allowed)}{hint}"
371 )
372 return
373 if any(_takes_any(branch) for branch in fitting):
374 return
375 if isinstance(value, dict):
376 table = next(branch for branch in fitting if branch.get("type") == "object")
377 _table(table, cast("dict[str, Any]", value), path, found)
378 elif isinstance(value, list):
379 array = next(branch for branch in fitting if branch.get("type") == "array")
380 entries = cast("dict[str, Any]", array.get("items", {}))
381 if _is_strings(array):
382 _choices(array, cast("list[str]", value), named, found)
383 return
384 if _takes_any(entries):
385 return
386 listed_at = (*path[:-1], f"{path[-1]}[]")
387 for item in cast("list[object]", value):
388 _value(entries, item, listed_at, found)
389
390
391def _choices(
392 array: dict[str, Any], value: list[str], named: str, found: list[str]
393) -> None:
394 """Refuse an entry of a list of strings off its values, and one listed twice."""
395 allowed = cast("list[str] | None", array["items"].get("enum"))
396 if allowed is None:
397 return
398 takes = ", ".join(allowed)
399 seen: set[str] = set()
400 for item in value:
401 if item not in allowed:
402 near = difflib.get_close_matches(item, allowed, n=1)
403 hint = f"; did you mean {near[0]!r}?" if near else ""
404 found.append(f"{named} lists {item!r}; it takes {takes}{hint}")
405 elif item in seen:
406 found.append(f"{named} lists {item!r} twice; it takes each of {takes} once")
407 seen.add(item)
408
409
410def _is_strings(branch: dict[str, Any]) -> bool:
411 """Whether *branch* is a ``strs`` key's list of strings, its doc set aside.
412
413 A list of strings, or one taking each of its values at most once;
414 a ``list`` key's entries are judged one by one instead.
415 """
416 shape = {key: value for key, value in branch.items() if key != "description"}
417 if shape == _STRINGS:
418 return True
419 items = cast("dict[str, Any]", shape.get("items", {}))
420 return (
421 shape.get("uniqueItems") is True
422 and shape.get("type") == "array"
423 and items.get("type") == "string"
424 and "enum" in items
425 )
426
427
428def _takes_any(schema: dict[str, Any]) -> bool:
429 """Whether *schema* takes every value: no type, no choices, nothing beneath."""
430 return not any(key in schema for key in ("type", "anyOf", "enum", "not"))
431
432
433def _fits(branch: dict[str, Any], value: object) -> bool:
434 """Whether *value* has the type *branch* takes; a list of strings, whole."""
435 kind = branch.get("type")
436 if kind is None:
437 return _takes_any(branch)
438 if kind == "string":
439 return isinstance(value, str)
440 if kind == "integer":
441 return isinstance(value, int) and not isinstance(value, bool)
442 if kind == "number":
443 return isinstance(value, (int, float)) and not isinstance(value, bool)
444 if kind == "boolean":
445 return isinstance(value, bool)
446 if kind == "object":
447 return isinstance(value, dict)
448 if kind == "array":448 ↛ 454line 448 didn't jump to line 454 because the condition on line 448 was always true
449 if not isinstance(value, list):
450 return False
451 if _is_strings(branch):
452 return all(isinstance(item, str) for item in cast("list[object]", value))
453 return True
454 return False
455
456
457def _type_of(value: object) -> str:
458 if isinstance(value, bool):458 ↛ 459line 458 didn't jump to line 459 because the condition on line 458 was never true
459 return "bool"
460 if isinstance(value, int):
461 return "int"
462 if isinstance(value, float):462 ↛ 463line 462 didn't jump to line 463 because the condition on line 462 was never true
463 return "number"
464 if isinstance(value, str):
465 return "str"
466 if isinstance(value, list):466 ↛ 468line 466 didn't jump to line 468 because the condition on line 466 was always true
467 return "list"
468 if isinstance(value, dict):
469 return "table"
470 return type(value).__name__
471
472
473#: How a refusal names the type a value has.
474_ACTUAL = {
475 "str": "a string",
476 "int": "an integer",
477 "number": "a number",
478 "bool": "a boolean",
479 "list": "a list",
480 "table": "a table",
481}
482
483#: How a refusal names what a key takes, by JSON Schema type.
484_WORDS = {
485 "string": "a string",
486 "integer": "an integer",
487 "number": "a number",
488 "boolean": "true or false",
489 "array": "a list",
490 "object": "a table",
491}
492
493
494def _spoken(branch: dict[str, Any]) -> str:
495 """What *branch* takes, as a refusal says it."""
496 if _is_strings(branch):
497 return "a list of strings"
498 kind = branch.get("type")
499 return _WORDS.get(str(kind), "any value") if kind is not None else "any value"