texpkg 0.1.0__py3-none-any.whl

texpkg/__init__.py

@@ -0,0 +1,18 @@
+"""texpkg: TeX packages published as Python packages. The declaration types an author writes."""
+
+from .assets import Asset, Role
+from .declaration import Design, Distribution, Kind, Variant
+from .migration import DefaultChange, Migrated, Unresolved, migration
+
+__all__ = [
+    "Asset",
+    "DefaultChange",
+    "Design",
+    "Distribution",
+    "Kind",
+    "Migrated",
+    "Role",
+    "Unresolved",
+    "Variant",
+    "migration",
+]

texpkg/_internal/__init__.py

@@ -0,0 +1 @@
+"""The internal modules of the run time: not public API."""

texpkg/_internal/adopt.py

@@ -0,0 +1,119 @@
+"""Adopting a release: the stored state of a document becomes a valid tree of this release, or nothing does (V14, V22,
+V23, V29, V31, V32).
+
+Every migration across the `data` versions crossed runs, in the order the build's, the kind's, the consumer's; the
+result is validated whole; any unresolved item, any validation error and any stored field the model no longer has
+left aborts with the report.
+"""
+
+import copy
+from collections.abc import Iterator, Mapping, Sequence
+from typing import Any
+
+from texmodel.components import Node
+
+from ..declaration import Kind
+from ..errors import MigrationError
+from ..migration import DefaultChange, Migration, Unresolved
+from . import state
+from .envelope import Envelope
+from .history import problems, unplaced
+
+UNRESOLVED = (
+    "$unresolved"  # in the state a migration gets: what the earlier ones left, as `{"path", "reason", "value"}`
+)
+
+
+def _policy(changes: DefaultChange | Mapping[str, DefaultChange], path: str, key: str) -> DefaultChange:
+    """The policy for a default: the one named by the field's data path, else by `Class.field`, else `FOLLOW` (V23)."""
+    if isinstance(changes, DefaultChange):
+        return changes
+    return changes.get(path, changes.get(key, DefaultChange.FOLLOW))
+
+
+def _walk(node: dict[str, Any], path: str = "") -> Iterator[tuple[str, dict[str, Any]]]:
+    yield path, node
+    for i, child in enumerate(node.get("content", ())):
+        yield from _walk(child, f"{path}/content/{i}")
+
+
+def default_changes(
+    tree: dict[str, Any],
+    old: Mapping[str, Any],
+    new: Mapping[str, Any],
+    policy: DefaultChange | Mapping[str, DefaultChange],
+) -> list[dict[str, Any]]:
+    """Apply the consumer's policy to every value still marked as a default whose default this release changed (V22): a
+    value that follows needs nothing (the model fills the new default); one that is frozen keeps the old value and stops
+    being marked; one that asks is returned as unresolved."""
+    changed = {key for key in old.keys() & new.keys() if old[key] != new[key]}
+    asked: list[dict[str, Any]] = []
+    for path, node in _walk(tree):
+        for field in list(node.get(state.DEFAULTS, ())):
+            key = f"{node.get('type')}.{field}"
+            if key not in changed:
+                continue
+            action = _policy(policy, f"{path}/{field}", key)
+            if action is DefaultChange.FREEZE:
+                node[field] = old[key]
+                node[state.DEFAULTS].remove(field)
+            elif action is DefaultChange.ASK:
+                reason = f"the default of {key} changed from {old[key]!r} to {new[key]!r}"
+                asked.append(
+                    {"path": f"{path}/{field}", "reason": reason, "value": node.get(field), "boundary": "defaults"}
+                )
+        if not node.get(state.DEFAULTS, True):
+            del node[state.DEFAULTS]
+    return asked
+
+
+def _kind_migrations(kind: Kind, boundary: int, base_data: Mapping[int, int] | None) -> list[Migration]:
+    """The kind's own migrations for `boundary`. An exposed base kind's are numbered by the base: the ones for the base
+    versions that this package's `boundary` stands for run at it (P30)."""
+    if base_data is None:
+        return [m for m in kind.migrations if m.to == boundary]
+    low, high = base_data.get(boundary - 1, 0), base_data.get(boundary, 0)
+    return [m for m in kind.migrations if low < m.to <= high]
+
+
+def adopt(
+    *,
+    kind: Kind,
+    envelope: Envelope,
+    current: int,
+    age: int,
+    consumer: Sequence[Migration],
+    policy: DefaultChange | Mapping[str, DefaultChange],
+    saved_defaults: Mapping[str, Any] | None,
+    base_data: Mapping[int, int] | None = None,
+) -> Node:
+    """The tree of `kind` that `envelope` describes at `data` version `current`, or a `MigrationError` naming everything
+    that no migration placed. Nothing is written."""
+    tree = copy.deepcopy(envelope.tree)
+    left: list[dict[str, Any]] = []
+    if saved_defaults is not None:
+        left += default_changes(tree, saved_defaults, state.defaults_table(kind.model), policy)
+    if envelope.data < current - age:
+        for boundary in range(envelope.data + 1, current + 1):
+            label = f"{boundary - 1} -> {boundary}"
+            for migration in (*_kind_migrations(kind, boundary, base_data), *(m for m in consumer if m.to == boundary)):
+                tree[UNRESOLVED] = left
+                result = migration(tree)
+                tree = result.state
+                left = [*tree.pop(UNRESOLVED, []), *({**vars(u), "boundary": label} for u in result.unresolved)]
+    schema = state.schema(kind.model, "validation")
+    left += [{**p, "boundary": "validation"} for p in unplaced(tree, schema)]
+    left += [{**p, "boundary": "validation"} for p in problems(kind.model, state.given(tree), schema)]
+    if left:
+        items = tuple(
+            Unresolved(i["path"], i["reason"], i.get("value"), i.get("schema") or {}, i.get("boundary", ""))
+            for i in left
+        )
+        shown = "; ".join(f"{u.path or '/'} ({u.boundary}): {u.reason}" for u in items)
+        raise MigrationError(
+            f"{len(items)} unresolved: {shown}",
+            code="TP-M003",
+            unresolved=items,
+            hint="extend the process with a migration of your own: load(path, migrations=[...])",
+        )
+    return state.tree_from_state(kind.model, tree)

texpkg/_internal/classify.py

@@ -0,0 +1,190 @@
+"""Diffing two snapshots into bumps (V12, V13): Avro-style rules over schemas, names and signatures over the interface.
+
+In the run time because `changes(old, new)` diffs two shipped snapshots. Written to move into texmodel (V9, X5): it
+reads
+JSON Schema and plain dicts, and only the triples of texpkg.
+"""
+
+import dataclasses
+import enum
+from typing import Any
+
+from ..contracts import Pair, Triple
+
+
+@enum.unique
+class Level(enum.IntEnum):
+    """How much a change asks of a contract's consumers; the largest of a contract's changes decides its bump (V10)."""
+
+    NONE = 0
+    REVISION = 1  # implementation only: a description, a default, a doc
+    COMPATIBLE = 2  # an addition: old data and old callers still work
+    BREAKING = 3
+
+
+@dataclasses.dataclass(frozen=True)
+class Change:
+    level: Level
+    where: str  # `Class.field`, `kind expert`, `component Fact`
+    what: str
+
+
+_UPPER = ("maxLength", "maximum", "maxItems", "exclusiveMaximum")  # lowering one tightens it
+_LOWER = ("minLength", "minimum", "minItems", "exclusiveMinimum")  # raising one tightens it
+
+
+def _compare_property(where: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    out: list[Change] = []
+    for key in ("type", "$ref", "const", "format", "pattern"):
+        if old.get(key) != new.get(key):
+            out.append(Change(Level.BREAKING, where, f"{key} changed from {old.get(key)!r} to {new.get(key)!r}"))
+    if (gone := [v for v in old.get("enum", ()) if v not in new.get("enum", ())]) or ("enum" in old) != ("enum" in new):
+        out.append(Change(Level.BREAKING, where, f"values no longer allowed: {gone or 'any'}"))
+    elif added := [v for v in new.get("enum", ()) if v not in old.get("enum", ())]:
+        out.append(Change(Level.COMPATIBLE, where, f"values added: {added}"))
+    for key in _UPPER + _LOWER:
+        was, now = old.get(key), new.get(key)
+        if was == now:
+            continue
+        tighter = now is not None and (was is None or (now < was if key in _UPPER else now > was))
+        out.append(Change(Level.BREAKING if tighter else Level.COMPATIBLE, where, f"{key} {was} -> {now}"))
+    if old.get("items") != new.get("items") and "items" in old:
+        out += _compare_items(where, old["items"], new.get("items", {}))
+    for key in ("default", "description", "title"):
+        if old.get(key) != new.get(key):
+            out.append(Change(Level.REVISION, where, f"{key} changed"))
+    return out
+
+
+def _compare_items(where: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    """The element schema of a list: a branch of a union that went is breaking, one that came is compatible."""
+
+    def refs(items: dict[str, Any]) -> set[str]:
+        branches = items.get("oneOf") or [items]
+        return {b.get("$ref", b.get("type", "")) for b in branches}
+
+    gone, added = refs(old) - refs(new), refs(new) - refs(old)
+    out = [Change(Level.BREAKING, where, f"{g} is no longer allowed here") for g in sorted(gone)]
+    out += [Change(Level.COMPATIBLE, where, f"{a} is allowed here") for a in sorted(added)]
+    return out or ([] if old == new else _compare_property(where, old, new))
+
+
+def _classes(schema: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    out = {str(schema.get("title")): schema}
+    out |= {str(node.get("title", name)): node for name, node in schema.get("$defs", {}).items()}
+    return out
+
+
+def schema_changes(old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    """What changed in the data a kind accepts (the input schema): the changes, each with its level (V12)."""
+    out: list[Change] = []
+    was, now = _classes(old), _classes(new)
+    for title in sorted(was.keys() - now.keys()):
+        out.append(Change(Level.BREAKING, title, "no longer part of the kind"))
+    for title in sorted(now.keys() - was.keys()):
+        out.append(Change(Level.COMPATIBLE, title, "added to the kind"))
+    for title in sorted(was.keys() & now.keys()):
+        before, after = was[title].get("properties", {}), now[title].get("properties", {})
+        renamed = {p.get("x-renamed-from"): name for name, p in after.items() if p.get("x-renamed-from")}
+        for name in before:
+            if name in after:
+                out += _compare_property(f"{title}.{name}", before[name], after[name])
+            elif name in renamed:
+                out.append(
+                    Change(Level.COMPATIBLE, f"{title}.{name}", f"renamed {renamed[name]} (old name still read)")
+                )
+            else:
+                out.append(Change(Level.BREAKING, f"{title}.{name}", "removed"))
+        now_required, was_required = set(now[title].get("required", ())), set(was[title].get("required", ()))
+        for name in sorted((now_required - was_required) & before.keys() & after.keys()):
+            out.append(Change(Level.BREAKING, f"{title}.{name}", "became required"))
+        for name in sorted(after.keys() - before.keys() - set(renamed.values())):
+            level = Level.BREAKING if name in now_required else Level.COMPATIBLE
+            out.append(Change(level, f"{title}.{name}", "added" + (" and required" if name in now_required else "")))
+    return out
+
+
+def interface_changes(old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    """What changed in the public names and their signatures, and in the kinds and variants (V12)."""
+    out: list[Change] = []
+    for section, label in (("components", "component"), ("kinds", "kind")):
+        was, now = old.get(section, {}), new.get(section, {})
+        out += [Change(Level.BREAKING, f"{label} {n}", "removed") for n in sorted(was.keys() - now.keys())]
+        out += [Change(Level.COMPATIBLE, f"{label} {n}", "added") for n in sorted(now.keys() - was.keys())]
+        for name in sorted(was.keys() & now.keys()):
+            out += _compare_entry(f"{label} {name}", was[name], now[name])
+    return out
+
+
+def _compare_entry(where: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    out: list[Change] = []
+    for key in sorted(old.keys() | new.keys()):
+        if old.get(key) == new.get(key):
+            continue
+        if key == "variants":
+            gone, added = set(old.get(key, ())) - set(new.get(key, ())), set(new.get(key, ())) - set(old.get(key, ()))
+            out += [Change(Level.BREAKING, where, f"variant {v} removed") for v in sorted(gone)]
+            out += [Change(Level.COMPATIBLE, where, f"variant {v} added") for v in sorted(added)]
+        elif key == "doc":
+            out.append(Change(Level.REVISION, where, "documentation changed"))
+        elif key == "signature":
+            added = new.get(key, [])[len(old.get(key, [])) :]
+            keeps = new.get(key, [])[: len(old.get(key, []))] == old.get(key, [])
+            if keeps and all(arg[2] for arg in added):  # trailing optional arguments: old calls still work
+                out.append(Change(Level.COMPATIBLE, where, f"optional arguments added: {[a[0] for a in added]}"))
+            else:
+                out.append(Change(Level.BREAKING, where, "signature changed"))
+        else:
+            out.append(Change(Level.BREAKING, where, f"{key} changed from {old.get(key)!r} to {new.get(key)!r}"))
+    return out
+
+
+def worst(changes: list[Change]) -> Level:
+    return max((c.level for c in changes), default=Level.NONE)
+
+
+def bump(previous: Triple, level: Level) -> Triple:
+    """libtool's rules (V10): none keeps it, a revision adds one, an addition raises `current` and `age`, a break
+    resets them."""
+    match level:
+        case Level.NONE:
+            return previous
+        case Level.REVISION:
+            return Triple(previous.current, previous.revision + 1, previous.age)
+        case Level.COMPATIBLE:
+            return Triple(previous.current + 1, 0, previous.age + 1)
+        case Level.BREAKING:
+            return Triple(previous.current + 1, 0, 0)
+
+
+def bump_output(previous: Pair, change: str) -> Pair:
+    """`output` has no age: `current` when the appearance changed, `revision` when only bytes did (V10). `change` is the
+    author's statement; an empty one means nothing changed."""
+    match change:
+        case "current":
+            return Pair(previous.current + 1, 0)
+        case "revision":
+            return Pair(previous.current, previous.revision + 1)
+        case _:
+            return previous
+
+
+Version = tuple[int, int, int]
+
+
+def parse_version(text: str) -> Version:
+    major, minor, patch = (int(p) for p in text.split(".")[:3])
+    return major, minor, patch
+
+
+def required_release(previous: str, data: Level, interface: Level, output_changed: bool) -> str:
+    """The smallest release number that does not understate the contracts (V13): a break is major, any other change
+    minor, no contract change a patch; each one place lower before 1.0."""
+    major, minor, patch = parse_version(previous)
+    breaking = Level.BREAKING in (data, interface)
+    changed = bool(data or interface) or output_changed
+    if major == 0:
+        return f"0.{minor + 1}.0" if breaking else f"0.{minor}.{patch + 1}"
+    if breaking:
+        return f"{major + 1}.0.0"
+    return f"{major}.{minor + 1}.0" if changed else f"{major}.{minor}.{patch + 1}"

texpkg/_internal/directory.py

@@ -0,0 +1,48 @@
+"""The document directory (P27, D5): one visible `_texpkg/` folder beside the `.tex`, the payload and the consumer's own
+files. Everything here takes the directory and text; nothing knows what a kind is."""
+
+import pathlib
+import shutil
+from collections.abc import Mapping
+
+DIR = "_texpkg"
+STATE = f"{DIR}/state.json"  # the user's state (D1)
+TEMPLATE = f"{DIR}/template.json"  # the package as it was when the document was saved (D1, D6)
+HISTORY = 3  # the last saves kept (D2)
+
+
+def plan_file(variant: str | None) -> str:
+    """The saved plan of the `.tex` of `variant` (D7)."""
+    return f"{DIR}/plan.json" if variant is None else f"{DIR}/plan-{variant}.json"
+
+
+def read(root: pathlib.Path, rel: str) -> str | None:
+    path = root / rel
+    return path.read_text(encoding="utf-8") if path.is_file() else None
+
+
+def differing(root: pathlib.Path, files: Mapping[str, str]) -> dict[str, str]:
+    """The files whose text on disk is not `files`' (absent counts): content, never time (A4)."""
+    return {rel: text for rel, text in files.items() if read(root, rel) != text}
+
+
+def write(root: pathlib.Path, files: Mapping[str, str]) -> None:
+    for rel, text in files.items():
+        (root / rel).parent.mkdir(parents=True, exist_ok=True)
+        (root / rel).write_text(text, encoding="utf-8")
+
+
+def rotate_history(root: pathlib.Path) -> None:
+    """Keep the pair of states on disk as `history/1`, the earlier ones one further, and drop what is beyond `HISTORY`
+    (D2, D3). Nothing happens when there is no pair yet."""
+    pair = [rel for rel in (STATE, TEMPLATE) if (root / rel).is_file()]
+    if not pair:
+        return
+    history = root / DIR / "history"
+    shutil.rmtree(history / str(HISTORY), ignore_errors=True)
+    for n in range(HISTORY - 1, 0, -1):
+        if (history / str(n)).is_dir():
+            (history / str(n)).rename(history / str(n + 1))
+    (history / "1").mkdir(parents=True)
+    for rel in pair:
+        shutil.copyfile(root / rel, history / "1" / pathlib.PurePosixPath(rel).name)

texpkg/_internal/envelope.py

@@ -0,0 +1,37 @@
+"""The envelope of a stored document: `{package, kind, data, tree}` (K3). It names the package and kind the tree belongs
+to and the `data` version it was written for (V14)."""
+
+import dataclasses
+import json
+from typing import Any
+
+from ..errors import NotADocumentError
+
+
+def dumps(value: object) -> str:
+    """The text of a state file: stable, readable, one trailing newline."""
+    return json.dumps(value, indent=2, ensure_ascii=False) + "\n"
+
+
+@dataclasses.dataclass(frozen=True)
+class Envelope:
+    package: str
+    kind: str
+    data: int
+    tree: dict[str, Any]
+
+    def to_text(self) -> str:
+        return dumps({"package": self.package, "kind": self.kind, "data": self.data, "tree": self.tree})
+
+    @classmethod
+    def parse(cls, text: str, where: str) -> "Envelope":
+        try:
+            found = json.loads(text)
+            return cls(str(found["package"]), str(found["kind"]), int(found["data"]), dict(found["tree"]))
+        except (ValueError, KeyError, TypeError) as exc:
+            raise NotADocumentError(
+                f"{where}: not a document state ({exc!r})",
+                code="TP-D001",
+                path=where,
+                hint="it is written by a kind's create and save",
+            ) from exc

texpkg/_internal/export.py

@@ -0,0 +1,49 @@
+"""The plain-LaTeX export (E1): what a project that does not use Python needs, written for each kind.
+
+A kind's template is its example rendered with the kind's settings (L8), so locks reach a plain-LaTeX user; its
+README is generated from the kind's classes.
+"""
+
+from collections.abc import Sequence
+
+from texmodel.components import Command, Environment, control_name
+from texmodel.package import setting_line
+
+from ..declaration import Distribution, Kind, reachable
+
+
+def template_name(kind: Kind) -> str:
+    return f"{kind.name}-template.tex"
+
+
+def readme_name(kind: Kind) -> str:
+    return f"README-{kind.name}.md"
+
+
+def _call(cls: type[Command] | type[Environment]) -> str:
+    """The TeX shape of a component: `\\abFact[accent]{text}` or `\\begin{abCard}` ... `\\end{abCard}`."""
+    optional_first = [a for a in cls.__tm_args__ if a.optional and not a.placed]
+    ordered = [*optional_first, *(a for a in cls.__tm_args__ if a not in optional_first)]
+    args = "".join(f"{a.delimiter.open}{a.name}{a.delimiter.close}" for a in ordered)
+    name = control_name(cls)
+    return f"\\begin{{{name}}}{args} ... \\end{{{name}}}" if issubclass(cls, Environment) else f"\\{name}{args}"
+
+
+def readme(dist: Distribution, kind: Kind, release: str, files: Sequence[str]) -> str:
+    """The README of `kind`: how to compile its template, what the template is written with, and its commands."""
+    base = dist.base_kind(kind)
+    model = base.model if base else kind.model
+    commands = "\n".join(f"- `{_call(c)}`: {c.__tm_doc__}" for c in reachable(model))
+    settings = "\n".join(f"- `{setting_line(v)}`" for v in (*(base.presets if base else ()), *kind.presets))
+    variants = ", ".join(f"`{v.name}`" for v in kind.variants) or "none"
+    listing = "\n".join(f"- `{name}`" for name in files)
+    return (
+        f"# {kind.name}: {dist.name} {release}\n\n"
+        f"{kind.model.__tm_doc__}\n\n"
+        f"Compile the template with LuaLaTeX from this directory:\n\n"
+        f"    latexmk -lualatex {template_name(kind)}\n\n"
+        f"## Files\n\n{listing}\n\n"
+        f"## The template is written with\n\n{settings or 'no settings of its own'}\n\n"
+        f"Variants of the kind (the Python module writes them; the template is the kind's own): {variants}.\n\n"
+        f"## Commands\n\n{commands}\n"
+    )

texpkg/_internal/handedits.py

@@ -0,0 +1,33 @@
+"""Hand edits: a `.tex` against the plan of what was last written (D7-D9).
+
+The plan says which node wrote each line, so an edit is found by path even when the model has moved on.
+"""
+
+import pathlib
+import re
+from collections.abc import Sequence
+
+from texmodel.plan import Edit, Plan
+
+from . import directory
+
+_NODE = re.compile(r"[A-Z][A-Za-z]*\[(\d+)\]")  # a component's name: a capital, then letters (TM-M001)
+
+
+def data_path(plan_path: str) -> str:
+    """The data path of a plan path: `Deck[0]/Card[1]/Title[0]` is `/content/1/content/0`, the root being the document.
+    A line that no node wrote (`header`, `preamble.before_package[0]`, `settings[2]`) keeps its plan path."""
+    nodes = [_NODE.fullmatch(part) for part in plan_path.split("/")]
+    if not all(nodes):
+        return plan_path
+    return "".join(f"/content/{node[1]}" for node in nodes[1:] if node)
+
+
+def edits(root: pathlib.Path, files: Sequence[tuple[str | None, str]]) -> list[tuple[str, Edit]]:
+    """For each `(variant, file name)` that exists beside a saved plan: the file and its edits against that plan."""
+    found: list[tuple[str, Edit]] = []
+    for variant, name in files:
+        text, saved = directory.read(root, name), directory.read(root, directory.plan_file(variant))
+        if text is not None and saved is not None:
+            found += [(name, edit) for edit in Plan.from_json(saved).edits(text)]
+    return found

texpkg/_internal/history.py

@@ -0,0 +1,91 @@
+"""One model's history: what a stored state needs to become a valid tree of the current model (V8, V9, V28, V30).
+
+Written to move into texmodel (N5): it knows models, schemas and paths, not packages, kinds or releases. A problem is a
+plain dict `{"path", "reason", "value", "schema"}` with the path a data path (`/content/1/content/0/text`).
+"""
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+import pydantic
+from texmodel.components import Command, Environment
+
+type Problem = dict[str, Any]
+
+_NODE = re.compile(r"([A-Z][A-Za-z]*)(?:\[(\d+)\])?")
+
+
+def pointer(loc: Sequence[str | int]) -> str:
+    """The data path of a pydantic error location: a tagged child's class name follows its index and is not data."""
+    out: list[str] = []
+    after_index = False
+    for part in loc:
+        if after_index and isinstance(part, str):
+            after_index = False
+            continue
+        after_index = isinstance(part, int)
+        out.append(str(part))
+    return "".join(f"/{part}" for part in out)
+
+
+def violation_pointer(path: str) -> str:
+    """The data path of a grammar violation's path (`Deck/Card[1]` is `/content/1`)."""
+    parts = path.split("/")
+    return "".join(f"/content/{m[2]}" for part in parts[1:] if (m := _NODE.fullmatch(part)) and m[2] is not None)
+
+
+def schema_at(schema: Mapping[str, Any], loc: Sequence[str | int]) -> dict[str, Any]:
+    """The schema of the field an error location names: `$defs[<class>].properties[<field>]`, `{}` if there is none."""
+    classes = [str(p) for i, p in enumerate(loc) if isinstance(p, str) and i > 0 and isinstance(loc[i - 1], int)]
+    owner = schema.get("$defs", {}).get(classes[-1]) if classes else schema
+    field = loc[-1]
+    found = (owner or {}).get("properties", {}).get(field) if isinstance(field, str) and field != "content" else None
+    return cast("dict[str, Any]", found) if isinstance(found, dict) else {}
+
+
+def problems(
+    model: type[Command] | type[Environment], data: dict[str, Any], schema: Mapping[str, Any]
+) -> list[Problem]:
+    """Everything that stops `data` from being a valid tree of `model`: pydantic's errors with their constraint,
+    then the grammar's violations (V30)."""
+    try:
+        tree = model.model_validate(data)
+    except pydantic.ValidationError as exc:
+        return [
+            {
+                "path": pointer(e["loc"]),
+                "reason": e["msg"],
+                "value": e.get("input"),
+                "schema": schema_at(schema, e["loc"]),
+            }
+            for e in exc.errors(include_url=False)
+        ]
+    return [
+        {"path": violation_pointer(v.path), "reason": v.message, "value": None, "schema": {}} for v in tree.violations()
+    ]
+
+
+def unplaced(state: Mapping[str, Any], schema: Mapping[str, Any], path: str = "") -> list[Problem]:
+    """The fields of a stored state that the model has no field for, which loading it would drop without a word: a
+    migration places each one or removes it on purpose. A node whose class the schema does not know is left to the
+    validation, which names it."""
+    fields = {schema.get("title"): schema.get("properties", {})} | {
+        name: node.get("properties", {}) for name, node in schema.get("$defs", {}).items()
+    }
+    known = fields.get(state.get("type"))
+    if known is None:
+        return []
+    out: list[Problem] = [
+        {
+            "path": f"{path}/{key}",
+            "reason": f"the model has no field {key!r}: a migration has to place it or remove it on purpose",
+            "value": value,
+            "schema": {},
+        }
+        for key, value in state.items()
+        if key not in known and key != "$defaults"
+    ]
+    for i, child in enumerate(state.get("content", ())):
+        out += unplaced(child, schema, f"{path}/content/{i}")
+    return out