worktree-shield 0.1.0__py3-none-any.whl

worktree_shield/models.py

@@ -0,0 +1,356 @@
+"""Typed facts and findings shared by collectors, rules and renderers."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import StrEnum
+
+SCHEMA_VERSION = 1
+"""Version of the snapshot/JSON report layout; bumped only for incompatible changes."""
+
+FINDING_ID = re.compile(r"WTS-[A-Z]+-[0-9]{3}")
+"""Finding codes are part of the public contract: ``WTS-<AREA>-<NNN>``, e.g. ``WTS-PORT-001``."""
+
+
+class Status(StrEnum):
+    """Outcome of one check.
+
+    Only ``PASS`` means that a check ran and found nothing shared. A check that could not
+    run is ``UNKNOWN``; one that was deliberately skipped (runtime inspection nobody asked
+    for) is ``NOT_TESTED``; one that does not apply to this repository is
+    ``NOT_APPLICABLE``.
+    """
+
+    PASS = "pass"  # noqa: S105 - a status name, not a password
+    WARN = "warn"
+    FAIL = "fail"
+    UNKNOWN = "unknown"
+    NOT_APPLICABLE = "not_applicable"
+    NOT_TESTED = "not_tested"
+
+
+class Severity(StrEnum):
+    """How much a finding matters, independent of certainty."""
+
+    INFO = "info"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class Confidence(StrEnum):
+    """How well the evidence supports a finding."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class Certainty(StrEnum):
+    """How sure a collision is, from the kind of evidence behind it.
+
+    Static evidence (two configs declare the same port) is ``PROBABLE`` at most: it only
+    matters if both run at once on the same host. ``CONFIRMED`` needs a running process
+    attributed to a worktree by its working directory. ``POSSIBLE`` covers looser matches
+    (``localhost`` against ``127.0.0.1``); ``UNKNOWN`` means it could not be decided.
+    """
+
+    CONFIRMED = "confirmed"
+    PROBABLE = "probable"
+    POSSIBLE = "possible"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class SourceRef:
+    """Where a claim comes from: a file (relative to its worktree) and, if known, a line."""
+
+    worktree: str
+    path: str
+    line: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Evidence:
+    """One observed fact that a finding relies on; ``value`` is ``None`` when missing."""
+
+    source: str
+    key: str
+    value: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """A diagnosis with everything a user needs to judge and verify it.
+
+    ``resource_key`` is the normalised shared resource (``tcp://*:5173``,
+    ``db://postgres/localhost:5432/app_dev``…), ``worktrees`` the worktrees involved and
+    ``sources`` where each claim was found. ``certainty`` applies to collisions.
+    ``verify_command`` re-checks the result after acting on ``recommended_action``;
+    ``caused_by`` names the finding this one follows from, so reports show one root
+    cause instead of a cascade.
+    """
+
+    id: str
+    status: Status
+    severity: Severity
+    confidence: Confidence
+    summary: str
+    reason: str
+    resource_key: str | None = None
+    certainty: Certainty | None = None
+    worktrees: tuple[str, ...] = ()
+    sources: tuple[SourceRef, ...] = ()
+    evidence: tuple[Evidence, ...] = ()
+    recommended_action: str | None = None
+    verify_command: str | None = None
+    limitations: tuple[str, ...] = ()
+    caused_by: str | None = None
+
+    def __post_init__(self) -> None:
+        if not FINDING_ID.fullmatch(self.id):
+            raise ValueError(f"finding id {self.id!r} does not match WTS-<AREA>-<NNN>")
+        if self.caused_by is not None and not FINDING_ID.fullmatch(self.caused_by):
+            raise ValueError(f"caused_by {self.caused_by!r} does not match WTS-<AREA>-<NNN>")
+        if not self.summary.strip():
+            raise ValueError(f"finding {self.id} has an empty summary")
+
+
+class FailureKind(StrEnum):
+    """Why a probe produced no usable facts."""
+
+    NOT_FOUND = "not_found"
+    PERMISSION_DENIED = "permission_denied"
+    TIMEOUT = "timeout"
+    NONZERO_EXIT = "nonzero_exit"
+    MALFORMED_OUTPUT = "malformed_output"
+    OS_ERROR = "os_error"
+    PROBE_ERROR = "probe_error"
+    """The probe ran, but reported that part of its own work failed."""
+
+
+@dataclass(frozen=True, slots=True)
+class ProbeFailure:
+    """A probe that could not deliver its facts; collectors return these instead of raising."""
+
+    probe: str
+    kind: FailureKind
+    detail: str
+
+
+def utc_timestamp() -> str:
+    """Current time as an ISO 8601 UTC string with second precision."""
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@dataclass(frozen=True, slots=True)
+class Worktree:
+    """One entry of ``git worktree list --porcelain``.
+
+    ``branch`` is the full ref (``refs/heads/feature``) or ``None`` when detached or
+    bare. ``locked`` and ``prunable`` carry Git's reason, ``""`` when it gave none and
+    ``None`` when the flag is not set. A prunable worktree is listed but its directory
+    is gone; it is reported, never pruned.
+    """
+
+    path: str
+    head: str | None = None
+    branch: str | None = None
+    bare: bool = False
+    detached: bool = False
+    locked: str | None = None
+    prunable: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Repository:
+    """The repository the scan started in, and every worktree that shares its ``.git``.
+
+    ``common_dir`` is the shared Git directory, ``current`` the top of the worktree the
+    scan started in (``None`` in a bare repository), ``worktrees`` Git's own list of all
+    worktrees attached to ``common_dir``, nothing found by searching the disk.
+    """
+
+    common_dir: str
+    current: str | None
+    bare: bool
+    worktrees: tuple[Worktree, ...]
+
+
+class PolicyLevel(StrEnum):
+    """What a kind of shared resource means for ``--strict``.
+
+    ``allow`` reports it as information, ``warn`` as a warning, ``deny`` as a failure,
+    which makes ``--strict`` exit with 1.
+    """
+
+    ALLOW = "allow"
+    WARN = "warn"
+    DENY = "deny"
+
+
+@dataclass(frozen=True, slots=True)
+class Policy:
+    """The effective policy: built-in defaults, then the repository's file, then flags.
+
+    ``allow_ports`` are shared *infrastructure endpoints* that every worktree may
+    connect to (one Postgres on 5432 for all of them); they never excuse two processes
+    trying to *listen* on the same port. ``source`` is the policy file that was read,
+    ``None`` for the defaults alone.
+    """
+
+    include_runtime: bool = True
+    include_env_files: bool = False
+    max_file_bytes: int = 262_144
+    shared_host_ports: PolicyLevel = PolicyLevel.DENY
+    shared_database: PolicyLevel = PolicyLevel.WARN
+    shared_compose_projects: PolicyLevel = PolicyLevel.WARN
+    fixed_container_names: PolicyLevel = PolicyLevel.WARN
+    shared_absolute_paths: PolicyLevel = PolicyLevel.WARN
+    allow_ports: tuple[int, ...] = ()
+    allow_paths: tuple[str, ...] = ()
+    source: str | None = None
+
+
+class ResourceKind(StrEnum):
+    """What a worktree claims.
+
+    A *listen* port is one its own process binds; a *client endpoint* is a server it
+    connects to (a shared Postgres on 5432). Two listeners on one port collide; two
+    clients of one server do not, which is why they are different kinds.
+    """
+
+    LISTEN_PORT = "listen_port"
+    CLIENT_ENDPOINT = "client_endpoint"
+    DATABASE = "database"
+    COMPOSE_PROJECT = "compose_project"
+    CONTAINER_NAME = "container_name"
+    VOLUME = "volume"
+    ABSOLUTE_PATH = "absolute_path"
+
+
+class Observation(StrEnum):
+    """How a claim was found: read from configuration, or seen on the running system."""
+
+    STATIC = "static"
+    RUNTIME = "runtime"
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceClaim:
+    """One resource a worktree declares or uses, with where it was found.
+
+    ``key`` identifies the resource (``tcp://*:5173``, ``db://postgres/localhost:5432/app``);
+    claims of different worktrees with overlapping keys are collision candidates.
+    ``detail`` is what was read, already reduced to safe facts: never a password or the
+    value of a variable no rule needs. ``strict`` says whether the program fails when
+    the port is taken (``True``) or moves to another one (``False``); ``None`` when the
+    configuration does not say.
+    """
+
+    kind: ResourceKind
+    key: str
+    worktree: str
+    source: SourceRef
+    detail: str
+    observation: Observation = Observation.STATIC
+    strict: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SkippedFile:
+    """A configuration file that was found but not read, and why (too large, a link
+    out of the worktree, not UTF-8…). A skipped file can hide a collision."""
+
+    source: SourceRef
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class Collision:
+    """Two or more worktrees claiming the same resource.
+
+    ``key`` names the resource (the first of the overlapping keys), ``claims`` are all
+    claims involved, ``certainty`` says how sure the overlap is and ``reason`` why, in a
+    sentence a report can show.
+    """
+
+    kind: ResourceKind
+    key: str
+    certainty: Certainty
+    reason: str
+    claims: tuple[ResourceClaim, ...]
+
+    @property
+    def worktrees(self) -> tuple[str, ...]:
+        """The worktrees involved, in the order of their first claim."""
+        return tuple(dict.fromkeys(claim.worktree for claim in self.claims))
+
+
+@dataclass(frozen=True, slots=True)
+class UnreadableValue:
+    """A value that names a resource but could not be read safely, such as a database
+    URL whose host is uncertain. ``name`` is the variable or field, never its value."""
+
+    kind: ResourceKind
+    source: SourceRef
+    name: str
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class Listener:
+    """A listening socket that could not be tied to a worktree, kept when one of the
+    worktrees configures its port. ``note`` says why it is not attributed; ``process``
+    is the process name only, never its command line."""
+
+    protocol: str
+    address: str
+    port: int
+    pid: int | None
+    process: str | None
+    note: str
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeFacts:
+    """What the runtime observation saw beyond the claims it made: listeners on
+    configured ports that belong to no worktree, and what limited the view."""
+
+    unattributed: tuple[Listener, ...] = ()
+    limitations: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class RedactionCount:
+    """How many values of one kind (``home_path``, ``secret_value``…) were redacted."""
+
+    kind: str
+    count: int
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot:
+    """Everything one scan observed and concluded; the input of every renderer.
+
+    ``repository`` is ``None`` when discovery failed (see ``probe_failures``). ``policy``
+    is the effective policy, ``claims`` every resource found in the worktrees,
+    ``skipped`` the configuration files that could not be read and ``unreadable`` the
+    values that name a resource without saying safely which one. ``runtime`` is
+    ``None`` when running processes were not looked at.
+    """
+
+    tool_version: str
+    created_at: str
+    schema_version: int = SCHEMA_VERSION
+    repository: Repository | None = None
+    policy: Policy | None = None
+    claims: tuple[ResourceClaim, ...] = ()
+    skipped: tuple[SkippedFile, ...] = ()
+    unreadable: tuple[UnreadableValue, ...] = ()
+    runtime: RuntimeFacts | None = None
+    probe_failures: tuple[ProbeFailure, ...] = ()
+    findings: tuple[Finding, ...] = ()
+    redactions: tuple[RedactionCount, ...] = ()

worktree_shield/names.py

@@ -0,0 +1,83 @@
+"""What a variable name says about its value, and which literal values are plain hosts.
+
+Shared by every collector, so ``DB_PORT`` means the same thing in a ``.env`` file and
+in an npm script.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+
+from worktree_shield.models import ResourceKind
+
+
+def _words(text: str) -> frozenset[str]:
+    return frozenset(text.split())
+
+
+# A *_PORT with one of these words names a server the app connects to, not one it runs.
+CLIENT_WORDS = _words(
+    "DB DATABASE POSTGRES POSTGRESQL PG MYSQL MARIADB REDIS MONGO MONGODB RABBITMQ AMQP SMTP "
+    "MAIL EMAIL ELASTICSEARCH ELASTIC OPENSEARCH KAFKA MEMCACHED MINIO S3 NATS CLICKHOUSE"
+)
+_PATH_WORDS = _words(
+    "DIR DIRECTORY PATH ROOT FOLDER CACHE OUT OUTPUT OUTDIR STORAGE UPLOAD UPLOADS DATA LOG "
+    "LOGS TMP TEMP TMPDIR FILE LOCATION"
+)
+# Read-only by nature: search paths, installations, certificates and configuration.
+_SEARCH_PATHS = _words(
+    "PATH PYTHONPATH NODE_PATH LD_LIBRARY_PATH DYLD_LIBRARY_PATH MANPATH CLASSPATH GOPATH "
+    "PKG_CONFIG_PATH CDPATH"
+)
+_READ_ONLY_WORDS = _words("HOME CERT CERTS KEY CA SSL TLS CONFIG CONF ETC")
+
+
+def port_variable(name: str) -> ResourceKind | None:
+    """``LISTEN_PORT`` for ``PORT`` and ``API_PORT``, ``CLIENT_ENDPOINT`` for ``DB_PORT``
+    and ``PGPORT``, ``None`` for a name that holds no port."""
+    upper = name.upper()
+    if upper == "PGPORT":
+        return ResourceKind.CLIENT_ENDPOINT
+    if upper != "PORT" and not upper.endswith("_PORT"):
+        return None
+    if CLIENT_WORDS.intersection(upper.split("_")):
+        return ResourceKind.CLIENT_ENDPOINT
+    return ResourceKind.LISTEN_PORT
+
+
+def host_variable(port_name: str) -> str:
+    """The host variable that goes with a port variable: ``API_PORT`` → ``API_HOST``."""
+    upper = port_name.upper()
+    return "PGHOST" if upper == "PGPORT" else upper.removesuffix("PORT") + "HOST"
+
+
+def is_mutable_path_variable(name: str) -> bool:
+    """Whether a variable that holds a path is likely written to (``UPLOAD_DIR``,
+    ``CACHE_PATH``) rather than read (``PYTHONPATH``, ``JAVA_HOME``, ``SSL_CERT_FILE``)."""
+    upper = name.upper()
+    if upper in _SEARCH_PATHS:
+        return False
+    words = set(upper.split("_"))
+    return bool(words & _PATH_WORDS) and not words & _READ_ONLY_WORDS
+
+
+def port_number(text: str) -> int | None:
+    """A port written as plain ASCII digits, 1 to 65535."""
+    if not text.isascii() or not text.isdigit() or len(text) > 5:
+        return None
+    port = int(text)
+    return port if 1 <= port <= 65535 else None
+
+
+def literal_host(text: str) -> str | None:
+    """A host name or address as written, lower-cased; ``None`` for anything else
+    (references, spaces, non-ASCII names)."""
+    value = text.strip().lower()
+    try:
+        return str(ipaddress.ip_address(value.strip("[]")))
+    except ValueError:
+        pass
+    labels = value.split(".")
+    if value.isascii() and all(label and label.replace("-", "").isalnum() for label in labels):
+        return value
+    return None

worktree_shield/orchestrator.py

@@ -0,0 +1,121 @@
+"""Runs the collectors and assembles the snapshot; no diagnosis happens here."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import replace
+from pathlib import Path
+
+import psutil
+
+from worktree_shield import __version__
+from worktree_shield.collectors.base import Collected, Scope
+from worktree_shield.collectors.runtime import ProcessTable, PsutilTable, observe_runtime
+from worktree_shield.collectors.static import collect_worktree
+from worktree_shield.config import apply_overrides, policy_of
+from worktree_shield.git.discovery import discover
+from worktree_shield.models import (
+    ResourceClaim,
+    ResourceKind,
+    RuntimeFacts,
+    SkippedFile,
+    Snapshot,
+    SourceRef,
+    utc_timestamp,
+)
+from worktree_shield.runner import CommandRunner
+
+
+def inspect_worktrees(runner: CommandRunner, start: Path) -> Snapshot:
+    """The repository containing ``start`` and its worktrees.
+
+    Raises ``NotARepositoryError`` when ``start`` is not inside a repository.
+    """
+    repository, failures = discover(runner, start)
+    return Snapshot(
+        tool_version=__version__,
+        created_at=utc_timestamp(),
+        repository=repository,
+        probe_failures=failures,
+    )
+
+
+_PORT = re.compile(r"([a-z]+)://.*:([0-9]+)")
+
+
+def inspect_resources(
+    runner: CommandRunner,
+    start: Path,
+    *,
+    include_env_files: bool | None = None,
+    include_runtime: bool | None = None,
+    table: ProcessTable | None = None,
+) -> Snapshot:
+    """The worktrees of the repository, the effective policy and every resource the
+    worktrees declare in their configuration or, with ``include_runtime``, hold with a
+    running server.
+
+    Bare and prunable worktrees have no files to read and are left out. Raises
+    ``NotARepositoryError`` outside a repository and ``PolicyError`` for a policy file
+    that cannot be used.
+    """
+    snapshot = inspect_worktrees(runner, start)
+    if snapshot.repository is None:
+        return snapshot
+    policy = apply_overrides(
+        policy_of(snapshot.repository),
+        include_env_files=include_env_files,
+        include_runtime=include_runtime,
+    )
+    out = Collected()
+    with_files: list[str] = []
+    for worktree in snapshot.repository.worktrees:
+        if worktree.bare or worktree.prunable is not None:
+            continue
+        root = Path(worktree.path)
+        if not root.is_dir():
+            reason = "is listed by Git but is not a directory"
+            out.skipped.append(SkippedFile(SourceRef(worktree.path, "."), reason))
+            continue
+        with_files.append(worktree.path)
+        collect_worktree(Scope(root, worktree.path, policy.max_file_bytes), policy, out)
+    runtime = None
+    if policy.include_runtime:
+        runtime = _observe(table or PsutilTable(), with_files, out.claims)
+    return replace(
+        snapshot,
+        policy=policy,
+        claims=tuple(out.claims),
+        skipped=tuple(out.skipped),
+        unreadable=tuple(out.unreadable),
+        runtime=runtime,
+    )
+
+
+def _observe(
+    table: ProcessTable, worktrees: list[str], claims: list[ResourceClaim]
+) -> RuntimeFacts:
+    """Add the runtime claims to ``claims``; keep the unattributed listeners only on
+    ports some worktree configures, since only those can block one."""
+    try:
+        found, unattributed, limitations = observe_runtime(table, worktrees)
+    except (psutil.Error, OSError) as error:
+        return RuntimeFacts(limitations=(f"running processes could not be listed ({error})",))
+    configured = set()
+    for claim in claims:
+        match = _PORT.fullmatch(claim.key)
+        if claim.kind is ResourceKind.LISTEN_PORT and match is not None:
+            configured.add((match.group(1), int(match.group(2))))
+    claims += found
+    relevant = tuple(u for u in unattributed if (u.protocol, u.port) in configured)
+    return RuntimeFacts(relevant, tuple(limitations))
+
+
+def diagnose(snapshot: Snapshot) -> Snapshot:
+    """The snapshot with the findings of every built-in rule added."""
+    from worktree_shield.rules.catalog import builtin_rules
+    from worktree_shield.rules.engine import evaluate
+
+    if snapshot.repository is None:
+        return snapshot
+    return replace(snapshot, findings=evaluate(snapshot, builtin_rules()))