revision-engine 0.2.2__py3-none-any.whl

revision_engine/config.py

@@ -0,0 +1,159 @@
+"""Load and validate revision.yaml and curriculum.yaml into frozen dataclasses."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from revision_engine.errors import BuildError
+
+SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+HOSTS = ("github", "gitlab")
+DEFAULT_VOICE = "en_US-lessac-medium"
+
+
+@dataclass(frozen=True)
+class SiteConfig:
+    title: str
+    base_url: str
+
+
+@dataclass(frozen=True)
+class RepoConfig:
+    url: str
+    host: str
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    root: Path
+    site: SiteConfig
+    repo: RepoConfig
+    content: Path
+    output: Path
+    voice: str
+
+
+@dataclass(frozen=True)
+class LessonRef:
+    slug: str
+    title: str
+    path: Path
+    type: str = "lesson"
+
+
+@dataclass(frozen=True)
+class Chapter:
+    slug: str
+    title: str
+    lessons: tuple[LessonRef, ...]
+
+
+@dataclass(frozen=True)
+class Curriculum:
+    chapters: tuple[Chapter, ...]
+
+
+def _load_yaml(path: Path) -> Any:
+    if not path.is_file():
+        raise BuildError(f"{path.name} not found at {path}")
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as e:
+        raise BuildError(f"{path}: invalid YAML: {e}") from e
+    return {} if data is None else data
+
+
+def _mapping(data: Any, where: str, file: str) -> dict:
+    if not isinstance(data, dict):
+        raise BuildError(f"{file}: {where} must be a mapping")
+    return data
+
+
+def _require(m: dict, key: str, where: str, file: str) -> Any:
+    if key not in m or m[key] is None:
+        raise BuildError(f"{file}: {where}.{key} is required")
+    return m[key]
+
+
+def _string(m: dict, key: str, where: str, file: str, default: str | None = None) -> str:
+    value = m.get(key, default) if default is not None else _require(m, key, where, file)
+    if not isinstance(value, str):
+        raise BuildError(f"{file}: {where}.{key} must be a string")
+    return value
+
+
+def _slug(value: Any, where: str, file: str) -> str:
+    if not isinstance(value, str) or not SLUG_RE.match(value):
+        raise BuildError(f"{file}: {where}: {value!r} is not a slug (lowercase letters, digits, hyphens)")
+    return value
+
+
+def load_project_config(root: Path) -> ProjectConfig:
+    root = root.resolve()
+    file = "revision.yaml"
+    data = _mapping(_load_yaml(root / file), "top level", file)
+
+    site = _mapping(_require(data, "site", "top level", file), "site", file)
+    repo = _mapping(_require(data, "repo", "top level", file), "repo", file)
+    host = _string(repo, "host", "repo", file)
+    if host not in HOSTS:
+        raise BuildError(f"{file}: repo.host must be one of: {', '.join(HOSTS)} (got {host!r})")
+
+    narration = _mapping(data.get("narration") or {}, "narration", file)
+
+    return ProjectConfig(
+        root=root,
+        site=SiteConfig(
+            title=_string(site, "title", "site", file),
+            base_url=_string(site, "base_url", "site", file, ""),
+        ),
+        repo=RepoConfig(url=_string(repo, "url", "repo", file), host=host),
+        content=root / _string(data, "content", "top level", file, "docs/revision"),
+        output=root / _string(data, "output", "top level", file, "public"),
+        voice=_string(narration, "voice", "narration", file, DEFAULT_VOICE),
+    )
+
+
+def load_curriculum(cfg: ProjectConfig) -> Curriculum:
+    path = cfg.content / "curriculum.yaml"
+    file = path.relative_to(cfg.root).as_posix()
+    data = _mapping(_load_yaml(path), "top level", file)
+    raw_chapters = data.get("chapters")
+    if not isinstance(raw_chapters, list):
+        raise BuildError(f"{file}: chapters must be a list")
+
+    chapters: list[Chapter] = []
+    seen_chapters: set[str] = set()
+    for ci, raw in enumerate(raw_chapters):
+        where = f"chapters[{ci}]"
+        m = _mapping(raw, where, file)
+        slug = _slug(m.get("slug"), f"{where}.slug", file)
+        if slug in seen_chapters:
+            raise BuildError(f"{file}: duplicate chapter slug {slug!r}")
+        seen_chapters.add(slug)
+        raw_lessons = m.get("lessons")
+        if not isinstance(raw_lessons, list):
+            raise BuildError(f"{file}: {where}.lessons must be a list")
+        lessons: list[LessonRef] = []
+        seen_lessons: set[str] = set()
+        for li, lraw in enumerate(raw_lessons):
+            lwhere = f"{where}.lessons[{li}]"
+            lm = _mapping(lraw, lwhere, file)
+            lslug = _slug(lm.get("slug"), f"{lwhere}.slug", file)
+            if lslug in seen_lessons:
+                raise BuildError(f"{file}: duplicate lesson slug {lslug!r} in chapter {slug!r}")
+            seen_lessons.add(lslug)
+            ltype = _string(lm, "type", lwhere, file, "lesson")
+            if ltype != "lesson":
+                raise BuildError(f"{file}: {lwhere}.type: only 'lesson' is supported in this version")
+            lpath = (cfg.content / _string(lm, "path", lwhere, file)).resolve()
+            if not (lpath / "lesson.md").is_file():
+                raise BuildError(f"{file}: {lwhere}.path: {lpath / 'lesson.md'} not found")
+            lessons.append(LessonRef(slug=lslug, title=_string(lm, "title", lwhere, file), path=lpath, type=ltype))
+        chapters.append(Chapter(slug=slug, title=_string(m, "title", where, file), lessons=tuple(lessons)))
+    return Curriculum(chapters=tuple(chapters))

revision_engine/diagrams.py

@@ -0,0 +1,108 @@
+"""Render Graphviz dot files to inline SVG and stamp node ids for the front end."""
+
+from __future__ import annotations
+
+import html
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from revision_engine.errors import BuildError
+
+_STRIP_RES = (
+    re.compile(r"<\?xml[^>]*\?>\s*"),
+    re.compile(r"<!DOCTYPE[^>]*>\s*"),
+    re.compile(r"<!--.*?-->\s*", re.S),
+)
+_NODE_RE = re.compile(r'<g id="([^"]+)" class="node"')
+_SVG_OPEN_RE = re.compile(r"<svg\b")
+# Quote-aware: render_dot unescapes ids, so a quoted attribute value may hold a raw '>'.
+_G_OPEN_RE = re.compile(r'<g\b(?:[^>"]|"[^"]*")*>')
+_CLASS_RE = re.compile(r'(?<![\w-])class="([^"]*)"')
+_ANCHOR_ATTR_RE = re.compile(r'(?<![\w-])data-anchor="([^"]*)"')
+_A_OPEN_RE = re.compile(r'<a\b(?:[^>"]|"[^"]*")*>')
+_HAS_LINK_RE = re.compile(r'\s(?:xlink:)?href="')
+_LINK_ATTR_RE = re.compile(r'\s(?:xlink:)?href="[^"]*"|\starget="[^"]*"')
+_GROUP_KINDS = {"node", "edge", "cluster", "graph"}
+
+
+def graphviz_version() -> str | None:
+    if shutil.which("dot") is None:
+        return None
+    out = subprocess.run(["dot", "-V"], capture_output=True, text=True, check=False)
+    m = re.search(r"version\s+(\S+)", out.stderr + out.stdout)
+    return m.group(1) if m else None
+
+
+def render_dot(path: Path, where: str) -> str:
+    if shutil.which("dot") is None:
+        raise BuildError(f"{where}: graphviz 'dot' is not installed or not on PATH")
+    proc = subprocess.run(
+        ["dot", "-Tsvg", "-Gbgcolor=transparent", str(path)],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        check=False,
+    )
+    if proc.returncode != 0:
+        raise BuildError(f"{where}: graphviz failed: {proc.stderr.strip()}")
+    svg = proc.stdout
+    for rx in _STRIP_RES:
+        svg = rx.sub("", svg)
+    svg = svg.strip()
+
+    def node(m: re.Match) -> str:
+        # Graphviz entity-escapes ids (a hyphen becomes &#45;); restore the author's spelling.
+        name = html.unescape(m.group(1))
+        return f'<g id="{name}" class="node" data-node="{name}"'
+
+    svg = _NODE_RE.sub(node, svg)
+    svg = _SVG_OPEN_RE.sub('<svg class="rv-svg"', svg, count=1)
+    return svg
+
+
+def stamp_anchors(svg: str, anchor_names: set[str]) -> str:
+    def repl(m: re.Match) -> str:
+        node = m.group(1)
+        if node in anchor_names:
+            return f'<g id="{node}" class="node rv-svg-anchor" data-node="{node}" data-anchor="{node}"'
+        return m.group(0)
+
+    return re.sub(r'<g id="([^"]+)" class="node" data-node="[^"]+"', repl, svg)
+
+
+def unlink_anchors(svg: str) -> tuple[str, list[str]]:
+    """Strip links from anchored nodes: a click on an anchored node pins it, so a link inside is dead.
+
+    Returns the new SVG and the sorted names of the anchored nodes that held a link.
+    """
+    if 'data-anchor="' not in svg:
+        return svg, []
+    groups = []
+    for m in _G_OPEN_RE.finditer(svg):
+        cls = _CLASS_RE.search(m.group(0))
+        if cls and _GROUP_KINDS.intersection(cls.group(1).split()):
+            groups.append(m)
+    ends = [g.start() for g in groups[1:]] + [len(svg)]
+
+    def unlink(m: re.Match) -> str:
+        tag = m.group(0)
+        return _LINK_ATTR_RE.sub("", tag) if _HAS_LINK_RE.search(tag) else tag
+
+    out: list[str] = []
+    names: list[str] = []
+    pos = 0
+    for g, end in zip(groups, ends):
+        anchor = _ANCHOR_ATTR_RE.search(g.group(0))
+        if anchor is None:
+            continue
+        span = svg[g.end() : end]
+        new = _A_OPEN_RE.sub(unlink, span)
+        if new != span:
+            names.append(anchor.group(1))
+            out.append(svg[pos : g.end()])
+            out.append(new)
+            pos = end
+    out.append(svg[pos:])
+    return "".join(out), sorted(set(names))

revision_engine/errors.py

@@ -0,0 +1,18 @@
+"""Error and warning types shared by every build stage."""
+
+
+class BuildError(Exception):
+    """A content or configuration problem that must stop the build.
+
+    The message always names the file and, where possible, the key path or line.
+    """
+
+
+class Report:
+    """Collects non-fatal warnings during a build for a summary at the end."""
+
+    def __init__(self) -> None:
+        self.warnings: list[str] = []
+
+    def warn(self, message: str) -> None:
+        self.warnings.append(message)

revision_engine/highlight.py

@@ -0,0 +1,62 @@
+"""Pygments highlighting emitted as one <div class="rv-line"> per source line."""
+
+from __future__ import annotations
+
+import re
+
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import TextLexer, get_lexer_for_filename
+from pygments.util import ClassNotFound
+
+from revision_engine.sources import SourceFile
+
+# With linespans set, Pygments emits `<span id="L-n">…\n</span>` per line: the newline sits
+# inside the span, before its close tag, and tokens never cross a line boundary.
+_LINE_RE = re.compile(r'<span id="L-(\d+)">(.*?)\n</span>', re.S)
+
+
+def _lexer(path: str):
+    try:
+        return get_lexer_for_filename(path, stripnl=False, ensurenl=False)
+    except ClassNotFound:
+        return TextLexer(stripnl=False, ensurenl=False)
+
+
+def highlight_source(source: SourceFile) -> str:
+    n = len(source.lines)
+    if n == 0:
+        return ""
+    formatter = HtmlFormatter(linespans="L", cssclass="rvhl", nowrap=False)
+    text = "\n".join(source.lines) + "\n"
+    html = highlight(text, _lexer(source.path), formatter)
+    inner = html[html.index("<pre>") + len("<pre>") : html.rindex("</pre>")]
+    matches = _LINE_RE.findall(inner)
+    if len(matches) != n:
+        raise AssertionError(f"highlighter produced {len(matches)} lines for {n} source lines in {source.path}")
+
+    out: list[str] = []
+    for i, (_, code) in enumerate(matches, start=1):
+        out.append(
+            f'<div class="rv-line" id="L{i}" data-line="{i}">'
+            f'<span class="rv-ln">{i}</span><span class="rv-code">{code}</span></div>'
+        )
+    return "\n".join(out) + "\n"
+
+
+def _style_defs(style: str, selector: str) -> str:
+    """Pygments token rules under `selector`, without the container background rule."""
+    defs = HtmlFormatter(style=style).get_style_defs(selector)
+    kept = [line for line in defs.splitlines() if not re.match(re.escape(selector) + r"\s*\{", line)]
+    return "\n".join(kept)
+
+
+def token_css() -> str:
+    light = _style_defs("default", ".rv-code")
+    dark_forced = _style_defs("github-dark", ':root[data-theme="dark"] .rv-code')
+    dark_auto = _style_defs("github-dark", ':root:not([data-theme="light"]) .rv-code')
+    return (
+        f"{light}\n"
+        f"@media (prefers-color-scheme: dark) {{\n{dark_auto}\n}}\n"
+        f"{dark_forced}\n"
+    )

revision_engine/intrinsics/__init__.py

@@ -0,0 +1,34 @@
+"""Map SIMD intrinsic names to vendor documentation URLs."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib import resources
+
+import yaml
+
+_VENDORS = ("intel", "arm", "riscv")
+
+
+@lru_cache(maxsize=1)
+def _table() -> dict[str, str]:
+    table: dict[str, str] = {}
+    for vendor in _VENDORS:
+        text = resources.files(__package__).joinpath(f"{vendor}.yaml").read_text(encoding="utf-8")
+        data = yaml.safe_load(text)
+        for name in data.get("names") or ():
+            table[name] = data["url"].format(name=name)
+        # Vendors whose page can't be derived from the name carry one explicit URL per name.
+        for name, url in (data.get("urls") or {}).items():
+            table[str(name)] = str(url)
+    return table
+
+
+def vendors() -> tuple[str, ...]:
+    return _VENDORS
+
+
+def lookup(name: str) -> str | None:
+    if not name:
+        return None
+    return _table().get(name)

revision_engine/intrinsics/arm.yaml

@@ -0,0 +1,22 @@
+url: "https://developer.arm.com/architectures/instruction-sets/intrinsics/{name}"
+names:
+  - vld1q_f32
+  - vst1q_f32
+  - vld2q_f32
+  - vst2q_f32
+  - vld4q_f32
+  - vdupq_n_f32
+  - vmulq_f32
+  - vaddq_f32
+  - vsubq_f32
+  - vadd_f32
+  - vmlaq_f32
+  - vmlsq_f32
+  - vfmaq_f32
+  - vfmsq_f32
+  - vpadd_f32
+  - vget_low_f32
+  - vget_high_f32
+  - vgetq_lane_f32
+  - vget_lane_f32
+  - vaddvq_f32

revision_engine/intrinsics/intel.yaml

@@ -0,0 +1,42 @@
+url: "https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text={name}"
+names:
+  - _mm_setzero_ps
+  - _mm_load_ps
+  - _mm_loadu_ps
+  - _mm_store_ps
+  - _mm_storeu_ps
+  - _mm_mul_ps
+  - _mm_add_ps
+  - _mm_add_ss
+  - _mm_addsub_ps
+  - _mm_or_ps
+  - _mm_moveldup_ps
+  - _mm_movehdup_ps
+  - _mm_hadd_ps
+  - _mm_dp_ps
+  - _mm_shuffle_ps
+  - _mm_movehl_ps
+  - _mm_cvtss_f32
+  - _mm256_setzero_ps
+  - _mm256_load_ps
+  - _mm256_loadu_ps
+  - _mm256_store_ps
+  - _mm256_storeu_ps
+  - _mm256_mul_ps
+  - _mm256_add_ps
+  - _mm256_addsub_ps
+  - _mm256_shuffle_ps
+  - _mm256_moveldup_ps
+  - _mm256_movehdup_ps
+  - _mm256_fmadd_ps
+  - _mm256_fmaddsub_ps
+  - _mm256_hadd_ps
+  - _mm256_extractf128_ps
+  - _mm256_castps256_ps128
+  - _mm512_setzero_ps
+  - _mm512_load_ps
+  - _mm512_loadu_ps
+  - _mm512_store_ps
+  - _mm512_storeu_ps
+  - _mm512_fmadd_ps
+  - _mm512_reduce_add_ps

revision_engine/intrinsics/riscv.yaml

@@ -0,0 +1,28 @@
+# RISC-V Vector C intrinsics, ratified v1.0 reference (riscv-non-isa/riscv-rvv-intrinsic-doc,
+# tag v1.0-ratified). Each name links to the section that lists it as a prototype; the section
+# cannot be derived from the name, so every row carries its full URL. Rows checked 2026-10-03.
+urls:
+  __riscv_vfadd: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/04_vector_floating-point_intrinsics.html#overloaded-vector-single-width-floating-point-add-subtract"
+  __riscv_vfadd_tu: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/policy_funcs/overloaded_intrinsic_funcs/04_vector_floating-point_intrinsics.html#policy-variant-overloadedvector-single-width-floating-point-add-subtract"
+  __riscv_vfmacc: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/04_vector_floating-point_intrinsics.html#overloaded-vector-single-width-floating-point-fused-multiply-add"
+  __riscv_vfmacc_tu: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/policy_funcs/overloaded_intrinsic_funcs/04_vector_floating-point_intrinsics.html#policy-variant-overloadedvector-single-width-floating-point-fused-multiply-add"
+  __riscv_vfmul: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/04_vector_floating-point_intrinsics.html#overloaded-vector-single-width-floating-point-multiply-divide"
+  __riscv_vfmv_f: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/07_vector_permutation_intrinsics.html#overloaded-integer-scalar-move"
+  __riscv_vfmv_s_f_f32m1: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/07_vector_permutation_intrinsics.html#integer-scalar-move"
+  __riscv_vfmv_v_f_f32m2: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/04_vector_floating-point_intrinsics.html#vector-floating-point-move"
+  __riscv_vfmv_v_f_f32m8: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/04_vector_floating-point_intrinsics.html#vector-floating-point-move"
+  __riscv_vfneg: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/04_vector_floating-point_intrinsics.html#overloaded-vector-single-width-floating-point-add-subtract"
+  __riscv_vfnmsac: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/04_vector_floating-point_intrinsics.html#overloaded-vector-single-width-floating-point-fused-multiply-add"
+  __riscv_vfredusum: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/05_vector_reduction_operations.html#overloaded-vector-single-width-floating-point-reduction"
+  __riscv_vget_f32m1: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/08_miscellaneous_vector_utility_intrinsics.html#overloaded-vector-extraction"
+  __riscv_vget_f32m2: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/08_miscellaneous_vector_utility_intrinsics.html#overloaded-vector-extraction"
+  __riscv_vle32_v_f32m8: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/00_vector_loads_and_stores_intrinsics.html#vector-unit-stride-load"
+  __riscv_vle64_v_u64m4: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/00_vector_loads_and_stores_intrinsics.html#vector-unit-stride-load"
+  __riscv_vlseg2e32_v_f32m2x2: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/01_vector_loads_and_stores_segment_intrinsics.html#vector-unit-stride-segment-load"
+  __riscv_vnsrl: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/02_vector_integer_arithmetic_intrinsics.html#overloaded-vector-narrowing-integer-right-shift"
+  __riscv_vreinterpret_f32m2: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/overloaded_intrinsic_funcs/08_miscellaneous_vector_utility_intrinsics.html#overloaded-reinterpret-cast-conversion"
+  __riscv_vsetvl_e32m2: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/08_miscellaneous_vector_utility_intrinsics.html#set-vl-and-vtype"
+  __riscv_vsetvl_e32m8: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/08_miscellaneous_vector_utility_intrinsics.html#set-vl-and-vtype"
+  __riscv_vsetvlmax_e32m1: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/08_miscellaneous_vector_utility_intrinsics.html#set-vl-to-vlmax-with-specific-vtype"
+  __riscv_vsetvlmax_e32m2: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/08_miscellaneous_vector_utility_intrinsics.html#set-vl-to-vlmax-with-specific-vtype"
+  __riscv_vsetvlmax_e32m8: "https://docs.riscv.org/reference/vector-c-intrinsics/v1.0/intrinsic_funcs/08_miscellaneous_vector_utility_intrinsics.html#set-vl-to-vlmax-with-specific-vtype"

revision_engine/lesson.py

@@ -0,0 +1,64 @@
+"""Parse lesson.md: YAML front matter plus a Markdown body."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from revision_engine.errors import BuildError
+
+
+@dataclass(frozen=True)
+class LessonDoc:
+    title: str
+    summary: str
+    file: str
+    start: str | None
+    media: str | None
+    voice: str | None
+    body: str
+    body_line: int = 1  # 1-based line number in lesson.md where the body starts
+
+
+def _opt_str(m: dict, key: str, where: str) -> str | None:
+    v = m.get(key)
+    if v is None:
+        return None
+    if not isinstance(v, str):
+        raise BuildError(f"{where}: front matter key {key!r} must be a string")
+    return v
+
+
+def load_lesson(path: Path, where: str) -> LessonDoc:
+    text = path.read_text(encoding="utf-8").replace("\r\n", "\n")
+    if not text.startswith("---\n"):
+        raise BuildError(f"{where}: front matter must start with '---' on line 1")
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        if text.endswith("\n---"):
+            end = len(text) - 4
+        else:
+            raise BuildError(f"{where}: front matter is not closed by a '---' line")
+    try:
+        meta = yaml.safe_load(text[4:end]) or {}
+    except yaml.YAMLError as e:
+        raise BuildError(f"{where}: front matter is not valid YAML: {e}") from e
+    if not isinstance(meta, dict):
+        raise BuildError(f"{where}: front matter must be a mapping")
+    for key in ("title", "file"):
+        if not isinstance(meta.get(key), str) or not meta[key]:
+            raise BuildError(f"{where}: front matter key {key!r} is required")
+    body = text[end + 5 :]
+    body_line = text[: end + 5].count("\n") + 1
+    return LessonDoc(
+        title=meta["title"],
+        summary=_opt_str(meta, "summary", where) or "",
+        file=meta["file"].replace("\\", "/"),
+        start=_opt_str(meta, "start", where),
+        media=_opt_str(meta, "media", where),
+        voice=_opt_str(meta, "voice", where),
+        body=body,
+        body_line=body_line,
+    )