revision-engine 0.2.2__py3-none-any.whl

revision_engine/__init__.py

@@ -0,0 +1,3 @@
+"""reVision: a static-site build tool for teaching code by example."""
+
+__version__ = "0.2.2"

revision_engine/anchors.py

@@ -0,0 +1,163 @@
+"""Named code regions: load from anchors.yaml and resolve to concrete line ranges."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from revision_engine.config import SLUG_RE
+from revision_engine.errors import BuildError
+from revision_engine.sources import SourceFile
+
+
+@dataclass(frozen=True)
+class AnchorSpec:
+    name: str
+    file: str
+    from_: str | None
+    to: str | None
+    match: str | None
+    lines: tuple[int, int] | None
+    variant: bool
+    label: str
+    within: str | None = None
+
+
+@dataclass(frozen=True)
+class Anchor:
+    name: str
+    file: str
+    start: int
+    end: int
+    variant: bool
+    label: str
+
+
+def _parse_lines(value: Any, name: str, where: str) -> tuple[int, int]:
+    if isinstance(value, str):
+        m = re.fullmatch(r"\s*(\d+)\s*-\s*(\d+)\s*", value)
+        if not m:
+            raise BuildError(f"{where}: anchor {name!r}: lines must look like '88-92'")
+        a, b = int(m.group(1)), int(m.group(2))
+    elif isinstance(value, list) and len(value) == 2 and all(isinstance(v, int) for v in value):
+        a, b = value
+    elif isinstance(value, int):
+        a = b = value
+    else:
+        raise BuildError(f"{where}: anchor {name!r}: lines must look like '88-92'")
+    if a < 1 or b < a:
+        raise BuildError(f"{where}: anchor {name!r}: lines {a}-{b} is not a valid range")
+    return (a, b)
+
+
+def load_anchors(path: Path, default_file: str, where: str) -> dict[str, AnchorSpec]:
+    if not path.is_file():
+        return {}
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        raise BuildError(f"{where}: invalid YAML: {e}") from e
+    if not isinstance(data, dict):
+        raise BuildError(f"{where}: top level must be a mapping of anchor name to definition")
+
+    specs: dict[str, AnchorSpec] = {}
+    for name, body in data.items():
+        if not isinstance(name, str) or not SLUG_RE.match(name):
+            raise BuildError(f"{where}: {name!r} is not a slug (lowercase letters, digits, hyphens)")
+        if not isinstance(body, dict):
+            raise BuildError(f"{where}: anchor {name!r} must be a mapping")
+        forms = [k for k in ("from", "match", "lines") if k in body]
+        if len(forms) != 1 or ("to" in body and "from" not in body):
+            raise BuildError(f"{where}: anchor {name!r} must use exactly one of from/to, match, lines")
+        if "from" in body and "to" not in body:
+            raise BuildError(f"{where}: anchor {name!r} has 'from' but no 'to'")
+        for key in ("from", "to", "match", "file", "label", "within"):
+            if key in body and not isinstance(body[key], str):
+                raise BuildError(f"{where}: anchor {name!r}: {key} must be a string")
+        if "to" in body:
+            try:
+                re.compile(body["to"])
+            except re.error as e:
+                raise BuildError(f"{where}: anchor {name!r}: 'to' is not a valid regex: {e}") from e
+        variant = body.get("variant", False)
+        if not isinstance(variant, bool):
+            raise BuildError(f"{where}: anchor {name!r}: variant must be true or false")
+        specs[name] = AnchorSpec(
+            name=name,
+            file=body.get("file", default_file).replace(chr(92), "/"),
+            from_=body.get("from"),
+            to=body.get("to"),
+            match=body.get("match"),
+            lines=_parse_lines(body["lines"], name, where) if "lines" in body else None,
+            variant=variant,
+            label=body.get("label", name),
+            within=body.get("within"),
+        )
+    return specs
+
+
+def _scope(spec: AnchorSpec) -> str:
+    return f" within {spec.within!r}" if spec.within else ""
+
+
+def _single_line(needle: str, source: SourceFile, spec: AnchorSpec, what: str, bounds: tuple[int, int]) -> int:
+    lo, hi = bounds
+    hits = [i + 1 for i in range(lo - 1, hi) if needle in source.lines[i]]
+    if not hits:
+        raise BuildError(f"anchor {spec.name!r} in {source.path}: no line contains {needle!r}{_scope(spec)} ({what})")
+    if len(hits) > 1:
+        listing = "; ".join(f"line {n}: {source.lines[n - 1].strip()}" for n in hits)
+        raise BuildError(
+            f"anchor {spec.name!r} in {source.path}: {what} {needle!r} matches {len(hits)} lines{_scope(spec)}, "
+            f"need exactly one: {listing}"
+        )
+    return hits[0]
+
+
+def resolve(spec: AnchorSpec, source: SourceFile, bounds: tuple[int, int] | None = None) -> Anchor:
+    """Resolve one spec; ``bounds`` (1-based, inclusive) limits the search to an enclosing anchor."""
+    n = len(source.lines)
+    lo, hi = bounds or (1, n)
+    if spec.lines is not None:
+        start, end = spec.lines
+        if end > n:
+            raise BuildError(f"anchor {spec.name!r} in {source.path}: lines {start}-{end} exceed file length {n}")
+        if bounds and (start < lo or end > hi):
+            raise BuildError(
+                f"anchor {spec.name!r} in {source.path}: lines {start}-{end} fall outside {spec.within!r} ({lo}-{hi})"
+            )
+    elif spec.match is not None:
+        start = end = _single_line(spec.match, source, spec, "match", (lo, hi))
+    else:
+        assert spec.from_ is not None and spec.to is not None
+        start = _single_line(spec.from_, source, spec, "from", (lo, hi))
+        pattern = re.compile(spec.to)
+        end = next((i + 1 for i in range(start, hi) if pattern.search(source.lines[i])), None)
+        if end is None:
+            raise BuildError(
+                f"anchor {spec.name!r} in {source.path}: no line after line {start}{_scope(spec)} matches to={spec.to!r}"
+            )
+    return Anchor(name=spec.name, file=source.path, start=start, end=end, variant=spec.variant, label=spec.label)
+
+
+def resolve_all(specs: dict[str, AnchorSpec], sources: dict[str, SourceFile]) -> dict[str, Anchor]:
+    out: dict[str, Anchor] = {}
+    for name, spec in specs.items():
+        if spec.file not in sources:
+            raise BuildError(f"anchor {name!r} refers to file {spec.file!r} which is not loaded")
+        bounds = None
+        if spec.within is not None:
+            if spec.within not in out:
+                raise BuildError(
+                    f"anchor {name!r} is within {spec.within!r}, which is not defined earlier in anchors.yaml"
+                )
+            outer = out[spec.within]
+            if outer.file != spec.file:
+                raise BuildError(f"anchor {name!r} is within {spec.within!r} but they name different files")
+            bounds = (outer.start, outer.end)
+        out[name] = resolve(spec, sources[spec.file], bounds)
+    return out

revision_engine/build.py

@@ -0,0 +1,268 @@
+"""Orchestrate the seven build stages into a static site. Pure: same tree, same bytes."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from revision_engine.anchors import Anchor, load_anchors, resolve_all
+from revision_engine.config import (
+    Chapter,
+    Curriculum,
+    LessonRef,
+    ProjectConfig,
+    load_curriculum,
+    load_project_config,
+)
+from revision_engine.diagrams import render_dot, stamp_anchors, unlink_anchors
+from revision_engine.errors import BuildError, Report
+from revision_engine.highlight import highlight_source, token_css
+from revision_engine.intrinsics import lookup
+from revision_engine.lesson import LessonDoc, load_lesson
+from revision_engine.markdown_ext import RenderContext, render_markdown
+from revision_engine.narration import check_cues, load_cues, load_narration
+from revision_engine.render import (
+    NavChapter,
+    NavLesson,
+    PageModel,
+    Variant,
+    render_page,
+    render_redirect,
+    site_index,
+    write_assets,
+)
+from revision_engine.sources import file_url, git_commit, read_source, short
+
+VIDEO_SUFFIXES = (".mp4", ".webm", ".ogv")
+
+
+@dataclass
+class BuildResult:
+    output: Path
+    pages: list[Path]
+    report: Report
+    commit: str
+    unlinked: list[tuple[str, int, str]] = field(default_factory=list)  # (lesson.md path, line, span text)
+
+
+@dataclass
+class _LessonBuild:
+    ref: LessonRef
+    chapter: Chapter
+    doc: LessonDoc
+    where: str
+    anchors: dict[str, Anchor]
+    code_html: str
+    lesson_html: str
+    media: str | None
+    cues: list[dict[str, Any]] | None
+    unlinked: list[tuple[str, int, str]]
+
+
+def _rel(cfg: ProjectConfig, p: Path) -> str:
+    return p.relative_to(cfg.root).as_posix()
+
+
+def _check_output(cfg: ProjectConfig, output: Path) -> None:
+    """Refuse to wipe the repository itself or any folder above it."""
+    output = output.resolve()
+    if output == cfg.root or output in cfg.root.parents:
+        raise BuildError("output folder must be inside the repository and not the repository itself")
+
+
+def _build_lesson(cfg: ProjectConfig, chapter: Chapter, ref: LessonRef, report: Report) -> _LessonBuild:
+    where = _rel(cfg, ref.path)
+    doc = load_lesson(ref.path / "lesson.md", f"{where}/lesson.md")
+
+    specs = load_anchors(ref.path / "anchors.yaml", doc.file, f"{where}/anchors.yaml")
+    files = sorted({doc.file} | {s.file for s in specs.values()})
+    sources = {f: read_source(cfg.root, f) for f in files}
+    anchors = resolve_all(specs, sources)
+    # Version one shows one file per lesson. Every consumer of the anchor set (fragments,
+    # variants, cues, diagram nodes) would otherwise box foreign line numbers onto this file.
+    for name, a in anchors.items():
+        if a.file != doc.file:
+            raise BuildError(
+                f"{where}/anchors.yaml: anchor {name!r} resolves in {a.file!r} but this lesson shows {doc.file!r}"
+            )
+    if doc.start is not None and doc.start not in anchors:
+        raise BuildError(f"{where}/lesson.md: start anchor {doc.start!r} is not defined in anchors.yaml")
+
+    diagrams: dict[str, str] = {}
+    diagrams_dir = ref.path / "diagrams"
+    if diagrams_dir.is_dir():
+        for dot in sorted(diagrams_dir.glob("*.dot")):
+            dwhere = f"{where}/diagrams/{dot.name}"
+            svg, unlinked = unlink_anchors(stamp_anchors(render_dot(dot, dwhere), set(anchors)))
+            for node in unlinked:
+                report.warn(f"{dwhere}: node {node!r} is an anchor; its link is removed")
+            diagrams[dot.stem] = svg
+
+    ctx = RenderContext(
+        anchors={name: a.file for name, a in anchors.items()},
+        diagrams=diagrams,
+        lookup=lookup,
+        report=report,
+        where=f"{where}/lesson.md",
+        lesson_file=doc.file,
+        line_offset=doc.body_line - 1,
+    )
+    rendered = render_markdown(doc.body, ctx)
+
+    media: str | None = None
+    cues: list[dict[str, Any]] | None = None
+    narration_path = ref.path / "narration.yaml"
+    cues_path = ref.path / "cues.json"
+    if narration_path.is_file():
+        if not cues_path.is_file():
+            raise BuildError(f"{where}: narration.yaml present but cues.json missing; run 'rv2 narrate {where}'")
+        narration = load_narration(narration_path, f"{where}/narration.yaml")
+        data = load_cues(cues_path, f"{where}/cues.json")
+        check_cues(narration, data, where)
+        media = data["media"]
+        cues = data["segments"]
+    elif doc.media:
+        media = doc.media
+        if cues_path.is_file():
+            cues = load_cues(cues_path, f"{where}/cues.json")["segments"]
+
+    if media is not None:
+        media_path = (ref.path / media).resolve()
+        lesson_root = ref.path.resolve()
+        if Path(media).is_absolute() or lesson_root not in media_path.parents:
+            raise BuildError(f"{where}: media path {media!r} must be a relative path inside the lesson folder")
+        if not media_path.is_file():
+            raise BuildError(f"{where}: media file {media!r} not found")
+    for i, seg in enumerate(cues or [], start=1):
+        for name in seg.get("show", []):
+            if name not in anchors:
+                raise BuildError(f"{where}/cues.json: segment {i} shows unknown anchor {name!r}")
+        if "diagram" in seg and seg["diagram"] not in diagrams:
+            raise BuildError(f"{where}/cues.json: segment {i} refers to unknown diagram {seg['diagram']!r}")
+        if "node" in seg:
+            svg = diagrams.get(seg.get("diagram", ""), "")
+            if f'data-node="{seg["node"]}"' not in svg:
+                raise BuildError(
+                    f"{where}/cues.json: segment {i} refers to node {seg['node']!r} "
+                    f"which is not in diagram {seg.get('diagram')!r}"
+                )
+
+    return _LessonBuild(
+        ref=ref,
+        chapter=chapter,
+        doc=doc,
+        where=where,
+        anchors=anchors,
+        code_html=highlight_source(sources[doc.file]),
+        lesson_html=rendered.html,
+        media=media,
+        cues=cues,
+        unlinked=[(ctx.where, line, text) for line, text in rendered.unlinked_code],
+    )
+
+
+def _nav(curriculum: Curriculum, current: LessonRef) -> tuple[NavChapter, ...]:
+    return tuple(
+        NavChapter(
+            slug=ch.slug,
+            title=ch.title,
+            lessons=tuple(
+                NavLesson(le.slug, le.title, f"{ch.slug}/{le.slug}/", le is current) for le in ch.lessons
+            ),
+        )
+        for ch in curriculum.chapters
+    )
+
+
+def _media_kind(media: str | None) -> str | None:
+    if media is None:
+        return None
+    return "video" if media.lower().endswith(VIDEO_SUFFIXES) else "audio"
+
+
+def build(
+    root: Path, output: Path | None = None, commit: str | None = None, check_only: bool = False
+) -> BuildResult:
+    cfg = load_project_config(root)
+    curriculum = load_curriculum(cfg)
+    output = (output or cfg.output).resolve()
+    _check_output(cfg, output)
+
+    commit = commit or git_commit(cfg.root)
+    if commit is None:
+        raise BuildError("not a git repository; pass --commit <sha> to identify the source revision")
+    if not re.fullmatch(r"[0-9a-f]{40}", commit):
+        raise BuildError(f"commit must be a 40-character hex sha (got {commit!r})")
+
+    report = Report()
+    flat = [(ch, le) for ch in curriculum.chapters for le in ch.lessons]
+    built = [_build_lesson(cfg, ch, le, report) for ch, le in flat]
+    unlinked = [u for lb in built for u in lb.unlinked]
+
+    if check_only:
+        return BuildResult(output=output, pages=[], report=report, commit=commit, unlinked=unlinked)
+
+    if output.exists():
+        if any(output.iterdir()) and not (output / "site.json").is_file():
+            raise BuildError(
+                f"output folder {output} exists and was not written by rv2 (no site.json); "
+                "delete it yourself or choose another --output"
+            )
+        shutil.rmtree(output)
+    output.mkdir(parents=True)
+    assets = write_assets(output, token_css())
+
+    pages: list[Path] = []
+    for i, lb in enumerate(built):
+        ch, le = lb.chapter, lb.ref
+        prev_href = f"{flat[i - 1][0].slug}/{flat[i - 1][1].slug}/" if i > 0 else None
+        next_href = f"{flat[i + 1][0].slug}/{flat[i + 1][1].slug}/" if i + 1 < len(flat) else None
+        variants = tuple(Variant(a.name, a.label, a.start) for a in lb.anchors.values() if a.variant)
+        rv_data = {
+            "anchors": {name: {"start": a.start, "end": a.end} for name, a in sorted(lb.anchors.items())},
+            "start": lb.doc.start,
+            "cues": lb.cues,
+            "variants": [{"name": v.name, "label": v.label, "start": v.start} for v in variants],
+        }
+        model = PageModel(
+            site_title=cfg.site.title,
+            root="../../",
+            assets=assets,
+            chapter_title=ch.title,
+            lesson_title=lb.doc.title,
+            summary=lb.doc.summary,
+            nav=_nav(curriculum, le),
+            prev_href=prev_href,
+            next_href=next_href,
+            file_path=lb.doc.file,
+            commit_short=short(commit),
+            file_url=file_url(cfg.repo, commit, lb.doc.file),
+            code_html=lb.code_html,
+            variants=variants,
+            lesson_html=lb.lesson_html,
+            media_url=lb.media,
+            media_kind=_media_kind(lb.media),
+            cues=lb.cues,
+            rv_data=rv_data,
+        )
+        page_dir = output / ch.slug / le.slug
+        page_dir.mkdir(parents=True)
+        page = page_dir / "index.html"
+        page.write_text(render_page(model), encoding="utf-8", newline="\n")
+        pages.append(page)
+        if lb.media:
+            dst = page_dir / lb.media
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(le.path / lb.media, dst)
+
+    (output / "site.json").write_text(
+        json.dumps(site_index(cfg, curriculum), indent=2, sort_keys=True) + "\n", encoding="utf-8", newline="\n"
+    )
+    if flat:
+        first = f"{flat[0][0].slug}/{flat[0][1].slug}/"
+        (output / "index.html").write_text(render_redirect(first, cfg.site.title), encoding="utf-8", newline="\n")
+    return BuildResult(output=output, pages=pages, report=report, commit=commit, unlinked=unlinked)

revision_engine/cli.py

@@ -0,0 +1,159 @@
+"""Command-line entry point: rv2 build | check | serve | narrate."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from revision_engine import __version__
+from revision_engine.errors import BuildError
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="rv2", description="reVision static-site builder. Revision control, revisited.")
+    p.add_argument("--version", action="version", version=f"rv2 {__version__}")
+    sub = p.add_subparsers(dest="command", metavar="command")
+
+    def common(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("--root", type=Path, default=Path("."), help="repository root holding revision.yaml (default: .)")
+        sp.add_argument("--commit", help="40-char sha to label the build when not in a git checkout")
+
+    b = sub.add_parser("build", help="build the static site into the output folder")
+    common(b)
+    b.add_argument("--output", type=Path, help="override the output folder from revision.yaml")
+
+    c = sub.add_parser("check", help="run every build check without writing output")
+    common(c)
+    c.add_argument("--strict", action="store_true", help="exit 1 if the check reports any warning")
+    c.add_argument(
+        "--list-unlinked", action="store_true", help="list inline code spans that match no vendor intrinsic table"
+    )
+
+    s = sub.add_parser("serve", help="build, serve on localhost, rebuild on change")
+    common(s)
+    s.add_argument("--port", type=int, default=8000)
+
+    n = sub.add_parser("narrate", help="synthesize a lesson's narration.yaml into audio + cues.json")
+    n.add_argument("lesson_dir", type=Path)
+    n.add_argument("--model", type=Path, help="path to a Piper voice model (.onnx); default: <voice>.onnx in $RV2_VOICES or ~/piper-voices")
+    n.add_argument(
+        "--voice",
+        help="voice name, not a path (default: narration.yaml's voice, then the lesson's front matter voice, "
+        "then the project's narration.voice)",
+    )
+    n.add_argument("--silent", action="store_true", help="use the deterministic silent voice (fixtures and tests)")
+    n.add_argument("--mp3", action="store_true", help="also transcode to MP3 with ffmpeg and point cues at it")
+    return p
+
+
+def _report(result) -> None:
+    for w in result.report.warnings:
+        print(f"warning: {w}")
+    if result.report.warnings:
+        print(f"{len(result.report.warnings)} warning(s)")
+
+
+def _cmd_build(args) -> int:
+    from revision_engine.build import build
+
+    result = build(args.root, output=args.output, commit=args.commit)
+    print(f"built {len(result.pages)} pages at commit {result.commit[:7]} -> {result.output}")
+    _report(result)
+    return 0
+
+
+def _cmd_check(args) -> int:
+    from revision_engine.build import build
+
+    result = build(args.root, commit=args.commit, check_only=True)
+    failed = args.strict and result.report.warnings
+    if not failed:
+        print(f"ok: all checks passed at commit {result.commit[:7]}")
+    if args.list_unlinked:
+        for where, line, text in result.unlinked:
+            print(f"unlinked: {where}:{line}: {text!r}")
+        if result.unlinked:
+            print(f"{len(result.unlinked)} unlinked code span(s)")
+    _report(result)
+    if failed:
+        print(f"error: --strict: {len(result.report.warnings)} warning(s)", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_serve(args) -> int:
+    from revision_engine.serve import serve
+
+    serve(args.root, port=args.port, commit=args.commit)
+    return 0
+
+
+def _cmd_narrate(args) -> int:
+    from revision_engine.narration import PiperSynthesizer, SilentSynthesizer, narrate
+
+    if args.silent:
+        synth = SilentSynthesizer()
+        voice = args.voice or "silent-fixture"
+    else:
+        from revision_engine.narration import resolve_voice_model
+
+        voice, model = resolve_voice_model(args.lesson_dir, args.voice, args.model)
+        synth = PiperSynthesizer(model)
+    cues = narrate(args.lesson_dir, synth, voice=voice)
+    if args.mp3:
+        _transcode_mp3(args.lesson_dir, cues)
+    print(f"wrote {len(cues['segments'])} segments -> {args.lesson_dir / cues['media']}")
+    return 0
+
+
+def _transcode_mp3(lesson_dir: Path, cues: dict) -> None:
+    import json
+    import shutil
+    import subprocess
+
+    if shutil.which("ffmpeg") is None:
+        raise BuildError("--mp3 needs ffmpeg on PATH")
+    wav = lesson_dir / cues["media"]
+    mp3 = wav.with_suffix(".mp3")
+    proc = subprocess.run(
+        ["ffmpeg", "-y", "-loglevel", "error", "-i", str(wav), "-codec:a", "libmp3lame", "-q:a", "4", str(mp3)],
+        check=False,
+    )
+    if proc.returncode != 0:
+        raise BuildError("ffmpeg failed to transcode narration")
+    wav.unlink()
+    cues["media"] = f"media/{mp3.name}"
+    (lesson_dir / "cues.json").write_text(
+        json.dumps(cues, indent=2, sort_keys=True) + "\n", encoding="utf-8", newline="\n"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(sys.argv[1:] if argv is None else argv)
+    if args.command is None:
+        parser.print_help(sys.stderr)
+        return 2
+    # A lesson's text can hold characters the console codec cannot encode (cp1252 on a
+    # redirected Windows stdout); escape them rather than crash mid-report. Line buffering
+    # keeps stdout ahead of a later stderr line when CI merges the two streams.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(errors="backslashreplace", line_buffering=True)
+    try:
+        if args.command == "build":
+            return _cmd_build(args)
+        if args.command == "check":
+            return _cmd_check(args)
+        if args.command == "serve":
+            return _cmd_serve(args)
+        if args.command == "narrate":
+            return _cmd_narrate(args)
+    except BuildError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())