gitpane 1.0.0__py3-none-any.whl

gitpane/worktree/ignore_rule.py

@@ -0,0 +1,266 @@
+"""Append literal exclusion rules without changing any byte already in the ignore file."""
+
+from __future__ import annotations
+
+import os
+import stat
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Self
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.config import IGNORE_RULE_LIMIT_BYTES
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.operation.repository_operation import OperationAction
+from gitpane.system.path_identity import canonical_path
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError
+from gitpane.worktree.worktree_file import FILE_STABLE_IDENTITY_FIELDS, PRIVATE_FILE_MODE, FileImage, creation_permission_mode, stat_identity, validate_destination
+from gitpane.worktree.worktree_snapshot import StagingSide, read_validated_size
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.worktree.mutation import MutationService
+    from gitpane.worktree.worktree_service import WorktreeService
+    from gitpane.worktree.worktree_snapshot import LocalEntry, WorktreeKey, WorktreeSnapshot
+
+CHECK_IGNORE_RECORD_FIELDS = 4
+
+
+class IgnoreDestination(Enum):
+    """The file an ignore rule is added to, with the label of its menu entry."""
+
+    WORKTREE = ("worktree", "Add file to .gitignore")
+    EXCLUDE = ("exclude", "Add file to .git/info/exclude")
+
+    def __new__(cls, value: str, label: str) -> Self:
+        """Keep the name of the destination as the value, and its menu label beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.label = label
+        return member
+
+
+@dataclass(frozen=True)
+class IgnoreOutcome:
+    """Retain publication and effective-pattern results even after the initiating view closes."""
+
+    key: WorktreeKey
+    status: OperationStatus
+    destination_filename: str
+    added_paths: tuple[bytes, ...] = ()
+    existing_paths: tuple[bytes, ...] = ()
+    overridden_paths: tuple[bytes, ...] = ()
+    diagnostic: PreparedDiagnostic | None = None
+
+
+def literal_rule(path: bytes) -> bytes:
+    """Anchor one byte path at the repository root, escaping Git's pattern grammar."""
+    if not path or any(character in path for character in (b"\r", b"\n", b"\0")):
+        raise ValueError("Ignore rules cannot represent paths containing CR, LF or NUL")
+    if any(part in (b"", b".", b"..") for part in path.split(b"/")):
+        raise ValueError("Ignore rules require a relative Git file path")
+    escaped = bytearray(b"/")
+    for character in path:
+        if character in b"!#\\*?[] ":
+            escaped.extend(b"\\")
+        escaped.append(character)
+    return bytes(escaped)
+
+
+def capture_rule_image(filename: str) -> FileImage:
+    """Capture a service-authorized regular rule file and every parent without following links."""
+    parent_dir = os.path.dirname(filename)
+    parents: list[tuple[str, tuple[int, int]]] = []
+    while True:
+        metadata = os.lstat(parent_dir)
+        if not stat.S_ISDIR(metadata.st_mode) or os.path.islink(parent_dir) or os.path.isjunction(parent_dir):
+            raise ValueError("The ignore destination traverses a linked or invalid directory")
+        parents.append((parent_dir, (metadata.st_dev, metadata.st_ino)))
+        ancestor_dir = os.path.dirname(parent_dir)
+        if ancestor_dir == parent_dir:
+            break
+        parent_dir = ancestor_dir
+    try:
+        metadata = os.lstat(filename)
+    except FileNotFoundError:
+        return FileImage(False, 0, parents=tuple(parents))
+    if not stat.S_ISREG(metadata.st_mode) or os.path.isjunction(filename):
+        raise ValueError("The ignore destination must be a regular file")
+    with open(filename, "rb") as stream:
+        opened = os.fstat(stream.fileno())
+        if stat_identity(opened)[:FILE_STABLE_IDENTITY_FIELDS] != stat_identity(metadata)[:FILE_STABLE_IDENTITY_FIELDS]:
+            raise ValueError("Ignore rules changed while reading")
+        if opened.st_size > IGNORE_RULE_LIMIT_BYTES:
+            raise ValueError("The ignore file exceeds the supported read limit")
+        content = read_validated_size(stream, opened.st_size)
+        if stat_identity(os.fstat(stream.fileno()))[:FILE_STABLE_IDENTITY_FIELDS] != stat_identity(opened)[:FILE_STABLE_IDENTITY_FIELDS]:
+            raise ValueError("Ignore rules changed while reading")
+    if len(content) != opened.st_size:
+        raise ValueError("Ignore rules changed while reading")
+    if stat_identity(os.lstat(filename)) != stat_identity(metadata):
+        raise ValueError("Ignore rules changed while reading")
+    return FileImage(True, metadata.st_mode, content=content, identity=stat_identity(metadata), parents=tuple(parents))
+
+
+def publish_rule_image(filename: str, before: FileImage, content: bytes) -> None:
+    """Publish under an owned lock only while bytes, type and parent identities still agree."""
+    if capture_rule_image(filename) != before:
+        raise ValueError("Ignore rules or their parent changed; refresh and try again")
+    permission_mode = stat.S_IMODE(before.mode) if before.exists else creation_permission_mode(os.path.dirname(filename))
+    lock_filename = filename + ".lock"
+    descriptor = os.open(lock_filename, os.O_CREAT | os.O_EXCL | os.O_WRONLY, PRIVATE_FILE_MODE)
+    lock_metadata = os.fstat(descriptor)
+    lock_identity = (lock_metadata.st_dev, lock_metadata.st_ino)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        if capture_rule_image(filename) != before:
+            raise ValueError("Ignore rules or their parent changed; refresh and try again")
+        if before.exists and not before.mode & stat.S_IWUSR:
+            raise PermissionError("The ignore file is read-only")
+        metadata = os.lstat(lock_filename)
+        if (metadata.st_dev, metadata.st_ino) != lock_identity:
+            raise ValueError("The ignore publication lock changed externally")
+        os.chmod(lock_filename, permission_mode)
+        if before.exists:
+            os.replace(lock_filename, filename)
+        else:
+            # A hard link prevents overwriting a rule file created since the absence check.
+            os.link(lock_filename, filename)
+    finally:
+        if os.path.lexists(lock_filename):
+            metadata = os.lstat(lock_filename)
+            if (metadata.st_dev, metadata.st_ino) == lock_identity:
+                os.unlink(lock_filename)
+
+
+class IgnoreRuleService(QObject):
+    """Reserve each worktree and canonical rule file across all injected session services."""
+
+    finished = Signal(object)
+    changed = Signal(object)
+
+    def __init__(self, worktree_service: WorktreeService, mutation: MutationService, parent: QObject | None = None) -> None:
+        """Share write reservations and asynchronous filesystem work with the existing services."""
+        super().__init__(parent)
+        self.worktree_service = worktree_service
+        self.mutation = mutation
+        self.active = False
+
+    def submit(self, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...], destination: IgnoreDestination) -> None:
+        """Capture selected paths and report a terminal result for every submission.
+
+        A refused reservation writes no rule and gives the real reason, worked out right away so it describes the state
+        that refused it.
+        """
+        operation_id = uuid.uuid4().hex
+        if not self.mutation.acquire(snapshot, operation_id, action=OperationAction.WORKTREE_EDIT):
+            cause = self.mutation.acquire_refusal_cause(snapshot, operation_id, action=OperationAction.WORKTREE_EDIT)
+            diagnostic = Diagnostic("Add ignore rule", snapshot.context.repository_dir, snapshot.git_filename, [], cause).prepare()
+            QTimer.singleShot(0, lambda: self.finished.emit(IgnoreOutcome(snapshot.key, OperationStatus.REFUSED, "", diagnostic=diagnostic)))
+            return
+        self.active = True
+
+        def complete(outcome: IgnoreOutcome | None, error: Exception | None) -> None:
+            """Release reservations before notifying all affected views to reread."""
+            self.mutation.release(snapshot.key, operation_id)
+            self.active = False
+            if error is not None:
+                diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic("Add ignore rule", snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+                outcome = IgnoreOutcome(snapshot.key, OperationStatus.REFUSED, "", diagnostic=diagnostic)
+            self.finished.emit(outcome)
+            self.changed.emit(snapshot.context)
+
+        self.worktree_service.run(snapshot.context, snapshot.git_filename, self._append(snapshot, entries, destination), complete, operation_id=operation_id)
+
+    def _append(self, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...], destination: IgnoreDestination) -> Generator:
+        """Resolve the single authorized administrative exception and append without normalizing old rules.
+
+        Only a member names a destination: the text of a destination is refused like an unknown one.
+        """
+        if not isinstance(destination, IgnoreDestination) or not snapshot.fresh or not entries:
+            raise ValueError("Choose current Unstaged files and a supported ignore destination")
+        paths: list[bytes] = []
+        rules: list[bytes] = []
+        for entry in entries:
+            if entry not in snapshot.entries or entry.side != StagingSide.UNSTAGED or entry.conflict_stages or entry.skip_worktree or entry.old_mode == "160000":
+                raise ValueError("Choose current ordinary Unstaged files")
+            validate_destination(snapshot.context, entry.path, allow_missing_parents=True)
+            if entry.path not in paths:
+                paths.append(entry.path)
+                rules.append(literal_rule(entry.path))
+        if destination == IgnoreDestination.EXCLUDE:
+            output = yield GitCommand(["rev-parse", "--path-format=absolute", "--git-path", "info/exclude"])
+            filename = os.fsdecode(output.removesuffix(b"\n").removesuffix(b"\r"))
+            if not os.path.isabs(filename):
+                raise ValueError("Git did not resolve an absolute exclude file")
+        else:
+            filename, _parents = validate_destination(snapshot.context, b".gitignore")
+        resource = canonical_path(filename)
+        if resource in self.mutation.active_rule_filename_set:
+            raise ValueError("This ignore file is being edited in another worktree")
+        self.mutation.active_rule_filename_set.add(resource)
+        added_paths: list[bytes] = []
+        existing_paths: list[bytes] = []
+        published = False
+        try:
+            before = yield FileTask(lambda: capture_rule_image(filename))
+            content = before.read()
+            newline = b"\r\n" if b"\r\n" in content else b"\n"
+            existing_rule_set: set[bytes] = set()
+            for line in content.split(b"\n"):
+                existing_rule_set.add(line.removesuffix(b"\r"))
+            for path, rule in zip(paths, rules, strict=True):
+                if rule in existing_rule_set:
+                    existing_paths.append(path)
+                    continue
+                if content and not content.endswith(b"\n"):
+                    content += newline
+                content += rule + newline
+                added_paths.append(path)
+                existing_rule_set.add(rule)
+            if len(content) > IGNORE_RULE_LIMIT_BYTES:
+                raise ValueError("The resulting ignore file exceeds the supported read limit")
+            # Git compares HEAD, index, configuration, attributes and the chosen files with the selection; the rule
+            # file itself is compared with its capture again under the publication lock.
+            yield from self.worktree_service.verify(snapshot, tuple(paths))
+            if added_paths:
+                def publish() -> None:
+                    """Check native authority in the worker immediately before saving rules."""
+                    self.mutation.validate_write(snapshot.key)
+                    publish_rule_image(filename, before, content)
+
+                yield FileTask(publish)
+            published = True
+            # check-ignore reads literal NUL paths itself and rejects the runner's pathspec-magic option.
+            output = yield GitCommand(["--no-literal-pathspecs", "check-ignore", "--no-index", "-z", "--stdin", "--verbose", "--non-matching"],
+                                      stdin=b"\0".join(paths) + b"\0", accepted_codes=(0, 1))
+            fields = output.split(b"\0")
+            if fields.pop() != b"" or len(fields) != len(paths) * CHECK_IGNORE_RECORD_FIELDS:
+                raise ValueError("Git returned incomplete ignore verification")
+            overridden_paths: list[bytes] = []
+            for offset in range(0, len(fields), CHECK_IGNORE_RECORD_FIELDS):
+                _source, _line, pattern, path = fields[offset:offset + CHECK_IGNORE_RECORD_FIELDS]
+                if path not in paths:
+                    raise ValueError("Git verified a different ignore path")
+                if not pattern or pattern.startswith(b"!"):
+                    overridden_paths.append(path)
+            cause = ""
+            if overridden_paths:
+                cause = "Rules saved, but another ignore rule overrides them: " + ", ".join(os.fsdecode(path) for path in overridden_paths)
+            elif any(entry.old_blob_oid is not None for entry in entries):
+                cause = "Rules saved. Already tracked files remain tracked; use Stop tracking this file separately if intended."
+            diagnostic = Diagnostic("Add ignore rule", snapshot.context.repository_dir, snapshot.git_filename, [], cause).prepare() if cause else None
+            return IgnoreOutcome(snapshot.key, OperationStatus.SUCCESS, filename, tuple(added_paths), tuple(existing_paths), tuple(overridden_paths), diagnostic)
+        except (OSError, ValueError, RuntimeError) as error:
+            diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic("Add ignore rule", snapshot.context.repository_dir, snapshot.git_filename, [], str(error)).prepare()
+            return IgnoreOutcome(snapshot.key, OperationStatus.UNKNOWN if published else OperationStatus.REFUSED, filename, tuple(added_paths) if published else (), tuple(existing_paths), diagnostic=diagnostic)
+        finally:
+            self.mutation.active_rule_filename_set.discard(resource)