worktree-shield 0.1.0__py3-none-any.whl

worktree_shield/collectors/procfile.py

@@ -0,0 +1,134 @@
+"""Listen ports in Procfiles and dev containers.
+
+``Procfile`` and ``Procfile.dev`` (foreman, honcho, Heroku, Rails ``bin/dev``) hold one
+``name: command`` per line; each command is scanned by
+:func:`~worktree_shield.parsers.commands.listen_ports` and never run.
+
+A dev container (``.devcontainer/devcontainer.json`` or ``.devcontainer.json``) can
+publish ``appPort`` on the host, which fails when the port is taken, and forward
+``forwardPorts`` to this machine, which the editor moves to another local port when it
+is taken: those claims are not strict.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import PurePosixPath
+from typing import Any
+
+from worktree_shield.collectors.base import Collected, Scope, port_key
+from worktree_shield.models import ResourceClaim, ResourceKind, SkippedFile
+from worktree_shield.names import port_number
+from worktree_shield.parsers.commands import listen_ports
+from worktree_shield.parsers.jsonc import strip_jsonc
+
+PROCFILES = ("Procfile", "Procfile.dev")
+DEVCONTAINERS = (".devcontainer/devcontainer.json", ".devcontainer.json")
+_PROCESS = re.compile(r"([A-Za-z0-9_-]+):\s*(.+)")
+
+
+def collect_procfiles(scope: Scope, directory: PurePosixPath, out: Collected) -> None:
+    """The listen ports of every process in the Procfiles of ``directory``."""
+    for name in PROCFILES:
+        relative = directory / name
+        text = scope.read(relative, out)
+        if text is None:
+            continue
+        for number, line in enumerate(text.splitlines(), start=1):
+            match = _PROCESS.fullmatch(line.strip())
+            if match is None or line.lstrip().startswith("#"):
+                continue
+            process, command = match.groups()
+            for mention in listen_ports(command):
+                out.claims.append(
+                    ResourceClaim(
+                        ResourceKind.LISTEN_PORT,
+                        port_key(mention.host, mention.port),
+                        scope.worktree,
+                        scope.source(relative, number),
+                        f"{name} {process}: {mention.fragment}",
+                        strict=mention.strict,
+                    )
+                )
+
+
+def collect_devcontainer(scope: Scope, directory: PurePosixPath, out: Collected) -> None:
+    """The ports a dev container in ``directory`` publishes or forwards."""
+    for name in DEVCONTAINERS:
+        relative = directory / name
+        text = scope.read(relative, out)
+        if text is None:
+            continue
+        plain = strip_jsonc(text)
+        try:
+            data = json.loads(plain)
+        except json.JSONDecodeError as error:
+            out.skipped.append(
+                SkippedFile(scope.source(relative, error.lineno), "is not valid JSON")
+            )
+            continue
+        if not isinstance(data, dict):
+            continue
+        finder = _Lines(plain)
+        for key, strict in (("forwardPorts", False), ("appPort", True)):
+            entries = _entries(data.get(key), single_allowed=key == "appPort")
+            start = finder.key(key)
+            for entry in entries:
+                port = _port(entry, published=strict)
+                if port is None:
+                    continue
+                host = "localhost" if key == "forwardPorts" else None
+                out.claims.append(
+                    ResourceClaim(
+                        ResourceKind.LISTEN_PORT,
+                        port_key(host, port),
+                        scope.worktree,
+                        scope.source(relative, finder.value(entry, start)),
+                        f"{key}: {entry}",
+                        strict=strict,
+                    )
+                )
+
+
+def _entries(value: Any, *, single_allowed: bool) -> list[Any]:
+    """The entries of a port list; appPort may also be a single port (the spec says so,
+    forwardPorts must be an array)."""
+    if isinstance(value, list):
+        return value
+    return [value] if single_allowed and value is not None else []
+
+
+def _port(entry: Any, *, published: bool) -> int | None:
+    """The local port of a forwardPorts or appPort entry: ``3000``, ``"db:5432"``
+    (forwarded service port) or ``"8080:80"`` (published host:container)."""
+    if isinstance(entry, bool):
+        return None
+    if isinstance(entry, int):
+        return port_number(str(entry))
+    if isinstance(entry, str):
+        first, _, second = entry.partition(":")
+        if not second:
+            return port_number(first)
+        return port_number(first if published else second)
+    return None
+
+
+class _Lines:
+    """Lines of keys and array values in already parsed JSON text, found in order."""
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self.position = 0
+
+    def key(self, key: str) -> int:
+        match = re.search(re.escape(json.dumps(key)) + r"\s*:", self.text)
+        return match.end() if match else len(self.text)
+
+    def value(self, entry: Any, start: int) -> int | None:
+        literal = re.escape(json.dumps(entry)) if isinstance(entry, str) else rf"\b{entry}\b"
+        match = re.compile(literal).search(self.text, max(start, self.position))
+        if match is None:
+            return None
+        self.position = match.end()
+        return self.text.count("\n", 0, match.start()) + 1

worktree_shield/collectors/python.py

@@ -0,0 +1,128 @@
+"""Listen ports in the task runners of ``pyproject.toml``: poe, taskipy, pdm, hatch, rye.
+
+The file is parsed with :mod:`tomllib`; task commands are scanned as text by
+:func:`~worktree_shield.parsers.commands.listen_ports` and never run. Script tasks that
+call Python functions (``script = "api:main"``) are not commands and are skipped. A
+task's ``env`` table counts like a ``PORT=…`` prefix.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+import tomllib
+from collections.abc import Iterator
+from pathlib import PurePosixPath
+from typing import Any
+
+from worktree_shield.collectors.base import Collected, Scope, port_key
+from worktree_shield.models import ResourceClaim, ResourceKind, SkippedFile
+from worktree_shield.names import port_number, port_variable
+from worktree_shield.parsers.commands import PortMention, listen_ports
+
+_MAX_DEPTH = 8  # sequences of sequences; real projects use two levels at most
+_COMMAND_KEYS = ("cmd", "shell")
+_SEQUENCE_KEYS = ("sequence", "composite", "chain")
+
+
+def collect_pyproject(scope: Scope, directory: PurePosixPath, out: Collected) -> None:
+    """The listen ports in the task runners of ``directory/pyproject.toml``."""
+    relative = directory / "pyproject.toml"
+    text = scope.read(relative, out)
+    if text is None:
+        return
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError:
+        out.skipped.append(SkippedFile(scope.source(relative), "is not valid TOML"))
+        return
+    found: list[ResourceClaim] = []
+    for section, tasks in _task_tables(data):
+        for name, task in tasks.items():
+            line = _line(text, section, name)
+            label = ".".join((*section, name))
+            for mention in _mentions(task, 0):
+                found.append(
+                    ResourceClaim(
+                        ResourceKind.LISTEN_PORT,
+                        port_key(mention.host, mention.port),
+                        scope.worktree,
+                        scope.source(relative, line),
+                        f"{label}: {mention.fragment}",
+                        strict=mention.strict,
+                    )
+                )
+    # In file order, whichever runner comes first; tasks without a known line last.
+    out.claims += sorted(found, key=lambda claim: claim.source.line or len(text) + 1)
+
+
+def _task_tables(data: dict[str, Any]) -> Iterator[tuple[tuple[str, ...], dict[str, Any]]]:
+    tool = data.get("tool")
+    if not isinstance(tool, dict):
+        return
+    for runner, key in (
+        ("poe", "tasks"),
+        ("taskipy", "tasks"),
+        ("pdm", "scripts"),
+        ("rye", "scripts"),
+    ):
+        table = tool.get(runner)
+        if isinstance(table, dict) and isinstance(table.get(key), dict):
+            yield ("tool", runner, key), table[key]
+    hatch = tool.get("hatch")
+    envs = hatch.get("envs") if isinstance(hatch, dict) else None
+    if isinstance(envs, dict):
+        for env, settings in envs.items():
+            if isinstance(settings, dict) and isinstance(settings.get("scripts"), dict):
+                yield ("tool", "hatch", "envs", env, "scripts"), settings["scripts"]
+
+
+def _mentions(task: Any, depth: int) -> list[PortMention]:
+    """The listen ports of one task in any of the documented shapes."""
+    if depth > _MAX_DEPTH:
+        return []
+    if isinstance(task, str):
+        return listen_ports(task)
+    if isinstance(task, list):
+        return [m for item in task for m in _mentions(item, depth + 1)]
+    if not isinstance(task, dict):
+        return []
+    found: list[PortMention] = []
+    for key in _COMMAND_KEYS:
+        command = task.get(key)
+        if isinstance(command, str):
+            found += listen_ports(command)
+        elif isinstance(command, list) and all(isinstance(arg, str) for arg in command):
+            found += listen_ports(shlex.join(command))  # an argument vector
+    for key in _SEQUENCE_KEYS:
+        if isinstance(task.get(key), list):
+            found += _mentions(task[key], depth + 1)
+    env = task.get("env")
+    if isinstance(env, dict):
+        for name, value in env.items():
+            port = port_number(value) if isinstance(value, str) else None
+            if port is not None and port_variable(name) is ResourceKind.LISTEN_PORT:
+                found.append(PortMention(port, None, f"env.{name}={port}"))
+    return found
+
+
+def _line(text: str, section: tuple[str, ...], name: str) -> int | None:
+    """The line defining task ``name``: its own ``[section.name]`` table, or a
+    ``name = …`` line under ``[section]``. ``None`` when written some other way."""
+    dotted = r"\s*\.\s*".join(_key_pattern(part) for part in section)
+    own = re.compile(rf"^[ \t]*\[\s*{dotted}\s*\.\s*{_key_pattern(name)}\s*\]", re.M)
+    if match := own.search(text):
+        return text.count("\n", 0, match.start()) + 1
+    header = re.compile(rf"^[ \t]*\[\s*{dotted}\s*\]", re.M).search(text)
+    if header is None:
+        return None
+    following = re.compile(r"^[ \t]*\[", re.M).search(text, header.end())
+    end = following.start() if following else len(text)
+    key = re.compile(rf"^[ \t]*{_key_pattern(name)}\s*=", re.M).search(text, header.end(), end)
+    return text.count("\n", 0, key.start()) + 1 if key else None
+
+
+def _key_pattern(key: str) -> str:
+    """A TOML key as written: bare, or in double or single quotes."""
+    escaped = re.escape(key)
+    return f"(?:{escaped}|\"{escaped}\"|'{escaped}')"

worktree_shield/collectors/runtime.py

@@ -0,0 +1,167 @@
+"""Listening processes, tied to a worktree only by their working directory.
+
+Read-only and without privileges: the listening sockets the system shows, and for each
+owning process its name and working directory. Never its command line or environment,
+which can hold secrets, and nothing is signalled. A process name like ``node`` says
+nothing about the worktree, so it is never used to attribute one; a listener that
+cannot be tied is kept with the reason, because it may still hold a port a worktree
+needs.
+
+The view is a snapshot: a server started a second later is not seen. On Linux the
+sockets of other users' processes are listed without their owner; on macOS only the
+current user's processes are visible.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass
+from socket import SOCK_DGRAM, SOCK_STREAM
+from typing import Any, Protocol
+
+import psutil
+
+from worktree_shield.collectors.base import port_key
+from worktree_shield.models import Listener, Observation, ResourceClaim, ResourceKind, SourceRef
+
+
+@dataclass(frozen=True, slots=True)
+class Socket:
+    """A listening (TCP) or bound (UDP) local socket and the process owning it."""
+
+    protocol: str
+    address: str
+    port: int
+    pid: int | None
+
+
+class ProcessGoneError(Exception):
+    """The process ended while it was looked at."""
+
+
+class ProcessDeniedError(Exception):
+    """The process cannot be inspected without more privileges."""
+
+
+class ProcessTable(Protocol):
+    def listening_sockets(self) -> tuple[list[Socket], str | None]:
+        """The sockets, and what limited the view (``None`` when nothing did)."""
+        ...
+
+    def process(self, pid: int) -> tuple[str, str | None]:
+        """Name and working directory (``None`` if unreadable) of a process."""
+        ...
+
+
+def observe_runtime(
+    table: ProcessTable, worktrees: Sequence[str]
+) -> tuple[list[ResourceClaim], list[Listener], list[str]]:
+    """Runtime claims of the worktrees, the listeners no worktree owns, and the
+    limitations of the view."""
+    sockets, limitation = table.listening_sockets()
+    roots = sorted(((_canonical(w), w) for w in worktrees), key=lambda r: len(r[0]), reverse=True)
+    looked_up: dict[int, tuple[str | None, str | None, str | None]] = {}
+    claims: list[ResourceClaim] = []
+    unattributed: list[Listener] = []
+    for socket in sockets:
+        if socket.pid is None:
+            unattributed.append(_listener(socket, None, "owned by a process of another user"))
+            continue
+        if socket.pid not in looked_up:
+            looked_up[socket.pid] = _look_up(table, socket.pid, roots)
+        name, worktree, note = looked_up[socket.pid]
+        if worktree is None:
+            unattributed.append(_listener(socket, name, note or ""))
+            continue
+        key = port_key(socket.address, socket.port, protocol=socket.protocol)
+        source = SourceRef(worktree, f"pid {socket.pid}")
+        detail = f"{name} (pid {socket.pid}) is listening; it runs in this worktree"
+        claims.append(
+            ResourceClaim(
+                ResourceKind.LISTEN_PORT, key, worktree, source, detail, Observation.RUNTIME
+            )
+        )
+    return claims, unattributed, [limitation] if limitation else []
+
+
+def _look_up(
+    table: ProcessTable, pid: int, roots: list[tuple[str, str]]
+) -> tuple[str | None, str | None, str | None]:
+    """(name, worktree, note): the worktree it runs in, or why there is none."""
+    try:
+        name, cwd = table.process(pid)
+    except ProcessGoneError:
+        return None, None, "the process ended while it was looked at"
+    except ProcessDeniedError:
+        return None, None, "the process cannot be inspected without more privileges"
+    if cwd is None:
+        return name, None, "its working directory cannot be read"
+    directory = _canonical(cwd)
+    for root, worktree in roots:  # deepest first: nested worktrees
+        if directory == root or directory.startswith(root.rstrip(os.sep) + os.sep):
+            return name, worktree, None
+    return name, None, "it runs outside every worktree"
+
+
+def _listener(socket: Socket, process: str | None, note: str) -> Listener:
+    return Listener(socket.protocol, socket.address, socket.port, socket.pid, process, note)
+
+
+def _canonical(path: str) -> str:
+    return os.path.normcase(os.path.realpath(path))
+
+
+class PsutilTable:
+    """The real process table, through psutil."""
+
+    def listening_sockets(self) -> tuple[list[Socket], str | None]:
+        found: list[Socket | None]
+        try:
+            found = [_socket(c, c.pid) for c in psutil.net_connections(kind="inet")]
+            limitation = None
+        except psutil.AccessDenied:  # macOS: only the current user's processes
+            found = []
+            for process in psutil.process_iter():
+                try:
+                    found += [_socket(c, process.pid) for c in process.net_connections(kind="inet")]
+                except (psutil.AccessDenied, psutil.NoSuchProcess, psutil.ZombieProcess):
+                    continue
+            limitation = "only the processes of the current user are visible"
+        listening = [s for s in found if s is not None]
+        if limitation is None and any(s.pid is None for s in listening):
+            limitation = "the sockets of other users' processes are listed without their owner"
+        return listening, limitation
+
+    def process(self, pid: int) -> tuple[str, str | None]:
+        try:
+            process = psutil.Process(pid)
+            name = process.name()
+            try:
+                cwd: str | None = process.cwd()
+            except psutil.AccessDenied:
+                cwd = None
+            return name, cwd or None
+        except (psutil.NoSuchProcess, psutil.ZombieProcess):
+            raise ProcessGoneError from None
+        except psutil.AccessDenied:
+            raise ProcessDeniedError from None
+
+
+def _socket(connection: Any, pid: int | None) -> Socket | None:
+    """A listening TCP or bound, unconnected UDP socket; ``None`` for anything else.
+    ``connection`` is a psutil ``sconn`` or ``pconn``; only the fields both have are used."""
+    if not connection.laddr:
+        return None
+    if connection.type == SOCK_STREAM:
+        if connection.status != psutil.CONN_LISTEN:
+            return None
+        protocol = "tcp"
+    elif connection.type == SOCK_DGRAM:
+        if connection.raddr:
+            return None
+        protocol = "udp"
+    else:  # pragma: no cover - kind="inet" lists only TCP and UDP
+        return None
+    address, port = connection.laddr.ip, connection.laddr.port
+    return Socket(protocol, address.split("%", 1)[0], port, pid)

worktree_shield/collectors/static.py

@@ -0,0 +1,25 @@
+"""All static collectors over one worktree: configuration files, read as data."""
+
+from __future__ import annotations
+
+from worktree_shield.collectors.base import Collected, Scope
+from worktree_shield.collectors.compose import collect_compose
+from worktree_shield.collectors.envfiles import collect_env_files
+from worktree_shield.collectors.layout import config_directories
+from worktree_shield.collectors.node import collect_package_json
+from worktree_shield.collectors.procfile import collect_devcontainer, collect_procfiles
+from worktree_shield.collectors.python import collect_pyproject
+from worktree_shield.collectors.vite import collect_vite_config
+from worktree_shield.models import Policy
+
+
+def collect_worktree(scope: Scope, policy: Policy, out: Collected) -> None:
+    """Every claim in the configuration of one worktree, directory by directory."""
+    for directory in config_directories(scope, out):
+        collect_env_files(scope, directory, policy, out)
+        collect_package_json(scope, directory, out)
+        collect_vite_config(scope, directory, out)
+        collect_pyproject(scope, directory, out)
+        collect_compose(scope, directory, policy, out)
+        collect_procfiles(scope, directory, out)
+        collect_devcontainer(scope, directory, out)

worktree_shield/collectors/vite.py

@@ -0,0 +1,133 @@
+"""Ports and paths in ``vite.config.*``, matched as text; the config is never run.
+
+Only literal settings count: ``server.port`` and ``preview.port`` (with ``host`` and
+``strictPort`` from the same block), ``cacheDir`` and ``build.outDir`` when absolute. A
+port computed from the environment (``Number(process.env.PORT)``) is left to the
+collector that reads the variable. Comments, strings and template literals are blanked
+first, so a commented-out block or a string that looks like one is ignored.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import PurePosixPath
+
+from worktree_shield.collectors.base import Collected, Scope, is_absolute_path, path_key, port_key
+from worktree_shield.models import ResourceClaim, ResourceKind
+from worktree_shield.names import literal_host, port_number
+from worktree_shield.parsers.jstext import blank_code
+
+CONFIG_FILES = tuple(f"vite.config.{ext}" for ext in ("js", "ts", "mjs", "mts", "cjs", "cts"))
+_BLOCK = re.compile(r"\b(server|preview|build)\s*:\s*\{")
+_SETTING = re.compile(r"\b(port|host|strictPort|outDir)\s*:\s*")
+_CACHE_DIR = re.compile(r"\bcacheDir\s*:\s*")
+_END = r"(?=\s*(?:,|\}|\n|$))"  # the literal is the whole value
+_NUMBER = re.compile(r"([0-9]+)" + _END)
+_BOOLEAN = re.compile(r"(true|false)" + _END)
+
+_Value = str | int | bool
+
+
+def collect_vite_config(scope: Scope, directory: PurePosixPath, out: Collected) -> None:
+    """The claims of every ``vite.config.*`` in ``directory``."""
+    for name in CONFIG_FILES:
+        relative = directory / name
+        text = scope.read(relative, out)
+        if text is not None:
+            out.claims += _claims(scope, relative, text)
+
+
+def _claims(scope: Scope, relative: PurePosixPath, text: str) -> list[ResourceClaim]:
+    code = blank_code(text)
+    ports: list[ResourceClaim] = []
+    paths: list[tuple[int, ResourceClaim]] = []
+
+    def line(position: int) -> int:
+        return text.count("\n", 0, position) + 1
+
+    def path_claim(position: int, label: str, value: _Value | None) -> None:
+        if isinstance(value, str) and is_absolute_path(value):
+            source = scope.source(relative, line(position))
+            claim = ResourceClaim(
+                ResourceKind.ABSOLUTE_PATH,
+                path_key(value),
+                scope.worktree,
+                source,
+                f"{label}: {value}",
+            )
+            paths.append((position, claim))
+
+    for block in _BLOCK.finditer(code):
+        settings = _settings(code, text, block.end() - 1)
+        kind = block.group(1)
+        if kind == "build":
+            if "outDir" in settings:
+                value, position = settings["outDir"]
+                path_claim(position, "build.outDir", value)
+            continue
+        if "port" not in settings:
+            continue
+        value, position = settings["port"]
+        port = (
+            port_number(str(value))
+            if isinstance(value, int) and not isinstance(value, bool)
+            else None
+        )
+        if port is None:
+            continue
+        host_value = settings.get("host", (None, 0))[0]
+        host = literal_host(host_value) if isinstance(host_value, str) else None
+        strict = settings.get("strictPort", (False, 0))[0] is True
+        source = scope.source(relative, line(position))
+        ports.append(
+            ResourceClaim(
+                ResourceKind.LISTEN_PORT,
+                port_key(host, port),
+                scope.worktree,
+                source,
+                f"{kind}.port: {port}",
+                strict=strict,
+            )
+        )
+    for match in _CACHE_DIR.finditer(code):
+        path_claim(match.start(), "cacheDir", _literal(code, text, match.end()))
+    return ports + [claim for _, claim in sorted(paths, key=lambda item: item[0])]
+
+
+def _settings(code: str, text: str, opening: int) -> dict[str, tuple[_Value | None, int]]:
+    """The literal settings directly inside the object that opens at ``opening``
+    (nested objects such as ``hmr: { port }`` are skipped); empty if it never closes."""
+    depth = 0
+    found: dict[str, tuple[_Value | None, int]] = {}
+    index = opening + 1
+    while index < len(code):
+        char = code[index]
+        if char in "{[(":
+            depth += 1
+        elif char in "}])":
+            if depth == 0:
+                return found
+            depth -= 1
+        elif depth == 0 and (match := _SETTING.match(code, index)) and _starts_word(code, index):
+            found[match.group(1)] = (_literal(code, text, match.end()), index)
+            index = match.end()
+            continue
+        index += 1
+    return {}
+
+
+def _starts_word(code: str, index: int) -> bool:
+    return index == 0 or not (code[index - 1].isalnum() or code[index - 1] in "_$")
+
+
+def _literal(code: str, text: str, position: int) -> _Value | None:
+    """A number, boolean or string literal that is the whole value at ``position``."""
+    if number := _NUMBER.match(code, position):
+        return int(number.group(1))
+    if boolean := _BOOLEAN.match(code, position):
+        return boolean.group(1) == "true"
+    if position < len(code) and code[position] in "'\"":
+        closing = code.find(code[position], position + 1)
+        if closing > 0 and re.match(_END, code[closing + 1 :]):
+            return text[position + 1 : closing]
+    return None