cv-tools-cli 2.0.0__py3-none-any.whl

cv_tools/v1.py

@@ -0,0 +1,484 @@
+"""v1 detection and the v1 to v2 conversion, used for rendering and by ``cv-tools migrate``."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from .loader import Source, YamlPath, describe
+from .markup import Latex, escape_url, to_latex, v1_decode
+from .model import ContactItem
+from .render import latex
+
+DEPRECATION = (
+    "cv-tools: {file} uses the v1 format, which is deprecated and will be removed "
+    "in a future release. Run 'cv-tools migrate {file}' to convert it."
+)
+
+CV_DATE_ITEM = "Curriculum Vitae, {date}"
+# v1 printed the address separator (\\ inside \address, "$|$\ ") before the
+# date item only; "| " prints the same.
+CV_DATE_AFTER_SEPARATOR = "| " + CV_DATE_ITEM
+
+_SOCIALS = {"orcid_id": "orcid", "linkedin": "linkedin", "github": "github", "twitter": "twitter"}
+_ICONS = set(_SOCIALS.values())  # attach to the previous item with a space
+
+_KNOWN_KEYS = {
+    "document": {"version", "heading", "subheading", "sections"},
+    "heading": {"name"},
+    "subheading-group": {"type", "content"},
+    "links": {"name", "highlight", "show_below"},
+    "socials": {"type", "url", "show_below"},
+    "education": {"type", "content"},
+    "education-entry": {
+        "university", "location", "dates", "degree", "honors", "thesis_title", "supervisor", "bullets",
+    },
+    "experience": {"type", "content"},
+    "experience-group": {"name", "entity"},
+    "experience-entry": {
+        "organization", "dates", "position", "supervisor", "department", "location", "responsibilities",
+    },
+    "bullets": {"type", "title", "description", "content"},
+    "bullets-entry": {"item", "subitems"},
+    "skills": {"type", "content"},
+    "skills-entry": {"name", "data"},
+    "talks": {"type", "title", "content"},
+    "talks-entry": {"name", "month", "year"},
+    "publications": {"type", "title", "bibfile"},
+    "newpage": {"type"},
+}
+
+
+def version_of(value: Any) -> int | None:
+    """1 or 2 for a numeric ``version`` value that names a format, else None."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return int(value) if value in (1, 2) else None
+
+
+def detect(src: Source) -> str:
+    """Return ``"v1"`` or ``"v2"``, or raise :class:`CVError`."""
+    data = src.data
+    if not isinstance(data, dict):
+        raise src.error("expected a mapping at the top level of the CV file")
+    if "version" in data:
+        value = data["version"]
+        version = version_of(value)
+        if version is not None:
+            return f"v{version}"
+        if isinstance(value, str) and version_of(_number(value)) is not None:
+            raise src.error(f"unsupported version {value!r}: the version is a number; "
+                            f"write 'version: {value.strip()}' without quotes", ("version",))
+        raise src.error(f"unsupported version {value!r}: expected 'version: 2' "
+                        "(or 'version: 1' for the deprecated v1 format)", ("version",))
+    sections = data.get("sections")
+    typed = isinstance(sections, list) and any(isinstance(s, dict) and "type" in s for s in sections)
+    if "heading" in data or "subheading" in data or typed:
+        return "v1"
+    raise src.error(
+        "cannot tell the CV format: expected 'version: 2' at the top of a v2 file "
+        "(v1 files have 'heading', 'subheading' or sections with 'type')"
+    )
+
+
+def _number(text: str) -> float | None:
+    try:
+        return float(text)
+    except ValueError:
+        return None
+
+
+def unescape(text: str) -> str:
+    """Turn the simple v1 escapes (``\\% \\& \\# \\_ \\$``) into plain characters."""
+    return re.sub(r"\\([%&#_$])", r"\1", text)
+
+
+@dataclass
+class Conversion:
+    data: dict
+    warnings: list[str] = field(default_factory=list)
+    # v2 path -> v1 path, to carry comments over.
+    origins: dict[YamlPath, YamlPath] = field(default_factory=dict)
+
+
+def convert(src: Source, clean: bool = False) -> Conversion:
+    return _Converter(src, clean).run()
+
+
+class _Converter:
+    def __init__(self, src: Source, clean: bool):
+        self.src = src
+        self.clean = clean
+        self.out = Conversion({})
+        self.warnings: list[tuple[tuple[int, int], str]] = []
+        self.highlight: list[str] = []  # v1 bolds authors equal to the raw heading name
+
+    def warn(self, path: YamlPath, message: str, key: bool = False) -> None:
+        error = self.src.error(message, path, key)
+        self.warnings.append(((error.line or 0, error.col or 0), error.format("warning")))
+
+    def origin(self, v2: YamlPath, v1: YamlPath) -> None:
+        self.out.origins[v2] = v1
+
+    def mapping(self, value: Any, path: YamlPath, kind: str) -> dict:
+        if not isinstance(value, dict):
+            raise self.src.error(f"expected a mapping, got {describe(value)}", path)
+        for key in value:
+            if key not in _KNOWN_KEYS[kind]:
+                self.warn(path + (key,), f"v1 ignores the field '{key}'; it is dropped", key=True)
+        return value
+
+    def items(self, value: Any, path: YamlPath) -> list[tuple[int, Any]]:
+        # Missing and null mean empty, as in v1's Jinja loops.
+        if value is None:
+            return []
+        if not isinstance(value, list):
+            raise self.src.error(f"expected a list, got {describe(value)}", path)
+        out = []
+        for i, item in enumerate(value):
+            if item is None:
+                self.warn(path + (i,), "empty list item (null); it is dropped")
+            else:
+                out.append((i, item))
+        return out
+
+    def decode(self, value: Any, path: YamlPath) -> str:
+        if isinstance(value, str):
+            return v1_decode(value)
+        if isinstance(value, (int, float)):  # includes bool, printed as True/False by Jinja
+            return str(value)
+        raise self.src.error(f"expected text, got {describe(value)}", path)
+
+    def text(
+        self,
+        value: Any,
+        path: YamlPath,
+        wrap: tuple[str, str] = ("", ""),
+        latex_wrap: tuple[str, str] = ("", ""),
+        key: Callable[[Any], Any] = to_latex,
+    ) -> Any:
+        latex = latex_wrap[0] + self.decode(value, path) + latex_wrap[1]
+        if self.clean:
+            if isinstance(value, str):
+                candidate: Any = wrap[0] + unescape(value) + wrap[1]
+            elif wrap == ("", "") and not isinstance(value, bool):
+                candidate = value
+            else:
+                candidate = wrap[0] + str(value) + wrap[1]
+            if key(candidate) == key(Latex(latex)):
+                return candidate
+        return {"latex": latex}
+
+    def raw(self, latex: str, candidate: Any, key: Callable[[Any], Any] = to_latex) -> Any:
+        if self.clean and key(candidate) == key(Latex(latex)):
+            return candidate
+        return {"latex": latex}
+
+    def url(self, value: Any, path: YamlPath) -> Any:
+        latex = self.decode(value, path) if value is not None else ""
+        candidate = value if isinstance(value, str) else latex
+        if self.clean and escape_url(candidate) == latex:
+            return candidate
+        return {"latex": latex}
+
+    def run(self) -> Conversion:
+        data = self.mapping(self.src.data, (), "document")
+        doc = self.out.data
+        doc["version"] = 2
+
+        heading = data.get("heading")
+        raw_name = None
+        if heading is not None:
+            raw_name = self.mapping(heading, ("heading",), "heading").get("name")
+        doc["name"] = self.text(raw_name, ("heading", "name")) if raw_name is not None else ""
+        self.origin(("name",), ("heading", "name"))
+        if isinstance(raw_name, str) and raw_name:
+            self.highlight = [raw_name]  # compared before decoding, as v1 did
+
+        if data.get("subheading"):
+            doc["contact"] = self.contact(data["subheading"])
+            self.origin(("contact",), ("subheading",))
+
+        sections: list = []
+        for i, section in self.items(data.get("sections"), ("sections",)):
+            sections.extend(self.section(section, ("sections", i), len(sections)))
+        doc["sections"] = sections
+        self.origin(("sections",), ("sections",))
+        self.out.warnings = [text for _, text in sorted(self.warnings, key=lambda w: w[0])]
+        return self.out
+
+    def contact(self, subheading: Any) -> list:
+        lines: dict[bool, list[tuple[str, Any, str]]] = {False: [], True: []}
+        for g, group in self.items(subheading, ("subheading",)):
+            gpath = ("subheading", g)
+            group = self.mapping(group, gpath, "subheading-group")
+            gtype = group.get("type")
+            for e, entity in self.items(group.get("content"), gpath + ("content",)):
+                epath = gpath + ("content", e)
+                if gtype not in ("links", "socials"):
+                    self.warn(epath, f"v1 does not print subheading groups of type {gtype!r}; the item is dropped")
+                    continue
+                entity = self.mapping(entity, epath, gtype)
+                below = entity.get("show_below")
+                if not isinstance(below, bool):
+                    self.warn(
+                        epath,
+                        "v1 does not print subheading items without show_below: true or false; the item is dropped",
+                    )
+                    continue
+                item = self.contact_item(gtype, entity, epath)
+                if item is not None:
+                    lines[below].append(item)
+
+        line1 = [{kind: value} if kind != "text" else value for kind, value, _ in lines[False]]
+        if any(kind not in _ICONS for kind, _, _ in lines[False][1:]):
+            line1 = {"items": line1, "separator": " "}  # v1 joins a line with spaces
+
+        below = lines[True]
+        line2: Any = [{kind: value} if kind != "text" else value for kind, value, _ in below]
+        if any(kind not in _ICONS for kind, _, _ in below[1:]):
+            # v1 joins these items with spaces and puts the address separator
+            # only before the date item.
+            line2 = {"items": line2 + [CV_DATE_AFTER_SEPARATOR], "separator": " "}
+        else:
+            # Without items before it, v1 starts the date line with a space,
+            # which moves the centred line by half a space.
+            line2.append(CV_DATE_ITEM if below else " " + CV_DATE_ITEM)
+        return [line1, line2]
+
+    def contact_item(self, gtype: str, entity: dict, path: YamlPath) -> tuple[str, Any, str] | None:
+        if gtype == "links":
+            name = entity.get("name")
+            if entity.get("highlight") is True:
+                kind, value = "url", self.url(name, path + ("name",))
+            elif name is None:
+                kind, value = "text", ""
+            else:
+                kind, value = "text", self.text(name, path + ("name",), key=_contact_key)
+                if isinstance(value, str) and "\n" in value:
+                    value = {"latex": self.decode(name, path + ("name",))}  # v2 contact text is single-line
+        else:
+            social = entity.get("type")
+            if social not in _SOCIALS:
+                self.warn(path + ("type",), f"v1 does not print socials of type {social!r}; the item is dropped")
+                return None
+            kind, value = _SOCIALS[social], self.url(entity.get("url"), path + ("url",))
+        model_value = Latex(value["latex"]) if isinstance(value, dict) else value
+        return (kind, value, latex.contact_item(ContactItem(kind, model_value), latex.AUTO_DATE))
+
+    def section(self, section: Any, path: YamlPath, index: int) -> list:
+        if not isinstance(section, dict):
+            raise self.src.error(f"expected a section mapping, got {describe(section)}", path)
+        stype = section.get("type")
+        if stype not in _SECTION_TYPES:
+            self.warn(path, f"v1 does not print sections of type {stype!r}; the section is dropped")
+            return []
+        self.mapping(section, path, stype)
+        out = getattr(self, "section_" + stype)(section, path, index)
+        if out and isinstance(out[0], dict):
+            self.origin(("sections", index, "layout"), path + ("type",))
+        return out
+
+    def title(self, section: dict, path: YamlPath, v2: YamlPath) -> Any:
+        self.origin(v2 + ("title",), path + ("title",))
+        value = section.get("title")
+        return self.text(value, path + ("title",)) if value is not None else ""
+
+    def entries(self, section: dict, path: YamlPath, kind: str):
+        for n, (i, entry) in enumerate(self.items(section.get("content"), path + ("content",))):
+            epath = path + ("content", i)
+            yield n, epath, self.mapping(entry, epath, kind)
+
+    def field(self, entry: dict, name: str, path: YamlPath, out: dict, v2name: str, v2: YamlPath, **kw) -> None:
+        if entry.get(name) is not None:
+            out[v2name] = self.text(entry[name], path + (name,), **kw)
+            self.origin(v2 + (v2name,), path + (name,))
+
+    def bullets(self, value: Any, path: YamlPath) -> list:
+        return [self.text(b, path + (i,)) for i, b in self.items(value, path)]
+
+    def section_education(self, section: dict, path: YamlPath, index: int) -> list:
+        v2 = ("sections", index)
+        self.origin(v2, path)
+        entries = []
+        for i, epath, edu in self.entries(section, path, "education-entry"):
+            e2 = v2 + ("entries", i)
+            self.origin(e2, epath)
+            entry = {"title": ""}
+            self.field(edu, "university", epath, entry, "title", e2)
+            # v1 always prints ", location", even when the location is missing.
+            entry["location"] = ""
+            self.field(edu, "location", epath, entry, "location", e2)
+            self.field(edu, "dates", epath, entry, "date", e2)
+            self.field(edu, "degree", epath, entry, "subtitle", e2)
+            self.field(edu, "honors", epath, entry, "note", e2)
+            details = []
+            if edu.get("thesis_title"):
+                details.append(
+                    self.text(
+                        edu["thesis_title"], epath + ("thesis_title",),
+                        wrap=("Thesis Title: *", "*"), latex_wrap=("Thesis Title: \\textit{", "}"),
+                    )
+                )
+            if edu.get("supervisor"):
+                details.append(
+                    self.text(
+                        edu["supervisor"], epath + ("supervisor",),
+                        wrap=("Supervisor: ", ""), latex_wrap=("Supervisor: ", ""),
+                    )
+                )
+            if details:
+                entry["details"] = details
+            if edu.get("bullets"):
+                entry["bullets"] = self.bullets(edu["bullets"], epath + ("bullets",))
+                self.origin(e2 + ("bullets",), epath + ("bullets",))
+            entries.append(entry)
+        return [{"title": "Education", "layout": "entries-inline", "entries": entries}]
+
+    def section_experience(self, section: dict, path: YamlPath, index: int) -> list:
+        out = []
+        for g, gpath, group in self.entries(section, path, "experience-group"):
+            v2 = ("sections", index + g)
+            self.origin(v2, gpath)
+            title = self.text(group["name"], gpath + ("name",)) if group.get("name") is not None else ""
+            self.origin(v2 + ("title",), gpath + ("name",))
+            entries = []
+            for n, (i, entity) in enumerate(self.items(group.get("entity"), gpath + ("entity",))):
+                epath = gpath + ("entity", i)
+                e2 = v2 + ("entries", n)
+                self.origin(e2, epath)
+                exp = self.mapping(entity, epath, "experience-entry")
+                entry = {"title": ""}
+                self.field(exp, "organization", epath, entry, "title", e2)
+                self.field(exp, "dates", epath, entry, "date", e2)
+                self.field(exp, "position", epath, entry, "subtitle", e2)
+                if exp.get("supervisor"):
+                    entry["note"] = self.text(
+                        exp["supervisor"], epath + ("supervisor",),
+                        wrap=("Supervisor: ", ""), latex_wrap=("Supervisor: ", ""),
+                    )
+                    self.origin(e2 + ("note",), epath + ("supervisor",))
+                # v1 prints "department\\location" as the fifth rSubsection argument.
+                details = []
+                if exp.get("department"):
+                    details.append(self.text(exp["department"], epath + ("department",)))
+                location = exp.get("location")
+                if location is not None and location != "":
+                    details.append(self.text(location, epath + ("location",)))
+                elif details:
+                    details.append("")  # v1 leaves a trailing line break
+                if details:
+                    entry["details"] = details
+                if exp.get("responsibilities"):
+                    entry["bullets"] = self.bullets(exp["responsibilities"], epath + ("responsibilities",))
+                    self.origin(e2 + ("bullets",), epath + ("responsibilities",))
+                entries.append(entry)
+            out.append({"title": title, "layout": "entries", "entries": entries})
+        return out
+
+    def section_bullets(self, section: dict, path: YamlPath, index: int) -> list:
+        v2 = ("sections", index)
+        self.origin(v2, path)
+        out: dict = {"title": self.title(section, path, v2), "layout": "list"}
+        if section.get("description"):
+            out["description"] = self.text(section["description"], path + ("description",))
+            self.origin(v2 + ("description",), path + ("description",))
+        entries = []
+        for i, epath, item in self.entries(section, path, "bullets-entry"):
+            self.origin(v2 + ("entries", i), epath)
+            text = self.text(item["item"], epath + ("item",)) if item.get("item") is not None else ""
+            if item.get("subitems"):
+                entries.append({"text": text, "bullets": self.bullets(item["subitems"], epath + ("subitems",))})
+                self.origin(v2 + ("entries", i, "bullets"), epath + ("subitems",))
+            else:
+                entries.append(text)
+        out["entries"] = entries
+        return [out]
+
+    def section_skills(self, section: dict, path: YamlPath, index: int) -> list:
+        v2 = ("sections", index)
+        self.origin(v2, path)
+        entries = []
+        for i, epath, skill in self.entries(section, path, "skills-entry"):
+            e2 = v2 + ("entries", i)
+            self.origin(e2, epath)
+            entry = {"title": "", "text": ""}
+            self.field(skill, "name", epath, entry, "title", e2)
+            self.field(skill, "data", epath, entry, "text", e2)
+            entries.append(entry)
+        return [{"title": "Skills", "layout": "pairs", "entries": entries}]
+
+    def section_talks(self, section: dict, path: YamlPath, index: int) -> list:
+        v2 = ("sections", index)
+        self.origin(v2, path)
+        out = {"title": self.title(section, path, v2), "layout": "dated"}
+        entries = []
+        for i, epath, talk in self.entries(section, path, "talks-entry"):
+            e2 = v2 + ("entries", i)
+            self.origin(e2, epath)
+            entry: dict = {}
+            date = self.talk_date(talk, epath)
+            if date is not None:
+                entry["date"] = date
+                self.origin(e2 + ("date",), epath + ("month",))
+            entry["text"] = ""
+            # v2 prints a line break in a dated cell as \newline, where v1 wrote \\.
+            self.field(talk, "name", epath, entry, "text", e2, key=latex.dated_text)
+            entries.append(entry)
+        out["entries"] = entries
+        return [out]
+
+    def talk_date(self, talk: dict, path: YamlPath) -> Any:
+        month, year = talk.get("month"), talk.get("year")
+        if month is None and year is None:
+            return None
+        m = self.decode(month, path + ("month",)) if month is not None else ""
+        y = self.decode(year, path + ("year",)) if year is not None else ""
+        latex = f"{m} {y}"
+        if _dated_date(Latex(latex)) != (m, y):
+            latex = f"{m} {{{y}}}"  # keep the year in one column; braces print nothing
+        if month is None:
+            candidate = unescape(year) if isinstance(year, str) else str(year) if isinstance(year, bool) else year
+        else:
+            parts = [unescape(v) if isinstance(v, str) else str(v) for v in (month, "" if year is None else year)]
+            candidate = " ".join(parts)
+        return self.raw(latex, candidate, key=_dated_date)
+
+    def section_publications(self, section: dict, path: YamlPath, index: int) -> list:
+        v2 = ("sections", index)
+        self.origin(v2, path)
+        bibfile = section.get("bibfile")
+        if not isinstance(bibfile, str):
+            raise self.src.error(
+                f"section '{section.get('title', 'Untitled')}' is missing a 'bibfile' entry", path
+            )
+        out = {"title": self.title(section, path, v2), "layout": "publications", "bib": bibfile}
+        self.origin(v2 + ("bib",), path + ("bibfile",))
+        name = self.out.data["name"]
+        default = [name["latex"] if isinstance(name, dict) else str(name)]
+        if not self.clean or _names(default) != _names(self.highlight):
+            out["highlight"] = list(self.highlight)
+        return [out]
+
+    def section_newpage(self, section: dict, path: YamlPath, index: int) -> list:
+        self.origin(("sections", index), path)
+        return ["newpage"]
+
+
+_SECTION_TYPES = {"education", "experience", "bullets", "skills", "talks", "publications", "newpage"}
+
+
+def _dated_date(value: Any) -> tuple[str, str]:
+    # talk_date has a local variable named latex.
+    return latex.dated_date(value)
+
+
+def _names(names: list[str]) -> list[str]:
+    return [n for n in names if n]
+
+
+def _contact_key(value: Any) -> str:
+    # A contact text item replaces {date}; any marker works for the comparison.
+    return to_latex(value, date="\x00date\x00")
+

cv_tools/validate.py

@@ -0,0 +1,165 @@
+"""JSON Schema validation of v2 files with line-numbered, friendly errors."""
+
+from __future__ import annotations
+
+import difflib
+import json
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib import resources
+
+import jsonschema
+
+from .loader import CVError, Source, YamlPath, describe
+
+# Slips that difflib would not suggest; the first valid one wins.
+_ALIASES = {
+    "content": ("entries", "bullets"),
+    "items": ("entries", "bullets"),
+    "entity": ("entries",),
+    "subitems": ("bullets", "entries"),
+    "responsibilities": ("bullets", "entries"),
+    "dates": ("date",),
+    "month": ("date",),
+    "year": ("date",),
+    "heading": ("name",),
+    "subheading": ("contact",),
+    "type": ("layout",),
+    "bibfile": ("bib",),
+    "name": ("title", "text"),  # text where an entry has no title (dated, list, text)
+    "organization": ("title",),
+    "university": ("title",),
+    "data": ("text",),
+    "item": ("text",),
+    "position": ("subtitle",),
+    "degree": ("subtitle",),
+    "honors": ("note",),
+}
+
+# Keys only v1 files use; the first one also says how to convert the file.
+_V1_ONLY = {
+    "type", "heading", "subheading", "content", "entity", "subitems", "responsibilities",
+    "bibfile", "thesis_title", "show_below",
+}
+V1_HINT = "This looks like a v1 file; run 'cv-tools migrate' to convert it"
+
+_TYPE_NAMES = {
+    "string": "a string",
+    "number": "a number",
+    "integer": "an integer",
+    "object": "a mapping",
+    "array": "a list",
+    "boolean": "a boolean",
+    "null": "null",
+}
+
+
+class ValidationError(CVError):
+    """One or more schema errors. ``errors`` holds one :class:`CVError` each."""
+
+    def __init__(self, errors: list[CVError]):
+        super().__init__("\n".join(str(e) for e in errors), errors[0].file)
+        self.errors = errors
+
+    def __str__(self) -> str:
+        return self.message
+
+
+@lru_cache(maxsize=1)
+def schema() -> dict:
+    text = (resources.files("cv_tools") / "schema" / "cv-v2.schema.json").read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+def format_path(path: YamlPath) -> str:
+    out = ""
+    for part in path:
+        out += f"[{part}]" if isinstance(part, int) else (f".{part}" if out else str(part))
+    return out
+
+
+def suggest(word: str, choices: list[str]) -> str | None:
+    for alias in _ALIASES.get(word, ()):
+        if alias in choices:
+            return alias
+    close = difflib.get_close_matches(word, choices, n=1, cutoff=0.7)
+    return close[0] if close else None
+
+
+@dataclass(frozen=True)
+class _Problem:
+    path: YamlPath
+    message: str
+    at_key: bool = False  # report at the mapping key rather than the value
+    missing: str | None = None  # the key a "required" error is about
+    hint: str | None = None  # the key an unknown key probably meant
+
+
+def _problems(error: jsonschema.ValidationError) -> list[_Problem]:
+    path = tuple(error.absolute_path)
+    v, value, sch = error.validator, error.instance, error.schema
+    expected = sch.get("x-expected")
+    if v == "not" and "x-message" in sch:
+        return [_Problem(path, sch["x-message"])]
+    if v == "type" and value is None and path and isinstance(path[-1], int):
+        return [_Problem(path, "empty list item (null); remove the '-' line or give the item a value")]
+    if v == "additionalProperties":
+        allowed = sorted(sch.get("properties", {}))
+        out = []
+        for key in value:
+            if key in allowed:
+                continue
+            hint = suggest(str(key), allowed)
+            detail = f"; did you mean '{hint}'?" if hint else f" (expected one of: {', '.join(allowed)})"
+            out.append(_Problem(path + (key,), f"unknown key '{key}'{detail}", at_key=True, hint=hint))
+        return out
+    if v == "required":
+        missing = [k for k in error.validator_value if k not in value]
+        out = []
+        for k in missing:
+            message = f"missing required key '{k}'"
+            if k == "layout" and "type" in value:
+                message += f" (v1 sections had 'type'). {V1_HINT}"
+            out.append(_Problem(path, message, missing=k))
+        return out
+    if v == "type":
+        if expected is None:
+            types = error.validator_value if isinstance(error.validator_value, list) else [error.validator_value]
+            expected = " or ".join(_TYPE_NAMES.get(t, t) for t in types)
+        return [_Problem(path, f"expected {expected}, got {describe(value)}")]
+    if v == "enum":
+        hint = suggest(str(value), [str(c) for c in error.validator_value])
+        detail = f"; did you mean '{hint}'?" if hint else f" (expected one of: {', '.join(map(str, error.validator_value))})"
+        return [_Problem(path, f"unknown value {value!r}{detail}")]
+    if v == "const":
+        return [_Problem(path, f"expected {expected or repr(error.validator_value)}, got {value!r}")]
+    if v in ("minProperties", "maxProperties") and expected:
+        return [_Problem(path, f"expected {expected}")]
+    if v == "maxItems":
+        return [_Problem(path, f"at most {error.validator_value} items allowed, got {len(value)}")]
+    return [_Problem(path, error.message)]
+
+
+def validate(src: Source) -> list[CVError]:
+    """Schema errors in a v2 document, sorted by position."""
+    validator = jsonschema.Draft202012Validator(schema())
+    problems = [p for error in validator.iter_errors(src.data) for p in _problems(error)]
+    # "unknown key 'titel'; did you mean 'title'?" already explains a missing title.
+    hinted = {(p.path[:-1], p.hint) for p in problems if p.hint}
+    found: dict[tuple, CVError] = {}
+    for p in problems:
+        if p.missing is not None and (p.path, p.missing) in hinted:
+            continue
+        where = format_path(p.path)
+        err = src.error(f"{where}: {p.message}" if where else p.message, p.path, key=p.at_key)
+        found.setdefault((err.line or 0, err.col or 0, err.message), err)
+    errors = [found[k] for k in sorted(found)]
+    for err in errors:
+        key = re.match(r"unknown key '([^']*)'", err.message.split(": ", 1)[-1])
+        if V1_HINT in err.message:
+            break
+        if key and key.group(1) in _V1_ONLY:
+            err.message += (" " if err.message.endswith("?") else ". ") + V1_HINT
+            break
+    return errors