pytest-txtar 0.1.0__tar.gz

pytest_txtar-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Sync deps
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Typecheck
+        run: uv run basedpyright
+
+      - name: Test
+        run: uv run pytest
+
+  publish:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

pytest_txtar-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/

pytest_txtar-0.1.0/LICENSE

@@ -0,0 +1,55 @@
+MIT License
+
+Copyright (c) 2026 Anton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+
+src/pytest_txtar/txtar.py is a port of the txtar archive format from
+golang.org/x/tools/txtar, which carries the following license:
+
+Copyright 2018 The Go Authors.
+Copyright (c) 2009 The Go Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pytest_txtar-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: pytest-txtar
+Version: 0.1.0
+Summary: Txtar-driven contract testing for command-line tools: sandboxed runs, normalized assertions, golden update.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pytest>=8
+Description-Content-Type: text/markdown
+
+# pytest-txtar
+
+Contract testing for command-line tools, driven by [txtar](https://pkg.go.dev/golang.org/x/tools/txtar)
+archives: one file per case carrying the fixture tree, the invocation, and everything asserted about
+the result — stdout, stderr, exit code, and files left behind.
+
+Each case runs in a fresh sandbox; paths that vary per run are normalized to tokens before
+comparison, and a golden-update flow rewrites assertions from the actual run.
+
+The package is layered: `pytest_txtar.txtar` parses the archive format, the pytest-free core
+(`case`, `sandbox`, `compare`, `update`) executes and compares cases parameterized by a
+`TxtarSpec`, and a pytest plugin collects `*.txtar` files as test items.
+
+Status: pre-release, under construction.
+
+## Configuration
+
+A consumer states what to run and where by implementing the `pytest_txtar_spec` hook in a
+`conftest.py` beside its cases:
+
+```python
+from pathlib import Path
+
+import pytest
+from pytest_txtar.case import TxtarSpec
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def pytest_txtar_spec(config: pytest.Config) -> TxtarSpec:
+    return TxtarSpec(
+        commands={"mytool": ROOT / "bin" / "mytool"},
+        roots=("home", "xdg", "cwd"),
+        cwd_root="cwd",
+        env={"HOME": "home", "XDG_CONFIG_HOME": "xdg"},
+    )
+```
+
+| Field | Meaning |
+| --- | --- |
+| `commands` | Command word → binary it resolves to, for the first word of a `cmd` line. |
+| `roots` | Sandbox subdirectories a case may address under `fixtures/` and `expected/`. |
+| `cwd_root` | The root the commands run in. |
+| `env` | Environment variable → the root it is pointed at, on top of the ambient environment. |
+| `tokens` | Root → normalization token; defaults to the upper-cased root in braces. |
+
+The `home`/`xdg`/`cwd` roots above are one configuration, not a fixed set: a spec may name any roots
+and bind any variables to them.
+
+## Case format
+
+This section defines the behavior; the package implements it. A runner in another language is
+conformant when it agrees with everything below.
+
+### Container — txtar
+
+An archive is a leading comment followed by file sections. A section starts with a marker line
+`-- name --`; everything up to the next marker line is its content.
+
+- The marker line is exactly `--`, a space, the name, a space, `--`. Surrounding whitespace in the
+  name is stripped; a name may contain `/`.
+- A line whose name would be empty (`--  --`) is content, not a marker.
+- Content that does not end in a newline is treated as if it did. A well-formed archive therefore
+  round-trips byte-exactly through parse and serialize.
+- A section name may appear only once per case; a repeat is a malformed case.
+- There are no other syntax errors: any byte sequence parses.
+
+### Sections
+
+| Section | Required | Meaning |
+| --- | --- | --- |
+| `cmd` | yes | One command per line, run in order in the sandbox. |
+| `exit` | no (default `0`) | Expected exit code of the last `cmd` line, as a decimal integer. |
+| `stdout` | no | Expected stdout, normalized. |
+| `stderr` | no | Expected stderr, normalized. |
+| `fixtures/<root>/<path>` | no | File written under that sandbox root before the run. |
+| `expected/<root>/<path>` | no | Expected content of that file after the run, normalized. |
+
+`<root>` is one of the spec's `roots`, and `<path>` must stay inside it — an absent root, a bare
+root with no path, or a path escaping through `..` is a malformed case.
+
+Any other section name is a hard error — the case is malformed and collection fails. Unknown
+sections are never ignored, so a typo (`stdOut`, `expect/cwd/x`) fails loudly instead of silently
+asserting nothing.
+
+Parent directories of a `fixtures/` path are created; an empty section creates an empty file.
+
+### Sandbox
+
+Each case runs in a fresh temporary directory holding one subdirectory per root in the spec. The
+spec's `env` mapping points the named environment variables at those directories, and the commands
+run in `cwd_root`.
+
+Fixtures are materialized into the roots, then the `cmd` lines run. Nothing outside the sandbox is
+read or written, and the sandbox is discarded after the case.
+
+### Commands
+
+Each `cmd` line is split with shell-like quoting and executed directly — there is no shell, so no
+pipes, redirection, globbing or variable expansion. A first word listed in the spec's `commands`
+mapping resolves to its configured binary path; any other first word is executed as given.
+
+With more than one line:
+
+- every line but the last must exit `0`; if one does not, the case fails;
+- the last line's exit code is compared against `exit`;
+- `stdout` and `stderr` are asserted against the concatenation of all lines' output, in order.
+
+All lines share one sandbox, so a case can chain commands that build on each other's writes.
+
+### Normalization
+
+Before comparison, both sides are rewritten so that volatile values do not leak into the expected
+text. Expected sections are written in normalized form.
+
+Absolute sandbox paths in captured output are replaced by each root's token — `{HOME}` for the
+`home` root by default, and whatever the spec's `tokens` mapping says otherwise.
+
+Comparison is line by line. Within a line, the literal `[..]` matches any run of characters,
+including none, and never crosses a line boundary — it covers commit hashes, timestamps and
+durations. A line without `[..]` must match exactly, whitespace included.
+
+Tokens and `[..]` apply to `stdout`, `stderr` and every `expected/` section. They are not expanded
+in `cmd` or `fixtures/`, which are taken literally.
+
+### Assertions
+
+- An absent section asserts nothing. A case with no `stderr` section does not require stderr to be
+  empty; a file with no `expected/` section is not checked.
+- An absent `exit` asserts exit `0`.
+- An `expected/` section for a file that does not exist fails the case.
+- Files created beyond those named by `expected/` are not flagged.
+- A failure that needs an unwritable path or another OS-level fault is not expressible — fixtures
+  carry content, not permissions.
+
+## Running
+
+Cases collect as ordinary pytest items, one per `*.txtar` file, whose nodeid is the case path:
+
+```
+pytest tests/cases
+pytest tests/cases -k smoke
+```
+
+Selection, parallelism, reporting and exit codes are pytest's. A failing case reports one labeled
+unified diff per mismatched section; a malformed case is a collection error.
+
+## Authoring a case
+
+Write the comment, `cmd` and `fixtures/` sections by hand, then let the runner fill in the rest:
+
+```
+pytest tests/cases/my-case.txtar --txtar-update
+```
+
+`--txtar-update` rewrites each selected case whose assertions do not hold — its `stdout`, `stderr`,
+`exit` and `expected/` sections come from the actual normalized run, `cmd` and `fixtures/` are left
+untouched — and lists the rewritten cases in the terminal summary. A case that already passes is
+never rewritten, so a holding `[..]` is not flattened into the run's literal text. Review the resulting diff as you would any other change —
+a baseline is only as good as the reading it got. Re-running `--txtar-update` on an unchanged
+corpus must produce no diff.
+
+## Worked example
+
+```txtar
+Initializes a project from the template named in the user's config.
+
+-- fixtures/xdg/mytool/config.yaml --
+template: minimal
+-- cmd --
+mytool init demo
+-- exit --
+0
+-- stdout --
+created demo/ from template minimal (config: {XDG}/mytool/config.yaml)
+-- expected/cwd/demo/mytool.yaml --
+template: minimal
+```
+
+The fixture lands at `<sandbox>/xdg/mytool/config.yaml`, which the spec's `XDG_CONFIG_HOME` binding
+makes the tool read as the user's config. The absolute path it echoes back is normalized to
+`{XDG}`, while `demo` is relative to the working directory and needs no token. The trailing
+`expected/cwd/` section asserts the file the run left behind.
+
+## License
+
+MIT. `src/pytest_txtar/txtar.py` is a port of `golang.org/x/tools/txtar` and carries the upstream
+BSD-3-Clause notice — see [LICENSE](LICENSE).

pytest_txtar-0.1.0/README.md

@@ -0,0 +1,188 @@
+# pytest-txtar
+
+Contract testing for command-line tools, driven by [txtar](https://pkg.go.dev/golang.org/x/tools/txtar)
+archives: one file per case carrying the fixture tree, the invocation, and everything asserted about
+the result — stdout, stderr, exit code, and files left behind.
+
+Each case runs in a fresh sandbox; paths that vary per run are normalized to tokens before
+comparison, and a golden-update flow rewrites assertions from the actual run.
+
+The package is layered: `pytest_txtar.txtar` parses the archive format, the pytest-free core
+(`case`, `sandbox`, `compare`, `update`) executes and compares cases parameterized by a
+`TxtarSpec`, and a pytest plugin collects `*.txtar` files as test items.
+
+Status: pre-release, under construction.
+
+## Configuration
+
+A consumer states what to run and where by implementing the `pytest_txtar_spec` hook in a
+`conftest.py` beside its cases:
+
+```python
+from pathlib import Path
+
+import pytest
+from pytest_txtar.case import TxtarSpec
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def pytest_txtar_spec(config: pytest.Config) -> TxtarSpec:
+    return TxtarSpec(
+        commands={"mytool": ROOT / "bin" / "mytool"},
+        roots=("home", "xdg", "cwd"),
+        cwd_root="cwd",
+        env={"HOME": "home", "XDG_CONFIG_HOME": "xdg"},
+    )
+```
+
+| Field | Meaning |
+| --- | --- |
+| `commands` | Command word → binary it resolves to, for the first word of a `cmd` line. |
+| `roots` | Sandbox subdirectories a case may address under `fixtures/` and `expected/`. |
+| `cwd_root` | The root the commands run in. |
+| `env` | Environment variable → the root it is pointed at, on top of the ambient environment. |
+| `tokens` | Root → normalization token; defaults to the upper-cased root in braces. |
+
+The `home`/`xdg`/`cwd` roots above are one configuration, not a fixed set: a spec may name any roots
+and bind any variables to them.
+
+## Case format
+
+This section defines the behavior; the package implements it. A runner in another language is
+conformant when it agrees with everything below.
+
+### Container — txtar
+
+An archive is a leading comment followed by file sections. A section starts with a marker line
+`-- name --`; everything up to the next marker line is its content.
+
+- The marker line is exactly `--`, a space, the name, a space, `--`. Surrounding whitespace in the
+  name is stripped; a name may contain `/`.
+- A line whose name would be empty (`--  --`) is content, not a marker.
+- Content that does not end in a newline is treated as if it did. A well-formed archive therefore
+  round-trips byte-exactly through parse and serialize.
+- A section name may appear only once per case; a repeat is a malformed case.
+- There are no other syntax errors: any byte sequence parses.
+
+### Sections
+
+| Section | Required | Meaning |
+| --- | --- | --- |
+| `cmd` | yes | One command per line, run in order in the sandbox. |
+| `exit` | no (default `0`) | Expected exit code of the last `cmd` line, as a decimal integer. |
+| `stdout` | no | Expected stdout, normalized. |
+| `stderr` | no | Expected stderr, normalized. |
+| `fixtures/<root>/<path>` | no | File written under that sandbox root before the run. |
+| `expected/<root>/<path>` | no | Expected content of that file after the run, normalized. |
+
+`<root>` is one of the spec's `roots`, and `<path>` must stay inside it — an absent root, a bare
+root with no path, or a path escaping through `..` is a malformed case.
+
+Any other section name is a hard error — the case is malformed and collection fails. Unknown
+sections are never ignored, so a typo (`stdOut`, `expect/cwd/x`) fails loudly instead of silently
+asserting nothing.
+
+Parent directories of a `fixtures/` path are created; an empty section creates an empty file.
+
+### Sandbox
+
+Each case runs in a fresh temporary directory holding one subdirectory per root in the spec. The
+spec's `env` mapping points the named environment variables at those directories, and the commands
+run in `cwd_root`.
+
+Fixtures are materialized into the roots, then the `cmd` lines run. Nothing outside the sandbox is
+read or written, and the sandbox is discarded after the case.
+
+### Commands
+
+Each `cmd` line is split with shell-like quoting and executed directly — there is no shell, so no
+pipes, redirection, globbing or variable expansion. A first word listed in the spec's `commands`
+mapping resolves to its configured binary path; any other first word is executed as given.
+
+With more than one line:
+
+- every line but the last must exit `0`; if one does not, the case fails;
+- the last line's exit code is compared against `exit`;
+- `stdout` and `stderr` are asserted against the concatenation of all lines' output, in order.
+
+All lines share one sandbox, so a case can chain commands that build on each other's writes.
+
+### Normalization
+
+Before comparison, both sides are rewritten so that volatile values do not leak into the expected
+text. Expected sections are written in normalized form.
+
+Absolute sandbox paths in captured output are replaced by each root's token — `{HOME}` for the
+`home` root by default, and whatever the spec's `tokens` mapping says otherwise.
+
+Comparison is line by line. Within a line, the literal `[..]` matches any run of characters,
+including none, and never crosses a line boundary — it covers commit hashes, timestamps and
+durations. A line without `[..]` must match exactly, whitespace included.
+
+Tokens and `[..]` apply to `stdout`, `stderr` and every `expected/` section. They are not expanded
+in `cmd` or `fixtures/`, which are taken literally.
+
+### Assertions
+
+- An absent section asserts nothing. A case with no `stderr` section does not require stderr to be
+  empty; a file with no `expected/` section is not checked.
+- An absent `exit` asserts exit `0`.
+- An `expected/` section for a file that does not exist fails the case.
+- Files created beyond those named by `expected/` are not flagged.
+- A failure that needs an unwritable path or another OS-level fault is not expressible — fixtures
+  carry content, not permissions.
+
+## Running
+
+Cases collect as ordinary pytest items, one per `*.txtar` file, whose nodeid is the case path:
+
+```
+pytest tests/cases
+pytest tests/cases -k smoke
+```
+
+Selection, parallelism, reporting and exit codes are pytest's. A failing case reports one labeled
+unified diff per mismatched section; a malformed case is a collection error.
+
+## Authoring a case
+
+Write the comment, `cmd` and `fixtures/` sections by hand, then let the runner fill in the rest:
+
+```
+pytest tests/cases/my-case.txtar --txtar-update
+```
+
+`--txtar-update` rewrites each selected case whose assertions do not hold — its `stdout`, `stderr`,
+`exit` and `expected/` sections come from the actual normalized run, `cmd` and `fixtures/` are left
+untouched — and lists the rewritten cases in the terminal summary. A case that already passes is
+never rewritten, so a holding `[..]` is not flattened into the run's literal text. Review the resulting diff as you would any other change —
+a baseline is only as good as the reading it got. Re-running `--txtar-update` on an unchanged
+corpus must produce no diff.
+
+## Worked example
+
+```txtar
+Initializes a project from the template named in the user's config.
+
+-- fixtures/xdg/mytool/config.yaml --
+template: minimal
+-- cmd --
+mytool init demo
+-- exit --
+0
+-- stdout --
+created demo/ from template minimal (config: {XDG}/mytool/config.yaml)
+-- expected/cwd/demo/mytool.yaml --
+template: minimal
+```
+
+The fixture lands at `<sandbox>/xdg/mytool/config.yaml`, which the spec's `XDG_CONFIG_HOME` binding
+makes the tool read as the user's config. The absolute path it echoes back is normalized to
+`{XDG}`, while `demo` is relative to the working directory and needs no token. The trailing
+`expected/cwd/` section asserts the file the run left behind.
+
+## License
+
+MIT. `src/pytest_txtar/txtar.py` is a port of `golang.org/x/tools/txtar` and carries the upstream
+BSD-3-Clause notice — see [LICENSE](LICENSE).

pytest_txtar-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "pytest-txtar"
+version = "0.1.0"
+description = "Txtar-driven contract testing for command-line tools: sandboxed runs, normalized assertions, golden update."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["pytest>=8"]
+
+[project.entry-points.pytest11]
+pytest_txtar = "pytest_txtar.plugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pytest_txtar"]
+
+[dependency-groups]
+dev = [
+    "ruff",
+    "basedpyright",
+]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.basedpyright]
+include = ["src", "tests"]
+extraPaths = ["src"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"

pytest_txtar-0.1.0/src/pytest_txtar/case.py

@@ -0,0 +1,101 @@
+"""Case model: the spec a consumer supplies, and loading a case file into it."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pytest_txtar import txtar
+
+
+class CaseError(Exception):
+    """A malformed case file."""
+
+
+@dataclass(frozen=True)
+class TxtarSpec:
+    """What a consumer must state to run cases: the tool, the sandbox, the tokens.
+
+    ``commands`` maps a command word appearing first on a ``cmd`` line to the
+    binary it stands for. ``roots`` names the sandbox subdirectories a case may
+    address under ``fixtures/`` and ``expected/``; the process runs in
+    ``cwd_root``, and ``env`` maps an environment variable to the root it points
+    at. ``tokens`` maps a root to the token its path is normalized to, defaulting
+    to the upper-cased root in braces.
+    """
+
+    commands: Mapping[str, Path]
+    roots: tuple[str, ...]
+    cwd_root: str
+    env: Mapping[str, str] = field(default_factory=dict[str, str])
+    tokens: Mapping[str, str] | None = None
+
+    @property
+    def token_map(self) -> Mapping[str, str]:
+        if self.tokens is not None:
+            return self.tokens
+        return {root: "{" + root.upper() + "}" for root in self.roots}
+
+
+@dataclass
+class Case:
+    path: Path
+    archive: txtar.Archive
+    cmd: list[str]
+    exit_code: int = 0
+    stdout: str | None = None
+    stderr: str | None = None
+    fixtures: list[tuple[str, str]] = field(default_factory=list)
+    expected: list[tuple[str, str]] = field(default_factory=list)
+
+
+def load_case(path: Path, spec: TxtarSpec) -> Case:
+    try:
+        archive = txtar.parse(path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        raise CaseError(str(exc)) from exc
+
+    case = Case(path=path, archive=archive, cmd=[])
+    seen_cmd = False
+    for name, data in archive.files:
+        if name == "cmd":
+            case.cmd = [line for line in data.splitlines() if line.strip()]
+            seen_cmd = True
+        elif name == "exit":
+            case.exit_code = parse_exit(data)
+        elif name == "stdout":
+            case.stdout = data
+        elif name == "stderr":
+            case.stderr = data
+        elif name.startswith("fixtures/"):
+            case.fixtures.append((check_tree_path(name, spec.roots), data))
+        elif name.startswith("expected/"):
+            case.expected.append((check_tree_path(name, spec.roots), data))
+        else:
+            raise CaseError(f"unknown section: {name}")
+
+    if not seen_cmd:
+        raise CaseError("missing section: cmd")
+    if not case.cmd:
+        raise CaseError("empty section: cmd")
+    return case
+
+
+def parse_exit(data: str) -> int:
+    text = data.strip()
+    try:
+        return int(text)
+    except ValueError as exc:
+        raise CaseError(f"exit is not an integer: {text!r}") from exc
+
+
+def check_tree_path(name: str, roots: tuple[str, ...]) -> str:
+    prefix, _, rest = name.partition("/")
+    root, _, relative = rest.partition("/")
+    if root not in roots or not relative:
+        listed = ", ".join(f"{root}/" for root in roots)
+        raise CaseError(f"{prefix}/ path must start with one of {listed}: {name}")
+    if ".." in Path(relative).parts or Path(relative).is_absolute():
+        raise CaseError(f"{prefix}/ path escapes its root: {name}")
+    return name