notedelta 0.1.0__py3-none-any.whl

notedelta/__init__.py

@@ -0,0 +1,15 @@
+"""NoteDelta: scientific notebook review and numerical regression analysis.
+
+The public, stable entry points are:
+
+* :func:`notedelta.engine.compare_files` - compare two notebook files and return a
+  :class:`notedelta.model.Report`.
+* :func:`notedelta.engine.compare_notebooks` - the same for already-loaded notebooks.
+* The ``notedelta`` command line interface (:mod:`notedelta.cli`).
+
+Everything else is internal and may change between minor versions.
+"""
+
+from notedelta._version import __version__
+
+__all__ = ["__version__"]

notedelta/__main__.py

@@ -0,0 +1,3 @@
+from notedelta.cli import main
+
+raise SystemExit(main())

notedelta/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

notedelta/cli.py

@@ -0,0 +1,473 @@
+"""``notedelta`` command line interface.
+
+Exit codes: 0 success, 1 fail-on condition met, 2 invalid input/configuration/usage,
+3 internal, git or execution error. Ordinary comparison never runs notebook code and
+never touches the network.
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import sys
+import tempfile
+import traceback
+from pathlib import Path
+from typing import TextIO
+
+from notedelta._version import __version__
+from notedelta.config.loader import STARTER_CONFIG, find_config, load_config
+from notedelta.config.schema import FAIL_CATEGORIES, NoteDeltaConfig
+from notedelta.errors import ExitCode, InputError, NoteDeltaError
+from notedelta.limits import DEFAULT_LIMITS, Limits
+from notedelta.model import Report
+from notedelta.reporting.terminal import ASCII_MAP as _ASCII
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:  # type: ignore[override]
+        self.print_usage(sys.stderr)
+        sys.stderr.write(f"notedelta: error: {message}\n")
+        raise SystemExit(ExitCode.INVALID_INPUT)
+
+
+def _out(stream: TextIO, text: str) -> None:
+    enc = (getattr(stream, "encoding", None) or "utf-8").lower()
+    if "utf" not in enc:
+        text = text.translate(_ASCII).encode(enc, errors="replace").decode(enc)
+    stream.write(text)
+
+
+def _fail_on(values: list[str] | None) -> list[str]:
+    result: list[str] = []
+    for v in values or []:
+        for part in v.split(","):
+            part = part.strip()
+            if not part:
+                continue
+            if part not in FAIL_CATEGORIES:
+                raise InputError(f"unknown --fail-on category {part!r}; choose from {', '.join(FAIL_CATEGORIES)}")
+            result.append(part)
+    return result
+
+
+def _load_cfg(args: argparse.Namespace, search_from: Path) -> tuple[NoteDeltaConfig, str | None]:
+    if getattr(args, "no_config", False):
+        return NoteDeltaConfig(), None
+    path: Path | None
+    if args.config:
+        path = Path(args.config)
+        if not path.is_file():
+            raise InputError(f"configuration file not found: {args.config}")
+    else:
+        path = find_config(search_from) or find_config(Path.cwd())
+    if path is None:
+        return NoteDeltaConfig(), None
+    cfg = load_config(path)
+    if args.no_discovery:
+        cfg = cfg.model_copy(update={"discovery": cfg.discovery.model_copy(update={"enabled": False})})
+    return cfg, path.name
+
+
+def _limits(args: argparse.Namespace) -> Limits:
+    if args.max_notebook_mb:
+        if args.max_notebook_mb <= 0:
+            raise InputError("--max-notebook-mb must be positive")
+        return Limits(max_notebook_bytes=int(args.max_notebook_mb * 1024 * 1024))
+    return DEFAULT_LIMITS
+
+
+def _options(args: argparse.Namespace, cfg: NoteDeltaConfig, source: str | None) -> object:
+    from notedelta.engine import CompareOptions
+
+    extra = _fail_on(args.fail_on)
+    if args.fail_on_regression:
+        extra.append("regression")
+    if args.no_discovery and source is None:
+        cfg = cfg.model_copy(update={"discovery": cfg.discovery.model_copy(update={"enabled": False})})
+    return CompareOptions(
+        config=cfg,
+        config_source=source,
+        baseline_project=Path(args.baseline_project) if getattr(args, "baseline_project", None) else None,
+        candidate_project=Path(args.candidate_project) if getattr(args, "candidate_project", None) else None,
+        environment=not args.no_env,
+        embed_images=args.embed_images,
+        redact=not args.no_redact,
+        limits=_limits(args),
+        extra_fail_on=extra,
+    )
+
+
+def _render(report: Report, fmt: str, *, verbose: bool = False, color: bool = False) -> str:
+    from notedelta.reporting import render_html, render_json, render_markdown, render_text
+
+    if fmt == "json":
+        return render_json(report)
+    if fmt == "html":
+        return render_html(report)
+    if fmt == "markdown":
+        return render_markdown(report)
+    ascii_only = "utf" not in (getattr(sys.stdout, "encoding", None) or "utf-8").lower()
+    return render_text(report, verbose=verbose, color=color, ascii_only=ascii_only)
+
+
+def _write_file(path: Path, text: str, protected: list[Path]) -> None:
+    resolved = path.resolve()
+    if any(resolved == p.resolve() for p in protected):
+        raise InputError(f"refusing to overwrite an input notebook: {path.name}")
+    if resolved.suffix == ".ipynb":
+        raise InputError(f"refusing to write a report to a .ipynb file: {path.name}")
+    try:
+        resolved.parent.mkdir(parents=True, exist_ok=True)
+        resolved.write_text(text, encoding="utf-8", newline="\n")
+    except OSError as exc:
+        raise InputError(f"cannot write {path.name}: {exc.strerror or exc}") from exc
+
+
+def _emit(report: Report, args: argparse.Namespace, protected: list[Path]) -> None:
+    from notedelta.reporting.terminal import use_color
+
+    if args.json:
+        _write_file(Path(args.json), _render(report, "json"), protected)
+    if args.html:
+        _write_file(Path(args.html), _render(report, "html"), protected)
+    if args.markdown:
+        _write_file(Path(args.markdown), _render(report, "markdown"), protected)
+    if args.output:
+        _write_file(Path(args.output), _render(report, args.format), protected)
+        if not args.quiet and args.format != "text":
+            _out(sys.stderr, f"notedelta: wrote {args.format} report to {Path(args.output).name}\n")
+    elif not args.quiet:
+        if args.format == "text":
+            _out(sys.stdout, _render(report, "text", verbose=args.verbose, color=use_color(sys.stdout, args.color)))
+        else:
+            _out(sys.stdout, _render(report, args.format))
+    elif args.quiet and report.policy.failed:
+        _out(sys.stderr, "notedelta: FAIL: " + "; ".join(report.policy.reasons) + "\n")
+
+
+def cmd_compare(args: argparse.Namespace) -> int:
+    from notedelta.engine import CompareOptions, compare_files
+
+    base, cand = Path(args.baseline), Path(args.candidate)
+    cfg, source = _load_cfg(args, cand.resolve().parent if cand.exists() else Path.cwd())
+    opts = _options(args, cfg, source)
+    assert isinstance(opts, CompareOptions)
+    report = compare_files(base, cand, opts)
+    _emit(report, args, [base, cand])
+    return ExitCode.POLICY_FAILURE if report.policy.failed else ExitCode.OK
+
+
+def _expand(patterns: list[str]) -> list[Path]:
+    paths: list[Path] = []
+    for pat in patterns:
+        if any(ch in pat for ch in "*?["):
+            matches = sorted(glob.glob(pat, recursive=True))
+            paths.extend(Path(m) for m in matches if m.endswith(".ipynb") and "/.ipynb_checkpoints/" not in m.replace("\\", "/"))
+        else:
+            paths.append(Path(pat))
+    unique: list[Path] = []
+    for p in paths:
+        if p.resolve() not in [u.resolve() for u in unique]:
+            unique.append(p)
+    return unique
+
+
+def cmd_compare_git(args: argparse.Namespace) -> int:
+    from notedelta import gitref
+    from notedelta.engine import CompareOptions, compare_files
+    from notedelta.reporting import render_markdown
+
+    notebooks = _expand(args.notebooks)
+    if not notebooks:
+        raise InputError("no notebooks matched")
+    multi = len(notebooks) > 1
+    if multi and (args.output or args.json or args.html or args.markdown):
+        raise InputError("with several notebooks use --report-dir instead of --output/--json/--html/--markdown")
+    worst = ExitCode.OK
+    summaries: list[str] = []
+    for nb in notebooks:
+        if not nb.is_file():
+            raise InputError(f"{nb.name}: file not found")
+        cfg, source = _load_cfg(args, nb.resolve().parent)
+        with tempfile.TemporaryDirectory(prefix="notedelta-git-") as tmp:
+            snap = gitref.snapshot(nb, args.ref, Path(tmp) / "baseline")
+            if args.candidate_ref:
+                csnap = gitref.snapshot(nb, args.candidate_ref, Path(tmp) / "candidate")
+                if csnap.notebook is None:
+                    raise InputError(f"{nb.name} does not exist at {args.candidate_ref}")
+                cand_path, cand_project, cand_label = csnap.notebook, csnap.project_dir, csnap.label
+            else:
+                cand_path, cand_project, cand_label = nb, nb.resolve().parent, f"{nb.name} (working tree)"
+            if snap.notebook is None:
+                msg = f"{nb.name}: new notebook - it does not exist at {args.ref}, nothing to compare"
+                if not args.quiet:
+                    _out(sys.stderr, f"notedelta: {msg}\n")
+                summaries.append(f"### ℹ️ NoteDelta: {nb.name}\n\n{msg}.\n")
+                continue
+            opts = _options(args, cfg, source)
+            assert isinstance(opts, CompareOptions)
+            opts.baseline_project = snap.project_dir
+            opts.candidate_project = cand_project
+            report = compare_files(snap.notebook, cand_path, opts, baseline_name=snap.label, candidate_name=cand_label)
+        if args.report_dir:
+            rd = Path(args.report_dir)
+            stem = nb.stem if not multi else nb.with_suffix("").as_posix().replace("/", "__").replace(":", "")
+            _write_file(rd / f"{stem}.html", _render(report, "html"), [nb])
+            _write_file(rd / f"{stem}.json", _render(report, "json"), [nb])
+        summaries.append(render_markdown(report, title=nb.as_posix()))
+        if multi:
+            if not args.quiet:
+                from notedelta.reporting.terminal import use_color
+
+                _out(
+                    sys.stdout,
+                    _render(report, "text", verbose=args.verbose, color=use_color(sys.stdout, args.color)) + "\n",
+                )
+        else:
+            _emit(report, args, [nb])
+        if report.policy.failed:
+            worst = ExitCode.POLICY_FAILURE
+    if args.summary:
+        path = Path(args.summary)
+        try:
+            with path.open("a", encoding="utf-8", newline="\n") as fh:
+                fh.write("\n".join(summaries) + "\n")
+        except OSError as exc:
+            raise InputError(f"cannot append summary to {path.name}: {exc.strerror or exc}") from exc
+    return worst
+
+
+def cmd_check_config(args: argparse.Namespace) -> int:
+    path = Path(args.path) if args.path else find_config(Path.cwd())
+    if path is None:
+        raise InputError("no .notedelta.yml found in this folder or its parents (create one with 'notedelta init')")
+    if not path.is_file():
+        raise InputError(f"configuration file not found: {args.path}")
+    cfg = load_config(path)
+    lines = [f"{path.name}: valid (version {cfg.version})"]
+    for m in cfg.metrics:
+        tol = []
+        if m.tolerance.absolute:
+            tol.append(f"abs {m.tolerance.absolute:g}")
+        if m.tolerance.relative:
+            tol.append(f"rel {m.tolerance.relative:g}")
+        lines.append(f"  metric {m.name}: {m.extraction.type}, direction {m.direction}, tolerance {' / '.join(tol) or 'exact'}")
+    if cfg.policy.fail_on:
+        lines.append(f"  policy fail_on: {', '.join(cfg.policy.fail_on)}")
+    _out(sys.stdout, "\n".join(lines) + "\n")
+    return ExitCode.OK
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    target = Path(args.directory) / ".notedelta.yml"
+    if target.exists() and not args.force:
+        raise InputError(f"{target.name} already exists (use --force to overwrite)")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(STARTER_CONFIG, encoding="utf-8", newline="\n")
+    _out(sys.stdout, f"wrote {target.name} - edit the metrics section, then run 'notedelta check-config'\n")
+    return ExitCode.OK
+
+
+def cmd_schema(args: argparse.Namespace) -> int:
+    if args.which == "config":
+        schema = NoteDeltaConfig.model_json_schema()
+        schema["$id"] = "https://notedelta.dev/schema/config-v1.json"
+    else:
+        schema = Report.model_json_schema()
+        schema["$id"] = "https://notedelta.dev/schema/report-v1.json"
+    _out(sys.stdout, json.dumps(schema, indent=2) + "\n")
+    return ExitCode.OK
+
+
+def cmd_execute(args: argparse.Namespace) -> int:
+    from notedelta.execution.runner import execute_notebook
+
+    path = Path(args.notebook)
+    if not path.is_file():
+        raise InputError(f"{path.name}: file not found")
+    warning = (
+        f"Executing {path.name} runs its code with your user permissions. This is NOT a sandbox: the code can "
+        "read and modify your files and use the network."
+    )
+    if not args.trust:
+        if not sys.stdin.isatty():
+            raise InputError(warning + " Pass --trust to confirm you trust this notebook.")
+        _out(sys.stderr, warning + "\nType 'yes' to execute: ")
+        if input().strip().lower() != "yes":
+            _out(sys.stderr, "notedelta: execution cancelled\n")
+            return ExitCode.INVALID_INPUT
+    records = execute_notebook(
+        path,
+        output_dir=Path(args.output_dir),
+        kernel=args.kernel,
+        timeout=args.timeout,
+        repeat=args.repeat,
+        workdir=args.workdir,
+        allow_errors=args.allow_errors,
+        force=args.force,
+    )
+    failed = False
+    for r in records:
+        state = "ok" if r.status == "ok" else f"{r.status}: {r.error}"
+        _out(sys.stdout, f"run {r.run}: {r.output}  {r.duration_seconds:.1f}s  kernel {r.kernel}  {state}\n")
+        failed |= r.status != "ok"
+    if len(records) > 1:
+        _out(
+            sys.stdout,
+            "compare runs with: notedelta stability " + " ".join(str(Path(args.output_dir) / r.output) for r in records) + "\n",
+        )
+    return ExitCode.INTERNAL_ERROR if failed else ExitCode.OK
+
+
+def cmd_stability(args: argparse.Namespace) -> int:
+    from notedelta.stability import analyze, render_stability_text
+
+    paths = _expand(args.notebooks)
+    if len(paths) < 2:
+        raise InputError("stability needs at least two notebooks (for example the outputs of 'notedelta execute --repeat 3')")
+    args.no_discovery = False
+    cfg, _ = _load_cfg(args, paths[0].resolve().parent)
+    if not cfg.metrics:
+        raise InputError("no metrics configured; stability analysis uses the metrics in .notedelta.yml")
+    rep = analyze(paths, cfg)
+    _out(sys.stdout, rep.model_dump_json(indent=2) + "\n" if args.format == "json" else render_stability_text(rep))
+    return ExitCode.OK
+
+
+def _add_compare_options(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("configuration")
+    g.add_argument("--config", metavar="FILE", help="path to .notedelta.yml (default: searched upwards from the candidate)")
+    g.add_argument("--no-config", action="store_true", help="ignore any .notedelta.yml")
+    g.add_argument("--no-discovery", action="store_true", help="do not report automatically discovered numbers")
+    g.add_argument("--no-env", action="store_true", help="skip environment and reproducibility diagnostics")
+    o = p.add_argument_group("output")
+    o.add_argument(
+        "-f",
+        "--format",
+        choices=["text", "json", "html", "markdown"],
+        default="text",
+        help="format written to stdout or --output (default: text)",
+    )
+    o.add_argument("-o", "--output", metavar="FILE", help="write the --format output to FILE instead of stdout")
+    o.add_argument("--json", metavar="FILE", help="also write a JSON report")
+    o.add_argument("--html", metavar="FILE", help="also write a self-contained HTML report")
+    o.add_argument("--markdown", metavar="FILE", help="also write a Markdown summary")
+    o.add_argument("--embed-images", action="store_true", help="embed changed raster images in the HTML report")
+    o.add_argument("--no-redact", action="store_true", help="do not redact secrets and home-directory paths in excerpts")
+    o.add_argument("-v", "--verbose", action="store_true", help="list every cell change and notice")
+    o.add_argument("-q", "--quiet", action="store_true", help="print nothing except failures (use the exit code)")
+    o.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    c = p.add_argument_group("checks")
+    c.add_argument("--fail-on-regression", action="store_true", help="exit with status 1 if a configured metric regressed")
+    c.add_argument(
+        "--fail-on",
+        action="append",
+        metavar="CATS",
+        help="exit 1 on any of these (comma separated): " + ", ".join(FAIL_CATEGORIES),
+    )
+    c.add_argument("--max-notebook-mb", type=float, metavar="MB", help="refuse notebooks larger than this (default 256)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(
+        prog="notedelta",
+        description="Know what changed in your scientific results, not just your code. "
+        "Compares Jupyter notebooks offline; never executes notebook code unless you run 'notedelta execute'.",
+        epilog="Exit codes: 0 ok, 1 fail-on condition met, 2 invalid input or configuration, 3 internal/git/execution error.",
+    )
+    parser.add_argument("--version", action="version", version=f"notedelta {__version__}")
+    parser.add_argument("--debug", action="store_true", help=argparse.SUPPRESS)
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND", parser_class=_Parser)
+
+    p = sub.add_parser(
+        "compare", help="compare two notebooks", description="Compare a baseline notebook with a candidate notebook."
+    )
+    p.add_argument("baseline", help="baseline .ipynb (the reference)")
+    p.add_argument("candidate", help="candidate .ipynb (the new version)")
+    p.add_argument("--baseline-project", metavar="DIR", help="folder whose dependency files describe the baseline environment")
+    p.add_argument("--candidate-project", metavar="DIR", help="folder whose dependency files describe the candidate environment")
+    _add_compare_options(p)
+    p.set_defaults(func=cmd_compare)
+
+    g = sub.add_parser(
+        "compare-git",
+        help="compare notebooks with their version at a git revision",
+        description="Compare each notebook (working tree) with the same file at a git revision. "
+        "Dependency files are read from that revision too.",
+    )
+    g.add_argument("notebooks", nargs="+", metavar="NOTEBOOK", help="notebook path(s) or glob(s), e.g. 'notebooks/**/*.ipynb'")
+    g.add_argument("--ref", default="HEAD", help="baseline revision (default: HEAD)")
+    g.add_argument("--candidate-ref", metavar="REF", help="compare against this revision instead of the working tree")
+    g.add_argument("--report-dir", metavar="DIR", help="write <name>.html and <name>.json for each notebook here")
+    g.add_argument("--summary", metavar="FILE", help="append a Markdown summary (e.g. $GITHUB_STEP_SUMMARY)")
+    _add_compare_options(g)
+    g.set_defaults(func=cmd_compare_git)
+
+    c = sub.add_parser("check-config", help="validate a .notedelta.yml file")
+    c.add_argument("path", nargs="?", help="config file (default: search upwards from the current folder)")
+    c.set_defaults(func=cmd_check_config)
+
+    i = sub.add_parser("init", help="write a starter .notedelta.yml")
+    i.add_argument("directory", nargs="?", default=".", help="folder to write into (default: current folder)")
+    i.add_argument("--force", action="store_true", help="overwrite an existing file")
+    i.set_defaults(func=cmd_init)
+
+    s = sub.add_parser("schema", help="print the JSON Schema of the report or the configuration")
+    s.add_argument("which", choices=["report", "config"], nargs="?", default="report")
+    s.set_defaults(func=cmd_schema)
+
+    x = sub.add_parser(
+        "execute",
+        help="re-run a notebook into a copy (opt-in; runs code; not sandboxed)",
+        description="Execute a notebook with a Jupyter kernel and save executed copies. "
+        "The original notebook is not modified. Requires: pip install 'notedelta[execute]'. "
+        "WARNING: this runs the notebook's code with your permissions; it is not a sandbox.",
+    )
+    x.add_argument("notebook")
+    x.add_argument("--trust", action="store_true", help="confirm that you trust this notebook's code")
+    x.add_argument("--kernel", help="kernel name (default: the notebook's kernelspec, else python3)")
+    x.add_argument("--timeout", type=int, default=600, help="per-cell timeout in seconds (default 600)")
+    x.add_argument("--repeat", type=int, default=1, help="number of independent runs (default 1)")
+    x.add_argument("--output-dir", default="notedelta-runs", help="where executed copies are written (default ./notedelta-runs)")
+    x.add_argument(
+        "--workdir",
+        choices=["notebook", "temp"],
+        default="notebook",
+        help="kernel working directory: the notebook's folder (default) or an empty temporary folder",
+    )
+    x.add_argument("--allow-errors", action="store_true", help="continue after a failing cell")
+    x.add_argument("--force", action="store_true", help="overwrite existing run files")
+    x.set_defaults(func=cmd_execute)
+
+    st = sub.add_parser("stability", help="describe metric variation across repeated runs")
+    st.add_argument("notebooks", nargs="+", metavar="NOTEBOOK")
+    st.add_argument("--config", metavar="FILE")
+    st.add_argument("--format", choices=["text", "json"], default="text")
+    st.set_defaults(func=cmd_stability, no_config=False)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return ExitCode.INVALID_INPUT
+    try:
+        code: int = args.func(args)
+        return code
+    except NoteDeltaError as exc:
+        _out(sys.stderr, f"notedelta: error: {exc}\n")
+        return exc.exit_code
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:  # pragma: no cover - defensive
+        _out(sys.stderr, f"notedelta: internal error: {type(exc).__name__}: {exc}\n")
+        if args.debug or os.environ.get("NOTEDELTA_DEBUG"):
+            traceback.print_exc()
+        else:
+            _out(sys.stderr, "notedelta: re-run with --debug for a traceback, and please report the problem\n")
+        return ExitCode.INTERNAL_ERROR

notedelta/config/__init__.py

@@ -0,0 +1,4 @@
+from notedelta.config.loader import STARTER_CONFIG, find_config, load_config, parse_config
+from notedelta.config.schema import MetricSpec, NoteDeltaConfig
+
+__all__ = ["STARTER_CONFIG", "MetricSpec", "NoteDeltaConfig", "find_config", "load_config", "parse_config"]

notedelta/config/loader.py

@@ -0,0 +1,137 @@
+"""Locate, read and validate ``.notedelta.yml``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from notedelta.config.schema import NoteDeltaConfig
+from notedelta.errors import ConfigError
+from notedelta.limits import DEFAULT_LIMITS
+
+CONFIG_NAMES = (".notedelta.yml", ".notedelta.yaml")
+
+
+def find_config(start: Path, max_levels: int = 12) -> Path | None:
+    """Search ``start`` and its parents (stopping at a git root) for a config file."""
+    cur = start.resolve()
+    if cur.is_file():
+        cur = cur.parent
+    for _ in range(max_levels):
+        for name in CONFIG_NAMES:
+            candidate = cur / name
+            if candidate.is_file():
+                return candidate
+        if (cur / ".git").exists() or cur.parent == cur:
+            return None
+        cur = cur.parent
+    return None
+
+
+def _format_loc(loc: tuple[Any, ...], data: Any) -> str:
+    parts: list[str] = []
+    node = data
+    for item in loc:
+        if isinstance(item, int):
+            label = f"[{item}]"
+            if isinstance(node, list) and 0 <= item < len(node):
+                node = node[item]
+                if isinstance(node, dict) and isinstance(node.get("name"), str):
+                    label = f"[{item}:{node['name']}]"
+            else:
+                node = None
+            parts.append(label)
+        else:
+            # discriminated-union tags ("regex", "key_value", ...) are not user-visible keys
+            if item in ("regex", "key_value", "json_path") and isinstance(node, dict) and "type" in node:
+                continue
+            node = node.get(item) if isinstance(node, dict) else None
+            parts.append(("." if parts else "") + str(item))
+    return "".join(parts) or "(root)"
+
+
+def parse_config(text: str, source: str = ".notedelta.yml") -> NoteDeltaConfig:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        where = f" (line {mark.line + 1}, column {mark.column + 1})" if mark is not None else ""
+        raise ConfigError(f"{source}: invalid YAML{where}: {getattr(exc, 'problem', None) or exc}") from exc
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise ConfigError(f"{source}: top level must be a mapping (key: value), got {type(data).__name__}")
+    if "version" not in data:
+        raise ConfigError(f"{source}: missing required key 'version' (use 'version: 1')")
+    if data.get("version") != 1:
+        raise ConfigError(f"{source}: unsupported config version {data.get('version')!r}; this NoteDelta supports version 1")
+    try:
+        return NoteDeltaConfig.model_validate(data)
+    except ValidationError as exc:
+        lines = []
+        for err in exc.errors()[:20]:
+            msg = err.get("msg", "invalid value")
+            if msg.startswith("Value error, "):
+                msg = msg[len("Value error, ") :]
+            if err.get("type") == "extra_forbidden":
+                msg = "unknown key (check spelling)"
+            lines.append(f"  - {_format_loc(tuple(err.get('loc', ())), data)}: {msg}")
+        raise ConfigError(f"{source}: invalid configuration\n" + "\n".join(lines)) from exc
+
+
+def load_config(path: Path) -> NoteDeltaConfig:
+    name = path.name
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        raise ConfigError(f"{name}: cannot read configuration ({exc.strerror or exc})") from exc
+    if size > DEFAULT_LIMITS.max_config_bytes:
+        raise ConfigError(f"{name}: configuration file is larger than 1 MB")
+    try:
+        text = path.read_text(encoding="utf-8-sig")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise ConfigError(f"{name}: cannot read configuration ({exc})") from exc
+    return parse_config(text, name)
+
+
+STARTER_CONFIG = """\
+# NoteDelta configuration - https://github.com/ouyang-matters/notedelta/blob/main/docs/configuration.md
+version: 1
+
+# Scientific metrics you care about. Each one is located in notebook outputs,
+# compared with a tolerance, and judged using its direction.
+metrics:
+  - name: validation_accuracy
+    label: Validation accuracy
+    direction: maximize          # maximize | minimize | none
+    unit: fraction               # values in [0, 1]; differences shown in percentage points
+    extraction:
+      type: key_value            # matches lines like "Validation accuracy = 0.912"
+      key: Validation accuracy
+    tolerance:
+      absolute: 0.002            # changes up to 0.2 percentage points are within tolerance
+
+  # - name: reconstruction_error
+  #   label: Relative reconstruction error
+  #   direction: minimize
+  #   extraction:
+  #     type: regex
+  #     pattern: 'Relative reconstruction error\\s*=\\s*([0-9.eE+-]+)'
+  #   tolerance:
+  #     absolute: 0.0001
+  #     relative: 0.02           # 2% of the baseline value
+
+# Numbers found automatically in changed outputs (no direction, so never "regressions").
+discovery:
+  enabled: true
+  tolerance:
+    absolute: 1.0e-12
+    relative: 1.0e-9
+
+# Exit with status 1 when any of these occur (also see --fail-on-regression).
+policy:
+  fail_on: []                    # e.g. [regression, output_missing, new_error]
+"""