worktree-shield 0.1.0__py3-none-any.whl

worktree_shield/parsers/dotenv.py

@@ -0,0 +1,91 @@
+"""``.env`` files read as data, in the line format the common loaders agree on.
+
+python-dotenv, Node's dotenv (and so Vite) and Docker Compose all accept ``KEY=value``,
+an ``export`` prefix, spaces around ``=``, ``#`` comments, single, double and backtick
+quotes, and quoted values over several lines. Other lines are ignored, as they are.
+
+Nothing is expanded or run: ``${VAR}`` stays in the value and the entry is marked as a
+*reference*, so a collector never treats ``${DATA_ROOT}/uploads`` as a literal path. An
+unquoted ``#`` starts a comment only after a space or tab, as in python-dotenv and
+Compose; Node's dotenv also cuts ``https://x/#a`` there, so such values are rare in
+practice.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+_LINE = re.compile(r"[ \t]*(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_.-]*)[ \t]*=[ \t]*(.*)")
+_REFERENCE = re.compile(r"\$(?:\{[A-Za-z_]|[A-Za-z_])")
+_COMMENT = re.compile(r"[ \t]+#")
+_ESCAPES = {"n": "\n", "r": "\r", "t": "\t", '"': '"', "\\": "\\"}
+_QUOTES = "'\"`"
+MAX_VALUE_LINES = 200  # a quoted value longer than this is treated as never closed
+
+
+@dataclass(frozen=True, slots=True)
+class EnvEntry:
+    """One variable; ``line`` is where it starts. The value never appears in repr()."""
+
+    key: str
+    value: str = field(repr=False)
+    line: int
+    reference: bool = False
+
+
+def parse_dotenv(text: str) -> tuple[EnvEntry, ...]:
+    """The variables of a ``.env`` file; a later definition replaces an earlier one."""
+    lines = text.replace("\r\n", "\n").split("\n")
+    entries: dict[str, EnvEntry] = {}
+    index = 0
+    while index < len(lines):
+        number = index + 1
+        match = _LINE.fullmatch(lines[index])
+        index += 1
+        if match is None:
+            continue
+        key, rest = match.groups()
+        if rest[:1] and rest[0] in _QUOTES:
+            quoted = _quoted(rest[0], rest[1:], lines, index)
+            if quoted is None:  # never closed: skip this line only
+                continue
+            value, index = quoted
+            reference = rest[0] != "'" and _REFERENCE.search(value) is not None
+        else:
+            comment = _COMMENT.search(rest)
+            value = (rest[: comment.start()] if comment else rest).rstrip(" \t")
+            reference = _REFERENCE.search(value) is not None
+        entries[key] = EnvEntry(key, value, number, reference)
+    return tuple(entries.values())
+
+
+def _quoted(quote: str, first: str, lines: list[str], index: int) -> tuple[str, int] | None:
+    """The value of a quoted assignment and the index of the line after it."""
+    text = first
+    for extra in range(MAX_VALUE_LINES):
+        end = _closing(text, quote)
+        if end is not None:
+            body = text[:end]
+            return (_unescape(body) if quote == '"' else body), index + extra
+        if index + extra >= len(lines):
+            return None
+        text += "\n" + lines[index + extra]
+    return None
+
+
+def _closing(text: str, quote: str) -> int | None:
+    position = 0
+    while position < len(text):
+        char = text[position]
+        if char == "\\" and quote == '"':
+            position += 2
+            continue
+        if char == quote:
+            return position
+        position += 1
+    return None
+
+
+def _unescape(body: str) -> str:
+    return re.sub(r"\\(.)", lambda m: _ESCAPES.get(m.group(1), m.group(0)), body, flags=re.S)

worktree_shield/parsers/interpolate.py

@@ -0,0 +1,142 @@
+"""Compose variable interpolation, resolved from the variables of the files read.
+
+Implements the operators of the Compose specification: ``$VAR``, ``${VAR}``,
+``${VAR:-default}`` / ``${VAR-default}``, ``${VAR:?error}`` / ``${VAR?error}``,
+``${VAR:+replacement}`` / ``${VAR+replacement}``, nested defaults and ``$$`` for a
+literal ``$``. Nothing is read from the environment of worktree-shield itself: the
+shell that will run ``docker compose`` is not this one.
+
+A variable that no file set is *assumed unset*: its default is used and the result
+records the assumption, so a report can say "unless WEB_PORT is set in your shell". A
+value that needs such a variable and has no default has no value (``None``) and the
+variable is listed as *missing*; guessing an empty string, as Compose would, could
+invent a collision.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_OPERATOR = re.compile(r":?[-?+]")
+MAX_NESTING = 16  # ${A:-${B:-…}} levels; more is not a real configuration
+
+
+@dataclass(frozen=True, slots=True)
+class Interpolated:
+    """The resolved text, or ``None`` when it depends on a missing variable or the
+    syntax is invalid; ``missing`` and ``assumed_unset`` name variables in order."""
+
+    value: str | None
+    missing: tuple[str, ...] = ()
+    assumed_unset: tuple[str, ...] = ()
+
+
+class _Invalid(Exception):
+    pass
+
+
+class _Missing(Exception):
+    pass
+
+
+def interpolate(text: str, variables: Mapping[str, str]) -> Interpolated:
+    """``text`` with every variable reference resolved from ``variables``."""
+    resolver = _Resolver(variables, 0)
+    try:
+        value, _ = resolver.text(text, 0, closing=False)
+    except _Invalid:
+        return Interpolated(None)
+    value_or_none = None if resolver.missing else value
+    return Interpolated(value_or_none, tuple(resolver.missing), tuple(resolver.assumed))
+
+
+class _Resolver:
+    def __init__(self, variables: Mapping[str, str], depth: int) -> None:
+        if depth > MAX_NESTING:
+            raise _Invalid
+        self.variables = variables
+        self.depth = depth
+        self.missing: list[str] = []
+        self.assumed: list[str] = []
+
+    def _note(self, names: list[str], name: str) -> None:
+        if name not in names:
+            names.append(name)
+
+    def _adopt(self, child: _Resolver) -> None:
+        """Take over what a default needed, once the default is actually used."""
+        for name in child.assumed:
+            self._note(self.assumed, name)
+        for name in child.missing:
+            self._note(self.missing, name)
+
+    def text(self, text: str, index: int, *, closing: bool) -> tuple[str, int]:
+        """Resolve from ``index`` to the end, or to the ``}`` closing a default when
+        ``closing`` is set; returns the text and the index after it."""
+        parts: list[str] = []
+        while index < len(text):
+            char = text[index]
+            if closing and char == "}":
+                return "".join(parts), index
+            if char != "$":
+                parts.append(char)
+                index += 1
+                continue
+            following = text[index + 1 : index + 2]
+            if following == "$":
+                parts.append("$")
+                index += 2
+            elif following == "{":
+                value, index = self.braced(text, index + 2)
+                parts.append(value)
+            elif name := _NAME.match(text, index + 1):
+                parts.append(self.lookup(name.group(0)))
+                index = name.end()
+            else:  # a lone "$" is kept, as Compose keeps it
+                parts.append("$")
+                index += 1
+        if closing:
+            raise _Invalid
+        return "".join(parts), index
+
+    def lookup(self, name: str) -> str:
+        if name in self.variables:
+            return self.variables[name]
+        self._note(self.missing, name)
+        return ""
+
+    def braced(self, text: str, index: int) -> tuple[str, int]:
+        """``${…}`` starting after ``${``; returns its value and the index after ``}``."""
+        name_match = _NAME.match(text, index)
+        if name_match is None:
+            raise _Invalid
+        name, index = name_match.group(0), name_match.end()
+        if text[index : index + 1] == "}":
+            return self.lookup(name), index + 1
+        operator_match = _OPERATOR.match(text, index)
+        if operator_match is None:
+            raise _Invalid
+        operator = operator_match.group(0)
+        default = _Resolver(self.variables, self.depth + 1)
+        argument, end = default.text(text, operator_match.end(), closing=True)
+        known = name in self.variables
+        value = self.variables.get(name, "")
+        is_set = known and (value != "" or not operator.startswith(":"))
+        if operator.endswith("?"):
+            if not is_set:
+                self._note(self.missing, name)  # Compose would stop with the error
+            return value, end + 1
+        if not known:
+            self._note(self.assumed, name)
+        if operator.endswith("-"):
+            if is_set:
+                return value, end + 1
+            self._adopt(default)
+            return argument, end + 1
+        if is_set:  # "+": the replacement only when the variable is set
+            self._adopt(default)
+            return argument, end + 1
+        return "", end + 1

worktree_shield/parsers/jsonc.py

@@ -0,0 +1,48 @@
+"""JSON with comments and trailing commas (as VS Code and dev containers allow) made
+plain JSON, without moving any line.
+
+Comments become spaces (their newlines are kept), and a comma that is followed only by
+whitespace and a closing bracket is dropped. Strings are left exactly as they are, so
+``"a // b"`` stays a string.
+"""
+
+from __future__ import annotations
+
+import re
+
+_TRAILING_COMMA = re.compile(r",(\s*[}\]])")
+
+
+def strip_jsonc(text: str) -> str:
+    out: list[str] = []
+    index, length = 0, len(text)
+    while index < length:
+        char = text[index]
+        if char == '"':
+            end = index + 1
+            while end < length and text[end] != '"':
+                end += 2 if text[end] == "\\" else 1
+            out.append(text[index : end + 1])
+            index = end + 1
+        elif text.startswith("//", index):
+            end = text.find("\n", index)
+            end = length if end < 0 else end
+            out.append(" " * (end - index))
+            index = end
+        elif text.startswith("/*", index):
+            end = text.find("*/", index + 2)
+            end = length if end < 0 else end + 2
+            out.append("".join("\n" if c == "\n" else " " for c in text[index:end]))
+            index = end
+        else:
+            out.append(char)
+            index += 1
+    return _drop_trailing_commas("".join(out))
+
+
+def _drop_trailing_commas(text: str) -> str:
+    """Drop commas before a closing bracket, outside strings."""
+    parts = re.split(r'("(?:[^"\\]|\\.)*")', text)  # odd parts are strings
+    return "".join(
+        part if index % 2 else _TRAILING_COMMA.sub(r" \1", part) for index, part in enumerate(parts)
+    )

worktree_shield/parsers/jstext.py

@@ -0,0 +1,142 @@
+"""JavaScript and TypeScript source with comments and literals blanked out.
+
+Nothing is evaluated. :func:`blank_code` returns the source with the *contents* of
+comments, strings, template literals and regular expressions replaced by spaces (quotes
+and newlines kept, so positions and line numbers do not move). Patterns matched against
+the result only see code: ``"server: { port: 9999 }"`` inside a string or a commented-out
+block no longer looks like a setting. Literal values are then read from the original
+text at the same position.
+
+It is a lexer, not a parser: a ``/`` counts as the start of a regular expression when
+the previous code character cannot end an operand, which is right for configuration
+files but not for every program.
+"""
+
+from __future__ import annotations
+
+_OPERAND_END = frozenset(")]}")  # after these (and names, numbers, literals) "/" divides
+
+
+def blank_code(source: str) -> str:
+    """``source`` with comment and literal contents replaced by spaces."""
+    out = list(source)
+    _code(source, 0, out, nested=False)
+    return "".join(out)
+
+
+def _blank(out: list[str], start: int, end: int) -> None:
+    for index in range(start, min(end, len(out))):
+        if out[index] != "\n":
+            out[index] = " "
+
+
+def _code(source: str, index: int, out: list[str], *, nested: bool) -> int:
+    """Scan code from ``index``; inside a template ``${…}`` stop after its ``}``."""
+    length = len(source)
+    depth = 0
+    previous = ""  # the last code character, to tell a regex from a division
+    while index < length:
+        char = source[index]
+        pair = source[index : index + 2]
+        if pair == "//":
+            end = source.find("\n", index)
+            end = length if end < 0 else end
+            _blank(out, index, end)
+            index = end
+        elif pair == "/*":
+            end = source.find("*/", index + 2)
+            end = length if end < 0 else end + 2
+            _blank(out, index, end)
+            index = end
+        elif char in "'\"":
+            closing, end = _string_end(source, index, char)
+            _blank(out, index + 1, closing)
+            index, previous = end, "a"
+        elif char == "`":
+            index, previous = _template(source, index, out), "a"
+        elif char == "/" and not _ends_operand(previous):
+            regex = _regex_end(source, index)
+            if regex is None:  # not a regex after all: a lone slash
+                index, previous = index + 1, char
+                continue
+            _blank(out, index + 1, regex[0])
+            index, previous = regex[1], "a"
+        else:
+            if nested and char == "{":
+                depth += 1
+            elif nested and char == "}":
+                if depth == 0:
+                    return index + 1
+                depth -= 1
+            if not char.isspace():
+                previous = char
+            index += 1
+    return index
+
+
+def _ends_operand(previous: str) -> bool:
+    """Whether a ``/`` after this character divides rather than starts a regex."""
+    return previous.isalnum() or previous in "_$" or previous in _OPERAND_END
+
+
+def _string_end(source: str, start: int, quote: str) -> tuple[int, int]:
+    """Where the contents end and where code resumes: after the closing quote, or at the
+    end of the line when the string is never closed."""
+    index = start + 1
+    while index < len(source):
+        char = source[index]
+        if char == "\\":
+            index += 2
+            continue
+        if char == quote:
+            return index, index + 1
+        if char == "\n":
+            return index, index
+        index += 1
+    return len(source), len(source)
+
+
+def _template(source: str, start: int, out: list[str]) -> int:
+    """Blank a template literal's text, scan its ``${…}`` parts as code."""
+    index = start + 1
+    text_from = index
+    while index < len(source):
+        char = source[index]
+        if char == "\\":
+            index += 2
+        elif char == "`":
+            _blank(out, text_from, index)
+            return index + 1
+        elif source.startswith("${", index):
+            _blank(out, text_from, index)
+            index = _code(source, index + 2, out, nested=True)
+            text_from = index
+        else:
+            index += 1
+    _blank(out, text_from, len(source))
+    return len(source)
+
+
+def _regex_end(source: str, start: int) -> tuple[int, int] | None:
+    """The closing ``/`` of a regex literal and the index after its flags, or ``None``
+    when the line ends first."""
+    index = start + 1
+    in_class = False
+    while index < len(source):
+        char = source[index]
+        if char == "\\":
+            index += 2
+            continue
+        if char == "\n":
+            return None
+        if char == "[":
+            in_class = True
+        elif char == "]":
+            in_class = False
+        elif char == "/" and not in_class:
+            end = index + 1
+            while end < len(source) and source[end].isalpha():
+                end += 1
+            return index, end
+        index += 1
+    return None

worktree_shield/plan.py

@@ -0,0 +1,175 @@
+"""A plan of changes that would resolve the collisions; worktree-shield applies none.
+
+For every finding that needs attention, the current worktree (or the first one) keeps
+its value and each other worktree gets its own: the next port that no worktree
+configures and no process holds, a database name with the worktree's name appended,
+the worktree's name as its Compose project. A value read from a committed ``.env``
+template is overridden in that worktree's own ``.env``, since editing the template
+would change it for every branch; values in other files are changed in place.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from worktree_shield.collectors.envfiles import TEMPLATE_FILES
+from worktree_shield.models import Evidence, Finding, ResourceKind, Snapshot, Status
+from worktree_shield.rules.common import name_of, port_of
+
+_PROBLEMS = (Status.FAIL, Status.WARN)
+
+
+@dataclass(frozen=True, slots=True)
+class Suggestion:
+    """In ``worktree``, at ``where`` (a file, with a line when known), make ``change``."""
+
+    worktree: str
+    where: str
+    change: str
+    rule: str
+
+
+def make_plan(snapshot: Snapshot) -> list[Suggestion]:
+    """The suggested changes, in finding order; empty when nothing needs attention."""
+    repository = snapshot.repository
+    if repository is None:
+        return []
+    order = [w.path for w in repository.worktrees]
+    current = repository.current
+    taken = {p for c in snapshot.claims if (p := port_of(c.key)) is not None}
+    if snapshot.runtime is not None:
+        taken |= {listener.port for listener in snapshot.runtime.unattributed}
+    planner = _Planner(order, current, taken)
+    suggestions: list[Suggestion] = []
+    for finding in snapshot.findings:
+        if finding.status in _PROBLEMS and finding.caused_by is None:
+            suggestions += planner.suggest(finding)
+    return suggestions
+
+
+class _Planner:
+    def __init__(self, order: list[str], current: str | None, taken: set[int]) -> None:
+        self.rank = {worktree: index for index, worktree in enumerate(order)}
+        self.current, self.taken = current, taken
+        self.assigned: dict[tuple[str, int], int] = {}  # (worktree, old port) -> new port
+        self.seen: set[tuple[str, str, str]] = set()
+
+    def movers(self, finding: Finding) -> list[str]:
+        """The worktrees that change: all but the one that keeps the value, by path, so
+        the result does not depend on the order Git lists them in."""
+        involved = sorted(finding.worktrees, key=lambda w: self.rank.get(w, len(self.rank)))
+        if finding.id == "WTS-PORT-002" and not finding.summary.endswith("another worktree"):
+            return sorted(involved)  # a process outside the worktrees holds it: all move
+        keeper = self.current if self.current in involved else involved[0]
+        return sorted(w for w in involved if w != keeper)
+
+    def new_port(self, worktree: str, old: int) -> int:
+        """One new port per worktree and old port, however many findings name it."""
+        if (worktree, old) not in self.assigned:
+            port = old + 1
+            while port in self.taken:
+                port += 1
+            self.taken.add(port)
+            self.assigned[(worktree, old)] = port
+        return self.assigned[(worktree, old)]
+
+    def suggest(self, finding: Finding) -> Iterator[Suggestion]:
+        for suggestion in self._suggest(finding):
+            key = (suggestion.worktree, suggestion.where, suggestion.change)
+            if key not in self.seen:
+                self.seen.add(key)
+                yield suggestion
+
+    def _suggest(self, finding: Finding) -> Iterator[Suggestion]:
+        kind = _KIND_OF.get(finding.id)
+        if kind is None or finding.resource_key is None:
+            return
+        key = finding.resource_key
+        for position, worktree in enumerate(self.movers(finding), start=1):
+            items = [
+                e for e in finding.evidence if e.key == worktree and not e.source.startswith("pid ")
+            ]
+            if kind is ResourceKind.LISTEN_PORT:
+                old = port_of(key) or 0
+                new = self.new_port(worktree, old)
+                for item in items:
+                    yield _port(finding, worktree, item, old, new)
+            elif kind is ResourceKind.DATABASE:
+                new_name, database = _database(key, worktree, position)
+                for item in items:
+                    where = _env_override(item) or item.source
+                    change = f"{item.value} naming the database {new_name} instead of {database}"
+                    yield Suggestion(worktree, where, change, finding.id)
+            elif kind is ResourceKind.COMPOSE_PROJECT:
+                for item in items[:1]:
+                    folder = PurePosixPath(item.source.split(":", 1)[0]).parent
+                    change = f"COMPOSE_PROJECT_NAME={_slug(worktree, '-')}"
+                    yield Suggestion(worktree, (folder / ".env").as_posix(), change, finding.id)
+            elif kind is ResourceKind.CONTAINER_NAME:
+                change = (
+                    f"container_name: remove it, or use ${{COMPOSE_PROJECT_NAME}}-{name_of(key)}"
+                )
+                for item in items:
+                    yield Suggestion(worktree, item.source, change, finding.id)
+            else:  # volumes and paths: a name of their own
+                yield from _renamed(finding, worktree, items)
+
+
+def _port(finding: Finding, worktree: str, item: Evidence, old: int, new: int) -> Suggestion:
+    detail = item.value or ""
+    override = _env_override(item)
+    if override is not None:  # PORT=5173 from .env.example: PORT=5174 in .env
+        variable = detail.split("=", 1)[0]
+        return Suggestion(worktree, override, f"{variable}={new}", finding.id)
+    if detail.startswith(("scripts.", "tool.")) and ": " in detail:
+        detail = detail.split(": ", 1)[1]  # the fragment, not the task name
+    # The first number is the host port: in "5432:5432" the container's stays.
+    changed = detail.replace(str(old), str(new), 1) if str(old) in detail else f"port {new}"
+    return Suggestion(worktree, item.source, f"{detail} → {changed}", finding.id)
+
+
+def _database(key: str, worktree: str, position: int) -> tuple[str, str]:
+    """(new name, old name); Redis databases are numbers, so the next free ones."""
+    engine = name_of(key).split("/", 1)[0]
+    database = name_of(key).rsplit("/", 1)[-1]
+    if engine == "redis" and database.isdigit():
+        return str(int(database) + position), database
+    return f"{database}_{_slug(worktree, '_')}", database
+
+
+def _renamed(finding: Finding, worktree: str, items: list[Evidence]) -> Iterator[Suggestion]:
+    name = name_of(finding.resource_key or "")
+    renamed = f"{name}-{_slug(worktree, '-')}"
+    for item in items:
+        override = _env_override(item)
+        if override is not None:  # UPLOAD_DIR=… from a template
+            variable = (item.value or "").split("=", 1)[0]
+            yield Suggestion(worktree, override, f"{variable}={renamed}", finding.id)
+        else:
+            yield Suggestion(worktree, item.source, f"{name} → {renamed}", finding.id)
+
+
+_KIND_OF = {
+    "WTS-PORT-001": ResourceKind.LISTEN_PORT,
+    "WTS-PORT-002": ResourceKind.LISTEN_PORT,
+    "WTS-DB-001": ResourceKind.DATABASE,
+    "WTS-DOCKER-001": ResourceKind.COMPOSE_PROJECT,
+    "WTS-DOCKER-002": ResourceKind.CONTAINER_NAME,
+    "WTS-DOCKER-003": ResourceKind.VOLUME,
+    "WTS-PATH-001": ResourceKind.ABSOLUTE_PATH,
+}
+
+
+def _env_override(item: Evidence) -> str | None:
+    """``apps/web/.env`` for a claim read from ``apps/web/.env.example``."""
+    path = PurePosixPath(item.source.split(":", 1)[0])
+    return (path.parent / ".env").as_posix() if path.name in TEMPLATE_FILES else None
+
+
+def _slug(worktree: str, separator: str) -> str:
+    """The worktree's directory name, as an identifier: ``app-login`` / ``app_login``."""
+    name = PurePosixPath(worktree.replace("\\", "/")).name.lower()
+    return re.sub(r"[^a-z0-9]+", separator, name).strip(separator) or "worktree"