patchshuttle 0.1.0a2__py3-none-any.whl

patchshuttle/formatters/runner.py

@@ -0,0 +1,240 @@
+"""Controlled isort and Black execution for immutable formatting scopes."""
+
+from __future__ import annotations
+
+import hashlib
+import stat
+import sys
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path, PurePosixPath
+from typing import Literal, TypeAlias
+
+from patchshuttle._process import ProcessCommand, run_process
+from patchshuttle.planner import Plan
+from patchshuttle.policy import PathKind, Policy
+
+FormatterName: TypeAlias = Literal["isort", "black"]
+_FORMATTER_ORDER: tuple[FormatterName, FormatterName] = ("isort", "black")
+
+
+class FormatterStatus(str, Enum):
+    """Observable outcome of one controlled formatter process."""
+
+    PASSED = "PASSED"
+    FAILED = "FAILED"
+    TIMED_OUT = "TIMED_OUT"
+    ERROR = "ERROR"
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedFormatter:
+    """One fixed formatter command over the approved changed-Python scope."""
+
+    id: str
+    name: FormatterName
+    argv: tuple[str, ...]
+    working_directory: Path
+    timeout_seconds: int
+
+
+@dataclass(frozen=True, slots=True)
+class FormatterResult:
+    """Bounded captured outcome of one launched formatter."""
+
+    id: str
+    name: FormatterName
+    status: FormatterStatus
+    argv: tuple[str, ...]
+    working_directory: Path
+    timeout_seconds: int
+    return_code: int | None
+    duration_ms: int
+    stdout: str
+    stderr: str
+    stdout_truncated: bool
+    stderr_truncated: bool
+
+    @property
+    def success(self) -> bool:
+        return self.status is FormatterStatus.PASSED
+
+
+@dataclass(frozen=True, slots=True)
+class FormatterRunResult:
+    """Ordered formatter results through the first failure, if any."""
+
+    results: tuple[FormatterResult, ...]
+
+    @property
+    def success(self) -> bool:
+        return all(result.success for result in self.results)
+
+    @property
+    def failed(self) -> FormatterResult | None:
+        return next((result for result in self.results if not result.success), None)
+
+
+@dataclass(frozen=True, slots=True)
+class FormattedFileState:
+    """Exact bounded post-formatter state retained through final checks."""
+
+    path: PurePosixPath
+    sha256: str
+    size: int
+    mode: int
+    content: bytes = field(repr=False)
+
+
+def prepare_formatters(plan: Plan) -> tuple[PreparedFormatter, ...]:
+    """Build fixed isort-then-Black commands from the immutable plan scope."""
+
+    formatting = plan.workspace.config.formatting
+    expected_targets = (
+        tuple(
+            change.path for change in plan.file_changes if change.path.suffix == ".py"
+        )
+        if formatting.enabled
+        else ()
+    )
+    if plan.formatting_targets != expected_targets:
+        raise ValueError("plan formatting targets do not match changed Python files")
+    if not expected_targets:
+        return ()
+    if formatting.order != _FORMATTER_ORDER:
+        raise ValueError("protocol 1 requires isort then Black formatter order")
+
+    paths = tuple(path.as_posix() for path in expected_targets)
+    timeout = plan.workspace.config.execution.default_timeout_seconds
+    commands: list[PreparedFormatter] = []
+    for index, name in enumerate(_FORMATTER_ORDER, start=1):
+        options = ("--overwrite-in-place",) if name == "isort" else ()
+        commands.append(
+            PreparedFormatter(
+                id=f"formatter_{index:03d}",
+                name=name,
+                argv=(
+                    sys.executable,
+                    "-I",
+                    "-m",
+                    name,
+                    *options,
+                    "--",
+                    *paths,
+                ),
+                working_directory=plan.workspace.root,
+                timeout_seconds=timeout,
+            )
+        )
+    return tuple(commands)
+
+
+def run_formatters(plan: Plan) -> FormatterRunResult:
+    """Run isort and Black sequentially, stopping at the first failure."""
+
+    maximum = plan.workspace.config.execution.max_command_output_bytes
+    results: list[FormatterResult] = []
+    for formatter in prepare_formatters(plan):
+        process = run_process(
+            ProcessCommand(
+                argv=formatter.argv,
+                working_directory=formatter.working_directory,
+                timeout_seconds=formatter.timeout_seconds,
+            ),
+            maximum_output_bytes=maximum,
+        )
+        result = FormatterResult(
+            id=formatter.id,
+            name=formatter.name,
+            status=FormatterStatus(process.status.value),
+            argv=formatter.argv,
+            working_directory=formatter.working_directory,
+            timeout_seconds=formatter.timeout_seconds,
+            return_code=process.return_code,
+            duration_ms=process.duration_ms,
+            stdout=process.stdout,
+            stderr=process.stderr,
+            stdout_truncated=process.stdout_truncated,
+            stderr_truncated=process.stderr_truncated,
+        )
+        results.append(result)
+        if not result.success:
+            break
+    return FormatterRunResult(results=tuple(results))
+
+
+def capture_formatted_files(plan: Plan) -> tuple[FormattedFileState, ...]:
+    """Capture exact regular-file states for every approved formatter target."""
+
+    policy = Policy(plan.workspace)
+    maximum = plan.workspace.config.execution.max_single_file_bytes
+    return tuple(
+        _capture_file(policy, path, maximum=maximum) for path in plan.formatting_targets
+    )
+
+
+def verify_formatted_files(
+    plan: Plan,
+    expected: tuple[FormattedFileState, ...],
+) -> None:
+    """Require formatter targets to retain their captured exact final state."""
+
+    if tuple(item.path for item in expected) != plan.formatting_targets:
+        raise ValueError("formatted-file snapshot scope does not match the plan")
+    if capture_formatted_files(plan) != expected:
+        raise OSError("a formatter target changed after formatting")
+
+
+def _capture_file(
+    policy: Policy,
+    path: PurePosixPath,
+    *,
+    maximum: int,
+) -> FormattedFileState:
+    target = policy.resolve(path, allow_missing=True)
+    if target.kind is not PathKind.FILE:
+        raise OSError(f"formatter target is not a regular file: {path}")
+    before = target.absolute.lstat()
+    if before.st_size > maximum:
+        raise OSError(f"formatter output exceeds the configured size limit: {path}")
+    raw = target.absolute.read_bytes()
+    after_target = policy.resolve(path, allow_missing=True)
+    if after_target.kind is not PathKind.FILE:
+        raise OSError(f"formatter target is not a regular file: {path}")
+    after = after_target.absolute.lstat()
+    before_identity = (
+        before.st_dev,
+        before.st_ino,
+        before.st_size,
+        before.st_mtime_ns,
+        before.st_mode,
+    )
+    after_identity = (
+        after.st_dev,
+        after.st_ino,
+        after.st_size,
+        after.st_mtime_ns,
+        after.st_mode,
+    )
+    if before_identity != after_identity or len(raw) != after.st_size:
+        raise OSError(f"formatter target changed while it was captured: {path}")
+    return FormattedFileState(
+        path=path,
+        sha256=hashlib.sha256(raw).hexdigest(),
+        size=len(raw),
+        mode=stat.S_IMODE(after.st_mode),
+        content=raw,
+    )
+
+
+__all__ = [
+    "FormattedFileState",
+    "FormatterResult",
+    "FormatterRunResult",
+    "FormatterStatus",
+    "PreparedFormatter",
+    "capture_formatted_files",
+    "prepare_formatters",
+    "run_formatters",
+    "verify_formatted_files",
+]

patchshuttle/identifiers.py

@@ -0,0 +1,20 @@
+"""Canonical project identifiers for PatchShuttle workspaces and jobs."""
+
+from __future__ import annotations
+
+import secrets
+from typing import Annotated, TypeAlias
+
+from pydantic import Field
+
+PROJECT_ID_PATTERN = r"^PSH-[0-9A-F]{16}$"
+ProjectId: TypeAlias = Annotated[str, Field(strict=True, pattern=PROJECT_ID_PATTERN)]
+
+
+def generate_project_id() -> str:
+    """Return a project identifier backed by eight secure random bytes."""
+
+    return f"PSH-{secrets.token_hex(8).upper()}"
+
+
+__all__ = ["PROJECT_ID_PATTERN", "ProjectId", "generate_project_id"]

patchshuttle/inventory.py

@@ -0,0 +1,331 @@
+"""Bounded workspace inventories and deterministic before/after comparison."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path, PurePosixPath
+
+from patchshuttle.policy import Policy
+from patchshuttle.workspace import Workspace
+
+_HASH_CHUNK_BYTES = 1024 * 1024
+
+
+class InventoryEntryKind(str, Enum):
+    """Filesystem kinds recorded without following symbolic links."""
+
+    FILE = "FILE"
+    DIRECTORY = "DIRECTORY"
+    SYMLINK = "SYMLINK"
+    OTHER = "OTHER"
+
+
+class WorkspaceChangeKind(str, Enum):
+    """Stable classifications for a workspace difference."""
+
+    ADDED = "ADDED"
+    REMOVED = "REMOVED"
+    MODIFIED = "MODIFIED"
+    TYPE_CHANGED = "TYPE_CHANGED"
+
+
+class InventoryErrorCode(str, Enum):
+    """Stable failures for bounded workspace inspection."""
+
+    ENTRY_LIMIT_EXCEEDED = "ENTRY_LIMIT_EXCEEDED"
+    BYTE_LIMIT_EXCEEDED = "BYTE_LIMIT_EXCEEDED"
+    INSPECTION_FAILED = "INSPECTION_FAILED"
+    FILE_CHANGED_DURING_CAPTURE = "FILE_CHANGED_DURING_CAPTURE"
+
+
+class InventoryError(RuntimeError):
+    """A workspace inventory could not be captured exactly within policy."""
+
+    def __init__(
+        self,
+        code: InventoryErrorCode,
+        message: str,
+        *,
+        path: PurePosixPath | None = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.path = path
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        prefix = f"[{self.code.value}]"
+        return (
+            f"{prefix} {self.path.as_posix()}: {self.message}"
+            if self.path is not None
+            else f"{prefix} {self.message}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class InventoryEntry:
+    """Exact metadata and optional content hash for one workspace path."""
+
+    path: PurePosixPath
+    kind: InventoryEntryKind
+    size: int
+    modified_ns: int
+    mode: int
+    sha256: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceInventory:
+    """One deterministic bounded snapshot of non-ignored workspace entries."""
+
+    entries: tuple[InventoryEntry, ...]
+    hashed_bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceChange:
+    """One classified difference between two workspace inventories."""
+
+    path: PurePosixPath
+    kind: WorkspaceChangeKind
+    expected: bool
+    before: InventoryEntry | None
+    after: InventoryEntry | None
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceComparison:
+    """Complete inventory pair and its ordered differences."""
+
+    before: WorkspaceInventory
+    after: WorkspaceInventory
+    changes: tuple[WorkspaceChange, ...]
+
+    @property
+    def unexpected_changes(self) -> tuple[WorkspaceChange, ...]:
+        return tuple(change for change in self.changes if not change.expected)
+
+    @property
+    def success(self) -> bool:
+        return not self.unexpected_changes
+
+
+def capture_inventory(workspace: Workspace) -> WorkspaceInventory:
+    """Hash every non-ignored regular file within configured hard limits."""
+
+    policy = Policy(workspace)
+    maximum_entries = workspace.config.execution.max_inventory_entries
+    maximum_bytes = workspace.config.execution.max_inventory_bytes
+    entries: list[InventoryEntry] = []
+    hashed_bytes = 0
+    pending = [(workspace.root, PurePosixPath())]
+
+    while pending:
+        directory, parent = pending.pop()
+        children = _scan_directory(directory, parent)
+        child_directories: list[tuple[Path, PurePosixPath]] = []
+        for child in children:
+            relative = parent / child.name
+            if policy.is_ignored(relative):
+                continue
+            if len(entries) >= maximum_entries:
+                raise InventoryError(
+                    InventoryErrorCode.ENTRY_LIMIT_EXCEEDED,
+                    "workspace inventory entry limit was exceeded",
+                    path=relative,
+                )
+            metadata = _entry_metadata(child, relative)
+            kind = _entry_kind(metadata.st_mode)
+            digest: str | None = None
+            size = metadata.st_size
+            modified_ns = metadata.st_mtime_ns
+            if kind is InventoryEntryKind.FILE:
+                if hashed_bytes + size > maximum_bytes:
+                    raise InventoryError(
+                        InventoryErrorCode.BYTE_LIMIT_EXCEEDED,
+                        "workspace inventory byte limit was exceeded",
+                        path=relative,
+                    )
+                digest = _hash_regular_file(Path(child.path), relative, metadata)
+                hashed_bytes += size
+            elif kind is InventoryEntryKind.DIRECTORY:
+                size = 0
+                modified_ns = 0
+                child_directories.append((Path(child.path), relative))
+
+            entries.append(
+                InventoryEntry(
+                    path=relative,
+                    kind=kind,
+                    size=size,
+                    modified_ns=modified_ns,
+                    mode=stat.S_IMODE(metadata.st_mode),
+                    sha256=digest,
+                )
+            )
+        pending.extend(reversed(child_directories))
+
+    entries.sort(key=lambda entry: entry.path.as_posix())
+    return WorkspaceInventory(entries=tuple(entries), hashed_bytes=hashed_bytes)
+
+
+def compare_inventories(
+    before: WorkspaceInventory,
+    after: WorkspaceInventory,
+    *,
+    expected_paths: tuple[PurePosixPath, ...] = (),
+) -> WorkspaceComparison:
+    """Classify every before/after difference and mark declared paths."""
+
+    before_by_path = {entry.path: entry for entry in before.entries}
+    after_by_path = {entry.path: entry for entry in after.entries}
+    expected = frozenset(expected_paths)
+    changes: list[WorkspaceChange] = []
+    paths = sorted(
+        before_by_path.keys() | after_by_path.keys(),
+        key=PurePosixPath.as_posix,
+    )
+    for path in paths:
+        earlier = before_by_path.get(path)
+        later = after_by_path.get(path)
+        if earlier is None:
+            kind = WorkspaceChangeKind.ADDED
+        elif later is None:
+            kind = WorkspaceChangeKind.REMOVED
+        elif earlier.kind is not later.kind:
+            kind = WorkspaceChangeKind.TYPE_CHANGED
+        elif earlier != later:
+            kind = WorkspaceChangeKind.MODIFIED
+        else:
+            continue
+        changes.append(
+            WorkspaceChange(
+                path=path,
+                kind=kind,
+                expected=path in expected,
+                before=earlier,
+                after=later,
+            )
+        )
+
+    return WorkspaceComparison(
+        before=before,
+        after=after,
+        changes=tuple(changes),
+    )
+
+
+def _scan_directory(
+    directory: Path,
+    relative: PurePosixPath,
+) -> tuple[os.DirEntry[str], ...]:
+    try:
+        with os.scandir(directory) as iterator:
+            return tuple(sorted(iterator, key=lambda entry: entry.name))
+    except OSError as exc:
+        raise InventoryError(
+            InventoryErrorCode.INSPECTION_FAILED,
+            "workspace directory could not be inspected",
+            path=relative if relative.parts else None,
+        ) from exc
+
+
+def _entry_metadata(
+    entry: os.DirEntry[str],
+    relative: PurePosixPath,
+) -> os.stat_result:
+    try:
+        return entry.stat(follow_symlinks=False)
+    except OSError as exc:
+        raise InventoryError(
+            InventoryErrorCode.INSPECTION_FAILED,
+            "workspace entry metadata could not be inspected",
+            path=relative,
+        ) from exc
+
+
+def _entry_kind(mode: int) -> InventoryEntryKind:
+    if stat.S_ISREG(mode):
+        return InventoryEntryKind.FILE
+    if stat.S_ISDIR(mode):
+        return InventoryEntryKind.DIRECTORY
+    if stat.S_ISLNK(mode):
+        return InventoryEntryKind.SYMLINK
+    return InventoryEntryKind.OTHER
+
+
+def _hash_regular_file(
+    path: Path,
+    relative: PurePosixPath,
+    expected: os.stat_result,
+) -> str:
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags)
+    except OSError as exc:
+        raise InventoryError(
+            InventoryErrorCode.INSPECTION_FAILED,
+            "workspace file could not be opened for hashing",
+            path=relative,
+        ) from exc
+
+    digest = hashlib.sha256()
+    try:
+        opened = os.fstat(descriptor)
+        if not _same_file_state(expected, opened):
+            raise InventoryError(
+                InventoryErrorCode.FILE_CHANGED_DURING_CAPTURE,
+                "workspace file changed while inventory was captured",
+                path=relative,
+            )
+        while chunk := os.read(descriptor, _HASH_CHUNK_BYTES):
+            digest.update(chunk)
+        completed = os.fstat(descriptor)
+        if not _same_file_state(opened, completed):
+            raise InventoryError(
+                InventoryErrorCode.FILE_CHANGED_DURING_CAPTURE,
+                "workspace file changed while inventory was captured",
+                path=relative,
+            )
+    except OSError as exc:
+        raise InventoryError(
+            InventoryErrorCode.INSPECTION_FAILED,
+            "workspace file could not be hashed",
+            path=relative,
+        ) from exc
+    finally:
+        os.close(descriptor)
+    return digest.hexdigest()
+
+
+def _same_file_state(left: os.stat_result, right: os.stat_result) -> bool:
+    identity_available = left.st_ino != 0 and right.st_ino != 0
+    return (
+        stat.S_ISREG(right.st_mode)
+        and (
+            not identity_available
+            or (left.st_dev == right.st_dev and left.st_ino == right.st_ino)
+        )
+        and left.st_size == right.st_size
+        and left.st_mtime_ns == right.st_mtime_ns
+        and stat.S_IMODE(left.st_mode) == stat.S_IMODE(right.st_mode)
+    )
+
+
+__all__ = [
+    "InventoryEntry",
+    "InventoryEntryKind",
+    "InventoryError",
+    "InventoryErrorCode",
+    "WorkspaceChange",
+    "WorkspaceChangeKind",
+    "WorkspaceComparison",
+    "WorkspaceInventory",
+    "capture_inventory",
+    "compare_inventories",
+]