warrant-cli 0.1.0__py3-none-any.whl

warrant/__init__.py

@@ -0,0 +1,8 @@
+"""Warrant: humans state intent, agents write the code, evidence decides what ships."""
+
+import sys
+
+if sys.version_info < (3, 11):
+    raise ImportError("Warrant needs Python 3.11 or newer")
+
+__version__ = "0.1.0"

warrant/__main__.py

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

warrant/checks.py

@@ -0,0 +1,120 @@
+"""Checks: the machine-decidable form of the intent, approved by a principal."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+
+from warrant.config import STRENGTHS, Config, load_toml
+from warrant.errors import WarrantError
+from warrant.hashing import digest_json, tree_digest
+from warrant.intent import Intent
+
+MANIFEST = "checks.toml"
+_FIELDS = {"id", "covers", "statement", "run", "strength", "timeout", "tags", "regression_for"}
+_ID = re.compile(r"^[A-Za-z][A-Za-z0-9_.-]*$")
+
+
+@dataclass
+class Check:
+    id: str
+    visibility: str  # "public" (the builder may see it) or "holdout" (the builder must not)
+    covers: list[str]
+    statement: str
+    run: list[str]
+    strength: str
+    timeout: int
+    tags: list[str]
+    regression_for: list[str]
+    directory: Path
+    digest: str  # covers the definition and every file in the check's directory
+
+    def matches(self, selector: str) -> bool:
+        if selector == "all":
+            return True
+        if selector in ("public", "holdout"):
+            return self.visibility == selector
+        kind, _, value = selector.partition(":")
+        return (kind == "tag" and value in self.tags) or (kind == "id" and value == self.id)
+
+
+def load_checks(config: Config, intent: Intent) -> list[Check]:
+    checks: list[Check] = []
+    seen: set[str] = set()
+    for visibility, directory in (("public", config.public_dir), ("holdout", config.holdout_dir)):
+        if directory is None:
+            continue
+        manifest = directory / MANIFEST
+        if not manifest.is_file():
+            raise WarrantError(f"missing {config.display(manifest)}")
+        entries = load_toml(manifest).get("check", [])
+        if not isinstance(entries, list):
+            raise WarrantError(f"{config.display(manifest)}: write checks as [[check]] tables")
+        files = tree_digest(directory)
+        for number, entry in enumerate(entries, start=1):
+            check = _parse(entry, visibility, directory, files, intent, f"{config.display(manifest)}, check {number}")
+            if check.id in seen:
+                raise WarrantError(f"check {check.id} is defined more than once")
+            seen.add(check.id)
+            checks.append(check)
+    return checks
+
+
+def _parse(entry, visibility: str, directory: Path, files: str, intent: Intent, where: str) -> Check:
+    if not isinstance(entry, dict):
+        raise WarrantError(f"{where}: each [[check]] must be a table")
+    unknown = sorted(set(entry) - _FIELDS)
+    if unknown:
+        raise WarrantError(f"{where}: unknown field(s) {', '.join(unknown)}")
+    check_id = entry.get("id")
+    if not isinstance(check_id, str) or not _ID.match(check_id):
+        raise WarrantError(f"{where}: id must be a short identifier such as P1 or H3")
+    where = f"check {check_id}"
+
+    covers = entry.get("covers")
+    if not isinstance(covers, list) or not covers or not all(isinstance(c, str) for c in covers):
+        raise WarrantError(f'{where}: covers must list the promises it checks, e.g. covers = ["G1"]')
+    missing = [clause for clause in covers if intent.clause(clause) is None]
+    if missing:
+        raise WarrantError(f"{where} covers {', '.join(missing)}, which {intent.path.name} does not define")
+
+    statement = entry.get("statement")
+    if not isinstance(statement, str) or not statement.strip():
+        raise WarrantError(f"{where}: statement must say in plain words what the check shows")
+
+    run = entry.get("run")
+    if isinstance(run, str):
+        run = shlex.split(run)
+    if not isinstance(run, list) or not run or not all(isinstance(part, str) for part in run):
+        raise WarrantError(f"{where}: run must be a command, as a string or a list of strings")
+
+    strength = entry.get("strength")
+    if strength not in STRENGTHS:
+        raise WarrantError(f"{where}: strength must be one of {', '.join(STRENGTHS)}")
+
+    timeout = entry.get("timeout", 120)
+    if type(timeout) is not int or timeout <= 0:
+        raise WarrantError(f"{where}: timeout must be a whole number of seconds")
+
+    definition = {
+        "id": check_id,
+        "visibility": visibility,
+        "covers": covers,
+        "statement": " ".join(statement.split()),
+        "run": run,
+        "strength": strength,
+        "timeout": timeout,
+        "tags": _strings(entry, "tags", where),
+        "regression_for": _strings(entry, "regression_for", where),
+    }
+    digest = digest_json({"definition": definition, "files": files})
+    return Check(**definition, directory=directory, digest=digest)
+
+
+def _strings(entry: dict, key: str, where: str) -> list[str]:
+    value = entry.get(key, [])
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        raise WarrantError(f"{where}: {key} must be a list of strings")
+    return value

warrant/cli.py

@@ -0,0 +1,321 @@
+"""The warrant command."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+from warrant import __version__, gate, report, scaffold
+from warrant.config import load_config, validate_selector
+from warrant.errors import WarrantError
+from warrant.hashing import short, tree_digest
+from warrant.ledger import Ledger
+from warrant.project import Project, find_root, load_project
+from warrant.verify import run_checks
+
+_INCIDENT_ID = re.compile(r"^[A-Za-z][A-Za-z0-9_.-]*$")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "handler"):
+        parser.print_help()
+        return 2
+    try:
+        code = args.handler(args)
+        sys.stdout.flush()
+        return code
+    except WarrantError as error:
+        print(f"warrant: {error}", file=sys.stderr)
+        return 2
+    except BrokenPipeError:
+        # The reader went away (for example `warrant log | head`); that's not an error.
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="warrant",
+        description="Humans state intent. Agents write the code. Evidence decides what ships.",
+    )
+    parser.add_argument("--version", action="version", version=f"warrant {__version__}")
+    parser.add_argument("-C", dest="directory", default=".", metavar="DIR", help="run as if started in DIR")
+    commands = parser.add_subparsers(metavar="COMMAND")
+
+    command = commands.add_parser("init", help="create a new project")
+    command.add_argument("path", nargs="?", default=".", help="where to create it (default: here)")
+    command.add_argument("--name", help="project name (default: the directory's name)")
+    command.set_defaults(handler=_init)
+
+    command = commands.add_parser("check", help="validate the intent, checks and policy, and show coverage")
+    command.add_argument("--workspace", metavar="DIR", help="check separation against this workspace")
+    command.set_defaults(handler=_check)
+
+    command = commands.add_parser("approve", help="approve the current intent, checks and policy (principals only)")
+    command.add_argument("--by", required=True, metavar="NAME", help="who is approving")
+    command.add_argument("--note", default="", help="why, or what changed")
+    command.set_defaults(handler=_approve)
+
+    command = commands.add_parser("brief", help="print the builder's brief, which never includes hidden checks")
+    command.add_argument("--out", metavar="FILE", help="write it to FILE")
+    command.set_defaults(handler=_brief)
+
+    command = commands.add_parser("verify", help="run checks on a snapshot of the workspace and record evidence")
+    command.add_argument("--workspace", metavar="DIR")
+    command.add_argument(
+        "--audience", choices=("principal", "builder"), default="principal",
+        help="builder output reveals hidden checks only as the promises they found broken",
+    )
+    command.add_argument(
+        "--select", action="append", metavar="SELECTOR",
+        help="run only matching checks: all, public, holdout, tag:NAME or id:ID (repeatable)",
+    )
+    command.set_defaults(handler=_verify)
+
+    command = commands.add_parser("gate", help="issue a warrant or a denial for an action such as merge")
+    command.add_argument("action", help="a gate defined in warrant.toml")
+    command.add_argument("--workspace", metavar="DIR")
+    command.set_defaults(handler=_gate)
+
+    command = commands.add_parser("report", help="show which promises are kept and broken")
+    command.add_argument("--workspace", metavar="DIR")
+    command.add_argument("--audience", choices=("principal", "builder"), default="principal")
+    command.add_argument("--out", metavar="FILE", help="write it to FILE")
+    command.set_defaults(handler=_report)
+
+    command = commands.add_parser("incident", help="record or list problems found in operation")
+    actions = command.add_subparsers(dest="incident_action", metavar="ACTION")
+    add = actions.add_parser("add", help="record an incident")
+    add.add_argument("id", help="an ID such as INC-1")
+    add.add_argument("description", help="what happened, in plain words")
+    add.add_argument("--clause", action="append", default=[], metavar="ID", help="a promise involved (repeatable)")
+    add.add_argument("--by", required=True, metavar="NAME", help="who is recording it")
+    actions.add_parser("list", help="list incidents and their regression checks")
+    command.set_defaults(handler=_incident, incident_parser=command)
+
+    command = commands.add_parser("log", help="show the ledger")
+    command.add_argument("--verify", action="store_true", help="check that the ledger and evidence are intact")
+    command.set_defaults(handler=_log)
+    return parser
+
+
+def _base(args) -> Path:
+    base = Path(args.directory).expanduser().resolve()
+    if not base.is_dir():
+        raise WarrantError(f"-C {args.directory}: not a directory")
+    return base
+
+
+def _project(args) -> Project:
+    return load_project(find_root(_base(args)))
+
+
+def _workspace(args, project: Project) -> tuple[Path, str]:
+    if args.workspace:
+        path = Path(args.workspace).expanduser()
+        path = path if path.is_absolute() else _base(args) / path
+    elif project.config.workspace is not None:
+        path = project.config.workspace
+    else:
+        raise WarrantError("no workspace given: pass --workspace DIR or set workspace in warrant.toml")
+    if not path.is_dir():
+        raise WarrantError(f"workspace {path} is not a directory")
+    return path.resolve(), project.config.display(path)
+
+
+def _emit(text: str, out: str | None, args) -> None:
+    if out is None:
+        sys.stdout.write(text)
+        return
+    path = Path(out).expanduser()
+    path = path if path.is_absolute() else _base(args) / path
+    path.write_text(text, encoding="utf-8")
+    print(f"Wrote {path}")
+
+
+def _init(args) -> int:
+    target = Path(args.path).expanduser()
+    target = (target if target.is_absolute() else _base(args) / target).resolve()
+    name = args.name or target.name
+    created = scaffold.create(target, name)
+    print(f"Created a Warrant project in {target}:")
+    for path in created:
+        print(f"  {path.relative_to(target)}")
+    print("  workspace/")
+    print()
+    print("Next:")
+    print("  1. Write your promises in intent.md.")
+    print("  2. Have an examiner draft checks for them in checks/, or write them yourself.")
+    print("  3. Review the checks, then approve:  warrant approve --by YOUR-NAME")
+    print("  4. Hand the builder its brief:       warrant brief")
+    return 0
+
+
+def _check(args) -> int:
+    project = _project(args)
+    config, intent = project.config, project.intent
+    ok = True
+    print(config.name)
+    print(f"  intent      {config.display(intent.path)}: {len(intent.clauses)} promises ({report.section_summary(intent)})")
+    visible = sum(check.visibility == "public" for check in project.checks)
+    print(f"  checks      {visible} visible, {len(project.checks) - visible} hidden")
+
+    coverage = project.coverage()
+    uncovered = [clause for clause, checks in coverage.items() if not checks]
+    visible_only = [
+        clause for clause, checks in coverage.items()
+        if checks and all(check.visibility == "public" for check in checks)
+    ]
+    if uncovered:
+        ok = False
+        print(f"  coverage    NOT COVERED: {', '.join(uncovered)}")
+    else:
+        note = f"; only visible checks cover {', '.join(visible_only)}" if visible_only else ""
+        print(f"  coverage    every promise has a check{note}")
+
+    workspace = None
+    if args.workspace:
+        workspace = Path(args.workspace).expanduser()
+        workspace = workspace if workspace.is_absolute() else _base(args) / workspace
+    elif config.workspace is not None:
+        workspace = config.workspace
+    if workspace is None:
+        print("  separation  no workspace configured")
+    else:
+        problems = config.separation_problems(workspace)
+        for problem in problems:
+            print(f"  separation  PROBLEM: {problem}")
+        if problems:
+            ok = False
+        else:
+            print(f"  separation  ok: hidden checks and the ledger are outside {config.display(workspace)}")
+
+    print(f"  approval    {report.approval_line(project)}")
+    print(f"  gates       {', '.join(config.gates)}")
+    return 0 if ok else 1
+
+
+def _approve(args) -> int:
+    project = _project(args)
+    if project.config.workspace is not None:
+        problems = project.config.separation_problems(project.config.workspace)
+        if problems:
+            raise WarrantError("refusing to approve: " + "; ".join(problems))
+    state, previous = project.approval_state()
+    if state == "current":
+        by, at = previous["data"]["by"], report.when(previous["time"])
+        print(f"Nothing to approve: {by} approved this exact intent, checks and policy on {at}.")
+        return 0
+    entry = project.ledger.append("approve", f"principal:{args.by}", {
+        "by": args.by,
+        "note": args.note,
+        "baseline": project.baseline_digest(),
+        **project.baseline(),
+    })
+    print(
+        f"Approved {short(entry['data']['baseline'])}: {len(project.intent.clauses)} promises, "
+        f"{len(project.checks)} checks and {len(project.config.gates)} gates."
+    )
+    if state == "stale":
+        print("  Changes since the last approval: " + "; ".join(project.changes_since(previous)))
+    uncovered = [clause for clause, checks in project.coverage().items() if not checks]
+    if uncovered:
+        print(f"  Warning: no check covers {', '.join(uncovered)}.")
+    print(f"Recorded in ledger entry #{entry['seq']}.")
+    return 0
+
+
+def _brief(args) -> int:
+    _emit(report.render_brief(_project(args)), args.out, args)
+    return 0
+
+
+def _verify(args) -> int:
+    project = _project(args)
+    workspace, label = _workspace(args, project)
+    selectors = args.select or ["all"]
+    for selector in selectors:
+        validate_selector(selector, "--select")
+    run = run_checks(project, workspace, label, selectors)
+    print(report.render_run(project, run, args.audience))
+    if args.audience == "principal" and project.approval_state()[0] != "current":
+        print("Note: these checks aren't approved in their current form, so gates won't count this evidence yet.")
+    return 0 if all(outcome.result == "pass" for outcome in run.outcomes) else 1
+
+
+def _gate(args) -> int:
+    project = _project(args)
+    workspace, label = _workspace(args, project)
+    decision = gate.evaluate(project, args.action, tree_digest(workspace))
+    entry = gate.record(project, decision, label)
+    print(report.render_decision(decision, label, entry))
+    return 0 if decision.granted else 1
+
+
+def _report(args) -> int:
+    project = _project(args)
+    workspace, label = _workspace(args, project)
+    _emit(report.render_report(project, tree_digest(workspace), label, args.audience), args.out, args)
+    return 0
+
+
+def _incident(args) -> int:
+    if args.incident_action is None:
+        args.incident_parser.print_help()
+        return 2
+    project = _project(args)
+    incidents = project.incidents()
+    if args.incident_action == "list":
+        if not incidents:
+            print("No incidents recorded.")
+        for incident in incidents:
+            regressions = [check.id for check in project.checks if incident["id"] in check.regression_for]
+            print(f"{incident['id']}  {report.when(incident['time'])}  {incident['description']}")
+            print(f"    promises: {', '.join(incident['clauses']) or 'none named'}; "
+                  f"regression checks: {', '.join(regressions) or 'none yet'}")
+        return 0
+    if not _INCIDENT_ID.match(args.id):
+        raise WarrantError(f"{args.id!r} is not a usable incident ID; try something like INC-1")
+    if any(incident["id"] == args.id for incident in incidents):
+        raise WarrantError(f"incident {args.id} is already recorded")
+    unknown = [clause for clause in args.clause if project.intent.clause(clause) is None]
+    if unknown:
+        raise WarrantError(f"{project.intent.path.name} does not define {', '.join(unknown)}")
+    entry = project.ledger.append("incident", f"principal:{args.by}", {
+        "id": args.id,
+        "description": args.description,
+        "clauses": args.clause,
+        "by": args.by,
+    })
+    print(f"Recorded incident {args.id} in ledger entry #{entry['seq']}.")
+    stopped = [name for name, g in project.config.gates.items() if g.require_regressions]
+    if stopped:
+        print(f"  {', '.join(stopped)} will be denied until an approved check with "
+              f'regression_for = ["{args.id}"] passes.')
+    if not args.clause:
+        print("  It names no promise. If none of the intent covers what went wrong, the intent is missing one.")
+    return 0
+
+
+def _log(args) -> int:
+    ledger = Ledger(load_config(find_root(_base(args))).ledger_dir)
+    entries = ledger.entries()
+    if args.verify:
+        problems = ledger.problems()
+        if problems:
+            print("The ledger has been altered:")
+            print("\n".join(f"  - {problem}" for problem in problems))
+            return 1
+        print(f"Ledger intact: {len(entries)} entries, head {short(ledger.head())}.")
+        print("Keep a copy of the head digest where builders can't write, to detect a wholesale rewrite.")
+        return 0
+    if not entries:
+        print("The ledger is empty.")
+    for entry in entries:
+        print(report.render_entry(entry))
+    return 0

warrant/config.py

@@ -0,0 +1,192 @@
+"""warrant.toml: where things live, and which evidence authorizes which action."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from warrant.errors import WarrantError
+from warrant.hashing import digest_json
+
+CONFIG_NAME = "warrant.toml"
+STRENGTHS = ("judged", "tested", "proved")
+
+_TOP_LEVEL = {"project", "checks", "gates"}
+_PROJECT_FIELDS = {"name", "intent", "workspace", "ledger"}
+_CHECKS_FIELDS = {"public", "holdout"}
+_GATE_FIELDS = {"checks", "min_strength", "after", "cover_all_intent", "require_regressions"}
+
+
+@dataclass
+class Gate:
+    name: str
+    checks: list[str]
+    min_strength: str
+    after: list[str]
+    cover_all_intent: bool
+    require_regressions: bool
+
+    def policy(self) -> dict:
+        return {
+            "checks": self.checks,
+            "min_strength": self.min_strength,
+            "after": self.after,
+            "cover_all_intent": self.cover_all_intent,
+            "require_regressions": self.require_regressions,
+        }
+
+
+@dataclass
+class Config:
+    root: Path
+    name: str
+    intent_path: Path
+    workspace: Path | None
+    ledger_dir: Path
+    public_dir: Path | None
+    holdout_dir: Path | None
+    gates: dict[str, Gate]
+
+    def policy_digest(self) -> str:
+        return digest_json({name: gate.policy() for name, gate in sorted(self.gates.items())})
+
+    def display(self, path: Path) -> str:
+        """A path as people should see it: relative to the project when possible."""
+        return os.path.relpath(path.resolve(), self.root)
+
+    def separation_problems(self, workspace: Path) -> list[str]:
+        """Ways the builder working in this workspace could read what it must not."""
+        workspace = workspace.resolve()
+        problems = []
+        for label, path in (("the hidden checks", self.holdout_dir), ("the ledger", self.ledger_dir)):
+            if path is not None and path.resolve().is_relative_to(workspace):
+                problems.append(
+                    f"{label} ({self.display(path)}) would be inside the builder's workspace "
+                    f"({self.display(workspace)}), where the builder could read them"
+                )
+        return problems
+
+
+def load_toml(path: Path) -> dict:
+    try:
+        with path.open("rb") as handle:
+            return tomllib.load(handle)
+    except FileNotFoundError:
+        raise WarrantError(f"file not found: {path}") from None
+    except tomllib.TOMLDecodeError as error:
+        raise WarrantError(f"{path}: {error}") from None
+
+
+def load_config(root: Path) -> Config:
+    root = root.resolve()
+    data = load_toml(root / CONFIG_NAME)
+    _known(data, _TOP_LEVEL, CONFIG_NAME)
+    project = _table(data, "project", CONFIG_NAME)
+    checks = _table(data, "checks", CONFIG_NAME)
+    gate_tables = _table(data, "gates", CONFIG_NAME)
+    _known(project, _PROJECT_FIELDS, "[project]")
+    _known(checks, _CHECKS_FIELDS, "[checks]")
+    if not gate_tables:
+        raise WarrantError(f"{CONFIG_NAME} defines no gates; add one such as [gates.merge]")
+    gates = {name: _gate(name, table) for name, table in gate_tables.items()}
+    _check_order(gates)
+    public, holdout = _path(root, checks, "public", "[checks]"), _path(root, checks, "holdout", "[checks]")
+    if public is None and holdout is None:
+        raise WarrantError("[checks] needs a public or a holdout directory")
+    return Config(
+        root=root,
+        name=_string(project, "name", "[project]", default=root.name),
+        intent_path=_path(root, project, "intent", "[project]", default="intent.md"),
+        workspace=_path(root, project, "workspace", "[project]"),
+        ledger_dir=_path(root, project, "ledger", "[project]", default="ledger"),
+        public_dir=public,
+        holdout_dir=holdout,
+        gates=gates,
+    )
+
+
+def validate_selector(selector: str, where: str) -> None:
+    if selector in ("all", "public", "holdout"):
+        return
+    kind, separator, value = selector.partition(":")
+    if separator and kind in ("tag", "id") and value:
+        return
+    raise WarrantError(f"{where}: unknown check selector {selector!r}; use all, public, holdout, tag:NAME or id:ID")
+
+
+def _gate(name: str, table) -> Gate:
+    where = f"[gates.{name}]"
+    if not isinstance(table, dict):
+        raise WarrantError(f"{where} must be a table")
+    _known(table, _GATE_FIELDS, where)
+    selectors = _strings(table, "checks", where, default=["all"])
+    for selector in selectors:
+        validate_selector(selector, where)
+    strength = table.get("min_strength", "tested")
+    if strength not in STRENGTHS:
+        raise WarrantError(f"{where}: min_strength must be one of {', '.join(STRENGTHS)}")
+    return Gate(
+        name=name,
+        checks=selectors,
+        min_strength=strength,
+        after=_strings(table, "after", where, default=[]),
+        cover_all_intent=_bool(table, "cover_all_intent", where),
+        require_regressions=_bool(table, "require_regressions", where),
+    )
+
+
+def _check_order(gates: dict[str, Gate]) -> None:
+    for gate in gates.values():
+        for prerequisite in gate.after:
+            if prerequisite not in gates:
+                raise WarrantError(f"[gates.{gate.name}] comes after {prerequisite!r}, which is not a gate")
+
+    def visit(name: str, path: tuple[str, ...]) -> None:
+        if name in path:
+            raise WarrantError("gates depend on each other in a loop: " + " -> ".join((*path, name)))
+        for prerequisite in gates[name].after:
+            visit(prerequisite, (*path, name))
+
+    for name in gates:
+        visit(name, ())
+
+
+def _known(table: dict, allowed: set[str], where: str) -> None:
+    unknown = sorted(set(table) - allowed)
+    if unknown:
+        raise WarrantError(f"{where}: unknown setting(s) {', '.join(unknown)}")
+
+
+def _table(data: dict, key: str, where: str) -> dict:
+    value = data.get(key, {})
+    if not isinstance(value, dict):
+        raise WarrantError(f"{where}: [{key}] must be a table")
+    return value
+
+
+def _string(table: dict, key: str, where: str, default: str | None = None) -> str | None:
+    value = table.get(key, default)
+    if value is not None and (not isinstance(value, str) or not value.strip()):
+        raise WarrantError(f"{where}: {key} must be a non-empty string")
+    return value
+
+
+def _strings(table: dict, key: str, where: str, default: list[str]) -> list[str]:
+    value = table.get(key, default)
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        raise WarrantError(f"{where}: {key} must be a list of strings")
+    return value
+
+
+def _bool(table: dict, key: str, where: str) -> bool:
+    value = table.get(key, False)
+    if not isinstance(value, bool):
+        raise WarrantError(f"{where}: {key} must be true or false")
+    return value
+
+
+def _path(root: Path, table: dict, key: str, where: str, default: str | None = None) -> Path | None:
+    value = _string(table, key, where, default)
+    return None if value is None else (root / value).resolve()

warrant/errors.py

@@ -0,0 +1,2 @@
+class WarrantError(Exception):
+    """A problem the user can fix, such as a bad setting or a malformed file."""