worktree-shield 0.1.0__py3-none-any.whl

worktree_shield/collisions.py

@@ -0,0 +1,115 @@
+"""The collision graph: claims of different worktrees on overlapping resources.
+
+Pure: claims in, collisions out. Keys of one kind are joined when any two of them
+overlap (:func:`~worktree_shield.overlap.overlap`), so ``0.0.0.0:8000`` links
+``127.0.0.1:8000`` and ``127.0.0.2:8000`` into one collision even though those two do
+not overlap each other. A group claimed by one worktree only is no collision.
+
+Certainty
+    *confirmed* when a running server (a runtime claim) of one worktree certainly holds
+    what another worktree's configuration needs; *probable* when the configured
+    resources certainly overlap; *possible* when the overlap depends on how a name
+    resolves or how a path is used, or when every server involved moves to the next free
+    port (Vite without ``strictPort``). Static evidence alone never confirms.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from itertools import combinations
+
+from worktree_shield.models import (
+    Certainty,
+    Collision,
+    Observation,
+    ResourceClaim,
+    ResourceKind,
+)
+from worktree_shield.overlap import Overlap, overlap
+
+_KIND_ORDER = {kind: index for index, kind in enumerate(ResourceKind)}
+
+
+def find_collisions(
+    claims: tuple[ResourceClaim, ...] | list[ResourceClaim],
+) -> tuple[Collision, ...]:
+    """Every collision among ``claims``, ordered by kind and key."""
+    by_kind: dict[ResourceKind, list[ResourceClaim]] = defaultdict(list)
+    for claim in claims:
+        if claim.kind is not ResourceKind.CLIENT_ENDPOINT:
+            by_kind[claim.kind].append(claim)
+    found: list[Collision] = []
+    for kind, members in by_kind.items():
+        for group in _groups(kind, members):
+            if len({claim.worktree for claim in group}) > 1:
+                found.append(_collision(kind, group))
+    return tuple(sorted(found, key=lambda c: (_KIND_ORDER[c.kind], c.key)))
+
+
+def _groups(kind: ResourceKind, claims: list[ResourceClaim]) -> list[list[ResourceClaim]]:
+    """Claims joined by overlapping keys (connected components over the keys)."""
+    keys = sorted({claim.key for claim in claims})
+    parent = {key: key for key in keys}
+
+    def root(key: str) -> str:
+        while parent[key] != key:
+            parent[key] = parent[parent[key]]
+            key = parent[key]
+        return key
+
+    for a, b in combinations(keys, 2):
+        if overlap(kind, a, b) is not Overlap.NONE:
+            parent[root(a)] = root(b)
+    groups: dict[str, list[ResourceClaim]] = defaultdict(list)
+    for claim in claims:
+        groups[root(claim.key)].append(claim)
+    return list(groups.values())
+
+
+def _collision(kind: ResourceKind, claims: list[ResourceClaim]) -> Collision:
+    pairs = [
+        (a, b, overlap(kind, a.key, b.key))
+        for a, b in combinations(claims, 2)
+        if a.worktree != b.worktree
+    ]
+    certain = [(a, b) for a, b, result in pairs if result is Overlap.SAME]
+    if any(Observation.RUNTIME in (a.observation, b.observation) for a, b in certain):
+        certainty = Certainty.CONFIRMED
+    elif not certain or (
+        kind is ResourceKind.LISTEN_PORT and all(c.strict is False for c in claims)
+    ):
+        certainty = Certainty.POSSIBLE
+    else:
+        certainty = Certainty.PROBABLE
+    key = min(claim.key for claim in claims)
+    worktrees = len({claim.worktree for claim in claims})
+    return Collision(kind, key, certainty, _reason(kind, key, worktrees, claims), tuple(claims))
+
+
+def _reason(kind: ResourceKind, key: str, worktrees: int, claims: list[ResourceClaim]) -> str:
+    name = key.split("://", 1)[-1]
+    count = f"{worktrees} worktrees"
+    if kind is ResourceKind.LISTEN_PORT:
+        port = name.rpartition(":")[2]
+        reason = f"{count} start a server on port {port}; only one can listen on it at a time"
+        if all(claim.strict is False for claim in claims):
+            reason += ", but Vite moves to the next free port unless strictPort is set"
+        return reason
+    if kind is ResourceKind.DATABASE:
+        return (
+            f"{count} use the same database; migrations, seed data and tests of one "
+            "change the data of the other"
+        )
+    if kind is ResourceKind.COMPOSE_PROJECT:
+        return (
+            f"{count} have the Compose project name {name}; docker compose up in one "
+            "takes over the containers, networks and volumes of the other"
+        )
+    if kind is ResourceKind.CONTAINER_NAME:
+        return (
+            f"{count} name a container {name}; a Docker daemon runs one container of that "
+            "name, so starting the second stack replaces or fails on the first"
+        )
+    if kind is ResourceKind.VOLUME:
+        return f"{count} mount the Docker volume {name}, so they read and write the same data"
+    return f"{count} write to {name} or a directory inside it"

worktree_shield/config.py

@@ -0,0 +1,188 @@
+"""The repository policy, ``.worktree-shield.toml``: TOML read as data, never run.
+
+Precedence is flags, then the file in the current worktree, then the defaults in
+:class:`~worktree_shield.models.Policy`; there is no user-wide policy. Anything the
+parser does not know is an error rather than a silent default, so a misspelt key cannot
+quietly turn a ``deny`` back into a ``warn``.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import tomllib
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import Any
+
+from worktree_shield.files import RefusedError, read_text_inside
+from worktree_shield.models import Policy, PolicyLevel, Repository
+
+POLICY_FILE = ".worktree-shield.toml"
+MAX_POLICY_BYTES = 64 * 1024
+SCHEMA_VERSION = 1
+MAX_FILE_BYTES_LIMIT = 16 * 1024 * 1024
+
+_SCAN_FLAGS = ("include_runtime", "include_env_files")
+_LEVELS = (
+    "shared_host_ports",
+    "shared_database",
+    "shared_compose_projects",
+    "fixed_container_names",
+    "shared_absolute_paths",
+)
+_SECTIONS: dict[str, tuple[str, ...]] = {
+    "scan": (*_SCAN_FLAGS, "max_file_bytes"),
+    "policy": _LEVELS,
+    "allow": ("ports", "paths"),
+}
+
+
+class PolicyError(Exception):
+    """The policy file cannot be used; the message names the file and the problem."""
+
+
+def parse_policy(text: str, source: str) -> Policy:
+    """The policy in ``text``; ``source`` names the file in messages and in the result."""
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise PolicyError(f"{source} is not valid TOML: {error}") from None
+    try:
+        return _policy(data, source)
+    except _Invalid as error:
+        raise PolicyError(f"{source}: {error}") from None
+
+
+def load_policy(worktree: Path) -> Policy:
+    """The policy of a worktree, or the defaults when it has no policy file.
+
+    The file must be a regular file inside the worktree (a link may point elsewhere in
+    it) and at most :data:`MAX_POLICY_BYTES` long.
+    """
+    path = worktree / POLICY_FILE
+    try:
+        text = read_text_inside(worktree, POLICY_FILE, MAX_POLICY_BYTES)
+    except RefusedError as error:
+        raise PolicyError(f"{path} {error}") from None
+    if text is None:
+        return Policy()
+    return parse_policy(text, str(path))
+
+
+def policy_of(repository: Repository) -> Policy:
+    """The policy of the current worktree; a bare repository has the defaults only."""
+    if repository.current is None:
+        return Policy()
+    return load_policy(Path(repository.current))
+
+
+def apply_overrides(
+    policy: Policy,
+    *,
+    include_runtime: bool | None = None,
+    include_env_files: bool | None = None,
+) -> Policy:
+    """The policy with the settings given on the command line; ``None`` keeps the file's."""
+    changes: dict[str, Any] = {}
+    if include_runtime is not None:
+        changes["include_runtime"] = include_runtime
+    if include_env_files is not None:
+        changes["include_env_files"] = include_env_files
+    return dataclasses.replace(policy, **changes) if changes else policy
+
+
+class _Invalid(Exception):
+    pass
+
+
+def _policy(data: dict[str, Any], source: str) -> Policy:
+    for key, value in data.items():
+        if key == "schema_version":
+            continue
+        if key not in _SECTIONS:
+            unknown = f"section [{key}]" if isinstance(value, dict) else f"key {key}"
+            raise _Invalid(f"unknown {unknown}")
+        if not isinstance(value, dict):
+            raise _Invalid(f"{key} must be a section, written [{key}]")
+        for name in value:
+            if name not in _SECTIONS[key]:
+                raise _Invalid(f"unknown key {key}.{name}")
+    _schema_version(data)
+    scan = data.get("scan", {})
+    levels = data.get("policy", {})
+    allow = data.get("allow", {})
+    settings: dict[str, Any] = {name: _flag(scan, name) for name in _SCAN_FLAGS if name in scan}
+    if "max_file_bytes" in scan:
+        settings["max_file_bytes"] = _max_file_bytes(scan["max_file_bytes"])
+    settings |= {name: _level(levels, name) for name in _LEVELS if name in levels}
+    if "ports" in allow:
+        settings["allow_ports"] = _ports(allow["ports"])
+    if "paths" in allow:
+        settings["allow_paths"] = _paths(allow["paths"])
+    return Policy(**settings, source=source)
+
+
+def _schema_version(data: dict[str, Any]) -> None:
+    if "schema_version" not in data:
+        raise _Invalid(
+            f"schema_version is missing; start the file with schema_version = {SCHEMA_VERSION}"
+        )
+    version = data["schema_version"]
+    if not _is_int(version):
+        raise _Invalid(f"schema_version must be the number {SCHEMA_VERSION}, not {_shown(version)}")
+    if version != SCHEMA_VERSION:
+        raise _Invalid(
+            f"schema_version {version} is not supported; this version reads {SCHEMA_VERSION}"
+        )
+
+
+def _flag(section: dict[str, Any], name: str) -> bool:
+    value = section[name]
+    if not isinstance(value, bool):
+        raise _Invalid(f"scan.{name} must be true or false, not {_shown(value)}")
+    return value
+
+
+def _max_file_bytes(value: Any) -> int:
+    if not _is_int(value) or not 1 <= value <= MAX_FILE_BYTES_LIMIT:
+        raise _Invalid(
+            f"scan.max_file_bytes must be a whole number from 1 to {MAX_FILE_BYTES_LIMIT}, "
+            f"not {_shown(value)}"
+        )
+    result: int = value
+    return result
+
+
+def _level(section: dict[str, Any], name: str) -> PolicyLevel:
+    value = section[name]
+    allowed = ", ".join(level.value for level in PolicyLevel)
+    if not isinstance(value, str) or value not in {level.value for level in PolicyLevel}:
+        raise _Invalid(f"policy.{name} must be one of {allowed}, not {_shown(value)}")
+    return PolicyLevel(value)
+
+
+def _ports(value: Any) -> tuple[int, ...]:
+    if not isinstance(value, list) or not all(_is_int(p) and 1 <= p <= 65535 for p in value):
+        raise _Invalid("allow.ports must be port numbers from 1 to 65535 in a list, like [5432]")
+    return tuple(sorted(set(value)))
+
+
+def _paths(value: Any) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(_is_absolute(p) for p in value):
+        raise _Invalid('allow.paths must be absolute paths in a list, like ["/srv/cache"]')
+    return tuple(dict.fromkeys(value))
+
+
+def _is_int(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _is_absolute(value: Any) -> bool:
+    if not isinstance(value, str) or any(ord(c) < 32 or ord(c) == 127 for c in value):
+        return False
+    return PurePosixPath(value).is_absolute() or PureWindowsPath(value).is_absolute()
+
+
+def _shown(value: Any) -> str:
+    """A value from the file for a message: repr() escapes control characters."""
+    shown = repr(value)
+    return shown if len(shown) <= 40 else shown[:39] + "…"

worktree_shield/exit_codes.py

@@ -0,0 +1,22 @@
+"""Exit codes are a contract: scripts and CI jobs depend on them."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    """The scan ran. Findings, even failing ones, do not change this."""
+
+    STRICT_FAILURE = 1
+    """``--strict`` was given and a finding reached the policy's fail level (``deny``)."""
+
+    ERROR = 2
+    """Wrong usage, or the tool itself failed."""
+
+    CONTEXT_UNAVAILABLE = 3
+    """Something the command needs is missing, e.g. the directory is not in a Git repository."""
+
+    INTERRUPTED = 130
+    """Stopped with Ctrl+C (128 + SIGINT, as shells report it)."""

worktree_shield/files.py

@@ -0,0 +1,70 @@
+"""Reading a configuration file of a worktree, and nothing outside it.
+
+Every file worktree-shield reads from a repository goes through :func:`read_inside`:
+links may point elsewhere in the worktree but not out of it, only regular files are
+opened (a named pipe would block, a device could be endless), and a file larger than
+the cap is refused rather than read in part, since half a file can mean something else.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+_FLAGS = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_NOFOLLOW", 0)
+_FLAGS |= getattr(os, "O_BINARY", 0)
+
+
+class RefusedError(Exception):
+    """The file exists but was not read; ``str()`` completes "<path> …" for a report."""
+
+
+def read_inside(root: Path, relative: str | Path, max_bytes: int) -> bytes | None:
+    """The bytes of ``root / relative``, or ``None`` when there is no such file.
+
+    Raises :class:`RefusedError` when the file must not be read: a link out of ``root``,
+    not a regular file, larger than ``max_bytes`` or unreadable.
+    """
+    path = root / relative
+    if not os.path.lexists(path):
+        return None
+    try:
+        target = path.resolve(strict=True)
+        if not target.is_relative_to(root.resolve(strict=True)):
+            raise RefusedError("is a link to a file outside the worktree")
+        if not stat.S_ISREG(target.stat().st_mode):  # Windows cannot open() a directory
+            raise RefusedError("is not a regular file")
+        # Checked again on what was opened: a file swapped for a pipe after the check
+        # cannot block (O_NONBLOCK) and is refused by fstat().
+        fd = os.open(target, _FLAGS)
+    except FileNotFoundError:
+        raise RefusedError("could not be read (a link to a file that does not exist)") from None
+    except OSError as error:
+        raise RefusedError(f"could not be read ({error.strerror or error})") from None
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise RefusedError("is not a regular file")
+        chunks: list[bytes] = []
+        size = 0
+        while size <= max_bytes and (chunk := os.read(fd, max_bytes + 1 - size)):
+            chunks.append(chunk)
+            size += len(chunk)
+    except OSError as error:
+        raise RefusedError(f"could not be read ({error.strerror or error})") from None
+    finally:
+        os.close(fd)
+    if size > max_bytes:
+        raise RefusedError(f"is larger than {max_bytes} bytes")
+    return b"".join(chunks)
+
+
+def read_text_inside(root: Path, relative: str | Path, max_bytes: int) -> str | None:
+    """Like :func:`read_inside`, decoded as UTF-8 (a byte order mark is dropped)."""
+    raw = read_inside(root, relative, max_bytes)
+    if raw is None:
+        return None
+    try:
+        return raw.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        raise RefusedError("is not UTF-8 text") from None

worktree_shield/git/__init__.py

@@ -0,0 +1 @@
+"""Reading the repository through Git's machine-readable interfaces, never changing it."""

worktree_shield/git/discovery.py

@@ -0,0 +1,85 @@
+"""Find the repository and its worktrees, without changing anything in ``.git``.
+
+Every git command runs as ``git -c core.fsmonitor=false -C <dir> …`` with
+``GIT_OPTIONAL_LOCKS=0`` (no index refresh, so no ``index.lock``),
+``GIT_TERMINAL_PROMPT=0`` (never wait for credentials) and ``LC_ALL=C``. Disabling the
+fsmonitor stops a repository-configured program from being run. Only ``rev-parse``
+and ``worktree list`` are used; nothing is pruned, repaired or locked.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from worktree_shield.git.porcelain import PorcelainError, parse_worktree_list
+from worktree_shield.models import FailureKind, ProbeFailure, Repository
+from worktree_shield.runner import CommandResult, CommandRunner, probe_failure
+
+GIT_TIMEOUT = 10.0
+"""Seconds; worktree listing reads a few small files."""
+
+GIT_ENV = {"GIT_OPTIONAL_LOCKS": "0", "GIT_TERMINAL_PROMPT": "0", "LC_ALL": "C"}
+
+
+class NotARepositoryError(Exception):
+    """The directory is not inside a Git repository (exit code 3, not a failure)."""
+
+
+def git_argv(directory: Path, *args: str) -> list[str]:
+    return ["git", "-c", "core.fsmonitor=false", "-C", str(directory), *args]
+
+
+def _git(runner: CommandRunner, directory: Path, *args: str) -> CommandResult:
+    return runner.run(git_argv(directory, *args), timeout=GIT_TIMEOUT, env_overrides=GIT_ENV)
+
+
+def discover(
+    runner: CommandRunner, start: Path
+) -> tuple[Repository | None, tuple[ProbeFailure, ...]]:
+    """The repository containing ``start`` and all its worktrees.
+
+    Raises :class:`NotARepositoryError` when ``start`` is not in a repository; any
+    other problem (git missing, a repository owned by another user, a timeout) is a
+    ProbeFailure and no repository.
+    """
+    result = _git(
+        runner,
+        start,
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-common-dir",
+        "--is-bare-repository",
+    )
+    if not result.ok and "not a git repository" in result.stderr:
+        raise NotARepositoryError(result.stderr.strip().splitlines()[0])
+    failure = probe_failure("git rev-parse", result)
+    if failure is not None:
+        return None, (failure,)
+    lines = result.stdout.splitlines()
+    if len(lines) != 2 or lines[1] not in {"true", "false"}:
+        return None, (_malformed("git rev-parse", "expected the common directory and true/false"),)
+    common_dir, bare = lines[0], lines[1] == "true"
+
+    current: str | None = None
+    if not bare:
+        result = _git(runner, start, "rev-parse", "--path-format=absolute", "--show-toplevel")
+        failure = probe_failure("git rev-parse --show-toplevel", result)
+        if failure is not None:
+            return None, (failure,)
+        current = result.stdout.strip() or None
+
+    result = _git(runner, start, "worktree", "list", "--porcelain", "-z")
+    failure = probe_failure("git worktree list", result)
+    if failure is not None:
+        return None, (failure,)
+    if result.stdout_truncated:
+        return None, (_malformed("git worktree list", "the list was longer than the output cap"),)
+    try:
+        worktrees = parse_worktree_list(result.stdout)
+    except PorcelainError as exc:
+        return None, (_malformed("git worktree list", str(exc)),)
+    return Repository(common_dir, current, bare, worktrees), ()
+
+
+def _malformed(probe: str, detail: str) -> ProbeFailure:
+    return ProbeFailure(probe, FailureKind.MALFORMED_OUTPUT, detail)

worktree_shield/git/porcelain.py

@@ -0,0 +1,48 @@
+"""Parse ``git worktree list --porcelain -z``.
+
+With ``-z`` every attribute ends with NUL and every record with one more NUL, so paths
+with spaces, newlines or any other byte except NUL come through intact. This is the
+format Git documents as stable for scripts; the human-readable list is never parsed.
+"""
+
+from __future__ import annotations
+
+from worktree_shield.models import Worktree
+
+
+class PorcelainError(ValueError):
+    """The output is not a worktree list."""
+
+
+def parse_worktree_list(text: str) -> tuple[Worktree, ...]:
+    """The worktrees in Git's order: the main worktree first, then the linked ones.
+
+    Unknown attributes are skipped, so a newer Git that adds one does not break the
+    scan. A record without a ``worktree`` line is an error.
+    """
+    worktrees: list[Worktree] = []
+    for record in text.split("\0\0"):
+        attributes = [item for item in record.split("\0") if item]
+        if not attributes:
+            continue
+        name, _, path = attributes[0].partition(" ")
+        if name != "worktree" or not path:
+            raise PorcelainError(f"a record starts with {name!r}, not 'worktree <path>'")
+        head = branch = locked = prunable = None
+        bare = detached = False
+        for attribute in attributes[1:]:
+            key, space, value = attribute.partition(" ")
+            if key == "HEAD":
+                head = value or None
+            elif key == "branch":
+                branch = value or None
+            elif key == "bare":
+                bare = True
+            elif key == "detached":
+                detached = True
+            elif key == "locked":
+                locked = value if space else ""
+            elif key == "prunable":
+                prunable = value if space else ""
+        worktrees.append(Worktree(path, head, branch, bare, detached, locked, prunable))
+    return tuple(worktrees)